The access door
Developers
The published contract of the access door: what a key reads, what it can never reach, the one write, every operation with its scope and an example, the MCP tools, the webhook signature, the limits and the change policy; and whether the door is open today.
Every statement on this page names the code that makes it true and the law that holds it in every build; the operations, the error contract and the tool list are printed from the registry the server serves its contract from, so this page cannot say more than the door does.
- Made true by:
src/lib/access/contract.ts,src/lib/access/openapi.ts,src/lib/access/mcp.ts- Held by:
src/lib/access/contract.test.ts,src/lib/access/openapi.test.ts,src/lib/access/mcp.test.ts
The door today
The door is closed today. On the owner’s decision of 2026-10-26 (D-12, release 45) FLAG_ACCESS_API is off in DraftCounsel production, so the contract document and every operation answer 404 not-found before anything is read; FLAG_MCP is off and the MCP adapter serves nothing. When the door opens, this page will say so and since when, in a dated version.
- Made true by:
src/lib/access/handlers.ts,src/lib/access/mcp.ts,src/lib/registers/feature-inventory.ts- Held by:
src/app/api/v1/openapi.json/route.test.ts,src/lib/access/mcp.test.ts,src/lib/access/contract.test.ts
When the owner opens it, a request without a key is answered 401 key-required. A keyed call is checked against its key on every request. The reads of the matters a key reaches and of a matter’s runs, decisions, deadline proposals, proof packets and export receipts are served through the path a person’s session walks; the findings, citation-report and foundations reads and the proposal inbox arrive in later parts of the upgrade plan, and until they do each answers 503 read-faulted with its reason, never an empty 200.
- Made true by:
src/lib/access/handlers.ts,src/lib/access/openapi.ts- Held by:
src/app/api/v1/openapi.json/route.test.ts,src/lib/access/openapi.test.ts
Opening is staged: a preview, then the owner’s own firm, then firms the owner names, then open. Each stage is the owner’s act and is written in the activation record when it happens.
- Made true by:
docs/registers/ACTIVATION-RECORD.md,src/lib/quality/activation.ts- Held by:
src/lib/quality/activation.test.ts
What a key reads
The reach rule, drawn
A key reaches the matters its issuer owns and the matters of the firm’s partition, less every matter a wall or a hold screens, narrowed to the key’s allow-list when it has one; the allow-list only narrows and never widens.
- Made true by:
src/lib/access/keys.ts- Held by:
src/lib/access/keys.test.ts
Every call, and every continuation of a stream, runs the check again: the key’s hash, its revocation, the issuer’s standing in the firm, the scope, the acting permission and the reach. A revoked key fails on its next request.
- Made true by:
src/lib/access/keys.ts- Held by:
src/lib/access/keys.test.ts
A key is minted as an attorney key or a client-safe key and the class is fixed for its life; a client-safe key is forced to the client-producible view of everything it reads.
- Made true by:
src/lib/access/keys.ts- Held by:
src/lib/access/keys.test.ts
A read resolves through the same effective policy a person’s session resolves through, with the key’s issuer as the actor and the actor kind external-proposal, so the approve and transmit classes deny by construction; the as-of a read reports is the data’s own, never the response time.
- Made true by:
src/lib/access/effective-policy.ts,src/lib/policy.ts- Held by:
src/lib/access/effective-policy.test.ts
Every read writes a usage row naming the key, the operation, the result and the bytes, and a read-audit row naming the lane; neither row carries content.
- Made true by:
src/lib/access/keys.ts- Held by:
src/lib/access/keys.test.ts
What a key can never reach
A privileged document is never served on a key, whatever the key’s scope, class or allow-list; the request is answered 404, indistinguishable from a matter the key does not reach.
- Made true by:
src/lib/access/keys.ts,src/lib/refusals/catalogue.ts- Held by:
src/lib/access/keys.test.ts,src/lib/refusals/catalogue.test.ts
A matter behind a wall or a hold is outside every key’s reach, and the door never says which: not found and not reachable are one answer.
- Made true by:
src/lib/access/keys.ts,src/lib/access/openapi.ts- Held by:
src/lib/access/keys.test.ts,src/lib/access/openapi.test.ts
No confirmation token is minted, returned or accepted through the API, the MCP adapter or any batch or cancellation path, and the door’s module graph cannot import the executor, the artifact decision, the confirmation mint, the calendar gate, sharing or email: the propose-only law reads the sources.
- Made true by:
src/lib/access/proposals.ts,src/lib/access/handlers.ts- Held by:
src/lib/access/proposals.test.ts
A key is never professional authority: nothing it sends is approved, filed, served, signed, calendared, exported or deleted by the door. A proposal it makes is handed to the desk’s own rail as a row that executes nothing.
- Made true by:
src/lib/access/proposals.ts- Held by:
src/lib/access/proposals.test.ts
An external-agent grant is single-use, expiring, bound to one key, one firm and named matters, closed to read, upload and propose, refused for a client-safe key and inert without its key; a spent grant says spent.
- Made true by:
src/lib/access/grants.ts- Held by:
src/lib/access/grants.test.ts
The one write
The single write is a proposal: a finding to add, a deadline to propose, a revision to request or a note, into a bounded inbox at the suggest rung, with the matter snapshot it stood on bound to it. The door never applies it: an attorney accepts it to the desk’s rail or declines it, by name, one at a time, and “approve all” is refused.
- Made true by:
src/lib/access/proposals.ts- Held by:
src/lib/access/proposals.test.ts
A proposal needs an idempotency key of at least eight characters: the same key with the same body returns the same proposal, and with a different body is answered 409. A body over 64 KiB is answered 413. Override flags among the arguments are stripped and shown on the card. A matter holds at most 50 undecided proposals; the next is answered 429.
- Made true by:
src/lib/access/proposals.ts,src/lib/access/handlers.ts- Held by:
src/lib/access/proposals.test.ts,src/lib/access/contract.test.ts
Every payload
Every payload carries its schema name and number, the time it was generated and the matter it is about; a list says whether more pages follow, apart from whether the source itself was truncated.
- Made true by:
src/lib/access/openapi.ts- Held by:
src/lib/access/openapi.test.ts
A page cursor is signed with the server’s secret and bound to the key, the endpoint and the set it paged; a tampered, swapped or cross-set cursor fails.
- Made true by:
src/lib/access/openapi.ts- Held by:
src/lib/access/openapi.test.ts
A read that faults is answered 503 read-faulted, never an empty 200; a check that did not run is answered 502 check-failed, never a pass.
- Made true by:
src/lib/access/openapi.ts- Held by:
src/lib/access/openapi.test.ts
Every MCP read carries the ids of what it read, a verification status rolled up to its weakest item (verified, attested, not checked or unreadable), the as-of of the data and a read state of read, empty or unreadable; an unread table is null, never an empty list, and a read is never reported stronger than its weakest item.
- Made true by:
src/lib/access/mcp.ts- Held by:
src/lib/access/mcp.test.ts
The MCP adapter
The tool list is generated from the same registry, one tool per operation, with the operation’s kind, scope and key class in its description; a census law fails if the tool list and the operation list differ. Keys only at first: sign-in by OAuth is an owner decision (OD-7) and arrives with its migration when a named firm asks for it.
- Made true by:
src/lib/access/mcp.ts,src/lib/access/openapi.ts- Held by:
src/lib/access/mcp.test.ts
The MCP adapter awaits demonstrated demand (an owner decision); its tools are listed from the registry and pinned by a test, and nothing serves until FLAG_MCP=1.
- Made true by:
src/lib/access/mcp.ts- Held by:
src/lib/access/mcp.test.ts,src/lib/access/contract.test.ts
The MCP tools
Tool:
matters_list(Operationmatters.list)Description: The matters the key reaches. (read; scope read; client-safe keys allowed)
Tool:
runs_list(Operationruns.list)Description: Durable runs of a matter with their states. (read; scope read; attorney keys only)
Tool:
findings_list(Operationfindings.list)Description: Findings of a matter with their decisions. (read; scope read:findings; attorney keys only)
Tool:
decisions_list(Operationdecisions.list)Description: Attorney decisions on artifact versions. (read; scope read:decisions; attorney keys only)
Tool:
packets_list(Operationpackets.list)Description: Decision packets and their manifests. (read; scope read:packets; client-safe keys allowed)
Tool:
cite-reports_list(Operationcite-reports.list)Description: Citation reports with their verdicts. (read; scope read; attorney keys only)
Tool:
foundations_list(Operationfoundations.list)Description: Pinned foundations with the ladder rung reached. (read; scope read; attorney keys only)
Tool:
receipts_list(Operationreceipts.list)Description: Coverage and ingestion receipts. (read; scope read; client-safe keys allowed)
Tool:
deadline-proposals_list(Operationdeadline-proposals.list)Description: Deadline proposals with their derivations. (read; scope read; attorney keys only)
Tool:
proposals_create(Operationproposals.create)Description: The single write: a proposal into the bounded inbox. (propose; scope write-propose; attorney keys only)
Webhooks
A subscription names its events among run.completed, decision.recorded, packet.exported, source.changed and deadline.proposed; its secret is generated by the server and shown once, and only its hash is kept.
- Made true by:
src/lib/access/webhooks.ts- Held by:
src/lib/access/webhooks.test.ts,src/lib/access/contract.test.ts
Every delivery carries three headers: x-draftcounsel-signature, x-draftcounsel-timestamp and x-draftcounsel-delivery. The signature reads t=<timestamp>,e=<event id>,v1=<hmac>, where the HMAC is SHA-256 under the subscription’s secret over the timestamp, a dot, the event id, a dot and the raw bytes of the body; verify over the bytes you received, never a re-serialization. A timestamp more than five minutes from now is refused as a replay; after a rotation the previous secret verifies for the same five minutes while the new one signs.
- Made true by:
src/lib/access/webhooks.ts- Held by:
src/lib/access/webhooks.test.ts,src/lib/access/contract.test.ts
A payload carries pointers only: ids, states and times of at most 128 characters each. A pointer named text, body, document, quote, snippet, content, findings, title, name, email or excerpt is refused by law.
- Made true by:
src/lib/access/webhooks.ts- Held by:
src/lib/access/webhooks.test.ts,src/lib/access/contract.test.ts
A delivery not answered 2xx is tried again after 30 seconds, 2 minutes, 10 minutes, 1 hour and 6 hours, then kept as a dead letter. The delivery id is stable across attempts, so a receiver can de-duplicate; delivery never blocks the action that raised the event; the target is checked on every attempt to be https, a public host name and public resolved addresses.
- Made true by:
src/lib/access/webhooks.ts,src/lib/egress/private-host.ts- Held by:
src/lib/access/webhooks.test.ts,src/lib/access/contract.test.ts
No subscription can be made today: no route takes one and no handler reaches the webhook module. The switch that opens them arrives with the fourth part of the access door, and this page will say so.
- Made true by:
src/lib/access/webhooks.ts,src/lib/access/handlers.ts- Held by:
src/lib/access/contract.test.ts
The limits
Each key may make 60 requests a minute; the next is answered 429 with Retry-After naming the seconds to wait. The count is kept by the key’s hash, never the key.
- Made true by:
src/lib/access/handlers.ts- Held by:
src/lib/access/contract.test.ts,src/lib/attorney-shell/phase10-systems.test.ts
The contract document at /api/v1/openapi.json is served without a key when the door is open, and is limited to 60 requests an hour per address.
- Made true by:
src/app/api/v1/openapi.json/route.ts- Held by:
src/app/api/v1/openapi.json/route.test.ts,src/lib/access/contract.test.ts
Every key carries a daily budget of calls and bytes, set when it is minted; a spent budget refuses until the day turns.
- Made true by:
src/lib/access/keys.ts- Held by:
src/lib/access/keys.test.ts
The change policy
The version is in the path: every operation lives under /api/v1, and every payload names its schema with a number (matter-list/1 and the rest). Within v1 a field may be added; a field is never removed or given a new meaning. A change that would remove or re-mean a field is a new schema number under a new path version, announced on this page before it is served, and v1 keeps serving while it is announced.
- Made true by:
src/lib/access/openapi.ts,src/lib/access/contract.ts- Held by:
src/lib/access/contract.test.ts,src/lib/access/openapi.test.ts
This page is a document of the trust index: its words cannot change without a new dated version, the build fails otherwise, and its history is on the security page beside every other governance document.
- Made true by:
src/lib/registers/governance-documents.ts,src/lib/registers/governance-words.ts- Held by:
src/lib/registers/governance-documents.test.ts
Every operation
The operations below are printed from the registry the server builds its OpenAPI document from; a census law holds the registry equal to the registered routes with an empty pending list, and the document itself is served at /api/v1/openapi.json when the door is open.
- Made true by:
src/lib/access/openapi.ts,src/app/api/v1/openapi.json/route.ts- Held by:
src/lib/access/openapi.test.ts,src/app/api/v1/openapi.json/route.test.ts
matters.listThe matters the key reaches.
- Method:
GET- Path:
/api/v1/matters- Scope:
read- Keys:
- client-safe keys allowed
- Kind:
- read
- Schema:
matter-list/1
Example
curl -H "Authorization: Bearer dck_<your key>" "https://draftcounsel.io/api/v1/matters"runs.listDurable runs of a matter with their states.
- Method:
GET- Path:
/api/v1/matters/{matterId}/runs- Scope:
read- Keys:
- attorney keys only
- Kind:
- read
- Schema:
run-list/1
Example
curl -H "Authorization: Bearer dck_<your key>" "https://draftcounsel.io/api/v1/matters/<matter id>/runs"findings.listFindings of a matter with their decisions.
- Method:
GET- Path:
/api/v1/matters/{matterId}/findings- Scope:
read:findings- Keys:
- attorney keys only
- Kind:
- read
- Schema:
finding-list/1
Example
curl -H "Authorization: Bearer dck_<your key>" "https://draftcounsel.io/api/v1/matters/<matter id>/findings"decisions.listAttorney decisions on artifact versions.
- Method:
GET- Path:
/api/v1/matters/{matterId}/decisions- Scope:
read:decisions- Keys:
- attorney keys only
- Kind:
- read
- Schema:
decision-list/1
Example
curl -H "Authorization: Bearer dck_<your key>" "https://draftcounsel.io/api/v1/matters/<matter id>/decisions"packets.listDecision packets and their manifests.
- Method:
GET- Path:
/api/v1/matters/{matterId}/packets- Scope:
read:packets- Keys:
- client-safe keys allowed
- Kind:
- read
- Schema:
packet-list/1
Example
curl -H "Authorization: Bearer dck_<your key>" "https://draftcounsel.io/api/v1/matters/<matter id>/packets"cite-reports.listCitation reports with their verdicts.
- Method:
GET- Path:
/api/v1/matters/{matterId}/cite-reports- Scope:
read- Keys:
- attorney keys only
- Kind:
- read
- Schema:
cite-report-list/1
Example
curl -H "Authorization: Bearer dck_<your key>" "https://draftcounsel.io/api/v1/matters/<matter id>/cite-reports"foundations.listPinned foundations with the ladder rung reached.
- Method:
GET- Path:
/api/v1/matters/{matterId}/foundations- Scope:
read- Keys:
- attorney keys only
- Kind:
- read
- Schema:
foundation-list/1
Example
curl -H "Authorization: Bearer dck_<your key>" "https://draftcounsel.io/api/v1/matters/<matter id>/foundations"receipts.listCoverage and ingestion receipts.
- Method:
GET- Path:
/api/v1/matters/{matterId}/receipts- Scope:
read- Keys:
- client-safe keys allowed
- Kind:
- read
- Schema:
receipt-list/1
Example
curl -H "Authorization: Bearer dck_<your key>" "https://draftcounsel.io/api/v1/matters/<matter id>/receipts"deadline-proposals.listDeadline proposals with their derivations.
- Method:
GET- Path:
/api/v1/matters/{matterId}/deadline-proposals- Scope:
read- Keys:
- attorney keys only
- Kind:
- read
- Schema:
deadline-proposal-list/1
Example
curl -H "Authorization: Bearer dck_<your key>" "https://draftcounsel.io/api/v1/matters/<matter id>/deadline-proposals"proposals.createThe single write: a proposal into the bounded inbox.
- Method:
POST- Path:
/api/v1/matters/{matterId}/proposals- Scope:
write-propose- Keys:
- attorney keys only
- Kind:
- propose
- Schema:
proposal/1
Example
curl -X POST -H "Authorization: Bearer dck_<your key>" \ -H "Idempotency-Key: <eight characters or more>" \ -H "Content-Type: application/json" \ -d '{"kind":"note","arguments":{"note":"<the note, for an attorney to accept or decline>"}}' \ "https://draftcounsel.io/api/v1/matters/<matter id>/proposals"
The error contract
| Status | Meaning |
|---|---|
400 | the request is malformed |
401 | no key, a bad key or a revoked key |
403 | the key lacks the scope, or the acting permission is refused |
404 | not found or not reachable, indistinguishable |
409 | an idempotency key was reused with a different body |
413 | the body exceeds the bound |
429 | rate limited; Retry-After names the wait |
502 | a check failed; never reported as a pass |
503 | a read faulted; never an empty 200 |