Module auth 

Cryptographic identity for Joy’s Trust Model.

Auth provides passphrase-derived Ed25519 identity keys using Argon2id for key derivation. This is the Trustship pillar of AI Governance: it answers “who is this?” with cryptographic proof rather than self-declaration.

Key hierarchy:

Passphrase + Salt --[Argon2id]--> DerivedKey --[Ed25519]--> Keypair

Cryptographic primitives (KDF, AEAD, Ed25519, key wrapping) live in the joy-crypt crate (ADR-039 §“Crate boundary and dependency direction”). This module owns the identity application layer: sessions, tokens, OTPs, attestations, and the project.yaml schema.

Modules

attestation

Per-member attestation signing and verification.

delegation

Per-(operator, AI) delegation key derivation.

otp

One-time password generation and verification for member onboarding.

seed

Wrapped-seed identity helpers (ADR-039).

session

Session management for authenticated Joy operations.

token

AI delegation tokens with dual signatures (ADR-023, refined by ADR-033 and ADR-041).

Structs

DerivedKey

32-byte derived key material. Zeroed on drop.

IdentityKeypair

Ed25519 signing keypair. Private key is zeroed on drop (handled by ed25519-dalek’s internal Zeroize).

PublicKey

Ed25519 verification key. Stored in project.yaml as hex.

Salt

Random 32-byte salt. Stored per-member in project.yaml as hex.

UnlockedIdentity

Result of unlocking a member’s identity from a passphrase.

Constants

MIN_PASSPHRASE_WORDS

Minimum word count for a Joy passphrase. Diceware-style with Argon2id parameters Joy ships, three well-chosen words still give substantial brute-force resistance for the local-key-derivation threat model. See JOY-0171-50.

Functions

derive_key

Derive 32 bytes of key material from a passphrase and salt using Argon2id.

generate_salt

Generate a random 32-byte salt.

unlock_identity

Verify a passphrase against a member entry and return the resulting IdentityKeypair and seed. Handles both the wrapped-seed model (ADR-039) and the legacy model where the Argon2id-derived key is the Ed25519 seed.

validate_passphrase

Validate that a passphrase has at least MIN_PASSPHRASE_WORDS whitespace-separated words.