@norskvideo/ctl-sdk 0.1.42 → 0.1.44

package/manifest-schema.d.ts

@@ -9,6 +9,19 @@ declare const DefaultProductTemplateSchema: z.ZodObject<{
     url: z.ZodString;
 }, z.core.$strip>;
 export type DefaultProductTemplate = z.infer<typeof DefaultProductTemplateSchema>;
+/** One product role (RFC 0003 D5a). The name rule is foundation's, so the
+ *  runner that stamps it and the manifest that declares it cannot disagree. */
+declare const ProductRoleSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    defaultFor: z.ZodOptional<z.ZodEnum<{
+        viewer: "viewer";
+        operator: "operator";
+        builder: "builder";
+        admin: "admin";
+    }>>;
+}, z.core.$strip>;
+export type ProductRoleDeclaration = z.infer<typeof ProductRoleSchema>;
 export declare const ManifestSchema: z.ZodObject<{
     manifestSchemaVersion: z.ZodLiteral<1>;
     name: z.ZodString;
@@ -16,6 +29,18 @@ export declare const ManifestSchema: z.ZodObject<{
     minRunnerVersion: z.ZodOptional<z.ZodString>;
     requires: z.ZodOptional<z.ZodArray<z.ZodString>>;
     accessModes: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    access: z.ZodOptional<z.ZodObject<{
+        roles: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            description: z.ZodString;
+            defaultFor: z.ZodOptional<z.ZodEnum<{
+                viewer: "viewer";
+                operator: "operator";
+                builder: "builder";
+                admin: "admin";
+            }>>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
     api: z.ZodObject<{
         basePath: z.ZodString;
         proxyPaths: z.ZodArray<z.ZodString>;
@@ -73,9 +98,9 @@ export declare const ManifestSchema: z.ZodObject<{
                 }, z.core.$strip>>>;
                 request: z.ZodOptional<z.ZodObject<{
                     method: z.ZodEnum<{
+                        PUT: "PUT";
                         GET: "GET";
                         POST: "POST";
-                        PUT: "PUT";
                         DELETE: "DELETE";
                     }>;
                     path: z.ZodString;
@@ -83,9 +108,9 @@ export declare const ManifestSchema: z.ZodObject<{
             }, z.core.$strip>>>;
             request: z.ZodOptional<z.ZodObject<{
                 method: z.ZodEnum<{
+                    PUT: "PUT";
                     GET: "GET";
                     POST: "POST";
-                    PUT: "PUT";
                     DELETE: "DELETE";
                 }>;
                 path: z.ZodString;
@@ -169,6 +194,9 @@ export declare const ManifestSchema: z.ZodObject<{
             }>;
             value: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>>;
+        st2110Nics: z.ZodOptional<z.ZodObject<{
+            count: z.ZodNumber;
+        }, z.core.$strip>>;
     }, z.core.$strip>>;
     defaultProductTemplates: z.ZodDefault<z.ZodArray<z.ZodObject<{
         name: z.ZodString;

package/manifest-schema.js

@@ -1,3 +1,4 @@
+import { PLATFORM_ROLE_LADDER, parseProductRoleName } from "@norskvideo/ctl-foundation";
 import { ProductTemplateRequirementsSchema } from "@norskvideo/ctl-product-template-schema";
 import { z } from "zod";
 const TargetSchema = z.enum(["norsk-ctl", "docker-compose"]);
@@ -91,6 +92,30 @@ const ExportSchema = z.object({
     include: z.array(z.string()).default([]),
     exclude: z.array(z.string()).default([]),
 });
+/** One product role (RFC 0003 D5a). The name rule is foundation's, so the
+ *  runner that stamps it and the manifest that declares it cannot disagree. */
+const ProductRoleSchema = z.object({
+    name: z
+        .string()
+        .refine((name) => parseProductRoleName(name).status === "ok", {
+        message: "a product role is lower-kebab and never a platform role's name",
+    })
+        .meta({
+        description: "Bare role name, as Studio's access policy names it (`mcr-operator`). Lower-kebab, starting with a letter, never a platform role's name. Travels bare in `X-Norsk-Roles`, so two products on one host may share a name only if they agree on its `defaultFor`.",
+    }),
+    description: z.string().meta({ description: "What holding this role is for, for the operator assigning it." }),
+    defaultFor: z.enum(PLATFORM_ROLE_LADDER).optional().meta({
+        description: "A platform rung whose holders get this role implicitly on this product's instances (that rung or stronger). An implicit assignment a product release could widen, so the runner records it on add and reload, and an operator can switch implicit defaults off (`acceptProductDefaults: false`).",
+    }),
+});
+const AccessSchema = z.object({
+    roles: z
+        .array(ProductRoleSchema)
+        .default([])
+        .refine((roles) => new Set(roles.map((r) => r.name)).size === roles.length, {
+        message: "a product role is declared at most once",
+    }),
+});
 export const ManifestSchema = z.object({
     manifestSchemaVersion: z.literal(1),
     name: z.string(),
@@ -102,6 +127,9 @@ export const ManifestSchema = z.object({
     accessModes: z.array(z.string().min(1)).optional().meta({
         description: "The NORSK_PRODUCT_ACCESS values this product's control plane understands. The runner sets that variable only when the mode it is in appears here; absent, it sets nothing and the control plane runs with its gate dormant. This is the POSITIVE signal RFC 0001's 2026-09-21 amendment requires before a product may decline to serve: a product must never infer that it was promised enforcement from a missing variable, because a developer running it directly and an older runner launching it are indistinguishable from the inside. Declared on the product manifest rather than a product template because the control plane is started by `docker run` at `product add`, before any template for it exists -- templates are fetched FROM it -- and because this manifest is served by the very image that enforces, so the two cannot drift. A list rather than a boolean: the runner must never send a word this image predates.",
     }),
+    access: AccessSchema.optional().meta({
+        description: "The product roles this product defines (RFC 0003 D5a/D6). Additive: a manifest without it declares none, and every principal reaches its instances on platform roles alone, as before.",
+    }),
     api: z.object({
         basePath: z.string(),
         proxyPaths: z.array(z.string()),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-sdk",
-  "version": "0.1.42",
+  "version": "0.1.44",
   "type": "module",
   "exports": {
     ".": {

package/parsing.d.ts

@@ -6,4 +6,10 @@ export declare function parseSpec(raw: unknown, where: string, path: string): Pr
 export interface ProductsFile {
     products: ProductRegistration[];
 }
+/** The products file's schema version. Unstamped files are version 0 (every
+ *  file written so far); a file stamped with a higher version was written by
+ *  a newer norsk-ctl or norsk-mgr and is refused rather than misread, the
+ *  rule every other store follows. Bump when the shape changes and add the
+ *  migration at the store. */
+export declare const PRODUCTS_FILE_VERSION = 0;
 export declare function parseProductsFile(raw: unknown, path: string): ProductsFile;

package/parsing.js

@@ -1,3 +1,4 @@
+import { parsePlatformRole } from "@norskvideo/ctl-foundation";
 import { ManifestSchema } from "./manifest-schema.js";
 export class ProductsParseError extends Error {
     constructor(path, reason) {
@@ -59,9 +60,19 @@ function parseLicense(raw, where, path) {
     }
     throw new ProductsParseError(path, `${where}.license.mode must be 'byol' or 'marketplace'`);
 }
+/** The products file's schema version. Unstamped files are version 0 (every
+ *  file written so far); a file stamped with a higher version was written by
+ *  a newer norsk-ctl or norsk-mgr and is refused rather than misread, the
+ *  rule every other store follows. Bump when the shape changes and add the
+ *  migration at the store. */
+export const PRODUCTS_FILE_VERSION = 0;
 export function parseProductsFile(raw, path) {
     if (!isRecord(raw))
         throw new ProductsParseError(path, "file is not a YAML object");
+    if (typeof raw.version === "number" && raw.version > PRODUCTS_FILE_VERSION) {
+        throw new ProductsParseError(path, `is at version ${raw.version}, written by a newer norsk-ctl/norsk-mgr; this one understands up to ${PRODUCTS_FILE_VERSION}. ` +
+            "Run the newer one, or restore the pre-upgrade copy kept beside the file.");
+    }
     const products = raw.products;
     if (products === undefined)
         return { products: [] };
@@ -100,6 +111,19 @@ export function parseProductsFile(raw, path) {
             reg.reachHost = entry.reachHost;
         if (entry.license !== undefined)
             reg.license = parseLicense(entry.license, where, path);
+        if (Array.isArray(entry.acceptedRoleDefaults)) {
+            // Anything malformed is dropped rather than refused: this is an
+            // acceptance record, and the safe reading of a damaged one is "accepted
+            // less", which only ever withholds a default.
+            reg.acceptedRoleDefaults = entry.acceptedRoleDefaults.flatMap((d) => {
+                const { name, defaultFor } = (d ?? {});
+                return typeof name === "string" &&
+                    typeof defaultFor === "string" &&
+                    parsePlatformRole(defaultFor).status === "ok"
+                    ? [{ name, defaultFor: defaultFor }]
+                    : [];
+            });
+        }
         validated.push(reg);
     }
     return { products: validated };

package/product-error.d.ts

@@ -1,4 +1,8 @@
 export declare class ProductError extends Error {
-    code: "DEV_URL_INVALID" | "DEV_URL_NOT_LOCALHOST" | "PORT_EXHAUSTED" | "DOCKER_PULL_FAILED" | "DOCKER_RUN_FAILED" | "READINESS_TIMEOUT" | "MANIFEST_FETCH_FAILED" | "MANIFEST_INVALID" | "CONFIG_SCREEN_UNREACHABLE" | "CONFIG_SCREEN_DEV_SERVER" | "LICENSE_INVALID" | "NAME_CONFLICT" | "NOT_FOUND" | "NOT_RESTARTABLE" | "RUNNER_TOO_OLD" | "PRODUCT_TEMPLATE_FETCH_FAILED";
-    constructor(code: "DEV_URL_INVALID" | "DEV_URL_NOT_LOCALHOST" | "PORT_EXHAUSTED" | "DOCKER_PULL_FAILED" | "DOCKER_RUN_FAILED" | "READINESS_TIMEOUT" | "MANIFEST_FETCH_FAILED" | "MANIFEST_INVALID" | "CONFIG_SCREEN_UNREACHABLE" | "CONFIG_SCREEN_DEV_SERVER" | "LICENSE_INVALID" | "NAME_CONFLICT" | "NOT_FOUND" | "NOT_RESTARTABLE" | "RUNNER_TOO_OLD" | "PRODUCT_TEMPLATE_FETCH_FAILED", message: string);
+    code: "DEV_URL_INVALID" | "DEV_URL_NOT_LOCALHOST" | "PORT_EXHAUSTED" | "DOCKER_PULL_FAILED" | "DOCKER_RUN_FAILED" | "READINESS_TIMEOUT" | "MANIFEST_FETCH_FAILED" | "MANIFEST_INVALID" | "CONFIG_SCREEN_UNREACHABLE" | "CONFIG_SCREEN_DEV_SERVER" | "LICENSE_INVALID" | "NAME_CONFLICT" | "NOT_FOUND" | "NOT_RESTARTABLE" | "RUNNER_TOO_OLD" | "PRODUCT_TEMPLATE_FETCH_FAILED"
+    /** Two products declare one bare role name with different `defaultFor`. */
+     | "ROLE_CONFLICT";
+    constructor(code: "DEV_URL_INVALID" | "DEV_URL_NOT_LOCALHOST" | "PORT_EXHAUSTED" | "DOCKER_PULL_FAILED" | "DOCKER_RUN_FAILED" | "READINESS_TIMEOUT" | "MANIFEST_FETCH_FAILED" | "MANIFEST_INVALID" | "CONFIG_SCREEN_UNREACHABLE" | "CONFIG_SCREEN_DEV_SERVER" | "LICENSE_INVALID" | "NAME_CONFLICT" | "NOT_FOUND" | "NOT_RESTARTABLE" | "RUNNER_TOO_OLD" | "PRODUCT_TEMPLATE_FETCH_FAILED"
+    /** Two products declare one bare role name with different `defaultFor`. */
+     | "ROLE_CONFLICT", message: string);
 }

package/product-service.d.ts

@@ -1,9 +1,9 @@
 import { type ProductPlacement } from "./docker-runner.js";
 import { type LicenseStager } from "./license-registration.js";
-import type { Manifest } from "./manifest-schema.js";
+import type { Manifest, ProductRoleDeclaration } from "./manifest-schema.js";
 import { type ProductReach } from "./product-reach.js";
 import type { ProductTemplateSource } from "./product-template-record.js";
-import type { ProductLicense, ProductRegistration, ProductSpec } from "./product-types.js";
+import type { ProductLicense, ProductRegistration, ProductSpec, RoleDefault } from "./product-types.js";
 /**
  * Result of registering a new product. `warnings` reserved for future
  * non-fatal advisories surfaced alongside the success message; currently
@@ -150,6 +150,18 @@ export interface ProductServiceOptions {
     /** Drop whatever `identityEnvFor` minted, once the registration holding it
      *  has gone. */
     forgetIdentity?: (productName: string) => void;
+    /**
+     * Told the product roles a manifest declares (RFC 0003 D5a), once per add
+     * and per reload that stores it. `defaultFor` is an implicit assignment a
+     * product release can widen, so the host records every declaration rather
+     * than taking it silently. Omitted by hosts that assign no product roles.
+     */
+    onRolesDeclared?: (productName: string, roles: readonly ProductRoleDeclaration[], acceptance: {
+        pending: readonly RoleDefault[];
+    }) => void;
+    /** Told once a registration is removed, so the host can drop whatever it
+     *  holds against the product (role assignments on `product/<name>`). */
+    onRemoved?: (productName: string) => void;
     /**
      * What the daemon asserts when it dials a REGISTERED product's own routes —
      * the config-screen probe and the product-template fetches (RFC 0003 D7's
@@ -205,6 +217,16 @@ export declare class ProductService {
     /** The address to record for a freshly started container: its own, when
      *  this daemon cannot dial the host loopback; otherwise nothing. */
     private reachHostFor;
+    private readonly onRolesDeclared?;
+    private readonly onRemoved?;
+    /**
+     * Product roles travel bare, so a name means one thing on a host. Two
+     * products may share one — a common vocabulary is the point — but not with
+     * different `defaultFor`, which would make "who implicitly holds it" depend
+     * on which manifest was read last. Named in the refusal: the operator has to
+     * know which two products to talk to.
+     */
+    private refuseRoleConflicts;
     private refuseUnknownCapabilities;
     list(): ProductRegistration[];
     /** Docker's default `--pull=missing` keeps whatever a moving tag resolved to
@@ -257,3 +279,13 @@ export declare class ProductService {
     restart(name: string): Promise<void>;
     private restartSerialised;
 }
+/**
+ * A registered product's roles as they take effect (RFC 0003 D5): every
+ * declared role, carrying its `defaultFor` only where the operator accepted
+ * that exact pair. What the host reads, so an unaccepted widening grants
+ * nobody anything.
+ */
+export declare function effectiveRoleDeclarations(registration: Pick<ProductRegistration, "manifest" | "acceptedRoleDefaults">): {
+    name: string;
+    defaultFor?: RoleDefault["defaultFor"];
+}[];

package/product-service.js

@@ -73,6 +73,8 @@ export class ProductService {
         this.reach = opts.reach ?? detectProductReach({});
         this.knownCapabilities = opts.knownCapabilities ?? [];
         this.identityEnvFor = opts.identityEnvFor;
+        this.onRolesDeclared = opts.onRolesDeclared;
+        this.onRemoved = opts.onRemoved;
         this.forgetIdentity = opts.forgetIdentity;
         this.probeHeadersFor = opts.probeHeadersFor;
     }
@@ -94,6 +96,30 @@ export class ProductService {
             return undefined;
         return this.containerOps.address(containerId);
     }
+    onRolesDeclared;
+    onRemoved;
+    /**
+     * Product roles travel bare, so a name means one thing on a host. Two
+     * products may share one — a common vocabulary is the point — but not with
+     * different `defaultFor`, which would make "who implicitly holds it" depend
+     * on which manifest was read last. Named in the refusal: the operator has to
+     * know which two products to talk to.
+     */
+    refuseRoleConflicts(manifest, others) {
+        for (const role of manifest.access?.roles ?? []) {
+            for (const other of others) {
+                if (other.name === manifest.name)
+                    continue;
+                const theirs = other.manifest.access?.roles.find((r) => r.name === role.name);
+                if (theirs !== undefined && theirs.defaultFor !== role.defaultFor) {
+                    return new ProductError("ROLE_CONFLICT", `product role '${role.name}' is declared by '${other.name}' with defaultFor ${theirs.defaultFor ?? "none"} ` +
+                        `and by '${manifest.name}' with defaultFor ${role.defaultFor ?? "none"}; product roles are bare names, ` +
+                        "so two products must agree on one before both can be registered");
+                }
+            }
+        }
+        return undefined;
+    }
     refuseUnknownCapabilities(manifest) {
         const check = checkRequiredCapabilities({ product: manifest.name, version: manifest.version, requires: manifest.requires }, this.knownCapabilities);
         return check.status === "error" ? new ProductError("RUNNER_TOO_OLD", check.error.message) : undefined;
@@ -172,6 +198,12 @@ export class ProductService {
                 await this.containerOps.remove(containerId);
             throw new ProductError("NAME_CONFLICT", `product '${manifest.name}' already registered`);
         }
+        const roleConflict = this.refuseRoleConflicts(manifest, existing);
+        if (roleConflict) {
+            if (containerId)
+                await this.containerOps.remove(containerId);
+            throw roleConflict;
+        }
         const warnings = [];
         // Licensing V2: a per-product license file must actually entitle this
         // product (name + image ref/version + expiry, root signature). Anything
@@ -280,6 +312,8 @@ export class ProductService {
             spec,
             addedAt: new Date().toISOString(),
             manifest,
+            // What the operator saw at add is what is accepted (RFC 0003 D5).
+            acceptedRoleDefaults: roleDefaultsOf(manifest),
             ...(port !== undefined ? { port } : {}),
             ...(containerId !== undefined ? { containerId } : {}),
             ...(reachHost !== undefined ? { reachHost } : {}),
@@ -293,6 +327,7 @@ export class ProductService {
         };
         await this.store.update((products) => [...products, registration]);
         logger.info(`Product '${manifest.name}' registered (${spec.kind})`);
+        this.onRolesDeclared?.(manifest.name, manifest.access?.roles ?? [], { pending: [] });
         // defaultProductTemplates: fetch each declared URL relative to the
         // product's base and hand the bytes to the host's product-template store.
         // Failures here are downgraded to warnings rather than rolling back
@@ -339,6 +374,7 @@ export class ProductService {
         // for a product nothing routes to. Safe because every launch mints afresh,
         // so a re-added product of the same name is stamped anew.
         this.forgetIdentity?.(name);
+        this.onRemoved?.(name);
         logger.info(`Product '${name}' removed`);
     }
     /** Bring a registration up to date with what its image now serves. For a
@@ -383,12 +419,21 @@ export class ProductService {
         const refusal = this.refuseUnknownCapabilities(manifest);
         if (refusal)
             throw refusal;
+        const roleConflict = this.refuseRoleConflicts(manifest, this.store.read());
+        if (roleConflict)
+            throw roleConflict;
         if (manifest.name !== target.name) {
             throw new ProductError("NAME_CONFLICT", `manifest now reports name '${manifest.name}', was '${target.name}' — use remove + add`);
         }
-        const updated = await this.store.update((products) => products.map((p) => (p.name === name ? { ...p, manifest } : p)));
+        // A reload may narrow what is accepted, never widen it: a default the
+        // operator did not see at add is pending until the product is re-added.
+        const declaredDefaults = roleDefaultsOf(manifest);
+        const accepted = declaredDefaults.filter((d) => sameDefault(target.acceptedRoleDefaults ?? [], d));
+        const pending = declaredDefaults.filter((d) => !sameDefault(accepted, d));
+        const updated = await this.store.update((products) => products.map((p) => (p.name === name ? { ...p, manifest, acceptedRoleDefaults: accepted } : p)));
         const registration = updated.find((p) => p.name === name);
         logger.info(`Product '${name}' reloaded${containerRestarted ? " (container re-run)" : ""}`);
+        this.onRolesDeclared?.(name, manifest.access?.roles ?? [], { pending });
         // Same downgrade as add's default-template import: the product itself is
         // healthy, so a template the host refuses (in use, foreign) or a fetch
         // that fails is a warning the operator acts on, not a failed reload.
@@ -537,3 +582,22 @@ function withContainerId(reg, containerId, reachHost) {
 function withPlacement(reg, containerId, hostPort, reachHost) {
     return { ...withContainerId(reg, containerId, reachHost), port: hostPort };
 }
+/** The `defaultFor` pairs a manifest declares. */
+function roleDefaultsOf(manifest) {
+    return (manifest.access?.roles ?? []).flatMap((r) => r.defaultFor === undefined ? [] : [{ name: r.name, defaultFor: r.defaultFor }]);
+}
+function sameDefault(set, d) {
+    return set.some((a) => a.name === d.name && a.defaultFor === d.defaultFor);
+}
+/**
+ * A registered product's roles as they take effect (RFC 0003 D5): every
+ * declared role, carrying its `defaultFor` only where the operator accepted
+ * that exact pair. What the host reads, so an unaccepted widening grants
+ * nobody anything.
+ */
+export function effectiveRoleDeclarations(registration) {
+    const accepted = registration.acceptedRoleDefaults ?? [];
+    return (registration.manifest.access?.roles ?? []).map((r) => r.defaultFor !== undefined && sameDefault(accepted, { name: r.name, defaultFor: r.defaultFor })
+        ? { name: r.name, defaultFor: r.defaultFor }
+        : { name: r.name });
+}

package/product-types.d.ts

@@ -1,3 +1,4 @@
+import type { PlatformRole } from "@norskvideo/ctl-foundation";
 import type { Manifest } from "./manifest-schema.js";
 export type ProductSpec = 
 /** `env` is the deploy-time environment for the control-plane container,
@@ -38,4 +39,17 @@ export interface ProductRegistration {
     /** Absent on registrations that predate per-product licenses — launches
      *  fall back to the host's global license setting. */
     license?: ProductLicense;
+    /**
+     * The `defaultFor` pairs an operator has accepted for this product (RFC 0003
+     * D5). Set to the declared defaults at add — the declaration the operator
+     * saw — and only ever narrowed by a reload: a reload that widens a default
+     * leaves the widened pair out, reported as pending. Absent on registrations
+     * from before acceptance existed, which accepted nothing.
+     */
+    acceptedRoleDefaults?: RoleDefault[];
+}
+/** One accepted `defaultFor`: the role and the rung it defaults to. */
+export interface RoleDefault {
+    name: string;
+    defaultFor: PlatformRole;
 }