This specification defines a library for exposing data and tools as typed capabilities, resolving policy into authorized views, allowing agents to compose presentation, and enforcing the final action at the execution boundary.
Draft standard · reference implementation: TypeScript
CUP is the authorization and presentation contract between applications and agents. It makes available actions explicit without prescribing one visual language.
A data object, collection, file, tool, workflow, view, model, agent, or identity.
A person, agent, service, group, or organization. A delegated agent remains distinct from its delegator.
A named operation with inputs, outputs, side effects, risk, and required policy.
An allow or deny rule connecting a principal, operation, resource, scope, and conditions.
The subset of resources, fields, and actions that may be disclosed to a consumer.
An append-only record of authorization, confirmation, execution, and outcome.
All identifiers are namespaced strings. Resource schemas use JSON Schema 2020-12 or a compatible typed schema. Unknown fields are rejected by default.
A tool is a resource whose operation is usually execute. Its schema can be inspectable even when invocation is denied. A data resource can expose read capabilities and mutation capabilities separately.
| Permission | Discloses | Does not imply |
|---|---|---|
| discover | That a resource exists | Schema, contents, or use |
| inspect | Metadata, schema, risk, side effects | Contents or execution |
| read | Contents, subject to field filters | Mutation or sharing |
| execute | Invocation of a named capability | Access to implementation data |
| share | Permission to grant access onward | Permission to use the resource personally |
Policies are declarative. The reference evaluator is deterministic, side-effect free, and usable without an agent or network call.
subjectIs, roleIs, ownerIsSubject, resourceInWorkspace, fieldsWithin
purposeIs, approvalPresent, timeBetween, deviceTrustAtLeast, mfaRecent
recipientCountAtMost, amountAtMost, domainIs, queryContainsNoSecrets
requireConfirmation, previewChanges, redactFields, writeReceipt, requireHumanReview
The evaluator must return the same result for the same policy set, request, and context. A deny result is the default.
The library is split into pure core contracts and adapters. A host application can use only the parts it needs.
register(resource) · get(id,version) · listDiscoverable(request) · validate(id,input)
authorize(request) · explain(request) · policyVersion() · invalidate(cacheKey)
project(request) · redact(resource,decision) · buildActionSchema(capability)
prepare(request) · confirm(token) · execute(request) · reverse(receiptId)
The projector converts policy decisions into an agent-safe document. It includes only what the consumer may see and do.
Field filters are applied after authorization and before projection. A caller may read a contact record while receiving only name and organization. Redaction must be structural, not a string replacement that can leak through derived fields.
| Projection state | Agent receives | Renderer may show |
|---|---|---|
| Hidden | Nothing | Nothing |
| Listed | Stable ref and safe label | Existence and label |
| Inspectable | Schema, risk, side effects | Form structure and warnings |
| Readable | Filtered contents | Authorized fields |
| Usable | Short-lived action token | Action control with obligations |
Execution is a separate protocol from projection. The executor trusts neither a UI event nor an agent-produced payload.
Validate capability ID, input schema, subject, purpose, current resource version, and action-token audience.
For an explicit obligation, show the normalized action and side effects. Bind confirmation to the exact input hash.
Re-authorize immediately before calling the adapter. Enforce scope and input constraints again.
Record policy version, input hash, confirmation, result, actor, and reversal reference.
Use idempotency keys for capabilities that can create duplicate external effects.
Expose a separate reversal capability. Reversibility is never inferred from the original operation.
Boundary rule: agents and renderers are untrusted consumers of projections. External adapters are trusted only to perform the operation that the executor has already authorized.
Adapters isolate vendor and framework choices from the protocol.
Resolves authenticated subjects and attributes. It cannot grant resource permissions.
Loads current resource metadata, versions, schemas, and data. It applies ownership rules supplied by the host.
Evaluates requests locally or through OPA, Cedar, a database, or a custom evaluator.
Executes a named operation after the executor has authorized it. It receives normalized input only.
Converts authorized schemas into React, Web Components, native controls, voice prompts, or other presentation.
Writes receipts to an append-only store and supports lookup by request, actor, resource, and capability.
An implementation is CUP-conformant only when it passes semantic tests. Matching method names is insufficient.
TypeScript types, pure evaluator, JSON Schema validation, projections, action tokens, receipts, and conformance fixtures.
PostgreSQL resource adapter, OPA or Cedar bridge, React renderer contract, Web Components renderer, and policy simulator.
Delegation chains, capability attenuation, organization policy, approval workflows, and cross-service receipts.
| Question | Current proposal | Evidence needed |
|---|---|---|
| Policy language | Typed builder API plus portable JSON representation | Interoperability tests across evaluators |
| Action tokens | Opaque, short-lived, audience-bound tokens | Operational latency and revocation requirements |
| Policy conflict | Deny-overrides with explicit priority | Enterprise policy authoring studies |
| UI contract | AuthorizedView independent of visual framework | React, native, voice, and accessibility implementations |
| Receipt storage | Append-only sink owned by host application | Audit, privacy, retention, and redaction requirements |