@aooth/auth 0.1.18 → 0.1.20

package/dist/authz.d.cts

@@ -1,5 +1,5 @@
 import { t as Clock } from "./clock-BjXa0LXb.cjs";
-import { a as NewAuthCode, c as PendingAuthorization, d as PendingAuthorizationStoreMemoryOptions, f as TokenPolicy, i as AuthCodeStoreMemoryOptions, l as PendingAuthorizationStore, n as AuthCodeStore, o as DEFAULT_PENDING_TTL_MS, r as AuthCodeStoreMemory, s as NewPendingAuthorization, t as AuthCode, u as PendingAuthorizationStoreMemory } from "./auth-code-store-BZ88d_tq.cjs";
+import { _ as TokenPolicy, a as NewDynamicClient, c as AuthCodeStoreMemory, d as DEFAULT_PENDING_TTL_MS, f as NewPendingAuthorization, g as PendingAuthorizationStoreMemoryOptions, h as PendingAuthorizationStoreMemory, i as DynamicClientStoreMemoryOptions, l as AuthCodeStoreMemoryOptions, m as PendingAuthorizationStore, n as DynamicClientStore, o as AuthCode, p as PendingAuthorization, r as DynamicClientStoreMemory, s as AuthCodeStore, t as DynamicClient, u as NewAuthCode } from "./dynamic-client-store-DzqdUwnw.cjs";
 import { JWK } from "jose";
 
 //#region src/authz/authz-errors.d.ts
@@ -10,7 +10,12 @@ import { JWK } from "jose";
  * code. Messages are benign — they must not disclose whether a failure was an
  * unknown client vs. a bad redirect vs. an expired code.
  */
-type AuthorizeErrorCode = /** Missing or malformed parameter at `/authorize` or `/token`. */"invalid_request" /** `redirect_uri` is not an allowed (loopback / registered) target. */ | "invalid_redirect" /** Code unknown / expired / already-redeemed, or PKCE verifier mismatch (`/token`). */ | "invalid_grant" /** Unknown or unauthenticated client (Tier 2). */ | "invalid_client" /** A known client used a grant/response it is not allowed (Tier 2). */ | "unauthorized_client" /** The user declined the authorization (consent). */ | "access_denied" /** An unexpected server-side failure. */ | "server_error";
+type AuthorizeErrorCode = /** Missing or malformed parameter at `/authorize` or `/token`. */"invalid_request" /** `redirect_uri` is not an allowed (loopback / registered) target. */ | "invalid_redirect" /** Code unknown / expired / already-redeemed, or PKCE verifier mismatch (`/token`). */ | "invalid_grant" /** Unknown or unauthenticated client (Tier 2). */ | "invalid_client" /** A known client used a grant/response it is not allowed (Tier 2). */ | "unauthorized_client"
+/**
+ * RFC 8707: more than one `resource` value on a leg, or the `/token`
+ * `resource` differs from the one recorded at `/authorize`.
+ */
+| "invalid_target" /** The user declined the authorization (consent). */ | "access_denied" /** An unexpected server-side failure. */ | "server_error";
 /** A typed authorization-server failure. */
 declare class AuthorizeError extends Error {
   readonly code: AuthorizeErrorCode;
@@ -25,6 +30,13 @@ declare class AuthorizeError extends Error {
 interface ResolvedClient {
   /** Registered client id (Tier 2), absent for a public/loopback client. */
   clientId?: string;
+  /**
+   * Display name for the consent prompt. For a dynamically-registered client
+   * this is the (sanitized) DCR `client_name` — UNTRUSTED text supplied by the
+   * registrant: render it as a text node, never as markup/links, and show the
+   * validated redirect host next to it as the trustworthy identity.
+   */
+  clientName?: string;
   /** The validated `redirect_uri` the code will be delivered to. */
   redirectUri: string;
   /** What the grant mints (fixed here, recorded on the pending authorization). */
@@ -75,6 +87,14 @@ interface ClientRedirectPolicy {
     clientId?: string;
     clientSecret?: string;
   }): void | Promise<void>;
+  /**
+   * Known-ness probe: does this policy recognize `clientId`? Optional in
+   * general, but REQUIRED on the `registered` slot when a
+   * `CompositeClientPolicy` composes it WITH a `dynamic` slot — the composite
+   * dispatches a presented `client_id` to whichever policy owns it (static
+   * registry first), for `resolveClient` and `authenticateClient` alike.
+   */
+  hasClient?(clientId: string): boolean | Promise<boolean>;
 }
 /**
  * `true` when `uri` is a syntactically valid http(s) URL whose host is a
@@ -118,6 +138,8 @@ declare class LoopbackClientPolicy implements ClientRedirectPolicy {
 interface RegisteredClient {
   /** Stable client identifier; the `id_token` `aud`. */
   clientId: string;
+  /** Display name for the consent prompt (rendered as text). Falls back to `clientId`. */
+  clientName?: string;
   /** Exact-match `redirect_uri` allowlist (the safe default). */
   redirectUris?: string[];
   /**
@@ -158,6 +180,8 @@ declare class RegisteredClientPolicy implements ClientRedirectPolicy {
     redirectUri: string;
     scope?: string;
   }): ResolvedClient;
+  /** Known-ness probe for `CompositeClientPolicy` dispatch (static registry, sync). */
+  hasClient(clientId: string): boolean;
   authenticateClient(args: {
     clientId?: string;
     clientSecret?: string;
@@ -171,22 +195,33 @@ declare class RegisteredClientPolicy implements ClientRedirectPolicy {
 interface CompositeClientPolicyOptions {
   /** Used when the request carries NO `client_id` (Tier-1 public/loopback CLI). */
   loopback: ClientRedirectPolicy;
-  /** Used when the request carries a `client_id` (Tier-2 registered service). */
-  registered: ClientRedirectPolicy;
+  /** Used when the request carries a `client_id` it recognizes (Tier-2 registered service). */
+  registered?: ClientRedirectPolicy;
+  /**
+   * Used when the request carries a `client_id` the `registered` policy does
+   * NOT recognize (RFC 7591 dynamically-registered connector clients). When
+   * both `registered` and `dynamic` are set, `registered` MUST implement
+   * `hasClient` — it is the dispatch probe.
+   */
+  dynamic?: ClientRedirectPolicy;
 }
 /**
- * Runs Tier-1 and Tier-2 side by side, dispatching on the **presence of
- * `client_id`** (AUTH-SERVER.md §10): a request with a `client_id` is a
- * registered client, one without is a loopback CLI. The split is the safety
- * boundary — a registered client is routed only to {@link RegisteredClientPolicy}
- * (which enforces ITS redirect allowlist, so it cannot smuggle a loopback
- * redirect), and a no-`client_id` request is routed only to the loopback policy
- * (so it cannot claim to be a registered client). Each sub-policy still owns its
- * own redirect validation; this only picks which one runs.
+ * Runs the tiers side by side, dispatching on the **presence and ownership of
+ * `client_id`** (AUTH-SERVER.md §10, OAUTH.md R2): a request without a
+ * `client_id` is a loopback CLI; one with a `client_id` belongs to the static
+ * registry when it knows the id (`hasClient`), else to the dynamic policy. The
+ * split is the safety boundary — each sub-policy still enforces ITS OWN
+ * redirect allowlist (so a registered client cannot smuggle a loopback
+ * redirect and a no-`client_id` request cannot claim to be registered), and
+ * static-first dispatch means a dynamic registration can never shadow a static
+ * client id. `authenticateClient` routes through the SAME picker: a dynamic
+ * `client_id` must be authenticated by the dynamic policy (existence check,
+ * PKCE binds), never rejected by the static registry that doesn't know it.
  */
 declare class CompositeClientPolicy implements ClientRedirectPolicy {
   private readonly loopback;
-  private readonly registered;
+  private readonly registered?;
+  private readonly dynamic?;
   constructor(opts: CompositeClientPolicyOptions);
   resolveClient(args: {
     clientId?: string;
@@ -197,6 +232,165 @@ declare class CompositeClientPolicy implements ClientRedirectPolicy {
     clientId?: string;
     clientSecret?: string;
   }): void | Promise<void>;
+  /**
+   * Ownership dispatch for a presented `client_id` — static registry first
+   * (when it knows the id), dynamic otherwise. Sync when the probe is sync
+   * (the static registry's is), preserving the callers' sync fast path.
+   */
+  private pickForClientId;
+}
+//#endregion
+//#region src/authz/client-registration.d.ts
+/**
+ * RFC 7591 §3.2.2 error vocabulary — deliberately separate from
+ * `AuthorizeErrorCode`: registration errors are a different wire contract
+ * (`400 { error, error_description }`) than the authorize/token taxonomy.
+ */
+type ClientRegistrationErrorCode = "invalid_redirect_uri" | "invalid_client_metadata";
+/** A typed RFC 7591 registration failure; `message` becomes `error_description`. */
+declare class ClientRegistrationError extends Error {
+  readonly code: ClientRegistrationErrorCode;
+  constructor(code: ClientRegistrationErrorCode, message: string);
+}
+interface ClientRegistrationValidationOptions {
+  /** Max `redirect_uris` entries (anonymous endpoint — rows must stay small). Default 5. */
+  maxRedirectUris?: number;
+  /** Max length of a single redirect URI. Default 512. */
+  maxRedirectUriLength?: number;
+  /** Max `client_name` length (after sanitization). Default 128. */
+  maxClientNameLength?: number;
+  /** Max `scope` string length. Default 256. */
+  maxScopeLength?: number;
+  /**
+   * Registration-time scope filter: the stored `scope` is the intersection of
+   * the requested tokens with this list. Omit to record the requested scope
+   * as-is. NOTE this is an upper bound on what the client may LATER request —
+   * the authorize-time grant is additionally bounded by
+   * `DynamicClientPolicyOptions.allowedScopes` (the server allow-list).
+   */
+  allowedScopes?: string[];
+}
+/**
+ * Validate + normalize an RFC 7591 registration request body into a
+ * {@link NewDynamicClient}, or THROW a {@link ClientRegistrationError}.
+ *
+ * Normalization is allowed by RFC 7591 §2 (the server MAY replace requested
+ * metadata with its own values) and is load-bearing for real connectors:
+ * `grant_types` / `response_types` are INTERSECTED with what the server
+ * supports (a connector requesting `["authorization_code", "refresh_token"]`
+ * registers with `["authorization_code"]` — the 201 echo of the narrowed set
+ * is the contract) rather than rejected. `token_endpoint_auth_method` defaults
+ * to `"none"` when absent (v1 is public-clients-only, so the RFC's
+ * `client_secret_basic` default is unsupported), but an EXPLICIT non-`"none"`
+ * ask is rejected — never silently downgrade a client that asked for a secret.
+ * Unknown fields are ignored and never echoed.
+ */
+declare function validateClientRegistration(body: unknown, opts?: ClientRegistrationValidationOptions): NewDynamicClient;
+interface DynamicClientRegistrationOptions {
+  store: DynamicClientStore;
+  /**
+   * Hard cap on stored registrations — `/register` is anonymous, so this
+   * bounds storage. REJECT-when-full (never evict): evicting a used row
+   * strands a connector that cached its `client_id`. Default 1000.
+   */
+  maxClients?: number;
+  /**
+   * Age after which a NEVER-USED registration (no `lastUsedAt`) is
+   * garbage-collected — lazily, on the next `register()` call, before the cap
+   * check. Omit to disable GC.
+   */
+  unusedClientTtlMs?: number;
+  /**
+   * Pluggable abuse guard, called with the validated metadata BEFORE anything
+   * is stored. Throw a {@link ClientRegistrationError} to reject with a 7591
+   * error; any other throw is a server fault (the endpoint answers 500).
+   * Rate limiting belongs at the consumer's ingress, not here.
+   */
+  guard?: (args: {
+    metadata: NewDynamicClient;
+  }) => void | Promise<void>;
+  validation?: ClientRegistrationValidationOptions;
+  /** Injectable clock for deterministic GC tests. Defaults to {@link defaultClock}. */
+  clock?: Clock;
+}
+/**
+ * The RFC 7591 registration operation behind `POST {issuer}/register`
+ * (OAUTH.md R2): validate → guard → lazy GC of never-used rows → hard cap →
+ * persist. Framework-free — `@aooth/auth-moost`'s controller endpoint is a
+ * thin HTTP adapter over `register()`, and non-moost servers can call it
+ * directly.
+ */
+declare class DynamicClientRegistration {
+  private readonly store;
+  private readonly maxClients;
+  private readonly unusedClientTtlMs?;
+  private readonly guard?;
+  private readonly validation?;
+  private readonly clock;
+  constructor(opts: DynamicClientRegistrationOptions);
+  /** Validate and persist a registration request body; returns the minted client. */
+  register(body: unknown): Promise<DynamicClient>;
+}
+//#endregion
+//#region src/authz/dynamic-client-policy.d.ts
+interface DynamicClientPolicyOptions {
+  store: DynamicClientStore;
+  /**
+   * What a dynamic-client grant mints. Default: a `dynamic-session` access
+   * token with a 30-day TTL. Override to re-label or scope connector tokens
+   * (e.g. `{ kind: "mcp-session", ttl: 30 * 24 * 60 * 60_000 }`).
+   */
+  tokenPolicy?: TokenPolicy;
+  /**
+   * Server-side scope allow-list: the granted scope is
+   * `requested ∩ allowedScopes` (∩ the registration's `scope` when set).
+   * Omit to fall back to `requested ∩ registration scope` alone. NEVER treat
+   * the registration's self-declared `scope` as the allow-set by itself — it
+   * is attacker-supplied and also feeds the consent copy.
+   */
+  allowedScopes?: string[];
+  /** Injectable clock for deterministic `lastUsedAt` stamps. Defaults to wall-clock. */
+  clock?: Clock;
+}
+/**
+ * Policy for RFC 7591 dynamically-registered public clients (OAUTH.md R2) on
+ * the `ClientRedirectPolicy` seam. `resolveClient` authorizes the client +
+ * `redirect_uri` against ITS registered allowlist and resolves the granted
+ * scope + token policy; `authenticateClient` re-checks existence at `/token`
+ * (`token_endpoint_auth_method: "none"` ⇒ no secret — PKCE is the binding, and
+ * a registration garbage-collected mid-flight fails closed). Dynamic clients
+ * receive an access token only — NO `id_token` in v1 (OAUTH.md R6).
+ *
+ * INVARIANT: the returned {@link ResolvedClient} always carries `clientId`, so
+ * the minted code records it and the token endpoint's symmetric client binding
+ * applies — a dynamic code redeemed without (or with another) `client_id` is
+ * rejected exactly like a Tier-2 code.
+ */
+declare class DynamicClientPolicy implements ClientRedirectPolicy {
+  private readonly store;
+  private readonly tokenPolicy;
+  private readonly allowedScopes?;
+  private readonly clock;
+  constructor(opts: DynamicClientPolicyOptions);
+  resolveClient(args: {
+    clientId?: string;
+    redirectUri: string;
+    scope?: string;
+  }): Promise<ResolvedClient>;
+  /**
+   * `/token`-side check: the client must still exist (fail closed when the
+   * registration was deleted/GC'd between authorize and redemption). No secret
+   * is checked — public client, PKCE is the binding; a spurious
+   * `client_secret` is ignored.
+   */
+  authenticateClient(args: {
+    clientId?: string;
+    clientSecret?: string;
+  }): Promise<void>;
+  /** Known-ness probe for `CompositeClientPolicy` dispatch. */
+  hasClient(clientId: string): Promise<boolean>;
+  private requireClient;
+  private grantScope;
 }
 //#endregion
 //#region src/authz/id-token-signer.d.ts
@@ -304,4 +498,133 @@ declare class NoopOidcClaimsResolver extends OidcClaimsResolver {
 /** `true` when `scope` (space-joined) grants `claim` — `"email"`/`"profile"` etc. */
 declare function scopeGrants(scope: string | undefined, claim: string): boolean;
 //#endregion
-export { type AuthCode, AuthCodeStore, AuthCodeStoreMemory, type AuthCodeStoreMemoryOptions, AuthorizeError, type AuthorizeErrorCode, type ClientRedirectPolicy, CompositeClientPolicy, type CompositeClientPolicyOptions, DEFAULT_PENDING_TTL_MS, type IdTokenAlg, type IdTokenClaims, IdTokenSigner, type IdTokenSignerOptions, LoopbackClientPolicy, type LoopbackClientPolicyOptions, type NewAuthCode, type NewPendingAuthorization, NoopOidcClaimsResolver, OidcClaimsResolver, type PendingAuthorization, PendingAuthorizationStore, PendingAuthorizationStoreMemory, type PendingAuthorizationStoreMemoryOptions, type RegisteredClient, RegisteredClientPolicy, type RegisteredClientPolicyOptions, type ResolvedClient, type TokenPolicy, isLoopbackRedirectUri, scopeGrants };
+//#region src/authz/server-metadata.d.ts
+/**
+ * Strip a trailing slash from an issuer identifier. RFC 8414 mandates EXACT
+ * (byte-identical) string comparison of issuer values, so every document that
+ * spells the issuer must canonicalize it the same way — same rule as
+ * `IdTokenSigner`. Shared by the AS metadata and protected-resource builders.
+ */
+declare function canonicalizeIssuer(issuer: string): string;
+/**
+ * RFC 8414 Authorization Server Metadata — the discovery document MCP connector
+ * clients fetch from `/.well-known/oauth-authorization-server` to locate the
+ * authorize / token / registration endpoints. Field names are the wire-format
+ * snake_case the RFC mandates; this is the JSON body, serialized as-is.
+ */
+interface AuthorizationServerMetadata {
+  issuer: string;
+  authorization_endpoint: string;
+  token_endpoint: string;
+  registration_endpoint?: string;
+  jwks_uri?: string;
+  response_types_supported: string[];
+  grant_types_supported: string[];
+  code_challenge_methods_supported: string[];
+  token_endpoint_auth_methods_supported: string[];
+  scopes_supported?: string[];
+}
+interface BuildAuthorizationServerMetadataOptions {
+  /**
+   * The server's issuer identifier. A trailing slash is stripped so the
+   * document's `issuer` (and the endpoints derived from it) stay byte-identical
+   * to the `iss` a client compares for EXACT string equality (RFC 8414) — same
+   * canonicalization rule as `IdTokenSigner`.
+   */
+  issuer: string;
+  /** Override the authorization endpoint. Default: `${issuer}/authorize`. */
+  authorizationEndpoint?: string;
+  /** Override the token endpoint. Default: `${issuer}/token`. */
+  tokenEndpoint?: string;
+  /** RFC 7591 dynamic-registration endpoint. Omitted ⇒ field absent. */
+  registrationEndpoint?: string;
+  /** JWKS document URL (OIDC id_token verification). Omitted ⇒ field absent. */
+  jwksUri?: string;
+  /** Advertised scopes. Omitted ⇒ field absent (clients may request any). */
+  scopesSupported?: string[];
+  /**
+   * Token-endpoint client-auth methods. Default `["none", "client_secret_post"]`.
+   * `"none"` is ALWAYS included even if a custom list omits it — MCP connector
+   * clients are public clients (PKCE-bound, no secret) and refuse a server that
+   * doesn't advertise it; see {@link buildAuthorizationServerMetadata}.
+   */
+  tokenEndpointAuthMethodsSupported?: string[];
+}
+/**
+ * Build the RFC 8414 discovery document for this authorization server. Pure —
+ * no I/O, no framework: mount the result on any HTTP stack (including the
+ * RFC 8414 path-insertion form rooted at the HTTP origin,
+ * `/.well-known/oauth-authorization-server/<issuer-path>`).
+ *
+ * Capability fields are fixed to what the server actually implements:
+ * `response_types_supported` `["code"]`, `grant_types_supported`
+ * `["authorization_code"]`, `code_challenge_methods_supported` `["S256"]`
+ * (PKCE is mandatory — it is the binding for public clients). Optional fields
+ * are omitted entirely (no `undefined` keys) so the serialized JSON carries
+ * only what was configured.
+ */
+declare function buildAuthorizationServerMetadata(opts: BuildAuthorizationServerMetadataOptions): AuthorizationServerMetadata;
+//#endregion
+//#region src/authz/resource-metadata.d.ts
+/**
+ * RFC 9728 Protected Resource Metadata — the document a resource server (an
+ * MCP server, an API) publishes at `/.well-known/oauth-protected-resource` so
+ * clients can discover WHICH authorization server(s) guard it. Field names are
+ * the wire-format snake_case; this is the JSON body, serialized as-is.
+ */
+interface ProtectedResourceMetadata {
+  resource: string;
+  authorization_servers: string[];
+  bearer_methods_supported: string[];
+  scopes_supported?: string[];
+  resource_name?: string;
+}
+interface BuildProtectedResourceMetadataOptions {
+  /** The resource identifier — the canonical URL of the protected resource. */
+  resource: string;
+  /**
+   * Issuer identifiers of the authorization server(s). Trailing slashes are
+   * stripped: clients match these against the AS metadata `issuer` for EXACT
+   * string equality (RFC 8414), so both documents must spell it byte-identically.
+   */
+  authorizationServers: string[];
+  /** Scopes the resource understands. Omitted ⇒ field absent. */
+  scopesSupported?: string[];
+  /** How the bearer token may be presented. Default `["header"]` (RFC 6750 §2.1). */
+  bearerMethodsSupported?: string[];
+  /** Human-readable display name. Omitted ⇒ field absent. */
+  resourceName?: string;
+}
+/**
+ * Build the RFC 9728 protected-resource document. Pure — no I/O, no framework;
+ * mount it on any HTTP stack. Optional fields are omitted entirely (no
+ * `undefined` keys) so the serialized JSON carries only what was configured.
+ */
+declare function buildProtectedResourceMetadata(opts: BuildProtectedResourceMetadataOptions): ProtectedResourceMetadata;
+interface WwwAuthenticateBearerChallengeOptions {
+  /**
+   * URL of the protected-resource document (RFC 9728 §5.1) — emitted as
+   * `resource_metadata="..."` so a client receiving a 401 can discover the
+   * authorization server without out-of-band configuration.
+   */
+  resourceMetadataUrl?: string;
+  /** RFC 6750 §3.1 error code (`invalid_token`, `insufficient_scope`, ...). */
+  error?: string;
+  /** Human-readable detail — emitted as `error_description="..."`. */
+  errorDescription?: string;
+  /** Scope(s) required to access the resource (space-separated). */
+  scope?: string;
+  /** Protection-space identifier (RFC 7235). */
+  realm?: string;
+}
+/**
+ * Build the VALUE of an RFC 6750 `WWW-Authenticate` Bearer challenge, e.g.
+ * `Bearer resource_metadata="https://...", error="invalid_token"`. With no
+ * options (or all absent) it degrades to the bare scheme `Bearer`. Every
+ * parameter is emitted as a quoted-string (RFC 6750 style) in a fixed order:
+ * `realm`, `error`, `error_description`, `resource_metadata`, `scope`. All
+ * values pass through {@link sanitizeQuotedStringValue} — see its security note.
+ */
+declare function buildWwwAuthenticateBearerChallenge(opts?: WwwAuthenticateBearerChallengeOptions): string;
+//#endregion
+export { type AuthCode, AuthCodeStore, AuthCodeStoreMemory, type AuthCodeStoreMemoryOptions, type AuthorizationServerMetadata, AuthorizeError, type AuthorizeErrorCode, type BuildAuthorizationServerMetadataOptions, type BuildProtectedResourceMetadataOptions, type ClientRedirectPolicy, ClientRegistrationError, type ClientRegistrationErrorCode, type ClientRegistrationValidationOptions, CompositeClientPolicy, type CompositeClientPolicyOptions, DEFAULT_PENDING_TTL_MS, type DynamicClient, DynamicClientPolicy, type DynamicClientPolicyOptions, DynamicClientRegistration, type DynamicClientRegistrationOptions, DynamicClientStore, DynamicClientStoreMemory, type DynamicClientStoreMemoryOptions, type IdTokenAlg, type IdTokenClaims, IdTokenSigner, type IdTokenSignerOptions, LoopbackClientPolicy, type LoopbackClientPolicyOptions, type NewAuthCode, type NewDynamicClient, type NewPendingAuthorization, NoopOidcClaimsResolver, OidcClaimsResolver, type PendingAuthorization, PendingAuthorizationStore, PendingAuthorizationStoreMemory, type PendingAuthorizationStoreMemoryOptions, type ProtectedResourceMetadata, type RegisteredClient, RegisteredClientPolicy, type RegisteredClientPolicyOptions, type ResolvedClient, type TokenPolicy, type WwwAuthenticateBearerChallengeOptions, buildAuthorizationServerMetadata, buildProtectedResourceMetadata, buildWwwAuthenticateBearerChallenge, canonicalizeIssuer, isLoopbackRedirectUri, scopeGrants, validateClientRegistration };