@norskvideo/ctl-product-template-schema 0.1.16 → 0.1.18

package/index.d.ts

@@ -132,6 +132,9 @@ export declare const ProductTemplateManifestSchema: z.ZodObject<{
             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>;
@@ -307,6 +310,9 @@ export declare const ProductTemplateMaterialsSchema: z.ZodObject<{
                 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

@@ -256,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.16",
+  "version": "0.1.18",
   "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",
@@ -25,7 +33,7 @@
   "dependencies": {
     "@norskvideo/ctl-foundation": "^0.1.0",
     "yaml": "^2.8.0",
-    "zod": "^4.3.6"
+    "zod": "4.4.3"
   },
   "publishConfig": {
     "access": "public"

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