approval-engine/docs/access-claim-fact-reader.md

# Thin Access Approval fact reader — owner source contract proposal

Owner scope: Approval Engine / PIP. Work: APPROVAL-WP-0005-T01, selected source
subset of APPROVAL-WP-0002-T01/T05 under CUST-WP-0080. This interprets the existing
claim schema 0.1, not a new API/schema/signature or policy grant. Access's B2
implementation stays DENY until its separately reviewed complete successor.

## Authoritative source and guarantee

Only server-installed, independently admitted provider origin and transport may
GET `/v1/approvals/{id}/claim`, with least-scope `approval:read` credential and
exact admitted store tenant. No caller URL/opener/key/verified flag, redirects,
environment proxy, caller JSON or public same-channel key bootstrap can supply
this provenance. Owner transport must enforce total deadline/size, exact 200
application/json UTF-8, no encoding, duplicate-key/nonfinite/malformed JSON
refusal, no retry and bounded errors without bearer/body leakage. Provider
unavailability refuses this source join. Never invoke a credential-carrying
Python subprocess as the Go adapter; reuse Go's existing transport boundary.

At the provider observation, `valid_now: true` AND `binding.human_control: true`
means the configured required count of distinct entries is met and every entry
has verified `principal_type=human`. `/entries` obtains identities/types only from
its authenticator, rejects non-human binds for this declaration, and persists
UNIQUE(approval_id, subject_id); `_evaluate` repeats the threshold/human check.
It does NOT mean required_count is two, requester/actor/principal is human,
directory-derived tenant membership, a particular MFA/assurance level, policy
eligibility, uncompromised source, native issuer admission, or continuing
validity after the observation. Consumer trusts this owner evaluation instead
of fetching identities/counting approvers or revalidating human JWTs. Native
issuer/profile acceptance is still T01, not established by synthetic vectors.

## Minimal typed fact validation

The submitted claim and fetched observation must each satisfy existing schema
0.1 with exact JSON types; `human_control` must be present and exactly true on
this lane despite being historically optional in the generic schema. Require
schema_version=0.1, kind=approval-claim, issuer=approval-engine, exact expected
approval UUID, state=valid, valid_now=true, consumed=false, reason_code=ok,
pdp_path=true and non-null lowercase sha256 pdp_digest. Reject decision-shaped
keys and unknown schema members (except optional informational yields_to).
The signed/requesting service must never become a human approver by inference.

At one captured UTC validation instant now, require zoned RFC3339 timestamps,
positive integral ttl_seconds, observed_at<=now<not_after and
not_after=observed_at+ttl_seconds. Require not_before<=now<expires_at. Do not
invent skew or extend TTL; a separately admitted clock policy is needed to
relax the zero-skew default. The provider default TTL is 30 seconds but source
configuration may differ; an Access-owned maximum may only shorten it.

Compare exact five-field act against the owner-derived normalized proposed act,
including all nested target values; no action vocabulary translation is owned
here. Recompute native binding.digest from those five fields and require exact
served and expected digest correspondence. Match pdp_digest to Access's actual
ApprovalBindingDigest over the exact normalized original request (excludes only
top-level context.approval). Preserve execution_contract and all other context.
Never substitute full request_digest, native act digest or a guessed Go digest.
The PDP digest proves correspondence, not decision authenticity or approval
source authenticity. Registry/normalization changes must fail or reissue.

## Original request is immutable; fresh observation stays out-of-band

The original submitted context.approval must remain byte/value-equivalent under
Access's existing canonical request rules. Do not replace it, update freshness,
change binding/declarations, or manufacture an evaluated refreshed request.
Validate its own original freshness/validity too; a newly fetched observation
cannot rescue a stale original claim. Require all non-freshness authority facts
to match between the submitted and fetched claims: schema/kind/issuer/id,
state/valid_now/consumed/reason_code, binding and validity. Optional yields_to
is informational only. Each native binding is independently recomputed.
Freshness is validated separately on both observations; a later observation
may have a later freshness window without changing the signed request.

Return a package-private/server-created typed observation handle only after
these checks. Access may bind its source identity/revision, observed_at,
not_after, fetched-claim content digest and validation time into owner-produced
signed provenance separately from unchanged request_digest and
approval_binding_digest. This does not require changing the Approval schema;
Access owns the minimal existing provenance representation and signer contract.
An HTTP caller cannot instantiate this handle or set its verified state.

Suggested Go boundary, for Access to implement in its existing process:
`ApprovalFactSource.Observe(ctx, approvalID) (Observation, error)` reads only
provider bytes plus source provenance; a separate package-private validator
joins Observation with the immutable normalized request, submitted claim and
captured validation time. The handle retains detached raw provider bytes and
strict parsed numbers (json.Number), not caller-installable validation flags.
Neither this reader nor its validator evaluates policy. Access's existing
single policy evaluator consumes the verified factual handle without rewriting
the request. Callers may not supply a ready-made Observation on the HTTP body.

Effective input deadline is the minimum of ORIGINAL submitted freshness,
fetched freshness, approval expiry, authenticated caller expiry and operation/
decision deadlines. No equality at an expiry boundary is accepted. Refetching
does not renew the original full request. Revocation/use may race a read; the
PEP still performs one original exact consume CAS before effect and retains
the same live Platform journal admission, deadlines and unknown-outcome rules.
Access never consumes or executes. Historical confirm_consumption cannot
substitute for this fresh predecision source validation.

## Go canonicalization and golden vectors

`examples/access-claim-reader-vectors.json` contains producer-generated native
canonical UTF-8 bytes/digests and source lifecycle observations, plus explicitly
mutated refusal fixtures. Python dict equality and Go decoding numbers into
float64 lose authority distinctions: True/1, 1/1.0 and integers above 2^53 differ.
Go default json.Marshal additionally escapes HTML/U+2028 differently. Retain
number tokens with UseNumber and implement/test compatibility with Approval's
existing Python json.dumps(sort_keys=True,separators=(',', ':'),ensure_ascii=False)
format; do not silently normalize types or hash whole binding/freshness.
UseNumber preserves number tokens but is NOT a canonicalizer: producer parsing
of `1e-7` emits `1e-07`, `1e20` emits `1e+20`, `1.0` remains distinct from `1`,
and negative floating zero emits `-0.0`. A signed typed Go envelope alone does
not preserve or authenticate Python's original numeric representation.

These finite vectors are a minimum, not proof of a complete Python float/string
port. A thin pilot may fail closed on unsupported numeric/string domains only
if its actual owner-compiled operation contract excludes those values and Access
declares/tests that boundary. It may not silently change the global Approval
algorithm or accept a digest without checking the proposed act. Required vectors
cover bool/int/float distinction, large integer, Unicode/HTML/U+2028, reordered
keys, nested containers, exponent formatting and negative floating zero. These
are authoritative producer vectors for the domains shown, not arbitrary new
restrictions on current pilot metadata. No currently authoritative narrow numeric
restriction was established by this review, so it cannot be presumed. If a
small shared producer-owned Go canonicalization helper becomes necessary, scope
it explicitly to the actual consumer need and test against these producer bytes;
do not invent a second unverified serialization algorithm in the adapter. This
initial review provided vectors only. Subsequent scoped WP0005-T03 supplies
`adapters/go/approvalfact`, a producer-owned pure data implementation agreed with
Access; it adds no credential transport/runtime. The Go consumer owner must
return exact accepted/refused vector results and transport negatives
(redirect/proxy/duplicate/size/deadline).

The superseded service-http-join-proposal-r1 B3 refreshed-evaluation wording is
changes-requested for this immutable-context path. B2's source reader can proceed
against this proposal after Access's own design/conformance review. No foreign
owner assent, policy activation, live credential or native acceptance is implied.