@theokit/sdk 4.63.4 → 5.0.0-next.2

package/dist/server/auth/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/server/auth/validate-return-to.ts","../../../src/server/auth/orchestrator.ts"],"names":["webcrypto","AuthConfigError","AuthProviderNotFoundError","newTransaction","AuthCancelledError","AuthCallbackError","getTransaction","clearTransaction"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * Clamp a caller-supplied `returnTo` to a same-origin destination, falling back\n * to `'/'` for anything else. This is the open-redirect guard for a post-login\n * redirect (`@theokit/sdk/server/auth`; OWASP A01:2021, v1.1 EC-2). Without it,\n * `/login?returnTo=https://evil.com` would send the freshly authenticated session\n * to an attacker's domain.\n *\n *   validateReturnTo(req.query.returnTo, new URL(\"https://app.example.com\"));\n *\n * Pure and synchronous. It never throws and always returns a string:\n *   - undefined / empty / whitespace-only `returnTo` -> `'/'`\n *   - protocol-relative `//evil.com` -> `'/'` (a browser would resolve it against\n *     the current protocol)\n *   - absolute URL whose origin differs from `baseUrl.origin` -> `'/'`\n *   - absolute URL on `baseUrl.origin` -> its `pathname + search + hash`, with\n *     the origin dropped\n *   - relative path starting with `'/'` -> kept verbatim\n *   - anything else, including `javascript:` and `data:` -> `'/'`\n *\n * `baseUrl` is compared by ORIGIN only (scheme + host + port); its path is\n * ignored, so an app mounted under a sub-path gets no extra containment from it.\n *\n * Trap: this defends the origin, not the route. A same-origin relative path is\n * returned unchanged — `..` segments included, and with no notion of whether the\n * user is allowed there. Authorise the destination separately.\n */\nexport function validateReturnTo(returnTo: string | undefined, baseUrl: URL): string {\n  if (!returnTo || typeof returnTo !== \"string\" || returnTo.trim() === \"\") {\n    return \"/\";\n  }\n\n  const trimmed = returnTo.trim();\n\n  // Protocol-relative URLs (//evil.com) are dangerous — browser would resolve to current protocol\n  if (trimmed.startsWith(\"//\")) {\n    return \"/\";\n  }\n\n  // Try absolute URL parsing first\n  if (URL.canParse(trimmed)) {\n    const parsed = new URL(trimmed);\n    if (parsed.origin === baseUrl.origin) {\n      // Same-origin absolute URL — return the pathname+search+hash portion (drop origin)\n      return parsed.pathname + parsed.search + parsed.hash;\n    }\n    // Cross-origin — reject\n    return \"/\";\n  }\n\n  // Not parseable as absolute. Must start with '/' to be a valid relative path\n  if (trimmed.startsWith(\"/\")) {\n    return trimmed;\n  }\n\n  // Anything else (e.g., \"javascript:alert\", \"data:...\" that wasn't parseable, or bare strings) → default\n  return \"/\";\n}\n","/**\n * DefineAuth orchestrator runtime (Path C Hybrid) — `@theokit/sdk/server/auth`.\n *\n * Plan T1.2 implementation per blueprint Q5 § Path C signatures.\n * Composes existing primitives + the v1.1 EC-1/EC-2/EC-10 fixes.\n */\n\nimport { webcrypto } from \"node:crypto\";\nimport type { IncomingMessage, ServerResponse } from \"node:http\";\nimport {\n  AuthCallbackError,\n  AuthCancelledError,\n  AuthConfigError,\n  AuthProviderNotFoundError,\n} from \"./errors.js\";\nimport { clearTransaction, getTransaction, newTransaction } from \"./oauth-transaction-store.js\";\nimport type { AuthOrchestrator, AuthProvider, DefineAuthOptions } from \"./types.js\";\nimport { validateReturnTo } from \"./validate-return-to.js\";\n\nconst PROVIDER_NAME_RE = /^[a-z0-9-]{1,32}$/;\n\nfunction randomState(): string {\n  const bytes = webcrypto.getRandomValues(new Uint8Array(24));\n  return Buffer.from(bytes).toString(\"base64url\");\n}\n\n/**\n * Generate a PKCE code_verifier per RFC 7636 §4.1 — 43..128 chars from the\n * unreserved set [A-Z][a-z][0-9]-._~ (base64url is a strict subset).\n *\n * 32 random bytes → 43 base64url chars satisfies the minimum. Provided by\n * the orchestrator so every transaction carries one; PKCE-aware providers\n * (Google) consume it; PKCE-ignorant providers (GitHub) discard it.\n */\nfunction generatePkceVerifier(): string {\n  const bytes = webcrypto.getRandomValues(new Uint8Array(32));\n  return Buffer.from(bytes).toString(\"base64url\");\n}\n\nfunction txCookieSecret<TSession>(opts: DefineAuthOptions<TSession>): string {\n  // For T1.2 minimal impl, derive a per-session-manager secret from the\n  // SessionManager identity. Production T2+ may refactor to share the\n  // SessionManager's actual secret rotation chain via a `getCookieSecret()` method.\n  // Falls back to TX_FALLBACK_SECRET when not available — apps should override.\n  const sess = opts.session as unknown as { secret?: string | string[] };\n  if (sess.secret) {\n    if (Array.isArray(sess.secret)) {\n      const first = sess.secret[0];\n      if (first) return first;\n    } else {\n      return sess.secret;\n    }\n  }\n  const fromEnv = process.env.THEOKIT_OAUTH_TX_SECRET;\n  if (fromEnv) return fromEnv;\n\n  // The comment that used to sit here said this fallback \"will fail in production scrutiny —\n  // flagged by future audit\". This is that audit, and the fallback is now refused where it matters.\n  //\n  // The cookie this secret encrypts carries `state` and `pkceVerifier` — the two values that make\n  // an authorization-code flow safe against CSRF and code interception. Encrypting them with a\n  // constant published inside the package protects nothing from anyone who can read npm.\n  //\n  // `AuthSecretTooShortError` never caught it: the constant is 48 characters, and that guard checks\n  // LENGTH, not provenance.\n  //\n  // Refused in production only. Blocking it everywhere would break every `pnpm dev`, and the risk\n  // is a deployed app rather than a laptop. The branch above (`opts.session.secret`) stays for\n  // callers who wire one, though `SessionManager` declares no such field today.\n  if (process.env.NODE_ENV === \"production\") {\n    throw new AuthConfigError(\n      \"missing_tx_secret\",\n      \"No OAuth transaction secret is configured. Set THEOKIT_OAUTH_TX_SECRET to a 32+ character \" +\n        \"random value — e.g. `openssl rand -hex 32`. Refusing to encrypt the transaction cookie \" +\n        \"with the development fallback, which ships inside this package and protects nothing.\",\n    );\n  }\n  return \"DEV_ONLY_INSECURE_OAUTH_TX_SECRET_REPLACE_IN_PROD\";\n}\n\nfunction defineAuth<TSession>(opts: DefineAuthOptions<TSession>): AuthOrchestrator<TSession> {\n  // Validate config at define-time (per blueprint Q5 invariants)\n  if (!opts.session) {\n    throw new AuthConfigError(\"missing_session\", \"defineAuth({ session }) is required\");\n  }\n\n  const providersMap = new Map<string, AuthProvider<unknown, string>>();\n  for (const provider of opts.providers ?? []) {\n    if (!provider.name || !PROVIDER_NAME_RE.test(provider.name)) {\n      throw new AuthConfigError(\n        \"invalid_provider_name\",\n        `Provider name must match ${PROVIDER_NAME_RE} (got: '${provider.name}')`,\n      );\n    }\n    if (providersMap.has(provider.name)) {\n      throw new AuthConfigError(\n        \"duplicate_provider_name\",\n        `Duplicate provider name: '${provider.name}'`,\n      );\n    }\n    providersMap.set(provider.name, provider);\n  }\n\n  const txSecret = txCookieSecret(opts);\n\n  function requireProvider(name: string): AuthProvider<unknown, string> {\n    const p = providersMap.get(name);\n    if (!p) throw new AuthProviderNotFoundError(name);\n    return p;\n  }\n\n  async function startSignIn(\n    providerName: string,\n    req: IncomingMessage,\n    startOpts?: { returnTo?: string },\n  ): Promise<Response> {\n    const provider = requireProvider(providerName);\n\n    // EC-2 (v1.1) — validate returnTo same-origin\n    const baseUrl = new URL(`http://${req.headers.host ?? \"localhost\"}${req.url ?? \"/\"}`);\n    const safeReturnTo = validateReturnTo(startOpts?.returnTo, baseUrl);\n\n    // Generate transaction. Always include a PKCE verifier — PKCE-aware\n    // providers (Google OIDC) consume it; PKCE-ignorant providers (GitHub\n    // OAuth 2.0) discard it. Generating unconditionally simplifies the\n    // provider contract: every tx is PKCE-ready.\n    const state = randomState();\n    const pkceVerifier = generatePkceVerifier();\n    const tx = newTransaction({\n      state,\n      pkceVerifier,\n      returnTo: safeReturnTo === \"/\" ? undefined : safeReturnTo,\n    });\n\n    // Persist transaction cookie via headers (since we return Response, need Set-Cookie header manually)\n    const authUrl = await provider.createAuthorizationURL(tx);\n\n    // Build response with Set-Cookie + redirect\n    const headers = new Headers();\n    headers.set(\"Location\", authUrl.toString());\n    const { encodeTransaction, COOKIE_NAME } = await import(\"./oauth-transaction-store.js\");\n    const encodedTx = await encodeTransaction(tx, txSecret);\n    // COOKIE_NAME, never a literal: this header used to be written by hand as `theo_oauth_tx=`,\n    // while the store reads the `__Host-` prefixed name — so `finishSignIn` never found the cookie\n    // and every sign-in failed at the callback. One constant, one name.\n    //\n    // The `__Host-` prefix requires exactly what is set below: `Secure`, `Path=/`, and NO `Domain`.\n    headers.set(\n      \"Set-Cookie\",\n      `${COOKIE_NAME}=${encodedTx}; HttpOnly; Secure; SameSite=Lax; Path=/; Max-Age=600`,\n    );\n\n    return new Response(null, { status: 302, headers });\n  }\n\n  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: OAuth callback handler must validate 6 distinct error conditions sequentially (provider error / state / tx fetch / PKCE / code exchange / session) — extracting helpers fragments the linear control flow without clarifying intent (per EC-1 v1.1 absorbed)\n  async function finishSignIn(\n    providerName: string,\n    req: IncomingMessage,\n    res: ServerResponse,\n  ): Promise<{ session: TSession; returnTo?: string }> {\n    const provider = requireProvider(providerName);\n\n    // EC-1 (v1.1) — OAuth provider error response (user declined consent) check BEFORE code-exchange\n    const url = new URL(`http://${req.headers.host ?? \"localhost\"}${req.url ?? \"/\"}`);\n    const errorParam = url.searchParams.get(\"error\");\n    if (errorParam) {\n      const errorDescription = url.searchParams.get(\"error_description\") ?? undefined;\n      if (errorParam === \"access_denied\") {\n        throw new AuthCancelledError(errorDescription);\n      }\n      throw new AuthCallbackError(\n        \"oauth_provider_error\",\n        `Provider returned error: ${errorParam}${errorDescription ? ` (${errorDescription})` : \"\"}`,\n      );\n    }\n\n    // Read + validate transaction cookie\n    const tx = await getTransaction(req, txSecret);\n    if (!tx) {\n      throw new AuthCallbackError(\n        \"oauth_transaction_expired\",\n        \"OAuth transaction cookie missing or expired (>10min). Please retry sign-in.\",\n      );\n    }\n\n    // Verify state matches query param (CSRF defense per RFC 6749 §10.12)\n    const queryState = url.searchParams.get(\"state\");\n    if (!queryState || queryState !== tx.state) {\n      throw new AuthCallbackError(\n        \"oauth_state_mismatch\",\n        \"OAuth state mismatch. Possible CSRF attempt or stale callback.\",\n      );\n    }\n\n    // Provider-specific callback handling (token exchange + userinfo fetch)\n    const result = await provider.handleCallback(req, tx);\n\n    // Invoke onSignIn callback if defined to derive session shape\n    let sessionData: TSession;\n    if (opts.onSignIn) {\n      sessionData = await opts.onSignIn({ profile: result.profile, provider: result.providerName });\n    } else {\n      // No onSignIn — pass the raw profile as session (consumers must type their own TSession)\n      sessionData = result.profile as unknown as TSession;\n    }\n\n    // EC-10 (v1.1) — OWASP A07:2021 session fixation mitigation: rotate session ID BEFORE creating new session\n    try {\n      await opts.session.rotateSession(req, res);\n    } catch {\n      // rotateSession may no-op if no pre-existing session — non-fatal\n    }\n\n    // Create session cookie\n    await opts.session.createSession(res, sessionData);\n\n    // Clear transaction cookie\n    clearTransaction(res);\n\n    return { session: sessionData, returnTo: tx.returnTo };\n  }\n\n  async function signIn<TProfile>(\n    profile: TProfile,\n    providerName: string,\n    req: IncomingMessage,\n    res: ServerResponse,\n  ): Promise<TSession> {\n    // Path A escape hatch — skip OAuth flow, directly derive + persist session\n    let sessionData: TSession;\n    if (opts.onSignIn) {\n      sessionData = await opts.onSignIn({ profile, provider: providerName });\n    } else {\n      sessionData = profile as unknown as TSession;\n    }\n\n    try {\n      await opts.session.rotateSession(req, res);\n    } catch {\n      /* no-op if no pre-existing session */\n    }\n\n    await opts.session.createSession(res, sessionData);\n    return sessionData;\n  }\n\n  async function signOut(res: ServerResponse): Promise<void> {\n    // Read current session before destroying (so onSignOut can see it)\n    let sessionData: TSession | null = null;\n    if (opts.onSignOut) {\n      // We don't have req here per AuthOrchestrator contract; onSignOut receives null\n      // when no pre-existing session is available. Apps that need session-aware\n      // signOut should use the manual session.destroySession + custom logic.\n      sessionData = null;\n    }\n\n    opts.session.destroySession(res);\n\n    if (opts.onSignOut) {\n      await opts.onSignOut(sessionData);\n    }\n  }\n\n  async function getSession(req: IncomingMessage): Promise<TSession | null> {\n    return opts.session.getSession(req);\n  }\n\n  return { startSignIn, finishSignIn, signIn, signOut, getSession };\n}\n\n/** SE36 — `Auth.create` replaces `defineAuth` (ADR 0015). @public */\nexport class Auth {\n  private constructor() {}\n  static create<TSession>(opts: DefineAuthOptions<TSession>): AuthOrchestrator<TSession> {\n    return defineAuth(opts);\n  }\n}\n"]}
+{"version":3,"sources":["../../../src/server/auth/validate-return-to.ts","../../../src/server/auth/orchestrator.ts"],"names":["webcrypto","AuthConfigError","AuthProviderNotFoundError","newTransaction","AuthCancelledError","AuthCallbackError","getTransaction","clearTransaction"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * Clamp a caller-supplied `returnTo` to a same-origin destination, falling back\n * to `'/'` for anything else. This is the open-redirect guard for a post-login\n * redirect (`@theokit/sdk/server/auth`; OWASP A01:2021, v1.1 EC-2). Without it,\n * `/login?returnTo=https://evil.com` would send the freshly authenticated session\n * to an attacker's domain.\n *\n *   validateReturnTo(req.query.returnTo, new URL(\"https://app.example.com\"));\n *\n * Pure and synchronous. It never throws and always returns a string:\n *   - undefined / empty / whitespace-only `returnTo` -> `'/'`\n *   - protocol-relative `//evil.com` -> `'/'` (a browser would resolve it against\n *     the current protocol)\n *   - absolute URL whose origin differs from `baseUrl.origin` -> `'/'`\n *   - absolute URL on `baseUrl.origin` -> its `pathname + search + hash`, with\n *     the origin dropped\n *   - relative path starting with `'/'` -> kept verbatim\n *   - anything else, including `javascript:` and `data:` -> `'/'`\n *\n * `baseUrl` is compared by ORIGIN only (scheme + host + port); its path is\n * ignored, so an app mounted under a sub-path gets no extra containment from it.\n *\n * Trap: this defends the origin, not the route. A same-origin relative path is\n * returned unchanged — `..` segments included, and with no notion of whether the\n * user is allowed there. Authorise the destination separately.\n */\nexport function validateReturnTo(returnTo: string | undefined, baseUrl: URL): string {\n  if (!returnTo || typeof returnTo !== \"string\" || returnTo.trim() === \"\") {\n    return \"/\";\n  }\n\n  const trimmed = returnTo.trim();\n\n  // Protocol-relative URLs (//evil.com) are dangerous — browser would resolve to current protocol\n  if (trimmed.startsWith(\"//\")) {\n    return \"/\";\n  }\n\n  // Try absolute URL parsing first\n  if (URL.canParse(trimmed)) {\n    const parsed = new URL(trimmed);\n    if (parsed.origin === baseUrl.origin) {\n      // Same-origin absolute URL — return the pathname+search+hash portion (drop origin)\n      return parsed.pathname + parsed.search + parsed.hash;\n    }\n    // Cross-origin — reject\n    return \"/\";\n  }\n\n  // Not parseable as absolute. Must start with '/' to be a valid relative path\n  if (trimmed.startsWith(\"/\")) {\n    return trimmed;\n  }\n\n  // Anything else (e.g., \"javascript:alert\", \"data:...\" that wasn't parseable, or bare strings) → default\n  return \"/\";\n}\n","/**\n * DefineAuth orchestrator runtime (Path C Hybrid) — `@theokit/sdk/server/auth`.\n *\n * Plan T1.2 implementation per blueprint Q5 § Path C signatures.\n * Composes existing primitives + the v1.1 EC-1/EC-2/EC-10 fixes.\n */\n\nimport { webcrypto } from \"node:crypto\";\nimport type { IncomingMessage, ServerResponse } from \"node:http\";\nimport {\n  AuthCallbackError,\n  AuthCancelledError,\n  AuthConfigError,\n  AuthProviderNotFoundError,\n} from \"./errors.js\";\nimport { clearTransaction, getTransaction, newTransaction } from \"./oauth-transaction-store.js\";\nimport type { AuthOrchestrator, AuthProvider, DefineAuthOptions } from \"./types.js\";\nimport { validateReturnTo } from \"./validate-return-to.js\";\n\nconst PROVIDER_NAME_RE = /^[a-z0-9-]{1,32}$/;\n\nfunction randomState(): string {\n  const bytes = webcrypto.getRandomValues(new Uint8Array(24));\n  return Buffer.from(bytes).toString(\"base64url\");\n}\n\n/**\n * Generate a PKCE code_verifier per RFC 7636 §4.1 — 43..128 chars from the\n * unreserved set [A-Z][a-z][0-9]-._~ (base64url is a strict subset).\n *\n * 32 random bytes → 43 base64url chars satisfies the minimum. Provided by\n * the orchestrator so every transaction carries one; PKCE-aware providers\n * (Google) consume it; PKCE-ignorant providers (GitHub) discard it.\n */\nfunction generatePkceVerifier(): string {\n  const bytes = webcrypto.getRandomValues(new Uint8Array(32));\n  return Buffer.from(bytes).toString(\"base64url\");\n}\n\nfunction txCookieSecret<TSession>(opts: DefineAuthOptions<TSession>): string {\n  // Read through the PORT. This was `opts.session as unknown as { secret?: string | string[] }` —\n  // and `as unknown as` is the tell: TypeScript would have refused the property access, so the code\n  // asserted a shape `SessionManager` does not offer. No conforming caller could reach the branch,\n  // nothing in src/ supplied the field, and it was green only because a test double carried one. The\n  // comment that stood here said this code WANTED a `getCookieSecret()` method; `SessionManager` now\n  // declares it, optional and additive, so the branch is reachable through the contract and the\n  // double conforms rather than the code conforming to the double.\n  const fromManager = opts.session.getCookieSecret?.();\n  if (Array.isArray(fromManager)) {\n    // First entry encrypts; the rest exist to verify cookies written before the last rotation.\n    const first = fromManager[0];\n    if (first !== undefined && first !== \"\") return first;\n  } else if (fromManager !== undefined && fromManager !== \"\") {\n    return fromManager;\n  }\n  const fromEnv = process.env.THEOKIT_OAUTH_TX_SECRET;\n  if (fromEnv) return fromEnv;\n\n  // The comment that used to sit here said this fallback \"will fail in production scrutiny —\n  // flagged by future audit\". This is that audit, and the fallback is now refused where it matters.\n  //\n  // The cookie this secret encrypts carries `state` and `pkceVerifier` — the two values that make\n  // an authorization-code flow safe against CSRF and code interception. Encrypting them with a\n  // constant published inside the package protects nothing from anyone who can read npm.\n  //\n  // `AuthSecretTooShortError` never caught it: the constant is 48 characters, and that guard checks\n  // LENGTH, not provenance.\n  //\n  // Refused in production only. Blocking it everywhere would break every `pnpm dev`, and the risk\n  // is a deployed app rather than a laptop. The branch above (`opts.session.secret`) stays for\n  // callers who wire one, though `SessionManager` declares no such field today.\n  if (process.env.NODE_ENV === \"production\") {\n    throw new AuthConfigError(\n      \"missing_tx_secret\",\n      \"No OAuth transaction secret is configured. Set THEOKIT_OAUTH_TX_SECRET to a 32+ character \" +\n        \"random value — e.g. `openssl rand -hex 32`. Refusing to encrypt the transaction cookie \" +\n        \"with the development fallback, which ships inside this package and protects nothing.\",\n    );\n  }\n  return \"DEV_ONLY_INSECURE_OAUTH_TX_SECRET_REPLACE_IN_PROD\";\n}\n\nfunction defineAuth<TSession>(opts: DefineAuthOptions<TSession>): AuthOrchestrator<TSession> {\n  // Validate config at define-time (per blueprint Q5 invariants)\n  if (!opts.session) {\n    throw new AuthConfigError(\"missing_session\", \"defineAuth({ session }) is required\");\n  }\n\n  const providersMap = new Map<string, AuthProvider<unknown, string>>();\n  for (const provider of opts.providers ?? []) {\n    if (!provider.name || !PROVIDER_NAME_RE.test(provider.name)) {\n      throw new AuthConfigError(\n        \"invalid_provider_name\",\n        `Provider name must match ${PROVIDER_NAME_RE} (got: '${provider.name}')`,\n      );\n    }\n    if (providersMap.has(provider.name)) {\n      throw new AuthConfigError(\n        \"duplicate_provider_name\",\n        `Duplicate provider name: '${provider.name}'`,\n      );\n    }\n    providersMap.set(provider.name, provider);\n  }\n\n  const txSecret = txCookieSecret(opts);\n\n  function requireProvider(name: string): AuthProvider<unknown, string> {\n    const p = providersMap.get(name);\n    if (!p) throw new AuthProviderNotFoundError(name);\n    return p;\n  }\n\n  async function startSignIn(\n    providerName: string,\n    req: IncomingMessage,\n    startOpts?: { returnTo?: string },\n  ): Promise<Response> {\n    const provider = requireProvider(providerName);\n\n    // EC-2 (v1.1) — validate returnTo same-origin\n    const baseUrl = new URL(`http://${req.headers.host ?? \"localhost\"}${req.url ?? \"/\"}`);\n    const safeReturnTo = validateReturnTo(startOpts?.returnTo, baseUrl);\n\n    // Generate transaction. Always include a PKCE verifier — PKCE-aware\n    // providers (Google OIDC) consume it; PKCE-ignorant providers (GitHub\n    // OAuth 2.0) discard it. Generating unconditionally simplifies the\n    // provider contract: every tx is PKCE-ready.\n    const state = randomState();\n    const pkceVerifier = generatePkceVerifier();\n    const tx = newTransaction({\n      state,\n      pkceVerifier,\n      returnTo: safeReturnTo === \"/\" ? undefined : safeReturnTo,\n    });\n\n    // Persist transaction cookie via headers (since we return Response, need Set-Cookie header manually)\n    const authUrl = await provider.createAuthorizationURL(tx);\n\n    // Build response with Set-Cookie + redirect\n    const headers = new Headers();\n    headers.set(\"Location\", authUrl.toString());\n    const { encodeTransaction, COOKIE_NAME } = await import(\"./oauth-transaction-store.js\");\n    const encodedTx = await encodeTransaction(tx, txSecret);\n    // COOKIE_NAME, never a literal: this header used to be written by hand as `theo_oauth_tx=`,\n    // while the store reads the `__Host-` prefixed name — so `finishSignIn` never found the cookie\n    // and every sign-in failed at the callback. One constant, one name.\n    //\n    // The `__Host-` prefix requires exactly what is set below: `Secure`, `Path=/`, and NO `Domain`.\n    headers.set(\n      \"Set-Cookie\",\n      `${COOKIE_NAME}=${encodedTx}; HttpOnly; Secure; SameSite=Lax; Path=/; Max-Age=600`,\n    );\n\n    return new Response(null, { status: 302, headers });\n  }\n\n  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: OAuth callback handler must validate 6 distinct error conditions sequentially (provider error / state / tx fetch / PKCE / code exchange / session) — extracting helpers fragments the linear control flow without clarifying intent (per EC-1 v1.1 absorbed)\n  async function finishSignIn(\n    providerName: string,\n    req: IncomingMessage,\n    res: ServerResponse,\n  ): Promise<{ session: TSession; returnTo?: string }> {\n    const provider = requireProvider(providerName);\n\n    // EC-1 (v1.1) — OAuth provider error response (user declined consent) check BEFORE code-exchange\n    const url = new URL(`http://${req.headers.host ?? \"localhost\"}${req.url ?? \"/\"}`);\n    const errorParam = url.searchParams.get(\"error\");\n    if (errorParam) {\n      const errorDescription = url.searchParams.get(\"error_description\") ?? undefined;\n      if (errorParam === \"access_denied\") {\n        throw new AuthCancelledError(errorDescription);\n      }\n      throw new AuthCallbackError(\n        \"oauth_provider_error\",\n        `Provider returned error: ${errorParam}${errorDescription ? ` (${errorDescription})` : \"\"}`,\n      );\n    }\n\n    // Read + validate transaction cookie\n    const tx = await getTransaction(req, txSecret);\n    if (!tx) {\n      throw new AuthCallbackError(\n        \"oauth_transaction_expired\",\n        \"OAuth transaction cookie missing or expired (>10min). Please retry sign-in.\",\n      );\n    }\n\n    // Verify state matches query param (CSRF defense per RFC 6749 §10.12)\n    const queryState = url.searchParams.get(\"state\");\n    if (!queryState || queryState !== tx.state) {\n      throw new AuthCallbackError(\n        \"oauth_state_mismatch\",\n        \"OAuth state mismatch. Possible CSRF attempt or stale callback.\",\n      );\n    }\n\n    // Provider-specific callback handling (token exchange + userinfo fetch)\n    const result = await provider.handleCallback(req, tx);\n\n    // Invoke onSignIn callback if defined to derive session shape\n    let sessionData: TSession;\n    if (opts.onSignIn) {\n      sessionData = await opts.onSignIn({ profile: result.profile, provider: result.providerName });\n    } else {\n      // No onSignIn — pass the raw profile as session (consumers must type their own TSession)\n      sessionData = result.profile as unknown as TSession;\n    }\n\n    // EC-10 (v1.1) — OWASP A07:2021 session fixation mitigation: rotate session ID BEFORE creating new session\n    try {\n      await opts.session.rotateSession(req, res);\n    } catch {\n      // rotateSession may no-op if no pre-existing session — non-fatal\n    }\n\n    // Create session cookie\n    await opts.session.createSession(res, sessionData);\n\n    // Clear transaction cookie\n    clearTransaction(res);\n\n    return { session: sessionData, returnTo: tx.returnTo };\n  }\n\n  async function signIn<TProfile>(\n    profile: TProfile,\n    providerName: string,\n    req: IncomingMessage,\n    res: ServerResponse,\n  ): Promise<TSession> {\n    // Path A escape hatch — skip OAuth flow, directly derive + persist session\n    let sessionData: TSession;\n    if (opts.onSignIn) {\n      sessionData = await opts.onSignIn({ profile, provider: providerName });\n    } else {\n      sessionData = profile as unknown as TSession;\n    }\n\n    try {\n      await opts.session.rotateSession(req, res);\n    } catch {\n      /* no-op if no pre-existing session */\n    }\n\n    await opts.session.createSession(res, sessionData);\n    return sessionData;\n  }\n\n  async function signOut(res: ServerResponse): Promise<void> {\n    // Read current session before destroying (so onSignOut can see it)\n    let sessionData: TSession | null = null;\n    if (opts.onSignOut) {\n      // We don't have req here per AuthOrchestrator contract; onSignOut receives null\n      // when no pre-existing session is available. Apps that need session-aware\n      // signOut should use the manual session.destroySession + custom logic.\n      sessionData = null;\n    }\n\n    opts.session.destroySession(res);\n\n    if (opts.onSignOut) {\n      await opts.onSignOut(sessionData);\n    }\n  }\n\n  async function getSession(req: IncomingMessage): Promise<TSession | null> {\n    return opts.session.getSession(req);\n  }\n\n  return { startSignIn, finishSignIn, signIn, signOut, getSession };\n}\n\n/** SE36 — `Auth.create` replaces `defineAuth` (ADR 0015). @public  *\n * `Auth.create` returns an **`AuthOrchestrator<TSession>`**, not an `Auth`. The class is\n * the namespace; the orchestrator is the product.\n */\nexport class Auth {\n  private constructor() {}\n  static create<TSession>(opts: DefineAuthOptions<TSession>): AuthOrchestrator<TSession> {\n    return defineAuth(opts);\n  }\n}\n\n/**\n * Test seam over {@link txCookieSecret}.\n *\n * Exported so the resolution order can be exercised through a CONFORMING `SessionManager` — the\n * point of the change that introduced `getCookieSecret`. Without a seam the only way to reach it is\n * a full `defineAuth` round trip, which is what let the previous version go untested through the\n * port and tested only through a cast.\n *\n * @internal\n */\nexport function _txCookieSecretForTests<TSession>(\n  opts: Pick<DefineAuthOptions<TSession>, \"session\">,\n): string {\n  return txCookieSecret(opts as DefineAuthOptions<TSession>);\n}\n"]}

package/dist/server/auth/index.d.cts

@@ -1,3 +1,4 @@
+import { T as TheokitAgentError } from '../../errors-base-B5g01neU.cjs';
 import { IncomingMessage, ServerResponse } from 'node:http';
 
 /**
@@ -5,11 +6,12 @@ import { IncomingMessage, ServerResponse } from 'node:http';
  *
  * Plan T1.2 + v1.1 EC-1 (AuthCancelledError for OAuth provider error response RFC 6749 §4.1.2.1).
  */
+
 /**
  * Thrown at `defineAuth()` time when configuration is invalid
  * (e.g., duplicate provider name, invalid email shape per EC-V1-12).
  */
-declare class AuthConfigError extends Error {
+declare class AuthConfigError extends TheokitAgentError {
     readonly name = "AuthConfigError";
     readonly code: string;
     constructor(code: string, message: string);
@@ -18,7 +20,7 @@ declare class AuthConfigError extends Error {
  * Thrown at `startSignIn(providerName, ...)` or `finishSignIn(providerName, ...)`
  * when the named provider is not registered in `providers[]`.
  */
-declare class AuthProviderNotFoundError extends Error {
+declare class AuthProviderNotFoundError extends TheokitAgentError {
     readonly name = "AuthProviderNotFoundError";
     readonly providerName: string;
     constructor(providerName: string);
@@ -35,7 +37,7 @@ declare class AuthProviderNotFoundError extends Error {
  *   - 'oauth_userinfo_failed' — userinfo endpoint returned error
  *   - 'oauth_missing_code_or_state' — required query params absent
  */
-declare class AuthCallbackError extends Error {
+declare class AuthCallbackError extends TheokitAgentError {
     readonly name: string;
     readonly code: string;
     constructor(code: string, message?: string);
@@ -73,6 +75,24 @@ interface SessionManager<TSession> {
     createSession(res: ServerResponse, data: TSession): Promise<void>;
     destroySession(res: ServerResponse): void;
     rotateSession(req: IncomingMessage, res: ServerResponse): Promise<TSession | null>;
+    /**
+     * The secret used to encrypt the OAuth transaction cookie, when this manager has one to share.
+     *
+     * OPTIONAL and additive: a manager without it makes `defineAuth` fall back to
+     * `THEOKIT_OAUTH_TX_SECRET`, which is the behaviour that already existed.
+     *
+     * It exists because the orchestrator was reading `session.secret` through
+     * `as unknown as { secret?: string | string[] }` — asserting a shape this contract did not offer,
+     * so no conforming caller could reach the branch and nothing in `src/` supplied it. The branch was
+     * green only because a test double carried the field. `orchestrator.ts` said in a comment that it
+     * WANTED this member ("may refactor to share the SessionManager's actual secret rotation chain via
+     * a `getCookieSecret()` method"); declaring it is what makes the branch reachable through the port
+     * and the double conform instead of the reverse.
+     *
+     * An array is accepted for rotation: the first entry encrypts, and the rest are for verifying
+     * cookies written before the last rotation.
+     */
+    getCookieSecret?(): string | string[] | undefined;
 }
 /**
  * Per ADR D5 — OAuth transaction state stored in encrypted HttpOnly cookie
@@ -172,7 +192,7 @@ interface AuthOrchestrator<TSession> {
  *
  * @public
  */
-declare class AuthSecretTooShortError extends Error {
+declare class AuthSecretTooShortError extends TheokitAgentError {
     readonly name = "AuthSecretTooShortError";
     constructor(actualBytes: number);
 }
@@ -184,7 +204,10 @@ declare class AuthSecretTooShortError extends Error {
  * Composes existing primitives + the v1.1 EC-1/EC-2/EC-10 fixes.
  */
 
-/** SE36 — `Auth.create` replaces `defineAuth` (ADR 0015). @public */
+/** SE36 — `Auth.create` replaces `defineAuth` (ADR 0015). @public  *
+ * `Auth.create` returns an **`AuthOrchestrator<TSession>`**, not an `Auth`. The class is
+ * the namespace; the orchestrator is the product.
+ */
 declare class Auth {
     private constructor();
     static create<TSession>(opts: DefineAuthOptions<TSession>): AuthOrchestrator<TSession>;

package/dist/server/auth/index.d.ts

@@ -1,3 +1,4 @@
+import { T as TheokitAgentError } from '../../errors-base-B5g01neU.js';
 import { IncomingMessage, ServerResponse } from 'node:http';
 
 /**
@@ -5,11 +6,12 @@ import { IncomingMessage, ServerResponse } from 'node:http';
  *
  * Plan T1.2 + v1.1 EC-1 (AuthCancelledError for OAuth provider error response RFC 6749 §4.1.2.1).
  */
+
 /**
  * Thrown at `defineAuth()` time when configuration is invalid
  * (e.g., duplicate provider name, invalid email shape per EC-V1-12).
  */
-declare class AuthConfigError extends Error {
+declare class AuthConfigError extends TheokitAgentError {
     readonly name = "AuthConfigError";
     readonly code: string;
     constructor(code: string, message: string);
@@ -18,7 +20,7 @@ declare class AuthConfigError extends Error {
  * Thrown at `startSignIn(providerName, ...)` or `finishSignIn(providerName, ...)`
  * when the named provider is not registered in `providers[]`.
  */
-declare class AuthProviderNotFoundError extends Error {
+declare class AuthProviderNotFoundError extends TheokitAgentError {
     readonly name = "AuthProviderNotFoundError";
     readonly providerName: string;
     constructor(providerName: string);
@@ -35,7 +37,7 @@ declare class AuthProviderNotFoundError extends Error {
  *   - 'oauth_userinfo_failed' — userinfo endpoint returned error
  *   - 'oauth_missing_code_or_state' — required query params absent
  */
-declare class AuthCallbackError extends Error {
+declare class AuthCallbackError extends TheokitAgentError {
     readonly name: string;
     readonly code: string;
     constructor(code: string, message?: string);
@@ -73,6 +75,24 @@ interface SessionManager<TSession> {
     createSession(res: ServerResponse, data: TSession): Promise<void>;
     destroySession(res: ServerResponse): void;
     rotateSession(req: IncomingMessage, res: ServerResponse): Promise<TSession | null>;
+    /**
+     * The secret used to encrypt the OAuth transaction cookie, when this manager has one to share.
+     *
+     * OPTIONAL and additive: a manager without it makes `defineAuth` fall back to
+     * `THEOKIT_OAUTH_TX_SECRET`, which is the behaviour that already existed.
+     *
+     * It exists because the orchestrator was reading `session.secret` through
+     * `as unknown as { secret?: string | string[] }` — asserting a shape this contract did not offer,
+     * so no conforming caller could reach the branch and nothing in `src/` supplied it. The branch was
+     * green only because a test double carried the field. `orchestrator.ts` said in a comment that it
+     * WANTED this member ("may refactor to share the SessionManager's actual secret rotation chain via
+     * a `getCookieSecret()` method"); declaring it is what makes the branch reachable through the port
+     * and the double conform instead of the reverse.
+     *
+     * An array is accepted for rotation: the first entry encrypts, and the rest are for verifying
+     * cookies written before the last rotation.
+     */
+    getCookieSecret?(): string | string[] | undefined;
 }
 /**
  * Per ADR D5 — OAuth transaction state stored in encrypted HttpOnly cookie
@@ -172,7 +192,7 @@ interface AuthOrchestrator<TSession> {
  *
  * @public
  */
-declare class AuthSecretTooShortError extends Error {
+declare class AuthSecretTooShortError extends TheokitAgentError {
     readonly name = "AuthSecretTooShortError";
     constructor(actualBytes: number);
 }
@@ -184,7 +204,10 @@ declare class AuthSecretTooShortError extends Error {
  * Composes existing primitives + the v1.1 EC-1/EC-2/EC-10 fixes.
  */
 
-/** SE36 — `Auth.create` replaces `defineAuth` (ADR 0015). @public */
+/** SE36 — `Auth.create` replaces `defineAuth` (ADR 0015). @public  *
+ * `Auth.create` returns an **`AuthOrchestrator<TSession>`**, not an `Auth`. The class is
+ * the namespace; the orchestrator is the product.
+ */
 declare class Auth {
     private constructor();
     static create<TSession>(opts: DefineAuthOptions<TSession>): AuthOrchestrator<TSession>;

package/dist/server/auth/index.js

@@ -1,7 +1,9 @@
-import { getTransaction, clearTransaction, newTransaction } from '../../chunk-AWO27VRZ.js';
-export { AuthSecretTooShortError } from '../../chunk-AWO27VRZ.js';
-import { AuthConfigError, AuthCancelledError, AuthCallbackError, AuthProviderNotFoundError } from '../../chunk-3OR54XG4.js';
-export { AuthCallbackError, AuthCancelledError, AuthConfigError, AuthProviderNotFoundError } from '../../chunk-3OR54XG4.js';
+import { getTransaction, clearTransaction, newTransaction } from '../../chunk-DMRT67Y6.js';
+export { AuthSecretTooShortError } from '../../chunk-DMRT67Y6.js';
+import { AuthConfigError, AuthCancelledError, AuthCallbackError, AuthProviderNotFoundError } from '../../chunk-NJWYQWDL.js';
+export { AuthCallbackError, AuthCancelledError, AuthConfigError, AuthProviderNotFoundError } from '../../chunk-NJWYQWDL.js';
+import '../../chunk-ALUN2B4W.js';
+import '../../chunk-CZJ6Q7CW.js';
 import { webcrypto } from 'crypto';
 
 // src/server/auth/validate-return-to.ts
@@ -37,14 +39,12 @@ function generatePkceVerifier() {
   return Buffer.from(bytes).toString("base64url");
 }
 function txCookieSecret(opts) {
-  const sess = opts.session;
-  if (sess.secret) {
-    if (Array.isArray(sess.secret)) {
-      const first = sess.secret[0];
-      if (first) return first;
-    } else {
-      return sess.secret;
-    }
+  const fromManager = opts.session.getCookieSecret?.();
+  if (Array.isArray(fromManager)) {
+    const first = fromManager[0];
+    if (first !== void 0 && first !== "") return first;
+  } else if (fromManager !== void 0 && fromManager !== "") {
+    return fromManager;
   }
   const fromEnv = process.env.THEOKIT_OAUTH_TX_SECRET;
   if (fromEnv) return fromEnv;
@@ -96,7 +96,7 @@ function defineAuth(opts) {
     const authUrl = await provider.createAuthorizationURL(tx);
     const headers = new Headers();
     headers.set("Location", authUrl.toString());
-    const { encodeTransaction, COOKIE_NAME } = await import('../../oauth-transaction-store-W52KVHQ4.js');
+    const { encodeTransaction, COOKIE_NAME } = await import('../../oauth-transaction-store-5RIR6D5C.js');
     const encodedTx = await encodeTransaction(tx, txSecret);
     headers.set(
       "Set-Cookie",

package/dist/server/auth/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../../src/server/auth/validate-return-to.ts","../../../src/server/auth/orchestrator.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Clamp a caller-supplied `returnTo` to a same-origin destination, falling back\n * to `'/'` for anything else. This is the open-redirect guard for a post-login\n * redirect (`@theokit/sdk/server/auth`; OWASP A01:2021, v1.1 EC-2). Without it,\n * `/login?returnTo=https://evil.com` would send the freshly authenticated session\n * to an attacker's domain.\n *\n *   validateReturnTo(req.query.returnTo, new URL(\"https://app.example.com\"));\n *\n * Pure and synchronous. It never throws and always returns a string:\n *   - undefined / empty / whitespace-only `returnTo` -> `'/'`\n *   - protocol-relative `//evil.com` -> `'/'` (a browser would resolve it against\n *     the current protocol)\n *   - absolute URL whose origin differs from `baseUrl.origin` -> `'/'`\n *   - absolute URL on `baseUrl.origin` -> its `pathname + search + hash`, with\n *     the origin dropped\n *   - relative path starting with `'/'` -> kept verbatim\n *   - anything else, including `javascript:` and `data:` -> `'/'`\n *\n * `baseUrl` is compared by ORIGIN only (scheme + host + port); its path is\n * ignored, so an app mounted under a sub-path gets no extra containment from it.\n *\n * Trap: this defends the origin, not the route. A same-origin relative path is\n * returned unchanged — `..` segments included, and with no notion of whether the\n * user is allowed there. Authorise the destination separately.\n */\nexport function validateReturnTo(returnTo: string | undefined, baseUrl: URL): string {\n  if (!returnTo || typeof returnTo !== \"string\" || returnTo.trim() === \"\") {\n    return \"/\";\n  }\n\n  const trimmed = returnTo.trim();\n\n  // Protocol-relative URLs (//evil.com) are dangerous — browser would resolve to current protocol\n  if (trimmed.startsWith(\"//\")) {\n    return \"/\";\n  }\n\n  // Try absolute URL parsing first\n  if (URL.canParse(trimmed)) {\n    const parsed = new URL(trimmed);\n    if (parsed.origin === baseUrl.origin) {\n      // Same-origin absolute URL — return the pathname+search+hash portion (drop origin)\n      return parsed.pathname + parsed.search + parsed.hash;\n    }\n    // Cross-origin — reject\n    return \"/\";\n  }\n\n  // Not parseable as absolute. Must start with '/' to be a valid relative path\n  if (trimmed.startsWith(\"/\")) {\n    return trimmed;\n  }\n\n  // Anything else (e.g., \"javascript:alert\", \"data:...\" that wasn't parseable, or bare strings) → default\n  return \"/\";\n}\n","/**\n * DefineAuth orchestrator runtime (Path C Hybrid) — `@theokit/sdk/server/auth`.\n *\n * Plan T1.2 implementation per blueprint Q5 § Path C signatures.\n * Composes existing primitives + the v1.1 EC-1/EC-2/EC-10 fixes.\n */\n\nimport { webcrypto } from \"node:crypto\";\nimport type { IncomingMessage, ServerResponse } from \"node:http\";\nimport {\n  AuthCallbackError,\n  AuthCancelledError,\n  AuthConfigError,\n  AuthProviderNotFoundError,\n} from \"./errors.js\";\nimport { clearTransaction, getTransaction, newTransaction } from \"./oauth-transaction-store.js\";\nimport type { AuthOrchestrator, AuthProvider, DefineAuthOptions } from \"./types.js\";\nimport { validateReturnTo } from \"./validate-return-to.js\";\n\nconst PROVIDER_NAME_RE = /^[a-z0-9-]{1,32}$/;\n\nfunction randomState(): string {\n  const bytes = webcrypto.getRandomValues(new Uint8Array(24));\n  return Buffer.from(bytes).toString(\"base64url\");\n}\n\n/**\n * Generate a PKCE code_verifier per RFC 7636 §4.1 — 43..128 chars from the\n * unreserved set [A-Z][a-z][0-9]-._~ (base64url is a strict subset).\n *\n * 32 random bytes → 43 base64url chars satisfies the minimum. Provided by\n * the orchestrator so every transaction carries one; PKCE-aware providers\n * (Google) consume it; PKCE-ignorant providers (GitHub) discard it.\n */\nfunction generatePkceVerifier(): string {\n  const bytes = webcrypto.getRandomValues(new Uint8Array(32));\n  return Buffer.from(bytes).toString(\"base64url\");\n}\n\nfunction txCookieSecret<TSession>(opts: DefineAuthOptions<TSession>): string {\n  // For T1.2 minimal impl, derive a per-session-manager secret from the\n  // SessionManager identity. Production T2+ may refactor to share the\n  // SessionManager's actual secret rotation chain via a `getCookieSecret()` method.\n  // Falls back to TX_FALLBACK_SECRET when not available — apps should override.\n  const sess = opts.session as unknown as { secret?: string | string[] };\n  if (sess.secret) {\n    if (Array.isArray(sess.secret)) {\n      const first = sess.secret[0];\n      if (first) return first;\n    } else {\n      return sess.secret;\n    }\n  }\n  const fromEnv = process.env.THEOKIT_OAUTH_TX_SECRET;\n  if (fromEnv) return fromEnv;\n\n  // The comment that used to sit here said this fallback \"will fail in production scrutiny —\n  // flagged by future audit\". This is that audit, and the fallback is now refused where it matters.\n  //\n  // The cookie this secret encrypts carries `state` and `pkceVerifier` — the two values that make\n  // an authorization-code flow safe against CSRF and code interception. Encrypting them with a\n  // constant published inside the package protects nothing from anyone who can read npm.\n  //\n  // `AuthSecretTooShortError` never caught it: the constant is 48 characters, and that guard checks\n  // LENGTH, not provenance.\n  //\n  // Refused in production only. Blocking it everywhere would break every `pnpm dev`, and the risk\n  // is a deployed app rather than a laptop. The branch above (`opts.session.secret`) stays for\n  // callers who wire one, though `SessionManager` declares no such field today.\n  if (process.env.NODE_ENV === \"production\") {\n    throw new AuthConfigError(\n      \"missing_tx_secret\",\n      \"No OAuth transaction secret is configured. Set THEOKIT_OAUTH_TX_SECRET to a 32+ character \" +\n        \"random value — e.g. `openssl rand -hex 32`. Refusing to encrypt the transaction cookie \" +\n        \"with the development fallback, which ships inside this package and protects nothing.\",\n    );\n  }\n  return \"DEV_ONLY_INSECURE_OAUTH_TX_SECRET_REPLACE_IN_PROD\";\n}\n\nfunction defineAuth<TSession>(opts: DefineAuthOptions<TSession>): AuthOrchestrator<TSession> {\n  // Validate config at define-time (per blueprint Q5 invariants)\n  if (!opts.session) {\n    throw new AuthConfigError(\"missing_session\", \"defineAuth({ session }) is required\");\n  }\n\n  const providersMap = new Map<string, AuthProvider<unknown, string>>();\n  for (const provider of opts.providers ?? []) {\n    if (!provider.name || !PROVIDER_NAME_RE.test(provider.name)) {\n      throw new AuthConfigError(\n        \"invalid_provider_name\",\n        `Provider name must match ${PROVIDER_NAME_RE} (got: '${provider.name}')`,\n      );\n    }\n    if (providersMap.has(provider.name)) {\n      throw new AuthConfigError(\n        \"duplicate_provider_name\",\n        `Duplicate provider name: '${provider.name}'`,\n      );\n    }\n    providersMap.set(provider.name, provider);\n  }\n\n  const txSecret = txCookieSecret(opts);\n\n  function requireProvider(name: string): AuthProvider<unknown, string> {\n    const p = providersMap.get(name);\n    if (!p) throw new AuthProviderNotFoundError(name);\n    return p;\n  }\n\n  async function startSignIn(\n    providerName: string,\n    req: IncomingMessage,\n    startOpts?: { returnTo?: string },\n  ): Promise<Response> {\n    const provider = requireProvider(providerName);\n\n    // EC-2 (v1.1) — validate returnTo same-origin\n    const baseUrl = new URL(`http://${req.headers.host ?? \"localhost\"}${req.url ?? \"/\"}`);\n    const safeReturnTo = validateReturnTo(startOpts?.returnTo, baseUrl);\n\n    // Generate transaction. Always include a PKCE verifier — PKCE-aware\n    // providers (Google OIDC) consume it; PKCE-ignorant providers (GitHub\n    // OAuth 2.0) discard it. Generating unconditionally simplifies the\n    // provider contract: every tx is PKCE-ready.\n    const state = randomState();\n    const pkceVerifier = generatePkceVerifier();\n    const tx = newTransaction({\n      state,\n      pkceVerifier,\n      returnTo: safeReturnTo === \"/\" ? undefined : safeReturnTo,\n    });\n\n    // Persist transaction cookie via headers (since we return Response, need Set-Cookie header manually)\n    const authUrl = await provider.createAuthorizationURL(tx);\n\n    // Build response with Set-Cookie + redirect\n    const headers = new Headers();\n    headers.set(\"Location\", authUrl.toString());\n    const { encodeTransaction, COOKIE_NAME } = await import(\"./oauth-transaction-store.js\");\n    const encodedTx = await encodeTransaction(tx, txSecret);\n    // COOKIE_NAME, never a literal: this header used to be written by hand as `theo_oauth_tx=`,\n    // while the store reads the `__Host-` prefixed name — so `finishSignIn` never found the cookie\n    // and every sign-in failed at the callback. One constant, one name.\n    //\n    // The `__Host-` prefix requires exactly what is set below: `Secure`, `Path=/`, and NO `Domain`.\n    headers.set(\n      \"Set-Cookie\",\n      `${COOKIE_NAME}=${encodedTx}; HttpOnly; Secure; SameSite=Lax; Path=/; Max-Age=600`,\n    );\n\n    return new Response(null, { status: 302, headers });\n  }\n\n  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: OAuth callback handler must validate 6 distinct error conditions sequentially (provider error / state / tx fetch / PKCE / code exchange / session) — extracting helpers fragments the linear control flow without clarifying intent (per EC-1 v1.1 absorbed)\n  async function finishSignIn(\n    providerName: string,\n    req: IncomingMessage,\n    res: ServerResponse,\n  ): Promise<{ session: TSession; returnTo?: string }> {\n    const provider = requireProvider(providerName);\n\n    // EC-1 (v1.1) — OAuth provider error response (user declined consent) check BEFORE code-exchange\n    const url = new URL(`http://${req.headers.host ?? \"localhost\"}${req.url ?? \"/\"}`);\n    const errorParam = url.searchParams.get(\"error\");\n    if (errorParam) {\n      const errorDescription = url.searchParams.get(\"error_description\") ?? undefined;\n      if (errorParam === \"access_denied\") {\n        throw new AuthCancelledError(errorDescription);\n      }\n      throw new AuthCallbackError(\n        \"oauth_provider_error\",\n        `Provider returned error: ${errorParam}${errorDescription ? ` (${errorDescription})` : \"\"}`,\n      );\n    }\n\n    // Read + validate transaction cookie\n    const tx = await getTransaction(req, txSecret);\n    if (!tx) {\n      throw new AuthCallbackError(\n        \"oauth_transaction_expired\",\n        \"OAuth transaction cookie missing or expired (>10min). Please retry sign-in.\",\n      );\n    }\n\n    // Verify state matches query param (CSRF defense per RFC 6749 §10.12)\n    const queryState = url.searchParams.get(\"state\");\n    if (!queryState || queryState !== tx.state) {\n      throw new AuthCallbackError(\n        \"oauth_state_mismatch\",\n        \"OAuth state mismatch. Possible CSRF attempt or stale callback.\",\n      );\n    }\n\n    // Provider-specific callback handling (token exchange + userinfo fetch)\n    const result = await provider.handleCallback(req, tx);\n\n    // Invoke onSignIn callback if defined to derive session shape\n    let sessionData: TSession;\n    if (opts.onSignIn) {\n      sessionData = await opts.onSignIn({ profile: result.profile, provider: result.providerName });\n    } else {\n      // No onSignIn — pass the raw profile as session (consumers must type their own TSession)\n      sessionData = result.profile as unknown as TSession;\n    }\n\n    // EC-10 (v1.1) — OWASP A07:2021 session fixation mitigation: rotate session ID BEFORE creating new session\n    try {\n      await opts.session.rotateSession(req, res);\n    } catch {\n      // rotateSession may no-op if no pre-existing session — non-fatal\n    }\n\n    // Create session cookie\n    await opts.session.createSession(res, sessionData);\n\n    // Clear transaction cookie\n    clearTransaction(res);\n\n    return { session: sessionData, returnTo: tx.returnTo };\n  }\n\n  async function signIn<TProfile>(\n    profile: TProfile,\n    providerName: string,\n    req: IncomingMessage,\n    res: ServerResponse,\n  ): Promise<TSession> {\n    // Path A escape hatch — skip OAuth flow, directly derive + persist session\n    let sessionData: TSession;\n    if (opts.onSignIn) {\n      sessionData = await opts.onSignIn({ profile, provider: providerName });\n    } else {\n      sessionData = profile as unknown as TSession;\n    }\n\n    try {\n      await opts.session.rotateSession(req, res);\n    } catch {\n      /* no-op if no pre-existing session */\n    }\n\n    await opts.session.createSession(res, sessionData);\n    return sessionData;\n  }\n\n  async function signOut(res: ServerResponse): Promise<void> {\n    // Read current session before destroying (so onSignOut can see it)\n    let sessionData: TSession | null = null;\n    if (opts.onSignOut) {\n      // We don't have req here per AuthOrchestrator contract; onSignOut receives null\n      // when no pre-existing session is available. Apps that need session-aware\n      // signOut should use the manual session.destroySession + custom logic.\n      sessionData = null;\n    }\n\n    opts.session.destroySession(res);\n\n    if (opts.onSignOut) {\n      await opts.onSignOut(sessionData);\n    }\n  }\n\n  async function getSession(req: IncomingMessage): Promise<TSession | null> {\n    return opts.session.getSession(req);\n  }\n\n  return { startSignIn, finishSignIn, signIn, signOut, getSession };\n}\n\n/** SE36 — `Auth.create` replaces `defineAuth` (ADR 0015). @public */\nexport class Auth {\n  private constructor() {}\n  static create<TSession>(opts: DefineAuthOptions<TSession>): AuthOrchestrator<TSession> {\n    return defineAuth(opts);\n  }\n}\n"]}
+{"version":3,"sources":["../../../src/server/auth/validate-return-to.ts","../../../src/server/auth/orchestrator.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Clamp a caller-supplied `returnTo` to a same-origin destination, falling back\n * to `'/'` for anything else. This is the open-redirect guard for a post-login\n * redirect (`@theokit/sdk/server/auth`; OWASP A01:2021, v1.1 EC-2). Without it,\n * `/login?returnTo=https://evil.com` would send the freshly authenticated session\n * to an attacker's domain.\n *\n *   validateReturnTo(req.query.returnTo, new URL(\"https://app.example.com\"));\n *\n * Pure and synchronous. It never throws and always returns a string:\n *   - undefined / empty / whitespace-only `returnTo` -> `'/'`\n *   - protocol-relative `//evil.com` -> `'/'` (a browser would resolve it against\n *     the current protocol)\n *   - absolute URL whose origin differs from `baseUrl.origin` -> `'/'`\n *   - absolute URL on `baseUrl.origin` -> its `pathname + search + hash`, with\n *     the origin dropped\n *   - relative path starting with `'/'` -> kept verbatim\n *   - anything else, including `javascript:` and `data:` -> `'/'`\n *\n * `baseUrl` is compared by ORIGIN only (scheme + host + port); its path is\n * ignored, so an app mounted under a sub-path gets no extra containment from it.\n *\n * Trap: this defends the origin, not the route. A same-origin relative path is\n * returned unchanged — `..` segments included, and with no notion of whether the\n * user is allowed there. Authorise the destination separately.\n */\nexport function validateReturnTo(returnTo: string | undefined, baseUrl: URL): string {\n  if (!returnTo || typeof returnTo !== \"string\" || returnTo.trim() === \"\") {\n    return \"/\";\n  }\n\n  const trimmed = returnTo.trim();\n\n  // Protocol-relative URLs (//evil.com) are dangerous — browser would resolve to current protocol\n  if (trimmed.startsWith(\"//\")) {\n    return \"/\";\n  }\n\n  // Try absolute URL parsing first\n  if (URL.canParse(trimmed)) {\n    const parsed = new URL(trimmed);\n    if (parsed.origin === baseUrl.origin) {\n      // Same-origin absolute URL — return the pathname+search+hash portion (drop origin)\n      return parsed.pathname + parsed.search + parsed.hash;\n    }\n    // Cross-origin — reject\n    return \"/\";\n  }\n\n  // Not parseable as absolute. Must start with '/' to be a valid relative path\n  if (trimmed.startsWith(\"/\")) {\n    return trimmed;\n  }\n\n  // Anything else (e.g., \"javascript:alert\", \"data:...\" that wasn't parseable, or bare strings) → default\n  return \"/\";\n}\n","/**\n * DefineAuth orchestrator runtime (Path C Hybrid) — `@theokit/sdk/server/auth`.\n *\n * Plan T1.2 implementation per blueprint Q5 § Path C signatures.\n * Composes existing primitives + the v1.1 EC-1/EC-2/EC-10 fixes.\n */\n\nimport { webcrypto } from \"node:crypto\";\nimport type { IncomingMessage, ServerResponse } from \"node:http\";\nimport {\n  AuthCallbackError,\n  AuthCancelledError,\n  AuthConfigError,\n  AuthProviderNotFoundError,\n} from \"./errors.js\";\nimport { clearTransaction, getTransaction, newTransaction } from \"./oauth-transaction-store.js\";\nimport type { AuthOrchestrator, AuthProvider, DefineAuthOptions } from \"./types.js\";\nimport { validateReturnTo } from \"./validate-return-to.js\";\n\nconst PROVIDER_NAME_RE = /^[a-z0-9-]{1,32}$/;\n\nfunction randomState(): string {\n  const bytes = webcrypto.getRandomValues(new Uint8Array(24));\n  return Buffer.from(bytes).toString(\"base64url\");\n}\n\n/**\n * Generate a PKCE code_verifier per RFC 7636 §4.1 — 43..128 chars from the\n * unreserved set [A-Z][a-z][0-9]-._~ (base64url is a strict subset).\n *\n * 32 random bytes → 43 base64url chars satisfies the minimum. Provided by\n * the orchestrator so every transaction carries one; PKCE-aware providers\n * (Google) consume it; PKCE-ignorant providers (GitHub) discard it.\n */\nfunction generatePkceVerifier(): string {\n  const bytes = webcrypto.getRandomValues(new Uint8Array(32));\n  return Buffer.from(bytes).toString(\"base64url\");\n}\n\nfunction txCookieSecret<TSession>(opts: DefineAuthOptions<TSession>): string {\n  // Read through the PORT. This was `opts.session as unknown as { secret?: string | string[] }` —\n  // and `as unknown as` is the tell: TypeScript would have refused the property access, so the code\n  // asserted a shape `SessionManager` does not offer. No conforming caller could reach the branch,\n  // nothing in src/ supplied the field, and it was green only because a test double carried one. The\n  // comment that stood here said this code WANTED a `getCookieSecret()` method; `SessionManager` now\n  // declares it, optional and additive, so the branch is reachable through the contract and the\n  // double conforms rather than the code conforming to the double.\n  const fromManager = opts.session.getCookieSecret?.();\n  if (Array.isArray(fromManager)) {\n    // First entry encrypts; the rest exist to verify cookies written before the last rotation.\n    const first = fromManager[0];\n    if (first !== undefined && first !== \"\") return first;\n  } else if (fromManager !== undefined && fromManager !== \"\") {\n    return fromManager;\n  }\n  const fromEnv = process.env.THEOKIT_OAUTH_TX_SECRET;\n  if (fromEnv) return fromEnv;\n\n  // The comment that used to sit here said this fallback \"will fail in production scrutiny —\n  // flagged by future audit\". This is that audit, and the fallback is now refused where it matters.\n  //\n  // The cookie this secret encrypts carries `state` and `pkceVerifier` — the two values that make\n  // an authorization-code flow safe against CSRF and code interception. Encrypting them with a\n  // constant published inside the package protects nothing from anyone who can read npm.\n  //\n  // `AuthSecretTooShortError` never caught it: the constant is 48 characters, and that guard checks\n  // LENGTH, not provenance.\n  //\n  // Refused in production only. Blocking it everywhere would break every `pnpm dev`, and the risk\n  // is a deployed app rather than a laptop. The branch above (`opts.session.secret`) stays for\n  // callers who wire one, though `SessionManager` declares no such field today.\n  if (process.env.NODE_ENV === \"production\") {\n    throw new AuthConfigError(\n      \"missing_tx_secret\",\n      \"No OAuth transaction secret is configured. Set THEOKIT_OAUTH_TX_SECRET to a 32+ character \" +\n        \"random value — e.g. `openssl rand -hex 32`. Refusing to encrypt the transaction cookie \" +\n        \"with the development fallback, which ships inside this package and protects nothing.\",\n    );\n  }\n  return \"DEV_ONLY_INSECURE_OAUTH_TX_SECRET_REPLACE_IN_PROD\";\n}\n\nfunction defineAuth<TSession>(opts: DefineAuthOptions<TSession>): AuthOrchestrator<TSession> {\n  // Validate config at define-time (per blueprint Q5 invariants)\n  if (!opts.session) {\n    throw new AuthConfigError(\"missing_session\", \"defineAuth({ session }) is required\");\n  }\n\n  const providersMap = new Map<string, AuthProvider<unknown, string>>();\n  for (const provider of opts.providers ?? []) {\n    if (!provider.name || !PROVIDER_NAME_RE.test(provider.name)) {\n      throw new AuthConfigError(\n        \"invalid_provider_name\",\n        `Provider name must match ${PROVIDER_NAME_RE} (got: '${provider.name}')`,\n      );\n    }\n    if (providersMap.has(provider.name)) {\n      throw new AuthConfigError(\n        \"duplicate_provider_name\",\n        `Duplicate provider name: '${provider.name}'`,\n      );\n    }\n    providersMap.set(provider.name, provider);\n  }\n\n  const txSecret = txCookieSecret(opts);\n\n  function requireProvider(name: string): AuthProvider<unknown, string> {\n    const p = providersMap.get(name);\n    if (!p) throw new AuthProviderNotFoundError(name);\n    return p;\n  }\n\n  async function startSignIn(\n    providerName: string,\n    req: IncomingMessage,\n    startOpts?: { returnTo?: string },\n  ): Promise<Response> {\n    const provider = requireProvider(providerName);\n\n    // EC-2 (v1.1) — validate returnTo same-origin\n    const baseUrl = new URL(`http://${req.headers.host ?? \"localhost\"}${req.url ?? \"/\"}`);\n    const safeReturnTo = validateReturnTo(startOpts?.returnTo, baseUrl);\n\n    // Generate transaction. Always include a PKCE verifier — PKCE-aware\n    // providers (Google OIDC) consume it; PKCE-ignorant providers (GitHub\n    // OAuth 2.0) discard it. Generating unconditionally simplifies the\n    // provider contract: every tx is PKCE-ready.\n    const state = randomState();\n    const pkceVerifier = generatePkceVerifier();\n    const tx = newTransaction({\n      state,\n      pkceVerifier,\n      returnTo: safeReturnTo === \"/\" ? undefined : safeReturnTo,\n    });\n\n    // Persist transaction cookie via headers (since we return Response, need Set-Cookie header manually)\n    const authUrl = await provider.createAuthorizationURL(tx);\n\n    // Build response with Set-Cookie + redirect\n    const headers = new Headers();\n    headers.set(\"Location\", authUrl.toString());\n    const { encodeTransaction, COOKIE_NAME } = await import(\"./oauth-transaction-store.js\");\n    const encodedTx = await encodeTransaction(tx, txSecret);\n    // COOKIE_NAME, never a literal: this header used to be written by hand as `theo_oauth_tx=`,\n    // while the store reads the `__Host-` prefixed name — so `finishSignIn` never found the cookie\n    // and every sign-in failed at the callback. One constant, one name.\n    //\n    // The `__Host-` prefix requires exactly what is set below: `Secure`, `Path=/`, and NO `Domain`.\n    headers.set(\n      \"Set-Cookie\",\n      `${COOKIE_NAME}=${encodedTx}; HttpOnly; Secure; SameSite=Lax; Path=/; Max-Age=600`,\n    );\n\n    return new Response(null, { status: 302, headers });\n  }\n\n  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: OAuth callback handler must validate 6 distinct error conditions sequentially (provider error / state / tx fetch / PKCE / code exchange / session) — extracting helpers fragments the linear control flow without clarifying intent (per EC-1 v1.1 absorbed)\n  async function finishSignIn(\n    providerName: string,\n    req: IncomingMessage,\n    res: ServerResponse,\n  ): Promise<{ session: TSession; returnTo?: string }> {\n    const provider = requireProvider(providerName);\n\n    // EC-1 (v1.1) — OAuth provider error response (user declined consent) check BEFORE code-exchange\n    const url = new URL(`http://${req.headers.host ?? \"localhost\"}${req.url ?? \"/\"}`);\n    const errorParam = url.searchParams.get(\"error\");\n    if (errorParam) {\n      const errorDescription = url.searchParams.get(\"error_description\") ?? undefined;\n      if (errorParam === \"access_denied\") {\n        throw new AuthCancelledError(errorDescription);\n      }\n      throw new AuthCallbackError(\n        \"oauth_provider_error\",\n        `Provider returned error: ${errorParam}${errorDescription ? ` (${errorDescription})` : \"\"}`,\n      );\n    }\n\n    // Read + validate transaction cookie\n    const tx = await getTransaction(req, txSecret);\n    if (!tx) {\n      throw new AuthCallbackError(\n        \"oauth_transaction_expired\",\n        \"OAuth transaction cookie missing or expired (>10min). Please retry sign-in.\",\n      );\n    }\n\n    // Verify state matches query param (CSRF defense per RFC 6749 §10.12)\n    const queryState = url.searchParams.get(\"state\");\n    if (!queryState || queryState !== tx.state) {\n      throw new AuthCallbackError(\n        \"oauth_state_mismatch\",\n        \"OAuth state mismatch. Possible CSRF attempt or stale callback.\",\n      );\n    }\n\n    // Provider-specific callback handling (token exchange + userinfo fetch)\n    const result = await provider.handleCallback(req, tx);\n\n    // Invoke onSignIn callback if defined to derive session shape\n    let sessionData: TSession;\n    if (opts.onSignIn) {\n      sessionData = await opts.onSignIn({ profile: result.profile, provider: result.providerName });\n    } else {\n      // No onSignIn — pass the raw profile as session (consumers must type their own TSession)\n      sessionData = result.profile as unknown as TSession;\n    }\n\n    // EC-10 (v1.1) — OWASP A07:2021 session fixation mitigation: rotate session ID BEFORE creating new session\n    try {\n      await opts.session.rotateSession(req, res);\n    } catch {\n      // rotateSession may no-op if no pre-existing session — non-fatal\n    }\n\n    // Create session cookie\n    await opts.session.createSession(res, sessionData);\n\n    // Clear transaction cookie\n    clearTransaction(res);\n\n    return { session: sessionData, returnTo: tx.returnTo };\n  }\n\n  async function signIn<TProfile>(\n    profile: TProfile,\n    providerName: string,\n    req: IncomingMessage,\n    res: ServerResponse,\n  ): Promise<TSession> {\n    // Path A escape hatch — skip OAuth flow, directly derive + persist session\n    let sessionData: TSession;\n    if (opts.onSignIn) {\n      sessionData = await opts.onSignIn({ profile, provider: providerName });\n    } else {\n      sessionData = profile as unknown as TSession;\n    }\n\n    try {\n      await opts.session.rotateSession(req, res);\n    } catch {\n      /* no-op if no pre-existing session */\n    }\n\n    await opts.session.createSession(res, sessionData);\n    return sessionData;\n  }\n\n  async function signOut(res: ServerResponse): Promise<void> {\n    // Read current session before destroying (so onSignOut can see it)\n    let sessionData: TSession | null = null;\n    if (opts.onSignOut) {\n      // We don't have req here per AuthOrchestrator contract; onSignOut receives null\n      // when no pre-existing session is available. Apps that need session-aware\n      // signOut should use the manual session.destroySession + custom logic.\n      sessionData = null;\n    }\n\n    opts.session.destroySession(res);\n\n    if (opts.onSignOut) {\n      await opts.onSignOut(sessionData);\n    }\n  }\n\n  async function getSession(req: IncomingMessage): Promise<TSession | null> {\n    return opts.session.getSession(req);\n  }\n\n  return { startSignIn, finishSignIn, signIn, signOut, getSession };\n}\n\n/** SE36 — `Auth.create` replaces `defineAuth` (ADR 0015). @public  *\n * `Auth.create` returns an **`AuthOrchestrator<TSession>`**, not an `Auth`. The class is\n * the namespace; the orchestrator is the product.\n */\nexport class Auth {\n  private constructor() {}\n  static create<TSession>(opts: DefineAuthOptions<TSession>): AuthOrchestrator<TSession> {\n    return defineAuth(opts);\n  }\n}\n\n/**\n * Test seam over {@link txCookieSecret}.\n *\n * Exported so the resolution order can be exercised through a CONFORMING `SessionManager` — the\n * point of the change that introduced `getCookieSecret`. Without a seam the only way to reach it is\n * a full `defineAuth` round trip, which is what let the previous version go untested through the\n * port and tested only through a cast.\n *\n * @internal\n */\nexport function _txCookieSecretForTests<TSession>(\n  opts: Pick<DefineAuthOptions<TSession>, \"session\">,\n): string {\n  return txCookieSecret(opts as DefineAuthOptions<TSession>);\n}\n"]}

package/dist/server/auth/oauth-transaction-store.d.cts

@@ -17,6 +17,7 @@
  * refactor to share SessionManager's encrypt path.
  */
 import type { IncomingMessage, ServerResponse } from "node:http";
+import { TheokitAgentError } from "../../errors.js";
 import type { OAuthTransaction } from "./types.js";
 /**
  * The transaction cookie's name. EXPORTED so the orchestrator uses this and not a second literal.
@@ -37,7 +38,7 @@ export declare const COOKIE_NAME = "__Host-theo_oauth_tx";
  *
  * @public
  */
-export declare class AuthSecretTooShortError extends Error {
+export declare class AuthSecretTooShortError extends TheokitAgentError {
     readonly name = "AuthSecretTooShortError";
     constructor(actualBytes: number);
 }

package/dist/server/auth/oauth-transaction-store.d.ts

@@ -17,6 +17,7 @@
  * refactor to share SessionManager's encrypt path.
  */
 import type { IncomingMessage, ServerResponse } from "node:http";
+import { TheokitAgentError } from "../../errors.js";
 import type { OAuthTransaction } from "./types.js";
 /**
  * The transaction cookie's name. EXPORTED so the orchestrator uses this and not a second literal.
@@ -37,7 +38,7 @@ export declare const COOKIE_NAME = "__Host-theo_oauth_tx";
  *
  * @public
  */
-export declare class AuthSecretTooShortError extends Error {
+export declare class AuthSecretTooShortError extends TheokitAgentError {
     readonly name = "AuthSecretTooShortError";
     constructor(actualBytes: number);
 }

package/dist/server/auth/orchestrator.d.cts

@@ -5,7 +5,10 @@
  * Composes existing primitives + the v1.1 EC-1/EC-2/EC-10 fixes.
  */
 import type { AuthOrchestrator, DefineAuthOptions } from "./types.js";
-/** SE36 — `Auth.create` replaces `defineAuth` (ADR 0015). @public */
+/** SE36 — `Auth.create` replaces `defineAuth` (ADR 0015). @public  *
+ * `Auth.create` returns an **`AuthOrchestrator<TSession>`**, not an `Auth`. The class is
+ * the namespace; the orchestrator is the product.
+ */
 export declare class Auth {
     private constructor();
     static create<TSession>(opts: DefineAuthOptions<TSession>): AuthOrchestrator<TSession>;

package/dist/server/auth/orchestrator.d.ts

@@ -5,7 +5,10 @@
  * Composes existing primitives + the v1.1 EC-1/EC-2/EC-10 fixes.
  */
 import type { AuthOrchestrator, DefineAuthOptions } from "./types.js";
-/** SE36 — `Auth.create` replaces `defineAuth` (ADR 0015). @public */
+/** SE36 — `Auth.create` replaces `defineAuth` (ADR 0015). @public  *
+ * `Auth.create` returns an **`AuthOrchestrator<TSession>`**, not an `Auth`. The class is
+ * the namespace; the orchestrator is the product.
+ */
 export declare class Auth {
     private constructor();
     static create<TSession>(opts: DefineAuthOptions<TSession>): AuthOrchestrator<TSession>;

package/dist/server/auth/types.d.cts

@@ -17,6 +17,24 @@ export interface SessionManager<TSession> {
     createSession(res: ServerResponse, data: TSession): Promise<void>;
     destroySession(res: ServerResponse): void;
     rotateSession(req: IncomingMessage, res: ServerResponse): Promise<TSession | null>;
+    /**
+     * The secret used to encrypt the OAuth transaction cookie, when this manager has one to share.
+     *
+     * OPTIONAL and additive: a manager without it makes `defineAuth` fall back to
+     * `THEOKIT_OAUTH_TX_SECRET`, which is the behaviour that already existed.
+     *
+     * It exists because the orchestrator was reading `session.secret` through
+     * `as unknown as { secret?: string | string[] }` — asserting a shape this contract did not offer,
+     * so no conforming caller could reach the branch and nothing in `src/` supplied it. The branch was
+     * green only because a test double carried the field. `orchestrator.ts` said in a comment that it
+     * WANTED this member ("may refactor to share the SessionManager's actual secret rotation chain via
+     * a `getCookieSecret()` method"); declaring it is what makes the branch reachable through the port
+     * and the double conform instead of the reverse.
+     *
+     * An array is accepted for rotation: the first entry encrypts, and the rest are for verifying
+     * cookies written before the last rotation.
+     */
+    getCookieSecret?(): string | string[] | undefined;
 }
 /**
  * Per ADR D5 — OAuth transaction state stored in encrypted HttpOnly cookie

package/dist/server/auth/types.d.ts

@@ -17,6 +17,24 @@ export interface SessionManager<TSession> {
     createSession(res: ServerResponse, data: TSession): Promise<void>;
     destroySession(res: ServerResponse): void;
     rotateSession(req: IncomingMessage, res: ServerResponse): Promise<TSession | null>;
+    /**
+     * The secret used to encrypt the OAuth transaction cookie, when this manager has one to share.
+     *
+     * OPTIONAL and additive: a manager without it makes `defineAuth` fall back to
+     * `THEOKIT_OAUTH_TX_SECRET`, which is the behaviour that already existed.
+     *
+     * It exists because the orchestrator was reading `session.secret` through
+     * `as unknown as { secret?: string | string[] }` — asserting a shape this contract did not offer,
+     * so no conforming caller could reach the branch and nothing in `src/` supplied it. The branch was
+     * green only because a test double carried the field. `orchestrator.ts` said in a comment that it
+     * WANTED this member ("may refactor to share the SessionManager's actual secret rotation chain via
+     * a `getCookieSecret()` method"); declaring it is what makes the branch reachable through the port
+     * and the double conform instead of the reverse.
+     *
+     * An array is accepted for rotation: the first entry encrypts, and the rest are for verifying
+     * cookies written before the last rotation.
+     */
+    getCookieSecret?(): string | string[] | undefined;
 }
 /**
  * Per ADR D5 — OAuth transaction state stored in encrypted HttpOnly cookie

package/dist/server/errors-envelope.cjs

@@ -1,8 +1,7 @@
 'use strict';
 
-var chunk4ZHTIJNE_cjs = require('../chunk-4ZHTIJNE.cjs');
-require('../chunk-XL7Q7HB2.cjs');
-require('../chunk-EG4QM7ZJ.cjs');
+var chunkJ7J7J2GN_cjs = require('../chunk-J7J7J2GN.cjs');
+require('../chunk-6LHQPOMI.cjs');
 
 // src/server/errors-envelope.ts
 var NAME_TO_CODE = /* @__PURE__ */ new Map([
@@ -38,7 +37,7 @@ function toEnvelope(value) {
 }
 function buildMeta(name, err) {
   const meta = { sdkErrorName: name };
-  if (err instanceof chunk4ZHTIJNE_cjs.TheokitAgentError && err.metadata !== void 0) {
+  if (err instanceof chunkJ7J7J2GN_cjs.TheokitAgentError && err.metadata !== void 0) {
     meta.provider = err.metadata.provider;
     meta.endpoint = err.metadata.endpoint;
     if (err.metadata.statusCode !== void 0) {
@@ -48,13 +47,13 @@ function buildMeta(name, err) {
   return meta;
 }
 function buildExt(err) {
-  if (err instanceof chunk4ZHTIJNE_cjs.RateLimitError && err.metadata?.retryAfter !== void 0) {
+  if (err instanceof chunkJ7J7J2GN_cjs.RateLimitError && err.metadata?.retryAfter !== void 0) {
     return {
       retryable: true,
       retryAfterMs: err.metadata.retryAfter * 1e3
     };
   }
-  if (err instanceof chunk4ZHTIJNE_cjs.CredentialPoolExhaustedError && err.nextRetryAt !== void 0) {
+  if (err instanceof chunkJ7J7J2GN_cjs.CredentialPoolExhaustedError && err.nextRetryAt !== void 0) {
     const delayMs = Math.max(0, err.nextRetryAt - Date.now());
     return {
       retryable: true,
@@ -64,22 +63,22 @@ function buildExt(err) {
   return void 0;
 }
 var CODE_TO_RECONSTRUCTOR = /* @__PURE__ */ new Map([
-  ["UNAUTHORIZED", (env) => new chunk4ZHTIJNE_cjs.AuthenticationError(env.message)],
+  ["UNAUTHORIZED", (env) => new chunkJ7J7J2GN_cjs.AuthenticationError(env.message)],
   [
     "RATE_LIMITED",
-    (env) => new chunk4ZHTIJNE_cjs.RateLimitError(env.message, env.cause !== void 0 ? { cause: env.cause } : {})
+    (env) => new chunkJ7J7J2GN_cjs.RateLimitError(env.message, env.cause !== void 0 ? { cause: env.cause } : {})
   ],
-  ["PROVIDER_KEY_MISSING", (env) => new chunk4ZHTIJNE_cjs.ConfigurationError(env.message)],
-  ["SERVICE_UNAVAILABLE", (env) => new chunk4ZHTIJNE_cjs.NetworkError(env.message)],
-  ["GATEWAY_TIMEOUT", (env) => new chunk4ZHTIJNE_cjs.NetworkError(env.message)],
+  ["PROVIDER_KEY_MISSING", (env) => new chunkJ7J7J2GN_cjs.ConfigurationError(env.message)],
+  ["SERVICE_UNAVAILABLE", (env) => new chunkJ7J7J2GN_cjs.NetworkError(env.message)],
+  ["GATEWAY_TIMEOUT", (env) => new chunkJ7J7J2GN_cjs.NetworkError(env.message)],
   [
     "AGENT_RUN_ERROR",
-    (env) => new chunk4ZHTIJNE_cjs.AgentRunError(env.message, {
+    (env) => new chunkJ7J7J2GN_cjs.AgentRunError(env.message, {
       code: "unknown",
       ...env.cause !== void 0 ? { cause: env.cause } : {}
     })
   ],
-  ["INTERNAL_SERVER_ERROR", (env) => new chunk4ZHTIJNE_cjs.UnknownAgentError(env.message)]
+  ["INTERNAL_SERVER_ERROR", (env) => new chunkJ7J7J2GN_cjs.UnknownAgentError(env.message)]
   // BUDGET_EXCEEDED + CREDENTIAL_POOL_EXHAUSTED reconstructors require
   // domain-specific args (budgetName, provider) that the envelope doesn't
   // always carry. Fall back to UnknownAgentError when those fields are
@@ -89,12 +88,12 @@ var CODE_TO_RECONSTRUCTOR = /* @__PURE__ */ new Map([
 function fromEnvelope(env) {
   const reconstructor = CODE_TO_RECONSTRUCTOR.get(env.code);
   if (reconstructor) return reconstructor(env);
-  return new chunk4ZHTIJNE_cjs.UnknownAgentError(env.message);
+  return new chunkJ7J7J2GN_cjs.UnknownAgentError(env.message);
 }
 
 Object.defineProperty(exports, "MemoryAdapterError", {
   enumerable: true,
-  get: function () { return chunk4ZHTIJNE_cjs.MemoryAdapterError; }
+  get: function () { return chunkJ7J7J2GN_cjs.MemoryAdapterError; }
 });
 exports.fromEnvelope = fromEnvelope;
 exports.toEnvelope = toEnvelope;