okengine 0.18.5 → 0.19.0

package/src/plugins/config-source.ts

@@ -59,7 +59,7 @@ export interface ConfigSourceOptions<T extends object> {
 /**
  * A live config box for one plugin. `current()` is synchronous and never
  * throws — safe to read from any hook. `sync()` is the refresh flow the
- * app binds once: `on(every("30s"), source.sync())`.
+ * app binds once: `on(syncClock, source.sync())`.
  */
 export interface ConfigSource<T extends object> {
   readonly [configSourceBrand]: true;

package/src/plugins/csrf.test.ts

@@ -117,3 +117,68 @@ describe("csrf plugin", () => {
     expect(res.status).toBe(200);
   });
 });
+
+describe("csrf soft-require when cookies enabled", () => {
+  test("prod boots refuse without csrf plugin", async () => {
+    const app = oke({
+      autoBoot: false,
+      name: `csrf-cookie-${crypto.randomUUID()}`,
+      env: "prod",
+      registry: "ignore",
+      gate: {
+        auth: {
+          secret: "test-secret-at-least-32-characters!!",
+          cookies: { enabled: true },
+          http: false,
+        },
+      },
+    });
+    await expect(app.boot()).rejects.toThrow(/csrf plugin/);
+  });
+
+  test("test/dev boots warn without csrf plugin", async () => {
+    const warnings: string[] = [];
+    const prev = console.warn;
+    console.warn = (...args: unknown[]) => {
+      warnings.push(args.map(String).join(" "));
+    };
+    try {
+      const app = oke({
+        autoBoot: false,
+        name: `csrf-cookie-dev-${crypto.randomUUID()}`,
+        env: "test",
+        registry: "ignore",
+        gate: {
+          auth: {
+            secret: "test-secret-at-least-32-characters!!",
+            cookies: { enabled: true },
+            http: false,
+          },
+        },
+      });
+      await app.boot({ env: "test" });
+      expect(warnings.some((w) => w.includes("csrf"))).toBe(true);
+      await app.stop();
+    } finally {
+      console.warn = prev;
+    }
+  });
+
+  test("boots with csrf plugin when cookies enabled", async () => {
+    const app = oke({
+      autoBoot: false,
+      name: `csrf-cookie-ok-${crypto.randomUUID()}`,
+      env: "test",
+      registry: "ignore",
+      gate: {
+        auth: {
+          secret: "test-secret-at-least-32-characters!!",
+          cookies: { enabled: true },
+          http: false,
+        },
+      },
+    }).plug(csrf({ allowNoHeader: false }));
+    await app.boot({ env: "test" });
+    await app.stop();
+  });
+});

package/src/plugins/index.ts

@@ -15,6 +15,7 @@ export {
   type ConfigSourceOptions,
 } from "./config-source.ts";
 export { cors, type CorsOptions } from "./cors.ts";
+export { csrf, type CsrfOptions } from "./csrf.ts";
 export { ipAllowlist, type IpAllowlistOptions } from "./ip-allowlist.ts";
 export {
   magicLink,
@@ -67,6 +68,7 @@ export {
   type TwoFactorRow,
   type TwoFactorStore,
 } from "./two-factor.ts";
+export type { TwoFactorMethod } from "../auth/two-factor-challenge.ts";
 export {
   assertUsernamePolicy,
   createUsernameStore,

package/src/plugins/magic-link.ts

@@ -6,7 +6,13 @@
  * local DX without Mailpit / SMTP.
  */
 
-import { linkOrProvision, normalizeEmail, type IdentityStore } from "../auth/identity.ts";
+import {
+  completeVerifiedEmailSignIn,
+  IdentityError,
+  normalizeEmail,
+  type IdentityStore,
+  type UserIdentityRow,
+} from "../auth/identity.ts";
 import { issueSessionWithScopes } from "../auth/sessions.ts";
 import {
   createVerificationStore,
@@ -28,6 +34,7 @@ import {
   z,
   type AuthMethodOptions,
 } from "./auth/shared.ts";
+import { okid } from "../okid.ts";
 
 const DEFAULT_TTL_MS = 10 * 60 * 1000;
 const DEFAULT_FROM = "OKE <no-reply@oke.local>";
@@ -103,22 +110,25 @@ export function magicLink(opts: MagicLinkOptions = {}): PluginDef {
         })
       : magicLinkTemplate;
 
-  const request = flow("auth.requestMagicLink", {
-    plane: "user",
+  const requestContract = {
     in: z.object({ email: z.string().min(3) }),
     out: z.object({
       ok: z.literal(true),
       devToken: z.string().optional(),
     }),
     errors: { AuthFailed, AuthRateLimited },
+  };
+
+  const request = flow("auth.requestMagicLink", {
+    plane: "user",
     effects: { sends: ["auth-magic-link"] },
     do: async (input, fx) => {
       const email = normalizeEmail(input.email);
       if (!email.includes("@")) return fail("AuthFailed", { reason: "invalid_email" });
-      const token = `ml_${crypto.randomUUID().replace(/-/g, "")}`;
+      const token = `ml_${okid()}`;
       const now = runtime.now();
       putVerification(verifications, {
-        id: crypto.randomUUID(),
+        id: okid(),
         identifier: `magic:${email}`,
         value: await hashChallenge(token),
         expiresAt: now + ttlMs,
@@ -138,11 +148,14 @@ export function magicLink(opts: MagicLinkOptions = {}): PluginDef {
     },
   });
 
-  const verify = flow("auth.verifyMagicLink", {
-    plane: "user",
+  const verifyContract = {
     in: z.object({ token: z.string().min(1) }),
     out: SessionTokensOut,
     errors: { AuthFailed, AuthRateLimited },
+  };
+
+  const verify = flow("auth.verifyMagicLink", {
+    plane: "user",
     do: async (input) => {
       const hash = await hashChallenge(input.token);
       const now = runtime.now();
@@ -168,13 +181,20 @@ export function magicLink(opts: MagicLinkOptions = {}): PluginDef {
       if (!row) return fail("AuthFailed", { reason: "invalid_credentials" });
       row.consumedAt = now;
       const email = row.identifier.slice("magic:".length);
-      const { user } = await linkOrProvision(identities, {
-        provider: "magic-link",
-        providerAccountId: email,
-        email,
-        emailVerified: true,
-        now: () => now,
-      });
+      let user: UserIdentityRow;
+      try {
+        ({ user } = await completeVerifiedEmailSignIn(identities, runtime.sessions, {
+          provider: "magic-link",
+          providerAccountId: email,
+          email,
+          now: () => now,
+        }));
+      } catch (err) {
+        if (err instanceof IdentityError) {
+          return fail("AuthFailed", { reason: "invalid_credentials" });
+        }
+        throw err;
+      }
       const issued = await issueSessionWithScopes(runtime.sessions, runtime.crypto, {
         id: user.id,
         plane: "user",
@@ -194,6 +214,6 @@ export function magicLink(opts: MagicLinkOptions = {}): PluginDef {
     .needs("channel")
     .channelTemplate(tmpl)
     .channelCatalog(magicLinkCatalog)
-    .binding(bindPublicAuth("/magic-link/request", request, "otp"))
-    .binding(bindPublicAuth("/magic-link/verify", verify, "otp"));
+    .binding(bindPublicAuth("/magic-link/request", request, "otp", requestContract))
+    .binding(bindPublicAuth("/magic-link/verify", verify, "otp", verifyContract));
 }

package/src/plugins/oauth/shared.ts

@@ -7,6 +7,7 @@ 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 { BoundaryContract } from "../../kernel/boundary-contract.ts";
 import type { AnyFlowDef } from "../../kernel/flow.ts";
 import { bindAuthHttp } from "../../auth/bindings.ts";
 import { http } from "../auth/shared.ts";
@@ -97,10 +98,11 @@ export function bindPublicAuthGet(
   path: string,
   flowDef: AnyFlowDef,
   gates: readonly Parameters<ReturnType<typeof http.get>["gate"]>[0][] = [],
+  contract?: BoundaryContract,
 ): Binding {
   return bindAuthHttp(
     http
-      .get(path)
+      .get(path, contract)
       .public()
       .gate(...gates),
     flowDef,

package/src/plugins/oauth.ts

@@ -30,6 +30,7 @@ import {
 import { bindAuthHttp } from "../auth/bindings.ts";
 import { hashChallenge } from "../auth/verification.ts";
 import { issueSessionWithScopes } from "../auth/sessions.ts";
+import type { BoundaryContract } from "../kernel/boundary-contract.ts";
 import type { Binding } from "../kernel/on.ts";
 import type { Fx } from "../kernel/fx.ts";
 import type { AnyFlowDef } from "../kernel/flow.ts";
@@ -117,12 +118,14 @@ export function oauth(options: OAuthOptions = {}) {
   const now: () => number = () => runtime.now();
   const providers = buildProviders(options);
 
-  const start = flow("auth.oauthStart", {
-    plane: "user",
+  const startContract = {
     in: StartIn,
     out: StartOut,
     errors: { AuthFailed, AuthRateLimited },
-    effects: {},
+  };
+
+  const start = flow("auth.oauthStart", {
+    plane: "user",
     do: async (input) => {
       const p = providers.find((c) => c.id === input.provider);
       if (!p) return fail("AuthFailed", { reason: "provider_disabled" });
@@ -162,11 +165,14 @@ export function oauth(options: OAuthOptions = {}) {
     },
   });
 
-  const callback = flow("auth.oauthCallback", {
-    plane: "user",
+  const callbackContract = {
     in: CallbackIn,
     out: SessionTokensOut,
     errors: { AuthFailed, AuthRateLimited },
+  };
+
+  const callback = flow("auth.oauthCallback", {
+    plane: "user",
     effects: { secrets: callbackSecretRefs(providers) },
     do: async (input, fx) => {
       if (typeof input.error === "string" && input.error.length > 0) {
@@ -257,12 +263,14 @@ export function oauth(options: OAuthOptions = {}) {
     },
   });
 
-  const linkStart = flow("auth.oauthLinkStart", {
-    plane: "user",
+  const linkStartContract = {
     in: StartIn,
     out: StartOut,
     errors: { AuthFailed, AuthRateLimited },
-    effects: {},
+  };
+
+  const linkStart = flow("auth.oauthLinkStart", {
+    plane: "user",
     do: async (input, fx) => {
       const currentUserId = fx.auth.userId;
       if (!currentUserId) return fail("AuthFailed", { reason: "unauthenticated" });
@@ -314,9 +322,9 @@ export function oauth(options: OAuthOptions = {}) {
     .flow(callback)
     .flow(linkStart);
 
-  def.binding(bindPublicAuth("/oauth/:provider/start", start, "otp"));
-  for (const b of bindCallbackBothMethods(callback)) def.binding(b);
-  def.binding(bindSessionAuth("/oauth/:provider/link", linkStart));
+  def.binding(bindPublicAuth("/oauth/:provider/start", start, "otp", startContract));
+  for (const b of bindCallbackBothMethods(callback, callbackContract)) def.binding(b);
+  def.binding(bindSessionAuth("/oauth/:provider/link", linkStart, linkStartContract));
 
   for (const contract of vaultContracts(providers)) def.vault(contract);
 
@@ -335,12 +343,12 @@ const OAUTH_FLOW_TTL_MS = 10 * 60_000;
  *
  * @param flowDef - Callback flow
  */
-function bindCallbackBothMethods(flowDef: AnyFlowDef): Binding[] {
+function bindCallbackBothMethods(flowDef: AnyFlowDef, contract: BoundaryContract): Binding[] {
   const gates = authPublicGates("otp");
-  const getBinding = bindPublicAuthGet("/auth/oauth/callback/:provider", flowDef, gates);
+  const getBinding = bindPublicAuthGet("/auth/oauth/callback/:provider", flowDef, gates, contract);
   const postBinding = bindAuthHttp(
     http
-      .post("/auth/oauth/callback/:provider")
+      .post("/auth/oauth/callback/:provider", contract)
       .public()
       .gate(...gates),
     flowDef,

package/src/plugins/otp.ts

@@ -5,6 +5,7 @@
 
 import { constantTimeEqual } from "../auth/constant-time.ts";
 import {
+  completeVerifiedEmailSignIn,
   IdentityError,
   linkOrProvision,
   normalizeEmail,
@@ -40,6 +41,7 @@ import {
   z,
   type AuthMethodOptions,
 } from "./auth/shared.ts";
+import { okid } from "../okid.ts";
 
 const E164 = /^\+[1-9]\d{7,14}$/;
 const DEFAULT_TTL_MS = 10 * 60 * 1000;
@@ -238,14 +240,17 @@ export function otp(opts: OtpOptions): PluginDef {
   });
 
   if (opts.mode === "provider") {
-    const request = flow("auth.requestOtp", {
-      plane: "user",
+    const requestContract = {
       in: z.object({
         phone: z.string().min(8),
         lang: z.enum(["en", "ar"]).optional(),
       }),
       out: requestOut,
       errors: { AuthFailed, AuthRateLimited },
+    };
+
+    const request = flow("auth.requestOtp", {
+      plane: "user",
       effects: { sends: ["sms-otp"] },
       do: async (input, fx) => {
         const phone = input.phone.trim();
@@ -254,7 +259,7 @@ export function otp(opts: OtpOptions): PluginDef {
         const identifier = `otp:${phone}`;
         invalidateVerifications(verifications, identifier, now);
 
-        const requestId = crypto.randomUUID();
+        const requestId = okid();
         await fx.sendOtp({
           to: phone,
           requestId,
@@ -262,7 +267,7 @@ export function otp(opts: OtpOptions): PluginDef {
         });
 
         putVerification(verifications, {
-          id: crypto.randomUUID(),
+          id: okid(),
           identifier,
           value: `provider:${requestId}`,
           expiresAt: now + ttlMs,
@@ -277,8 +282,7 @@ export function otp(opts: OtpOptions): PluginDef {
       },
     });
 
-    const verify = flow("auth.verifyOtp", {
-      plane: "user",
+    const verifyContract = {
       in: z.object({
         phone: z.string().min(8),
         otp: z.string().min(4).max(8),
@@ -286,6 +290,10 @@ export function otp(opts: OtpOptions): PluginDef {
       }),
       out: SessionTokensOut,
       errors: { AuthFailed, AuthRateLimited },
+    };
+
+    const verify = flow("auth.verifyOtp", {
+      plane: "user",
       effects: { sends: ["sms-otp"] },
       do: async (input, fx) => {
         const phone = input.phone.trim();
@@ -352,13 +360,12 @@ export function otp(opts: OtpOptions): PluginDef {
 
     return plugin("otp", { version: "0.0.1", config: configSnapshot })
       .needs("auth")
-      .binding(bindPublicAuth("/otp/request", request, "otp"))
-      .binding(bindPublicAuth("/otp/verify", verify, "otp"));
+      .binding(bindPublicAuth("/otp/request", request, "otp", requestContract))
+      .binding(bindPublicAuth("/otp/verify", verify, "otp", verifyContract));
   }
 
   // ── App mode ───────────────────────────────────────────────────────────
-  const request = flow("auth.requestOtp", {
-    plane: "user",
+  const requestContract = {
     in: z.object({
       email: z.string().min(3).optional(),
       phone: z.string().min(8).optional(),
@@ -367,6 +374,10 @@ export function otp(opts: OtpOptions): PluginDef {
     }),
     out: requestOut,
     errors: { AuthFailed, AuthRateLimited },
+  };
+
+  const request = flow("auth.requestOtp", {
+    plane: "user",
     effects: { sends: ["auth-otp", "auth-otp-email", "auth-otp-sms", "auth-otp-whatsapp"] },
     do: async (input, fx) => {
       const email = input.email ? normalizeEmail(input.email) : undefined;
@@ -392,7 +403,7 @@ export function otp(opts: OtpOptions): PluginDef {
 
       const sealed = await sealOtp(secret, otpCode);
       putVerification(verifications, {
-        id: crypto.randomUUID(),
+        id: okid(),
         identifier,
         value: await hashChallenge(otpCode),
         expiresAt: now + ttlMs,
@@ -423,8 +434,7 @@ export function otp(opts: OtpOptions): PluginDef {
     },
   });
 
-  const resend = flow("auth.resendOtp", {
-    plane: "user",
+  const resendContract = {
     in: z.object({
       email: z.string().min(3).optional(),
       phone: z.string().min(8).optional(),
@@ -433,6 +443,10 @@ export function otp(opts: OtpOptions): PluginDef {
     }),
     out: requestOut,
     errors: { AuthFailed, AuthRateLimited },
+  };
+
+  const resend = flow("auth.resendOtp", {
+    plane: "user",
     effects: { sends: ["auth-otp", "auth-otp-email", "auth-otp-sms", "auth-otp-whatsapp"] },
     do: async (input, fx) => {
       const email = input.email ? normalizeEmail(input.email) : undefined;
@@ -492,8 +506,7 @@ export function otp(opts: OtpOptions): PluginDef {
     },
   });
 
-  const verify = flow("auth.verifyOtp", {
-    plane: "user",
+  const verifyContract = {
     in: z.object({
       email: z.string().min(3).optional(),
       phone: z.string().min(8).optional(),
@@ -501,6 +514,10 @@ export function otp(opts: OtpOptions): PluginDef {
     }),
     out: SessionTokensOut,
     errors: { AuthFailed, AuthRateLimited },
+  };
+
+  const verify = flow("auth.verifyOtp", {
+    plane: "user",
     do: async (input) => {
       const email = input.email ? normalizeEmail(input.email) : undefined;
       const phone = input.phone?.trim();
@@ -563,11 +580,10 @@ export function otp(opts: OtpOptions): PluginDef {
       let user: UserIdentityRow;
       try {
         user = (
-          await linkOrProvision(identities, {
+          await completeVerifiedEmailSignIn(identities, runtime.sessions, {
             provider: "otp",
             providerAccountId: email!,
-            email,
-            emailVerified: true,
+            email: email!,
             now: () => now,
           })
         ).user;
@@ -598,7 +614,7 @@ export function otp(opts: OtpOptions): PluginDef {
     .channelTemplate(otpSmsTemplate)
     .channelTemplate(otpWhatsappTemplate)
     .channelCatalog(otpCatalog)
-    .binding(bindPublicAuth("/otp/request", request, "otp"))
-    .binding(bindPublicAuth("/otp/verify", verify, "otp"))
-    .binding(bindPublicAuth("/otp/resend", resend, "otp"));
+    .binding(bindPublicAuth("/otp/request", request, "otp", requestContract))
+    .binding(bindPublicAuth("/otp/verify", verify, "otp", verifyContract))
+    .binding(bindPublicAuth("/otp/resend", resend, "otp", resendContract));
 }

package/src/plugins/passkey-webauthn.ts

@@ -2,7 +2,7 @@
  * Minimal WebAuthn assertion / registration verifier (ES256 / P-256).
  *
  * Validates clientDataJSON (type · challenge · origin), authenticatorData
- * (rpId hash · user-presence), and ECDSA signature over
+ * (rpId hash · user-presence · user-verified), and ECDSA signature over
  * `authenticatorData || SHA-256(clientDataJSON)` against a stored SPKI public key.
  */
 
@@ -92,14 +92,17 @@ export async function verifyWebAuthnCeremony(
   const flags = authData[32]!;
   // User Present (bit 0) required.
   if ((flags & 0x01) === 0) return { ok: false, reason: "invalid_credentials" };
+  // User Verified (bit 2) required — never accept UV=false (even if RP policy is "preferred").
+  if ((flags & 0x04) === 0) return { ok: false, reason: "user_not_verified" };
 
   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" };
+    // Stored counter non-zero + non-increasing → possible cloned / replayed authenticator.
+    // Skip when stored is 0 (synced / non-counter authenticators).
+    if (opts.previousSignCount !== 0 && signCount <= opts.previousSignCount) {
+      return { ok: false, reason: "cloned_authenticator" };
     }
   }
 
@@ -164,12 +167,12 @@ export function b64urlDecode(input: string): Uint8Array<ArrayBuffer> {
  *
  * @param rpId - Relying party id
  * @param signCount - Counter
- * @param flags - Flag byte (default UP=0x01)
+ * @param flags - Flag byte (default UP|UV = 0x05)
  */
 export async function buildAuthenticatorData(
   rpId: string,
   signCount: number,
-  flags = 0x01,
+  flags = 0x05,
 ): Promise<Uint8Array> {
   const rpHash = new Uint8Array(
     await crypto.subtle.digest("SHA-256", new TextEncoder().encode(rpId)),