enprot 0.5.8

Engyon Protected Text (EPT) — confidentiality processor and capability ledger
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126

# ExtField Schema Specification

**Version**: 1.0  
**Status**: Normative  
**Scope**: Typed ExtField wire format for EPT directives

## 1. Overview

ExtFields are metadata key:value pairs that appear inside EPT
directives. They carry self-describing parameters so encrypted blobs
and anchor blocks are fully self-contained.

This spec defines the typed schema for both:
- **EncryptedExtField** — fields on ENCRYPTED segments
- **AnchorExtField** — fields on CHAIN/anchor segments

## 2. Wire Format

ExtFields appear as space-separated `key:value` pairs after the WORD
and optional hash in a directive:

```
// <( ENCRYPTED <word> <hash>? <extfield>* )>
```

Values are URL-encoded. Unknown keys are preserved as `Unknown(key,
value)` for forward compatibility.

## 3. EncryptedExtField

Typed enum for fields on ENCRYPTED segments.

### Variants

| Variant           | Wire key       | Value format                        |
|-------------------|---------------|-------------------------------------|
| `Pbkdf`           | `pbkdf`       | PHC string ($argon2id$... or $pbkdf2-...) |
| `Cipher`          | `cipher`      | Algorithm name (e.g., `aes-256-gcm-siv`) |
| `Recipients`      | `recipients`  | Comma-separated fingerprints        |
| `RecipientMlKemCt`| `r:<fp>`      | Base64 ML-KEM ciphertext for recipient |
| `Attribute`       | `attr:<name>` | URL-encoded attribute value         |
| `Unknown`         | `<any>`       | Preserved verbatim                  |

### Example

```
pbkdf:$argon2id$v=19$m=65536,t=3,p=1$c2FsdA$<hash>
cipher:aes-256-gcm-siv
recipients:abc123,def456
r:abc123:<base64-mlkem-ct>
attr:classification:confidential
```

### Round-Tip

`into_entry()` / `from_entry()` convert between the typed enum and
the wire-format `(key, value)` pair. Unknown keys round-trip through
the `Unknown` variant without data loss.

## 4. AnchorExtField

Typed enum for fields on CHAIN/anchor segments.

### Variants

| Variant    | Wire key     | Value format                         |
|------------|-------------|--------------------------------------|
| `Signer`   | `signer`    | Single key fingerprint               |
| `Signers`  | `signers`   | Comma-separated fingerprints         |
| `Payload`  | `payload`   | Hex SHA3-256 of the payload          |
| `Sig`      | `sig`       | Base64 signature (single signer)     |
| `Sigs`     | `sigs`      | Comma-separated base64 signatures    |
| `Parents`  | `parents`   | Comma-separated hex parent hashes    |
| `Timestamp`| `ts`        | Unix timestamp (seconds)             |
| `Mutation` | `mut`       | Mutation type (create/update/delete) |
| `Unknown`  | `<any>`     | Preserved verbatim                   |

### Example

```
signer:abc123def456
sig:<base64-signature>
parents:a1b2c3d4,e5f6g7h8
ts:1722259200
mut:create
```

## 5. Versioning Strategy

- **Forward compatibility**: Unknown keys are preserved as
  `Unknown(String, String)`. New fields added by future versions are
  not lost when round-tripped through older code.
- **Backward compatibility**: Old field names continue to work.
  Renamed fields map both old and new names to the same variant.
- **No version number in wire format**: The schema is identified by
  the key names themselves. Adding new keys is non-breaking.

## 6. Implementation

The typed enums are in `src/extfield.rs`:

```rust
pub enum EncryptedExtField {
    Pbkdf(String),
    Cipher(String),
    Recipients(Vec<String>),
    RecipientMlKemCt { fp: String, ct: Vec<u8> },
    Attribute { name: String, value: String },
    Unknown(String, String),
}

pub enum AnchorExtField {
    Signer(String),
    Signers(Vec<String>),
    Payload(String),
    Sig(Vec<u8>),
    Sigs(Vec<Vec<u8>>),
    Parents(Vec<String>),
    Timestamp(u64),
    Mutation(String),
    Unknown(String, String),
}
```

Both enums implement `into_entry() -> (String, String)` and
`from_entry(key, value) -> Self` for wire-format conversion.