feat(policy): add one-time MCP approvals

[mohanagy]

Closes #27.

Summary

Implements connection-bound, one-time approvals for confirmation-required tools, resources, and prompts:

• binds approvals to the session, source/routed profiles, upstream, target, normalized arguments, and short expiry;
• uses native MCP form elicitation where supported, with a safe fallback bearer otherwise;
• adds pending-only list, approve, and deny management tools;
• serializes request, decision, expiry, and consumption audit transitions.

Security impact

Approval bearers and raw operation arguments are never persisted or audited. Stored state contains only keyed digests and safe metadata; a bearer can authorize only its exact, connection-bound operation once. Failed expiry audit writes retain the transition for retry and expose audit health without replacing the caller's actionable approval error.

Validation

• focused approval fallback regression: 18 passing
• npm run lint and npm run typecheck pass
• prior full local suites: 656 passing, 11 platform skips; this sandbox cannot bind loopback listeners or reach the npm registry, so fresh package-consumer installation and remote transport cases require CI
• updated-head CI and CodeRabbit review are pending

[coderabbitai]

📝 Walkthrough

Walkthrough

This change adds connection-bound, one-time approvals for confirmation-required MCP operations, including fallback tokens, form elicitation, approval management tools, expiry and replay protection, audited lifecycle transitions, bounded in-memory storage, and integration tests.

Changes

Approval lifecycle

Layer / File(s)	Summary
Approval store lifecycle and binding src/approvals/approval-store.ts, tests/approval-store.test.ts	Adds session-scoped approval records with HMAC-based binding and token digests, bounded storage, expiry, denial, atomic consumption, replay protection, and concurrency coverage.
Approval audit and error contracts src/audit/*, src/utils/errors.ts, src/cli/exit-codes.ts, tests/cli-exit-codes.test.ts	Adds approval audit event types and writing, plus approval-specific policy errors and CLI mappings.
Pipeline enforcement and MCP integration src/mcp/server/operation-pipeline.ts, src/mcp/server/miftah-server.ts, tests/operation-pipeline.test.ts	Routes confirmation decisions through approval bindings, propagates request context, supports approval management tools and form or fallback flows, and serializes audited transitions.
Approval validation and documentation tests/approval-fallback.test.ts, tests/approval-docs-contract.test.ts, README.md, docs/*, CHANGELOG.md	Covers fallback, elicitation, expiry, audit failure, replay, and resource/prompt behavior while documenting approval semantics and security boundaries.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant MiftahServer
  participant ApprovalStore
  participant OperationPipeline
  participant Upstream
  Client->>MiftahServer: Call confirmation-required operation
  MiftahServer->>OperationPipeline: Execute with request context
  OperationPipeline->>MiftahServer: Request approval for exact binding
  MiftahServer->>ApprovalStore: Create pending approval
  MiftahServer-->>Client: Form elicitation or fallback token flow
  Client->>MiftahServer: Approve or deny approval
  MiftahServer->>ApprovalStore: Consume approved binding once
  MiftahServer->>OperationPipeline: Continue approved operation
  OperationPipeline->>Upstream: Forward exact operation

Loading

Possibly related PRs

• mohanagy/miftah#46: Updates the shared error typing used by the new approval error codes.
• mohanagy/miftah#48: Also changes resource and prompt routing in miftah-server.ts.
• mohanagy/miftah#53: Provides related audit infrastructure extended here for approval events.

Poem

A bunny guards each token tight,
Bound to one request, day or night.
Forms may bloom or bearers glow,
One hop consumed, then off they go.
Audits trail softly, secrets stay—
Approval hops along its way.

---

Caution

Pre-merge checks failed

Please resolve all errors before merging. Addressing warnings is optional.

• Ignore

❌ Failed checks (1 error)

Check name	Status	Explanation	Resolution
Docstring Coverage	❌ Error	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes match #27: binding, one-time consumption, elicitation fallback, management tools, auditing, redaction, and concurrency coverage are all present.
Out of Scope Changes check	✅ Passed	The docs, tests, and code changes all support the approval feature and do not introduce unrelated scope.
Title check	✅ Passed	The title is concise and accurately captures the main change: adding one-time MCP approvals.
Description check	✅ Passed	The description includes the required Summary, Security impact, and Validation sections with relevant details, though the validation checklist is not fully exhaustive.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/issue-27-approvals

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/mcp/server/miftah-server.ts`:
- Around line 935-953: Update withApprovalExpiryAudit so failures from
writeExpiredApprovalTransitions in the operation() catch branch cannot replace
the original operation error. Attempt the audit write while suppressing or
separately handling its failure, then rethrow the original caught error; keep
the existing rollback behavior for audit failure after a successful operation.
- Around line 976-991: Update the writeApproval method to use the existing
ApprovalAuditAction type from audit-types.ts (or the established audit-trail
re-export) instead of its inline literal union, preserving the current allowed
action values while eliminating the duplicate source of truth.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 0843890a-bd51-48d6-b4b9-fed83d66bb34

📥 Commits

Reviewing files that changed from the base of the PR and between f798f66 and 9997605.

📒 Files selected for processing (17)

• CHANGELOG.md
• README.md
• docs/architecture.md
• docs/config.md
• docs/security.md
• src/approvals/approval-store.ts
• src/audit/audit-trail.ts
• src/audit/audit-types.ts
• src/cli/exit-codes.ts
• src/mcp/server/miftah-server.ts
• src/mcp/server/operation-pipeline.ts
• src/utils/errors.ts
• tests/approval-docs-contract.test.ts
• tests/approval-fallback.test.ts
• tests/approval-store.test.ts
• tests/cli-exit-codes.test.ts
• tests/operation-pipeline.test.ts