Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 0 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <issue>` | Start SDLC pipeline with token-gated approvals for the given issue number |

### egg-deploy CLI

Expand Down Expand Up @@ -268,7 +267,6 @@ For monitoring all active SDLC pipelines in real-time:
| `--exec <cmd>` | Execute command in new ephemeral container |
| `--timeout <min>` | Timeout for --exec commands (default: 30) |
| `--auth <method>` | Anthropic auth method for --exec: `oauth-token` (default) or `api-key` |
| `--sdlc <issue>` | 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 |
Expand Down
25 changes: 0 additions & 25 deletions docs/adr/implemented/ADR-SDLC-Pipeline.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <issue>`.

**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 <phase>` 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
Expand Down
3 changes: 0 additions & 3 deletions docs/architecture/orchestrator.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
37 changes: 0 additions & 37 deletions docs/guides/sdlc-pipeline.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <phase>` 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):
Expand All @@ -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
Expand Down