@substrat-run/vertical-host
The platform's /internal/* management contract — the routes the control plane calls to provision, reconcile, introspect, snapshot, export/restore, bookmark/rewind and configure an install — plus the application/problem+json error envelope, authored once and mounted into a vertical's Hono worker. The /model export, createModelHost, is how a vertical calls a language model on platform-held credentials, with no provider key of its own; it has its own section below.
Before this package every sandbox-clean vertical hand-copied those routes and a Hono onError into its own worker.ts. The copies drifted — route sets disagreed and some workers shipped without the error handler, so a failing /internal/restore surfaced to the control plane as the Workers runtime's bare Internal Server Error with no diagnosis. One copy, mounted, removes that whole failure class.
mountPlatformSurface(app, deps)
import { Hono } from 'hono';
import { mountPlatformSurface } from '@substrat-run/vertical-host';
import { CloudflareScopeHost } from '@substrat-run/adapter-cloudflare';
import { ROLES, OWNER_ROLE_KEY } from './provision.js';
const app = new Hono<{ Bindings: Env }>();
// your own user-facing surface:
app.get('/api/me', /* … */);
app.post('/api/invoke', /* … */);
// the entire platform contract + guaranteed error envelope, in one call:
mountPlatformSurface(app, {
platformSecret: (env) => env.PLATFORM_SECRET,
hostFor: (env) => hostFor(env),
roles: ROLES,
ownerRoleKey: OWNER_ROLE_KEY,
onProvision, // pending-owner claim / site registry (optional)
resolveOwner, // owner-of-record for reconcile (omit ⇒ 501)
onConfigure, // per-instance config store (omit ⇒ 501)
ownerSeat, // the owner seat's state, for the dashboard (omit ⇒ 501)
mintOwnerClaim, // a short-lived owner-claim link (omit ⇒ 501)
transferOwner, // hand the owner of record to another member (omit ⇒ 501)
completeOwnerTransfer, // close that hand-over once seated and revoked (required with it)
abandonOwnerTransfer, // close an open hand-over without finishing it (omit ⇒ an abandon 501s)
members, // let the dashboard manage this app's members — vertical-auth's membersHook (omit ⇒ 501)
onDeleteScope, // (env, scopeId, tenantId?) — e.g. drop a scope from a registry (optional)
});
export default app;onDeleteScope(env, scopeId, tenantId?) receives the tenant ID from current control planes, so a vertical can remove the scope from a tenant-specific registry. Older delete requests omit the tenant ID; handle undefined if the hook must support them.
What it owns vs. what you supply
- Generic routes —
export,restore,bookmarks,migrations,rewind,snapshot,delete-scope,tables,tables/:table,query,history,facets,cause,effects,invocation,dead-letters,lifecycle-flow,operation-series,denials,denials/summary,capabilities,platform-requests,platform-requests/history,platform-requests/settle— pure delegations to your scope host, owned entirely by the package. The table, query, denial and event reads (tables,tables/:table,query,denials,denials/summary,capabilities,history,facets,cause,effects,invocation,dead-letters,lifecycle-flow,operation-series) are how the control plane answers those questions for a hosted vertical, whose scope it cannot open itself: the transport delegates the read here, then records the K-24 access row for it as if it had served the read (seeHostAdmin.recordDelegatedRead).migrationsis delegated the same way but is schema metadata, and leaves no access row. - Connector write-back routes —
connector-invoke,connector-attachment,connector-attachment-stream,connector-attachment/:attachmentId,connector-grant— the far end of the shared control plane running this vertical's connectors (#574, #711): the connection directory and its sealed secrets live platform-side, so what comes back over these verbs carries no credential — an operation invoked as the connection, provider bytes in (multipart: ametaJSON field beside thebodyfile; or, for a file too large to hold,connector-attachment-stream, whose body is the file itself, read into the bucket as it arrives, with the metadata and declared size in a header, #2498) or out (the raw bytes, with the record in a header; read from the bucket as the platform reads the response when your host hasconnectorAttachmentOpenStreamLocal, sent at the record's size, with the sha256 checked as the bytes pass so a mismatch breaks the body before its last chunk, #2514), and theconnection:<id>grant tuple the first three are checked against. Both upload routes hold the metadata toCONNECTOR_ATTACHMENT_META_MAX_BYTES(8 KiB once URI-encoded) and answer one400for more. Both also hold the file to a size bound and answer one413for more, with a different bound for each because they hold the file differently: the stream route toCONNECTOR_ATTACHMENT_STREAM_MAX_BYTES(95 MiB, a request-size limit, since a stream is never held), judged from the declared size before it reads a byte; the multipart route toCONNECTOR_ATTACHMENT_BUFFERED_MAX_BYTES(16 MiB, a memory limit, since a buffered file is resident several times over), judged fromContent-Lengthbefore it buffers anything or, for a body without one, by cutting the read off at that size plus a 16 KiB multipart envelope (#2538); the multipart route's answer tells the caller to use a streamed upload. A streamed upload asks the connection's write gate before the first byte is read, so a connection that may not write stores no object (#2516). The multipart route cannot: it buffers the body first, because the gate needs the parsedmeta, so its bound is the only thing held before the bytes are read. Each is authorized in the scope's own DO like any other caller, and the grant has no revoke mirror because every delegated call re-passes the platform's live-connection gate first. Generic in the same sense as the group above: owned by the package, answered by your host'sconnector…Localmembers. - Members —
GET /internal/members,POST /internal/members/invite,…/roleand…/remove: the dashboard's Members section for an installed app. One scope per call. The platform names thecaller, the signed-in person, and every change is bounded by what that person holds in this scope (the kernel's assignment bound, asked in the same scope task that writes): an invite throughassignScopeRoleBounded, a role move throughchangeScopeRoleBounded, which takes the old role and grants the new one together or not at all, and a removal throughrevokeScopeRolesBounded. A refusal answers403naming what is missing and writes nothing. Every bound is over the roles the person holds in the scope, never an invite row's recorded role. A removal takes every scope role first (a refusal writes nothing), then withdraws the open invite, then unbinds every login, so an accept of the old link afterwards finds nothing. The roster lists each open invite with both the role it was minted at and the roles its principal holds now. The owner of record answers409: move it withowner-transfer. So does a principal holding a role outside the hook'sroles, such as a service account. A role move for someone whose invite is still open answers409too: withdraw it and invite them again at the new role, so an open invite's recorded role is always the role it confers. Omitmembersand all four answer501(this app declares no member roles), which the dashboard shows as such. - Flavored routes —
provision,reconcile,configure,owner-seat,owner-claim,owner-transfer— the package keeps the platform-secret gate, body parse and response envelope; you supply only the hook. OmitresolveOwner/onConfigure/ownerSeat/mintOwnerClaim/transferOwnerand that route answers501. The two owner-seat routes are how the dashboard sees whether anyone has claimed an instance, and mints the claim link that binds its owner once the first-sign-in window has closed (see vertical-auth).owner-transferis the hand-over. YourtransferOwnerhook moves the owner of record; the package then seatstoinownerRoleKey, revokesfrom's, and callscompleteOwnerTransfer, in that order, so the scope always has a live owner seat. Sending the same hand-over again finishes one a failure left open, and once it is closed, answersdoneand changes nothing. Only the scope-level seat is revoked:fromRevoked: falsecan meanfromstill holds the role at the tenant level, which the platform, not the vertical, takes back. A reconcile's lockout repair re-seats whoever the record names, so after a hand-over it brings back the new owner, never the old one. - The gate — one
/internal/*middleware runs the platform-secret check; an unset secret fails closed (403). - The error envelope — a Hono
onErrorthat maps the kernel/engine vocabulary onto HTTP (permission denied → 403,not found / unknown scope → 404,invalid transition / immutable → 409, a runtime fault →502) and renders every failure as an RFC 9457 problem document —Content-Type: application/problem+json, with the platform's closedcodeand, where a module narrowed it, the module's ownreason.erroris still present as a copy ofdetailfor one migration window; readdetail. Registered last, so mounting the surface installs it. The shape is the one every surface answers with, described in API design § failures are data.
problemResponse(c, err)
The same envelope, for a vertical's own routes. The onError above is registered by mountPlatformSurface for the whole app, so a vertical that mounts the platform surface already answers problem+json everywhere; a vertical that owns its onError — to log, or to map its own domain errors to a status first — keeps the shape in one line:
import { problemResponse } from '@substrat-run/vertical-host';
app.onError((err, c) => problemResponse(c, err));An HTTPException that already carries its own response is handed back untouched, so a redirect or a WWW-Authenticate a route chose survives. demos/handlebar and demos/manyfold are the worked references.
mountOperations(app, operations, resolveStub, options?)
One route per declared operation, from the same object the module registers — the seam that reads If-Match (a stale tag → 412 precondition_failed) and Idempotency-Key (a reused key → 409 conflict, a replay → the stored response with Idempotency-Replayed: true) on every unsafe method, so a vertical never hand-parses either header. It maps the kernel's own vocabulary to a status (PermissionDenied → 403, a ZodError → 400, a runtime fault → 502) and re-throws everything else unchanged, so a vertical's domain errors reach app.onError exactly as before — this decides the status, problemResponse decides the shape. A throw that declared no code but whose sentence says "not found", "permission denied" or "invalid transition" still gets 404, 403 or 409 for now; that reading is deprecated and announced in the log (API design), so declare the code instead. Two declarations that would dispatch identically fail at mount, naming both. The headers and their semantics are specified in API design — §7 writes are safe to retry and §7b a read-modify-write says what it is writing over.
It also serves the API reference
mountOperations registers GET /api/docs and its self-hosted renderer at /api/docs/renderer.js automatically, and the OpenAPI document the page renders at GET /api/openapi.json. The document is derived from the operations the call mounts, the same catalog the routes and the MCP tools come from, and is read through resolveStub: a signed-out visitor gets a 401, which the page turns into a sign-in prompt. The page reads it with the browser's existing session; try-it calls stay on the app's origin. No CDN, asset build step, or per-app docs route is needed, and because both paths sit under /api, a dev server's Vite proxy and a hosted app's runWorkerFirst: ['/api/*'] already reach them.
docs: { info: { title, version } } names the derived document, and docs: { document } serves one the app already builds (with its own tags and prose) instead. A route registered at /api/docs or /api/openapi.json before mountOperations takes precedence; use docs: false to disable both when supplying your own reference. As with the other mounted routes, call mountOperations before an API catch-all.
It also mounts the MCP surface
The same call renders those operations a second way: an MCP endpoint at ${basePath}/mcp, one tool per operation that declares http, dispatching through the same resolveStub and the same permission checks. On by default and zero rows of setup — mcp: false in the options turns it off, and mcp: { path, serverInfo } configures it. Per operation, mcp: false keeps a machine-facing route out of the tool list.
mcpToolsOf(operations) is exported so a vertical can see or assert its own tool surface without standing up a server. See the MCP surface.
The scope host is structural
hostFor returns anything satisfying the VerticalScopeHost interface — the …Local methods plus the introspection and platform-request reads. Every member is required, and the list grows with the routes above: beside the lifecycle halves (provisionScopeLocal, restoreScopeLocal, projectRolesLocal, exportScopeLocal, snapshotScopeLocal, deleteScopeLocal, migrationBookmarksLocal, rewindScopeLocal) it now needs appliedMigrationsLocal (#1320) and the six event reads — entityHistoryLocal, facetEventsLocal, eventCauseLocal, eventEffectsLocal, invocationEventsLocal, deadLettersLocal — plus the introspection reads (introspectScopeTables, introspectScopeTable, introspectScopeQuery, and readTombstoneTable, #2563), the denial reads (listDenialsLocal, summarizeDenialsLocal), the platform-request reads and settle (listPlatformRequests, listPlatformRequestHistory, settlePlatformRequest), and the connector write-back's far end (connectorInvokeLocal, connectorAttachmentUploadLocal, connectorAttachmentOpenLocal, connectorGrantLocal). A host written against an older list fails to compile, which is the point of the interface being structural. The package therefore depends on neither @substrat-run/adapter-cloudflare nor any concrete host, and a future adapter fits the same shape.
The table page, the console and the held flag (#2563)
introspectScopeTable and introspectScopeQuery refuse a scope the deployment does not hold (409, the shared sentence). readTombstoneTable does not: the carry reads a wiped copy's _substrat_meta tombstone through it, and only the carry and its cleanup call it. On the wire, GET /internal/tables/:table runs the guarded read only when the query carries held=1 (strictly that value; 0, true, an empty value or none read as readTombstoneTable, so a control plane that predates the flag keeps working). POST /internal/query is guarded outright and takes no flag. The default flips to guarded in a later release.
Self-enforcing
A vertical that never calls mountPlatformSurface has no /internal/provision, so it fails to provision on first deploy and in its scenario test — louder than any lint could be.
mountPublicSurface(app, options)
A surface anybody's browser may call, from a page you never served — a support widget, an embeddable booking form. The other two mounts both assume a caller: mountPlatformSurface is gated by the platform secret, mountOperations resolves a stub from whatever the vertical authenticated. A visitor in a chat bubble has neither, and never gets a principal.
import { mountPublicSurface } from '@substrat-run/vertical-host';
mountPublicSurface(app, {
service: 'widget', // the service principal this surface runs as, named by you
basePath: '/widget',
resolveActor: async (c, { origin, service }) => {
const desk = await deskFor(c, origin); // which install — from the request, never the body
if (!desk) return null; // → 403, same answer as an unlisted page
const stub = await stubFor(desk, service);
const invoke = <T,>(op: string, input: unknown) => stub.invoke(op, input) as Promise<T>;
const { origins } = await invoke<{ origins: string[] }>('desk/widget-origins', {});
return { invoke, allowedOrigins: origins }; // read LIVE, per request
},
routes: (route) => {
route.post('/sessions', async (c, { actor, origin }) =>
c.json(await actor.invoke('desk/widget-start', { origin })),
);
},
});Three properties, and they are the reason this is platform code rather than a snippet:
- It runs as a declared service principal, and only that. No header, cookie or body field on a public request selects an actor — you name one service at mount, and every call is invoked as whatever
resolveActoranswers for it. A public surface that can be talked into a different principal is not public, it is unauthenticated privilege. - CORS is answered in middleware, from an async resolver, per request. Not
hono/cors: itsorigincallback is synchronous, so an allowlist living in a scope has to be cached at boot — and the cached copy disagrees with the live one the moment an admin edits it. The preflight is the first place the live list has to be true, since a browser that cached a permissive one never sends the request. - The refusal happens before the handler. Withholding
access-control-allow-originstops a browser reading a response; it does nothing to stop the write behind it. So an unlisted origin never reaches a route, and a page holding a leaked session token cannot post from an origin the install never listed.
The Origin header is what is checked — a browser sets it and a page cannot forge it — never a body field, which would be a suggestion. Refusals are thrown, so they go through the same onError every other refusal on the worker does. Paths are relative to basePath, so a route cannot be declared outside the middleware guarding it, and the preflight advertises exactly the methods the surface registered. demos/ticket0 is the worked reference. Rate limiting is not here yet.
mountLiveReads(app, options)
The route a page holds open to hear that something changed: GET /api/live, a WebSocket subscription to the scope's change feed. A frame names the entity that changed, and the page re-reads it through the operation it already calls. Mount it on both hosts:
import { mountLiveReads } from '@substrat-run/vertical-host';
mountLiveReads(app, {
live: (c) => hostFor(c.env).liveReads, // undefined on the pure host
subscriber: async (c) => {
const node = nodeFor(c.req.raw, c.env); // tenant + scope, as the router asserted them
const principal = await principalFor(c.env, c.req.raw); // your own session: the principal only
return principal ? { ...node, principal } : null;
},
});Take the tenant and scope from where the rest of your routes take them, the node the router asserted for this request, and only the principal from the session. Never take the scope from the session or from anything the client sent: the socket would then subscribe to whichever scope the cookie or the query string named.
Register it before mountOperations. It decides four things, in this order:
- It is a WebSocket handshake. Anything without
Upgrade: websocketis426withx-substrat-live: not-an-upgrade, before anything else is asked. This is what makes the next rule safe: a browser's WebSocket API always sendsOrigin, while a plain cross-site GET carrying aSameSite=Laxcookie may not. - The page asking is your own. A browser sends cookies on a WebSocket handshake, and a WebSocket handshake is not subject to CORS. A
SameSite=Laxsession cookie does not help either, because another tenant's subdomain of the platform's domain is the same site. So the route compares theOriginheader with the request's own origin, exactly (scheme, host and port), and answers403on any difference, includingOrigin: null. The host is not asked andsubscriberis not called. A WebSocket handshake with noOrigindid not come from a browser page, and goes through. Behind a TLS-terminating proxy on a self-hosted node server, the request's URL ishttpwhile the page'sOriginishttps, so the route answers403. That costs only the push: a client that keeps its poll as the floor, as ticket0's does, goes on polling. - This host can push at all. The pure host has no
liveReads, so the route answers501withx-substrat-live: poll. That is the same header the hosted adapter sets on its own refusals, so a client that reads it keeps polling whichever end said no. The name is exported from@substrat-run/contractsasLIVE_MODE_HEADER, with its values asLiveRefusal. - Who is asking. Your
subscribercallback, from your own session.nullis401, never a subscription as some default principal.
The route does not decide what a subscriber hears. The scope checks every frame against the liveTargets read permission your module declares, on that frame's entity, so subscribing grants nothing. path moves the route; the gate moves with it. demos/ticket0 is the worked reference.
Narrowing a feed to one entity
subscriber may also return within, an EntityRef. The feed then carries only frames about that entity and what hangs beneath it through declared parent edges (what ctx.link and ctx.relink write), the same walk a permission check makes. The principal's own check still runs on every frame, so within can only take frames away. A screen watching one record passes it to stop hearing the rest of the scope.
Two built roots go further. Each replaces the per-frame check with a check on the root, and each frame is then a bare nudge ({ kind: 'nudge', id, at }) that names no event type and no entity, because the subscriber may not be able to read each row beneath it. Both come from @substrat-run/kernel, and a plain object of the same shape is refused: the builder is the only way in.
within: checkedWithin(entity, permission): for a signed-in principal whose grant reaches the root but not each row the way aliveTargetskey would. The principal must passpermissiononentityat the handshake, or the route answers403withx-substrat-live: forbidden. The check runs again, once per socket, on every pass that has a row beneath the root to announce. If it refuses or throws, the scope closes the socket (1008) before sending anything, and the client's reconnect meets the403. A withdrawn grant, or a root moved out of the grant's reach, therefore ends the feed. ticket0's portal does this (harness/portal-live.ts): rooted at a conversation's public thread, checked on the customer's ownconversation:read-own.within: vouchedWithin(entity, { because }): for a subscriber with no principal of its own, such as a visitor holding a session token. Your code proves access once, before subscribing, and nothing re-checks it, so a token revoked while the socket is open keeps receiving nudges until the socket closes. That is accepted for ticket0's widget (harness/widget-surface.ts), rooted at the visitor's session, because the nudge names nothing and every re-read it causes is checked again.
Prefer checkedWithin whenever there is a grant to check: authority then leaves with the grant. For either one, root the feed at an entity whose subtree holds only what the caller may see, because the walk is the row filter.
A socket ends with its session
subscriber may return expiresAt, the instant the caller's credential stops being valid. AuthSubject.expiresAt from @substrat-run/vertical-auth carries it: a session cookie's or a bearer's exp. A handshake at or past it is refused, and the scope closes the socket (1008) on its first pass at or past it, before sending anything, whatever the caller's grants still say. A scope nobody writes to has no passes, so the scope also sets an alarm for the earliest expiry among its sockets and closes them then. Without expiresAt, a socket lives until one end closes it.
How many sockets
One principal may hold 8 live sockets on a scope (LIVE_SOCKETS_PER_PRINCIPAL, the hosted adapter's own limit). The next is accepted and closed at once with LIVE_CLOSE.tooMany (4429), because a browser never sees a failed handshake's status, only a close code. A client should read 4429 as "poll and stop asking", not as a reason to reconnect. It can import LIVE_CLOSE from @substrat-run/contracts/wire-headers, which imports nothing, so a browser bundle takes the close codes without the rest of the package. checkedWithin gates are asked once per (principal, key, root) per pass, however many of those sockets share a root, when the scope reads its permissions from its own storage. A scope that still reads them from the directory asks once per socket instead (see below).
How fresh a live decision is
Each frame is decided just before it is sent. A decision the pass reuses for a later socket or row (a checkedWithin gate, the walk up from a row) is reused only while all three of these still hold, checked against the clock immediately before each send:
- nothing has been written to the scope since the decision was made;
- no grant, tuple, parent edge or entitlement in the scope has reached its
expires_atsince the decision was made; - the scope reads its permissions from its own storage. While it still reads tenant tuples, roles and org membership from the directory, a change there writes nothing in the scope, so the gate is asked again for every socket and row.
What stays open is a change that lands while a check is still being evaluated. It can let that one evaluation's frame through: one nudge, after the change. Frames carry no content (a nudge names no entity, and a change frame only names a row the subscriber could read when it was checked). The next frame, the next pass and the client's poll all see the change. This is the live-read freshness contract: a push is a hint that can be up to one evaluation stale, and the read it prompts is checked as usual.
requestConnectUrl(request)
How a vertical starts a provider consent round itself (#1310), for the case the connections hub does not fit: the people connecting a new client company to its bookkeeping provider work inside the vertical and have no dashboard account, and there is no credential to paste until the round has happened.
import { requestConnectUrl, ConnectUrlRequestError } from '@substrat-run/vertical-host';
// module.ts — the authorizing act, and the only place a permission is checked
const connectClientBooks: OperationHandler<{ clientId: string }, ConnectRequest> = async (ctx, raw) => {
assertAllowed(await ctx.check(PERM.manageIntegrations));
// …
return { provider: 'fortnox', subjectRef: client.id }; // no URL yet, and no secret ever
};
// server.ts — the effect
const request = await scope.invoke('crm/connect-client-books', { clientId });
const { url, expiresAt, vertical } = await requestConnectUrl({
controlPlaneUrl: env.CONTROL_PLANE_URL,
platformSecret: env.PLATFORM_SECRET,
tenantId, scopeId,
provider: request.provider,
createdBy: principal, // the principal whose check just passed
subjectRef: request.subjectRef, // your name for what is being connected, echoed back
returnUrl: `https://${host}/clients/${clientId}`,
});
return Response.redirect(url, 302);The permission check lives in the operation and the call lives in the harness, the shape the credential relay established: module code cannot fetch, and the authority behind a connect URL is a decision the scope already made. The vertical never learns the provider's client credentials, the consent code or the token — it receives a link and forgets it — and the resulting connection is stamped createdBy the principal named here, so the audit trail leads back to that ctx.check rather than to a platform actor. What the platform decides, not the caller: which vertical the connection lands on is re-derived from the directory's record for (tenantId, scopeId) and again at the callback, returnUrl must be an https surface bound to this scope, ttlSeconds may not exceed 900 (a longer value is refused with 400, not clamped — 15 minutes is the ceiling, and the default when it is omitted), and a provider with no platform consent round is refused, naming the paste door. A refusal throws ConnectUrlRequestError, carrying the relay's status so a route can map it, and the refusal's taxonomy code as problemCode (branch on that, not on the sentence), undefined when the platform named none. An unreachable control plane is a different failure: the fetch itself rejects, and that rejection is passed through as-is — a TypeError with no status — so a handler that wants to answer 502 for both catches the two separately. The call goes through POST /internal/connections/connect-url on the control plane, under the platform secret injected into every dispatch script.
mintConnectLink(request), listConnectLinks(request), revokeConnectLink(request)
The mailed sibling of requestConnectUrl. A bookkeeping bureau's staff work in the vertical, but the person who must approve at Fortnox is the client company's own administrator, who has no account anywhere and opens the link days later from an inbox. A connect URL lives fifteen minutes and cannot be withdrawn; a connect link is a row the platform holds, so it is single-use (the platform's callback spends it before storing the credential), revocable, and lives seven days unless you ask for up to thirty.
import { mintConnectLink, revokeConnectLink, ConnectLinkRequestError } from '@substrat-run/vertical-host';
// module.ts — the authorizing act, exactly as for requestConnectUrl
const inviteClientBooks: OperationHandler<{ clientId: string }, ConnectRequest> = async (ctx, raw) => {
assertAllowed(await ctx.check(PERM.manageIntegrations));
// …
return { provider: 'fortnox', subjectRef: client.id };
};
// server.ts — the effect
const request = await scope.invoke('crm/invite-client-books', { clientId });
const { url, link } = await mintConnectLink({
controlPlaneUrl: env.CONTROL_PLANE_URL,
platformSecret: env.PLATFORM_SECRET,
tenantId, scopeId,
provider: request.provider,
createdBy: principal, // the principal whose check just passed
subjectRef: request.subjectRef, // stored on the link, shown when you list it
ttlSeconds: 14 * 24 * 60 * 60, // optional: default 7 days, at most 30
});
await sendMail(client.fortnoxAdmin, url); // mail the URL; keep link.id, not the URL
await scope.invoke('crm/record-books-link', { clientId, linkId: link.id }); // on your client rowKeep the link id. Store it on your own row beside the subjectRef it was minted for — the client row, here. Reading and revoking a link both name it by that id; there is no "every link this scope minted" read.
listConnectLinks({ …, linkIds, provider?, outstanding? }) answers the named links (1 to 100 ids), newest first — each with its status (outstanding, used, revoked), expiresAt, and once spent, usedAt, accountRef and accountLabel (for Fortnox: the database number and the company name that consented). An id that is not one of this scope's links is left out of the answer rather than refused. revokeConnectLink({ …, linkId }) withdraws one; it is idempotent, and a link that was already used answers used — disconnect the connection instead. Both are permission-checked acts like the mint: the operation checks and returns the ids, the harness calls the helper. Only this scope's links are reachable; for a revoke, another scope's id is a 404, the same as an unknown one.
Where the round ends is yours to choose. Leave returnUrl out for a link mailed to someone with no account on your surface — the round then ends on the platform's own page, whose copy sends the reader back to whoever sent the link. With a returnUrl (https, on a hostname bound to this scope), success and every refusal return there, as for requestConnectUrl, plus link=<id>; a spent, withdrawn, lapsed or unknown link arrives as ?error=link_used, link_revoked, link_expired or link_unknown. A link is refused for a preview or a fork, and for a provider with no platform consent round. A refusal throws ConnectLinkRequestError with the relay's status, and its taxonomy code as problemCode (undefined when the platform named none). The calls go through POST /internal/connections/connect-links, …/list and …/revoke under the platform secret. The tenant's admin also sees your outstanding links on the dashboard's integrations card and can revoke them there.
upsertConnection(request), bindConnection(request), unbindConnection(request), listBindings(request), syncConnections(request)
How a vertical stores a provider credential from its own admin screen, and binds a scope's own connection to that scope with that scope's options (#2732) — one folder of a file source per scope, say, where a tenant-wide landing would mirror the same folder into every scope.
import { upsertConnection, bindConnection, unbindConnection, listBindings, ConnectionRequestError } from '@substrat-run/vertical-host';
// module.ts — the authorizing act, and the only place a permission is checked
const connectSource: OperationHandler = async (ctx, raw) => {
assertAllowed(await ctx.check(PERM.manageSource));
return { principal: ctx.principal, folder: schema.parse(raw).folder };
};
// worker.ts — the effect
const { principal, folder } = await scope.invoke<{ principal: string; folder: string }>('drive/connect-source', { folder: body.folder });
const access = { controlPlaneUrl: env.CONTROL_PLANE_URL, platformSecret: env.PLATFORM_SECRET, tenantId, scopeId };
const { connectionId } = await upsertConnection({
...access,
provider: 'acme-files',
secret: { token }, // sealed by the platform, never echoed back
owner: 'scope', // this scope's own connection, not the tenant's
createdBy: principal,
});
const { options, boundAt } = await bindConnection({ ...access, connectionId, options: { folder }, boundBy: principal });
// later, from another permission-checked operation:
await unbindConnection({ ...access, connectionId, unboundBy: principal });The bodies are the relays' own request shapes (connectionRelayRequest, connectionBindRequest, connectionUnbindRequest in @substrat-run/contracts), and the answers are parsed by their result schemas. upsertConnection creates the connection, or rotates the live one's secret in place; it answers { connectionId, created, granted, probe? }, never the secret. Leave owner out for a tenant-wide connection, as before.
bindConnection binds through the on-request landing your running version declares for the provider, so the operation and the key it grants on this scope come from that declaration, never from the call. The connector validates and normalises options, and the answer { connectionId, scopeId, options, boundAt } carries the options as it stored them; a rebind keeps the options it does not name. unbindConnection drops the binding and takes the landing key back on this scope, keeps everything the scope already landed, and is idempotent; it answers { connectionId, scopeId, unbound: true }. Only the scope's own connection is reachable: another one answers 404, as an unknown one does.
Bind, unbind, the bindings read and an owner: 'scope' upsert need a proven caller: call them from the worker, on the request it is serving, never from inside a Durable Object. A refusal, or a 2xx that is not the relay's answer, throws ConnectionRequestError with the relay's status and its taxonomy code as problemCode (undefined when the platform named none). The calls go through POST /internal/connections/upsert, …/bind, …/unbind and …/bindings.
listBindings(request)
What a settings screen shows for the scope's source: "last synced", and the last error.
const { bindings } = await listBindings({ ...access });
// [{ connectionId, provider, status, options, boundAt, lastSyncedAt, lastError: { at, message } | null }]It lists the scope's own connections that are bound to it — never another scope's, and not a tenant-wide connection bound here, whose sweeps cover every scope it lands in and so cannot say how this one fares. status is the connection's (expired or error asks for a reconnect). lastSyncedAt is the last sweep that completed, and lastError the last that failed, in the platform's words with a reference staff can trace; the provider's own answer is never in it. Only sweeps since boundAt count, so a rebind starts afresh. Sweep records are kept 14 days, so a null means none in that window, not necessarily never, and lastError can be older than lastSyncedAt: compare the two to tell a past failure from a current one. A binding nothing polls (its sweep is skipped, or unsupported for that binding) reads null in both, as one not swept yet does.
Ask with health: true for how each binding fares as its connector keeps it, and for the tenant's connections bound to the scope as well:
const { bindings } = await listBindings({ ...access, health: true });
// [{ …, owner: 'scope' | 'tenant',
// health?: { caughtUp, stalled: [{ record, recordId, message, firstFailedAt, failedAt, attempts }], skipped: […], skippedTotal } }]health is per binding, which is why a tenant's connection can be listed with it; that one's lastSyncedAt and lastError are null, since its sweep record covers every scope. A sweep that moved past a record it could not land still completes, so health is what tells a stalled binding from a caught-up one: stalled names the records a walk waits at, skipped (at most 20, longest waiting first, skippedTotal counting them all) the ones it moved past, each with why. Only a connector that walks a provider's records reports it — WooCommerce today; other bindings carry no health. Opt-in, because a @substrat-run/vertical-host older than this field refuses an answer that carries it.
syncConnections(request)
A "Sync now" button (#2672): poll the scope's bindings of one provider now, instead of waiting for the platform's next pass, and show what the poll did.
// from a permission-checked operation, as with bind
const { bindings } = await syncConnections({ ...access, provider: 'fortnox' });
// [{ connectionId, outcome: 'landed' | 'unchanged' | 'failed' | 'in-progress', at, pending, error? }]Every binding of the scope counts: a tenant's connection bound here as well as the scope's own. The poll is the platform's own sweep narrowed to this scope, so an unchanged book lands nothing, and each call is paced under Fortnox's request rate as a pass is. A supplier-invoice binding is also held to a pass's budget of reads and its 90 s deadline: pending: true says one of them ran out and a later pass takes the rest, while what landed stays landed. A ledger binding has neither, so its poll runs to the end and pending is always false for it. The polls of a scope's bindings run one after another inside the one HTTP request (two invoice bindings can take up to 90 s each), and a caller that times out does not cancel them: the poll still runs and is recorded, so asking again straight away answers 429. Those limits are the call's own, not shared: a poll of this scope while the platform's pass polls another scope on the same Fortnox company paces separately, so Fortnox may answer some requests "too many" and the poll waits them out, and every call spends a fresh budget. Ask when a person asks, not on a timer. at is when the poll finished, the "last fetched" a screen shows. A failed binding's error is the platform's words with a reference staff can trace. in-progress means another call writing that binding's state (the platform's own pass, an earlier ask still running, or an event being delivered to the connector) was under way, so nothing ran for it and nothing was recorded; ask again later. An empty bindings means the scope has no binding of the provider.
A binding polled for this scope in the last minute refuses the whole call with 429; nothing is queued, so ask again later. A provider whose bindings cannot be polled on request answers 501; today that is every provider but Fortnox. The caller must be proven as the scope, as with bind. The call goes through POST /internal/connections/sync.
mailInAddress(request)
This scope's inbound mail address (#2611): ask for one, read it, rotate it, or give it up. Mail sent to it lands through the operation your manifest declares under connections: [{ provider: 'mail-in', … }], with attachment bytes stored on the entity that operation answers.
import { mailInAddress, MailInAddressError } from '@substrat-run/vertical-host';
const { principal } = await scope.invoke('docs/manage-mail-in', {}); // your ctx.check
const address = await mailInAddress({
controlPlaneUrl: env.CONTROL_PLANE_URL,
platformSecret: env.PLATFORM_SECRET,
tenantId, scopeId,
action: 'request', // 'get' | 'request' | 'rotate' | 'revoke'
createdBy: principal, // required for everything but 'get'
allowlist: ['me@example.com'], // optional; replaces the list
});
// address?.address === 'mail+docs-x7k2…@in.substrat.run', or null when the scope has noneThe same split as requestConnectUrl: the check in the operation, the call in the worker. Unlike it, the platform requires a proven caller for every action, a read included — an address delivers into the scope it names — so call it from the worker, never from inside a Durable Object. Which operation and key the address lands through is read from the manifest the scope runs, never from this call; a vertical that declares none is refused with 409. A refusal throws MailInAddressError with the relay's status, and its taxonomy code as problemCode (undefined when the platform named none). The call goes through POST /internal/mail-in/address.
mountUploadLinkRedeem(app, options)
Mounts PUT and POST at /api/attachment-uploads/:entityType/:entityId/:secret, the path ctx.attachments.mintUploadUrl returns, and redeems one upload link per request through the host's inspectUploadLink and redeemUploadLink:
import { mountUploadLinkRedeem } from '@substrat-run/vertical-host';
mountUploadLinkRedeem(app, { host: () => host, node: (c) => nodeOf(c) });| Request | |
|---|---|
| body | the file's bytes, read under the link's size ceiling |
?filename=, Content-Disposition | the file name, when the link fixed none |
Content-Type | the media type, unless absent or generic |
Idempotency-Key | optional: 16 to 255 visible ASCII characters, with no space, " or \ (a UUID or a ULID). "…" is read without its quotes |
The answer is { id, filename, contentType, size, sha256 }: 201 when the file was stored by this request, and 200 when the request repeats, with the same Idempotency-Key and the same bytes, the redemption that spent the link, up to 10 minutes after the link's expiry. The refusals are 400, 403, 404, 410, 413, 415 and 422. Attachments has the table, and A lost reply the replay's rules.
createModelHost(options) — from @substrat-run/vertical-host/model
The platform's model host: governance around one language-model call, provider-neutral. Master plan §5.7 / D-18 splits the AI capability in two — the model is an adapter (any row of @substrat-run/model-providers), the governance is the kernel's — and this is the governance, at the host layer:
import { createAnthropic } from '@ai-sdk/anthropic';
import { createModelHost } from '@substrat-run/vertical-host/model';
const models = createModelHost({
env, // the worker's own bindings — platform-held credentials
aiBinding: env.AI, // the Workers AI binding: the cloudflare row then needs no credential (bound when package.json declares substrat.usesModels)
factories: { anthropic: createAnthropic }, // the direct rows this bundle statically carries
guard: async ({ spec, attribution }) => { // policy, before the bytes go out — throw to refuse
if (await spentToday(attribution.tenant) > budget) throw new Error('daily budget exhausted');
},
record: (line) => ledger.write(line), // the one fact every call produces
});
const run = await models.run({
spec: 'cloudflare:@cf/meta/llama-3.1-8b-instruct-fp8', // whatever the tenant picked
attribution: { tenant, scope, vertical, version, operation: 'ticket0/answer' },
system, prompt, maxOutputTokens: 400,
});
run.text; // the answer
run.line; // the ModelUsageLine, already handed to `record`No provider key. A vertical that answers with a model declares "usesModels": true under substrat in its package.json. A push then binds the platform's model runtime to the worker as env.AI, versioned with the code like outbound; without the declaration there is no binding. The Cloudflare row then runs with no credential on the script, and the platform's own account pays. demos/ticket0/src/worker.ts (modelHostFor) is a worked example.
What it does, in order: resolve the spec against platform-held credentials (only the row's own variables — never a per-install token); consult guard; run; turn the AI SDK's usage into one ModelUsageLine — token counts as the provider reported them (reported: false and zeros when it reported none; never an estimate that becomes a bill), listUsd from the rate card on our side (null for a model the card does not know — unpriced, not $0), and the five fixed attribution keys tenant / scope / vertical / version / operation (the smallest per-request metadata limit among the providers we route through is five, so a sixth key is refused at the line rather than silently dropped on the wire). A record that throws fails the run: a call that could not be recorded must not look like one that was.
Tools and conversations. Instead of prompt, a request may carry messages, a conversation oldest first and ending with the user's turn (exactly one of the two). It may also carry tools: each is { description, input, execute }, where input is a Zod schema the model's arguments are parsed with and execute is your code, running with your authority. A tool call runs execute, hands its result back to the model, and the run goes on, up to maxSteps model calls (default 4, at most MODEL_MAX_STEPS, 8). The guard runs once, before the first call: a request with tools is one decision to spend. The usage line covers every step, priced per step. run.steps lists each model call with the tool calls it made and their results, which is what a turn record or a "query it ran" view shows.
const run = await models.run({
spec, attribution,
system,
messages: [{ role: 'user', content: 'Why do uploads fail?' }],
tools: {
list_findings: {
description: 'List the team’s open findings',
input: z.object({ limit: z.number().int().max(25).optional() }),
execute: async ({ limit }) => ({ findings: await readFindingsAsTheCaller(limit) }),
},
},
maxSteps: 4,
});
run.steps; // [{ text, toolCalls: [{ callId, tool, input }], toolResults: [{ callId, tool, output }] }, …]status(spec) answers a settings screen — is this row configured on the platform, and what is it missing — without running anything.
It lives around operations, not on OperationContext: a model call is a multi-second network round-trip, and holding a scope's transaction open across it would be the "no network in module code" rule broken from the inside. A vertical calls it from its harness and records the result through its own operations. Margin is not here either — the line carries list price; the platform's rate lives beside entitlements.
Trusting the edges
The code that reads what the router asserted about a request, and writes that assertion down. It lived in the kernel until #1978; nothing in it needs a kernel guarantee.
readRoutedNode(headers, options),RouterAssertionError— the vertical's side of the router contract: read the(tenant, scope, surface)the router asserted over its service binding. A request with no assertion is legitimate — that is a standalone deploy — so it answersnull; a present but unsigned, incomplete or malformed one throws.invocationLog(options),withInvocationLog(worker, options),invocationStampOf— one structured log line per invocation, stamped with the tenant and scope the router asserted: the two dimensions Cloudflare cannot record, because observability is keyed on the script and one vertical's script serves every tenant that installed it. A successful request otherwise emits no log event at all, so this line is what gives a tenant-facing log view any rows. The stamp is written fromreadRoutedNode's verified answer, never from the header: a forged tenant would file chosen text on somebody else's dashboard, and an un-routed local invocation writes nothing.withInvocationLogis the same stamp around a whole module worker'sfetch, and it is what the platform wraps every uploaded vertical in (#1893). Mounted as middleware,app.use('*', invocationLog({ routerSecret }))first on a Hono app, it writes the line itself when nothing outside stamped the request, and steps aside when something did: the two share one stamp per request throughinvocationStampOf, so a request is never logged twice.pnpm lint:invocation-logrefuses a missing, late or secretless mount (#1418). The line's shape,InvocationLogLine, is the kernel's (invocation-line.ts), re-exported here.requestIdOf(c)— the id the stamp minted for the request a Hono context serves (#2192), orundefinedon a request nothing stamped. The same value goes out on every response the stamped request gets, asx-substrat-request-id(REQUEST_ID_HEADERin contracts), and on every problem body the platform renders for it, asrequestId: it is the line'sinvocationId, the id the dashboard's request view opens. For a vertical to repeat in an envelope or a log line of its own;ctx.requestIdis the same value inside an operation.assertPlatformCall,PlatformCallError— is the platform itself calling? Defined in@substrat-run/contracts/wire-auth, because the control plane checks it too, and re-exported here.kickFlags(setHeader)— both response flags that ask the router to act on a scope now rather than at the next sweep, as the scope stub options that raise them.
License
AGPL-3.0-only (dual-licensed commercially).