Struct PairingGuard 

pub struct PairingGuard { /* private fields */ }

Manages pairing state for the gateway.

Bearer tokens are stored as SHA-256 hashes to prevent plaintext exposure in config files. When a new token is generated, the plaintext is returned to the client once, and only the hash is retained.

Implementations

impl PairingGuard

pub fn new(require_pairing: bool, existing_tokens: &[String]) -> Self

Create a new pairing guard.

If require_pairing is true and no tokens exist yet, a fresh pairing code is generated and printed to the terminal. Once paired, no code is generated on restart — operators can use generate_new_pairing_code() or the CLI to create one on demand.

Existing tokens are accepted in both forms:

• Plaintext (zc_...): hashed on load for backward compatibility
• Already hashed (64-char hex): stored as-is

pub fn pairing_code(&self) -> Option<String>

The one-time pairing code (generated only on first startup when no tokens exist).

pub fn require_pairing(&self) -> bool

Whether pairing is required at all.

pub async fn try_pair( &self, code: &str, client_id: &str, ) -> Result<Option<String>, u64>

Attempt to pair with the given code. Returns a bearer token on success. Returns Err(lockout_seconds) if locked out due to brute force. client_id identifies the client for per-client lockout accounting.

pub fn is_authenticated(&self, token: &str) -> bool

Check if a bearer token is valid (compares against stored hashes).

pub fn is_paired(&self) -> bool

Returns true if the gateway is already paired (has at least one token).

pub fn tokens(&self) -> Vec<String>

Get all paired token hashes (for persisting to config).

pub fn revoke_token(&self, token: &str) -> bool

Revoke a paired token by plaintext. Returns true if removed.

Test/convenience wrapper that hashes the plaintext, then defers to revoke_token_hash. Production revoke paths already hold the hash (the device registry stores it) and should call revoke_token_hash directly rather than re-hashing the plaintext.

In-memory only; the caller must persist tokens() to config or a restart will resurrect the token from disk.

pub fn revoke_token_hash(&self, token_hash: &str) -> bool

Revoke a paired token by its SHA-256 hash. Returns true if removed.

pub fn revoke_all_tokens(&self) -> usize

Revoke every paired token at once. Returns the number of tokens invalidated. This is the “rotate after compromise — nuke everything” path: when an operator does not know which token leaked, the only safe action is to invalidate all of them and force every client to re-pair. The caller must persist tokens() to config so a daemon restart does not resurrect the revoked set.

pub fn generate_new_pairing_code(&self) -> Option<String>

Generate a new pairing code that pairs an additional client.

Does not revoke existing tokens. To rotate a compromised token, pair with revoke_token/revoke_token_hash + a config persist pass.

pub fn generate_pairing_code_if_vacant( &self, ) -> Result<String, GeneratePairingCodeError>

Generate a new pairing code only when no code is already pending.

Returns Ok(code) on success, Err(GeneratePairingCodeError::Pending) when the slot is already occupied, and Err(GeneratePairingCodeError::PairingDisabled) when pairing is off. The check + write is atomic — concurrent callers cannot both observe the slot vacant and then both write into it.

pub fn token_hash(token: &str) -> String

Get the token hash for a given plaintext token (for device registry lookup).

pub fn authenticate_and_hash(&self, token: &str) -> Option<String>

Check if a token is paired and return its hash.

Trait Implementations

impl Clone for PairingGuard

fn clone(&self) -> PairingGuard

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for PairingGuard

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.