Skip to main content

Crate atlas_pca

Crate atlas_pca 

Source
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§

ClassifierDecision
The rule-18 decision: ok and the class per classifier id, or the failure reason.
ConformResult
The rule-14 conformance result (conformAction): ok, else the violation code and, for a parameter, its path.
IntentPolicy
Verifier-side intent policy (Intent Layer M2). ACTIVE iff require is true or either threshold is Some (even an invalid one); an active policy runs the intent check 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.
IntentV2Check
One reported v2 check.
IntentV2Context
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 JSON null or of the wrong type is malformed and fails, closed, the check that owns it.
IntentV2Decision
The v2 decision: the reported checks in pipeline order and the verifier-computed predicate env (canon when schema passed, acc / mon when accumulators passed, world / prov / class when W-B admits or asks).
IntentWbResult
The W-B result (decideIntentWB): reported checks in order facts, provenance, classes; the first failing one ends the unit.
IntentWorldDecision
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 its p_ppm.
ProvenanceDecision
The rule-17 decision: outcome (pass | question | deny), the friction of a question, the label per classified path, the data classes per parameter and env.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.
VerifyOptions
Optional verifier policies of verify_pcactn_core_with (VerifyOptions::default() == verify_pcactn_core).

Enums§

PcaHeaderError
Why decode_pca_header refused a PCA-Action header 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_digest is the salted map commitment, the goal v2c).
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_at and the verifier’s clock.
REGISTERED_SUITES
The closed TS suite registry (SIG_SUITES in 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}))); None where 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 canonicalize plus 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 under authority_pq_pk), scope, now <= not_after, issued_at <= now + 60 s; d. now - issued_at <= max_age_ms; e. revoked is the full signed set (revset_root); f. append-only against last (well-formed by b’s shape and e): no rollback, no dropped id, no equivocation; g. no id of ids is 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, and accumulators when the PCActn carries intent_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’s IntentWBInput. 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). params absent = {}; never panics.
decide_param_provenance
The rule-17 decision on the reference’s ProvenanceInput (decideParamProvenance). Never panics.
decide_read_purpose
decideReadPurpose on {fields: [{path, class, optional?}], purpose, coverage: {purpose: [pattern]}, on_uncovered?}. Malformed input (JSON null anywhere included) is deny with empty lists; coverage[purpose] is an own member; a field is covered when its class is public or 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). When len is given the DECODED length must equal it. Returns None on ANY deviation.
decode_pca_header
Decode a PCA-Action header value to the encoded PCActn JSON text (pass it to strict_parse).
delta_revocation_id
"pca-intent:delta:" + grant id.
evaluate_caveats
Evaluate a caveat list against a policy context; (ok, failed) where ok iff every caveat is satisfied and failed lists 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.ts canonicalBytes is canonicalizeStrict): depth <= MAX_JSON_DEPTH, safe integers only, plain-decimal non-integers. None on 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?}, prev present iff seq > 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 JSON null or of the wrong JSON type is malformed. Covers the policy (and its members), params, schema, session, acc, the layers ceilings (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). None when 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>}))). None where the reference throws.
policy_caveats
Every caveat the policy layer evaluates for an action under grant delegated along chain (root first): the grant’s caveats with its FIRST envelope caveat removed (order kept; that one is the policy container read separately), then the caveats the hops appended (leaf.caveats beyond the grant’s, leaf = the last chain element). Nothing is appended when chain is not a non-empty array or either caveat list is not an array. A non-array grant list is returned as is (Null when absent), and evaluate_caveats refuses 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 (null is malformed), and the alg a suite the dispatch implements (unsupported_suite otherwise).
revset_root
revset_root(L) = b64u(sha256(“pca-revset/v1\0” || strictCanonical({size: |L|, tree}))), tree the RFC-6962-shaped Merkle root over the ids in order (leaf SHA-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_ref of 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: None on 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_parse for 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 cap MAX_JSON_DEPTH applied to the WHOLE envelope, as the reference does (require-pca.ts defaultExtract strict-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 terminal wire check).
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.kid names a listed discovery key, sig.alg equals 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, alg absent = ed25519) over msg under its suite: the wire shape per suite, then the ONE suite dispatch with the Ed25519 half under ed_pub and the PQ half under the artifact’s OWN pq_pk (CALLER-VOUCHED: only for keys the caller authorised elsewhere, e.g. the pq_artifact conformance primitives). False for an unsupported / unknown suite or any failure. Total.
verify_chain
Mirrors verifyChain in capability.ts. Ok(()) when valid, else Err(reason). The 16-hop cap is enforced before any signature work.
verify_chain_policy
verify_chain with 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_pins maps the root issuer (Ed25519, base64url) to its ML-DSA public key (a pin that differs from the root’s pq_pk is a refusal); trusted_root is 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/size are 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 intent when the PCActn carries it). now is epoch milliseconds; audience is this verifier’s own audience id. Later-milestone checks (attestation, threshold, revocation, …) are out of scope.
verify_pcactn_core_policy
verify_pcactn_core with an optional allowed-suites policy (None = none; Some(&[]) refuses every hop and leaf suite; absent alg == “ed25519”). Hybrid / pure-PQ keys are always required to be bound to the signer’s holder_pq (no unbound escape hatch).
verify_pcactn_core_with
verify_pcactn_core with explicit VerifyOptions. The intent check runs after counter and is reported iff the PCActn carries intent or opts.intent is 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 wire failure), then verify_pcactn_core.
verify_pcactn_json_policy
verify_pcactn_json with an optional allowed-suites policy.
verify_pcactn_json_with
verify_pcactn_json with explicit VerifyOptions.
verify_session_root
verifySessionRoot(S) with NO verifier pins: an Ed25519 root verifies as before; a pure-PQ / hybrid root fails closed (see verify_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 = context session.pq_pins, an object whose own member for the signer is a string), never under the root’s own principals[].pq_pk; the signer’s own entry, when it declares a pq_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 false on 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) under share.publicKey (or share.pq_pk per share.alg, routed through the same suite seam as the leaf). Consequently the PRE-v2.1 bare agent share (a sig over 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. entry is a { role, t, signer_set, threshold_message, share{publicKey, sig, alg?, pq_pk?, pq_sig?} } object (the primitives.threshold_share[] shape).