wip: working on presentations

Author: CMCDragonkai

docs/reference/specifications/PSP-1 - Capability Model and Grammar.mdx

@@ -64,14 +64,14 @@ Design goals:
 - Secure by default: Holder-of-key (PoP) + channel binding; short TTLs for Presentations; pure, bounded builtins only.
 - Receipt-ready: CEPs can emit Access PoARs with program projection/proof traces (see PSP-2).
 
-Non-goals (out of scope for PSP-01):
+Non-goals (out of scope for PSP-1):
 
 - Enforcement placement/modes: CEP/BA placements (P/S/R) and mediate/derive/reveal semantics are specified in the CEP/BA spec.
 - Lease lifecycle/rotation: Lease issuance and rotation policies are defined elsewhere; PSP-1 only requires Lease freshness to be verified when Grants touch non-native SoA (enforced by CEP per TAP).
 - Receipt schemas: All receipt formats (PoAR/VOR/View) are specified in PSP-2.
 - Transport/envelope and sigchain framing (JOSE/COSE/DSSE, canonical bytes): specified in PSP-3.
 - Channel-binding mechanisms: Concrete binding profiles (e.g., TLS exporter, DPoP) are profiled elsewhere; PSP-1 only requires a verified binding.
-- Global time/ordering: PSP-01 does not require a global clock or total order. Acceptance (TAP) specifies clock sources and tolerances.
+- Global time/ordering: PSP-1 does not require a global clock or total order. Acceptance (TAP) specifies clock sources and tolerances.
 - Secret issuance/derivation/aggregation crypto and interactive evaluation flows.
 - No ZK/succinct delegation proofs in core; no signature aggregation (e.g., BLS).
 - No recursion or negation-as-failure in the Program (monotone only).
@@ -443,7 +443,7 @@ A conforming Grant MUST satisfy all of the following.
    - If any resource string in a declaration cannot be normalized under its scheme's rules, verification MUST deny.
    - If program_bytes cannot be parsed into a valid CPL/0 Program per PSP-1 (e.g., type errors, prohibited terms), verification MUST deny.
 7. Determinism and normalization invariants
-   - A CEP MUST evaluate using only `{program_bytes/program_id, bundled Declarations, builtins_id, channel_lattice_id when used, and the scheme comparator selected by scheme name}`. No other registry artifacts may change the decision at verification.
+   - The CEP MUST evaluate using only `{program_bytes/program_id, bundled Declarations, builtins_id, channel_lattice_id when used, and the scheme comparator selected by scheme name}`. No other registry artifacts may change the decision at verification.
    - At verification time the CEP MUST normalize the environment resource using the same scheme comparator semantics as those used during declaration canonicalization; normalization failure MUST cause deny.
 
 ### Attenuation by Derivation (Grant → Derived Grant)
@@ -471,9 +471,9 @@ Informative note: The precise tightening rules for builtins (e.g., within_time i
 - Presentations are ephemeral proofs that reference a Grant by its canonical digest (grant_ref). They carry PoP, channel binding, iat/exp, and ctx facts. Presentations are NOT recorded on sigchains.
 - CEPs verify the Grant (signatures, revocation per PSP-3), verify custody and syntactic attenuation along any delegation chain under the pinned registries, then evaluate the leaf Program against CEP-provided environment facts and the Grant's bundled Declarations.
 - On success, enforcement MAY proceed, and the CEP SHOULD emit an Access PoAR containing program_id, declaration CIDs, registry pins, and a minimal evaluation trace per PSP-2.
-- CEPs MUST deny if grant_ref cannot be resolved to a valid Grant under PSP‑3 framing and signatures.
+- CEPs MUST deny if grant_ref cannot be resolved to a valid Grant under PSP-3 framing and signatures.
 
-### Minimial Illustrative Projection (Non-Normative)
+### Minimal Illustrative Projection (Non-Normative)
 
 The following illustrates only the Grant payload structure relevant to PSP-1. Envelope fields, signatures, canonical claim bytes, and multihash details are defined in PSP-3.
 
@@ -498,6 +498,90 @@ Implementers MUST NOT rely on this projection for wire encoding; the normative t
 
 ## Presentations
 
+A Presentation is an ephemeral, on-path proof by the Subject (S) that it possesses a specific Grant and is exercising it now, on this live channel, in this runtime context. Presentations are NOT written to sigchains. They reference a Grant by its canonical digest (grant_ref, per PSP-3), are proof-of-possession (PoP) bound to the holder's key, and are cryptographically bound to the live session via a channel-binding profile. PSP-1 defines what a CEP must verify and evaluate; PSP-3 defines the on-wire framing and field mappings.
+
+### Purpose and Role
+
+- Ephemeral proof: Demonstrates holder-of-key (PoP) and binds use to the current session.
+- Grant reference: Points to the leaf Grant (grant_ref per PSP-3) that carries the Program and bundled Declarations.
+- Runtime facts: Conveys ctx and timing (iat/exp) the CEP uses to evaluate the Program's literals (e.g., ctx_eq, ttl_ok, within_time).
+
+### Structure (Informative Projection)
+
+Note: The names below are non-normative conceptual labels used by PSP-1. The normative on-wire field names and encodings are defined in PSP-3.
+
+- presenter: DID of the holder (Subject).
+- grant_ref: canonical digest of the leaf Grant (per PSP-3).
+- iat: Int (NumericDate seconds) - mint time.
+- exp: Int (NumericDate seconds) - expiry; exp - iat SHOULD be short; MAY be bounded by Program via ttl_ok.
+- jti: nonce (unique) for replay resistance.
+- channel_binding: `{ profile: Str, value: BytesOrB64 }` - binding to the live session (e.g., TLS exporter, DPoP).
+- ctx: `Map<Str, Term>` — runtime context; MUST include at least the k/v required by the Program's ctx_eq literals.
+- chain (delegation material; TAP-governed; one is REQUIRED):
+  - grants: OPTIONAL embedded Grant bodies (leaf→root) for offline verification (RECOMMENDED for air-gapped CEPs), or
+  - grant_refs (+ resolvers): OPTIONAL parent digests and resolvers to fetch/verify custody; TAP MAY forbid network fetches.
+
+### Normative Requirements
+
+- Proof-of-possession and channel binding
+  - The Presentation MUST be signed by the presenter (PoP). The CEP MUST verify PoP.
+  - The Presentation MUST be bound to the live session per the declared channel_binding profile. The CEP MUST verify that the binding matches the live session and deny on mismatch.
+- Lifetime and timing
+  - The CEP MUST reject if the Presentation is expired (now ≥ exp) or used too early (now < iat), subject to TAP clock discipline.
+  - If the Program contains ttl_ok or within_time literals, the CEP MUST enforce them using iat/now/exp as appropriate.
+  - If the Grant envelope carries a validity window (not_before/not_after) per PSP-3, the CEP MUST enforce it and, where both apply, MUST enforce the intersection with the Presentation's lifetime.
+  - If the Program does not constrain Presentation lifetime via ttl_ok, TAP MAY impose a default maximum Presentation TTL.
+- Context
+  - ctx MUST be a superset of the required ctx_eq(k, v) literals in the Program. Missing keys or unequal values MUST cause deny.
+- Grant reference and custody
+  - grant_ref MUST resolve to a valid leaf Grant under PSP-3 framing and signatures; failure MUST cause deny.
+  - If delegation is present, the Presentation MUST carry (or allow resolution of) sufficient delegation material to verify:
+    - custody hop-by-hop (issuer(child) == subject(parent)),
+    - prev linkage (per PSP-3),
+    - pins compatibility (lang_version, builtins_id, and channel_lattice_id when channel_geq is used),
+    - syntactic attenuation (checks/literals tightening and declarations subset).
+  - Any failure in the above MUST cause deny.
+- Storage
+  - Presentations MUST NOT be recorded on sigchains.
+
+### Fail-Closed Conditions
+
+A CEP MUST deny if any of the following holds:
+
+- PoP signature invalid or channel binding does not match the live session.
+- Presentation lifetime invalid or violates ttl_ok/within_time literals.
+- grant_ref cannot be resolved to a valid Grant (PSP-3).
+- Custody/attenuation verification fails (missing parents; signature or prev linkage failure; cycle; TAP depth exceeded; pins mismatch; non-attenuating child).
+- Unknown or unavailable builtin referenced by the Program; unknown channel_lattice_id when channel_geq is present.
+- Unknown or unavailable scheme comparator required for declaration evaluation; env.resource normalization failure under the active comparator.
+- Missing required ctx keys or mismatched ctx_eq values.
+- Grant envelope validity window is violated (now outside not_before/not_after per PSP-3).
+
+### Minimal Illustrative Projection (Non-Normative)
+
+Note: PSP-3 defines the authoritative on-wire encoding and field mapping.
+
+```
+{
+  "iss": "did:pk:S",
+  "grant_ref": "cid://G_leaf",
+  "iat": 1768099200,
+  "exp": 1768099320,
+  "jti": "uuid-1234",
+  "channel_binding": {
+    "profile": "tls_exporter:v1",
+    "value": "base64url(exporter)"
+  },
+  "ctx": { "ns": "ci", "pod": "runner-xyz" },
+  "grants": [ /* OPTIONAL: embedded leaf→root chain for offline */ ]
+}
+```
+
+### Notes (informative)
+
+- PSP-1 does not mandate exact Presentation field names or encodings; those appear in PSP-3. The CEP's obligations here are limited to PoP verification, channel binding verification, custody/attenuation verification, and Program evaluation under the pinned semantics and bundled declarations.
+- Per-use narrowing is achieved by the Program's literals (e.g., ctx_eq, ttl_ok) evaluated against Presentation-supplied ctx and iat/exp. A future TAP-gated profile MAY introduce presentation overlays with strict attenuation and receipt requirements.
+
 ## Delegation && Attenuation
 
 ## CEP Verification Algorithm