Skip to content

Commit 4046484

Browse files
committed
fix(psp-1):
- changed `langVersion` to be `cpl/0` only - changed `lease_status` to `leaseStatus` - lease freshness is governed by TAP - no more mentions about the contents of PoAR and DenyReceipts
1 parent 94f5be4 commit 4046484

File tree

1 file changed

+60
-62
lines changed

1 file changed

+60
-62
lines changed

docs/reference/specifications/psp-1.mdx

Lines changed: 60 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -390,8 +390,9 @@ reference these facts by name.
390390
- ctx: `Map<Str, Term>` - runtime context (e.g.,
391391
`{"ns":"prod","pod":"runner-42"}`).
392392
- Optional environment facts (TAP-gated)
393-
- lease_status - opaque assurance/freshness input for lease checks (no I/O in
394-
the builtin).
393+
- leaseStatus - optional TAP-provided evidence used to assess upstream
394+
lease/credential freshness. Semantics are TAP-defined; no network I/O occurs
395+
during evaluation.
395396
- TAP MAY require additional environment facts (e.g., provenance labels,
396397
jurisdiction tags, or digest references) and define how they are obtained
397398
and verified. PSP-1 does not enumerate these; Programs assert them via
@@ -574,10 +575,11 @@ or a scheme comparator evolved.
574575

575576
### 6.2 What MUST be pinned
576577

577-
A Grant **MUST** include the following identifiers in its `pins` map. Each
578+
A Grant MUST include the following identifiers in its `pins` map. Each
578579
identifier references an immutable snapshot in a registry (see PSP-4):
579580

580-
- **`langVersion`** - the CPL/0 edition string (e.g., `cpl/0@1`).
581+
- **`langVersion`** - the CPL/0 language generation. For this specification the
582+
value MUST be `cpl/0`.
581583
- **`builtinsId`** - a content-addressed snapshot of the builtin operators in
582584
use (including each opcode's semantics, type signatures, tightening rules, and
583585
resource bounds).
@@ -634,7 +636,7 @@ denial.
634636

635637
### 6.5 Fail-closed conditions
636638

637-
A CEP **MUST** deny if any of the following holds:
639+
A CEP MUST deny if any of the following holds:
638640

639641
- `builtinsId` is missing, unknown, or cannot be loaded.
640642
- The Program uses `channelGeq` but `channelLatticeId` is missing or unknown.
@@ -814,10 +816,10 @@ A conforming Grant MUST satisfy all of the following.
814816
- The bytes for every referenced declaration MUST be bundled in the Grant
815817
payload; no network fetches at evaluation.
816818
- `pins`: Registry pins that fix semantics across CEPs and time:
817-
- `langVersion`: The CPL/0 language version string (e.g., `"cpl/0@1"` -
818-
string form defined in PSP-4).
819-
- `builtinsId`: Content-addressed identifier of the Builtins registry
820-
snapshot used by the Program.
819+
- `langVersion`: The CPL/0 language generation. In this specification the
820+
value MUST be `"cpl/0"` when present. The string form is defined in PSP-4.
821+
- `builtinsId`: Content-addressed identifier of the Builtins registry
822+
snapshot used by the Program.
821823
- `channelLatticeId`: REQUIRED only if the Program uses `channelGeq`. It MUST
822824
be omitted if the Program does not call `channelGeq`. When present, it pins
823825
the channel lattice used to interpret `>=`.
@@ -915,7 +917,7 @@ names.
915917
"resources:cid:Qr...": "..." // canonical bytes of ResourceSet (if used)
916918
},
917919
"pins": {
918-
"langVersion": "cpl/0@1",
920+
"langVersion": "cpl/0",
919921
"builtinsId": "cid:builtins@YYYYMMDD",
920922
"channelLatticeId": "cid:lattice@1", // REQUIRED iff Program uses `channelGeq`
921923
"schemesSnapshotId": "cid:schemes@YYYYMMDD" // REQUIRED: pinned manifest of scheme comparators
@@ -973,12 +975,12 @@ Grants and transient proof-of-use.
973975
early (now < iat), subject to TAP clock discipline.
974976
- If the Program contains ttlOk or withinTime literals, the CEP MUST enforce
975977
them using iat/now/exp as appropriate.
976-
- Effective lifetime: When both `[iat, exp)` and `ttlOk` appear, both MUST
977-
pass at the captured `now`. The effective acceptance window is the
978-
intersection of these constraints.
979-
- If the Grant envelope carries a validity window (not_before/not_after) per
980-
PSP-3, the CEP MUST enforce it and, where both apply, MUST enforce the
981-
intersection with the Presentation's lifetime.
978+
- Effective lifetime: The CEP MUST enforce the intersection of all applicable
979+
time windows at the captured `now`. Specifically, the Presentation window
980+
`[iat, exp)`, any Grant envelope validity window (`not_before`/`not_after`
981+
per PSP-3), and any Program time literals such as `ttlOk` or `withinTime`
982+
MUST all succeed. If any one of these constraints fails at `now`,
983+
enforcement MUST deny.
982984
- If the Program does not constrain Presentation lifetime via ttlOk, TAP MAY
983985
impose a default maximum Presentation TTL.
984986
- Context
@@ -1133,7 +1135,10 @@ additional discussion of the risks mitigated by syntactic attenuation.
11331135
- issuer(child) MUST equal subject(parent).
11341136
- Each Grant in the chain MUST be written on its issuer's sigchain with valid
11351137
signatures per PSP-3.
1136-
- prev linkage MUST form a simple path leaf->root; the CEP MUST reject cycles.
1138+
- All required parent Grants MUST be locally available at enforcement;
1139+
otherwise the CEP MUST deny. (Pre-enforcement acquisition is TAP-governed.)
1140+
- `prev` linkage MUST form a simple path from leaf to root; the CEP MUST deny
1141+
if any digest repeats (cycle detection).
11371142
- Depth and anchors (TAP-governed)
11381143
- TAP MAY set a maximum delegation depth H; the CEP MUST deny when exceeded.
11391144
- Anchoring of the root issuer for the target resource domain (when
@@ -1297,8 +1302,8 @@ remain pure; no network I/O occurs during Program evaluation.
12971302
lease rotation), upstream rotation (leases, credentials, keys) is governed by
12981303
TAP.
12991304
- The CEP MUST enforce any time/freshness constraints asserted by the Program
1300-
(e.g., withinTime, ttlOk) and any TAP-approved environment facts (e.g.,
1301-
lease_status) presented at enforcement.
1305+
(e.g., `withinTime`, `ttlOk`) and any TAP-approved environment facts (e.g.,
1306+
`leaseStatus`) presented at enforcement.
13021307
- An Access PoAR MAY include a leaseRef/freshness pointer or similar evidence as
13031308
defined by PSP-2. PSP-1 does not mandate an on-wire format for rotation
13041309
artifacts.
@@ -1371,6 +1376,12 @@ Preconditions (TAP-governed, outside evaluation)
13711376
and Presentation windows apply, enforce their intersection; else deny.
13721377
- Check revocation state for the leaf Grant per PSP-3/TAP (locally
13731378
available). If revoked or indeterminate per TAP freshness policy, deny.
1379+
- If enforcement relies on an upstream lease, credential, or secret from a
1380+
non-native Source of Authority (e.g., a Bridge/Adapter flow), the CEP MUST
1381+
evaluate freshness per TAP using only locally available evidence (e.g., a
1382+
TAP-approved environment fact such as `leaseStatus`). If freshness cannot
1383+
be established per TAP policy, the CEP MUST deny. PSP-1 does not define the
1384+
format or acquisition of such evidence.
13741385
4. Verify delegation chain (if applicable)
13751386
- Ensure all required parent Grants are locally available; else deny.
13761387
- For each hop child -> parent:
@@ -1403,7 +1414,7 @@ Preconditions (TAP-governed, outside evaluation)
14031414
- enforcer: Str (CEP identifier/audience)
14041415
- channel: Str (live session profile)
14051416
- ctx: `Map<Str, Term>` (runtime context)
1406-
- Optional TAP-approved freshness facts (e.g., lease_status), if present
1417+
- Optional TAP-approved freshness facts (e.g., `leaseStatus`), if present
14071418
- Normalize env.resource using the same scheme comparator semantics used for
14081419
declaration canonicalization; normalization failure -> deny.
14091420
6. Load Program and Declarations from the leaf Grant
@@ -1423,30 +1434,22 @@ Preconditions (TAP-governed, outside evaluation)
14231434
- presenterIs (if used)
14241435
- Enforce type checks; ill-typed literals -> deny.
14251436
- Enforce resource bounds (CPU/steps/memory). Exceeding limits MUST result in
1426-
deny. (The enforcing CEP SHOULD use an appropriate reason code from the
1427-
PSP-2 registry to indicate a resource limit or deadline breach.)
1437+
deny.
14281438
- Unknown builtin, unknown lattice, or unknown scheme comparator required by
14291439
the Program -> deny.
14301440
- Context superset: ctx MUST include all required ctxEq(k, v) literals with
14311441
equal values; else deny.
14321442
8. Decision and receipts (placement-agnostic)
1433-
- On success:
1434-
- Allow enforcement per placement/mode (mediate/derive/reveal are defined
1435-
outside PSP-1).
1436-
- The enforcing CEP MUST record a decision event for the authorization
1437-
outcome. If the CEP implements PSP-2 receipts, the enforcing CEP MUST
1438-
emit an Access PoAR to record the decision. PoARs MUST include
1439-
`programId`, declaration CIDs, pins (including `schemesSnapshotId`), a
1440-
minimal evaluation trace (which check/query passed), revocation/freshness
1441-
decision context, comparator fingerprints, and the enforcer measurement
1442-
(`adapterRef`).
1443-
- On failure:
1444-
- The enforcing CEP MUST record a decision event for the authorization
1445-
outcome. If the CEP implements PSP-2 receipts, the enforcing CEP MUST emit
1446-
a DenyReceipt. DenyReceipts MUST include a reason code from the PSP-2
1447-
registry. As with PoARs, DenyReceipts SHOULD avoid disclosing sensitive
1448-
detail and SHOULD record enough context for auditors to reconstruct the
1449-
decision.
1443+
- Allow enforcement per placement/mode (mediate/derive/reveal are defined
1444+
outside PSP-1).
1445+
- The enforcing CEP MUST record a decision event (allow or deny) for every
1446+
enforcement.
1447+
- If the implementation supports PSP-2 receipts, it MUST additionally emit
1448+
the appropriate receipt:
1449+
- Access PoAR on allow.
1450+
- DenyReceipt on deny.
1451+
- The structure and required fields of these receipts are defined in PSP-2.
1452+
PSP-1 does not define receipt contents.
14501453

14511454
### 13.3 Execution Constraints
14521455

@@ -1461,8 +1464,7 @@ Preconditions (TAP-governed, outside evaluation)
14611464
- Deadlines and budgets
14621465
- The CEP MUST enforce bounded evaluation (CPU/steps/memory). If TAP sets a
14631466
per-request deadline, the CEP MUST abort and deny when the deadline is
1464-
reached. The enforcing CEP SHOULD log an appropriate reason code as defined
1465-
by the PSP-2 registry.
1467+
reached.
14661468
- Closed-world inputs
14671469
- All required inputs (leaf Grant, parent Grants, revocation state) MUST be
14681470
locally available at the start of enforcement; otherwise the CEP MUST deny.
@@ -1554,8 +1556,7 @@ across delegation, and (d) TAP-governed acceptance and deployment hygiene.
15541556

15551557
- Resource budgets
15561558
- CEPs MUST enforce CPU/steps/memory limits for Program evaluation. Exceeding
1557-
limits MUST result in deny. The enforcing CEP SHOULD log an appropriate reason
1558-
code from the PSP-2 registry to indicate a resource or deadline violation.
1559+
limits MUST result in deny.
15591560
- Input bounds
15601561
- Programs and Declarations MUST remain finite. CEPs SHOULD bound sizes of
15611562
`programBytes`, declaration tables, and `ctx` to mitigate memory/CPU
@@ -1612,9 +1613,9 @@ across delegation, and (d) TAP-governed acceptance and deployment hygiene.
16121613
timing variations in hot paths (especially channelBinding and signature
16131614
checks).
16141615
- Error reporting
1615-
- When a receipt is emitted, implementations SHOULD include a reason code from
1616-
the registry defined in PSP-2. Avoid leaking sensitive detail in free-form
1617-
error messages; audit context belongs in receipts as specified by PSP-2.
1616+
- Free-form error messages SHOULD NOT leak sensitive details. PSP-1 does not
1617+
define receipt formats; if receipts are used, their structure is defined by
1618+
PSP-2.
16181619

16191620
### 14.10 Placement-Specific Guidance
16201621

@@ -1685,7 +1686,7 @@ Declarations (PairSet; canonicalized and content-addressed)
16851686

16861687
Pins
16871688

1688-
- `langVersion`: "cpl/0@1"
1689+
- `langVersion`: "cpl/0"
16891690
- `builtinsId`: "cid:builtins@2025-09-01"
16901691
- `channelLatticeId`: "cid:channel-lattice@v1" (required because `channelGeq` is
16911692
used)
@@ -1701,7 +1702,7 @@ Grant (payload only, non-normative)
17011702
"pairs:bafyPairsDev1": "<PairSet-bytes>"
17021703
},
17031704
"pins": {
1704-
"langVersion": "cpl/0@1",
1705+
"langVersion": "cpl/0",
17051706
"builtinsId": "cid:builtins@2025-09-01",
17061707
"channelLatticeId": "cid:channel-lattice@v1",
17071708
"schemesSnapshotId": "cid:schemes@2025-09-01"
@@ -1787,7 +1788,7 @@ Declarations (PairSet; canonicalized and content-addressed)
17871788

17881789
Pins
17891790

1790-
- `langVersion`: "cpl/0@1"
1791+
- `langVersion`: "cpl/0"
17911792
- `builtinsId`: "cid:builtins@2025-09-01"
17921793
- `channelLatticeId`: "cid:channel-lattice@v1"
17931794
- `schemesSnapshotId`: "cid:schemes@2025-09-01"
@@ -1802,7 +1803,7 @@ Grant (payload only, non-normative)
18021803
"pairs:bafyPairsDbMint1": "<PairSet-bytes>"
18031804
},
18041805
"pins": {
1805-
"langVersion": "cpl/0@1",
1806+
"langVersion": "cpl/0",
18061807
"builtinsId": "cid:builtins@2025-09-01",
18071808
"channelLatticeId": "cid:channel-lattice@v1",
18081809
"schemesSnapshotId": "cid:schemes@2025-09-01"
@@ -1858,9 +1859,9 @@ CEP evaluation outline
18581859
- Presentations remain small; do not embed Grant bodies in PSP-1 core. If
18591860
parents aren't local at enforcement, deny (TAP defines pre-enforcement
18601861
hydration or profile-level stapling).
1861-
- Receipts: PoAR should capture enough to audit the decision (`programId`,
1862-
declaration CIDs, pins, minimal trace), plus derivation metadata (tokenRef),
1863-
but never the token itself.
1862+
- Receipts: PoAR should capture enough to audit the decision (`programId`,
1863+
declaration CIDs, pins, minimal trace), plus derivation metadata (tokenRef),
1864+
but never the token itself.
18641865

18651866
### Example 3: Physical Access - Open a door lock
18661867

@@ -1894,7 +1895,7 @@ Declarations (PairSet; canonicalized and content-addressed)
18941895

18951896
Pins
18961897

1897-
- `langVersion`: "cpl/0@1"
1898+
- `langVersion`: "cpl/0"
18981899
- `builtinsId`: "cid:builtins@2025-09-01"
18991900
- `channelLatticeId`: "cid:channel-lattice@v1"
19001901
- `schemesSnapshotId`: "cid:schemes@2025-09-01"
@@ -1909,7 +1910,7 @@ Grant (payload only, non-normative)
19091910
"pairs:bafyPairsDoor1": "<PairSet-bytes>"
19101911
},
19111912
"pins": {
1912-
"langVersion": "cpl/0@1",
1913+
"langVersion": "cpl/0",
19131914
"builtinsId": "cid:builtins@2025-09-01",
19141915
"channelLatticeId": "cid:channel-lattice@v1",
19151916
"schemesSnapshotId": "cid:schemes@2025-09-01"
@@ -1947,8 +1948,7 @@ CEP evaluation outline (resource-side CEP, OT-aware)
19471948
- ttlOk(iat,now,60): true
19481949
- ctxEq("visitorId","door-visit-123"): true
19491950
7. Allow within tight deadline; emit a PoAR if receipts are used (see PSP-2). If
1950-
a TAP-imposed deadline is exceeded, deny (an appropriate reason code from the
1951-
PSP-2 registry SHOULD be used).
1951+
a TAP-imposed deadline is exceeded, deny.
19521952

19531953
Delegated child (illustrative; equality permitted)
19541954

@@ -2056,7 +2056,7 @@ the exact set via `builtinsId`.
20562056
`withinTime(now, nbf, exp)` or `inPairSet(action, resource, "cid")`). Builtins
20572057
are **pure, deterministic, and resource-bounded**; they perform no network I/O
20582058
and return Booleans. A Grant's `builtinsId` pins a content-addressed snapshot of
2059-
the builtin catalog. CEPs **MUST** deny on unknown operators or ill-typed
2059+
the builtin catalog. CEPs MUST deny on unknown operators or ill-typed
20602060
invocations.
20612061

20622062
**Builtin operations summary**
@@ -2228,7 +2228,6 @@ Expected: Chain acceptance; allow only if `now < iat+60` and `ctx.ns="prod"`.
22282228
Setup: Parent has two Checks (AND); Child omits one parent Check.
22292229

22302230
Expect: Chain verification MUST fail due to a syntactic attenuation violation.
2231-
(Reason code per the PSP-2 registry.)
22322231

22332232
Inputs (sketch):
22342233

@@ -2237,7 +2236,7 @@ Parent: (all ( (any (and (ctxEq "ns" "prod"))) (any (and (channelGeq channel "m
22372236
Child: (all ( (any (and (ctxEq "ns" "prod"))) )) ; second Check missing
22382237
```
22392238

2240-
Expected: Deny with an appropriate reason code from the PSP-2 registry.
2239+
Expected: Deny.
22412240

22422241
#### Example 4 Time Boundaries - half-open edges
22432242

@@ -2265,8 +2264,7 @@ Expected: Allow (assuming other literals hold); deny if normalization fails.
22652264
Setup: Parent pins `schemesSnapshotId = S1`; Child pins `schemesSnapshotId = S2`
22662265
where `S2 != S1`.
22672266

2268-
Expect: Deny at chain verification due to a pin mismatch (reason code per the
2269-
PSP-2 registry).
2267+
Expect: Deny at chain verification due to a pin mismatch.
22702268

22712269
## 17. References
22722270

0 commit comments

Comments
 (0)