@replayio/app-building 1.33.0 → 1.34.0

package/README.md

@@ -63,46 +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**.
 
-The secrets server spawns the command with the requested secrets in its environment and **redacts requested 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.
 
-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.
+### 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 which commands the agent may invoke via `exec-secrets`. The allowlist constrains the *target* — the agent still names which secrets to inject in each call. Each entry is `{ name, helpString, shellCommand }`:
+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
-const config: ContainerConfig = {
-  ...,
-  secretAllowlist: [
-    {
-      name: "neon-query",
-      helpString: "Run a SQL query against the project's Neon database. Usage: exec-secrets DATABASE_URL -- neon-query <sql>",
-      shellCommand: 'psql "$DATABASE_URL" -c "$1"',
-    },
-    {
-      name: "netlify-deploy",
-      helpString: "Deploy the app to production.",
-      shellCommand: "netlify deploy --prod --auth $NETLIFY_AUTH_TOKEN --site $NETLIFY_SITE_ID",
-    },
-  ],
-};
+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"',
+  },
+]
 ```
 
-When configured:
+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.
 
-- `list-secrets` returns both `secrets` (available secret names) and `allowlist` (`name — helpString` per entry).
-- `exec-secrets` keeps the same surface: `exec-secrets <SECRET1> [SECRET2 …] -- <name> [args…]`. The named secrets are still injected into env (and only those values are redacted from output); `<name>` must match an allowlist entry, and `[args…]` become positional params (`$1`, `$2`, …) inside that entry's `shellCommand`. `$0` is `"exec-secrets"`.
-- Targets not in the allowlist are rejected — the agent can't invoke arbitrary binaries.
+#### 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"' }
+```
 
-`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).
+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
 

package/package.json

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