deepdebug-local-agent 1.0.22 → 1.1.0

package/docs/legacy-connectors.md

@@ -0,0 +1,268 @@
+# Legacy connectors — configuration & troubleshooting
+
+Phase 2 of VisionHammer ships five Node.js EventEmitter adapters that ingest
+logs from legacy on-prem systems into the DeepDebug pipeline. This document is
+the operator's reference for enabling and tuning them.
+
+## Quick start
+
+1. Read [Setup](#setup) to configure your GitHub PAT (only needed if you plan to
+   run `npm run sync-fixtures` to refresh test fixtures).
+2. Set `LEGACY_STACKS=<stacks>` in the agent's environment to choose which
+   adapters boot. Example: `LEGACY_STACKS=sap,cobol`.
+3. Provide per-adapter config via env or `agent.yaml` (see
+   [Configuration](#configuration) below).
+4. Restart the local agent. Adapters start automatically and stop within 5 s on
+   `SIGTERM`.
+
+## Setup
+
+The `npm run sync-fixtures` script clones the
+`williambella/visionhammer-example-*` GitHub repos to refresh
+`test/fixtures/<stack>/` from upstream. It needs a GitHub PAT.
+
+1. On github.com → Developer settings → Personal access tokens → Tokens
+   (classic) → Generate new token. Scope: `repo` (read-only is sufficient).
+2. Save the PAT to `~/.config/visionhammer/github-pat` with permissions `0600`:
+   ```bash
+   mkdir -p ~/.config/visionhammer
+   echo "YOUR_PAT_HERE" > ~/.config/visionhammer/github-pat
+   chmod 600 ~/.config/visionhammer/github-pat
+   ```
+3. **Never paste** the PAT into a shell env var. The script reads the file
+   directly at invocation time and validates the token against `GET /user`
+   before any clone. (T-2-04 + T-2-05 mitigation.)
+
+## Configuration
+
+Adapters are configured via the `LEGACY_STACKS` env var (which stacks to boot)
+plus per-adapter env vars or `agent.yaml` entries.
+
+### Supported stacks
+
+| Stack          | Adapter dir                | Default config                                                          | Required mounts/access                                                        |
+| -------------- | -------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `sap`          | `src/adapters/sap/`        | `{sapDir: '/usr/sap/PRD', instanceNumber: '00', interval: 5000}`        | NFS/SMB mount of `/usr/sap/<SID>/` readable by the agent user                 |
+| `ibmmq`        | `src/adapters/ibmmq/`      | `{errorsDir: '/var/mqm/qmgrs/QM_PRD01/errors', interval: 5000}`         | Read access to qmgr `errors/` directory                                       |
+| `as400`        | `src/adapters/as400/`      | `{host: 'as400-prd-01', port: 22, pollInterval: 30000}`                 | SSH credentials (password OR private-key); user with `DSPLOG` authority       |
+| `oracle-forms` | `src/adapters/oracle-forms/` | `{traceDir: '/u01/oracle/forms/trace', interval: 5000}`               | Read access to `FORMS_TRACE_DIR`                                              |
+| `cobol`        | `src/adapters/cobol/`      | `{spoolDir: '/var/spool/jes2', interval: 5000}`                         | Read access to JES2 spool export dir                                          |
+
+Glob anchors (per-adapter, hard-coded):
+
+- **SAP** watches `<sapDir>/D<instanceNumber>/work/dev_w*` AND
+  `<sapDir>/D<instanceNumber>/log/SLOG*` (T-2-03 mitigation — narrow regex
+  surface).
+- **IBM MQ** watches `<errorsDir>/AMQERR*.LOG` then enforces filename anchor
+  `^AMQERR0[1-3]\.LOG$` in-handler (chokidar bracket-class workaround on macOS
+  / Node 24 / chokidar 3.6.0).
+- **Oracle Forms** watches `<traceDir>/*.trc` only (`*.log` is **not** read).
+- **COBOL** watches `<spoolDir>/*` with `depth: 0` (broad spool glob — JES2
+  exports use arbitrary file names; non-files are filtered with `isFile()`).
+- **AS/400** does NOT watch files; it polls the literal command
+  `system "DSPLOG OUTPUT(*PRINT) LOGTYPE(*MSG) MSGTYPE(*ESCAPE *NOTIFY)"` over
+  SSH every `pollInterval` ms.
+
+### Per-adapter config sub-objects
+
+The registry's
+`loadAdapters({legacyStacks, sap, ibmmq, as400, 'oracle-forms', cobol})`
+accepts one sub-object per stack. Each is passed straight to the adapter
+constructor. Override defaults by setting the corresponding key. Example:
+
+```javascript
+import { loadAdapters, stopAll } from "./src/adapters/index.js";
+
+const adapters = loadAdapters({
+  legacyStacks: ['sap', 'cobol'],
+  sap:   { sapDir: '/sapmnt/PRD', instanceNumber: '01', interval: 10000 },
+  cobol: { spoolDir: '/mnt/zos/spool', interval: 30000 },
+});
+
+for (const a of adapters) await a.start();
+// ... later, on shutdown
+await stopAll(adapters, 5000);
+```
+
+`loadAdapters` returns adapters **unstarted** (AD-1 contract). The caller owns
+the lifecycle. The `LEGACY_STACKS` env-var bootstrap path in `src/server.js`
+already wires `loadAdapters` + `start()` for you when the env var is set.
+
+## Event shape
+
+Every adapter emits `error` events with EXACTLY this shape (frozen, 6 keys, no
+extras — alphabetical key order matters for the failsafe contract test):
+
+```javascript
+{
+  adapter:   'sap' | 'ibmmq' | 'as400' | 'oracle-forms' | 'cobol',
+  errorCode: 'ORA-01403' | 'AMQ7472W' | 'CPF1234' | 'S0C7' | null,
+  file:      '/usr/sap/PRD/D00/work/dev_w0',
+  message:   '<verbatim matched line>',
+  source:    '/usr/sap/PRD/D00/work',
+  timestamp: '2024-01-15T09:12:44.000Z'
+}
+```
+
+Per AD-5, events are ordered by byte position **within a single file**.
+Cross-file and cross-adapter ordering are explicit non-guarantees — the
+downstream gateway pipeline correlates by `incidentId`, not by event sequence.
+
+`timestamp` is the moment the adapter detected the line (not the timestamp
+inside the log line — log-line timestamps have inconsistent precision across
+formats).
+
+## Sync fixtures script
+
+```bash
+# Sync all 5 stacks
+npm run sync-fixtures
+
+# Sync only a subset
+node scripts/sync-fixtures.mjs --stacks=oracle-forms,cobol
+```
+
+What it does, in order, for each requested stack:
+
+1. Reads the PAT once from `~/.config/visionhammer/github-pat`.
+2. Validates the PAT via `GET https://api.github.com/user` (T-2-05).
+3. Shallow-clones `williambella/visionhammer-example-<stack>` to
+   `/tmp/sync-<stack>` via `git clone --depth 1 --branch main` with the PAT
+   embedded in the URL **only as a `child_process.spawn` argv element**, never
+   echoed to stdout/stderr/argv-string/env (T-2-04).
+4. Copies `samples/*.log` (case-insensitive) into `test/fixtures/<dir>/`
+   (mapping: `sap-abap → sap`, `ibm-mq → ibmmq`, others identity).
+5. Renames IBM MQ fixtures so they pass the adapter's `^AMQERR0[1-3]\.LOG$`
+   filename anchor:
+
+   | Source filename                          | Target filename |
+   | ---------------------------------------- | --------------- |
+   | `ibm-mq-sample-mqrc-2033.log`            | `AMQERR01.LOG`  |
+   | `ibm-mq-sample-mqrc-2058.log`            | `AMQERR02.LOG`  |
+   | `ibm-mq-sample-resource-leak.log`        | `AMQERR03.LOG`  |
+
+6. Removes the `/tmp/sync-<stack>` clone scratch dir.
+
+Idempotent — re-runs cleanly overwrite prior fixtures and rewipe scratch dirs.
+On git failure the embedded PAT is replaced with `***REDACTED***` before
+stderr is written.
+
+## Example fixture repos
+
+| Stack             | Repo                                                                                       |
+| ----------------- | ------------------------------------------------------------------------------------------ |
+| Oracle Forms 12c  | [williambella/visionhammer-example-oracle-forms](https://github.com/williambella/visionhammer-example-oracle-forms) |
+| Oracle PL/SQL     | [williambella/visionhammer-example-plsql](https://github.com/williambella/visionhammer-example-plsql)               |
+| SAP ABAP          | [williambella/visionhammer-example-sap-abap](https://github.com/williambella/visionhammer-example-sap-abap)         |
+| COBOL / z/OS      | [williambella/visionhammer-example-cobol](https://github.com/williambella/visionhammer-example-cobol)               |
+| IBM MQ Java       | [williambella/visionhammer-example-ibm-mq](https://github.com/williambella/visionhammer-example-ibm-mq)             |
+
+Each repo carries: an intentional-bug `README.md`, source code reproducing each
+bug, `samples/<stack>-sample-<n>.log` synthetic logs, and `samples/README.md`
+with `## Source citation`, `## Product version`, and
+`## Zero PII confirmation` sections per AD-6.
+
+## Troubleshooting
+
+### CPU usage too high (T-2-01)
+
+Default poll intervals are conservative (5 s for chokidar-based adapters,
+30 s for AS/400 SSH). If you see elevated CPU on the agent host or the legacy
+system:
+
+- Increase `interval` for chokidar adapters (sap, ibmmq, oracle-forms, cobol).
+  Try `10000` (10 s) first.
+- Increase `pollInterval` for AS/400. Try `60000` (60 s).
+- Do **not** set `interval < 1000`. NFS/SMB watch polling at sub-second cadence
+  is pathological for production systems.
+
+### AS/400 SSH session keeps dropping (T-2-02)
+
+The AS/400 adapter uses SSH keepalive (`keepaliveInterval: 30000` ×
+`keepaliveCountMax: 3` = 90 s tolerance) and auto-reconnects on `'close'` with
+exponential backoff:
+
+```
+1 s → 2 s → 4 s → 8 s → 16 s → 32 s → 60 s (cap)
+```
+
+Backoff resets to 1 s on successful re-auth (`'ready'` event).
+
+To verify reconnect health: tail the agent log; `'close'` events should be
+followed by a successful `'ready'` within ~60 s. If reconnect storms occur:
+
+- Verify the AS/400 SSH server's idle timeout setting. Some SSH daemons close
+  sessions despite keepalive; tune the daemon's `ClientAliveInterval` higher
+  than 30 s.
+- Check network MTU between the agent and AS/400. Fragmented keepalive packets
+  get dropped.
+- The polling cadence (`pollInterval`, default 30 s) is independent of the
+  keepalive cadence — they run on separate timers.
+
+### `npm run sync-fixtures` fails with "GitHub credentials not configured"
+
+Confirm `~/.config/visionhammer/github-pat` exists, is readable by the agent
+user, and contains a valid PAT with `repo` scope. The script reads this file
+once at invocation; it never accepts a PAT from env vars. (T-2-04 mitigation.)
+
+### `npm run sync-fixtures` fails with "PAT validation failed"
+
+The PAT validity gate (`GET /user`) returned a non-200 status. Causes:
+
+- PAT expired or revoked. Regenerate at github.com/settings/tokens.
+- PAT lost `repo` scope. Regenerate.
+- Network failure to api.github.com. Re-run when connectivity returns.
+
+### `npm run sync-fixtures` partial failure for one stack
+
+The script aborts on first failure (per current implementation) so each clone
+gates the next. Common causes:
+
+- Repo deleted from `williambella/visionhammer-example-<stack>`. Recreate by
+  re-running Phase 2 / Plan 02-0X (where X = 2..6).
+- Stack name typo in `--stacks=`. Allowed values:
+  `oracle-forms,plsql,sap-abap,cobol,ibm-mq`.
+- Network failure mid-clone. Re-run the script.
+
+### SIGTERM doesn't shut down adapters cleanly
+
+The `SIGTERM` handler in `src/server.js` calls `stopAll(_legacyAdapters, 5000)`
+— adapters have 5 s to release file handles + close SSH. The 5-s budget is
+enforced by an `unref`'d timer racing the `Promise.all` of per-adapter
+`stop()` calls; per-adapter exceptions are swallowed so the shutdown path
+always returns.
+
+If a process refuses to exit altogether, that's a separate concern: the
+`local-agent` process keeps an `express` listener (`PORT`) and an MCP HTTP
+listener (`MCP_PORT`) open, plus an optional WebSocket reverse tunnel. Those
+are not closed by the SIGTERM handler today (pre-existing local-agent
+architecture). Set `DISABLE_WS_TUNNEL=true` to drop the WS half; the express
++ MCP listeners require a separate explicit close path.
+
+For the **legacy connector contract specifically** — `stopAll(adapters, 5000)`
+is verified to resolve within 5 s (registry contract test
+`stopAll respects timeout — slow stop does not block forever`).
+
+### Adapter logs nothing
+
+Possible causes by adapter:
+
+- **All chokidar adapters** — TAIL mode is the default. Newly-appended lines
+  emit; existing content does not. To replay a file from byte 0 set
+  `replayOnStart: true` in the adapter config.
+- **SAP / IBM MQ / Oracle Forms / COBOL** — verify the watched directory
+  exists; ENOENT is silent by design (legitimate state for newly-provisioned
+  systems).
+- **IBM MQ** — only `AMQERR01.LOG`, `AMQERR02.LOG`, `AMQERR03.LOG` are read.
+  `AMQERR04.LOG` and other names are silently dropped at the in-handler anchor
+  regex.
+- **AS/400** — verify SSH connectivity (`ssh -p 22 user@as400-prd-01 'system DSPLOG'`).
+  ENOENT-equivalent (unreachable host) shows in the agent stderr only on the
+  first `'close'` failure; subsequent reconnect attempts are silent.
+
+## Field references
+
+- 02-SPEC.md: `~/Documents/Projects/visionhammer-agents/.planning/phases/02-legacy-stack-support/02-SPEC.md`
+- Phase 3 (LegacyErrorPatterns Java catalog): consumes `test/fixtures/<stack>/`
+  as test fixtures.
+- Phase 6 (E2E smoke): re-uses the example repos as workspaces.

package/docs/releasing.md

@@ -0,0 +1,43 @@
+# Releasing the local agent
+
+Two artefacts are released: the npm package `deepdebug-local-agent` and the
+public BYOC image `local-agent-full`. Nothing here runs on a normal push.
+
+## npm package
+
+`.github/workflows/npm-publish.yml` runs on every push to `main` that touches
+`src/**`, `package.json` or `bin/**`, and bumps the **patch** version
+automatically (from the highest of the latest `v*` tag and `package.json`).
+That is right for routine fixes and wrong for a minor release: with
+`package.json` at `1.1.0` the automatic bump would publish `1.1.1`.
+
+To publish an exact version (for example `1.1.0`):
+
+1. Leave `package.json` as it is. Do **not** bump it in a PR (a push to `main`
+   would trigger the automatic patch bump).
+2. Actions → **Publish NPM Package** → *Run workflow* on `main`, input
+   `version` = `1.1.0`. The workflow validates `X.Y.Z`, requires it to be
+   greater than the highest existing tag and `package.json`, runs
+   `npm version 1.1.0`, publishes with provenance, then pushes the bump commit
+   and the `v1.1.0` tag.
+3. Left empty, the input keeps the old behaviour (automatic patch bump).
+
+Prerequisite (owner of the npm package): Trusted Publisher configured for
+`VISIONHAMMER/deepdebug-local-agent`, workflow `npm-publish.yml` (see the
+header of the workflow). Without it the publish step fails and no version is
+burned.
+
+Heads-up: merging any PR that changes `src/**` to `main` starts an automatic
+patch publish (for example `1.0.39`) once the Trusted Publisher exists. To
+release `1.1.0` as the next version, dispatch it before merging further
+`src/**` changes, or merge with `[skip ci]` in the commit message.
+
+## BYOC image (`local-agent-full`)
+
+Tags pushed by `npm-publish.yml` use `GITHUB_TOKEN` and do not trigger other
+workflows, so after the npm release run Actions → **Build BYOC Agent Image**
+on `main` with `version` = `1.1.0`
+(see `docs/byoc-agent-image.md`). Tick `supply_chain` to also sign the image
+(cosign keyless), attach the SBOM and the provenance, and verify them.
+For `v*` tag and release runs the same job runs when the repository variable
+`BYOC_SUPPLY_CHAIN` is `true`. Default: off.

package/docs/signed-commands.md

@@ -0,0 +1,163 @@
+# Signed and allow-listed commands — operator notes
+
+The platform (vh-api-gateway, visionhammer-agents) signs every command it sends
+to a local agent with an Ed25519 key, and the agent runs shell commands only
+from an allowlist. Both checks have three modes, `off | warn | enforce`. The
+default is `enforce` (signature: since 1.1.0; exec policy: since 1.0.35), and an
+unrecognised value also means `enforce`. `warn` verifies and logs without
+rejecting; use it only as an explicit, temporary opt-out
+(`LOCAL_AGENT_SIGNATURE_MODE=warn`) for an agent whose platform side does not
+sign yet. Without a listen address the agent also binds `127.0.0.1` unless a
+token (`LOCAL_AGENT_TOKEN` / `AGENT_SHARED_SECRET`) or Cloud Run is present.
+
+## Protocol v1
+
+HTTP headers on every platform → agent request:
+
+| Header | Value |
+|---|---|
+| `X-VH-Key-Id` | id of the signing key, for example `vh-2026-09` |
+| `X-VH-Timestamp` | unix epoch **seconds** |
+| `X-VH-Nonce` | 16–128 chars `[A-Za-z0-9_-]`, unique per request |
+| `X-VH-Tenant-Id` / `X-VH-Workspace-Id` | the tenant and workspace the platform acts for (`""` when unknown) |
+| `X-VH-Signature` | base64 Ed25519 signature over the canonical string |
+
+Canonical string (UTF-8, `\n`-joined, no trailing newline):
+
+```
+VH-AGENT-SIG-V1
+<METHOD upper-case>
+<raw path + "?" + raw query, as sent>
+<hex sha256 of the exact body bytes (sha256("") when empty)>
+<tenantId>
+<workspaceId>
+<timestamp>
+<nonce>
+```
+
+Golden vector (all three implementations test against it): method `post`, path
+`/workspace/exec?x=1`, body `{}`, tenant `t`, workspace `w`, timestamp
+`1790000000`, nonce `abcdefghijklmnop` →
+`VH-AGENT-SIG-V1\nPOST\n/workspace/exec?x=1\n44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a\nt\nw\n1790000000\nabcdefghijklmnop`.
+
+WebSocket tunnel: the envelope gains `paramsRaw` (the exact JSON the platform
+signed) and `sig: {keyId, timestamp, nonce, tenantId, workspaceId, signature}`.
+Method is `WS`, path is the command name, body is `paramsRaw`. A verified
+envelope runs `JSON.parse(paramsRaw)`; the unsigned `params` copy is used only
+by older agents, or in `warn`/`off` mode when the envelope is not signed.
+
+The agent rejects (in `enforce`) with 401 when:
+
+* the request has no signature, or the key id is unknown;
+* the signature does not verify;
+* `|now − timestamp| > 60 s`;
+* the nonce was already used (in-memory LRU, TTL 120 s, 100k entries);
+* the tenant does not match the agent's identity (`LOCAL_AGENT_TENANT_ID` →
+  `TENANT_ID` → `~/.deepdebug/config.json`). If the signed workspace is
+  non-empty, it must match `LOCAL_AGENT_WORKSPACE_ID` / `WORKSPACE_ID` (set
+  `LOCAL_AGENT_REQUIRE_WORKSPACE=true` to require it on every call). A shared
+  operator agent with no identity accepts any signed tenant.
+
+`X-Agent-Token` (`LOCAL_AGENT_TOKEN`) is still checked first, as the second
+factor. `GET /health` and `/metrics` stay public.
+
+## Exec allowlist
+
+`/workspace/exec`, `/workspace/run`, `/mcp/execute-command` and
+`/setup/run-command` accept a command only when every segment (`&&`, `||`,
+`;`, `|`) belongs to one of these families: read-only git; package-manager
+install, test, build or lint for an ecosystem detected in the workspace (npm,
+yarn, pnpm, mvn/mvnw, gradle/gradlew, pip, poetry, uv, go, cargo, dotnet); test
+runners; linters; file read/write inside the workspace root; or `cd` inside
+the root. `$VAR`, `$(...)`, backticks, subshells, `&`, here-docs, process
+substitution and paths outside the root are refused.
+
+Hardening rules:
+
+* **Wrappers are validated recursively.** `env`, `time`, `nice`, `timeout`,
+  `c8`, `nyc`, `npx`, `npm/pnpm exec`, `poetry run` and `uv run` wrap another
+  command, and that command must pass the same policy. `xargs` is refused.
+  Interpreter eval (`node -e/-p`, `python -c`, `sh/bash -c`) is never
+  allowed. Test runners refuse inline JSON config.
+* **Paths are realpath-resolved.** Every non-flag token that is path-like or
+  exists on disk, every `--opt=value`, every redirect target and every
+  `cd`/`git -C` directory is resolved with symlinks followed and must stay
+  inside the root. An unquoted glob may use wildcards only in its last segment,
+  and none of the symlinks it can match may point outside.
+* **Protected files.** A redirect, `tee`, `cp`, `mv`, `rm`, `touch`, `chmod`
+  or `sort -o` is refused on these paths: `.git/**`, hook dirs (`.husky`,
+  `.githooks`), and build/test config that executes code. That includes
+  `package.json`, `.npmrc`, lockfiles, `Makefile`, `pom.xml`, `*.gradle*`,
+  `gradle/wrapper`, `setup.py`, `pyproject.toml`, `conftest.py`, and
+  `*.config.js` for jest, vitest, eslint and similar tools. Those files change
+  only through the signed apply-patch tool.
+* **No write-then-execute.** A command string that writes files may not run a
+  package-manager, test or lint tool in a later segment. The source of truth is
+`src/utils/exec-policy.js`; the reason is returned in the 403 body.
+
+Two exceptions:
+
+1. **Human approval (REQUIRE_HUMAN).** An `X-VH-Approval` header (or
+   `approvalToken` in the body) holding a PolicyGate token
+   `vhapr1.<keyId>.<b64url payload>.<b64url sig>`. It is signed with the same
+   platform key over `VH-HUMAN-APPROVAL-V1\n<keyId>\n<payload segment>`. The
+   token is bound to the SHA-256 of the exact command, the tenant and the
+   workspace. It lives at most 15 minutes and can be used once.
+2. **Platform-authored tools.** A body with `commandOrigin: "platform"` and a
+   known `tool` (`create_branch`, `git_commit`, `git_push`, `close_pr`,
+   `delete_branch`, `publish_scope`, `current_branch`). It is honoured only
+   when the request signature verified. The model's free-form `run_command`
+   never carries it.
+
+## Rollout
+
+1. **Generate the keypair** on a trusted workstation. Keep the private key
+   off disk after upload.
+   ```sh
+   openssl genpkey -algorithm ed25519 -out local-agent-signing-key.pem
+   openssl pkey -in local-agent-signing-key.pem -pubout -outform DER | base64   # SPKI, 60 chars
+   ```
+2. **Store the private key** in Secret Manager as `local-agent-signing-key`
+   (PKCS#8 PEM) in `visionhammer`, and grant `secretAccessor` to the gateway
+   and agent2 runtime service accounts.
+   ```sh
+   gcloud secrets create local-agent-signing-key --replication-policy=automatic --data-file=local-agent-signing-key.pem
+   ```
+3. **Mount it on the signers.** On gateway and software-engineer (agent2)
+   Cloud Run, set
+   `--set-secrets=LOCAL_AGENT_SIGNING_KEY=local-agent-signing-key:latest` and
+   `--update-env-vars=LOCAL_AGENT_SIGNING_KEY_ID=vh-2026-09`. Without the key
+   they log once and send unsigned requests, as before. Remember
+   `--vpc-egress=private-ranges-only` on `run services update`.
+4. **Give the agents the public key:**
+   * Image default: add `{"keyId":"vh-2026-09","publicKey":"<SPKI b64>"}` to
+     `src/config/trusted-signing-keys.json` and cut a new image.
+   * BYOC provisioning: set `LOCAL_AGENT_SIGNING_PUBLIC_KEYS=vh-2026-09=<SPKI b64>`
+     on the gateway. `CloudEngineerService` copies it, along with
+     `LOCAL_AGENT_SIGNATURE_MODE` and `LOCAL_AGENT_EXEC_POLICY_MODE`, into
+     every ACI/Cloud Run agent it provisions.
+   * Operator QA agent: set the same env on `deepdebug-local-agent-qa`.
+5. **Soak in `warn`.** Watch the logs for `[agent-sig] WARN` and
+   `[exec-policy] WARN`. The logs are rate-limited, one line per reason and
+   path per minute. Expect zero signature warnings from updated platform
+   callers. Every exec warning is a command that `enforce` would block.
+6. **Flip to enforce** per agent: `LOCAL_AGENT_SIGNATURE_MODE=enforce` once
+   the signature warnings are zero. Set the gateway env to `enforce` so new
+   BYOC agents start enforced. Roll back by setting `warn` again, with no
+   redeploy of the platform.
+
+   Since 1.0.35 (security review 2026-10-11) the **exec policy defaults to
+   `enforce`**: a command outside the allowlist is refused unless it carries a
+   PolicyGate approval token or is a signed platform tool command. Set
+   `LOCAL_AGENT_EXEC_POLICY_MODE=warn` explicitly on an agent that still needs
+   the soak. In the same release the HTTP perimeter stopped defaulting to
+   `compat`: `AGENT_SHARED_SECRET` is enforced as `X-Agent-Token`, and an agent
+   with no token outside Cloud Run only answers loopback callers (the reverse
+   WS tunnel). `LOCAL_AGENT_AUTH=compat` is the explicit, logged opt-out.
+
+### Key rotation
+
+Add the new public key next to the old one (`kid1=...,kid2=...` / two file
+entries) on every agent. Then switch `LOCAL_AGENT_SIGNING_KEY` and
+`LOCAL_AGENT_SIGNING_KEY_ID` on the signers to the new version. After a day,
+remove the old public key. Approval tokens use the same keys.

package/env.example

@@ -39,3 +39,33 @@ LOG_LEVEL=info
 
 # For on-premise DeepDebug server
 # DEEPDEBUG_API_URL=https://deepdebug.internal.company.com
+
+# ─── Security (audit 2026-09) ───
+# LOCAL_AGENT_TOKEN: when set, every route except GET /health and /metrics
+# requires the X-Agent-Token header. Set it only once every caller (gateway,
+# agents) sends the header. AGENT_SHARED_SECRET (injected by the gateway on
+# BYOC ACI agents) is enforced the same way when LOCAL_AGENT_TOKEN is not set.
+# With neither (and outside Cloud Run) the agent is loopback-only: it binds
+# 127.0.0.1 and refuses non-loopback callers. LOCAL_AGENT_BIND_HOST overrides.
+# LOCAL_AGENT_TOKEN=
+# Extra browser origins allowed by CORS (comma-separated, exact match).
+# LOCAL_AGENT_CORS_ORIGINS=
+# Re-enable /setup/run-command, /setup/install-tool, /setup/run-auth-command.
+# LOCAL_AGENT_ENABLE_SETUP_COMMANDS=false
+# LOCAL_AGENT_AUTH=loopback  -> accept loopback callers only (laptop + WS tunnel)
+# LOCAL_AGENT_AUTH=off       -> emergency opt-out (NOT recommended)
+
+# ─── Signed + allow-listed commands (docs/signed-commands.md) ───
+# Trusted platform public keys (Ed25519), keyId=base64 (raw 32-byte or SPKI DER).
+# Several entries = rotation window. The image default lives in
+# src/config/trusted-signing-keys.json.
+# LOCAL_AGENT_SIGNING_PUBLIC_KEYS=vh-2026-09=MCowBQYDK2VwAyEA...
+# off | warn | enforce (default) — verify X-VH-Signature on every command.
+# Set warn only as a loud, temporary opt-out for a platform that does not sign yet.
+# LOCAL_AGENT_SIGNATURE_MODE=enforce
+# off | warn | enforce (default) — shell allowlist on exec endpoints.
+# LOCAL_AGENT_EXEC_POLICY_MODE=enforce
+# Identity the signature must match (defaults: TENANT_ID / WORKSPACE_ID).
+# LOCAL_AGENT_TENANT_ID=
+# LOCAL_AGENT_WORKSPACE_ID=
+# LOCAL_AGENT_REQUIRE_WORKSPACE=false

package/helm/Chart.yaml

@@ -2,8 +2,8 @@ apiVersion: v2
 name: deepdebug-agent
 description: DeepDebug Local Agent for enterprise code debugging and analysis
 type: application
-version: 1.0.0
-appVersion: "1.0.0"
+version: 1.1.0
+appVersion: "1.1.0"
 keywords:
   - debugging
   - ai

package/helm/templates/deployment.yaml

@@ -38,14 +38,24 @@ spec:
               value: "production"
             - name: PORT
               value: "5055"
-            - name: DEEPDEBUG_API_URL
+            # Names aligned to what src/server.js actually reads (server.js frozen):
+            # GATEWAY_URL (server.js:73), TENANT_ID (:7505), WORKSPACE_ROOT (:637).
+            - name: GATEWAY_URL
               value: {{ .Values.config.apiUrl | quote }}
-            - name: DEEPDEBUG_TENANT_ID
+            - name: TENANT_ID
               valueFrom:
                 secretKeyRef:
                   name: {{ include "deepdebug-agent.fullname" . }}-secret
                   key: tenant-id
-            - name: DEEPDEBUG_WORKSPACE_PATH
+            # Without a token the agent is loopback-only (bind 127.0.0.1) and the
+            # kubelet probes would fail; with it, every route but /health and
+            # /metrics needs X-Agent-Token.
+            - name: LOCAL_AGENT_TOKEN
+              valueFrom:
+                secretKeyRef:
+                  name: {{ include "deepdebug-agent.fullname" . }}-secret
+                  key: agent-token
+            - name: WORKSPACE_ROOT
               value: {{ .Values.config.workspacePath | quote }}
             - name: LOG_LEVEL
               value: {{ .Values.config.logLevel | quote }}

package/helm/templates/networkpolicy.yaml

@@ -0,0 +1,22 @@
+{{- if .Values.networkPolicy.enabled }}
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata:
+  name: {{ include "deepdebug-agent.fullname" . }}
+  labels:
+    {{- include "deepdebug-agent.labels" . | nindent 4 }}
+spec:
+  podSelector:
+    matchLabels:
+      {{- include "deepdebug-agent.selectorLabels" . | nindent 6 }}
+  policyTypes:
+    - Ingress
+  {{- with .Values.networkPolicy.allowFrom }}
+  ingress:
+    - from:
+        {{- toYaml . | nindent 8 }}
+      ports:
+        - protocol: TCP
+          port: 5055
+  {{- end }}
+{{- end }}

package/helm/templates/secret.yaml

@@ -7,3 +7,4 @@ metadata:
 type: Opaque
 data:
   tenant-id: {{ .Values.config.tenantId | b64enc | quote }}
+  agent-token: {{ required "config.agentToken is required (LOCAL_AGENT_TOKEN: the agent refuses remote callers without it)" .Values.config.agentToken | b64enc | quote }}

package/helm/values.yaml

@@ -27,6 +27,9 @@ replicaCount: 1
 # ─────────────────────────────────────────
 config:
   tenantId: ""  # Required: Your tenant ID
+  # Required: shared secret for X-Agent-Token (LOCAL_AGENT_TOKEN). Pass it with
+  # --set config.agentToken=$(openssl rand -hex 32); never commit it.
+  agentToken: ""
   apiUrl: "https://api.deepdebug.ai"
   logLevel: "info"
   
@@ -117,20 +120,6 @@ readinessProbe:
   timeoutSeconds: 5
   failureThreshold: 3
 
-# ─────────────────────────────────────────
-# Network Policies (Enterprise)
-# ─────────────────────────────────────────
-networkPolicy:
-  enabled: true
-  # Allow egress only to DeepDebug API
-  egressRules:
-    - to:
-        - ipBlock:
-            cidr: 0.0.0.0/0
-      ports:
-        - protocol: TCP
-          port: 443
-
 # ─────────────────────────────────────────
 # Pod Disruption Budget
 # ─────────────────────────────────────────
@@ -160,3 +149,13 @@ podAnnotations:
   prometheus.io/scrape: "true"
   prometheus.io/port: "5055"
   prometheus.io/path: "/metrics"
+
+# ─────────────────────────────────────────
+# Network Policy (security review 2026-10-11, C1)
+# ─────────────────────────────────────────
+# The agent reaches the platform over an OUTBOUND tunnel, so it needs no
+# inbound traffic except kubelet probes. Default: deny all ingress except the
+# sources listed in allowFrom (NetworkPolicy peers, e.g. a podSelector).
+networkPolicy:
+  enabled: true
+  allowFrom: []

package/mcp-server.js

@@ -6,6 +6,7 @@ import {
     ListToolsRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
 import path from "path";
+import { createAuthMiddleware } from "./src/utils/agent-auth.js";
 import { spawn } from "child_process";
 import { exists, listRecursive, readFile, writeFile, stat } from "./fs-utils.js";
 import { detectProject, readText } from "./detectors.js";
@@ -454,6 +455,8 @@ function errorResponse(message) {
 export async function startMCPHttpServer(wsManager, port = 5056) {
     const express = (await import("express")).default;
     const app = express();
+    // SECURITY: execute_command runs `sh -c`; same auth perimeter as the main API.
+    app.use(createAuthMiddleware());
 
     const server = createMCPServer(wsManager);
 
@@ -522,7 +525,7 @@ export async function startMCPHttpServer(wsManager, port = 5056) {
         }
     });
 
-    app.listen(port, () => {
+    app.listen(port, process.env.MCP_BIND_HOST || "127.0.0.1", () => {
         console.log(`🧠 DeepDebug MCP Server listening on http://localhost:${port}`);
         console.log(`   SSE: http://localhost:${port}/sse`);
         console.log(`   REST: http://localhost:${port}/tool/{toolName}`);