Guide
Module requirements: what a worker must contain to work with auth and core
A worker becomes a module when it describes itself, and a module can join
two optional workers: core (the admin home page and the navigation shared
between panels) and auth (accounts, roles, one sign-in for every panel).
This page is the checklist: what your worker must contain for each. The
formats themselves are specified elsewhere and linked from each rule — this
page says what is required, those say exactly how.
MUST is a condition for working at all; SHOULD is what every bundled template does and what people who run your module will expect.
Three levels
Each level includes the one before it. Stop where your module's needs stop.
| Level | You get | You add |
|---|---|---|
| 1. Module | The build checks your worker and can list it | module.json |
2. Works with core |
A place in the shared navigation, a card on the admin home page, a live status, your numbers and to-dos in one overview | manifest endpoint, health or summary endpoint, registry entry, one line of HTML in the panel |
3. Works with auth |
People sign in once for every panel; each action needs a permission; scripts use service tokens | the verifier file, permissions per action, the auth variables, a CSRF check |
A worker with no admin side (a public endpoint, a webhook checked by a
provider's signature) stops at level 1: panel: null, empty nav and
permissions.
What you get in return
Everything below already exists; your worker uses it instead of building it.
From auth — in your code
One call, verifySession(request, config), answers who is asking. No request
to auth, no database of your own.
| You receive | Use it for |
|---|---|
user.id, user.email |
who acted: the author of a change, the name in your audit trail |
perms, checked with can(perms, "<id>:<action>") |
a decision per action, not one gate for the whole panel |
kind — user or service |
telling a person in a browser from a script; a bearer request needs no CSRF check |
sessionId, expiresAt |
audit entries; knowing when the panel must refresh |
denied(), forbidden(), loginRedirect() |
the right answer to every refusal — a redirect to sign-in for a page, 401 or 403 JSON for an API call |
From auth — what you do not have to build
- Sign-in: the login page, passwords and their storage, lockout after failed attempts, reset links, sessions, refresh, logout and "log out everywhere". Your worker has no login form at all.
- More ways to sign in, with no change in your worker: Google, Microsoft, Apple, GitHub, Facebook, Cloudflare Access, a second factor (authenticator app, backup codes, passkeys).
- People and rights: invitations, roles, groups and grants, managed in the
accounts panel at
/auth/admin/. Your permissions appear there once declared; an administrator grants them, you only check them. - A second factor for risky actions: a role that needs one simply lacks
its permissions until the person has passed it — your
can()check is enough. - Access for scripts: service accounts and service tokens for CI, cron
and assistants, narrowed to the permissions a script needs, with expiry and
revocation. Your API accepts them through the same
verifySession. - A link to your panel on each person's "Your panels" page.
From core — in your panel
- The shared navigation: one line of HTML gives your panel a bar linking every panel the person may open, the site's name or logo, who is signed in, and a sign-out button. Your panel needs no menu of other panels and no sign-out of its own.
- The site's look:
/core/theme.cssrestyles your panel in the colours, fonts and logo the site's owner set once inadmin_theme:— with contrast already checked for light and dark. - A place on the admin home page at
/core/: a card with your title and description in the reader's language, your numbers, a small chart, and your to-dos in the one list of what needs attention across the whole site. - A live status: whether your module answers, since when it does not, and your configuration problems shown where the administrator looks first — instead of in a log nobody reads.
- Management by the administrator: your module's place in the order, its label and a note, without a line of your code.
Asking core yourself
The bar is one use of an API your panel can call too. To build your own menu
of the site's other panels — a sidebar, a "switch to" list, a link from one
panel into another — ask GET /api/core/modules:
1// The site's other panels, as the signed-in person may see them.
2async function otherPanels(currentId) {
3 try {
4 const lang = document.documentElement.lang || "en";
5 const res = await fetch(`/api/core/modules?lang=${encodeURIComponent(lang)}`, {
6 headers: { "x-core-quiet": "1" }, // a refusal never pops up a password dialog
7 redirect: "error",
8 });
9 if (!res.ok) return []; // no core, or not signed in: show nothing
10 const { items } = await res.json();
11 return items.filter((m) => m.id !== currentId && m.panel);
12 } catch {
13 return []; // core is optional: its absence is not an error
14 }
15}
Each item is ready to show — insert the texts as text, never as HTML:
| Field | What it is |
|---|---|
id, kind, version |
the module's manifest values |
title, description |
already in the asked language (English where the module lacks it); title is the administrator's label when one is set |
panel |
the panel's address: an absolute path on this host, or null |
nav[] |
{label, path, permission} — the module's own pages, paths absolute on this host |
status |
registered, live, unreachable or invalid_manifest |
The same answer carries home (the admin home page), signOut (where to
post a sign-out, or null), brand ({name, logo, logoDark} or null),
user and mode.
What you do not have to work out yourself:
- Who may see what. In the
authmode the list holds only modules the caller has a permission for, and only thenaventries they may open. With a password or Access it holds every module. - Order, visibility and names set by the administrator are already applied.
- Addresses. A standalone Worker's base path is already joined in; a path that would leave the host has been dropped.
To link to one particular module, find it by id and use its panel — never
hard-code another worker's address: a standalone Worker may be mounted on any
base path. When it is not in the list, the person cannot open it (or it is
not installed): show no link.
Other routes, the same way: GET /api/core/status (which modules answer, and
how fast), GET /api/core/overview (every module's numbers and to-dos),
GET /api/core/info (the site, the build, versions) —
workers/core/README. All of them are
behind core's sign-in and work from a page on the same host; a worker
calling them from its own code forwards the caller's cookie and
authorization headers and nothing else.
What stays yours
Neither worker stores your data, proxies your requests or refuses on your
behalf. core hides a link a person cannot use; only your module can refuse
the request. auth says who is asking and what they hold; what each
permission means is decided in your handlers.
What the directory contains
workers/<id>/
├── module.json level 1 — the manifest
├── README.md install, variables, permissions, how to switch it off
├── wrangler.snippet.toml a Pages template: bindings and [vars] to merge
│ or wrangler.toml a standalone Worker: its own deployment
├── functions/api/<id>/… a Pages template (src/… in a standalone Worker)
│ ├── _module.ts level 2 — generated copy of module.json (Pages only)
│ ├── _summary-kit.ts level 2 — copy of workers/module-summary-kit.ts, if it serves a summary
│ └── _session-verifier.ts level 3 — copy of workers/auth/portable/session-verifier.ts
├── public/… the panel, if any
└── test/
├── auth-copy-guard.ts level 3 — copy of workers/auth/portable/copy-guard.ts
├── auth-copies.test.ts level 3 — fails while a copy differs from its source
└── summary-sample.ts level 2 — prints a summary for the cross-template test
Copies are deliberate: a template is scaffolded alone (ssg new worker <id>)
and cannot import from another template. A copy is never edited; a test keeps
it identical to its source.
Level 1 — the manifest
Format and field rules: WORKER-MODULES.
- MUST have
module.jsonat the worker's root, valid againstworkers/module.schema.json, withidequal to the directory name andkindmatching the layout (pages-functionorworker). - MUST give every text (
title,description,navlabels, permission descriptions,disable) in all five panel languages:en,pl,hi,de,fr. - MUST list only paths the worker really serves (
panel,nav,endpoints), relative to the module's base, never a scheme or host. - MUST declare every permission its admin side distinguishes, named
<namespace>:<action>in lower case — one per level of trust: who may only look, who may change, who may do something irreversible or that reaches people. No wildcards in a declaration. - MUST say in
disablehow to really switch the module off. Hiding it in a navigation does not disable it. - MUST NOT contain a secret, a configuration value or data.
- SHOULD bump
versionwhen routes, the panel or permissions change.
Level 2 — working with core
core only shows and links. It does not proxy requests and does not
authorise anything on your module's behalf — your module refuses on its own,
always. Details: workers/core/README.
Being found
- MUST be on the same host as the site. A worker on another host cannot be a module of this site.
- MUST be listed: in
workers:(a Pages template) or as amodules:entry with its base path in.ssg.yaml(a standalone Worker) — the module registry.
Describing itself at run time
- MUST serve its manifest with
GETat the path declared asendpoints.manifest(by convention…/api/module), behind the same check as the rest of its admin API. A refusal is byte for byte what the admin endpoint answers. - MUST accept the caller's own credential on that route — the
cookieandauthorizationheaderscoreforwards unchanged.corehas no key of its own. - MUST answer within two seconds (
CORE_PROBE_TIMEOUT_MS) with at most 256 KiB and without a redirect; anything else shows the module as unavailable. - SHOULD serve
endpoints.healthfor a status that does not depend on who asks.
The summary — optional, and the reason people open the home page (format):
- MUST, when declared as
endpoints.summary: followworkers/module-summary.schema.json— at most 4 metrics, 10 attention items, 10 problems, one series of 90 points, 32 KiB in all. - MUST hold aggregates and fixed sentences only: no address, name, message text, token, IP or any other per-person value.
- MUST link (
href) only into its own panel. - SHOULD compute it with one or two aggregate statements, never by reading rows into the worker.
The panel
- SHOULD include the shared navigation — one line at the top of
<body>:<script type="module" src="/core/nav.js"></script><ssg-admin-nav current="<id>"></ssg-admin-nav>. - SHOULD load
/core/theme.cssafter its own tokens and style itself with the token names ofworkers/core/public/core/tokens.css, so the site'sadmin_theme:restyles it. - MUST keep working unchanged when
coreis absent or down: the bar does not appear, the theme file is a 404, nothing else changes.
Level 3 — working with auth
The agreement is the auth contract. Your
module never asks auth anything per request: it checks the signed token
itself with the public key.
The verifier
- MUST carry
workers/auth/portable/session-verifier.tsbyte for byte (a Pages template: with a leading underscore) and guard it with the copy guard. Never reimplement token checking. - MUST take its settings from
<PREFIX>_AUTH_ISSUER,<PREFIX>_AUTH_LOGIN_URLand exactly one of<PREFIX>_AUTH_PUBLIC_KEY(recommended) or<PREFIX>_AUTH_JWKS_URL;<PREFIX>_AUTH_AUDIENCEis optional. The prefix is your module's own.
Sign-in modes
- MUST check modes in this order, for the ones it offers: Cloudflare
Access →
auth→ shared password. - MUST answer 503 when nothing is configured or the
authset is incomplete. Never open, and never a silent fall-through from a half-setauthto the password. - MAY offer
authas its only mode when every action needs a known author or a permission (a module that publishes on someone's behalf, for one). Its README then says so in the first screen. - SHOULD otherwise keep the shared password as a full mode: one person with one worker needs no accounts.
Permissions
- MUST check a declared permission on every admin route and every action
with
can(perms, required), in the handler that does the work — not only in the panel, and not only in a router in front of it. - MUST answer with the verifier's own responses:
denied()for a failed session (a page is sent to the login URL, an API call gets 401) andforbidden(permission)for a missing permission (403 naming it). - MUST treat the
navpermission as a display hint only. A hidden link is not a refusal. - SHOULD follow the naming
authtreats as sensitive:<id>:erasefor deleting people's data. A sensitive permission reaches a service token only with an owner's explicit allowance (service tokens). - SHOULD declare
"sensitive": truein module.json on any other permission that gives the trust of a person with write access to the repository or the site — code the build runs or a visitor gets, settings that deploy, references to secrets (designer-ui:theme,designer-ui:advanced). No name rule can guess them; the declaration reachesauththroughAUTH_KNOWN_PERMISSIONS.
Requests
- MUST check
Origin(orSec-Fetch-Site) on every state-changing request authenticated by the cookie, also in the Access mode. A request authenticated by a bearer header needs no such check. - MUST accept people's tokens from the cookie only and machines' tokens
from
Authorization: Beareronly — the verifier enforces it; do not work aroundwrong_kind. - SHOULD, in the panel, answer a 401 by calling
POST /api/auth/refreshonce and retrying. - SHOULD record who acted (
user.id, andsessionId) for actions worth an audit trail.
What to tell the people who run it
- MUST document that a removed role, a blocked account or a logout reaches the module at the latest after the token lifetime plus 30 seconds (10 min 30 s by default) — the module does not see revocation sooner.
- MUST document its
<PREFIX>_AUTH_*variables in the README and in the wrangler file, and that its permissions must be inauth'sAUTH_KNOWN_PERMISSIONSto be grantable (node workers/auth/scripts/auth-permissions.mjs workers/*/module.jsonprints the value).
Every panel, whatever the level
- MUST be served from the site's own host with a strict Content Security
Policy:
script-src 'self'; style-src 'self', no inline script or style, no external resource. - MUST insert data as text, never as HTML. Every worker on the host shares one session; an injection in one panel acts in all of them.
- MUST send
Cache-Control: no-storeon admin answers and keep the panel out of search indexes. - MUST never return or log a secret, a token or password material, and refuse rather than open when configuration is missing.
- SHOULD offer the five panel languages, light and dark, WCAG 2.2 AA contrast, full keyboard use, and fit a 360-pixel screen.
- SHOULD answer errors as
{"error": "<snake_case>", "detail"?}and lists as{"items", "nextCursor"}, like the bundled templates.
Tests a module ships
- The manifest validates and matches the code — inside the ssg repository
node --test 'workers/*.test.ts'checks every template; outside it, the one-line check. - The manifest and summary routes answer exactly as the admin route does when refused.
- Each admin route × no session, a session without the permission, a session
with it; a half-configured
authset → 503. - A state-changing request with a foreign
Originis refused. - The summary, seeded with recognisable personal data, contains none of it.
- The copies are identical to their sources.
Before you call it done
- [ ]
module.jsonis valid, complete in five languages, lists only served paths - [ ] the module is in
workers:ormodules: - [ ] manifest route is behind the admin check; health or summary declared
- [ ] the panel works with and without
core - [ ] every action checks a permission in the
authmode - [ ] nothing configured → 503
- [ ] CSRF check on every write authenticated by a cookie
- [ ] README: install, variables, permissions, revocation delay, how to switch it off
What is not required
core and auth are both optional, for the site and for a module: a module
at level 1 or 2 is complete without auth, and a level-3 module works without
core. A module needs no database for any of this, no particular framework,
and no change in core or auth to be added — they learn about it from its
manifest.