feat: add approval request intake and bypass-request promotion

[daviddanialy]

Adds approval-request intake (AIS-469) — the two entry points that need no surface-placement decision. Stacked on the org-exposure-signals branch; review that stack bottom-up.

What it does

mcpApproval.createRequest — the proactive path. A member names a server (URL or stdio launch command) and says why. Deliberately carries no RBAC scope, per the ticket's decision: the people asking typically cannot reach the dashboard, and a scope for it would either be ungranted for everyone who needs it or granted so universally it means nothing — the same posture as the block and bypass surfaces. Authentication, project membership, and the product-feature gate still apply, each tested.

mcpApproval.promote — decide-scoped. Brings a risk-policy bypass request (minted by a shadow-MCP block) into the review queue, carrying the blocked employee as requester with their justification, and linking the source on risk_policy_bypass_request_id. Whole-policy bypasses are rejected (they name no server), and a bypass whose hook couldn't resolve a user still promotes — the ask isn't lost, it just carries no requester attribution.

The promote path is the sharpest IDOR surface in this workflow

The bypass-request id is caller-supplied, and there is deliberately no database-level pin between bypass requests and projects for this pair (adding one would have made the schema migration non-transactional). So the handler's project-scoped resolve is the primary control: the id is read under the caller's project before anything is written, and the cross-project test asserts both the 404 and that nothing entered the queue.

Dedupe converges across entry points

Server URLs canonicalize with the same function that keys the shadow-MCP inventory, so a proactive ask, a promoted block, and the org's own observed traffic land on one review per server — https://MCP.Example.com:443/sse#x and https://mcp.example.com/sse are the same request, whichever door it came through. One row per person per request: a repeat ask keeps the freshest justification without erasing an earlier one when the new ask carries none. A re-request reopens a denied review with its decision history intact.

Also

• Identity resolution runs at intake, so artifact_ref / version_pinned are populated before an admin looks; an unidentifiable reference is stored as explicitly unresolved, never as empty.
• Every admission audits as mcp_approval_request:create in the same transaction.

Evidence assembly at intake

Every admission now gathers the deterministic evidence into the versioned current_evidence document — resolved identity (always present, unknown shown as unknown), registry metadata for package references (with package_not_published as a distinct clean outcome), and the org's own traffic exposure for remote ones (fed the resolved URL, so mcp-remote stdio commands hit the inventory). Per-source failures land in a gaps list inside the document rather than reading as checked-and-clean, gathering runs before the transaction under a bounded timeout, and a flaky registry can delay evidence but never lose an admission.

The optional research agent deliberately stays outside this document: web-sourced findings keep their own trust tier and lifecycle in mcp_research_reports, and this document doubles as the agent's briefing when an admin later triggers a run — DecodeDocument is the version-dispatched typed read the runner (and any frozen-snapshot reader) will use.

Not in this PR

Where the employee-facing proactive surface lives (block-page family vs device-agent) — the ticket defers that to the design partner. End-to-end verification of the non-admin block-page auth path is also outstanding.

Testing

13 new tests (44 total in the package): both happy paths, cross-project promote, dedupe across users and entry points, repeat-ask note semantics, unattributed requester, feature gate, scope boundary, audit delta. mise run lint:server, mise run gen:sdk, and pnpm -F dashboard type-check all pass.

AIS-469

🤖 Generated with Claude Code

---

Summary by cubic

Adds employee approval-request intake and admin bypass-request promotion for MCP approvals. Also assembles a versioned evidence document at intake so admins have identity, registry, and traffic signals ready (AIS-469).

• New Features

  • mcpApproval.createRequest: members ask by server URL or stdio command; no RBAC scope; auth, project membership, and feature gate enforced.
  • mcpApproval.promote (decide-scoped): promotes a bypass into the queue, links risk_policy_bypass_request_id, validates the id within the caller’s project, rejects whole-policy bypasses, supports unattributed users.
  • Dedupe across entry points via canonical server keys; repeat asks attach; re-requests reopen denied reviews without losing history.
  • Evidence at intake: builds versioned current_evidence with identity, package-registry metadata, and org traffic exposure; records gaps; bounded timeout with per-source deadlines; pooled registry client to reduce churn; research agent stays separate.
  • Auditing + SDK/CLI: every intake logs mcp_approval_request:create; OpenAPI updated; new client methods and React Query hooks (createMcpApprovalRequest, promoteMcpApprovalRequest); CLI adds create-request and promote.

• Bug Fixes

  • Redacts server URLs (scheme/host/path) before persisting/auditing; only http/https targets allowed; target_kind enforced as an enum at the API boundary.
  • createRequest requires a non-blank note; promote note stays optional and won’t erase an existing justification; reopen guards verified; audit event wording now covers creates.

^{Written for commit faf4073. Summary will update on new commits.}

[linear-code]

AIS-469

[changeset-bot]

🦋 Changeset detected

Latest commit: faf4073

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
server	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[cubic-dev-ai]

cubic analysis

All reported issues were addressed

Linked issue analysis

Linked issue: AIS-469: feat: approval request intake for employees without dashboard access

Status	Acceptance criteria	Notes
✅	Proactive intake endpoint to let a non-admin member request review (mcpApproval.createRequest) that accepts a target and a free-text justification (note) and intentionally carries no new RBAC scope	Handler, API surface, SDK and CLI were added for createRequest; payload includes target, targetKind, and note; tests exercise createRequest and scope/feature-gate boundaries.
✅	Promote a shadow-MCP bypass request into the approval queue and carry the blocked employee as the requester with their justification (mcpApproval.promote), rejecting whole-policy bypasses and allowing unattributed requests	Promote endpoint and plumbing implemented; promote links risk_policy_bypass_request_id and preserves requester/note handling; tests include cross-project safety and unattributed-requester behavior.
✅	Dedupe: proactive asks, promoted blocks, and observed traffic converge on one review per canonicalized server reference	Target canonicalization used when creating/upserting requests so repeated asks attach to the same review; DB upsert preserves existing rows and re-opens denied reviews per description and tests.
✅	Identity resolution runs at intake so evidence fields (artifact_ref / version_pinned) are populated or explicitly marked unresolved before an admin looks	Intake invokes identity resolution and stores resolved references or explicit unresolved markers; tests exercise identity/resolve semantics and repeat-ask note behavior.
✅	Every intake is audited as mcp_approval_request:create in the same transaction	Audit action and logger added; tests include audit delta assertions.

<sub>Tip: instead of fixing issues one by one fix them all with cubic

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 7 files (changes from recent commits).

<sub>Tip: Review your code locally with the cubic CLI to iterate faster.

Fix all with cubic | Re-trigger cubic</sub>