okengine 0.4.3 → 0.5.1

package/src/plugins/passkey.ts

@@ -0,0 +1,282 @@
+/**
+ * Passkey (WebAuthn) Gate auth method plugin.
+ *
+ * Registration and authentication verify clientDataJSON origin + challenge,
+ * authenticatorData rpId hash, and ECDSA P-256 signature against the stored
+ * SPKI public key. Presence-only authenticate is rejected.
+ */
+
+import { constantTimeEqual } from "../auth/constant-time.ts";
+import {
+  createVerificationStore,
+  hashChallenge,
+  putVerification,
+  type VerificationStore,
+} from "../auth/verification.ts";
+import { issueSessionWithScopes } from "../auth/sessions.ts";
+import { plugin, type PluginDef } from "../kernel/plugin.ts";
+import {
+  AuthFailed,
+  AuthRateLimited,
+  SessionTokensOut,
+  bindPublicAuth,
+  bindSessionAuth,
+  createMethodRuntime,
+  fail,
+  flow,
+  z,
+  type AuthMethodOptions,
+} from "./auth/shared.ts";
+import { verifyWebAuthnCeremony } from "./passkey-webauthn.ts";
+
+/** Stored passkey credential. */
+export interface PasskeyCredential {
+  readonly credentialId: string;
+  readonly userId: string;
+  /** Base64url SPKI public key (ECDSA P-256). */
+  readonly publicKey: string;
+  counter: number;
+  readonly createdAt: number;
+}
+
+/** In-memory passkey store. */
+export interface PasskeyStore {
+  readonly byCredentialId: Map<string, PasskeyCredential>;
+  readonly byUserId: Map<string, PasskeyCredential[]>;
+}
+
+/**
+ * Create an empty passkey store.
+ */
+export function createPasskeyStore(): PasskeyStore {
+  return { byCredentialId: new Map(), byUserId: new Map() };
+}
+
+/** Options for {@link passkey}. */
+export interface PasskeyOptions extends AuthMethodOptions {
+  readonly passkeys?: PasskeyStore;
+  readonly challenges?: VerificationStore;
+  /** Relying party id (default `localhost`). */
+  readonly rpId?: string;
+  /**
+   * Allowed `clientDataJSON.origin` values.
+   * Default: `http://localhost` and `https://localhost`.
+   */
+  readonly origins?: readonly string[];
+}
+
+const CeremonyIn = z.object({
+  credentialId: z.string().min(1),
+  publicKey: z.string().min(1).optional(),
+  userId: z.string().min(1).optional(),
+  challenge: z.string().min(1),
+  clientDataJSON: z.string().min(1),
+  authenticatorData: z.string().min(1),
+  signature: z.string().min(1),
+});
+
+/**
+ * Passkey register / authenticate with cryptographic WebAuthn verify (`oke_passkeys`).
+ *
+ * @param opts - Stores / RP id / allowed origins
+ */
+export function passkey(opts: PasskeyOptions = {}): PluginDef {
+  const runtime = createMethodRuntime(opts);
+  const passkeys = opts.passkeys ?? createPasskeyStore();
+  const challenges = opts.challenges ?? createVerificationStore();
+  const rpId = opts.rpId ?? "localhost";
+  const origins = opts.origins ?? ["http://localhost", "https://localhost"];
+
+  const registerOptions = flow({
+    name: "auth.passkeyRegisterOptions",
+    unit: "auth",
+    plane: "user",
+    out: z.object({
+      challenge: z.string(),
+      rpId: z.string(),
+      userId: z.string(),
+    }),
+    errors: { AuthFailed },
+    do: async (_input, fx) => {
+      const userId = fx.auth.userId;
+      if (!userId) return fail("AuthFailed", { reason: "unauthenticated" });
+      const challenge = crypto.randomUUID().replace(/-/g, "");
+      const now = runtime.now();
+      putVerification(challenges, {
+        id: crypto.randomUUID(),
+        identifier: `passkey-reg:${userId}`,
+        value: await hashChallenge(challenge),
+        expiresAt: now + 5 * 60 * 1000,
+        createdAt: now,
+        consumedAt: null,
+        attempts: 0,
+      });
+      return { challenge, rpId, userId };
+    },
+  });
+
+  const register = flow({
+    name: "auth.passkeyRegister",
+    unit: "auth",
+    plane: "user",
+    in: CeremonyIn.extend({
+      publicKey: z.string().min(1),
+      userId: z.string().min(1),
+    }),
+    out: z.object({ ok: z.literal(true) }),
+    errors: { AuthFailed },
+    do: async (input, fx) => {
+      const sessionUser = fx.auth.userId;
+      if (!sessionUser || sessionUser !== input.userId) {
+        return fail("AuthFailed", { reason: "unauthenticated" });
+      }
+      const consumed = await consumeChallenge(
+        challenges,
+        `passkey-reg:${input.userId}`,
+        input.challenge,
+        runtime.now(),
+      );
+      if (!consumed) return fail("AuthFailed", { reason: "invalid_credentials" });
+
+      const verified = await verifyWebAuthnCeremony({
+        expectedType: "webauthn.create",
+        expectedChallenge: input.challenge,
+        expectedOrigins: origins,
+        rpId,
+        publicKeySpkiB64url: input.publicKey,
+        clientDataJSON: input.clientDataJSON,
+        authenticatorData: input.authenticatorData,
+        signature: input.signature,
+      });
+      if (!verified.ok) {
+        return fail("AuthFailed", {
+          reason: verified.reason === "invalid_origin" ? "invalid_origin" : "invalid_credentials",
+        });
+      }
+      if (passkeys.byCredentialId.has(input.credentialId)) {
+        return fail("AuthFailed", { reason: "invalid_credentials" });
+      }
+      const cred: PasskeyCredential = {
+        credentialId: input.credentialId,
+        userId: input.userId,
+        publicKey: input.publicKey,
+        counter: verified.signCount,
+        createdAt: runtime.now(),
+      };
+      passkeys.byCredentialId.set(cred.credentialId, cred);
+      const list = passkeys.byUserId.get(cred.userId) ?? [];
+      list.push(cred);
+      passkeys.byUserId.set(cred.userId, list);
+      return { ok: true as const };
+    },
+  });
+
+  const authenticateOptions = flow({
+    name: "auth.passkeyAuthenticateOptions",
+    unit: "auth",
+    plane: "user",
+    in: z.object({ email: z.string().optional() }),
+    out: z.object({
+      challenge: z.string(),
+      rpId: z.string(),
+      allowCredentials: z.array(z.string()),
+    }),
+    errors: { AuthFailed, AuthRateLimited },
+    do: async (input) => {
+      const challenge = crypto.randomUUID().replace(/-/g, "");
+      const now = runtime.now();
+      const key = input.email?.trim().toLowerCase() || "anonymous";
+      putVerification(challenges, {
+        id: crypto.randomUUID(),
+        identifier: `passkey-auth:${key}`,
+        value: await hashChallenge(challenge),
+        expiresAt: now + 5 * 60 * 1000,
+        createdAt: now,
+        consumedAt: null,
+        attempts: 0,
+      });
+      return { challenge, rpId, allowCredentials: [] as string[] };
+    },
+  });
+
+  const authenticate = flow({
+    name: "auth.passkeyAuthenticate",
+    unit: "auth",
+    plane: "user",
+    in: CeremonyIn.extend({
+      challenge: z.string().min(1),
+      /** Challenge bucket key from authenticate options (default `anonymous`). */
+      email: z.string().optional(),
+    }),
+    out: SessionTokensOut,
+    errors: { AuthFailed, AuthRateLimited },
+    do: async (input) => {
+      const cred = passkeys.byCredentialId.get(input.credentialId);
+      if (!cred) return fail("AuthFailed", { reason: "invalid_credentials" });
+
+      const bucket = input.email?.trim().toLowerCase() || "anonymous";
+      const consumed = await consumeChallenge(
+        challenges,
+        `passkey-auth:${bucket}`,
+        input.challenge,
+        runtime.now(),
+      );
+      if (!consumed) return fail("AuthFailed", { reason: "invalid_credentials" });
+
+      const verified = await verifyWebAuthnCeremony({
+        expectedType: "webauthn.get",
+        expectedChallenge: input.challenge,
+        expectedOrigins: origins,
+        rpId,
+        publicKeySpkiB64url: cred.publicKey,
+        clientDataJSON: input.clientDataJSON,
+        authenticatorData: input.authenticatorData,
+        signature: input.signature,
+        previousSignCount: cred.counter,
+      });
+      if (!verified.ok) {
+        return fail("AuthFailed", {
+          reason: verified.reason === "invalid_origin" ? "invalid_origin" : "invalid_credentials",
+        });
+      }
+      cred.counter = verified.signCount;
+
+      const issued = await issueSessionWithScopes(runtime.sessions, runtime.crypto, {
+        id: cred.userId,
+        plane: "user",
+        scopes: [],
+      });
+      return {
+        accessToken: issued.accessToken,
+        refreshToken: issued.refreshToken,
+        accessExpiresAt: issued.accessExpiresAt,
+        userId: cred.userId,
+      };
+    },
+  });
+
+  return plugin("passkey", { version: "0.0.1", config: { method: "passkey" } })
+    .needs("auth")
+    .table("oke_passkeys", undefined, { plane: "user", description: "WebAuthn credentials" })
+    .binding(bindSessionAuth("/passkey/register/options", registerOptions))
+    .binding(bindSessionAuth("/passkey/register", register))
+    .binding(bindPublicAuth("/passkey/authenticate/options", authenticateOptions, "otp"))
+    .binding(bindPublicAuth("/passkey/authenticate", authenticate, "otp"));
+}
+
+async function consumeChallenge(
+  store: VerificationStore,
+  identifier: string,
+  challenge: string,
+  now: number,
+): Promise<boolean> {
+  const hash = await hashChallenge(challenge);
+  for (const row of store.rows.values()) {
+    if (row.identifier !== identifier) continue;
+    if (row.consumedAt !== null || row.expiresAt <= now) continue;
+    if (!constantTimeEqual(row.value, hash)) continue;
+    row.consumedAt = now;
+    return true;
+  }
+  return false;
+}

package/src/plugins/phone-number.ts

@@ -0,0 +1,149 @@
+/**
+ * Phone-number OTP Gate auth method plugin (E.164).
+ */
+
+import { issueSessionWithScopes } from "../auth/sessions.ts";
+import {
+  createVerificationStore,
+  findActiveVerification,
+  generateOtp,
+  hashChallenge,
+  putVerification,
+  type VerificationStore,
+} from "../auth/verification.ts";
+import { plugin, type PluginDef } from "../kernel/plugin.ts";
+import {
+  AuthFailed,
+  AuthRateLimited,
+  SessionTokensOut,
+  bindPublicAuth,
+  createMethodRuntime,
+  fail,
+  flow,
+  z,
+  type AuthMethodOptions,
+} from "./auth/shared.ts";
+
+const E164 = /^\+[1-9]\d{7,14}$/;
+const DEFAULT_TTL_MS = 10 * 60 * 1000;
+const MAX_ATTEMPTS = 5;
+
+/** Phone principal store (phone → userId). */
+export interface PhoneStore {
+  readonly byPhone: Map<string, string>;
+}
+
+/**
+ * Create an empty phone → user map.
+ */
+export function createPhoneStore(): PhoneStore {
+  return { byPhone: new Map() };
+}
+
+/** Options for {@link phoneNumber}. */
+export interface PhoneNumberOptions extends AuthMethodOptions {
+  readonly ttlMs?: number;
+  readonly phones?: PhoneStore;
+  readonly verifications?: VerificationStore;
+  /** Return raw OTP in the request response (test / local). */
+  readonly exposeDevOtp?: boolean;
+}
+
+/**
+ * Phone OTP request + verify (E.164, 6-digit, hashed, 5 attempts).
+ *
+ * @param opts - TTL / stores / dev OTP
+ */
+export function phoneNumber(opts: PhoneNumberOptions = {}): PluginDef {
+  const runtime = createMethodRuntime(opts);
+  const phones = opts.phones ?? createPhoneStore();
+  const verifications = opts.verifications ?? createVerificationStore();
+  const ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
+
+  const request = flow({
+    name: "auth.requestPhoneOtp",
+    unit: "auth",
+    plane: "user",
+    in: z.object({ phone: z.string().min(8) }),
+    out: z.object({
+      ok: z.literal(true),
+      devOtp: z.string().optional(),
+    }),
+    errors: { AuthFailed, AuthRateLimited },
+    do: async (input) => {
+      const phone = input.phone.trim();
+      if (!E164.test(phone)) return fail("AuthFailed", { reason: "invalid_phone" });
+      const otp = generateOtp(6);
+      const now = runtime.now();
+      for (const row of verifications.rows.values()) {
+        if (row.identifier === `phone-otp:${phone}` && row.consumedAt === null) {
+          row.consumedAt = now;
+        }
+      }
+      putVerification(verifications, {
+        id: crypto.randomUUID(),
+        identifier: `phone-otp:${phone}`,
+        value: await hashChallenge(otp),
+        expiresAt: now + ttlMs,
+        createdAt: now,
+        consumedAt: null,
+        attempts: 0,
+      });
+      return {
+        ok: true as const,
+        ...(opts.exposeDevOtp ? { devOtp: otp } : {}),
+      };
+    },
+  });
+
+  const verify = flow({
+    name: "auth.verifyPhoneOtp",
+    unit: "auth",
+    plane: "user",
+    in: z.object({
+      phone: z.string().min(8),
+      otp: z.string().min(4).max(8),
+    }),
+    out: SessionTokensOut,
+    errors: { AuthFailed, AuthRateLimited },
+    do: async (input) => {
+      const phone = input.phone.trim();
+      if (!E164.test(phone)) return fail("AuthFailed", { reason: "invalid_phone" });
+      const now = runtime.now();
+      const row = findActiveVerification(verifications, `phone-otp:${phone}`, now);
+      if (!row) return fail("AuthFailed", { reason: "invalid_credentials" });
+      if (row.attempts >= MAX_ATTEMPTS) {
+        row.consumedAt = now;
+        return fail("AuthFailed", { reason: "invalid_credentials" });
+      }
+      const hash = await hashChallenge(input.otp.trim());
+      if (hash !== row.value) {
+        row.attempts += 1;
+        if (row.attempts >= MAX_ATTEMPTS) row.consumedAt = now;
+        return fail("AuthFailed", { reason: "invalid_credentials" });
+      }
+      row.consumedAt = now;
+      let userId = phones.byPhone.get(phone);
+      if (!userId) {
+        userId = crypto.randomUUID();
+        phones.byPhone.set(phone, userId);
+      }
+      const issued = await issueSessionWithScopes(runtime.sessions, runtime.crypto, {
+        id: userId,
+        plane: "user",
+        scopes: [],
+      });
+      return {
+        accessToken: issued.accessToken,
+        refreshToken: issued.refreshToken,
+        accessExpiresAt: issued.accessExpiresAt,
+        userId,
+      };
+    },
+  });
+
+  return plugin("phoneNumber", { version: "0.0.1", config: { method: "phone-number" } })
+    .needs("auth")
+    .binding(bindPublicAuth("/phone/request", request, "otp"))
+    .binding(bindPublicAuth("/phone/verify", verify, "otp"));
+}

package/src/plugins/response-headers.ts

@@ -0,0 +1,54 @@
+/**
+ * Shared response-header mutation for HTTP middleware plugins.
+ * Web `Headers` are immutable-in-place on a built `Response` — rebuild instead.
+ */
+
+/**
+ * Rebuild a response with headers mutated by `fn`.
+ *
+ * @param response - Original response
+ * @param fn - Header mutation
+ */
+export function withHeaders(response: Response, fn: (headers: Headers) => void): Response {
+  const headers = new Headers(response.headers);
+  fn(headers);
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+  });
+}
+
+/**
+ * Set a header only when absent (or when `override` is on).
+ *
+ * @param headers - Mutable headers
+ * @param name - Header name
+ * @param value - Header value
+ * @param override - Replace an app-set value
+ */
+export function setUnlessPresent(
+  headers: Headers,
+  name: string,
+  value: string,
+  override: boolean,
+): void {
+  if (!override && headers.has(name)) return;
+  headers.set(name, value);
+}
+
+/**
+ * Append a token to `Vary` without duplicating it.
+ *
+ * @param headers - Mutable headers
+ * @param token - Vary token (e.g. `"origin"`)
+ */
+export function appendVary(headers: Headers, token: string): void {
+  const vary = headers.get("vary");
+  if (vary === null) {
+    headers.set("vary", token);
+    return;
+  }
+  const pattern = new RegExp(`\\b${token.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`, "i");
+  if (!pattern.test(vary)) headers.set("vary", `${vary}, ${token}`);
+}