aarondb/envelope

envelope — canonical Ed25519-signed generic facts and events

EnvelopeV1 has deliberately boring bytes: a fixed tag/version followed by length-delimited fields in this exact order. The unsigned frame is hashed with its domain and then signed. It is unrelated to local capability auth.

Types

Envelope

pub type Envelope {
  Envelope(
    version: Int,
    domain: String,
    payload: BitArray,
    payload_hash: BitArray,
    author: BitArray,
    parents: List(BitArray),
    logical_clock: Int,
    key_epoch: Int,
    signature: BitArray,
  )
}

Constructors

Envelope(
  version: Int,
  domain: String,
  payload: BitArray,
  payload_hash: BitArray,
  author: BitArray,
  parents: List(BitArray),
  logical_clock: Int,
  key_epoch: Int,
  signature: BitArray,
)

EnvelopeError

pub type EnvelopeError {
  UnsupportedVersion(Int)
  WrongDomain(expected: String, actual: String)
  InvalidPayloadHash
  InvalidSignature
  UnknownAuthor
  InactiveKey
  RevokedKey
  WrongKeyEpoch(expected: Int, actual: Int)
  FrameTooLarge(actual: Int, maximum: Int)
  TooManyParents(actual: Int, maximum: Int)
  NegativeLogicalClock
}

Constructors

```
UnsupportedVersion(Int)
```

WrongDomain(expected: String, actual: String)

```
InvalidPayloadHash
```
```
InvalidSignature
```
```
UnknownAuthor
```
```
InactiveKey
```
```
RevokedKey
```

WrongKeyEpoch(expected: Int, actual: Int)

FrameTooLarge(actual: Int, maximum: Int)

TooManyParents(actual: Int, maximum: Int)

```
NegativeLogicalClock
```

Key

pub type Key {
  Key(public_key: BitArray, state: KeyState)
}

Constructors

Key(public_key: BitArray, state: KeyState)

KeyState

pub type KeyState {
  Active(epoch: Int)
  Rotated(epoch: Int)
  Revoked
}

Constructors

```
Active(epoch: Int)
```
```
Rotated(epoch: Int)
```
```
Revoked
```

Keyring

pub type Keyring {
  Keyring(
    keys: List(Key),
    maximum_frame_bytes: Int,
    maximum_parents: Int,
  )
}

Constructors

Keyring(
  keys: List(Key),
  maximum_frame_bytes: Int,
  maximum_parents: Int,
)

Values

canonical_bytes

pub fn canonical_bytes(envelope: Envelope) -> BitArray

new_keyring

pub fn new_keyring(
  maximum_frame_bytes: Int,
  maximum_parents: Int,
) -> Keyring

payload_digest

pub fn payload_digest(payload: BitArray) -> BitArray

public_key

pub fn public_key(private_key: BitArray) -> BitArray

put_key

pub fn put_key(keyring: Keyring, key: Key) -> Keyring

Adding the same public key replaces its lifecycle state; no map ordering is involved in either key lookup or canonical envelope bytes.

revoke

pub fn revoke(keyring: Keyring, public_key: BitArray) -> Keyring

sign

pub fn sign(
  domain: String,
  payload: BitArray,
  author_private_key: BitArray,
  parents: List(BitArray),
  logical_clock: Int,
  key_epoch: Int,
) -> Envelope

verify

pub fn verify(
  envelope: Envelope,
  domain: String,
  keyring: Keyring,
) -> Result(Nil, EnvelopeError)

Verification binds the requested application domain as well as the exact unsigned frame. A valid signature for another domain is not reusable here.

version_v1

pub const version_v1: Int