create-substrat 0.7.1 → 0.7.3

package/dev-servers.js

@@ -23,7 +23,15 @@
  * @property {Record<string,string>} [env] Env the `dev` script sets for this process.
  */
 
-/** The template ships one process: the Hono API. There is no web app to scaffold yet. */
+/**
+ * Two processes: the local OIDC issuer, and the Hono API that relies on it. There is no
+ * web app to scaffold yet.
+ *
+ * The issuer is a separate PROCESS rather than a branch inside the API on purpose — that
+ * is what keeps the vertical free of any dev-only auth path, and lets it be swapped for a
+ * real issuer by changing `OIDC_ISSUER` alone.
+ */
 export const DEV_SERVERS = [
+  { name: 'issuer', run: 'issuer', portEnv: 'ISSUER_PORT', portFrom: 'src/server.ts' },
   { name: 'api', run: 'server', portEnv: 'PORT', portFrom: 'src/server.ts' },
 ];

package/index.js

@@ -17,6 +17,7 @@ import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { DEV_SERVERS } from './dev-servers.js';
+import { TSCONFIG, VITEST_CONFIG } from './project-files.js';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const TEMPLATE = join(HERE, 'template');
@@ -35,10 +36,11 @@ const TEMPLATE = join(HERE, 'template');
 // The runtime packages release together off one version line (the changesets `fixed`
 // group), so one constant is right for all of them. Engines do NOT share a line —
 // each versions on its own, so one pin per engine, deliberately.
-const SUBSTRAT = '^0.84.0';
-const ENGINE_WORKORDER = '^0.8.0';
-const ENGINE_INVOICING = '^0.9.0';
-const BOUNDARY_LINT = '^0.1.0';
+const SUBSTRAT = '^0.86.0';
+const ENGINE_WORKORDER = '^0.8.2';
+const ENGINE_INVOICING = '^0.9.2';
+const BOUNDARY_LINT = '^0.1.2';
+const DEV_ISSUER = '^0.1.0';
 
 const DOCS = 'https://substrat.net';
 
@@ -117,7 +119,9 @@ function packageJson(name) {
         devServers: DEV_SERVERS,
       },
       scripts: {
-        dev: 'tsx watch src/server.ts',
+        // Two processes: the local OIDC issuer you sign in at, and the API.
+        dev: 'concurrently -n issuer,api -c magenta,blue "pnpm run issuer" "tsx watch src/server.ts"',
+        issuer: 'substrat-dev-issuer --personas src/personas.ts',
         server: 'tsx src/server.ts',
         test: 'vitest run',
         typecheck: 'tsc --noEmit && tsc -p tsconfig.worker.json --noEmit',
@@ -137,6 +141,9 @@ function packageJson(name) {
       },
       devDependencies: {
         '@substrat-run/boundary-lint': BOUNDARY_LINT,
+        // The local OIDC issuer `pnpm dev` signs you in at. A devDependency on
+        // purpose: it is never imported by anything the worker bundles.
+        '@substrat-run/dev-issuer': DEV_ISSUER,
         '@cloudflare/workers-types': '^4.20250109.0',
         '@types/better-sqlite3': '^9.6.0',
         '@types/node': '^22.0.0',
@@ -154,40 +161,6 @@ function packageJson(name) {
   )}\n`;
 }
 
-const TSCONFIG = `${JSON.stringify(
-  {
-    compilerOptions: {
-      target: 'ES2022',
-      module: 'NodeNext',
-      moduleResolution: 'NodeNext',
-      lib: ['ES2022'],
-      strict: true,
-      esModuleInterop: true,
-      skipLibCheck: true,
-      forceConsistentCasingInFileNames: true,
-      noEmit: true,
-      types: ['node'],
-    },
-    include: ['src', 'test'],
-    // The worker and its Cloudflare-only stores compile against workers-types
-    // under their own config (tsconfig.worker.json) — the node config must not
-    // see them. `src/routes.ts` is deliberately NOT excluded: the shared route
-    // table must typecheck under both, which is what keeps it host-agnostic.
-    exclude: ['src/worker.ts', 'src/config-do.ts'],
-  },
-  null,
-  2,
-)}\n`;
-
-const VITEST_CONFIG = `import { defineConfig } from 'vitest/config';
-
-export default defineConfig({
-  test: {
-    include: ['test/**/*.test.ts'],
-  },
-});
-`;
-
 const GITIGNORE = `node_modules/
 dist/
 *.sqlite

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-substrat",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "Scaffold a Substrat vertical — `npm create substrat <dir>`.",
   "license": "Apache-2.0",
   "repository": {
@@ -25,6 +25,7 @@
   "files": [
     "index.js",
     "dev-servers.js",
+    "project-files.js",
     "template"
   ],
   "engines": {

package/project-files.js

@@ -0,0 +1,51 @@
+/**
+ * The generated project files — the configs a scaffold gets that are NOT in
+ * `template/`, because they are computed rather than copied.
+ *
+ * Split out of `index.js` for one reason: `tools/template-sync.mjs` materializes
+ * the template against the WORKSPACE (issue #878) and has to compile it under the
+ * same configs a real scaffold gets. Two hand-kept copies of a tsconfig is the
+ * drift class this repo has been bitten by repeatedly, so there is one copy and
+ * both readers import it.
+ *
+ * `packageJson()` deliberately stays in `index.js`: it interpolates the emitted
+ * pin block, and `tools/pins-emit.mts` writes that block into `index.js` by path.
+ * The workspace check does not want those pins anyway — resolving `@substrat-run/*`
+ * from npm is exactly what it is NOT doing.
+ *
+ * Dependency-free, like everything else in this package.
+ */
+
+export const TSCONFIG = `${JSON.stringify(
+  {
+    compilerOptions: {
+      target: 'ES2022',
+      module: 'NodeNext',
+      moduleResolution: 'NodeNext',
+      lib: ['ES2022'],
+      strict: true,
+      esModuleInterop: true,
+      skipLibCheck: true,
+      forceConsistentCasingInFileNames: true,
+      noEmit: true,
+      types: ['node'],
+    },
+    include: ['src', 'test'],
+    // The worker and its Cloudflare-only stores compile against workers-types
+    // under their own config (tsconfig.worker.json) — the node config must not
+    // see them. `src/routes.ts` is deliberately NOT excluded: the shared route
+    // table must typecheck under both, which is what keeps it host-agnostic.
+    exclude: ['src/worker.ts', 'src/config-do.ts'],
+  },
+  null,
+  2,
+)}\n`;
+
+export const VITEST_CONFIG = `import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    include: ['test/**/*.test.ts'],
+  },
+});
+`;

package/template/.claude/launch.json

@@ -1,6 +1,16 @@
 {
   "version": "0.0.1",
   "configurations": [
+    {
+      "name": "issuer",
+      "runtimeExecutable": "pnpm",
+      "runtimeArgs": [
+        "run",
+        "issuer"
+      ],
+      "port": 8879,
+      "autoPort": false
+    },
     {
       "name": "api",
       "runtimeExecutable": "pnpm",

package/template/.substrat/playbook.md

@@ -191,9 +191,11 @@ plain language, so nothing there is a surprise:
    cross-tenant attacker gets nothing).
 9. **Open decisions** — each with a **recommended default**, so the user chooses rather
    than specifies:
-   - **Auth.** Local dev uses an `x-principal` header — a dev seam, not a login. Real auth
-     gates *exposing* the app, not *building* it — but if the app will be deployed for real
-     users, wire the OIDC seam from the start: the standard is a **separate OIDC issuer**
+   - **Auth.** Local dev signs in at `@substrat-run/dev-issuer`, a real OIDC provider you
+     authenticate with by picking a name — so the local login is already the production
+     flow, and there is no dev-only auth path to unpick later. Real auth still gates
+     *exposing* the app, not *building* it, and the hosted worker resolves nobody until you
+     wire its seam; if the app will be deployed for real users, do that from the start: the standard is a **separate OIDC issuer**
      (an Auth Server app in the same team, or an external issuer — Supabase/Auth0/AuthHero/
      Keycloak), never per-app credential storage. The vertical is a pure OIDC **relying
      party**: depend on `@substrat-run/vertical-auth`, bind its `IdentityDO` (the
@@ -407,13 +409,54 @@ pnpm dev                         # API on :8871 (PORT=… WEB_PORT=… to move i
 ```
 
 Then **actually exercise it** — don't just report that the server started. A green scenario
-test never touches `server.ts`, its routes, or the principal picker, so it can be green
-while the app is broken. Drive the real flow with curl (create → assign → start → report →
-complete) as two personas, switching `x-principal` to show a denial landing as a denial.
-The moment the attack fails is the demo; make sure the user sees it.
+test never touches `server.ts`, its routes, or the login, so it can be green while the app
+is broken. Drive the real flow with curl (create → assign → start → report → complete) as
+two personas, so a denial lands as a denial. Get a session without a browser by minting a
+token at the issuer — `curl -XPOST localhost:8879/dev/token -d '{"sub":"dev|greta"}'` — and
+sending it as `Authorization: Bearer …`. The moment the attack fails is the demo; make sure
+the user sees it.
+
+If they want a UI, scaffold a minimal Vite + React app under `app/` with typed wrappers over
+the routes and a sign-in button that redirects to `/api/auth/login`. Ask first — it roughly
+doubles the work.
+
+**The same change that creates `app/` declares it** — before a single component is written.
+A UI ships as NATIVE assets: `substrat push` runs the declared build, hashes the output and
+uploads it to the runtime's own asset store, served from the edge without invoking the
+worker. Undeclared, the directory is never built, never uploaded, and the deployed vertical
+answers `/api/*` and 404s on `/` — a deploy that looks entirely successful, and a failure no
+gate before deploy can see (`pnpm test` never touches `server.ts`, boundary-lint has no
+opinion about static files, and a vertical with no UI must legitimately declare no assets).
 
-If they want a UI, scaffold a minimal Vite + React app under `app/` with a principal picker
-and typed wrappers over the routes. Ask first — it roughly doubles the work.
+```jsonc
+"substrat": {
+  "runtimeNeeds": {
+    "entry": "src/worker.ts",
+    "build": "npm --prefix app install && npm --prefix app run build",
+    "assets": {
+      "directory": "app/dist",
+      "notFoundHandling": "single-page-application",   // deep client routes → index.html
+      "runWorkerFirst": ["/api/*", "/internal/*"]      // only these reach the worker
+    }
+  }
+}
+```
+
+`build` runs before assets are collected, so the directory may be pure build output. Never
+base64-inline a built `app/dist` into a generated worker module: it costs ~+33 % script size
+and a worker invocation per image.
+
+Two more that each fail silently:
+
+- **`runWorkerFirst` must list every worker-owned prefix.** With
+  `notFoundHandling: "single-page-application"`, a missing `/api/*` entry answers every API
+  call with `index.html` — the app then reports parse errors instead of denials.
+- **The app calls its own origin** (`fetch('/api' + path)`), never a baked base URL. The Vite
+  `proxy` block is a dev-only convenience; `VITE_API_URL` or `localhost:8871` works on the
+  author's machine and reaches nothing from a phone.
+
+`substrat push` refuses an `app/` that nothing would serve, so this cannot reach a hostname
+undeclared — but the refusal is a backstop, not the instruction. Declare it here.
 
 ---
 
@@ -464,27 +507,26 @@ authenticated CLI, and the author never holds a Cloudflare token:
 - `substrat hostnames bind <slug> --surface <s> [--domain <d>]` — mint a live hostname, or
   record a custom domain pending DNS validation (`substrat hostnames verify`).
 
-**A SPA ships as NATIVE assets — never inline it into the worker.** Declare it in
-`runtimeNeeds` and `substrat push` builds, hashes, and uploads the directory to the
-runtime's own asset store, served from the edge without invoking the worker:
+**If this vertical has a UI, its `runtimeNeeds.assets` block was written back in Step 7**,
+when `app/` was created — that is the one description of it, and it is not repeated here so
+the two cannot drift. If you are deploying a vertical scaffolded before that rule existed,
+go read it now: an undeclared `app/` deploys clean and 404s at its own hostname. `substrat
+push` refuses that push, with the recipe.
 
-```jsonc
-"substrat": {
-  "runtimeNeeds": {
-    "entry": "src/worker.ts",
-    "build": "npm --prefix app install && npm --prefix app run build",
-    "assets": {
-      "directory": "app/dist",
-      "notFoundHandling": "single-page-application",   // deep client routes → index.html
-      "runWorkerFirst": ["/api/*", "/internal/*"]      // only these reach the worker
-    }
-  }
-}
+**A deploy is not done until the URL serves the app.** Two requests, and show the user both:
+
+```sh
+curl -si https://<hostname>/        | head -3   # expect 200 + content-type: text/html
+curl -si https://<hostname>/api/me  | head -3   # expect the worker, not index.html
 ```
 
-`build` runs before assets are collected, so the directory may be pure build output. Never
-base64-inline a built `app/dist` into a generated worker module: it costs ~+33 % script
-size and a worker invocation per image.
+Triage a 404 in one request instead of an hour — the two layers fail differently:
+
+| What you see | Where it broke |
+|---|---|
+| `404` with a Cloudflare body, `/internal/*` answers `403` | the worker ran; assets are undeclared or unbuilt |
+| `404` before any worker header | the hostname is not bound to this surface |
+| `/api/*` returns HTML | `runWorkerFirst` is missing that prefix |
 
 **Let changesets own the version, and pass it to push explicitly** — the default bump walks
 the registry forward on its own, so `package.json` and the registry drift apart within a
@@ -511,8 +553,9 @@ the version you just replaced. Changesets needs a git repo with a commit on the
 Updates deploy **in place** from one stable script — data carries forward, migrations run
 against prod data, backout is a time-boxed PITR rewind.
 
-Before deploying: the `x-principal` dev header **must** be gone. Shipping it is a
-cross-tenant hole with a UI.
+Before deploying: `worker.ts`'s auth seam **must** be wired — it resolves nobody as it
+ships, so every `/api/*` call is 401 until you do. Never substitute a header that names the
+caller: that is a cross-tenant hole with a UI, which is why the starter no longer has one.
 
 ---
 

package/template/AGENTS.md

@@ -66,9 +66,16 @@ modules defined anywhere else will run locally and silently not deploy.
 `worker.ts` **mounts** the platform's `/internal/*` management contract via
 `mountPlatformSurface` from `@substrat-run/vertical-host` (one call — the routes
 and the `{ error }` envelope are authored there, not here, so they can't drift or
-ship half-done). What `worker.ts` still owns is **the auth seam** — the dev
-`x-principal` header is the only caller resolution until you wire real auth there;
-deploying with `ALLOW_DEV_HEADER` set is a cross-tenant hole with a UI.
+ship half-done). What `worker.ts` still owns is **the auth seam** — it resolves
+nobody until you wire real auth there, and every `/api/*` call is 401 until you do.
+That is deliberate: there is no dev header to forget to turn off. `src/server.ts`
+shows the shape, signing in against the local OIDC issuer `pnpm dev` starts.
+
+**A UI ships as declared assets.** If `app/` exists, `substrat.runtimeNeeds.assets` must
+point at its build output and `runtimeNeeds.build` must produce it — otherwise the deployed
+vertical serves the API and 404s on `/`, with every local gate green. Declare it in the same
+change that creates `app/`, not at deploy time. (`substrat push` refuses an undeclared UI,
+but by then you are already deploying.)
 
 Among the hooks it passes, **`onConfigure` is the one you must not drop.** It is
 how per-instance settings reach the running app: the dashboard's Settings → Env

package/template/src/module.ts

@@ -3,15 +3,18 @@ import {
   compareDecimal,
   moneyOf,
   mulMoney,
+  pageVisible,
   z,
   type EntityRef,
   type Money,
+  type Page,
 } from '@substrat-run/contracts';
 import {
   assertAllowed,
   ulid,
   type ModuleRegistration,
   type OperationHandler,
+  type PageParams,
 } from '@substrat-run/kernel';
 import {
   closeWorkOrder,
@@ -244,15 +247,25 @@ const closeRepairOp: OperationHandler<{ orderId: string }, WorkOrder> = async (c
  * PER-ENTITY check per repair. A portal customer holds an entity-narrowed grant
  * on their own customer record, so the walk workorder → bike → customer lets
  * them through for their own repairs and no one else's.
+ *
+ * Paged by OVER-FETCHING, which is what a permission-filtered walk needs: a page
+ * of 20 rows read from the table can leave 3 standing after the proof walk, so the
+ * fetch size and the page size are not the same number and cannot be made the same
+ * number. `pageVisible` does the over-fetch and advances the cursor by the last row
+ * EXAMINED — advancing by the last row RETURNED would re-examine every rejected row
+ * on the next request, and a page the walk rejects entirely would never advance at
+ * all. So a SHORT page does not end this walk; only a null `nextCursor` does.
  */
-const portalRepairsOp: OperationHandler<undefined, WorkOrder[]> = async (ctx) => {
-  const visible: WorkOrder[] = [];
-  for (const order of listOrders(ctx)) {
-    const decision = await ctx.check(WO.read, { entityType: 'workorder', entityId: order.id });
-    if (decision.allowed) visible.push(order);
-  }
-  return visible;
-};
+const portalRepairsOp: OperationHandler<PageParams | undefined, Page<WorkOrder>> = async (
+  ctx,
+  input,
+) =>
+  pageVisible(
+    (p) => listOrders(ctx, { ...input, ...p }),
+    input,
+    async (order) =>
+      (await ctx.check(WO.read, { entityType: 'workorder', entityId: order.id })).allowed,
+  );
 
 const timelineInput = z.object({
   entityType: z.string().min(1),

package/template/src/personas.ts

@@ -0,0 +1,35 @@
+import type { DevPersona } from '@substrat-run/dev-issuer';
+
+/**
+ * The local dev cast — the ONE place the issuer and this vertical agree on who exists.
+ *
+ * `pnpm dev` starts `@substrat-run/dev-issuer` pointed at this file: a real OpenID Connect
+ * provider whose only shortcut is that `/authorize` lists names instead of asking for a
+ * password. `linkDevPersonas` reads the same array and binds each `sub` to a principal in
+ * the identity directory. Neither side holds a copy of the other's list.
+ *
+ * Nothing here is a bypass, and that is the point. The issuer asserts a subject and the
+ * directory maps it to a principal — the same two steps a deployed instance performs against
+ * a real issuer, so the login you exercise all day is the login your users will run. What
+ * stood here before was an `x-principal` header: a name the server was simply told and
+ * believed, which is an impersonation bypass, and which meant the dev login was one no
+ * deployment ever ran.
+ *
+ * Add or rename people here freely — this is your world. Keep the `sub` values stable and
+ * readable: they end up in an identity directory that outlives a restart.
+ */
+export const PERSONAS: DevPersona[] = [
+  { sub: 'dev|greta', name: 'Greta', email: 'greta@kedja.test', note: 'workshop-admin' },
+  { sub: 'dev|mans', name: 'Måns', email: 'mans@kedja.test', note: 'mechanic' },
+  { sub: 'dev|lisbeth', name: 'Lisbeth', email: 'lisbeth@example.test', note: 'portal customer' },
+  { sub: 'dev|otto', name: 'Otto', email: 'otto@example.test', note: 'portal customer' },
+  // The other shop, so the cross-tenant beat has someone to be turned away as.
+  { sub: 'dev|rutger', name: 'Rutger', email: 'rutger@trampolin.test', note: 'admin at a DIFFERENT shop' },
+];
+
+/**
+ * The identity pool these logins belong to (K-23). `central`: one issuer serves both demo
+ * tenants, so the same subject is the same person in each. Named for the pool rather than
+ * its URL, so moving the issuer's port does not orphan every link in `.data`.
+ */
+export const DEV_PROVIDER = 'oidc:dev-issuer';

package/template/src/routes.ts

@@ -5,8 +5,8 @@ import type { ScopeStub } from '@substrat-run/kernel';
 /**
  * The bike shop's HTTP API — ONE route table, adapter- and auth-agnostic.
  *
- * Both entrypoints mount this: `server.ts` (node, pure-SQLite adapter, `x-principal`
- * dev auth) and `worker.ts` (Cloudflare, Durable-Object adapter, the auth seam). Each
+ * Both entrypoints mount this: `server.ts` (node, pure-SQLite adapter, OIDC against the
+ * local dev issuer) and `worker.ts` (Cloudflare, Durable-Object adapter, the auth seam). Each
  * supplies a `resolveStub` that authenticates the caller its own way and returns a
  * capability `ScopeStub`; every route here is a thin wrapper over ONE operation, with
  * no business logic — the rules live in an operation or an engine.

package/template/src/seed.ts

@@ -17,6 +17,7 @@ import { ENTITLEMENT_KEYS, MODULES, OWNER_ROLE_KEY, portalPerms, ROLES } from '.
 // provision.ts — node-free so the worker bundles it and `substrat push` reads
 // it. Re-exported here for callers that treat seed.ts as the world's front door.
 export { ENTITY_GRANTS, MODULES, permissions, ROLES } from './provision.js';
+import { DEV_PROVIDER, PERSONAS } from './personas.js';
 
 // ============================================================================
 // The seeded world. TWO tenants on purpose: the first is the shop the scenario
@@ -221,3 +222,45 @@ export async function seedBikeShop(host: SqliteScopeHost, dir: string): Promise<
   writeFileSync(castPath, JSON.stringify(world, null, 2));
   return world;
 }
+
+/**
+ * Bind each dev persona's OIDC `sub` to its principal in the identity directory.
+ *
+ * This is the ordinary production seam, not a dev one: a deployed instance builds the same
+ * rows when someone claims the owner seat or accepts an invite. All that differs locally is
+ * that the subjects are known up front, so nobody has to click through a first-run claim
+ * after every data wipe.
+ *
+ * Run on EVERY boot rather than only on a fresh seed: `seedBikeShop` returns early once
+ * `cast.json` exists, and `linkIdentity` is idempotent for an unchanged binding, so
+ * re-running costs nothing and a wiped `.data` heals itself.
+ */
+export async function linkDevPersonas(host: SqliteScopeHost, world: BikeShopWorld): Promise<void> {
+  const staff = platformActorId.parse(ulid());
+  await host.admin.registerIdentityPool(staff, {
+    provider: DEV_PROVIDER,
+    topology: 'central',
+    tenantId: null,
+  });
+  // `scopeId` on the link is what carries a persona to their own node — Rutger into the
+  // other shop entirely, which is why the cross-tenant beat still runs with no persona
+  // table anywhere in the server.
+  const homes: Record<string, { principal: PrincipalId; tenantId: TenantId; scopeId: ScopeId }> = {
+    'dev|greta': { principal: world.greta, tenantId: world.t1, scopeId: world.s1 },
+    'dev|mans': { principal: world.mans, tenantId: world.t1, scopeId: world.s1 },
+    'dev|lisbeth': { principal: world.lisbeth, tenantId: world.t1, scopeId: world.s1 },
+    'dev|otto': { principal: world.otto, tenantId: world.t1, scopeId: world.s1 },
+    'dev|rutger': { principal: world.rutger, tenantId: world.t2, scopeId: world.s2 },
+  };
+  for (const persona of PERSONAS) {
+    const home = homes[persona.sub];
+    if (!home) continue;
+    await host.admin.linkIdentity(staff, {
+      provider: DEV_PROVIDER,
+      externalId: persona.sub,
+      principal: home.principal,
+      tenantId: home.tenantId,
+      scopeId: home.scopeId,
+    });
+  }
+}

package/template/src/server.ts

@@ -4,17 +4,38 @@ import { fileURLToPath } from 'node:url';
 import { serve } from '@hono/node-server';
 import { Hono } from 'hono';
 import type { Context } from 'hono';
-import { PermissionDenied, type ScopeStub } from '@substrat-run/kernel';
-import type { PrincipalId } from '@substrat-run/contracts';
-import { buildBikeShopHost, seedBikeShop, type BikeShopWorld } from './seed.js';
+import { HTTPException } from 'hono/http-exception';
+import { platformActorId } from '@substrat-run/contracts';
+import { ulid, type ScopeStub } from '@substrat-run/kernel';
+import { devLogin } from '@substrat-run/dev-issuer';
+import { buildBikeShopHost, linkDevPersonas, seedBikeShop, type BikeShopWorld } from './seed.js';
+import { DEV_PROVIDER } from './personas.js';
 import { mountApi } from './routes.js';
 
 // ============================================================================
 // The DEV entrypoint. It owns exactly three things — a SQLite host on disk, the
-// `x-principal` persona picker, and the port — and then mounts `routes.ts`, the
-// same route table `worker.ts` mounts. There is no business logic here and no
-// route here either: a route added to this file would exist in dev and 404 in
+// relying-party login, and the port — and then mounts `routes.ts`, the same
+// route table `worker.ts` mounts. There is no business logic here and no route
+// here either: a route added to this file would exist in dev and 404 in
 // production, which is the one failure this split exists to prevent.
+//
+// ── AUTH ────────────────────────────────────────────────────────────────────
+// An ordinary OpenID Connect round-trip, against whatever `OIDC_ISSUER` names.
+// `pnpm dev` starts `@substrat-run/dev-issuer` on :8879 — a real provider whose
+// only shortcut is that you pick a name instead of typing a password — so the
+// login you exercise locally is the one your users will run, and pointing this
+// at Auth0, Keycloak or your own issuer is a change of configuration, not code.
+//
+// There is deliberately NO dev header here. A header naming the caller is an
+// impersonation bypass; kept for convenience it becomes a second auth path that
+// no deployment runs, and one environment variable away from being live.
+// Impersonation for scripts lives at the issuer instead:
+//   curl -XPOST localhost:8879/dev/token -d '{"sub":"dev|greta"}'
+//
+// ── THE VITE PROXY, IF YOU ADD ONE ──────────────────────────────────────────
+// Do not set `changeOrigin` on a proxy in front of this server: the OIDC
+// `redirect_uri` is derived from the forwarded Host header, and rewriting it
+// sends the login callback to the API port instead of back to your app.
 // ============================================================================
 
 const dataDir = join(dirname(fileURLToPath(import.meta.url)), '..', '.data');
@@ -22,34 +43,46 @@ mkdirSync(dataDir, { recursive: true });
 
 const host = buildBikeShopHost(dataDir);
 const world: BikeShopWorld = await seedBikeShop(host, dataDir);
+await linkDevPersonas(host, world);
 
-// The dev cast, keyed by the `x-principal` header value. Every entry is a real
-// principal with real tuples — nothing here is a bypass.
-const CAST: Record<string, { name: string; principal: PrincipalId }> = {
-  greta: { name: 'Greta (workshop-admin)', principal: world.greta },
-  mans: { name: 'Måns (mechanic)', principal: world.mans },
-  lisbeth: { name: 'Lisbeth (portal customer)', principal: world.lisbeth },
-  otto: { name: 'Otto (portal customer)', principal: world.otto },
-  rutger: { name: 'Rutger (other shop — attacker)', principal: world.rutger },
-};
-
-function principalOf(c: Context): PrincipalId {
-  const who = c.req.header('x-principal') ?? 'greta';
-  const entry = CAST[who];
-  if (!entry) throw new PermissionDenied(`unknown principal: ${who}`);
-  return entry.principal;
-}
+// The local platform actor (a stub locally): directory reads are stamped with it.
+const staffActor = platformActorId.parse(ulid());
 
-function stub(c: Context): Promise<ScopeStub> {
-  return host.getScope(principalOf(c), world.t1, world.s1);
-}
+/**
+ * The relying party — login, callback, logout, plus `sub` → principal through the
+ * identity directory. The persona's tenant and scope come out of the link the seed
+ * wrote, which is why signing in as Rutger lands in the OTHER shop and every one of
+ * this shop's rows stays out of reach.
+ */
+// Both ports are bound in THIS file so they move together: `substrat.devServers` names
+// it for the API and for the issuer alike, and `ISSUER_PORT=… PORT=… pnpm dev` shifts the
+// pair without either end losing track of the other.
+const ISSUER_PORT = Number(process.env.ISSUER_PORT ?? 8879);
+const login = devLogin({
+  directory: host.admin,
+  actor: staffActor,
+  provider: DEV_PROVIDER,
+  issuer: process.env.OIDC_ISSUER ?? `http://localhost:${ISSUER_PORT}`,
+});
 
 const app = new Hono();
 
-// The persona picker — genuinely dev-only, so it stays out of the shared table.
-// Its ABSENCE in the worker is how a client can tell it is talking to a real
-// deployment; the worker answers `/api/me` instead.
-app.get('/api/cast', (c) => c.json(CAST));
+// Login, callback, logout. Accounts and passwords live at the issuer; this vertical
+// runs no credential store of its own.
+app.on(['GET', 'POST'], '/api/auth/*', (c) => login.handle(c.req.raw));
+
+/** Who is signed in, or 401 — the same question `worker.ts` answers. */
+app.get('/api/me', async (c) => {
+  const caller = await login.caller(c.req.raw.headers);
+  if (!caller) return c.json({ error: 'unauthorized' }, 401);
+  return c.json({ principal: caller.principal, display: caller.display });
+});
+
+async function stub(c: Context): Promise<ScopeStub> {
+  const caller = await login.caller(c.req.raw.headers);
+  if (!caller) throw new HTTPException(401, { message: 'unauthorized' });
+  return host.getScope(caller.principal, caller.tenantId, caller.scopeId);
+}
 
 // Everything else — including `/api/invoke` and the shared error envelope.
 mountApi(app, stub);
@@ -57,4 +90,4 @@ mountApi(app, stub);
 const PORT = Number(process.env.PORT ?? 8873);
 serve({ fetch: app.fetch, port: PORT });
 console.log(`Bike-shop API on http://localhost:${PORT} — data in ${dataDir}`);
-console.log(`Pick a principal with the "x-principal" header: ${Object.keys(CAST).join(', ')}`);
+console.log(`Sign in at http://localhost:${PORT}/api/auth/login — issuer: ${login.issuer}`);

package/template/src/worker.ts

@@ -12,20 +12,26 @@
  * you never author wrangler config.
  *
  * ── THE AUTH SEAM ────────────────────────────────────────────────────────────
- * This starter resolves a caller ONLY through the `x-principal` dev header,
- * gated on ALLOW_DEV_HEADER — an impersonation bypass by design, for local
- * `wrangler dev` and smoke tests. In production the gate is off and every
- * /api/* call is 401 until you wire real auth into `authenticatedPrincipal`
- * below (a session/bearer verifier that maps a login → PrincipalId — see
- * @substrat-run/vertical-auth, the platform's pluggable AuthProvider +
- * per-tenant identity DO, for the intended shape). Deploying with the dev
- * header enabled is a cross-tenant hole with a UI. ──────────────────────────
+ * This starter ships NO auth in the worker: every /api/* call is 401 until you
+ * wire `authenticatedPrincipal` below. That is deliberate and it is honest —
+ * there is nothing here that resolves a caller, in any environment, so there is
+ * nothing to accidentally deploy.
+ *
+ * It used to resolve a caller through an `x-principal` header gated on
+ * ALLOW_DEV_HEADER. That is an impersonation bypass — a cross-tenant hole with a
+ * UI, one environment variable from being live — and it is gone. `src/server.ts`
+ * shows the shape you want instead: @substrat-run/vertical-auth's
+ * `oidcRpAuthProvider` verifies the request against your issuer and hands you a
+ * subject; an identity directory maps that subject to a PrincipalId. The dev
+ * server can use `host.admin` as that directory. A hosted worker needs a durable
+ * one — @substrat-run/vertical-auth's per-tenant `IdentityDO` is the platform's,
+ * and it also gives you the owner-claim and invite flows a new install needs.
+ * ───────────────────────────────────────────────────────────────────────────
  */
 import { Hono } from 'hono';
 import type { Context } from 'hono';
 import { HTTPException } from 'hono/http-exception';
 import {
-  principalId,
   resolveScopedEnvSpec,
   scopeId,
   tenantId,
@@ -84,8 +90,12 @@ interface Node {
 }
 
 // A fixed dev node (valid ULIDs) — ONLY the fallback for local `wrangler dev`,
-// where there is no router to assert one; gated on ALLOW_DEV_HEADER (never set
-// in prod).
+// where there is no router to assert one; gated on ALLOW_DEV_NODE (never set in
+// prod).
+//
+// This is an ADDRESS, not an identity: it says which instance an un-routed local
+// request belongs to, and grants nobody anything. Keeping the two separate is why
+// it survived the removal of the dev header, which named the CALLER.
 const DEV_NODE: Node = {
   tenantId: tenantId.parse('01JZ00000000000000000DEV01'),
   scopeId: scopeId.parse('01JZ00000000000000000DEV02'),
@@ -98,8 +108,9 @@ interface Env {
   SWEEPER: DurableObjectNamespace;
   /** Per-instance config delivered by the platform (`/internal/configure`). */
   CONFIG: DurableObjectNamespace;
-  /** Local dev only: when 'true', trust the `x-principal` header. NEVER set in prod. */
-  ALLOW_DEV_HEADER?: string;
+  /** Local `wrangler dev` only: when 'true', fall back to DEV_NODE if no router
+   *  asserted a node. Addresses an instance; authenticates nobody. */
+  ALLOW_DEV_NODE?: string;
   /** Shared secret the router presents (how this worker knows the asserted node is real). */
   ROUTER_SECRET?: string;
   /** Shared secret the platform presents on /internal/* calls. */
@@ -116,7 +127,7 @@ function nodeFor(req: Request, env: Env): Node {
     throw e;
   }
   if (routed) return { tenantId: routed.tenantId, scopeId: routed.scopeId };
-  if (env.ALLOW_DEV_HEADER === 'true') return DEV_NODE;
+  if (env.ALLOW_DEV_NODE === 'true') return DEV_NODE;
   throw new HTTPException(503, { message: 'no scope was asserted for this request (missing router assertion)' });
 }
 
@@ -170,16 +181,23 @@ async function instanceConfig(env: Env, node: Node) {
 }
 
 /**
- * THE AUTH SEAM (see the header comment): resolve the caller to a PrincipalId,
- * or null for nobody. Replace the body with a real session/bearer verifier
- * before exposing this worker to users — the dev header is dev-only.
+ * THE AUTH SEAM (see the header comment): resolve the caller to a PrincipalId, or
+ * null for nobody. Two steps, and this starter ships neither:
+ *
+ *   1. Verify the request → a subject. `instanceConfig` already reads the issuer
+ *      the dashboard delivered as `substrat:auth`, so this is
+ *      `oidcRpAuthProvider({ issuer, clientId, clientSecret, sessionSecret }).resolve(...)`
+ *      — and you mount the same provider's `handle` on `/api/auth/*` for the login
+ *      round-trip. `src/server.ts` does exactly this against the local dev issuer.
+ *   2. Map that subject → a PrincipalId, per scope. This needs a durable store the
+ *      worker owns; @substrat-run/vertical-auth's `IdentityDO` is one, and carries
+ *      the owner-claim (first sign-in takes the seat) and invite flows with it.
+ *
+ * Returning null unconditionally is the safe default, not an oversight: a starter
+ * that guessed here would be a starter that let the wrong person in.
  */
-async function authenticatedPrincipal(req: Request, env: Env): Promise<PrincipalId | null> {
-  if (env.ALLOW_DEV_HEADER === 'true') {
-    const parsed = principalId.safeParse(req.headers.get('x-principal') ?? '');
-    if (parsed.success) return parsed.data;
-  }
-  return null; // ← wire real auth here
+async function authenticatedPrincipal(_req: Request, _env: Env): Promise<PrincipalId | null> {
+  return null; // ← wire real auth here (see the two steps above)
 }
 
 /** Resolve caller + routed node → a scope stub. 401 if nobody. */
@@ -214,8 +232,8 @@ async function unauthorizedReason(env: Env, node: Node): Promise<string> {
 const app = new Hono<{ Bindings: Env }>();
 
 // Who am I, and what instance am I on — resolves the caller without invoking
-// anything. Auth-shaped and host-specific, so it stays OUT of the shared table:
-// the dev server answers `/api/cast` instead, and a client can tell the two apart.
+// anything. Auth-shaped and host-specific, so it stays OUT of the shared table;
+// `server.ts` answers the same question from its own login.
 app.get('/api/me', async (c) => {
   const node = nodeFor(c.req.raw, c.env);
   const principal = await authenticatedPrincipal(c.req.raw, c.env);

package/template/test/scenario.test.ts

@@ -3,7 +3,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import Database from 'better-sqlite3';
 import { describe, it, expect, beforeAll, afterAll } from 'vitest';
-import { addMoney, moneyOf, mulMoney } from '@substrat-run/contracts';
+import { addMoney, moneyOf, mulMoney, type Page } from '@substrat-run/contracts';
 import type { ScopeStub } from '@substrat-run/kernel';
 import type { SqliteScopeHost } from '@substrat-run/adapter-sqlite';
 import type { WorkOrder, BillableLine } from '@substrat-run/engine-workorder';
@@ -105,7 +105,8 @@ describe('bike-shop scenario', () => {
       lisbeth.invoke('workorder/report-time', { orderId: repairId, hours: '1' }),
     ).rejects.toThrow(/permission denied/);
     // …but she CAN see her own repair through the portal walk.
-    await expect(lisbeth.invoke<WorkOrder[]>('shop/portal-repairs')).resolves.toHaveLength(1);
+    const lisbethSees = await lisbeth.invoke<Page<WorkOrder>>('shop/portal-repairs');
+    expect(lisbethSees.entries).toHaveLength(1);
 
     // The cross-tenant attacker: claiming t1's scope under his OWN tenant fails
     // the (tenant, scope) pair check…
@@ -120,7 +121,8 @@ describe('bike-shop scenario', () => {
     await expect(rutger.invoke('invoicing/list')).rejects.toThrow(/permission denied/);
     // …the control: the per-entity portal walk resolves for him too, and returns
     // exactly nothing — an open door onto an empty room, not a denial.
-    await expect(rutger.invoke<WorkOrder[]>('shop/portal-repairs')).resolves.toEqual([]);
+    const rutgerSees = await rutger.invoke<Page<WorkOrder>>('shop/portal-repairs');
+    expect(rutgerSees.entries).toEqual([]);
   });
 
   it('5. priced completion: the half-hour minimum bills, internal dropped, math exact', async () => {
@@ -153,9 +155,9 @@ describe('bike-shop scenario', () => {
   });
 
   it('6. star topology: the invoicing engine consumed workorder.completed', async () => {
-    const underlag = await greta.invoke<{ id: string; status: string; total: string }[]>(
-      'invoicing/list',
-    );
+    const { entries: underlag } = await greta.invoke<
+      Page<{ id: string; status: string; total: string }>
+    >('invoicing/list');
     expect(underlag).toHaveLength(1);
     expect(underlag[0]!.status).toBe('open');
     expect(underlag[0]!.total).toBe('336.5');
@@ -178,9 +180,10 @@ describe('bike-shop scenario', () => {
     const lisbeth = await host.getScope(w.lisbeth, w.t1, w.s1);
     const otto = await host.getScope(w.otto, w.t1, w.s1);
 
-    const hers = await lisbeth.invoke<WorkOrder[]>('shop/portal-repairs');
-    expect(hers.map((o) => o.id)).toEqual([repairId]);
-    await expect(otto.invoke<WorkOrder[]>('shop/portal-repairs')).resolves.toEqual([]);
+    const hers = await lisbeth.invoke<Page<WorkOrder>>('shop/portal-repairs');
+    expect(hers.entries.map((o) => o.id)).toEqual([repairId]);
+    const ottos = await otto.invoke<Page<WorkOrder>>('shop/portal-repairs');
+    expect(ottos.entries).toEqual([]);
 
     // Lisbeth reads her repair's timeline via the same entity walk…
     await expect(
@@ -194,7 +197,9 @@ describe('bike-shop scenario', () => {
   });
 
   it('8. export makes the underlag immutable; the next completion opens a new one', async () => {
-    const [underlag] = await greta.invoke<{ id: string }[]>('invoicing/list');
+    const {
+      entries: [underlag],
+    } = await greta.invoke<Page<{ id: string }>>('invoicing/list');
     await greta.invoke('invoicing/export', { underlagId: underlag!.id });
     await expect(greta.invoke('invoicing/export', { underlagId: underlag!.id })).rejects.toThrow(
       /immutable/,
@@ -214,7 +219,9 @@ describe('bike-shop scenario', () => {
     });
     await greta.invoke('shop/complete-repair', { orderId: repair2.id });
 
-    const all = await greta.invoke<{ status: string; total: string }[]>('invoicing/list');
+    const { entries: all } = await greta.invoke<Page<{ status: string; total: string }>>(
+      'invoicing/list',
+    );
     expect(all).toHaveLength(2);
     expect(all.filter((u) => u.status === 'open')).toHaveLength(1);
     expect(all.filter((u) => u.status === 'exported')).toHaveLength(1);