@vxil/feature-configs 0.7.1 → 0.8.0

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export * from './hooks.js';
 export * from './readmodels.js';
 export * from './apiState.js';
 export * from './canonicalJson.js';
+export * from './publicAssets.js';
 export declare const RESERVED_CREDIT_TYPES: ReadonlySet<string>;
 /** A function binding's `retry.maxAttempts` ceiling, and the
  *  binding kinds that may carry `retry` — the platform-delivered event lanes
@@ -378,6 +379,17 @@ export declare const FilesConfigSchema: import("@sinclair/typebox").TObject<{
         asyncOverJobs: import("@sinclair/typebox").TBoolean;
         boundingBoxes: import("@sinclair/typebox").TBoolean;
     }>>;
+    publicAssets: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
+        enabled: import("@sinclair/typebox").TBoolean;
+        corsOrigins: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>;
+        variants: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TObject<{
+            w: import("@sinclair/typebox").TInteger;
+            h: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+            fit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"scale-down">, import("@sinclair/typebox").TLiteral<"contain">, import("@sinclair/typebox").TLiteral<"cover">, import("@sinclair/typebox").TLiteral<"crop">, import("@sinclair/typebox").TLiteral<"pad">]>>;
+            fmt: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"webp">, import("@sinclair/typebox").TLiteral<"avif">, import("@sinclair/typebox").TLiteral<"jpeg">, import("@sinclair/typebox").TLiteral<"png">]>;
+            q: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+        }>>>;
+    }>>;
 }>;
 export type FilesConfig = Static<typeof FilesConfigSchema>;
 export declare const DeclaredWebhookSubscriptionSchema: import("@sinclair/typebox").TObject<{

package/dist/index.js

@@ -8,6 +8,7 @@ import { Value } from '@sinclair/typebox/value';
 import { validateHooksConfig } from './hooks.js';
 import { validateCdcConfig, validateReadModelsConfig } from './readmodels.js';
 import { isFnTriggerSubscriptionUrl } from './apiState.js';
+import { PublicAssetsConfigSchema, VARIANT_PRESET_NAME_PATTERN } from './publicAssets.js';
 // Re-export the CMS lifecycle-hook engine so feature workers (cms-v1, runtime
 // eval) and the control plane (config-time validation) share one definition.
 export * from './hooks.js';
@@ -21,6 +22,10 @@ export * from './apiState.js';
 // Key-order-insensitive JSON: the one declared-vs-stored manifest compare
 // (control-plane shallowDiff, CLI diffManifest).
 export * from './canonicalJson.js';
+// Public asset delivery (files.publicAssets): the publishable content-type
+// allowlist, the URL/key shape and the variant presets — shared by files-v1
+// (publish) and files-cdn (serve), which never import each other.
+export * from './publicAssets.js';
 // TypeBox validates `format:` only for registered formats — register the ones
 // our schemas use (pragmatic RFC-lite email check; providers do the real one).
 if (!FormatRegistry.Has('email')) {
@@ -712,6 +717,11 @@ export const FilesConfigSchema = Type.Object({
         asyncOverJobs: Type.Boolean({ default: true }), // large/multi-page → jobs
         boundingBoxes: Type.Boolean({ default: false }),
     })),
+    // Public asset delivery (2026-10-03, guide ch. 6 files): publish
+    // an object to the cache-forever public host (POST /v1/files/{id}/publish).
+    // ONE optional bag: { enabled, corsOrigins, variants }. The published-bytes
+    // ceiling is a PLAN line (control-plane plans.ts), never a tenant knob.
+    publicAssets: Type.Optional(PublicAssetsConfigSchema),
 });
 // webhooks-out (wishlist feature): outbound event fan-out over the jobs delivery
 // engine. Subscriptions live in their own store (one writer per datum); config is just the capability gate + a cap.
@@ -1810,6 +1820,13 @@ export function validateDeclaredAiTemplates(templates) {
     });
     return errs;
 }
+function badVariantPresetNames(raw) {
+    const variants = raw?.publicAssets?.variants;
+    if (!variants || typeof variants !== 'object' || Array.isArray(variants))
+        return [];
+    const re = new RegExp(VARIANT_PRESET_NAME_PATTERN);
+    return Object.keys(variants).filter((k) => !re.test(k));
+}
 export function validateFeatureConfig(feature, raw) {
     const schema = FEATURE_SCHEMAS[feature];
     if (!schema) {
@@ -1818,6 +1835,18 @@ export function validateFeatureConfig(feature, raw) {
     if (countLeaves(schema) > CONFIG_FLAG_CAP) {
         return { ok: false, errors: [`schema for '${feature}' exceeds the ${CONFIG_FLAG_CAP}-flag cap`] };
     }
+    // files.publicAssets.variants is a pattern-keyed record: Value.Clean below
+    // would silently DROP a preset whose name is not URL-safe, and the tenant
+    // would wonder why `/v/My Thumb` 404s. Refuse it by name instead.
+    if (feature === 'files') {
+        const bad = badVariantPresetNames(raw);
+        if (bad.length > 0) {
+            return {
+                ok: false,
+                errors: bad.map((n) => `/publicAssets/variants/${n}: a preset name is lower-case letters, numbers, '-' or '_' (at most 32 characters, starting with a letter or number)`),
+            };
+        }
+    }
     // Apply defaults to a clone, then STRIP any property the schema does not
     // declare, then check. Value.Clean makes the validator TOTAL:
     // the schemas are open Type.Object()s, so without it Value.Check passes on —

package/dist/publicAssets.d.ts

@@ -0,0 +1,73 @@
+import { type Static } from '@sinclair/typebox';
+/** extension → the exact Content-Type served for it. */
+export declare const PUBLIC_ASSET_TYPES: Readonly<Record<string, string>>;
+/** The extension a stored content type publishes under, or null when the type
+ *  may not be published (html, svg, pdf, zip, octet-stream, …). */
+export declare function publicExtForContentType(contentType: string | null | undefined): string | null;
+/** Raster image extensions a variant preset may transform. */
+export declare const VARIANT_SOURCE_EXTS: ReadonlySet<string>;
+/** Video/audio types served `inline` (playable) by shared links and the public
+ *  host — media formats a browser plays in a player, never as a document. */
+export declare const INLINE_MEDIA_TYPES: ReadonlySet<string>;
+/** The public-asset URL path shape: `/<tenant_id>/<sha256>.<ext>` with an
+ *  optional `/v/<preset>` variant suffix. The tenant is bound from THIS path
+ *  (never a Host header). */
+export declare const PUBLIC_ASSET_PATH_RE: RegExp;
+/** The object key in the public bucket: `<tenant_id>/<sha256>.<ext>` —
+ *  tenant-prefixed (no cross-tenant dedupe, so no hash-existence oracle across
+ *  tenants) and content-addressed (immutable: a URL never changes meaning). */
+export declare function publicAssetKey(tenantId: string, sha256: string, ext: string): string;
+/** Most variant presets one tenant may declare (the schema bound; the plan
+ *  ceiling in control-plane plans.ts may be lower). */
+export declare const MAX_VARIANT_PRESETS = 8;
+/** Most CORS origins one tenant may declare. */
+export declare const MAX_CORS_ORIGINS = 20;
+/** Most object ids one bulk publish accepts (the batch download-urls bound). */
+export declare const MAX_BULK_PUBLISH = 100;
+/** Largest object that may be published (bytes): 512 MiB — the largest
+ *  object the public host's edge cache holds, so every published object
+ *  (and every Range of it) is served from the cache after its first read.
+ *  Bigger media belongs on a streaming/transcoding vendor, not a
+ *  cache-forever host. */
+export declare const MAX_PUBLISH_OBJECT_BYTES: number;
+/** Most bytes ONE bulk publish call may stream (hashing an object without a
+ *  recorded checksum reads it once, copying reads it again). Ids past the
+ *  budget land in `errors[]` as `batch_budget_exceeded` — publish them in a
+ *  further call. */
+export declare const MAX_BULK_PUBLISH_BYTES: number;
+/** Largest source image a variant preset transforms (bytes). */
+export declare const MAX_VARIANT_SOURCE_BYTES: number;
+/** A CORS origin: `*`, an https origin, or a localhost http origin (dev). No
+ *  path, no trailing slash, no wildcard sub-domains. */
+export declare const CORS_ORIGIN_PATTERN = "^(\\*|https://[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*(:[0-9]{1,5})?|http://(localhost|127\\.0\\.0\\.1)(:[0-9]{1,5})?)$";
+/** A preset name: lower-case, URL-safe, ≤ 32 chars (it is a path segment). */
+export declare const VARIANT_PRESET_NAME_PATTERN = "^[a-z0-9][a-z0-9_-]{0,31}$";
+export declare const VariantPresetSchema: import("@sinclair/typebox").TObject<{
+    w: import("@sinclair/typebox").TInteger;
+    h: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+    fit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"scale-down">, import("@sinclair/typebox").TLiteral<"contain">, import("@sinclair/typebox").TLiteral<"cover">, import("@sinclair/typebox").TLiteral<"crop">, import("@sinclair/typebox").TLiteral<"pad">]>>;
+    fmt: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"webp">, import("@sinclair/typebox").TLiteral<"avif">, import("@sinclair/typebox").TLiteral<"jpeg">, import("@sinclair/typebox").TLiteral<"png">]>;
+    q: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+}>;
+export type VariantPreset = Static<typeof VariantPresetSchema>;
+/** `files.publicAssets` — ONE optional bag (one leaf against the 15-leaf cap).
+ *  `enabled` is the tenant's own kill switch: false ⇒ publish refuses and the
+ *  public host answers 404 for every one of the tenant's assets. */
+export declare const PublicAssetsConfigSchema: import("@sinclair/typebox").TObject<{
+    enabled: import("@sinclair/typebox").TBoolean;
+    corsOrigins: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>;
+    variants: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TObject<{
+        w: import("@sinclair/typebox").TInteger;
+        h: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+        fit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"scale-down">, import("@sinclair/typebox").TLiteral<"contain">, import("@sinclair/typebox").TLiteral<"cover">, import("@sinclair/typebox").TLiteral<"crop">, import("@sinclair/typebox").TLiteral<"pad">]>>;
+        fmt: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"webp">, import("@sinclair/typebox").TLiteral<"avif">, import("@sinclair/typebox").TLiteral<"jpeg">, import("@sinclair/typebox").TLiteral<"png">]>;
+        q: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+    }>>>;
+}>;
+export type PublicAssetsConfig = Static<typeof PublicAssetsConfigSchema>;
+/** The MIME type a variant `fmt` outputs. */
+export declare function variantOutputType(fmt: VariantPreset['fmt']): 'image/webp' | 'image/avif' | 'image/jpeg' | 'image/png';
+/** A stable short fingerprint of a preset definition — part of the variant
+ *  cache key, so editing a preset never serves the old rendition. FNV-1a over
+ *  the canonical field order (no crypto needed: it only has to change). */
+export declare function presetFingerprint(p: VariantPreset): string;

package/dist/publicAssets.js

@@ -0,0 +1,130 @@
+// files PUBLIC ASSET DELIVERY (2026-10-03) — the one definition of
+// what may be published to the public asset host, shared by the publish path
+// (files-v1), the serving Worker (files-cdn), the config schema below and the
+// docs gates. A feature worker never imports another worker's code, so the
+// constants that BOTH sides must agree on live in this shared package.
+//
+// THE CONTENT-TYPE ALLOWLIST is the security boundary of a public, cookie-less,
+// cache-forever host: only types a browser never executes as a document.
+// `text/html` is absent by construction, and `image/svg+xml` is REFUSED (an SVG
+// is a document that can run script; serving it under a CSP sandbox was the
+// alternative, refusing is the smaller surface). The serving Worker derives the
+// served Content-Type from the URL's extension through THIS map — never from
+// stored metadata — and adds `X-Content-Type-Options: nosniff`, so bytes that
+// lie about their type are still never rendered as HTML.
+import { Type } from '@sinclair/typebox';
+/** extension → the exact Content-Type served for it. */
+export const PUBLIC_ASSET_TYPES = {
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    webp: 'image/webp',
+    avif: 'image/avif',
+    gif: 'image/gif',
+    mp4: 'video/mp4',
+    webm: 'video/webm',
+    mp3: 'audio/mpeg',
+    m4a: 'audio/mp4',
+    ogg: 'audio/ogg',
+    woff2: 'font/woff2',
+    woff: 'font/woff',
+    json: 'application/json',
+};
+/** Stored content types (lower-cased, parameters stripped) accepted at publish
+ *  → the extension they are published under. The canonical type of each
+ *  extension plus a few common aliases uploaders send. */
+const TYPE_TO_EXT = {
+    ...Object.fromEntries(Object.entries(PUBLIC_ASSET_TYPES).map(([ext, ct]) => [ct, ext])),
+    'image/jpg': 'jpg',
+    'image/pjpeg': 'jpg',
+    'audio/mp3': 'mp3',
+    'audio/x-m4a': 'm4a',
+    'audio/m4a': 'm4a',
+    'application/font-woff': 'woff',
+    'application/font-woff2': 'woff2',
+};
+/** The extension a stored content type publishes under, or null when the type
+ *  may not be published (html, svg, pdf, zip, octet-stream, …). */
+export function publicExtForContentType(contentType) {
+    if (!contentType)
+        return null;
+    const base = contentType.split(';')[0].trim().toLowerCase();
+    return TYPE_TO_EXT[base] ?? null;
+}
+/** Raster image extensions a variant preset may transform. */
+export const VARIANT_SOURCE_EXTS = new Set(['png', 'jpg', 'webp', 'avif', 'gif']);
+/** Video/audio types served `inline` (playable) by shared links and the public
+ *  host — media formats a browser plays in a player, never as a document. */
+export const INLINE_MEDIA_TYPES = new Set([
+    'video/mp4', 'video/webm', 'audio/mpeg', 'audio/mp4', 'audio/ogg',
+]);
+/** The public-asset URL path shape: `/<tenant_id>/<sha256>.<ext>` with an
+ *  optional `/v/<preset>` variant suffix. The tenant is bound from THIS path
+ *  (never a Host header). */
+export const PUBLIC_ASSET_PATH_RE = /^\/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\/([0-9a-f]{64})\.([a-z0-9]{2,5})(?:\/v\/([a-z0-9][a-z0-9_-]{0,31}))?$/;
+/** The object key in the public bucket: `<tenant_id>/<sha256>.<ext>` —
+ *  tenant-prefixed (no cross-tenant dedupe, so no hash-existence oracle across
+ *  tenants) and content-addressed (immutable: a URL never changes meaning). */
+export function publicAssetKey(tenantId, sha256, ext) {
+    return `${tenantId}/${sha256}.${ext}`;
+}
+/** Most variant presets one tenant may declare (the schema bound; the plan
+ *  ceiling in control-plane plans.ts may be lower). */
+export const MAX_VARIANT_PRESETS = 8;
+/** Most CORS origins one tenant may declare. */
+export const MAX_CORS_ORIGINS = 20;
+/** Most object ids one bulk publish accepts (the batch download-urls bound). */
+export const MAX_BULK_PUBLISH = 100;
+/** Largest object that may be published (bytes): 512 MiB — the largest
+ *  object the public host's edge cache holds, so every published object
+ *  (and every Range of it) is served from the cache after its first read.
+ *  Bigger media belongs on a streaming/transcoding vendor, not a
+ *  cache-forever host. */
+export const MAX_PUBLISH_OBJECT_BYTES = 512 * 1024 * 1024;
+/** Most bytes ONE bulk publish call may stream (hashing an object without a
+ *  recorded checksum reads it once, copying reads it again). Ids past the
+ *  budget land in `errors[]` as `batch_budget_exceeded` — publish them in a
+ *  further call. */
+export const MAX_BULK_PUBLISH_BYTES = 2 * 1024 * 1024 * 1024;
+/** Largest source image a variant preset transforms (bytes). */
+export const MAX_VARIANT_SOURCE_BYTES = 25 * 1024 * 1024;
+/** A CORS origin: `*`, an https origin, or a localhost http origin (dev). No
+ *  path, no trailing slash, no wildcard sub-domains. */
+export const CORS_ORIGIN_PATTERN = '^(\\*|https://[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*(:[0-9]{1,5})?|http://(localhost|127\\.0\\.0\\.1)(:[0-9]{1,5})?)$';
+/** A preset name: lower-case, URL-safe, ≤ 32 chars (it is a path segment). */
+export const VARIANT_PRESET_NAME_PATTERN = '^[a-z0-9][a-z0-9_-]{0,31}$';
+export const VariantPresetSchema = Type.Object({
+    w: Type.Integer({ minimum: 1, maximum: 4096 }),
+    h: Type.Optional(Type.Integer({ minimum: 1, maximum: 4096 })),
+    fit: Type.Optional(Type.Union([
+        Type.Literal('scale-down'), Type.Literal('contain'), Type.Literal('cover'),
+        Type.Literal('crop'), Type.Literal('pad'),
+    ])),
+    fmt: Type.Union([Type.Literal('webp'), Type.Literal('avif'), Type.Literal('jpeg'), Type.Literal('png')]),
+    q: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })),
+});
+/** `files.publicAssets` — ONE optional bag (one leaf against the 15-leaf cap).
+ *  `enabled` is the tenant's own kill switch: false ⇒ publish refuses and the
+ *  public host answers 404 for every one of the tenant's assets. */
+export const PublicAssetsConfigSchema = Type.Object({
+    enabled: Type.Boolean({ default: false }),
+    corsOrigins: Type.Array(Type.String({ pattern: CORS_ORIGIN_PATTERN, maxLength: 253 }), {
+        default: [], maxItems: MAX_CORS_ORIGINS,
+    }),
+    variants: Type.Optional(Type.Record(Type.String({ pattern: VARIANT_PRESET_NAME_PATTERN }), VariantPresetSchema, { maxProperties: MAX_VARIANT_PRESETS })),
+});
+/** The MIME type a variant `fmt` outputs. */
+export function variantOutputType(fmt) {
+    return `image/${fmt}`;
+}
+/** A stable short fingerprint of a preset definition — part of the variant
+ *  cache key, so editing a preset never serves the old rendition. FNV-1a over
+ *  the canonical field order (no crypto needed: it only has to change). */
+export function presetFingerprint(p) {
+    const s = `${p.w}|${p.h ?? ''}|${p.fit ?? ''}|${p.fmt}|${p.q ?? ''}`;
+    let h = 0x811c9dc5;
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 0x01000193) >>> 0;
+    }
+    return h.toString(16).padStart(8, '0');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vxil/feature-configs",
-  "version": "0.7.1",
+  "version": "0.8.0",
   "description": "The per-feature configuration schemas and validators behind vxil.config.ts (published for @vxil/cli and @vxil/config).",
   "license": "MIT",
   "homepage": "https://vxil.com",

package/src/index.ts

@@ -8,6 +8,7 @@ import { Value } from '@sinclair/typebox/value';
 import { validateHooksConfig, type HookDef } from './hooks.js';
 import { validateCdcConfig, validateReadModelsConfig } from './readmodels.js';
 import { isFnTriggerSubscriptionUrl } from './apiState.js';
+import { PublicAssetsConfigSchema, VARIANT_PRESET_NAME_PATTERN } from './publicAssets.js';
 
 // Re-export the CMS lifecycle-hook engine so feature workers (cms-v1, runtime
 // eval) and the control plane (config-time validation) share one definition.
@@ -22,6 +23,10 @@ export * from './apiState.js';
 // Key-order-insensitive JSON: the one declared-vs-stored manifest compare
 // (control-plane shallowDiff, CLI diffManifest).
 export * from './canonicalJson.js';
+// Public asset delivery (files.publicAssets): the publishable content-type
+// allowlist, the URL/key shape and the variant presets — shared by files-v1
+// (publish) and files-cdn (serve), which never import each other.
+export * from './publicAssets.js';
 
 // TypeBox validates `format:` only for registered formats — register the ones
 // our schemas use (pragmatic RFC-lite email check; providers do the real one).
@@ -844,8 +849,13 @@ export const FilesConfigSchema = Type.Object({
     asyncOverJobs: Type.Boolean({ default: true }), // large/multi-page → jobs
     boundingBoxes: Type.Boolean({ default: false }),
   })),
+  // Public asset delivery (2026-10-03, guide ch. 6 files): publish
+  // an object to the cache-forever public host (POST /v1/files/{id}/publish).
+  // ONE optional bag: { enabled, corsOrigins, variants }. The published-bytes
+  // ceiling is a PLAN line (control-plane plans.ts), never a tenant knob.
+  publicAssets: Type.Optional(PublicAssetsConfigSchema),
 });
-// Leaves: 9 + ttl(1, optional bag) + extractText(1, optional bag) = 11. Cap = 15.
+// Leaves: 9 + ttl(1) + extractText(1) + publicAssets(1, optional bags) = 12. Cap = 15.
 // (was 14 — 2026-09-11 deleted the inert bucketRef leaf and the inert contentScan bag.)
 
 export type FilesConfig = Static<typeof FilesConfigSchema>;
@@ -2210,6 +2220,13 @@ export function validateDeclaredAiTemplates(templates: readonly DeclaredAiTempla
   return errs;
 }
 
+function badVariantPresetNames(raw: unknown): string[] {
+  const variants = (raw as { publicAssets?: { variants?: unknown } } | null)?.publicAssets?.variants;
+  if (!variants || typeof variants !== 'object' || Array.isArray(variants)) return [];
+  const re = new RegExp(VARIANT_PRESET_NAME_PATTERN);
+  return Object.keys(variants).filter((k) => !re.test(k));
+}
+
 export function validateFeatureConfig(feature: string, raw: unknown): ConfigValidation {
   const schema = FEATURE_SCHEMAS[feature];
   if (!schema) {
@@ -2218,6 +2235,18 @@ export function validateFeatureConfig(feature: string, raw: unknown): ConfigVali
   if (countLeaves(schema) > CONFIG_FLAG_CAP) {
     return { ok: false, errors: [`schema for '${feature}' exceeds the ${CONFIG_FLAG_CAP}-flag cap`] };
   }
+  // files.publicAssets.variants is a pattern-keyed record: Value.Clean below
+  // would silently DROP a preset whose name is not URL-safe, and the tenant
+  // would wonder why `/v/My Thumb` 404s. Refuse it by name instead.
+  if (feature === 'files') {
+    const bad = badVariantPresetNames(raw);
+    if (bad.length > 0) {
+      return {
+        ok: false,
+        errors: bad.map((n) => `/publicAssets/variants/${n}: a preset name is lower-case letters, numbers, '-' or '_' (at most 32 characters, starting with a letter or number)`),
+      };
+    }
+  }
   // Apply defaults to a clone, then STRIP any property the schema does not
   // declare, then check. Value.Clean makes the validator TOTAL:
   // the schemas are open Type.Object()s, so without it Value.Check passes on —

package/src/publicAssets.ts

@@ -0,0 +1,151 @@
+// files PUBLIC ASSET DELIVERY (2026-10-03) — the one definition of
+// what may be published to the public asset host, shared by the publish path
+// (files-v1), the serving Worker (files-cdn), the config schema below and the
+// docs gates. A feature worker never imports another worker's code, so the
+// constants that BOTH sides must agree on live in this shared package.
+//
+// THE CONTENT-TYPE ALLOWLIST is the security boundary of a public, cookie-less,
+// cache-forever host: only types a browser never executes as a document.
+// `text/html` is absent by construction, and `image/svg+xml` is REFUSED (an SVG
+// is a document that can run script; serving it under a CSP sandbox was the
+// alternative, refusing is the smaller surface). The serving Worker derives the
+// served Content-Type from the URL's extension through THIS map — never from
+// stored metadata — and adds `X-Content-Type-Options: nosniff`, so bytes that
+// lie about their type are still never rendered as HTML.
+import { Type, type Static } from '@sinclair/typebox';
+
+/** extension → the exact Content-Type served for it. */
+export const PUBLIC_ASSET_TYPES: Readonly<Record<string, string>> = {
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  webp: 'image/webp',
+  avif: 'image/avif',
+  gif: 'image/gif',
+  mp4: 'video/mp4',
+  webm: 'video/webm',
+  mp3: 'audio/mpeg',
+  m4a: 'audio/mp4',
+  ogg: 'audio/ogg',
+  woff2: 'font/woff2',
+  woff: 'font/woff',
+  json: 'application/json',
+};
+
+/** Stored content types (lower-cased, parameters stripped) accepted at publish
+ *  → the extension they are published under. The canonical type of each
+ *  extension plus a few common aliases uploaders send. */
+const TYPE_TO_EXT: Readonly<Record<string, string>> = {
+  ...Object.fromEntries(Object.entries(PUBLIC_ASSET_TYPES).map(([ext, ct]) => [ct, ext])),
+  'image/jpg': 'jpg',
+  'image/pjpeg': 'jpg',
+  'audio/mp3': 'mp3',
+  'audio/x-m4a': 'm4a',
+  'audio/m4a': 'm4a',
+  'application/font-woff': 'woff',
+  'application/font-woff2': 'woff2',
+};
+
+/** The extension a stored content type publishes under, or null when the type
+ *  may not be published (html, svg, pdf, zip, octet-stream, …). */
+export function publicExtForContentType(contentType: string | null | undefined): string | null {
+  if (!contentType) return null;
+  const base = contentType.split(';')[0]!.trim().toLowerCase();
+  return TYPE_TO_EXT[base] ?? null;
+}
+
+/** Raster image extensions a variant preset may transform. */
+export const VARIANT_SOURCE_EXTS: ReadonlySet<string> = new Set(['png', 'jpg', 'webp', 'avif', 'gif']);
+
+/** Video/audio types served `inline` (playable) by shared links and the public
+ *  host — media formats a browser plays in a player, never as a document. */
+export const INLINE_MEDIA_TYPES: ReadonlySet<string> = new Set([
+  'video/mp4', 'video/webm', 'audio/mpeg', 'audio/mp4', 'audio/ogg',
+]);
+
+/** The public-asset URL path shape: `/<tenant_id>/<sha256>.<ext>` with an
+ *  optional `/v/<preset>` variant suffix. The tenant is bound from THIS path
+ *  (never a Host header). */
+export const PUBLIC_ASSET_PATH_RE =
+  /^\/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\/([0-9a-f]{64})\.([a-z0-9]{2,5})(?:\/v\/([a-z0-9][a-z0-9_-]{0,31}))?$/;
+
+/** The object key in the public bucket: `<tenant_id>/<sha256>.<ext>` —
+ *  tenant-prefixed (no cross-tenant dedupe, so no hash-existence oracle across
+ *  tenants) and content-addressed (immutable: a URL never changes meaning). */
+export function publicAssetKey(tenantId: string, sha256: string, ext: string): string {
+  return `${tenantId}/${sha256}.${ext}`;
+}
+
+/** Most variant presets one tenant may declare (the schema bound; the plan
+ *  ceiling in control-plane plans.ts may be lower). */
+export const MAX_VARIANT_PRESETS = 8;
+/** Most CORS origins one tenant may declare. */
+export const MAX_CORS_ORIGINS = 20;
+/** Most object ids one bulk publish accepts (the batch download-urls bound). */
+export const MAX_BULK_PUBLISH = 100;
+/** Largest object that may be published (bytes): 512 MiB — the largest
+ *  object the public host's edge cache holds, so every published object
+ *  (and every Range of it) is served from the cache after its first read.
+ *  Bigger media belongs on a streaming/transcoding vendor, not a
+ *  cache-forever host. */
+export const MAX_PUBLISH_OBJECT_BYTES = 512 * 1024 * 1024;
+/** Most bytes ONE bulk publish call may stream (hashing an object without a
+ *  recorded checksum reads it once, copying reads it again). Ids past the
+ *  budget land in `errors[]` as `batch_budget_exceeded` — publish them in a
+ *  further call. */
+export const MAX_BULK_PUBLISH_BYTES = 2 * 1024 * 1024 * 1024;
+/** Largest source image a variant preset transforms (bytes). */
+export const MAX_VARIANT_SOURCE_BYTES = 25 * 1024 * 1024;
+
+/** A CORS origin: `*`, an https origin, or a localhost http origin (dev). No
+ *  path, no trailing slash, no wildcard sub-domains. */
+export const CORS_ORIGIN_PATTERN =
+  '^(\\*|https://[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*(:[0-9]{1,5})?|http://(localhost|127\\.0\\.0\\.1)(:[0-9]{1,5})?)$';
+
+/** A preset name: lower-case, URL-safe, ≤ 32 chars (it is a path segment). */
+export const VARIANT_PRESET_NAME_PATTERN = '^[a-z0-9][a-z0-9_-]{0,31}$';
+
+export const VariantPresetSchema = Type.Object({
+  w: Type.Integer({ minimum: 1, maximum: 4096 }),
+  h: Type.Optional(Type.Integer({ minimum: 1, maximum: 4096 })),
+  fit: Type.Optional(Type.Union([
+    Type.Literal('scale-down'), Type.Literal('contain'), Type.Literal('cover'),
+    Type.Literal('crop'), Type.Literal('pad'),
+  ])),
+  fmt: Type.Union([Type.Literal('webp'), Type.Literal('avif'), Type.Literal('jpeg'), Type.Literal('png')]),
+  q: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })),
+});
+export type VariantPreset = Static<typeof VariantPresetSchema>;
+
+/** `files.publicAssets` — ONE optional bag (one leaf against the 15-leaf cap).
+ *  `enabled` is the tenant's own kill switch: false ⇒ publish refuses and the
+ *  public host answers 404 for every one of the tenant's assets. */
+export const PublicAssetsConfigSchema = Type.Object({
+  enabled: Type.Boolean({ default: false }),
+  corsOrigins: Type.Array(Type.String({ pattern: CORS_ORIGIN_PATTERN, maxLength: 253 }), {
+    default: [], maxItems: MAX_CORS_ORIGINS,
+  }),
+  variants: Type.Optional(Type.Record(
+    Type.String({ pattern: VARIANT_PRESET_NAME_PATTERN }),
+    VariantPresetSchema,
+    { maxProperties: MAX_VARIANT_PRESETS },
+  )),
+});
+export type PublicAssetsConfig = Static<typeof PublicAssetsConfigSchema>;
+
+/** The MIME type a variant `fmt` outputs. */
+export function variantOutputType(fmt: VariantPreset['fmt']): 'image/webp' | 'image/avif' | 'image/jpeg' | 'image/png' {
+  return `image/${fmt}` as 'image/webp' | 'image/avif' | 'image/jpeg' | 'image/png';
+}
+
+/** A stable short fingerprint of a preset definition — part of the variant
+ *  cache key, so editing a preset never serves the old rendition. FNV-1a over
+ *  the canonical field order (no crypto needed: it only has to change). */
+export function presetFingerprint(p: VariantPreset): string {
+  const s = `${p.w}|${p.h ?? ''}|${p.fit ?? ''}|${p.fmt}|${p.q ?? ''}`;
+  let h = 0x811c9dc5;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 0x01000193) >>> 0;
+  }
+  return h.toString(16).padStart(8, '0');
+}