@norskvideo/ctl-product-template-schema 0.1.15 → 0.1.17

package/index.d.ts

@@ -3,6 +3,7 @@ export declare const ProductTemplateTargetSchema: z.ZodEnum<{
     "docker-compose": "docker-compose";
 }>;
 export type ProductTemplateTarget = z.infer<typeof ProductTemplateTargetSchema>;
+export declare const RESERVED_INSTANCE_ROUTE_SEGMENTS: readonly ["studio", "media", "visualiser", "uvis", "status", "metrics"];
 export declare const PRODUCT_TEMPLATE_ADVANCED_NETWORK_MODES: readonly ["docker", "hybrid"];
 export declare const ProductTemplateAdvancedSchema: z.ZodObject<{
     networkMode: z.ZodOptional<z.ZodObject<{
@@ -123,7 +124,17 @@ export declare const ProductTemplateManifestSchema: z.ZodObject<{
     }, z.core.$strip>>;
     proxy: z.ZodOptional<z.ZodObject<{
         expose: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        routes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            segment: z.ZodString;
+            service: z.ZodString;
+            port: z.ZodOptional<z.ZodNumber>;
+            websocket: z.ZodOptional<z.ZodBoolean>;
+            auth: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>>;
     }, z.core.$strip>>;
+    allowWorkflowUploads: z.ZodOptional<z.ZodBoolean>;
+    isStudio: z.ZodOptional<z.ZodBoolean>;
+    supportsCustomAssets: z.ZodOptional<z.ZodBoolean>;
     requiresWorkingDirectory: z.ZodOptional<z.ZodBoolean>;
     sideload: z.ZodOptional<z.ZodObject<{
         gpuInference: z.ZodOptional<z.ZodBoolean>;
@@ -291,7 +302,17 @@ export declare const ProductTemplateMaterialsSchema: z.ZodObject<{
         }, z.core.$strip>>;
         proxy: z.ZodOptional<z.ZodObject<{
             expose: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            routes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                segment: z.ZodString;
+                service: z.ZodString;
+                port: z.ZodOptional<z.ZodNumber>;
+                websocket: z.ZodOptional<z.ZodBoolean>;
+                auth: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strip>>>;
         }, z.core.$strip>>;
+        allowWorkflowUploads: z.ZodOptional<z.ZodBoolean>;
+        isStudio: z.ZodOptional<z.ZodBoolean>;
+        supportsCustomAssets: z.ZodOptional<z.ZodBoolean>;
         requiresWorkingDirectory: z.ZodOptional<z.ZodBoolean>;
         sideload: z.ZodOptional<z.ZodObject<{
             gpuInference: z.ZodOptional<z.ZodBoolean>;

package/index.js

@@ -50,10 +50,48 @@ const ProductTemplateDebugSchema = z.object({
         .optional()
         .meta({ description: "Show the Debug menu's 'Open Visualiser' link. Default true." }),
 });
+// Path segments the runner owns under /instance/<id>/ and a product may never
+// claim. They are the six base routes instance-routes.ts always emits; a
+// declared route colliding with one would be shadowed by nginx's more-specific
+// match and silently never serve, so the schema rejects it instead.
+export const RESERVED_INSTANCE_ROUTE_SEGMENTS = ["studio", "media", "visualiser", "uvis", "status", "metrics"];
+// One additional HTTP service a product wants behind the runner's front door,
+// beside the runtime-screen catch-all. WHY THIS EXISTS: a product's second UI
+// otherwise needs a published host port, and a plain http host port is a secure
+// context on localhost only — browser APIs like WebCodecs fail from any other
+// machine. The catch-all is a single slot, so a product with two UIs used to
+// have to reverse-proxy one behind the other itself, websocket bridging
+// included.
+const ProductTemplateRouteSchema = z.object({
+    segment: z
+        .string()
+        .regex(/^[a-z0-9][a-z0-9-]*$/, "one lowercase path segment: letters, digits and dashes")
+        .refine((s) => !RESERVED_INSTANCE_ROUTE_SEGMENTS.includes(s), {
+        message: `segment is reserved by the runner (${RESERVED_INSTANCE_ROUTE_SEGMENTS.join(", ")})`,
+    })
+        .meta({
+        description: "Single path segment under the instance root. The runner serves it at /instance/<id>/<segment>/. Must not be one of the runner's reserved segments (studio, media, visualiser, uvis, status, metrics).",
+    }),
+    service: z.string().min(1).meta({
+        description: "Compose service that serves this route. Must be a service in the template's own compose.yml; the runner dials it by its compose container name.",
+    }),
+    port: z.number().int().positive().optional().meta({
+        description: "Container port to dial. Omit for the conventional 8000.",
+    }),
+    websocket: z.boolean().optional().meta({
+        description: "Emit the Upgrade/Connection proxy headers so this route can carry websockets. Omit for a plain HTTP route. HTTP is always served; this only adds the upgrade path, so a route carrying both needs just this flag.",
+    }),
+    auth: z.boolean().optional().meta({
+        description: "Whether the route sits behind the runner's oauth2 auth_request. Omit for the default `true`. Set false only for a surface that must be reachable unauthenticated, as the media route is.",
+    }),
+});
 const ProductTemplateProxySchema = z.object({
     expose: z.array(z.string()).default([]).meta({
         description: "Paths (or globs) the runner's nginx routes through to this instance. Anything not in the list returns 404 from the proxy. Glob-shaped strings (`/static/*`) are accepted as hints — current implementation treats the whole set as a signal to mount a catch-all on the instance root; per-path filtering can come later.",
     }),
+    routes: z.array(ProductTemplateRouteSchema).optional().meta({
+        description: "Extra named services to route under the instance root, beside the runtime-screen catch-all. Additive and optional: a template that omits it routes exactly as before, so an older runner ignoring the field still launches the product.",
+    }),
 });
 // product-template-schema cannot import @norsk-ctl/shared (dependency direction), so
 // this is a literal copy of the runner's network-mode enum — and the runner
@@ -218,6 +256,19 @@ export const ProductTemplateManifestSchema = z
         description: "Per-instance Debug menu toggles. Each of `studio`/`visualiser` defaults to shown; set false to hide a redundant link (e.g. Studio hides its own 'Open Studio').",
     }),
     proxy: ProductTemplateProxySchema.optional(),
+    allowWorkflowUploads: z.boolean().optional().meta({
+        description: "Whether the operator may upload workflow documents for this product. They land in the working directory's studio-save-files/, where Studio lists them for the operator to open — so this is for Norsk Studio itself (the editor), not for appliances built on it: an appliance (probe, playout) generates its one workflow from its config screen and has nothing to select. Absent = false. Assets are governed separately by `supportsCustomAssets`.",
+    }),
+    /** @deprecated Renamed to `allowWorkflowUploads`, which says what it
+     *  gates. Read-side only: existing stored product templates carry it, and
+     *  dropping it would silently un-set the flag on a real install. Nothing
+     *  writes it. */
+    isStudio: z.boolean().optional().meta({
+        description: "DEPRECATED — renamed to `allowWorkflowUploads`. Accepted on read so product templates built before the rename keep working; nothing writes it.",
+    }),
+    supportsCustomAssets: z.boolean().optional().meta({
+        description: "Whether the operator may attach their own files (media, overlays, rundowns) to the working directory. Absent = true: every product gets a working directory, so the asset surface is universal and a product opts OUT rather than in. Assets land at operator-named workdir-relative paths and are also surfaced as NORSK_WORKDIR_ASSETS.",
+    }),
     requiresWorkingDirectory: z.boolean().optional().meta({
         description: "When true, the operator must choose a working directory at launch (a dev product template they own and keep), rather than getting the auto-assigned per-instance default. The runner's launch UI makes the working-directory field mandatory.",
     }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-product-template-schema",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "type": "module",
   "exports": {
     ".": {
@@ -18,6 +18,14 @@
     "./read": {
       "types": "./read.d.ts",
       "default": "./read.js"
+    },
+    "./workdir-fetch": {
+      "types": "./workdir-fetch.d.ts",
+      "default": "./workdir-fetch.js"
+    },
+    "./workdir-path": {
+      "types": "./workdir-path.d.ts",
+      "default": "./workdir-path.js"
     }
   },
   "main": "./index.js",

package/workdir-fetch.d.ts

@@ -0,0 +1,30 @@
+import { z } from "zod";
+/** Reserved parameter carrying the JSON-encoded fetch list. Infra-injected —
+ *  `invalidParameterNames` rejects operator entries in the NORSK_ namespace. */
+export declare const WORKDIR_FETCH_PARAM = "NORSK_WORKDIR_FETCH";
+export declare const WorkdirFetchEntrySchema: z.ZodObject<{
+    path: z.ZodString;
+    url: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    sha256: z.ZodOptional<z.ZodString>;
+    optional: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type WorkdirFetchEntry = z.infer<typeof WorkdirFetchEntrySchema>;
+export declare const WorkdirFetchListSchema: z.ZodArray<z.ZodObject<{
+    path: z.ZodString;
+    url: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    sha256: z.ZodOptional<z.ZodString>;
+    optional: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>>;
+export type WorkdirFetchList = z.infer<typeof WorkdirFetchListSchema>;
+/** Parse the reserved parameter's value. Returns [] for an absent/blank
+ *  value; a malformed one is an error the caller reports rather than a
+ *  silent empty list — a typo'd list must not look like "no assets". */
+export declare function parseWorkdirFetchParam(raw: string | undefined): WorkdirFetchList;
+export declare function encodeWorkdirFetchParam(list: WorkdirFetchList): string;
+export { assertSafeWorkdirPath, checkWorkdirPath, type WorkdirPathProblem, } from "./workdir-path.js";
+/** Stack the tiers — product template < production template < launch — the
+ *  same way the parameter tiers stack. Later layers win by `path`, and the
+ *  winner keeps its position so the resolved order stays readable in the UI. */
+export declare function mergeWorkdirFetchLayers(...layers: (WorkdirFetchList | undefined)[]): WorkdirFetchList;

package/workdir-fetch.js

@@ -0,0 +1,82 @@
+// Working-directory fetch list — the per-JOB channel for operator content
+// (assets, media, rundowns) that must land in an instance's working
+// directory on an ephemeral cloud node.
+//
+// Design: norsk-mgr-deploy/docs/design/working-directory-and-assets.md.
+// The list rides the job rather than the product template's tar, which is
+// what keeps the tar immutable: `ProductTemplateRef.sha256` names the on-disk
+// extract on the worker (`worker-<sha12>`) and a repeat import is skipped as
+// NAME_CONFLICT, so mutating a template's bytes would silently give two nodes
+// different content for the same production.
+//
+// Transport is the existing `product_template_parameters` map<string,string>
+// under the reserved name below — no proto change. mgr builds and interpolates
+// the list at launch (where ${production}/${role}/${index} are in scope) and
+// the worker resolves it after seeding, before compose up.
+//
+// This module is on the browser side of the barrel (mgr's composer imports the
+// schema to validate operator input), so: zod only, no node builtins.
+import { z } from "zod";
+import { checkWorkdirPath } from "./workdir-path.js";
+/** Reserved parameter carrying the JSON-encoded fetch list. Infra-injected —
+ *  `invalidParameterNames` rejects operator entries in the NORSK_ namespace. */
+export const WORKDIR_FETCH_PARAM = "NORSK_WORKDIR_FETCH";
+const SHA256 = z.string().regex(/^[0-9a-f]{64}$/, "lowercase-hex sha256");
+export const WorkdirFetchEntrySchema = z
+    .object({
+    path: z.string().meta({
+        description: "Destination relative to the instance working directory. Must survive assertSafeWorkdirPath: no absolute paths, no '..', and nothing landing under a runner-managed read-only mount point.",
+    }),
+    url: z.string().meta({
+        description: "Where the bytes come from: https:// (plain fetch), s3:// (resolved with the worker's instance role — never credentials in a template), or an absolute mgr URL for operator-uploaded bytes. May carry interpolation tokens (production, runtime, index, role); mgr resolves them before this reaches the wire.",
+    }),
+    name: z.string().optional().meta({
+        description: "Display label for the manager UI. Never a lookup key: assets simply land in the working directory (mounted at /data), and a product may create or rename them at runtime, so no name→path map is meaningful at template time.",
+    }),
+    sha256: SHA256.optional().meta({
+        description: "Content hash. When present the worker verifies the download and caches it content-addressed, so N nodes of a count-launch share one fetch.",
+    }),
+    optional: z.boolean().optional().meta({
+        description: "When true a missing object (404 / NoSuchKey) is not a launch failure — the entry is skipped. For interpolated per-event URLs that may legitimately not exist yet.",
+    }),
+})
+    .meta({ id: "WorkdirFetchEntry", outputId: "WorkdirFetchEntry" });
+export const WorkdirFetchListSchema = z.array(WorkdirFetchEntrySchema);
+/** Parse the reserved parameter's value. Returns [] for an absent/blank
+ *  value; a malformed one is an error the caller reports rather than a
+ *  silent empty list — a typo'd list must not look like "no assets". */
+export function parseWorkdirFetchParam(raw) {
+    if (raw === undefined || raw.trim() === "")
+        return [];
+    let json;
+    try {
+        json = JSON.parse(raw);
+    }
+    catch (e) {
+        throw new Error(`${WORKDIR_FETCH_PARAM} is not valid JSON: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    const parsed = WorkdirFetchListSchema.safeParse(json);
+    if (!parsed.success)
+        throw new Error(`${WORKDIR_FETCH_PARAM} is not a valid fetch list: ${parsed.error.message}`);
+    return parsed.data;
+}
+export function encodeWorkdirFetchParam(list) {
+    return JSON.stringify(list);
+}
+// Destination safety lives in ./workdir-path.ts — zod-free, so browsers can
+// import the same rules the server enforces. Re-exported here because callers
+// reach for the fetch-list contract as one module.
+export { assertSafeWorkdirPath, checkWorkdirPath, } from "./workdir-path.js";
+/** Stack the tiers — product template < production template < launch — the
+ *  same way the parameter tiers stack. Later layers win by `path`, and the
+ *  winner keeps its position so the resolved order stays readable in the UI. */
+export function mergeWorkdirFetchLayers(...layers) {
+    const byPath = new Map();
+    for (const layer of layers) {
+        for (const entry of layer ?? []) {
+            const checked = checkWorkdirPath(entry.path);
+            byPath.set(checked.ok ? checked.path : entry.path, entry);
+        }
+    }
+    return [...byPath.values()];
+}

package/workdir-path.d.ts

@@ -0,0 +1,17 @@
+export type WorkdirPathProblem = {
+    kind: "escape" | "shadowed";
+    message: string;
+};
+/** The normalised workdir-relative path, or why it is not usable. Pure string
+ *  logic — no node:path — because this runs in the composer as well as on the
+ *  worker, and both must agree. */
+export declare function checkWorkdirPath(raw: string): {
+    ok: true;
+    path: string;
+} | {
+    ok: false;
+    problem: WorkdirPathProblem;
+};
+/** checkWorkdirPath, throwing. For the worker, where a bad path is a launch
+ *  failure rather than a form validation message. */
+export declare function assertSafeWorkdirPath(raw: string): string;

package/workdir-path.js

@@ -0,0 +1,67 @@
+// Destination safety for working-directory assets — where a file may and may
+// not land inside an instance's working directory.
+//
+// Deliberately ZOD-FREE and dependency-free so browsers can import it: the
+// manager's composer, the product-template forms and (soon) norsk-ctl's UI all
+// validate destinations as the operator types, and none of them should pull a
+// schema library into their bundle to do it. The server validates the same list
+// with the zod schema in ./workdir-fetch.ts, which re-exports everything here —
+// so form and server can never disagree about what a legal destination is.
+// Two separate hazards, deliberately not conflated:
+//   escape    — `../../etc/x` writes outside the workdir. A hole.
+//   shadowing — a file written UNDER one of the runner's read-only bind
+//               mounts is on disk and invisible to the container. Not a
+//               security problem, but a miserable one to debug, so it is
+//               refused at upload time rather than discovered at runtime.
+/** Runner-managed read-only mount points inside the working directory
+ *  (override-generator.ts). `workflow.yml` is a file mount; the other two are
+ *  directory mounts, so anything beneath them is shadowed too. */
+const READONLY_MOUNTS = {
+    file: ["studio-save-files/workflow.yml"],
+    dir: [".norsk"],
+    /** `studio-save-files/<anything>/dashboards` — the per-workflow dashboard mount. */
+    pattern: [/^studio-save-files\/[^/]+\/dashboards(\/|$)/],
+};
+/** The normalised workdir-relative path, or why it is not usable. Pure string
+ *  logic — no node:path — because this runs in the composer as well as on the
+ *  worker, and both must agree. */
+export function checkWorkdirPath(raw) {
+    const escaped = (message) => ({ ok: false, problem: { kind: "escape", message } });
+    if (raw.includes("\\"))
+        return escaped(`'${raw}' must use '/' separators`);
+    if (raw.startsWith("/") || /^[a-zA-Z]:/.test(raw))
+        return escaped(`'${raw}' must be relative to the working directory`);
+    if (raw.startsWith("~"))
+        return escaped(`'${raw}' must not start with '~'`);
+    const segments = raw.split("/").filter((s) => s !== "" && s !== ".");
+    if (segments.length === 0)
+        return escaped(`'${raw}' names no file`);
+    if (segments.some((s) => s === ".."))
+        return escaped(`'${raw}' escapes the working directory`);
+    const path = segments.join("/");
+    const shadowed = (mount) => ({
+        ok: false,
+        problem: {
+            kind: "shadowed",
+            message: `'${path}' lands under the read-only mount '${mount}', where it would be on disk but invisible to the container`,
+        },
+    });
+    for (const file of READONLY_MOUNTS.file)
+        if (path === file)
+            return shadowed(file);
+    for (const dir of READONLY_MOUNTS.dir)
+        if (path === dir || path.startsWith(`${dir}/`))
+            return shadowed(dir);
+    for (const re of READONLY_MOUNTS.pattern)
+        if (re.test(path))
+            return shadowed(path.split("/").slice(0, 3).join("/"));
+    return { ok: true, path };
+}
+/** checkWorkdirPath, throwing. For the worker, where a bad path is a launch
+ *  failure rather than a form validation message. */
+export function assertSafeWorkdirPath(raw) {
+    const checked = checkWorkdirPath(raw);
+    if (!checked.ok)
+        throw new Error(checked.problem.message);
+    return checked.path;
+}