authkeep-client

The authkeep-client crate provides consumer-side operations for verifying SIG feeds, deriving relationship state, and performing authorization checks. It supports both remote feeds fetched over HTTP and local feeds loaded from disk. This crate depends on authkeep-core and authkeep-jose, and uses reqwest for HTTP operations.

Key Types

VerificationOutput

pub struct VerificationOutput {
    pub metadata: OreMetadata,
    pub state: FeedState,
    pub verified_events: usize,
}

The result of verifying a feed. Contains the parsed metadata, the fully derived FeedState after replaying all verified events, and a count of how many events were successfully verified.

CheckDecision

pub enum CheckDecision {
    Allow,
    Deny,
}

The binary outcome of an authorization check. Allow indicates the subject meets the specified requirements; Deny indicates they do not.

CheckRequirement

pub enum CheckRequirement {
    Relationship(String),
    Role(String),
}

A single condition that must be satisfied for an authorization check to pass. Relationship matches against the relationship_type field, while Role matches against values in the relationship roles array.

CheckOutput

pub struct CheckOutput {
    pub decision: CheckDecision,
    pub subject: String,
    pub requirements: Vec<String>,
    pub matched_relationship_id: Option<String>,
    pub last_sequence: u64,
}

Detailed output from an authorization check. Includes the decision, the subject that was checked, the requirements that were evaluated, the ID of the matching relationship (if any), and the feed’s last sequence number at the time of the check.

CheckResult

pub struct CheckResult {
    pub output: CheckOutput,
    pub explain: Vec<String>,
}

Wraps CheckOutput with an explanation trace. The explain field contains human-readable strings describing each step of the decision evaluation, useful for debugging and audit logging.

ClientError

pub enum ClientError {
    IssuerMismatch { payload: String, metadata: String },
    SequenceIntegrity { line: usize, got: u64, expected: u64 },
    DidWebHostMismatch { issuer_host: String, metadata_host: String },
    MetadataAlgorithmMismatch { alg: String },
    Jose(/* ... */),
}

Error type covering all failure modes in client operations, from HTTP fetch failures to cryptographic verification errors.

Key Functions

verify_registry

pub fn verify_registry(ore_metadata_uri: &str) -> Result<VerificationOutput>

Performs end-to-end verification of a remote SIG feed. This function:

1. Fetches the sig-metadata.json from the provided URI.
2. Resolves and fetches the JWKS from the URI specified in the metadata.
3. Validates the did:web binding between the domain, the DID document, and the JWKS.
4. Fetches the events file from the URI specified in the metadata.
5. Parses each line as a JWS envelope and verifies signatures against the JWKS.
6. Replays all verified events through authkeep-core’s state reducer to derive the current feed state. Returns a VerificationOutput containing the full derived state.

verify_materialized_feed

pub fn verify_materialized_feed(
    metadata: OreMetadata,
    jwks: Jwks,
    events_text: &str,
) -> Result<VerificationOutput>

Verifies a feed from pre-loaded data rather than fetching over HTTP. Useful for local file verification, testing, and environments without network access. Accepts the metadata, JWKS, and raw events text directly. Performs the same signature verification and state replay as verify_registry.

check_registry

pub fn check_registry(
    ore_metadata_uri: &str,
    subject: &str,
    requirements: &[CheckRequirement],
) -> Result<CheckResult>

Performs an authorization check against a remote SIG feed. Fetches and verifies the feed, then evaluates whether the specified subject has an active relationship matching any of the provided requirements. The decision logic works as follows:

• The feed is fully verified and the state is derived.
• All active (non-revoked, non-expired) relationships for the given subject are collected.
• Each requirement is checked against the active relationships.
• If all requirements match an active relationship, the decision is Allow and the matching relationship ID is recorded.
• If no requirements match, the decision is Deny.
• Each evaluation step is recorded in the explain trace for transparency.

parse_check_requirement

pub fn parse_check_requirement(
    input: &str,
) -> Result<CheckRequirement, RequirementParseError>

Parses a string into a CheckRequirement. Accepts two formats:

• relationship=<type> — creates a CheckRequirement::Relationship matching the given type (e.g., relationship=employee).
• role=<name> — creates a CheckRequirement::Role matching the given role name (e.g., role=engineering). Returns a RequirementParseError if the input does not match either format.

HTTP and Local File Loading

The client supports two modes of operation:

• Remote (HTTP): verify_registry and check_registry fetch all resources over HTTPS using reqwest. URIs are resolved relative to the metadata document’s location.
• Local: verify_materialized_feed accepts pre-loaded data, allowing verification of feeds stored on disk or bundled in applications. This is also the path used by the CLI’s verify command when given a local directory.

did:web Binding Validation

During verification, the client validates did:web host consistency:

• metadata URL host must match issuer DID host (for remote metadata URLs)
• jwks_uri and events_uri hosts must also match issuer DID host If host binding fails, verification stops with a host mismatch error.