# Cryptographic Design

*"Choose boring cryptography. Interesting cryptography is how you end up in a postmortem."*

## Overview

Aura's cryptographic surface is small, intentional, and drawn entirely from primitives with broad deployment history and mature Rust implementations. We do not invent. We do not roll our own. Every algorithm listed below has published peer review, reference implementations, and a track record of resisting sustained academic attention. This page documents the primitives, their parameters, the key lifecycle, and the design rationale. It is written for readers who want to verify — not trust — our choices.

Aura is developed by Naridon, Inc. and released under Apache 2.0. The cryptographic code paths are in open repositories; every claim below can be audited against the source.

## Threat Scope

The cryptographic layer addresses four concrete problems:

1. **Authenticity of intent** — prove that a given intent was authored by a specific identity and has not been altered since it was signed.
2. **Integrity of logic nodes** — prove that a function body retrieved from a peer is exactly the body the author signed off on.
3. **Confidentiality of transport** — prevent passive network observers from reading peer-to-peer traffic or capturing credentials.
4. **Authenticity of peer identity** — when a peer claims to be `alice@team`, bind that claim to a specific public key the Mothership has previously issued a credential for.

These problems are addressed by four distinct primitives, chosen to minimize the number of places where cryptographic failure translates into operational failure. See the full [threat model](/threat-model) for how these primitives compose against the adversary set.

## Mechanism

### Primitive selection

| Purpose | Primitive | Parameters | Rationale |
|---|---|---|---|
| Transport encryption | TLS 1.3 | `rustls` with `ring` backend; AEAD suites only | Mature, widely deployed, no CBC or RC4 legacy |
| Digital signatures | Ed25519 | RFC 8032, 32-byte public keys, deterministic | Fast, no nonce-reuse footgun, small signatures (64 bytes) |
| Content addressing | BLAKE3 | 256-bit output, default mode | Keyed-hash-capable, extremely fast, parallelizable |
| Token format | JWT with EdDSA (Ed25519) | RFC 8037 alg `EdDSA` | Signed, not encrypted — tokens carry no secrets |
| Password / passphrase hashing | Argon2id | m=64 MiB, t=3, p=4 | OWASP-recommended parameters for 2026 |
| CSRNG | OS-provided | `/dev/urandom` on Unix, `BCryptGenRandom` on Windows | Trust the kernel; don't reseed userspace |

There is deliberately no RSA, no ECDSA with non-deterministic nonces, no SHA-1 in any security-sensitive context, and no AES-CBC. The absence of these primitives is a feature.

### Transport: TLS 1.3

All network traffic in Aura — peer-to-peer sync, peer-to-Mothership control, MCP agent traffic — is wrapped in TLS 1.3. We restrict cipher suites to the AEAD-only subset defined by RFC 8446:

- `TLS_AES_256_GCM_SHA384`
- `TLS_CHACHA20_POLY1305_SHA256`
- `TLS_AES_128_GCM_SHA256`

TLS 1.2 and earlier are not accepted. The `rustls` library is used; OpenSSL is not a dependency of the core binary.

When a peer connects to another peer, certificate pinning is enforced: the expected certificate fingerprint is derived from the Mothership's directory and compared to the presented certificate. A mismatch is a hard failure; there is no fallback. This prevents on-path attackers from substituting their own certificate even if they have briefly compromised a public CA.

### Intent signatures: Ed25519

Every entry in the [intent log](/audit-trail) carries an Ed25519 signature over a canonical byte representation of `(timestamp, author_id, parent_hash, ast_delta_hash, intent_text)`. The signature is produced using the peer's identity key, which never leaves the peer machine.

Why Ed25519 and not ECDSA? Ed25519 is deterministic — the signature is a pure function of the message and private key, so there is no nonce to accidentally reuse. The deterministic construction eliminates an entire class of catastrophic failures (Sony PlayStation 3, various Bitcoin wallet bugs) caused by weak ECDSA nonce generation. Signatures are 64 bytes, verification is fast enough to run on every sync without noticeable overhead.

### Content addressing: BLAKE3

Every logic node — every function, class, module header — is identified by the BLAKE3 hash of its canonical AST representation. See [content-addressed logic](/content-addressed-logic) for the addressing scheme.

BLAKE3 was chosen over SHA-256 and SHA-3 for three reasons:

1. **Speed.** BLAKE3 is several times faster than SHA-256 on commodity hardware. Aura hashes every node on every commit; the performance difference is user-visible.
2. **Security margin.** BLAKE3 is a direct descendant of BLAKE2 (a SHA-3 finalist) with no cryptanalytic regressions.
3. **Keyed mode.** BLAKE3 supports keyed hashing natively, which we use for per-repository domain separation so that a logic node hash from repository A cannot be confused with an identical-looking node from repository B.

A 256-bit output is used throughout; truncation is not permitted.

### Join tokens: JWT with EdDSA

When a new peer joins a team, the Mothership issues a JWT. The token is *signed*, not *encrypted* — it carries no secrets, only a claim set. A captured token cannot be decrypted because there is nothing to decrypt; it can only be replayed, which is why tokens are tightly time-bounded and individually revocable.

A representative token payload:

```json
{
  "iss": "mothership://team.local",
  "sub": "peer-5f3a",
  "aud": "aura-peer",
  "iat": 1745251200,
  "exp": 1745254800,
  "jti": "tk_01J2ABCDEFGHJKMNPQ",
  "cap": ["read_logic", "write_logic", "commit", "push"],
  "role": "contributor"
}
```

- `exp - iat` defaults to one hour; configurable down to 5 minutes for high-security deployments.
- `jti` is a unique token ID the Mothership stores; revocation is by ID.
- `cap` is the capability set; see [agent permissions](/agent-permissions).

Revocation is handled by a revocation list the Mothership publishes to peers on every sync. A revoked `jti` is refused regardless of signature validity.

### Key lifecycle

**Mothership signing key.** Generated at first start using the OS CSRNG. Stored as a 32-byte seed in `$MOTHERSHIP_DATA/identity/signing.key`, permissions `0600`, owned by the Mothership service account. The corresponding public key is published at the Mothership's root URL and pinned by every peer at join time.

Rotation is supported via `aura mothership rotate-signing-key`. The rotation procedure:

1. Generate a new key pair.
2. Publish the new public key alongside the old, flagged as the successor.
3. Issue new join tokens under the new key.
4. After the configured grace window (default 14 days), retire the old key.

During the grace window both keys verify. Revocation lists continue to be signed by the old key until retirement, then by the new.

**Peer identity keys.** Generated on each peer at install time. Stored in `~/.aura/identity.toml`, permissions `0600`. The private key never leaves the peer. If a peer is decommissioned, `aura mothership revoke-peer <id>` invalidates the public key within the Mothership directory; subsequent connections presenting that identity are refused.

**Session keys.** TLS session keys are ephemeral, negotiated per connection, discarded on connection close. Forward secrecy is guaranteed by TLS 1.3's mandatory ECDHE key exchange.

### Canonicalization

Signatures are only meaningful if the bytes being signed are reproducible. Aura uses a strict canonical encoding for every signed structure:

- Fields in fixed order.
- Integers as unsigned little-endian.
- Strings as UTF-8 with NFC normalization.
- No floating-point values in signed structures.
- No optional whitespace or trailing bytes.

Canonicalization code is isolated in a single module (`aura-crypto/src/canon.rs`) and audited specifically. A change to canonicalization is a hard-fork event and requires a major version bump.

## Configuration

The cryptographic defaults are safe and most deployments should not change them. Where overrides are supported, they live in `aura.toml`:

```toml
[crypto]
# Token lifetime in seconds. Default 3600 (1h). Minimum 300.
join_token_ttl = 3600

# TLS minimum version. "1.3" only; "1.2" is refused by policy.
tls_min_version = "1.3"

# Peer certificate pinning — keep this on in production
require_peer_pinning = true

[crypto.rotation]
# Mothership signing key rotation grace period in days
signing_key_grace_days = 14
```

For high-security environments, shorten `join_token_ttl` to 600 (10 minutes) and pair with an automation that mints tokens on demand from the Mothership CLI. This reduces the exposure window of any captured token.

## Limitations

- **Post-quantum readiness.** Ed25519 and TLS 1.3 are not post-quantum. A cryptanalytic break of ECDLP would compromise signature authenticity retroactively. Aura's roadmap includes hybrid post-quantum signatures (Ed25519 + a NIST PQC selection) once the Rust ecosystem ships audited implementations. Content-addressed logic nodes (BLAKE3) are considered post-quantum secure under current assumptions.
- **No hardware-backed key storage by default.** Peer identity keys live on disk. Integration with platform secure enclaves (Apple Keychain, Windows DPAPI, Linux TPM via `tpm2-tss`) is supported via an optional feature flag but is not default. Deployments with elevated requirements should enable it.
- **No threshold signing.** The Mothership signing key is a single-party key. If your threat model requires an m-of-n signing arrangement (e.g., two admins must approve certain actions), that capability is on the roadmap but not currently shipped.
- **We do not publish FIPS-validated builds.** The underlying `ring` backend used by `rustls` has undergone FIPS validation in specific configurations, but Naridon does not currently distribute a FIPS-mode binary. Regulated deployments that require FIPS should build from source against a validated `ring` and pin accordingly.

## See Also

- [Threat model](/threat-model) — the adversaries these primitives resist
- [End-to-end encryption](/e2e-encryption) — transport details
- [Content-addressed logic](/content-addressed-logic) — BLAKE3 in context
- [Audit trail](/audit-trail) — how signatures compose into a log
- [Agent permissions](/agent-permissions) — capability tokens
- [Supply-chain integrity](/supply-chain-integrity) — reproducible builds and SBOMs
- [Incident response](/incident-response) — key rotation procedures