@vxil/feature-configs 0.7.0 → 0.8.0

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/dist/readmodels.d.ts

@@ -9,7 +9,7 @@ export declare const READ_MODEL_LIMITS: {
 /**
  * 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 declare function validateReadModelSpecShape(where: string, kind: 'aggregate' | 'rank', spec: unknown): string[];
 /** Shape of one declared read-model (mirrors the CmsConfigSchema Record). */

package/dist/readmodels.js

@@ -103,7 +103,7 @@ function filterErrors(where, raw) {
 /**
  * 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, kind, spec) {
     if (!isObj(spec))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vxil/feature-configs",
-  "version": "0.7.0",
+  "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/apiState.ts

@@ -1,12 +1,10 @@
-// DECLARED API STATE — the pure declared-vs-live planner (roadmap §4.11 P0-3,
-// 2026-09-23).
+// DECLARED API STATE — the pure declared-vs-live planner (2026-09-23).
 //
 // Three datums used to be API state OUTSIDE vxil.config — rows their own /v1
 // route created, that `vxil push` never converged and a rollback never
 // restored — so every tenant that wanted a reproducible second environment
-// wrote an `ensure-*.ts` script and a nightly assert (the cvskit evaluation,
-// §8 P1-7). They are now DECLARED in the feature's config block and CONVERGED
-// by `vxil push` and `POST /v1/apply`:
+// wrote an `ensure-*.ts` script and a nightly assert. They are now DECLARED in
+// the feature's config block and CONVERGED by `vxil push` and `POST /v1/apply`:
 //
 //   rate-limits.policies[]     — keyed by `name`      (POST/PUT/DELETE /v1/rate-limits/policies)
 //   webhooks.subscriptions[]   — keyed by `target_url` (POST/PATCH/DELETE /v1/webhooks/subscriptions)
@@ -307,12 +305,12 @@ export interface ApiStateResponseField extends ApiStateSummary {
 
 /** The note every executor reports for a DISABLED feature whose block still
  *  declares rows: the declaration is kept in the manifest and nothing is
- *  converged (a parked feature is not a propagation window — review finding 2). */
+ *  converged (a parked feature is not a propagation window). */
 export const API_STATE_DISABLED_NOTE = 'feature disabled — declaration kept, not converged';
 
 /** `GET /v1/rate-limits/policies` is a 100-row HARD cap with no cursor. A list
  *  AT the cap is not a complete live set, so planning creates against it would
- *  re-POST every declared name the cap hid (review finding 5). The server's
+ *  re-POST every declared name the cap hid. The server's
  *  converge and the CLI's read-only plan refuse with this message instead. */
 export function rlPolicyListCapError(liveCount: number): string | null {
   if (liveCount < RL_POLICY_LIST_CAP) return null;

package/src/hooks.ts

@@ -330,7 +330,7 @@ export function validateAst(root: Node): string[] {
 }
 
 // ── evaluator (bounded, deterministic interpreter) ──────────────────────────
-/** The VERIFIED caller/session context for read hooks (design §5.6). Read-only;
+/** The VERIFIED caller/session context for read hooks (guide ch. 7). Read-only;
  *  present only on the read path in end-user mode. In server mode / write path
  *  the whole object is null. */
 export interface HookCaller {
@@ -663,7 +663,7 @@ export function runReadHooks(
   collection: string,
   rows: ReadonlyArray<Record<string, unknown>>,
   now: string,
-  /** verified caller/session context (design §5.6) — read-only, exposed to
+  /** verified caller/session context (guide ch. 7) — read-only, exposed to
    *  expressions as `caller.endUserId` / `caller.principal`. Omitted ⇒ null
    *  (server-caller mode). */
   caller?: HookCaller | null,