@aooth/auth 0.1.46 → 0.1.48

package/dist/authz.cjs

@@ -1,8 +1,38 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_clock = require("./clock-Bl-H3eqE.cjs");
-const require_dynamic_client_store = require("./dynamic-client-store-DAStgv2j.cjs");
+const require_opaque_token = require("./opaque-token-CaZgD2i6.cjs");
+const require_dynamic_client_store = require("./dynamic-client-store-DykM9QOT.cjs");
 let node_crypto = require("node:crypto");
 let jose = require("jose");
+//#region src/authz/token-policy.ts
+/**
+* Default refresh-token (grant) lifetime for {@link TokenPolicy.refresh} when
+* no `ttl` is given: 30 days. Deliberately independent of the session tier's
+* `AuthCredentialOptions.refresh.ttl` — an authz grant's lifetime is the
+* policy's decision, never inherited from browser-session posture.
+*/
+const DEFAULT_AUTHZ_REFRESH_TTL_MS = 720 * 60 * 6e4;
+/**
+* Flatten a {@link TokenPolicy} into the `AuthCredential.issue()` options a
+* token endpoint forwards. The refresh dimension applies only to client-bound
+* grants — the family is stamped with `metadata.authzClientId`, the binding
+* the `refresh_token` grant enforces — so a clientless (loopback) grant
+* ignores `policy.refresh`. `refresh: false` otherwise: an authz mint never
+* rides the instance-level session refresh config (no orphaned refresh row
+* for a policy that didn't opt in). Lives HERE, next to the policy type and
+* its default ttl, so every HTTP adapter applies the same semantics.
+*/
+function tokenPolicyToIssueOptions(policy, clientId) {
+	const withRefresh = policy.refresh !== void 0 && clientId !== void 0;
+	return {
+		...policy.payload,
+		...policy.kind !== void 0 && { kind: policy.kind },
+		...policy.ttl !== void 0 && { ttl: policy.ttl },
+		refresh: withRefresh ? { ttl: policy.refresh?.ttl ?? 2592e6 } : false,
+		...withRefresh && { metadata: { authzClientId: clientId } }
+	};
+}
+//#endregion
 //#region src/authz/authz-errors.ts
 /** A typed authorization-server failure. */
 var AuthorizeError = class extends Error {
@@ -60,6 +90,15 @@ var LoopbackClientPolicy = class {
 	}
 };
 //#endregion
+//#region src/utils/timing-safe.ts
+/** Constant-time string compare that also fails closed on a length mismatch. */
+function timingSafeEqualStr(a, b) {
+	const ab = Buffer.from(a, "utf8");
+	const bb = Buffer.from(b, "utf8");
+	if (ab.length !== bb.length) return false;
+	return (0, node_crypto.timingSafeEqual)(ab, bb);
+}
+//#endregion
 //#region src/authz/oidc-claims-resolver.ts
 /**
 * Resolves the OIDC profile claims to embed in an `id_token` for a given user +
@@ -157,13 +196,6 @@ var RegisteredClientPolicy = class {
 		return granted.length > 0 ? granted.join(" ") : void 0;
 	}
 };
-/** Constant-time string compare that also fails closed on a length mismatch. */
-function timingSafeEqualStr(a, b) {
-	const ab = Buffer.from(a, "utf8");
-	const bb = Buffer.from(b, "utf8");
-	if (ab.length !== bb.length) return false;
-	return (0, node_crypto.timingSafeEqual)(ab, bb);
-}
 //#endregion
 //#region src/authz/composite-client-policy.ts
 /**
@@ -213,6 +245,30 @@ var CompositeClientPolicy = class {
 	}
 };
 //#endregion
+//#region src/authz/client-secret.ts
+/**
+* Mint a confidential dynamic client's secret (RFC 7591 `client_secret`) — a
+* plain {@link generateOpaqueToken} mint. Returned to the registrant ONCE in
+* the registration response; only its {@link hashClientSecret} digest is
+* stored.
+*/
+function mintClientSecret() {
+	return require_opaque_token.generateOpaqueToken();
+}
+/**
+* Storage digest for a client secret — plain SHA-256 (hex). No KDF/salt on
+* purpose: the secret is high-entropy server-minted material (never a human
+* password), so brute-forcing the digest is infeasible and a per-row salt
+* buys nothing.
+*/
+function hashClientSecret(secret) {
+	return (0, node_crypto.createHash)("sha256").update(secret, "utf8").digest("hex");
+}
+/** Constant-time check of a presented secret against a stored digest. */
+function verifyClientSecret(secret, hash) {
+	return timingSafeEqualStr(hashClientSecret(secret), hash);
+}
+//#endregion
 //#region src/authz/client-registration.ts
 /** A typed RFC 7591 registration failure; `message` becomes `error_description`. */
 var ClientRegistrationError = class extends Error {
@@ -223,9 +279,11 @@ var ClientRegistrationError = class extends Error {
 		this.code = code;
 	}
 };
-/** Grant/response types the v1 authorization server supports (auth-code + PKCE only). */
-const SUPPORTED_GRANT_TYPES = ["authorization_code"];
+/** Grant/response types the authorization server supports (auth-code + PKCE, plus refresh). */
+const SUPPORTED_GRANT_TYPES = ["authorization_code", "refresh_token"];
 const SUPPORTED_RESPONSE_TYPES = ["code"];
+/** Token-endpoint auth methods DCR accepts (both advertised in the RFC 8414 document). */
+const SUPPORTED_TOKEN_ENDPOINT_AUTH_METHODS = ["none", "client_secret_post"];
 /** RFC 6749 §3.3 scope-token charset: printable ASCII minus space, `"` and `\`. */
 const SCOPE_TOKEN_RE = /^[\x21\x23-\x5B\x5D-\x7E]+$/u;
 const DEFAULT_MAX_REDIRECT_URIS = 5;
@@ -274,13 +332,14 @@ function isAcceptableRedirectUri(uri) {
 * 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.
+* supports (an unsupported grant is dropped from the echo — the 201 echo of
+* the narrowed set is the contract) rather than rejected, but the result must
+* still include `authorization_code` (it is the only way to establish a grant;
+* `refresh_token` alone mints nothing). `token_endpoint_auth_method` defaults
+* to `"none"` when absent (the RFC's `client_secret_basic` default is
+* unsupported — secrets travel in the POST form body); an EXPLICIT ask outside
+* the allowed set is rejected — never silently downgrade a client that asked
+* for a secret. Unknown fields are ignored and never echoed.
 */
 function validateClientRegistration(body, opts) {
 	if (typeof body !== "object" || body === null || Array.isArray(body)) throw new ClientRegistrationError("invalid_client_metadata", "registration request must be a JSON object");
@@ -292,9 +351,11 @@ function validateClientRegistration(body, opts) {
 	if (redirectUris.length === 0) throw new ClientRegistrationError("invalid_redirect_uri", "redirect_uris must be non-empty");
 	if (redirectUris.length > maxUris) throw new ClientRegistrationError("invalid_redirect_uri", `redirect_uris accepts at most ${maxUris} entries`);
 	for (const uri of redirectUris) if (uri.length > maxUriLength || !isAcceptableRedirectUri(uri)) throw new ClientRegistrationError("invalid_redirect_uri", "each redirect_uri must be an https URL with an explicit host or a loopback literal, without a fragment");
-	if ((req.token_endpoint_auth_method ?? "none") !== "none") throw new ClientRegistrationError("invalid_client_metadata", "only token_endpoint_auth_method \"none\" is supported");
+	const allowedAuthMethods = (opts?.allowedTokenEndpointAuthMethods ?? SUPPORTED_TOKEN_ENDPOINT_AUTH_METHODS).filter((m) => SUPPORTED_TOKEN_ENDPOINT_AUTH_METHODS.includes(m));
+	const authMethod = req.token_endpoint_auth_method ?? "none";
+	if (typeof authMethod !== "string" || !allowedAuthMethods.includes(authMethod)) throw new ClientRegistrationError("invalid_client_metadata", `only token_endpoint_auth_method ${allowedAuthMethods.map((m) => `"${m}"`).join(" / ")} is supported`);
 	const grantTypes = req.grant_types === void 0 ? [...SUPPORTED_GRANT_TYPES] : asStringArray(req.grant_types, "grant_types").filter((g) => SUPPORTED_GRANT_TYPES.includes(g));
-	if (grantTypes.length === 0) throw new ClientRegistrationError("invalid_client_metadata", "grant_types must include authorization_code");
+	if (!grantTypes.includes("authorization_code")) throw new ClientRegistrationError("invalid_client_metadata", "grant_types must include authorization_code");
 	const responseTypes = req.response_types === void 0 ? [...SUPPORTED_RESPONSE_TYPES] : asStringArray(req.response_types, "response_types").filter((r) => SUPPORTED_RESPONSE_TYPES.includes(r));
 	if (responseTypes.length === 0) throw new ClientRegistrationError("invalid_client_metadata", "response_types must include code");
 	let clientName;
@@ -313,7 +374,7 @@ function validateClientRegistration(body, opts) {
 	}
 	return {
 		redirectUris,
-		tokenEndpointAuthMethod: "none",
+		tokenEndpointAuthMethod: authMethod,
 		grantTypes,
 		responseTypes,
 		...clientName !== void 0 && { clientName },
@@ -324,9 +385,9 @@ const DEFAULT_MAX_CLIENTS = 1e3;
 /**
 * 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.
+* mint secret (confidential) → persist. Framework-free — `@aooth/auth-moost`'s
+* controller endpoint is a thin HTTP adapter over `register()`, and non-moost
+* servers can call it directly.
 */
 var DynamicClientRegistration = class {
 	store;
@@ -343,12 +404,28 @@ var DynamicClientRegistration = class {
 		this.validation = opts.validation;
 		this.clock = opts.clock ?? require_clock.defaultClock;
 	}
-	/** Validate and persist a registration request body; returns the minted client. */
+	/**
+	* Validate and persist a registration request body; returns the minted
+	* client. For a `client_secret_post` registration the returned record
+	* additionally carries the plaintext `clientSecret` (the ONE disclosure —
+	* only its SHA-256 digest is stored).
+	*/
 	async register(body) {
 		const metadata = validateClientRegistration(body, this.validation);
 		await this.guard?.({ metadata });
 		if (this.unusedClientTtlMs !== void 0) await this.store.deleteUnusedBefore(this.clock.now() - this.unusedClientTtlMs);
 		if (await this.store.count() >= this.maxClients) throw new ClientRegistrationError("invalid_client_metadata", "registration limit reached");
+		if (metadata.tokenEndpointAuthMethod === "client_secret_post") {
+			const clientSecret = mintClientSecret();
+			return {
+				...await this.store.create({
+					...metadata,
+					clientSecretHash: hashClientSecret(clientSecret)
+				}),
+				clientSecret,
+				clientSecretExpiresAt: 0
+			};
+		}
 		return this.store.create(metadata);
 	}
 };
@@ -359,13 +436,14 @@ const DEFAULT_DYNAMIC_TOKEN_POLICY = {
 	ttl: 720 * 60 * 6e4
 };
 /**
-* Policy for RFC 7591 dynamically-registered public clients (OAUTH.md R2) on
-* the `ClientRedirectPolicy` seam. `resolveClient` authorizes the client +
+* Policy for RFC 7591 dynamically-registered 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).
+* (a registration garbage-collected mid-flight fails closed) and, for a
+* `client_secret_post` registration, validates the presented secret against
+* the stored digest (public `"none"` clients: PKCE is the binding). 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
@@ -401,12 +479,16 @@ var DynamicClientPolicy = class {
 	}
 	/**
 	* `/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.
+	* registration was deleted/GC'd between authorize and redemption). A client
+	* registered with `token_endpoint_auth_method: "client_secret_post"` must
+	* additionally present its minted `client_secret` (constant-time check
+	* against the stored digest). For a public (`"none"`) client no secret is
+	* checked — PKCE is the binding; a spurious `client_secret` is ignored.
 	*/
 	async authenticateClient(args) {
-		await this.requireClient(args.clientId);
+		const client = await this.requireClient(args.clientId);
+		if (client.tokenEndpointAuthMethod !== "client_secret_post") return;
+		if (client.clientSecretHash === void 0 || args.clientSecret === void 0 || !verifyClientSecret(args.clientSecret, client.clientSecretHash)) throw new AuthorizeError("invalid_client", "client authentication failed");
 	}
 	/** Known-ness probe for `CompositeClientPolicy` dispatch. */
 	async hasClient(clientId) {
@@ -537,7 +619,9 @@ function canonicalizeIssuer(issuer) {
 *
 * Capability fields are fixed to what the server actually implements:
 * `response_types_supported` `["code"]`, `grant_types_supported`
-* `["authorization_code"]`, `code_challenge_methods_supported` `["S256"]`
+* `["authorization_code", "refresh_token"]` (the grant is implemented server-
+* wide; whether a given client's grant mints a refresh token is per-policy —
+* `TokenPolicy.refresh`), `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.
@@ -552,7 +636,7 @@ function buildAuthorizationServerMetadata(opts) {
 		...opts.registrationEndpoint !== void 0 && { registration_endpoint: opts.registrationEndpoint },
 		...opts.jwksUri !== void 0 && { jwks_uri: opts.jwksUri },
 		response_types_supported: ["code"],
-		grant_types_supported: ["authorization_code"],
+		grant_types_supported: ["authorization_code", "refresh_token"],
 		code_challenge_methods_supported: ["S256"],
 		token_endpoint_auth_methods_supported: authMethods.includes("none") ? authMethods : ["none", ...authMethods],
 		...opts.scopesSupported !== void 0 && { scopes_supported: opts.scopesSupported }
@@ -612,6 +696,7 @@ exports.AuthCodeStoreMemory = require_dynamic_client_store.AuthCodeStoreMemory;
 exports.AuthorizeError = AuthorizeError;
 exports.ClientRegistrationError = ClientRegistrationError;
 exports.CompositeClientPolicy = CompositeClientPolicy;
+exports.DEFAULT_AUTHZ_REFRESH_TTL_MS = DEFAULT_AUTHZ_REFRESH_TTL_MS;
 exports.DEFAULT_PENDING_TTL_MS = require_dynamic_client_store.DEFAULT_PENDING_TTL_MS;
 exports.DynamicClientPolicy = DynamicClientPolicy;
 exports.DynamicClientRegistration = DynamicClientRegistration;
@@ -628,6 +713,10 @@ exports.buildAuthorizationServerMetadata = buildAuthorizationServerMetadata;
 exports.buildProtectedResourceMetadata = buildProtectedResourceMetadata;
 exports.buildWwwAuthenticateBearerChallenge = buildWwwAuthenticateBearerChallenge;
 exports.canonicalizeIssuer = canonicalizeIssuer;
+exports.hashClientSecret = hashClientSecret;
 exports.isLoopbackRedirectUri = isLoopbackRedirectUri;
+exports.mintClientSecret = mintClientSecret;
 exports.scopeGrants = scopeGrants;
+exports.tokenPolicyToIssueOptions = tokenPolicyToIssueOptions;
 exports.validateClientRegistration = validateClientRegistration;
+exports.verifyClientSecret = verifyClientSecret;

package/dist/authz.d.cts

@@ -1,5 +1,5 @@
-import { t as Clock } from "./clock-BjXa0LXb.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 { t as Clock } from "./clock-DJ_eroHW.cjs";
+import { _ as PendingAuthorizationStoreMemoryOptions, a as DynamicClientStoreMemoryOptions, b as tokenPolicyToIssueOptions, c as AuthCodeStore, d as NewAuthCode, f as DEFAULT_PENDING_TTL_MS, g as PendingAuthorizationStoreMemory, h as PendingAuthorizationStore, i as DynamicClientStoreMemory, l as AuthCodeStoreMemory, m as PendingAuthorization, n as DynamicClientAuthMethod, o as NewDynamicClient, p as NewPendingAuthorization, r as DynamicClientStore, s as AuthCode, t as DynamicClient, u as AuthCodeStoreMemoryOptions, v as DEFAULT_AUTHZ_REFRESH_TTL_MS, y as TokenPolicy } from "./dynamic-client-store-DbiSLOj0.cjs";
 import { JWK } from "jose";
 
 //#region src/authz/authz-errors.d.ts
@@ -269,6 +269,15 @@ interface ClientRegistrationValidationOptions {
    * `DynamicClientPolicyOptions.allowedScopes` (the server allow-list).
    */
   allowedScopes?: string[];
+  /**
+   * Which `token_endpoint_auth_method` values registrations may use. Default:
+   * both supported methods (`["none", "client_secret_post"]` — matching what
+   * the RFC 8414 document advertises). Narrow to `["none"]` for a
+   * public-clients-only deployment. An explicit ask outside this list is
+   * REJECTED, never silently downgraded — a client that asked for a secret
+   * must not end up public without noticing.
+   */
+  allowedTokenEndpointAuthMethods?: DynamicClientAuthMethod[];
 }
 /**
  * Validate + normalize an RFC 7591 registration request body into a
@@ -277,13 +286,14 @@ interface ClientRegistrationValidationOptions {
  * 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.
+ * supports (an unsupported grant is dropped from the echo — the 201 echo of
+ * the narrowed set is the contract) rather than rejected, but the result must
+ * still include `authorization_code` (it is the only way to establish a grant;
+ * `refresh_token` alone mints nothing). `token_endpoint_auth_method` defaults
+ * to `"none"` when absent (the RFC's `client_secret_basic` default is
+ * unsupported — secrets travel in the POST form body); an EXPLICIT ask outside
+ * the allowed set 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 {
@@ -313,12 +323,28 @@ interface DynamicClientRegistrationOptions {
   /** Injectable clock for deterministic GC tests. Defaults to {@link defaultClock}. */
   clock?: Clock;
 }
+/**
+ * What {@link DynamicClientRegistration.register} returns: the persisted
+ * record plus — for a `client_secret_post` registration — the plaintext
+ * `clientSecret`, surfaced HERE and ONLY here (RFC 7591 §3.2.1: the secret is
+ * disclosed once in the registration response; the store keeps only its hash).
+ */
+type RegisteredDynamicClient = DynamicClient & {
+  clientSecret?: string;
+  /**
+   * Expiry of the minted secret in seconds since epoch (RFC 7591 §3.2.1's
+   * unit); `0` ⇒ the secret never expires. Present iff {@link clientSecret}
+   * is — decided HERE, where the secret is minted, so HTTP adapters echo the
+   * lifecycle instead of asserting their own.
+   */
+  clientSecretExpiresAt?: number;
+};
 /**
  * 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.
+ * mint secret (confidential) → 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;
@@ -328,10 +354,33 @@ declare class DynamicClientRegistration {
   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>;
+  /**
+   * Validate and persist a registration request body; returns the minted
+   * client. For a `client_secret_post` registration the returned record
+   * additionally carries the plaintext `clientSecret` (the ONE disclosure —
+   * only its SHA-256 digest is stored).
+   */
+  register(body: unknown): Promise<RegisteredDynamicClient>;
 }
 //#endregion
+//#region src/authz/client-secret.d.ts
+/**
+ * Mint a confidential dynamic client's secret (RFC 7591 `client_secret`) — a
+ * plain {@link generateOpaqueToken} mint. Returned to the registrant ONCE in
+ * the registration response; only its {@link hashClientSecret} digest is
+ * stored.
+ */
+declare function mintClientSecret(): string;
+/**
+ * Storage digest for a client secret — plain SHA-256 (hex). No KDF/salt on
+ * purpose: the secret is high-entropy server-minted material (never a human
+ * password), so brute-forcing the digest is infeasible and a per-row salt
+ * buys nothing.
+ */
+declare function hashClientSecret(secret: string): string;
+/** Constant-time check of a presented secret against a stored digest. */
+declare function verifyClientSecret(secret: string, hash: string): boolean;
+//#endregion
 //#region src/authz/dynamic-client-policy.d.ts
 interface DynamicClientPolicyOptions {
   store: DynamicClientStore;
@@ -353,13 +402,14 @@ interface DynamicClientPolicyOptions {
   clock?: Clock;
 }
 /**
- * Policy for RFC 7591 dynamically-registered public clients (OAUTH.md R2) on
- * the `ClientRedirectPolicy` seam. `resolveClient` authorizes the client +
+ * Policy for RFC 7591 dynamically-registered 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).
+ * (a registration garbage-collected mid-flight fails closed) and, for a
+ * `client_secret_post` registration, validates the presented secret against
+ * the stored digest (public `"none"` clients: PKCE is the binding). 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
@@ -379,9 +429,11 @@ declare class DynamicClientPolicy implements ClientRedirectPolicy {
   }): 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.
+   * registration was deleted/GC'd between authorize and redemption). A client
+   * registered with `token_endpoint_auth_method: "client_secret_post"` must
+   * additionally present its minted `client_secret` (constant-time check
+   * against the stored digest). For a public (`"none"`) client no secret is
+   * checked — PKCE is the binding; a spurious `client_secret` is ignored.
    */
   authenticateClient(args: {
     clientId?: string;
@@ -558,7 +610,9 @@ interface BuildAuthorizationServerMetadataOptions {
  *
  * Capability fields are fixed to what the server actually implements:
  * `response_types_supported` `["code"]`, `grant_types_supported`
- * `["authorization_code"]`, `code_challenge_methods_supported` `["S256"]`
+ * `["authorization_code", "refresh_token"]` (the grant is implemented server-
+ * wide; whether a given client's grant mints a refresh token is per-policy —
+ * `TokenPolicy.refresh`), `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.
@@ -627,4 +681,4 @@ interface WwwAuthenticateBearerChallengeOptions {
  */
 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 };
+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_AUTHZ_REFRESH_TTL_MS, DEFAULT_PENDING_TTL_MS, type DynamicClient, type DynamicClientAuthMethod, 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 RegisteredDynamicClient, type ResolvedClient, type TokenPolicy, type WwwAuthenticateBearerChallengeOptions, buildAuthorizationServerMetadata, buildProtectedResourceMetadata, buildWwwAuthenticateBearerChallenge, canonicalizeIssuer, hashClientSecret, isLoopbackRedirectUri, mintClientSecret, scopeGrants, tokenPolicyToIssueOptions, validateClientRegistration, verifyClientSecret };

package/dist/authz.d.mts

@@ -1,5 +1,5 @@
-import { t as Clock } from "./clock-BjXa0LXb.mjs";
-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-oHEsQaJg.mjs";
+import { t as Clock } from "./clock-DJ_eroHW.mjs";
+import { _ as PendingAuthorizationStoreMemoryOptions, a as DynamicClientStoreMemoryOptions, b as tokenPolicyToIssueOptions, c as AuthCodeStore, d as NewAuthCode, f as DEFAULT_PENDING_TTL_MS, g as PendingAuthorizationStoreMemory, h as PendingAuthorizationStore, i as DynamicClientStoreMemory, l as AuthCodeStoreMemory, m as PendingAuthorization, n as DynamicClientAuthMethod, o as NewDynamicClient, p as NewPendingAuthorization, r as DynamicClientStore, s as AuthCode, t as DynamicClient, u as AuthCodeStoreMemoryOptions, v as DEFAULT_AUTHZ_REFRESH_TTL_MS, y as TokenPolicy } from "./dynamic-client-store-DJgtMjPw.mjs";
 import { JWK } from "jose";
 
 //#region src/authz/authz-errors.d.ts
@@ -269,6 +269,15 @@ interface ClientRegistrationValidationOptions {
    * `DynamicClientPolicyOptions.allowedScopes` (the server allow-list).
    */
   allowedScopes?: string[];
+  /**
+   * Which `token_endpoint_auth_method` values registrations may use. Default:
+   * both supported methods (`["none", "client_secret_post"]` — matching what
+   * the RFC 8414 document advertises). Narrow to `["none"]` for a
+   * public-clients-only deployment. An explicit ask outside this list is
+   * REJECTED, never silently downgraded — a client that asked for a secret
+   * must not end up public without noticing.
+   */
+  allowedTokenEndpointAuthMethods?: DynamicClientAuthMethod[];
 }
 /**
  * Validate + normalize an RFC 7591 registration request body into a
@@ -277,13 +286,14 @@ interface ClientRegistrationValidationOptions {
  * 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.
+ * supports (an unsupported grant is dropped from the echo — the 201 echo of
+ * the narrowed set is the contract) rather than rejected, but the result must
+ * still include `authorization_code` (it is the only way to establish a grant;
+ * `refresh_token` alone mints nothing). `token_endpoint_auth_method` defaults
+ * to `"none"` when absent (the RFC's `client_secret_basic` default is
+ * unsupported — secrets travel in the POST form body); an EXPLICIT ask outside
+ * the allowed set 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 {
@@ -313,12 +323,28 @@ interface DynamicClientRegistrationOptions {
   /** Injectable clock for deterministic GC tests. Defaults to {@link defaultClock}. */
   clock?: Clock;
 }
+/**
+ * What {@link DynamicClientRegistration.register} returns: the persisted
+ * record plus — for a `client_secret_post` registration — the plaintext
+ * `clientSecret`, surfaced HERE and ONLY here (RFC 7591 §3.2.1: the secret is
+ * disclosed once in the registration response; the store keeps only its hash).
+ */
+type RegisteredDynamicClient = DynamicClient & {
+  clientSecret?: string;
+  /**
+   * Expiry of the minted secret in seconds since epoch (RFC 7591 §3.2.1's
+   * unit); `0` ⇒ the secret never expires. Present iff {@link clientSecret}
+   * is — decided HERE, where the secret is minted, so HTTP adapters echo the
+   * lifecycle instead of asserting their own.
+   */
+  clientSecretExpiresAt?: number;
+};
 /**
  * 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.
+ * mint secret (confidential) → 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;
@@ -328,10 +354,33 @@ declare class DynamicClientRegistration {
   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>;
+  /**
+   * Validate and persist a registration request body; returns the minted
+   * client. For a `client_secret_post` registration the returned record
+   * additionally carries the plaintext `clientSecret` (the ONE disclosure —
+   * only its SHA-256 digest is stored).
+   */
+  register(body: unknown): Promise<RegisteredDynamicClient>;
 }
 //#endregion
+//#region src/authz/client-secret.d.ts
+/**
+ * Mint a confidential dynamic client's secret (RFC 7591 `client_secret`) — a
+ * plain {@link generateOpaqueToken} mint. Returned to the registrant ONCE in
+ * the registration response; only its {@link hashClientSecret} digest is
+ * stored.
+ */
+declare function mintClientSecret(): string;
+/**
+ * Storage digest for a client secret — plain SHA-256 (hex). No KDF/salt on
+ * purpose: the secret is high-entropy server-minted material (never a human
+ * password), so brute-forcing the digest is infeasible and a per-row salt
+ * buys nothing.
+ */
+declare function hashClientSecret(secret: string): string;
+/** Constant-time check of a presented secret against a stored digest. */
+declare function verifyClientSecret(secret: string, hash: string): boolean;
+//#endregion
 //#region src/authz/dynamic-client-policy.d.ts
 interface DynamicClientPolicyOptions {
   store: DynamicClientStore;
@@ -353,13 +402,14 @@ interface DynamicClientPolicyOptions {
   clock?: Clock;
 }
 /**
- * Policy for RFC 7591 dynamically-registered public clients (OAUTH.md R2) on
- * the `ClientRedirectPolicy` seam. `resolveClient` authorizes the client +
+ * Policy for RFC 7591 dynamically-registered 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).
+ * (a registration garbage-collected mid-flight fails closed) and, for a
+ * `client_secret_post` registration, validates the presented secret against
+ * the stored digest (public `"none"` clients: PKCE is the binding). 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
@@ -379,9 +429,11 @@ declare class DynamicClientPolicy implements ClientRedirectPolicy {
   }): 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.
+   * registration was deleted/GC'd between authorize and redemption). A client
+   * registered with `token_endpoint_auth_method: "client_secret_post"` must
+   * additionally present its minted `client_secret` (constant-time check
+   * against the stored digest). For a public (`"none"`) client no secret is
+   * checked — PKCE is the binding; a spurious `client_secret` is ignored.
    */
   authenticateClient(args: {
     clientId?: string;
@@ -558,7 +610,9 @@ interface BuildAuthorizationServerMetadataOptions {
  *
  * Capability fields are fixed to what the server actually implements:
  * `response_types_supported` `["code"]`, `grant_types_supported`
- * `["authorization_code"]`, `code_challenge_methods_supported` `["S256"]`
+ * `["authorization_code", "refresh_token"]` (the grant is implemented server-
+ * wide; whether a given client's grant mints a refresh token is per-policy —
+ * `TokenPolicy.refresh`), `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.
@@ -627,4 +681,4 @@ interface WwwAuthenticateBearerChallengeOptions {
  */
 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 };
+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_AUTHZ_REFRESH_TTL_MS, DEFAULT_PENDING_TTL_MS, type DynamicClient, type DynamicClientAuthMethod, 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 RegisteredDynamicClient, type ResolvedClient, type TokenPolicy, type WwwAuthenticateBearerChallengeOptions, buildAuthorizationServerMetadata, buildProtectedResourceMetadata, buildWwwAuthenticateBearerChallenge, canonicalizeIssuer, hashClientSecret, isLoopbackRedirectUri, mintClientSecret, scopeGrants, tokenPolicyToIssueOptions, validateClientRegistration, verifyClientSecret };