worker

The jevstrudel Cloudflare Worker, in TypeScript. Cloudflare serves the static site's files itself; the Worker answers the paths that are not files.

Two environments

Production (nix run .#deploy, --env="") is the site plus the relay, the votes, accounts, listening, listening parties, listeners' content and the hosted MCP (/jev/mcp, for everyone's own AI, behind OAuth). It has no dev hub, so /mcp and /strudel/* answer 404 and the public page never turns the dev MCP on. The votes read the deploy's song list through the ASSETS binding, so a vote is only ever for a song that deploy has.

Development (buck2 run //:dev, wrangler dev --env dev on port 4323) adds the dev hub, so Claude Code in this repo can play into your local tab without signing in (its code is the page's own); the hosted MCP runs there too, at http://localhost:4322/jev/mcp. The dev server (localhost:4322) proxies the Worker's paths to it, and wrangler reloads the Worker on every save, tool changes included. There the votes read the song list from the dev server itself (SONGS_URL), so a new song is votable on reload; dev.mjs gives the inherited assets an empty folder, since wrangler requires one.

Storage

Each kind of data lives where its shape fits, so a new feature picks by the table below rather than by what the last one used.

The database's schema is migrations/ (0001_votes.sql, …). Every place that runs the Worker applies them first: //:dev and //:preview to their local databases on start (tools/dev/migrate.mjs), and the deploy to the real one before it publishes (tools/deploy/resources.mjs, which also creates the database on an account that has none, and the R2 bucket). wrangler.json names the database and the bucket but holds no id: the deploy looks them up by name each time.

To add a table, see migrations/README.md. To read the local data:

wrangler d1 execute jevstrudel --local --env dev --config worker/wrangler.json \
  --command "SELECT * FROM votes"

from the repo root (//:preview's is --env "" --persist-to worker/.wrangler/preview). The real one takes --remote in place of --local, through the deploy's wrangler, which reads the token from 1Password.

The relay's cache keys an answer by the SHA-256 of the exact body it forwards, under the pinned model, so only a request identical in every byte gets another's answer; it keeps only a 200, for an hour, and marks every answer Jev-Cache: hit or miss (src/answer-cache.ts has the reasoning). A hit is logged with outcome: "cached", and TypeSafe is not asked.

An event is declared in src/events-schema.ts (its fields, their columns, what they mean) and written with event() from src/events.ts, whose types allow exactly the declared fields. nix run .#events reads them back (tools/events/). Analytics Engine creates the dataset on the first write, so there is nothing to provision; wrangler dev keeps it local, so only the deployed Worker's events can be queried.

Production can also run locally: buck2 run //:preview serves the deploy's own static build with the production Worker on port 4324 (tools/dev/).

What is public

jevstrudel is a playground shared in the Jev community, and everything it stores is public: the jev panel's data tab (website/src/jev/DataTab.jsx) reads it through GET /jev/data[/*] (src/data.ts), which anyone may call.

An account's page (/jev/data/accounts/<id>) is also its profile on the jev panel: it adds publicSongs, the account's songs as the listeners' list shows them, and takes, its newest 50 performances (a listener song's with its public title), which the you tab's "recently played" and the profile's "played lately" merge with its radio plays. /jev/data/activity?before=<ms>&limit= is the activity tab's feed (src/activity.ts): what happened, newest first, at most 50 an answer, with next for the page before. Songs published and revised come with Jev's verdict and, once scored, a scored item with the art; comments and pitches with their verdict and their text only when public; and every performance as a take item: who played it (null signed out), the song (a listener song's public title with it), how many sections and how it ended, and its id for the replay link. It is cached for 10 s, since everyone polls the same first page.

The lists are paged (offset, limit up to 100) and no-store; reads are DATA_LIMIT (120 a minute per visitor, namespace 1012). The KV and R2 counts are list operations, of which the free plan allows 1000 a day, so each isolate counts at most every ten minutes. Sign-up says it all plainly, on the site and on the OAuth page.

Accounts

Listeners can sign in with a passkey (WebAuthn): no password, no email, no third party. Everything works as before without an account; signed in, a listener's Jev calls are charged to a daily budget of their own, and the radio remembers what it played for them across sessions and devices.

The ceremonies are verified by @simplewebauthn/server, which uses only Web Crypto and runs in workerd; passkeys must verify the user (PIN, face or fingerprint), since they are the only factor. The relying party is the host the request came to: RP ID localhost in dev, the workers.dev host in production. A challenge is issued into D1 and taken back by its verify with DELETE … RETURNING, so it is used at most once, and only within five minutes. A session is an HttpOnly, Secure, SameSite=Lax cookie holding a random token; D1 keeps only its SHA-256, for 30 days. The auth routes have their own per-visitor rate (AUTH_LIMIT).

The daily budget. Each signed-in user has a JevBudget Durable Object (BUDGET.idFromName(userId)) counting the relay calls charged to them per UTC day. A call is charged when the relay is about to forward it to TypeSafe; an answer from the cache costs nothing and is not charged. The check and the charge are one SQL statement in an object that runs one call at a time, so a user's tabs and devices racing each other are counted exactly. Once the day's budget is spent, the relay answers 429 with Retry-After until 00:00 UTC and Jev-Budget: spent, so the page backs off and songs play their fallbacks; each charged answer says Jev-Budget: <used>/<limit>, which the header shows. The call that spends the last of it writes a jev.budget.exhausted event.

The budget is JEV_DAILY_PER_USER in wrangler.json (vars, in both environments), 1000 calls: the user's to set. A song asks about one call a section, a couple a minute, so 1000 is several hours of listening. It must be a positive whole number; anything else and signed-in calls are refused rather than charged against a guessed number.

Anonymous callers keep the per-address JEV_LIMIT, and are never charged. Signed-in callers are held to JEV_LIMIT too, keyed by their account rather than their address.

Listening parties

A host's page starts a party from a song's view ("listen together") and shares /songs/<theme>/<song>/?party=<room>; the room id is 128 random bits the host's page makes. Every page in the party holds one WebSocket to /jev/party/<room>, which the Worker hands to that room's Party Durable Object (idFromName(room)). The page's side is website/src/jev/party.mjs.

The protocol, JSON text frames:

The first host connection claims the room with a key (kept in its tab's sessionStorage, so the host's reload rejoins as host); the room keeps only its SHA-256. A guest cannot join a room with nobody in it (4404: the party has ended). Limits: 50 people a room, 16 KiB a message, a burst of 30 messages per connection refilled at 5 a second, sections below 64 and jev()s below 8, and PARTY_LIMIT (20 joins a minute per visitor) at the route.

The room uses the Hibernation API, so a party between messages costs no duration. Its storage holds the current performance only, and is deleted when the last person leaves; a room found with storage and nobody in it is cleared by whoever arrives. Nothing about a party is logged or kept.

Rooms cannot be listed, so each tells the site's one PartyDirectory (src/party-directory.ts) when its people or song change, and the data tab lists the live ones: song, people, whether the host is there, since when. The directory is keyed by the room's Durable Object id, a hash that cannot be turned back into the room's name, so a party stays unlisted to join; an entry goes when its room empties, or six hours after its last report (a room lost in a crash).

A listed party can be joined from the list. The host decides, with the lobby's "show me here": a host whose tab is listed connects with listed=1, and the room then keeps its own name (the Worker's route hands the object its name in X-Jev-Party-Room, a header set by the Worker and never by the page) and reports listed to the directory. The directory gives a listed entry its object id, and GET /jev/parties lists them; GET /jev/parties/<id> asks that room (PARTY.idFromString) for its name, which it answers only while it has people and its host chose listing, and the page joins as a guest, exactly as with a link. The object id is the token rather than a new secret: it cannot be turned back into the name, the room answers for itself (so an ended or unlisted party gives nothing, with no second copy of the name to go stale), and an unlisted party's room keeps no name at all. A host's choice is read when it connects, and again the moment it changes: the host's page sends listed { listed, room? }, and the room lists or unlists itself and reports to the directory at once, guests staying in. To list itself mid-party the room needs its name, which it takes from that message only after proving it its own (PARTY.idFromName(room) equals the object's id), so the page still cannot give a room a name that is not its. Both routes are GET only, under PARTY_LIMIT.

The lobby

Every open page holds one WebSocket to /jev/lobby, the site's one LobbyRoom Durable Object (idFromName('lobby')), and says what its tab is doing; the jev panel lists everyone else's tabs, grouped by who, each with its song, whether it plays, and how far through it is, and "🎧 listen along" (website/src/jev/lobby.mjs, Lobby.jsx). The header's 👥 is how many pages are open.

Who a tab is comes from the Worker. The route reads the session (signedIn) and hands the object the account's display name, its id (for its profile; accounts are public, What is public) and a group key (the first 8 bytes of SHA-256 of lobby: and the account's id); signed out, no name or id, and the tab is its own group, which pages show as "a listener". The page never says who it is. The user's call (2026-09-27) was a more social site, so a tab is listed by default; "show me here" on the jev panel hides it (kept per browser), and a hidden tab is sent to nobody, only counted in the total.

The protocol, JSON text frames:

Listening along is an ordinary listening party (above): the asker joins its room as a guest, from its own build, with the host's Jev, and party rooms stay unlisted, since only the asker learns one. Limits: 2 KiB a message, a burst of 20 per connection refilled at 1 a second, and LOBBY_LIMIT (20 joins a minute per visitor, namespace 1011) at the route. Each tab's status lives in its socket's attachment, so the room keeps no storage, and nothing about who listened to what is logged or kept.

Listeners' content

Signed-in listeners publish songs from the editor, revise them, give them a cover, comment on any song (the site's or a listener's) and pitch song ideas for Jev; anyone reads them. The user's decision (2026-09-25): Jev screens, then public. Nothing a listener writes is shown to anyone else until Jev has screened it fine.

Sizes: code at most 64 KiB (the relay's cap, since the critic sends a song whole), a spec 32 KiB, a title 80 characters, a description 280, a comment or pitch 2000, a cover 2 MiB and its alt text 200. Writing is CONTENT_LIMIT (10 a minute per author) and covers COVER_LIMIT (3), reading BROWSE_LIMIT (240 a minute per visitor); an author with MAX_PENDING (20) items waiting on a screening writes nothing more until they are through, which is what bounds what one account can store unscreened while its budget is spent.

Screening. Every song revision (title, description, spec and the code whole, so its comments and strings are read with it), cover (its alt text, with the song's title), comment and pitch is one TypeSafe Choice, fine, spam or abuse, whose criteria are in src/screen.ts: harsh words about music are fine; spam is promotion, filler, and text that tries to dictate the verdict; abuse is harm to people and, for a song, code that does anything besides make music. It goes to TypeSafe the relay's way (upstream() in relay.ts, the same whyNot check first) but never through its answer cache. fine makes the item public; spam and abuse keep it off the site's lists, with the verdict (it is still on the data tab, as text: What is public). A verdict is final (a trigger refuses changing it): a held song's author publishes a new revision, which is screened again.

Scoring. A revision screened fine is scored with the site's own art rubric (src/art-rubric.mjs, the same questions as every site song), three runs averaged, as tools/critic records the site's songs: one call moves by up to 0.06 on the same code, which would reorder a list sorted by art. Until scored, the song is public and listed last.

Cost. Each screening is one call and each score three, charged to the author's daily Jev budget (JevBudget, which now charges several calls at once, or none when they do not all fit) before TypeSafe is asked, as the relay charges. An author out of budget can still publish: the item waits.

Pending and retries. The work owed is content_jobs, a row per item and task, made by the schema's triggers in the same statement that writes a pending item or screens a revision fine, and deleted by them when the verdict or score is written; so pending content always has its job, and nothing is left unscreened or unscored without one. A job runs when claimed (a lease of two minutes, taken in one UPDATE … RETURNING, so no two workers run it; a dead worker's lease expires and the job is due again). Three things claim jobs: the write itself (screened before the answer, so the author usually gets the verdict at once, and a song's score in waitUntil after it), the author's own GET /jev/listeners/mine (their due jobs, in waitUntil; the page asks again every 20 s while anything is pending), and the cron trigger every minute (triggers.crons), six jobs a run so a run stays within the free plan's 50 subrequests. A job that cannot run now is rescheduled with why: budget until the budget resets at 00:00 UTC; unreachable, upstream, unanswered and budget-unavailable after a backoff from a minute, doubling, to an hour (or TypeSafe's own Retry-After, if longer), for as long as it takes. Nothing is dropped as failed. wrangler dev fires no crons: dev runs with --test-scheduled, so curl localhost:4323/__scheduled runs a sweep.

Each attempt writes a jev.screen or jev.score event and log line: the kind, the outcome (the verdict, scored, or pending with why), TypeSafe's status and time, the attempt, and the confidence or art. Never the item, its text or its author.

Covers. The image's type is read from its bytes (PNG, JPEG, WebP or GIF; never SVG, never what the upload says), stored under a new id per upload in R2, and served with that type, nosniff, a sandboxing CSP and a day's caching. Jev reads text only, so it screens a cover's alt text, not its pixels. What guards the pixels instead: a cover is served only while its alt text is fine and its song has a public revision, so an account whose songs are all held shows no image to anyone; uploads are signed in and limited to 3 a minute; a cover is replaced, not added to, so each song has one. The gap stays: an image whose description is fine can show something that is not. Taking one down today is by hand: UPDATE covers cannot un-screen it (the verdict is final), so delete its row (DELETE FROM covers WHERE id = … through wrangler d1 execute --remote) and its object (wrangler r2 object delete jevstrudel-covers/covers/<id> --remote).

A listener's song runs in a sandbox, never in the page. Playing a listener's song evaluates someone else's code. On the site's own origin that code could do whatever the page can — for a signed-in visitor, post comments, publish, or spend their daily Jev budget with their session. So the page never evaluates it. It plays in an iframe with an opaque origin (sandbox="allow-scripts", never allow-same-origin) served with a strict CSP; the parent sends the code in by postMessage and receives back only playback state, logs and Jev decisions, each rebuilt from typed, bounded fields before anything reads it (website/src/jev/sandbox.mjs, sandboxProtocol.mjs, sandboxPolicy.mjs, sandbox/player.mjs). The boundary is the origin, so:

• The frame has no cookies and no storage of the site's: document.cookie and localStorage throw, and it cannot reach the parent page or top. Proven headless: a published song that builds fetch/document/parent at runtime (so the name check below never sees them) reads no cookie, touches no parent, and posts no comment.
• Its fetches carry Origin: null and no credentials. The Worker refuses every write (any method but GET/HEAD) whose Origin is not this site's, before any route runs (refuseCrossOrigin in session.ts), and signedIn returns null for such a request, so a sandbox call is never charged to or acted on as the visitor — it is an anonymous, per-address call, as signing out would be. The CSP's connect-src also limits it to the site's relay and the sample hosts site songs use.
• The frame's own scripts and the sample pack are cross-origin to it, so they are served with Access-Control-Allow-Origin: * (public, no credentials): _headers on the deploy, the dev middleware in dev (sandboxPolicy.mjs, astro.config.mjs).

The name check and the screen are now defence in depth, not the boundary. whyNotCode still refuses, before Jev is asked, code whose identifiers reach the page's powers (network, storage, cookies, the document, evaluating strings, the ways back to the global object; every site song passes it, screen.test.ts), and the screening's abuse still covers code that does anything but make music. They give an author fast feedback and keep obvious abuse from ever going public, but the isolation no longer depends on them: code that slips past both still cannot escape the opaque origin.

Only untrusted code is sandboxed. The site's own songs are first-party, curated code and keep running in the page, where they can drive the visuals, listening parties and performance recording the sandbox deliberately lacks. The sandbox is for what the page did not write: a listener's song, and code arriving in a link (#hash/?hash). The editor tracks this provenance (sandbox.mjs): foreign code stays foreign through the visitor's edits and plays only in the sandbox; loading a site song, pattern or example makes the editor the page's own again. A listener song's link (/?listener=<id>) loads it without playing; a card plays it on the listener's click.

The residual gap is availability, not integrity: a song can still make its own sandboxed browser fetch a sample from an allowed host. It cannot read or act as the visitor.

The hosted MCP

Anyone with an account can connect their own AI (Claude Code, Claude's custom connectors, any MCP client) and make songs with it: play code in their own open tabs, read the site's and listeners' songs, publish and revise their own. The site's page for it is /ai/ (website/src/pages/ai.astro). The user's decisions (2026-09-24): OAuth 2.1 per MCP's authorization spec with the site's passkeys as the sign-in; only the signed-in user's own tabs; the code plays in the sandbox; publishing through the listener pipeline; per-user limits.

Who a token acts for. @cloudflare/workers-oauth-provider (1.1.0) is both the authorization server and the resource server here, one pair per origin (the issuer and resource are the request's own origin, as the passkey relying party is). The authorize page is this site's own origin, so the session cookie and passkeys are the site's: a visitor not signed in signs in or makes an account on that page, then allows or denies. The consent page shows the app's name (escaped; unverified unless it is a CIMD client, whose domain it shows), where access goes (a warning for localhost), and the scopes: play (the tab tools) and publish (writing, and reading one's own content statuses); public songs need only a valid token. The grant stores { userId, app } as its props. A tool without its scope answers the MCP scope challenge (403, insufficient_scope). Clients register by Client ID Metadata Document (preferred by the 2026 spec and by Claude; needs the global_fetch_strictly_public flag, which is set) or by dynamic registration. Access tokens last an hour; a grant lasts 30 days past its last refresh; connecting the same app again replaces its grant.

Only their own tabs. A tab joins TAB_HUB.idFromName(userId) only through /jev/me/tabs, which takes the session cookie from this site's own pages (a browser's WebSocket always sends its page's Origin, and signedIn refuses any other), and the MCP handler reaches only the hub its token's user names. There is no path from one user's token to another's hub; hosted-mcp.test.ts and tools/mcp-e2e/ hold it. A hub keeps at most 8 tabs (the oldest goes), and uses the Hibernation API, so an open tab between commands costs nothing.

The AI's code plays in the sandbox. The tab puts it in the editor as foreign code ({ ai: app }, website/src/jev/myTabs.mjs) and plays it only in the opaque-origin iframe listeners' songs play in (A listener's song runs in a sandbox, above), never in the page: code a prompt-injected agent was talked into writing cannot read the page, post, publish or reach the session. Its logs and state come back through the sandbox's protocol, rebuilt and bounded, then again by the hub (tab-hub-core.ts).

Whose budget. Jev's calls from the AI's code are charged to the listener's own daily budget: the page makes them for the frame with its own session (credentials: 'same-origin'), exactly as the listener's own Jev calls. The frame never holds the session, so nothing it could exfiltrate is worth anything; the worst it can do is spend the budget the listener gave this app to spend, at most ASKS_PER_MINUTE (30) a minute. Anonymous calls were the alternative, and wrong: they would let a connected app spend the address's shared allowance instead of its own user's, and one listener's agent would starve everyone behind that address. A listener's song, which the visitor did not ask anyone to write, stays anonymous as before. Screening and scoring what the app publishes are charged to the author as for any listener content.

Limits. MCP_LIMIT (namespace 1010): 120 requests a minute per user, every method counted; an agent iterating plays, reads logs and plays again a few times a minute. A request body is at most 384 KiB (a publish's code and spec, JSON-escaped: content.ts's own cap), code to play 64 KiB, a tab's reply 256 KiB and 500 log lines of 500 characters. Publishing also meets content.ts's CONTENT_LIMIT and pending cap, since it is the same writeSong. Registering, authorizing and token swaps (/jev/oauth/*) share the passkey ceremonies' per-visitor AUTH_LIMIT, since each writes to KV. Browser pages of other origins are refused before any route (refuseCrossOrigin), which is also what MCP's transport asks of a server against DNS rebinding; MCP clients that are not browsers send no Origin.

The tools both MCPs share. Nine tools are the dev hub's and the hosted MCP's alike (shared-tools.json, run by shared-mcp.ts), so the proxy's tool list has them in either environment. Most are a command to the tab (tab-hub-core.ts's SharedCommand), which the tab answers from what its panel shows (website/src/jev/tabTools.mjs), rebuilt from typed, bounded fields before it is read, in the dev hub as in the hosted one:

The hosted MCP adds comment (publish: content.ts's commentAs, the page's rate and pending cap, screened by Jev) and get_logs with source: "console", the page's console tab: what a site song played in the page logged, as the listener sees it (the dev hub's get_logs already is the page's console). Settings are play, not a scope of their own: only how the editor looks and types can be changed, each undone in the settings tab, and an app that may replace the editor's code and play sound in the tab is trusted with more than its font (hosted-tools.ts). A tab has 60 s for a command that asks Jev, 30 s for a play, 15 s for the rest (replyMs).

KV on the free plan allows 1,000 writes and 1,000 lists a day. An authorization writes a handful of records, a refresh two, a dynamic registration one (Claude registers again on every fresh connection, which CIMD avoids); listing a user's apps is one list. Workable at today's scale; the answer cache's writes share the same allowance.

Logs

The relay logs one structured line per call (event: "jev.relay"): outcome (refused by the relay, forwarded to TypeSafe, cached from the answer cache, or unreachable), status, upstreamMs (until TypeSafe's response headers; null when the relay refused the call itself), requestBytes, colo (the Cloudflare data centre that ran it), and the page's own timing, which ask.mjs sends as headers the relay never forwards: sectionInS, how many seconds before its section began the call went out (negative once it had begun; null before a song starts), and attempt (0, then its retries). So a late answer shows whether the call went out late (small sectionInS) or TypeSafe was slow (large upstreamMs).

Workers Logs (observability in wrangler.json) keeps them, queryable in the Cloudflare dashboard under the Worker's Observability tab; wrangler tail jevstrudel --format json (through the deploy's 1Password-fed wrangler) streams them live. Cloudflare's own per-request invocation logs are off: they record the request's metadata, which is the visitor's.

The same fields go to Analytics Engine as a jev.relay event, where they can be counted and charted over time: nix run .#events -- jev.relay. The account is never in either: a signed-in call's line and event are the same as an anonymous one's.

Type checking

wrangler bundles src/ with esbuild, which strips the types without checking them, so a type error deploys. nix flake check catches it: its worker-types check generates the Workers runtime types with wrangler types and runs tsc -p worker. To run it in the devshell, from worker/: wrangler types --include-env=false once (it writes the gitignored worker-configuration.d.ts), then tsc -p .. The check and the deploy both use strudel.worker (nix/strudel.nix): worker/ with a node_modules of exactly its dependencies, so a copy of it bundles alone.

The key comes from 1Password (JEVSTRUDEL_TYPESAFE_API_KEY): as a Worker secret on deploy, and through the process environment in dev (tools/dev/worker.mjs). It is never written to a file.