@ultimat3/cli 22.0.0 → 22.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "22.0.0",
+  "version": "22.2.0",
   "description": "The `x` binary: new, dev, build, verify, generate, db, mcp, doctor, deploy",
   "license": "MIT",
   "type": "module",
@@ -38,33 +38,33 @@
   },
   "dependencies": {
     "@babel/core": "^8.0.1",
-    "@ultimat3/action": "22.0.0",
-    "@ultimat3/admin": "22.0.0",
-    "@ultimat3/ai": "22.0.0",
-    "@ultimat3/auth": "22.0.0",
-    "@ultimat3/cache": "22.0.0",
-    "@ultimat3/core": "22.0.0",
-    "@ultimat3/db": "22.0.0",
-    "@ultimat3/entity": "22.0.0",
-    "@ultimat3/flags": "22.0.0",
-    "@ultimat3/http": "22.0.0",
-    "@ultimat3/i18n": "22.0.0",
-    "@ultimat3/jobs": "22.0.0",
-    "@ultimat3/mail": "22.0.0",
-    "@ultimat3/manifest": "22.0.0",
-    "@ultimat3/mcp": "22.0.0",
-    "@ultimat3/money": "22.0.0",
-    "@ultimat3/notify": "22.0.0",
-    "@ultimat3/policy": "22.0.0",
-    "@ultimat3/pwa": "22.0.0",
-    "@ultimat3/query": "22.0.0",
-    "@ultimat3/realtime": "22.0.0",
-    "@ultimat3/render": "22.0.0",
-    "@ultimat3/schema": "22.0.0",
-    "@ultimat3/seo": "22.0.0",
-    "@ultimat3/storage": "22.0.0",
-    "@ultimat3/testing": "22.0.0",
-    "@ultimat3/time": "22.0.0",
+    "@ultimat3/action": "22.2.0",
+    "@ultimat3/admin": "22.2.0",
+    "@ultimat3/ai": "22.2.0",
+    "@ultimat3/auth": "22.2.0",
+    "@ultimat3/cache": "22.2.0",
+    "@ultimat3/core": "22.2.0",
+    "@ultimat3/db": "22.2.0",
+    "@ultimat3/entity": "22.2.0",
+    "@ultimat3/flags": "22.2.0",
+    "@ultimat3/http": "22.2.0",
+    "@ultimat3/i18n": "22.2.0",
+    "@ultimat3/jobs": "22.2.0",
+    "@ultimat3/mail": "22.2.0",
+    "@ultimat3/manifest": "22.2.0",
+    "@ultimat3/mcp": "22.2.0",
+    "@ultimat3/money": "22.2.0",
+    "@ultimat3/notify": "22.2.0",
+    "@ultimat3/policy": "22.2.0",
+    "@ultimat3/pwa": "22.2.0",
+    "@ultimat3/query": "22.2.0",
+    "@ultimat3/realtime": "22.2.0",
+    "@ultimat3/render": "22.2.0",
+    "@ultimat3/schema": "22.2.0",
+    "@ultimat3/seo": "22.2.0",
+    "@ultimat3/storage": "22.2.0",
+    "@ultimat3/testing": "22.2.0",
+    "@ultimat3/time": "22.2.0",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/dev-route-table.ts

@@ -18,7 +18,7 @@ import { pageSync } from './page-sync';
 import { loadPwaArtifacts } from './pwa-artifacts';
 import { assetRoutes } from './runtime-assets';
 import { appRoutes } from './runtime-render';
-import { storageRoutes } from './runtime-storage';
+import { servedStorage, storageRoutes } from './runtime-storage';
 import { styleBundle } from './style-bundle';
 import { styleRoutes } from './style-routes';
 import { serviceWorkerArtifacts } from './sw-artifacts';
@@ -72,6 +72,8 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
   // call `runRole` makes — `POST /mcp` answered 404 in every process the framework booted until
   // one of them asked. Warned once here when `expose` is true and nothing can be mounted.
   const mcpMount = await mountAppMcp(input.root);
+  // `serve-boot.ts`'s answer: the app's declared disks when it has any, read per request.
+  const served = servedStorage(input.storage);
   const routes: readonly Route[] = [
     ...devDashboardRoutes(input.dashboard),
     // The same API table the container serves: a read that answers here and 404s in production
@@ -83,10 +85,10 @@ export async function devRouteTable(input: DevRouteTableInput): Promise<DevRoute
     // never shadow `/icons` or `/media`.
     ...assetRoutes({
       root: input.root,
-      storage: input.storage,
+      storage: served,
       ...(pwa === undefined ? {} : { pwa }),
     }),
-    ...storageRoutes({ storage: input.storage }),
+    ...storageRoutes({ storage: served }),
     // The chunks the documents below name. Mounted before the app's routes for the reason
     // `/icons` and `/media` are: a page route must not be able to shadow an asset URL.
     ...islandRoutes(() => input.islands()),

package/src/mcp-ui.ts

@@ -95,6 +95,8 @@ export interface UiHostInput {
   readonly driver?: ((viewport: UiShotInput['viewport']) => Promise<ShotDriver>) | undefined;
   /** Injected by a test: the route table, in place of the registry. */
   readonly routes?: (() => readonly DeclaredRoute[]) | undefined;
+  /** Injected by a test: the settle wait, in place of `DEFAULT_SETTLE_MS` (a real sleep per call). */
+  readonly settleMs?: number | undefined;
 }
 
 export interface UiCapabilities {
@@ -163,7 +165,7 @@ export function uiCapabilities(input: UiHostInput): UiCapabilities {
         outDir,
         driver,
         boot,
-        settleMs: DEFAULT_SETTLE_MS,
+        settleMs: input.settleMs ?? DEFAULT_SETTLE_MS,
         timeoutMs: DEFAULT_PAGE_TIMEOUT_MS,
         fullPage: shot.fullPage,
         colorScheme: shot.colorScheme,
@@ -197,7 +199,7 @@ export function uiCapabilities(input: UiHostInput): UiCapabilities {
         root,
         island: island.island,
         ...(island.state === undefined ? {} : { state: island.state }),
-        settleMs: DEFAULT_SETTLE_MS,
+        settleMs: input.settleMs ?? DEFAULT_SETTLE_MS,
         timeoutMs: DEFAULT_PAGE_TIMEOUT_MS,
         ...(executablePath === undefined ? {} : { executablePath }),
         ...(cdpUrl === undefined ? {} : { cdpUrl }),

package/src/role-sync.ts

@@ -20,6 +20,7 @@ import { neighbouringPort, PORT_RANGE, portPairAfter } from './flag-number';
 import { portFree } from './port-probe';
 import type { StartRolesOptions } from './role-start';
 import { syncAuthenticator } from './sync-authenticator';
+import { syncOriginsFrom } from './sync-url';
 import { DEV_BINDING } from './web-binding';
 
 /**
@@ -201,6 +202,9 @@ export async function prepareSync(options: StartRolesOptions): Promise<PreparedS
     buildId: options.buildId,
     sockets,
     ...(authenticate === undefined ? {} : { authenticate }),
+    // The page's origin when it is served on another host than this node; the node's own host is
+    // admitted without it. Anything else is refused before `authenticate` (X_SOCKET_ORIGIN_REFUSED).
+    allowedOrigins: syncOriginsFrom(options.env),
     // Tier 1 is presence, and without a registry the node answers a topic subscribe with no member
     // list at all — the KV bucket the transport just created would hold nothing and every `sync`
     // container would run a presence-less protocol. It reads and writes `transport.shared`, so it

package/src/runtime-render.ts

@@ -19,8 +19,13 @@ import { posix } from 'node:path';
 import { clientScopeOf } from '@ultimat3/auth';
 import type { Ctx } from '@ultimat3/core';
 import { CLIENT_SCOPE_HEADER } from '@ultimat3/core';
-import type { RouteMeta as HttpRouteMeta, Route, RouteParams } from '@ultimat3/http';
-import { asCtx, html, stream } from '@ultimat3/http';
+import type {
+  RouteMeta as HttpRouteMeta,
+  RedirectIntent,
+  Route,
+  RouteParams,
+} from '@ultimat3/http';
+import { asCtx, html, NO_STORE, redirect, stream, takeRedirect } from '@ultimat3/http';
 import { currentLocale } from '@ultimat3/i18n';
 import type {
   ClientSyncHead,
@@ -289,14 +294,12 @@ async function documentFrom(
 async function resultFor(
   entry: RouteEntry,
   request: DevRouteData,
+  data: RouteData,
   options: DevRenderOptions,
   isr: IsrController,
   ctx: Ctx,
 ): Promise<RenderResult> {
   const url = new URL(request.url);
-  // ONCE per request, before the mode is chosen. Every branch below reads this same object, so a
-  // route's `load` runs exactly once however its mode splits head from body.
-  const data = await routeDataFor(entry.config, request);
   // The status the loader answered through `withStatus`, 200 when it said nothing. Read once,
   // here, and handed to every mode: this file mints the `Response`, render owns the seam.
   const status = routeStatusOf(data);
@@ -380,6 +383,18 @@ const withScope = (result: RenderResult, scope: string | undefined): RenderResul
     ? result
     : { ...result, headers: { ...result.headers, [CLIENT_SCOPE_HEADER]: scope } };
 
+/**
+ * A loader's redirect. No declared `cache` means `private, no-store`: the loader decided it for
+ * THIS request (it recorded an open, it checked a token), and the mode's default would offer that
+ * decision to a CDN, which would then answer every later request without running the loader. A
+ * declared one is the pipeline's to apply, off `meta.cache`, exactly as for any handler.
+ */
+function loadRedirect(entry: RouteEntry, to: RedirectIntent): Response {
+  const response = redirect(to.location, to.status);
+  if (entry.config.cache === undefined) response.headers.set('cache-control', 'private, no-store');
+  return response;
+}
+
 const responseOf = (result: RenderResult): Response =>
   typeof result.body === 'string'
     ? html(result.body, { status: result.status, headers: result.headers })
@@ -395,6 +410,12 @@ const metaOf = (entry: RouteEntry): HttpRouteMeta => ({
   render: entry.config.render,
   tags: [entry.surface],
   ...(entry.config.policy === undefined ? {} : { policy: entry.config.policy.permission }),
+  // Projected so the router screens its ages at mount (`assertRouteCache`) and the `cache-headers`
+  // stage applies it to a response that wrote none — a loader's redirect. The rendered document
+  // carries its own header, from `ssrHeaders`, which the stage reviews rather than replaces.
+  ...(entry.config.cache === undefined
+    ? {}
+    : { cache: entry.config.cache === 'no-store' ? NO_STORE : entry.config.cache }),
 });
 
 /**
@@ -424,7 +445,15 @@ export function appRoutes(options: DevRenderOptions): readonly Route[] {
     handler: async (request, ctx): Promise<Response> => {
       const entry = routeFor(registered.path) ?? registered;
       const data: DevRouteData = { url: request.url.href, params: ctx.params };
-      return responseOf(await resultFor(entry, data, options, isr, asCtx(ctx)));
+      // ONCE per request, before the mode is chosen: every branch of `resultFor` reads this same
+      // object, so a route's `load` runs exactly once however its mode splits head from body.
+      const loaded = await routeDataFor(entry.config, data);
+      // `setRedirect()` inside `load` — the same slot an action's handler fills — answers here,
+      // before a document is rendered for a page the visitor is leaving. `withStatus` refuses a
+      // 3xx because a rendered document has no `Location`; this is the path that has one.
+      const to = takeRedirect(ctx);
+      if (to !== undefined) return loadRedirect(entry, to);
+      return responseOf(await resultFor(entry, data, loaded, options, isr, asCtx(ctx)));
     },
   }));
 }

package/src/runtime-storage-upload.ts

@@ -0,0 +1,100 @@
+// Single responsibility: the upload half of `/_storage` — the `PUT` a `grantUpload` URL names.
+// `@ultimat3/storage` owns every accept decision (`acceptSignedUpload`); this file is where those
+// decisions meet a `Route`, beside the GET in `runtime-storage.ts`, so `x dev` and `runRole` mount
+// one write path through the one `storageRoutes()` both tables already call (#523).
+
+import { finiteCount, readWithinLimit } from '@ultimat3/core';
+import type { RequestContext, Route, UltimateRequest } from '@ultimat3/http';
+import { json, NO_STORE } from '@ultimat3/http';
+import type { Storage } from '@ultimat3/storage';
+import {
+  acceptSignedUpload,
+  DEFAULT_MAX_UPLOAD_BYTES,
+  DEFAULT_SIGNED_URL_BASE,
+  objectNotFound,
+  signedUploadConstraints,
+  tooLarge,
+  uploadPolicy,
+} from '@ultimat3/storage';
+
+/**
+ * The route's URL is the capability, so the one thing read off the request before it is verified
+ * is the URL itself — path and query exactly as the grant signed them.
+ */
+const signedUrlOf = (request: UltimateRequest): string =>
+  `${request.url.pathname}${request.url.search}`;
+
+/**
+ * The GRANT is the policy. `grantUpload` refused a type and a size the app's `uploadPolicy` did not
+ * allow before it signed, and the signature carries both — so the accept validates against what
+ * was signed, never against `uploadPolicy()`'s image-only default, which would refuse every PDF an
+ * app granted on purpose. The magic-byte sniff still runs: a signature bounds the declared type,
+ * the bytes still have to be it.
+ */
+async function acceptUpload(
+  storage: Storage,
+  request: UltimateRequest,
+  ctx: RequestContext,
+): Promise<Response> {
+  const diskName = request.params['disk'] ?? '';
+  const key = request.params['key'] ?? '';
+  // The GET's answer for a disk this app does not have, for the GET's reason: a refusal that lists
+  // the configured disks tells a caller which names exist.
+  if (!storage.diskNames.includes(diskName)) throw objectNotFound(diskName, key);
+  const disk = storage.disk(diskName);
+  const url = signedUrlOf(request);
+  // The actor's org, never one off the request: `acceptSignedUpload` holds the verified key to it.
+  const orgId = ctx.actor.orgId ?? '';
+
+  // Verified BEFORE the body is read, so the signed ceiling caps the read — not `bodyLimitBytes`,
+  // which is an RPC body's limit and would refuse every upload over a megabyte the app granted,
+  // and never an unverified `?max=` a forger could raise to make this process hold gigabytes.
+  const constraints = await signedUploadConstraints({ url, disk, orgId });
+  // Screened as every defaulted count is: a signed ceiling is verified, but `NaN` would still read
+  // as "no cap" to the counting reader below.
+  const ceiling = finiteCount(
+    'storageUploadRoute',
+    'maxBytes',
+    constraints.maxBytes === undefined ? DEFAULT_MAX_UPLOAD_BYTES : constraints.maxBytes,
+    1,
+  );
+  const read = await readWithinLimit(request.raw.body, ceiling);
+  if ('over' in read) throw tooLarge(constraints.key, read.over, ceiling);
+
+  const stored = await acceptSignedUpload({
+    url,
+    disk,
+    orgId,
+    bytes: read.bytes,
+    declaredContentType: request.header('content-type') ?? undefined,
+    policy: uploadPolicy({
+      maxBytes: ceiling,
+      ...(constraints.contentType === undefined
+        ? {}
+        : { allowedContentTypes: [constraints.contentType] }),
+    }),
+  });
+  return json({ key: stored.key }, { status: 201 });
+}
+
+/**
+ * `auth: 'required'` and `enforcedBy: 'handler'`, the GET's posture and for its reasons. No
+ * permission: the grant is the authorization, decided by the action that minted it under its own
+ * policy, and this route re-proves the three things a leaked URL must not buy — the signature,
+ * the expiry, and the actor's tenant. `no-store`: a 201 for one actor's write is nothing to cache.
+ */
+export function storageUploadRoute(storage: Storage): Route {
+  return {
+    method: 'PUT',
+    path: `${DEFAULT_SIGNED_URL_BASE}/:disk/*key`,
+    meta: {
+      name: 'storage.upload',
+      auth: 'required',
+      enforcedBy: 'handler',
+      cache: NO_STORE,
+      tags: ['storage'],
+    },
+    handler: (request: UltimateRequest, ctx: RequestContext): Promise<Response> =>
+      acceptUpload(storage, request, ctx),
+  };
+}

package/src/runtime-storage.ts

@@ -17,11 +17,13 @@ import type { Storage, StorageRead } from '@ultimat3/storage';
 import {
   assertSafeKey,
   DEFAULT_SIGNED_URL_BASE,
+  definedStorage,
   isTenantScoped,
   isWithinOrg,
   objectNotFound,
   orgMismatch,
 } from '@ultimat3/storage';
+import { storageUploadRoute } from './runtime-storage-upload';
 
 /**
  * The one capability that gates reading a stored object, on every disk. A permission and not a
@@ -211,6 +213,30 @@ export function storageResponse(request: UltimateRequest, read: StorageRead): Re
   return new Response(new Uint8Array(slice), { status: 206, headers });
 }
 
+/**
+ * The `Storage` the framework's own routes serve: the process's ONE registry when there is one —
+ * the last `defineStorage()`, which is the app's whenever an app module declares its disks — and
+ * the host's env-selected disk only when nothing did. Resolved per call, never captured at mount:
+ * the boot builds its disk before the app's modules load, and `x dev` re-imports them on a save.
+ *
+ * Why not the host's disk alone (#524): an app that declared `defineStorage({ disks: { uploads,
+ * evidence } })` wrote through `disk('evidence')` while `/_storage` and `/media` read the host's
+ * `local`/`object`, so every URL the app's own disks signed answered 404. The app's code and the
+ * framework's routes must be reading one registry, and `defineStorage` says there is only one.
+ */
+export function servedStorage(host: Storage): Storage {
+  const current = (): Storage => definedStorage() ?? host;
+  return {
+    get defaultDisk(): string {
+      return current().defaultDisk;
+    },
+    get diskNames(): readonly string[] {
+      return current().diskNames;
+    },
+    disk: (name?: string) => current().disk(name),
+  };
+}
+
 export interface StorageRoutesOptions {
   /** The configured disks. The driver seam only — this route never assumes a filesystem. */
   readonly storage: Storage;
@@ -249,5 +275,8 @@ export function storageRoutes(options: StorageRoutesOptions): readonly Route[] {
         return storageResponse(request, await readStorageObject(options.storage, input, ctx.actor));
       },
     },
+    // The upload half: the `PUT` every `grantUpload` URL names (#523). One call mounts both, so
+    // no route table can serve the reads of a disk it cannot write to.
+    storageUploadRoute(options.storage),
   ];
 }

package/src/serve-boot.ts

@@ -24,7 +24,7 @@ import { assetRoutes } from './runtime-assets';
 import { appRoutes } from './runtime-render';
 import { replicaOverrides } from './runtime-replica';
 import type { RunningServices } from './runtime-services';
-import { storageRoutes } from './runtime-storage';
+import { servedStorage, storageRoutes } from './runtime-storage';
 import { loadDrainConfig } from './serve-drain';
 import { configureReporting, containerBinding, metricsPortFor, portFromEnv } from './serve-env';
 import type { ServedApp, ServeOptions } from './serve-types';
@@ -156,17 +156,19 @@ async function webSurface(
         });
   // The app's own MCP endpoint, through the same call `x dev` makes — see `app-mcp.ts`.
   const mcpMount = await mountAppMcp(options.root);
+  // The app's own disks when it declared any (`defineStorage` in an app module), else this boot's.
+  const served = servedStorage(runtime.storage);
   const routes: readonly Route[] = [
     ...apiRoutes(),
     ...mcpMount.routes,
     ...(serviceWorker === undefined ? [] : serviceWorkerRoutes(serviceWorker)),
     ...assetRoutes({
       root: options.root,
-      storage: runtime.storage,
+      storage: served,
       ...(options.runtime?.images === undefined ? {} : { images: options.runtime.images }),
       ...(pwa === undefined ? {} : { pwa }),
     }),
-    ...storageRoutes({ storage: runtime.storage }),
+    ...storageRoutes({ storage: served }),
     ...islandRoutes(() => islands),
     // The surface stylesheets the documents link. Built from the registry the `loadApp` above
     // filled, so this process serves exactly the CSS it renders against.

package/src/sync-url.ts

@@ -1,5 +1,6 @@
 // Where a page's one socket dials — the framework's answer, so no app owns a `sync-url.ts`. Read
-// once at boot from the deployment's env and handed to every document as `ultimate-sync`.
+// once at boot from the deployment's env and handed to every document as `ultimate-sync` — and
+// the page origin the node admits, which is the same question asked from the other end.
 
 import { ConfigInvalidError } from '@ultimat3/core';
 
@@ -29,3 +30,22 @@ export function syncUrlFrom(env: Readonly<Record<string, string | undefined>>):
   }
   return declared;
 }
+
+/**
+ * The page origins a sync node admits besides its own host name: `APP_URL`'s, when set. Only a
+ * deployment that serves the page on another host than the node needs it; an unparsable value is
+ * refused rather than read as "no page origin", which would refuse every socket in silence.
+ */
+export function syncOriginsFrom(env: Readonly<Record<string, string | undefined>>): string[] {
+  const declared = env['APP_URL']?.trim() ?? '';
+  if (declared === '') return [];
+  const parsed = URL.parse(declared);
+  if (parsed === null || (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')) {
+    throw new ConfigInvalidError({
+      cause: 'APP_URL is set but is not an http:// or https:// URL, so no page origin can match it',
+      fix: 'export APP_URL="https://www.example.com"   # the origin your pages are served on',
+      meta: { key: 'APP_URL' },
+    });
+  }
+  return [parsed.origin];
+}

package/src/templates/scaffold-container-compose.ts

@@ -138,7 +138,7 @@ services:
     # (X_REALTIME_TOPOLOGY). To turn live queries and channels on: declare realtime: { enabled:
     # true, transport: 'nats', urlEnv: 'NATS_URL' } in app.config.ts, add a NATS service and set the
     # SAME NATS_URL for web, sync and a replicator service (ROLE=replicator, exactly one), start
-    # Postgres with wal_level=logical and a publication for the entity tables, then set replicas: 1.
+    # Postgres with wal_level=logical and a REPLICATION role on a cluster dedicated to this app (the replicator creates its publication at boot), then set replicas: 1.
     # A NATS_URL under transport 'memory' refuses the boot (X_CONFIG_INVALID), and so does 'nats'
     # without one.
     deploy: { replicas: 0 } # when on: scales on concurrent websockets — pinned to 1 by the port

package/src/templates/scaffold-env.ts

@@ -29,6 +29,12 @@ export const SCAFFOLD_ENV_SCHEMA = {
     role: 'sync',
     description: 'Realtime fan-out cluster. Only the sync role is asked for it.',
   },
+  APP_URL: {
+    type: 'url',
+    required: false,
+    role: ['web', 'sync'],
+    description: 'Public origin of the pages. Sync admits sockets from it.',
+  },
   SYNC_URL: {
     type: 'string',
     required: false,

package/src/templates/scaffold-helm.ts

@@ -95,7 +95,7 @@ roles:
     # urlEnv: 'NATS_URL' } in app.config.ts (a NATS_URL under transport 'memory' is refused, and
     # 'nats' without it is too); run NATS and set the SAME NATS_URL for web, sync and the
     # replicator; enable exactly one replicator (below) against a Postgres started with
-    # wal_level=logical and a publication for the entity tables; then set this to true.
+    # wal_level=logical (the replicator creates its publication at boot) and a role with REPLICATION on a cluster dedicated to this app; then set this to true.
     enabled: false
     replicas: 2
     port: 3001