okengine 0.3.6 → 0.5.0

package/src/kernel/registry.ts

@@ -12,9 +12,16 @@
  * @see docs/spec/console.md §9.15
  */
 
-import type { FlowErrorMap } from "./flow.ts";
+import type { ChannelTemplateDecl } from "../elements/channel/declare.ts";
+import type { ClockDecl } from "../elements/clock/declare.ts";
+import type { GateDecl } from "../elements/gate/declare.ts";
+import type { SignalDecl } from "../elements/signal/declare.ts";
+import type { VaultSecretDecl } from "../elements/vault/declare.ts";
+import type { SchemaInput } from "../validation/standard-schema.ts";
+import type { AnyFlowDef, FlowErrorMap } from "./flow.ts";
 import type { HookFn, HookMap, HookStage } from "./hooks.ts";
 import { tagHookWithPlugin } from "./hook-timing.ts";
+import type { Binding } from "./on.ts";
 import type {
   CliContribution,
   ClientExtensionContribution,
@@ -30,8 +37,6 @@ import type {
   PluginTableOptions,
   TableContribution,
 } from "./plugin.ts";
-import type { SchemaInput } from "../validation/standard-schema.ts";
-import type { AnyFlowDef } from "./flow.ts";
 
 /** Attachment-point scope — the position is the scope. No escape hatch. */
 export type PluginScope =
@@ -72,8 +77,14 @@ export function createRecordingApi(identity: { readonly name: string; readonly v
   const cli: CliContribution[] = [];
   const images: ImageRecipeContribution[] = [];
   const flows: AnyFlowDef[] = [];
+  const bindings: Binding[] = [];
   const errors: FlowErrorMap = {};
   const client: ClientExtensionContribution[] = [];
+  const vaultSecrets: VaultSecretDecl[] = [];
+  const clocks: ClockDecl[] = [];
+  const signals: SignalDecl[] = [];
+  const gates: GateDecl[] = [];
+  const channelTemplates: ChannelTemplateDecl[] = [];
   const needs: string[] = [];
   const declares: string[] = [];
   const intercepts: string[] = [];
@@ -146,6 +157,13 @@ export function createRecordingApi(identity: { readonly name: string; readonly v
       pushDeclare(`table:${name}`);
       return api;
     },
+    binding(binding) {
+      bindings.push(binding);
+      flows.push(binding.flow);
+      pushDeclare(`binding:${binding.flow.name}`);
+      pushDeclare(`flow:${binding.flow.name}`);
+      return api;
+    },
     flow(flowDef) {
       flows.push(flowDef);
       pushDeclare(`flow:${flowDef.name}`);
@@ -161,6 +179,31 @@ export function createRecordingApi(identity: { readonly name: string; readonly v
       pushDeclare("config");
       return api;
     },
+    vault(secret) {
+      vaultSecrets.push(secret);
+      pushDeclare(`vault:${secret.name}`);
+      return api;
+    },
+    clock(decl) {
+      clocks.push(decl);
+      pushDeclare(`clock:${decl.name}`);
+      return api;
+    },
+    signal(decl) {
+      signals.push(decl);
+      pushDeclare(`signal:${decl.name}`);
+      return api;
+    },
+    gate(decl) {
+      gates.push(decl);
+      pushDeclare(`gate:${decl.name}`);
+      return api;
+    },
+    channelTemplate(decl) {
+      channelTemplates.push(decl);
+      pushDeclare(`channel:${decl.name}`);
+      return api;
+    },
   };
 
   return {
@@ -186,9 +229,15 @@ export function createRecordingApi(identity: { readonly name: string; readonly v
         cli: cli.slice(),
         images: images.slice(),
         flows: flows.slice(),
+        bindings: bindings.slice(),
         errors: { ...errors },
         client: client.slice(),
         configSchema,
+        vaultSecrets: vaultSecrets.slice(),
+        clocks: clocks.slice(),
+        signals: signals.slice(),
+        gates: gates.slice(),
+        channelTemplates: channelTemplates.slice(),
       };
     },
   };
@@ -259,6 +308,18 @@ export interface PluginRegistry {
    * plugin name). Used by `oke db` emit to merge plugin `field.*` tables.
    */
   tableContributions(): readonly TableContribution[];
+  /** Vault contracts from installed plugins (first install per plugin name). */
+  vaultContributions(): readonly VaultSecretDecl[];
+  /** Clock schedules from installed plugins. */
+  clockContributions(): readonly ClockDecl[];
+  /** Signal declarations from installed plugins. */
+  signalContributions(): readonly SignalDecl[];
+  /** Gate declarations from installed plugins. */
+  gateContributions(): readonly GateDecl[];
+  /** Channel templates from installed plugins. */
+  channelTemplateContributions(): readonly ChannelTemplateDecl[];
+  /** HTTP Bindings from installed plugins (auth method plugins). */
+  bindingContributions(): readonly Binding[];
 }
 
 /**
@@ -413,11 +474,49 @@ export function createPluginRegistry(): PluginRegistry {
       }
       return out;
     },
+    vaultContributions() {
+      return firstPerPlugin(installed, (r) => r.vaultSecrets);
+    },
+    clockContributions() {
+      return firstPerPlugin(installed, (r) => r.clocks);
+    },
+    signalContributions() {
+      return firstPerPlugin(installed, (r) => r.signals);
+    },
+    gateContributions() {
+      return firstPerPlugin(installed, (r) => r.gates);
+    },
+    channelTemplateContributions() {
+      return firstPerPlugin(installed, (r) => r.channelTemplates);
+    },
+    bindingContributions() {
+      return firstPerPlugin(installed, (r) => r.bindings);
+    },
   };
 
   return registry;
 }
 
+/**
+ * Collect contributions from the first install of each plugin name.
+ *
+ * @param installed - Registry installs
+ * @param pick - Selector
+ */
+function firstPerPlugin<T>(
+  installed: readonly InstalledPlugin[],
+  pick: (r: PluginRegistration) => readonly T[],
+): T[] {
+  const seenPlugins = new Set<string>();
+  const out: T[] = [];
+  for (const entry of installed) {
+    if (seenPlugins.has(entry.plugin.name)) continue;
+    seenPlugins.add(entry.plugin.name);
+    out.push(...pick(entry.registration));
+  }
+  return out;
+}
+
 /**
  * Normalize plugin `.table()` args — supports columns + options, and legacy
  * `{ plane }` as the second argument.

package/src/kernel/router.ts

@@ -1,6 +1,6 @@
 /**
- * HTTP router — compiled RegExp matching with a Trie fallback
- * (Hono's SmartRouter idea), plus a linear preset for cold-start edge builds.
+ * HTTP router — compiled RegExp matching with a Trie fallback, plus a linear
+ * preset for cold-start edge builds.
  *
  * Chosen at build/startup: try RegExp first; on unsupported patterns fall
  * back to Trie. The `edge` preset uses LinearRouter for fast registration.
@@ -141,7 +141,7 @@ function matchCompiled<T>(dyn: CompiledDynamic<T>, path: string): RouteMatch<T>
 
 /**
  * Compiled RegExp router — O(1) static map, plus per-bucket compiled
- * regular expressions for parametric routes (Hono RegExpRouter idea).
+ * regular expressions for parametric routes.
  */
 export class RegExpRouter<T> implements Router<T> {
   readonly name = "RegExpRouter";

package/src/manifest/types.ts

@@ -327,6 +327,8 @@ export interface Plugin {
   version?: string;
   declares?: string[];
   intercepts?: string[];
+  /** Declared `.needs()` dependencies (plugin names or element/driver ids). */
+  needs?: string[];
   /** Optional metadata for `table:*` contributions. */
   tables?: Record<string, PluginTable>;
 }

package/src/plugins/anonymous.ts

@@ -0,0 +1,58 @@
+/**
+ * Anonymous sign-in Gate auth method plugin.
+ */
+
+import { issueSessionWithScopes } from "../auth/sessions.ts";
+import { plugin, type PluginDef } from "../kernel/plugin.ts";
+import {
+  AuthFailed,
+  AuthRateLimited,
+  SessionTokensOut,
+  bindPublicAuth,
+  createMethodRuntime,
+  flow,
+  type AuthMethodOptions,
+} from "./auth/shared.ts";
+
+/** Options for {@link anonymous}. */
+export interface AnonymousPluginOptions extends AuthMethodOptions {
+  /**
+   * Reserved for future disposable emails (`user@domain`). Unused in v1.
+   */
+  readonly emailDomain?: string;
+}
+
+/**
+ * Issue a user-plane session with a random principal id (no password).
+ *
+ * @param opts - Secret / session overrides
+ */
+export function anonymous(opts: AnonymousPluginOptions = {}): PluginDef {
+  const runtime = createMethodRuntime(opts);
+
+  const signIn = flow({
+    name: "auth.signInAnonymous",
+    unit: "auth",
+    plane: "user",
+    out: SessionTokensOut,
+    errors: { AuthFailed, AuthRateLimited },
+    do: async () => {
+      const userId = crypto.randomUUID();
+      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("anonymous", { version: "0.0.1", config: { method: "anonymous" } })
+    .needs("auth")
+    .binding(bindPublicAuth("/sign-in/anonymous", signIn, "signIn"));
+}

package/src/plugins/auth/shared.ts

@@ -0,0 +1,121 @@
+/**
+ * Shared helpers for Gate auth method plugins.
+ */
+
+import { z } from "zod";
+import { AUTH_RATE_PRESETS, AUTH_SESSION_GATE, bindAuthHttp } from "../../auth/bindings.ts";
+import { getActiveGateAuthContext } from "../../auth/method-context.ts";
+import { createSessionStore, type SessionCrypto, type SessionStore } from "../../auth/sessions.ts";
+import { gate } from "../../elements/gate.ts";
+import type { GateDecl } from "../../elements/gate/declare.ts";
+import { fail } from "../../kernel/errors.ts";
+import { flow, type AnyFlowDef } from "../../kernel/flow.ts";
+import type { Binding } from "../../kernel/on.ts";
+import { http } from "../../kernel/triggers.ts";
+import { createEnv } from "../../runtime/primitives.ts";
+
+export const AuthFailed = z.object({ reason: z.string().optional() });
+export const AuthRateLimited = z.object({ reason: z.string() });
+
+export const SessionTokensOut = z.object({
+  accessToken: z.string(),
+  refreshToken: z.string(),
+  accessExpiresAt: z.number(),
+  userId: z.string().optional(),
+});
+
+/** Common options for auth method plugins (session issue). */
+export interface AuthMethodOptions {
+  /** HMAC secret; falls back to `OKE_AUTH_SECRET`, then a dev default. */
+  readonly secret?: string;
+  /** Shared session store (prefer the same store as `gate.auth`). */
+  readonly sessions?: SessionStore;
+  /** Injectable clock. */
+  readonly now?: () => number;
+}
+
+/**
+ * Resolve HMAC secret for method plugins.
+ *
+ * @param opts - Optional explicit secret
+ */
+export function resolveMethodSecret(opts: { readonly secret?: string } = {}): string {
+  if (opts.secret && opts.secret.length > 0) return opts.secret;
+  const active = getActiveGateAuthContext();
+  if (active?.secret) return active.secret;
+  const fromEnv = createEnv().get("OKE_AUTH_SECRET");
+  if (fromEnv && fromEnv.length > 0) return fromEnv;
+  return "oke-dev-auth-secret-change-me";
+}
+
+/**
+ * Session store + crypto closed over by a method plugin factory.
+ * Prefers explicit opts, then the active `gate.auth` context from `oke()`.
+ *
+ * @param opts - Common method options
+ */
+export function createMethodRuntime(opts: AuthMethodOptions = {}): {
+  readonly sessions: SessionStore;
+  readonly crypto: SessionCrypto;
+  now(): number;
+} {
+  const active = getActiveGateAuthContext();
+  const sessions = opts.sessions ?? active?.sessions ?? createSessionStore();
+  const now = opts.now ?? active?.now ?? (() => Date.now());
+  return {
+    sessions,
+    now,
+    crypto: {
+      secret: resolveMethodSecret(opts),
+      now,
+    },
+  };
+}
+
+/**
+ * Public + rate gate chain for credential-ish auth paths.
+ *
+ * @param kind - Preset key
+ */
+export function authPublicGates(kind: keyof typeof AUTH_RATE_PRESETS = "otp"): GateDecl[] {
+  const preset = AUTH_RATE_PRESETS[kind];
+  return [
+    gate.public,
+    gate.rate({
+      max: preset.max,
+      per: preset.per,
+      keyBy: preset.keyBy,
+      description: `Auth ${kind} rate limit`,
+    }),
+  ];
+}
+
+/**
+ * Bind a public auth Flow under `/auth/...`.
+ *
+ * @param path - Path under `/auth` (e.g. `/sign-in/username`)
+ * @param flowDef - Flow
+ * @param kind - Rate preset
+ */
+export function bindPublicAuth(
+  path: string,
+  flowDef: AnyFlowDef,
+  kind: keyof typeof AUTH_RATE_PRESETS = "otp",
+): Binding {
+  const gates = authPublicGates(kind);
+  let trigger = http.post(`/auth${path}`);
+  for (const g of gates) trigger = trigger.gate(g);
+  return bindAuthHttp(trigger, flowDef);
+}
+
+/**
+ * Bind a session-gated auth Flow under `/auth/...`.
+ *
+ * @param path - Path under `/auth`
+ * @param flowDef - Flow
+ */
+export function bindSessionAuth(path: string, flowDef: AnyFlowDef): Binding {
+  return bindAuthHttp(http.post(`/auth${path}`).gate(AUTH_SESSION_GATE), flowDef);
+}
+
+export { AUTH_SESSION_GATE, fail, flow, http, z };

package/src/plugins/auth-methods.test.ts

@@ -0,0 +1,176 @@
+/**
+ * Phase 2 Gate auth method plugins — username, anonymous, magic-link, email OTP.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { oke } from "../kernel/app.ts";
+import { resetFlowSeq } from "../kernel/flow.ts";
+import { resetBindings } from "../kernel/on.ts";
+import { anonymous } from "./anonymous.ts";
+import { emailOtp } from "./email-otp.ts";
+import { magicLink } from "./magic-link.ts";
+import { username } from "./username.ts";
+
+afterEach(() => {
+  resetBindings();
+  resetFlowSeq();
+});
+
+function authApp() {
+  return oke({
+    name: "auth-plugins",
+    env: "test",
+    registry: "ignore",
+    gate: {
+      auth: {
+        secret: "test-secret-at-least-16",
+        emailAndPassword: { enabled: true },
+      },
+    },
+  })
+    .plug(username())
+    .plug(anonymous())
+    .plug(magicLink({ exposeDevToken: true }))
+    .plug(emailOtp({ exposeDevOtp: true }));
+}
+
+describe("auth method plugins", () => {
+  test("bindings appear on router after .plug()", async () => {
+    const app = authApp();
+    expect(app.router.match("POST", "/auth/sign-up/username")).toBeTruthy();
+    expect(app.router.match("POST", "/auth/sign-in/username")).toBeTruthy();
+    expect(app.router.match("POST", "/auth/sign-in/anonymous")).toBeTruthy();
+    expect(app.router.match("POST", "/auth/magic-link/request")).toBeTruthy();
+    expect(app.router.match("POST", "/auth/magic-link/verify")).toBeTruthy();
+    expect(app.router.match("POST", "/auth/email-otp/request")).toBeTruthy();
+    expect(app.router.match("POST", "/auth/email-otp/verify")).toBeTruthy();
+    await app.boot({ env: "test" });
+    await app.stop();
+  });
+
+  test("username sign-up + sign-in", async () => {
+    const app = authApp();
+    await app.boot({ env: "test" });
+
+    const signUp = await app.fetch(
+      new Request("http://localhost/auth/sign-up/username", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ username: "alice", password: "CorrectHorse1" }),
+      }),
+    );
+    expect(signUp.status).toBe(200);
+    const created = (await signUp.json()) as {
+      data: { accessToken: string; userId: string };
+    };
+    expect(created.data.accessToken).toBeTruthy();
+    expect(created.data.userId).toBeTruthy();
+
+    const bad = await app.fetch(
+      new Request("http://localhost/auth/sign-in/username", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ username: "alice", password: "wrong-password" }),
+      }),
+    );
+    const badBody = (await bad.json()) as { error: { data?: { reason?: string } } };
+    expect(badBody.error.data?.reason).toBe("invalid_credentials");
+
+    const signIn = await app.fetch(
+      new Request("http://localhost/auth/sign-in/username", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ username: "alice", password: "CorrectHorse1" }),
+      }),
+    );
+    expect(signIn.status).toBe(200);
+    const session = (await signIn.json()) as { data: { accessToken: string } };
+    expect(session.data.accessToken).toBeTruthy();
+
+    await app.stop();
+  });
+
+  test("anonymous sign-in issues session", async () => {
+    const app = authApp();
+    await app.boot({ env: "test" });
+
+    const res = await app.fetch(
+      new Request("http://localhost/auth/sign-in/anonymous", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: "{}",
+      }),
+    );
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as {
+      data: { accessToken: string; userId: string };
+    };
+    expect(body.data.accessToken).toBeTruthy();
+    expect(body.data.userId).toBeTruthy();
+
+    await app.stop();
+  });
+
+  test("magic-link request + verify with devToken", async () => {
+    const app = authApp();
+    await app.boot({ env: "test" });
+
+    const req = await app.fetch(
+      new Request("http://localhost/auth/magic-link/request", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ email: "ml@example.com" }),
+      }),
+    );
+    expect(req.status).toBe(200);
+    const requested = (await req.json()) as { data: { ok: true; devToken?: string } };
+    expect(requested.data.ok).toBe(true);
+    expect(requested.data.devToken).toBeTruthy();
+
+    const verify = await app.fetch(
+      new Request("http://localhost/auth/magic-link/verify", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ token: requested.data.devToken }),
+      }),
+    );
+    expect(verify.status).toBe(200);
+    const session = (await verify.json()) as { data: { accessToken: string; userId: string } };
+    expect(session.data.accessToken).toBeTruthy();
+    expect(session.data.userId).toBeTruthy();
+
+    await app.stop();
+  });
+
+  test("email OTP request + verify with devOtp", async () => {
+    const app = authApp();
+    await app.boot({ env: "test" });
+
+    const req = await app.fetch(
+      new Request("http://localhost/auth/email-otp/request", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ email: "otp@example.com" }),
+      }),
+    );
+    expect(req.status).toBe(200);
+    const requested = (await req.json()) as { data: { ok: true; devOtp?: string } };
+    expect(requested.data.devOtp).toMatch(/^\d{6}$/);
+
+    const verify = await app.fetch(
+      new Request("http://localhost/auth/email-otp/verify", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({
+          email: "otp@example.com",
+          otp: requested.data.devOtp,
+        }),
+      }),
+    );
+    expect(verify.status).toBe(200);
+    const session = (await verify.json()) as { data: { accessToken: string } };
+    expect(session.data.accessToken).toBeTruthy();
+
+    await app.stop();
+  });
+});

package/src/plugins/compression.test.ts

@@ -38,7 +38,7 @@ describe("acceptsGzip", () => {
 describe("compression plugin", () => {
   test("gzips a large JSON body when the client accepts gzip", async () => {
     on(http.get("/big"), flow({ name: "big.get", do: bigPayload }));
-    const app = oke({ name: "zip" }).plug(compression());
+    const app = oke({ autoBoot: false, name: "zip" }).plug(compression());
 
     const res = await app.fetch(
       new Request("http://localhost/big", { headers: { "accept-encoding": "gzip" } }),
@@ -59,7 +59,7 @@ describe("compression plugin", () => {
 
   test("passes through untouched without Accept-Encoding: gzip", async () => {
     on(http.get("/big"), flow({ name: "big.get", do: bigPayload }));
-    const app = oke({ name: "zip-plain" }).plug(compression());
+    const app = oke({ autoBoot: false, name: "zip-plain" }).plug(compression());
 
     const res = await app.fetch(new Request("http://localhost/big"));
 
@@ -70,7 +70,7 @@ describe("compression plugin", () => {
 
   test("skips bodies under minSize", async () => {
     on(http.get("/small"), flow({ name: "small.get", do: () => ({ ok: true }) }));
-    const app = oke({ name: "zip-small" }).plug(compression());
+    const app = oke({ autoBoot: false, name: "zip-small" }).plug(compression());
 
     const res = await app.fetch(
       new Request("http://localhost/small", { headers: { "accept-encoding": "gzip" } }),
@@ -81,7 +81,7 @@ describe("compression plugin", () => {
 
   test("minSize: 0 compresses even tiny bodies", async () => {
     on(http.get("/small"), flow({ name: "small.get", do: () => ({ ok: true }) }));
-    const app = oke({ name: "zip-zero" }).plug(compression({ minSize: 0 }));
+    const app = oke({ autoBoot: false, name: "zip-zero" }).plug(compression({ minSize: 0 }));
 
     const res = await app.fetch(
       new Request("http://localhost/small", { headers: { "accept-encoding": "gzip" } }),
@@ -112,7 +112,7 @@ describe("compression plugin", () => {
           ),
       }),
     );
-    const app = oke({ name: "zip-skip" }).plug(compression());
+    const app = oke({ autoBoot: false, name: "zip-skip" }).plug(compression());
 
     const img = await app.fetch(
       new Request("http://localhost/img", { headers: { "accept-encoding": "gzip" } }),

package/src/plugins/config-source.test.ts

@@ -156,7 +156,7 @@ describe("configSource — plugin wiring", () => {
     });
 
     on(http.get("/x"), flow({ name: "x.get", do: () => ({ ok: true }) }));
-    const app = oke({ name: "cfg-live" }).plug(maintenanceMode(source));
+    const app = oke({ autoBoot: false, name: "cfg-live" }).plug(maintenanceMode(source));
 
     expect((await app.fetch(new Request("http://localhost/x"))).status).toBe(200);