okengine 0.17.2 → 0.18.3

package/src/okid.ts

@@ -0,0 +1,245 @@
+/**
+ * OKID — OKE's native id generator.
+ *
+ * A compact, URL-safe, cryptographically random identifier with an opt-in
+ * time-sortable variant and opt-in alphabet control. Zero dependencies, zero
+ * shared state, safe under concurrent generation.
+ *
+ * Design properties:
+ *
+ * - **Default form** — 21 chars over a 64-char URL-safe alphabet
+ *   (`A-Za-z0-9-_`) = exactly 6 bits per char = **126 bits** of entropy.
+ *   Birthday bound: n² / 2¹²⁷ — generating one billion ids yields a collision
+ *   probability around 10⁻²¹. No timestamps, counters, or machine
+ *   fingerprints are exposed by default.
+ * - **Sortable variant** — `okid({ sortable: true })` prefixes the id with a
+ *   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
+ *   distorts ordering but can never cause duplicates (the tail stays random).
+ * - **Alphabet control** — group toggles (`numbers`, `lowercase`,
+ *   `uppercase`, `symbols`) and `lookAlikes` shrink the alphabet for
+ *   human-transcribed codes. Non-power-of-two alphabets use rejection
+ *   sampling, so every character remains equally likely — no modulo bias at
+ *   any alphabet size.
+ * - **Randomness** — exclusively `crypto.getRandomValues()`. Never
+ *   `Math.random`. Stateless, therefore concurrency-safe.
+ *
+ * Use OKID for application identifiers: database primary keys, request /
+ * job / workflow / resource ids. Do NOT use it as a secret or token (ids are
+ * not unguessable credentials), and use UUID instead where an external
+ * protocol explicitly requires that format. Sortable ids embed their creation
+ * time (~ms precision) — keep them internal, not publicly enumerable.
+ *
+ * @example
+ * ```ts
+ * import { okid } from "okengine/okid";
+ *
+ * const userId = okid();                       // 21 chars, 126 bits
+ * const requestId = okid(16);                  // explicit length
+ * const eventKey = okid({ sortable: true });   // time-prefixed
+ * const inviteCode = okid({
+ *   lookAlikes: false,
+ *   uppercase: false,
+ * });                                          // human-transcribable
+ * ```
+ *
+ * @module
+ */
+
+/** Character groups addressable through {@link OkidOptions} toggles. */
+const GROUPS = {
+  numbers: "0123456789",
+  lowercase: "abcdefghijklmnopqrstuvwxyz",
+  uppercase: "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
+  symbols: "-_",
+} as const;
+
+/**
+ * Characters removed when `lookAlikes` is disabled (human transcription).
+ */
+export const OKID_LOOKALIKE_CHARS = "1lI0Oouv5Ss";
+
+/** Default URL-safe alphabet: Base64URL charset in its conventional order. */
+export const OKID_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+
+/**
+ * Codepoint-ordered variant of {@link OKID_ALPHABET}: identical characters,
+ * sorted by code unit so plain string comparison equals value comparison.
+ * The default Base64URL order is NOT lexicographic (`_` sorts between `Z`
+ * and `a`), which would silently break time ordering — so the sortable
+ * encoder always uses this order.
+ *
+ * Kept as a literal (not `[...OKID_ALPHABET].sort().join("")`) so the public
+ * JSR API stays fast-type / explicitly typed.
+ */
+export const OKID_SORTABLE_ALPHABET: string =
+  "-0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz";
+
+/** Default id length — 21 chars × 6 bits = 126 bits of entropy. */
+export const OKID_DEFAULT_LENGTH = 21;
+
+/** Shortest permitted id length (8 chars ≈ 48 bits entropy floor). */
+export const OKID_MIN_LENGTH = 8;
+
+/** Longest permitted id length. */
+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;
+
+/** Options for {@link okid}. All alphabet toggles default to included. */
+export interface OkidOptions {
+  /** Total id length (default {@link OKID_DEFAULT_LENGTH}). */
+  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}.
+   */
+  readonly sortable?: boolean;
+  /** Include `a-z` (default true). */
+  readonly lowercase?: boolean;
+  /** Include `A-Z` (default true). */
+  readonly uppercase?: boolean;
+  /** Include `0-9` (default true). */
+  readonly numbers?: boolean;
+  /** Include `-` and `_` (default true). */
+  readonly symbols?: boolean;
+  /**
+   * Include visually confusable characters (`1lI0Oouv5Ss`, default true).
+   * Set `false` to drop them for human transcription.
+   */
+  readonly lookAlikes?: boolean;
+}
+
+/** Resolved alphabet + encoding metadata for one options combination. */
+interface ResolvedAlphabet {
+  readonly chars: string;
+  readonly size: number;
+  /** Bitmask covering `size` values (`size` is always a power of two here). */
+  readonly mask: number;
+}
+
+/** Memoized resolutions keyed by the toggle bitmask (32 combinations max). */
+const ALPHABET_CACHE = new Map<number, ResolvedAlphabet>();
+
+function resolveAlphabet(
+  numbers: boolean,
+  lowercase: boolean,
+  uppercase: boolean,
+  symbols: boolean,
+  lookAlikes: boolean,
+): ResolvedAlphabet {
+  const key =
+    (numbers ? 1 : 0) |
+    (lowercase ? 2 : 0) |
+    (uppercase ? 4 : 0) |
+    (symbols ? 8 : 0) |
+    (lookAlikes ? 0 : 16);
+  const cached = ALPHABET_CACHE.get(key);
+  if (cached) return cached;
+
+  let chars = "";
+  if (numbers) chars += GROUPS.numbers;
+  if (lowercase) chars += GROUPS.lowercase;
+  if (uppercase) chars += GROUPS.uppercase;
+  if (symbols) chars += GROUPS.symbols;
+  if (!chars) {
+    throw new RangeError("okid: alphabet is empty — enable at least one character group");
+  }
+  if (!lookAlikes) {
+    chars = [...chars].filter((c) => !OKID_LOOKALIKE_CHARS.includes(c)).join("");
+  }
+
+  // Round up to a power of two for mask-based rejection sampling: bytes below
+  // `size` map uniformly, bytes above are discarded and re-drawn — unbiased at
+  // every alphabet size, unlike naive modulo.
+  const rawSize = chars.length;
+  const size = 1 << Math.ceil(Math.log2(rawSize));
+  const resolved: ResolvedAlphabet = { chars, size: rawSize, mask: size - 1 };
+  ALPHABET_CACHE.set(key, resolved);
+  return resolved;
+}
+
+/** Encode one random byte stream into `length` characters of `alphabet`. */
+function encode(alphabet: ResolvedAlphabet, length: number): string {
+  const { chars, size, mask } = alphabet;
+  const bytes = new Uint8Array(length + Math.ceil(length >> 2));
+  crypto.getRandomValues(bytes.subarray(0, length));
+  let out = "";
+  let i = 0;
+  while (out.length < length && i < bytes.length) {
+    const byte = bytes[i++]!;
+    if ((byte & mask) < size) out += chars[byte & mask];
+  }
+  return out;
+}
+
+/** Pack epoch-ms into exactly 8 codepoint-ordered characters (48 bits). */
+function encodeTimestamp(nowMs: number): string {
+  let t = nowMs % 2 ** 48;
+  let out = "";
+  for (let i = 0; i < 8; i++) {
+    out = OKID_SORTABLE_ALPHABET[t & 63]! + out;
+    t = Math.floor(t / 64);
+  }
+  return out;
+}
+
+/**
+ * Assert `length` is a valid integer within bounds for the requested mode.
+ *
+ * @param length - Requested length
+ * @param min - Mode-specific minimum
+ * @param label - Option name used in the error message
+ */
+function assertLength(length: number, min: number, label: string): void {
+  if (!Number.isInteger(length)) {
+    throw new RangeError(`okid: ${label} must be an integer, got ${length}`);
+  }
+  if (length < min || length > OKID_MAX_LENGTH) {
+    throw new RangeError(`okid: ${label} ${length} is out of range [${min}, ${OKID_MAX_LENGTH}]`);
+  }
+}
+
+/**
+ * Generate an OKE-native id.
+ *
+ * Accepts either a bare length or an options object; the bare-number form is
+ * 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
+ * @throws RangeError on invalid input (non-integer, out-of-range length,
+ * empty alphabet)
+ */
+export function okid(options: number | OkidOptions = OKID_DEFAULT_LENGTH): string {
+  if (typeof options === "number") {
+    assertLength(options, OKID_MIN_LENGTH, "length");
+    return encode(resolveAlphabet(true, true, true, true, true), options);
+  }
+
+  const {
+    length = OKID_DEFAULT_LENGTH,
+    sortable = false,
+    lowercase = true,
+    uppercase = true,
+    numbers = true,
+    symbols = true,
+    lookAlikes = true,
+  } = options;
+
+  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);
+  }
+
+  assertLength(length, OKID_MIN_LENGTH, "length");
+  return encode(resolveAlphabet(numbers, lowercase, uppercase, symbols, lookAlikes), length);
+}

package/src/plugins/anonymous.ts

@@ -2,6 +2,7 @@
  * Anonymous sign-in Gate auth method plugin.
  */
 
+import { IdentityError, linkOrProvision } from "../auth/identity.ts";
 import { issueSessionWithScopes } from "../auth/sessions.ts";
 import { plugin, type PluginDef } from "../kernel/plugin.ts";
 import {
@@ -10,7 +11,9 @@ import {
   SessionTokensOut,
   bindPublicAuth,
   createMethodRuntime,
+  fail,
   flow,
+  resolveSharedIdentities,
   type AuthMethodOptions,
 } from "./auth/shared.ts";
 
@@ -29,13 +32,28 @@ export interface AnonymousPluginOptions extends AuthMethodOptions {
  */
 export function anonymous(opts: AnonymousPluginOptions = {}): PluginDef {
   const runtime = createMethodRuntime(opts);
+  const identities = resolveSharedIdentities(opts);
 
   const signIn = flow("auth.signInAnonymous", {
     plane: "user",
     out: SessionTokensOut,
     errors: { AuthFailed, AuthRateLimited },
     do: async () => {
-      const userId = crypto.randomUUID();
+      let userId: string;
+      try {
+        userId = (
+          await linkOrProvision(identities, {
+            provider: "anonymous",
+            providerAccountId: crypto.randomUUID(),
+            now: runtime.now,
+          })
+        ).user.id;
+      } catch (err) {
+        if (err instanceof IdentityError) {
+          return fail("AuthFailed", { reason: "invalid_credentials" });
+        }
+        throw err;
+      }
       const issued = await issueSessionWithScopes(runtime.sessions, runtime.crypto, {
         id: userId,
         plane: "user",

package/src/plugins/auth/shared.ts

@@ -4,6 +4,7 @@
 
 import { z } from "zod";
 import { AUTH_RATE_PRESETS, AUTH_SESSION_GATE, bindAuthHttp } from "../../auth/bindings.ts";
+import { createIdentityStore, type IdentityStore } from "../../auth/identity.ts";
 import { getActiveGateAuthContext } from "../../auth/method-context.ts";
 import { createSessionStore, type SessionCrypto, type SessionStore } from "../../auth/sessions.ts";
 import { gate } from "../../elements/gate.ts";
@@ -34,6 +35,8 @@ export interface AuthMethodOptions {
   readonly secret?: string;
   /** Shared session store (prefer the same store as `gate.auth`). */
   readonly sessions?: SessionStore;
+  /** Shared identity/credential store (defaults to `gate.auth.identities`). */
+  readonly identities?: IdentityStore;
   /** Injectable clock. */
   readonly now?: () => number;
 }
@@ -76,6 +79,18 @@ export function createMethodRuntime(opts: AuthMethodOptions = {}): {
   };
 }
 
+/**
+ * Resolve the shared identity/credential store for a method plugin.
+ * Prefers explicit opts, then the active `gate.auth.identities`, else a new
+ * isolated store (advanced / test-injection).
+ *
+ * @param opts - Method options carrying an optional `identities`
+ */
+export function resolveSharedIdentities(opts: AuthMethodOptions = {}): IdentityStore {
+  const active = getActiveGateAuthContext();
+  return opts.identities ?? active?.identities ?? createIdentityStore();
+}
+
 /**
  * Public + rate gate chain for credential-ish auth paths.
  *

package/src/plugins/index.ts

@@ -42,6 +42,8 @@ export {
   type PasskeyOptions,
   type PasskeyStore,
 } from "./passkey.ts";
+export { oauth, type OAuthOptions } from "./oauth.ts";
+export { mcpOauth, mcpOauthConsentFlows, type McpOauthOptions } from "./mcp-oauth.ts";
 export {
   b64urlDecode,
   b64urlEncode,

package/src/plugins/magic-link.ts

@@ -6,12 +6,7 @@
  * local DX without Mailpit / SMTP.
  */
 
-import {
-  createIdentityStore,
-  ensureUserByEmail,
-  normalizeEmail,
-  type IdentityStore,
-} from "../auth/identity.ts";
+import { linkOrProvision, normalizeEmail, type IdentityStore } from "../auth/identity.ts";
 import { issueSessionWithScopes } from "../auth/sessions.ts";
 import {
   createVerificationStore,
@@ -29,6 +24,7 @@ import {
   createMethodRuntime,
   fail,
   flow,
+  resolveSharedIdentities,
   z,
   type AuthMethodOptions,
 } from "./auth/shared.ts";
@@ -90,7 +86,7 @@ export interface MagicLinkOptions extends AuthMethodOptions {
  */
 export function magicLink(opts: MagicLinkOptions = {}): PluginDef {
   const runtime = createMethodRuntime(opts);
-  const identities = opts.identities ?? createIdentityStore();
+  const identities = resolveSharedIdentities(opts);
   const verifications = opts.verifications ?? createVerificationStore();
   const ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
   const baseUrl = (opts.baseUrl ?? process.env.OKE_APP_URL ?? DEFAULT_BASE_URL).replace(/\/$/, "");
@@ -172,7 +168,13 @@ 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 = ensureUserByEmail(identities, email, now);
+      const { user } = await linkOrProvision(identities, {
+        provider: "magic-link",
+        providerAccountId: email,
+        email,
+        emailVerified: true,
+        now: () => now,
+      });
       const issued = await issueSessionWithScopes(runtime.sessions, runtime.crypto, {
         id: user.id,
         plane: "user",

package/src/plugins/mcp-oauth.ts

@@ -0,0 +1,208 @@
+/**
+ * `mcpOauth` — hand-rolled OAuth 2.1 Authorization Server plugin for MCP.
+ *
+ * This is the ISSUER track, separate from the `oauth()` RP plugin (which
+ * consumes other IdPs for social sign-in). They share identity tables via
+ * gate.auth; they do not share token formats or endpoints.
+ *
+ * Locked decisions implemented here:
+ * - CIMD only (client_id is a metadata-document URL; no DCR)
+ * - DPoP required on every token grant (`cnf.jkt` on issued tokens)
+ * - RFC 8707 `resource` required on every authorize/token request,
+ *   matched against the canonical resource URI
+ * - Exact redirect_uri matching from fetched client metadata
+ * - Consent is a JSON Flow contract the app's own UI renders;
+ *   Console gets read-only audit only
+ *
+ * The AS crypto/JWKS module is dynamically imported at `.plug()` time so
+ * Store-only / non-MCP apps never pay for it (zero-cost when unplugged).
+ */
+
+import { field } from "../elements/store/schema-decl.ts";
+import { plugin, type PluginDef } from "../kernel/plugin.ts";
+
+/**
+ * Options for {@link mcpOauth}.
+ */
+export interface McpOauthOptions {
+  /** Issuer origin (e.g. `https://api.example.com`). */
+  readonly issuer: string;
+  /**
+   * Canonical RFC 8707 resource URI clients must request (the MCP RS
+   * origin/path). Every authorize/token request must match exactly.
+   */
+  readonly resource: string;
+  /** Refresh-token TTL (default 14 days). */
+  readonly refreshTtlMs?: number;
+  /** App consent screen path (default `/oauth/consent`). */
+  readonly consentPath?: string;
+  /** Injectable clock. */
+  readonly now?: () => number;
+  /** Injectable CIMD document fetch (tests / mock IdP). */
+  readonly fetchDoc?: (url: string) => Promise<unknown>;
+}
+
+/**
+ * Define the Authorization Server plugin.
+ *
+ * The plugin contributes the six `oke_oauth_*` tables and an edge handler
+ * serving: `/.well-known/oauth-authorization-server`,
+ * `/.well-known/oauth-protected-resource`, `/oauth/authorize`,
+ * `/oauth/token`, `/oauth/jwks`.
+ *
+ * Consent Flows are created with {@link mcpOauthConsentFlows} — bind them
+ * with session gates so the app's own consent screen can drive them over
+ * JSON; the framework never ships end-user HTML.
+ *
+ * @param options - Issuer/resource identity plus injectables
+ */
+export function mcpOauth(options: McpOauthOptions): PluginDef {
+  // Lazy: a static import would pin ES256/DPoP code on every app bundle.
+  const runtimePromise = import("../auth/oauth-as/http.ts").then((mod) =>
+    mod.createOauthAs({
+      issuer: options.issuer,
+      resource: options.resource,
+      stores: mod.createAsStores(),
+      ...(options.refreshTtlMs !== undefined ? { refreshTtlMs: options.refreshTtlMs } : {}),
+      ...(options.now !== undefined ? { now: options.now } : {}),
+      ...(options.fetchDoc !== undefined ? { fetchDoc: options.fetchDoc } : {}),
+      ...(options.consentPath !== undefined ? { consentPath: options.consentPath } : {}),
+    }),
+  );
+
+  const def = plugin("mcpOauth", {
+    version: "0.0.1",
+    config: { issuer: options.issuer, resource: options.resource },
+  })
+    .table("oke_oauth_signing_keys", signingKeyColumns(), { plane: "user" })
+    .table("oke_oauth_client_cache", cimdColumns(), { plane: "user" })
+    .table("oke_oauth_auth_codes", authCodeColumns(), { plane: "user" })
+    .table("oke_oauth_access_tokens", accessTokenColumns(), { plane: "user" })
+    .table("oke_oauth_refresh_tokens", refreshTokenColumns(), { plane: "user" })
+    .table("oke_oauth_consents", consentColumns(), {
+      plane: "user",
+      description: "OAuth consents — audit source for Console",
+    })
+    .edge((request, info) => runtimePromise.then((rt) => rt.edge(request, info)));
+
+  return def;
+}
+
+/**
+ * Create the three consent JSON Flows (`view` / `approve` / `deny`) against
+ * a resolved AS facade. The developer's SPA calls these over HTTP; each
+ * returns plain JSON — never HTML.
+ *
+ * @param facade - Resolved facade from {@link mcpOauth}'s lazy module
+ *   (`await import("okengine/auth/oauth-as/http").then(m => m.createOauthAs(...))`)
+ * @param userId - The signed-in gate.auth user id (session-gated Flow input)
+ */
+export function mcpOauthConsentFlows(facade: {
+  describeConsent(pendingId: string): {
+    clientId: string;
+    clientName: string | null;
+    scope: readonly string[];
+    resource: string;
+  };
+  approveConsent(pendingId: string, userId: string): Promise<{ redirectTo: string }>;
+  denyConsent(pendingId: string, userId: string): { redirectTo: string };
+}) {
+  const view = async (input: { pendingId: string }) => facade.describeConsent(input.pendingId);
+  const approve = async (input: { pendingId: string; userId: string }) =>
+    facade.approveConsent(input.pendingId, input.userId);
+  const deny = async (input: { pendingId: string; userId: string }) =>
+    facade.denyConsent(input.pendingId, input.userId);
+  return { view, approve, deny };
+}
+
+/* ------------------------------------------------------------------ */
+/* Column declarations (field.* builders)                              */
+/* ------------------------------------------------------------------ */
+
+/** Column shape of `oke_oauth_signing_keys`. */
+function signingKeyColumns() {
+  return {
+    kid: field.text().primaryKey(),
+    alg: field.text().notNull(),
+    public_jwk: field.text().notNull(),
+    private_key: field.text().notNull(),
+    active: field.integer().notNull(),
+    created_at: field.integer().notNull(),
+    rotated_at: field.integer(),
+  };
+}
+
+/** Column shape of `oke_oauth_client_cache`. */
+function cimdColumns() {
+  return {
+    client_id: field.text().primaryKey(),
+    metadata: field.text().notNull(),
+    fetched_at: field.integer().notNull(),
+    denied_at: field.integer(),
+  };
+}
+
+/** Column shape of `oke_oauth_auth_codes`. */
+function authCodeColumns() {
+  return {
+    id: field.text().primaryKey(),
+    code_hash: field.text().notNull(),
+    user_id: field.text().notNull(),
+    client_id: field.text().notNull(),
+    redirect_uri: field.text().notNull(),
+    resource: field.text().notNull(),
+    scope: field.text().notNull(),
+    code_challenge: field.text().notNull(),
+    code_challenge_method: field.text().notNull(),
+    jkt: field.text(),
+    expires_at: field.integer().notNull(),
+    consumed_at: field.integer(),
+    created_at: field.integer().notNull(),
+  };
+}
+
+/** Column shape of `oke_oauth_access_tokens`. */
+function accessTokenColumns() {
+  return {
+    jti: field.text().primaryKey(),
+    user_id: field.text().notNull(),
+    client_id: field.text().notNull(),
+    resource: field.text().notNull(),
+    scope: field.text().notNull(),
+    jkt: field.text(),
+    expires_at: field.integer().notNull(),
+    revoked_at: field.integer(),
+    created_at: field.integer().notNull(),
+  };
+}
+
+/** Column shape of `oke_oauth_refresh_tokens`. */
+function refreshTokenColumns() {
+  return {
+    id: field.text().primaryKey(),
+    family_id: field.text().notNull(),
+    user_id: field.text().notNull(),
+    client_id: field.text().notNull(),
+    resource: field.text().notNull(),
+    scope: field.text().notNull(),
+    jkt: field.text(),
+    hash: field.text().notNull(),
+    expires_at: field.integer().notNull(),
+    used_at: field.integer(),
+    revoked_at: field.integer(),
+  };
+}
+
+/** Column shape of `oke_oauth_consents`. */
+function consentColumns() {
+  return {
+    user_id: field.text().notNull(),
+    client_id: field.text().notNull(),
+    client_name: field.text(),
+    resource: field.text().notNull(),
+    scope: field.text().notNull(),
+    granted_at: field.integer().notNull(),
+    updated_at: field.integer().notNull(),
+    revoked_at: field.integer(),
+  };
+}