Api Governance

CodeRifts — contract-change authorization

Only a granted change can proceed. Before a contract change merges, deploys or registers, CodeRifts decides whether it is authorized — and the check is red without a grant.

One grant binds three things: the authorization, its single use, and the target state the change moves to. The decision is signed, and the receipt verifies offline — you do not have to trust our database to check what was authorized.

Every decision also names what it does not prove.

• Hosted MCP server: https://app.coderifts.com/mcp
• Manifest: https://coderifts.com/mcp.json — the canonical published document. The mcp.json at the root of this repository is a pointer to it, not a second copy.
• Official MCP Registry: io.github.coderifts/api-governance
• Website: https://coderifts.com
• Live demo PR: https://github.com/coderifts/demo/pull/4

Install

# Claude Code/plugin marketplace add coderifts/api-governance/plugin install api-governance@coderifts
# Any MCP client (Streamable HTTP) — add to its MCP config{ "mcpServers": { "coderifts": { "url": "https://app.coderifts.com/mcp",  "headers": { "Authorization": "Bearer <YOUR_CODERIFTS_API_KEY>" } } } }
# SDKsnpm install @coderifts/sdkpip install coderifts-sdk

GitHub Copilot reads the same server under three different root keys — servers in .vscode/mcp.json, mcpServers in the cloud agent's MCP settings, and mcp-servers in a custom agent's frontmatter — and npx coderifts copilot-setup writes all three (details below).

A key is needed only to authorize; get one at https://app.coderifts.com/api/signup.

Claude Code plugin

Install the CodeRifts marketplace, then the api-governance plugin (MCP server + skill). Requires CODERIFTS_API_KEY for tool calls.

/plugin marketplace add coderifts/api-governance/plugin install api-governance@coderifts

Local checkout (after clone):

/plugin marketplace add ./plugin install api-governance@coderifts

The plugin wires the hosted MCP at https://app.coderifts.com/mcp and the api-governance skill. Tools exposed: preflight_change_set, verify_receipt, get_decision_details only.

Cursor plugin

Cursor Plugin package (measured Cursor layout: .cursor-plugin/plugin.json + skills/ + rules/ + mcp.json + hooks/hooks.json). Same hosted MCP and the same three tools as the Claude plugin — no fourth tool. Deterministic / signed / fail-closed — not an AI compatibility scan.

Validate:

npm run validate:cursor

The generated-rule check is LIVE when CODERIFTS_APP_ROOT (default ~/coderifts-app) has generated/agent-host/.cursor/rules/coderifts.mdc, and RECORDED against fixtures/recorded/app-generator when it does not (weaker, named). A missing or corrupt snapshot still exits 1 — no silent skip.

OpenAI / Codex package

Codex plugin package (measured OpenAI Codex layout: .codex-plugin/plugin.json + .mcp.json + skills/ + AGENTS.md). Same hosted MCP and the same three tools as the Claude plugin — no fourth tool.

Production pattern (function-calling apps)

OpenAI’s model only emits tool_call JSON; your app executes it. Wire governance at that host loop — not as a Claude-style PreToolUse hook. Full steps + one canonical loop:

→ plugins/api-governance-openai/docs/openai-production-pattern.md

# Offline smoke (needs ~/coderifts-agent-guard built, or CODERIFTS_AGENT_GUARD_ROOT)npm run smoke:openai-dispatch

⚠ Still failing on the same one assertion, re-measured 2026-09-24: ALLOW factory ran — execute() did not run. The other eight assertions pass (4 ALLOW, 5 BLOCK), and the BLOCK side — the side that matters for a gate — is fully green: the factory does not run, the content is the gate denial with no fabricated success, and the decision identity is surfaced. The failing assertion is on the ALLOW path, where the dispatch wrapper returns the function result without having invoked the injected factory.

The 2026-09-14 version of this note ended "Investigation is in progress." That was dropped rather than re-dated: ten days on, it is a claim about activity that nothing here can verify, and a README that reports its own diligence is reporting the one thing a reader cannot check. What a reader can check is the assertion name and today's date.

Local checkout in Codex (team marketplace path):

# From a clone of this repo, point Codex at .agents/plugins/marketplace.json# then install api-governance-openai (UI / plugin install — see Codex plugin docs).

Validate package consistency (manifest, tool parity, AGENTS.md empty-diff vs regeneration):

npm run validate:openai# or: node scripts/validate-openai-package.js

AGENTS.md regeneration is LIVE when ~/coderifts-app (or CODERIFTS_APP_ROOT) exists, and RECORDED against fixtures/recorded/app-generator when it does not (weaker, named). A missing or corrupt snapshot still exits 1. Directory listing / account submission steps are not automated here.

GitHub Copilot kit

Reference copies of the generated Copilot MCP configs + instructions (single source: coderifts-app generators). Same hosted MCP and the same three tools — no fourth tool.

Primary install (living command — prefer this over copying from the kit):

npx coderifts copilot-setup# optional: --out <dir>   --check (drift-gate)   --force

Agent-host instructions (including .github/copilot-instructions.md) come from:

npx coderifts agent-setup

Three Copilot surfaces (root keys differ)

From the generated guide (copilot/docs/copilot-mcp.md — do not re-author this table):

Tools allowlisted everywhere: preflight_change_set, verify_receipt, get_decision_details.

Vendored reference tree (copilot/)

Validate empty-diff vs regeneration + 3-tool discipline:

node scripts/validate-copilot-kit.js

Empty-diff vs regeneration is LIVE when CODERIFTS_APP_ROOT has the generators, and RECORDED against fixtures/recorded/app-generator when it does not (weaker, named). A missing or corrupt snapshot still exits 1. The kit is a communication / distribution mirror — npx coderifts copilot-setup remains the install path.

Agent Skill (skills.sh)

npx skills add coderifts/api-governance

The skills CLI discovers skills/api-governance/SKILL.md at this repository's root and installs it under the name api-governance. Where it lands depends on the agent (the CLI's own table): .agents/skills/api-governance/ for most agents (Codex, Cursor, Gemini CLI, GitHub Copilot, OpenCode, …) and .claude/skills/api-governance/ for Claude Code.

One skill, one name (2026-09-29). The three SKILL.md carriers — Claude (plugins/api-governance/skills/api-governance/), Cursor (plugins/api-governance-cursor/skills/coderifts/) and Codex/OpenAI (plugins/api-governance-openai/skills/api-governance/) — carry the same body byte for byte and the same name: coderifts, the name skills.sh lists (npx skills add coderifts/api-governance installs ./.agents/skills/coderifts/, measured 2026-09-29). Only the frontmatter description is per host. All three are generated by coderifts-app scripts/generate-skill-carriers.js from agent/skills/coderifts/SKILL.md; test/one-skill.test.js holds them together. The website's .well-known/agent-skills/coderifts/SKILL.md is the Cursor carrier, vendored.

MCP server

CodeRifts runs as a hosted Streamable HTTP MCP server. Any MCP-compatible agent (Claude Desktop, Cursor, LangGraph, AutoGen, custom) can connect and run governance checks before tool calls or merges.

• Endpoint: https://app.coderifts.com/mcp
• Transport: Streamable HTTP (protocol version 2025-06-18)
• Server: CodeRifts API Governance v1.0.3 — read from initialize → result.serverInfo.version on 2026-09-24. A version typed into a README is a claim with a date on it; npm run validate:tools-wire compares the TOOLS to the live server on every push, pull request and daily cron, but nothing compares this line, so re-read it rather than trust it.
• Auth: initialize, tools/list and an analyze tools/call need no key (measured live 2026-09-26). An authorize call mints a signed receipt and needs an API key — send Authorization: Bearer <key> or X-API-Key: <key>.

Connect

{  "mcpServers": {    "coderifts": {      "url": "https://app.coderifts.com/mcp",      "headers": {        "Authorization": "Bearer <YOUR_CODERIFTS_API_KEY>"      }    }  }}

Verify the connection

curl -sS https://app.coderifts.com/mcp \  -H 'Content-Type: application/json' \  -H 'Accept: application/json, text/event-stream' \  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

Expected: a JSON-RPC result with serverInfo and capabilities.tools.

Try without a key

An analyze call over MCP needs no key:

curl -sS https://app.coderifts.com/mcp \  -H 'Content-Type: application/json' \  -H 'Accept: application/json, text/event-stream' \  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"preflight_change_set","arguments":{"preflight_mode":"analyze","artifacts":[{"id":"api","type":"openapi","before":"openapi: 3.0.0\ninfo: {title: Pets, version: 1.0.0}\npaths:\n  /pets:\n    get:\n      responses:\n        \"200\":\n          description: ok\n          content:\n            application/json:\n              schema:\n                type: object\n                properties:\n                  id: {type: string}\n                  name: {type: string}\n","after":"openapi: 3.0.0\ninfo: {title: Pets, version: 1.0.0}\npaths:\n  /pets:\n    get:\n      responses:\n        \"200\":\n          description: ok\n          content:\n            application/json:\n              schema:\n                type: object\n                properties:\n                  id: {type: string}\n"}]}}}'

Measured response (live, 2026-09-26 — removing name from GET /pets), in the tool result:

{ "preflight_mode": "analyze", "analysis_outcome": "BREAKS_DETECTED",  "authorization_effect": "NONE", "may_execute": false, "receipt_kind": "NONE",  "breaking_changes": 1, "risk_score": 14 }

That is information, not permission: may_execute is false on every analyze answer. To act, call again with preflight_mode: "authorize" and context.operation, with a key.

Two public REST endpoints need no auth at all:

curl -s "https://app.coderifts.com/api/v1/public/preflight?url=https://petstore3.swagger.io/api/v3/openapi.json"
curl -s -X POST https://app.coderifts.com/api/v1/public/actionguard-check \  -H "Content-Type: application/json" \  -d '{"filename":".github/workflows/ci.yml","base_content":null,"head_content":"jobs:\n  b:\n    steps:\n      - uses: some-owner/some-action@main"}'

Both return HTTP 200 without a key. They do not share a response shape:

• GET /api/v1/public/preflight is analyze-only. There is no decision field. The body carries analysis_outcome (Petstore URL: NO_BREAK_DETECTED), authorization_effect: NONE, and may_execute: false.
• POST /api/v1/public/actionguard-check does return a decision field (unpinned uses: @main payload: WARN) plus execution_action: CONTINUE_WITH_MONITORING.

Tools

The hosted MCP server exposes exactly three tools (from live tools/list; pinned in this repository as tools.wire.v1.json, which npm run validate:tools-wire checks against the live server on every push, pull request and the daily cron):

On the authorize path of preflight_change_set, the decision envelope includes fields such as decision, execution_action, risk_score, safe_for_agent, and related analysis fields so agent runtimes can branch on a stable contract. Prefer branching on execution_action when present.

How agents use it

1. Before merging an API change (or before an agent acts on a contract change), call preflight_change_set with full before/after artifacts and preflight_mode: "authorize" (plus context.operation).
2. Branch on execution_action only: CONTINUE proceeds, CONTINUE_WITH_MONITORING proceeds with a wired monitoring sink, REQUEST_APPROVAL pauses for a human, STOP stops the merge / aborts the agent step. Any other value is not permission — fail closed.
3. Before acting under the receipt you hold, call verify_receipt with the same context the preflight was made under, and act only when currently_authorized is true. Do not re-preflight unless the change set or operation changed.
4. To inspect a prior decision by id, call get_decision_details.

Decision logic is deterministic: a single breaking change is never silently allowed. Tests can pass and still ship a broken contract — CodeRifts checks the contract itself at PR time.

Also available

• GitHub App on the GitHub Marketplace — installs without configuration and posts a signed contract-change decision (ALLOW / WARN / REQUIRE_APPROVAL / BLOCK) on every pull request, across four gates: API contract, schema-vs-code, auth surface and workflow actions. ⚠ It reports by default: the check's phase-1 conclusion is clamped to neutral and MERGEGATE_ENFORCE defaults false, so it prevents a merge only once the check is required on the branch and that variable is on. The platform truth table is the source of truth for that distinction: https://coderifts.com/docs/platform-truth-table/
• SDKs: npm install @coderifts/sdk (TypeScript), pip install coderifts-sdk (Python).
• CLI: coderifts (npm) with a pre-push hook.
• Integrations: Backstage plugin, VS Code extension, LangGraph / AutoGen / CrewAI.

Links

• Website: https://coderifts.com
• Decision Spec: https://coderifts.com/decision-spec/
• API reference: https://app.coderifts.com/api/docs
• Manifest: https://coderifts.com/mcp.json
• Receipt verifier (verify our receipts without trusting us): https://github.com/coderifts/receipt-verifier
• Contact: [email protected]

License

See LICENSE.