@adcp/sdk 5.25.1 → 6.1.0

package/dist/lib/server/decisioning/tenant-registry.d.ts

@@ -0,0 +1,289 @@
+/**
+ * TenantRegistry — multi-tenant deployment helper for the v6.0 decisioning
+ * runtime.
+ *
+ * Holds a map of `agentUrl → TenantConfig` and tracks per-tenant health.
+ * Composes with the existing `serve()` host-routing surface: the registry
+ * returns an `AdcpServer` factory that dispatches based on `ctx.host`.
+ *
+ * **Three health states**, never startup-fatal:
+ *
+ *   - `healthy` — JWKS validated, accepting traffic normally.
+ *   - `unverified` — validation hasn't completed (server starting, or
+ *     JWKS unreachable transiently). Tenant accepts traffic with a
+ *     warning header; framework periodically re-validates.
+ *   - `disabled` — validation failed deterministically (signing key not
+ *     in published JWKS, brand.json malformed). Tenant returns
+ *     `SERVICE_UNAVAILABLE` until an admin recheck succeeds.
+ *
+ * One bad tenant doesn't take down others — health is per-tenant, the
+ * other tenants keep serving.
+ *
+ * Status: Preview / 6.0.
+ *
+ * @public
+ */
+import type { DecisioningPlatform, RequiredPlatformsFor, RequiredCapabilitiesFor } from './platform';
+import type { DecisioningAdcpServer, CreateAdcpServerFromPlatformOptions } from './runtime/from-platform';
+export interface TenantSigningKey {
+    /** Stable key identifier — appears in the `Signature-Input` header. */
+    keyId: string;
+    /**
+     * JWK form of the public key. MUST appear in the JWKS at
+     * `{agentUrl}/.well-known/brand.json` for the tenant to validate.
+     */
+    publicJwk: JsonWebKey;
+    /** Private JWK used to sign outbound responses (RFC 9421). */
+    privateJwk: JsonWebKey;
+}
+export interface TenantConfig<P extends DecisioningPlatform = DecisioningPlatform> {
+    /**
+     * Public URL the tenant accepts traffic on (e.g.,
+     * `https://acme-tv.example.com`). Used for host-route matching and —
+     * unless `jwksUrl` overrides — as the JWKS fetch base (the default
+     * validator computes `{host}/.well-known/brand.json` from this URL).
+     *
+     * For deployments that accept traffic on multiple URLs simultaneously
+     * (DNS cutover, vanity domains, internal + public hostname), use
+     * {@link agentUrls} instead — `agentUrl` is the single-URL convenience
+     * form. When both are set, `agentUrls` wins and `agentUrl` is ignored.
+     */
+    agentUrl?: string;
+    /**
+     * Multiple public URLs this tenant accepts traffic on. Use for cutover
+     * windows where `old.example.com/mcp` and `new.example.com/mcp` must
+     * both resolve to the same tenant for a window before DNS or buyer
+     * caches catch up. The first URL is the **canonical** one — JWKS
+     * validation uses it (and any `jwksUrl` override applies to all URLs).
+     * Additional URLs are aliases; they share the same brand and signing
+     * key.
+     *
+     * Adopters with two truly distinct brands serving from one platform
+     * should register separate tenants — each brand has its own JWKS and
+     * signing identity. `agentUrls` is for the single-brand-multiple-URLs
+     * case.
+     *
+     * MUST contain at least one URL when set. Exactly one of `agentUrl` or
+     * `agentUrls` must be provided; supplying both is a register() error.
+     */
+    agentUrls?: string[];
+    /**
+     * Override the JWKS fetch URL for this tenant. Use this when the
+     * tenant's brand.json doesn't sit at the host root — i.e., a single
+     * host serves multiple agents under path prefixes
+     * (`https://shared.example.com/api/agent-a`,
+     * `https://shared.example.com/api/agent-b`) and each prefix has its
+     * own brand identity. Without this override, the default validator
+     * resolves `/.well-known/brand.json` against the host root, which
+     * collapses both agents onto the same brand.
+     *
+     * Spec convention is host-root, so the override is only needed for
+     * sub-routed multi-tenant deployments. Custom validators that take a
+     * different shape entirely (e.g., reading from a vault) read this
+     * field via the `jwksUrl` argument on `JwksValidator.validate`.
+     */
+    jwksUrl?: string;
+    /** Signing keypair for RFC 9421 response signing. */
+    signingKey: TenantSigningKey;
+    /** The DecisioningPlatform impl for this tenant. */
+    platform: P & RequiredPlatformsFor<P['capabilities']['specialisms'][number]> & RequiredCapabilitiesFor<P['capabilities']['specialisms'][number]>;
+    /** Display label for admin / logs. Optional. */
+    label?: string;
+    /** Per-tenant `createAdcpServerFromPlatform` options override. */
+    serverOptions?: Partial<CreateAdcpServerFromPlatformOptions>;
+}
+/**
+ * Tenant health lifecycle:
+ *   - `'pending'` — first JWKS validation hasn't succeeded yet. Brand-new
+ *     tenants land here. `resolveByHost` REFUSES TRAFFIC for `pending`
+ *     tenants — host transport should respond 503 + Retry-After. This
+ *     closes the register-then-serve race window where a tenant
+ *     registered with a wrong signing key would have served signed
+ *     responses no buyer can verify until the first refresh detected
+ *     the mismatch (60+ seconds).
+ *   - `'healthy'` — JWKS validation has succeeded at least once.
+ *     Periodic rechecks confirm.
+ *   - `'unverified'` — was previously `healthy`; latest recheck failed
+ *     transiently (network error, 5xx, etc.). `resolveByHost` still
+ *     returns the tenant — graceful degradation for known-good tenants
+ *     when brand.json is briefly unreachable. Distinct from `'pending'`
+ *     where we've never validated.
+ *   - `'disabled'` — permanent validation failure (key not in published
+ *     JWKS, brand.json malformed, etc.). `resolveByHost` returns null;
+ *     operator must fix and call `recheck()` to revive.
+ */
+export type TenantHealth = 'pending' | 'healthy' | 'unverified' | 'disabled';
+export interface TenantStatus {
+    tenantId: string;
+    /**
+     * Canonical URL — the first entry in the tenant's `agentUrls` (or the
+     * single `agentUrl` value). JWKS validates against this URL; ops
+     * dashboards page on this field for the primary identity.
+     */
+    agentUrl: string;
+    /**
+     * Full URL list when the tenant was registered with `agentUrls[]`.
+     * Single-URL tenants get a one-element array. Ops dashboards iterate
+     * this field to show every URL serving the tenant; required so admins
+     * can detect stale aliases or accidental host overlap with another
+     * tenant (#1097 follow-up — collision check below errors at register
+     * time, but the operator still wants visibility into what's live).
+     */
+    agentUrls: readonly string[];
+    health: TenantHealth;
+    /** Reason for unverified/disabled state. */
+    reason?: string;
+    /** ISO timestamp of the last health check. */
+    lastCheckedAt: string;
+}
+export interface JwksValidationResult {
+    ok: boolean;
+    /** Recovery classification when `ok === false`. */
+    recovery?: 'transient' | 'permanent';
+    reason?: string;
+}
+export interface JwksValidator {
+    /**
+     * Validate that the tenant's signing key appears in the published JWKS.
+     *
+     * - `agentUrl` is the tenant's public URL (used for host-relative URL
+     *   computation by the default validator).
+     * - `jwksUrl` is the explicit JWKS fetch URL when the tenant's
+     *   `TenantConfig.jwksUrl` was set; absent for the spec-default
+     *   host-root resolution.
+     * - `signingKey` is what to look for in the published JWKS.
+     */
+    validate(opts: {
+        agentUrl: string;
+        jwksUrl?: string;
+        signingKey: TenantSigningKey;
+    }): Promise<JwksValidationResult>;
+}
+export interface TenantRegistryOptions {
+    /**
+     * JWKS validator. Defaults to a fetch-based validator that hits
+     * `{agentUrl}/.well-known/brand.json`. Tests can pass a fake.
+     */
+    jwksValidator?: JwksValidator;
+    /**
+     * Per-tenant `createAdcpServerFromPlatform` options applied to every
+     * tenant unless overridden by `TenantConfig.serverOptions`.
+     */
+    defaultServerOptions: CreateAdcpServerFromPlatformOptions;
+    /**
+     * Auto-validate tenants when they're registered. Defaults to `true`.
+     *
+     * Disable ONLY for tests that drive validation manually via `recheck` —
+     * with this off, every `register()` leaves the tenant in `'pending'`
+     * health and `resolveByRequest` silently refuses traffic until the
+     * caller recheck()s each tenant. Production deployments should leave
+     * this at the default; the framework emits a one-shot console.warn at
+     * registry construction when `autoValidate: false` is set, to surface
+     * the "all traffic blocked" consequence.
+     */
+    autoValidate?: boolean;
+}
+export interface TenantRegistry {
+    /**
+     * Register a tenant. Tenant lands in `'pending'` health initially —
+     * `resolveByHost` refuses traffic until the first JWKS validation
+     * succeeds. Pass `{ awaitFirstValidation: true }` to block on the
+     * synchronous validation outcome (returns the resulting status; throws
+     * if registration is incompatible). Without the flag, register fires
+     * validation in the background and returns immediately; the caller
+     * polls `getStatus(tenantId).health === 'healthy'` if needed.
+     *
+     * **Admin-API security.** This method is the privileged surface — any
+     * caller invoking `register` can introduce a tenant that will sign
+     * outbound webhooks. Hosts wiring an HTTP/RPC endpoint in front of
+     * `register` MUST gate it with operator-level auth (mTLS, signed
+     * admin tokens, network ACL). The framework doesn't ship admin-HTTP
+     * scaffolding because the right auth shape varies by deployment;
+     * adopters who want a vetted shape can layer Express middleware
+     * around their `registry.register(...)` route handler.
+     */
+    register<P extends DecisioningPlatform>(tenantId: string, config: TenantConfig<P>, opts?: {
+        awaitFirstValidation?: boolean;
+    }): Promise<TenantStatus> | void;
+    unregister(tenantId: string): void;
+    /**
+     * Resolve a tenant by host alone (the lowercased authority of the
+     * request). Convenience wrapper around `resolveByRequest(host, '/')` —
+     * works for the canonical subdomain-routing pattern (e.g.,
+     * `sales.training.example.com`) where each tenant has its own host.
+     *
+     * For path-based routing (`training.example.com/sales`,
+     * `training.example.com/creative` on a single host), use
+     * `resolveByRequest(host, pathname)` instead.
+     *
+     * Returns null if no tenant matches, the tenant is `pending` (first
+     * validation hasn't succeeded), or the tenant is `disabled`.
+     * `unverified` tenants resolve normally — graceful degradation for
+     * known-good tenants whose latest recheck failed transiently.
+     */
+    resolveByHost(host: string): {
+        tenantId: string;
+        config: TenantConfig;
+        server: DecisioningAdcpServer;
+    } | null;
+    /**
+     * Resolve a tenant by host AND request path. The framework matches
+     * tenants whose `agentUrl` host equals the request host AND whose
+     * `agentUrl` path is a prefix of the request `pathname`. When multiple
+     * tenants share a host, the LONGEST matching path prefix wins (so
+     * `/sales-broadcast` is preferred over `/sales` for a request to
+     * `/sales-broadcast/mcp`).
+     *
+     * Use this for path-routed multi-tenant deployments where adopters
+     * don't want per-tenant subdomain DNS / TLS overhead. Each tenant's
+     * `agentUrl` carries the path: `https://training.example.com/sales`.
+     * Subdomain-routed tenants (`https://sales.training.example.com`)
+     * keep working — their path prefix is `/`, which matches any pathname.
+     *
+     * Returns null on no match, `pending`, or `disabled`. `unverified`
+     * tenants resolve normally (graceful degradation).
+     */
+    resolveByRequest(host: string, pathname: string): {
+        tenantId: string;
+        config: TenantConfig;
+        server: DecisioningAdcpServer;
+    } | null;
+    /**
+     * Direct tenant lookup by `tenantId`. Use this when your route layer
+     * has already resolved the tenant from session / path / header and
+     * needs the registry's `{ config, server }` entry without re-running
+     * URL parsing. Same `pending` / `disabled` health gate as the
+     * `resolveByXxx` helpers — returns `null` when the tenant isn't
+     * accepting traffic so callers don't have to re-check status.
+     *
+     * Adopters who decouple tenant lookup from URL routing (e.g., bind
+     * tenantId at their own Express middleware before calling into the
+     * registry) should prefer this over `resolveByRequest(host, '/<id>/mcp')`
+     * tricks.
+     */
+    get(tenantId: string): {
+        tenantId: string;
+        config: TenantConfig;
+        server: DecisioningAdcpServer;
+    } | null;
+    getStatus(tenantId: string): TenantStatus | null;
+    list(): readonly TenantStatus[];
+    /**
+     * Trigger a JWKS recheck for the tenant. Admin UI calls this after
+     * fixing a brand.json mismatch.
+     */
+    recheck(tenantId: string): Promise<TenantStatus>;
+}
+/**
+ * Default JWKS validator. Fetches `{agentUrl}/.well-known/brand.json` and
+ * checks that `signingKey.publicJwk` appears in the JWKS keys array.
+ *
+ * Uses the global `fetch`. Network errors classify as `transient`;
+ * 4xx / parse-error / key-not-in-JWKS classify as `permanent`.
+ */
+export declare function createDefaultJwksValidator(opts?: {
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}): JwksValidator;
+export declare function createTenantRegistry(opts: TenantRegistryOptions): TenantRegistry;
+//# sourceMappingURL=tenant-registry.d.ts.map

package/dist/lib/server/decisioning/tenant-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-registry.d.ts","sourceRoot":"","sources":["../../../../src/lib/server/decisioning/tenant-registry.ts"],"names":[],"mappings":"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"}