Hcs.Plug.Token

Signed and encrypted tokens for authentication.

Provides secure token generation and verification for auth tokens, password reset, email verification, etc.

Token format:

• signed: base64(data) . timestamp . base64(hmac)
• encrypted: base64(nonce + ciphertext + tag) . timestamp . base64(hmac)

type error = 
  | Expired (* Token has exceeded max_age *)
  | Invalid (* Token format invalid or signature mismatch *)
  | Tampered (* Token data has been modified *)

Error types for token operations

val error_to_string : error -> string

Internal helpers

val now : unit -> float

Get current Unix timestamp

val encode_timestamp : float -> string

Encode timestamp as compact varint-like format (8 bytes max)

val decode_timestamp : string -> float

Decode timestamp from bytes

val secure_compare : string -> string -> bool

Constant-time string comparison to prevent timing attacks

val hmac : key:string -> String.t -> string

Compute HMAC-SHA256

val b64_encode : string -> string

Base64 URL-safe encoding (no padding)

val b64_decode : string -> (string, [> `Msg of string ]) result

Base64 URL-safe decoding

Signed tokens

val sign : secret:string -> data:string -> max_age:'a -> string

Sign data with HMAC-SHA256.

Format: base64(data).base64(timestamp).base64(hmac)

The HMAC covers both data and timestamp to prevent replay attacks with modified timestamps.

parameter secret Shared secret key (should be at least 32 bytes) parameter data Payload to sign (arbitrary string) parameter max_age Maximum token age in seconds returns URL-safe signed token string

val verify : 
  secret:string ->
  token:string ->
  max_age:float ->
  (string, error) result

Verify a signed token.

parameter secret Shared secret key (must match signing key) parameter token The signed token to verify parameter max_age Maximum allowed age in seconds returns Ok(data) if valid, Error(reason) otherwise

Encrypted tokens

val encrypt : secret:String.t -> data:string -> max_age:'a -> string

Encrypt and sign data using AES-256-GCM.

Format: base64(nonce + ciphertext + tag).base64(timestamp).base64(hmac)

Encryption uses AES-256-GCM for authenticated encryption. The HMAC provides an additional layer of authentication over the encrypted blob and timestamp.

parameter secret Shared secret key (first 32 bytes for AES, full key for HMAC) parameter data Payload to encrypt parameter max_age Maximum token age in seconds returns URL-safe encrypted token string

val decrypt : 
  secret:String.t ->
  token:string ->
  max_age:float ->
  (string, error) result

Decrypt and verify an encrypted token.

parameter secret Shared secret key (must match encryption key) parameter token The encrypted token to decrypt parameter max_age Maximum allowed age in seconds returns Ok(data) if valid, Error(reason) otherwise

Convenience functions

val auth_token : secret:string -> user_id:string -> string

Create a signed auth token with user data. Default max_age is 24 hours (86400 seconds).

val reset_token : secret:String.t -> user_id:string -> string

Create an encrypted password reset token. Default max_age is 1 hour (3600 seconds). Encrypted so user cannot see/modify the payload.

val verify_auth : 
  secret:string ->
  token:string ->
  max_age:float ->
  (string, error) result

Verify an auth token, returning the user_id if valid.

val verify_reset : 
  secret:String.t ->
  token:string ->
  max_age:float ->
  (string, error) result

Verify a reset token, returning the user_id if valid.