@mondaydotcomorg/z2h-shared-utils 0.4.3 → 0.5.0

package/dist/esm/index.d.ts

@@ -1,2 +1,2 @@
-export {};
+export * from './secrets';
 //# sourceMappingURL=index.d.ts.map

package/dist/esm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC"}

package/dist/esm/index.mjs

@@ -1 +1 @@
-
+export { decryptSecret, encryptSecret } from './secrets/secret-cipher.mjs';

package/dist/esm/secrets/__tests__/secret-cipher.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=secret-cipher.test.d.ts.map

package/dist/esm/secrets/__tests__/secret-cipher.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-cipher.test.d.ts","sourceRoot":"","sources":["../../../../src/secrets/__tests__/secret-cipher.test.ts"],"names":[],"mappings":""}

package/dist/esm/secrets/index.d.ts

@@ -0,0 +1,2 @@
+export * from './secret-cipher';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/secrets/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/secrets/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC"}

package/dist/esm/secrets/index.mjs

@@ -0,0 +1 @@
+export { decryptSecret, encryptSecret } from './secret-cipher.mjs';

package/dist/esm/secrets/secret-cipher.d.ts

@@ -0,0 +1,3 @@
+export declare function encryptSecret(plaintext: string): string;
+export declare function decryptSecret(blob: string): string;
+//# sourceMappingURL=secret-cipher.d.ts.map

package/dist/esm/secrets/secret-cipher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-cipher.d.ts","sourceRoot":"","sources":["../../../src/secrets/secret-cipher.ts"],"names":[],"mappings":"AAqEA,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAavD;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAmBlD"}

package/dist/esm/secrets/secret-cipher.mjs

@@ -0,0 +1,99 @@
+import { randomBytes, createCipheriv, createDecipheriv, createHash, scryptSync } from 'node:crypto';
+import { Api } from '@mondaydotcomorg/trident-backend-api';
+
+/**
+ * Symmetric encryption for secrets at rest. AES-256-GCM with a key derived
+ * (via scrypt, salted per blob) from the `z2h_secrets_key` secret. The `v1:`
+ * prefix leaves room to rotate the scheme without breaking stored blobs.
+ * Decryption happens server-side only, and a decrypted value never crosses
+ * into an isolate.
+ *
+ * Shared between `bigbrain-zth` (encrypts on write) and `zth-backend-runner`
+ * (decrypts on use) — both must read the *same* `z2h_secrets_key` value, so
+ * this must stay byte-identical across the two callers.
+ */
+/** Config-variables key (how mm + the cluster inject it), stored as {"key":"…"}. */
+const KEY_CONFIG = 'z2h_secrets_key';
+const CURRENT_VERSION = 'v1';
+const SALT_LENGTH = 16;
+const SCRYPT_KEY_LENGTH = 32;
+/** Full-length GCM tag. Enforced on decrypt so a truncated tag can't weaken the
+ * forgery margin (a short tag shrinks it from 2^128 toward 2^32). */
+const GCM_TAG_LENGTH = 16;
+/** Bounds the derived-key cache below — one entry per distinct (passphrase,
+ * salt) pair ever seen, so a long-lived process can't grow this unbounded. */
+const MAX_CACHED_KEYS = 256;
+/**
+ * The passphrase from the trident `configurationVariables` secret, a
+ * `{ key: "…" }` object.
+ */
+function passphraseSource() {
+    const cfg = Api.getPart('configurationVariables')?.get(KEY_CONFIG);
+    return cfg?.key || undefined;
+}
+function passphrase() {
+    const configured = passphraseSource();
+    if (!configured) {
+        throw new Error(`${KEY_CONFIG} must be set`);
+    }
+    return configured;
+}
+// Each blob carries its own random salt (see encryptSecret), so the key derived
+// for it is cached by (passphrase, salt) rather than by passphrase alone — a
+// repeated read of the same still-live blob skips re-running scrypt.
+const derivedKeyCache = new Map();
+function deriveKey(source, salt) {
+    // Hash the passphrase for the cache key so the plaintext secret isn't held
+    // in memory for the cache's lifetime (rather than just for this call).
+    const sourceDigest = createHash('sha256').update(source).digest('base64');
+    const cacheKey = `${sourceDigest}:${salt.toString('base64')}`;
+    const cached = derivedKeyCache.get(cacheKey);
+    if (cached) {
+        return cached;
+    }
+    const derived = scryptSync(source, salt, SCRYPT_KEY_LENGTH);
+    if (derivedKeyCache.size >= MAX_CACHED_KEYS) {
+        const oldest = derivedKeyCache.keys().next().value;
+        if (oldest !== undefined) {
+            derivedKeyCache.delete(oldest);
+        }
+    }
+    derivedKeyCache.set(cacheKey, derived);
+    return derived;
+}
+function encryptSecret(plaintext) {
+    const salt = randomBytes(SALT_LENGTH);
+    const iv = randomBytes(12);
+    const cipher = createCipheriv('aes-256-gcm', deriveKey(passphrase(), salt), iv);
+    const enc = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return [
+        CURRENT_VERSION,
+        iv.toString('base64'),
+        salt.toString('base64'),
+        tag.toString('base64'),
+        enc.toString('base64'),
+    ].join(':');
+}
+function decryptSecret(blob) {
+    const parts = blob.split(':');
+    if (parts.length !== 5) {
+        throw new Error('unrecognized secret format');
+    }
+    const [version, ivB64, saltB64, tagB64, dataB64] = parts;
+    if (version !== CURRENT_VERSION || !ivB64 || !saltB64 || !tagB64 || dataB64 === undefined) {
+        throw new Error('unrecognized secret format');
+    }
+    const tag = Buffer.from(tagB64, 'base64');
+    if (tag.length !== GCM_TAG_LENGTH) {
+        throw new Error('unrecognized secret format');
+    }
+    const key = deriveKey(passphrase(), Buffer.from(saltB64, 'base64'));
+    const decipher = createDecipheriv('aes-256-gcm', key, Buffer.from(ivB64, 'base64'), {
+        authTagLength: GCM_TAG_LENGTH,
+    });
+    decipher.setAuthTag(tag);
+    return Buffer.concat([decipher.update(Buffer.from(dataB64, 'base64')), decipher.final()]).toString('utf8');
+}
+
+export { decryptSecret, encryptSecret };

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export {};
+export * from './secrets';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC"}

package/dist/index.js

@@ -1 +1,8 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 
+const secrets_secretCipher = require('./secrets/secret-cipher.js');
+
+
+
+exports.decryptSecret = secrets_secretCipher.decryptSecret;
+exports.encryptSecret = secrets_secretCipher.encryptSecret;

package/dist/secrets/__tests__/secret-cipher.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=secret-cipher.test.d.ts.map

package/dist/secrets/__tests__/secret-cipher.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-cipher.test.d.ts","sourceRoot":"","sources":["../../../src/secrets/__tests__/secret-cipher.test.ts"],"names":[],"mappings":""}

package/dist/secrets/index.d.ts

@@ -0,0 +1,2 @@
+export * from './secret-cipher';
+//# sourceMappingURL=index.d.ts.map

package/dist/secrets/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/secrets/index.ts"],"names":[],"mappings":"AAAA,cAAc,iBAAiB,CAAC"}

package/dist/secrets/index.js

@@ -0,0 +1,8 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const secrets_secretCipher = require('./secret-cipher.js');
+
+
+
+exports.decryptSecret = secrets_secretCipher.decryptSecret;
+exports.encryptSecret = secrets_secretCipher.encryptSecret;

package/dist/secrets/secret-cipher.d.ts

@@ -0,0 +1,3 @@
+export declare function encryptSecret(plaintext: string): string;
+export declare function decryptSecret(blob: string): string;
+//# sourceMappingURL=secret-cipher.d.ts.map

package/dist/secrets/secret-cipher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-cipher.d.ts","sourceRoot":"","sources":["../../src/secrets/secret-cipher.ts"],"names":[],"mappings":"AAqEA,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAavD;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAmBlD"}

package/dist/secrets/secret-cipher.js

@@ -0,0 +1,102 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+const node_crypto = require('node:crypto');
+const tridentBackendApi = require('@mondaydotcomorg/trident-backend-api');
+
+/**
+ * Symmetric encryption for secrets at rest. AES-256-GCM with a key derived
+ * (via scrypt, salted per blob) from the `z2h_secrets_key` secret. The `v1:`
+ * prefix leaves room to rotate the scheme without breaking stored blobs.
+ * Decryption happens server-side only, and a decrypted value never crosses
+ * into an isolate.
+ *
+ * Shared between `bigbrain-zth` (encrypts on write) and `zth-backend-runner`
+ * (decrypts on use) — both must read the *same* `z2h_secrets_key` value, so
+ * this must stay byte-identical across the two callers.
+ */
+/** Config-variables key (how mm + the cluster inject it), stored as {"key":"…"}. */
+const KEY_CONFIG = 'z2h_secrets_key';
+const CURRENT_VERSION = 'v1';
+const SALT_LENGTH = 16;
+const SCRYPT_KEY_LENGTH = 32;
+/** Full-length GCM tag. Enforced on decrypt so a truncated tag can't weaken the
+ * forgery margin (a short tag shrinks it from 2^128 toward 2^32). */
+const GCM_TAG_LENGTH = 16;
+/** Bounds the derived-key cache below — one entry per distinct (passphrase,
+ * salt) pair ever seen, so a long-lived process can't grow this unbounded. */
+const MAX_CACHED_KEYS = 256;
+/**
+ * The passphrase from the trident `configurationVariables` secret, a
+ * `{ key: "…" }` object.
+ */
+function passphraseSource() {
+    const cfg = tridentBackendApi.Api.getPart('configurationVariables')?.get(KEY_CONFIG);
+    return cfg?.key || undefined;
+}
+function passphrase() {
+    const configured = passphraseSource();
+    if (!configured) {
+        throw new Error(`${KEY_CONFIG} must be set`);
+    }
+    return configured;
+}
+// Each blob carries its own random salt (see encryptSecret), so the key derived
+// for it is cached by (passphrase, salt) rather than by passphrase alone — a
+// repeated read of the same still-live blob skips re-running scrypt.
+const derivedKeyCache = new Map();
+function deriveKey(source, salt) {
+    // Hash the passphrase for the cache key so the plaintext secret isn't held
+    // in memory for the cache's lifetime (rather than just for this call).
+    const sourceDigest = node_crypto.createHash('sha256').update(source).digest('base64');
+    const cacheKey = `${sourceDigest}:${salt.toString('base64')}`;
+    const cached = derivedKeyCache.get(cacheKey);
+    if (cached) {
+        return cached;
+    }
+    const derived = node_crypto.scryptSync(source, salt, SCRYPT_KEY_LENGTH);
+    if (derivedKeyCache.size >= MAX_CACHED_KEYS) {
+        const oldest = derivedKeyCache.keys().next().value;
+        if (oldest !== undefined) {
+            derivedKeyCache.delete(oldest);
+        }
+    }
+    derivedKeyCache.set(cacheKey, derived);
+    return derived;
+}
+function encryptSecret(plaintext) {
+    const salt = node_crypto.randomBytes(SALT_LENGTH);
+    const iv = node_crypto.randomBytes(12);
+    const cipher = node_crypto.createCipheriv('aes-256-gcm', deriveKey(passphrase(), salt), iv);
+    const enc = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return [
+        CURRENT_VERSION,
+        iv.toString('base64'),
+        salt.toString('base64'),
+        tag.toString('base64'),
+        enc.toString('base64'),
+    ].join(':');
+}
+function decryptSecret(blob) {
+    const parts = blob.split(':');
+    if (parts.length !== 5) {
+        throw new Error('unrecognized secret format');
+    }
+    const [version, ivB64, saltB64, tagB64, dataB64] = parts;
+    if (version !== CURRENT_VERSION || !ivB64 || !saltB64 || !tagB64 || dataB64 === undefined) {
+        throw new Error('unrecognized secret format');
+    }
+    const tag = Buffer.from(tagB64, 'base64');
+    if (tag.length !== GCM_TAG_LENGTH) {
+        throw new Error('unrecognized secret format');
+    }
+    const key = deriveKey(passphrase(), Buffer.from(saltB64, 'base64'));
+    const decipher = node_crypto.createDecipheriv('aes-256-gcm', key, Buffer.from(ivB64, 'base64'), {
+        authTagLength: GCM_TAG_LENGTH,
+    });
+    decipher.setAuthTag(tag);
+    return Buffer.concat([decipher.update(Buffer.from(dataB64, 'base64')), decipher.final()]).toString('utf8');
+}
+
+exports.decryptSecret = decryptSecret;
+exports.encryptSecret = encryptSecret;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mondaydotcomorg/z2h-shared-utils",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {

package/src/index.ts

@@ -1 +1 @@
-export {};
+export * from './secrets';

package/src/secrets/__tests__/secret-cipher.test.ts

@@ -0,0 +1,48 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { decryptSecret, encryptSecret } from '../secret-cipher';
+
+const getMock = vi.fn();
+
+vi.mock('@mondaydotcomorg/trident-backend-api', () => ({
+  Api: { getPart: vi.fn(() => ({ get: getMock })) },
+}));
+
+describe('secret-cipher', () => {
+  beforeEach(() => {
+    getMock.mockReset();
+    getMock.mockReturnValue({ key: 'test-secrets-key' });
+  });
+
+  it('round-trips a plaintext value', () => {
+    const blob = encryptSecret('super-secret-pat');
+    expect(decryptSecret(blob)).toBe('super-secret-pat');
+  });
+
+  it('produces a different blob (different iv/salt) for the same plaintext each time', () => {
+    const a = encryptSecret('same-value');
+    const b = encryptSecret('same-value');
+    expect(a).not.toBe(b);
+    expect(decryptSecret(a)).toBe('same-value');
+    expect(decryptSecret(b)).toBe('same-value');
+  });
+
+  it('rejects a tampered blob (flipped byte fails GCM auth)', () => {
+    const blob = encryptSecret('super-secret-pat');
+    const parts = blob.split(':');
+    const dataBuf = Buffer.from(parts[4], 'base64');
+    dataBuf[0] ^= 0xff;
+    parts[4] = dataBuf.toString('base64');
+    expect(() => decryptSecret(parts.join(':'))).toThrow();
+  });
+
+  it('rejects an unrecognized blob format', () => {
+    expect(() => decryptSecret('not-a-real-blob')).toThrow('unrecognized secret format');
+    expect(() => decryptSecret('v2:a:b:c:d')).toThrow('unrecognized secret format');
+  });
+
+  it('throws when the passphrase is not configured', () => {
+    getMock.mockReturnValue(undefined);
+    expect(() => encryptSecret('x')).toThrow('z2h_secrets_key must be set');
+  });
+});

package/src/secrets/index.ts

@@ -0,0 +1 @@
+export * from './secret-cipher';

package/src/secrets/secret-cipher.ts

@@ -0,0 +1,104 @@
+import { createCipheriv, createDecipheriv, createHash, randomBytes, scryptSync } from 'node:crypto';
+import { Api } from '@mondaydotcomorg/trident-backend-api';
+
+/**
+ * Symmetric encryption for secrets at rest. AES-256-GCM with a key derived
+ * (via scrypt, salted per blob) from the `z2h_secrets_key` secret. The `v1:`
+ * prefix leaves room to rotate the scheme without breaking stored blobs.
+ * Decryption happens server-side only, and a decrypted value never crosses
+ * into an isolate.
+ *
+ * Shared between `bigbrain-zth` (encrypts on write) and `zth-backend-runner`
+ * (decrypts on use) — both must read the *same* `z2h_secrets_key` value, so
+ * this must stay byte-identical across the two callers.
+ */
+
+/** Config-variables key (how mm + the cluster inject it), stored as {"key":"…"}. */
+const KEY_CONFIG = 'z2h_secrets_key';
+const CURRENT_VERSION = 'v1' as const;
+const SALT_LENGTH = 16;
+const SCRYPT_KEY_LENGTH = 32;
+/** Full-length GCM tag. Enforced on decrypt so a truncated tag can't weaken the
+ * forgery margin (a short tag shrinks it from 2^128 toward 2^32). */
+const GCM_TAG_LENGTH = 16;
+/** Bounds the derived-key cache below — one entry per distinct (passphrase,
+ * salt) pair ever seen, so a long-lived process can't grow this unbounded. */
+const MAX_CACHED_KEYS = 256;
+
+/**
+ * The passphrase from the trident `configurationVariables` secret, a
+ * `{ key: "…" }` object.
+ */
+function passphraseSource(): string | undefined {
+  const cfg = Api.getPart('configurationVariables')?.get(KEY_CONFIG) as { key?: string } | undefined;
+  return cfg?.key || undefined;
+}
+
+function passphrase(): string {
+  const configured = passphraseSource();
+  if (!configured) {
+    throw new Error(`${KEY_CONFIG} must be set`);
+  }
+  return configured;
+}
+
+// Each blob carries its own random salt (see encryptSecret), so the key derived
+// for it is cached by (passphrase, salt) rather than by passphrase alone — a
+// repeated read of the same still-live blob skips re-running scrypt.
+const derivedKeyCache = new Map<string, Buffer>();
+
+function deriveKey(source: string, salt: Buffer): Buffer {
+  // Hash the passphrase for the cache key so the plaintext secret isn't held
+  // in memory for the cache's lifetime (rather than just for this call).
+  const sourceDigest = createHash('sha256').update(source).digest('base64');
+  const cacheKey = `${sourceDigest}:${salt.toString('base64')}`;
+  const cached = derivedKeyCache.get(cacheKey);
+  if (cached) {
+    return cached;
+  }
+  const derived = scryptSync(source, salt, SCRYPT_KEY_LENGTH);
+  if (derivedKeyCache.size >= MAX_CACHED_KEYS) {
+    const oldest = derivedKeyCache.keys().next().value;
+    if (oldest !== undefined) {
+      derivedKeyCache.delete(oldest);
+    }
+  }
+  derivedKeyCache.set(cacheKey, derived);
+  return derived;
+}
+
+export function encryptSecret(plaintext: string): string {
+  const salt = randomBytes(SALT_LENGTH);
+  const iv = randomBytes(12);
+  const cipher = createCipheriv('aes-256-gcm', deriveKey(passphrase(), salt), iv);
+  const enc = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return [
+    CURRENT_VERSION,
+    iv.toString('base64'),
+    salt.toString('base64'),
+    tag.toString('base64'),
+    enc.toString('base64'),
+  ].join(':');
+}
+
+export function decryptSecret(blob: string): string {
+  const parts = blob.split(':');
+  if (parts.length !== 5) {
+    throw new Error('unrecognized secret format');
+  }
+  const [version, ivB64, saltB64, tagB64, dataB64] = parts;
+  if (version !== CURRENT_VERSION || !ivB64 || !saltB64 || !tagB64 || dataB64 === undefined) {
+    throw new Error('unrecognized secret format');
+  }
+  const tag = Buffer.from(tagB64, 'base64');
+  if (tag.length !== GCM_TAG_LENGTH) {
+    throw new Error('unrecognized secret format');
+  }
+  const key = deriveKey(passphrase(), Buffer.from(saltB64, 'base64'));
+  const decipher = createDecipheriv('aes-256-gcm', key, Buffer.from(ivB64, 'base64'), {
+    authTagLength: GCM_TAG_LENGTH,
+  });
+  decipher.setAuthTag(tag);
+  return Buffer.concat([decipher.update(Buffer.from(dataB64, 'base64')), decipher.final()]).toString('utf8');
+}