@openparachute/agent 0.1.0 → 0.1.2

package/src/modules/mount-security/expand-path.test.ts

@@ -0,0 +1,82 @@
+/**
+ * `expandPath` resolves operator-supplied paths inside the mount-allowlist
+ * (`~/projects` etc.) against `HOME_DIR` from src/config.ts. paraclaw#99
+ * pulled the HOME-resolution out of this module so the precedence rule
+ * (`process.env.HOME` → `os.homedir()`) lives in one place; these tests pin
+ * the contract.
+ *
+ * `vi.resetModules()` is required because config.ts captures HOME_DIR at
+ * module load — tests that flip env vars must re-import both config and the
+ * mount-security module so the new HOME_DIR threads through.
+ */
+import path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const ORIGINAL_HOME = process.env.HOME;
+
+beforeEach(() => {
+  vi.resetModules();
+});
+
+afterEach(() => {
+  if (ORIGINAL_HOME === undefined) delete process.env.HOME;
+  else process.env.HOME = ORIGINAL_HOME;
+});
+
+describe('expandPath HOME resolution', () => {
+  it("expands '~/foo' against config.HOME_DIR (default)", async () => {
+    process.env.HOME = '/Users/test-default';
+    const cfg = await import('../../config.js');
+    const { expandPath } = await import('./index.js');
+    expect(cfg.HOME_DIR).toBe('/Users/test-default');
+    expect(expandPath('~/projects')).toBe(path.join('/Users/test-default', 'projects'));
+  });
+
+  it("expands bare '~' to config.HOME_DIR", async () => {
+    process.env.HOME = '/Users/test-bare-tilde';
+    const { expandPath } = await import('./index.js');
+    expect(expandPath('~')).toBe('/Users/test-bare-tilde');
+  });
+
+  it('passes absolute paths through path.resolve unchanged', async () => {
+    process.env.HOME = '/Users/test-abs';
+    const { expandPath } = await import('./index.js');
+    // Absolute paths should NOT consult HOME_DIR — they resolve as-is.
+    expect(expandPath('/var/data/x')).toBe('/var/data/x');
+  });
+
+  it('honors HOME override at module load (sandbox-style override)', async () => {
+    // The override path: PARACHUTE_HOME does NOT route mount-allowlist (#99
+    // path 2 — operator-host policy is intentionally separate from runtime
+    // state), but the bare HOME env var IS honored by config.HOME_DIR for
+    // operators who reroute their entire shell session. Pin that flow.
+    process.env.HOME = '/tmp/sandbox-home-99';
+    const cfg = await import('../../config.js');
+    const { expandPath } = await import('./index.js');
+    expect(cfg.HOME_DIR).toBe('/tmp/sandbox-home-99');
+    expect(expandPath('~/repos')).toBe('/tmp/sandbox-home-99/repos');
+    // ALLOWLIST_DIR derives from HOME_DIR — it should follow.
+    expect(cfg.ALLOWLIST_DIR).toBe('/tmp/sandbox-home-99/.config/parachute-agent');
+  });
+
+  it('does NOT route through PARACHUTE_HOME (operator-policy stays at <HOME>/.config)', async () => {
+    // paraclaw#99 path 2 contract: PARACHUTE_HOME reroutes runtime state
+    // (DB + master.key) but NOT operator-host policy (mount-allowlist).
+    // Pin the split — if a future refactor accidentally collapses the two,
+    // sandboxes would silently see different mount permissions than the
+    // live install they share a host with.
+    process.env.HOME = '/Users/operator';
+    process.env.PARACHUTE_HOME = '/tmp/sandbox-home-collapse-check';
+    try {
+      const cfg = await import('../../config.js');
+      expect(cfg.PARACHUTE_DIR).toBe('/tmp/sandbox-home-collapse-check');
+      // CENTRAL_DB_DIR follows PARACHUTE_HOME — runtime state.
+      expect(cfg.CENTRAL_DB_DIR).toBe('/tmp/sandbox-home-collapse-check/agent');
+      // ALLOWLIST_DIR does NOT — operator-host policy.
+      expect(cfg.ALLOWLIST_DIR).toBe('/Users/operator/.config/parachute-agent');
+      expect(cfg.MOUNT_ALLOWLIST_PATH).toBe('/Users/operator/.config/parachute-agent/mount-allowlist.json');
+    } finally {
+      delete process.env.PARACHUTE_HOME;
+    }
+  });
+});

package/src/modules/mount-security/index.ts

@@ -4,14 +4,22 @@
  * Validates additional mounts against an allowlist stored OUTSIDE the project root.
  * This prevents container agents from modifying security configuration.
  *
- * Allowlist location: ~/.config/parachute-agent/mount-allowlist.json
- * (pre-0.1.0 installs auto-migrate from ~/.config/paraclaw/ on startup —
- * see migrateLegacyAllowlistDir below).
+ * Allowlist location: `<HOME>/.config/parachute-agent/mount-allowlist.json`
+ * (pre-0.1.0 installs auto-migrate from `<HOME>/.config/paraclaw/` on startup —
+ * see migrateLegacyAllowlistDir below). Path stays under `<HOME>/.config/`,
+ * NOT under `PARACHUTE_DIR`, because mount-allowlist is operator-host policy
+ * rather than per-install runtime state — see the doc-block on `ALLOWLIST_DIR`
+ * in src/config.ts (paraclaw#99).
+ *
+ * `HOME_DIR` is imported from src/config.ts so the precedence rule
+ * (`process.env.HOME` → `os.homedir()`) lives in one place. expandPath uses
+ * the same HOME_DIR for `~`-expansion in operator-supplied paths inside the
+ * allowlist (`~/projects` etc.), ensuring expansion agrees with the rest of
+ * the host process.
  */
 import fs from 'fs';
-import os from 'os';
 import path from 'path';
-import { ALLOWLIST_DIR, LEGACY_ALLOWLIST_DIR, MOUNT_ALLOWLIST_PATH } from '../../config.js';
+import { ALLOWLIST_DIR, HOME_DIR, LEGACY_ALLOWLIST_DIR, MOUNT_ALLOWLIST_PATH } from '../../config.js';
 import { log } from '../../log.js';
 
 export interface AdditionalMount {
@@ -119,15 +127,18 @@ export function loadMountAllowlist(): MountAllowlist | null {
 }
 
 /**
- * Expand ~ to home directory and resolve to absolute path
+ * Expand ~ to home directory and resolve to absolute path. `HOME_DIR` comes
+ * from src/config.ts so a future change to the precedence rule
+ * (`HOME` → `os.homedir()`) is one edit upstream rather than redrawn here.
+ * Exported for direct test coverage of the expansion (paraclaw#99); not
+ * intended for use outside this module.
  */
-function expandPath(p: string): string {
-  const homeDir = process.env.HOME || os.homedir();
+export function expandPath(p: string): string {
   if (p.startsWith('~/')) {
-    return path.join(homeDir, p.slice(2));
+    return path.join(HOME_DIR, p.slice(2));
   }
   if (p === '~') {
-    return homeDir;
+    return HOME_DIR;
   }
   return path.resolve(p);
 }

package/src/modules/permissions/sender-approval.test.ts

@@ -10,13 +10,23 @@
  *  - Approve path: member added, original message replayed via routeInbound,
  *    container woken
  *  - Deny path: pending row deleted, no member added
+ *  - Approve replay with attachment: row + file land cleanly at the
+ *    namespaced messages_in.id path (paraclaw#97)
+ *  - Approve replay with MUTATED original_message: on-disk attachment file
+ *    is preserved byte-for-byte; the dup-skip path absorbs the second write
+ *    so a path-normalization or any pre-replay mutation can't clobber state
+ *    that's already committed (paraclaw#97 — #96 invariant under the
+ *    sender-approval entry point)
  */
 import fs from 'fs';
+import path from 'path';
 import { beforeEach, afterEach, describe, expect, it, vi } from 'vitest';
 
+import { openDb } from '../../db/connection.js';
 import { initTestDb, closeDb, runMigrations } from '../../db/index.js';
 import { createAgentGroup } from '../../db/agent-groups.js';
 import { createMessagingGroup, createMessagingGroupAgent } from '../../db/messaging-groups.js';
+import { inboundDbPath, sessionDir } from '../../session-manager.js';
 import { upsertUser } from './db/users.js';
 import { grantRole } from './db/user-roles.js';
 
@@ -467,4 +477,165 @@ describe('unknown-sender request_approval flow', () => {
       .get('tg:stranger', 'ag-1');
     expect(member).toBeDefined();
   });
+
+  // ── paraclaw#97: replay-path coverage ──────────────────────────────────
+  //
+  // The unit tests above prove the response handler's bookkeeping (member
+  // added, pending row cleared, wake fired). The two tests below assert the
+  // full chain through routeInbound → writeSessionMessage on a message
+  // carrying a real attachment, plus the #96 file-clobber invariant under
+  // this entry point.
+
+  function strangerWithAttachment(textValue: string, attachmentBytes: Buffer) {
+    return {
+      channelType: 'telegram',
+      platformId: 'chat-123',
+      threadId: null,
+      message: {
+        id: 'tg-msg-with-att',
+        kind: 'chat' as const,
+        content: JSON.stringify({
+          senderId: 'tg:stranger',
+          senderName: 'Stranger',
+          text: textValue,
+          attachments: [
+            {
+              name: 'photo.jpg',
+              type: 'image',
+              size: attachmentBytes.length,
+              data: attachmentBytes.toString('base64'),
+            },
+          ],
+        }),
+        timestamp: now(),
+      },
+    };
+  }
+
+  it('approve replay → attachment lands cleanly at the namespaced messages_in.id path (paraclaw#97)', async () => {
+    const ORIGINAL_BYTES = Buffer.from('first-pic');
+    const event = strangerWithAttachment('see photo', ORIGINAL_BYTES);
+
+    const { routeInbound } = await import('../../router.js');
+    const { getResponseHandlers } = await import('../../response-registry.js');
+
+    // First route: gate denies (request_approval), pending row created. The
+    // wired agent has ignored_message_policy='drop', so no accumulate write
+    // happens — the replay will be the first writer of this messages_in.id.
+    await routeInbound(event);
+    await new Promise((r) => setTimeout(r, 10));
+
+    const { getDb } = await import('../../db/connection.js');
+    const pending = getDb().prepare('SELECT id FROM pending_sender_approvals').get() as { id: string };
+    expect(pending).toBeDefined();
+
+    for (const handler of getResponseHandlers()) {
+      const claimed = await handler({
+        questionId: pending.id,
+        value: 'approve',
+        userId: 'owner',
+        channelType: 'telegram',
+        platformId: 'dm-owner',
+        threadId: null,
+      });
+      if (claimed) break;
+    }
+
+    // The replay's deliverToAgent created the session — find it for the
+    // wired agent group and assert the row + file landed at the right spot.
+    const sess = getDb().prepare('SELECT id FROM sessions WHERE agent_group_id = ?').get('ag-1') as { id: string };
+    expect(sess).toBeDefined();
+
+    const inboundDb = openDb(inboundDbPath('ag-1', sess.id));
+    const rows = inboundDb.prepare('SELECT id, content FROM messages_in').all() as Array<{
+      id: string;
+      content: string;
+    }>;
+    inboundDb.close();
+
+    expect(rows).toHaveLength(1);
+    // messageIdForAgent namespaces the platform id with agent_group_id so a
+    // multi-agent fan-out can't collide on messages_in.id (router.ts).
+    const namespacedId = 'tg-msg-with-att:ag-1';
+    expect(rows[0].id).toBe(namespacedId);
+
+    // Row content carries localPath after extractAttachmentFiles ran post-
+    // commit; inline base64 is gone.
+    const parsed = JSON.parse(rows[0].content);
+    expect(parsed.attachments[0].localPath).toBe(`inbox/${namespacedId}/photo.jpg`);
+    expect(parsed.attachments[0].data).toBeUndefined();
+
+    const filePath = path.join(sessionDir('ag-1', sess.id), 'inbox', namespacedId, 'photo.jpg');
+    expect(fs.existsSync(filePath)).toBe(true);
+    expect(fs.readFileSync(filePath).equals(ORIGINAL_BYTES)).toBe(true);
+  });
+
+  it('approve replay with MUTATED original_message: on-disk file preserved (paraclaw#97 — #96 invariant)', async () => {
+    // Switch the wired agent to accumulate so the gate-denied first attempt
+    // writes the row + extracts the file BEFORE the approval card is acted
+    // on. This is the racing-dispatch shape #92 caught: two writers for the
+    // same messages_in.id, one from accumulate-on-gate-deny, one from the
+    // approval replay.
+    const { getDb } = await import('../../db/connection.js');
+    getDb()
+      .prepare(`UPDATE messaging_group_agents SET ignored_message_policy = 'accumulate' WHERE id = ?`)
+      .run('mga-1');
+
+    const ORIGINAL_BYTES = Buffer.from('first-pic');
+    const MUTATED_BYTES = Buffer.from('CLOBBERED');
+    const event = strangerWithAttachment('see photo', ORIGINAL_BYTES);
+
+    const { routeInbound } = await import('../../router.js');
+    const { getResponseHandlers } = await import('../../response-registry.js');
+
+    // First route: gate denies, but accumulate writes the row + extracts the
+    // file with ORIGINAL_BYTES.
+    await routeInbound(event);
+    await new Promise((r) => setTimeout(r, 10));
+
+    const sess = getDb().prepare('SELECT id FROM sessions WHERE agent_group_id = ?').get('ag-1') as { id: string };
+    expect(sess).toBeDefined();
+    const namespacedId = 'tg-msg-with-att:ag-1';
+    const filePath = path.join(sessionDir('ag-1', sess.id), 'inbox', namespacedId, 'photo.jpg');
+    expect(fs.readFileSync(filePath).equals(ORIGINAL_BYTES)).toBe(true);
+
+    // Mutate the pending row's original_message to carry MUTATED_BYTES. This
+    // mirrors any pre-replay normalization (path replacement, ContentRecord
+    // re-encoding, retry with re-fetched payload) that produces a JSON event
+    // whose attachment bytes don't match what's already on disk.
+    const pending = getDb().prepare('SELECT id FROM pending_sender_approvals').get() as { id: string };
+    expect(pending).toBeDefined();
+    const mutatedEvent = strangerWithAttachment('see photo', MUTATED_BYTES);
+    getDb()
+      .prepare('UPDATE pending_sender_approvals SET original_message = ? WHERE id = ?')
+      .run(JSON.stringify(mutatedEvent), pending.id);
+
+    // Approve. Replay's writeSessionMessage hits ON CONFLICT (id already
+    // present from the accumulate write), so extractAttachmentFiles never
+    // runs and the on-disk file stays put.
+    for (const handler of getResponseHandlers()) {
+      const claimed = await handler({
+        questionId: pending.id,
+        value: 'approve',
+        userId: 'owner',
+        channelType: 'telegram',
+        platformId: 'dm-owner',
+        threadId: null,
+      });
+      if (claimed) break;
+    }
+
+    // 1. File on disk is byte-for-byte the original — no mutated clobber.
+    const onDisk = fs.readFileSync(filePath);
+    expect(onDisk.equals(ORIGINAL_BYTES)).toBe(true);
+    expect(onDisk.equals(MUTATED_BYTES)).toBe(false);
+
+    // 2. Exactly one row in messages_in (the accumulate write); the replay
+    //    didn't slip a second row in.
+    const inboundDb = openDb(inboundDbPath('ag-1', sess.id));
+    const rows = inboundDb.prepare('SELECT id FROM messages_in').all() as Array<{ id: string }>;
+    inboundDb.close();
+    expect(rows).toHaveLength(1);
+    expect(rows[0].id).toBe(namespacedId);
+  });
 });

package/src/secrets/index.ts

@@ -94,22 +94,43 @@ export function putSecret(name: string, value: string, opts: PutSecretOpts = {})
   }
 
   const id = crypto.randomUUID();
-  db()
-    .prepare(
-      `INSERT INTO secrets
-         (id, name, value_encrypted, kind, agent_group_id, created_at, updated_at)
-       VALUES
-         (@id, @name, @value_encrypted, @kind, @agent_group_id, @created_at, @updated_at)`,
-    )
-    .run({
-      id,
-      name,
-      value_encrypted: ct,
-      kind,
-      agent_group_id: agentGroupId,
-      created_at: now,
-      updated_at: now,
-    });
+  // Auto-seed the matching `secret_assignments` row when the secret is
+  // scoped to a group (paraclaw#127). For a scoped secret the only valid
+  // assignment-row pair is (id, owning_group); the resolver only injects
+  // when `s.agent_group_id = g.id OR s.agent_group_id IS NULL`, so an
+  // assignment elsewhere is meaningless. Without this seed, scoped
+  // creates land orphaned under the default `selective` group mode and
+  // are silently invisible to `resolveInjectableSecrets`. INSERT path
+  // only — UPDATE/rotate leaves the existing assignment set alone.
+  // ON CONFLICT DO NOTHING for idempotency-on-replay (the constraint
+  // already exists in `replaceAssignments` for the same reason).
+  db().transaction(() => {
+    db()
+      .prepare(
+        `INSERT INTO secrets
+           (id, name, value_encrypted, kind, agent_group_id, created_at, updated_at)
+         VALUES
+           (@id, @name, @value_encrypted, @kind, @agent_group_id, @created_at, @updated_at)`,
+      )
+      .run({
+        id,
+        name,
+        value_encrypted: ct,
+        kind,
+        agent_group_id: agentGroupId,
+        created_at: now,
+        updated_at: now,
+      });
+    if (agentGroupId !== null) {
+      db()
+        .prepare(
+          `INSERT INTO secret_assignments (secret_id, agent_group_id, created_at)
+             VALUES (@secret_id, @agent_group_id, @created_at)
+             ON CONFLICT (secret_id, agent_group_id) DO NOTHING`,
+        )
+        .run({ secret_id: id, agent_group_id: agentGroupId, created_at: now });
+    }
+  })();
   return id;
 }
 
@@ -289,11 +310,12 @@ export interface StaleSession {
  * Note on a subtle asymmetry: `resolveInjectableSecrets` additionally gates
  * scoped secrets through `(secret_mode='all' OR assignment row exists)` on
  * the recipient group. The SQL here accepts the scoped match unconditionally.
- * The asymmetry is benign — the only configs where it would diverge (a
- * scoped secret paired with its parent group in `selective` mode and no
- * assignment row) are unreachable via the UI, which always seeds an
- * assignment row when scoping. If a future code path makes that config
- * reachable, tighten the SQL to add the same gate.
+ * The asymmetry is benign — the only config where it would diverge (a scoped
+ * secret in a `selective`-mode group with no assignment row) is structurally
+ * unreachable from `putSecret`: paraclaw#127 made the INSERT path auto-seed
+ * the (id, owning_group) assignment row in the same transaction. If a future
+ * code path bypasses `putSecret` and writes the orphan state directly, tighten
+ * the SQL to add the same gate.
  *
  * The host injects env vars at spawn time only — there is no in-process
  * update path. This helper powers the post-save banner that prompts the
@@ -353,3 +375,87 @@ export function getSecretById(id: string): SecretRow | undefined {
     .prepare<SecretRow>(`SELECT id, name, kind, agent_group_id, created_at, updated_at FROM secrets WHERE id = ?`)
     .get(id);
 }
+
+/**
+ * Why a secret lands in a particular agent group's injectable set:
+ *   - `scoped`   — secret is owned by this group (`s.agent_group_id = g.id`).
+ *   - `assigned` — global secret with an explicit `secret_assignments` row
+ *                  pointing at this group.
+ *   - `global`   — global secret with no assignment row, included only because
+ *                  the recipient group is in `secret_mode='all'`.
+ *
+ * When a global has BOTH an assignment row AND `secret_mode='all'`, we report
+ * `assigned` — the explicit row reflects deliberate operator intent, while
+ * mode='all' is a blanket setting; surfacing the more-specific reason makes
+ * the GroupDetail page actionable ("revoke this assignment" vs "flip to
+ * selective"). See paraclaw#104.
+ */
+export type SecretInclusionScope = 'global' | 'scoped' | 'assigned';
+
+export interface InjectableSecretView extends SecretRow {
+  scope: SecretInclusionScope;
+}
+
+/**
+ * Metadata-only mirror of `resolveInjectableSecrets` for the GroupDetail
+ * "Secrets" panel. Returns the same row set (subject to the same SQL gate)
+ * tagged with the inclusion reason — never decrypts. Caller is the read-only
+ * `GET /api/groups/:folder/secrets` route.
+ *
+ * The SQL mirrors `resolveInjectableSecrets` (the `(s.agent_group_id = g.id
+ * OR s.agent_group_id IS NULL)` row predicate gated by `(secret_mode='all'
+ * OR assignment exists)`) so the panel cannot disagree with what the
+ * container will actually receive at spawn time. Drift here would defeat
+ * the entire point of #104 — keep them in lockstep. If you change either,
+ * change both.
+ *
+ * `ORDER BY s.agent_group_id IS NULL` puts scoped rows first so the
+ * dedupe-by-name loop honors the "scoped wins on collision" rule
+ * `resolveInjectableSecrets` enforces.
+ */
+export function listInjectableSecretsForGroup(agentGroupId: string): InjectableSecretView[] {
+  const rows = db()
+    .prepare<{
+      id: string;
+      name: string;
+      kind: SecretKind;
+      agent_group_id: string | null;
+      created_at: string;
+      updated_at: string;
+      assignment_present: number;
+    }>(
+      `SELECT s.id, s.name, s.kind, s.agent_group_id, s.created_at, s.updated_at,
+              CASE WHEN a.secret_id IS NULL THEN 0 ELSE 1 END AS assignment_present
+         FROM secrets s
+         LEFT JOIN secret_assignments a
+           ON a.secret_id = s.id
+          AND a.agent_group_id = @agent_group_id
+         LEFT JOIN agent_groups g
+           ON g.id = @agent_group_id
+        WHERE (s.agent_group_id = @agent_group_id OR s.agent_group_id IS NULL)
+          AND (g.secret_mode = 'all' OR a.secret_id IS NOT NULL)
+        ORDER BY s.agent_group_id IS NULL, s.name`,
+    )
+    .all({ agent_group_id: agentGroupId });
+
+  const out: InjectableSecretView[] = [];
+  const seen = new Set<string>();
+  for (const row of rows) {
+    if (seen.has(row.name)) continue;
+    seen.add(row.name);
+    let scope: SecretInclusionScope;
+    if (row.agent_group_id === agentGroupId) scope = 'scoped';
+    else if (row.assignment_present === 1) scope = 'assigned';
+    else scope = 'global';
+    out.push({
+      id: row.id,
+      name: row.name,
+      kind: row.kind,
+      agent_group_id: row.agent_group_id,
+      created_at: row.created_at,
+      updated_at: row.updated_at,
+      scope,
+    });
+  }
+  return out;
+}