1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
/*
* Copyright Nitro Agility S.r.l.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* https://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
//! # PIC Protocol — Provenance Identity Continuity
//!
//! Rust implementation of the [PIC Protocol](https://www.pic-protocol.org):
//! verifiable authority continuity across distributed and agentic execution
//! chains, as defined by the
//! [PIC Specification](https://github.com/pic-protocol/pic-spec).
//!
//! Where a bearer token proves *possession*, a PIC continuity state proves
//! *provenance*: each hop of an execution chain carries a signed, verifiable
//! lineage of how its authority was derived — and authority can only be
//! attenuated along the way, never expanded.
//!
//! This crate is the facade over the protocol crates; today it re-exports
//! one implementation crate:
//!
//! - [`continuity`] — PIC Profile 0.2: the artifact family (PIC Token JWT,
//! PIC PCA COSE, PIC Continuity COSE, PIC Continuity Transition COSE),
//! the canonical Indexed Authority Map, the Prover (candidate
//! construction), and the Verifier (settled-state verification and the
//! settlement procedure).
//!
//! # Quick start
//!
//! 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 (e.g. after an OAuth-to-PIC token exchange).
//! 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);
//! # Ok::<(), pic::continuity::error::ContinuityError>(())
//! ```
//!
//! See the [`continuity`] module documentation for the full role map
//! (Prover, ordinary verifier, settlement authority) and feature flags.
//!
//! # Feature flags
//!
//! | Feature | Effect |
//! |---------|--------|
//! | `ed25519` *(default)* | Ed25519 signers/verifiers via `ed25519-dalek` |
//! | `p256` | ECDSA P-256 (`ES256`) |
//! | `p384` | ECDSA P-384 (`ES384`) |
//! | `crypto-full` / `full` | All of the above |
/// PIC Profile 0.2: continuity artifacts, Prover, and Verifier.