okengine 0.1.4

package/src/auth/api-keys.ts

@@ -0,0 +1,168 @@
+/**
+ * API keys are first-class principals with attenuation.
+ *
+ * A key can never exceed the permissions of whoever created it.
+ * The raw secret is returned exactly once on create / rotate.
+ *
+ * @see docs/spec/console.md §3.3 · §9.14
+ */
+
+import { assertAttenuated } from "./attenuation.ts";
+import type { AuthPlane } from "./planes.ts";
+import type { ApiKeyRow } from "./tables.ts";
+
+/** Options when creating an API key. */
+export interface CreateApiKeyOptions {
+  readonly plane: AuthPlane;
+  readonly name: string;
+  readonly scopes: readonly string[];
+  readonly creatorId: string;
+  /** Creator's full scope set — attenuation ceiling. */
+  readonly creatorScopes: ReadonlySet<string> | Iterable<string>;
+  readonly expiresAt?: number | null;
+  readonly rateLimit?: { max: number; per: string } | null;
+  readonly ipAllowlist?: readonly string[];
+  /** Injectable id / secret / hash (tests). */
+  readonly id?: string;
+  readonly secret?: string;
+  readonly hash?: string;
+  readonly now?: () => number;
+}
+
+/** Result of key creation — secret shown exactly once. */
+export interface CreatedApiKey {
+  readonly row: ApiKeyRow;
+  /** Raw secret — shown exactly once. */
+  readonly secret: string;
+}
+
+/** In-memory API key store. */
+export interface ApiKeyStore {
+  keys: Map<string, ApiKeyRow>;
+}
+
+/**
+ * Create an empty API key store.
+ */
+export function createApiKeyStore(): ApiKeyStore {
+  return { keys: new Map() };
+}
+
+/**
+ * Hash an API key secret (SHA-256 hex).
+ *
+ * @param secret - Raw secret
+ */
+export async function hashApiKeySecret(secret: string): Promise<string> {
+  const bytes = new TextEncoder().encode(secret);
+  const digest = await crypto.subtle.digest("SHA-256", bytes);
+  return [...new Uint8Array(digest)]
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+/**
+ * Create an API key attenuated to the creator's scopes.
+ *
+ * @param store - Key store
+ * @param options - Key fields + creator ceiling
+ */
+export async function createApiKey(
+  store: ApiKeyStore,
+  options: CreateApiKeyOptions,
+): Promise<CreatedApiKey> {
+  assertAttenuated(options.creatorScopes, options.scopes, "api key");
+
+  const now = options.now ?? (() => Date.now());
+  const id = options.id ?? crypto.randomUUID();
+  const secret = options.secret ?? `oke_${id.replace(/-/g, "")}_${randomSecret()}`;
+  const hash = options.hash ?? (await hashApiKeySecret(secret));
+  const creatorScopes = [...options.creatorScopes];
+
+  const row: ApiKeyRow = {
+    id,
+    plane: options.plane,
+    hash,
+    name: options.name,
+    scopes: [...options.scopes],
+    expiresAt: options.expiresAt ?? null,
+    rateLimit: options.rateLimit ?? null,
+    ipAllowlist: [...(options.ipAllowlist ?? [])],
+    creatorId: options.creatorId,
+    creatorScopes,
+    createdAt: now(),
+    lastUsedAt: null,
+    revokedAt: null,
+  };
+  store.keys.set(id, row);
+  return { row, secret };
+}
+
+/**
+ * Resolve a key by raw secret; enforces expiry and revocation.
+ *
+ * @param store - Key store
+ * @param secret - Raw secret
+ * @param now - Clock
+ */
+export async function authenticateApiKey(
+  store: ApiKeyStore,
+  secret: string,
+  now: () => number = () => Date.now(),
+): Promise<ApiKeyRow | null> {
+  const hash = await hashApiKeySecret(secret);
+  for (const row of store.keys.values()) {
+    if (row.hash !== hash) continue;
+    if (row.revokedAt !== null) return null;
+    if (row.expiresAt !== null && row.expiresAt <= now()) return null;
+    row.lastUsedAt = now();
+    return row;
+  }
+  return null;
+}
+
+/**
+ * Revoke an API key — irreversible. The row remains for audit / hygiene.
+ *
+ * @param store - Key store
+ * @param id - Key id
+ * @param now - Clock
+ */
+export function revokeApiKey(
+  store: ApiKeyStore,
+  id: string,
+  now: () => number = () => Date.now(),
+): ApiKeyRow | null {
+  const row = store.keys.get(id);
+  if (!row || row.revokedAt !== null) return null;
+  row.revokedAt = now();
+  return row;
+}
+
+/**
+ * Rotate an API key secret — new value shown exactly once; old hash dies.
+ *
+ * @param store - Key store
+ * @param id - Key id
+ * @param options - Optional secret override / clock
+ */
+export async function rotateApiKey(
+  store: ApiKeyStore,
+  id: string,
+  options: {
+    readonly secret?: string;
+    readonly now?: () => number;
+  } = {},
+): Promise<CreatedApiKey | null> {
+  const row = store.keys.get(id);
+  if (!row || row.revokedAt !== null) return null;
+  const secret =
+    options.secret ?? `oke_${id.replace(/-/g, "")}_${randomSecret()}`;
+  row.hash = await hashApiKeySecret(secret);
+  return { row, secret };
+}
+
+function randomSecret(): string {
+  const bytes = crypto.getRandomValues(new Uint8Array(24));
+  return [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");
+}

package/src/auth/attenuation.ts

@@ -0,0 +1,116 @@
+/**
+ * Attenuation — a derived principal can never exceed its creator.
+ *
+ * Applies to API keys and `invoke-as` exactly the same way.
+ *
+ * @see docs/spec/console.md §3.3 · §10.4
+ */
+
+/** Result of an attenuation check. */
+export interface AttenuationResult {
+  readonly ok: boolean;
+  /** Scopes the creator lacks (empty when ok). */
+  readonly excess: readonly string[];
+}
+
+/**
+ * Expand held scopes against a catalog — `console:*` covers every
+ * `console:…` pair in the catalog (Access · MCP inheritance).
+ *
+ * @param held - Raw scopes from the principal / session
+ * @param catalog - Manifest-derived Module:Action pairs
+ */
+export function expandHeldScopes(
+  held: Iterable<string>,
+  catalog: readonly string[],
+): Set<string> {
+  const out = new Set<string>();
+  let star = false;
+  for (const s of held) {
+    out.add(s);
+    if (s === "console:*") star = true;
+  }
+  if (star) {
+    for (const scope of catalog) {
+      if (scope.startsWith("console:")) out.add(scope);
+    }
+  }
+  return out;
+}
+
+/**
+ * Whether `requested` is a subset of `creator` scopes.
+ *
+ * @param creatorScopes - Creator's Module:Action set
+ * @param requestedScopes - Requested scopes for the derived principal
+ */
+export function attenuateScopes(
+  creatorScopes: ReadonlySet<string> | Iterable<string>,
+  requestedScopes: Iterable<string>,
+): AttenuationResult {
+  const creator =
+    creatorScopes instanceof Set ? creatorScopes : new Set(creatorScopes);
+  const excess: string[] = [];
+  for (const scope of requestedScopes) {
+    if (!creator.has(scope)) excess.push(scope);
+  }
+  return { ok: excess.length === 0, excess };
+}
+
+/**
+ * Scopes a principal may grant on a plane — intersection of catalog,
+ * plane membership, and {@link attenuateScopes} against the expanded
+ * ceiling. Impossibility is taught by absence (console §9.14).
+ *
+ * @param options - Held scopes, catalog, plane predicate
+ */
+export function grantableScopes(options: {
+  readonly held: Iterable<string>;
+  readonly catalog: readonly string[];
+  readonly planeOf: (scope: string) => "user" | "operator";
+  readonly plane: "user" | "operator";
+}): string[] {
+  const ceiling = expandHeldScopes(options.held, options.catalog);
+  return options.catalog
+    .filter((scope) => {
+      if (options.planeOf(scope) !== options.plane) return false;
+      return attenuateScopes(ceiling, [scope]).ok;
+    })
+    .sort((a, b) => a.localeCompare(b));
+}
+
+/**
+ * Assert attenuation; throw when the key/invoke-as would escalate.
+ *
+ * @param creatorScopes - Creator scopes
+ * @param requestedScopes - Requested scopes
+ * @param label - Error label (`api key` / `invoke-as`)
+ */
+export function assertAttenuated(
+  creatorScopes: ReadonlySet<string> | Iterable<string>,
+  requestedScopes: Iterable<string>,
+  label = "principal",
+): void {
+  const result = attenuateScopes(creatorScopes, requestedScopes);
+  if (!result.ok) {
+    throw new AttenuationError(
+      `${label} cannot exceed creator scopes; missing: ${result.excess.join(", ")}`,
+      result.excess,
+    );
+  }
+}
+
+/** Privilege-escalation attempt via key or invoke-as. */
+export class AttenuationError extends Error {
+  readonly excess: readonly string[];
+
+  /**
+   * @param message - Diagnostic
+   * @param excess - Scopes the creator lacks
+   */
+  constructor(message: string, excess: readonly string[]) {
+    super(message);
+    this.name = "AttenuationError";
+    this.excess = excess;
+  }
+}

package/src/auth/auth.test.ts

@@ -0,0 +1,273 @@
+/**
+ * Auth acceptance:
+ * - API key cannot exceed creator scopes
+ * - cross-plane: application principal → console flow is a compile error
+ * - hybrid sessions rotate refresh tokens with reuse detection
+ * - operator local credential cannot be removed; SSO is additive
+ * - invoke-as attenuated like an API key
+ * - roles are data
+ */
+
+import { describe, expect, test } from "bun:test";
+import type { Manifest } from "../manifest/types.ts";
+import {
+  assertAttenuated,
+  assertCrossPlane,
+  AttenuationError,
+  authenticateOperator,
+  auth,
+  checkCrossPlane,
+  createApiKey,
+  createApiKeyStore,
+  createOperator,
+  createOperatorStore,
+  createRoleStore,
+  createSessionStore,
+  CrossPlaneError,
+  invokeAs,
+  issueSessionWithScopes,
+  linkOperatorSso,
+  removeOperatorCredential,
+  rotateRefresh,
+  setRoleGrants,
+  scopesForRoles,
+  SessionError,
+  upsertRole,
+  userPrincipal,
+  assertPlaneAccess,
+} from "./index.ts";
+
+describe("auth plugin", () => {
+  test("registers oke_ tables on both planes", () => {
+    const tables: string[] = [];
+    auth({ secret: "test" }).register({
+      hook() { return this; },
+      decorate() { return this; },
+      element() { return this; },
+      needs() { return this; },
+      errors() { return this; },
+      consolePanel() { return this; },
+      cli() { return this; },
+      driver() { return this; },
+      image() { return this; },
+      table(name) {
+        tables.push(name);
+        return this;
+      },
+      flow() { return this; },
+      client() { return this; },
+      config() { return this; },
+    });
+    expect(tables).toContain("oke_operators");
+    expect(tables).toContain("oke_operator_credentials");
+    expect(tables).toContain("oke_identities");
+    expect(tables).toContain("oke_api_keys");
+    expect(tables).toContain("oke_refresh_tokens");
+  });
+});
+
+describe("API key attenuation", () => {
+  test("key cannot be created with a scope its creator lacks", async () => {
+    const store = createApiKeyStore();
+    const creatorScopes = new Set(["bookings:create", "bookings:list"]);
+
+    await expect(
+      createApiKey(store, {
+        plane: "user",
+        name: "escalated",
+        scopes: ["bookings:create", "admin:all"],
+        creatorId: "u1",
+        creatorScopes,
+      }),
+    ).rejects.toBeInstanceOf(AttenuationError);
+
+    const ok = await createApiKey(store, {
+      plane: "user",
+      name: "ok",
+      scopes: ["bookings:list"],
+      creatorId: "u1",
+      creatorScopes,
+    });
+    expect(ok.row.scopes).toEqual(["bookings:list"]);
+    expect(ok.secret.startsWith("oke_")).toBe(true);
+    expect(ok.row.createdAt).toBeGreaterThan(0);
+    expect(ok.row.revokedAt).toBeNull();
+  });
+
+  test("revoke and rotate — secret once on rotate", async () => {
+    const { revokeApiKey, rotateApiKey } = await import("./api-keys.ts");
+    const store = createApiKeyStore();
+    const created = await createApiKey(store, {
+      plane: "user",
+      name: "rot",
+      scopes: ["bookings:list"],
+      creatorId: "u1",
+      creatorScopes: ["bookings:list"],
+    });
+    const rotated = await rotateApiKey(store, created.row.id);
+    expect(rotated?.secret).toBeTruthy();
+    expect(rotated?.secret).not.toBe(created.secret);
+    const revoked = revokeApiKey(store, created.row.id);
+    expect(revoked?.revokedAt).not.toBeNull();
+    expect(await rotateApiKey(store, created.row.id)).toBeNull();
+  });
+});
+
+describe("cross-plane compile error", () => {
+  test("application principal reaching a console flow is a compile error", () => {
+    const manifest: Manifest = {
+      oke: "1.0",
+      app: "skyport",
+      flows: {
+        "bookings.create": { plane: "user", effects: { calls: ["console.store.query"] } },
+        "console.store.query": { plane: "operator" },
+      },
+    };
+
+    const diags = checkCrossPlane(manifest, [
+      {
+        path: "src/flows/console/store.ts",
+        flow: "console.store.query",
+        source: `
+          export const query = flow({
+            name: "console.store.query",
+            plane: "operator",
+            do: (_i, fx) => fx.auth.userId,
+          });
+        `,
+      },
+    ]);
+
+    expect(diags.some((d) => d.message.includes("fx.auth"))).toBe(true);
+    expect(diags.some((d) => d.message.includes("cross-plane call"))).toBe(true);
+
+    expect(() => assertCrossPlane(manifest, [
+      {
+        path: "x.ts",
+        flow: "console.store.query",
+        source: `plane: "operator"; fx.auth.userId`,
+      },
+    ])).toThrow(CrossPlaneError);
+
+    const user = userPrincipal({ userId: "u1", scopes: ["bookings:create"] });
+    expect(() => assertPlaneAccess(user, "operator")).toThrow(CrossPlaneError);
+  });
+});
+
+describe("hybrid sessions", () => {
+  test("rotate refresh tokens with reuse detection", async () => {
+    const store = createSessionStore();
+    let now = 1_000_000;
+    const crypto = { secret: "test-secret", now: () => now };
+
+    const issued = await issueSessionWithScopes(store, crypto, {
+      id: "user-1",
+      plane: "user",
+      scopes: ["bookings:create"],
+    });
+
+    now += 1_000;
+    const rotated = await rotateRefresh(store, crypto, issued.refreshToken);
+    expect(rotated.refreshToken).not.toBe(issued.refreshToken);
+    expect(rotated.accessToken).not.toBe(issued.accessToken);
+
+    // Reuse of the old refresh token revokes the family.
+    await expect(
+      rotateRefresh(store, crypto, issued.refreshToken),
+    ).rejects.toMatchObject({ name: "SessionError" });
+
+    // Family revoked — the rotated refresh is also dead.
+    await expect(
+      rotateRefresh(store, crypto, rotated.refreshToken),
+    ).rejects.toBeInstanceOf(SessionError);
+  });
+});
+
+describe("operator plane", () => {
+  test("local credential cannot be removed; SSO is additive", async () => {
+    const store = createOperatorStore();
+    const op = await createOperator(store, {
+      email: "ops@example.com",
+      name: "Ops",
+      password: "correct horse battery staple",
+    });
+
+    expect(store.credentials.has(op.id)).toBe(true);
+    expect(() => removeOperatorCredential(store, op.id)).toThrow(
+      /cannot be removed/,
+    );
+    expect(store.credentials.has(op.id)).toBe(true);
+
+    linkOperatorSso(store, op.id, "oidc", "sub-123");
+    expect(store.ssoLinks.get(op.id)).toHaveLength(1);
+    // Local login still works after SSO link.
+    const authed = await authenticateOperator(
+      store,
+      "ops@example.com",
+      "correct horse battery staple",
+    );
+    expect(authed?.id).toBe(op.id);
+  });
+});
+
+describe("invoke-as attenuation", () => {
+  test("attenuated exactly like an API key", () => {
+    const operatorScopes = new Set(["bookings:create", "bookings:list"]);
+
+    expect(() =>
+      invokeAs({
+        operatorScopes,
+        scopes: ["bookings:create", "admin:all"],
+        userId: "synthetic-1",
+      }),
+    ).toThrow(AttenuationError);
+
+    const principal = invokeAs({
+      operatorScopes,
+      scopes: ["bookings:create"],
+      userId: "synthetic-1",
+    });
+    expect(principal.plane).toBe("user");
+    expect(principal.scopes.has("bookings:create")).toBe(true);
+
+    expect(() =>
+      invokeAs({
+        operatorScopes,
+        scopes: ["bookings:create"],
+        userId: "real-user",
+        impersonateRealUser: true,
+        development: false,
+      }),
+    ).toThrow(/development-only/);
+  });
+});
+
+describe("roles are data", () => {
+  test("grants assignable without redeploy", () => {
+    const store = createRoleStore();
+    upsertRole(store, {
+      id: "r1",
+      name: "agent",
+      plane: "user",
+      description: "support agent",
+    });
+    setRoleGrants(store, "r1", ["bookings:list", "bookings:create"]);
+    const scopes = scopesForRoles(store, ["r1"], "user");
+    expect(scopes.has("bookings:list")).toBe(true);
+    // Plane isolation: operator roles ignored for user resolution.
+    upsertRole(store, {
+      id: "r-ops",
+      name: "admin",
+      plane: "operator",
+      description: "ops",
+    });
+    setRoleGrants(store, "r-ops", ["console:store.sql:write"]);
+    expect(scopesForRoles(store, ["r-ops"], "user").size).toBe(0);
+  });
+
+  test("assertAttenuated helper", () => {
+    expect(() =>
+      assertAttenuated(new Set(["a"]), ["a", "b"], "api key"),
+    ).toThrow(/missing: b/);
+  });
+});

package/src/auth/cross-plane.ts

@@ -0,0 +1,98 @@
+/**
+ * Cross-plane compile checks — application principals never reach console flows.
+ *
+ * @see docs/spec/console.md §2.2
+ */
+
+import type { Manifest } from "../manifest/types.ts";
+import { CrossPlaneError } from "./planes.ts";
+
+/** One cross-plane diagnostic. */
+export interface CrossPlaneDiagnostic {
+  readonly flow: string;
+  readonly message: string;
+}
+
+/** Source snippet used for principal-usage analysis. */
+export interface PlaneSourceFile {
+  readonly path: string;
+  readonly source: string;
+  /** Flow id this file contributes to (when known). */
+  readonly flow?: string;
+}
+
+/**
+ * Compile-time check: application principal (`fx.auth`) must not reach
+ * operator-plane (console) flows; user-plane flows must not call operator flows.
+ *
+ * @param manifest - Extracted Manifest
+ * @param sources - Optional source files for `fx.auth` / `fx.operator` usage
+ * @returns Diagnostics (empty when clean)
+ */
+export function checkCrossPlane(
+  manifest: Manifest,
+  sources: readonly PlaneSourceFile[] = [],
+): CrossPlaneDiagnostic[] {
+  const diagnostics: CrossPlaneDiagnostic[] = [];
+  const planes = new Map<string, "user" | "operator">();
+
+  for (const [id, flow] of Object.entries(manifest.flows ?? {})) {
+    planes.set(id, flow.plane ?? "user");
+  }
+
+  for (const [id, flow] of Object.entries(manifest.flows ?? {})) {
+    const plane = flow.plane ?? "user";
+    for (const callee of flow.effects?.calls ?? []) {
+      const calleePlane = planes.get(callee);
+      if (calleePlane === "operator" && plane === "user") {
+        diagnostics.push({
+          flow: id,
+          message: `cross-plane call: user flow "${id}" calls operator flow "${callee}"`,
+        });
+      }
+    }
+  }
+
+  for (const file of sources) {
+    const flowId = file.flow ?? inferFlowFromPath(file.path);
+    if (!flowId) continue;
+    const plane = planes.get(flowId) ?? inferPlaneFromSource(file.source);
+    if (plane === "operator" && /\bfx\.auth\b/.test(file.source)) {
+      diagnostics.push({
+        flow: flowId,
+        message: `application principal (fx.auth) reaches console flow "${flowId}"`,
+      });
+    }
+  }
+
+  return diagnostics;
+}
+
+/**
+ * Assert cross-plane isolation; throw {@link CrossPlaneError} on violation.
+ *
+ * @param manifest - Manifest
+ * @param sources - Sources
+ */
+export function assertCrossPlane(
+  manifest: Manifest,
+  sources: readonly PlaneSourceFile[] = [],
+): void {
+  const diagnostics = checkCrossPlane(manifest, sources);
+  if (diagnostics.length > 0) {
+    throw new CrossPlaneError(diagnostics.map((d) => d.message).join("; "));
+  }
+}
+
+function inferFlowFromPath(path: string): string | undefined {
+  // …/flows/bookings/create.ts → bookings.create
+  const m = /flows\/([^/]+)\/([^/]+)\.(ts|tsx|js)$/.exec(path.replace(/\\/g, "/"));
+  if (m) return `${m[1]}.${m[2]}`;
+  return undefined;
+}
+
+function inferPlaneFromSource(source: string): "user" | "operator" | undefined {
+  if (/plane\s*:\s*["']operator["']/.test(source)) return "operator";
+  if (/plane\s*:\s*["']user["']/.test(source)) return "user";
+  return undefined;
+}