251 lines
4.8 KiB
Markdown
251 lines
4.8 KiB
Markdown
Below is a **minimal, sufficient, and future-proof specification for the Policy Hash**, designed to *anchor meaning without freezing evolution*.
|
||
It is intentionally **small**, **deterministic**, and **composable**, and it fits cleanly into your DAM + PER + federation model.
|
||
|
||
---
|
||
|
||
# Policy Hash Specification
|
||
|
||
---
|
||
|
||
## 1. Purpose of the Policy Hash
|
||
|
||
The **policy hash** binds **domain rules** to **snapshots and authority** without embedding mutable text inside every artifact.
|
||
|
||
It answers:
|
||
|
||
> *“Under what rules was this snapshot, PER, or publication considered valid?”*
|
||
|
||
The hash ensures:
|
||
|
||
* Deterministic interpretation
|
||
* Replay safety
|
||
* Cross-domain verification
|
||
* Explicit policy evolution
|
||
|
||
---
|
||
|
||
## 2. What the Policy Hash Is (and Is Not)
|
||
|
||
### Is:
|
||
|
||
✔ A content hash of **policy assertions**
|
||
✔ Snapshot-pinned
|
||
✔ Interpreted identically across nodes
|
||
|
||
### Is Not:
|
||
|
||
✘ A live configuration
|
||
✘ An ACL
|
||
✘ A rules engine
|
||
✘ A machine policy
|
||
|
||
---
|
||
|
||
## 3. Policy Hash Coverage (Normative)
|
||
|
||
The policy hash MUST cover **only semantic constraints that affect correctness or trust**.
|
||
|
||
### Mandatory Sections
|
||
|
||
1. **Publication Rules**
|
||
2. **Execution Rules**
|
||
3. **Federation Rules**
|
||
4. **Retention & GC Constraints**
|
||
5. **Visibility Rules**
|
||
|
||
Nothing else.
|
||
|
||
---
|
||
|
||
## 4. Canonical Policy Document (Logical Structure)
|
||
|
||
The policy document is a **pure data artifact**.
|
||
|
||
```text
|
||
DomainPolicy {
|
||
version : u32
|
||
publication_policy : PublicationPolicy
|
||
execution_policy : ExecutionPolicy
|
||
federation_policy : FederationPolicy
|
||
retention_policy : RetentionPolicy
|
||
visibility_policy : VisibilityPolicy
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 5. Policy Sections (Minimal Content)
|
||
|
||
### 5.1 Publication Policy
|
||
|
||
```text
|
||
PublicationPolicy {
|
||
require_signature : bool
|
||
allowed_roles[] : Role
|
||
snapshot_required : bool
|
||
}
|
||
```
|
||
|
||
Example meaning:
|
||
|
||
* Artifacts must be signed
|
||
* Only `publish` role may publish
|
||
* Publication must be snapshot-bound
|
||
|
||
---
|
||
|
||
### 5.2 Execution Policy
|
||
|
||
```text
|
||
ExecutionPolicy {
|
||
per_signature_required : bool
|
||
allowed_roles[] : Role
|
||
deterministic_only : bool
|
||
}
|
||
```
|
||
|
||
Meaning:
|
||
|
||
* PERs must be signed
|
||
* Only `execute` role may emit PERs
|
||
* No nondeterministic execution accepted
|
||
|
||
---
|
||
|
||
### 5.3 Federation Policy
|
||
|
||
```text
|
||
FederationPolicy {
|
||
export_published_only : bool
|
||
require_snapshot : bool
|
||
trusted_domains[] : DomainID
|
||
}
|
||
```
|
||
|
||
Meaning:
|
||
|
||
* Only published state may be federated
|
||
* Federation is snapshot-based
|
||
* Optional allowlist of domains
|
||
|
||
Empty allowlist = open federation.
|
||
|
||
---
|
||
|
||
### 5.4 Retention & GC Policy
|
||
|
||
```text
|
||
RetentionPolicy {
|
||
gc_unpublished_allowed : bool
|
||
min_snapshot_retention : u32
|
||
}
|
||
```
|
||
|
||
Meaning:
|
||
|
||
* Whether unpublished artifacts may be GC’d
|
||
* Minimum snapshots to retain
|
||
|
||
---
|
||
|
||
### 5.5 Visibility Policy
|
||
|
||
```text
|
||
VisibilityPolicy {
|
||
internal_hidden : bool
|
||
published_read_only : bool
|
||
}
|
||
```
|
||
|
||
Meaning:
|
||
|
||
* Internal artifacts invisible externally
|
||
* Published artifacts immutable
|
||
|
||
---
|
||
|
||
## 6. Canonicalization Rules (Critical)
|
||
|
||
The policy hash MUST be computed from **canonical bytes**:
|
||
|
||
1. Field order fixed
|
||
2. Arrays sorted lexicographically
|
||
3. No whitespace
|
||
4. No comments
|
||
5. Big-endian integers
|
||
6. Boolean encoded as `0x00` / `0x01`
|
||
7. No optional fields omitted — use explicit defaults
|
||
|
||
Hash algorithm: **SHA-256** (or domain-declared)
|
||
|
||
---
|
||
|
||
## 7. Policy Hash Computation
|
||
|
||
```text
|
||
policy_bytes = CanonicalSerialize(DomainPolicy)
|
||
policy_hash = HASH(policy_bytes)
|
||
```
|
||
|
||
The `policy_hash` is stored in:
|
||
|
||
* Domain Authority Manifest
|
||
* Snapshot metadata
|
||
* Federation metadata
|
||
* Optional PER metadata (reference only)
|
||
|
||
---
|
||
|
||
## 8. Validation Semantics
|
||
|
||
A node MUST reject any operation where:
|
||
|
||
* Policy hash does not match snapshot
|
||
* Policy version unsupported
|
||
* Required signature missing
|
||
* Required role not satisfied
|
||
* Federation rules violated
|
||
|
||
---
|
||
|
||
## 9. Policy Evolution (Key Design Point)
|
||
|
||
Policy changes do **not** mutate history.
|
||
|
||
Instead:
|
||
|
||
1. New policy document created
|
||
2. New policy hash computed
|
||
3. New DAM published
|
||
4. New snapshots reference new hash
|
||
|
||
Old snapshots remain valid forever.
|
||
|
||
---
|
||
|
||
## 10. Why This Is Minimal but Complete
|
||
|
||
✔ Captures all trust-affecting rules
|
||
✔ Deterministic across nodes
|
||
✔ Decouples authority from text
|
||
✔ Enables offline replay
|
||
✔ Avoids configuration drift
|
||
|
||
---
|
||
|
||
## 11. One-Sentence Summary
|
||
|
||
> **The policy hash cryptographically binds the rules of trust and visibility to every snapshot and execution without embedding mutable policy text into the data plane.**
|
||
|
||
---
|
||
|
||
If you want, next we can:
|
||
|
||
* Define **canonical serialization format** (exact byte layout)
|
||
* Show **policy hash verification during federation**
|
||
* Walk through **policy evolution example**
|
||
* Tie policy hash into **GC safety proofs**
|
||
|
||
Just tell me where to continue.
|
||
|