@ultimat3/cli 22.1.0 → 22.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/cli",
-  "version": "22.1.0",
+  "version": "22.2.1",
   "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.1.0",
-    "@ultimat3/admin": "22.1.0",
-    "@ultimat3/ai": "22.1.0",
-    "@ultimat3/auth": "22.1.0",
-    "@ultimat3/cache": "22.1.0",
-    "@ultimat3/core": "22.1.0",
-    "@ultimat3/db": "22.1.0",
-    "@ultimat3/entity": "22.1.0",
-    "@ultimat3/flags": "22.1.0",
-    "@ultimat3/http": "22.1.0",
-    "@ultimat3/i18n": "22.1.0",
-    "@ultimat3/jobs": "22.1.0",
-    "@ultimat3/mail": "22.1.0",
-    "@ultimat3/manifest": "22.1.0",
-    "@ultimat3/mcp": "22.1.0",
-    "@ultimat3/money": "22.1.0",
-    "@ultimat3/notify": "22.1.0",
-    "@ultimat3/policy": "22.1.0",
-    "@ultimat3/pwa": "22.1.0",
-    "@ultimat3/query": "22.1.0",
-    "@ultimat3/realtime": "22.1.0",
-    "@ultimat3/render": "22.1.0",
-    "@ultimat3/schema": "22.1.0",
-    "@ultimat3/seo": "22.1.0",
-    "@ultimat3/storage": "22.1.0",
-    "@ultimat3/testing": "22.1.0",
-    "@ultimat3/time": "22.1.0",
+    "@ultimat3/action": "22.2.1",
+    "@ultimat3/admin": "22.2.1",
+    "@ultimat3/ai": "22.2.1",
+    "@ultimat3/auth": "22.2.1",
+    "@ultimat3/cache": "22.2.1",
+    "@ultimat3/core": "22.2.1",
+    "@ultimat3/db": "22.2.1",
+    "@ultimat3/entity": "22.2.1",
+    "@ultimat3/flags": "22.2.1",
+    "@ultimat3/http": "22.2.1",
+    "@ultimat3/i18n": "22.2.1",
+    "@ultimat3/jobs": "22.2.1",
+    "@ultimat3/mail": "22.2.1",
+    "@ultimat3/manifest": "22.2.1",
+    "@ultimat3/mcp": "22.2.1",
+    "@ultimat3/money": "22.2.1",
+    "@ultimat3/notify": "22.2.1",
+    "@ultimat3/policy": "22.2.1",
+    "@ultimat3/pwa": "22.2.1",
+    "@ultimat3/query": "22.2.1",
+    "@ultimat3/realtime": "22.2.1",
+    "@ultimat3/render": "22.2.1",
+    "@ultimat3/schema": "22.2.1",
+    "@ultimat3/seo": "22.2.1",
+    "@ultimat3/storage": "22.2.1",
+    "@ultimat3/testing": "22.2.1",
+    "@ultimat3/time": "22.2.1",
     "babel-preset-solid": "^1.9.15"
   }
 }

package/src/app-load.ts

@@ -19,8 +19,9 @@ import { isRouteConfig, pageComponentOf, registerRoute, routeEntries } from '@ul
 // every app module below is loaded by the dynamic `import()` in this file. Before the render
 // barrel split it came free with the line above; after it, the only other path to `/server` from
 // here is six hops through `error-contract` → `fix-command` → the command registry, which is an
-// accident one refactor away from compiling every app's `.tsx` to `React.createElement`.
-import '@ultimat3/render/server';
+// accident one refactor away from compiling every app's `.tsx` to `React.createElement`. The named
+// import is a value import, so the side effect holds without the bare line it replaced.
+import { setStylesheetRoot } from '@ultimat3/render/server';
 import { APP_CONFIG_FILE } from './app-root';
 import { collectDeclaredCodes } from './error-contract';
 import type { Finding } from './output';
@@ -108,6 +109,10 @@ export function resetAppLoad(): void {
 }
 
 export async function loadApp(root: string): Promise<LoadedApp> {
+  // Before any import: a stylesheet's surface is read below the app root, never off its absolute
+  // path — under the container's `WORKDIR /app` that path's first segment is `app/`, and every
+  // sheet, the site's included, classified as app CSS.
+  setStylesheetRoot(root);
   const files: string[] = [];
   const findings: Finding[] = [];
 

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/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.