okengine 0.3.6 → 0.5.0

package/site/content/docs/reference/index.mdx

@@ -0,0 +1,45 @@
+---
+title: "Reference"
+description: "Lookup pages — config, fx, client, env vars, errors, plugins API, CLI, and Console security."
+icon: "BookMarked"
+source: "docs/spec/unified-theory.md"
+---
+
+Dense tables and command lists. Reach for these when you already know what you are looking for.
+
+## Pages
+
+<Cards>
+  <Card
+    title="Configuration"
+    description="Every option in oke.config.ts."
+    href="/docs/reference/configuration"
+  />
+  <Card title="fx" description="The complete fx surface and effects." href="/docs/reference/fx" />
+  <Card
+    title="Client"
+    description="Typed createClient — REST, RPC, envelope helpers."
+    href="/docs/reference/client"
+  />
+  <Card
+    title="Environment Variables"
+    description="Every variable OKE reads."
+    href="/docs/reference/environment-variables"
+  />
+  <Card title="Errors" description="OKE codes, denials, fixes." href="/docs/reference/errors" />
+  <Card
+    title="Plugins"
+    description="Plugin API — hooks, schemas, identity."
+    href="/docs/reference/plugins"
+  />
+  <Card
+    title="CLI Reference"
+    description="oke and create-oke commands."
+    href="/docs/reference/cli"
+  />
+  <Card
+    title="Security"
+    description="Console Host, Origin, MCP posture."
+    href="/docs/reference/security"
+  />
+</Cards>

package/site/content/docs/reference/meta.json

@@ -1,5 +1,15 @@
 {
   "title": "Reference",
   "icon": "BookMarked",
-  "pages": ["configuration", "fx", "environment-variables", "errors", "plugins", "cli", "security"]
+  "pages": [
+    "index",
+    "configuration",
+    "fx",
+    "client",
+    "environment-variables",
+    "errors",
+    "plugins",
+    "cli",
+    "security"
+  ]
 }

package/site/content/docs/reference/plugins.mdx

@@ -66,20 +66,26 @@ Every method below exists on both the fluent definition and the boot-time builde
 
 | Method                           | Contributes                                                                                   |
 | -------------------------------- | --------------------------------------------------------------------------------------------- |
-| `.flow(def)`                     | An ordinary flow — Manifest, Console, client types                                            |
+| `.flow(def)`                     | An ordinary flow — Manifest / Console metadata (does **not** join the HTTP router alone)      |
+| `.binding({ trigger, flow })`    | A real Binding — joins `adopted` + the router on `app.plug()` (auth method plugins)           |
 | `.hook(stage, fn)`               | A per-request intercept at one pipeline stage                                                 |
 | `.edge(fn)`                      | A handler for HTTP requests that match **no** flow                                            |
 | `.decorate(key, value)`          | A typed context decoration, visible to flows                                                  |
-| `.element({ kind, name })`       | An element contribution (e.g. `store.sql` facet)                                              |
+| `.element({ kind, name })`       | An opaque element contribution (e.g. `store.sql` facet)                                       |
+| `.vault(secret)`                 | A vault secret/config contract — merged into boot secrets                                     |
+| `.clock(decl)`                   | A named clock schedule — merged into boot clocks                                              |
+| `.signal(decl)`                  | A signal declaration — merged into boot signals                                               |
+| `.gate(decl)`                    | A gate declaration — merged into boot gates                                                   |
+| `.channelTemplate(decl)`         | A channel template — merged into boot channel templates                                       |
 | `.driver(id, impl)`              | A protocol-named driver for an existing element                                               |
 | `.image(role, recipe)`           | An image recipe for a docker role                                                             |
 | `.table(name, columns, options)` | A whole DB table, merged into the generated schema (`options.description` / `plane` optional) |
 | `.errors(map)`                   | Typed errors flows can fail with                                                              |
-| `.client(name, ext)`             | A typed client extension                                                                      |
+| `.client(name, ext)`             | A typed client extension (reserved seam — not yet merged into `createClient`)                 |
 | `.consolePanel(panel)`           | A Console panel (ESM entry loaded at runtime)                                                 |
 | `.cli(name, handler)`            | An `oke <name>` CLI command                                                                   |
 | `.config(schema)`                | A config schema; values live on the plugin identity                                           |
-| `.needs(dep)`                    | A declared dependency (e.g. `"store.kv"`)                                                     |
+| `.needs(dep)`                    | Runtime dependency — plugin name or element/driver id; unmet → `PluginNeedsError` at boot     |
 
 New infrastructure is a **driver** for an existing element, never a ninth element — plugins follow the same law.
 
@@ -202,13 +208,13 @@ Extending an existing **app-owned** table with plugin columns is not supported i
 
 ## Identity, config, and dependencies
 
-| Concept    | Rule                                                                           |
-| ---------- | ------------------------------------------------------------------------------ |
-| Name       | Stable plugin id — the Manifest key and conflict namespace                     |
-| `version`  | Semver string recorded in the Manifest                                         |
-| `config`   | Snapshot for identity dedup: same name + same config → no-op re-plug           |
-| Conflict   | Same name + **different** config → loud boot error, never a silent merge       |
-| `.needs()` | Declares runtime dependencies so boot fails early when a capability is missing |
+| Concept    | Rule                                                                                         |
+| ---------- | -------------------------------------------------------------------------------------------- |
+| Name       | Stable plugin id — the Manifest key and conflict namespace                                   |
+| `version`  | Semver string recorded in the Manifest                                                       |
+| `config`   | Snapshot for identity dedup: same name + same config → no-op re-plug                         |
+| Conflict   | Same name + **different** config → loud boot error, never a silent merge                     |
+| `.needs()` | Declares runtime dependencies (plugin name or element/driver id); unmet → `PluginNeedsError` |
 
 ## Troubleshooting
 
@@ -227,11 +233,16 @@ Extending an existing **app-owned** table with plugin columns is not supported i
     table above, and confirm the flow you expect actually reaches that stage (a gate denial never
     reaches `beforeHandle`).
   </Accordion>
+  <Accordion title="Boot: plugin boot failed — unmet .needs() dependencies">
+    A plugged plugin declared `.needs("auth")` or `.needs("store.sql")` (or another token) and
+    nothing satisfied it. For `"auth"`, enable `oke({ gate: { auth } })`. Otherwise plug the peer
+    plugin, or ensure the element/driver is available (tables imply `store.sql`, and so on).
+  </Accordion>
 </Accordions>
 
 ## Learn more
 
-- [Security Headers](/docs/plugins/security-headers) · [CORS](/docs/plugins/cors) · [CSRF](/docs/plugins/csrf) · [Compression](/docs/plugins/compression) · [Maintenance Mode](/docs/plugins/maintenance-mode) · [IP Allowlist](/docs/plugins/ip-allowlist) — first-party plugins built on exactly this API
+- [Plugins](/docs/plugins) — [username](/docs/plugins/username) · [anonymous](/docs/plugins/anonymous) · [magic link](/docs/plugins/magic-link) · [email OTP](/docs/plugins/email-otp) · [phone](/docs/plugins/phone-number) · [two-factor](/docs/plugins/two-factor) · [passkey](/docs/plugins/passkey) · [Headers](/docs/plugins/headers) · [CORS](/docs/plugins/cors) · [CSRF](/docs/plugins/csrf) · [Compression](/docs/plugins/compression) · [Maintenance Mode](/docs/plugins/maintenance-mode) · [IP Allowlist](/docs/plugins/ip-allowlist)
 - [Flow](/docs/elements/flow) — what plugin flows and hooks plug into
 - [Store](/docs/elements/store) — `field.*` builders and schema sync
 - [Configuration](/docs/reference/configuration) — where plugin config is declared
@@ -240,9 +251,9 @@ Extending an existing **app-owned** table with plugin columns is not supported i
 
 <Cards>
   <Card
-    title="Security Headers"
+    title="Headers"
     description="The full secure-headers set on every response."
-    href="/docs/plugins/security-headers"
+    href="/docs/plugins/headers"
   />
   <Card title="CORS" description="Cross-origin rules at the edge." href="/docs/plugins/cors" />
   <Card title="Flow" description="Triggers, effects, and durability." href="/docs/elements/flow" />

package/src/auth/auth.test.ts

@@ -75,6 +75,9 @@ describe("auth plugin", () => {
         tables.push(name);
         return this;
       },
+      binding() {
+        return this;
+      },
       flow() {
         return this;
       },
@@ -84,6 +87,21 @@ describe("auth plugin", () => {
       config() {
         return this;
       },
+      vault() {
+        return this;
+      },
+      clock() {
+        return this;
+      },
+      signal() {
+        return this;
+      },
+      gate() {
+        return this;
+      },
+      channelTemplate() {
+        return this;
+      },
     });
     expect(tables).toContain("oke_operators");
     expect(tables).toContain("oke_operator_credentials");
@@ -218,7 +236,7 @@ describe("operator plane", () => {
     const op = await createOperator(store, {
       email: "ops@example.com",
       name: "Ops",
-      password: "correct horse battery staple",
+      password: "correct horse battery staple 1",
     });
 
     expect(store.credentials.has(op.id)).toBe(true);
@@ -231,7 +249,7 @@ describe("operator plane", () => {
     const authed = await authenticateOperator(
       store,
       "ops@example.com",
-      "correct horse battery staple",
+      "correct horse battery staple 1",
     );
     expect(authed?.id).toBe(op.id);
   });

package/src/auth/bindings.ts

@@ -0,0 +1,439 @@
+/**
+ * Materialize Gate auth HTTP surfaces as real {@link Binding}s.
+ *
+ * Must be pushed into `adopted` + the smart router **before**
+ * `assertHttpGatePosture` — never registry `flows[]` alone.
+ */
+
+import { z } from "zod";
+import { gate, type PolicyGateDecl } 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, normalizeTrigger, type HttpTrigger, type Trigger } from "../kernel/triggers.ts";
+import type { ResolvedGateAuth } from "./config.ts";
+import { BreachCheckError } from "./breach-check.ts";
+import {
+  authenticateUser,
+  createIdentityStore,
+  createUserWithPassword,
+  getUserById,
+  IdentityError,
+  type IdentityStore,
+} from "./identity.ts";
+import { PasswordPolicyError } from "./password-policy.ts";
+import {
+  createSessionStore,
+  issueSessionWithScopes,
+  revokeFamily,
+  rotateRefresh,
+  SessionError,
+  type SessionCrypto,
+  type SessionStore,
+} from "./sessions.ts";
+import { touchRateLimit, type LoginAttemptBag, createLoginAttemptBag } from "./rate.ts";
+
+/** Built-in policy: verified user session (for `/auth/me` and step-up surfaces). */
+export const AUTH_SESSION_GATE: PolicyGateDecl = gate.policy(
+  "auth.session",
+  ({ auth }) => !!auth.userId && auth.verified === true,
+);
+
+/** Built-in policy: session within `freshAge` (step-up). Requires `meta.sessionCreatedAt`. */
+export function createFreshSessionGate(freshAgeMs: number): GateDecl {
+  return gate.policy("auth.fresh", (ctx) => {
+    if (!ctx.auth.userId || ctx.auth.verified !== true) return false;
+    const createdAt = ctx.meta?.sessionCreatedAt;
+    if (typeof createdAt !== "number") return false;
+    return Date.now() - createdAt <= freshAgeMs;
+  });
+}
+
+/** Auth rate presets (stricter on credential paths). */
+export const AUTH_RATE_PRESETS = {
+  signIn: { max: 5, per: "1m", keyBy: "ip" },
+  signUp: { max: 10, per: "1m", keyBy: "ip" },
+  refresh: { max: 30, per: "1m", keyBy: "ip" },
+  otp: { max: 5, per: "1m", keyBy: "ip" },
+} as const;
+
+/** Runtime context shared by auth Flows. */
+export interface AuthRuntimeContext {
+  readonly config: ResolvedGateAuth;
+  readonly sessions: SessionStore;
+  readonly identities: IdentityStore;
+  readonly loginAttempts: LoginAttemptBag;
+  readonly authGates: readonly GateDecl[];
+  now(): number;
+  sessionCrypto(): SessionCrypto;
+}
+
+/** Result of {@link createAuthHttpBindings}. */
+export interface AuthHttpMaterialization {
+  readonly bindings: readonly Binding[];
+  readonly flows: {
+    readonly refresh: AnyFlowDef;
+    readonly revoke: AnyFlowDef;
+    readonly me: AnyFlowDef;
+    readonly signInEmail?: AnyFlowDef;
+    readonly signUpEmail?: AnyFlowDef;
+  };
+  readonly ctx: AuthRuntimeContext;
+  /** Rate + policy gates to merge into boot `gates`. */
+  readonly authGates: readonly GateDecl[];
+}
+
+const SessionTokensOut = z.object({
+  accessToken: z.string(),
+  refreshToken: z.string(),
+  accessExpiresAt: z.number(),
+  userId: z.string().optional(),
+});
+
+const RefreshIn = z.object({
+  refreshToken: z.string().min(1),
+});
+
+const RevokeIn = z.object({
+  refreshToken: z.string().min(1).optional(),
+});
+
+const EmailPasswordIn = z.object({
+  email: z.string().min(3),
+  password: z.string().min(1),
+  name: z.string().optional(),
+});
+
+const AuthFailed = z.object({
+  reason: z.string().optional(),
+  /** Password-policy failure details (`reason: "password_policy"`). */
+  reasons: z.array(z.string()).optional(),
+});
+
+const AuthRateLimited = z.object({
+  reason: z.string(),
+});
+
+const MeOut = z.object({
+  userId: z.string(),
+  email: z.string(),
+  name: z.string(),
+  emailVerified: z.boolean(),
+});
+
+/**
+ * Build rate gate decls for auth paths (when rate limiting enabled).
+ *
+ * @param enabled - Whether presets are active
+ */
+export function createAuthRateGates(enabled: boolean): GateDecl[] {
+  if (!enabled) return [];
+  return [
+    gate.rate({
+      max: AUTH_RATE_PRESETS.signIn.max,
+      per: AUTH_RATE_PRESETS.signIn.per,
+      keyBy: AUTH_RATE_PRESETS.signIn.keyBy,
+      description: "Auth sign-in rate limit",
+    }),
+    gate.rate({
+      max: AUTH_RATE_PRESETS.signUp.max,
+      per: AUTH_RATE_PRESETS.signUp.per,
+      keyBy: AUTH_RATE_PRESETS.signUp.keyBy,
+      description: "Auth sign-up rate limit",
+    }),
+    gate.rate({
+      max: AUTH_RATE_PRESETS.refresh.max,
+      per: AUTH_RATE_PRESETS.refresh.per,
+      keyBy: AUTH_RATE_PRESETS.refresh.keyBy,
+      description: "Auth refresh rate limit",
+    }),
+  ];
+}
+
+/**
+ * Policy gates contributed by Gate auth (session + optional fresh).
+ *
+ * @param config - Resolved auth
+ */
+export function createAuthPolicyGates(config: ResolvedGateAuth): GateDecl[] {
+  return [AUTH_SESSION_GATE, createFreshSessionGate(config.session.freshAgeMs)];
+}
+
+/**
+ * Materialize auth HTTP Bindings for the same `adopted` / router / posture path.
+ *
+ * @param config - Resolved gate.auth
+ * @param options - Rate-limit enable + optional shared stores
+ */
+export function createAuthHttpBindings(
+  config: ResolvedGateAuth,
+  options: {
+    readonly rateLimitEnabled?: boolean;
+    readonly sessions?: SessionStore;
+    readonly identities?: IdentityStore;
+  } = {},
+): AuthHttpMaterialization {
+  const sessions = options.sessions ?? config.sessions ?? createSessionStore();
+  const identities = options.identities ?? createIdentityStore();
+  const loginAttempts = createLoginAttemptBag();
+  const rateGates = createAuthRateGates(options.rateLimitEnabled !== false);
+  const policyGates = createAuthPolicyGates(config);
+  const authGates = [...policyGates, ...rateGates];
+  const signInRate = rateGates[0];
+  const signUpRate = rateGates[1];
+  const refreshRate = rateGates[2];
+
+  const ctx: AuthRuntimeContext = {
+    config,
+    sessions,
+    identities,
+    loginAttempts,
+    authGates,
+    now: () => (config.now ?? (() => Date.now()))(),
+    sessionCrypto: () => ({
+      secret: config.secret,
+      now: () => ctx.now(),
+      accessTtlMs: config.session.accessTtlMs,
+      refreshTtlMs: config.session.refreshTtlMs,
+      idleTtlMs: config.session.idleTtlMs,
+      absoluteTtlMs: config.session.absoluteTtlMs,
+      singleSessionPerUser: config.session.singleSessionPerUser,
+      audience: config.audience,
+    }),
+  };
+
+  const base = config.basePath;
+
+  const refresh = flow({
+    name: "auth.refresh",
+    unit: "auth",
+    plane: "user",
+    in: RefreshIn,
+    out: SessionTokensOut,
+    errors: { AuthFailed, AuthRateLimited },
+    do: async (input) => {
+      try {
+        const issued = await rotateRefresh(sessions, ctx.sessionCrypto(), input.refreshToken);
+        return {
+          accessToken: issued.accessToken,
+          refreshToken: issued.refreshToken,
+          accessExpiresAt: issued.accessExpiresAt,
+          userId: issued.session.principalId,
+        };
+      } catch (err) {
+        if (err instanceof SessionError) {
+          // Enumeration-safe: same error shape for unknown / reused / expired.
+          return fail("AuthFailed", { reason: "invalid_refresh" });
+        }
+        throw err;
+      }
+    },
+  });
+
+  const revoke = flow({
+    name: "auth.revoke",
+    unit: "auth",
+    plane: "user",
+    in: RevokeIn,
+    out: z.object({ ok: z.literal(true) }),
+    errors: { AuthFailed },
+    do: async (input) => {
+      if (input.refreshToken) {
+        try {
+          const hash = await hashRefresh(input.refreshToken);
+          const row = [...sessions.refresh.values()].find((r) => r.hash === hash);
+          if (row) revokeFamily(sessions, row.familyId, ctx.now());
+        } catch {
+          /* ignore — revoke is idempotent */
+        }
+      }
+      return { ok: true as const };
+    },
+  });
+
+  const me = flow({
+    name: "auth.me",
+    unit: "auth",
+    plane: "user",
+    out: MeOut,
+    errors: { AuthFailed },
+    do: (_input, fx) => {
+      const userId = fx.auth.userId;
+      if (!userId) return fail("AuthFailed", { reason: "unauthenticated" });
+      const user = getUserById(identities, userId);
+      if (!user) return fail("AuthFailed", { reason: "unauthenticated" });
+      return {
+        userId: user.id,
+        email: user.email,
+        name: user.name,
+        emailVerified: user.emailVerified,
+      };
+    },
+  });
+
+  const flows: {
+    refresh: AnyFlowDef;
+    revoke: AnyFlowDef;
+    me: AnyFlowDef;
+    signInEmail?: AnyFlowDef;
+    signUpEmail?: AnyFlowDef;
+  } = { refresh, revoke, me };
+  const bindings: Binding[] = [
+    bindAuthHttp(
+      http.post(`${base}/refresh`).gate(gate.public, ...(refreshRate ? [refreshRate] : [])),
+      refresh,
+    ),
+    bindAuthHttp(http.post(`${base}/revoke`).gate(gate.public), revoke),
+    bindAuthHttp(http.get(`${base}/me`).gate(AUTH_SESSION_GATE), me),
+  ];
+
+  if (config.emailAndPassword.enabled) {
+    const signInEmail = flow({
+      name: "auth.signInEmail",
+      unit: "auth",
+      plane: "user",
+      in: EmailPasswordIn,
+      out: SessionTokensOut,
+      errors: { AuthFailed, AuthRateLimited },
+      do: async (input) => {
+        const key = input.email.trim().toLowerCase();
+        let bag = loginAttempts.get(key);
+        if (!bag) {
+          bag = [];
+          loginAttempts.set(key, bag);
+        }
+        if (touchRateLimit(bag, ctx.now()) === "rate_limited") {
+          return fail("AuthRateLimited", {
+            reason: "too many sign-in attempts; retry later",
+          });
+        }
+        const user = await authenticateUser(identities, input.email, input.password);
+        // Enumeration hygiene: identical failure for unknown email / bad password.
+        if (!user) return fail("AuthFailed", { reason: "invalid_credentials" });
+        if (config.emailAndPassword.requireEmailVerification && !user.emailVerified) {
+          return fail("AuthFailed", { reason: "invalid_credentials" });
+        }
+        const issued = await issueSessionWithScopes(sessions, ctx.sessionCrypto(), {
+          id: user.id,
+          plane: "user",
+          scopes: [],
+        });
+        return {
+          accessToken: issued.accessToken,
+          refreshToken: issued.refreshToken,
+          accessExpiresAt: issued.accessExpiresAt,
+          userId: user.id,
+        };
+      },
+    });
+
+    const signUpEmail = flow({
+      name: "auth.signUpEmail",
+      unit: "auth",
+      plane: "user",
+      in: EmailPasswordIn,
+      out: SessionTokensOut,
+      errors: { AuthFailed, AuthRateLimited },
+      do: async (input) => {
+        try {
+          const user = await createUserWithPassword(identities, {
+            email: input.email,
+            password: input.password,
+            name: input.name,
+            passwordPolicy: config.passwordPolicy,
+            passwordHash: config.password,
+            breachCheck: config.breachCheck,
+            now: () => ctx.now(),
+          });
+          if (config.hooks?.user?.create?.after) {
+            await config.hooks.user.create.after({
+              id: user.id,
+              email: user.email,
+              name: user.name,
+            });
+          }
+          const issued = await issueSessionWithScopes(sessions, ctx.sessionCrypto(), {
+            id: user.id,
+            plane: "user",
+            scopes: [],
+          });
+          return {
+            accessToken: issued.accessToken,
+            refreshToken: issued.refreshToken,
+            accessExpiresAt: issued.accessExpiresAt,
+            userId: user.id,
+          };
+        } catch (err) {
+          if (err instanceof PasswordPolicyError) {
+            return fail("AuthFailed", {
+              reason: "password_policy",
+              reasons: [...err.reasons],
+            });
+          }
+          if (err instanceof BreachCheckError) {
+            return fail("AuthFailed", { reason: "password_breached" });
+          }
+          if (err instanceof IdentityError) {
+            // Enumeration-safe on email_taken — same shape as generic failure.
+            if (err.code === "email_taken") {
+              return fail("AuthFailed", { reason: "invalid_credentials" });
+            }
+            return fail("AuthFailed", { reason: err.code });
+          }
+          throw err;
+        }
+      },
+    });
+
+    flows.signInEmail = signInEmail;
+    flows.signUpEmail = signUpEmail;
+    bindings.push(
+      bindAuthHttp(
+        http.post(`${base}/sign-in/email`).gate(gate.public, ...(signInRate ? [signInRate] : [])),
+        signInEmail,
+      ),
+      bindAuthHttp(
+        http.post(`${base}/sign-up/email`).gate(gate.public, ...(signUpRate ? [signUpRate] : [])),
+        signUpEmail,
+      ),
+    );
+  }
+
+  return { bindings, flows, ctx, authGates };
+}
+
+/**
+ * Whether a session is still within the fresh-age window.
+ *
+ * @param createdAt - Session creation epoch-ms
+ * @param freshAgeMs - Fresh window
+ * @param now - Clock
+ */
+export function isSessionFresh(
+  createdAt: number,
+  freshAgeMs: number,
+  now: number = Date.now(),
+): boolean {
+  return now - createdAt <= freshAgeMs;
+}
+
+/**
+ * Bind without touching the global `on` registry.
+ *
+ * @param trigger - HTTP trigger (must already carry posture)
+ * @param flowDef - Flow
+ */
+export function bindAuthHttp(trigger: HttpTrigger, flowDef: AnyFlowDef): Binding {
+  const withPosture = trigger.gates.length > 0 ? trigger : trigger.gate(gate.public);
+  const normalized = normalizeTrigger(withPosture);
+  const list = flowDef.triggers as Trigger[];
+  list.push(normalized);
+  (flowDef as { $trigger: Trigger }).$trigger = normalized;
+  return { trigger: normalized, flow: flowDef };
+}
+
+async function hashRefresh(raw: string): Promise<string> {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(raw));
+  return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}