okengine 0.2.8 → 0.3.4

package/src/drivers/vault-openbao.ts

@@ -1,21 +1,30 @@
 /**
- * `openbao` vault driver — HashiCorp Vault / OpenBao KV v2 HTTP API.
+ * `openbao` vault driver — OpenBao (Vault-compatible) KV v2 HTTP API.
  *
  * Protocol-named; image/vendor choice lives in `images`.
  */
 
 import type { VaultBag, VaultDriver, VaultOpenOptions } from "./vault-types.ts";
 
+/** Error thrown when the remote OpenBao is unreachable / sealed / errors. */
+export class OpenBaoUnavailableError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "OpenBaoUnavailableError";
+  }
+}
+
 /**
- * OpenBao / Vault KV driver.
+ * OpenBao KV-v2 bag. Reads are loaded at open when `url` + `token` resolve;
+ * writes (`set` / `delete`) hit the HTTP API directly.
  *
- * Expects `url` + `token` + optional `mount` (default `secret`).
- * Fetches `GET {url}/v1/{mount}/data/{name}` for each requested secret
- * lazily via a cached bag loaded at open when `secrets` seed keys are listed,
- * or returns empty until {@link VaultBag.get} is called against a remote.
+ * When `url` and `token` are provided, an unreachable, sealed, or erroring
+ * OpenBao is **fatal** (fail-loud) — the bag never silently degrades to an
+ * empty / seed-only view.
  *
  * For boot validation the runtime passes declared names; this driver loads
- * all keys under `mount` when the LIST API is available, else uses seed names.
+ * all keys under `mount` when the LIST API is available, else falls back to
+ * GETs for the seed names.
  */
 export const openbaoVaultDriver: VaultDriver = {
   id: "openbao",
@@ -30,36 +39,60 @@ export const openbaoVaultDriver: VaultDriver = {
       ),
     );
 
-    if (url && token) {
-      // Best-effort LIST; ignore failures (permission / disabled).
+    const remote = url !== undefined && token !== undefined;
+    let mutableRemote = false;
+
+    if (remote && url !== undefined && token !== undefined) {
+      const headers = { "X-Vault-Token": token };
+      const base = `${url}/v1/${mount}`;
+
+      async function listNames(): Promise<string[]> {
+        const res = await fetchFn(`${base}/metadata?list=true`, { headers });
+        if (!res.ok) return [];
+        const body = (await res.json()) as { data?: { keys?: string[] } };
+        return (body.data?.keys ?? []).map((k) => k.replace(/\/$/, ""));
+      }
+
+      async function readName(name: string): Promise<boolean> {
+        const res = await fetchFn(`${base}/data/${encodeURIComponent(name)}`, { headers });
+        if (res.status === 404) return false;
+        if (!res.ok) {
+          throw new OpenBaoUnavailableError(
+            `openbao vault: GET ${name} failed (${res.status}) — sealed or unauthorized?`,
+          );
+        }
+        const body = (await res.json()) as { data?: { data?: Record<string, unknown> } };
+        const data = body.data?.data ?? {};
+        const value =
+          typeof data.value === "string"
+            ? data.value
+            : typeof data[name] === "string"
+              ? (data[name] as string)
+              : JSON.stringify(data);
+        map.set(name, value);
+        return true;
+      }
+
+      // LIST when the token has metadata list; otherwise only fetch the
+      // seed/declared names so a least-privilege token still works. A
+      // connection-level failure here must never degrade to an empty bag.
+      let names: string[] = [];
       try {
-        const listRes = await fetchFn(`${url}/v1/${mount}/metadata?list=true`, {
-          headers: { "X-Vault-Token": token },
-        });
-        if (listRes.ok) {
-          const body = (await listRes.json()) as {
-            data?: { keys?: string[] };
-          };
-          for (const key of body.data?.keys ?? []) {
-            const getRes = await fetchFn(`${url}/v1/${mount}/data/${key}`, {
-              headers: { "X-Vault-Token": token },
-            });
-            if (!getRes.ok) continue;
-            const got = (await getRes.json()) as {
-              data?: { data?: Record<string, unknown> };
-            };
-            const data = got.data?.data ?? {};
-            const value =
-              typeof data.value === "string"
-                ? data.value
-                : typeof data[key] === "string"
-                  ? (data[key] as string)
-                  : JSON.stringify(data);
-            map.set(key.replace(/\/$/, ""), value);
-          }
+        names = await listNames();
+      } catch (err) {
+        if (map.size === 0) {
+          throw new OpenBaoUnavailableError(
+            `openbao vault: unreachable at ${url} — ${err instanceof Error ? err.message : String(err)}`,
+          );
         }
-      } catch {
-        // Remote unavailable — bag stays at seed / empty; boot validation reports gaps.
+        // Fall through: LIST denied but we still have declared names to GET.
+      }
+      if (names.length > 0) {
+        for (const key of names) await readName(key);
+        mutableRemote = true;
+      } else if (map.size > 0) {
+        for (const name of map.keys()) await readName(name);
+        mutableRemote = true;
       }
     }
 
@@ -71,6 +104,40 @@ export const openbaoVaultDriver: VaultDriver = {
       names() {
         return [...map.keys()];
       },
+      ...(mutableRemote && url !== undefined && token !== undefined
+        ? {
+            set(name: string, value: string) {
+              void (async () => {
+                const res = await fetchFn(`${url}/v1/${mount}/data/${encodeURIComponent(name)}`, {
+                  method: "POST",
+                  headers: { "X-Vault-Token": token, "content-type": "application/json" },
+                  body: JSON.stringify({ data: { value } }),
+                });
+                if (!res.ok) {
+                  throw new OpenBaoUnavailableError(
+                    `openbao vault: write ${name} failed (${res.status})`,
+                  );
+                }
+                map.set(name, value);
+              })();
+            },
+            delete(name: string) {
+              const had = map.delete(name);
+              void (async () => {
+                const res = await fetchFn(`${url}/v1/${mount}/data/${encodeURIComponent(name)}`, {
+                  method: "DELETE",
+                  headers: { "X-Vault-Token": token },
+                });
+                if (!res.ok && res.status !== 404) {
+                  throw new OpenBaoUnavailableError(
+                    `openbao vault: delete ${name} failed (${res.status})`,
+                  );
+                }
+              })();
+              return had;
+            },
+          }
+        : {}),
     };
   },
 };

package/src/drivers/vault-types.ts

@@ -1,24 +1,17 @@
 /**
  * Protocol-named vault driver contracts.
  *
- * Driver ids: `sops` · `env` · `openbao` · `infisical` · `managed` · `memory`.
+ * Driver ids: `env` · `openbao` · `infisical` · `managed` · `memory`.
  * Never vendor names (`neon`, `infisical-cloud`, …) — vendor choice lives in `images`.
  */
 
 /** Protocol ids for vault drivers. */
-export type VaultDriverId = "sops" | "env" | "openbao" | "infisical" | "managed" | "memory";
+export type VaultDriverId = "env" | "openbao" | "infisical" | "managed" | "memory";
 
 /** Options when opening a vault backend. */
 export interface VaultOpenOptions {
-  /**
-   * Path to a SOPS-encrypted file (`sops` driver) or a dotenv file (`env` driver).
-   * Prefer JSON / ENV formats produced by `sops -e` for SOPS.
-   */
+  /** Path to a dotenv file (`env` driver). */
   readonly path?: string;
-  /** Inline SOPS ciphertext (tests). */
-  readonly ciphertext?: string | Uint8Array;
-  /** Age identity (`AGE-SECRET-KEY-…`) for Typage decryption. */
-  readonly ageIdentity?: string;
   /** Env prefix filter for the `env` driver (default: none — whole `process.env`). */
   readonly envPrefix?: string;
   /** Injected env map for tests (defaults to `process.env`). */

package/src/elements/store/declare.ts

@@ -5,6 +5,7 @@
  */
 
 import type { ColumnClassification, ResourceRef, StoreFacet } from "../../manifest/types.ts";
+import { resource } from "./resource.ts";
 import { schema } from "./schema-decl.ts";
 import { resolveTableName, type TableHandle } from "./table.ts";
 
@@ -180,7 +181,7 @@ export function index(name: string, options: IndexStoreOptions = {}): IndexStore
   };
 }
 
-/** Public `store` element — four facets + abstract schema declare. */
+/** Public `store` element — four facets + abstract schema declare + resource. */
 export const store = {
   sql,
   kv,
@@ -188,4 +189,6 @@ export const store = {
   index,
   /** ORM-agnostic table declarations (`store.schema.table`). */
   schema,
+  /** CRUD + list factory (`store.resource(db, table, opts)`). */
+  resource,
 } as const;

package/src/elements/store/resource-list-docs.fixture.ts

@@ -0,0 +1,56 @@
+/**
+ * Typechecked fixtures backing the two illustrative Store list configurations
+ * on the Store element docs page. They compile against the real
+ * `store.resource` / `ResourceListOptions` API — not a teaching-app claimed
+ * fence. If the resource list options change, these fail typecheck instead of
+ * rotting into invalid prose syntax.
+ *
+ * Docs copy the `list: { … }` option blocks below as unheaded illustrative
+ * fences; the 422 behavior for the restricted variant is locked by
+ * `resource-list-docs.test.ts`.
+ */
+
+import { z } from "zod";
+import { field, id, now, store } from "../store.ts";
+
+const docsItems = store.schema.table("docs_items", {
+  id: field.text().primaryKey().defaultFn(id),
+  title: field.text().notNull(),
+  secret: field.text().notNull(),
+  createdAt: field.integer().notNull().defaultFn(now),
+});
+
+const db = store.sql("docs-items", { schema: { docs_items: docsItems } });
+
+const inSchema = z.object({ title: z.string().min(1), secret: z.string().min(1) });
+const outSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  secret: z.string(),
+  createdAt: z.number(),
+});
+
+/**
+ * Admin table — offset paging with an exact row count. Docs illustrate
+ * `count: "exact"` (offset default) and point to `count: "none"` as the escape
+ * hatch when COUNT(*) is too expensive.
+ */
+export const docsAdminTableResource = store.resource(db, docsItems, {
+  in: inSchema,
+  out: outSchema,
+  list: { mode: "offset", count: "exact", limit: 20 },
+  unit: "docs-admin",
+  breaking: true,
+});
+
+/**
+ * Public restricted endpoint — filters off entirely. Any `?col=op.value`
+ * query key that is not a reserved list param fails validation (422).
+ */
+export const docsRestrictedResource = store.resource(db, docsItems, {
+  in: inSchema,
+  out: outSchema,
+  list: { mode: "offset", filter: "none", limit: 20 },
+  unit: "docs-restricted",
+  breaking: true,
+});

package/src/elements/store/resource-list-docs.test.ts

@@ -0,0 +1,79 @@
+/**
+ * Lock the documented Store behaviors for the typechecked docs fixtures:
+ *
+ * 1. `filter: "none"` — a forbidden filter query key fails with HTTP 422 and a
+ *    `ValidationError` whose message is exactly `unknown list param "<key>"`
+ *    (`badInput` in `resource.ts`). The Store element page quotes this shape.
+ * 2. `mode: "offset"` + `count: "exact"` — list answers `meta.total` via
+ *    `COUNT(*)`. Changing it to `"none"` must drop `meta.total` and keep only
+ *    `meta.offset`; this test catches a silent behavior flip in either config.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { oke } from "../../kernel/app.ts";
+import { resetFlowSeq } from "../../kernel/flow.ts";
+import { on, resetBindings } from "../../kernel/on.ts";
+import { http } from "../../kernel/triggers.ts";
+import { createTestApp } from "../../test/create-test-app.ts";
+import { docsAdminTableResource, docsRestrictedResource } from "./resource-list-docs.fixture.ts";
+
+afterEach(() => {
+  resetBindings();
+  resetFlowSeq();
+});
+
+describe("resource-list-docs fixtures — documented behaviors stay real", () => {
+  test("filter: \"none\" — forbidden filter key → 422 ValidationError 'unknown list param'", async () => {
+    resetBindings();
+    resetFlowSeq();
+
+    const mounted = on(http.resource("/docs-restricted", docsRestrictedResource.all()));
+    const app = oke({ name: "docs-restricted-test" }).adopt({ docs: mounted });
+    Object.assign(app.$options, { env: "test" });
+
+    const t = await createTestApp(app);
+
+    const bad = await app.fetch(new Request("http://localhost/docs-restricted?secret=eq.x"));
+    expect(bad.status).toBe(422);
+    const badBody = (await bad.json()) as {
+      data: null;
+      error: { code: string; data: { issues: Array<{ message: string; path: string[] }> } };
+    };
+    expect(badBody.error.code).toBe("ValidationError");
+    expect(badBody.error.data.issues[0]!.message).toBe('unknown list param "secret"');
+    expect(badBody.error.data.issues[0]!.path).toEqual(["secret"]);
+
+    const ok = await app.fetch(new Request("http://localhost/docs-restricted?limit=20"));
+    expect(ok.status).toBe(200);
+
+    await t.close();
+  });
+
+  test('offset + count: "exact" answers meta.total; "none" drops it', async () => {
+    resetBindings();
+    resetFlowSeq();
+
+    const exactMounted = on(http.resource("/docs-admin", docsAdminTableResource.all()));
+    const app = oke({ name: "docs-admin-test" }).adopt({ docs: exactMounted });
+    Object.assign(app.$options, { env: "test" });
+
+    const t = await createTestApp(app);
+    await app.fetch(
+      new Request("http://localhost/docs-admin", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ title: "one", secret: "s" }),
+      }),
+    );
+
+    const exact = await app.fetch(new Request("http://localhost/docs-admin?limit=20"));
+    expect(exact.status).toBe(200);
+    const exactBody = (await exact.json()) as {
+      meta: Record<string, unknown>;
+    };
+    expect(exactBody.meta.total).toBe(1);
+    expect(exactBody.meta.offset).toBe(0);
+
+    await t.close();
+  });
+});

package/src/elements/store/resource.test.ts

@@ -0,0 +1,253 @@
+/**
+ * `store.resource` row shape — declared JS keys only, never raw SQL names.
+ * Also locks the PII-masking order: mask after remapping so a `.pii()` column
+ * whose TS key differs from its SQL name cannot leak cleartext under the
+ * client-facing key.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { Database } from "bun:sqlite";
+import { integer, sqliteTable, text } from "drizzle-orm/sqlite-core";
+import { createInsertSchema, createSelectSchema } from "drizzle-zod";
+import { z } from "zod";
+import { sqliteDriver } from "../../drivers/sqlite.ts";
+import { oke } from "../../kernel/app.ts";
+import { resetFlowSeq } from "../../kernel/flow.ts";
+import { on, resetBindings } from "../../kernel/on.ts";
+import { http } from "../../kernel/triggers.ts";
+import { createTestApp } from "../../test/create-test-app.ts";
+import { classify, field, id, now, PII_MASK, store } from "../store.ts";
+import { createSqlStoreHandle } from "./sql-session.ts";
+import { mapRowToJs, resolveColumns } from "./table.ts";
+
+afterEach(() => {
+  resetBindings();
+  resetFlowSeq();
+});
+
+describe("mapRowToJs — declared keys only", () => {
+  const posts = sqliteTable("posts", {
+    id: text("id").primaryKey(),
+    createdAt: integer("created_at").notNull(),
+  });
+
+  test("SQL-keyed driver row becomes JS keys; raw SQL name is dropped", () => {
+    const cols = resolveColumns(posts);
+    expect(cols.find((c) => c.key === "createdAt")?.sqlName).toBe("created_at");
+
+    const mapped = mapRowToJs(posts, { id: "p1", created_at: 100 });
+    expect(mapped).toEqual({ id: "p1", createdAt: 100 });
+    expect("created_at" in mapped).toBe(false);
+  });
+
+  test("already JS-keyed row prefers JS key; raw SQL name is dropped", () => {
+    const mapped = mapRowToJs(posts, { id: "p1", createdAt: 100, created_at: 999 });
+    expect(mapped).toEqual({ id: "p1", createdAt: 100 });
+    expect("created_at" in mapped).toBe(false);
+  });
+});
+
+describe("SqlStoreHandle exit — list/get/create return JS keys only", () => {
+  const posts = sqliteTable("posts", {
+    id: text("id").primaryKey(),
+    title: text("title").notNull(),
+    createdAt: integer("created_at").notNull(),
+  });
+
+  test("select / findById / insert.returning never emit created_at", async () => {
+    const conn = await sqliteDriver.connect({
+      client: new Database(":memory:"),
+      role: "primary",
+    });
+    const handle = createSqlStoreHandle("sql:app", {
+      connection: conn,
+      classifications: new Map(),
+      routedRole: "primary",
+      domainDdl: "ensure",
+    });
+
+    const [created] = await handle
+      .insert(posts)
+      .values({ id: "p1", title: "one", createdAt: 100 })
+      .returning();
+    expect(Object.keys(created!).sort()).toEqual(["createdAt", "id", "title"]);
+    expect("created_at" in created!).toBe(false);
+
+    const listed = await handle.select().from(posts);
+    expect(Object.keys(listed[0]!).sort()).toEqual(["createdAt", "id", "title"]);
+    expect("created_at" in listed[0]!).toBe(false);
+
+    const got = await handle.findById(posts, "p1");
+    expect(Object.keys(got!).sort()).toEqual(["createdAt", "id", "title"]);
+    expect("created_at" in got!).toBe(false);
+
+    await conn.close();
+  });
+});
+
+describe("resource HTTP — exact keys + PII with differing TS/SQL names", () => {
+  // TS `email` ↔ SQL `email_addr`; TS `createdAt` ↔ SQL `created_at`.
+  const contacts = sqliteTable("contacts", {
+    id: text("id").primaryKey().$defaultFn(id),
+    email: text("email_addr").notNull(),
+    createdAt: integer("created_at").notNull().$defaultFn(now),
+  });
+
+  const NewContact = createInsertSchema(contacts).omit({ id: true, createdAt: true });
+  const Contact = createSelectSchema(contacts);
+
+  function buildApp() {
+    resetBindings();
+    resetFlowSeq();
+
+    const db = store.sql("contacts", {
+      schema: { contacts },
+      classify: { contacts: { email: classify({ pii: true }) } },
+    });
+
+    const contactsR = store.resource(db, contacts, {
+      in: NewContact,
+      out: Contact,
+      update: NewContact.partial(),
+      list: {
+        cursor: [contacts.createdAt, contacts.id],
+        direction: "desc",
+        limit: 20,
+        filter: "all",
+        order: "all",
+      },
+      unit: "contacts",
+      breaking: true,
+    });
+
+    const mounted = on(http.resource("/contacts", contactsR.all()));
+    const app = oke({ name: "contacts-resource-test" }).adopt({ contacts: mounted });
+    Object.assign(app.$options, { env: "test", stores: [db] });
+    return app;
+  }
+
+  /** Assert a row object has exactly the declared keys — no raw SQL names. */
+  function expectExactContactKeys(row: Record<string, unknown>) {
+    expect(Object.keys(row).sort()).toEqual(["createdAt", "email", "id"]);
+    expect("created_at" in row).toBe(false);
+    expect("email_addr" in row).toBe(false);
+  }
+
+  test("app.fetch list/get/create/update: only createdAt + masked email, never raw SQL keys", async () => {
+    const app = buildApp();
+    const t = await createTestApp(app);
+
+    // create → 201
+    const created = await app.fetch(
+      new Request("http://localhost/contacts", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ email: "secret@example.com" }),
+      }),
+    );
+    expect(created.status).toBe(201);
+    const createdText = await created.text();
+    expect(createdText).not.toContain("created_at");
+    expect(createdText).not.toContain("email_addr");
+    expect(createdText).not.toContain("secret@example.com");
+    const createdBody = JSON.parse(createdText) as {
+      data: Record<string, unknown>;
+      error: null;
+    };
+    expect(createdBody.error).toBeNull();
+    expectExactContactKeys(createdBody.data);
+    expect(createdBody.data.email).toBe(PII_MASK);
+    expect(typeof createdBody.data.createdAt).toBe("number");
+    const contactId = createdBody.data.id as string;
+
+    // get → 200
+    const got = await app.fetch(new Request(`http://localhost/contacts/${contactId}`));
+    expect(got.status).toBe(200);
+    const gotText = await got.text();
+    expect(gotText).not.toContain("created_at");
+    expect(gotText).not.toContain("email_addr");
+    expect(gotText).not.toContain("secret@example.com");
+    const gotBody = JSON.parse(gotText) as { data: Record<string, unknown> };
+    expectExactContactKeys(gotBody.data);
+    expect(gotBody.data.email).toBe(PII_MASK);
+
+    // list → 200 (query present so list `in` is a record, not undefined)
+    const list = await app.fetch(new Request("http://localhost/contacts?limit=20"));
+    expect(list.status).toBe(200);
+    const listText = await list.text();
+    expect(listText).not.toContain("created_at");
+    expect(listText).not.toContain("email_addr");
+    expect(listText).not.toContain("secret@example.com");
+    const listBody = JSON.parse(listText) as { data: Record<string, unknown>[] };
+    expect(listBody.data).toHaveLength(1);
+    expectExactContactKeys(listBody.data[0]!);
+    expect(listBody.data[0]!.email).toBe(PII_MASK);
+
+    // update → 200
+    const updated = await app.fetch(
+      new Request(`http://localhost/contacts/${contactId}`, {
+        method: "PATCH",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ email: "other@example.com" }),
+      }),
+    );
+    expect(updated.status).toBe(200);
+    const updatedText = await updated.text();
+    expect(updatedText).not.toContain("created_at");
+    expect(updatedText).not.toContain("email_addr");
+    expect(updatedText).not.toContain("other@example.com");
+    const updatedBody = JSON.parse(updatedText) as { data: Record<string, unknown> };
+    expectExactContactKeys(updatedBody.data);
+    expect(updatedBody.data.email).toBe(PII_MASK);
+
+    await t.close();
+  });
+
+  test("schema-decl .pii().as(sqlName) masks the final JS key via app.fetch", async () => {
+    resetBindings();
+    resetFlowSeq();
+
+    const peopleTable = store.schema.table("people", {
+      id: field.text().primaryKey().defaultFn(id),
+      email: field.text().notNull().pii().as("email_addr"),
+      createdAt: field.integer().notNull().defaultFn(now),
+    });
+
+    const db = store.sql("people", { schema: { people: peopleTable } });
+    const peopleR = store.resource(db, peopleTable, {
+      in: z.object({ email: z.string().email() }),
+      out: z.object({
+        id: z.string(),
+        email: z.string(),
+        createdAt: z.number(),
+      }),
+      update: z.object({ email: z.string().email() }).partial(),
+      list: { mode: "offset", limit: 20 },
+      unit: "people",
+      breaking: true,
+    });
+
+    const mounted = on(http.resource("/people", peopleR.all()));
+    const app = oke({ name: "people-pii-test" }).adopt({ people: mounted });
+    Object.assign(app.$options, { env: "test", stores: [db] });
+
+    const t = await createTestApp(app);
+    const created = await app.fetch(
+      new Request("http://localhost/people", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ email: "alice@example.com" }),
+      }),
+    );
+    expect(created.status).toBe(201);
+    const text = await created.text();
+    expect(text).not.toContain("email_addr");
+    expect(text).not.toContain("created_at");
+    expect(text).not.toContain("alice@example.com");
+    const body = JSON.parse(text) as { data: Record<string, unknown> };
+    expect(Object.keys(body.data).sort()).toEqual(["createdAt", "email", "id"]);
+    expect(body.data.email).toBe(PII_MASK);
+
+    await t.close();
+  });
+});