@norskvideo/ctl-sdk 0.1.35 → 0.1.37

package/http-proxy.d.ts

@@ -25,6 +25,10 @@ export type ProxyHttpOptions = ForwardResponseOptions & {
     timeoutMs?: number;
 };
 /** Proxy one HTTP request to `targetUrl`, streaming the response body back.
+ *  Forwards the request's headers as they arrive: this runs INSIDE an instance
+ *  (a product backend fronting its own studio), where the ingress has already
+ *  blanked the client-supplied identity headers. The runner's product proxy,
+ *  which sits at the trust boundary, strips them itself in proxy-middleware.ts.
  *  Never throws into express: an unreachable/booting upstream surfaces as a
  *  502 the caller retries. */
 export declare function proxyHttp(req: Request, res: Response, targetUrl: string, opts?: ProxyHttpOptions): Promise<void>;

package/http-proxy.js

@@ -93,6 +93,10 @@ export async function forwardUpstreamResponse(res, upstream, opts = {}) {
 }
 const DEFAULT_PROXY_TIMEOUT_MS = 30_000;
 /** Proxy one HTTP request to `targetUrl`, streaming the response body back.
+ *  Forwards the request's headers as they arrive: this runs INSIDE an instance
+ *  (a product backend fronting its own studio), where the ingress has already
+ *  blanked the client-supplied identity headers. The runner's product proxy,
+ *  which sits at the trust boundary, strips them itself in proxy-middleware.ts.
  *  Never throws into express: an unreachable/booting upstream surfaces as a
  *  502 the caller retries. */
 export async function proxyHttp(req, res, targetUrl, opts = {}) {

package/index.d.ts

@@ -20,4 +20,5 @@ export * from "./product-service.js";
 export * from "./product-template-materials.js";
 export * from "./proxy-middleware.js";
 export * from "./route-error.js";
+export * from "./runner-capabilities.js";
 export * from "./sse.js";

package/index.js

@@ -22,4 +22,5 @@ export * from "./product-service.js";
 export * from "./product-template-materials.js";
 export * from "./proxy-middleware.js";
 export * from "./route-error.js";
+export * from "./runner-capabilities.js";
 export * from "./sse.js";

package/manifest-schema.d.ts

@@ -14,6 +14,7 @@ export declare const ManifestSchema: z.ZodObject<{
     name: z.ZodString;
     version: z.ZodString;
     minRunnerVersion: z.ZodOptional<z.ZodString>;
+    requires: z.ZodOptional<z.ZodArray<z.ZodString>>;
     api: z.ZodObject<{
         basePath: z.ZodString;
         proxyPaths: z.ZodArray<z.ZodString>;

package/manifest-schema.js

@@ -96,6 +96,9 @@ export const ManifestSchema = z.object({
     name: z.string(),
     version: z.string(),
     minRunnerVersion: z.string().optional(),
+    requires: z.array(z.string().min(1)).optional().meta({
+        description: "Named runner capabilities this product version cannot launch without (RFC 0001 §3.6). A runner that lacks any of them refuses the product as too old rather than mis-launching it. Usually absent — evolve the contract additively first; never a runner version number.",
+    }),
     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.35",
+  "version": "0.1.37",
   "type": "module",
   "exports": {
     ".": {
@@ -23,6 +23,10 @@
       "types": "./manifest-seed.d.ts",
       "default": "./manifest-seed.js"
     },
+    "./runner-capabilities": {
+      "types": "./runner-capabilities.d.ts",
+      "default": "./runner-capabilities.js"
+    },
     "./runtime": {
       "types": "./runtime.d.ts",
       "default": "./runtime.js"

package/product-error.d.ts

@@ -1,4 +1,4 @@
 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" | "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" | "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";
+    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);
 }

package/product-service.d.ts

@@ -121,6 +121,10 @@ export interface ProductServiceOptions {
      *  in a container). Default: detected from the daemon's cgroup, overridable
      *  with NORSK_CTL_PRODUCT_REACH. */
     reach?: ProductReach;
+    /** Named runner capabilities this host knows (RFC 0001 §3.6). A product
+     *  whose manifest `requires` any other is refused at add and reload.
+     *  Default: none. */
+    knownCapabilities?: readonly string[];
 }
 export declare class ProductService {
     /**
@@ -145,10 +149,12 @@ export declare class ProductService {
     private readonly isDevUrlAlive;
     private readonly containerOps;
     private readonly reach;
+    private readonly knownCapabilities;
     constructor(opts: ProductServiceOptions);
     /** The address to record for a freshly started container: its own, when
      *  this daemon cannot dial the host loopback; otherwise nothing. */
     private reachHostFor;
+    private refuseUnknownCapabilities;
     list(): ProductRegistration[];
     /** Docker's default `--pull=missing` keeps whatever a moving tag resolved to
      *  last time, so a rebuilt `:latest`/`:dev` never reached a new registration.

package/product-service.js

@@ -7,6 +7,7 @@ import { checkProductEntitlement, notV2EnvelopeMessage, parseLicenseContents } f
 import { fetchManifest, isDevUrlAlive, probeConfigScreen, productBaseUrl, specBaseUrl, waitForReady, } from "./manifest-fetch.js";
 import { ProductError } from "./product-error.js";
 import { detectProductReach } from "./product-reach.js";
+import { checkRequiredCapabilities } from "./runner-capabilities.js";
 /** GET a product-template tar from a product. `url` is whatever the manifest
  *  declared; we treat it as a path on the product's HTTP surface and
  *  resolve against the product's base URL. Returns the raw tar bytes,
@@ -58,6 +59,7 @@ export class ProductService {
     isDevUrlAlive;
     containerOps;
     reach;
+    knownCapabilities;
     constructor(opts) {
         this.store = opts.store;
         this.importProductTemplateBytes = opts.importProductTemplateBytes;
@@ -66,6 +68,7 @@ export class ProductService {
         this.isDevUrlAlive = opts.isDevUrlAlive ?? isDevUrlAlive;
         this.containerOps = opts.containerOps ?? defaultProductContainerOps;
         this.reach = opts.reach ?? detectProductReach({});
+        this.knownCapabilities = opts.knownCapabilities ?? [];
     }
     /** The address to record for a freshly started container: its own, when
      *  this daemon cannot dial the host loopback; otherwise nothing. */
@@ -74,6 +77,10 @@ export class ProductService {
             return undefined;
         return this.containerOps.address(containerId);
     }
+    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;
+    }
     list() {
         return this.store.read();
     }
@@ -137,6 +144,12 @@ export class ProductService {
                 await this.containerOps.remove(containerId);
             throw e;
         });
+        const refusal = this.refuseUnknownCapabilities(manifest);
+        if (refusal) {
+            if (containerId)
+                await this.containerOps.remove(containerId);
+            throw refusal;
+        }
         if (existing.some((p) => p.name === manifest.name)) {
             if (containerId)
                 await this.containerOps.remove(containerId);
@@ -319,6 +332,9 @@ export class ProductService {
         const current = this.store.read().find((p) => p.name === name) ?? target;
         const baseUrl = productBaseUrl(current);
         const manifest = await fetchManifest(baseUrl);
+        const refusal = this.refuseUnknownCapabilities(manifest);
+        if (refusal)
+            throw refusal;
         if (manifest.name !== target.name) {
             throw new ProductError("NAME_CONFLICT", `manifest now reports name '${manifest.name}', was '${target.name}' — use remove + add`);
         }

package/proxy-middleware.d.ts

@@ -3,5 +3,6 @@ import type { ProductRegistration } from "./product-types.js";
 interface ProductRegistry {
     list(): ProductRegistration[];
 }
+export declare function isOauth2SessionCookieName(name: string): boolean;
 export declare function createProductProxyMiddleware(svc: ProductRegistry): (req: Request, res: ExpressResponse, next: NextFunction) => Promise<void>;
 export {};

package/proxy-middleware.js

@@ -7,6 +7,41 @@ function targetBaseUrl(reg) {
     }
     return reg.spec.url.replace(/\/$/, "");
 }
+// The session cookie oauth2-proxy sets at the ctl/mgr ingress (see
+// packages/proxy/src/oauth2-config.ts), including the _0, _1... chunks it
+// splits an oversized session into.
+const OAUTH2_SESSION_COOKIE = /^__(Host|Secure)-[A-Za-z0-9_-]+_oauth2(_\d+)?$/;
+export function isOauth2SessionCookieName(name) {
+    return OAUTH2_SESSION_COOKIE.test(name);
+}
+// No product control plane calls back into ctl/mgr, so the ingress secret
+// (full admin), the caller's bearer token and the ingress session cookie
+// have no business reaching one. The whole `x-norsk-*` space goes, per RFC
+// 0003 Phase 0 item 4 — a header the ingress starts asserting later must not
+// reach a product merely because this code was not updated with its name.
+function buildProductForwardHeaders(req) {
+    const headers = buildForwardHeaders(req);
+    const norskHeaders = [];
+    headers.forEach((_value, name) => {
+        if (name.toLowerCase().startsWith("x-norsk-"))
+            norskHeaders.push(name);
+    });
+    for (const name of norskHeaders)
+        headers.delete(name);
+    headers.delete("authorization");
+    const cookie = headers.get("cookie");
+    if (cookie !== null) {
+        const kept = cookie
+            .split(";")
+            .map((c) => c.trim())
+            .filter((c) => c !== "" && !isOauth2SessionCookieName(c.split("=", 1)[0] ?? ""));
+        if (kept.length > 0)
+            headers.set("cookie", kept.join("; "));
+        else
+            headers.delete("cookie");
+    }
+    return headers;
+}
 export function createProductProxyMiddleware(svc) {
     return async (req, res, next) => {
         const name = req.params.name;
@@ -24,7 +59,7 @@ export function createProductProxyMiddleware(svc) {
             return;
         }
         const targetUrl = `${base}${req.url}`;
-        const headers = buildForwardHeaders(req);
+        const headers = buildProductForwardHeaders(req);
         const body = await readRequestBody(req);
         let upstream;
         try {

package/runner-capabilities.d.ts

@@ -0,0 +1,10 @@
+import { type Result } from "@norskvideo/ctl-foundation";
+export interface CapabilityRefusal {
+    missing: string[];
+    message: string;
+}
+export declare function checkRequiredCapabilities(target: {
+    product: string;
+    version: string;
+    requires?: readonly string[];
+}, known: readonly string[]): Result<void, CapabilityRefusal>;

package/runner-capabilities.js

@@ -0,0 +1,14 @@
+import { err, ok } from "@norskvideo/ctl-foundation";
+// RFC 0001 §3.6: a version whose `requires` names a capability this runner
+// does not know is refused with an explicit "too old" stop rather than a
+// silent mis-launch. Run it before pulling anything for that version.
+export function checkRequiredCapabilities(target, known) {
+    const missing = (target.requires ?? []).filter((c) => !known.includes(c));
+    if (missing.length === 0)
+        return ok(undefined);
+    const needs = missing.map((c) => `'${c}'`).join(", ");
+    return err({
+        missing,
+        message: `your norsk-ctl can't launch ${target.product} ${target.version} — it needs ${needs}; run 'norsk-ctl upgrade'`,
+    });
+}