Am.Keyward.Mcp 0.39.1-preview

This is a prerelease version of Am.Keyward.Mcp.
{
  "inputs": [
    {
      "type": "promptString",
      "id": "Keyward__ServiceUri",
      "description": "Address of the KEYWARD host, e.g. https://toolbox.bvd.li"
    }
  ],
  "servers": {
    "am.keyward.mcp": {
      "type": "stdio",
      "command": "dnx",
      "args": ["am.keyward.mcp@0.39.1-preview", "--yes"],
      "env": {
        "Keyward__ServiceUri": "${input:Keyward__ServiceUri}"
      }
    }
  }
}
                    
This package contains an MCP Server. The server can be used in VS Code by copying the generated JSON to your VS Code workspace's .vscode/mcp.json settings file.
dotnet tool install --global Am.Keyward.Mcp --version 0.39.1-preview
                    
This package contains a .NET tool you can call from the shell/command line.
dotnet new tool-manifest
                    
if you are setting up this repo
dotnet tool install --local Am.Keyward.Mcp --version 0.39.1-preview
                    
This package contains a .NET tool you can call from the shell/command line.
#tool dotnet:?package=Am.Keyward.Mcp&version=0.39.1-preview&prerelease
                    
nuke :add-package Am.Keyward.Mcp --version 0.39.1-preview
                    

AM KEYWARD

⚠️ Pre-1.0 — no external security review yet. AM KEYWARD is usable and the design is documented in full below, but no independent party has audited the crypto, the tenant isolation or the audit chain. You can run it with real secrets; do so knowing that assurance rests on this project's own testing, and weigh that against what those secrets protect. See SECURITY.md.

AM KEYWARD is an open-source, .NET-native, library-first credential & secrets manager: a building block you embed in your own .NET environment (and can offer to your own users), plus an optional standalone reference app.

It covers two halves equally:

  • Software credentials — machine/integration secrets (API keys, connection strings), scoped per project & environment, fetched by your software via an API. Each value can carry a rotation date and a note on how a new one is obtained; the date is advisory (reads keep working) and raises advance notices.
  • Human vaults — personal & team password vaults on one «Vaults» page, team vaults shared to groups or individuals. A Login can hold its 2FA key (TOTP): KEYWARD shows the current one-time code, and the key can be read from a screenshot of the website's QR code.

What it is / is not

  • Is: an embeddable toolkit + reference app that you self-host and operate.
  • Is not: a hosted service, and not a HashiCorp-Vault-at-scale replacement.

There is no central, vendor-hosted AM KEYWARD. Each operator runs and secures their own deployment (key custody, database, hardening) — see SECURITY.md.

How the human-vault half differs from Bitwarden / KeePass

AM KEYWARD is not trying to out-feature a dedicated password manager. Its human vaults exist so that one system covers both halves of an organization's secrets — the machine credentials your software reads at runtime and the passwords your people share — under one data model, one login, one admin, one tamper-evident audit log, with the same envelope encryption and the same operator-owned KEK.

  • vs KeePass (a local encrypted file): AM KEYWARD is server-side and multi-user with central authorization grants, tenancy isolation, versioning and audit — not a file you sync by hand.
  • vs Bitwarden (an excellent hosted/self-hosted password manager): AM KEYWARD is embeddable in your own .NET app and unifies software credentials with human vaults; it is not a hosted service and does not (yet) ship browser-extension autofill or zero-knowledge vaults (zero-knowledge is the v0.2 goal, gated on an external review). If you only need a password manager for people, use Bitwarden.

Threat model (summary)

What AM KEYWARD is designed to resist, and what it explicitly does not:

In scope / mitigated

  • Database compromise alone — a stolen DB backup yields only ciphertext; the KEK lives outside the database, so without the KEK store the envelopes cannot be decrypted.
  • Cross-tenant / cross-user leakage — defense-in-depth: a composite application query filter, a server-authoritative active tenant, and SQL Server row-level security via SESSION_CONTEXT. The RLS layer holds whatever login the runtime uses — a security policy's filter predicates apply to every principal, db_owner included, unless the predicate exempts them, and ours do not. A least-privilege runtime login is therefore optional hardening (it withholds the right to disable the policy), not what makes the isolation work. Exercised by an adversarial isolation test gate.
  • Ciphertext replay across slots — AEAD AAD binds every ciphertext to its exact tenant / owner / project / environment / item / version, so a Dev/old ciphertext cannot be moved into a Prod/current row.
  • Audit tampering — a per-tenant hash chain, single-writer/serializable append, with an out-of-band chain-head checkpoint so a DB admin who rewrites history is detectable.
  • Insider / admin abuse of emergency access — server-side recovery is dual-control break-glass with an out-of-band, append-only non-repudiation trail.
  • Secrets in telemetry — the encrypted envelope is redacted from logs; problem-details and provider exceptions never echo values or connection strings.
  • Token abuse — software-client tokens are env-scoped (scope from the persisted token, never the request), hashed at rest, rotatable/revocable, rate-limited, with advance-expiry notifications. Guessed tokens are throttled per client IP.
  • AI agents acting for a user — an agent token (issued by the user on «AI agent tokens») acts as that user but only on vaults that were explicitly opened to agents (team vaults, or the user's own personal vaults) and put on the token's allowlist, with the permissions ticked, optionally only from given networks. Every request re-checks the token, the user (not disabled, still a member), the vault and the user's grant; agent actions are audited as the agent. Tokens always expire, and disabling a user revokes them. With «Manage applications» (software operators only) a token sets up applications for the software-client API — write-only, only on its allowlisted or self-created applications, never app tokens; it may rename or delete only its own still-empty placeholders.

Out of scope / operator-owned

  • KEK custody and loss — losing the KEK is total, unrecoverable data loss; the operator backs it up (offline, split) and rehearses the restore. See the operations runbook.
  • The escrow read path returns plaintext by design — for server-side vaults and the software API, the server can decrypt; this is the acknowledged trade-off of escrow (zero-knowledge human vaults are v0.2).
  • Host hardening — OS, network exposure, TLS, and the security of the identity provider are the operator's responsibility.
  • No external security review yet (pre-1.0) — nothing here has been audited by an independent party, so the assurance behind every mitigation above is this project's own testing. That is a real limit on how much weight the list deserves, not a reason it cannot be used; judge it against the value of what you store.

Security & operations

  • SECURITY.md — reporting, operator responsibilities, no-warranty.
  • Operations & KEK/DR runbook — key custody, backup/restore order, KEK rotation (with the re-wrap job) and compromise response, monitoring/health endpoints, break-glass, audit anchors, GDPR erasure and account-deletion retention.
  • One instance per database. Background jobs (notification mails, statistics flush, heartbeat monitoring, retention) are not coordinated across processes: no web farm, no IIS web garden, no overlapping deployment. A second instance logs an error and reports Unhealthy (KeywardSingleInstanceHealthCheck).
  • Running the reference shell outside Development. It refuses to start without an explicit ASPNETCORE_ENVIRONMENT / DOTNET_ENVIRONMENT, ConnectionStrings:Keyward, an https Keyward:PublicBaseUrl and Windows: its KEK is a DPAPI-protected file in Keyward:Kek:Directory (default %ProgramData%\Ardimedia\Am.Keyward\kek; back it up with the escrow export), and the break-glass trail defaults next to it. Set AllowedHosts to your host name. Behind a reverse proxy list the proxy in Keyward:ForwardedHeaders:KnownProxies (or KnownNetworks) — without it every caller has the proxy's address, which breaks throttling and the allow-lists — and never let the proxy lie inside an AllowedNetworks range. The agent API is mapped only with Keyward:Agent:Enabled or Keyward:Agent:AllowedNetworks.
  • Registration. Keyward:Registration:Mode is InviteOnly by default: the first account on an empty installation becomes System Admin, everyone else is invited by e-mail from the admin user page (InvitationLifetimeHours, default 48). Open lets anyone register and is meant for demos only.
  • Security headers. The shell sends a Content Security Policy that allows scripts only from the site plus a per-request nonce, with frame-ancestors 'none', plus X-Frame-Options: DENY, nosniff, Referrer-Policy: no-referrer and Permissions-Policy. Custom pages must not use inline scripts or onclick= handlers.

Embedding in your own ASP.NET Core / Blazor app

AM KEYWARD is library-first: you add it to your own .NET 10 Blazor Web App (interactive server) and it brings its services, API, and feature UI. Reference it either as the published preview NuGet packages (dotnet add package Am.Keyward.Infrastructure --prerelease, same for Am.Keyward.AspNetCore, Am.Keyward.Ui.Blazor, and Am.Keyward.Api if you expose the REST APIs) or as direct ProjectReferences (e.g. a git submodule). Deployed applications that only read their secrets reference the lightweight Am.Keyward.Client package instead — see Consuming secrets from a deployed application.

0. Prerequisites — the Keyward pages are interactive-server and [Authorize]-protected, so your app needs interactivity, auth-state cascading and (that's all — localization comes with AddKeywardUi):

builder.Services.AddRazorComponents().AddInteractiveServerComponents();
builder.Services.AddCascadingAuthenticationState();   // [Authorize]/<AuthorizeView> need the cascade
// ...plus your own cookie/OIDC authentication setup.

1. Register the services — one call wires up the EF Core DbContext (schema amkeyward), envelope crypto, audit, vaults, tokens, break-glass and monitoring:

// The KEK comes from your provider (Azure Key Vault / HSM / a protected file) — NEVER from the DB/appsettings.
// On Windows, DpapiKekFile is the packaged recommended custody: a DPAPI-protected file in a directory YOU
// choose (outside the database and outside any folder a deploy replaces), created on first run:
//   var (kek, kekId, created) = DpapiKekFile.LoadOrCreate(@"C:\ProgramData\<Company>\<App>\keyward");
// `created` is your cue to log the "back it up offline" warning once — see the escrow note below.
// Each call narrows the folder and kek.bin to SYSTEM, Administrators and the app's own identity (inheritance off);
// pass a logger — DpapiKekFile.LoadOrCreate(dir, logger) — to hear about it when the process may not do that.
var keywardConn = builder.Configuration.GetConnectionString("Keyward")!;
var (kek, kekId) = LoadKekFromYourProvider();
builder.Services.AddKeyward(keywardConn, kek, kekId);

// Prefer this overload when the KEK stays in a KMS/HSM (the raw key never enters the process). Supply your
// own IKekProvider, or a KeyRingKekProvider holding the current + prior versions during a KEK rotation:
// builder.Services.AddKeyward(keywardConn, sp => new KeyRingKekProvider(currentKekId, keksByVersion));

// Tell the embedded UI which tenant to operate in. A SINGLE-ORGANIZATION host takes the packaged glue —
// one call registers the fixed-tenant IKeywardWorkspaceContext AND the circuit handler that pins the tenant
// scope (pair it with app.UseKeywardSingleTenant below for the HTTP/SSR path). A MULTI-TENANT host instead
// implements IKeywardWorkspaceContext (Am.Keyward.Core.Abstractions) from its own selection and calls
// ITenantScopeSetter.SetTenant itself.
builder.Services.AddKeywardSingleTenant(myTenantId);

// Register the UI's own services (circuit-scoped state + localization for the Keyward strings, six
// languages built in).
// ProductName is what your users see (browser tab, brand, texts, e-mails); default "AM KEYWARD".
// PublicBaseUrl (optional) enables absolute links in notification e-mails sent by background jobs.
// NotificationLanguage (optional) sets the language for those background e-mails (account e-mails
// follow the request culture); default English.
// TokenEnvironmentVariableName / ClientApiBasePath (optional) only shape the ready-to-run PowerShell
// snippet shown next to a freshly issued app token. By default the variable name is derived PER
// APPLICATION (application "Bvd.Li.Toolbox" -> KEYWARD_BVD_LI_TOOLBOX_TOKEN), so two applications on one
// host never collide; set TokenEnvironmentVariableName only if every application here reads one fixed
// variable. ClientApiBasePath is the path you mapped MapKeywardClientApi at.
builder.Services.AddKeywardUi(o =>
{
    o.ProductName = "Contoso Secrets";
    o.PublicBaseUrl = "https://secrets.contoso.com";
    o.NotificationLanguage = "en";
    o.TokenEnvironmentVariableName = "CONTOSO_SECRETS_TOKEN";   // default: derived per application
    o.ClientApiBasePath = "/keyward/api/v1";                    // default
});

// Optional — transient notifications ("Vault created", "Moved", errors). Keyward depends only on the
// IKeywardNotifier port. Standalone it shows its own BlazorBlueprint-styled toast (KeywardToastHost). If
// your app already has a toast system, override the port so Keyward's notifications use it and are
// indistinguishable from the rest of your app (registered with TryAdd, so your registration wins):
builder.Services.AddScoped<IKeywardNotifier, MyToastNotifier>();   // e.g. routes onto BlazorBlueprint's BbToast

2. Bind identity at the edge. The libraries are identity-agnostic: they read ICurrentUser / ICurrentTenant, which you set from your auth. Your auth layer stamps the Keyward AppUser id onto the signed-in principal as the KeywardClaims.UserId claim (however you map it — ASP.NET Identity, external OIDC, ...); the Am.Keyward.AspNetCore package then establishes the current user on both the HTTP and the Blazor-circuit path for you:

builder.Services.AddKeywardBlazorUserScope();   // circuit handler: current user per Blazor circuit
// ...
app.UseAuthentication();
app.UseAuthorization();
app.UseAntiforgery();                            // MUST come after auth — tokens bind to the signed-in user
app.UseKeywardCurrentUser();                     // middleware: current user per HTTP request
app.UseKeywardSingleTenant(myTenantId);          // single-organization host: pin the tenant on the HTTP path

Creating those Keyward records is done for you. IKeywardIdentityBinder (registered by AddKeyward) finds or just-in-time creates the AppUser for your user id, keeps its flags in sync and reconciles the tenant membership — including removing it when you withdraw vault access. All you decide is what the user may be, from your own access model. In ASP.NET Core that is a claims factory plus one call:

public sealed class MyKeywardClaimsFactory(
    UserManager<MyUser> users, RoleManager<IdentityRole> roles, IOptions<IdentityOptions> options,
    IKeywardIdentityBinder binder, ILogger<MyKeywardClaimsFactory> logger)
    : UserClaimsPrincipalFactory<MyUser, IdentityRole>(users, roles, options)
{
    protected override async Task<ClaimsIdentity> GenerateClaimsAsync(MyUser user)
    {
        var identity = await base.GenerateClaimsAsync(user);   // your role claims
        var isAdmin = identity.HasClaim(Options.ClaimsIdentity.RoleClaimType, "Admin");

        await KeywardClaimsBinding.ApplyAsync(
            identity, binder, user.Id, user.UserName ?? user.Id, myTenantId,
            isAdmin ? KeywardIdentityBinding.Administrator : KeywardIdentityBinding.Member,
            logger);

        return identity;   // Keyward unavailable? The user still signs in, only Keyward pages are dead.
    }
}

Disabling and deleting users. A binding that grants nothing disables the user's Keyward record at their next sign-in, and a binding that grants something enables it again. But your own «disable user» and «delete user» actions run without the user signing in, so call the binder there as well — otherwise Keyward keeps treating the account as active:

await binder.DisableAsync(user.Id);   // in your disable and delete actions
await binder.EnableAsync(user.Id);    // in your enable action

A disabled user counts as a member of no tenant (system admins included), and no token may act for them.

  • KeywardClaims.UserId must be a GUID that exists in Keyward's Users table (AppUser). Use IKeywardIdentityBinder (above) — it creates the AppUser and the TenantMembership for you. The Tenant itself is seeded once at startup: KeywardSingleTenantSeeder.EnsureSeededAsync(...) covers the fixed tenant and, optionally, your own machine-secrets application. Without these rows the pages render empty and read-only.
  • Tenant selection stays yours where it is app-specific: a multi-tenant host registers a CircuitHandler that calls ITenantScopeSetter.SetTenant(...) in OnCircuitOpenedAsync with the same tenant its IKeywardWorkspaceContext returns, and pins the same tenant per HTTP request. A single-organization host gets both from AddKeywardSingleTenant + UseKeywardSingleTenant. If either scope is missing, pages fail with "Tenant scope mismatch" — the HTTP one bites first, on a prerendering page.
  • Symptom check: a Keyward page stuck at "Loading…" for a signed-in user means the circuit has no Keyward user — verify AddKeywardBlazorUserScope() is registered and the principal carries a valid-GUID KeywardClaims.UserId.

3. Discover the feature pages. The pages live under the /amkeyward/* route prefix (so they can't collide with your routes). Add the RCL assembly to the endpoint and the router — and route through AuthorizeRouteView (a plain RouteView ignores [Authorize]):

app.MapRazorComponents<App>()
   .AddInteractiveServerRenderMode()
   .AddAdditionalAssemblies(typeof(Am.Keyward.Ui.Blazor.KeywardRoutes).Assembly);
<Router AppAssembly="..." AdditionalAssemblies="new[] { typeof(Am.Keyward.Ui.Blazor.KeywardRoutes).Assembly }">
    <Found Context="routeData">
        <AuthorizeRouteView RouteData="routeData" DefaultLayout="typeof(Layout.MainLayout)">
            <NotAuthorized>@* redirect to your login *@</NotAuthorized>
        </AuthorizeRouteView>
    </Found>
</Router>

4. Drop the navigation into your layout (localized, auth-aware, no hardcoded routes):

<KeywardNav />

Style its .nav-link / .nav-group-label classes in your layout (see the reference shell's NavMenu.razor.css) — the nav deliberately adopts the host's look. KeywardNav lists the end-user pages; place links to the admin pages (KeywardRoutes.Groups, KeywardRoutes.DefaultEnvironments) in your own administration section.

5. Optional REST APIs. The software-client read API (deployed apps fetch their secrets with a bearer token) needs the service registration, the rate-limiter middleware AND the endpoint mapping — the endpoints don't exist otherwise:

builder.Services.AddKeywardSoftwareClientApi(o => // "Keyward.SoftwareClient" scheme + rate-limiter policy
    o.AllowedNetworks = builder.Configuration[KeywardSoftwareClientApiOptions.AllowedNetworksConfigurationKey]);
// ...
app.UseRateLimiter();                            // the mapped group requires the middleware — BEFORE auth
app.UseAuthentication();
app.UseAuthorization();
// ...
app.MapKeywardClientApi();                       // GET /keyward/api/v1/secrets[/{key}]
// Optional management REST API, guarded by YOUR admin policy:
app.MapKeywardApi(authorizationPolicy: "YourAdminPolicy");

Place UseRateLimiter() before UseAuthentication(): the token is checked inside the authorization middleware, so a limiter after it only sees requests that already cost a token lookup. Independently of the limiter, failed token authentications are throttled per client IP (20 per 5 minutes by default, tunable via AddKeywardSoftwareClientApi(o => { o.FailedAuthenticationLimit = …; o.FailedAuthenticationWindow = …; })). The management API checks the software-operator role (tenant admin, software manager or system admin) for every mutation and for every read of application data (key list, values), whatever policy you pass.

Limit the client API to the networks of your applications. Keyward:Client:AllowedNetworks (the option KeywardSoftwareClientApiOptions.AllowedNetworks, a comma-separated CIDR list such as 10.1.0.0/23, 10.8.0.0/24) is checked before any token lookup — callers from elsewhere get 403 with an empty body, with or without a token. It is evaluated on Connection.RemoteIpAddress, so behind a reverse proxy configure ForwardedHeaders with that proxy as a known proxy and keep the proxy's network out of the list (a list that contains a known proxy is rejected). Without the setting the API answers every network, as before, and a warning is logged at startup; an unusable value is logged as an error and the API refuses everyone until it is corrected — it never stops the host. The agent API has the same option (Keyward:Agent:AllowedNetworks), see agent API.

Code that runs without a signed-in user (seeding, background jobs) and calls the software-operator services (applications, environments, application data, app tokens, monitoring) must declare itself first: scope.ServiceProvider.GetRequiredService<IActorScopeSetter>().SetSystemActor(); — a scope with neither a user nor that declaration is refused. KeywardMachineSecrets does this itself for its startup overlay.

With the client API mapped, Keyward also records access statistics per app token (last access + IP, requests per day, seen IPs) and derives rule-based access alerts (never-seen IP, active again after a long silence) — visible on each application's «Statistics» tab and optionally e-mailed to opted-in admins. Recording is in-memory on the hot path and persisted batched; tune or disable via the Keyward:TokenAccess section (Enabled, FlushIntervalSeconds, RetentionDays, SilenceAlertDays). Details: docs/software-client-api.md. Behind a proxy, configure forwarded-headers middleware so the recorded IP is the client's, not the proxy's.

Building on that signal, heartbeat monitoring (a dead-man's switch per app token) alarms on the failure an application cannot report itself: a scheduled task that never starts sends no error mail — it just goes silent. Enable a monitor on the application's «Monitoring» tab (maximum silence, weekday/time watch window so a Mo–Fr job doesn't false-alarm over the weekend, optional all-clear mail, snooze); consumers that load their configuration through Keyward need no change at all, long-running services ping GET /ping (KeywardSecretsClient.PingAsync). Configure via Keyward:Monitoring (Enabled, CheckIntervalSeconds, TimeZone). TimeZone is the installation's zone — it governs the watch windows, the statistics day buckets and the timestamps in notification mails; unset it defaults to the server's local zone. Timestamps are stored in UTC and shown in the viewer's own local time zone in the UI.

AI assistants (agent tokens + MCP server)

An agent token lets an assistant such as Claude Code work with vault entries as you, narrowed to the vaults and permissions you choose: list and search entries, read a Login's URL and user name, store new credentials (it hands you a link, never echoes the value) and update entries. To see a secret it must ask; you approve each request on «AI agent tokens», and the MCP server Am.Keyward.Mcp (amkeyward-mcp — a .NET tool, or a single program file per platform on the GitHub Releases) copies the value to the clipboard of Windows or macOS — never into the assistant's context.

With the separate permission «Manage applications» the assistant also sets up an application for the software-client API: it creates the application, its environments and its secret keys, and hands you the link to paste the values. It sets a value itself only when it legitimately holds it, write-only — no endpoint ever returns one. App tokens stay with you: the assistant can neither issue, show nor revoke them. Setup, endpoints and the checklist for enabling the API on a host: docs/agent-api.md.

Scripts and tools (keyward command line)

keyward (Am.Keyward.Cli — a .NET tool, or a single program file per platform on the GitHub Releases) reads secrets for scripts, scheduled tasks and MCP servers with an app token per consumer application, kept in the Windows Credential Manager or the macOS Keychain: keyward get ops:Prtg:ApiToken prints one value, keyward run --env PRTG_TOKEN=ops:Prtg:ApiToken -- prtg-mcp starts one program with values in its environment, keyward headers feeds Claude Code's headersHelper, and keyward powershell install adds a read-only PowerShell SecretManagement vault. keyward import moves a plain-text secrets file into application keys from a mapping an AI agent may write — the values never pass through the agent. Details: docs/keyward-cli.md.

Consuming secrets from a deployed application (Am.Keyward.Client)

The consumer side of the software-client API is one line in the deployed application's Program.cs — no hand-rolled HTTP. Am.Keyward.Client is deliberately lightweight (no EF Core, no server code; just the configuration provider and a typed HTTP client):

builder.Configuration.AddKeywardSecrets(o =>
{
    o.ServiceUri = new Uri("https://keyward.example.com");
    o.ApplicationName = "Bvd.Li.Toolbox";   // token read from KEYWARD_BVD_LI_TOOLBOX_TOKEN
});

ServiceUri must be https (plain http is accepted only for a loopback address; AllowInsecureHttp opts out and is insecure).

The bulk read (GET /secrets) lands in IConfiguration, so ConnectionStrings:Main, options binding etc. resolve like any other configuration value — later sources overlay earlier ones as usual. The token comes from the same per-application environment variable the Keyward UI's deployment PowerShell snippet sets on the host (set o.TokenEnvironmentVariableName for a fixed name, or o.Token to pass it directly).

Defaults are deliberate: the source fails the host loudly at startup when no token is deployed or the server is unreachable (an app whose connection strings live in Keyward must not silently start without them; set o.Optional = true to tolerate it), and the startup load retries with backoff (LoadRetryCount/LoadRetryDelay) so a service booting right after a host reboot does not lose the race against the Keyward server; StartupTimeout (default 20 s) bounds the whole startup load, so a Windows service stays within its start limit. A rejected token (401/403) is not retried, and an answer that is not JSON counts as a failure. Set o.ReloadInterval to re-read periodically (with ±10 % jitter) and raise a configuration reload when values changed (IOptionsMonitor<T> picks it up); a failed refresh keeps the last known good values, and a token rejected during a reload is logged as an error once (through o.Logger, or stderr when none is set).

For direct runtime reads (a secret fetched on demand rather than at startup), register the typed client via IHttpClientFactory and inject KeywardSecretsClient:

builder.Services.AddKeywardSecretsClient(o =>
{
    o.ServiceUri = new Uri("https://keyward.example.com");
    o.ApplicationName = "Bvd.Li.Toolbox";
});
// ...then: string? value = await keywardSecretsClient.GetAsync("ConnectionStrings:Main", ct);

Styling and routes come for free. The UI theme is component-scoped CSS in the RCL, so it is folded into your app's standard {Assembly}.styles.css bundle automatically — no extra stylesheet <link> needed (the template's existing bundle link covers it). Theming: Keyward's --kw-* variables read the am.ui / shadcn design-token contract first — --background, --card, --muted, --foreground, --muted-foreground, --border, --primary, --primary-foreground, --destructive, --success, --warning, --info, --ring, --radius, plus an optional --primary-hover — so a host on that contract themes Keyward completely, dark mode included; without it Keyward's own palette applies. To restyle only Keyward, redefine the --kw-* variables on .keyward-ui; dark mode / color themes react to html.dark / html[data-theme="…"] if your host toggles them (see the reference shell's js/keyward-theme.js) — with no toggling you get the light default. Navigation contract: KeywardNav ships no styling; the host styles .nav-group-label (section heading) and .nav-link (a NavLink that gets active on the current page, containing an svg.kw-icon and a text <span>). The vault/application pages use <KeywardUi Fill="true">: in a plain layout they render with a normal page scroll; for the pinned header + independently scrolling panes, make your content container a fixed-height flex column and add .your-content:has(> .keyward-ui.kw-fill) { overflow: hidden; display: flex; flex-direction: column; } (see the reference shell's MainLayout.razor.css); below 860px Keyward stacks the panes, so turn that off there again (overflow: auto; display: block). The tree pane's width and, in a vault, the split between the entry list and the entry detail (stacked, 50/50 by default) can be dragged — the browser remembers both (localStorage am-keyward.tree-pane-width, am-keyward.vault-entries-split) and clamps them so the second pane always stays visible. Secondary areas (settings, sharing, import/export, statistics, …) are collapsible KeywardAreas: they start collapsed and remember their open state per browser in localStorage (am-area:keyward.… keys, the prefix am.ui's AmArea uses as well). To pin the UI language, add UseRequestLocalization with your supported cultures; without it the pages follow the server culture (en/de/fr/it/es/pt ship built in). The feature routes are the /amkeyward/* namespace; use the KeywardRoutes constants for links.

Database & migrations

  • You provide the database via the connection string passed to AddKeyward(connectionString, …). AM KEYWARD is SQL Server only (incl. Azure SQL). The reference shell reads it from ConnectionStrings:Keyward (override it in appsettings.json, an environment variable, or user-secrets; it falls back to a localhost dev default). AM KEYWARD never hardcodes the database name — that lives in your connection string.
  • It coexists in your database. All AM KEYWARD tables live in a dedicated schema amkeyward with a schema-scoped migrations-history table, so you can point it at the same database your host app already uses without colliding with your tables or your own EF migrations.
  • Migrations are not automatic just from the connection string. AddKeyward only registers the DbContext; the connection string only says where the database is. Apply Keyward's migrations one of these ways (the reference shell does the first two):
    • call MigrateAsync() at startup — this creates the database if it doesn't exist and applies pending migrations (using Am.Keyward.Infrastructure.Persistence;):
      await using var scope = app.Services.CreateAsyncScope();
      await scope.ServiceProvider.GetRequiredService<KeywardDbContext>().Database.MigrateAsync();
      
    • and/or run a periodic safety-net (re-applies pending migrations if the DB is swapped under a running app) — see the reference shell's DatabaseMigrationBackgroundService and the DatabaseMigration config section (Enabled, CheckIntervalSeconds);
    • or apply them out-of-band in your deploy step (dotnet ef database update).
  • Two database logins — optional hardening, not a prerequisite. Tenant row-level security is enforced against every principal, db_owner included, so a single privileged connection gets the same isolation; the split only withholds the right to disable the policy or alter the schema. Adopt it where it is cheap (a dedicated AM KEYWARD database), skip it where AM KEYWARD is embedded in a host's own database and a password would have to be created, deployed and rotated for that one property. If you adopt it, apply migrations out-of-band with the migrator login (the runtime login cannot DDL) and give AddKeyward only the runtime connection string; run db/setup-logins.sql once after the first migration. See docs/database-logins.md.

UI design principle — match BlazorBlueprint

The embedded Keyward UI MUST follow BlazorBlueprint's behaviour and layout — its controls, spacing, interaction patterns and notifications should be indistinguishable from a BlazorBlueprint host, so Keyward looks and feels native inside one. Keyward stays self-contained (no hard dependency on BlazorBlueprint, its own --kw-* tokens and components) so it also embeds anywhere; this principle governs that its own UI is kept visually and behaviourally aligned with BlazorBlueprint's conventions.

Two layers realise this:

  • Behaviour via ports. Where a host has a better-integrated primitive, Keyward depends on a small port, not on the concrete control, and the host wires the real thing. The transient-notification port IKeywardNotifier is the reference: a BlazorBlueprint host overrides it to use BbToast (real BB, identical to the rest of the app); standalone, Keyward's built-in KeywardToastHost renders a BlazorBlueprint-styled toast (bottom-right, auto-dismiss, per-kind accent) that mimics it.
  • Layout via the token contract. Keyward's own components style against --kw-* tokens chosen to match BlazorBlueprint's look; a host maps them to its theme.

Consequence for contributions: new Keyward UI, and any review of existing UI, is measured against BlazorBlueprint — if a control or message deviates from how BlazorBlueprint would present it, adjust Keyward (or add a port the host fills), don't diverge. The current UI is being reviewed against this and adjusted where it deviates (the notification split — success → toast, errors → inline — was the first pass).

Tech

.NET 10 · Blazor Server · ASP.NET Core · EF Core (Microsoft SQL Server) · MIT licensed.

Build

dotnet build Am.Keyward.slnx
dotnet test Am.Keyward.slnx

Requires the .NET 10 SDK; data/integration tests require a local SQL Server reachable on localhost via Integrated Security.

Documentation

End-user & operator documentation lives in docs/ and grows as features ship:

  • Software-client API — how a deployed app fetches its secrets with a token.
  • keyward command line — secrets for scripts, scheduled tasks, MCP servers and PowerShell with an app token in the Credential Manager / Keychain; import of a plain-text secrets file.
  • Agent API and MCP server — let an AI assistant store and find vault entries as you, with every secret reveal approved by you and sent to the clipboard only, and set up applications for the software-client API write-only; includes the checklist for enabling the API on a host.
  • Database logins — the least-privilege runtime login vs. the migration login that underpins tenant isolation.

License

MIT © 2026 Ardimedia Anstalt

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

This package has no dependencies.

Version Downloads Last Updated
0.39.1-preview 55 11/11/2026
0.39.0-preview 48 11/11/2026
0.38.0-preview 49 11/11/2026
0.37.0-preview 61 11/9/2026
0.36.0-preview 88 10/19/2026
0.35.0-preview 67 10/19/2026
0.34.0-preview 66 10/14/2026
0.33.0-preview 63 10/14/2026
0.32.0-preview 66 10/14/2026
0.31.0-preview 67 10/13/2026
0.30.0-preview 62 10/13/2026
0.29.0-preview 68 10/12/2026
0.28.0-preview 69 10/11/2026
0.27.2-preview 68 10/11/2026
0.27.1-preview 69 10/7/2026
0.27.0-preview 68 10/6/2026
0.26.1-preview 70 10/2/2026
0.26.0-preview 61 10/2/2026
0.25.0-preview 72 10/1/2026
0.24.0-preview 73 10/1/2026
Loading failed