Crate pic_continuity

Expand description

PIC Profile 0.2 — continuity artifacts, Prover, and Verifier.

Implements the artifact family and procedures of the PIC Prover and Verifier Specification (draft 0.2):

artifacts — PIC PCA COSE, PIC Continuity COSE, PIC Continuity Transition COSE, and the PIC Token JWT envelope;
authority — Logical Context of Authority, canonical Indexed Authority Map, removal bitmaps, execution-contract additions, and the non-expansion order;
proposal — the Initial Continuity Proposal JSON object and its continuity_proposal wire encoding (compact JSON, unpadded Base64url);
prover — builds a workload-signed advancement candidate from the current trusted checkpoint;
verifier — ordinary verification of settled artifacts and the settlement-authority validation procedure (the role PIC-X realizes);
jwk — verification keys from published JWKs, and the algorithm agreement that stops an artifact choosing how it is verified;
por — the pluggable Proof of Relationship validation boundary;
trust — the traits a host supplies (trusted checkpoints, key material, revocation, policy);
cose — a generic, crypto-agnostic COSE_Sign1 envelope. Self contained by design: it is the candidate for extraction into its own crate when a second consumer needs it.

The Verifier is pure: it performs no I/O, and everything environmental (trusted checkpoint state, issuer trust, revocation, policy) enters through the trust and por traits.

§Roles

Role	Entry point
Workload / Prover	`prover::build_candidate`
Ordinary verifier	`verifier::verify_settled`
Settlement authority (realm)	`verifier::SettlementAuthority::settle`, `verifier::issue_settled`

§Example: issue and verify a settled state

The initialization path — a realm signs checkpoint 0 (for example after an OAuth-to-PIC token exchange) and any holder of the realm public key verifies the resulting PIC Token JWT offline:

use pic_continuity::artifacts::PicPcaPayload;
use pic_continuity::authority::{
    AuthorityValue, IndexedAuthorityMap, Invariant, LogicalAuthority,
};
use pic_continuity::trust::{Ed25519Signer, Ed25519Verifier};
use pic_continuity::verifier::{issue_settled, verify_settled, SettlementContext};
use std::collections::BTreeMap;

// The realm signing key (settlement authority).
let realm_key = ed25519_dalek::SigningKey::generate(&mut rand::rngs::OsRng);
let realm = Ed25519Signer::new(realm_key, "https://pic-x.example.com/realms/acme#key-1");

// A Logical Context of Authority, canonicalized deterministically.
let mut contract = BTreeMap::new();
contract.insert("corporation".into(), AuthorityValue::One("ACME".into()));
let logical = LogicalAuthority::new(
    None,
    vec![Invariant::new(
        "documents:read:document-42", "read", "documents", "document-42",
    )],
    contract,
);
let authority = IndexedAuthorityMap::from_logical(&logical)?;

// Checkpoint 0 with its verifier-issued challenge.
let checkpoint = PicPcaPayload::new(0, authority, vec![0x7b; 32]);
let issued = issue_settled(checkpoint, &realm, &SettlementContext {
    iss: "https://pic-x.example.com/realms/acme".into(),
    ..Default::default()
})?;

// Any workload with the realm public key verifies the settled token.
let verifier = Ed25519Verifier::new(realm.verifying_key());
let settled = verify_settled(&issued.token, &verifier)?;
assert_eq!(settled.checkpoint.position, 0);

Advancement is the prover::build_candidate → verifier::SettlementAuthority::settle round trip; the crate’s walkthrough integration test exercises the full lineage (checkpoint 0 → 1 → 2) including attenuation and rejection paths.

§Feature flags

Feature	Effect
`ed25519` (default)	`trust::Ed25519Signer` / `trust::Ed25519Verifier` and COSE `EdDSA` support via `ed25519-dalek`
`p256`	ECDSA P-256 (`ES256`) COSE helpers
`p384`	ECDSA P-384 (`ES384`) COSE helpers
`full`	All of the above

The core protocol logic is crypto-agnostic: with no features enabled the crate still builds, and signing/verification enter through closures or the trust::ArtifactSigner / trust::ArtifactVerifier traits.

§What this crate does not do

SD-JWT Proof of Relationship validation — deployment-specific; supply it through por::PorValidator.
Revocation state — supply it through trust::RevocationCheck.
Transport, storage, OAuth endpoints — this crate is pure protocol logic; PIC-X is the reference deployment that hosts it.

Modules§

artifacts: Profile 0.2 artifacts, one file per protocol object:
authority: Authority: logical form, canonical indexed form, attenuation.
cose: Generic COSE_Sign1 envelope (RFC 9052) for CBOR-serializable payloads.
error: Error types.
jwk: Verification keys from published JWKs (RFC 7517).
por: Proof of Relationship validation boundary.
proposal: The Initial Continuity Proposal (Profile 0.2).
prover: PIC Prover (Profile 0.2, centralized settlement).
trust: Host-supplied trust boundaries.
verifier: PIC Verifier (Profile 0.2).

Constants§

FORMAT_PIC_CONTINUITY_COSE: Profile 0.2 artifact format identifier for the PIC Continuity COSE.
FORMAT_PIC_PCA_COSE: Profile 0.2 artifact format identifier for the PIC PCA COSE.
FORMAT_PIC_TOKEN_JWT: Profile 0.2 artifact format identifier for the PIC Token JWT.
FORMAT_PIC_TRANSITION_COSE: Profile 0.2 artifact format identifier for the PIC Continuity Transition COSE.
POR_TYPE_SD_JWT: The Proof of Relationship type required by current Profile 0.2.
PREDECESSOR_TYPE_PCA: The predecessor reference type required by current Profile 0.2.
PROFILE_0_2: The active PIC profile identifier implemented by this crate.
PROPOSAL_TYPE_CONTINUITY_INITIAL: Stable semantic URI for the Initial Continuity Proposal type.
TOKEN_TYPE_PIC: Stable semantic URI for the PIC token type (RFC 8693 token exchange binding).

Functions§

continuity_version: This crate’s version, as published.