SeedPass/docs/agent_autonomy_security_plan.md

# SeedPass Agent Autonomy Security Plan

## Goal
Implement a staged security architecture that enables autonomous agents to use SeedPass safely in production environments without relying on plaintext secrets or overly broad access.

## Program Structure
- Phase A: Foundation
  Add policy engine hardening, brokered auth, scoped tokens, redaction, and auditable access.
- Phase B: Guardrails
  Add approval gates, high-risk secret isolation, and deterministic export controls.
- Phase C: Operations
  Add posture tooling, rotation workflows, recovery hardening, and conflict-safe sync semantics.

## Implementation Snapshot (2026-03-01)

- Implemented: 1, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15
- In Progress: 2 (continuing enforcement-depth hardening and broad validation across all operation paths)
- Tracking source of truth: `docs/security_readiness_checklist.md` (Agent Autonomy Control Track section)

## 1. Native Non-Interactive Auth Brokers
- Problem:
  Agent auth depends heavily on env vars and manual password flow.
- Implementation:
  Add an auth broker abstraction with providers:
  `env` (backward-compatible), `keyring` (OS-native), `command` (for HSM/YubiKey helpers).
  Add broker options to `seedpass agent init/get` and then `vault unlock`, `api start`.
  Add broker plugins for `pkcs11` and `yubikey` as optional modules later.
- Data/Config:
  `--auth-broker`, `--broker-service`, `--broker-account`, `--broker-command`.
- Security:
  Never persist broker-returned secrets; memory-only use.
- Tests:
  broker resolution, failure handling, per-profile account defaults.
- Acceptance:
  agent workflows can authenticate without password env vars by using keyring/broker commands.

## 2. Fine-Grained RBAC Per Profile
- Problem:
  Coarse kind-level permissions are insufficient.
- Implementation:
  Extend policy rules to enforce allow/deny by:
  entry path, label regex, kind, field, operation (`read/create/update/export`).
  Enforce in CLI agent commands, API endpoints, and service layer wrappers.
- Data/Config:
  `agent_policy.json` schema v2 with explicit operation matrix and precedence.
- Tests:
  policy precedence, deny overrides, path+field restrictions.
- Acceptance:
  deterministic policy decisions for every operation and entry field.

## 3. Short-Lived Scoped Tokens
- Problem:
  Long-lived static tokens increase blast radius.
- Implementation:
  Expand token store to support:
  scope lists, TTL, usage count, profile binding, optional IP/host binding, revocation reason.
  Add token introspection endpoint/command.
- Data/Config:
  `agent_tokens.json` versioned schema.
- Tests:
  expiry, revoke, scope denial, kind denial, reuse after exhaustion.
- Acceptance:
  all agent access can use revocable TTL-bound scoped credentials.

## 4. One-Time Secret Leases
- Problem:
  Secrets may be exposed repeatedly after retrieval.
- Implementation:
  Add lease records tied to token and resource:
  fetch-once or N-use, automatic invalidation, lease audit linkage.
  Optional server-side one-time retrieval IDs for API consumers.
- Tests:
  first-use success, second-use denial, race behavior under concurrency.
- Acceptance:
  one-time leases are enforced reliably under parallel access.

## 5. Policy-Enforced Redaction
- Problem:
  Secrets can leak through stdout/logging by default.
- Implementation:
  Make safe output mode default in agent/API.
  Redact by field policy with optional reveal override requiring permission.
  Add structured redaction markers.
- Tests:
  output snapshot tests for masked/unmasked modes.
- Acceptance:
  secrets are masked by default in automation logs.

## 6. Auditable Event Log
- Problem:
  Access traceability is weak without tamper evidence.
- Implementation:
  Keep append-only signed chain log.
  Add verifier command:
  `seedpass agent audit-verify`.
  Add export to JSONL with integrity proofs.
- Tests:
  chain continuity, tamper detection, clock skew handling.
- Acceptance:
  any log tampering is detectable; access events are attributable.

## 7. Approval Gates
- Problem:
  High-risk actions need step-up control.
- Implementation:
  Define gate policies for `export`, `reveal_parent_seed`, `private_key_retrieval`.
  Add approval plugins:
  local second factor, signed approval token, webhook approver.
  Add TTL and single-use approval grants.
- Tests:
  denied without approval, success with valid grant, grant expiry.
- Acceptance:
  risky operations cannot execute without valid step-up approval.

## 8. Secret-Class Isolation
- Problem:
  High-risk materials should not share unlock context with standard secrets.
- Implementation:
  Partition vault by class:
  standard vs high-risk (`seed`, `ssh`, `pgp`).
  Separate derived encryption keys and unlock factors.
  Per-class lock/unlock state.
- Data/Config:
  class partition metadata in encrypted config.
- Tests:
  class lock boundary, cross-class access denial.
- Acceptance:
  compromise of standard unlock path does not unlock high-risk partitions.

## 9. Agent Identities
- Problem:
  Tokens alone do not model lifecycle and ownership.
- Implementation:
  Add first-class agent accounts:
  id, owner, policy binding, rotation interval, revocation state.
  Tokens must be issued under agent identity.
- Data/Config:
  `agent_identities.json` versioned schema.
- Tests:
  identity disable/revoke, policy inheritance.
- Acceptance:
  every token and access event maps to a managed agent identity.

## 10. Safer Automation Primitives
- Problem:
  cron jobs often use plaintext env secrets.
- Implementation:
  Add job runner integration:
  broker-only auth, scoped policy binding, ephemeral runtime context.
  Add template commands for systemd timers and cron wrappers.
- Tests:
  non-interactive scheduled task success without plaintext secret files.
- Acceptance:
  supported scheduled workflows avoid plaintext env password dependence.

## 11. Recovery Hardening
- Problem:
  Recovery process can be brittle or under-tested.
- Implementation:
  Add Shamir split/recovery workflows for parent seed protection.
  Add scheduled backup verification drills with signed reports.
- Tests:
  split/recombine determinism, threshold enforcement, drill report generation.
- Acceptance:
  enforceable recovery posture with verifiable drills.

## 12. Conflict-Safe Sync Primitives
- Problem:
  multi-device edits can conflict unpredictably.
- Implementation:
  Introduce deterministic merge strategy:
  monotonic timestamps + deterministic tie-breaker + field-level merge rules.
  Encrypt metadata needed for conflict resolution.
- Tests:
  concurrent edit replay, deterministic final state across nodes.
- Acceptance:
  same inputs always produce same merged vault state.

## 13. Policy as Code
- Problem:
  policy lifecycle lacks strong review workflows.
- Implementation:
  Add schema validation, linting, canonical formatting, diff tooling, policy tests.
  Add optional signed policy bundles and hash pinning.
- Tests:
  lint failures, schema migration tests, canonical output tests.
- Acceptance:
  policy changes are reviewable, testable, and reproducible.

## 14. Deterministic Export Controls
- Problem:
  full-vault exports are dangerous for agent profiles.
- Implementation:
  Enforce policy-restricted subset exports:
  allowed kinds/paths/fields only, default deny full-vault for agent identities.
  Add deterministic manifest for exported subset.
- Tests:
  blocked full export, allowed subset export correctness.
- Acceptance:
  agent profiles cannot perform unrestricted exports by default.

## 15. Security Posture Tooling
- Problem:
  drift and misconfiguration can silently increase risk.
- Implementation:
  Add `seedpass agent posture-check`:
  stale credentials, weak broker config, overbroad policy rules, missing rotation, gate bypasses.
  Output machine-readable report and severity levels.
- Tests:
  posture check fixtures with expected findings.
- Acceptance:
  actionable posture report with CI-friendly nonzero exit on critical findings.

## Recommended Delivery Order
1. Item 1 completion across all auth entry points.
2. Items 2, 7, 14 enforcement expansion.
3. Items 3, 4, 9 identity-token lifecycle.
4. Items 6, 13, 15 governance and audit maturity.
5. Items 8, 10, 11, 12 deeper operational hardening.

## Definition of Done (Cross-Cutting)
- No plaintext secret persistence introduced.
- New schemas are versioned and migration tested.
- All new controls covered by unit + integration tests.
- CLI/API paths return deterministic, machine-readable error payloads.

## Help and Discoverability TODO Backlog
### Objective
Make SeedPass self-describing for autonomous agents and human operators so feature discovery does not depend on external docs or code spelunking.

### TODO 1: Login-Time Guidance
- Add concise post-unlock guidance text in:
  `seedpass vault unlock` and API `/api/v1/vault/unlock`.
- Include links/hints to:
  `seedpass --help`, `seedpass <group> --help`, API `/docs`.
- Add tests verifying hint visibility and stability.

### TODO 2: Machine-Readable Capability Surface
- Add `seedpass capabilities --format json|yaml|text`.
- Include:
  command groups, commands, option schema, auth modes, output mode (`json`/text), risk class, and policy gates.
- Ensure deterministic ordering for diffability in CI.

### TODO 3: Command Metadata Registry
- Add a central metadata registry for CLI/API capabilities.
- Fields:
  `name`, `summary`, `requires_unlock`, `supports_noninteractive`, `requires_approval`, `sensitive_outputs`, `policy_operations`.
- Generate help and capabilities output from the same registry to prevent drift.

### TODO 4: Agent-Focused Help Profile
- Add `--help-profile agent|human`.
- Agent profile:
  concise machine-actionable semantics, failure modes, deterministic examples, JSON schemas.
- Human profile:
  richer narrative hints and workflow examples.

### TODO 5: Output Schema Discovery
- Add `--output json` and `--describe-output` support to critical commands (`agent get`, `vault unlock`, token/policy commands).
- Publish expected JSON field schema in command help and capability output.

### TODO 6: Risk and Approval Annotations in Help
- Mark risky commands in help with a stable tag:
  `risk:high`, `approval:required`.
- Apply to:
  export, reveal-parent-seed, private key retrieval paths.

### TODO 7: Context Bootstrap Command for Agents
- Add `seedpass agent bootstrap-context`.
- Return:
  active profile fingerprint, policy status, broker options available, token status summary, feature support map, version info.

### TODO 8: API Discoverability Parity
- Ensure API endpoint metadata mirrors CLI capability data.
- Add a protected endpoint:
  `/api/v1/capabilities`.
- Keep OpenAPI tags aligned with CLI command groups.

### TODO 9: Regression Tests for Help Contracts
- Snapshot tests for:
  root help, group help, key command help, capabilities JSON.
- Add contract tests ensuring new commands include metadata fields.

### TODO 10: Documentation Sync Automation
- Add a CI check that compares:
  generated capabilities output vs docs command reference.
- Fail CI when command metadata and docs diverge.