Epic: 2keychains v0.5 MVP — Local Secret Broker

[helixclaw]

Overview

Implement the v0.5 MVP of 2keychains as defined in ROADMAP.md. This is a local-only secret broker that replaces direct secret access with a controlled intermediary. It introduces manual approval, contextual justification, UUID abstraction, and ephemeral injection.

Key Design Decisions

• Local-only: Runs on the same machine as the AI agent
• Plain JSON file for secret storage (NOT macOS keychain — that's a later phase)
• Discord webhook/bot for the approval flow
• Clean channel interface so future notification integrations (Slack, email, SMS) can be swapped in
• UUID abstraction: AI only interacts with UUID references, never human-readable names or raw values
• Contextual justification required for every access request (reason, task reference, duration)
• Time-bound ephemeral injection: Secrets injected into process environments for a short window, then purged
• Stateless flow: Request → Approve → Fetch → Inject → Purge

Technology

• TypeScript / Node.js
• commander for CLI
• discord.js for bot, Discord webhook API for notifications
• uuid for UUID generation
• Plain JSON file for secret persistence

Exit Criteria (from ROADMAP)

• All secrets routed through broker
• Approval workflow stable
• Logging consistent and reliable

Security Limitations (acknowledged for v0.5)

• Runs on same host as AI
• Can be bypassed by attacker with system-level access
• Not resistant to privilege escalation

Out of Scope (Post-MVP)

• macOS Keychain integration
• 1Password sync
• Honeytoken / decoy secrets
• Rate limiting
• Anomaly detection

[helixclaw]

Architectural Decision Record (ADR)

Decision: Technology Stack

TypeScript / Node.js for the CLI and all core logic.

• Native JSON handling (secret store is a JSON file)
• commander for CLI — mature, well-documented
• discord.js for bot interactions, native fetch for webhooks
• uuid (v4) for UUID generation
• vitest for testing, eslint + prettier for code quality

Rationale: TypeScript provides strong typing for the interface abstractions (channel interface, request model, grant model) while being fast to iterate on. The Discord ecosystem is strongest in JS/TS.

Decision: Plain JSON File for Secret Storage

Store secrets in ~/.2kc/secrets.json with 0600 permissions.

Rationale: ROADMAP explicitly defers macOS Keychain integration. A JSON file is the simplest possible backend that lets us focus on the broker logic. The SecretStore interface will make swapping backends trivial later.

Decision: Channel Abstraction Pattern

A NotificationChannel interface with three methods: sendApprovalRequest, waitForResponse, sendNotification.

Rationale: ROADMAP requires a "clean channel interface" for future Slack/email/SMS. This interface is the minimal contract. Only DiscordChannel is implemented for v0.5.

Decision: In-Memory Grant Storage

Access grants live only in process memory, not on disk.

Rationale: Grants are ephemeral by design (stateless flow). Since the CLI is a one-shot process (not a daemon), grants naturally expire when the process exits. This simplifies implementation and avoids stale grant files.

Decision: Tag-Based Approval Routing

Secrets are tagged (e.g., ["production", "api"]), and config maps tags to approval requirements.

Rationale: This is more flexible than per-secret config and matches how teams think about security tiers. A defaultRequireApproval fallback handles untagged secrets.

Key Trade-offs

Choice	Benefit	Cost
JSON file over Keychain	Simpler, cross-platform for testing	Not encrypted at rest
One-shot CLI over daemon	Stateless, simpler	No background grant expiration; grants die with process
discord.js over raw API	Rich bot features	Heavier dependency
In-memory grants	No cleanup needed	Can't survive process restart

Recommended Execution Order

1. Project bootstrap & CLI skeleton #2 (bootstrap) — unblocks everything
2. Secret store with UUID mapping layer #3, Notification channel interface + Discord implementation #4, Access request model with contextual justification #5 in parallel (store, channel, request model) — independent tracks
3. Approval workflow engine with tag-based config #6 (workflow) — converges the three tracks
4. Time-bound access grants & expiration enforcement #7 (grants) → Ephemeral secret injection into process environment #8 (injection) → End-to-end CLI integration & audit logging #9 (integration) — sequential critical path

[helixclaw]

Child Issues Created

Issue	Title	Dependencies
#2	Project bootstrap & CLI skeleton	None
#3	Secret store with UUID mapping layer	#2
#4	Notification channel interface + Discord implementation	#2
#5	Access request model with contextual justification	#2
#6	Approval workflow engine with tag-based config	#3, #4, #5
#7	Time-bound access grants & expiration enforcement	#6
#8	Ephemeral secret injection into process environment	#7
#9	End-to-end CLI integration & audit logging	#8

Dependency Graph

graph TD
    2["#2 Project bootstrap & CLI skeleton"]
    3["#3 Secret store with UUID mapping"]
    4["#4 Notification channel + Discord"]
    5["#5 Access request model"]
    6["#6 Approval workflow engine"]
    7["#7 Time-bound access grants"]
    8["#8 Ephemeral secret injection"]
    9["#9 E2E CLI integration & audit logging"]
    2 --> 3
    2 --> 4
    2 --> 5
    3 --> 6
    4 --> 6
    5 --> 6
    6 --> 7
    7 --> 8
    8 --> 9
    click 2 "https://github.com/helixclaw/2keychains/issues/2"
    click 3 "https://github.com/helixclaw/2keychains/issues/3"
    click 4 "https://github.com/helixclaw/2keychains/issues/4"
    click 5 "https://github.com/helixclaw/2keychains/issues/5"
    click 6 "https://github.com/helixclaw/2keychains/issues/6"
    click 7 "https://github.com/helixclaw/2keychains/issues/7"
    click 8 "https://github.com/helixclaw/2keychains/issues/8"
    click 9 "https://github.com/helixclaw/2keychains/issues/9"

Loading

Execution Strategy

Phase 1 (serial): #2 — Project bootstrap
Phase 2 (parallel): #3, #4, #5 — Store, Channel, Request model (independent tracks)
Phase 3 (convergence): #6 — Workflow engine brings the three tracks together
Phase 4 (serial): #7 → #8 → #9 — Grants → Injection → Integration