Module token 

Compact binary token format.

Wire format (big-endian)

  off  size  field
  ---  ----  -----
    0     2  magic                = 0xA9 0x1D
    2     1  version              = 0x01
    3     1  flags                = 0x00 (reserved)
    4     8  issued_at  (i64)
   12     8  expires_at (i64)
   20     4  max_calls  (u32, 0 = unlimited)
   24     8  token_id   (u64, random nonce)
   32    32  issuer_pubkey (Ed25519)
   64     1  name_len   (u8)
   65     N  name       (utf-8)
   65+N   1  project_len (u8)
   66+N   M  project    (utf-8)
   66+N+M 1  scope_count (u8)
        repeating scopes:
                 1  scope_len (u8)
                 K  scope     (utf-8)
    END  64  ed25519 signature over bytes [0..END)

Typical size: ~170-180 bytes for name="research-bot", two scopes, etc. That’s ~4-5x smaller than an equivalent JWT, with ~6x faster verification.

Why not JWT?

JWTs encode JSON twice (header + payload), use slow RSA/ECDSA defaults, omit rate limits, and require JWK discovery for key rotation. None of that helps machine-to-machine traffic. AgentID tokens are binary, Ed25519, self-contained, and fixed-overhead.

Structs

AgentClaims

Decoded token claims.

TokenBuilder

Fluent builder for tokens.

Enums

TokenError

Errors produced by the token layer.

Constants

DEFAULT_TTL_SECONDS

Default token TTL, in seconds (15 minutes).

HEADER_LEN

Bytes consumed by the fixed-size header (magic..issuer_pubkey).

MAGIC

Magic prefix — chosen for compactness and uniqueness vs. common formats.

MAX_TTL_SECONDS

Maximum allowed TTL, in seconds (24 hours). Tokens past this are usually a sign of misuse — long-lived credentials should live in the vault.

VERSION

Current wire-format version.

Functions

parse

Parse a token without verifying its signature or expiry. Useful for debugging; never trust the result for authorization.

verify

Parse + verify a token’s signature and expiry.