Expand description
Reference verifier for the CORE PCActn checks (wire format v2): wire, version, audience, validity,
capability chain, grant_ref binding, Merkle plan inclusion, strict Ed25519 leaf signature, counter. Byte-matches
@atlasauth/pca (the shared conformance corpus defines the normative rules).
Re-exports§
pub use serde_json;
Structs§
- Classifier
Decision - The rule-18 decision:
okand the class per classifier id, or the failure reason. - Conform
Result - The rule-14 conformance result (
conformAction):ok, else the violationcodeand, for a parameter, itspath. - Intent
Policy - Verifier-side intent policy (Intent Layer M2). ACTIVE iff
requireis true or either threshold isSome(even an invalid one); an active policy runs theintentcheck even for a PCActn without the slot and fails it closed. A set threshold that is not a non-negative safe integer is a misconfiguration and fails the check. - Intent
V2Check - One reported v2 check.
- Intent
V2Context - The verifier state the v2 checks read (
IntentV2Context):{policy?, params?, schema?: {docs, keys}, session?: {root, grants, revocation?}, layers?, wb?: {artifacts?, policy?}, acc?: {state?, monitors?, receipts?, last_seq?, sequencer_keys?}}. All of it is VERIFIER state (its store, its configuration), never the agent’s. It is kept as the JSON the host supplies and read strictly: an absent member is empty / default, a member that is JSONnullor of the wrong type is malformed and fails, closed, the check that owns it. - Intent
V2Decision - The v2 decision: the reported checks in pipeline order and the verifier-computed predicate
env(canonwhenschemapassed,acc/monwhenaccumulatorspassed,world/prov/classwhen W-B admits or asks). - Intent
WbResult - The W-B result (
decideIntentWB): reported checks in order facts, provenance, classes; the first failing one ends the unit. - Intent
World Decision - The rule-16 decision:
ok, the world map and the single-source worlds (policy order), or the failure reason. - MapDecision
- The rule-19 Z0 decision:
ok, and when ok the action’s cell indices and itsp_ppm. - Provenance
Decision - The rule-17 decision:
outcome(pass|question|deny), the friction of a question, the label per classified path, the data classes per parameter andenv.prov. - Verdict
- Verdict for the core checks.
checks[name]is true when it passed. A wire failure is terminal and is the ONLY entry ({wire: false}); otherwise all of wire, version, audience, validity, chain, plan_inclusion, leaf_signature, counter are present. - Verify
Options - Optional verifier policies of
verify_pcactn_core_with(VerifyOptions::default()==verify_pcactn_core).
Enums§
- PcaHeader
Error - Why
decode_pca_headerrefused aPCA-Actionheader value. - WbCheck
- One W-B check verdict.
Constants§
- ARTIFACT_
SIZE_ REASON - Shared reason string for the raw-size cap (identical across all PCA verifiers).
- CAVEAT_
LIMIT_ REASON - Shared reason string for the caveat caps (identical across all PCA verifiers).
- DEFAULT_
MAX_ KEYSET_ AGE_ MS - Default
policy.acc.max_keyset_age_s(ms). - DEFAULT_
MAX_ RECEIPT_ AGE_ MS - Default
policy.acc.max_receipt_age_s(ms). - MAP_
FORM_ COMMIT - The only
intent_session.map_form(rule 19:intent.map_digestis the salted map commitment, the goalv2c). - MAX_
ARTIFACT_ BYTES - Shared raw wire-size cap of a PCActn JSON document (UTF-8 bytes), checked before any parsing.
- MAX_
CAVEATS_ PER_ CHAIN - MAX_
CAVEATS_ PER_ HOP - Shared hard caveat caps (all PCA verifiers): per-hop cumulative list, and the sum over every hop of a chain.
- MAX_
CHAIN_ DEPTH - MAX_
DECIMAL_ DIGITS - MAX_
INTENT_ GOAL_ SALT_ LEN - UTF-8 byte cap of
intent.goal_salt. - MAX_
JSON_ CHARS - MAX_
JSON_ DEPTH - MAX_
LIFETIME_ MS - MAX_
RECEIPT_ LIFETIME_ MS - A receipt lives at most this long:
issued_at <= expires_at <= issued_at + MAX_RECEIPT_LIFETIME_MS(15 min). - MAX_
SESSION_ SEQ - Largest delta sequence number (2^31 - 1).
- MAX_
SKEW_ MS - ML_
DSA_ 65_ PUBLIC_ KEY_ BYTES - ML-DSA-65 (FIPS-204, category 3) encoded sizes, in bytes.
- ML_
DSA_ 65_ SIGNATURE_ BYTES - PCACTN_
WIRE_ VERSION - Wire format version this verifier accepts.
- RECEIPT_
SKEW_ MS - Allowed clock skew between a receipt’s
issued_atand the verifier’s clock. - REGISTERED_
SUITES - The closed TS suite registry (
SIG_SUITESin packages/pca/src/pq.ts), in registry order. - UNSUPPORTED_
SUITE_ REASON - The reason token of a REGISTERED suite this verifier does not implement (the full reason is
unsupported_suite: <alg>).
Functions§
- acc_
receipt_ digest accReceiptDigest(r)= b64u(sha256(strictCanonical({d: “atlas-pca/acc-receipt-ref/v1”, r}))).- action_
schema_ digest actionSchemaDigest(doc)= b64u(sha256(strictCanonical({d: “atlas-pca/action-schema-ref/v1”, s: doc})));Nonewhere the reference throws (an out-of-profile document).- action_
schema_ shape_ error actionSchemaShapeError(doc)of a SIGNED document.None= well-formed.- canonicalize
- LENIENT canonical JSON (capability content addressing, Merkle leaves): keys sorted BYTEWISE over UTF-8,
compact, escape only
"\and < U+0020, shortest round-trip numbers,-0->0. - canonicalize_
strict - STRICT canonical form of a signed PCActn body (wire v2): as
canonicalizeplus integer-valued numbers must be safe integers (no-0), non-integers plain decimal <= 15 significant digits and >= 1e-6, and nesting depth <= 32. Errs on any violation. - cap_
hash - Hash of the full capability, including its signature.
- caveat_
limit_ exceeded - True when the chain breaks the caveat caps; reads raw list sizes only, so it runs before any hashing/signature work.
- check_
session_ revocation checkSessionRevocation({epoch, revoked}, {session, authority, ids, now, maxAgeMs, pin, scope?, last?})(NORMATIVE, rule 13 step 7), first failure wins: a. the max age a non-negative safe integer, the clock a safe integer; b. the evidence an object, the epoch strictly shaped,epoch.guardian == authority(only the dedicated authority); c. the epoch verifies under the authority (a PQ suite only underauthority_pq_pk), scope,now <= not_after,issued_at <= now + 60 s; d.now - issued_at <= max_age_ms; e.revokedis the full signed set (revset_root); f. append-only againstlast(well-formed by b’s shape and e): no rollback, no dropped id, no equivocation; g. no id ofidsis revoked.- conform_
action conformAction(doc, verb, params)(NORMATIVE, rule 14 step 5). First failure wins: params not an object; unknown verb; an undeclared key (UTF-8 byte order); then every declared path in UTF-8 byte order: missing and required, else the value check.- decide_
classifier_ dimensions - The rule-18 decision on the reference’s
ClassifierInput(decideClassifierDimensions). Never panics. - decide_
intent_ v2 - Run the v2 checks on a wire-valid PCActn (
decideIntentV2). Never panics: an internal error fails the check being evaluated. A malformed verifier context (intent_v2_context_error) fails every v2 check that could be reported (schema,intent_session, andaccumulatorswhen the PCActn carriesintent_session); a clock that is not a safe integer fails every reported check. - decide_
intent_ wb decideIntentWB(input): rules 16, 17 and 18 in order on the reference’sIntentWBInput. Never panics.- decide_
intent_ world - The rule-16 decision on the reference’s
IntentWorldInput(decideIntentWorld). Never panics. - decide_
map_ disclosure decideMapDisclosure({mapCommit, action: {verb, resource, params_digest}, params, disclosure, maxResidualRiskPpm})(NORMATIVE, rule 19 steps 1-8).paramsabsent ={}; never panics.- decide_
param_ provenance - The rule-17 decision on the reference’s
ProvenanceInput(decideParamProvenance). Never panics. - decide_
read_ purpose decideReadPurposeon{fields: [{path, class, optional?}], purpose, coverage: {purpose: [pattern]}, on_uncovered?}. Malformed input (JSONnullanywhere included) isdenywith empty lists;coverage[purpose]is an own member; a field is covered when its class ispublicor matches a pattern (a class,p.*,*). Never panics.- decode_
b64u_ strict - STRICT base64url (RFC 4648 section 5, no padding): only
[A-Za-z0-9_-], no whitespace,len % 4 != 1, zero trailing bits (re-encoding must reproduce the input). Whenlenis given the DECODED length must equal it. ReturnsNoneon ANY deviation. - decode_
pca_ header - Decode a
PCA-Actionheader value to the encoded PCActn JSON text (pass it tostrict_parse). - delta_
revocation_ id "pca-intent:delta:" + grant id.- evaluate_
caveats - Evaluate a caveat list against a policy context;
(ok, failed)whereokiff every caveat is satisfied andfailedlists the unsatisfied caveats’type("<malformed>"when it is not a string) in order. A non-array list is(false, ["<malformed caveats>"]). Total: never panics. - hash_
canonical - base64url-nopad(sha256(canonical(v))) (lenient canonical form). Content addressing only: the verifiers never
use it for a protocol digest (see
hash_canonical_strict). - hash_
canonical_ strict - base64url-nopad(sha256(STRICT canonical(v))), like the reference
hashCanonical(hash.tscanonicalBytesiscanonicalizeStrict): depth <=MAX_JSON_DEPTH, safe integers only, plain-decimal non-integers.Noneon an out-of-profile value. Every protocol digest the verifiers compute (capability / grant hash, hop body digest, caveat comparison, Merkle leaf) goes through it: a lenient digest would accept a correctly signed out-of-profile hop that the reference refuses, and would recurse without bound on a deep caller-built value. - intent_
goal_ commit - The goal commitment a root grant minted for this IntentStatement and Intent Map carries:
hash_canonical_strict({d: "atlas-pca/goal/v1\0", goal: "pca-intent:v1:" + ref + ":" + map_digest, salt}). - intent_
goal_ commit_ v2 - The goal commitment of an Intent Layer v2 session grant (rule 13 amends rule 12 step 2):
hash_canonical_strict({d: "atlas-pca/goal/v1\0", goal: "pca-intent:v2:" + session + ":" + map_digest, salt}). - intent_
goal_ commit_ v2c - The goal commitment of a session grant over a COMMITTED map (rule 19 amends rule 12 step 2):
hash_canonical_strict({d: "atlas-pca/goal/v1\0", goal: "pca-intent:v2c:" + session + ":" + map_commit, salt}). - intent_
session_ caveat_ error intentSessionCaveatError(c): exactly{type: "intent_session", session, seq, root, prev?},prevpresent iffseq > 0.None= well-formed.- intent_
v2_ active - True iff any v2 check would be reported (the PCActn carries
intent_session, a v2 policy flag is set, or the context is malformed and the checks fail closed). - intent_
v2_ context_ error - The whole v2 context (
intentV2ContextError): an ABSENT member is empty / default; a member PRESENT with JSONnullor of the wrong JSON type is malformed. Covers the policy (and its members), params, schema, session, acc, thelayersceilings (each{predicates: [...]}) and the W-B members passed through. - intent_
wb_ active - Which W-B checks a verifier reports (
intentWBActive,primitives.intent_wb_active) for{intent_session, policy: {world?, provenance?, classifiers?}}:(facts, provenance, classes). - map_
commit_ of_ leaves primitives.intent_map_commit: the commitment of a full leaf list[{kind, salt, leaf}](in leaf order).Nonewhen an entry is malformed (not exactly{kind, salt, leaf}, unknown kind, salt not 32 bytes, an out-of-profile leaf) or the list is empty.- map_
revocation_ id "pca-intent:map:" + map_digest.- merkle_
root - RFC-6962-shaped Merkle root (split at the largest power of two < n).
- params_
digest - hashCanonical(params ?? {}).
- pcactn_
reservation_ digest pcactnReservationDigest(p): b64u(sha256(strictCanonical({d: “atlas-pca/acc-reserve/v1”, b: <PCActn without sig, pq_sig, threshold, intent_session>}))).Nonewhere the reference throws.- policy_
caveats - Every caveat the policy layer evaluates for an action under
grantdelegated alongchain(root first): the grant’s caveats with its FIRSTenvelopecaveat removed (order kept; that one is the policy container read separately), then the caveats the hops appended (leaf.caveatsbeyond the grant’s, leaf = the last chain element). Nothing is appended whenchainis not a non-empty array or either caveat list is not an array. A non-array grant list is returned as is (Nullwhen absent), andevaluate_caveatsrefuses it (fail closed). Total. - profile_
revocation_ id "pca-intent:profile:" + profile + "@" + version.- revocation_
epoch_ shape_ error - Strict shape of a revocation epoch as rule 13 consumes it (
revocationEpochShapeError): every number a non-negative safe integer, every string a string, an optional member absent or of its type (nullis malformed), and thealga suite the dispatch implements (unsupported_suiteotherwise). - revset_
root revset_root(L)= b64u(sha256(“pca-revset/v1\0” || strictCanonical({size: |L|, tree}))),treethe RFC-6962-shaped Merkle root over the ids in order (leafSHA-256(0x00 || canonical(id))), b64u(sha256(“”)) for the empty list.- sequencer_
key_ set_ digest - A key set’s content address (
sequencerKeySetDigest): b64u(sha256(strictCanonical({“d”: “atlas-pca/sequencer-keys-ref/v1”, “k”: set}))) over the whole set, signatures included. - session_
revocation_ id "pca-intent:session:" + session.- session_
revocation_ scope - The
grant_refof a session revocation epoch:"pca-intent-session:" + session. - session_
root_ digest sessionRootDigest(S)= b64u(sha256(strictCanonical({d: “atlas-pca/intent-session-ref/v1”, s: S}))).- session_
root_ shape_ error sessionRootShapeError(S)of a signed root.None= well-formed.- signer_
set_ hash_ b64u - The signer-set hash as base64url:
Noneon a set with a non-object entry or a non-string role / publicKey. - strict_
parse - STRICT JSON profile for signed bytes (README section 2): hand-written RFC 8259 parser rejecting comments, trailing commas, a BOM, non-JSON whitespace, duplicate keys (post-unescape), lone surrogates (raw or escaped), raw control chars in strings, unknown escapes, nesting > 32, input > 2^20 UTF-8 bytes, and any number not in the canonical wire form. Returns any JSON value (the PCActn check requires an object).
- strict_
parse_ envelope - R6-01:
strict_parsefor an untrusted transport envelope that WRAPS a PCActn one level deep (the middleware body{"pcactn": ...}): the same strict profile (duplicate keys refused at ANY depth, strict numbers, no lone surrogates, size cap) with the depth capMAX_JSON_DEPTHapplied to the WHOLE envelope, as the reference does (require-pca.tsdefaultExtractstrict-parses the body text): the wrapped PCActn therefore gets one level less than in header mode. - supported_
suites - The capability manifest: the registered suites this crate implements, in registry order.
- threshold_
message - SIG_DOMAIN || sha256(strictCanonical(pcactn without
sig,threshold,pq_sig)). - validate_
intent_ session_ wire - Wire validation of the PCActn member
intent_session(rule 13; part of the terminalwirecheck). - validate_
wire - Validate the wire form (README section 1/3/5): closed field sets, presence, JSON types, safe integers,
canonical fixed-length base64url, and that the whole signed body admits the strict canonical encoding.
Ok(())when well-formed, else a short reason. - verify_
action_ schema verifyActionSchema(doc, keys): shape,sig.kidnames a listed discovery key,sig.algequals THAT KEY’s suite, and the signature verifies (a PQ key only as pinned by the key entry). Never panics.- verify_
artifact_ suite - Verify a signed artifact (
alg/sig/pq_pk/pq_sig,algabsent = ed25519) overmsgunder its suite: the wire shape per suite, then the ONE suite dispatch with the Ed25519 half undered_puband the PQ half under the artifact’s OWNpq_pk(CALLER-VOUCHED: only for keys the caller authorised elsewhere, e.g. thepq_artifactconformance primitives). False for an unsupported / unknown suite or any failure. Total. - verify_
chain - Mirrors verifyChain in capability.ts.
Ok(())when valid, elseErr(reason). The 16-hop cap is enforced before any signature work. - verify_
chain_ policy verify_chainwith an optional allowed-suites policy (None= none;Some(&[])refuses every suite) and the verifier-side PQ authority for a non-ed25519 ROOT (R4-01):pq_pinsmaps the root issuer (Ed25519, base64url) to its ML-DSA public key (a pin that differs from the root’spq_pkis a refusal);trusted_rootis the verifier’s own stored root capability (accepted when its content hash equals the presented root’s). Ed25519 roots need neither.- verify_
inclusion - Never panics; malformed proofs return false.
index/sizeare bound to the path shape (size >= 1,0 <= index < size, path length and every side recomputed from them). - verify_
pcactn_ core - Checks, in the normative order: wire (terminal), version, audience, validity, chain, plan_inclusion,
leaf_signature, counter (then
intentwhen the PCActn carries it).nowis epoch milliseconds;audienceis this verifier’s own audience id. Later-milestone checks (attestation, threshold, revocation, …) are out of scope. - verify_
pcactn_ core_ policy verify_pcactn_corewith an optional allowed-suites policy (None= none;Some(&[])refuses every hop and leaf suite; absentalg== “ed25519”). Hybrid / pure-PQ keys are always required to be bound to the signer’sholder_pq(no unbound escape hatch).- verify_
pcactn_ core_ with verify_pcactn_corewith explicitVerifyOptions. Theintentcheck runs aftercounterand is reported iff the PCActn carriesintentoropts.intentis active; otherwise the verdict is the pre-M2 one.- verify_
pcactn_ json - Verify a RAW PCActn text: strict-parse it first (a parse failure is a
wirefailure), thenverify_pcactn_core. - verify_
pcactn_ json_ policy verify_pcactn_jsonwith an optional allowed-suites policy.- verify_
pcactn_ json_ with verify_pcactn_jsonwith explicitVerifyOptions.- verify_
session_ root verifySessionRoot(S)with NO verifier pins: an Ed25519 root verifies as before; a pure-PQ / hybrid root fails closed (seeverify_session_root_pinned).- verify_
session_ root_ pinned verifySessionRoot(S, {pqPins}): shape, signer listed, suite signature over"atlas-pca/intent-session/v1\0" || strictCanonical(body + signer + bound suite fields). R3-01 (fail closed): a non-ed25519 root verifies only under the VERIFIER’s pin for its signer (pq_pins= contextsession.pq_pins, an object whose own member for the signer is a string), never under the root’s ownprincipals[].pq_pk; the signer’s own entry, when it declares apq_pk, must agree. An Ed25519 root never consults the pins.- verify_
threshold_ share - Verify a single threshold share under the v2.1 agent-leaf share binding. FAIL-CLOSED: returns
falseon any malformed input (never panics). The share signature MUST verify over the bound message"atlas-pca/share/<role>\0" || sha256(thresholdMessage) || signerSetHash || t(1 byte)undershare.publicKey(orshare.pq_pkpershare.alg, routed through the same suite seam as the leaf). Consequently the PRE-v2.1 bare agent share (asigover the bare threshold message) and a cross-signer-set replay (a share bound to a DIFFERENT signer set) both fail — the clean break the v2.1 binding mandates.entryis a{ role, t, signer_set, threshold_message, share{publicKey, sig, alg?, pq_pk?, pq_sig?} }object (theprimitives.threshold_share[]shape).