Skip to content

Tokens, signed URLs, and session URLs

The HTTP access token lifecycle and the two temporary-sharing URL schemes. The security semantics are in 10-security; storage is in 13-data-storage.

Tokens and revocation

HTTP access tokens are Branca tokens signed with the Site master token; their meaning at the proxy is in 10-security. The API contract:

  • POST /token/ requires duration (seconds, 1..2147483647) and identifier ([A-Za-z0-9._@-]+); permission is r or rw, compared after lowercasing. The code's default r only applies to a body that fails to parse, and such a request then fails the duration check: every successful creation carries an explicit permission. The response is {token} with the expiry embedded in the Branca payload.
  • POST /token/decode/ checks revocation first (403 for a revoked token), then returns {expiration, identifier, permission, valid} and records a last-use entry asynchronously.
  • DELETE /token/ accepts {token} or a 64-character {hash}; an unknown hash answers 404.
  • GET /token/history/ returns a per-token summary (not an event log), soonest expiry first, with status in active | expiring | expired | revoked; identifier, permission, and include_expired filter the query, while expiring_within only feeds the expiring computation of status and filters nothing. DELETE /token/history/ removes one entry by hash.
  • POST /token/history/backup/ writes a gzipped JSON snapshot beside the database and reports row count and checksum; POST /token/history/restore/ reads that file, replaces all rows, and rebuilds the filter (the read is capped at 64 MiB after decompression). The storage and recovery contract is in 13-data-storage.

Revocation is checked on every token decode: an in-memory Bloom filter (10 000 capacity, 0.1% false-positive rate) seeded from the SQLite history database at startup filters most lookups, and the database gives the authoritative answer (api/token_revocation_bloom.go, api/token_storage_sqlite.go). Only the decode path's last-use write is asynchronous: it goes through a bounded queue of 256 entries (four workers) and overflows are dropped with a warning. Token creation records nothing in the history; revocation writes its history row synchronously inside the request. A background job purges records older than a 7-day grace after expiry; it runs once at startup and then daily.

Deliberate trade-off: when the history database is unavailable, revocation fails open — the decode path treats the token as valid — while the history, backup, and revoke endpoints answer 503. The code records that this choice needs a broader design review before it changes.

Signed and session URLs

  • POST /signed-urls/ takes duration, url, and permission (r/rw), and returns the same URL with the s/signed/r/ or s/signed/rw/ prefix inserted and a base58 expiry signature (query changes do not invalidate the signature). POST /signed-urls/verify/ answers 204 for a valid URL and 403 for a tampered or expired one. The proxy's Lua layer calls verify during the access phase.
  • POST /session-urls/ takes duration, permission, a required identifier, and an optional path scope (default /, .. rejected), and returns a URL carrying the Branca token under s/session/. The scheme follows X-Forwarded-Proto with an https default. Verify answers 403 for a bad token, an expired token, or a request path outside the scope (sibling prefixes are rejected, not just .. escapes); on success it returns the token payload. The proxy calls verify for every session URL request.