Initial Commit

openspec/archive/2026-05-26-api-secrets-bun/proposal.md

@@ -0,0 +1,45 @@
+# `@suaveplan/api-secrets-bun` — `Bun.secrets`-backed secrets adapter
+
+**Package**: `@suaveplan/api-secrets-bun`
+**Status**: PROPOSED
+**Type**: new-package
+**Stage**: 8 — see umbrella `openspec/changes/api-plugin-foundation/`
+
+## Why
+
+Per design doc §3 (`secrets[]` manifest block) and §13.2 (the `secrets` capability slot), plugins read configured secrets via the `secrets` capability. `Bun.secrets` exposes the OS keystore (macOS Keychain, Linux libsecret, Windows Credential Manager) which is the right default for local-dev and single-host operator setups — secrets never touch disk in plaintext and rotate via the OS UI.
+
+## What changes
+
+- ADDED: `createBunSecretsAdapter({ service, allowlist })` — implements the abstract `secrets` capability from `api-secrets`. Reads from `Bun.secrets.get({ service, name })`; writes via `Bun.secrets.set({ service, name, value })`.
+- ADDED: Per-plugin scoping — adapter is instantiated per plugin with its manifest's `secrets[]` as the allowlist. Reads outside the allowlist raise `SECRETS_BUN_NOT_ALLOWED`.
+- ADDED: Capability `secrets.bun` declared so plugins that specifically require the Bun-keystore backend (e.g. for desktop runtimes) can require it via `requiredCapabilities`.
+- ADDED: Conformance — passes `runSecretsConformance` from `api-secrets/testing`.
+- ADDED: Error codes (`SECRETS_BUN_*`): `NOT_FOUND`, `NOT_ALLOWED`, `KEYSTORE_UNAVAILABLE`, `KEYSTORE_LOCKED`, `WRITE_FAILED`.
+
+## Out of scope
+
+- Other secret backends — sibling packages (`api-secrets-vault`, future `api-secrets-aws-sm`, etc.).
+- Migrating existing OS keychain entries between machines — operator concern.
+- Plaintext fallback when the OS keystore is unavailable — adapter refuses to start; another adapter must be selected.
+
+## Source mapping
+
+Genesis-original. Source of design intent: `docs/superpowers/specs/2026-05-13-api-plugin-foundation-design.md`.
+
+| Requirement | Design doc section |
+|---|---|
+| `secrets` capability | §3, §5, §13.2 |
+| `secrets.bun` capability declarable in manifest | §3 (`requiredCapabilities`) |
+| Per-plugin allowlist from manifest `secrets[]` | §3 |
+
+## Verification approach
+
+- `src/adapter/adapter.test.ts` — read / write / list against a fixture `Bun.secrets` namespace; allowlist enforcement (read of un-manifested name raises `SECRETS_BUN_NOT_ALLOWED`).
+- `src/adapter/adapter.spec-conformance.test.ts` — runs `runSecretsConformance` from `api-secrets/testing` against the Bun adapter.
+- `src/error-codes.ts` — every code listed.
+- `tests/dep-graph.test.ts` — runtime deps (`api-types`, `api-secrets`, `error`, `logger`).
+
+## Migration impact
+
+None — additive only. `api-host` registers this when `host.secrets.backend = "bun"`.

openspec/archive/2026-05-26-api-secrets-bun/specs/api-secrets-bun/spec.md

@@ -0,0 +1,60 @@
+<!-- markdownlint-disable MD024 -->
+
+# Capability Spec Delta: api-secrets-bun (api-secrets-bun)
+
+**Package**: `@suaveplan/api-secrets-bun`
+**Status**: PROPOSED
+
+> Every requirement below carries a `**Verified by:**` line at authoring time.
+
+## ADDED Requirements
+
+### Requirement: Bun-keystore-backed secrets adapter implements `secrets`
+
+The package SHALL implement the abstract `secrets` capability from `api-secrets` using `Bun.secrets` (macOS Keychain, Linux libsecret, Windows Credential Manager).
+
+#### Scenario: get returns stored value
+
+- WHEN a secret has been written via the adapter
+- THEN `get(name)` returns its value AND increments `api.secrets.reads_total{backend="bun"}`
+
+**Verified by:** `src/adapter/adapter.test.ts::"get returns stored value AND increments reads_total"`
+
+---
+
+### Requirement: Per-plugin allowlist enforcement
+
+The package SHALL refuse reads of secret names not in the plugin manifest's `secrets[]`. Refusals raise `SECRETS_BUN_NOT_ALLOWED`.
+
+#### Scenario: un-manifested read is refused
+
+- WHEN a plugin's manifest declares `secrets = [{ name: "STRIPE" }]` AND code calls `get("AWS")`
+- THEN the call raises `SECRETS_BUN_NOT_ALLOWED`
+
+**Verified by:** `src/allowlist/allowlist.test.ts::"un-manifested read raises SECRETS_BUN_NOT_ALLOWED"`
+
+---
+
+### Requirement: Locked keystore surfaces explicitly
+
+The package SHALL distinguish a locked keystore (`SECRETS_BUN_KEYSTORE_LOCKED`) from a missing entry (`SECRETS_BUN_NOT_FOUND`). The adapter MUST NOT fall back silently when the OS keystore is locked.
+
+#### Scenario: locked keystore raises specific code
+
+- WHEN the OS keystore is locked
+- THEN reads raise `SECRETS_BUN_KEYSTORE_LOCKED` AND no plaintext fallback occurs
+
+**Verified by:** `src/adapter/adapter.test.ts::"locked keystore raises SECRETS_BUN_KEYSTORE_LOCKED"`
+
+---
+
+### Requirement: Passes `runSecretsConformance`
+
+The package SHALL pass the conformance harness exported by `@suaveplan/api-secrets/testing`. This pins the Bun adapter to the same observable contract as every other secrets backend.
+
+#### Scenario: conformance passes
+
+- WHEN `runSecretsConformance("bun", makeBunAdapter)` runs
+- THEN every harness `it(...)` passes
+
+**Verified by:** `src/adapter/adapter.spec-conformance.test.ts::"Bun adapter passes runSecretsConformance"`

openspec/archive/2026-05-26-api-secrets-bun/tasks.md

@@ -0,0 +1,61 @@
+# Tasks — `@suaveplan/api-secrets-bun`
+
+## 0. Pre-flight (non-negotiable)
+
+- [x] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
+- [x] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
+- [x] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.
+
+## 1. Spec authoring
+
+- [x] 1.1 Read design doc (§3, §5, §13.2)
+- [x] 1.2 Read `openspec/AGENTS.md` Sections 13 and 14
+- [x] 1.3 Draft `proposal.md`
+- [x] 1.4 Draft `specs/api-secrets-bun/spec.md`
+- [x] 1.5 Every requirement carries `**Verified by:**`
+
+## 2. Implementation
+
+- [x] 2.1 Scaffold `packages/api/api-secrets-bun/`
+- [x] 2.2 `src/adapter/` — `createBunSecretsAdapter`
+- [x] 2.3 `src/allowlist/` — per-plugin allowlist enforcement
+- [x] 2.4 `src/error-codes.ts`
+- [x] 2.5 `src/index.ts` — explicit named re-exports
+
+## 3. Tests
+
+- [x] 3.1 `src/adapter/adapter.test.ts`
+- [x] 3.2 `src/adapter/adapter.spec-conformance.test.ts` — `runSecretsConformance`
+- [x] 3.3 `tests/dep-graph.test.ts`
+- [x] 3.4 Every `it(...)` carries `{ timeout: 5000 }`
+
+## 4. Documentation
+
+- [x] 4.1 Sibling `.md` per implementation `.ts`
+- [x] 4.2 `README.md` `## Modules`
+- [x] 4.3 Update `CLAUDE.md` package listing
+
+## 5. Pre-archive verification (the 5-gate triple)
+
+- [x] 5.1 `bun run check`
+- [x] 5.2 `bunx turbo lint typecheck test --filter=@suaveplan/api-secrets-bun`
+- [x] 5.3 `bunx turbo test:coverage --filter=@suaveplan/api-secrets-bun` — 100/100/100/100
+- [x] 5.4 `bun scripts/openspec-conformance.ts @suaveplan/api-secrets-bun`
+- [x] 5.5 `bunx turbo build --filter=@suaveplan/api-secrets-bun`
+
+## 6. Pre-archive 7-row checklist
+
+- [x] 6.1 Generics threaded
+- [x] 6.2 Zod schemas wired at manifest-allowlist ingestion
+- [x] 6.3 Every `SECRETS_BUN_*` code thrown by a production path
+- [x] 6.4 Strict-mode: locked keystore raises, never silently falls back
+- [x] 6.5 OTel `api.secrets.reads_total{backend="bun"}` asserted
+- [x] 6.6 Lifecycle dedup — adapter `dispose()` idempotent
+- [x] 6.7 No retroactive tick
+
+## 7. Archive
+
+- [x] 7.1 Fold spec delta into `openspec/specs/api-secrets-bun/spec.md`
+- [x] 7.2 Move folder to archive
+- [x] 7.3 Tick `8.13` in umbrella tasks
+- [x] 7.4 Refresh `MANIFEST.md`