@replayio/app-building 1.32.0 → 1.34.0

package/README.md

@@ -63,16 +63,146 @@ Secrets are never passed directly to the container or agent. Instead:
 2. At startup, the container fetches global secrets from Infisical for internal use (clone token, agent API key).
 3. A **secrets server** (`127.0.0.1:9119`) runs inside the container, accessible only locally. It fetches secrets live from Infisical on every request — no caching.
 4. The agent process runs with a **restricted environment** — only `ANTHROPIC_API_KEY` (required for the Claude CLI) is present.
-5. When the agent needs to run a command that requires secrets, it uses `exec-secrets`:
+5. Any time a secret is needed, the caller invokes `exec-secrets`:
 
-```bash
-exec-secrets NEON_API_KEY -- curl -s -H "Authorization: Bearer $NEON_API_KEY" https://...
-exec-secrets NETLIFY_AUTH_TOKEN NETLIFY_ACCOUNT_SLUG -- netlify deploy --prod
+   ```bash
+   exec-secrets <SECRET1> [SECRET2 …] -- <target> [args …]
+   ```
+
+   The secrets server spawns the target with the named secrets in its
+   environment and **redacts those secret values from the output**.
+
+`exec-secrets` is invoked recursively. The agent's own shell has no secrets,
+so when it runs an app script — `npm run test`, `npm run deploy`, a seed
+script, a migration — that script calls `exec-secrets` itself for each
+operation that needs a secret. One agent task can produce dozens of
+`exec-secrets` invocations from inside scripts it never directly typed.
+
+### Three commands you'll see
+
+| Command | Purpose |
+|---|---|
+| `exec-secrets <SECRETS…> -- <target> [args…]` | Run `<target>` with the named secrets injected, output redacted. |
+| `list-secrets` | Print the secret names the container can resolve. With an allowlist configured, also prints the allowed targets. |
+| `set-branch-secret <NAME> <value>` | Store a new branch-scoped secret in Infisical (e.g. `DATABASE_URL` after provisioning Neon). Rejected if `<value>` has already appeared in logs. |
+
+In **unrestricted mode** (no allowlist), `<target>` is any binary the
+container has installed — `curl`, `psql`, `npx netlify`, etc. In
+**restricted mode** (allowlist configured), `<target>` must be one of the
+allowlist entry names; see Allowlist mode below.
+
+### Allowlist mode
+
+Set `ContainerConfig.secretAllowlist` to restrict the set of secret-using
+operations available in the container. With an allowlist configured, every
+`exec-secrets` call — whether issued directly by the agent or by an app
+script the agent runs (`npm run test`, deploy scripts, seed scripts,
+migrations) — must name an entry; calls naming an arbitrary binary are
+rejected.
+
+Each entry is `{ name, helpString, shellCommand }`. The shellCommand body
+runs under `sh -c`; positional args supplied after the target become `$1`,
+`$2`, … and the named secrets are present in the environment.
+
+#### Design principle: one entry per verb
+
+Each entry should encode **one specific operation**. The `shellCommand`
+hardcodes URL, method, file path, and any other fixed structure; positional
+args carry only the data the operation needs. The caller supplies "what to
+operate on", never "what to do".
+
+#### Good entries
+
+```ts
+secretAllowlist: [
+  {
+    name: "neon-create-branch",
+    helpString: "Create a Neon branch. Args: <project_id> <branch_name>",
+    shellCommand:
+      'curl -fsS -X POST "https://console.neon.tech/api/v2/projects/$1/branches" ' +
+      '-H "Authorization: Bearer $NEON_API_KEY" ' +
+      '-H "Content-Type: application/json" ' +
+      '-d "{\\"branch\\":{\\"name\\":\\"$2\\"}}"',
+  },
+  {
+    name: "neon-delete-branch",
+    helpString: "Delete a Neon branch. Args: <project_id> <branch_id>",
+    shellCommand:
+      'curl -fsS -X DELETE "https://console.neon.tech/api/v2/projects/$1/branches/$2" ' +
+      '-H "Authorization: Bearer $NEON_API_KEY"',
+  },
+  {
+    name: "netlify-deploy-prod",
+    helpString: "Deploy the current build to production. No args.",
+    shellCommand:
+      'npx netlify deploy --prod --auth "$NETLIFY_AUTH_TOKEN" --site "$NETLIFY_SITE_ID"',
+  },
+  {
+    name: "replay-upload-all",
+    helpString: "Upload all pending Replay recordings. No args.",
+    shellCommand: 'npx replayio upload --all --api-key "$RECORD_REPLAY_API_KEY"',
+  },
+]
 ```
 
-The secrets server spawns the command with the requested secrets in its environment and **redacts requested secret values** from the output.
+Each of these:
+
+- Pins the URL, method, and headers — the caller can't redirect a Neon API
+  token at a different host or use it for an operation that wasn't allowed.
+- Pins the binary and its flags — Netlify / Replay invocations always carry
+  the right auth and the intended verb.
+- Takes data only — branch names, project IDs, etc.
+
+#### Anti-patterns
+
+Don't pass `"$@"` through to a primitive tool. These look like allowlist
+entries but they're not constraining anything:
+
+```ts
+// BAD — caller can curl any URL with the Neon token attached.
+{ name: "curl",  shellCommand: 'curl "$@"' }
+// BAD — caller can run arbitrary SQL, including `\!` shell escapes.
+{ name: "psql",  shellCommand: 'psql "$@"' }
+// BAD — caller can run arbitrary JS with every secret in env.
+{ name: "node",  shellCommand: 'node "$@"' }
+// BAD — sh/bash with -c is identical to "run anything".
+{ name: "shell", shellCommand: 'sh -c "$1"' }
+```
 
-The agent can also run `list-secrets` to see which secrets are available, and `set-branch-secret` to store new branch-level secrets (e.g., `DATABASE_URL` created at deploy time). The server rejects credential values that have already appeared in logs.
+If the same upstream API has ten operations the app needs, write ten
+entries — each hardcoding URL + method + headers, each taking only the
+data fields the operation requires.
+
+#### In-repo scripts aren't a security boundary
+
+The allowlist only constrains operations whose semantics live **outside the
+repo** — upstream HTTP APIs, third-party CLIs invoked with fixed flags. For
+anything that runs code the agent wrote (`npx tsx scripts/seed-db.ts`,
+`node scripts/migrate.js`, `npm run <anything>`), the agent controls the
+file contents and can do whatever it likes with the secrets in env.
+Pinning a path doesn't help — the agent can edit the file.
+
+So: do **not** add allowlist entries that exist to run an in-repo script.
+Instead, write narrow API-level entries (`neon-create-branch`,
+`netlify-env-set`, …) and have the in-repo script call `exec-secrets` for
+each of those verbs as needed. The allowlist then describes the set of
+operations the system supports, and the agent's code composes them.
+
+#### Behavior when configured
+
+- `list-secrets` returns `{ secrets, allowlist }` — `secrets` are the names
+  available before `--`; `allowlist` is `name — helpString` per entry,
+  available as targets after `--`.
+- `exec-secrets <SECRET1> [SECRET2 …] -- <name> [args…]`: named secrets are
+  injected into env (and only those values are redacted from output);
+  `<name>` must match an entry; `[args…]` become `$1`, `$2`, … inside the
+  entry's `shellCommand`. `$0` is `"exec-secrets"`.
+- Targets not in the allowlist are rejected with `Unknown allowlist entry`.
+
+`secretAllowlist` is serialized into the container as `SECRET_ALLOWLIST_JSON`;
+the secrets server parses it on startup. To swap or clear the allowlist on
+a running container without restarting, POST to `/reconfigure` (see
+Container HTTP API).
 
 ## Exported API
 
@@ -80,8 +210,9 @@ The agent can also run `list-secrets` to see which secrets are available, and `s
 
 | Export | Description |
 |---|---|
-| `ContainerConfig` | `infisical` (required `InfisicalConfig`), optional `projectRoot` (local Docker only), `registry`, `flyToken`/`flyApp` (set both for remote Fly.io), `flyGuest` (override Fly Machine guest sizing; default: 16 performance CPUs / 32 GiB), `flyVolumeSizeGb` (override Fly Volume size in GiB; default: 50), `imageRef`, `webhookUrl`/`webhookSecret`, `taskWebhookUrl` (GET endpoint for external task queue), `addTaskWebhookUrl` (POST endpoint for tasks added by `add-task` script), `detached`, `initialPrompt`, `localPort`, `absorbTasks`, `namePrefix` (default: `"app-building"`), `env` (extra env vars to inject into the container; cannot clobber package-reserved vars). |
+| `ContainerConfig` | `infisical` (required `InfisicalConfig`), optional `projectRoot` (local Docker only), `registry`, `flyToken`/`flyApp` (set both for remote Fly.io), `flyGuest` (override Fly Machine guest sizing; default: 16 performance CPUs / 32 GiB), `flyVolumeSizeGb` (override Fly Volume size in GiB; default: 50), `imageRef`, `webhookUrl`/`webhookSecret`, `taskWebhookUrl` (GET endpoint for external task queue), `addTaskWebhookUrl` (POST endpoint for tasks added by `add-task` script), `detached`, `initialPrompt`, `localPort`, `absorbTasks`, `namePrefix` (default: `"app-building"`), `env` (extra env vars to inject into the container; cannot clobber package-reserved vars), `secretAllowlist` (curated `exec-secrets` commands — see Secrets architecture > Allowlist mode). |
 | `FlyGuest` | Fly Machine guest spec: `cpu_kind` (`"shared"` \| `"performance"`), `cpus`, `memory_mb`. |
+| `SecretAllowlistEntry` | `name` (verb used with `exec-secrets`), `helpString` (one-line description shown by `list-secrets`), `shellCommand` (sh script body; args become `$1`, `$2`, …). |
 | `RepoOptions` | Per-invocation git settings: `repoUrl`, `cloneBranch`, `pushBranch`. |
 | `AgentState` | Returned by `startContainer`. Contains `type`, `containerName`, `port`, `baseUrl`, and Fly-specific fields for remote containers. |
 | `ContainerRegistry` | Interface for container registry storage. Methods: `log`, `markStopped`, `clearStopped`, `getRecent`, `find`, `findAlive`. |
@@ -162,6 +293,7 @@ Each container runs an HTTP server that accepts the following requests:
 | `POST /detach` | | Signal the container to exit once all tasks are done. |
 | `POST /stop` | | Force-stop the container immediately. Interrupts any running work, commits remaining changes, then exits. |
 | `POST /interrupt` | | Kill the currently running Claude process without stopping the container. |
+| `POST /reconfigure` | `{ secretAllowlist?: SecretAllowlistEntry[] \| null }` | Live-update container config. Omit to leave unchanged; `null` for unrestricted mode (`exec-secrets <SECRETS…> -- <cmd>` runs any binary); `[]` for restricted mode with zero entries (rejects every target); an array of entries to replace. Returns `{ ok: true }`. |
 | `GET /status` | | Container state, queue depth, iteration count, cost, revision, etc. |
 | `GET /events?offset=N` | | Stream of Claude events (JSON lines) since offset. |
 | `GET /logs?offset=N` | | Stream of log lines since offset. |

package/dist/index.d.ts

@@ -125,6 +125,29 @@ interface ContainerConfig {
      * always take precedence — values here cannot clobber them.
      */
     env?: Record<string, string>;
+    /**
+     * Allowlist of named shell commands the agent may invoke via `exec-secrets`.
+     * When set, `list-secrets` returns the allowlist (instead of raw secret
+     * names) and `exec-secrets <name> [args…]` runs the named entry's
+     * `shellCommand` with `args` mapped to positional params (`$1`, `$2`, …).
+     * All secrets are available in the command's environment; their values are
+     * redacted from output. When no allowlist is set, the container runs in
+     * unrestricted mode and `exec-secrets <SECRET…> -- <cmd>` may invoke any
+     * binary; with an allowlist set, the target after `--` must name an entry.
+     */
+    secretAllowlist?: SecretAllowlistEntry[];
+}
+interface SecretAllowlistEntry {
+    /** Name the agent uses with `exec-secrets <name>` (e.g. "neon-query"). */
+    name: string;
+    /** One-line description shown by `list-secrets`. */
+    helpString: string;
+    /**
+     * Shell script body. Invoked as `sh -c <shellCommand> exec-secrets <args…>`,
+     * so caller-supplied args become `$1`, `$2`, … and `$0` is `exec-secrets`.
+     * All secrets are present in the environment.
+     */
+    shellCommand: string;
 }
 interface RepoOptions {
     repoUrl: string;
@@ -202,4 +225,4 @@ interface Task {
  */
 declare function findReadyTask(pendingTasks: Task[], completedTasks: Pick<Task, "id" | "parentTaskId">[]): Task | null;
 
-export { type AgentState, type ContainerConfig, type ContainerRegistry, FileContainerRegistry, type FlyGuest, type HttpOptions, type InfisicalConfig, type RegistryEntry, type RepoOptions, type Task, buildImage, createBranchSecret, fetchBranchSecrets, fetchGlobalSecrets, fetchInfisicalSecrets, findReadyTask, getImageRef, getInfisicalConfig, httpGet, httpOptsFor, httpPost, infisicalLogin, loadDotEnv, probeAlive, spawnTestContainer, startContainer, stopContainer };
+export { type AgentState, type ContainerConfig, type ContainerRegistry, FileContainerRegistry, type FlyGuest, type HttpOptions, type InfisicalConfig, type RegistryEntry, type RepoOptions, type SecretAllowlistEntry, type Task, buildImage, createBranchSecret, fetchBranchSecrets, fetchGlobalSecrets, fetchInfisicalSecrets, findReadyTask, getImageRef, getInfisicalConfig, httpGet, httpOptsFor, httpPost, infisicalLogin, loadDotEnv, probeAlive, spawnTestContainer, startContainer, stopContainer };

package/dist/index.js

@@ -256,6 +256,9 @@ function buildExtraEnv(config, containerName) {
   if (config.env && Object.keys(config.env).length > 0) {
     extra.AGENT_ENV_PASSTHROUGH = Object.keys(config.env).join(",");
   }
+  if (config.secretAllowlist !== void 0) {
+    extra.SECRET_ALLOWLIST_JSON = JSON.stringify(config.secretAllowlist);
+  }
   return extra;
 }
 function isRemote(config) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@replayio/app-building",
-  "version": "1.32.0",
+  "version": "1.34.0",
   "description": "Library for managing agentic app-building containers",
   "type": "module",
   "exports": {