@aooth/auth 0.1.7 → 0.1.9

package/dist/authz.cjs

@@ -0,0 +1,378 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_clock = require("./clock-Bl-H3eqE.cjs");
+let node_crypto = require("node:crypto");
+let jose = require("jose");
+//#region src/authz/authz-errors.ts
+/** A typed authorization-server failure. */
+var AuthorizeError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.name = "AuthorizeError";
+		this.code = code;
+	}
+};
+//#endregion
+//#region src/authz/client-policy.ts
+/**
+* `true` when `uri` is a syntactically valid http(s) URL whose host is a
+* **loopback literal** — `127.0.0.1`, `::1`, or `localhost` — on any port (RFC
+* 8252 §7.3). Rejects everything else, including the classic bypasses: a
+* host-suffix (`127.0.0.1.evil.com`, `localhost.evil.com`), embedded credentials
+* (`http://127.0.0.1@evil.com` → host `evil.com`), a non-http scheme, and a bare
+* `0.0.0.0`. Only a local process can receive a loopback redirect, which is why
+* an arbitrary port is safe — the binding is the loopback host + PKCE.
+*/
+function isLoopbackRedirectUri(uri) {
+	let url;
+	try {
+		url = new URL(uri);
+	} catch {
+		return false;
+	}
+	if (url.protocol !== "http:" && url.protocol !== "https:") return false;
+	if (url.username !== "" || url.password !== "") return false;
+	const host = url.hostname.replace(/^\[|\]$/g, "");
+	return host === "127.0.0.1" || host === "::1" || host === "localhost";
+}
+const DEFAULT_CLI_TOKEN_POLICY = {
+	kind: "cli-session",
+	ttl: 720 * 60 * 6e4
+};
+/**
+* Tier-1 policy: accept any **loopback** `redirect_uri`, treat the client as a
+* public client (no `client_id` / secret — PKCE is the binding), and mint the
+* configured CLI token policy. Rejects every non-loopback redirect.
+*/
+var LoopbackClientPolicy = class {
+	tokenPolicy;
+	constructor(opts) {
+		this.tokenPolicy = opts?.tokenPolicy ?? DEFAULT_CLI_TOKEN_POLICY;
+	}
+	resolveClient(args) {
+		if (!isLoopbackRedirectUri(args.redirectUri)) throw new AuthorizeError("invalid_redirect", "redirect_uri must be a loopback address");
+		return {
+			redirectUri: args.redirectUri,
+			tokenPolicy: structuredClone(this.tokenPolicy),
+			...args.scope !== void 0 && { scope: args.scope }
+		};
+	}
+};
+//#endregion
+//#region src/authz/oidc-claims-resolver.ts
+/**
+* Resolves the OIDC profile claims to embed in an `id_token` for a given user +
+* granted scope (AUTH-SERVER.md §4.9). The authorization server already controls
+* the registered claims (`iss`/`aud`/`sub`/`iat`/`exp`/`nonce`) itself — this seam
+* supplies the **profile** claims that depend on the consumer's user shape
+* (`email`/`email_verified`/`name`/`picture`), which `@aooth/auth` cannot know.
+*
+* Pluggable like every other store/policy: the no-op default ({@link NoopOidcClaimsResolver},
+* `sub`-only tokens) ships, and a consumer subclasses it to read its own user
+* record. Bound in `@aooth/auth-moost` under `OIDC_CLAIMS_RESOLVER_TOKEN`.
+*
+* The map's keys are standard OIDC claim names; values MUST be JSON-safe. Honour
+* the granted `scope` — only emit `email`/`email_verified` under `email`, and
+* `name`/`picture`/etc. under `profile`, so a client receives only what it asked
+* for (and was allowed).
+*/
+var OidcClaimsResolver = class {};
+/** Default resolver: emits no profile claims, so the `id_token` carries only `sub` + the registered claims. */
+var NoopOidcClaimsResolver = class extends OidcClaimsResolver {
+	resolveClaims() {
+		return {};
+	}
+};
+/** `true` when `scope` (space-joined) grants `claim` — `"email"`/`"profile"` etc. */
+function scopeGrants(scope, claim) {
+	if (!scope) return false;
+	return scope.split(/\s+/u).includes(claim);
+}
+//#endregion
+//#region src/authz/registered-client-policy.ts
+/**
+* Tier-2 policy: a static registry of first-party clients. `resolveClient`
+* authorizes the client + `redirect_uri` (against the registered allowlist) and
+* resolves the granted scope + what the grant delivers (`id_token`/`access_token`,
+* `aud = client_id`); `authenticateClient` authenticates the client at `/token`
+* (`client_secret` for confidential clients; PKCE is the binding for public ones).
+* An unregistered client or an unlisted redirect is rejected.
+*/
+var RegisteredClientPolicy = class {
+	clients = /* @__PURE__ */ new Map();
+	constructor(opts) {
+		for (const c of opts.clients) this.clients.set(c.clientId, c);
+	}
+	resolveClient(args) {
+		const client = this.requireClient(args.clientId);
+		if (!this.redirectAllowed(client, args.redirectUri)) throw new AuthorizeError("invalid_redirect", "redirect_uri is not registered for this client");
+		const scope = this.grantScope(client, args.scope);
+		const idToken = client.idToken !== false && scopeGrants(scope, "openid");
+		return {
+			clientId: client.clientId,
+			redirectUri: args.redirectUri,
+			audience: client.clientId,
+			idToken,
+			accessToken: client.accessToken === true,
+			tokenPolicy: client.tokenPolicy ? structuredClone(client.tokenPolicy) : {},
+			...scope !== void 0 && { scope }
+		};
+	}
+	authenticateClient(args) {
+		const client = this.requireClient(args.clientId);
+		if ((client.type ?? "public") !== "confidential") return;
+		if (!client.clientSecret || !args.clientSecret || !timingSafeEqualStr(args.clientSecret, client.clientSecret)) throw new AuthorizeError("invalid_client", "client authentication failed");
+	}
+	requireClient(clientId) {
+		const client = clientId ? this.clients.get(clientId) : void 0;
+		if (!client) throw new AuthorizeError("invalid_client", "unknown client");
+		return client;
+	}
+	redirectAllowed(client, uri) {
+		if (client.redirectUris?.includes(uri)) return true;
+		if (!client.redirectPrefixes?.length) return false;
+		let normalized;
+		try {
+			normalized = new URL(uri).href;
+		} catch {
+			return false;
+		}
+		return client.redirectPrefixes.some((p) => {
+			if (p.length === 0 || !normalized.startsWith(p)) return false;
+			if (p.endsWith("/")) return true;
+			const next = normalized[p.length];
+			return next === void 0 || next === "/" || next === "?" || next === "#";
+		});
+	}
+	grantScope(client, requested) {
+		if (!requested) return void 0;
+		const req = requested.split(/\s+/u).filter(Boolean);
+		const granted = client.scopes ? req.filter((s) => client.scopes.includes(s)) : req;
+		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
+/**
+* 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.
+*/
+var CompositeClientPolicy = class {
+	loopback;
+	registered;
+	constructor(opts) {
+		this.loopback = opts.loopback;
+		this.registered = opts.registered;
+	}
+	resolveClient(args) {
+		return args.clientId ? this.registered.resolveClient(args) : this.loopback.resolveClient(args);
+	}
+	authenticateClient(args) {
+		if (args.clientId) return this.registered.authenticateClient?.(args);
+	}
+};
+//#endregion
+//#region src/authz/id-token-signer.ts
+/**
+* Signs OIDC `id_token`s and publishes the matching JWKS (AUTH-SERVER.md §4.9).
+* Holds one asymmetric keypair; mints short-lived RS256/ES256 tokens with the
+* issuer + audience + subject a relying `OidcProvider` validates, and exports the
+* public half as a JWKS for `GET /auth/jwks`. Keys are imported lazily and cached
+* (the Apple-client-secret pattern), so construction is cheap and synchronous.
+*
+* Never used for the access token (that stays in `AuthCredential`'s store) — the
+* `id_token` is a separate, audience-bound identity assertion.
+*/
+var IdTokenSigner = class {
+	/** The `iss` claim + discovery `issuer` (read by `/.well-known/openid-configuration`). */
+	issuer;
+	/** Signature algorithm — published in discovery's `id_token_signing_alg_values_supported`. */
+	alg;
+	/** Key id — the JWS header + JWKS entry `kid`. */
+	kid;
+	privateKeyPem;
+	publicKeyPem;
+	ttlSec;
+	clock;
+	privateKeyPromise;
+	jwksPromise;
+	constructor(opts) {
+		this.issuer = opts.issuer.replace(/\/$/u, "");
+		this.alg = opts.alg ?? "RS256";
+		this.kid = opts.kid;
+		this.privateKeyPem = opts.privateKey;
+		this.publicKeyPem = opts.publicKey;
+		this.ttlSec = opts.ttlSec ?? 300;
+		this.clock = opts.clock ?? require_clock.defaultClock;
+	}
+	/** Mint a signed `id_token` JWT. Iat/exp come from the injected clock. */
+	async sign(claims) {
+		const key = await this.importPrivateKey();
+		const nowSec = Math.floor(this.clock.now() / 1e3);
+		const ttl = claims.ttlSec ?? this.ttlSec;
+		const payload = { ...claims.extra };
+		if (claims.nonce !== void 0) payload.nonce = claims.nonce;
+		return new jose.SignJWT(payload).setProtectedHeader({
+			alg: this.alg,
+			kid: this.kid,
+			typ: "JWT"
+		}).setIssuer(this.issuer).setSubject(claims.sub).setAudience(claims.aud).setIssuedAt(nowSec).setExpirationTime(nowSec + ttl).sign(key);
+	}
+	/**
+	* The JWKS document served at `/auth/jwks` — the public key as a single
+	* `use: "sig"` entry tagged with the same `kid`/`alg` as the minted tokens, so
+	* a verifier selects it by `kid`. Computed once and cached.
+	*/
+	async jwks() {
+		this.jwksPromise ??= (async () => {
+			const jwk = await (0, jose.exportJWK)(await (0, jose.importSPKI)(this.publicKeyPem, this.alg, { extractable: true }));
+			jwk.kid = this.kid;
+			jwk.alg = this.alg;
+			jwk.use = "sig";
+			return { keys: [jwk] };
+		})();
+		return this.jwksPromise;
+	}
+	importPrivateKey() {
+		this.privateKeyPromise ??= (0, jose.importPKCS8)(this.privateKeyPem, this.alg);
+		return this.privateKeyPromise;
+	}
+};
+//#endregion
+//#region src/authz/pending-authorization-store.ts
+/**
+* Storage seam for in-flight authorizations (AUTH-SERVER.md §4.3). Short-lived
+* (≈ the login-session ceiling): created at `/authorize`, read+deleted at the
+* wf terminal. An in-memory impl ships for single-process apps + tests; a
+* multi-pod deployment provides a durable (e.g. Redis) impl under the same
+* `PENDING_AUTHORIZATION_STORE_TOKEN` (from `@aooth/auth-moost`).
+*/
+var PendingAuthorizationStore = class {};
+const DEFAULT_PENDING_TTL_MS = 15 * 6e4;
+/**
+* In-memory {@link PendingAuthorizationStore} — the reference impl for a
+* single-process app + tests. `structuredClone` on read/write isolates callers.
+*/
+var PendingAuthorizationStoreMemory = class extends PendingAuthorizationStore {
+	store = /* @__PURE__ */ new Map();
+	clock;
+	ttlMs;
+	constructor(opts) {
+		super();
+		this.clock = opts?.clock ?? require_clock.defaultClock;
+		this.ttlMs = opts?.ttlMs ?? DEFAULT_PENDING_TTL_MS;
+	}
+	async create(rec) {
+		const now = this.clock.now();
+		const row = {
+			handle: (0, node_crypto.randomUUID)(),
+			redirectUri: rec.redirectUri,
+			codeChallenge: rec.codeChallenge,
+			tokenPolicy: structuredClone(rec.tokenPolicy),
+			createdAt: now,
+			expiresAt: now + this.ttlMs,
+			...rec.clientId !== void 0 && { clientId: rec.clientId },
+			...rec.clientState !== void 0 && { clientState: rec.clientState },
+			...rec.scope !== void 0 && { scope: rec.scope },
+			...rec.nonce !== void 0 && { nonce: rec.nonce },
+			...rec.idToken !== void 0 && { idToken: rec.idToken },
+			...rec.accessToken !== void 0 && { accessToken: rec.accessToken },
+			...rec.audience !== void 0 && { audience: rec.audience }
+		};
+		this.store.set(row.handle, structuredClone(row));
+		return { handle: row.handle };
+	}
+	async get(handle) {
+		const row = this.store.get(handle);
+		if (!row) return null;
+		if (row.expiresAt <= this.clock.now()) {
+			this.store.delete(handle);
+			return null;
+		}
+		return structuredClone(row);
+	}
+	async delete(handle) {
+		return this.store.delete(handle);
+	}
+};
+//#endregion
+//#region src/authz/auth-code-store.ts
+/**
+* Storage seam for issued authorization codes (AUTH-SERVER.md §4.3). Very
+* short-lived (≈ 30–60 s) and **single-use**: {@link consume} returns the row
+* AND invalidates it in one atomic step, so a concurrent double-redeem (or a
+* back-button replay) yields the code to exactly one caller. An in-memory impl
+* ships (atomic for free in single-threaded JS); a durable impl must implement
+* `consume` as an atomic check-and-delete (e.g. `withCas` / `@db.column.version`,
+* or a Redis `GETDEL`).
+*/
+var AuthCodeStore = class {};
+const DEFAULT_CODE_TTL_MS = 6e4;
+/**
+* In-memory {@link AuthCodeStore} — the reference impl. `consume` is atomic
+* because the `get` + `delete` run with no intervening `await`, so a second
+* concurrent `consume` of the same code always misses.
+*/
+var AuthCodeStoreMemory = class extends AuthCodeStore {
+	store = /* @__PURE__ */ new Map();
+	clock;
+	ttlMs;
+	constructor(opts) {
+		super();
+		this.clock = opts?.clock ?? require_clock.defaultClock;
+		this.ttlMs = opts?.ttlMs ?? DEFAULT_CODE_TTL_MS;
+	}
+	async mint(rec) {
+		const code = (0, node_crypto.randomUUID)();
+		const row = {
+			code,
+			userId: rec.userId,
+			codeChallenge: rec.codeChallenge,
+			redirectUri: rec.redirectUri,
+			tokenPolicy: structuredClone(rec.tokenPolicy),
+			expiresAt: this.clock.now() + this.ttlMs,
+			...rec.clientId !== void 0 && { clientId: rec.clientId },
+			...rec.scope !== void 0 && { scope: rec.scope },
+			...rec.nonce !== void 0 && { nonce: rec.nonce },
+			...rec.idToken !== void 0 && { idToken: rec.idToken },
+			...rec.accessToken !== void 0 && { accessToken: rec.accessToken },
+			...rec.audience !== void 0 && { audience: rec.audience }
+		};
+		this.store.set(code, structuredClone(row));
+		return { code };
+	}
+	async consume(code) {
+		const row = this.store.get(code);
+		if (!row) return null;
+		this.store.delete(code);
+		if (row.expiresAt <= this.clock.now()) return null;
+		return structuredClone(row);
+	}
+};
+//#endregion
+exports.AuthCodeStore = AuthCodeStore;
+exports.AuthCodeStoreMemory = AuthCodeStoreMemory;
+exports.AuthorizeError = AuthorizeError;
+exports.CompositeClientPolicy = CompositeClientPolicy;
+exports.IdTokenSigner = IdTokenSigner;
+exports.LoopbackClientPolicy = LoopbackClientPolicy;
+exports.NoopOidcClaimsResolver = NoopOidcClaimsResolver;
+exports.OidcClaimsResolver = OidcClaimsResolver;
+exports.PendingAuthorizationStore = PendingAuthorizationStore;
+exports.PendingAuthorizationStoreMemory = PendingAuthorizationStoreMemory;
+exports.RegisteredClientPolicy = RegisteredClientPolicy;
+exports.isLoopbackRedirectUri = isLoopbackRedirectUri;
+exports.scopeGrants = scopeGrants;