@celilo/cli 2.1.0 → 2.2.0

package/src/hooks/hook-jail-toolchain-reach.test.ts

@@ -37,6 +37,7 @@ import { dirname, join, resolve } from 'node:path';
 import { executeHookScript } from './executor';
 import { detectJailBackend } from './jail';
 import { createCapturingLogger } from './logger';
+import { configStore, secretStore } from './test-fixtures/store-backed';
 import type { HookContext } from './types';
 
 const PROBE_HOOK = resolve(__dirname, 'test-fixtures/jail-toolchain-hook.ts');
@@ -115,8 +116,8 @@ async function measureReach(): Promise<{ reach: Reach; cleanup: () => void }> {
 
   const { logger } = createCapturingLogger();
   const context: HookContext = {
-    config: PROBE_BROWSER ? { browser_executable: PROBE_BROWSER } : {},
-    secrets: {},
+    config: PROBE_BROWSER ? configStore({ browser_executable: PROBE_BROWSER }) : configStore(),
+    secrets: secretStore(),
     systems: [],
     logger,
     debug: false,

package/src/hooks/hook-jail-unreachability.test.ts

@@ -35,6 +35,7 @@ const PLANTED_KEY_NAME = 'id_celilo_jail_probe';
 import { executeHookScript } from './executor';
 import { detectJailBackend, jailPolicy } from './jail';
 import { createCapturingLogger } from './logger';
+import { configStore, secretStore } from './test-fixtures/store-backed';
 import type { HookContext } from './types';
 
 const PROBE_HOOK = resolve(__dirname, 'test-fixtures/jail-probe-hook.ts');
@@ -110,12 +111,12 @@ async function runProbe(): Promise<Rig> {
 
   const { logger } = createCapturingLogger();
   const context: HookContext = {
-    config: {
+    config: configStore({
       planted_secret: plantedSecret,
       sibling_file: siblingFile,
       staged_input: stagedInput,
-    },
-    secrets: {},
+    }),
+    secrets: secretStore(),
     systems: [],
     logger,
     debug: false,

package/src/hooks/hook-protocol.ts

@@ -25,7 +25,7 @@
 
 import { z } from 'zod';
 
-export const HOOK_PROTOCOL_VERSION = 1;
+export const HOOK_PROTOCOL_VERSION = 2;
 
 /** Environment variable carrying the broker's socket path to the child. */
 export const HOOK_SOCKET_ENV = 'CELILO_HOOK_SOCKET';
@@ -91,6 +91,39 @@ export const CallFrameSchema = z.object({
   args: z.array(z.unknown()),
 });
 
+/**
+ * One hook-owned-state store operation, correlated like a `call` (and answered
+ * by the same `return`/`throw` frames — the runner's pending map keys on `id`
+ * alone).
+ *
+ * `store` names which of the module's two stores the call targets; `method` is
+ * one of the four `HookStore` operations. A `transaction` call carries the
+ * buffered operation list the CHILD accumulated — the hook's `fn` ran entirely
+ * child-side, so a throwing `fn` never sends anything, which is what makes the
+ * discard real rather than a promise the parent has to honor.
+ *
+ * Hook-owned-state design: the accessor is implemented once broker-side and
+ * reaches the hook as its own RPC family over this envelope, NOT as a fake
+ * capability — a fake one would surface in the `capabilities` shape frame and
+ * appear to the hook as a provider module.
+ */
+export const StoreCallFrameSchema = z.object({
+  type: z.literal('store'),
+  id: z.string(),
+  store: z.enum(['secrets', 'config']),
+  method: z.enum(['get', 'set', 'delete', 'transaction']),
+  args: z.array(z.unknown()),
+});
+
+/** One buffered operation inside a `transaction` store call. */
+export const BufferedStoreOpSchema = z.object({
+  op: z.enum(['set', 'delete']),
+  name: z.string(),
+  value: z.string().optional(),
+});
+
+export type BufferedStoreOp = z.infer<typeof BufferedStoreOpSchema>;
+
 /** One `ctx.logger` call. Fire and forget — the hook does not wait on it. */
 export const LogFrameSchema = z.object({
   type: z.literal('log'),
@@ -113,6 +146,7 @@ export const HookThrewFrameSchema = z.object({
 export const ChildFrameSchema = z.discriminatedUnion('type', [
   ReadyFrameSchema,
   CallFrameSchema,
+  StoreCallFrameSchema,
   LogFrameSchema,
   ResultFrameSchema,
   HookThrewFrameSchema,
@@ -145,6 +179,11 @@ export const MountEntrySchema = z.object({
   path: z.string(),
   mode: z.enum(['ro', 'rw', 'tmpfs']),
   reason: z.string(),
+  // Kept on the wire so this stays the structural twin its docblock below
+  // claims. The child ignores it — absence is decided when the set is derived,
+  // not by the hook — but a twin that has quietly stopped being one is how the
+  // round-trip test starts asserting about a shape nothing sends.
+  absence: z.enum(['required', 'declared-only', 'runtime', 'conditional']),
 });
 
 /** The derived mount set, on the wire. Structural twin of `MountSet`. */
@@ -272,6 +311,12 @@ export function createLineReader(onLine: (line: string) => void): (chunk: string
 /**
  * The handshake check, in one place so both ends produce the same sentence.
  *
+ * Version 2 added the `store` frame family (hook-owned-state task 3.5). Both
+ * ends of this protocol ship in the same celilo binary, so the check exists
+ * for one situation: a runner answering a broker built from different source
+ * than itself. It aborts the hook loudly instead of letting a store write
+ * disappear into a frame the other side cannot parse.
+ *
  * Names both numbers: a mismatch is an install skew (a `.deb` upgraded while a
  * module's bundled copy was not), and the operator needs to know which side is
  * which to fix it.

package/src/hooks/hook-runner.ts

@@ -26,6 +26,7 @@ import {
   serializeError,
   versionMismatch,
 } from './hook-protocol';
+import { buildStoreView } from './hook-store-proxy';
 import type { HookContext, HookLogger } from './types';
 import { forwardLintWarnings } from './unjailed-lint';
 
@@ -110,6 +111,22 @@ function callBroker(capability: string, method: string, args: unknown[]): Promis
   });
 }
 
+/**
+ * Store calls share the capability call's correlation machinery: the broker
+ * answers both families with the same `return`/`throw` frames, keyed by `id`.
+ */
+function callStore(
+  store: 'secrets' | 'config',
+  method: 'get' | 'set' | 'delete' | 'transaction',
+  args: unknown[],
+): Promise<unknown> {
+  const id = `c${nextCallId++}`;
+  return new Promise((resolve, reject) => {
+    pending.set(id, { resolve, reject });
+    send({ type: 'store', id, store, method, args });
+  });
+}
+
 /**
  * The `defineHook` brand check, moved here from the executor unchanged
  * (HOOK_API_V2 Phase 8 / D8). The brand is a `Symbol.for` key, so it survives
@@ -133,8 +150,27 @@ async function runHook(): Promise<void> {
     // hook's logger from here on (anything earlier was buffered).
     forwardLintWarnings(logger.warn);
 
+    // Attach the hook-owned-state accessor onto both maps. The maps crossed
+    // the context frame as plain data; the accessor methods exist only on
+    // this side, where the socket is. Old map reads keep working; new code
+    // calls `secrets.set(...)` / `config.get(...)` (hook-owned-state task 3.5).
+    // The casts say something true: celilo built both fields and controls
+    // their shape, the same rationale as the field check above.
+    const stores = buildStoreView(
+      'secrets',
+      (contextData.secrets ?? {}) as Record<string, string>,
+      callStore,
+    );
+    const configStores = buildStoreView(
+      'config',
+      (contextData.config ?? {}) as Record<string, unknown>,
+      callStore,
+    );
+
     const context = {
       ...contextData,
+      config: configStores,
+      secrets: stores,
       logger,
       capabilities: buildCapabilities(shape),
     } as unknown as HookContext;

package/src/hooks/hook-store-proxy.test.ts

@@ -0,0 +1,109 @@
+/**
+ * Tests for the child-side hook store view (hook-store-proxy).
+ *
+ * The load-bearing behavior is the transaction buffer: the hook's callback
+ * runs against a buffering view, and NOTHING crosses the transport until the
+ * callback resolves. A hook that writes then throws must send no frame at all
+ * — that is what makes D4's discard real rather than a promise the broker
+ * keeps. These tests watch the transport, which stands in for the socket.
+ */
+
+import { describe, expect, it } from 'bun:test';
+import { type StoreTransport, buildStoreView } from './hook-store-proxy';
+
+/** Record every transport call; answer `get` from a scripted map. */
+function fakeTransport(scripted: Record<string, string> = {}) {
+  const calls: Array<{ store: string; method: string; args: unknown[] }> = [];
+  const transport: StoreTransport = (store, method, args) => {
+    calls.push({ store, method, args });
+    if (method === 'get') {
+      return Promise.resolve(scripted[args[0] as string]);
+    }
+    return Promise.resolve(null);
+  };
+  return { calls, transport };
+}
+
+describe('hook store view (child side)', () => {
+  it('keeps the map surface readable alongside the accessor methods', () => {
+    const { transport } = fakeTransport({ bot_token: 'v' });
+    const view = buildStoreView('secrets', { bot_token: 'v' }, transport);
+
+    expect(view.bot_token).toBe('v');
+    expect(view.get('bot_token')).resolves.toBe('v');
+  });
+
+  it('forwards set/get/delete to the transport with the store name', async () => {
+    const { calls, transport } = fakeTransport();
+    const view = buildStoreView('config', {}, transport);
+
+    await view.set('public_ip', '203.0.113.7');
+    await view.delete('public_ip');
+
+    expect(calls).toEqual([
+      { store: 'config', method: 'set', args: ['public_ip', '203.0.113.7'] },
+      { store: 'config', method: 'delete', args: ['public_ip'] },
+    ]);
+  });
+
+  it('transaction sends one frame with the buffered ops after fn resolves', async () => {
+    const { calls, transport } = fakeTransport();
+    const view = buildStoreView('secrets', {}, transport);
+
+    await view.transaction((s) => {
+      s.set('bot_token', 'a');
+      s.set('api_key', 'b');
+      s.delete('old_key');
+    });
+
+    expect(calls).toEqual([
+      {
+        store: 'secrets',
+        method: 'transaction',
+        args: [
+          [
+            { op: 'set', name: 'bot_token', value: 'a' },
+            { op: 'set', name: 'api_key', value: 'b' },
+            { op: 'delete', name: 'old_key' },
+          ],
+        ],
+      },
+    ]);
+  });
+
+  it('a throwing fn sends NOTHING — the discard is on the wire', async () => {
+    const { calls, transport } = fakeTransport();
+    const view = buildStoreView('secrets', {}, transport);
+
+    await expect(
+      view.transaction(async (s) => {
+        s.set('bot_token', 'doomed');
+        throw new Error('hook failed midway');
+      }),
+    ).rejects.toThrow('hook failed midway');
+
+    expect(calls).toEqual([]);
+  });
+
+  it('get inside a transaction reads committed state, not the buffer', async () => {
+    const { transport } = fakeTransport({ bot_token: 'committed' });
+    const view = buildStoreView('secrets', {}, transport);
+
+    let seenInside: string | undefined;
+    await view.transaction(async (s) => {
+      s.set('bot_token', 'buffered');
+      seenInside = await s.get('bot_token');
+    });
+    expect(seenInside).toBe('committed');
+  });
+
+  it('a nested transaction rejects instead of reordering writes', async () => {
+    const { calls, transport } = fakeTransport();
+    const view = buildStoreView('secrets', {}, transport);
+
+    await expect(view.transaction((s) => s.transaction(() => Promise.resolve()))).rejects.toThrow(
+      /nested|transaction/i,
+    );
+    expect(calls).toEqual([]);
+  });
+});

package/src/hooks/hook-store-proxy.ts

@@ -0,0 +1,85 @@
+/**
+ * The asking half of the hook-owned-state accessor.
+ *
+ * Lives in the hook's own process (the runner shim builds the context from
+ * this), where every operation must cross the socket as a `store` frame. The
+ * answering half is `hook-store.ts` broker-side.
+ *
+ * The one subtlety is `transaction` (hook-owned-state design D4): the hook's
+ * callback runs entirely child-side against a BUFFERING view, and nothing is
+ * sent until the callback resolves. A hook that writes three names and throws
+ * therefore sends no frame at all — the discard is a property of the wire, not
+ * a promise the broker has to keep. This is the inverse of plain `set`, which
+ * lands when called; the design makes that trade deliberately and puts the
+ * choice at the call site.
+ *
+ * Pure construction (Rule 10.4) — the transport is injected, so the buffering
+ * rules are testable with no socket.
+ */
+
+import type { HookStore } from '@celilo/capabilities';
+import type { BufferedStoreOp } from './hook-protocol';
+
+/** One operation on a store, transported. The injectable boundary. */
+export type StoreTransport = (
+  store: 'secrets' | 'config',
+  method: 'get' | 'set' | 'delete' | 'transaction',
+  args: unknown[],
+) => Promise<unknown>;
+
+/**
+ * The names a transaction's callback must not call through its buffering view.
+ * A nested transaction has no honest meaning — there is nothing to commit the
+ * outer buffer against yet — and silently ignoring it would reorder writes.
+ */
+class NestedTransactionError extends Error {
+  constructor() {
+    super('transaction() cannot be called inside a transaction; apply the writes directly.');
+    this.name = 'NestedTransactionError';
+  }
+}
+
+/**
+ * Build the object the hook sees as `context.secrets` / `context.config`:
+ * the plain record of current values (the map surface older hooks still read),
+ * plus the four accessor methods.
+ *
+ * Methods sit ON the record deliberately during the migration window — a
+ * module declaring a secret or config key named `get`, `set`, `delete` or
+ * `transaction` would shadow one. That collision is rejected at the manifest
+ * layer only after task 3.6 removes the map surface; until then the risk is
+ * carried, not hidden.
+ */
+export function buildStoreView<T extends Record<string, unknown>>(
+  store: 'secrets' | 'config',
+  currentValues: T,
+  transport: StoreTransport,
+): T & HookStore {
+  const call = (method: 'get' | 'set' | 'delete', args: unknown[]) =>
+    transport(store, method, args) as Promise<unknown>;
+
+  const view = {
+    get: (name: string) => call('get', [name]) as Promise<string | undefined>,
+    set: (name: string, value: string) => call('set', [name, value]) as Promise<void>,
+    delete: (name: string) => call('delete', [name]) as Promise<void>,
+    transaction: async (fn: (buffered: HookStore) => void | Promise<void>) => {
+      const ops: BufferedStoreOp[] = [];
+      const buffered: HookStore = {
+        get: view.get,
+        set: (name, value) => {
+          ops.push({ op: 'set', name, value });
+          return Promise.resolve();
+        },
+        delete: (name) => {
+          ops.push({ op: 'delete', name });
+          return Promise.resolve();
+        },
+        transaction: () => Promise.reject(new NestedTransactionError()),
+      };
+      await fn(buffered);
+      await transport(store, 'transaction', [ops]);
+    },
+  };
+
+  return { ...currentValues, ...view } as T & HookStore;
+}

package/src/hooks/hook-store.test.ts

@@ -0,0 +1,162 @@
+/**
+ * Tests for the broker-side hook state stores (hook-owned-state tasks 3.2-3.4).
+ *
+ * The stores are what a jailed hook's `context.secrets` / `context.config`
+ * accessors answer against. Everything here runs against a real temp database
+ * with real encryption, because the interesting failures are storage failures:
+ * a value that will not decrypt back is worse than one that was never written.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { type DbClient, closeDb, createDbClient } from '../db/client';
+import { runMigrations } from '../db/migrate';
+import { moduleConfigs, modules, secrets } from '../db/schema';
+import { createHookStores } from './hook-store';
+
+describe('hook stores', () => {
+  let testDbPath: string;
+  let testDir: string;
+  let db: DbClient;
+
+  const MANIFEST = {
+    secrets: { declares: [{ name: 'bot_token' }, { name: 'api_key' }] },
+    variables: {
+      owns: [
+        { name: 'public_ip', type: 'string', source: 'hook' },
+        { name: 'registered_peers', type: 'string-map', source: 'hook' },
+        { name: 'acme_email', type: 'string', source: 'user' },
+      ],
+    },
+  };
+
+  beforeEach(async () => {
+    testDir = mkdtempSync(join(tmpdir(), 'celilo-hook-store-'));
+    testDbPath = join(testDir, 'test.db');
+    process.env.CELILO_DB_PATH = testDbPath;
+    // Redirect the master key so the test never touches the operator's real one.
+    process.env.CELILO_MASTER_KEY_PATH = join(testDir, 'master.key');
+    await runMigrations(testDbPath);
+
+    db = createDbClient({ path: testDbPath });
+    db.insert(modules)
+      .values({
+        id: 'test-module',
+        name: 'Test Module',
+        version: '1.0.0',
+        manifestData: MANIFEST,
+        sourcePath: '/test/path',
+      })
+      .run();
+  });
+
+  afterEach(() => {
+    closeDb();
+    rmSync(testDir, { recursive: true, force: true });
+    delete process.env.CELILO_MASTER_KEY_PATH;
+  });
+
+  it('round-trips a secret through encrypt and decrypt', async () => {
+    const { secrets: store } = await createHookStores(db, 'test-module');
+
+    await store.set('bot_token', 's3cret-value');
+    expect(await store.get('bot_token')).toBe('s3cret-value');
+  });
+
+  it('round-trips a hook-owned config value as plaintext', async () => {
+    const { config } = await createHookStores(db, 'test-module');
+
+    await config.set('public_ip', '203.0.113.7');
+    expect(await config.get('public_ip')).toBe('203.0.113.7');
+
+    // Plaintext: the row lands in module_configs, never in the secrets table.
+    const rows = db.select().from(moduleConfigs).all();
+    expect(rows.some((r) => r.key === 'public_ip' && r.valueJson === '"203.0.113.7"')).toBe(true);
+    expect(rows.some((r) => r.key === 'public_ip' && r.source === 'hook')).toBe(true);
+  });
+
+  it('set on an undeclared secret throws naming the module and the declared set', async () => {
+    const { secrets: store } = await createHookStores(db, 'test-module');
+
+    expect(store.set('not_declared', 'x')).rejects.toThrow(
+      /test-module[\s\S]*not_declared[\s\S]*bot_token[\s\S]*api_key/,
+    );
+  });
+
+  it('set on a name not owned as source: hook config throws naming the declared set', async () => {
+    const { config } = await createHookStores(db, 'test-module');
+
+    // acme_email is declared, but as source: user — the operator owns it.
+    await expect(config.set('acme_email', 'x')).rejects.toThrow(/source: hook/);
+    await expect(config.set('not_declared', 'x')).rejects.toThrow(/public_ip/);
+  });
+
+  it('delete of an absent name is a no-op', async () => {
+    const { secrets: store, config } = await createHookStores(db, 'test-module');
+
+    await expect(store.delete('bot_token')).resolves.toBeUndefined();
+    await expect(config.delete('public_ip')).resolves.toBeUndefined();
+  });
+
+  it('delete removes an existing row', async () => {
+    const { config } = await createHookStores(db, 'test-module');
+
+    await config.set('public_ip', '203.0.113.7');
+    await config.delete('public_ip');
+    expect(await config.get('public_ip')).toBeUndefined();
+  });
+
+  it('applyTransaction commits every buffered op on success', async () => {
+    const { secrets: store } = await createHookStores(db, 'test-module');
+
+    await store.applyTransaction([
+      { op: 'set', name: 'bot_token', value: 'committed' },
+      { op: 'set', name: 'api_key', value: 'committed-too' },
+    ]);
+    expect(await store.get('bot_token')).toBe('committed');
+    expect(await store.get('api_key')).toBe('committed-too');
+  });
+
+  it('an undeclared name inside a transaction discards the whole batch', async () => {
+    const { secrets: store } = await createHookStores(db, 'test-module');
+
+    await expect(
+      store.applyTransaction([
+        { op: 'set', name: 'api_key', value: 'good' },
+        { op: 'set', name: 'not_declared', value: 'bad' },
+      ]),
+    ).rejects.toThrow(/not_declared/);
+
+    expect(await store.get('api_key')).toBeUndefined();
+  });
+
+  it('a name owned as config is not writable through the secrets store and vice versa', async () => {
+    const { secrets: store, config } = await createHookStores(db, 'test-module');
+
+    await expect(store.set('public_ip', 'x')).rejects.toThrow(/bot_token|api_key/);
+    await expect(config.set('bot_token', 'x')).rejects.toThrow(/source: hook|public_ip/);
+  });
+
+  it('reads secrets the ordinary interview path wrote, and writes stay visible to it', async () => {
+    // The interview encrypts directly into the secrets table; the store must
+    // read those rows, not only its own writes.
+    const { encryptSecret } = await import('../secrets/encryption');
+    const { getOrCreateMasterKey } = await import('../secrets/master-key');
+    const masterKey = await getOrCreateMasterKey();
+    const encrypted = encryptSecret('interview-value', masterKey);
+    db.insert(secrets)
+      .values({ moduleId: 'test-module', name: 'bot_token', ...encrypted })
+      .run();
+
+    const { secrets: store } = await createHookStores(db, 'test-module');
+    expect(await store.get('bot_token')).toBe('interview-value');
+  });
+
+  it('reports the declared sets in the store metadata', async () => {
+    const stores = await createHookStores(db, 'test-module');
+    expect(stores.declaredSecretNames.sort()).toEqual(['api_key', 'bot_token']);
+    expect(stores.declaredConfigNames.sort()).toEqual(['public_ip', 'registered_peers']);
+  });
+});