Epic: Client-server architecture for 2keychains

[helixclaw]

Summary

Introduce a client-server model for 2keychains. A long-running server daemon manages secrets, handles Discord approval, tracks grants with TTL, and exposes a local HTTP API. The CLI becomes a thin client that communicates with the server. A configuration file (~/.2kc/config.json) determines the operating mode: standalone (current local-only behavior) or client (connects to a remote server).

Motivation

The current design assumes all operations happen in-process within the CLI. A client-server split enables:

• Persistent state: The server daemon can maintain in-memory grant tracking, Discord bot connections, and secret store caches across CLI invocations
• Multi-agent support: Multiple AI agents (or CLI sessions) can share a single approval server
• Remote operation: The server can run on a different machine or in a container
• Backwards compatibility: Standalone mode preserves the current local-only behavior for simple setups

Architecture

                                        ┌──────────────────┐
┌─────────────┐       HTTP/JSON         │  2kc server      │
│  2kc CLI    │ ◄────────────────────►  │  (daemon)        │
│  (client)   │   Bearer token auth     │                  │
└─────────────┘                         │  SecretStore     │
                                        │  GrantManager    │
┌─────────────┐                         │  Workflow        │
│  2kc CLI    │  standalone mode        │  Discord         │
│ (standalone)│  (direct, no server)    └──────────────────┘
└─────────────┘

Key Design Decisions

• Transport: HTTP/JSON via Fastify (lightweight, TypeScript-native, good DX)
• Auth: Bearer token (shared secret in config) -- sufficient for local/trusted network
• Daemon: PID file + child_process.fork for backgrounding
• Mode abstraction: Service interface pattern -- commands call an interface that has both LocalService (standalone) and RemoteService (client) implementations
• Config: ~/.2kc/config.json with defaults that preserve standalone behavior

Relationship to Other Issues

• Depends on: Project bootstrap & CLI skeleton #2 (complete)
• Logically related to: Secret store with UUID mapping layer #3-Ephemeral secret injection into process environment #8 (MVP features) -- the service interface defined here becomes the contract that those features implement. Those features can be built independently and plugged into both standalone and server modes.

Child Issues

See child issues below for the implementation breakdown.

[helixclaw]

Architectural Decision Record (ADR)

ADR-1: HTTP/JSON over Fastify for server API

Decision: Use Fastify as the HTTP framework for the server API.

Alternatives considered:

• node:http raw — too low-level, would need to reimplement routing, body parsing, error handling
• Express — heavier, less TypeScript-native, slower
• Unix domain sockets — better for local-only, but doesn't support remote operation
• gRPC — overkill for this use case, adds protobuf complexity

Rationale: Fastify has excellent TypeScript support, built-in schema validation, very low overhead, and a clean plugin architecture. It also includes Pino logging out of the box.

---

ADR-2: Bearer token (shared secret) for auth

Decision: Authenticate client-server communication using a shared bearer token.

Alternatives considered:

• mTLS — strong but complex to set up, overkill for local/trusted-network use
• No auth (localhost only) — risky if the port is accidentally exposed
• OAuth — unnecessary complexity for a single-user tool

Rationale: A shared secret is the simplest mechanism that provides meaningful protection. Combined with binding to 127.0.0.1 by default, this is sufficient for v0.5. Can be upgraded to mTLS later if needed.

---

ADR-3: Service interface pattern for mode abstraction

Decision: Define a Service interface that both LocalService and RemoteService implement. CLI commands program against the interface, not concrete implementations.

Alternatives considered:

• Separate CLI codepaths for standalone vs client — lots of duplication
• Proxy pattern (intercept all calls) — less explicit, harder to debug

Rationale: The interface pattern is explicit, testable, and makes it trivial to add new modes in the future. It also means CLI commands don't need any conditional logic — they just call the service.

---

ADR-4: PID file for daemon management

Decision: Use a PID file (~/.2kc/server.pid) with child_process.fork for daemon management.

Alternatives considered:

• systemd/launchd service — platform-specific, harder to set up
• PM2 — external dependency for a simple need
• Named pipes/sockets for IPC — more complex, PID file is sufficient

Rationale: PID file is the standard Unix pattern, requires no external dependencies, and works on all platforms. The --foreground flag provides an escape hatch for debugging.

---

Recommended execution order

1. Add configuration system with mode selection #15 — Config system (foundation, no deps)
2. Define service interface for mode abstraction #16 — Service interface (depends on config types)
3. Implement Fastify HTTP server with health endpoint #17 — HTTP server (depends on config, can parallel with Define service interface for mode abstraction #16)
4. Add bearer token auth middleware to server #18 — Auth middleware (depends on server)
5. Add server daemon lifecycle commands #19 — Daemon lifecycle (depends on server + config)
6. Implement client HTTP transport (RemoteService) #20 — Client transport (depends on service interface + server + auth)

[helixclaw]

Child Issues Created

Issue	Title	Dependencies
#15	Add configuration system with mode selection	None
#16	Define service interface for mode abstraction	#15
#17	Implement Fastify HTTP server with health endpoint	#15
#18	Add bearer token auth middleware to server	#17
#19	Add server daemon lifecycle commands	#15, #17
#20	Implement client HTTP transport (RemoteService)	#16, #17, #18

Dependency Graph

graph TD
    15["#15 Config system"]
    16["#16 Service interface"]
    17["#17 HTTP server"]
    18["#18 Auth middleware"]
    19["#19 Daemon lifecycle"]
    20["#20 Client transport"]
    15 --> 16
    15 --> 17
    15 --> 19
    17 --> 18
    17 --> 19
    16 --> 20
    17 --> 20
    18 --> 20
    click 15 "https://github.com/helixclaw/2keychains/issues/15"
    click 16 "https://github.com/helixclaw/2keychains/issues/16"
    click 17 "https://github.com/helixclaw/2keychains/issues/17"
    click 18 "https://github.com/helixclaw/2keychains/issues/18"
    click 19 "https://github.com/helixclaw/2keychains/issues/19"
    click 20 "https://github.com/helixclaw/2keychains/issues/20"

Loading