@norskvideo/ctl-product-template-schema 0.1.85 → 0.1.87

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@norskvideo/ctl-product-template-schema",
3
- "version": "0.1.85",
3
+ "version": "0.1.87",
4
4
  "type": "module",
5
5
  "repository": {
6
6
  "type": "git",
@@ -12,6 +12,7 @@ export { fileSecretProvider } from "./providers/file.js";
12
12
  export { DEFAULT_K8S_SECRETS_ROOT, k8sSecretProvider } from "./providers/k8s.js";
13
13
  export { localResolver, type ResolveContext, resolveSecretReferences, type SecretResolver } from "./resolver.js";
14
14
  export { Secret } from "./secret.js";
15
+ export { autoKeyFile, escrowedKids, escrowMarker, generateKeyLine, isSealed, type Keyring, keyIdOf, type LoadKeyringOptions, loadKeyring, type OpenedVault, type OpenVaultOptions, openSealed, openVault, parseKeyring, recordEscrow, rewrapSealed, SEALED_PREFIX, type SealedFor, seal, sealedKeyId, VAULT_DIR, type VaultKey, type VaultState, writeNewKeyring, } from "./vault.js";
15
16
  export * from "./wire.js";
16
17
  export declare const SECRET_PROVIDERS_ENV = "NORSK_SECRET_PROVIDERS";
17
18
  /** In local mode, a profile in use (NORSK_SECRETS_PROFILE) is announced once
package/secrets/index.js CHANGED
@@ -21,6 +21,7 @@ export { fileSecretProvider } from "./providers/file.js";
21
21
  export { DEFAULT_K8S_SECRETS_ROOT, k8sSecretProvider } from "./providers/k8s.js";
22
22
  export { localResolver, resolveSecretReferences } from "./resolver.js";
23
23
  export { Secret } from "./secret.js";
24
+ export { autoKeyFile, escrowedKids, escrowMarker, generateKeyLine, isSealed, keyIdOf, loadKeyring, openSealed, openVault, parseKeyring, recordEscrow, rewrapSealed, SEALED_PREFIX, seal, sealedKeyId, VAULT_DIR, writeNewKeyring, } from "./vault.js";
24
25
  export * from "./wire.js";
25
26
  export const SECRET_PROVIDERS_ENV = "NORSK_SECRET_PROVIDERS";
26
27
  /** `norsk` secrets are held by norsk-ctl or norsk-mgr, so only ctl resolves them. */
@@ -0,0 +1,93 @@
1
+ import { type Result } from "@norskvideo/ctl-foundation";
2
+ export declare const SEALED_PREFIX = "nsenc:v1:";
3
+ export interface VaultKey {
4
+ kid: string;
5
+ key: Buffer;
6
+ }
7
+ /** `keys[0]` is `current`: it seals every new write. The rest only open. */
8
+ export interface Keyring {
9
+ current: VaultKey;
10
+ keys: VaultKey[];
11
+ }
12
+ /** The record a value belongs to: what its ciphertext is bound to. */
13
+ export interface SealedFor {
14
+ name: string;
15
+ version: number;
16
+ }
17
+ export declare function keyIdOf(key: Buffer): string;
18
+ /** One key per line (base64 or base64url of 32 bytes), first current; blank
19
+ * lines and `#` comments ignored. */
20
+ export declare function parseKeyring(text: string): Result<Keyring, string>;
21
+ /** A new key, as a keyring line. */
22
+ export declare function generateKeyLine(): string;
23
+ /** Where the keyring made when none is configured lives: under the store's
24
+ * (norsk-mgr) or state directory (norsk-ctl), in a private vault directory
25
+ * no backup takes. */
26
+ export declare const VAULT_DIR = "vault";
27
+ export declare function autoKeyFile(storeDir: string): string;
28
+ export declare function isSealed(text: string): boolean;
29
+ export declare function sealedKeyId(text: string): string | undefined;
30
+ export declare function seal(keyring: Keyring, value: string, at: SealedFor): string;
31
+ export declare function openSealed(keyring: Keyring, text: string, at: SealedFor): Result<string, string>;
32
+ /** The same value under the keyring's current key: the data key is unwrapped
33
+ * and wrapped again, and the value is opened only to prove the result does. */
34
+ export declare function rewrapSealed(keyring: Keyring, text: string, at: SealedFor): Result<string, string>;
35
+ export interface LoadKeyringOptions {
36
+ /** Resolves a `secretref:` source; the deployment's local providers by default. */
37
+ resolve?: (reference: string) => Promise<Result<string, string>>;
38
+ }
39
+ /** The keyring from `source`: an absolute path to an owner-only file, or a
40
+ * `secretref:` resolved through the deployment's providers (not `norsk:`,
41
+ * and not `file:`, which does not check a file's mode: name the file). */
42
+ export declare function loadKeyring(source: string, opts?: LoadKeyringOptions): Promise<Result<Keyring, string>>;
43
+ /** `secret keygen` (norsk-mgr's and norsk-ctl's): a new keyring file, or with `rotate` a new
44
+ * current key in front of an existing file's. Answers the kids, never a key.
45
+ * Written to a fresh temp file (never through one planted there), synced,
46
+ * then renamed over the keyring and the directory synced, so a crash leaves
47
+ * the old keyring or the new one, never an empty one. */
48
+ export declare function writeNewKeyring(path: string, opts: {
49
+ rotate: boolean;
50
+ }): Result<{
51
+ kids: string[];
52
+ }, string>;
53
+ /** The vault's master key: loaded, or why not. With none loaded nothing new
54
+ * can be sealed, and no sealed value opens. */
55
+ export type VaultState = {
56
+ status: "on";
57
+ keyring: Keyring;
58
+ } | {
59
+ status: "unavailable";
60
+ reason: string;
61
+ };
62
+ export interface OpenVaultOptions {
63
+ /** The configured keyring: an owner-only file's absolute path or a
64
+ * `secretref:`. Undefined: the generated one at `autoKeyFile`. */
65
+ source: string | undefined;
66
+ /** Where a generated keyring lives (`autoKeyFile(<dir>)`). */
67
+ autoKeyFile: string;
68
+ /** Whether one may be generated there when none exists (not on a member
69
+ * of a cluster, whose members must share one). */
70
+ generate: boolean;
71
+ /** Why none may be generated, when `generate` is false. */
72
+ refusal?: string;
73
+ keyring?: LoadKeyringOptions;
74
+ }
75
+ export interface OpenedVault {
76
+ state: VaultState;
77
+ /** Set when the keyring is the generated one: the operator must keep a copy. */
78
+ autoKey?: string;
79
+ /** The current key's id when one was generated just now. */
80
+ generatedKid?: string;
81
+ }
82
+ /** The master key, by the one rule norsk-mgr and norsk-ctl share: the
83
+ * configured keyring, else the generated one (made on the first start
84
+ * without one). A configured key that does not load leaves the vault
85
+ * unavailable; it never falls back to a generated one. */
86
+ export declare function openVault(opts: OpenVaultOptions): Promise<OpenedVault>;
87
+ /** Beside a generated keyring: the key ids the operator has said are kept
88
+ * off the host. */
89
+ export declare const escrowMarker: (keyFile: string) => string;
90
+ export declare function escrowedKids(keyFile: string): string[];
91
+ /** Record that the generated keyring's current key is kept elsewhere.
92
+ * Answers whether it was newly recorded. */
93
+ export declare function recordEscrow(keyFile: string, kid: string): boolean;
@@ -0,0 +1,334 @@
1
+ // The secrets vault (norsk-ctl RFC 0013 §3), norsk-mgr's and a standalone
2
+ // norsk-ctl's alike: a `norsk` secret's value at rest, sealed with AES-256-GCM
3
+ // under a data key of its own, which is wrapped by a master key that is never
4
+ // in the store or a backup.
5
+ //
6
+ // nsenc:v1:<kid>:<wrapNonce>:<wrappedKey>:<nonce>:<ciphertext> (base64url)
7
+ //
8
+ // The data key's wrap is bound to its kid, and the value to its record's name
9
+ // and version, so a sealed value moved to another record does not open.
10
+ // Re-wrapping under a new master key changes only the wrapped data key.
11
+ // Nothing here logs, and no error carries a key, a value or an envelope.
12
+ import { createCipheriv, createDecipheriv, createHmac, randomBytes } from "node:crypto";
13
+ import { chmodSync, closeSync, constants, existsSync, fstatSync, fsyncSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeSync, } from "node:fs";
14
+ import { dirname, isAbsolute, join } from "node:path";
15
+ import { err, ok, tryResult } from "@norskvideo/ctl-foundation";
16
+ import { isSecretReference, parseSecretReference } from "../secret-references.js";
17
+ import { createResolverFromEnv } from "./index.js";
18
+ import { SECRETS_TOKEN_ENV, SECRETS_URL_ENV } from "./wire.js";
19
+ export const SEALED_PREFIX = "nsenc:v1:";
20
+ const KEY_BYTES = 32;
21
+ const NONCE_BYTES = 12;
22
+ const TAG_BYTES = 16;
23
+ const KID_INFO = "norsk-mgr secrets vault key id";
24
+ export function keyIdOf(key) {
25
+ return createHmac("sha256", key).update(KID_INFO).digest().subarray(0, 9).toString("base64url");
26
+ }
27
+ const BASE64ISH = /^[A-Za-z0-9+/_-]+={0,2}$/;
28
+ /** One key per line (base64 or base64url of 32 bytes), first current; blank
29
+ * lines and `#` comments ignored. */
30
+ export function parseKeyring(text) {
31
+ const keys = [];
32
+ const lines = text
33
+ .split(/\r?\n/)
34
+ .map((l) => l.trim())
35
+ .filter((l) => l !== "" && !l.startsWith("#"));
36
+ for (const [i, line] of lines.entries()) {
37
+ // Node's base64 decoder takes both alphabets; the pattern stops it
38
+ // skipping characters that are neither.
39
+ const key = BASE64ISH.test(line) ? Buffer.from(line, "base64") : undefined;
40
+ if (!key || key.length !== KEY_BYTES)
41
+ return err(`keyring line ${i + 1} is not a 32-byte key in base64`);
42
+ const kid = keyIdOf(key);
43
+ if (keys.some((k) => k.kid === kid))
44
+ return err(`keyring line ${i + 1} repeats key ${kid}`);
45
+ keys.push({ kid, key });
46
+ }
47
+ const [current] = keys;
48
+ if (!current)
49
+ return err("the keyring holds no key");
50
+ return ok({ current, keys });
51
+ }
52
+ /** A new key, as a keyring line. */
53
+ export function generateKeyLine() {
54
+ return randomBytes(KEY_BYTES).toString("base64url");
55
+ }
56
+ /** Where the keyring made when none is configured lives: under the store's
57
+ * (norsk-mgr) or state directory (norsk-ctl), in a private vault directory
58
+ * no backup takes. */
59
+ export const VAULT_DIR = "vault";
60
+ export function autoKeyFile(storeDir) {
61
+ return join(storeDir, VAULT_DIR, "secrets-master.key");
62
+ }
63
+ export function isSealed(text) {
64
+ return text.startsWith(SEALED_PREFIX);
65
+ }
66
+ export function sealedKeyId(text) {
67
+ return isSealed(text) ? text.slice(SEALED_PREFIX.length).split(":")[0] || undefined : undefined;
68
+ }
69
+ const b64 = (b) => b.toString("base64url");
70
+ function gcmSeal(key, plain, aad) {
71
+ const nonce = randomBytes(NONCE_BYTES);
72
+ const cipher = createCipheriv("aes-256-gcm", key, nonce);
73
+ cipher.setAAD(Buffer.from(aad, "utf-8"));
74
+ return { nonce, body: Buffer.concat([cipher.update(plain), cipher.final(), cipher.getAuthTag()]) };
75
+ }
76
+ function gcmOpen(key, nonce, body, aad) {
77
+ return tryResult(() => {
78
+ const decipher = createDecipheriv("aes-256-gcm", key, nonce);
79
+ decipher.setAAD(Buffer.from(aad, "utf-8"));
80
+ decipher.setAuthTag(body.subarray(body.length - TAG_BYTES));
81
+ return Buffer.concat([decipher.update(body.subarray(0, body.length - TAG_BYTES)), decipher.final()]);
82
+ }, () => "sealed value does not open (wrong key, or damaged)");
83
+ }
84
+ const wrapAad = (kid) => `${SEALED_PREFIX}${kid}`;
85
+ const valueAad = (at) => `nsenc:v1|${at.name}|${at.version}`;
86
+ function parse(text) {
87
+ if (!isSealed(text))
88
+ return err("not a sealed value");
89
+ const parts = text.slice(SEALED_PREFIX.length).split(":");
90
+ if (parts.length !== 5 || parts.some((p) => p === "" || !/^[A-Za-z0-9_-]+$/.test(p))) {
91
+ return err("malformed sealed value");
92
+ }
93
+ const [kid, wrapNonce, wrappedKey, nonce, ciphertext] = parts;
94
+ const parsed = {
95
+ kid,
96
+ wrapNonce: Buffer.from(wrapNonce, "base64url"),
97
+ wrappedKey: Buffer.from(wrappedKey, "base64url"),
98
+ nonce,
99
+ ciphertext,
100
+ };
101
+ if (parsed.wrapNonce.length !== NONCE_BYTES ||
102
+ parsed.wrappedKey.length !== KEY_BYTES + TAG_BYTES ||
103
+ Buffer.from(nonce, "base64url").length !== NONCE_BYTES ||
104
+ Buffer.from(ciphertext, "base64url").length < TAG_BYTES) {
105
+ return err("malformed sealed value");
106
+ }
107
+ return ok(parsed);
108
+ }
109
+ function unwrapDataKey(keyring, p) {
110
+ const master = keyring.keys.find((k) => k.kid === p.kid);
111
+ if (!master)
112
+ return err(`sealed under key ${p.kid}, which the keyring does not hold`);
113
+ return gcmOpen(master.key, p.wrapNonce, p.wrappedKey, wrapAad(p.kid));
114
+ }
115
+ function wrapDataKey(keyring, dataKey) {
116
+ const { kid, key } = keyring.current;
117
+ const wrapped = gcmSeal(key, dataKey, wrapAad(kid));
118
+ return `${SEALED_PREFIX}${kid}:${b64(wrapped.nonce)}:${b64(wrapped.body)}`;
119
+ }
120
+ export function seal(keyring, value, at) {
121
+ const dataKey = randomBytes(KEY_BYTES);
122
+ try {
123
+ const sealed = gcmSeal(dataKey, Buffer.from(value, "utf-8"), valueAad(at));
124
+ return `${wrapDataKey(keyring, dataKey)}:${b64(sealed.nonce)}:${b64(sealed.body)}`;
125
+ }
126
+ finally {
127
+ dataKey.fill(0);
128
+ }
129
+ }
130
+ export function openSealed(keyring, text, at) {
131
+ const p = parse(text);
132
+ if (p.status === "error")
133
+ return p;
134
+ const dataKey = unwrapDataKey(keyring, p.value);
135
+ if (dataKey.status === "error")
136
+ return dataKey;
137
+ try {
138
+ const plain = gcmOpen(dataKey.value, Buffer.from(p.value.nonce, "base64url"), Buffer.from(p.value.ciphertext, "base64url"), valueAad(at));
139
+ return plain.status === "ok" ? ok(plain.value.toString("utf-8")) : plain;
140
+ }
141
+ finally {
142
+ dataKey.value.fill(0);
143
+ }
144
+ }
145
+ /** The same value under the keyring's current key: the data key is unwrapped
146
+ * and wrapped again, and the value is opened only to prove the result does. */
147
+ export function rewrapSealed(keyring, text, at) {
148
+ const opened = openSealed(keyring, text, at);
149
+ if (opened.status === "error")
150
+ return opened;
151
+ const p = parse(text);
152
+ if (p.status === "error")
153
+ return p;
154
+ const dataKey = unwrapDataKey(keyring, p.value);
155
+ if (dataKey.status === "error")
156
+ return dataKey;
157
+ try {
158
+ return ok(`${wrapDataKey(keyring, dataKey.value)}:${p.value.nonce}:${p.value.ciphertext}`);
159
+ }
160
+ finally {
161
+ dataKey.value.fill(0);
162
+ }
163
+ }
164
+ async function resolveWithLocalProviders(reference) {
165
+ // Always local: the master key is never fetched from a norsk-ctl.
166
+ const env = { ...process.env, [SECRETS_URL_ENV]: undefined, [SECRETS_TOKEN_ENV]: undefined };
167
+ const resolved = await createResolverFromEnv(env).resolve({ secretsMasterKeyFile: reference }, { purpose: "secrets master key" });
168
+ if (resolved.status === "error")
169
+ return err(resolved.error.message);
170
+ const value = resolved.value.secretsMasterKeyFile;
171
+ return value === undefined ? err("no value") : ok(value.reveal());
172
+ }
173
+ /** The keyring from `source`: an absolute path to an owner-only file, or a
174
+ * `secretref:` resolved through the deployment's providers (not `norsk:`,
175
+ * and not `file:`, which does not check a file's mode: name the file). */
176
+ export async function loadKeyring(source, opts = {}) {
177
+ if (isSecretReference(source)) {
178
+ const ref = parseSecretReference(source);
179
+ if (ref.status === "error")
180
+ return err(`the secrets master key reference is malformed: ${ref.error}`);
181
+ if (ref.value.provider === "norsk")
182
+ return err("the secrets master key cannot be a norsk: secret");
183
+ if (ref.value.provider === "file") {
184
+ return err("the secrets master key cannot be a file: reference; give the key file's path, so its mode is checked");
185
+ }
186
+ const resolved = await (opts.resolve ?? resolveWithLocalProviders)(source);
187
+ if (resolved.status === "error")
188
+ return err(`the secrets master key could not be resolved: ${resolved.error}`);
189
+ return parseKeyring(resolved.value);
190
+ }
191
+ if (!isAbsolute(source))
192
+ return err(`the secrets master key file must be an absolute path, not '${source}'`);
193
+ const text = readOwnerOnly(source);
194
+ return text.status === "ok" ? parseKeyring(text.value) : text;
195
+ }
196
+ /** The file's text, checked on the descriptor it is read from (no window
197
+ * between the check and the read), and never through a symlink. */
198
+ function readOwnerOnly(path) {
199
+ let fd;
200
+ try {
201
+ fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
202
+ }
203
+ catch (e) {
204
+ const code = e.code;
205
+ if (code === "ENOENT")
206
+ return err(`the secrets master key file ${path} does not exist`);
207
+ if (code === "ELOOP")
208
+ return err(`the secrets master key file ${path} is a symlink; name the file itself`);
209
+ return err(`the secrets master key file ${path} cannot be opened (${code ?? "error"})`);
210
+ }
211
+ try {
212
+ const st = fstatSync(fd);
213
+ if (!st.isFile())
214
+ return err(`the secrets master key file ${path} is not a regular file`);
215
+ if ((st.mode & 0o077) !== 0) {
216
+ return err(`the secrets master key file ${path} can be read by others (mode ${(st.mode & 0o777).toString(8)}); make it 0600`);
217
+ }
218
+ if (typeof process.getuid === "function" && st.uid !== process.getuid()) {
219
+ return err(`the secrets master key file ${path} is not owned by this user`);
220
+ }
221
+ return ok(readFileSync(fd, "utf-8"));
222
+ }
223
+ finally {
224
+ closeSync(fd);
225
+ }
226
+ }
227
+ /** `secret keygen` (norsk-mgr's and norsk-ctl's): a new keyring file, or with `rotate` a new
228
+ * current key in front of an existing file's. Answers the kids, never a key.
229
+ * Written to a fresh temp file (never through one planted there), synced,
230
+ * then renamed over the keyring and the directory synced, so a crash leaves
231
+ * the old keyring or the new one, never an empty one. */
232
+ export function writeNewKeyring(path, opts) {
233
+ if (!isAbsolute(path))
234
+ return err(`give the key file as an absolute path, not '${path}'`);
235
+ let existing = "";
236
+ if (existsSync(path)) {
237
+ if (!opts.rotate)
238
+ return err(`${path} exists; pass --rotate to add a new current key to it`);
239
+ const read = readOwnerOnly(path);
240
+ if (read.status === "error")
241
+ return read;
242
+ existing = read.value;
243
+ const old = parseKeyring(existing);
244
+ if (old.status === "error")
245
+ return old;
246
+ }
247
+ else if (opts.rotate) {
248
+ return err(`${path} does not exist; leave out --rotate to create it`);
249
+ }
250
+ const text = `${generateKeyLine()}\n${existing}`;
251
+ const parsed = parseKeyring(text);
252
+ if (parsed.status === "error")
253
+ return parsed;
254
+ const dir = dirname(path);
255
+ mkdirSync(dir, { recursive: true, mode: 0o700 });
256
+ chmodSync(dir, 0o700);
257
+ const tmp = `${path}.tmp`;
258
+ rmSync(tmp, { force: true }); // a stale or planted one; a symlink is removed, not followed
259
+ const fd = openSync(tmp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
260
+ try {
261
+ writeSync(fd, text);
262
+ fsyncSync(fd);
263
+ }
264
+ finally {
265
+ closeSync(fd);
266
+ }
267
+ renameSync(tmp, path);
268
+ const dirFd = openSync(dir, constants.O_RDONLY);
269
+ try {
270
+ fsyncSync(dirFd);
271
+ }
272
+ finally {
273
+ closeSync(dirFd);
274
+ }
275
+ return ok({ kids: parsed.value.keys.map((k) => k.kid) });
276
+ }
277
+ /** The master key, by the one rule norsk-mgr and norsk-ctl share: the
278
+ * configured keyring, else the generated one (made on the first start
279
+ * without one). A configured key that does not load leaves the vault
280
+ * unavailable; it never falls back to a generated one. */
281
+ export async function openVault(opts) {
282
+ if (opts.source !== undefined) {
283
+ const loaded = await loadKeyring(opts.source, opts.keyring ?? {});
284
+ return {
285
+ state: loaded.status === "ok"
286
+ ? { status: "on", keyring: loaded.value }
287
+ : { status: "unavailable", reason: loaded.error },
288
+ };
289
+ }
290
+ let generatedKid;
291
+ if (!existsSync(opts.autoKeyFile)) {
292
+ if (!opts.generate)
293
+ return { state: { status: "unavailable", reason: opts.refusal ?? "no secrets master key" } };
294
+ const made = writeNewKeyring(opts.autoKeyFile, { rotate: false });
295
+ if (made.status === "error")
296
+ return { state: { status: "unavailable", reason: made.error } };
297
+ generatedKid = made.value.kids[0];
298
+ }
299
+ const loaded = await loadKeyring(opts.autoKeyFile);
300
+ if (loaded.status === "error")
301
+ return { state: { status: "unavailable", reason: loaded.error } };
302
+ return {
303
+ state: { status: "on", keyring: loaded.value },
304
+ autoKey: opts.autoKeyFile,
305
+ ...(generatedKid ? { generatedKid } : {}),
306
+ };
307
+ }
308
+ /** Beside a generated keyring: the key ids the operator has said are kept
309
+ * off the host. */
310
+ export const escrowMarker = (keyFile) => join(dirname(keyFile), "escrowed");
311
+ export function escrowedKids(keyFile) {
312
+ const marker = escrowMarker(keyFile);
313
+ return existsSync(marker) ? readFileSync(marker, "utf-8").split("\n").filter(Boolean) : [];
314
+ }
315
+ /** Record that the generated keyring's current key is kept elsewhere.
316
+ * Answers whether it was newly recorded. */
317
+ export function recordEscrow(keyFile, kid) {
318
+ const kids = escrowedKids(keyFile);
319
+ if (kids.includes(kid))
320
+ return false;
321
+ const marker = escrowMarker(keyFile);
322
+ const tmp = `${marker}.tmp`;
323
+ rmSync(tmp, { force: true });
324
+ const fd = openSync(tmp, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
325
+ try {
326
+ writeSync(fd, `${[...kids, kid].join("\n")}\n`);
327
+ fsyncSync(fd);
328
+ }
329
+ finally {
330
+ closeSync(fd);
331
+ }
332
+ renameSync(tmp, marker);
333
+ return true;
334
+ }