okengine 0.4.3 → 0.5.0

package/src/kernel/plugin.ts

@@ -14,8 +14,14 @@
  * @see docs/spec/console.md §9.15
  */
 
+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 { Binding } from "./on.ts";
 import type { HookFn, HookStage } from "./hooks.ts";
 
 /** Brand carrying accumulated decoration types through the builder. */
@@ -226,6 +232,13 @@ export interface PluginApi {
     columns?: Readonly<Record<string, unknown>>,
     options?: PluginTableOptions,
   ): PluginApi;
+  /**
+   * Contribute an HTTP (or other) Binding into the app router + adopted set.
+   * Required for auth method plugins — registry `flows[]` alone does not route.
+   *
+   * @param binding - Trigger + flow pair
+   */
+  binding(binding: Binding): PluginApi;
   /**
    * Contribute a flow.
    *
@@ -245,6 +258,36 @@ export interface PluginApi {
    * @param schema - Standard Schema
    */
   config(schema: SchemaInput): PluginApi;
+  /**
+   * Contribute a vault secret/config contract (merged into boot secrets).
+   *
+   * @param secret - Vault contract from `vault.secret(...)` / `vault.config(...)`
+   */
+  vault(secret: VaultSecretDecl): PluginApi;
+  /**
+   * Contribute a named clock schedule (merged into boot clocks).
+   *
+   * @param decl - Clock from `clock(...)`
+   */
+  clock(decl: ClockDecl): PluginApi;
+  /**
+   * Contribute a signal declaration (merged into boot signals).
+   *
+   * @param decl - Signal from `signal(...)`
+   */
+  signal(decl: SignalDecl): PluginApi;
+  /**
+   * Contribute a gate declaration (merged into boot gates).
+   *
+   * @param decl - Gate from `gate.policy` / `gate.scope` / `gate.rate` / `gate.public`
+   */
+  gate(decl: GateDecl): PluginApi;
+  /**
+   * Contribute a channel template (merged into boot channel templates).
+   *
+   * @param decl - Template from `channel.email.template(...)` etc.
+   */
+  channelTemplate(decl: ChannelTemplateDecl): PluginApi;
 }
 
 /** Captured capability lists for the Manifest. */
@@ -276,9 +319,15 @@ export interface PluginRegistration {
   readonly cli: readonly CliContribution[];
   readonly images: readonly ImageRecipeContribution[];
   readonly flows: readonly AnyFlowDef[];
+  readonly bindings: readonly Binding[];
   readonly errors: FlowErrorMap;
   readonly client: readonly ClientExtensionContribution[];
   readonly configSchema: SchemaInput | undefined;
+  readonly vaultSecrets: readonly VaultSecretDecl[];
+  readonly clocks: readonly ClockDecl[];
+  readonly signals: readonly SignalDecl[];
+  readonly gates: readonly GateDecl[];
+  readonly channelTemplates: readonly ChannelTemplateDecl[];
 }
 
 /**
@@ -383,6 +432,12 @@ export interface PluginDef<D extends Record<string, unknown> = {}> {
     columns?: Readonly<Record<string, unknown>>,
     options?: PluginTableOptions,
   ): PluginDef<D>;
+  /**
+   * Queue a Binding contribution (joins router + adopted on app.plug).
+   *
+   * @param binding - Trigger + flow
+   */
+  binding(binding: Binding): PluginDef<D>;
   /**
    * Queue a flow contribution.
    *
@@ -402,6 +457,16 @@ export interface PluginDef<D extends Record<string, unknown> = {}> {
    * @param schema - Standard Schema
    */
   config(schema: SchemaInput): PluginDef<D>;
+  /** Queue a vault secret/config contract. */
+  vault(secret: VaultSecretDecl): PluginDef<D>;
+  /** Queue a clock schedule. */
+  clock(decl: ClockDecl): PluginDef<D>;
+  /** Queue a signal declaration. */
+  signal(decl: SignalDecl): PluginDef<D>;
+  /** Queue a gate declaration. */
+  gate(decl: GateDecl): PluginDef<D>;
+  /** Queue a channel template. */
+  channelTemplate(decl: ChannelTemplateDecl): PluginDef<D>;
 }
 
 /** Extract accumulated decoration types from a {@link PluginDef}. */
@@ -505,6 +570,12 @@ export function plugin(name: string, options: PluginOptions): PluginDef {
       });
       return def;
     },
+    binding(binding) {
+      steps.push((api) => {
+        api.binding(binding);
+      });
+      return def;
+    },
     flow(flowDef) {
       steps.push((api) => {
         api.flow(flowDef);
@@ -523,6 +594,36 @@ export function plugin(name: string, options: PluginOptions): PluginDef {
       });
       return def;
     },
+    vault(secret) {
+      steps.push((api) => {
+        api.vault(secret);
+      });
+      return def;
+    },
+    clock(decl) {
+      steps.push((api) => {
+        api.clock(decl);
+      });
+      return def;
+    },
+    signal(decl) {
+      steps.push((api) => {
+        api.signal(decl);
+      });
+      return def;
+    },
+    gate(decl) {
+      steps.push((api) => {
+        api.gate(decl);
+      });
+      return def;
+    },
+    channelTemplate(decl) {
+      steps.push((api) => {
+        api.channelTemplate(decl);
+      });
+      return def;
+    },
   };
 
   return def;

package/src/kernel/registry-isolation.test.ts

@@ -22,11 +22,11 @@ afterEach(() => {
 describe("registry isolation", () => {
   test("consume (default): App B does not serve App A routes", async () => {
     on(http.get("/a"), flow({ name: "app-a.ping", do: () => "a" }));
-    const appA = oke({ name: "app-a" });
+    const appA = oke({ autoBoot: false, name: "app-a" });
 
     // No resetBindings() between the apps — the pre-fix leak scenario.
     on(http.get("/b"), flow({ name: "app-b.ping", do: () => "b" }));
-    const appB = oke({ name: "app-b" });
+    const appB = oke({ autoBoot: false, name: "app-b" });
 
     // Pre-fix this was 200: App B adopted App A's leftover binding.
     expect((await appB.fetch(new Request("http://localhost/a"))).status).toBe(404);
@@ -46,10 +46,10 @@ describe("registry isolation", () => {
 
   test("keep: today's behavior — registry survives construction", async () => {
     on(http.get("/a"), flow({ name: "kept.ping", do: () => "a" }));
-    oke({ name: "app-a", registry: "keep" });
+    oke({ autoBoot: false, name: "app-a", registry: "keep" });
     expect(listBindings()).toHaveLength(1);
 
-    const appB = oke({ name: "app-b", registry: "keep" });
+    const appB = oke({ autoBoot: false, name: "app-b", registry: "keep" });
     expect((await appB.fetch(new Request("http://localhost/a"))).status).toBe(200);
   });
 
@@ -60,7 +60,7 @@ describe("registry isolation", () => {
       trigger: http.get("/b"),
       flow: flow({ name: "only-b.ping", do: () => "b" }),
     };
-    const app = oke({ name: "app-b", registry: "ignore", bindings: [onlyB] });
+    const app = oke({ autoBoot: false, name: "app-b", registry: "ignore", bindings: [onlyB] });
 
     expect((await app.fetch(new Request("http://localhost/stray"))).status).toBe(404);
 

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/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 };