okengine 0.17.2 → 0.18.4

package/src/plugins/oauth/flow-store.ts

@@ -0,0 +1,117 @@
+/**
+ * OAuth flow records on the shared verification store — PKCE verifier,
+ * state, nonce, expected issuer, exact redirect URI and optional linking
+ * subject, keyed `oauth:{provider}:{stateHash}` with SHA-256-hashed state at
+ * rest (same hygiene as magic-link/OTP rows). Single-use via consume.
+ */
+
+import {
+  createVerificationStore,
+  findActiveVerification,
+  consumeVerification,
+  hashChallenge,
+  putVerification,
+  type VerificationStore,
+} from "../../auth/verification.ts";
+import type { OAuthProviderId } from "./shared.ts";
+
+/** TTL for a pending OAuth authorization flow. */
+export const OAUTH_FLOW_TTL_MS = 10 * 60_000;
+
+/** One pending OAuth authorization-code flow. */
+export interface OAuthFlowRecord {
+  readonly provider: OAuthProviderId;
+  /** SHA-256 hex of the raw state — the row's secret value. */
+  readonly stateHash: string;
+  readonly codeVerifier: string;
+  /** EXACT redirect URI string registered at the provider. */
+  readonly redirectUri: string;
+  readonly nonce?: string;
+  /** Issuer the flow was initiated against (mix-up anchor). */
+  readonly expectedIssuer: string;
+  /** Client id used to start the flow (aud check). */
+  readonly clientId: string;
+  /** Authenticated user linking this login to an existing account. */
+  readonly currentUserId?: string;
+}
+
+/**
+ * Create (or reuse) a verification store backing OAuth flows.
+ *
+ * @param existing - Shared store when the host app provides one
+ */
+export function createOAuthFlowStore(existing?: VerificationStore): VerificationStore {
+  return existing ?? createVerificationStore();
+}
+
+/**
+ * Persist a new flow record.
+ *
+ * @param store - Verification store
+ * @param record - Flow fields
+ * @param now - Epoch-ms
+ */
+export async function putOauthFlow(
+  store: VerificationStore,
+  record: OAuthFlowRecord,
+  now: number,
+): Promise<void> {
+  putVerification(store, {
+    id: `oauth:${record.provider}:${record.stateHash}`,
+    identifier: `oauth:${record.provider}`,
+    value: record.stateHash,
+    expiresAt: now + OAUTH_FLOW_TTL_MS,
+    createdAt: now,
+    consumedAt: null,
+    attempts: 0,
+    // Flow fields ride the row's JSON slot (same pattern as channel-neutral OTP).
+    email: JSON.stringify(record),
+  });
+}
+
+/**
+ * Find the active (non-consumed, non-expired) flow row for `(provider, rawState)`.
+ *
+ * @param store - Verification store
+ * @param provider - Route provider id
+ * @param rawState - Raw `state` query/form value
+ * @param now - Epoch-ms
+ */
+export async function findOauthFlow(
+  store: VerificationStore,
+  provider: OAuthProviderId,
+  rawState: string,
+  now: number,
+): Promise<OAuthFlowRecord | undefined> {
+  const stateHash = await hashChallenge(rawState);
+  for (const row of store.rows.values()) {
+    if (row.identifier !== `oauth:${provider}`) continue;
+    if (row.consumedAt !== null || row.expiresAt <= now) continue;
+    if (row.value !== stateHash || row.email === undefined || row.email === null) continue;
+    try {
+      return JSON.parse(row.email) as OAuthFlowRecord;
+    } catch {
+      return undefined;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Mark a flow row consumed (single-use — replay returns `invalid_state`).
+ *
+ * @param store - Verification store
+ * @param provider - Route provider id
+ * @param rawState - Raw state
+ * @param now - Epoch-ms
+ */
+export async function consumeOauthFlow(
+  store: VerificationStore,
+  provider: OAuthProviderId,
+  rawState: string,
+  now: number,
+): Promise<void> {
+  const stateHash = await hashChallenge(rawState);
+  const row = findActiveVerification(store, `oauth:${provider}`, now);
+  if (row && row.value === stateHash) consumeVerification(row, now);
+}

package/src/plugins/oauth/link.ts

@@ -0,0 +1,69 @@
+/**
+ * Identity bridge — every successful OAuth callback routes through
+ * `linkOrProvision`; driver assertions never write identities directly.
+ * `IdentityError` codes map onto the typed `AuthFailed` error surface.
+ */
+
+import { IdentityError, linkOrProvision, type IdentityStore } from "../../auth/identity.ts";
+import type { OAuthAssertion } from "../../drivers/oauth-types.ts";
+import type { OAuthProviderId } from "./shared.ts";
+
+/**
+ * Credential provider string namespacing OAuth accounts
+ * (`oke_credentials.provider = "oauth:google"` etc.).
+ *
+ * @param provider - Plugin provider id
+ */
+export function oauthCredentialProvider(provider: OAuthProviderId): string {
+  return `oauth:${provider}`;
+}
+
+/** Outcome of the identity bridge. */
+export interface OauthLinkResult {
+  readonly userId: string;
+}
+
+/**
+ * Route a verified assertion through `linkOrProvision`.
+ *
+ * GHSA-6g38-8j4p-j3pr defense: `emailVerified` comes verbatim from the
+ * driver trust matrix (default false), and `linkOrProvision` refuses to take
+ * over an existing email (`email_in_use`) unless `currentUserId` proves the
+ * caller already owns the account.
+ *
+ * @param identities - Shared identity store
+ * @param provider - Provider id
+ * @param assertion - Verified driver assertion
+ * @param currentUserId - Authenticated subject when linking from a session
+ */
+export async function oauthLink(
+  identities: IdentityStore,
+  provider: OAuthProviderId,
+  assertion: OAuthAssertion,
+  currentUserId?: string,
+): Promise<OauthLinkResult> {
+  const { user } = await linkOrProvision(identities, {
+    provider: oauthCredentialProvider(provider),
+    providerAccountId: assertion.subject,
+    ...(assertion.email !== undefined ? { email: assertion.email } : {}),
+    emailVerified: assertion.emailVerified,
+    ...(assertion.name !== undefined ? { name: assertion.name } : {}),
+    ...(currentUserId !== undefined ? { currentUserId } : {}),
+  });
+  return { userId: user.id };
+}
+
+/**
+ * Map an {@link IdentityError} code onto a client-safe failure reason.
+ *
+ * @param err - Identity error
+ */
+export function identityFailureReason(err: unknown): string | undefined {
+  if (err instanceof IdentityError) {
+    // Enumeration hygiene: never disclose which emails exist.
+    if (err.code === "email_in_use" || err.code === "email_conflict") return "email_in_use";
+    if (err.code === "identity_not_found") return "invalid_credentials";
+    return err.code;
+  }
+  return undefined;
+}

package/src/plugins/oauth/shared.ts

@@ -0,0 +1,108 @@
+/**
+ * OAuth plugin shared surface: options, provider ids, PKCE minting.
+ * Backend-only — never imported by Console UI.
+ */
+
+import type { VerificationStore } from "../../auth/verification.ts";
+import type { SessionStore } from "../../auth/sessions.ts";
+import { generateCodeVerifier, codeChallengeS256 } from "../../drivers/oauth-shared.ts";
+import type { OAuthDriverId } from "../../drivers/oauth-types.ts";
+import type { AnyFlowDef } from "../../kernel/flow.ts";
+import { bindAuthHttp } from "../../auth/bindings.ts";
+import { http } from "../auth/shared.ts";
+import type { Binding } from "../../kernel/on.ts";
+
+/** Every supported social provider. */
+export const OAUTH_PROVIDER_IDS = [
+  "google",
+  "apple",
+  "microsoft",
+  "github",
+  "discord",
+  "x",
+  "facebook",
+  "figma",
+] as const;
+
+/** Supported social providers (same set as {@link OAuthDriverId}). */
+export type OAuthProviderId = OAuthDriverId;
+
+/** Per-provider plugin configuration. */
+export interface OAuthProviderConfig {
+  /** Enable this provider (default `false`). */
+  readonly enabled?: boolean;
+  /**
+   * Confidential client id. Public information — inline config is fine;
+   * `OAUTH_<PROVIDER>_CLIENT_ID` via Vault/env also resolves at boot.
+   */
+  readonly clientId?: string;
+  /**
+   * EXACT redirect URI string registered at the provider console. Compared
+   * byte-for-byte — never derived from the request. Defaults to
+   * `${baseUrl}/auth/oauth/callback/{provider}`.
+   */
+  readonly redirectUri?: string;
+  /** Scopes requested at the provider (driver defaults apply when omitted). */
+  readonly scopes?: readonly string[];
+  /** Opt-in storage of provider tokens in Vault (encrypted), default off. */
+  readonly storeProviderTokens?: boolean;
+  /** Microsoft only — tenant selector or GUID (default `common`). */
+  readonly tenant?: "common" | "organizations" | "consumers" | string;
+  /** Apple only — Developer team id (client-secret JWT `iss`). */
+  readonly teamId?: string;
+  /** Apple only — Sign in with Apple private-key id (`kid`). */
+  readonly keyId?: string;
+}
+
+/** Options for the {@link oauth} plugin factory. */
+export interface OAuthOptions {
+  /** Per-provider configuration; providers default to disabled. */
+  readonly providers?: Readonly<Partial<Record<OAuthProviderId, OAuthProviderConfig>>>;
+  /**
+   * Default app origin used to synthesize per-provider callback redirect
+   * URIs (`{baseUrl}/auth/oauth/callback/{provider}`).
+   */
+  readonly baseUrl?: string;
+  /** HMAC secret; falls back to the active `gate.auth` secret like other methods. */
+  readonly secret?: string;
+  /** Shared session store (prefer the same store as `gate.auth`). */
+  readonly sessions?: SessionStore;
+  /** Shared identity/credential store (defaults to `gate.auth.identities`). */
+  readonly identities?: import("../../auth/identity.ts").IdentityStore;
+  /** Shared verification store backing OAuth flow rows (tests / advanced). */
+  readonly verifications?: VerificationStore;
+  /** Injectable clock. */
+  readonly now?: () => number;
+  /** Injectable fetch for every driver (tests — mock IdP). */
+  readonly fetch?: typeof globalThis.fetch;
+}
+
+/**
+ * Fresh PKCE pair for a new authorization-code flow (RFC 7636 S256).
+ */
+export async function mintPkcePair(): Promise<{ verifier: string; challenge: string }> {
+  const verifier = generateCodeVerifier();
+  return { verifier, challenge: await codeChallengeS256(verifier) };
+}
+
+/**
+ * Bind an auth Flow to a public **GET** trigger — provider redirects carry
+ * `?code=&state=`. The POST twin (Apple form_post) is bound separately.
+ *
+ * @param path - Absolute route path
+ * @param flowDef - Flow to bind
+ * @param gates - Optional gate decls (rate limiting)
+ */
+export function bindPublicAuthGet(
+  path: string,
+  flowDef: AnyFlowDef,
+  gates: readonly Parameters<ReturnType<typeof http.get>["gate"]>[0][] = [],
+): Binding {
+  return bindAuthHttp(
+    http
+      .get(path)
+      .public()
+      .gate(...gates),
+    flowDef,
+  );
+}

package/src/plugins/oauth/token-vault.ts

@@ -0,0 +1,100 @@
+/**
+ * Envelope sealing for opt-in provider-token storage.
+ *
+ * Vault paths hold one sealed blob per provider; inside, an AES-GCM-sealed
+ * map keyed by user id. The seal key is HKDF-derived from the auth secret
+ * with a domain-separated info string (never the session HMAC material) —
+ * same pattern as `otp-seal`.
+ */
+
+/** HKDF `info` — versioned; bump when the envelope format changes. */
+export const OAUTH_TOKEN_SEAL_HKDF_INFO = "oke-oauth-token-seal-v1";
+
+const INFO_BYTES = new TextEncoder().encode(OAUTH_TOKEN_SEAL_HKDF_INFO);
+const EMPTY_SALT = new Uint8Array(0);
+
+async function deriveSealKey(secret: string): Promise<CryptoKey> {
+  const baseKey = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(secret),
+    "HKDF",
+    false,
+    ["deriveKey"],
+  );
+  return crypto.subtle.deriveKey(
+    { name: "HKDF", hash: "SHA-256", salt: EMPTY_SALT, info: INFO_BYTES },
+    baseKey,
+    { name: "AES-GCM", length: 256 },
+    false,
+    ["encrypt", "decrypt"],
+  );
+}
+
+/**
+ * Seal a cleartext payload to `IV || ciphertext+tag`, base64-encoded.
+ *
+ * @param secret - Root auth secret
+ * @param plaintext - Cleartext bytes/string
+ */
+export async function sealTokenBlob(secret: string, plaintext: string): Promise<string> {
+  const key = await deriveSealKey(secret);
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const cipher = await crypto.subtle.encrypt(
+    { name: "AES-GCM", iv },
+    key,
+    new TextEncoder().encode(plaintext),
+  );
+  const packed = new Uint8Array(iv.length + cipher.byteLength);
+  packed.set(iv, 0);
+  packed.set(new Uint8Array(cipher), iv.length);
+  return Buffer.from(packed).toString("base64");
+}
+
+/**
+ * Open a blob produced by {@link sealTokenBlob}.
+ *
+ * @param secret - Root auth secret
+ * @param blob - Base64 sealed blob
+ */
+export async function openTokenBlob(secret: string, blob: string): Promise<string> {
+  const key = await deriveSealKey(secret);
+  const packed = Buffer.from(blob, "base64");
+  if (packed.byteLength < 13) throw new Error("oauth-token-seal: malformed blob");
+  const iv = new Uint8Array(packed.subarray(0, 12));
+  const data = packed.subarray(12);
+  const plain = await crypto.subtle.decrypt(
+    { name: "AES-GCM", iv: toArrayBuffer(iv) },
+    key,
+    toArrayBuffer(data),
+  );
+  return new TextDecoder().decode(plain);
+}
+
+function toArrayBuffer(view: Uint8Array): ArrayBuffer {
+  const copy = new Uint8Array(view.byteLength);
+  copy.set(view);
+  return copy.buffer;
+}
+
+/**
+ * Seal a full per-user token map (the vault path value).
+ *
+ * @param secret - Root auth secret
+ * @param envelope - userId → sealed per-user blob
+ */
+export async function sealTokenEnvelope(secret: string, envelopeJson: string): Promise<string> {
+  return sealTokenBlob(secret, envelopeJson);
+}
+
+/**
+ * Open a vault path value into its per-user token map.
+ *
+ * @param secret - Root auth secret
+ * @param sealed - Sealed envelope JSON
+ */
+export async function unsealTokenEnvelope(
+  secret: string,
+  sealed: string,
+): Promise<Record<string, string>> {
+  return JSON.parse(await openTokenBlob(secret, sealed)) as Record<string, string>;
+}