authkeep-core

The authkeep-core crate defines the SIG data model, validation rules, and the deterministic state reducer that replays verified events into derived relationship state. It has no internal crate dependencies and avoids cryptographic or I/O concerns.

Constants

pub const SPEC_VERSION: &str = "sig/0.1";
pub const JWS_TYP: &str = "sig-event+jws";

• SPEC_VERSION is embedded in every feed’s metadata and checked during verification.
• JWS_TYP is the required typ value in JWS protected headers for SIG events.

Enums

Visibility

pub enum Visibility {
    Public,
    Private,
}

Determines whether a feed is publicly accessible or restricted to authenticated consumers.

RelationshipType

pub enum RelationshipType {
    Employee,
    Founder,
    Contractor,
    Advisor,
    Investor,
    AdminDelegate,
    Other(String),
}

Categorizes the nature of the organizational relationship. The Other variant allows custom relationship types using a freeform string.

DerivedStatus

pub enum DerivedStatus {
    Active,
    Revoked,
    Expired,
}

The computed status of a relationship after replaying all events and evaluating expiration timestamps.

EventPayload

pub enum EventPayload {
    Upsert(RelationshipUpsertEvent),
    Revoke(RelationshipRevokeEvent),
    Unknown,
}

Discriminated union of the supported event types. Unknown represents event types not recognized by the current version, enabling forward-safe evolution.

Structs

CommonEventFields

pub struct CommonEventFields {
    pub spec: String,
    pub event_id: String,
    pub event_type: String,
    pub issued_at: OffsetDateTime,
    pub issuer_did: String,
    pub subject: String,
    pub sequence: u64,
}

Fields shared by all event types. The sequence field provides a monotonically increasing counter for ordering and replay.

DisplayHints

pub struct DisplayHints {
    pub issuer_name: Option<String>,
    pub issuer_logo_uri: Option<String>,
    pub subject_name: Option<String>,
    pub subject_title: Option<String>,
    pub subject_department: Option<String>,
}

Optional display metadata for presenting relationships in user interfaces. These fields are informational and do not affect protocol logic.

RelationshipUpsertEvent

pub struct RelationshipUpsertEvent {
    pub common: CommonEventFields,
    pub relationship_type: RelationshipType,
    pub relationship_id: String,
    pub visibility: Visibility,
    pub display: Option<DisplayHints>,
    pub expires_at: Option<OffsetDateTime>,
}

Creates or updates a relationship between an issuer and a subject.

RelationshipRevokeEvent

pub struct RelationshipRevokeEvent {
    pub common: CommonEventFields,
    pub relationship_id: String,
    pub reason: Option<String>,
}

Revokes a previously established relationship by its relationship_id.

JwsFlattenedEnvelope

pub struct JwsFlattenedEnvelope {
    pub protected: String,
    pub payload: String,
    pub signature: String,
}

The JWS Flattened JSON Serialization format used to encode signed events in feed files.

OreMetadata

pub struct OreMetadata {
    pub spec: String,
    pub issuer_did: String,
    pub jwks_uri: String,
    pub events_uri: String,
    pub feed_type: String,
}

The sig-metadata.json document that bootstraps feed discovery and verification.

VerifiedEvent

pub struct VerifiedEvent {
    pub payload: EventPayload,
    pub kid: String,
}

An event whose JWS signature has been verified against the issuer’s JWKS. Carries the decoded payload and the key ID used for signing.

DerivedRelationshipState

pub struct DerivedRelationshipState {
    pub relationship_id: String,
    pub relationship_type: RelationshipType,
    pub subject: String,
    pub status: DerivedStatus,
    pub display: Option<DisplayHints>,
    pub expires_at: Option<OffsetDateTime>,
    pub last_sequence: u64,
}

The computed state of a single relationship after applying all relevant events.

FeedState

pub struct FeedState {
    pub relationships: HashMap<String, DerivedRelationshipState>,
    pub last_sequence: u64,
    pub event_ids: HashSet<String>,
}

The aggregate state of an entire feed, tracking all derived relationships, the most recent sequence number, and a set of processed event IDs for deduplication.

Error Types

ValidationError

Returned when an event payload fails structural or semantic validation. Includes details about which field or constraint was violated.

ReplayError

Returned when the state reducer encounters an inconsistency during event replay, such as a sequence gap, duplicate event ID, or an attempt to revoke a non-existent relationship.

Key Functions

parse_event_payload

pub fn parse_event_payload(payload: Value) -> Result<EventPayload, ValidationError>

Parses a raw JSON value into a typed EventPayload. Determines the event type from the event_type field and deserializes into the corresponding struct. Returns EventPayload::Unknown for unrecognized event types rather than failing.

validate_event

pub fn validate_event(payload: &EventPayload, public_feed: bool) -> Result<(), ValidationError>

Validates an event payload against the SIG specification rules. Checks required fields, format constraints, and feed-type-specific rules. The public_feed flag controls whether public feed restrictions (such as visibility constraints) are enforced.

replay_verified_events

pub fn replay_verified_events(
    state: &mut FeedState,
    events: &[VerifiedEvent],
    now: Option<OffsetDateTime>,
    public_feed: bool,
) -> Result<(), ReplayError>

The deterministic state reducer. Applies a sequence of verified events to a FeedState, updating derived relationship states. Events must be in sequence order. The optional now parameter controls expiration evaluation; when None, the current system time is used. Rejects duplicate event IDs and enforces monotonic sequence ordering.