@_mustachio/openauth 0.9.2 → 0.11.0

package/src/adapters/postgres/token-store.ts

@@ -0,0 +1,263 @@
+/**
+ * Postgres `TokenStore`.
+ *
+ * - `consumeCode` is an atomic `DELETE … RETURNING` so concurrent
+ *   presentations of the same code resolve to exactly one winner. The
+ *   ciphertext blob is stored verbatim — `domain/authorize.ts` encrypts
+ *   payloads before they reach the adapter (M1), and `domain/token.ts`
+ *   decrypts after consume. The DB never sees plaintext.
+ * - `consumeRefresh` does an atomic `UPDATE … WHERE consumed_at IS NULL
+ *   RETURNING payload` so a refresh chain has a single live winner per
+ *   generation. Reuse-detection within the configurable window auto-revokes
+ *   the family.
+ *
+ * On reuse-detection the adapter returns `invalid_grant` and populates
+ * the structured `reuseSignal` carrier on the error (family / tenantId /
+ * subjectId), per the `TokenStore` port contract. The domain's audit
+ * emission consumes the typed signal directly — no string parsing.
+ */
+import { AUTH_CODE_TTL_MS } from "../../domain/authorize"
+import type { KeyStore } from "../../ports/key-store"
+import type { TokenStore } from "../../ports/token-store"
+import { authError } from "../../types/error"
+import type { Result } from "../../types/result"
+import { err, ok } from "../../types/result"
+import type { TenantId } from "../../types/tenant"
+import type { RefreshTokenPayload } from "../../types/token"
+
+import type { PostgresExecutor } from "./executor"
+
+export type PostgresTokenStoreOptions = {
+  exec: PostgresExecutor
+  /**
+   * Optional — retained for API stability after M1 moved code-payload
+   * encryption to the domain layer. The adapter no longer touches it.
+   */
+  keyStore?: KeyStore
+  /** Injectable clock — defaults to `Date.now`. Tests advance it. */
+  clock?: () => number
+}
+
+export class PostgresTokenStore implements TokenStore {
+  #exec: PostgresExecutor
+  #clock: () => number
+
+  constructor(opts: PostgresTokenStoreOptions) {
+    this.#exec = opts.exec
+    this.#clock = opts.clock ?? (() => Date.now())
+  }
+
+  async saveCode(
+    code: string,
+    ciphertext: string,
+    ttl: number,
+  ): Promise<Result<void>> {
+    if (ttl <= 0 || ttl > AUTH_CODE_TTL_MS) {
+      return err(
+        authError.internalError(
+          `saveCode: ttl ${ttl} outside (0, ${AUTH_CODE_TTL_MS}] (auth-code TTL is fixed at 60s by OAuth 2.1 BCP)`,
+        ),
+      )
+    }
+    const expiresAt = this.#clock() + ttl
+    try {
+      await this.#exec.query(
+        `INSERT INTO openauth_codes (code, ciphertext, expires_at) VALUES ($1, $2, $3)`,
+        [code, ciphertext, expiresAt],
+      )
+    } catch (e) {
+      return err(authError.internalError("saveCode: insert failed", e))
+    }
+    return ok(undefined)
+  }
+
+  async consumeCode(code: string): Promise<Result<string>> {
+    let row: { ciphertext: string; expires_at: string | number } | undefined
+    try {
+      const result = await this.#exec.query<{
+        ciphertext: string
+        expires_at: string | number
+      }>(
+        `DELETE FROM openauth_codes WHERE code = $1 RETURNING ciphertext, expires_at`,
+        [code],
+      )
+      row = result.rows[0]
+    } catch (e) {
+      return err(authError.internalError("consumeCode: query failed", e))
+    }
+    if (!row) {
+      return err(
+        authError.invalidGrant("auth code unknown or already consumed"),
+      )
+    }
+    if (this.#clock() >= Number(row.expires_at)) {
+      return err(authError.invalidGrant("auth code expired"))
+    }
+    return ok(row.ciphertext)
+  }
+
+  async saveRefresh(
+    refresh: string,
+    payload: RefreshTokenPayload,
+  ): Promise<Result<void>> {
+    try {
+      await this.#exec.query(
+        `INSERT INTO openauth_refresh_tokens
+           (token, tenant_id, client_id, subject_id, family, expires_at, payload)
+         VALUES ($1, $2, $3, $4, $5, $6, $7::jsonb)`,
+        [
+          refresh,
+          payload.tenantId,
+          payload.clientId,
+          payload.subjectId,
+          payload.family,
+          payload.expiresAt,
+          JSON.stringify(payload),
+        ],
+      )
+    } catch (e) {
+      return err(authError.internalError("saveRefresh: insert failed", e))
+    }
+    return ok(undefined)
+  }
+
+  async consumeRefresh(
+    refresh: string,
+    options: { reuseWindowMs?: number } = {},
+  ): Promise<Result<RefreshTokenPayload>> {
+    const reuseWindow = options.reuseWindowMs ?? 60_000
+    const now = this.#clock()
+    // First try to atomically claim the token — exactly one concurrent caller
+    // gets a row back. The UPDATE bounds-checks expiry under the same row
+    // lock so an expired token won't be marked consumed under us.
+    let claimed: { payload: unknown } | undefined
+    try {
+      const result = await this.#exec.query<{ payload: unknown }>(
+        `UPDATE openauth_refresh_tokens
+           SET consumed_at = $1
+         WHERE token = $2
+           AND consumed_at IS NULL
+           AND expires_at > $1
+         RETURNING payload`,
+        [now, refresh],
+      )
+      claimed = result.rows[0]
+    } catch (e) {
+      return err(authError.internalError("consumeRefresh: claim failed", e))
+    }
+    if (claimed) {
+      return ok(parseRefreshPayload(claimed.payload))
+    }
+    // No row claimed. Find out why — unknown, expired, or already consumed.
+    let existing:
+      | {
+          consumed_at: string | number | null
+          expires_at: string | number
+          payload: unknown
+        }
+      | undefined
+    try {
+      const result = await this.#exec.query<{
+        consumed_at: string | number | null
+        expires_at: string | number
+        payload: unknown
+      }>(
+        `SELECT consumed_at, expires_at, payload
+           FROM openauth_refresh_tokens
+          WHERE token = $1`,
+        [refresh],
+      )
+      existing = result.rows[0]
+    } catch (e) {
+      return err(authError.internalError("consumeRefresh: lookup failed", e))
+    }
+    if (!existing) {
+      return err(authError.invalidGrant("refresh token unknown"))
+    }
+    if (existing.consumed_at !== null && existing.consumed_at !== undefined) {
+      const consumedAt = Number(existing.consumed_at)
+      const withinWindow = now - consumedAt <= reuseWindow
+      if (withinWindow) {
+        const payload = parseRefreshPayload(existing.payload)
+        await this.revokeFamily(payload.family)
+        return err(
+          authError.invalidGrant(
+            `refresh token reuse detected (family=${payload.family})`,
+            {
+              family: payload.family,
+              tenantId: payload.tenantId,
+              subjectId: payload.subjectId,
+            },
+          ),
+        )
+      }
+      return err(authError.invalidGrant("refresh token already consumed"))
+    }
+    if (now >= Number(existing.expires_at)) {
+      return err(authError.invalidGrant("refresh token expired"))
+    }
+    // Should be unreachable — the UPDATE matched neither, but the row is
+    // unconsumed and unexpired. Surface as internal so we notice.
+    return err(authError.internalError("consumeRefresh: unexplained miss"))
+  }
+
+  async peekRefresh(refresh: string): Promise<Result<RefreshTokenPayload>> {
+    let row: { expires_at: string | number; payload: unknown } | undefined
+    try {
+      const result = await this.#exec.query<{
+        expires_at: string | number
+        payload: unknown
+      }>(
+        `SELECT expires_at, payload
+           FROM openauth_refresh_tokens
+          WHERE token = $1`,
+        [refresh],
+      )
+      row = result.rows[0]
+    } catch (e) {
+      return err(authError.internalError("peekRefresh: lookup failed", e))
+    }
+    if (!row) {
+      return err(authError.invalidGrant("refresh token unknown"))
+    }
+    if (this.#clock() >= Number(row.expires_at)) {
+      return err(authError.invalidGrant("refresh token expired"))
+    }
+    return ok(parseRefreshPayload(row.payload))
+  }
+
+  async revokeFamily(family: string): Promise<Result<void>> {
+    try {
+      await this.#exec.query(
+        `DELETE FROM openauth_refresh_tokens WHERE family = $1`,
+        [family],
+      )
+    } catch (e) {
+      return err(authError.internalError("revokeFamily: delete failed", e))
+    }
+    return ok(undefined)
+  }
+
+  async revokeBySubject(
+    tenantId: TenantId,
+    subjectId: string,
+  ): Promise<Result<void>> {
+    try {
+      await this.#exec.query(
+        `DELETE FROM openauth_refresh_tokens
+          WHERE tenant_id = $1 AND subject_id = $2`,
+        [tenantId, subjectId],
+      )
+    } catch (e) {
+      return err(authError.internalError("revokeBySubject: delete failed", e))
+    }
+    return ok(undefined)
+  }
+}
+
+function parseRefreshPayload(raw: unknown): RefreshTokenPayload {
+  // PGlite returns parsed JSON; postgres-js may return a string depending on
+  // pool config. Be tolerant of both.
+  if (typeof raw === "string") return JSON.parse(raw) as RefreshTokenPayload
+  return raw as RefreshTokenPayload
+}

package/src/client.ts

@@ -45,7 +45,7 @@ import {
   jwtVerify,
   decodeJwt,
 } from "jose"
-import { SubjectSchema } from "./subject.js"
+import type { SubjectSchema } from "./types/subject"
 import type { v1 } from "@standard-schema/spec"
 import {
   InvalidAccessTokenError,
@@ -91,6 +91,14 @@ export interface Tokens {
    * The number of seconds until the access token expires.
    */
   expiresIn: number
+
+  /**
+   * The OIDC `id_token` (signed JWT), present when `scope=openid` was granted.
+   *
+   * Refresh-grant rotation reissues this with a stable `auth_time` per
+   * OIDC Core §12 and deliberately omits the original `nonce`.
+   */
+  idToken?: string
 }
 
 interface ResponseLike {
@@ -178,6 +186,18 @@ export interface AuthorizeOptions {
    * If there's only one provider configured, the user will be redirected to that.
    */
   provider?: string
+  /**
+   * OAuth scopes to request, e.g. `["openid", "email", "profile"]`.
+   *
+   * Pass `openid` to request an `id_token` at `/token` (OIDC Core §2). Pass
+   * `email` / `profile` / `phone` / `address` to opt into the standard §5.4
+   * profile claim sets on the id_token and `/userinfo` response.
+   *
+   * Accepts an array or a pre-joined space-separated string. When omitted,
+   * no `scope` is sent — the IdP's default grant applies, which typically
+   * does NOT include `openid` and therefore does NOT issue an id_token.
+   */
+  scope?: string | string[]
 }
 
 export interface AuthorizeResult {
@@ -588,6 +608,12 @@ export function createClient(input: ClientInput): Client {
       result.searchParams.set("response_type", response)
       result.searchParams.set("state", challenge.state)
       if (opts?.provider) result.searchParams.set("provider", opts.provider)
+      if (opts?.scope !== undefined) {
+        const scope = Array.isArray(opts.scope)
+          ? opts.scope.join(" ")
+          : opts.scope
+        if (scope) result.searchParams.set("scope", scope)
+      }
       if (opts?.pkce && response === "code") {
         const pkce = await generatePKCE()
         result.searchParams.set("code_challenge_method", "S256")
@@ -648,6 +674,9 @@ export function createClient(input: ClientInput): Client {
           access: json.access_token as string,
           refresh: json.refresh_token as string,
           expiresIn: json.expires_in as number,
+          ...(typeof json.id_token === "string"
+            ? { idToken: json.id_token as string }
+            : {}),
         },
       }
     },
@@ -691,6 +720,9 @@ export function createClient(input: ClientInput): Client {
           access: json.access_token as string,
           refresh: json.refresh_token as string,
           expiresIn: json.expires_in as number,
+          ...(typeof json.id_token === "string"
+            ? { idToken: json.id_token as string }
+            : {}),
         },
       }
     },
@@ -701,26 +733,60 @@ export function createClient(input: ClientInput): Client {
     ): Promise<VerifyResult<T> | VerifyError> {
       const jwks = await getJWKS()
       try {
+        // Two issuer shapes are supported:
+        //
+        //   1. New `createIdP` — `AccessTokenClaims.claim = { type,
+        //      properties }`. No `mode` claim.
+        //   2. Legacy `issuer({...})` — `payload.type` / `payload.properties`
+        //      at the top level, gated by `payload.mode === "access"` so the
+        //      same key ring couldn't sign a refresh token that verified as
+        //      an access token.
+        //
+        // Prefer the nested shape, fall back to the top-level shape.
         const result = await jwtVerify<{
-          mode: "access"
-          type: keyof T
-          properties: v1.InferInput<T[keyof T]>
+          claim?: {
+            type: keyof T
+            properties: v1.InferInput<T[keyof T]>
+          }
+          mode?: "access" | "refresh"
+          type?: keyof T
+          properties?: v1.InferInput<T[keyof T]>
         }>(token, jwks, {
           issuer,
         })
-        const validated = await subjects[result.payload.type][
-          "~standard"
-        ].validate(result.payload.properties)
-        if (!validated.issues && result.payload.mode === "access")
-          return {
-            aud: result.payload.aud as string,
-            subject: {
-              type: result.payload.type,
-              properties: validated.value,
-            } as any,
-          }
+        const claim = result.payload.claim
+        let subjectType: keyof T | undefined
+        let subjectProperties: v1.InferInput<T[keyof T]> | undefined
+        if (claim && typeof claim.type === "string") {
+          // New shape — `mode` is not emitted; nested claim is authoritative.
+          subjectType = claim.type
+          subjectProperties = claim.properties
+        } else if (
+          result.payload.mode === "access" &&
+          typeof result.payload.type === "string"
+        ) {
+          // Legacy shape — keep the mode gate so a refresh-token payload
+          // signed under the same keys does not verify as an access token.
+          subjectType = result.payload.type
+          subjectProperties = result.payload.properties
+        }
+        if (subjectType === undefined) {
+          return { err: new InvalidSubjectError() }
+        }
+        const schema = subjects[subjectType]
+        if (!schema) {
+          return { err: new InvalidSubjectError() }
+        }
+        const validated = await schema["~standard"].validate(subjectProperties)
+        if (validated.issues) {
+          return { err: new InvalidSubjectError() }
+        }
         return {
-          err: new InvalidSubjectError(),
+          aud: result.payload.aud as string,
+          subject: {
+            type: subjectType,
+            properties: validated.value,
+          } as any,
         }
       } catch (e) {
         if (e instanceof errors.JWTExpired && options?.refresh) {

package/src/domain/audit.ts

@@ -0,0 +1,28 @@
+/**
+ * Shared `safeAudit` helper — every domain module that emits audit
+ * events used to keep its own private `audit(...)` wrapper around
+ * `auditLog.log(event)` that silently swallowed any thrown error. The
+ * intent (per `ports/audit-log.ts`) is that audit emission must not
+ * derail the OAuth hot path, but operators have no signal when the
+ * pipeline goes down.
+ *
+ * Until the Logger port lands in Phase 8, durability failures here
+ * surface via `console.error` with a discriminating prefix. The Logger
+ * port will replace this single helper — the call sites stay put.
+ */
+import type { AuditLog } from "../ports/audit-log"
+
+export async function safeAudit(
+  deps: { auditLog?: AuditLog },
+  event: Parameters<AuditLog["log"]>[0],
+): Promise<void> {
+  if (!deps.auditLog) return
+  try {
+    await deps.auditLog.log(event)
+  } catch (e) {
+    console.error(
+      `[openauth] auditLog.log failed for kind=${event.kind} — audit gap; check your AuditLog adapter health`,
+      e,
+    )
+  }
+}