access-engine/docs/application-access-readback.md

Application access readback

Status: proposed, for review with user-engine Date: 2026-10-09 Workplan: FLEX-WP-0035-T01 Decision: FLEX-DEC-2026-019 Consumer: user-engine (USER-WP-0026-T03, USER-WP-0028-T02)

user-engine wants to show a signed-in person which applications they can use. This document defines what access-engine answers to that request, what the answer means, and what it must never be used for.

1. Constraints from the current runtime

1. One pin evaluates one consumer. Each flex-auth-<consumer> Deployment loads one --registry snapshot and one --policy package. The flex-auth-user-engine pin holds no rules for any other application. It cannot answer for them, and widening it to do so would mix packages.
2. Caller auth is per system. /v1/batch_check authorizes the caller token against every resource.system in the batch. A caller bound to user-engine gets 403 for any other system. That is correct, and it stays.
3. There is no common action. Each package has its own action vocabulary. "May use the application" has no meaning until a package says what it means.
4. Registry content is not in decision provenance until G1 (FLEX-WP-0019). Under the 2026-08-19 boundary, anything that decides an allow belongs in a versioned policy package, not in the registry.
5. No key-cape client binding exists in protected_system_manifest.

2. The readback action: application.access, opted into per package

A system takes part in the readback by declaring the action application.access in its own policy package and giving it rules there.

• The rules are the system's own. They are reviewed, versioned and tested like any other action, and the decision records policy_package_digest.
• A system whose package does not declare the action answers not_applicable. user-engine renders that as unavailable.
• No registry-level mapping. Mapping "application access" onto an existing action in the registry was considered and rejected. Under constraint 4 it would let content outside provenance decide an allow.

application.access means: this subject, holding these claims, may begin to use the application. It grants nothing inside the application. Every action the application performs is still checked by that application's PEP against its own pin.

3. The answer is advisory and cannot be transferred

A readback decision is a real flex-auth decision. It is evaluated, recorded and attributable, but it cannot be accepted as an enforcement decision by any PEP:

• The binding carries purpose: "readback". The field is part of the hashed request, so request_digest and submitted_request_digest can never equal those of an enforcement request for the same subject and resource. Under §6.4.2 a PEP's digest comparison therefore fails.
• The readback route evaluates only application.access. Any other action is refused with 400 before evaluation. The readback surface cannot produce a decision about a real operation.
• The decision is evaluated over the claims that user-engine presents for the signed-in person, taken from its key-cape session. It is only as current as those claims. The target application's PEP receives its own claims on its own path.

4. Where it runs: a dedicated readback pin

The readback runs on a dedicated pin, flex-auth-application-readback. It loads the participating systems' packages at the same package digests their own pins run, plus a merged registry snapshot.

• Drift control: each decision states the policy_package_digest of the package it used. A test compares every package digest in the readback pin's values against that consumer's own pin values, and fails on any mismatch.
• The only admitted caller is a readback binding (T02), for example application-readback=system:serviceaccount:user-engine:user-engine. That binding authorizes the readback route only. It never authorizes /v1/check or /v1/batch_check on any pin.
• Rejected alternative: fan out from user-engine, or from a readback service, to each consumer pin. That needs a caller binding and an ingress rule on every consumer pin, which is exactly the widening constraint 2 forbids. It also makes per-page latency the sum of N pins.

Code needed: serve today takes one --policy. The readback pin needs a multi-package mode keyed by resource.system, restricted to application.access.

5. Request and response

POST /v1/readback/application_access

{
  "subject": {"issuer": "https://key-cape…/realms/…", "sub": "…", "type": "user"},
  "context": {"groups": ["…"], "acr": "…", "amr": ["pwd", "otp"], "auth_time": 0},
  "systems": ["informed-decision", "markitect"]
}

Response, one entry per requested system and in request order:

{
  "registry_snapshot_digest": "sha256:…",
  "results": [
    {
      "system": "informed-decision",
      "effect": "allow",
      "decision_id": "decision:…",
      "lifetime": {"expires_at": "…"},
      "revocation_visibility": {
        "claims": "immediate",
        "registry": "reload_or_lifetime",
        "policy_package": "reload_or_lifetime",
        "directory": "next_check"
      },
      "policy_package": "informed-decision.lifecycle",
      "policy_package_digest": "sha256:…"
    },
    {"system": "markitect", "effect": "not_applicable", "reason": "no application.access rule"}
  ]
}

• effect is one of allow, deny, not_applicable. A system the pin does not know answers not_applicable; it is never omitted. A whole-request failure is a non-2xx response, and user-engine renders every row unavailable.
• revocation_visibility restates per input class the deadlines published in docs/decision-input-freshness.md. It contains nothing new. The readback commits to no more than §9.7 already does.
• user-engine must not display an allow past lifetime.expires_at, and must re-read rather than extend.

6. Records

Readback decisions are recorded like any decision. They form their own event class, readback, declared in cadence.yaml as not load-bearing: a readback allow authorizes nothing. Under FLEX-DEC-2026-018, a failed commit still withholds an allow (503, rendered unavailable) and still releases deny/not_applicable.

7. Registry projection (T03)

GET /v1/readback/systems

The response lists every system in the merged snapshot: id, name, client_binding ({issuer, client_id} or absent), readback (whether its package declares application.access), and the registry_snapshot_digest.

This needs one new optional field on protected_system_manifest: client_binding. A system without one is still listed, and user-engine's rule then excludes it from the workload catalogue. The projection authorizes nothing. It describes what the readback pin knows.

8. Grants

Grants and revocations stay inside access-engine, in packages and registry content under their normal review. This work gives user-domain admins no grant or revoke surface.

9. Open questions for user-engine review

1. Claim set. Is forwarding the session's verified claims (groups, acr, amr, auth_time) acceptable to you? Or do you want the readback to resolve groups itself? Resolving them itself would add a directory dependency.
2. First participants. The proposal is informed-decision first: a human-facing web app with KeyCape AAL2 rules already in its packages. Which applications do you need in your first release?
3. Batch size. The ceiling is 64 systems per request. Is that enough?
4. Record volume. Each page view produces N decision records. If that is too much, the alternative is a shorter TTL plus client-side reuse up to expires_at, not unrecorded decisions.