CAAB runtime and security reference

Compiled policy format

A subject has one compiled policy document containing one entry per assigned capability. Operation snapshots preserve the method, path, input schema, response schema, upstream URL template, auth profile reference, and response rules that were reviewed at assignment time.

1{
2  "schema_version": "caab-user-policy-v1",
3  "policy_version": "2026-07-31T18:00:00Z",
4  "subject": {
5    "subject_id": "agent-order-support",
6    "subject_type": "agent",
7    "display_name": "Order Support Agent"
8  },
9  "expires_at": "2026-08-31T23:59:59Z",
10  "revoked_at": null,
11  "apis": [{
12    "capability_id": "acme-orders-a1b2c3d4",
13    "allowed_permission_ids": [
14      "acme-orders-a1b2c3d4:get:/orders/{orderId}"
15    ],
16    "auth_profile_ref": "auth-profile:acme-orders-a1b2c3d4:production",
17    "operations": ["<immutable operation snapshot>"],
18    "response_redactions": {
19      "acme-orders-a1b2c3d4:get:/orders/{orderId}": [
20        { "path": "/customer/email", "mode": "mask", "keep_last": 4 }
21      ]
22    }
23  }]
24}

External-subject v2 signed context

A headless external subject uses caab-user-policy-v2 and platform_service_v2. Its signed content binds the authorization artifact to independently derived tenant and identity context rather than caller-provided subject data.

1{
2  "schema_version": "caab-user-policy-v2",
3  "crypto_version": "platform_service_v2",
4  "subject_id": "caab-subject-7f31",
5  "caab_partner_id": "caab-partner-donorops",
6  "binding_id": "bnd_01JZ",
7  "issuer_hash": "sha256:<issuer-hash>",
8  "external_subject_hash": "sha256:<subject-hash>",
9  "mapping_version": "7",
10  "policy_version": "2026-08-01T18:00:00Z",
11  "policy_hash": "sha256:<policy-hash>",
12  "expires_at": "2026-08-31T23:59:59Z",
13  "revoked_at": null
14}

CAAB canonicalizes JSON with sorted keys and compact separators before hashing and protection. The public policy record includes the hash, versions, allowlist, expiry/revocation state, and an encrypted_present indicator; it does not expose the encrypted blob or secret credentials.

Crittora Secure policy protection

1. CAAB validates the policy shape, permission IDs, response rules, and auth-profile reference.

2. The canonical policy string is sent to the Crittora Secure Managed API at /sign-encrypt.

3. Legacy subject_credentials_v1 retains its existing per-subject credential and recipient behavior.

4. platform_service_v2 uses the CAAB-owned per-environment service identity and intentionally omits the optional recipient permissions list. The authenticated app client's Crittora Secure partner is the recipient.

5. Only the encrypted result is persisted as the enforceable policy artifact.

6. At runtime, CAAB loads the subject's artifact and calls /decrypt-verify. A missing payload, invalid signature, or v2 context mismatch stops authorization before downstream secrets are loaded.

Runtime invocation choices

CAAB exposes several runtime paths. Choose the path by what the caller needs to prove and whether CAAB should execute the downstream operation.

Common invocation outcomes

1// allow
2{
3  "status": "allowed",
4  "permissionId": "orders-api:get:/orders/{orderId}",
5  "requestId": "req_123"
6}
7
8// deny
9{
10  "status": "denied",
11  "reason": "operation_not_allowed",
12  "requestId": "req_124"
13}
14
15// missing policy
16{
17  "status": "denied",
18  "reason": "missing_policy",
19  "requestId": "req_125"
20}
21
22// policy expired
23{
24  "status": "denied",
25  "reason": "policy_expired",
26  "requestId": "req_126"
27}
28
29// user assertion rejected
30{
31  "message": "End-user assertion rejected",
32  "error": "invalid_user_assertion",
33  "requestId": "req_127"
34}

Authorization decision path

1POST /v1/authorize-invocation
2Authorization: Bearer <token>
3Content-Type: application/json
4
5{
6  "subject": { "subject_id": "agent-order-support" },
7  "capability_id": "acme-orders-a1b2c3d4",
8  "method": "GET",
9  "path": "/orders/{orderId}"
10}

1. Require an authenticated subject and capability context.

2. Resolve the partner-scoped capability and load the subject's encrypted policy.

3. Decrypt and verify the signature, select the v1 or v2 validation path, and ensure the verified policy subject matches independently derived request context.

4. Deny revoked or expired policy.

5. Map the requested method and normalized path to a catalog permission ID.

6. Return allow only when that exact permission ID is present for the capability. Record the decision either way.

Headless Partner API decision path

1POST /v1/bindings/bnd_01JZ/invoke
2Authorization: Bearer <binding-scoped-workload-access-token>
3X-CAAB-User-Assertion: <partner-issued-user-access-token>
4Idempotency-Key: <unique-request-key>
5Content-Type: application/json

1. Reject a revoked or unknown workload client before evaluating route scope.

2. Require the route binding to match the workload client's server-side CAAB partner and binding mapping.

3. Validate the partner-issued access token's asymmetric signature, algorithm, kid, issuer, audience, time claims, tenant claim, token_use=access, and immutable subject.

4. Derive the CAAB subject from binding, issuer, and external subject; never accept a caller-selected CAAB subject ID.

5. Before decrypt, check the active connection, external mapping, subject, and boundary.

6. After decrypt/verify, compare signed subject, CAAB partner, binding, issuer hash, external-subject hash, and mapping version with the derived request context.

7. Evaluate current authorization on every invocation, even when an MCP client caches its displayed tool list.

MCP tool discovery and execution

The hosted MCP runtime converts allowed operation snapshots into tools. Tool names are normalized and capped at 64 characters, with a short hash suffix derived from the permission ID to preserve uniqueness. Expired or revoked policies yield no dynamic tools.

Parameter constraints apply to REST and downstream MCP arguments. They are evaluated only from the verified operation snapshot; callers cannot supply or relax them. Missing required values, excluded values, invalid policy metadata, and unsafe evaluation all fail closed before secret loading or network activity.

This enforcement is rollout-controlled: the environment must enable parameter scoping and allowlist the policy owner partner. A constrained request outside that rollout fails closed; CAAB never silently ignores a signed constraint.

Audit, metering, and diagnostics

CAAB authority API surface

The portal uses the following authenticated route groups. They are an administrative integration surface, not a replacement for the Crittora Secure cryptographic API reference.

Secure operating guidance

• Use separate subjects and auth profiles across people, agents, environments, and privilege tiers.

• Grant narrowly designed operations; avoid broad endpoints that combine read, write, and administrative effects.

• Set policy expiry for temporary access and revoke immediately when a role, device, or integration is compromised.

• Keep Crittora and upstream credentials out of logs, OpenAPI examples, policy JSON, browser storage, and support artifacts.

• Keep the binding-scoped workload secret in a partner server secret manager and use overlapping clients for zero-downtime rotation.

• Treat persistent signature verification errors, unexpected tool visibility, OAuth failures, and diagnostic warnings as security-relevant incidents.

• Review allow/deny events and MCP audit records after every material policy or auth-profile change.