diff --git a/README.md b/README.md index 1579d59001..a286fa9519 100644 --- a/README.md +++ b/README.md @@ -228,7 +228,6 @@ Additional inputs include `prompt-file` (for large prompts), `bot-app-id`/`bot-a | `egg --compose` | Start gateway via Docker Compose | | `egg --compose --down` | Stop the Docker Compose stack (gateway + orchestrator) | | `egg --compose --build` | Rebuild compose images before starting | -| `egg --sdlc ` | Start SDLC pipeline with token-gated approvals for the given issue number | ### egg-deploy CLI @@ -268,7 +267,6 @@ For monitoring all active SDLC pipelines in real-time: | `--exec ` | Execute command in new ephemeral container | | `--timeout ` | Timeout for --exec commands (default: 30) | | `--auth ` | Anthropic auth method for --exec: `oauth-token` (default) or `api-key` | -| `--sdlc ` | Start SDLC pipeline with token-gated approvals for the given issue number | | `--rebuild` | Force rebuild Docker image | | `--time` | Show startup timing breakdown for debugging | | `-v, --verbose` | Show detailed output instead of progress bar | diff --git a/docs/adr/implemented/ADR-SDLC-Pipeline.md b/docs/adr/implemented/ADR-SDLC-Pipeline.md index 31357b7786..4afa958d27 100644 --- a/docs/adr/implemented/ADR-SDLC-Pipeline.md +++ b/docs/adr/implemented/ADR-SDLC-Pipeline.md @@ -190,31 +190,6 @@ In addition to formal HITL decisions, a simpler phase approval mechanism exists - Detected by the `handle-approval` job in `sdlc-hitl.yml` - See [Phase Completion Template](../../templates/phase-completion.md) for the comment format -### Token-Gated Approvals - -For local interactive sessions, token-gated approvals provide an additional security layer to prevent agents from self-approving phase transitions. This mechanism is available when starting the pipeline with `egg --sdlc `. - -**Architecture:** - -1. **Token Generation**: On startup, the entrypoint generates two 3-word human-memorizable tokens (e.g., `APPLE-HORSE-RIVER`) via the orchestrator's `/api/v1/sdlc-tokens/generate` endpoint -2. **Display to Human**: Tokens are displayed in the terminal before the agent launches -3. **Hook Installation**: A UserPromptSubmit hook (`sdlc-approve.sh`) is installed as root-owned (0555) to intercept `!approve ` commands -4. **Token Entry**: When the agent types `!approve refine`, the hook prompts the human via `/dev/tty` for the approval token -5. **Server-Side Validation**: The token is sent to `/api/v1/sdlc-tokens/approve` with SHA-256 hashing and timing-safe comparison -6. **Auto-Resolution**: On successful validation, pending HITL decisions for that phase are auto-resolved - -**Security Properties:** - -- **Agent Isolation**: Tokens are never visible to the agent (displayed before launch, entered via `/dev/tty`) -- **Tamper Resistance**: Hook script is root-owned; agent runs as `egg` user and cannot modify it -- **Watchdog Protection**: Background thread monitors `settings.json` for hook removal and re-adds if necessary -- **Privileged Endpoint Auth**: `/generate` and `/reset` endpoints require launcher secret authentication, preventing agents from calling them directly -- **Timing-Safe Validation**: SHA-256 hashing with `secrets.compare_digest` prevents timing side-channel attacks - -**Failure Recovery:** - -If the orchestrator restarts while a pipeline is token-gated, in-memory tokens are lost but the persistent `Pipeline.sdlc_token_gated` flag remains set in storage. The `/api/v1/sdlc-tokens/reset` endpoint (requires launcher secret auth) clears both the in-memory tokens and the persistent flag to allow the pipeline to proceed. - --- ## Gateway Integration diff --git a/docs/architecture/orchestrator.md b/docs/architecture/orchestrator.md index ca3b4c7dc2..efa69ed1f7 100644 --- a/docs/architecture/orchestrator.md +++ b/docs/architecture/orchestrator.md @@ -209,9 +209,6 @@ Fixed IPs: - `GET /pipelines/stream` - Unified SSE stream for all active pipelines (supports `?ascii=true`, `?active_only=false`, `?full_dag=true`) - `POST /pipelines/{id}/signal` - Sandbox signals (complete, progress, error) - `GET /pipelines/{id}/decisions` - HITL decision queue -- `POST /sdlc-tokens/generate` - Generate approval tokens for SDLC pipeline (requires launcher secret auth) -- `POST /sdlc-tokens/approve` - Validate token and approve SDLC phase -- `POST /sdlc-tokens/reset` - Clear token-gated state for recovery (requires launcher secret auth) ### Signal Flow diff --git a/docs/guides/sdlc-pipeline.md b/docs/guides/sdlc-pipeline.md index 2ed45bb812..d839d559a2 100644 --- a/docs/guides/sdlc-pipeline.md +++ b/docs/guides/sdlc-pipeline.md @@ -987,38 +987,6 @@ To set up SDLC labels in a repository: This script is idempotent and safe to run multiple times. -### Token-Gated Approvals - -The SDLC pipeline supports token-gated approvals to prevent agents from self-approving phase transitions. When enabled, phase approvals require a human-provided secret token that is never visible to the agent. - -**Starting a token-gated pipeline**: -```bash -egg --sdlc 123 -``` - -On startup, the system generates two 3-word tokens (e.g., `APPLE-HORSE-RIVER`) and displays them to the human before launching the agent. These tokens are required to approve the refine and plan phases. - -**How it works**: - -1. **Token generation**: The entrypoint calls the orchestrator's `/api/v1/sdlc-tokens/generate` endpoint (requires launcher secret authentication) -2. **Token display**: Tokens are displayed in the terminal before the agent starts -3. **Hook installation**: A UserPromptSubmit hook (`sdlc-approve.sh`) is installed as root-owned (0555) to intercept `!approve ` commands -4. **Token entry**: When the agent types `!approve refine`, the hook prompts the human (via `/dev/tty`) for the token -5. **Validation**: The token is sent to the orchestrator's `/api/v1/sdlc-tokens/approve` endpoint with SHA-256 hashing and timing-safe comparison -6. **Auto-resolution**: On successful validation, pending HITL decisions for that phase are auto-resolved - -**Security properties**: - -- Tokens are never visible to the agent (displayed before launch, entered via `/dev/tty`) -- Hook script is root-owned (agent runs as `egg` user, cannot modify) -- Watchdog thread monitors for hook removal and re-adds if necessary -- Launcher secret authentication prevents agents from calling privileged endpoints -- Server-side validation with timing-safe comparison prevents timing side-channel attacks - -**Failure recovery**: - -If the orchestrator restarts while a pipeline is token-gated, in-memory tokens are lost but the persistent `sdlc_token_gated` flag remains set. Use the `/api/v1/sdlc-tokens/reset` endpoint (requires launcher secret auth) to clear the token gate and allow the pipeline to proceed. - ### Triggering the Pipeline **Via label** (recommended): @@ -1031,11 +999,6 @@ gh issue edit 123 --add-label "sdlc:refine" gh workflow run sdlc-pipeline.yml -f issue_number=123 -f starting_phase=refine ``` -**With token-gated approvals** (local mode only): -```bash -egg --sdlc 123 -``` - ### Contract CLI Commands ```bash