From 9a4299d1ae6089631a88ec2437b0ac04e61e514c Mon Sep 17 00:00:00 2001 From: thePR0M3TH3AN <53631862+PR0M3TH3AN@users.noreply.github.com> Date: Thu, 13 Aug 2026 10:03:19 -0400 Subject: [PATCH] docs: add agent-blind secret lifecycle (provision/reference/use) to TS port plan Agents provision entries and get back references, never values; use goes through one-time leases to sinks (clipboard/exec/stdin/extension fill); reveal is a separate high-risk grant. Reference-first JSON output becomes a design constraint on the Milestone 5 CLI. Co-Authored-By: Claude Fable 5 --- docs/typescript_web_extension_port_plan.md | 69 +++++++++++++++++++++- 1 file changed, 68 insertions(+), 1 deletion(-) diff --git a/docs/typescript_web_extension_port_plan.md b/docs/typescript_web_extension_port_plan.md index 1ffea801..e44760eb 100644 --- a/docs/typescript_web_extension_port_plan.md +++ b/docs/typescript_web_extension_port_plan.md @@ -390,6 +390,10 @@ Reference features: - posture checks - HMAC-chained audit records +In addition to porting these, the TypeScript version adds the agent-blind +provision/reference/use lifecycle defined in section 9.3, which composes the +token, lease, and approval primitives into a default-safe agent surface. + ## 9. Security Model for Browser-Based SeedPass Browser support improves usability, but it changes the threat model. The browser @@ -457,6 +461,65 @@ Required rules: - extension permissions must be documented in release notes and reviewed before store submission +### 9.3 Agent-Blind Secret Lifecycle (Provision / Reference / Use) + +AI agents and automation are first-class SeedPass clients, but an agent's +transcript, context window, and logs are hostile territory for plaintext +secrets. The TypeScript port must support the full credential lifecycle without +the secret value ever entering the agent's input or output by default. + +Lifecycle model: + +1. Provision: a permitted agent may create entries of any supported kind + (password, totp, ssh, nostr, key_value, managed_account, ...). The creation + response contains only the entry id/index, label, kind, and non-secret + metadata — never the derived or imported secret value. +2. Reference: every entry is programmatically addressable by stable entry id, + derivation index, label, or search query. References are safe to store in + agent context, scripts, job templates, and chat transcripts. +3. Use: the agent requests a one-time lease for an entry and directs it to a + sink. SeedPass delivers the plaintext directly from vault to sink; the agent + orchestrates but never carries the value. +4. Backup: agent-created artifacts inherit the normal guarantees automatically. + Deterministic artifacts re-derive from the parent seed plus synced entry + metadata; non-deterministic artifacts live in the encrypted vault and sync + over Nostr like any user-created entry. Nothing an agent provisions can + exist only in a session transcript. + +Required CLI/API semantics: + +- `--format json` agent surfaces return references and metadata, never secret + values. Plaintext egress to stdout is a distinct operation behind an explicit + flag, a separate permission grant, and (where configured) an approval gate. +- Sink delivery commands, for example: + - `seedpass use --clipboard` (with timed clear) + - `seedpass use --exec -- ` (injected as env var or fd into the + child process, never interpolated into a shell string) + - `seedpass use --stdin-to ` + - `seedpass use --fill` (hand off to the browser extension for the + active, origin-verified tab) +- Leases are single-use or short-TTL, so a leaked handle is worthless after + the fact. +- Every provision, lease, sink delivery, and reveal is recorded in the + HMAC-chained audit log with the requesting identity/token, so the user can + reconstruct exactly what an agent did with which credential. + +Permission model (builds on the token/lease/approval features in section 8.6): + +- per-agent identity with scoped tokens +- separate scopes for create, use (sink delivery), and reveal (plaintext + egress), grantable per entry kind, per secret class, or per entry +- high-risk classes (parent seed, managed seeds, PGP/SSH private keys, full + export) require approval gates or a fresh user factor regardless of token + scope +- default deny: an unscoped agent can search metadata at most, and even that + can be restricted + +This section is a design constraint on Milestone 5 (CLI) and Milestone 8 +(agent features): the CLI command and JSON output design must be +reference-first from the start, so agent-blind operation is the default shape +of the product rather than a retrofit. + ## 10. Dependency Strategy Prefer small, audited, stable packages. Avoid convenience dependencies that @@ -655,7 +718,9 @@ Deliverables: - entry add/get/search/list/modify/archive/restore/delete - vault lock/unlock/export/import - Nostr sync commands -- JSON output mode +- JSON output mode (reference-first: returns entry ids/metadata, not secret + values, per section 9.3) +- sink delivery commands (`seedpass use --clipboard|--exec|--stdin-to`) - interactive terminal mode MVP Exit criteria: @@ -719,6 +784,8 @@ Deliverables: - identity model - approval gates - leases +- agent-blind provision/reference/use lifecycle (section 9.3): scoped create, + sink-only use, reveal as a separate high-risk grant - policy lint/review/apply - audit chain - high-risk secret partition model