okengine 0.18.4 → 0.19.0

package/src/mcp/docs-index.ts

@@ -12,7 +12,7 @@ import { join } from "node:path";
 export interface DocsPage {
   /** URL slug under `/docs` (`""` for the index page). */
   readonly slug: string;
-  /** Content-relative path (e.g. `get-started/introduction.mdx`). */
+  /** Content-relative path (e.g. `understand/the-problem.mdx`). */
   readonly path: string;
   /** Frontmatter title. */
   readonly title: string;
@@ -39,7 +39,7 @@ export interface DocsIndex {
   /**
    * Look up a page by slug or content path.
    *
-   * @param id - Slug (`get-started/introduction`) or path (`…/introduction.mdx`)
+   * @param id - Slug (`understand/the-problem`) or path (`…/the-problem.mdx`)
    */
   readonly get: (id: string) => DocsPage | null;
   /**
@@ -203,7 +203,7 @@ export async function loadDocsIndex(
 }
 
 /**
- * @param relativePath - e.g. `get-started/introduction.mdx`
+ * @param relativePath - e.g. `understand/the-problem.mdx`
  */
 function pathToSlug(relativePath: string): string {
   const noExt = relativePath.replace(/\.mdx?$/i, "");

package/src/mcp/docs-mcp.test.ts

@@ -112,7 +112,7 @@ describe("docs MCP tools", () => {
 
   test("oke.docs.get returns body byte-identical to on-disk source", async () => {
     const mcp = await createDocsMcpServer({ contentDir: CONTENT });
-    const slug = "get-started/introduction";
+    const slug = "understand/the-problem";
     const res = await mcpPost(mcp.fetch, {
       jsonrpc: "2.0",
       id: 2,
@@ -133,7 +133,7 @@ describe("docs MCP tools", () => {
     const content = envelope.content as { body: string; slug: string };
     expect(content.slug).toBe(slug);
 
-    const raw = await Bun.file(join(CONTENT, "get-started", "introduction.mdx")).text();
+    const raw = await Bun.file(join(CONTENT, "understand", "the-problem.mdx")).text();
     expect(content.body).toBe(stripYamlFrontmatter(raw));
   });
 

package/src/mcp/docs-tools.ts

@@ -52,7 +52,7 @@ export const DOCS_MCP_TOOLS: readonly DocsToolDescriptor[] = [
       properties: {
         slug: {
           type: "string",
-          description: "Page slug (e.g. get-started/introduction) or path (…/introduction.mdx)",
+          description: "Page slug (e.g. understand/the-problem) or path (…/the-problem.mdx)",
         },
       },
       required: ["slug"],

package/src/okid.test.ts

@@ -8,6 +8,7 @@ import {
   OKID_DEFAULT_LENGTH,
   OKID_LOOKALIKE_CHARS,
   OKID_MAX_LENGTH,
+  OKID_MAX_PREFIX_LENGTH,
   OKID_MIN_LENGTH,
   OKID_SORTABLE_ALPHABET,
   OKID_SORTABLE_MIN_LENGTH,
@@ -304,6 +305,61 @@ describe("okid sortable mode", () => {
   });
 });
 
+describe("okid semantic prefix", () => {
+  test("prepends the label and keeps body length", () => {
+    const id = okid({ prefix: "usr_" });
+    expect(id.startsWith("usr_")).toBe(true);
+    expect(id.length).toBe(4 + OKID_DEFAULT_LENGTH);
+    expect(id.slice(4).length).toBe(OKID_DEFAULT_LENGTH);
+  });
+
+  test("honors length as the body size, not the total", () => {
+    const id = okid({ prefix: "evt_", length: 16 });
+    expect(id.startsWith("evt_")).toBe(true);
+    expect(id.length).toBe(4 + 16);
+  });
+
+  test("combines with sortable: prefix + timestamp + random", () => {
+    const realNow = Date.now;
+    Date.now = () => 1_700_000_000_000;
+    try {
+      const a = okid({ prefix: "evt_", sortable: true, length: 16 });
+      const b = okid({ prefix: "evt_", sortable: true, length: 16 });
+      expect(a.startsWith("evt_")).toBe(true);
+      expect(a.length).toBe(4 + 16);
+      expect(a.slice(4, 12)).toBe(b.slice(4, 12));
+      expect(a.slice(12)).not.toBe(b.slice(12));
+    } finally {
+      Date.now = realNow;
+    }
+  });
+
+  test("empty / omitted prefix is a no-op", () => {
+    expect(okid({ prefix: "" }).length).toBe(OKID_DEFAULT_LENGTH);
+    expect(okid({}).length).toBe(OKID_DEFAULT_LENGTH);
+  });
+
+  test("rejects characters outside OKID_ALPHABET", () => {
+    expect(() => okid({ prefix: "usr:" })).toThrow(RangeError);
+    expect(() => okid({ prefix: "usr " })).toThrow(RangeError);
+    expect(() => okid({ prefix: "usr." })).toThrow(RangeError);
+  });
+
+  test("rejects oversized prefixes", () => {
+    expect(() => okid({ prefix: "a".repeat(OKID_MAX_PREFIX_LENGTH + 1) })).toThrow(RangeError);
+    expect(okid({ prefix: "a".repeat(OKID_MAX_PREFIX_LENGTH) }).length).toBe(
+      OKID_MAX_PREFIX_LENGTH + OKID_DEFAULT_LENGTH,
+    );
+  });
+
+  test("full id stays URL-safe", () => {
+    for (let i = 0; i < 200; i++) {
+      const id = okid({ prefix: "inst-" });
+      expect(encodeURIComponent(id)).toBe(id);
+    }
+  });
+});
+
 describe("okid entropy math", () => {
   const bitsPerChar = Math.log2;
 

package/src/okid.ts

@@ -16,8 +16,11 @@
  *   48-bit epoch-millisecond timestamp encoded in exactly 8 chars, leaving
  *   `length − 8` random chars (78 bits at the default length). Lexicographic
  *   order equals time order across milliseconds; ids minted within the same
- *   millisecond tie on the prefix and carry no intra-ms ordering. Clock skew
+ *   millisecond tie on the timestamp and carry no intra-ms ordering. Clock skew
  *   distorts ordering but can never cause duplicates (the tail stays random).
+ * - **Semantic prefix** — `okid({ prefix: "usr_" })` prepends a fixed label
+ *   from the OKID alphabet. `length` is always the generated body (random or
+ *   sortable); the returned string is `prefix + body`.
  * - **Alphabet control** — group toggles (`numbers`, `lowercase`,
  *   `uppercase`, `symbols`) and `lookAlikes` shrink the alphabet for
  *   human-transcribed codes. Non-power-of-two alphabets use rejection
@@ -38,7 +41,8 @@
  *
  * const userId = okid();                       // 21 chars, 126 bits
  * const requestId = okid(16);                  // explicit length
- * const eventKey = okid({ sortable: true });   // time-prefixed
+ * const eventKey = okid({ sortable: true });   // time-prefixed body
+ * const typedId = okid({ prefix: "usr_" });    // usr_ + 21-char body
  * const inviteCode = okid({
  *   lookAlikes: false,
  *   uppercase: false,
@@ -89,14 +93,27 @@ export const OKID_MAX_LENGTH = 128;
 /** Sortable ids need ≥ 16: 8 timestamp chars alone would leave no randomness. */
 export const OKID_SORTABLE_MIN_LENGTH = 16;
 
+/** Longest permitted semantic {@link OkidOptions.prefix}. */
+export const OKID_MAX_PREFIX_LENGTH = 32;
+
 /** Options for {@link okid}. All alphabet toggles default to included. */
 export interface OkidOptions {
-  /** Total id length (default {@link OKID_DEFAULT_LENGTH}). */
+  /**
+   * Generated body length (default {@link OKID_DEFAULT_LENGTH}). Does not
+   * include {@link prefix} — the returned string is `prefix + body`.
+   */
   readonly length?: number;
   /**
-   * Prefix a 48-bit epoch-ms timestamp (exactly 8 chars) so lexicographic
-   * order tracks creation time across milliseconds. Alphabet toggles are
-   * ignored under this mode — see {@link OKID_SORTABLE_ALPHABET}.
+   * Fixed semantic label prepended to the body (e.g. `"usr_"`, `"evt_"`).
+   * Characters must belong to {@link OKID_ALPHABET}; max
+   * {@link OKID_MAX_PREFIX_LENGTH}. Empty / omitted means no label.
+   */
+  readonly prefix?: string;
+  /**
+   * Prefix the body with a 48-bit epoch-ms timestamp (exactly 8 chars) so
+   * lexicographic order tracks creation time across milliseconds. Alphabet
+   * toggles are ignored under this mode — see {@link OKID_SORTABLE_ALPHABET}.
+   * Combines with {@link prefix}: `prefix + timestamp + random`.
    */
   readonly sortable?: boolean;
   /** Include `a-z` (default true). */
@@ -204,6 +221,26 @@ function assertLength(length: number, min: number, label: string): void {
   }
 }
 
+/**
+ * Assert a semantic prefix is within bounds and stays on the URL-safe alphabet.
+ *
+ * @param prefix - Caller-supplied label
+ */
+function assertPrefix(prefix: string): void {
+  if (prefix.length > OKID_MAX_PREFIX_LENGTH) {
+    throw new RangeError(
+      `okid: prefix length ${prefix.length} exceeds max ${OKID_MAX_PREFIX_LENGTH}`,
+    );
+  }
+  for (const char of prefix) {
+    if (!OKID_ALPHABET.includes(char)) {
+      throw new RangeError(
+        `okid: prefix contains invalid character ${JSON.stringify(char)} — use characters from OKID_ALPHABET`,
+      );
+    }
+  }
+}
+
 /**
  * Generate an OKE-native id.
  *
@@ -211,9 +248,10 @@ function assertLength(length: number, min: number, label: string): void {
  * the hot path and skips all option resolution beyond validation.
  *
  * @param options - Length in chars, or {@link OkidOptions}
- * @returns A URL-safe id of exactly the requested length
+ * @returns A URL-safe id: the generated body, optionally preceded by
+ * {@link OkidOptions.prefix}
  * @throws RangeError on invalid input (non-integer, out-of-range length,
- * empty alphabet)
+ * invalid prefix, empty alphabet)
  */
 export function okid(options: number | OkidOptions = OKID_DEFAULT_LENGTH): string {
   if (typeof options === "number") {
@@ -223,6 +261,7 @@ export function okid(options: number | OkidOptions = OKID_DEFAULT_LENGTH): strin
 
   const {
     length = OKID_DEFAULT_LENGTH,
+    prefix = "",
     sortable = false,
     lowercase = true,
     uppercase = true,
@@ -231,15 +270,20 @@ export function okid(options: number | OkidOptions = OKID_DEFAULT_LENGTH): strin
     lookAlikes = true,
   } = options;
 
+  if (prefix) assertPrefix(prefix);
+
+  let body: string;
   if (sortable) {
     assertLength(length, OKID_SORTABLE_MIN_LENGTH, "length");
     // Time ordering requires lexicographic encoding, which requires the full
     // codepoint-ordered alphabet — partial subsets cannot preserve both the
     // caller's charset choice AND cross-ms ordering, so toggles are ignored.
     const alphabet = resolveAlphabet(true, true, true, true, true);
-    return encodeTimestamp(Date.now()) + encode(alphabet, length - 8);
+    body = encodeTimestamp(Date.now()) + encode(alphabet, length - 8);
+  } else {
+    assertLength(length, OKID_MIN_LENGTH, "length");
+    body = encode(resolveAlphabet(numbers, lowercase, uppercase, symbols, lookAlikes), length);
   }
 
-  assertLength(length, OKID_MIN_LENGTH, "length");
-  return encode(resolveAlphabet(numbers, lowercase, uppercase, symbols, lookAlikes), length);
+  return prefix ? prefix + body : body;
 }

package/src/plugins/anonymous.ts

@@ -16,6 +16,7 @@ import {
   resolveSharedIdentities,
   type AuthMethodOptions,
 } from "./auth/shared.ts";
+import { okid } from "../okid.ts";
 
 /** Options for {@link anonymous}. */
 export interface AnonymousPluginOptions extends AuthMethodOptions {
@@ -34,17 +35,20 @@ export function anonymous(opts: AnonymousPluginOptions = {}): PluginDef {
   const runtime = createMethodRuntime(opts);
   const identities = resolveSharedIdentities(opts);
 
-  const signIn = flow("auth.signInAnonymous", {
-    plane: "user",
+  const signInContract = {
     out: SessionTokensOut,
     errors: { AuthFailed, AuthRateLimited },
+  };
+
+  const signIn = flow("auth.signInAnonymous", {
+    plane: "user",
     do: async () => {
       let userId: string;
       try {
         userId = (
           await linkOrProvision(identities, {
             provider: "anonymous",
-            providerAccountId: crypto.randomUUID(),
+            providerAccountId: okid(),
             now: runtime.now,
           })
         ).user.id;
@@ -70,5 +74,5 @@ export function anonymous(opts: AnonymousPluginOptions = {}): PluginDef {
 
   return plugin("anonymous", { version: "0.0.1", config: { method: "anonymous" } })
     .needs("auth")
-    .binding(bindPublicAuth("/sign-in/anonymous", signIn, "signIn"));
+    .binding(bindPublicAuth("/sign-in/anonymous", signIn, "signIn", signInContract));
 }

package/src/plugins/auth/shared.ts

@@ -9,6 +9,7 @@ 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 type { BoundaryContract } from "../../kernel/boundary-contract.ts";
 import { fail } from "../../kernel/errors.ts";
 import { flow, type AnyFlowDef } from "../../kernel/flow.ts";
 import type { Binding } from "../../kernel/on.ts";
@@ -21,6 +22,9 @@ export const AuthFailed = z.object({
   reasons: z.array(z.string()).optional(),
 });
 export const AuthRateLimited = z.object({ reason: z.string() });
+export const Forbidden = z.object({
+  reason: z.string().optional(),
+});
 
 export const SessionTokensOut = z.object({
   accessToken: z.string(),
@@ -29,6 +33,18 @@ export const SessionTokensOut = z.object({
   userId: z.string().optional(),
 });
 
+/** Sign-in may return tokens or a locked 2FA challenge. */
+export const SignInOut = z.union([
+  SessionTokensOut,
+  z.object({
+    twoFactorRequired: z.literal(true),
+    challengeId: z.string(),
+    method: z.enum(["totp", "email_otp"]),
+    userId: z.string(),
+    devOtp: 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. */
@@ -120,9 +136,11 @@ export function bindPublicAuth(
   path: string,
   flowDef: AnyFlowDef,
   kind: keyof typeof AUTH_RATE_PRESETS = "otp",
+  contract?: BoundaryContract,
 ): Binding {
   const gates = authPublicGates(kind);
-  let trigger = http.post(`/auth${path}`);
+  let trigger =
+    contract !== undefined ? http.post(`/auth${path}`, contract) : http.post(`/auth${path}`);
   for (const g of gates) trigger = trigger.gate(g);
   return bindAuthHttp(trigger, flowDef);
 }
@@ -133,8 +151,14 @@ export function bindPublicAuth(
  * @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 function bindSessionAuth(
+  path: string,
+  flowDef: AnyFlowDef,
+  contract?: BoundaryContract,
+): Binding {
+  const trigger =
+    contract !== undefined ? http.post(`/auth${path}`, contract) : http.post(`/auth${path}`);
+  return bindAuthHttp(trigger.gate(AUTH_SESSION_GATE), flowDef);
 }
 
 export { AUTH_SESSION_GATE, fail, flow, http, z };

package/src/plugins/auth-delivery.mailpit.integration.test.ts

@@ -18,7 +18,7 @@ import { otp } from "./otp.ts";
 import { magicLink } from "./magic-link.ts";
 
 const SECRET = "test-secret-at-least-16";
-const MAILPIT_IMAGE = "axllent/mailpit:v1.30.7";
+const MAILPIT_IMAGE = "axllent/mailpit:v1.31.1";
 
 afterEach(() => {
   resetBindings();