okengine 0.15.2 → 0.16.0

package/src/auth/api-keys.ts

@@ -3,14 +3,23 @@
  *
  * A key can never exceed the permissions of whoever created it.
  * The raw secret is returned exactly once on create / rotate.
+ * Hash is HMAC-SHA-256 with the auth pepper (gate.auth.secret).
  *
  * @see docs/spec/console.md §3.3 · §9.14
  */
 
+import { lookup as dnsLookup } from "node:dns/promises";
+import { parseDurationMs } from "../elements/clock/duration.ts";
 import { assertAttenuated } from "./attenuation.ts";
 import type { AuthPlane } from "./planes.ts";
 import type { ApiKeyRow } from "./tables.ts";
 
+/** Capability / Manifest resource for `fx.auth` key methods. */
+export const AUTH_API_KEYS_RESOURCE = "auth:api-keys";
+
+/** Default HMAC pepper when no `gate.auth.secret` is bound (tests). */
+const DEFAULT_PEPPER = "oke.api-key";
+
 /** Options when creating an API key. */
 export interface CreateApiKeyOptions {
   readonly plane: AuthPlane;
@@ -27,6 +36,19 @@ export interface CreateApiKeyOptions {
   readonly secret?: string;
   readonly hash?: string;
   readonly now?: () => number;
+  /** HMAC pepper override (defaults to store pepper). */
+  readonly pepper?: string;
+}
+
+/** Patch for {@link updateApiKey}. */
+export interface UpdateApiKeyOptions {
+  readonly name?: string;
+  readonly scopes?: readonly string[];
+  readonly expiresAt?: number | null;
+  readonly rateLimit?: { max: number; per: string } | null;
+  readonly ipAllowlist?: readonly string[];
+  /** Ceiling for scope changes (stored creatorScopes ∩ live scopes). */
+  readonly ceiling: ReadonlySet<string> | Iterable<string>;
 }
 
 /** Result of key creation — secret shown exactly once. */
@@ -36,27 +58,76 @@ export interface CreatedApiKey {
   readonly secret: string;
 }
 
-/** In-memory API key store. */
+/** Public key row returned by `fx.auth.listApiKeys` (never includes hash). */
+export interface ApiKeyPublicRow {
+  readonly id: string;
+  readonly name: string;
+  readonly plane: AuthPlane;
+  readonly scopes: readonly string[];
+  readonly createdAt: number;
+  readonly lastUsedAt: number | null;
+  readonly expiresAt: number | null;
+  readonly revokedAt: number | null;
+  readonly rateLimit: { max: number; per: string } | null;
+  readonly ipAllowlist: readonly string[];
+}
+
+/**
+ * API key store — in-memory Map, optionally HMAC-peppered.
+ * SQL persist is a write-through adapter bound at boot.
+ */
 export interface ApiKeyStore {
   keys: Map<string, ApiKeyRow>;
+  /** HMAC pepper (`gate.auth.secret`). */
+  pepper?: string;
+  /** Optional write-through persist (SQL). */
+  persist?: (row: ApiKeyRow) => void | Promise<void>;
+  /** Sliding-window hits for per-key rateLimit (subject = key id). */
+  rateHits?: Map<string, number[]>;
+}
+
+/** Options for {@link createApiKeyStore}. */
+export interface CreateApiKeyStoreOptions {
+  readonly pepper?: string;
+  readonly persist?: (row: ApiKeyRow) => void | Promise<void>;
 }
 
 /**
  * Create an empty API key store.
+ *
+ * @param options - Optional HMAC pepper / persist hook
  */
-export function createApiKeyStore(): ApiKeyStore {
-  return { keys: new Map() };
+export function createApiKeyStore(options: CreateApiKeyStoreOptions = {}): ApiKeyStore {
+  return {
+    keys: new Map(),
+    ...(options.pepper !== undefined ? { pepper: options.pepper } : {}),
+    ...(options.persist !== undefined ? { persist: options.persist } : {}),
+  };
 }
 
 /**
- * Hash an API key secret (SHA-256 hex).
+ * HMAC-SHA-256 hex of an API key secret.
  *
  * @param secret - Raw secret
+ * @param pepper - HMAC key (`gate.auth.secret`); defaults to a test pepper
  */
-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("");
+export async function hashApiKeySecret(
+  secret: string,
+  pepper: string = DEFAULT_PEPPER,
+): Promise<string> {
+  const key = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(pepper),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const sig = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(secret));
+  return [...new Uint8Array(sig)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+async function persistRow(store: ApiKeyStore, row: ApiKeyRow): Promise<void> {
+  await store.persist?.(row);
 }
 
 /**
@@ -74,7 +145,8 @@ export async function createApiKey(
   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 pepper = options.pepper ?? store.pepper ?? DEFAULT_PEPPER;
+  const hash = options.hash ?? (await hashApiKeySecret(secret, pepper));
   const creatorScopes = [...options.creatorScopes];
 
   const row: ApiKeyRow = {
@@ -93,32 +165,77 @@ export async function createApiKey(
     revokedAt: null,
   };
   store.keys.set(id, row);
+  await persistRow(store, row);
   return { row, secret };
 }
 
+/** Resolve a stored hostname to addresses (injected in tests). */
+export type AllowlistLookup = (host: string) => Promise<readonly string[]>;
+
+/** Options for {@link authenticateApiKey}. */
+export interface AuthenticateApiKeyOptions {
+  readonly now?: () => number;
+  /** Client IP for allowlist enforcement. */
+  readonly ip?: string;
+  /** Hostname → A/AAAA (defaults to system DNS). */
+  readonly lookup?: AllowlistLookup;
+}
+
 /**
- * Resolve a key by raw secret; enforces expiry and revocation.
+ * Resolve a key by raw secret; enforces expiry, revocation, and allowlist.
  *
  * @param store - Key store
  * @param secret - Raw secret
- * @param now - Clock
+ * @param nowOrOptions - Clock, or clock + client IP
  */
 export async function authenticateApiKey(
   store: ApiKeyStore,
   secret: string,
-  now: () => number = () => Date.now(),
+  nowOrOptions: (() => number) | AuthenticateApiKeyOptions = () => Date.now(),
 ): Promise<ApiKeyRow | null> {
-  const hash = await hashApiKeySecret(secret);
+  const options: AuthenticateApiKeyOptions =
+    typeof nowOrOptions === "function" ? { now: nowOrOptions } : nowOrOptions;
+  const now = options.now ?? (() => Date.now());
+  const pepper = store.pepper ?? DEFAULT_PEPPER;
+  const hash = await hashApiKeySecret(secret, pepper);
   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;
+    if (row.ipAllowlist.length > 0) {
+      const allowed = await allowlistAllowsIp(row.ipAllowlist, options.ip, options.lookup);
+      if (!allowed) return null;
+    }
+    if (row.rateLimit && !takeKeyRate(store, row.id, row.rateLimit, now())) return null;
     row.lastUsedAt = now();
+    await persistRow(store, row);
     return row;
   }
   return null;
 }
 
+/**
+ * List keys created by `creatorId` (includes revoked rows for audit).
+ *
+ * @param store - Key store
+ * @param creatorId - Issuer id
+ */
+export function listApiKeys(store: ApiKeyStore, creatorId: string): ApiKeyRow[] {
+  return [...store.keys.values()]
+    .filter((row) => row.creatorId === creatorId)
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Load one key by id.
+ *
+ * @param store - Key store
+ * @param id - Key id
+ */
+export function getApiKey(store: ApiKeyStore, id: string): ApiKeyRow | undefined {
+  return store.keys.get(id);
+}
+
 /**
  * Revoke an API key — irreversible. The row remains for audit / hygiene.
  *
@@ -134,6 +251,7 @@ export function revokeApiKey(
   const row = store.keys.get(id);
   if (!row || row.revokedAt !== null) return null;
   row.revokedAt = now();
+  void persistRow(store, row);
   return row;
 }
 
@@ -150,15 +268,156 @@ export async function rotateApiKey(
   options: {
     readonly secret?: string;
     readonly now?: () => number;
+    readonly pepper?: string;
   } = {},
 ): 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);
+  const pepper = options.pepper ?? store.pepper ?? DEFAULT_PEPPER;
+  row.hash = await hashApiKeySecret(secret, pepper);
+  await persistRow(store, row);
   return { row, secret };
 }
 
+/**
+ * Update key metadata. Scope changes re-run {@link assertAttenuated}.
+ *
+ * @param store - Key store
+ * @param id - Key id
+ * @param options - Patch + attenuation ceiling
+ */
+export function updateApiKey(
+  store: ApiKeyStore,
+  id: string,
+  options: UpdateApiKeyOptions,
+): ApiKeyRow | null {
+  const row = store.keys.get(id);
+  if (!row || row.revokedAt !== null) return null;
+  if (options.scopes !== undefined) {
+    assertAttenuated(options.ceiling, options.scopes, "api key");
+    row.scopes = [...options.scopes];
+  }
+  if (options.name !== undefined) row.name = options.name;
+  if (options.expiresAt !== undefined) row.expiresAt = options.expiresAt;
+  if (options.rateLimit !== undefined) row.rateLimit = options.rateLimit;
+  if (options.ipAllowlist !== undefined) row.ipAllowlist = [...options.ipAllowlist];
+  void persistRow(store, row);
+  return row;
+}
+
+/**
+ * Public projection of a key row (no hash / creatorScopes).
+ *
+ * @param row - Stored row
+ */
+export function toApiKeyPublicRow(row: ApiKeyRow): ApiKeyPublicRow {
+  return {
+    id: row.id,
+    name: row.name,
+    plane: row.plane,
+    scopes: [...row.scopes],
+    createdAt: row.createdAt,
+    lastUsedAt: row.lastUsedAt,
+    expiresAt: row.expiresAt,
+    revokedAt: row.revokedAt,
+    rateLimit: row.rateLimit,
+    ipAllowlist: [...row.ipAllowlist],
+  };
+}
+
+/**
+ * Whether the client IP matches an allowlist entry.
+ * Literals compare exactly. Hostnames resolve at verify time (fail closed).
+ *
+ * @param entries - IPs and/or hostnames
+ * @param ip - Client IP
+ * @param lookup - Hostname resolver
+ */
+export async function allowlistAllowsIp(
+  entries: readonly string[],
+  ip: string | undefined,
+  lookup: AllowlistLookup = lookupAllowlistHost,
+): Promise<boolean> {
+  if (entries.length === 0) return true;
+  if (ip === undefined) return false;
+  const client = ip.trim().toLowerCase();
+  for (const raw of entries) {
+    const entry = normalizeAllowlistEntry(raw);
+    if (entry.length === 0) continue;
+    if (isIpLiteral(entry)) {
+      if (entry === client) return true;
+      continue;
+    }
+    try {
+      const addrs = await lookup(entry);
+      if (addrs.some((addr) => addr.trim().toLowerCase() === client)) return true;
+    } catch {
+      // This host fails closed; other entries may still match.
+    }
+  }
+  return false;
+}
+
+function normalizeAllowlistEntry(raw: string): string {
+  let entry = raw.trim().toLowerCase();
+  entry = entry.replace(/^https?:\/\//, "");
+  const slash = entry.indexOf("/");
+  if (slash >= 0) entry = entry.slice(0, slash);
+  if (entry.endsWith(".")) entry = entry.slice(0, -1);
+  return entry;
+}
+
+function isIpLiteral(entry: string): boolean {
+  if (/^\d{1,3}(?:\.\d{1,3}){3}$/.test(entry)) {
+    return entry.split(".").every((octet) => Number(octet) <= 255);
+  }
+  return entry.includes(":") && /^[0-9a-f:.]+$/.test(entry);
+}
+
+async function lookupAllowlistHost(host: string): Promise<readonly string[]> {
+  const rows = await dnsLookup(host, { all: true, verbatim: true });
+  return rows.map((row) => row.address);
+}
+
+/**
+ * Client IP from X-Forwarded-For (right-most trusted hop) or X-Real-IP.
+ *
+ * @param request - Incoming request
+ * @param trustedProxyDepth - Hops from the right (default 1)
+ */
+export function clientIpFromRequest(request: Request, trustedProxyDepth = 1): string | undefined {
+  const xff = request.headers.get("x-forwarded-for");
+  if (xff) {
+    const hops = xff
+      .split(",")
+      .map((h) => h.trim())
+      .filter((h) => h.length > 0);
+    const index = hops.length - trustedProxyDepth;
+    if (index >= 0) return hops[index];
+  }
+  return request.headers.get("x-real-ip")?.trim() || undefined;
+}
+
+function takeKeyRate(
+  store: ApiKeyStore,
+  keyId: string,
+  limit: { max: number; per: string },
+  nowMs: number,
+): boolean {
+  const windowMs = parseDurationMs(limit.per);
+  const hits = store.rateHits ?? (store.rateHits = new Map<string, number[]>());
+  const prev = hits.get(keyId) ?? [];
+  const kept = prev.filter((t) => nowMs - t < windowMs);
+  if (kept.length >= limit.max) {
+    hits.set(keyId, kept);
+    return false;
+  }
+  kept.push(nowMs);
+  hits.set(keyId, kept);
+  return true;
+}
+
 function randomSecret(): string {
   const bytes = crypto.getRandomValues(new Uint8Array(24));
   return [...bytes].map((b) => b.toString(16).padStart(2, "0")).join("");

package/src/auth/auth.test.ts

@@ -114,6 +114,62 @@ describe("auth plugin", () => {
   });
 });
 
+describe("API key allowlist", () => {
+  test("hostname entry matches the resolved client IP", async () => {
+    const { authenticateApiKey } = await import("./api-keys.ts");
+    const store = createApiKeyStore();
+    const created = await createApiKey(store, {
+      plane: "user",
+      name: "ci",
+      scopes: ["member"],
+      creatorId: "u1",
+      creatorScopes: ["member"],
+      ipAllowlist: ["ci.example.com"],
+    });
+    const lookup = async (host: string) => (host === "ci.example.com" ? ["203.0.113.10"] : []);
+    expect(
+      await authenticateApiKey(store, created.secret, {
+        ip: "203.0.113.10",
+        lookup,
+      }),
+    ).not.toBeNull();
+    expect(
+      await authenticateApiKey(store, created.secret, {
+        ip: "198.51.100.7",
+        lookup,
+      }),
+    ).toBeNull();
+  });
+
+  test("hostname lookup failure is closed", async () => {
+    const { authenticateApiKey } = await import("./api-keys.ts");
+    const store = createApiKeyStore();
+    const created = await createApiKey(store, {
+      plane: "user",
+      name: "ci",
+      scopes: ["member"],
+      creatorId: "u1",
+      creatorScopes: ["member"],
+      ipAllowlist: ["ci.example.com", "203.0.113.10"],
+    });
+    const lookup = async () => {
+      throw new Error("nxdomain");
+    };
+    expect(
+      await authenticateApiKey(store, created.secret, {
+        ip: "203.0.113.10",
+        lookup,
+      }),
+    ).not.toBeNull();
+    expect(
+      await authenticateApiKey(store, created.secret, {
+        ip: "198.51.100.7",
+        lookup,
+      }),
+    ).toBeNull();
+  });
+});
+
 describe("API key attenuation", () => {
   test("key cannot be created with a scope its creator lacks", async () => {
     const store = createApiKeyStore();

package/src/auth/config.ts

@@ -6,7 +6,7 @@
 
 import type { PasswordHashOptions } from "../runtime/types.ts";
 import type { SessionStore } from "./sessions.ts";
-import type { ApiKeyStore } from "./api-keys.ts";
+import { createApiKeyStore, type ApiKeyStore } from "./api-keys.ts";
 import type { BreachCheckFn } from "./breach-check.ts";
 import type { PasswordPolicyOptions } from "./password-policy.ts";
 import {
@@ -111,8 +111,8 @@ export interface GateAuthOptions extends AuthSchemaOptions {
    */
   readonly sessions?: SessionStore;
   /**
-   * In-memory API key store for Bearer key auth (tests / embedding).
-   * Distinct from schema `apiKeys` table options.
+   * Shared API key store. Created automatically when omitted
+   * (`gate.auth.secret` is the HMAC pepper).
    */
   readonly apiKeyStore?: ApiKeyStore;
   /** Injectable clock. */
@@ -170,7 +170,7 @@ export interface ResolvedGateAuth {
   };
   readonly hooks: AuthDatabaseHooks | undefined;
   readonly sessions: SessionStore | undefined;
-  readonly apiKeyStore: ApiKeyStore | undefined;
+  readonly apiKeyStore: ApiKeyStore;
   readonly now: (() => number) | undefined;
 }
 
@@ -278,7 +278,7 @@ export function resolveGateAuth(options: ResolveGateAuthOptions): ResolvedGateAu
     },
     hooks: auth.hooks,
     sessions: auth.sessions,
-    apiKeyStore: auth.apiKeyStore,
+    apiKeyStore: auth.apiKeyStore ?? createApiKeyStore({ pepper: secret }),
     now: auth.now,
   };
 }

package/src/auth/index.ts

@@ -161,17 +161,41 @@ export {
 } from "./attenuation.ts";
 
 export {
+  AUTH_API_KEYS_RESOURCE,
+  allowlistAllowsIp,
+  authenticateApiKey,
+  clientIpFromRequest,
   createApiKey,
   createApiKeyStore,
-  authenticateApiKey,
+  getApiKey,
   hashApiKeySecret,
+  listApiKeys,
   revokeApiKey,
   rotateApiKey,
+  toApiKeyPublicRow,
+  updateApiKey,
+  type AllowlistLookup,
+  type ApiKeyPublicRow,
   type ApiKeyStore,
+  type AuthenticateApiKeyOptions,
   type CreateApiKeyOptions,
+  type CreateApiKeyStoreOptions,
   type CreatedApiKey,
+  type UpdateApiKeyOptions,
 } from "./api-keys.ts";
 
+export {
+  apiKeySqlExec,
+  bindApiKeySqlPersist,
+  bindHostApiKeySql,
+  bindHostApiKeySqlFromStore,
+  ensureApiKeyTable,
+  hydrateApiKeyStore,
+  persistApiKeyRow,
+  type ApiKeySqlExec,
+  type HostApiKeySqlRuntime,
+} from "./api-key-sql.ts";
+
 export {
   createOperatorInviteStore,
   createOperatorInvite,

package/src/auth/schema.ts

@@ -105,6 +105,10 @@ export const AUTH_MODEL_DEFAULT_FIELDS: Readonly<
     name: "name",
     scopes: "scopes",
     expiresAt: "expires_at",
+    rateLimit: "rate_limit",
+    ipAllowlist: "ip_allowlist",
+    creatorId: "creator_id",
+    creatorScopes: "creator_scopes",
     createdAt: "created_at",
     lastUsedAt: "last_used_at",
     revokedAt: "revoked_at",
@@ -190,6 +194,10 @@ const CORE_SQL_TYPES: Readonly<Record<string, AuthColumnSqlType>> = {
   scopes: "TEXT",
   audience: "TEXT",
   lastUsedAt: "INTEGER",
+  rateLimit: "TEXT",
+  ipAllowlist: "TEXT",
+  creatorId: "TEXT",
+  creatorScopes: "TEXT",
 };
 
 /**

package/src/cli/attach-host-console.test.ts

@@ -123,6 +123,43 @@ export const app = oke({
     await attached!.stop();
   });
 
+  test("Console Access uses the host apiKeyStore instance (not Console SQL)", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "oke-attach-keys-"));
+    const entry = join(dir, "app.ts");
+    await writeFile(
+      entry,
+      `
+import { oke, on, flow, http, gate, store } from ${JSON.stringify(OKE)};
+const db = store.sql("db");
+const member = gate.policy("member", ({ auth }) => !!auth.verified);
+export const ping = on(
+  http.get("/ping").gate(member),
+  flow("main.ping", { do: () => ({ ok: true }) }),
+);
+export const app = oke({
+  name: "attach-keys",
+  stores: [db],
+  gate: {
+    auth: { secret: "attach-host-key-pepper", http: false },
+    policies: [member],
+  },
+}).adopt({ ping });
+`,
+    );
+
+    const consoleKeys = { keys: new Map(), persist: async () => {} };
+    const state = {
+      invokeUserFlow: null,
+      storeRuntime: null,
+      apiKeys: consoleKeys,
+    } as unknown as ConsoleState;
+    const attached = await attachHostToConsole({ entry, cwd: dir, state });
+    expect(attached).not.toBeNull();
+    expect(state.apiKeys).not.toBe(consoleKeys);
+    expect(state.apiKeys.persist).not.toBe(consoleKeys.persist);
+    await attached!.stop();
+  });
+
   test("returns null when the entry is not a bootable app", async () => {
     const dir = await mkdtemp(join(tmpdir(), "oke-attach-empty-"));
     const entry = join(dir, "app.ts");

package/src/cli/attach-host-console.ts

@@ -69,6 +69,12 @@ export async function attachHostToConsole(
   if (vault) options.state.vaultRuntime = vault;
   const ai = host.elements?.ai ?? host.bootResult?.ai;
   if (ai) bindAiRuntime(options.state, ai);
+  const hostKeys = host.apiKeys;
+  if (hostKeys) {
+    // Host `gate.auth.apiKeyStore` is the durable store (`oke_api_keys` on
+    // `store.sql()`). Console displays that instance — never the reverse.
+    options.state.apiKeys = hostKeys;
+  }
 
   return {
     stop: async () => {

package/src/compiler/effects-infer.ts

@@ -7,6 +7,7 @@
  */
 
 import type {
+  AuthApiKeysResourceRef,
   Effects,
   PromptRef,
   ResourceRef,
@@ -145,8 +146,8 @@ const TABLE_ARG_METHODS = new Set([
  * @param options - Handler AST, bindings, and annotation flag
  */
 export function inferEffects(options: InferEffectsOptions): InferredEffects {
-  const reads = new Set<ResourceRef | SignalResourceRef>();
-  const writes = new Set<ResourceRef>();
+  const reads = new Set<ResourceRef | SignalResourceRef | AuthApiKeysResourceRef>();
+  const writes = new Set<ResourceRef | AuthApiKeysResourceRef>();
   const emits = new Set<SignalRef>();
   const sends = new Set<TemplateRef>();
   const asks = new Set<PromptRef>();
@@ -217,6 +218,20 @@ export function inferEffects(options: InferEffectsOptions): InferredEffects {
       continue;
     }
 
+    if (chain.rootMethod === "auth" && call === chain.rootCall) {
+      const method = chain.methods[1];
+      if (method === "listApiKeys") reads.add("auth:api-keys");
+      if (
+        method === "createApiKey" ||
+        method === "revokeApiKey" ||
+        method === "rotateApiKey" ||
+        method === "updateApiKey"
+      ) {
+        writes.add("auth:api-keys");
+      }
+      continue;
+    }
+
     if (chain.rootMethod === "search" && call === chain.rootCall) {
       const ref = resolveNamed(call.arguments[0], options.bindings, "embed");
       if (ref) {