Skip to content

Commit 365875c

Browse files
committed
feat(psp-1): Major structural and terminological overhaul
This commit introduces a major refactoring of PSP-1 to improve clarity, precision, and implementer experience. The document has been restructured to separate normative statements from informative content, a consistent naming convention has been adopted, and several key concepts have been expanded and clarified. A primary motivation is to make the specification more directly implementable by providing a clear normative kernel, explicit algorithms, and unambiguous terminology. - **New Document Structure:** - Introduced a "Normative Kernel" section (4) to consolidate all core verification logic. - Added a new top-level "Artifacts" section (5) to provide detailed normative descriptions of `Grants`, `Presentations`, and `Delegation & Attenuation`. - Massively expanded the "Motivation and Rationale" section (3) with detailed design principles, a threat model, and rationale for key design choices. - Added a dedicated "Examples and Conformance Test Vectors" section (9). - **Standardized Naming Convention:** - All specification identifiers (builtin `op` names, pin IDs, context keys, conceptual fields) have been standardized to `lower-camelCase`. - Examples: `grant_ref` -> `grantRef`, `builtins_id` -> `builtinsId`, `within_time` -> `withinTime`, `ctx_eq` -> `ctxEq`. - Added a new section `2.3 Identifier & casing convention` to make this rule explicit. - **Enhanced Semantic Pinning (BREAKING CHANGE):** - **`schemesSnapshotId` Pin:** Grants **MUST** now include a `schemesSnapshotId` pin. This is a content-addressed manifest that maps resource schemes (e.g., `vault:`) to their exact comparator snapshot, preventing comparator drift. This was previously implicit and is now a required, verifiable pin. - The "Semantic Pinning" section (4.4) has been completely rewritten to be more normative and precise about a Grant's required pins and delegation compatibility rules. - **Expanded Definitions:** - **New Terminology:** Added formal definitions for `Local Availability`, `CEP Placement Variants` (`CEP(R)`, `CEP(P)`, `CEP(S)`), and `Bridge Adapter (BA)`. - **Pin:** The definition of a `Pin` is now more generic and detailed, covering CIDs and URIs. - **Improved Normative Clarity:** - **Verification Algorithm:** Rewritten into a more precise, step-by-step algorithm in section `4.6`. - **Fail-Closed Catalogue:** Added a comprehensive table (`4.8`) summarizing all conditions that **MUST** result in a denial. - **Time Model:** Added a dedicated section `4.7` to clarify the "single time capture" rule and the use of half-open intervals. - **Documentation & Examples:** - Added section `2.4 Interpretation of JSON Projections` to clarify that JSON examples are non-normative. - Narrative examples in section `9.1` are now much more detailed, including illustrative Grant/Presentation projections and a CEP evaluation outline. - Conformance test vectors are now integrated into the main body in section `9.2`. - **PSP Dependencies:** - `PSP-4` is now listed as a formal dependency. - `PSP-2` is now listed as an "Informative reference" rather than a hard dependency for the core model. - **Minor Changes:** - Added a "Backwards Compatibility" section (7). - Merged old "Overview and Goals" into the new "Motivation and Rationale" section. - The CDDL grammar and builtin operator tables have been updated to reflect the new `camelCase` naming. - Removed "Appendix D - Suggested Reason Codes" in favor of the fail-closed catalogue. BREAKING CHANGE: This commit introduces significant breaking changes. 1. **Naming Convention:** All identifiers are now `lower-camelCase`. Implementations must update field names, builtin operator calls, and pin lookups. 2. **Required `schemesSnapshotId` Pin:** All Grants must now include the `schemesSnapshotId` pin. Verification logic must be updated to check for its presence and enforce compatibility across delegation chains.
1 parent ab24200 commit 365875c

File tree

1 file changed

+1265
-989
lines changed

1 file changed

+1265
-989
lines changed

0 commit comments

Comments
 (0)