@vxil/feature-configs 0.7.0 → 0.8.0

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');
+}

package/src/readmodels.ts

@@ -101,7 +101,7 @@ function filterErrors(where: string, raw: unknown): string[] {
 /**
  * Structural validation of a declared read-model `spec` — shared by the
  * config-write gate here and re-exported for anyone needing the pure check.
- * `kind` selects the §3.1 (aggregate) or §4.1 (rank) grammar.
+ * `kind` selects the aggregate or the rank grammar (guide ch. 4).
  */
 export function validateReadModelSpecShape(
   where: string,