Documentation
¶
Overview ¶
Package sandboxtoken is the signed, scoped per-sandbox token (plans/agent-sandbox-feature-parity.md §5.9, A1): a credential an owner can hand to a browser or an end user that works for one sandbox only, optionally narrowed to one port, one path prefix and a set of methods, and that expires. It is checked with no database call: the signature and the claims are everything a node needs.
Format ¶
avmst_<kid>.<payload>.<sig>
kid is the decimal id of the server key that signed it, payload is the base64url (no padding) JSON of Claims, and sig is the base64url Ed25519 signature over "aerolvm-sandbox-token/v1\x00<kid>.<payload>". The kid is outside the payload so the signature is checked before any JSON is parsed; it is still covered by the signature.
Keys ¶
There is no key store of its own. The signing key is derived (HKDF-SHA256, its own label) from the server key ring that already seals secrets and keys the idempotency digests (pkg/secrets token_keys.go). Every node of a cluster holds the same ring, so every node derives the same key pair and verifies a token any node issued. A key-store revoke drops the ring, and with it every token: nothing signs or verifies until the key is back.
Threat model ¶
- A stolen token is a bearer credential for exactly its scope until it expires: one sandbox, and within it either the toolbox (no port: exec, files and sessions under the path prefix and methods) or one public port (port set: HTTP to that port's public URL, A2). A port token is refused at the toolbox and a toolbox token at a public port. It can never reach another sandbox, any other API route, or mint, extend or widen a token: POST /v1/sandboxes/{id}/tokens refuses a sandbox token. The issuer needed sandbox.exec on that sandbox, the most a token can grant, so a token never holds more than the person who issued it.
- There is no revocation list (that would be the database call this design avoids). A token dies at expiry, when its sandbox is deleted (the sandbox id no longer resolves), when the server key it was signed with is retired, or when its sandbox's tokens are revoked. Lifetimes are still short: expiry is required and capped by SB_SANDBOX_TOKEN_MAX_TTL (default 24h).
- Revoke is per sandbox, not per token: POST /v1/sandboxes/{id}/tokens/revoke stores a not-before second on the sandbox's row (NotBeforeAt), and every token issued before it is refused (CheckNotBefore). The check costs no extra read: the toolbox route already reads the row on the owner node, and a gated port reads it from the same warm-cache entry or row read as its gate. A new row (a create, a failover recreate on another node, a WASM migration) starts with a not-before of its creation, so a token from before it never reaches it: not a token for a deleted sandbox whose id was reused, nor one revoked on an owner that then died. A node that takes a placement back and reuses the row it kept from before raises that row to the takeover's time, so a token revoked on the owner in between stays refused there too.
- Replay inside the lifetime is by design: it is a bearer token, like a signed URL. It travels only over HTTPS (A2 refuses token visibility without a domain) and is never forwarded into the sandbox: the toolbox proxy replaces Authorization with the sandbox's own toolbox token, and the public port strips the cookie and the ?token= parameter.
- Expiry and clock skew: a node accepts a token from ClockSkew before its issue time to ClockSkew after its expiry, so two nodes whose clocks disagree by up to ClockSkew agree on it. A token whose lifetime is longer than the verifying node's cap is refused (too_long_lived), so a bug or a node with a larger cap cannot mint a token that outlives the operator's limit elsewhere.
- Key rotation: the current server key signs; every key the ring still holds (staged or the previous current key) verifies. A staged key never signs, because a node that has not read the staged ring yet could not check it. Retiring a key ends its tokens, so the rotation runbook waits SB_SANDBOX_TOKEN_MAX_TTL after a promote before the retire. An unknown key id is refused like a bad signature.
- Tampering: any change to the kid, payload or signature fails the Ed25519 check (Go's ed25519.Verify rejects non-canonical signatures, and the base64 decoding is strict, so one token has one encoding). No secret is ever compared byte by byte here, so there is no timing-sensitive comparison to make constant-time.
- Logging: the token string is never logged, put in an error, an audit record or a metric. Only its id (stk_…, the jti claim) is: the issue call's audit record names it, and a call made with a token records sandbox_token:<id> as its caller. Refusals say only the reason (malformed, invalid_signature, expired, not_yet_valid, too_long_lived, revoked) and, for a scope miss, which part (sandbox, port, path or method), never a claim value or a key id.
Index ¶
- Constants
- Variables
- func IsToken(raw string) bool
- func IssueTime(now time.Time, notBefore int64) time.Time
- func NewTokenID() (string, error)
- func NormalizeMethods(methods []string) ([]string, error)
- func NotBeforeAt(now time.Time) int64
- func PathCovered(prefix, p string) bool
- func ValidatePathPrefix(p string) error
- type Claims
- type KeySource
- type Request
- type ScopeError
- type Signer
Constants ¶
const ( MaxPathPrefixLen = 1024 MaxSandboxIDLen = 128 )
MaxPathPrefixLen and MaxSandboxIDLen bound the claims a caller can put in a token (and so the token's length).
const ( ScopeSandbox = "sandbox" ScopePort = "port" ScopePath = "path" ScopeMethod = "method" )
Scope parts a ScopeError names.
const ClockSkew = 30 * time.Second
ClockSkew is how far two nodes' clocks may disagree and still agree on a token's validity window.
const MaxTokenLen = 4096
MaxTokenLen bounds the work a forged token can cause before the signature check refuses it. A real token is a few hundred bytes.
const Prefix = "avmst_"
Prefix starts every sandbox token. It is distinct from avm_ API tokens and from a JWT, so the API edge routes a bearer to the right check without trying the others.
const TokenIDPrefix = "stk_"
TokenIDPrefix starts a token's public id: what audit records and logs name instead of the token.
Variables ¶
var ( ErrMalformed = errors.New("sandbox token: malformed") ErrInvalidSignature = errors.New("sandbox token: invalid signature") ErrExpired = errors.New("sandbox token: expired") ErrNotYetValid = errors.New("sandbox token: not yet valid") ErrTooLongLived = errors.New("sandbox token: lifetime is longer than this server allows") // ErrRevoked is a good token issued before its sandbox's tokens were // revoked (CheckNotBefore). ErrRevoked = errors.New("sandbox token: revoked") // ErrOutOfScope is a valid token used for a request it does not cover. // ScopeError says which part. ErrOutOfScope = errors.New("sandbox token: does not cover this request") )
Refusal reasons. Each is a fixed word a caller may see; none carries a claim value, a key id or which key was tried.
Functions ¶
func IsToken ¶
IsToken reports whether raw is shaped like a sandbox token (by prefix only); the API edge uses it to pick this check for a bearer.
func IssueTime ¶
IssueTime is the time a token issued at now says it was issued, for a sandbox whose tokens_not_before is notBefore: now, or notBefore when that is later. It is later only for a token issued in the second of a revoke or of the row's creation, and then by under a second (well inside ClockSkew, so every node accepts it). After a clock step back on the owner it can be further ahead; the token then reads not_yet_valid until the clock catches up, rather than slipping under the revoke.
func NormalizeMethods ¶
NormalizeMethods upper-cases, checks, de-duplicates and sorts methods.
func NotBeforeAt ¶
NotBeforeAt is the not-before second a revoke (or a new row) made at now stores: the second after now's. IssuedAt is whole seconds, so a token issued earlier in now's own second carries the same IssuedAt as one issued later in it; storing now's second would let the earlier one through. The next second refuses both, and IssueTime lifts a token issued after the revoke but inside that same second up to it, so that one works.
func PathCovered ¶
PathCovered reports whether p is under prefix, segment by segment. A path that is not clean (".." or "." segments, "//") is never covered by a prefix: the check and the upstream that serves the request could resolve it differently. A trailing slash is allowed (a directory URL).
func ValidatePathPrefix ¶
ValidatePathPrefix checks a path prefix: empty, or an absolute, clean path (no "..", ".", "//" or trailing slash, except "/" itself) without a query, a fragment or a control character.
Types ¶
type Claims ¶
type Claims struct {
Version int `json:"v"`
// TokenID is the public id (stk_…), safe for logs and audit records.
TokenID string `json:"jti"`
SandboxID string `json:"sbx"`
// Owner is the sandbox's owner ref at issue time. The toolbox side
// scopes the caller to it, so even a scope-check bug could not reach
// another owner's sandbox.
Owner string `json:"own,omitempty"`
// Port, when set, makes this a public-port token (A2) for that port;
// zero makes it a toolbox token. Never both.
Port int `json:"port,omitempty"`
// PathPrefix, when set, limits the request path: the toolbox path
// (for example /files) or the public URL path. Segment-aware: /files
// covers /files and /files/x, not /files-x.
PathPrefix string `json:"path,omitempty"`
// Methods, when set, are the only HTTP methods allowed.
Methods []string `json:"m,omitempty"`
IssuedAt int64 `json:"iat"`
ExpiresAt int64 `json:"exp"`
// KeyID is the server key that signed the token. It is carried in the
// token's first segment, not the JSON.
KeyID uint32 `json:"-"`
}
Claims is what a token says. The JSON names are short because the token rides in a URL (?token=) and a cookie.
func Sign ¶
Sign signs c with s's current key. It sets Version and KeyID, and refuses claims a verifier would refuse (no id, no lifetime, a bad scope).
func Verify ¶
Verify checks raw's signature against keys, then its claims and its validity window at now. maxTTL, when positive, is the longest lifetime this node accepts. The error is one of the sentinels above; it never holds the token or a claim value.
func (Claims) Allows ¶
Allows reports whether c covers req. The order is fixed (sandbox, port, method, path) so a refusal names the first part that does not match.
func (Claims) CheckNotBefore ¶
CheckNotBefore refuses a token issued before notBefore, its sandbox's tokens_not_before (0: nothing was ever revoked).
type Request ¶
Request is the part of a request a token's scope is checked against. Port is zero for a toolbox request and the guest port for a public-port request. Path is the toolbox path (after /toolbox) or the URL path.
type ScopeError ¶
type ScopeError struct{ Part string }
ScopeError is ErrOutOfScope naming the part of the request the token does not cover: a fixed word, never a value from the token or the request.
func (*ScopeError) Error ¶
func (e *ScopeError) Error() string
func (*ScopeError) Unwrap ¶
func (e *ScopeError) Unwrap() error
Unwrap makes errors.Is(err, ErrOutOfScope) hold.