bots-go-framework / bots-fw / 29491236810

27%

Build Type

push

github

Committed by trakhimenok

Commit Message

feat(botstoken): add compact token codec with HMAC-signed variant for off-platform tokens

New package botstoken implements the (verb, subject, args) token codec
described in architecture.md §4.3 (SYS-CB-010).

Plain codec:
- Encode(verb, subject, args) -> tab-delimited wire format with sorted args
- Decode(token) -> Token{Verb, Subject, Args}
- Enforces a 64-byte limit (ErrTokenTooLong if exceeded) so tokens fit
  in Telegram callback_data and WhatsApp interactive reply ID fields
- Args are sorted by key, making output deterministic across calls

Signed codec (for tokens leaving the platform — web deep links, wa.me URLs):
- EncodeSignedToken(verb, subject, args, now, KeyProvider) -> base64url string
- DecodeSignedToken(token, maxAge, KeyProvider) -> Token (or error)
- HMAC-SHA256 over the payload before the sig field is added, with a
  hex-encoded signature appended as the "sig" arg
- Issued-at timestamp stored as "at" (unix seconds); expiry checked on decode
- Key rotation supported via the KeyProvider interface (SigningKey / VerifyingKey)
- Internal fields (sig, at, kid) are stripped from the returned Token.Args
- Signed tokens carry authentication overhead and are not subject to the
  64-byte plain-codec limit; callers control token length via input length

Errors: ErrTokenTooLong, ErrInvalidToken, ErrTokenExpired, ErrInvalidSignature

16 table-driven tests covering: simple/args encoding, exact-64-byte boundary,
over-64 rejection, round-trip decode, empty/malformed inputs, signed round-trip,
determinism, expiry, tamper detection (modified payload), unknown key ID, invalid
base64, and confirmation that signed tokens are not length-limited.

Coverage Stats

115 of 129 new or added lines in 1 file covered. (89.15%)

78 existing lines in 1 file now uncovered.

1483 of 5689 relevant lines covered (26.07%)

0.3 hits per line