Identity Vault Phase 2: MCP + REST contract (fan-out gate)

[izzywdev]

Phase 2 fan-out gate for the identity-vault subsystem (design: docs/superpowers/specs/2026-06-24-identity-vault-mcp-design.md). Backend, UI, and tests build against this frozen contract. Contract only — no implementation.

Authored by the contract-designer agent; finalized after it hit an account billing limit mid-run.

What's frozen (contracts/identity-vault/)

• openapi.yaml — OpenAPI 3.1, 23 paths / 46 schemas: discovery (metadata-only), gated secret access (profile / site-login / TOTP-code / card / api-token), store_site_login write, approvals (get/list/approve/deny), management (orgs/members/identities/agents/scopes/rotate), audit-log.
• mcp-tools.json — all 10 MCP tools from design §6, field-consistent with the REST schemas.
• README.md — REST↔MCP mapping, sensitivity/approval semantics, consumer usage.
• .spectral.yaml, package.json (lint / mock / gen:types), client/ (generated types target).

Security semantics encoded

• Bearer agent-token auth; scope-checked. 401 bad/missing token · 403 out-of-scope/cross-tenant · 404 not-found-under-owner · 202 approval_required (7 endpoints) for HIGH-sensitivity secrets → poll GET /approvals/{id} → one-time short-TTL value.
• TOTP endpoint returns the current code, never the seed. No endpoint returns a secret without policy + audit.

Validation

• openapi.yaml + mcp-tools.json parse clean; all 9 enums well-formed; no null schema nodes.
• ⚠️ Spectral CLI threw an internal null/enum error — its known OpenAPI-3.1 ruleset limitation, not a spec defect. CI should run npm run lint with a 3.1-compatible linter (or pin ruleset); npm run gen:types should be run to populate client/.

Why draft

Frozen as the gate, but kept draft until the lint/gen toolchain runs green in CI. Once merged, Phases 3–5 (vault infra, broker, approval UI) fan out against it.

🤖 Generated with Claude Code

[github-actions]

CI failure analysis

I investigated the failed CI run (#28237236661) and found two bugs:

---

Bug 1 (PRIMARY): Python 3.10 parsed as 3.1 in the YAML matrix

In .github/workflows/ci.yml, line 15:

python-version: [3.9, 3.10, 3.11]

YAML parses unquoted 3.10 as the float 3.1. GitHub Actions passes 3.1 to setup-python, which fails with:

The version '3.1' with architecture 'x64' was not found

This failure triggers fail-fast and cancels all other matrix jobs.

Fix: Quote the versions on line 15:

python-version: ['3.9', '3.10', '3.11']

⚠️ This fix requires workflows write permission. The autofix bot cannot push changes to .github/workflows/ files — a maintainer must apply this change manually.

---

Bug 2 (SECONDARY): Missing lint and type-check scripts in frontend/package.json

The CI workflow calls npm run lint and npm run type-check but neither script was defined in frontend/package.json. This would cause all matrix jobs to fail once they reach the frontend linting step (after Bug 1 is fixed).

Fix: Add to frontend/package.json scripts block:

"lint": "eslint src --ext .ts,.tsx,.js,.jsx",
"type-check": "tsc --noEmit"

This fix has been committed to branch claude-auto-fix-ci-feat/identity-vault-phase2-contract-28237273261 and pushed, but a PR could not be opened automatically. You can merge this branch into feat/identity-vault-phase2-contract or cherry-pick commit 25fe53f.

---

Summary of action needed:

1. Manually edit .github/workflows/ci.yml line 15 to quote the Python versions
2. Merge or cherry-pick the frontend/package.json fix from branch claude-auto-fix-ci-feat/identity-vault-phase2-contract-28237273261 (commit 25fe53f)