@mondaydotcomorg/z2h-shared-utils 0.4.3 → 0.6.0

package/dist/esm/index.d.ts

@@ -1,2 +1,3 @@
-export {};
+export { ALWAYS_ON_CHANNELS, DECLARED_INTEGRATIONS, type AlwaysOnChannel, type DeclaredIntegration, } from './integrations';
+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,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACrB,KAAK,eAAe,EACpB,KAAK,mBAAmB,GACzB,MAAM,gBAAgB,CAAC;AACxB,cAAc,WAAW,CAAC"}

package/dist/esm/index.mjs

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

package/dist/esm/integrations.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Backend channels surfaced as `ctx.api.v1.<name>`.
+ *
+ * Always-on channels need no OAuth and are never declared — the runner builds
+ * them for every app regardless of what its handlers touch.
+ */
+export declare const ALWAYS_ON_CHANNELS: readonly ["db", "llm", "snowflake"];
+export type AlwaysOnChannel = (typeof ALWAYS_ON_CHANNELS)[number];
+/**
+ * Declared (OAuth-gated) integrations: closed set the CLI detects from handler
+ * sources and the broker validates on register/update.
+ */
+export declare const DECLARED_INTEGRATIONS: readonly ["monday"];
+export type DeclaredIntegration = (typeof DECLARED_INTEGRATIONS)[number];
+//# sourceMappingURL=integrations.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"integrations.d.ts","sourceRoot":"","sources":["../../src/integrations.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,qCAAsC,CAAC;AACtE,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAElE;;;GAGG;AACH,eAAO,MAAM,qBAAqB,qBAAsB,CAAC;AACzD,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/dist/esm/integrations.mjs

@@ -0,0 +1,14 @@
+/**
+ * Backend channels surfaced as `ctx.api.v1.<name>`.
+ *
+ * Always-on channels need no OAuth and are never declared — the runner builds
+ * them for every app regardless of what its handlers touch.
+ */
+const ALWAYS_ON_CHANNELS = ['db', 'llm', 'snowflake'];
+/**
+ * Declared (OAuth-gated) integrations: closed set the CLI detects from handler
+ * sources and the broker validates on register/update.
+ */
+const DECLARED_INTEGRATIONS = ['monday'];
+
+export { ALWAYS_ON_CHANNELS, DECLARED_INTEGRATIONS };

package/dist/esm/observability/events.d.ts

@@ -72,5 +72,6 @@ export declare const Z2hAgentEvents: {
 /** BI events tracked in `z2h-cli`. */
 export declare const Z2hCliEvents: {
     readonly error: "z2h_cli_error";
+    readonly handlerParseError: "z2h_cli_handler_parse_error";
 };
 //# sourceMappingURL=events.d.ts.map

package/dist/esm/observability/events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../../src/observability/events.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiCtB,CAAC;AAEX,iEAAiE;AACjE,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;CAmBnB,CAAC;AAEX,oDAAoD;AACpD,eAAO,MAAM,cAAc;;;;;;;;CAQjB,CAAC;AAEX,sCAAsC;AACtC,eAAO,MAAM,YAAY;;CAEf,CAAC"}
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../../src/observability/events.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiCtB,CAAC;AAEX,iEAAiE;AACjE,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;CAmBnB,CAAC;AAEX,oDAAoD;AACpD,eAAO,MAAM,cAAc;;;;;;;;CAQjB,CAAC;AAEX,sCAAsC;AACtC,eAAO,MAAM,YAAY;;;CAGf,CAAC"}

package/dist/esm/observability/events.mjs

@@ -72,6 +72,7 @@ const Z2hAgentEvents = {
 /** BI events tracked in `z2h-cli`. */
 const Z2hCliEvents = {
     error: 'z2h_cli_error',
+    handlerParseError: 'z2h_cli_handler_parse_error',
 };
 
 export { BackendRunnerEvents, Z2hAgentEvents, Z2hCliEvents, Z2hServiceEvents };

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,3 @@
-export {};
+export { ALWAYS_ON_CHANNELS, DECLARED_INTEGRATIONS, type AlwaysOnChannel, type DeclaredIntegration, } from './integrations';
+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,OAAO,EACL,kBAAkB,EAClB,qBAAqB,EACrB,KAAK,eAAe,EACpB,KAAK,mBAAmB,GACzB,MAAM,gBAAgB,CAAC;AACxB,cAAc,WAAW,CAAC"}

package/dist/index.js

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

package/dist/integrations.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Backend channels surfaced as `ctx.api.v1.<name>`.
+ *
+ * Always-on channels need no OAuth and are never declared — the runner builds
+ * them for every app regardless of what its handlers touch.
+ */
+export declare const ALWAYS_ON_CHANNELS: readonly ["db", "llm", "snowflake"];
+export type AlwaysOnChannel = (typeof ALWAYS_ON_CHANNELS)[number];
+/**
+ * Declared (OAuth-gated) integrations: closed set the CLI detects from handler
+ * sources and the broker validates on register/update.
+ */
+export declare const DECLARED_INTEGRATIONS: readonly ["monday"];
+export type DeclaredIntegration = (typeof DECLARED_INTEGRATIONS)[number];
+//# sourceMappingURL=integrations.d.ts.map

package/dist/integrations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"integrations.d.ts","sourceRoot":"","sources":["../src/integrations.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,qCAAsC,CAAC;AACtE,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAElE;;;GAGG;AACH,eAAO,MAAM,qBAAqB,qBAAsB,CAAC;AACzD,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,qBAAqB,CAAC,CAAC,MAAM,CAAC,CAAC"}

package/dist/integrations.js

@@ -0,0 +1,17 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+/**
+ * Backend channels surfaced as `ctx.api.v1.<name>`.
+ *
+ * Always-on channels need no OAuth and are never declared — the runner builds
+ * them for every app regardless of what its handlers touch.
+ */
+const ALWAYS_ON_CHANNELS = ['db', 'llm', 'snowflake'];
+/**
+ * Declared (OAuth-gated) integrations: closed set the CLI detects from handler
+ * sources and the broker validates on register/update.
+ */
+const DECLARED_INTEGRATIONS = ['monday'];
+
+exports.ALWAYS_ON_CHANNELS = ALWAYS_ON_CHANNELS;
+exports.DECLARED_INTEGRATIONS = DECLARED_INTEGRATIONS;

package/dist/observability/events.d.ts

@@ -72,5 +72,6 @@ export declare const Z2hAgentEvents: {
 /** BI events tracked in `z2h-cli`. */
 export declare const Z2hCliEvents: {
     readonly error: "z2h_cli_error";
+    readonly handlerParseError: "z2h_cli_handler_parse_error";
 };
 //# sourceMappingURL=events.d.ts.map

package/dist/observability/events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/observability/events.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiCtB,CAAC;AAEX,iEAAiE;AACjE,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;CAmBnB,CAAC;AAEX,oDAAoD;AACpD,eAAO,MAAM,cAAc;;;;;;;;CAQjB,CAAC;AAEX,sCAAsC;AACtC,eAAO,MAAM,YAAY;;CAEf,CAAC"}
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/observability/events.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiCtB,CAAC;AAEX,iEAAiE;AACjE,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;CAmBnB,CAAC;AAEX,oDAAoD;AACpD,eAAO,MAAM,cAAc;;;;;;;;CAQjB,CAAC;AAEX,sCAAsC;AACtC,eAAO,MAAM,YAAY;;;CAGf,CAAC"}

package/dist/observability/events.js

@@ -74,6 +74,7 @@ const Z2hAgentEvents = {
 /** BI events tracked in `z2h-cli`. */
 const Z2hCliEvents = {
     error: 'z2h_cli_error',
+    handlerParseError: 'z2h_cli_handler_parse_error',
 };
 
 exports.BackendRunnerEvents = BackendRunnerEvents;

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.6.0",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {

package/src/index.ts

@@ -1 +1,7 @@
-export {};
+export {
+  ALWAYS_ON_CHANNELS,
+  DECLARED_INTEGRATIONS,
+  type AlwaysOnChannel,
+  type DeclaredIntegration,
+} from './integrations';
+export * from './secrets';

package/src/integrations.ts

@@ -0,0 +1,15 @@
+/**
+ * Backend channels surfaced as `ctx.api.v1.<name>`.
+ *
+ * Always-on channels need no OAuth and are never declared — the runner builds
+ * them for every app regardless of what its handlers touch.
+ */
+export const ALWAYS_ON_CHANNELS = ['db', 'llm', 'snowflake'] as const;
+export type AlwaysOnChannel = (typeof ALWAYS_ON_CHANNELS)[number];
+
+/**
+ * Declared (OAuth-gated) integrations: closed set the CLI detects from handler
+ * sources and the broker validates on register/update.
+ */
+export const DECLARED_INTEGRATIONS = ['monday'] as const;
+export type DeclaredIntegration = (typeof DECLARED_INTEGRATIONS)[number];

package/src/observability/events.ts

@@ -75,4 +75,5 @@ export const Z2hAgentEvents = {
 /** BI events tracked in `z2h-cli`. */
 export const Z2hCliEvents = {
   error: 'z2h_cli_error',
+  handlerParseError: 'z2h_cli_handler_parse_error',
 } as const;

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');
+}