Documentation
¶
Overview ¶
Package worktoken issues and authenticates the per-item sessions tokens a BYOC worker presents for a work item whose session attaches a memory store (docs/plan/36_memory-stores.md decision 15). The reference's poll response carries the token inside the item's `secret` — URL-safe base64 of a JSON object whose sessions_token key the reference worker reads (checked against anthropic-sdk-go v1.66.0 — worker.go sessionsTokenFromSecret) — and the worker then calls the item's heartbeat and stop, its session's read and events, the skill reads and the memory routes with the token as its Bearer, the environment key deleted from those requests.
A token is minted once per claim, in the claim's own transaction, and stored hash-only. It carries neither an expiry nor a revocation column: it is valid while the item it names is live — the join conditions Authenticate runs — so a re-hand-out (a fresh work id, #62), a lapsed lease and a session archive each end it without an event. A stop leaves it whole for a minute from the request (queue.WindDown), then ends it once the item is stopped, or keeps only the item's heartbeat and stop while it is still stopping (Authenticate). The reference worker's memory flush rides that minute: it flushes its unsynced memory writes once the control plane has reported the stop, on a context of its own bounded by 30 seconds (checked against anthropic-sdk-go v1.66.0 — memories.go SessionMemoryStores.Cleanup), and a token dead at that instant would lose them — a BYOC workdir is removed at the item's end, with no held sandbox to sync from later as a cloud session has. The minute covers a worker told of the stop promptly, the usual case: a claimed item's worker learns of it at its next heartbeat, within 15 s here. One told late, like the recorded never-claimed one (its force stop 60.1 s after the request), loses the flush, but its run was cancelled at its claim, before any tool ran, so it has nothing to flush. The value itself is gatetoken's mint under another prefix, so every internal bearer the platform issues shares one entropy and one alphabet.
Index ¶
Constants ¶
const TokenPrefix = "wtk_"
TokenPrefix marks a sessions token value. Internal-only, never an id on the /v1 wire — deliberately NOT in domain/id.go knownPrefixes, like gtk_ — and what the auth lane routes on: an environment key (sk-map-env01-…) and a JWT (two dots) can never carry it.
Variables ¶
This section is empty.
Functions ¶
func Mint ¶
Mint issues the token for workID's claim of sessionID's item and stores its hash on db. A later row for the same session needs no retry logic: the earlier one is dead by Authenticate's join conditions, its work id no longer a live item's.
func Secret ¶
Secret renders a token as the work item's `secret`: unpadded URL-safe base64 of {"sessions_token": token}, the envelope the reference worker decodes (padded or not). The other keys the reference's envelope may carry — its ingress and source tokens, which the worker does not consume — are absent; #165's vault-credential bundle would be another key beside this one.
Types ¶
type DB ¶
DB is the statement surface Mint needs: a pgx.Tx, so the token row commits with the claim it belongs to, or a pool.
type Principal ¶
Principal is what a token authenticates — the item, its session, and the environment both belong to. StopOnly marks a stopping item whose stop was requested more than queue.WindDown ago: its worker has only the stop left to finish, so the lane admits it on the item's heartbeat and stop alone.
func Authenticate ¶
Authenticate resolves a token to its principal, or the zero Principal when the token is unknown or no longer names a live item: the item's id must still be the one the token was minted for (a re-hand-out rewrites it), its session unarchived, and the item
- before any stop: its lease unexpired;
- stopping: until a force stop settles it, or a poll of the environment once its lease and WindDown have passed — never, if nothing polls. Its worker still has the stop to finish, and may learn of it only about WindDown after the request: the recorded claim on such work was sent 58.9 s after it, its force stop at 60.1 s (2026-09-19 custom-mixed-tools #23, #44 and #47). Past WindDown the principal is StopOnly, so a stranded item's token can still finish the stop and reach nothing else;
- stopped: its stop requested within queue.WindDown, the window the reference worker's post-stop flush rides (its doc). The finalizer settles an abandoned wind-down only past that window, so its re-arm never runs beside the abandoned item's token. A force stop and queue.CancelSession settle at once, so an old item's token can work for the rest of the window beside the session's next item.
The CASE and StopOnly rest on one invariant held two packages away: stop_requested_at is set by every stop but Queue.Complete, and Complete settles only Claim's items — the brain's turns and the cloud executor's tool runs — never a polled one.
Source Files