authkeep-jose — Authkeep Docs

The authkeep-jose crate handles all cryptographic operations for the SIG protocol. It provides Ed25519 key generation, JWS signing and verification using the Flattened JSON Serialization format, and JWK/JWKS key management. This crate depends on authkeep-core for shared types and uses ed25519-dalek for cryptographic primitives.

Key Types

Jwk

pub struct Jwk {
    pub kty: String,
    pub crv: String,
    pub kid: String,
    pub use_: String,
    pub alg: String,
    pub x: String, // base64url-encoded public key
}

Represents a JSON Web Key. SIG uses the OKP key type with the Ed25519 curve. The x field contains the base64url-encoded public key bytes. The kid (key ID) is used to match signatures to their verification key.

Jwks

pub struct Jwks {
    pub keys: Vec<Jwk>,
}

A JSON Web Key Set containing one or more public keys. Published by issuers at their JWKS URI and used by consumers to verify event signatures.

JwsProtectedHeader

pub struct JwsProtectedHeader {
    pub alg: String,
    pub kid: String,
    pub typ: String,
}

The protected header of a JWS envelope. The alg field must be EdDSA, kid identifies the signing key, and typ must be sig-event+jws.

VerifiedEnvelope

pub struct VerifiedEnvelope {
    pub header: JwsProtectedHeader,
    pub payload_json: Value,
}

The result of successfully verifying a JWS envelope. Contains the decoded protected header and the deserialized JSON payload, ready for further processing by authkeep-core.

JoseError

pub enum JoseError {
    InvalidBase64(String),
    InvalidJson(String),
    InvalidHeader(String),
    KeyNotFound(String),
    SignatureVerificationFailed,
    UnsupportedAlgorithm(String),
    // additional variants
}

Error type covering all failure modes in JWS and JWK operations.

Key Functions

generate_signing_key

pub fn generate_signing_key() -> SigningKey

Generates a new Ed25519 signing key using a cryptographically secure random number generator. The returned SigningKey (from ed25519-dalek) can be used for signing events and converted to a JWK for publication.

signing_key_to_jwk

pub fn signing_key_to_jwk(signing_key: &SigningKey, kid: impl Into<String>) -> Jwk

Extracts the public key from an Ed25519 signing key and encodes it as a JWK. The caller provides the kid value that will be used to reference this key in JWS headers and JWKS documents.

sign_payload

pub fn sign_payload(
    payload_bytes: &[u8],
    kid: &str,
    signing_key: &SigningKey,
) -> Result<JwsFlattenedEnvelope, JoseError>

Signs a JSON payload using Ed25519 and produces a JWS Flattened JSON Serialization envelope. Constructs the protected header with alg: "EdDSA", the provided kid, and typ: "sig-event+jws". The payload and header are base64url-encoded before signing per the JWS specification.

parse_envelope_line

pub fn parse_envelope_line(line: &str) -> Result<JwsFlattenedEnvelope, JoseError>

Parses a single line of JSON text into a JwsFlattenedEnvelope. Used when reading event feed files where each line contains one JWS-encoded event. Validates that the required protected, payload, and signature fields are present.

verify_envelope

pub fn verify_envelope(
    envelope: &JwsFlattenedEnvelope,
    jwks: &Jwks,
) -> Result<VerifiedEnvelope, JoseError>

Verifies a JWS envelope against a set of public keys. Decodes the protected header to extract the kid, looks up the corresponding key in the JWKS, and verifies the Ed25519 signature. Returns a VerifiedEnvelope containing the decoded header and payload on success.

verify_and_decode_event

pub fn verify_and_decode_event(
    envelope: &JwsFlattenedEnvelope,
    jwks: &Jwks,
) -> Result<EventPayload, JoseError>

Convenience function that combines signature verification with event payload parsing. Verifies the envelope, then passes the decoded payload JSON to authkeep-core’s parse_event_payload to produce a typed EventPayload. This is the primary entry point for consumers processing feed events.