@aooth/auth 0.1.6 → 0.1.8

package/dist/authz.d.cts

@@ -0,0 +1,252 @@
+import { t as Clock } from "./clock-BjXa0LXb.cjs";
+
+//#region src/authz/token-policy.d.ts
+/**
+ * What the authorization server mints for a completed grant — forwarded verbatim
+ * into `AuthCredential.issue(userId, …)` at the token endpoint. Decided by the
+ * {@link import("./client-policy").ClientRedirectPolicy} (per client / scope),
+ * never by the client request, and recorded on the pending-authorization + the
+ * issued auth-code so the grant's authority is fixed at `/authorize` time, not
+ * `/token` time.
+ *
+ * Tier 1 (CLI / loopback) → a full-authority `cli-session` (`{ kind, ttl }`, no
+ * `payload`). A scoped service token (Tier 2) additionally sets `payload` with
+ * the consumer's attenuation root fields.
+ */
+interface TokenPolicy {
+  /** Semantic credential kind stamped on the token (e.g. `"cli-session"`). See `IssueOptions.kind`. */
+  kind?: string;
+  /** Per-mint access-token lifetime in ms (forwarded to `IssueOptions.ttl`). */
+  ttl?: number;
+  /**
+   * Extra root payload merged into `issue()` — e.g. `@arbac.attenuate.*` fields
+   * for a SCOPED token. Omit for a full-authority token. MUST be JSON-safe: it
+   * is persisted on the pending-authorization + auth-code records.
+   */
+  payload?: Record<string, unknown>;
+}
+//#endregion
+//#region src/authz/authz-errors.d.ts
+/**
+ * Failure taxonomy for the authorization-server endpoints (AUTH-SERVER.md §7).
+ * The `/authorize` side fails SOFT (302 → an app error/login route, never a
+ * 500); the `/token` side returns the RFC-6749-shaped JSON error named by the
+ * 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" /** 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;
+  constructor(code: AuthorizeErrorCode, message: string);
+}
+//#endregion
+//#region src/authz/client-policy.d.ts
+/**
+ * The client + redirect resolved at `GET /auth/authorize` — what the grant is
+ * allowed to deliver and where.
+ */
+interface ResolvedClient {
+  /** Registered client id (Tier 2), absent for a public/loopback client. */
+  clientId?: string;
+  /** The validated `redirect_uri` the code will be delivered to. */
+  redirectUri: string;
+  /** What the grant mints (fixed here, recorded on the pending authorization). */
+  tokenPolicy: TokenPolicy;
+}
+/**
+ * The pluggable trust boundary of the authorization server (AUTH-SERVER.md §4.5):
+ * decide whether a client + `redirect_uri` may start a grant and what it may
+ * receive. The flow is otherwise identical across tiers — only this policy
+ * varies. Tier 1 ships {@link LoopbackClientPolicy}; a `RegisteredClientPolicy`
+ * (static client registry, exact/prefix redirect allowlist, `id_token`) is the
+ * Tier-2 addition.
+ */
+interface ClientRedirectPolicy {
+  /**
+   * Authorize the client + `redirect_uri` and resolve the token policy; THROW
+   * an {@link AuthorizeError} on a miss (`invalid_redirect` / `invalid_client`).
+   * This is THE open-redirect / token-theft gate — never reflect an unvalidated
+   * `redirect_uri`.
+   */
+  resolveClient(args: {
+    clientId?: string;
+    redirectUri: string;
+  }): ResolvedClient | Promise<ResolvedClient>;
+}
+/**
+ * `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.
+ */
+declare function isLoopbackRedirectUri(uri: string): boolean;
+interface LoopbackClientPolicyOptions {
+  /**
+   * What a loopback grant mints. Default: a full-authority `cli-session` with a
+   * 30-day TTL (un-attenuated — see {@link TokenPolicy}). Override to scope or
+   * re-label CLI tokens.
+   */
+  tokenPolicy?: TokenPolicy;
+}
+/**
+ * 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.
+ */
+declare class LoopbackClientPolicy implements ClientRedirectPolicy {
+  private readonly tokenPolicy;
+  constructor(opts?: LoopbackClientPolicyOptions);
+  resolveClient(args: {
+    clientId?: string;
+    redirectUri: string;
+  }): ResolvedClient;
+}
+//#endregion
+//#region src/authz/pending-authorization-store.d.ts
+/**
+ * One in-flight authorization request, recorded at `GET /auth/authorize` and
+ * read once at the login-workflow terminal that mints the auth code. Keyed by an
+ * opaque `handle` that rides the login-wf ctx (and, across a "Continue with
+ * Google" detour, the federated signed `state`) — so nothing secret leaves the
+ * server.
+ */
+interface PendingAuthorization {
+  /** Opaque server-side handle (the only thing that rides the URL / wf state). */
+  handle: string;
+  /** Registered client id (Tier 2), absent for a public/loopback client. */
+  clientId?: string;
+  /** The client's validated `redirect_uri` — where the code is delivered. */
+  redirectUri: string;
+  /** PKCE S256 challenge (client-generated); verified against the verifier at `/token`. */
+  codeChallenge: string;
+  /** The client's `state`, echoed back on the redirect so the client can correlate. */
+  clientState?: string;
+  /** Requested scope (space-joined), informational for Tier 1. */
+  scope?: string;
+  /** What the grant will mint (fixed at authorize time). */
+  tokenPolicy: TokenPolicy;
+  createdAt: number;
+  expiresAt: number;
+}
+/** Input to {@link PendingAuthorizationStore.create} — `handle`/timestamps are store-assigned. */
+interface NewPendingAuthorization {
+  clientId?: string;
+  redirectUri: string;
+  codeChallenge: string;
+  clientState?: string;
+  scope?: string;
+  tokenPolicy: TokenPolicy;
+}
+/**
+ * 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`).
+ */
+declare abstract class PendingAuthorizationStore {
+  /** Record a new pending authorization; returns its opaque `handle`. */
+  abstract create(rec: NewPendingAuthorization): Promise<{
+    handle: string;
+  }>;
+  /** Fetch by handle, or `null` when unknown/expired. */
+  abstract get(handle: string): Promise<PendingAuthorization | null>;
+  /** Drop a handle once consumed. Returns `true` when a row was removed. */
+  abstract delete(handle: string): Promise<boolean>;
+}
+interface PendingAuthorizationStoreMemoryOptions {
+  /** Injectable clock for deterministic expiry. Defaults to {@link defaultClock}. */
+  clock?: Clock;
+  /** How long a pending authorization stays valid. Default 15 min. */
+  ttlMs?: number;
+}
+/**
+ * In-memory {@link PendingAuthorizationStore} — the reference impl for a
+ * single-process app + tests. `structuredClone` on read/write isolates callers.
+ */
+declare class PendingAuthorizationStoreMemory extends PendingAuthorizationStore {
+  private store;
+  private clock;
+  private ttlMs;
+  constructor(opts?: PendingAuthorizationStoreMemoryOptions);
+  create(rec: NewPendingAuthorization): Promise<{
+    handle: string;
+  }>;
+  get(handle: string): Promise<PendingAuthorization | null>;
+  delete(handle: string): Promise<boolean>;
+}
+//#endregion
+//#region src/authz/auth-code-store.d.ts
+/**
+ * A minted, single-use authorization code, bound to the user the login resolved
+ * plus the PKCE challenge / redirect / token policy recorded at `/authorize`.
+ * Consumed atomically at `POST /auth/token` — the token is minted there, off the
+ * browser, so nothing long-lived ever rides a redirect URL.
+ */
+interface AuthCode {
+  /** Opaque single-use code (delivered to the client in the redirect query). */
+  code: string;
+  /** The user the login workflow authenticated. */
+  userId: string;
+  /** PKCE S256 challenge from the originating authorize request. */
+  codeChallenge: string;
+  /** The client's `redirect_uri` (bound; the code is meaningless elsewhere). */
+  redirectUri: string;
+  /** Registered client id (Tier 2), absent for a public/loopback client. */
+  clientId?: string;
+  /** What `/token` mints when this code is redeemed. */
+  tokenPolicy: TokenPolicy;
+  expiresAt: number;
+}
+/** Input to {@link AuthCodeStore.mint} — `code`/`expiresAt` are store-assigned. */
+interface NewAuthCode {
+  userId: string;
+  codeChallenge: string;
+  redirectUri: string;
+  clientId?: string;
+  tokenPolicy: TokenPolicy;
+}
+/**
+ * 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`).
+ */
+declare abstract class AuthCodeStore {
+  /** Mint + store a single-use code; returns the opaque code string. */
+  abstract mint(rec: NewAuthCode): Promise<{
+    code: string;
+  }>;
+  /** Atomically claim + return the code's row, or `null` on miss / reuse / expiry. */
+  abstract consume(code: string): Promise<AuthCode | null>;
+}
+interface AuthCodeStoreMemoryOptions {
+  /** Injectable clock for deterministic expiry. Defaults to {@link defaultClock}. */
+  clock?: Clock;
+  /** Code lifetime. Default 60 s. */
+  ttlMs?: number;
+}
+/**
+ * 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.
+ */
+declare class AuthCodeStoreMemory extends AuthCodeStore {
+  private store;
+  private clock;
+  private ttlMs;
+  constructor(opts?: AuthCodeStoreMemoryOptions);
+  mint(rec: NewAuthCode): Promise<{
+    code: string;
+  }>;
+  consume(code: string): Promise<AuthCode | null>;
+}
+//#endregion
+export { type AuthCode, AuthCodeStore, AuthCodeStoreMemory, type AuthCodeStoreMemoryOptions, AuthorizeError, type AuthorizeErrorCode, type ClientRedirectPolicy, LoopbackClientPolicy, type LoopbackClientPolicyOptions, type NewAuthCode, type NewPendingAuthorization, type PendingAuthorization, PendingAuthorizationStore, PendingAuthorizationStoreMemory, type PendingAuthorizationStoreMemoryOptions, type ResolvedClient, type TokenPolicy, isLoopbackRedirectUri };

package/dist/authz.d.mts

@@ -0,0 +1,252 @@
+import { t as Clock } from "./clock-BjXa0LXb.mjs";
+
+//#region src/authz/token-policy.d.ts
+/**
+ * What the authorization server mints for a completed grant — forwarded verbatim
+ * into `AuthCredential.issue(userId, …)` at the token endpoint. Decided by the
+ * {@link import("./client-policy").ClientRedirectPolicy} (per client / scope),
+ * never by the client request, and recorded on the pending-authorization + the
+ * issued auth-code so the grant's authority is fixed at `/authorize` time, not
+ * `/token` time.
+ *
+ * Tier 1 (CLI / loopback) → a full-authority `cli-session` (`{ kind, ttl }`, no
+ * `payload`). A scoped service token (Tier 2) additionally sets `payload` with
+ * the consumer's attenuation root fields.
+ */
+interface TokenPolicy {
+  /** Semantic credential kind stamped on the token (e.g. `"cli-session"`). See `IssueOptions.kind`. */
+  kind?: string;
+  /** Per-mint access-token lifetime in ms (forwarded to `IssueOptions.ttl`). */
+  ttl?: number;
+  /**
+   * Extra root payload merged into `issue()` — e.g. `@arbac.attenuate.*` fields
+   * for a SCOPED token. Omit for a full-authority token. MUST be JSON-safe: it
+   * is persisted on the pending-authorization + auth-code records.
+   */
+  payload?: Record<string, unknown>;
+}
+//#endregion
+//#region src/authz/authz-errors.d.ts
+/**
+ * Failure taxonomy for the authorization-server endpoints (AUTH-SERVER.md §7).
+ * The `/authorize` side fails SOFT (302 → an app error/login route, never a
+ * 500); the `/token` side returns the RFC-6749-shaped JSON error named by the
+ * 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" /** 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;
+  constructor(code: AuthorizeErrorCode, message: string);
+}
+//#endregion
+//#region src/authz/client-policy.d.ts
+/**
+ * The client + redirect resolved at `GET /auth/authorize` — what the grant is
+ * allowed to deliver and where.
+ */
+interface ResolvedClient {
+  /** Registered client id (Tier 2), absent for a public/loopback client. */
+  clientId?: string;
+  /** The validated `redirect_uri` the code will be delivered to. */
+  redirectUri: string;
+  /** What the grant mints (fixed here, recorded on the pending authorization). */
+  tokenPolicy: TokenPolicy;
+}
+/**
+ * The pluggable trust boundary of the authorization server (AUTH-SERVER.md §4.5):
+ * decide whether a client + `redirect_uri` may start a grant and what it may
+ * receive. The flow is otherwise identical across tiers — only this policy
+ * varies. Tier 1 ships {@link LoopbackClientPolicy}; a `RegisteredClientPolicy`
+ * (static client registry, exact/prefix redirect allowlist, `id_token`) is the
+ * Tier-2 addition.
+ */
+interface ClientRedirectPolicy {
+  /**
+   * Authorize the client + `redirect_uri` and resolve the token policy; THROW
+   * an {@link AuthorizeError} on a miss (`invalid_redirect` / `invalid_client`).
+   * This is THE open-redirect / token-theft gate — never reflect an unvalidated
+   * `redirect_uri`.
+   */
+  resolveClient(args: {
+    clientId?: string;
+    redirectUri: string;
+  }): ResolvedClient | Promise<ResolvedClient>;
+}
+/**
+ * `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.
+ */
+declare function isLoopbackRedirectUri(uri: string): boolean;
+interface LoopbackClientPolicyOptions {
+  /**
+   * What a loopback grant mints. Default: a full-authority `cli-session` with a
+   * 30-day TTL (un-attenuated — see {@link TokenPolicy}). Override to scope or
+   * re-label CLI tokens.
+   */
+  tokenPolicy?: TokenPolicy;
+}
+/**
+ * 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.
+ */
+declare class LoopbackClientPolicy implements ClientRedirectPolicy {
+  private readonly tokenPolicy;
+  constructor(opts?: LoopbackClientPolicyOptions);
+  resolveClient(args: {
+    clientId?: string;
+    redirectUri: string;
+  }): ResolvedClient;
+}
+//#endregion
+//#region src/authz/pending-authorization-store.d.ts
+/**
+ * One in-flight authorization request, recorded at `GET /auth/authorize` and
+ * read once at the login-workflow terminal that mints the auth code. Keyed by an
+ * opaque `handle` that rides the login-wf ctx (and, across a "Continue with
+ * Google" detour, the federated signed `state`) — so nothing secret leaves the
+ * server.
+ */
+interface PendingAuthorization {
+  /** Opaque server-side handle (the only thing that rides the URL / wf state). */
+  handle: string;
+  /** Registered client id (Tier 2), absent for a public/loopback client. */
+  clientId?: string;
+  /** The client's validated `redirect_uri` — where the code is delivered. */
+  redirectUri: string;
+  /** PKCE S256 challenge (client-generated); verified against the verifier at `/token`. */
+  codeChallenge: string;
+  /** The client's `state`, echoed back on the redirect so the client can correlate. */
+  clientState?: string;
+  /** Requested scope (space-joined), informational for Tier 1. */
+  scope?: string;
+  /** What the grant will mint (fixed at authorize time). */
+  tokenPolicy: TokenPolicy;
+  createdAt: number;
+  expiresAt: number;
+}
+/** Input to {@link PendingAuthorizationStore.create} — `handle`/timestamps are store-assigned. */
+interface NewPendingAuthorization {
+  clientId?: string;
+  redirectUri: string;
+  codeChallenge: string;
+  clientState?: string;
+  scope?: string;
+  tokenPolicy: TokenPolicy;
+}
+/**
+ * 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`).
+ */
+declare abstract class PendingAuthorizationStore {
+  /** Record a new pending authorization; returns its opaque `handle`. */
+  abstract create(rec: NewPendingAuthorization): Promise<{
+    handle: string;
+  }>;
+  /** Fetch by handle, or `null` when unknown/expired. */
+  abstract get(handle: string): Promise<PendingAuthorization | null>;
+  /** Drop a handle once consumed. Returns `true` when a row was removed. */
+  abstract delete(handle: string): Promise<boolean>;
+}
+interface PendingAuthorizationStoreMemoryOptions {
+  /** Injectable clock for deterministic expiry. Defaults to {@link defaultClock}. */
+  clock?: Clock;
+  /** How long a pending authorization stays valid. Default 15 min. */
+  ttlMs?: number;
+}
+/**
+ * In-memory {@link PendingAuthorizationStore} — the reference impl for a
+ * single-process app + tests. `structuredClone` on read/write isolates callers.
+ */
+declare class PendingAuthorizationStoreMemory extends PendingAuthorizationStore {
+  private store;
+  private clock;
+  private ttlMs;
+  constructor(opts?: PendingAuthorizationStoreMemoryOptions);
+  create(rec: NewPendingAuthorization): Promise<{
+    handle: string;
+  }>;
+  get(handle: string): Promise<PendingAuthorization | null>;
+  delete(handle: string): Promise<boolean>;
+}
+//#endregion
+//#region src/authz/auth-code-store.d.ts
+/**
+ * A minted, single-use authorization code, bound to the user the login resolved
+ * plus the PKCE challenge / redirect / token policy recorded at `/authorize`.
+ * Consumed atomically at `POST /auth/token` — the token is minted there, off the
+ * browser, so nothing long-lived ever rides a redirect URL.
+ */
+interface AuthCode {
+  /** Opaque single-use code (delivered to the client in the redirect query). */
+  code: string;
+  /** The user the login workflow authenticated. */
+  userId: string;
+  /** PKCE S256 challenge from the originating authorize request. */
+  codeChallenge: string;
+  /** The client's `redirect_uri` (bound; the code is meaningless elsewhere). */
+  redirectUri: string;
+  /** Registered client id (Tier 2), absent for a public/loopback client. */
+  clientId?: string;
+  /** What `/token` mints when this code is redeemed. */
+  tokenPolicy: TokenPolicy;
+  expiresAt: number;
+}
+/** Input to {@link AuthCodeStore.mint} — `code`/`expiresAt` are store-assigned. */
+interface NewAuthCode {
+  userId: string;
+  codeChallenge: string;
+  redirectUri: string;
+  clientId?: string;
+  tokenPolicy: TokenPolicy;
+}
+/**
+ * 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`).
+ */
+declare abstract class AuthCodeStore {
+  /** Mint + store a single-use code; returns the opaque code string. */
+  abstract mint(rec: NewAuthCode): Promise<{
+    code: string;
+  }>;
+  /** Atomically claim + return the code's row, or `null` on miss / reuse / expiry. */
+  abstract consume(code: string): Promise<AuthCode | null>;
+}
+interface AuthCodeStoreMemoryOptions {
+  /** Injectable clock for deterministic expiry. Defaults to {@link defaultClock}. */
+  clock?: Clock;
+  /** Code lifetime. Default 60 s. */
+  ttlMs?: number;
+}
+/**
+ * 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.
+ */
+declare class AuthCodeStoreMemory extends AuthCodeStore {
+  private store;
+  private clock;
+  private ttlMs;
+  constructor(opts?: AuthCodeStoreMemoryOptions);
+  mint(rec: NewAuthCode): Promise<{
+    code: string;
+  }>;
+  consume(code: string): Promise<AuthCode | null>;
+}
+//#endregion
+export { type AuthCode, AuthCodeStore, AuthCodeStoreMemory, type AuthCodeStoreMemoryOptions, AuthorizeError, type AuthorizeErrorCode, type ClientRedirectPolicy, LoopbackClientPolicy, type LoopbackClientPolicyOptions, type NewAuthCode, type NewPendingAuthorization, type PendingAuthorization, PendingAuthorizationStore, PendingAuthorizationStoreMemory, type PendingAuthorizationStoreMemoryOptions, type ResolvedClient, type TokenPolicy, isLoopbackRedirectUri };

package/dist/authz.mjs

@@ -0,0 +1,161 @@
+import { t as defaultClock } from "./clock-Bdsep_1j.mjs";
+import { randomUUID } from "node:crypto";
+//#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)
+		};
+	}
+};
+//#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 ?? defaultClock;
+		this.ttlMs = opts?.ttlMs ?? DEFAULT_PENDING_TTL_MS;
+	}
+	async create(rec) {
+		const now = this.clock.now();
+		const row = {
+			handle: 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 }
+		};
+		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 ?? defaultClock;
+		this.ttlMs = opts?.ttlMs ?? DEFAULT_CODE_TTL_MS;
+	}
+	async mint(rec) {
+		const code = 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 }
+		};
+		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
+export { AuthCodeStore, AuthCodeStoreMemory, AuthorizeError, LoopbackClientPolicy, PendingAuthorizationStore, PendingAuthorizationStoreMemory, isLoopbackRedirectUri };