Login
GET /healthz answers ok before any login, whatever host it is addressed to: a host’s probe that the app is up, and nothing more.
startApp(config, { ingress }) adds machine routes (IngressRoute), answered by exact path right after /healthz, ahead of the public sites and the login, at any host: each checks its own token. A route with prefix: true also answers every path under its own (/wakeup answers /wakeup/instances/…, the wakeup service) and matches what follows itself; a route at the exact path comes first, then the longest prefix.
POST /api/token/redeem is the other half of sanoma.token.handoff, answered before any login at every host: a machine signing in posts { code, verifier }, the one-time code a browser brought it and the PKCE verifier it kept, and is answered { token }, the api token the code hands off, once, with cache-control: no-store and no cookie. A code used, expired or unknown, a verifier that is not the code’s (which leaves the code to be redeemed) and a token revoked since, or another put under its name, all get one answer, 410; a body that is not { code, verifier } gets a 400.
Beside them, the app answers a git host’s webhooks at POST /webhooks/<vendor> for each connector whose remote half reads them (webhook; remote halves), GitHub’s at /webhooks/github: the half verifies the delivery’s signature over its raw body with the webhook secret (SANOMA_GITHUB_WEBHOOK_SECRET, the environment’s, else the stored one), and each event it carries starts a run of the built-in follow as the runtime’s agent host-check (SanomaClient.follow; one run per event, so a redelivery starts none), which the worker does with its checkout: a push to main applies the declared hosts, a push to a draft’s branch plans its change again, a closed pull request ends it. Every host answers them, the Worker’s bundle too. It answers 204 once the runs are started, 401 for a missing or wrong signature, 404 when no half of that vendor reads webhooks or its secret is not stored. Only an instance GitHub can reach hears them: a laptop has no public URL, so there a change’s merge reads its pull request on GitHub itself (one merged or closed there ends the change once Publish is pressed), and a push to main made outside Sanoma is not deployed. An App made by the manifest before this version has its webhook off and lacks commit statuses: turn on Active under the App’s settings’ Webhook (GitHub’s PATCH /app/hook/config sets only its URL, content type, secret and SSL check, not whether it is active), set its secret there if it has none and store it as SANOMA_GITHUB_WEBHOOK_SECRET, add Commit statuses: Read and write under its permissions, and accept the new permission on each installation. onWrite is called right before each change the app makes that a worker must run, a run’s start or an approval’s decision, never a read (sanoma serve starts its stopped worker again with it).
startApp takes a login provider, which says who may use the app and who is making each change. Without one, the app has no login and listens on this machine only; with one, it may listen on any host. A public site’s own host has its front door instead, its visitor login or none (Public sites): the login here is for the people who run the company.
No login, on this machine
Section titled “No login, on this machine”The default, loopbackLogin(). The page asks “Who are you?” once (the people the data files declare, a row each with their groups, to pick from, or while they declare no one a name to type; when they declare one person, as a new company does its founder, it takes them without asking), keeps the answer in the browser, and sends it, URI-encoded, in the x-sanoma-actor header with every server function call; a change that names nobody is refused. It keeps the name in the sanoma_actor cookie too (SameSite=Strict), which the login reads when a request has no header, so the server’s render of a page whose loader calls api knows who is asking; a page another site sends the browser to renders as nobody. Anyone who can reach the app can start runs and decide approvals as any name they type; the approver check only compares names. So startApp refuses any host but this machine’s (127.0.0.1, the default, localhost or ::1) without another login. While it listens on this machine only, it refuses every request (page, server function or static file) whose Host names anything but this machine (localhost, a loopback address, or a *.localhost name), so another site cannot reach it through DNS rebinding.
Reads are open. Anyone who can reach the app sees every run, its ledger (each operation’s input and output included) and its approvals, through the page and the server functions it reads them with; nothing asks who they are. On this machine, the Host check above is the only protection. A failure the app does not expect shows only “Something went wrong”: its message can name internal details, such as a database host, so the app logs it instead.
Staff sign-in on a host
Section titled “Staff sign-in on a host”staffLogin(betterAuthStaffLogin, { github }, address) signs people in with Better Auth inside the app (sanoma/better-auth), its tables in schema better_auth_staff on the company’s database, which the worker makes at its start (startWorker({ prepare: [prepareBetterAuthStaff] }), as the sanoma bin runs it) and the app only checks for (waiting up to a minute for a worker starting beside it), and the app admits a declared person only, matched by what the sign-in verified: their email, else their github login (each ignoring case). The sign-in page is /auth/login (signed in, it goes on to /), and every other request without a session gets it too, as a 401 (a server function call, JSON; a /.well-known/ path nobody answers, a 404 instead, since a client reads those as documents), so reads are signed in too and signing in there stays on the page asked for.
import { betterAuthStaffLogin } from "sanoma/better-auth";import { agentAddressAt, staffLogin, startApp } from "sanoma/app";
await startApp(config, { host: "0.0.0.0", // GitHub optional; the address optional too: without it no agent signs in to /mcp. login: staffLogin( betterAuthStaffLogin, { github: { clientId, clientSecret } }, agentAddressAt("https://app.acme.example"), ),});Three ways in, all to declared people only:
- An email code, when the config names a sender (
login: { sender: resend.emails.send, from: "Acme <login@acme.example>" }insanoma.config.ts, the sender’s address on a domain its vendor has verified): the sign-in page asks for a work email, then the six-digit code sent to it, which works for five minutes and three tries (Send again sends a new one, and the earlier stops working). Only a declared email gets one; any other gets the same answer and nothing is stored or sent. The code goes out as a run of the built-inlogin-codeworkflow, started by the runtime’s agentlogin, so the policy decides it and the ledger records it (the mail’s text as<text>, never the code); its run’s page shows the code sealed and cut to its first four characters (all the page is sent) and the mail’s text as redacted. A policy that holds sends needs|| principal == Sanoma::Principal::"login"in itsunless, or nobody receives a code:sanoma checknames the policy that would hold it. - GitHub, with the company’s GitHub App’s client: Continue with GitHub, Better Auth’s OAuth flow at
/auth/better-auth/callback/github, matched by the verified email GitHub gives, else the login. A sign-in that fails comes back to/auth/login?error=<code>(Better Auth’serrorCallbackURL; begun from an agent’s sign-in, with that sign-in’s signed request before it, so a code after it still goes on to the agent), which says why: foremail_not_found, that the App needs the Email addresses permission; fornot_declared, that the files declare nobody with that GitHub account; foraccount_not_linked,account_already_linked_to_different_userandunable_to_link_account, a line each; for anything else, that GitHub sign-in did not work. - An invite link, always: a one-use link, valid 24 hours, that signs one declared person in; a new one replaces their last. Someone in
adminmints one on People (Invite link), orPOST /auth/invitewith{ email }from the app’s own page (anyone else gets a 403: the link signs its holder in as that person); anyone holdingSANOMA_SIGNING_KEYmints one with{ request }, an invite request sealed with it (sealInvitefromsanoma/workflows, valid five minutes, and used once), recorded as by the agentlogin. Going live does this for whoever deploys once the host answers. The link lands on a page that names who sent it (the latest invite record’sby,lastInvite; a sealed request’s names nobody) and whom it signs in, as declared, with their groups, then Continue as, so a link preview never uses it up; a link used, replaced or expired gets a 410.
Without a sender, the sign-in page says email sign-in is not set up and to ask for an invite link (with Continue with GitHub when GitHub is on), and names no file, connector or variable: anyone can reach it. Each sign-in and each invite is a ledger record (signin.recorded, invite.minted), and People shows when each person last signed in. The session is Better Auth’s cookie (sanoma.session_token, Secure over HTTPS, 7 days), signed with a key derived from SANOMA_SIGNING_KEY, which must be set; a change to Better Auth’s routes is refused unless it comes from the app’s own origin, but for the token endpoint and revocation an MCP client posts to (Agents over MCP). A client’s sign-in goes through the same page, then a consent page of its own (/auth/consent) naming the client, the agent it acts as and for whom. These pages (and the invite’s) may not be framed by any other page (frame-ancestors 'none'). Who may sign in is read on every request, so removing someone from the people file takes effect at once. The person acts as declared, by their id and the groups that list them. The menu at the bar’s foot shows the login, your groups and Sign out. The sanoma bin builds this on any host beyond this machine, GitHub from SANOMA_GITHUB_CLIENT_ID and SANOMA_GITHUB_CLIENT_SECRET (in the environment or the selected secret store, where creating the App on Go live writes them) when both are set, and the agent address from SANOMA_HOSTNAME, else SANOMA_HOST_URL (agentAddressFrom(process.env), the rule the Worker reads its bindings by). agentAddressAt(url) makes one from the app’s own URL: { issuer: "<origin>/auth/better-auth", resource: "<origin>/mcp" }, the origin written as it is compared, with no trailing slash; a URL with a path is refused.
The sign-in page and the invite’s are the server’s own, outside the app’s shell, and look like the app: named for the company (the app’s package.json name, sanoma-ops as Sanoma Ops, with its initials), they link the built kit’s stylesheet (/assets/style-<hash>.css, which loads signed out with its fonts), set this browser’s light or dark theme before they paint, and stay legible on the dev server, which builds none.
Your own
Section titled “Your own”A LoginProvider is { name, check(listenHost), resolveActor, handle?, signOut?, open?, close?, invite? }; open(app, current) is called once the app listens (current() is the company as its files say when asked, which the staff sign-in reads who is declared from), close() when it closes, and invite(email, { origin, by }) mints a one-use invite link (the staff sign-in’s). check throws for a host the app may not listen on. resolveActor turns a request into who the login vouches for (LoginIdentity: { id?, email?, github? }), or undefined to refuse a change; the app admits only the declared person it matches (admitting: by email, then GitHub login, then id), who acts as declared, so a provider’s own roles or group claims never reach the policy. handle, when there is one, sees every request first: it answers its own routes under /auth/<name>/ and any request it will not let through, and returns undefined for the rest. signOut is the path the page POSTs to to sign out, which handle serves; with it, the menu shows Sign out.
With a login provider, the page never asks for a name: it shows who the login says you are. An approval addressed to a group ({ group: "finance" }) can be decided only by someone the people file lists in it. The app calls resolveActor only for a request that needs to know who is asking, once per request. One that throws fails the change with a 500, logged as “Could not tell who you are: “ and the resolver’s message; the menu at the bar’s foot says “Could not tell who you are” and asks again every 10 seconds.
These pages describe sanoma 0.11.24.