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, and a stop ends it queue.WindDown (a minute) after it was requested: the reference worker 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 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.
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 lease unexpired while it runs, or its stop requested within queue.WindDown once it is stopping or stopped (a graceful stop parks an active item in stopping with a lease the heartbeat no longer extends, so the window counts from the request rather than from the lease or the stop's completion: the wind-down and the post-stop flush both ride it), and its session unarchived. WindDown is sized to the reference worker's flow (its doc), and the queue settles an abandoned wind-down only once the same window has passed, so no settlement re-arms a session while its token still works. The CASE rests 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