@norskvideo/ctl-product-template-schema 0.1.59 → 0.1.61

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-product-template-schema",
-  "version": "0.1.59",
+  "version": "0.1.61",
   "type": "module",
   "repository": {
     "type": "git",
@@ -36,6 +36,10 @@
       "types": "./migration-socket.d.ts",
       "default": "./migration-socket.js"
     },
+    "./secret-references": {
+      "types": "./secret-references.d.ts",
+      "default": "./secret-references.js"
+    },
     "./product-channels": {
       "types": "./product-channels.d.ts",
       "default": "./product-channels.js"

package/secret-references.d.ts

@@ -0,0 +1,27 @@
+import { type Result } from "@norskvideo/ctl-foundation";
+export declare const SECRET_REFERENCE_PREFIX = "secretref:";
+/** The NodeInventory capability a worker advertises when it resolves secret
+ *  references, so placement can keep a job whose parameters hold one off an
+ *  older worker — which would hand the container the reference itself. */
+export declare const SECRET_REFERENCES_CAPABILITY = "norsk.io/secret-references";
+/** What a secret parameter's literal value is shown as wherever ctl prints
+ *  launch parameters back. */
+export declare const SECRET_PLACEHOLDER = "<secret>";
+export interface SecretReference {
+    provider: string;
+    key: string;
+}
+/** A value is a reference exactly when it carries the prefix. A malformed
+ *  reference is still a reference: it fails resolution rather than reaching a
+ *  container as a literal. */
+export declare function isSecretReference(value: string): boolean;
+export declare function parseSecretReference(value: string): Result<SecretReference, string>;
+export declare function secretReference(provider: string, key: string): string;
+/** Launch parameters as they may be shown: a parameter the template declares
+ *  `secret` has its literal value masked. A reference is shown as it is — it
+ *  is the point of a reference that it reveals nothing — and an empty value
+ *  stays visibly empty. */
+export declare function redactSecretParams(params: Record<string, string>, declared: readonly {
+    name: string;
+    secret?: boolean;
+}[]): Record<string, string>;

package/secret-references.js

@@ -0,0 +1,56 @@
+// Secret references: a launch parameter's value may name a secret instead of
+// carrying it, as `secretref:<provider>:<key>`. The worker that runs the
+// instance resolves the reference immediately before it writes the
+// container's environment, so a scheduler, its job store, its templates and
+// its backups only ever hold the reference (norsk-ctl ADR-0017).
+//
+// Shared by both ends: whoever builds launch parameters (a Manager front end,
+// a script) and the worker that resolves them. The provider names a resolver
+// configured on the worker; the key is that provider's business and may hold
+// colons, slashes or ciphertext.
+import { err, ok } from "@norskvideo/ctl-foundation";
+export const SECRET_REFERENCE_PREFIX = "secretref:";
+/** The NodeInventory capability a worker advertises when it resolves secret
+ *  references, so placement can keep a job whose parameters hold one off an
+ *  older worker — which would hand the container the reference itself. */
+export const SECRET_REFERENCES_CAPABILITY = "norsk.io/secret-references";
+/** What a secret parameter's literal value is shown as wherever ctl prints
+ *  launch parameters back. */
+export const SECRET_PLACEHOLDER = "<secret>";
+const PROVIDER_NAME = /^[a-z][a-z0-9-]*$/;
+/** A value is a reference exactly when it carries the prefix. A malformed
+ *  reference is still a reference: it fails resolution rather than reaching a
+ *  container as a literal. */
+export function isSecretReference(value) {
+    return value.startsWith(SECRET_REFERENCE_PREFIX);
+}
+export function parseSecretReference(value) {
+    if (!isSecretReference(value))
+        return err("not a secret reference");
+    const rest = value.slice(SECRET_REFERENCE_PREFIX.length);
+    const colon = rest.indexOf(":");
+    if (colon < 0)
+        return err(`a secret reference is ${SECRET_REFERENCE_PREFIX}<provider>:<key>`);
+    const provider = rest.slice(0, colon);
+    const key = rest.slice(colon + 1);
+    if (!PROVIDER_NAME.test(provider)) {
+        return err(`secret provider name '${provider}' must be lowercase letters, digits and dashes`);
+    }
+    if (key === "")
+        return err(`the secret reference for provider '${provider}' names no key`);
+    return ok({ provider, key });
+}
+export function secretReference(provider, key) {
+    return `${SECRET_REFERENCE_PREFIX}${provider}:${key}`;
+}
+/** Launch parameters as they may be shown: a parameter the template declares
+ *  `secret` has its literal value masked. A reference is shown as it is — it
+ *  is the point of a reference that it reveals nothing — and an empty value
+ *  stays visibly empty. */
+export function redactSecretParams(params, declared) {
+    const secret = new Set(declared.filter((p) => p.secret === true).map((p) => p.name));
+    return Object.fromEntries(Object.entries(params).map(([k, v]) => [
+        k,
+        secret.has(k) && v !== "" && !isSecretReference(v) ? SECRET_PLACEHOLDER : v,
+    ]));
+}