okengine 0.14.1 → 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/bindings.ts

@@ -275,10 +275,13 @@ export function createAuthHttpBindings(
   } = { refresh, revoke, me };
   const bindings: Binding[] = [
     bindAuthHttp(
-      http.post(`${base}/refresh`).gate.public.gate(...(refreshRate ? [refreshRate] : [])),
+      http
+        .post(`${base}/refresh`)
+        .public()
+        .gate(...(refreshRate ? [refreshRate] : [])),
       refresh,
     ),
-    bindAuthHttp(http.post(`${base}/revoke`).gate.public, revoke),
+    bindAuthHttp(http.post(`${base}/revoke`).public(), revoke),
     bindAuthHttp(http.get(`${base}/me`).gate(AUTH_SESSION_GATE), me),
   ];
 
@@ -371,11 +374,17 @@ export function createAuthHttpBindings(
     flows.signUpEmail = signUpEmail;
     bindings.push(
       bindAuthHttp(
-        http.post(`${base}/sign-in/email`).gate.public.gate(...(signInRate ? [signInRate] : [])),
+        http
+          .post(`${base}/sign-in/email`)
+          .public()
+          .gate(...(signInRate ? [signInRate] : [])),
         signInEmail,
       ),
       bindAuthHttp(
-        http.post(`${base}/sign-up/email`).gate.public.gate(...(signUpRate ? [signUpRate] : [])),
+        http
+          .post(`${base}/sign-up/email`)
+          .public()
+          .gate(...(signUpRate ? [signUpRate] : [])),
         signUpEmail,
       ),
     );
@@ -406,7 +415,7 @@ export function isSessionFresh(
  * @param flowDef - Flow
  */
 export function bindAuthHttp(trigger: HttpTrigger, flowDef: AnyFlowDef): Binding {
-  const withPosture = trigger.gates.length > 0 ? trigger : trigger.gate.public;
+  const withPosture = trigger.gates.length > 0 ? trigger : trigger.public();
   const normalized = normalizeTrigger(withPosture);
   const list = flowDef.triggers as Trigger[];
   list.push(normalized);

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/cross-plane.ts

@@ -86,9 +86,16 @@ export function assertCrossPlane(
 
 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;
+  // …/flows/notes/[id]/get.ts → notes.get (never notes.id.get)
+  const posix = path.replace(/\\/g, "/");
+  const m = /(?:^|\/)flows\/([^/]+)\/(.+)\.(ts|tsx|js)$/.exec(posix);
+  if (!m) return undefined;
+  const unit = m[1]!;
+  const rest = m[2]!;
+  const leaf = rest.split("/").pop();
+  if (!leaf || leaf === "index" || leaf.startsWith("_")) return undefined;
+  if (leaf === "shapes" || leaf === "signals" || leaf.endsWith(".test")) return undefined;
+  return `${unit}.${leaf}`;
 }
 
 function inferPlaneFromSource(source: string): "user" | "operator" | undefined {

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/ai-setup/ai-setup.test.ts

@@ -167,6 +167,68 @@ export default defineConfig({
       rmSync(dir, { recursive: true, force: true });
     }
   });
+
+  test("applyAiSetup prefers an existing src/core/ai.ts over a thin core.ts barrel", () => {
+    const dir = mkdtempSync(join(tmpdir(), "oke-ai-setup-split-"));
+    try {
+      writeFileSync(
+        join(dir, "oke.config.ts"),
+        `import { defineConfig } from "okengine/config";
+export default defineConfig({
+  drivers: {
+    channel: {
+      email: {
+        dev: "smtp",
+        test: "console",
+        prod: "smtp",
+      },
+    },
+  },
+  images: {
+    store: {
+      sql: "postgres:18-alpine",
+    },
+  },
+});
+`,
+        "utf8",
+      );
+      mkdirSync(join(dir, "src", "core"), { recursive: true });
+      writeFileSync(
+        join(dir, "src", "core.ts"),
+        `export * from "./core/store.ts";\nexport * from "./core/ai.ts";\n`,
+        "utf8",
+      );
+      writeFileSync(
+        join(dir, "src", "core", "store.ts"),
+        `import { store } from "okengine";\n\nexport const db = store.sql("app");\n`,
+        "utf8",
+      );
+      writeFileSync(join(dir, "src", "core", "ai.ts"), `import { ai } from "okengine";\n`, "utf8");
+      writeFileSync(
+        join(dir, "src", "app.ts"),
+        `import "@/core";\nexport const app = {};\n`,
+        "utf8",
+      );
+
+      applyAiSetup(dir, {
+        driver: "ollama",
+        baseUrl: "http://127.0.0.1:11434",
+        chatModel: "gemma4:e4b",
+        visionModel: "qwen3-vl:4b",
+        embedModel: "nomic-embed-text",
+      });
+
+      const barrel = readFileSync(join(dir, "src", "core.ts"), "utf8");
+      expect(barrel).not.toContain("ai.model");
+      expect(barrel).toContain('export * from "./core/ai.ts"');
+      const aiTs = readFileSync(join(dir, "src", "core", "ai.ts"), "utf8");
+      expect(aiTs).toContain("smart");
+      expect(aiTs).toContain('ai.model("vision"');
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
 });
 
 describe("parseAiSetupArgs", () => {