okengine 0.15.2 → 0.17.0

package/src/auth/api-key-sql.ts

@@ -0,0 +1,261 @@
+/**
+ * SQL persist / hydrate for {@link ApiKeyRow} on `oke_api_keys`.
+ *
+ * Host path: public schema on the app `store.sql()` connection
+ * (`sharedSqlConn` / `DATABASE_URL`). Console attaches that same
+ * {@link ApiKeyStore} — it does not own a second key table.
+ */
+
+import type { SqlConnection } from "../drivers/types.ts";
+import type { ApiKeyRow } from "./tables.ts";
+import { AUTH_TABLES } from "./tables.ts";
+import type { ApiKeyStore } from "./api-keys.ts";
+
+/** Minimal SQL executor for the auth key table. */
+export interface ApiKeySqlExec {
+  execute(sql: string, params: readonly unknown[]): Promise<void>;
+  all(sql: string): Promise<readonly Record<string, unknown>[]>;
+}
+
+/**
+ * Persist one key row to `oke_api_keys`.
+ *
+ * @param sql - Executor
+ * @param row - Key row
+ * @param table - Physical table (`oke_api_keys` or schema-qualified)
+ */
+export async function persistApiKeyRow(
+  sql: ApiKeySqlExec,
+  row: ApiKeyRow,
+  table: string = AUTH_TABLES.apiKeys,
+): Promise<void> {
+  await sql.execute(
+    `INSERT INTO ${table} (
+      id, plane, hash, name, scopes, expires_at, rate_limit, ip_allowlist,
+      creator_id, creator_scopes, created_at, last_used_at, revoked_at, tenant_id
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(id) DO UPDATE SET
+      hash = excluded.hash,
+      name = excluded.name,
+      scopes = excluded.scopes,
+      expires_at = excluded.expires_at,
+      rate_limit = excluded.rate_limit,
+      ip_allowlist = excluded.ip_allowlist,
+      creator_id = excluded.creator_id,
+      creator_scopes = excluded.creator_scopes,
+      last_used_at = excluded.last_used_at,
+      revoked_at = excluded.revoked_at,
+      tenant_id = excluded.tenant_id`,
+    [
+      row.id,
+      row.plane,
+      row.hash,
+      row.name,
+      JSON.stringify(row.scopes),
+      row.expiresAt,
+      row.rateLimit ? JSON.stringify(row.rateLimit) : null,
+      JSON.stringify(row.ipAllowlist),
+      row.creatorId,
+      JSON.stringify(row.creatorScopes),
+      row.createdAt,
+      row.lastUsedAt,
+      row.revokedAt,
+      row.tenantId ?? null,
+    ],
+  );
+}
+
+/**
+ * Load every key row from `oke_api_keys` into a store.
+ *
+ * @param sql - Executor
+ * @param store - Destination store
+ * @param table - Physical table
+ */
+export async function hydrateApiKeyStore(
+  sql: ApiKeySqlExec,
+  store: ApiKeyStore,
+  table: string = AUTH_TABLES.apiKeys,
+): Promise<void> {
+  const rows = await sql.all(`SELECT * FROM ${table}`);
+  for (const raw of rows) {
+    const row = rowFromSql(raw);
+    if (row) store.keys.set(row.id, row);
+  }
+}
+
+/**
+ * Bind write-through persist on a store.
+ *
+ * @param store - Key store
+ * @param sql - Executor
+ * @param table - Physical table
+ */
+export function bindApiKeySqlPersist(
+  store: ApiKeyStore,
+  sql: ApiKeySqlExec,
+  table: string = AUTH_TABLES.apiKeys,
+): void {
+  store.persist = (row) => persistApiKeyRow(sql, row, table);
+}
+
+/** Runtime that can open the app's shared primary SQL connection. */
+export interface HostApiKeySqlRuntime {
+  primarySql(): Promise<SqlConnection | undefined>;
+}
+
+/**
+ * Adapt a driver connection to {@link ApiKeySqlExec}.
+ *
+ * @param conn - Shared `store.sql()` connection
+ */
+export function apiKeySqlExec(conn: SqlConnection): ApiKeySqlExec {
+  return {
+    execute: async (sql, params) => {
+      await conn.exec(sql, params);
+    },
+    all: async (sql) => conn.query(sql),
+  };
+}
+
+/**
+ * Create public `oke_api_keys` when missing (host schema, not `oke_console`).
+ *
+ * @param conn - Shared SQL connection
+ * @param table - Physical table
+ */
+export async function ensureApiKeyTable(
+  conn: SqlConnection,
+  table: string = AUTH_TABLES.apiKeys,
+): Promise<void> {
+  await conn.exec(`
+    CREATE TABLE IF NOT EXISTS ${table} (
+      id TEXT PRIMARY KEY NOT NULL,
+      plane TEXT NOT NULL,
+      hash TEXT NOT NULL,
+      name TEXT NOT NULL,
+      scopes TEXT NOT NULL DEFAULT '[]',
+      expires_at BIGINT,
+      rate_limit TEXT,
+      ip_allowlist TEXT NOT NULL DEFAULT '[]',
+      creator_id TEXT NOT NULL,
+      creator_scopes TEXT NOT NULL DEFAULT '[]',
+      created_at BIGINT NOT NULL,
+      last_used_at BIGINT,
+      revoked_at BIGINT,
+      tenant_id TEXT
+    )
+  `);
+  await conn.exec(`ALTER TABLE ${table} ADD COLUMN IF NOT EXISTS tenant_id TEXT`);
+}
+
+/**
+ * Hydrate and write-through-persist a host {@link ApiKeyStore} on `conn`.
+ *
+ * Leaves an already-bound `persist` hook in place (injected test stores).
+ *
+ * @param conn - App SQL connection (`sharedSqlConn`)
+ * @param store - `gate.auth.apiKeyStore`
+ * @param table - Physical table (`oke_api_keys` in `public`)
+ */
+export async function bindHostApiKeySql(
+  conn: SqlConnection,
+  store: ApiKeyStore,
+  table: string = AUTH_TABLES.apiKeys,
+): Promise<void> {
+  await ensureApiKeyTable(conn, table);
+  const exec = apiKeySqlExec(conn);
+  await hydrateApiKeyStore(exec, store, table);
+  if (!store.persist) bindApiKeySqlPersist(store, exec, table);
+}
+
+/**
+ * Bind host key persist through {@link HostApiKeySqlRuntime.primarySql}.
+ *
+ * No-ops when the store runtime has no SQL driver (in-memory-only apps).
+ *
+ * @param runtime - Booted `store` element
+ * @param store - `gate.auth.apiKeyStore`
+ */
+export async function bindHostApiKeySqlFromStore(
+  runtime: HostApiKeySqlRuntime,
+  store: ApiKeyStore,
+): Promise<void> {
+  const conn = await runtime.primarySql();
+  if (!conn) return;
+  await bindHostApiKeySql(conn, store);
+}
+
+function rowFromSql(raw: Record<string, unknown>): ApiKeyRow | null {
+  const id = asString(raw.id ?? raw.ID);
+  const plane = raw.plane === "operator" ? "operator" : "user";
+  const hash = asString(raw.hash);
+  const name = asString(raw.name);
+  const creatorId = asString(raw.creator_id ?? raw.creatorId);
+  if (!id || !hash || !name || !creatorId) return null;
+  return {
+    id,
+    plane,
+    hash,
+    name,
+    scopes: asStringArray(raw.scopes),
+    expiresAt: asNumberOrNull(raw.expires_at ?? raw.expiresAt),
+    rateLimit: asRateLimit(raw.rate_limit ?? raw.rateLimit),
+    ipAllowlist: asStringArray(raw.ip_allowlist ?? raw.ipAllowlist),
+    creatorId,
+    creatorScopes: asStringArray(raw.creator_scopes ?? raw.creatorScopes),
+    createdAt: asNumberOrNull(raw.created_at ?? raw.createdAt) ?? 0,
+    lastUsedAt: asNumberOrNull(raw.last_used_at ?? raw.lastUsedAt),
+    revokedAt: asNumberOrNull(raw.revoked_at ?? raw.revokedAt),
+    ...(asString(raw.tenant_id ?? raw.tenantId) !== null
+      ? { tenantId: asString(raw.tenant_id ?? raw.tenantId) }
+      : {}),
+  };
+}
+
+function asString(value: unknown): string | null {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+function asNumberOrNull(value: unknown): number | null {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value.length > 0) {
+    const n = Number(value);
+    return Number.isFinite(n) ? n : null;
+  }
+  return null;
+}
+
+function asStringArray(value: unknown): string[] {
+  if (Array.isArray(value)) return value.filter((item): item is string => typeof item === "string");
+  if (typeof value === "string" && value.length > 0) {
+    try {
+      const parsed: unknown = JSON.parse(value);
+      if (Array.isArray(parsed)) {
+        return parsed.filter((item): item is string => typeof item === "string");
+      }
+    } catch {
+      return [];
+    }
+  }
+  return [];
+}
+
+function asRateLimit(value: unknown): { max: number; per: string } | null {
+  const parsed: unknown =
+    typeof value === "string" && value.length > 0
+      ? (() => {
+          try {
+            return JSON.parse(value) as unknown;
+          } catch {
+            return null;
+          }
+        })()
+      : value;
+  if (!parsed || typeof parsed !== "object") return null;
+  const rec = parsed as { max?: unknown; per?: unknown };
+  if (typeof rec.max === "number" && typeof rec.per === "string") {
+    return { max: rec.max, per: rec.per };
+  }
+  return null;
+}

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;
@@ -22,11 +31,26 @@ export interface CreateApiKeyOptions {
   readonly expiresAt?: number | null;
   readonly rateLimit?: { max: number; per: string } | null;
   readonly ipAllowlist?: readonly string[];
+  /** Optional tenant claim copied onto the key principal. */
+  readonly tenantId?: string | null;
   /** Injectable id / secret / hash (tests). */
   readonly id?: string;
   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 +60,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 +147,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 = {
@@ -91,34 +165,80 @@ export async function createApiKey(
     createdAt: now(),
     lastUsedAt: null,
     revokedAt: null,
+    ...(options.tenantId !== undefined ? { tenantId: options.tenantId } : {}),
   };
   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 +254,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 +271,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("");