248 lines
5.2 KiB
Markdown
248 lines
5.2 KiB
Markdown
Great — let’s formalize it cleanly and minimally, in the same style as your other specs.
|
||
|
||
Below is a **normative artifact specification**. I’ll keep it tight, auditable, and compatible with ASL / PEL thinking.
|
||
|
||
---
|
||
|
||
# **ASL-COMMON-WITNESS-ROTATION v0.1**
|
||
|
||
## 1. Purpose
|
||
|
||
The **Witness Rotation Artifact (WRA)** authorizes a change of the active **Common Witness Emitter** while preserving:
|
||
|
||
* single linear Common history
|
||
* offline operation
|
||
* auditability
|
||
* fork prevention
|
||
|
||
The WRA is the **only mechanism** by which witness authority may change.
|
||
|
||
---
|
||
|
||
## 2. Scope and guarantees
|
||
|
||
This artifact:
|
||
|
||
* does **not** modify artifacts, blocks, or snapshots directly
|
||
* authorizes **who may emit the next Common snapshot**
|
||
* is snapshot-bound and immutable
|
||
* is evaluated **only by ASL-HOST instances handling the Common domain**
|
||
|
||
---
|
||
|
||
## 3. Definitions
|
||
|
||
| Term | Meaning |
|
||
| --------------------- | ------------------------------------------------------ |
|
||
| **Witness Emitter** | The domain authorized to emit the next `common@N+1` |
|
||
| **Witness Authority** | A domain whose key may endorse witness changes |
|
||
| **Quorum** | A threshold of valid endorsements |
|
||
| **Rotation Snapshot** | The first snapshot emitted under new witness authority |
|
||
|
||
---
|
||
|
||
## 4. Artifact identity
|
||
|
||
**Artifact type:** `asl.common.witness-rotation`
|
||
**Artifact key:** content-addressed (CAS)
|
||
**Visibility:** published (Common domain only)
|
||
|
||
---
|
||
|
||
## 5. Canonical structure (logical)
|
||
|
||
```yaml
|
||
artifact_type: asl.common.witness-rotation
|
||
version: 0.1
|
||
|
||
common_domain_id: <domain-id>
|
||
|
||
previous_snapshot:
|
||
snapshot_id: common@N
|
||
snapshot_hash: <hash>
|
||
|
||
rotation:
|
||
old_witness:
|
||
domain_id: <domain-id>
|
||
pubkey_id: <key-id>
|
||
|
||
new_witness:
|
||
domain_id: <domain-id>
|
||
pubkey_id: <key-id>
|
||
|
||
policy_ref:
|
||
artifact_key: <common-policy-artifact>
|
||
|
||
reason: <utf8-string, optional>
|
||
|
||
endorsements:
|
||
threshold: <uint>
|
||
endorsements:
|
||
- domain_id: <domain-id>
|
||
pubkey_id: <key-id>
|
||
signature: <bytes>
|
||
- ...
|
||
|
||
created_at_logseq: <uint64>
|
||
```
|
||
|
||
---
|
||
|
||
## 6. Cryptographic requirements
|
||
|
||
### 6.1 Endorsement signature
|
||
|
||
Each endorsement signs **exactly**:
|
||
|
||
```
|
||
H(
|
||
artifact_type
|
||
|| version
|
||
|| common_domain_id
|
||
|| previous_snapshot.snapshot_id
|
||
|| previous_snapshot.snapshot_hash
|
||
|| new_witness.domain_id
|
||
|| new_witness.pubkey_id
|
||
|| policy_ref.artifact_key
|
||
)
|
||
```
|
||
|
||
* Hash function: same as ASL block hash
|
||
* Signature scheme: per ASL-AUTH (e.g. Ed25519)
|
||
|
||
---
|
||
|
||
## 7. Validation rules (normative)
|
||
|
||
An ASL-HOST **MUST accept** a witness rotation artifact if and only if:
|
||
|
||
1. `previous_snapshot` matches the current trusted Common snapshot
|
||
2. All endorsement signatures are valid
|
||
3. Endorsing keys are authorized by the referenced policy
|
||
4. Endorsement count ≥ policy quorum threshold
|
||
5. `new_witness` is not revoked in policy
|
||
6. Artifact hash matches CAS key
|
||
|
||
Otherwise the artifact **MUST be rejected**.
|
||
|
||
---
|
||
|
||
## 8. Application semantics
|
||
|
||
### 8.1 When applied
|
||
|
||
The WRA does **not** immediately advance Common.
|
||
|
||
It becomes effective **only when a snapshot is emitted** by `new_witness`.
|
||
|
||
---
|
||
|
||
### 8.2 Rotation snapshot
|
||
|
||
The first snapshot emitted by the new witness:
|
||
|
||
```
|
||
common@N+1
|
||
```
|
||
|
||
MUST include:
|
||
|
||
```yaml
|
||
witness:
|
||
domain_id: <new_witness.domain_id>
|
||
pubkey_id: <new_witness.pubkey_id>
|
||
rotation_artifact: <artifact_key>
|
||
```
|
||
|
||
This snapshot:
|
||
|
||
* seals the rotation
|
||
* permanently records authority transfer
|
||
* invalidates emissions by the old witness
|
||
|
||
---
|
||
|
||
## 9. Failure and recovery semantics
|
||
|
||
### 9.1 Old witness emits after rotation
|
||
|
||
Such snapshots:
|
||
|
||
* MUST be rejected
|
||
* MUST NOT be indexed
|
||
* MAY be retained as foreign artifacts for audit
|
||
|
||
---
|
||
|
||
### 9.2 New witness fails before emitting
|
||
|
||
Rotation remains **pending**.
|
||
|
||
Quorum may:
|
||
|
||
* re-endorse another WRA
|
||
* or extend grace period (policy-defined)
|
||
|
||
No fork occurs.
|
||
|
||
---
|
||
|
||
## 10. Interaction with snapshots and CURRENT
|
||
|
||
* CURRENT resolution **MUST consider only the active witness**
|
||
* Snapshot ordering remains strictly monotonic
|
||
* Rotation artifacts do **not** affect artifact visibility
|
||
|
||
---
|
||
|
||
## 11. Minimal policy requirements
|
||
|
||
The referenced Common policy artifact MUST define:
|
||
|
||
```yaml
|
||
witness_policy:
|
||
authorities:
|
||
- domain_id
|
||
- pubkey_id
|
||
quorum_threshold: uint
|
||
rotation_allowed: true
|
||
```
|
||
|
||
---
|
||
|
||
## 12. Security properties
|
||
|
||
This design guarantees:
|
||
|
||
* **No split-brain:** only one valid witness at a time
|
||
* **Offline survivability:** endorsements are asynchronous
|
||
* **Auditability:** every rotation is permanently recorded
|
||
* **Revocability:** compromised witnesses can be replaced
|
||
|
||
---
|
||
|
||
## 13. Why this fits ASL cleanly
|
||
|
||
* Rotation is an **artifact**
|
||
* Authority is **data**, not code
|
||
* History is **explicit**, not inferred
|
||
* No special network protocol required
|
||
|
||
---
|
||
|
||
## 14. One-sentence invariant (the one to remember)
|
||
|
||
> **A Common snapshot is valid if and only if its witness authority is provable from the previous snapshot.**
|
||
|
||
---
|
||
|
||
If you want next, we can:
|
||
|
||
* formalize the **Common Policy Artifact**
|
||
* define the **recovery-from-silence** artifact
|
||
* specify how ASL-HOST enforces witness authority at boot
|
||
* or walk through a concrete rotation with real keys and USB transfers
|
||
|
||
This piece is now solid.
|
||
|