Module api_token 

Local API token: generation, reading, and atomic 0600 writes.

Token format: <issued-at unix seconds>.<64 lowercase hex chars>. The issue timestamp is embedded in the token itself — file mtime is NOT trusted, because copies, backup restores, and sync tools all rewrite it. The daemon owns generation and rotation; local clients (beam CLI) only read the file and send the token verbatim as an Authorization: Bearer credential. Validity is an exact string match against daemon state, so a tampered timestamp never authenticates.

Constants

SIG_HEADER

Header carrying the hex HMAC-SHA256 signature.

SIG_NONCE_HEADER

Header carrying the per-request nonce.

SIG_TIMESTAMP_HEADER

Header carrying the signature timestamp (unix seconds).

SIG_WINDOW_SECS

Maximum accepted clock skew between signer and verifier, in seconds.

Functions

generate_api_token

Generate a new local API token issued at the current time.

generate_api_token_at

Generate a token for an explicit issue time (tests, clock control).

generate_sig_nonce

Generate a random per-request signature nonce.

now_unix_secs

Current wall-clock time as unix seconds.

parse_api_token

Parse a token into (issued_at_unix, secret). Returns None for malformed tokens — including legacy plain-hex tokens without a timestamp, which the daemon then treats as stale and rotates out.

read_api_token

Read the current token from disk. Returns None when the file is missing, unreadable, or empty.

sign_request

Compute the hex HMAC-SHA256 signature for one request.

signature_payload

Canonical string that gets HMAC-signed for one request. path_query is the request path with query string (e.g. /sessions/abc/input?x=1).

verify_request_signature

Constant-time verification of a presented hex signature.

write_api_token

Atomically write the token (tmp + rename) with 0600 permissions on Unix.