Struct CodeAuth 

pub struct CodeAuth<CS, RL, K, C, A> { /* private fields */ }

Manages one-time code issuance, validation, and redemption (RFC-013 §3).

Generic over:

• CS — the CodeStore backend;
• RL — the RateLimitStore backend (use () to opt out);
• K — the KeyProvider;
• C — the Clock;
• A — the AuditSink.

Implementations

impl<CS, RL, K, C, A> CodeAuth<CS, RL, K, C, A>

where CS: CodeStore, RL: RateLimitStore, K: KeyProvider, C: Clock, A: AuditSink,

pub fn new( store: CS, rate_limit_store: RL, hasher: SecretHasher<K>, clock: C, audit: A, policy: CodePolicy, rate_limit_policy: RateLimitPolicy, ) -> Self

Construct a CodeAuth with a rate-limit store and policy.

pub async fn issue_code<R: RandomSource>( &self, rng: &mut R, id: CodeId, purpose: Option<String>, scope: Option<String>, grant: Option<String>, ) -> Result<(CodeId, PlainCode), RedeemError>

Issue a new one-time code and insert it into the store.

Returns the CodeId (for audit/admin) and the plaintext code (for delivery to the recipient). The plaintext must not be logged or stored.

rng must be a fresh CSPRNG; ttl overrides the policy TTL if needed. scope and grant are host-owned and not interpreted by codlet.

Errors

Returns RedeemError::Internal if the RNG or store fails.

pub async fn find( &self, raw_input: &str, rate_key: Option<&RateLimitKey>, ) -> Result<RedeemableCode, RedeemError>

Step 1: validate and look up a submitted code without claiming it.

Returns a RedeemableCode that the caller can inspect (e.g. to display a confirmation or collect additional user input) before committing the claim in Self::claim.

Rate limiting is applied here if configured.

Errors

Returns RedeemError on validation failure, rate limit, or lookup miss.

pub async fn claim( &self, record: &RedeemableCode, subject: SubjectId, rate_key: Option<&RateLimitKey>, ) -> Result<RedeemSuccess, RedeemError>

Step 2: atomically claim a RedeemableCode found by Self::find.

Returns a RedeemSuccess proof only if claim_code returns Won. A Lost result means a concurrent caller already claimed the code.

Rate-limit failures are recorded on a failed claim, and cleared on a successful one, when a rate_key is provided.

Errors

Returns RedeemError::ClaimLost if the atomic claim was lost, or RedeemError::Internal on store failure.

pub async fn redeem_with_callback<F, Fut, E>( &self, raw_input: &str, rate_key: Option<&RateLimitKey>, on_won: F, ) -> Result<RedeemSuccess, RedeemError>

where F: FnOnce(&RedeemableCode) -> Fut, Fut: Future<Output = Result<SubjectId, E>>, E: Display,

👎Deprecated:

experimental: DB and audit state diverge if callback fails. Use find() + host subject creation + claim() for production.

Validate, look up, and claim a code in one call, invoking on_won as the host callback that creates or resolves the subject.

Enforces RFC-013 §10.3 step order. on_won is called only after a confirmed won claim; its error aborts the flow without a session.

Errors

Returns RedeemError on any failure. If on_won fails, returns RedeemError::Internal and the claim is already consumed (the host must decide on compensation if needed — RFC-013 §5).

Production warning

Experimental (RFC-D). This method claims the code before the host callback returns the real subject, leaving used_by_subject = "__pending__" in the database until the callback completes. If the callback fails, the code is permanently consumed with no subject recorded, and the audit event and database state disagree on who claimed it.

For production audit-sensitive deployments, use the explicit two-step flow: Self::find → host creates/resolves subject → Self::claim.

pub async fn revoke_code( &self, code_id: &CodeId, scope: Option<&str>, ) -> Result<(), RedeemError>

Revoke a code by its record ID. Scoped to scope when provided.

Errors

Returns RedeemError::Internal on store failure.

impl<CS, K, C, A> CodeAuth<CS, NoRateLimit, K, C, A>

where CS: CodeStore, K: KeyProvider, C: Clock, A: AuditSink,

Convenience impl: construct a CodeAuth with no rate-limit store.

Uses NoRateLimit as the RL type parameter so callers don’t need to spell out the full generic signature when rate limiting is handled elsewhere.

pub fn without_rate_limit( store: CS, hasher: SecretHasher<K>, clock: C, audit: A, policy: CodePolicy, ) -> Self

Construct without a rate-limit store. Equivalent to passing NoRateLimit explicitly.