@norskvideo/ctl-sdk 0.1.37 → 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";

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";

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/package.json

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

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 {