@norskvideo/ctl-product-template-schema 0.1.56 → 0.1.58

package/index.d.ts

@@ -209,6 +209,10 @@ export declare const ProductTemplateManifestSchema: z.ZodObject<{
             path: z.ZodString;
             openapi: z.ZodString;
         }, z.core.$strip>>>;
+        openPaths: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            prefix: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>>;
     }, z.core.$strip>>;
     dashboard: z.ZodOptional<z.ZodObject<{
         kind: z.ZodString;
@@ -481,6 +485,10 @@ export declare const ProductTemplateMaterialsSchema: z.ZodObject<{
                 path: z.ZodString;
                 openapi: z.ZodString;
             }, z.core.$strip>>>;
+            openPaths: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                path: z.ZodString;
+                prefix: z.ZodOptional<z.ZodBoolean>;
+            }, z.core.$strip>>>;
         }, z.core.$strip>>;
         dashboard: z.ZodOptional<z.ZodObject<{
             kind: z.ZodString;

package/index.js

@@ -117,6 +117,64 @@ export const ProductTemplateDashboardSchema = z.object({
         description: "The roles of the MoQ previews it offers, e.g. main.",
     }),
 });
+// One Studio path a guest reaches without the operator sign-in (RFC 0010): a
+// join page, its assets, the scoped routes it calls. The path carries its own
+// authority (a signed join token), so the sign-in protects nothing there and
+// only stops the guest.
+//
+// Studio's editor API (uploads included) and MCP are never open, and a prefix
+// may not reach into /live/, which holds every component's API and every live
+// socket. Exact paths under /live/ are how a product opens one route and not
+// its neighbours (`join` but not `join-link`).
+//
+// A `{name}` segment stands for any one segment, for guests named at runtime
+// (`commentators/{commentator}/join`). It never stands for the first segment,
+// which decides /api, /mcp and /live, nor for the component under /live/: the
+// component is what vouches for its own routes, so "this route on every
+// component" would open routes no component offered. A prefix is literal.
+const OPEN_PATH = /^\/[A-Za-z0-9._~-]+(\/([A-Za-z0-9._~-]+|\{[A-Za-z][A-Za-z0-9_]*\}))*\/?$/;
+const PLACEHOLDER = /^\{.*\}$/;
+const NEVER_OPEN = ["/api", "/mcp"];
+const under = (path, root) => path === root || path.startsWith(`${root}/`);
+/** The component a /live path addresses: `/live/<c>/ws`, `/live/api/<c>/...`. */
+const liveComponentSegment = (path) => {
+    const [, first, second, third] = path.split("/");
+    if (first !== "live")
+        return undefined;
+    return second === "api" ? third : second;
+};
+const ProductTemplateOpenPathSchema = z
+    .object({
+    path: z
+        .string()
+        .regex(OPEN_PATH, "an absolute path under the Studio route: letters, digits and . _ ~ - between slashes, or a whole-segment {name} after the first")
+        .refine(SAFE_SEGMENTS, { message: "no . or .. segments" })
+        .refine((p) => !NEVER_OPEN.some((root) => under(p, root)), {
+        message: `Studio's ${NEVER_OPEN.join(" and ")} are never open`,
+    })
+        .meta({
+        description: "Path relative to the instance's Studio route: /dashboard/x is served at /instance/<id>/studio/dashboard/x. Never under /api or /mcp. A whole segment written {name} matches any one segment, except the first and the component under /live/.",
+    }),
+    prefix: z.boolean().optional().meta({
+        description: "Open everything below `path`, which must then end in `/`. For static assets; a prefix may not reach into /live/. Omit for an exact path.",
+    }),
+})
+    .refine((o) => !o.prefix || o.path.endsWith("/"), {
+    message: "a prefix ends in /",
+    path: ["path"],
+})
+    .refine((o) => !o.prefix || !under(o.path.replace(/\/$/, ""), "/live"), {
+    message: "a prefix may not reach into /live/: open each route there by its exact path",
+    path: ["path"],
+})
+    .refine((o) => !o.prefix || !o.path.includes("{"), {
+    message: "a prefix is literal: placeholders are for exact paths",
+    path: ["path"],
+})
+    .refine((o) => !PLACEHOLDER.test(liveComponentSegment(o.path) ?? ""), {
+    message: "a placeholder may not stand for the component under /live/: name the component",
+    path: ["path"],
+});
 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.",
@@ -127,6 +185,15 @@ const ProductTemplateProxySchema = z.object({
     operations: z.array(ProductTemplateOperationsSchema).optional().meta({
         description: "The operations this template's runtimes serve, each set described by an OpenAPI document in the tar; the ones marked x-norsk-dashboard are what fleet dashboards may call, each decided per user by the platform. Additive: a runner that predates it ignores it.",
     }),
+    openPaths: z
+        .array(ProductTemplateOpenPathSchema)
+        .refine((paths) => new Set(paths.map((p) => `${p.prefix ? "prefix" : "exact"} ${p.path}`)).size === paths.length, {
+        message: "each open path once: nginx refuses a duplicate location, and that fails the reload for every instance",
+    })
+        .optional()
+        .meta({
+        description: "Studio paths served without the operator sign-in (RFC 0010): a guest page, its assets and the routes it calls, each of which carries its own authority. Additive: a runner that predates it leaves them signed in.",
+    }),
 });
 // 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-product-template-schema",
-  "version": "0.1.56",
+  "version": "0.1.58",
   "type": "module",
   "exports": {
     ".": {

package/read.d.ts

@@ -1,5 +1,17 @@
 import type { ProductTemplateParameter } from "./index.js";
 import { type ProductTemplateManifest } from "./index.js";
+/** The NORSK_ prefix is platform-injected (runtime identity, allocated ports,
+ *  the licence path...); mgr already refuses an operator value for one, so a
+ *  product declaring one asks for a value nobody may give it.
+ *
+ *  WARN-ONLY FOR ONE RELEASE, then a refusal (a superRefine on
+ *  ProductTemplateParameterSchema.name). Release order: relay (its NORSK_IMAGE
+ *  parameter became MEDIA_IMAGE) and db-chanel (NORSK_CTL_URL became CTL_URL)
+ *  ship first, then ctl and mgr with this warning, then the refusal. The
+ *  callers log what this returns at import, refresh, upload and metadata
+ *  update; nothing re-validates stored templates at startup. */
+export declare const RESERVED_PARAMETER_PREFIX = "NORSK_";
+export declare function reservedParameterNameWarnings(parameters: readonly ProductTemplateParameter[]): string[];
 /**
  * Error taxonomy for product-template lifecycle issues. Codes cover both the
  * "store + extract" path (ctl's ProductTemplateService — extraction, manifest

package/read.js

@@ -9,6 +9,23 @@
 // mgr (which stores raw bytes for relay) does not — so compose presence is a
 // reported fact here, not a verdict.
 import { ParametersFileSchema, ProductTemplateManifestSchema } from "./index.js";
+/** The NORSK_ prefix is platform-injected (runtime identity, allocated ports,
+ *  the licence path...); mgr already refuses an operator value for one, so a
+ *  product declaring one asks for a value nobody may give it.
+ *
+ *  WARN-ONLY FOR ONE RELEASE, then a refusal (a superRefine on
+ *  ProductTemplateParameterSchema.name). Release order: relay (its NORSK_IMAGE
+ *  parameter became MEDIA_IMAGE) and db-chanel (NORSK_CTL_URL became CTL_URL)
+ *  ship first, then ctl and mgr with this warning, then the refusal. The
+ *  callers log what this returns at import, refresh, upload and metadata
+ *  update; nothing re-validates stored templates at startup. */
+export const RESERVED_PARAMETER_PREFIX = "NORSK_";
+export function reservedParameterNameWarnings(parameters) {
+    return parameters
+        .filter((p) => p.name.startsWith(RESERVED_PARAMETER_PREFIX))
+        .map((p) => `parameter '${p.name}' uses the reserved ${RESERVED_PARAMETER_PREFIX} prefix, which the platform sets; ` +
+        "rename it without the prefix. A later release refuses such templates");
+}
 /**
  * Error taxonomy for product-template lifecycle issues. Codes cover both the
  * "store + extract" path (ctl's ProductTemplateService — extraction, manifest