create-substrat 0.6.3 → 0.7.0

package/template/src/worker.ts

@@ -2,9 +2,10 @@
  * This vertical as a deployable Cloudflare Worker — SANDBOX-CLEAN and
  * control-plane-less: the shape `substrat push` deploys into the platform's
  * dispatch namespace. Its only durable stores are its OWN DO classes — `SCOPE`
- * (kernel + engines + this vertical, bundled) and `SWEEPER` (the deployment's
- * own timer, #461); no CONTROL_PLANE binding, no service bindings, no ASSETS
- * binding — the platform refuses those.
+ * (kernel + engines + this vertical, bundled), `SWEEPER` (the deployment's own
+ * timer, #461) and `CONFIG` (per-instance settings delivered by the platform);
+ * no CONTROL_PLANE binding, no service bindings, no ASSETS binding — the
+ * platform refuses those.
  *
  * `substrat push` derives the deploy config from `substrat.runtimeNeeds` in
  * package.json (entry = this file, stores = the DO classes exported here) —
@@ -25,8 +26,10 @@ import type { Context } from 'hono';
 import { HTTPException } from 'hono/http-exception';
 import {
   principalId,
+  resolveScopedEnvSpec,
   scopeId,
   tenantId,
+  z,
   type PrincipalId,
   type ScopeId,
   type TenantId,
@@ -41,10 +44,21 @@ import {
 import { readRoutedNode, RouterAssertionError, type ScopeStub } from '@substrat-run/kernel';
 import { mountPlatformSurface } from '@substrat-run/vertical-host';
 import { MODULES, OWNER_ROLE_KEY, ROLES } from './provision.js';
+import { SHOP_ENV } from './manifest.js';
+import { mountApi } from './routes.js';
+import { AUTH_CONFIG_KEY, ConfigDO, type ConfigDo } from './config-do.js';
 
 /** The scope-DO class = the app binary: kernel + engines + this vertical, bundled. */
 export const ScopeDO = defineScopeDO(MODULES, {});
 
+/**
+ * The per-instance config store (`config-do.ts`) — one per tenant, rows keyed by scope.
+ * Declared as a store in package.json `substrat.runtimeNeeds.stores`, like `ScopeDO`
+ * above and `SweeperDO` below. Re-exported because workerd resolves a DO class from the
+ * ENTRY module's exports; defining it in another file is fine, hiding it here is not.
+ */
+export { ConfigDO };
+
 /**
  * The deployment's own timer (#461): a roster-keeping singleton whose alarm runs
  * each provisioned scope's due recurring work — executor retries and any
@@ -82,6 +96,8 @@ interface Env {
   SCOPE: DurableObjectNamespace;
   /** The roster-keeping sweep singleton — the deployment's own timer (#461). */
   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;
   /** Shared secret the router presents (how this worker knows the asserted node is real). */
@@ -110,6 +126,49 @@ function hostFor(env: Env): CloudflareScopeHost {
   return host;
 }
 
+/** This tenant's config DO — one per tenant, holding a row set per scope. */
+function configDo(env: Env, node: Node): DurableObjectStub & ConfigDo {
+  return env.CONFIG.get(env.CONFIG.idFromName(node.tenantId)) as DurableObjectStub & ConfigDo;
+}
+
+/**
+ * The scope's delivered auth choice. Parsed LENIENTLY on purpose: an absent or
+ * malformed entry means "nothing delivered", never a throw, so a bad delivery can
+ * never lock an instance out of its own login.
+ */
+const authChoice = z.object({
+  mode: z.literal('oidc'),
+  issuer: z.string().min(1),
+  clientId: z.string().min(1).optional(),
+  clientSecret: z.string().min(1).optional(),
+});
+
+/**
+ * Everything this instance was configured with, in ONE DO hop: the ordinary declared
+ * settings (`SHOP_ENV`) resolved delivered > env > default, and the structured
+ * `substrat:auth` choice the dashboard's Identity tab sends.
+ *
+ * Reading settings THROUGH this — rather than off `env` — is the whole reason the
+ * `/internal/configure` hook exists: a spec `default` rides as a worker binding shared
+ * by every install of one serving script, so `env.SHOP_NAME` is the same string for
+ * every tenant no matter what any of them saved.
+ */
+async function instanceConfig(env: Env, node: Node) {
+  const delivered = await configDo(env, node).getScopeConfig(node.scopeId);
+  const settings = resolveScopedEnvSpec(SHOP_ENV, env as unknown as Record<string, unknown>, delivered).values;
+  let identity: z.infer<typeof authChoice> | null = null;
+  const raw = delivered[AUTH_CONFIG_KEY];
+  if (raw) {
+    try {
+      const parsed = authChoice.safeParse(JSON.parse(raw));
+      identity = parsed.success ? parsed.data : null;
+    } catch {
+      identity = null;
+    }
+  }
+  return { settings, identity };
+}
+
 /**
  * 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
@@ -127,25 +186,49 @@ async function authenticatedPrincipal(req: Request, env: Env): Promise<Principal
 async function stub(c: Context<{ Bindings: Env }>): Promise<ScopeStub> {
   const node = nodeFor(c.req.raw, c.env);
   const principal = await authenticatedPrincipal(c.req.raw, c.env);
-  if (!principal) throw new HTTPException(401, { message: 'unauthorized' });
+  if (!principal) throw new HTTPException(401, { message: await unauthorizedReason(c.env, node) });
   return hostFor(c.env).getScope(principal, node.tenantId, node.scopeId);
 }
 
+/**
+ * Why the caller is nobody — a DIAGNOSIS, not a bare "unauthorized".
+ *
+ * The expensive case to debug is the one that looks like a platform bug and is not:
+ * a tenant picks an identity provider in the dashboard, the platform delivers it here
+ * successfully, and every request is still 401 — because this starter ships no auth.
+ * Saying so, and naming the seam, is the difference between a five-minute fix and a
+ * support thread. Only runs on the failure path, so it costs a DO hop on 401s alone.
+ */
+async function unauthorizedReason(env: Env, node: Node): Promise<string> {
+  try {
+    const { identity } = await instanceConfig(env, node);
+    if (identity) {
+      return `unauthorized — this instance has an identity provider configured (${identity.issuer}), but this vertical has not wired it up yet: implement \`authenticatedPrincipal\` in src/worker.ts (the auth seam)`;
+    }
+  } catch {
+    // The config store is unreachable — that is not the caller's problem to hear about.
+  }
+  return 'unauthorized';
+}
+
 const app = new Hono<{ Bindings: Env }>();
 
-// Who am I — resolves the caller without invoking anything.
+// 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.
 app.get('/api/me', async (c) => {
+  const node = nodeFor(c.req.raw, c.env);
   const principal = await authenticatedPrincipal(c.req.raw, c.env);
-  if (!principal) return c.json({ error: 'unauthorized' }, 401);
-  return c.json({ principal });
+  if (!principal) return c.json({ error: await unauthorizedReason(c.env, node) }, 401);
+  const { settings, identity } = await instanceConfig(c.env, node);
+  return c.json({ principal, settings, identity: identity ? { issuer: identity.issuer } : null });
 });
 
-// Generic invoke: the kernel checks a permission inside EVERY operation, so a
-// generic route is exactly as safe as one route per operation.
-app.post('/api/invoke', async (c) => {
-  const { op, input } = await c.req.json<{ op: string; input?: unknown }>();
-  return c.json((await (await stub(c)).invoke(op, input)) ?? null);
-});
+// ── The vertical's API — the SAME table `server.ts` mounts (src/routes.ts) ───
+// Including `/api/invoke`. Mounted BEFORE the platform surface: Hono keeps only the
+// last-registered `onError`, so the platform's envelope wins for the whole app — which
+// is harmless because both handlers classify through the same `classifyError`.
+mountApi(app, stub);
 
 // ── /internal/* — the platform-gated management contract ────────────────────
 // The control plane provisions, heals, inspects and restores installs through
@@ -173,6 +256,15 @@ mountPlatformSurface<Env>(app, {
   onDeleteScope: async (env, s) => {
     await sweeper(env).forgetScope(s);
   },
+  // Per-instance config delivery (the dashboard's Settings → Env and Identity tabs).
+  // WITHOUT this hook `/internal/configure` answers 501 for the life of the app: the
+  // dashboard saves the setting, reports `delivered: false`, and the running worker
+  // never sees it — including the `substrat:auth` issuer choice that is the difference
+  // between a working login and 401-on-everything. Store it; `instanceConfig` reads it
+  // back. Idempotent, so the platform's reconciliation sweep can re-deliver safely.
+  onConfigure: async (env, b) => {
+    await configDo(env, { tenantId: b.tenantId, scopeId: b.scopeId }).setScopeConfig(b.scopeId, b.entries);
+  },
 });
 
 // Unmatched /api/* fails as JSON; everything else gets a pointer, not a UI —
@@ -181,7 +273,7 @@ app.all('/api/*', (c) => c.json({ error: `unknown route: ${new URL(c.req.raw.url
 app.all('*', (c) =>
   c.json({
     service: 'substrat vertical',
-    api: 'POST /api/invoke { op, input }',
+    api: 'POST /api/invoke { op, input } — plus the named routes in src/routes.ts',
     docs: 'https://substrat.net',
   }),
 );

package/template/tsconfig.worker.json

@@ -9,5 +9,5 @@
     "skipLibCheck": true,
     "noEmit": true
   },
-  "include": ["src/worker.ts", "src/provision.ts", "src/manifest.ts", "src/migrations.ts", "src/module.ts"]
+  "include": ["src/worker.ts", "src/routes.ts", "src/config-do.ts", "src/provision.ts", "src/manifest.ts", "src/migrations.ts", "src/module.ts"]
 }