@replayio/app-building 1.32.0 → 1.33.0

package/README.md

@@ -74,14 +74,45 @@ The secrets server spawns the command with the requested secrets in its environm
 
 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.
 
+### 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 }`:
+
+```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",
+    },
+  ],
+};
+```
+
+When configured:
+
+- `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.
+
+`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
 
 ### Domain objects
 
 | 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 +193,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.33.0",
   "description": "Library for managing agentic app-building containers",
   "type": "module",
   "exports": {