okengine 0.4.3 → 0.5.1

package/src/plugins/magic-link.ts

@@ -0,0 +1,163 @@
+/**
+ * Magic-link Gate auth method plugin.
+ *
+ * Delivery via Channel is optional in v1 — when {@link MagicLinkOptions.exposeDevToken}
+ * is set, the request response includes `devToken` for tests / local DX.
+ */
+
+import {
+  createIdentityStore,
+  normalizeEmail,
+  type IdentityStore,
+  type UserIdentityRow,
+} from "../auth/identity.ts";
+import { issueSessionWithScopes } from "../auth/sessions.ts";
+import {
+  createVerificationStore,
+  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 DEFAULT_TTL_MS = 10 * 60 * 1000;
+
+/** Options for {@link magicLink}. */
+export interface MagicLinkOptions extends AuthMethodOptions {
+  /** Challenge TTL (default 10m). */
+  readonly ttlMs?: number;
+  /** Identity store for email → user. */
+  readonly identities?: IdentityStore;
+  /** Verification / challenge store. */
+  readonly verifications?: VerificationStore;
+  /** Return raw token in the request response (test / local). */
+  readonly exposeDevToken?: boolean;
+}
+
+/**
+ * Magic-link request + verify (`oke_verifications` challenge rows).
+ *
+ * @param opts - TTL / stores / dev token
+ */
+export function magicLink(opts: MagicLinkOptions = {}): PluginDef {
+  const runtime = createMethodRuntime(opts);
+  const identities = opts.identities ?? createIdentityStore();
+  const verifications = opts.verifications ?? createVerificationStore();
+  const ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
+
+  const request = flow({
+    name: "auth.requestMagicLink",
+    unit: "auth",
+    plane: "user",
+    in: z.object({ email: z.string().min(3) }),
+    out: z.object({
+      ok: z.literal(true),
+      devToken: z.string().optional(),
+    }),
+    errors: { AuthFailed, AuthRateLimited },
+    do: async (input) => {
+      const email = normalizeEmail(input.email);
+      if (!email.includes("@")) return fail("AuthFailed", { reason: "invalid_email" });
+      const token = `ml_${crypto.randomUUID().replace(/-/g, "")}`;
+      const now = runtime.now();
+      putVerification(verifications, {
+        id: crypto.randomUUID(),
+        identifier: `magic:${email}`,
+        value: await hashChallenge(token),
+        expiresAt: now + ttlMs,
+        createdAt: now,
+        consumedAt: null,
+        attempts: 0,
+      });
+      return {
+        ok: true as const,
+        ...(opts.exposeDevToken ? { devToken: token } : {}),
+      };
+    },
+  });
+
+  const verify = flow({
+    name: "auth.verifyMagicLink",
+    unit: "auth",
+    plane: "user",
+    in: z.object({ token: z.string().min(1) }),
+    out: SessionTokensOut,
+    errors: { AuthFailed, AuthRateLimited },
+    do: async (input) => {
+      const hash = await hashChallenge(input.token);
+      const now = runtime.now();
+      let row:
+        | {
+            id: string;
+            identifier: string;
+            value: string;
+            expiresAt: number;
+            consumedAt: number | null;
+            attempts: number;
+          }
+        | undefined;
+      for (const candidate of verifications.rows.values()) {
+        if (!candidate.identifier.startsWith("magic:")) continue;
+        if (candidate.consumedAt !== null) continue;
+        if (candidate.expiresAt <= now) continue;
+        if (candidate.value === hash) {
+          row = candidate;
+          break;
+        }
+      }
+      if (!row) return fail("AuthFailed", { reason: "invalid_credentials" });
+      row.consumedAt = now;
+      const email = row.identifier.slice("magic:".length);
+      const user = ensureUserByEmail(identities, email, now);
+      const issued = await issueSessionWithScopes(runtime.sessions, runtime.crypto, {
+        id: user.id,
+        plane: "user",
+        scopes: [],
+      });
+      return {
+        accessToken: issued.accessToken,
+        refreshToken: issued.refreshToken,
+        accessExpiresAt: issued.accessExpiresAt,
+        userId: user.id,
+      };
+    },
+  });
+
+  return plugin("magicLink", { version: "0.0.1", config: { method: "magic-link" } })
+    .needs("auth")
+    .binding(bindPublicAuth("/magic-link/request", request, "otp"))
+    .binding(bindPublicAuth("/magic-link/verify", verify, "otp"));
+}
+
+function ensureUserByEmail(store: IdentityStore, email: string, now: number): UserIdentityRow {
+  const existingId = store.byEmail.get(email);
+  if (existingId) {
+    const existing = store.users.get(existingId);
+    if (existing) return existing;
+  }
+  const id = crypto.randomUUID();
+  const user: UserIdentityRow = {
+    id,
+    email,
+    name: email.split("@")[0] || "user",
+    emailVerified: true,
+    status: "active",
+    createdAt: now,
+    updatedAt: now,
+    extra: {},
+  };
+  store.users.set(id, user);
+  store.byEmail.set(email, id);
+  return user;
+}

package/src/plugins/maintenance-mode.test.ts

@@ -18,7 +18,7 @@ beforeEach(() => {
 describe("maintenanceMode plugin", () => {
   test("returns 503 with ServiceUnavailable envelope and Retry-After", async () => {
     on(http.get("/x"), flow({ name: "x.get", do: () => ({ ok: true }) }));
-    const app = oke({ name: "maint" }).plug(maintenanceMode({ retryAfter: 120 }));
+    const app = oke({ autoBoot: false, name: "maint" }).plug(maintenanceMode({ retryAfter: 120 }));
 
     const res = await app.fetch(new Request("http://localhost/x"));
 
@@ -36,7 +36,9 @@ describe("maintenanceMode plugin", () => {
 
   test("enabled: false passes traffic through", async () => {
     on(http.get("/x"), flow({ name: "x.get", do: () => ({ ok: true }) }));
-    const app = oke({ name: "maint-off" }).plug(maintenanceMode({ enabled: false }));
+    const app = oke({ autoBoot: false, name: "maint-off" }).plug(
+      maintenanceMode({ enabled: false }),
+    );
 
     const res = await app.fetch(new Request("http://localhost/x"));
 
@@ -46,7 +48,9 @@ describe("maintenanceMode plugin", () => {
   test("allowPaths prefixes keep serving", async () => {
     on(http.get("/health"), flow({ name: "health.get", do: () => ({ up: true }) }));
     on(http.get("/x"), flow({ name: "x.get", do: () => ({ ok: true }) }));
-    const app = oke({ name: "maint-allow" }).plug(maintenanceMode({ allowPaths: ["/health"] }));
+    const app = oke({ autoBoot: false, name: "maint-allow" }).plug(
+      maintenanceMode({ allowPaths: ["/health"] }),
+    );
 
     const health = await app.fetch(new Request("http://localhost/health"));
     expect(health.status).toBe(200);
@@ -57,7 +61,7 @@ describe("maintenanceMode plugin", () => {
 
   test("bypass header lets operators through (any non-empty value)", async () => {
     on(http.get("/x"), flow({ name: "x.get", do: () => ({ ok: true }) }));
-    const app = oke({ name: "maint-bypass" }).plug(
+    const app = oke({ autoBoot: false, name: "maint-bypass" }).plug(
       maintenanceMode({ bypassHeader: "x-ops-token" }),
     );
 
@@ -72,7 +76,7 @@ describe("maintenanceMode plugin", () => {
 
   test("the 503 still flows through onResponse (other plugins stamp it)", async () => {
     on(http.get("/x"), flow({ name: "x.get", do: () => ({ ok: true }) }));
-    const app = oke({ name: "maint-stamp" }).plug(maintenanceMode());
+    const app = oke({ autoBoot: false, name: "maint-stamp" }).plug(maintenanceMode());
     app.hook("onResponse", (ctx) => {
       if (!ctx.response) return;
       const headers = new Headers(ctx.response.headers);

package/src/plugins/passkey-webauthn.ts

@@ -0,0 +1,217 @@
+/**
+ * Minimal WebAuthn assertion / registration verifier (ES256 / P-256).
+ *
+ * Validates clientDataJSON (type · challenge · origin), authenticatorData
+ * (rpId hash · user-presence), and ECDSA signature over
+ * `authenticatorData || SHA-256(clientDataJSON)` against a stored SPKI public key.
+ */
+
+import { constantTimeEqual } from "../auth/constant-time.ts";
+
+/** Result of a failed WebAuthn verify. */
+export type WebAuthnVerifyFailure = {
+  readonly ok: false;
+  readonly reason: string;
+};
+
+/** Successful assertion verify (with updated sign counter). */
+export type WebAuthnVerifySuccess = {
+  readonly ok: true;
+  readonly signCount: number;
+};
+
+/** Options for {@link verifyWebAuthnCeremony}. */
+export interface WebAuthnVerifyOptions {
+  readonly expectedType: "webauthn.create" | "webauthn.get";
+  readonly expectedChallenge: string;
+  readonly expectedOrigins: readonly string[];
+  readonly rpId: string;
+  /** Base64url SPKI (SubjectPublicKeyInfo) of the credential public key. */
+  readonly publicKeySpkiB64url: string;
+  /** Base64url clientDataJSON bytes. */
+  readonly clientDataJSON: string;
+  /** Base64url authenticatorData bytes. */
+  readonly authenticatorData: string;
+  /** Base64url ECDSA P-1363 signature. */
+  readonly signature: string;
+  /** Previous stored sign counter (authenticate only). */
+  readonly previousSignCount?: number;
+}
+
+/**
+ * Verify a WebAuthn create/get ceremony payload.
+ *
+ * @param opts - Expected RP values + assertion fields
+ */
+export async function verifyWebAuthnCeremony(
+  opts: WebAuthnVerifyOptions,
+): Promise<WebAuthnVerifySuccess | WebAuthnVerifyFailure> {
+  let clientDataBytes: Uint8Array;
+  let authData: Uint8Array;
+  let signature: Uint8Array;
+  try {
+    clientDataBytes = b64urlDecode(opts.clientDataJSON);
+    authData = b64urlDecode(opts.authenticatorData);
+    signature = b64urlDecode(opts.signature);
+  } catch {
+    return { ok: false, reason: "invalid_credentials" };
+  }
+
+  if (authData.length < 37) return { ok: false, reason: "invalid_credentials" };
+
+  let clientData: { type?: unknown; challenge?: unknown; origin?: unknown };
+  try {
+    clientData = JSON.parse(new TextDecoder().decode(clientDataBytes)) as typeof clientData;
+  } catch {
+    return { ok: false, reason: "invalid_credentials" };
+  }
+
+  if (typeof clientData.type !== "string" || clientData.type !== opts.expectedType) {
+    return { ok: false, reason: "invalid_credentials" };
+  }
+  if (typeof clientData.challenge !== "string") {
+    return { ok: false, reason: "invalid_credentials" };
+  }
+  if (!constantTimeEqual(clientData.challenge, opts.expectedChallenge)) {
+    return { ok: false, reason: "invalid_credentials" };
+  }
+  if (typeof clientData.origin !== "string") {
+    return { ok: false, reason: "invalid_credentials" };
+  }
+  if (!opts.expectedOrigins.includes(clientData.origin)) {
+    return { ok: false, reason: "invalid_origin" };
+  }
+
+  const rpHash = new Uint8Array(
+    await crypto.subtle.digest("SHA-256", new TextEncoder().encode(opts.rpId)),
+  );
+  for (let i = 0; i < 32; i++) {
+    if (authData[i] !== rpHash[i]) return { ok: false, reason: "invalid_credentials" };
+  }
+
+  const flags = authData[32]!;
+  // User Present (bit 0) required.
+  if ((flags & 0x01) === 0) return { ok: false, reason: "invalid_credentials" };
+
+  const signCount =
+    ((authData[33]! << 24) | (authData[34]! << 16) | (authData[35]! << 8) | authData[36]!) >>> 0;
+
+  if (opts.previousSignCount !== undefined) {
+    // Spec: if both non-zero, authenticator count must strictly increase.
+    if (opts.previousSignCount > 0 && signCount > 0 && signCount <= opts.previousSignCount) {
+      return { ok: false, reason: "invalid_credentials" };
+    }
+  }
+
+  const clientDataHash = new Uint8Array(
+    await crypto.subtle.digest("SHA-256", asBufferSource(clientDataBytes)),
+  );
+  const signed = new Uint8Array(authData.length + clientDataHash.length);
+  signed.set(authData, 0);
+  signed.set(clientDataHash, authData.length);
+
+  let key: CryptoKey;
+  try {
+    key = await crypto.subtle.importKey(
+      "spki",
+      asBufferSource(b64urlDecode(opts.publicKeySpkiB64url)),
+      { name: "ECDSA", namedCurve: "P-256" },
+      false,
+      ["verify"],
+    );
+  } catch {
+    return { ok: false, reason: "invalid_credentials" };
+  }
+
+  const valid = await crypto.subtle.verify(
+    { name: "ECDSA", hash: "SHA-256" },
+    key,
+    asBufferSource(signature),
+    asBufferSource(signed),
+  );
+  if (!valid) return { ok: false, reason: "invalid_credentials" };
+
+  return { ok: true, signCount };
+}
+
+/**
+ * Encode bytes as unpadded base64url.
+ *
+ * @param bytes - Raw bytes
+ */
+export function b64urlEncode(bytes: Uint8Array): string {
+  let s = "";
+  for (const b of bytes) s += String.fromCharCode(b);
+  return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+/**
+ * Decode unpadded base64url to bytes.
+ *
+ * @param input - Base64url string
+ */
+export function b64urlDecode(input: string): Uint8Array<ArrayBuffer> {
+  const pad = "=".repeat((4 - (input.length % 4)) % 4);
+  const b64 = (input + pad).replace(/-/g, "+").replace(/_/g, "/");
+  const bin = atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+/**
+ * Build minimal authenticatorData (rpIdHash · flags · signCount).
+ *
+ * @param rpId - Relying party id
+ * @param signCount - Counter
+ * @param flags - Flag byte (default UP=0x01)
+ */
+export async function buildAuthenticatorData(
+  rpId: string,
+  signCount: number,
+  flags = 0x01,
+): Promise<Uint8Array> {
+  const rpHash = new Uint8Array(
+    await crypto.subtle.digest("SHA-256", new TextEncoder().encode(rpId)),
+  );
+  const out = new Uint8Array(37);
+  out.set(rpHash, 0);
+  out[32] = flags;
+  out[33] = (signCount >>> 24) & 0xff;
+  out[34] = (signCount >>> 16) & 0xff;
+  out[35] = (signCount >>> 8) & 0xff;
+  out[36] = signCount & 0xff;
+  return out;
+}
+
+/**
+ * Sign `authenticatorData || SHA-256(clientDataJSON)` with an ECDSA P-256 key.
+ *
+ * @param privateKey - Signer
+ * @param authenticatorData - Auth data bytes
+ * @param clientDataJSON - Raw clientDataJSON bytes
+ */
+export async function signWebAuthnAssertion(
+  privateKey: CryptoKey,
+  authenticatorData: Uint8Array,
+  clientDataJSON: Uint8Array,
+): Promise<Uint8Array> {
+  const clientDataHash = new Uint8Array(
+    await crypto.subtle.digest("SHA-256", asBufferSource(clientDataJSON)),
+  );
+  const signed = new Uint8Array(authenticatorData.length + clientDataHash.length);
+  signed.set(authenticatorData, 0);
+  signed.set(clientDataHash, authenticatorData.length);
+  return new Uint8Array(
+    await crypto.subtle.sign(
+      { name: "ECDSA", hash: "SHA-256" },
+      privateKey,
+      asBufferSource(signed),
+    ),
+  );
+}
+
+/** Fresh buffer for Web Crypto `BufferSource` typing. */
+function asBufferSource(bytes: Uint8Array): Uint8Array<ArrayBuffer> {
+  return new Uint8Array(bytes);
+}