okengine 0.16.0 → 0.17.0

package/src/auth/tenant-tables.ts

@@ -0,0 +1,11 @@
+/**
+ * Tenant registry table names — kept off AUTH_TABLES so Store-only graphs
+ * that already ship `oke_api_keys` do not also pin `oke_tenants`.
+ */
+
+/** Opt-in via `gate.auth.tenant`. */
+export const AUTH_TENANT_TABLES = {
+  tenants: "oke_tenants",
+  tenantMembers: "oke_tenant_members",
+  tenantRoles: "oke_tenant_roles",
+} as const;

package/src/auth/tenants.test.ts

@@ -0,0 +1,63 @@
+/**
+ * Tenant registry — user-plane catalog on write; membership helpers.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { isApplicationScope } from "../elements/gate/permissions.ts";
+import {
+  createTenant,
+  createTenantStore,
+  tenantRoleScopeFailure,
+  upsertTenantRole,
+} from "./tenants.ts";
+
+describe("tenantRoleScopeFailure", () => {
+  const catalog = ["booking:create", "member", "console:store.sql:write", "console:*"];
+
+  test("unknown names and console:* fail the same way", () => {
+    const invented = tenantRoleScopeFailure(["this:was:never:declared"], catalog);
+    const consoleWrite = tenantRoleScopeFailure(["console:store.sql:write"], catalog);
+    const consoleStar = tenantRoleScopeFailure(["console:*"], catalog);
+    expect(invented?.reason).toBe("unknown_scope");
+    expect(consoleWrite?.reason).toBe("unknown_scope");
+    expect(consoleStar?.reason).toBe("unknown_scope");
+    expect(isApplicationScope("console:store.sql:write")).toBe(false);
+    expect(isApplicationScope("console:*")).toBe(false);
+  });
+
+  test("application catalog names are grantable", () => {
+    expect(tenantRoleScopeFailure(["booking:create", "member"], catalog)).toBeNull();
+  });
+});
+
+describe("upsertTenantRole", () => {
+  test("console-shaped upsert throws like an invented name", async () => {
+    const store = createTenantStore();
+    await createTenant(store, { name: "Acme", createdBy: "u1", id: "t1" });
+    const catalog = ["booking:create", "console:store.sql:write", "console:*"];
+    expect(() =>
+      upsertTenantRole(store, {
+        tenantId: "t1",
+        roleName: "admin",
+        scopes: ["console:store.sql:write"],
+        catalog,
+      }),
+    ).toThrow(/unknown or operator-plane scope/);
+    expect(() =>
+      upsertTenantRole(store, {
+        tenantId: "t1",
+        roleName: "admin",
+        scopes: ["console:*"],
+        catalog,
+      }),
+    ).toThrow(/unknown or operator-plane scope/);
+    expect(() =>
+      upsertTenantRole(store, {
+        tenantId: "t1",
+        roleName: "admin",
+        scopes: ["this:was:never:declared"],
+        catalog,
+      }),
+    ).toThrow(/unknown or operator-plane scope/);
+  });
+});

package/src/auth/tenants.ts

@@ -0,0 +1,360 @@
+/**
+ * Built-in tenant registry + N:N membership + tenant-scoped roles.
+ *
+ * Opt-in via `gate.auth.tenant`. Not an organizations product — no
+ * invitations UI, billing, or admin portal.
+ */
+
+import { isApplicationScope } from "../elements/gate/permissions.ts";
+import type { TenantMemberRow, TenantRoleRow, TenantRow } from "./tables.ts";
+
+export type { TenantMemberRow, TenantRoleRow, TenantRow };
+
+/** Capability / Manifest resource for `fx.auth` tenant methods. */
+export const AUTH_TENANTS_RESOURCE = "auth:tenants";
+
+/** Tenant registry / membership / role error. */
+export class TenantError extends Error {
+  readonly reason: string;
+  readonly scope?: string;
+
+  /**
+   * @param reason - Stable reason token
+   * @param message - Diagnostic
+   * @param scope - Illegal scope name when `unknown_scope`
+   */
+  constructor(reason: string, message: string, scope?: string) {
+    super(message);
+    this.name = "TenantError";
+    this.reason = reason;
+    if (scope !== undefined) this.scope = scope;
+  }
+}
+
+/** Default member role name until a mapping exists. */
+export const DEFAULT_TENANT_ROLE = "member";
+
+/** Lifecycle hooks for Clock per-tenant row expansion. */
+export interface TenantStoreHooks {
+  readonly onCreate?: (tenant: TenantRow) => void | Promise<void>;
+  readonly onDelete?: (tenant: TenantRow) => void | Promise<void>;
+}
+
+/** In-memory tenant store. */
+export interface TenantStore {
+  tenants: Map<string, TenantRow>;
+  members: Map<string, TenantMemberRow>;
+  roles: Map<string, TenantRoleRow>;
+  hooks?: TenantStoreHooks;
+}
+
+/**
+ * Create an empty tenant store.
+ *
+ * @param hooks - Optional create/delete hooks (Clock expansion)
+ */
+export function createTenantStore(hooks?: TenantStoreHooks): TenantStore {
+  return {
+    tenants: new Map(),
+    members: new Map(),
+    roles: new Map(),
+    ...(hooks !== undefined ? { hooks } : {}),
+  };
+}
+
+function memberKey(tenantId: string, userId: string): string {
+  return `${tenantId}:${userId}`;
+}
+
+function roleKey(tenantId: string, roleName: string): string {
+  return `${tenantId}:${roleName}`;
+}
+
+/** Public tenant row returned by `fx.auth.listTenants`. */
+export interface TenantPublicRow {
+  readonly id: string;
+  readonly name: string;
+  readonly slug: string | null;
+  readonly role: string;
+}
+
+/** Options for {@link createTenant}. */
+export interface CreateTenantOptions {
+  readonly name: string;
+  readonly createdBy: string;
+  readonly slug?: string | null;
+  readonly id?: string;
+  readonly now?: () => number;
+}
+
+/**
+ * Create a tenant and add the creator as a member.
+ *
+ * @param store - Tenant store
+ * @param options - Name / creator / optional id
+ */
+export async function createTenant(
+  store: TenantStore,
+  options: CreateTenantOptions,
+): Promise<TenantRow> {
+  const now = options.now ?? (() => Date.now());
+  const t = now();
+  const id = options.id ?? crypto.randomUUID();
+  if (store.tenants.has(id)) {
+    throw new TenantError("tenant_exists", `tenant already exists: ${id}`);
+  }
+  const slug = options.slug ?? null;
+  if (slug) {
+    for (const row of store.tenants.values()) {
+      if (row.slug === slug) {
+        throw new TenantError("slug_taken", `tenant slug already taken: ${slug}`);
+      }
+    }
+  }
+  const row: TenantRow = {
+    id,
+    name: options.name,
+    slug,
+    createdAt: t,
+    createdBy: options.createdBy,
+  };
+  store.tenants.set(id, row);
+  addMember(store, {
+    tenantId: id,
+    userId: options.createdBy,
+    role: DEFAULT_TENANT_ROLE,
+    now,
+  });
+  await store.hooks?.onCreate?.(row);
+  return row;
+}
+
+/**
+ * Delete a tenant, its memberships, and its custom roles.
+ *
+ * @param store - Tenant store
+ * @param id - Tenant id
+ */
+export async function deleteTenant(store: TenantStore, id: string): Promise<TenantRow | undefined> {
+  const row = store.tenants.get(id);
+  if (!row) return undefined;
+  store.tenants.delete(id);
+  for (const [key, member] of [...store.members.entries()]) {
+    if (member.tenantId === id) store.members.delete(key);
+  }
+  for (const [key, role] of [...store.roles.entries()]) {
+    if (role.tenantId === id) store.roles.delete(key);
+  }
+  await store.hooks?.onDelete?.(row);
+  return row;
+}
+
+/** Options for {@link addMember}. */
+export interface AddMemberOptions {
+  readonly tenantId: string;
+  readonly userId: string;
+  readonly role?: string;
+  readonly id?: string;
+  readonly now?: () => number;
+}
+
+/**
+ * Add a membership (idempotent on tenant+user).
+ *
+ * @param store - Tenant store
+ * @param options - Membership fields
+ */
+export function addMember(store: TenantStore, options: AddMemberOptions): TenantMemberRow {
+  if (!store.tenants.has(options.tenantId)) {
+    throw new TenantError("unknown_tenant", `unknown tenant: ${options.tenantId}`);
+  }
+  const key = memberKey(options.tenantId, options.userId);
+  const existing = store.members.get(key);
+  if (existing) {
+    if (options.role !== undefined && options.role !== existing.role) {
+      const next: TenantMemberRow = { ...existing, role: options.role };
+      store.members.set(key, next);
+      return next;
+    }
+    return existing;
+  }
+  const now = options.now ?? (() => Date.now());
+  const row: TenantMemberRow = {
+    id: options.id ?? crypto.randomUUID(),
+    tenantId: options.tenantId,
+    userId: options.userId,
+    role: options.role ?? DEFAULT_TENANT_ROLE,
+    createdAt: now(),
+  };
+  store.members.set(key, row);
+  return row;
+}
+
+/**
+ * Remove a membership.
+ *
+ * @param store - Tenant store
+ * @param tenantId - Tenant id
+ * @param userId - User id
+ */
+export function removeMember(
+  store: TenantStore,
+  tenantId: string,
+  userId: string,
+): TenantMemberRow | undefined {
+  const key = memberKey(tenantId, userId);
+  const row = store.members.get(key);
+  if (!row) return undefined;
+  store.members.delete(key);
+  return row;
+}
+
+/**
+ * Look up one membership.
+ *
+ * @param store - Tenant store
+ * @param tenantId - Tenant id
+ * @param userId - User id
+ */
+export function getMember(
+  store: TenantStore,
+  tenantId: string,
+  userId: string,
+): TenantMemberRow | undefined {
+  return store.members.get(memberKey(tenantId, userId));
+}
+
+/**
+ * Whether `userId` is a member of `tenantId`.
+ *
+ * @param store - Tenant store
+ * @param tenantId - Tenant id
+ * @param userId - User id
+ */
+export function isMember(store: TenantStore, tenantId: string, userId: string): boolean {
+  return store.members.has(memberKey(tenantId, userId));
+}
+
+/**
+ * List memberships for a user (for `listTenants`).
+ *
+ * @param store - Tenant store
+ * @param userId - User id
+ */
+export function listTenantsForUser(store: TenantStore, userId: string): TenantPublicRow[] {
+  const out: TenantPublicRow[] = [];
+  for (const member of store.members.values()) {
+    if (member.userId !== userId) continue;
+    const tenant = store.tenants.get(member.tenantId);
+    if (!tenant) continue;
+    out.push({
+      id: tenant.id,
+      name: tenant.name,
+      slug: tenant.slug,
+      role: member.role,
+    });
+  }
+  return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * List members of a tenant.
+ *
+ * @param store - Tenant store
+ * @param tenantId - Tenant id
+ */
+export function listMembers(store: TenantStore, tenantId: string): TenantMemberRow[] {
+  const out: TenantMemberRow[] = [];
+  for (const member of store.members.values()) {
+    if (member.tenantId === tenantId) out.push(member);
+  }
+  return out.sort((a, b) => a.userId.localeCompare(b.userId));
+}
+
+/**
+ * All tenant ids currently in the store (Clock reconcile expansion).
+ *
+ * @param store - Tenant store
+ */
+export function listTenantIds(store: TenantStore): string[] {
+  return [...store.tenants.keys()].sort();
+}
+
+/** Options for {@link upsertTenantRole}. */
+export interface UpsertTenantRoleOptions {
+  readonly tenantId: string;
+  readonly roleName: string;
+  readonly scopes: readonly string[];
+  readonly catalog: readonly string[];
+  readonly now?: () => number;
+}
+
+/**
+ * Validate scopes against the Manifest-derived **user-plane** catalog.
+ *
+ * Unknown names and `console:*` / `console:…` fail the same way.
+ *
+ * @param scopes - Requested scope names
+ * @param catalog - `deriveModuleActions(manifest)`
+ * @returns Failure when any name is illegal; `null` when all are grantable
+ */
+export function tenantRoleScopeFailure(
+  scopes: readonly string[],
+  catalog: readonly string[],
+): TenantError | null {
+  const allowed = new Set(catalog.filter(isApplicationScope));
+  for (const scope of scopes) {
+    if (!allowed.has(scope)) {
+      return new TenantError("unknown_scope", `unknown or operator-plane scope: ${scope}`, scope);
+    }
+  }
+  return null;
+}
+
+/**
+ * Create or replace a tenant role mapping.
+ *
+ * @param store - Tenant store
+ * @param options - Role + catalog
+ */
+export function upsertTenantRole(
+  store: TenantStore,
+  options: UpsertTenantRoleOptions,
+): TenantRoleRow {
+  if (!store.tenants.has(options.tenantId)) {
+    throw new TenantError("unknown_tenant", `unknown tenant: ${options.tenantId}`);
+  }
+  const denied = tenantRoleScopeFailure(options.scopes, options.catalog);
+  if (denied) throw denied;
+  const now = options.now ?? (() => Date.now());
+  const t = now();
+  const key = roleKey(options.tenantId, options.roleName);
+  const prev = store.roles.get(key);
+  const row: TenantRoleRow = {
+    tenantId: options.tenantId,
+    roleName: options.roleName,
+    scopes: [...options.scopes],
+    createdAt: prev?.createdAt ?? t,
+    updatedAt: t,
+  };
+  store.roles.set(key, row);
+  return row;
+}
+
+/**
+ * Expand a member's tenant role into application scopes.
+ *
+ * @param store - Tenant store
+ * @param tenantId - Tenant id
+ * @param userId - User id
+ */
+export function tenantScopesForMember(
+  store: TenantStore,
+  tenantId: string,
+  userId: string,
+): readonly string[] {
+  const member = getMember(store, tenantId, userId);
+  if (!member) return [];
+  const role = store.roles.get(roleKey(tenantId, member.role));
+  return role?.scopes ?? [];
+}

package/src/cli/build.ts

@@ -44,7 +44,7 @@ async function defaultSyncAdoptBarrel(rootDir: string): Promise<readonly string[
 }
 
 /**
- * Build a deployable bundle. Edge target aims at the &lt;15 kB kernel budget.
+ * Build a deployable bundle. Edge target aims at the &lt;16 kB kernel budget.
  *
  * @param options - Target / entry
  */
@@ -109,7 +109,7 @@ export async function buildCli(args: readonly string[]): Promise<number> {
     else if (a === "--help" || a === "-h") {
       console.log(`oke build [--target|-t bun|node|edge] [--entry|-e src/app.ts]
 
-Tree-shaken bundle. --target edge aims at the <15 kB kernel budget.
+Tree-shaken bundle. --target edge aims at the <16 kB kernel budget.
 `);
       return 0;
     }

package/src/client/budget.test.ts

@@ -1,6 +1,6 @@
 /**
  * Client runtime budget — AGENTS.md / unified-theory §24.
- * Limit: < 3 kB gzipped (minified bundle).
+ * Limit: gzipped minified bundle under {@link CLIENT_BUDGET_BYTES}.
  */
 
 import { describe, expect, test } from "bun:test";

package/src/client/create.ts

@@ -14,7 +14,22 @@
 
 import { createTransport, type Transport } from "./transport.ts";
 import { asThenableIterable, attachPager } from "./pager.ts";
-import type { Client, ClientOptions, ClientRouteMap, ResolveApp } from "./types.ts";
+import {
+  flattenLiveRoutes,
+  isLiveHandlers,
+  pickLiveExposure,
+  subscribeLive,
+  type LiveByFlow,
+  type LiveRouteTable,
+} from "./live.ts";
+import type {
+  Client,
+  ClientLive,
+  ClientOptions,
+  ClientRouteMap,
+  LiveHandlers,
+  ResolveApp,
+} from "./types.ts";
 
 /** App-shaped value that carries a runtime `$routes` table from typed adopt. */
 export interface AppWithRoutes {
@@ -80,10 +95,23 @@ export function createClient(
 function buildClient(url: string, opts: ClientOptions = {}): Client {
   const base = url.replace(/\/+$/, "");
   const routes = opts.routes ?? flattenRoutes(opts.$routes);
+  const live = flattenLiveRoutes(opts.$routes);
   const transport = createTransport(base, { ...opts, routes });
-  return proxy(transport, []) as Client;
+  return proxy(transport, [], {
+    base,
+    opts,
+    liveBySignal: live.bySignal,
+    liveByFlow: live.byFlow,
+  }) as Client;
 }
 
+type ProxyCtx = {
+  readonly base: string;
+  readonly opts: ClientOptions;
+  readonly liveBySignal: LiveRouteTable;
+  readonly liveByFlow: LiveByFlow;
+};
+
 /**
  * Flatten `app.$routes` into the transport REST table (`unit.flow` → method/path).
  * Entries without both method and path are omitted (RPC fallback).
@@ -115,7 +143,7 @@ export function flattenRoutes(
  * @param transport - HTTP transport
  * @param path - Accumulated property path
  */
-function proxy(transport: Transport, path: readonly string[]): unknown {
+function proxy(transport: Transport, path: readonly string[], ctx: ProxyCtx): unknown {
   const invoke = async (input?: unknown) => {
     if (path.length < 2) {
       return attachPager(
@@ -137,7 +165,18 @@ function proxy(transport: Transport, path: readonly string[]): unknown {
     const result = await transport.call(`${unit}/${flow}`, input);
     return attachPager(result, invoke, input);
   };
-  const call = (input?: unknown) => asThenableIterable(invoke, input);
+  const call = (a?: unknown, b?: unknown) => {
+    if (path.length >= 2) {
+      const key = `${path[0]}.${path.slice(1).join(".")}`;
+      const exposure = ctx.liveByFlow[key];
+      if (exposure && (isLiveHandlers(a) || isLiveHandlers(b))) {
+        const handlers = (isLiveHandlers(a) ? a : b) as LiveHandlers<unknown>;
+        const input = isLiveHandlers(a) ? undefined : a;
+        return subscribeLive(ctx.base, exposure, input, handlers, ctx.opts);
+      }
+    }
+    return asThenableIterable(invoke, a);
+  };
 
   return new Proxy(call, {
     get(_target, prop, receiver) {
@@ -145,7 +184,38 @@ function proxy(transport: Transport, path: readonly string[]): unknown {
         return Reflect.get(_target, prop, receiver);
       }
       if (prop === "then") return undefined;
-      return proxy(transport, [...path, prop]);
+      if (path.length === 0 && prop === "live") {
+        return makeLive(ctx);
+      }
+      return proxy(transport, [...path, prop], ctx);
     },
   });
 }
+
+function makeLive(ctx: ProxyCtx): ClientLive {
+  return ((signalOrName: unknown, inputOrHandlers: unknown, maybeHandlers?: unknown) => {
+    const name =
+      typeof signalOrName === "string"
+        ? signalOrName
+        : signalOrName !== null &&
+            typeof signalOrName === "object" &&
+            "name" in signalOrName &&
+            typeof (signalOrName as { name: unknown }).name === "string"
+          ? (signalOrName as { name: string }).name
+          : undefined;
+    if (!name) throw new Error("api.live requires a signal handle or name");
+    const handlers = isLiveHandlers(inputOrHandlers)
+      ? inputOrHandlers
+      : isLiveHandlers(maybeHandlers)
+        ? maybeHandlers
+        : undefined;
+    if (!handlers) throw new Error("api.live requires handlers with onEvent");
+    const input = isLiveHandlers(inputOrHandlers) ? undefined : inputOrHandlers;
+    const exposures = ctx.liveBySignal[name] ?? [];
+    if (exposures.length === 0) {
+      throw new Error(`No live HTTP exposure for signal "${name}"`);
+    }
+    const exposure = pickLiveExposure(exposures, input, handlers.via);
+    return subscribeLive(ctx.base, exposure, input, handlers, ctx.opts);
+  }) as ClientLive;
+}

package/src/client/index.ts

@@ -5,6 +5,14 @@
  * @module
  */
 
+export {
+  flattenLiveRoutes,
+  isLiveHandlers,
+  LIVE_RESUBSCRIBE_INITIAL_MS,
+  LIVE_RESUBSCRIBE_MAX_MS,
+  nextResubscribeDelay,
+  pickLiveExposure,
+} from "./live.ts";
 export { createClient, flattenRoutes } from "./create.ts";
 export type { AppWithRoutes } from "./create.ts";
 export { isErrorCode, isFail, isOk, isTransportError } from "./errors.ts";
@@ -29,7 +37,12 @@ export type {
   ClientResult,
   ClientThenableIterable,
   ClientRouteMap,
+  ClientLive,
   FlowContract,
+  LiveHandlers,
+  LiveInput,
+  LiveSignalHandle,
+  LiveUnsubscribe,
   Register,
   ResolveApp,
   RoutesOf,