@norskvideo/ctl-sdk 0.1.37 → 0.1.39

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";
@@ -15,6 +16,7 @@ export * from "./migration-client.js";
 export * from "./openapi-router.js";
 export * from "./product-health-monitor.js";
 export * from "./product-hub.js";
+export * from "./product-pep.js";
 export * from "./product-reach.js";
 export * from "./product-service.js";
 export * from "./product-template-materials.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";
@@ -17,6 +18,7 @@ export * from "./migration-client.js";
 export * from "./openapi-router.js";
 export * from "./product-health-monitor.js";
 export * from "./product-hub.js";
+export * from "./product-pep.js";
 export * from "./product-reach.js";
 export * from "./product-service.js";
 export * from "./product-template-materials.js";

package/ingress-identity.d.ts

@@ -0,0 +1,44 @@
+/**
+ * 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 mode ctl promises this control plane, and the reason it may enforce at
+ * all (RFC 0001's 2026-09-21 amendment, condition 3).
+ *
+ * Declared beside the credentials because it travels with them and means
+ * nothing apart from them: a secret without this is a gate ctl has not asked
+ * to be live, and this without a secret is a promise ctl cannot keep. Spelled
+ * once, here, because ctl writes it and the product reads it -- two spellings
+ * is how one side starts sending a word the other stopped honouring.
+ */
+export declare const PRODUCT_ACCESS_ENV = "NORSK_PRODUCT_ACCESS";
+/**
+ * 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,47 @@
+/**
+ * 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 mode ctl promises this control plane, and the reason it may enforce at
+ * all (RFC 0001's 2026-09-21 amendment, condition 3).
+ *
+ * Declared beside the credentials because it travels with them and means
+ * nothing apart from them: a secret without this is a gate ctl has not asked
+ * to be live, and this without a secret is a promise ctl cannot keep. Spelled
+ * once, here, because ctl writes it and the product reads it -- two spellings
+ * is how one side starts sending a word the other stopped honouring.
+ */
+export const PRODUCT_ACCESS_ENV = "NORSK_PRODUCT_ACCESS";
+/**
+ * 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-fetch.d.ts

@@ -44,4 +44,4 @@ export declare function waitForReady(baseUrl: string, opts?: {
  * Soft warnings (future) would return via the unused return-value slot
  * here. For now both detections are hard fails.
  */
-export declare function probeConfigScreen(baseUrl: string, configScreenUrl: string): Promise<void>;
+export declare function probeConfigScreen(baseUrl: string, configScreenUrl: string, headers?: Record<string, string>): Promise<void>;

package/manifest-fetch.js

@@ -96,12 +96,12 @@ export async function waitForReady(baseUrl, opts = {}) {
  * Soft warnings (future) would return via the unused return-value slot
  * here. For now both detections are hard fails.
  */
-export async function probeConfigScreen(baseUrl, configScreenUrl) {
+export async function probeConfigScreen(baseUrl, configScreenUrl, headers = {}) {
     const path = configScreenUrl.startsWith("/") ? configScreenUrl : `/${configScreenUrl}`;
     const url = `${baseUrl}${path}`;
     let response;
     try {
-        response = await fetch(url, { redirect: "follow" });
+        response = await fetch(url, { redirect: "follow", headers });
     }
     catch (e) {
         throw new ProductError("CONFIG_SCREEN_UNREACHABLE", `configScreenUrl '${path}' at ${baseUrl} unreachable: ${String(e)}`);

package/manifest-schema.d.ts

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

package/manifest-schema.js

@@ -99,6 +99,9 @@ export const ManifestSchema = z.object({
     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.",
     }),
+    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.",
+    }),
     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.37",
+  "version": "0.1.39",
   "type": "module",
   "exports": {
     ".": {

package/product-pep.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The policy enforcement point a product control plane mounts — RFC 0003 D2b
+ * and D4a, the product half of what ctl asserts at `/products/<name>`.
+ *
+ * ctl's own gate on that route is coarse by construction: the route is not a
+ * contract operation, so ctl can only read the METHOD, and a product serving a
+ * state change behind a GET is not protected by it. This is where a product
+ * says what its own routes are worth — D5 keeps that judgement with the product,
+ * because only the product knows that `/configure` is builder's work and
+ * `/docs` is anyone's.
+ *
+ * **Two decisions, kept apart.** What rung a person must hold, and whether a
+ * machine may call at all, are different questions. Collapsing them means either
+ * minting a machine credential strong enough to pass a human's gate — a
+ * builder-equivalent nobody reviews — or exempting a path, which stops being
+ * true the moment the path moves. `allowWorkloads` is therefore its own opt-in,
+ * defaulting to false so a product that has not thought about machines refuses
+ * them.
+ *
+ * **Why enforcement waits for a positive signal.** RFC 0001's 2026-09-21
+ * amendment, condition 3: a product may only decline to serve when it KNOWS it
+ * was promised enforcement, from a signal the launcher sends — never from the
+ * absence of one. From inside the container, a developer running the backend
+ * directly and an older ctl launching it are indistinguishable if you reason
+ * from a missing variable, and reasoning from absence is the defect RFC 0003
+ * has shipped most often. So the gate is dormant until ctl says otherwise.
+ */
+import { type AudienceAssertion, type PlatformRole } from "@norskvideo/ctl-foundation";
+import type { Request, RequestHandler } from "express";
+/** What this control plane is doing about access, right now. `dormant` is the
+ *  shape of every product before ctl promises it anything. */
+export type ProductPepMode = "dormant" | "enforced" | "permissive";
+export type PepDenyReason = 
+/** Told to enforce, given nothing to verify with. Never served. */
+"ingress-identity-missing"
+/** Nothing proved ctl sent this, so the identity headers are just headers. */
+ | "no-assertion"
+/** Authenticated, but does not hold the rung this route asks for. */
+ | "insufficient-role"
+/** Authenticated as a machine on a route that admits only people. */
+ | "workload-not-admitted";
+export interface PepDecision {
+    allow: boolean;
+    reason?: PepDenyReason;
+    sub?: string;
+    roles?: readonly string[];
+    /** Whether this was served despite a refusal, because the mode is permissive. */
+    unenforced?: boolean;
+}
+export interface ProductPepOptions {
+    env?: Record<string, string | undefined>;
+    /** Every decision, allow and refuse alike. A record that only explains its
+     *  refusals leaves the allows to be inferred — and under `permissive` the
+     *  record is the entire point of the exercise. */
+    onDecision?: (decision: PepDecision) => void;
+}
+export interface GateOptions {
+    /** The weakest rung a PERSON must hold. Omit to require only that ctl
+     *  asserted somebody. */
+    role?: PlatformRole;
+    /** Whether a machine principal may call this route at all — ctl's own
+     *  config-screen probe and template fetches are the ones that matter.
+     *  Defaults to false: a route that has not said yes refuses them. */
+    allowWorkloads?: boolean;
+}
+export interface ProductPep {
+    readonly mode: ProductPepMode;
+    /** One line an operator can read without having watched the boot — the
+     *  amendment's "never silent". */
+    describe(): string;
+    gate(options?: GateOptions): RequestHandler;
+    /** What ctl asserted about this request, once a gate has admitted it. */
+    identityOf(req: Request): AudienceAssertion | undefined;
+}
+export declare function createProductPep(options?: ProductPepOptions): ProductPep;

package/product-pep.js

@@ -0,0 +1,115 @@
+/**
+ * The policy enforcement point a product control plane mounts — RFC 0003 D2b
+ * and D4a, the product half of what ctl asserts at `/products/<name>`.
+ *
+ * ctl's own gate on that route is coarse by construction: the route is not a
+ * contract operation, so ctl can only read the METHOD, and a product serving a
+ * state change behind a GET is not protected by it. This is where a product
+ * says what its own routes are worth — D5 keeps that judgement with the product,
+ * because only the product knows that `/configure` is builder's work and
+ * `/docs` is anyone's.
+ *
+ * **Two decisions, kept apart.** What rung a person must hold, and whether a
+ * machine may call at all, are different questions. Collapsing them means either
+ * minting a machine credential strong enough to pass a human's gate — a
+ * builder-equivalent nobody reviews — or exempting a path, which stops being
+ * true the moment the path moves. `allowWorkloads` is therefore its own opt-in,
+ * defaulting to false so a product that has not thought about machines refuses
+ * them.
+ *
+ * **Why enforcement waits for a positive signal.** RFC 0001's 2026-09-21
+ * amendment, condition 3: a product may only decline to serve when it KNOWS it
+ * was promised enforcement, from a signal the launcher sends — never from the
+ * absence of one. From inside the container, a developer running the backend
+ * directly and an older ctl launching it are indistinguishable if you reason
+ * from a missing variable, and reasoning from absence is the defect RFC 0003
+ * has shipped most often. So the gate is dormant until ctl says otherwise.
+ */
+import { isWorkloadPrincipal, roleSatisfies, verifyIngressAssertion, } from "@norskvideo/ctl-foundation";
+import { AUDIENCE_ENV, AUDIENCE_SECRET_ENV, PRODUCT_ACCESS_ENV } from "./ingress-identity.js";
+const IDENTITY = Symbol("norsk.ingress.identity");
+function refuse(res, status, reason, message) {
+    // The SDK's route error shape: a stable label plus what happened.
+    res.status(status).json({ error: reason, message });
+}
+export function createProductPep(options = {}) {
+    const env = options.env ?? process.env;
+    const declared = env[PRODUCT_ACCESS_ENV];
+    const audience = env[AUDIENCE_ENV];
+    const secret = env[AUDIENCE_SECRET_ENV];
+    // An unrecognised word is treated as `enforced`, never as dormant: ctl only
+    // ever sends a mode this product named (membership, not copy), so a value we
+    // do not know means something is wrong, and the safe reading of "something is
+    // wrong" about a security control is not "carry on unguarded".
+    const mode = declared === undefined ? "dormant" : declared === "permissive" ? "permissive" : "enforced";
+    const record = (decision) => {
+        options.onDecision?.(decision);
+        return decision;
+    };
+    function describe() {
+        if (mode === "dormant") {
+            return `access control is DORMANT: ${PRODUCT_ACCESS_ENV} is not set, so this control plane was promised no enforcement and serves every caller. This is the shape of a product run directly, or launched by a runner that does not gate it.`;
+        }
+        if (audience === undefined || secret === undefined) {
+            return `access control is ${mode.toUpperCase()} but ${AUDIENCE_ENV}/${AUDIENCE_SECRET_ENV} are not both set, so nothing can be verified and every gated route refuses.`;
+        }
+        return `access control is ${mode.toUpperCase()} for ${audience}.`;
+    }
+    return {
+        mode,
+        describe,
+        identityOf: (req) => req[IDENTITY],
+        gate(gateOptions = {}) {
+            return (req, res, next) => {
+                if (mode === "dormant") {
+                    record({ allow: true });
+                    next();
+                    return;
+                }
+                // Promised enforcement, handed nothing to enforce with. Refused in both
+                // modes -- `permissive` relaxes a verdict the policy reached, and this
+                // is the absence of any means to reach one.
+                if (audience === undefined || secret === undefined) {
+                    record({ allow: false, reason: "ingress-identity-missing" });
+                    refuse(res, 503, "ingress-identity-missing", describe());
+                    return;
+                }
+                const served = (decision, status, message) => {
+                    if (mode === "permissive") {
+                        record({ ...decision, unenforced: true });
+                        next();
+                        return;
+                    }
+                    record(decision);
+                    refuse(res, status, decision.reason, message);
+                };
+                const verified = verifyIngressAssertion(req.headers, { audience, secret });
+                if (verified.status !== "ok") {
+                    served({ allow: false, reason: "no-assertion" }, 401, `this request carries no identity this control plane can trust: ${verified.error.message}`);
+                    return;
+                }
+                const assertion = verified.value;
+                req[IDENTITY] = assertion;
+                if (isWorkloadPrincipal(assertion.sub)) {
+                    // A machine holds no human rung, so the rung is not the question and
+                    // must not be consulted -- comparing would refuse every machine on a
+                    // route that deliberately admits them.
+                    if (gateOptions.allowWorkloads !== true) {
+                        served({ allow: false, reason: "workload-not-admitted", sub: assertion.sub }, 403, `${assertion.sub} is a machine, and this route admits only people`);
+                        return;
+                    }
+                    record({ allow: true, sub: assertion.sub, roles: assertion.roles });
+                    next();
+                    return;
+                }
+                const required = gateOptions.role;
+                if (required !== undefined && !assertion.roles.some((held) => roleSatisfies(held, required))) {
+                    served({ allow: false, reason: "insufficient-role", sub: assertion.sub, roles: assertion.roles }, 403, `this route needs ${required}`);
+                    return;
+                }
+                record({ allow: true, sub: assertion.sub, roles: assertion.roles });
+                next();
+            };
+        },
+    };
+}

package/product-service.d.ts

@@ -1,5 +1,6 @@
 import { type ProductPlacement } from "./docker-runner.js";
 import { type LicenseStager } from "./license-registration.js";
+import type { Manifest } 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";
@@ -125,6 +126,47 @@ export interface ProductServiceOptions {
      *  whose manifest `requires` any other is refused at add and reload.
      *  Default: none. */
     knownCapabilities?: readonly string[];
+    /**
+     * The ingress identity to run this product's control plane with (RFC 0003
+     * D2b): the audience it is, and the secret the daemon stamps on requests to
+     * it and to no other audience.
+     *
+     * Deliberately NOT part of `ProductSpec`. The spec is persisted on the
+     * registration and serialised by `GET /api/v1/products`, so a secret living
+     * there would leak; this is re-derived from the host's own custody on every
+     * path that runs a container. Hosts that mint nothing return undefined and
+     * the product is launched exactly as before — the absence is a state
+     * products must handle (RFC 0001), not a fault.
+     *
+     * The manifest comes too, because the host also decides here whether to tell
+     * this control plane to ENFORCE, and that has to be read off what the product
+     * declared (`accessModes`). On `add` it is the manifest just fetched from the
+     * container; on the relaunch paths it is the stored one, so a product that
+     * starts declaring a mode is taken at its word from the reload that stores it
+     * rather than the run that precedes it. `undefined` where no manifest is known
+     * yet.
+     */
+    identityEnvFor?: (productName: string, manifest: Manifest | undefined) => Record<string, string> | undefined;
+    /** Drop whatever `identityEnvFor` minted, once the registration holding it
+     *  has gone. */
+    forgetIdentity?: (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
+     * in-stack service→service row).
+     *
+     * These calls carried nothing, which is fine while no product gates anything
+     * and fatal the moment one does: `probeConfigScreen` treats a non-2xx as a
+     * hard rejection, so a product gating its own config screen would fail
+     * `product add` outright.
+     *
+     * Deliberately NOT the operator who triggered the add — this is ctl calling
+     * in its own name, so the `sub` is a workload's and it carries no human rung.
+     * `/manifest.json` is not covered and cannot be: readiness and the manifest
+     * fetch happen during the anonymous first run, before the name is known, so
+     * there is no secret to assert with.
+     */
+    probeHeadersFor?: (productName: string) => Record<string, string> | undefined;
 }
 export declare class ProductService {
     /**
@@ -150,7 +192,16 @@ export declare class ProductService {
     private readonly containerOps;
     private readonly reach;
     private readonly knownCapabilities;
+    private readonly identityEnvFor?;
+    private readonly forgetIdentity?;
+    private readonly probeHeadersFor?;
     constructor(opts: ProductServiceOptions);
+    /** The environment a (re)launch of `productName`'s control plane runs with:
+     *  the spec's deploy-time settings, with the freshly minted ingress identity
+     *  last. The ordering is load-bearing — an operator who got a reserved key
+     *  past the API boundary would otherwise hand themselves a forged identity,
+     *  and the identity is the daemon's decision, never theirs. */
+    private runEnvFor;
     /** The address to record for a freshly started container: its own, when
      *  this daemon cannot dial the host loopback; otherwise nothing. */
     private reachHostFor;

package/product-service.js

@@ -12,11 +12,11 @@ import { checkRequiredCapabilities } from "./runner-capabilities.js";
  *  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,
  *  or throws ProductError on any non-2xx / network failure. */
-async function fetchProductTemplateBytes(baseUrl, url) {
+async function fetchProductTemplateBytes(baseUrl, url, headers = {}) {
     const full = `${baseUrl.replace(/\/$/, "")}/${url.replace(/^\//, "")}`;
     let response;
     try {
-        response = await fetch(full);
+        response = await fetch(full, { headers });
     }
     catch (e) {
         throw new ProductError("PRODUCT_TEMPLATE_FETCH_FAILED", `fetch ${full} threw: ${String(e)}`);
@@ -60,6 +60,9 @@ export class ProductService {
     containerOps;
     reach;
     knownCapabilities;
+    identityEnvFor;
+    forgetIdentity;
+    probeHeadersFor;
     constructor(opts) {
         this.store = opts.store;
         this.importProductTemplateBytes = opts.importProductTemplateBytes;
@@ -69,6 +72,20 @@ export class ProductService {
         this.containerOps = opts.containerOps ?? defaultProductContainerOps;
         this.reach = opts.reach ?? detectProductReach({});
         this.knownCapabilities = opts.knownCapabilities ?? [];
+        this.identityEnvFor = opts.identityEnvFor;
+        this.forgetIdentity = opts.forgetIdentity;
+        this.probeHeadersFor = opts.probeHeadersFor;
+    }
+    /** The environment a (re)launch of `productName`'s control plane runs with:
+     *  the spec's deploy-time settings, with the freshly minted ingress identity
+     *  last. The ordering is load-bearing — an operator who got a reserved key
+     *  past the API boundary would otherwise hand themselves a forged identity,
+     *  and the identity is the daemon's decision, never theirs. */
+    runEnvFor(productName, specEnv, manifest) {
+        const identity = this.identityEnvFor?.(productName, manifest);
+        if (identity === undefined)
+            return specEnv;
+        return { ...specEnv, ...identity };
     }
     /** The address to record for a freshly started container: its own, when
      *  this daemon cannot dial the host loopback; otherwise nothing. */
@@ -213,6 +230,32 @@ export class ProductService {
                 warnings.push(...check.warnings);
             }
         }
+        // RFC 0003 D2b. A control plane can only be handed its own ingress
+        // identity once we know WHICH product it is, and the name comes from the
+        // manifest the container itself serves — so the first run is necessarily
+        // anonymous and the container is recreated with the identity here, after
+        // every refusal above and before anything is registered. An add that is
+        // going to be rejected therefore never mints, and never starts a second
+        // container. Dev products run no container of ours, so there is nowhere to
+        // inject the pair; they assert nothing.
+        if (containerId !== undefined && spec.kind === "container") {
+            const identity = this.identityEnvFor?.(manifest.name, manifest);
+            if (identity !== undefined) {
+                await this.containerOps.remove(containerId);
+                const placement = await this.containerOps.run(spec.image, { ...spec.env, ...identity });
+                containerId = placement.containerId;
+                port = placement.hostPort;
+                reachHost = await this.reachHostFor(containerId);
+                baseUrl = specBaseUrl(spec, port, reachHost);
+                try {
+                    await this.containerOps.waitForReady(baseUrl);
+                }
+                catch (e) {
+                    await this.containerOps.remove(containerId);
+                    throw e;
+                }
+            }
+        }
         // Now that the manifest name is known and unique, give the container a
         // stable, human-readable name (replacing docker's random alias). Tracked
         // by id, so a rename failure is harmless — hence best-effort.
@@ -224,7 +267,7 @@ export class ProductService {
         // because iframed product UIs need the built bundle to function.
         if (manifest.ui?.configScreenUrl) {
             try {
-                await probeConfigScreen(baseUrl, manifest.ui.configScreenUrl);
+                await probeConfigScreen(baseUrl, manifest.ui.configScreenUrl, this.probeHeadersFor?.(manifest.name) ?? {});
             }
             catch (e) {
                 if (containerId)
@@ -260,7 +303,7 @@ export class ProductService {
         if (manifest.defaultProductTemplates.length > 0 && this.importProductTemplateBytes) {
             for (const entry of manifest.defaultProductTemplates) {
                 try {
-                    const bytes = await fetchProductTemplateBytes(baseUrl, entry.url);
+                    const bytes = await fetchProductTemplateBytes(baseUrl, entry.url, this.probeHeadersFor?.(manifest.name) ?? {});
                     await this.importProductTemplateBytes({
                         name: entry.name,
                         bytes,
@@ -291,6 +334,11 @@ export class ProductService {
         if (target.containerId)
             await this.containerOps.remove(target.containerId);
         await this.store.update((products) => products.filter((p) => p.name !== name));
+        // RFC 0003 D2b. The container that held this product's ingress secret has
+        // gone; the store's copy would otherwise outlive it as a live credential
+        // 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);
         logger.info(`Product '${name}' removed`);
     }
     /** Bring a registration up to date with what its image now serves. For a
@@ -322,7 +370,7 @@ export class ProductService {
                     // Already gone (crashed / --rm reaped) — nothing to stop.
                 }
             }
-            const { containerId, hostPort } = await this.containerOps.run(target.spec.image, target.spec.env);
+            const { containerId, hostPort } = await this.containerOps.run(target.spec.image, this.runEnvFor(name, target.spec.env, target.manifest));
             const reachHost = await this.reachHostFor(containerId);
             await this.store.update((products) => products.map((p) => (p.name === name ? withPlacement(p, containerId, hostPort, reachHost) : p)));
             await this.containerOps.waitForReady(specBaseUrl(target.spec, hostPort, reachHost));
@@ -349,7 +397,7 @@ export class ProductService {
         if (this.refreshProductTemplateBytes) {
             for (const entry of manifest.defaultProductTemplates) {
                 try {
-                    const bytes = await fetchProductTemplateBytes(baseUrl, entry.url);
+                    const bytes = await fetchProductTemplateBytes(baseUrl, entry.url, this.probeHeadersFor?.(manifest.name) ?? {});
                     await this.refreshProductTemplateBytes({
                         name: entry.name,
                         bytes,
@@ -416,7 +464,7 @@ export class ProductService {
                 return;
             }
             try {
-                const { containerId, hostPort } = await this.containerOps.run(reg.spec.image, reg.spec.env);
+                const { containerId, hostPort } = await this.containerOps.run(reg.spec.image, this.runEnvFor(reg.name, reg.spec.env, reg.manifest));
                 const reachHost = await this.reachHostFor(containerId);
                 await this.containerOps.waitForReady(specBaseUrl(reg.spec, hostPort, reachHost));
                 await this.containerOps.rename(containerId, productContainerName(reg.name));
@@ -465,7 +513,7 @@ export class ProductService {
                 // Already gone (crashed / --rm reaped) — nothing to stop.
             }
         }
-        const { containerId, hostPort } = await this.containerOps.run(target.spec.image, target.spec.env);
+        const { containerId, hostPort } = await this.containerOps.run(target.spec.image, this.runEnvFor(name, target.spec.env, target.manifest));
         const reachHost = await this.reachHostFor(containerId);
         await this.store.update((products) => products.map((p) => (p.name === name ? withPlacement(p, containerId, hostPort, reachHost) : p)));
         await this.containerOps.waitForReady(specBaseUrl(target.spec, hostPort, reachHost));

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 {