@norskvideo/ctl-sdk 0.1.36 → 0.1.38

package/index.d.ts

@@ -5,6 +5,7 @@ export * from "./dev-url.js";
 export * from "./docker-runner.js";
 export * from "./docs-router.js";
 export * from "./http-proxy.js";
+export * from "./ingress-identity.js";
 export * from "./license-registration.js";
 export * from "./license-staged.js";
 export * from "./license-stager.js";
@@ -20,4 +21,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

@@ -7,6 +7,7 @@ export * from "./dev-url.js";
 export * from "./docker-runner.js";
 export * from "./docs-router.js";
 export * from "./http-proxy.js";
+export * from "./ingress-identity.js";
 export * from "./license-registration.js";
 export * from "./license-staged.js";
 export * from "./license-stager.js";
@@ -22,4 +23,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/ingress-identity.d.ts

@@ -0,0 +1,33 @@
+/**
+ * What a product control plane needs to believe ctl's ingress (RFC 0003 D2b).
+ *
+ * A **library, not a policy decision point**. It answers "did the ingress
+ * really say this, and who did it name?"; what a role may then do is the
+ * product's own `authorize()` (D4a), and Studio's gating lives in the
+ * norsk-studio repo.
+ *
+ * The format itself lives in `@norskvideo/ctl-foundation` so the ingress
+ * renderer and the products that read it cannot drift apart; this module is
+ * the published door onto it, plus the one thing only the launched side knows
+ * — where ctl puts the audience's credentials.
+ */
+export { type AssertionRefusal, AUDIENCE_HEADER, AUDIENCE_SECRET_HEADER, type AudienceAssertion, type AudienceHeaders, CTL_AUDIENCE, CTL_READINESS_PROBE_SUB, type IngressAssertion, ingressAssertionHeaders, instanceAudience, PRINCIPAL_HEADER, productAudience, ROLES_HEADER, verifyIngressAssertion, } from "@norskvideo/ctl-foundation";
+/** The audience this container is, e.g. `urn:norsk:instance:p-1`. */
+export declare const AUDIENCE_ENV = "NORSK_INGRESS_AUDIENCE";
+/** The secret the ingress stamps on this audience's locations, and on no
+ *  other's. */
+export declare const AUDIENCE_SECRET_ENV = "NORSK_INGRESS_AUDIENCE_SECRET";
+/**
+ * The audience credentials ctl injected at launch, or `undefined` when it
+ * injected none.
+ *
+ * `undefined` is a state products must handle rather than a fault: RFC 0001
+ * keeps old ctl launching new product releases, so a product built against
+ * this will run on a runner that has never heard of it. Returning an empty
+ * secret instead would hand that product a verifier that accepts everything,
+ * which is the opposite of what the absence means.
+ */
+export declare function audienceFromEnvironment(env?: Record<string, string | undefined>): {
+    audience: string;
+    secret: string;
+} | undefined;

package/ingress-identity.js

@@ -0,0 +1,36 @@
+/**
+ * What a product control plane needs to believe ctl's ingress (RFC 0003 D2b).
+ *
+ * A **library, not a policy decision point**. It answers "did the ingress
+ * really say this, and who did it name?"; what a role may then do is the
+ * product's own `authorize()` (D4a), and Studio's gating lives in the
+ * norsk-studio repo.
+ *
+ * The format itself lives in `@norskvideo/ctl-foundation` so the ingress
+ * renderer and the products that read it cannot drift apart; this module is
+ * the published door onto it, plus the one thing only the launched side knows
+ * — where ctl puts the audience's credentials.
+ */
+export { AUDIENCE_HEADER, AUDIENCE_SECRET_HEADER, CTL_AUDIENCE, CTL_READINESS_PROBE_SUB, ingressAssertionHeaders, instanceAudience, PRINCIPAL_HEADER, productAudience, ROLES_HEADER, verifyIngressAssertion, } from "@norskvideo/ctl-foundation";
+/** The audience this container is, e.g. `urn:norsk:instance:p-1`. */
+export const AUDIENCE_ENV = "NORSK_INGRESS_AUDIENCE";
+/** The secret the ingress stamps on this audience's locations, and on no
+ *  other's. */
+export const AUDIENCE_SECRET_ENV = "NORSK_INGRESS_AUDIENCE_SECRET";
+/**
+ * The audience credentials ctl injected at launch, or `undefined` when it
+ * injected none.
+ *
+ * `undefined` is a state products must handle rather than a fault: RFC 0001
+ * keeps old ctl launching new product releases, so a product built against
+ * this will run on a runner that has never heard of it. Returning an empty
+ * secret instead would hand that product a verifier that accepts everything,
+ * which is the opposite of what the absence means.
+ */
+export function audienceFromEnvironment(env = process.env) {
+    const audience = env[AUDIENCE_ENV];
+    const secret = env[AUDIENCE_SECRET_ENV];
+    if (!audience || !secret)
+        return undefined;
+    return { audience, secret };
+}

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.36",
+  "version": "0.1.38",
   "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

@@ -4,5 +4,28 @@ 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>;
+/** What the DAEMON asserts to a product control plane on this request (RFC
+ *  0003 D2b), or `undefined` when it has nothing to assert. */
+export interface ProductAssertion {
+    audience: string;
+    secret: string;
+    sub: string;
+    roles: readonly string[];
+}
+export interface ProductProxyOptions {
+    /**
+     * Mint this request's identity for the product it is addressed to.
+     *
+     * **Why the daemon and not the ingress.** `/products/<name>` is proxied by
+     * the daemon, so the ingress has no location on a product's control plane to
+     * stamp — asserting there would mean routing products through nginx
+     * directly, which is a different topology. Phase 0 item 4 (E6) made this
+     * proxy strip the client's `x-norsk-*`, `Cookie` and `Authorization`, and
+     * that strip stays and runs first: what crosses here is not forwarded, it is
+     * minted from the decision the daemon has already made, and the secret is the
+     * product's own rather than `x-norsk-proxy` (root-equivalent at ctl, E2).
+     */
+    assertIdentity?: (req: Request, productName: string) => Promise<ProductAssertion | undefined>;
+}
+export declare function createProductProxyMiddleware(svc: ProductRegistry, opts?: ProductProxyOptions): (req: Request, res: ExpressResponse, next: NextFunction) => Promise<void>;
 export {};

package/proxy-middleware.js

@@ -1,4 +1,4 @@
-import { logger } from "@norskvideo/ctl-foundation";
+import { ingressAssertionHeaders, logger } from "@norskvideo/ctl-foundation";
 import { buildForwardHeaders, forwardUpstreamResponse, readRequestBody } from "./http-proxy.js";
 import { productBaseUrl } from "./manifest-fetch.js";
 function targetBaseUrl(reg) {
@@ -42,7 +42,7 @@ function buildProductForwardHeaders(req) {
     }
     return headers;
 }
-export function createProductProxyMiddleware(svc) {
+export function createProductProxyMiddleware(svc, opts = {}) {
     return async (req, res, next) => {
         const name = req.params.name;
         if (typeof name !== "string" || !name)
@@ -59,7 +59,14 @@ export function createProductProxyMiddleware(svc) {
             return;
         }
         const targetUrl = `${base}${req.url}`;
+        // Strip first, always. The assertion below then SETS its own values, so a
+        // client's copies are gone whether or not there is anything to assert.
         const headers = buildProductForwardHeaders(req);
+        const asserted = await opts.assertIdentity?.(req, name);
+        if (asserted !== undefined) {
+            for (const [name, value] of Object.entries(ingressAssertionHeaders(asserted)))
+                headers.set(name, value);
+        }
         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'`,
+    });
+}