Epic: Core refactor — reference strings, batch grants, and injection overhaul

[helixclaw]

Summary

Refactor core features based on design feedback to improve developer ergonomics and security:

1. Human-readable reference strings — Add a ref field to secrets (e.g., perplexity-api-key) that serves as an alternative lookup key alongside UUIDs.
2. Batch grants — Allow multiple secrets to be requested in a single approval, producing a grant that unlocks all of them.
3. Injection overhaul — Scan env vars for 2k://{ref} or 2k://{uuid} placeholders and replace with secret values, support multiple --grant flags, and redact secret values from subprocess stdout/stderr.

Design Decisions

• The existing name field on SecretEntry becomes ref — a unique, URL-safe slug used for both display and lookup.
• Batch grants introduce secretUuids: string[] on AccessRequest and AccessGrant, replacing the singular secretUuid.
• Placeholder injection (2k://) is a new injection mode complementing the existing --env approach.
• Redaction wraps subprocess stdout/stderr streams, replacing any occurrence of a secret value with [REDACTED].

Scope

All changes are in the core library (src/core/), CLI (src/cli/), types (src/core/types.ts), and tests (src/__tests__/). No server API changes in this epic.

[helixclaw]

Architectural Decision Record

Context

The current design has three ergonomic and security gaps:

1. Secrets are only addressable by UUID — unfriendly for humans and configuration files.
2. Each request/grant covers exactly one secret — tedious for multi-secret workflows.
3. Injection is explicit-only (--env VAR_NAME) with no output redaction — risky if a subprocess logs secrets.

Decisions

1. Reference strings replace name
The existing name field on SecretEntry becomes ref — a URL-safe slug ([a-z0-9-]+). This is not just a display name; it's a first-class lookup key. SecretStore.resolve(refOrUuid) is the universal entry point that accepts either form. Rationale: one concept instead of two, and refs are directly usable in 2k:// URIs.

2. Batch grants via array-typed secretUuids
Rather than introducing a "grant group" wrapper, we extend the existing AccessRequest and AccessGrant to hold secretUuids: string[]. The singular case is just an array of length 1. Rationale: minimal model change, no new entity, backward-compatible semantics.

3. Placeholder scanning (2k://) as the primary injection mode
Users set env vars to 2k://perplexity-api-key in their shell config or .env files. The injector scans process.env, resolves each placeholder against the grant's secret pool, and replaces in-place before spawning. Explicit --env remains as an override. Rationale: declarative configuration is simpler than imperative flags for multi-secret cases.

4. Stream-level redaction via Transform
A RedactTransform stream processes stdout/stderr chunks, replacing any secret value with [REDACTED]. It buffers the tail of each chunk to handle secrets split across boundaries. Rationale: stream-level is more memory-efficient than post-hoc string replacement on captured output, and handles long-running processes.

Trade-offs

• Ref uniqueness enforcement adds a constraint users must manage, but the alternative (non-unique display names) would make 2k:// resolution ambiguous.
• Array-based secretUuids means even single-secret requests carry an array, slightly more verbose in code, but avoids a migration path or dual-model complexity.
• Chunk-boundary buffering in redaction adds latency (up to max-secret-length bytes), acceptable for the security guarantee.

Recommended execution order

1. Add ref field to SecretEntry and support ref-based lookups #40 — ref field (foundational)
2. Extend grants and requests to support multiple secrets (batch grants) #41 — batch grants (depends on ref resolution)
3. Add 2k:// placeholder scanning and env var injection #42 — placeholder injection (depends on both)
4. Add stdout/stderr secret redaction to injector #43 — redaction (depends on injection)

[helixclaw]

Child Issues Created

Issue	Title	Dependencies
#40	Add ref field to SecretEntry and support ref-based lookups	None
#41	Extend grants and requests to support multiple secrets (batch grants)	#40
#42	Add 2k:// placeholder scanning and env var injection	#40, #41
#43	Add stdout/stderr secret redaction to injector	#42

Dependency Graph

graph TD
    40["Add ref field to SecretEntry"]
    41["Batch grants for requests/grants"]
    42["2k:// placeholder scanning"]
    43["stdout/stderr redaction"]
    40 --> 41
    40 --> 42
    41 --> 42
    42 --> 43
    click 40 "https://github.com/helixclaw/2keychains/issues/40"
    click 41 "https://github.com/helixclaw/2keychains/issues/41"
    click 42 "https://github.com/helixclaw/2keychains/issues/42"
    click 43 "https://github.com/helixclaw/2keychains/issues/43"

Loading