@onlineapps/conn-infra-secrets 1.0.0 → 1.1.0

package/README.md

@@ -4,7 +4,15 @@ Resolution connector for `ctx.secrets.get(ref)`. Reads the encrypted Redis
 projection written by `biz-meta` (SecretBox) and decrypts it in-process with the
 injected AES-256-GCM master key. Authoritative store (`oagen_meta.secret`) is owned
 by `biz-meta` and never touched here. Projection key contract:
-`state:meta:secret:<tenant>:<workspace|->:<ref>`.
+`state:meta:secret:<tenant>:<workspace|->:<ref>` — tenant-wide is the `-` segment,
+and `workspace_id` `0` (the writer's `TENANT_WIDE`), `'0'`, `null` and omitted all
+resolve to it.
+
+This package also owns the **sealing contract** (`src/crypto.js`): `seal()` /
+`encrypt()` + `sealBlob()` for the writing side, `open()` for every reader, one
+layout `base64( iv[12] || authTag[16] || ciphertext )`. Both directions in one
+module so seal→open is tested across the real boundary, not against a
+reimplementation.
 
 Canonical design: [`api/docs/architecture/secretbox.md`](../../../docs/architecture/secretbox.md).
 
@@ -25,4 +33,8 @@ the invocation scope.
 - `SECRET_SCOPE_MISSING` / `SECRET_REF_INVALID` — bad call.
 
 ## Test
-`npm run test:unit` — decrypt round-trip, tamper/not-found, scope, mock.
+- `npm run test:unit` — seal/open round trip, byte compatibility with a blob
+  sealed by `biz-meta` own implementation, tamper/not-found/bad-key paths,
+  scope mapping, mock.
+- `npm run test:integration` — real Redis. Needs `REDIS_HOST` + `REDIS_PORT`
+  (dev stack: `REDIS_HOST=127.0.0.1 REDIS_PORT=33030`, container `api_node_cache`).

package/jest.integration.config.js

@@ -0,0 +1,18 @@
+'use strict';
+
+/**
+ * Separate Jest runner for the integration tier: it carries the `globalSetup`
+ * that probes the live Redis and aborts the run when it is absent, so the tier
+ * can never report a result on an environment that cannot serve it.
+ *
+ * @see tests/integration/setup.js
+ */
+
+module.exports = {
+  testEnvironment: 'node',
+  testMatch: ['**/tests/integration/**/*.test.js'],
+  testTimeout: 30000,
+  globalSetup: './tests/integration/setup.js',
+  coverageDirectory: 'coverage-integration',
+  verbose: true
+};

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "@onlineapps/conn-infra-secrets",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Secret resolution connector for ctx.secrets.get(ref) — reads the SecretBox Redis projection and decrypts in-process (AES-256-GCM)",
   "main": "src/index.js",
   "scripts": {
     "test": "jest",
-    "test:unit": "jest tests/unit"
+    "test:unit": "jest tests/unit",
+    "test:integration": "jest --config=jest.integration.config.js"
   },
   "keywords": [
     "secrets",

package/src/crypto.js

@@ -1,12 +1,20 @@
 'use strict';
 
 /**
- * Minimal AES-256-GCM open() for the secrets connector.
+ * AES-256-GCM sealing contract of the SecretBox — this module owns it.
  *
- * Deliberately a small, self-contained copy of the sealing contract owned by
- * api_secrets (`src/lib/crypto.js`) — the two packages cannot import each other.
- * Blob layout MUST stay identical: base64( iv[12] || authTag[16] || ciphertext ).
- * See api/docs/architecture/secretbox.md §4.
+ * Both directions live here: `seal()`/`encrypt()` for the writer (biz-meta) and
+ * `open()` for every reader (`ctx.secrets.get(ref)`). One owner means seal→open
+ * is exercised across the real boundary in this package's tests instead of each
+ * side testing against its own reimplementation of the other.
+ *
+ * Wire blob (Redis projection): base64( iv[12] || authTag[16] || ciphertext ).
+ * In MySQL the same three parts are stored in separate columns, which is why
+ * `encrypt()` returns them individually and `sealBlob()` concatenates them.
+ * Layout is specified in api/docs/architecture/secretbox.md §4 — changing it
+ * makes every already-stored secret unreadable.
+ *
+ * The key is always injected (never read from env here): principle 1, DI.
  */
 
 const crypto = require('crypto');
@@ -16,6 +24,11 @@ const KEY_BYTES = 32;
 const IV_BYTES = 12;
 const AUTH_TAG_BYTES = 16;
 
+/**
+ * Decode and validate a base64 master key.
+ * @param {string} masterKeyBase64
+ * @returns {Buffer} 32 raw bytes
+ */
 function loadMasterKey(masterKeyBase64) {
   if (typeof masterKeyBase64 !== 'string' || masterKeyBase64.length === 0) {
     throw new Error(
@@ -32,6 +45,57 @@ function loadMasterKey(masterKeyBase64) {
   return key;
 }
 
+/** @private Fail fast on a key that would otherwise blow up inside node:crypto. */
+function assertKey(key) {
+  if (!Buffer.isBuffer(key)) {
+    throw new Error(
+      '[conn-infra-secrets] Master key must be a Buffer - Fix: pass the result of loadMasterKey().'
+    );
+  }
+  if (key.length !== KEY_BYTES) {
+    throw new Error(
+      `[conn-infra-secrets] Invalid master key length - got ${key.length} bytes, expected ${KEY_BYTES}.`
+    );
+  }
+}
+
+/**
+ * Encrypt to the three parts the authoritative store keeps in separate columns.
+ * @param {string} plaintext
+ * @param {Buffer} key
+ * @returns {{ iv: Buffer, authTag: Buffer, ciphertext: Buffer }}
+ */
+function encrypt(plaintext, key) {
+  if (typeof plaintext !== 'string') {
+    throw new Error('[conn-infra-secrets] seal requires a string plaintext.');
+  }
+  assertKey(key);
+  const iv = crypto.randomBytes(IV_BYTES);
+  const cipher = crypto.createCipheriv(ALGORITHM, key, iv);
+  const ciphertext = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+  const authTag = cipher.getAuthTag();
+  return { iv, authTag, ciphertext };
+}
+
+/**
+ * Concatenate the parts into the Redis projection blob.
+ * @param {{ iv: Buffer, authTag: Buffer, ciphertext: Buffer }} parts
+ * @returns {string} base64
+ */
+function sealBlob({ iv, authTag, ciphertext }) {
+  return Buffer.concat([iv, authTag, ciphertext]).toString('base64');
+}
+
+/**
+ * Encrypt straight to the projection blob (`encrypt` + `sealBlob`).
+ * @param {string} plaintext
+ * @param {Buffer} key
+ * @returns {string} base64( iv || authTag || ciphertext )
+ */
+function seal(plaintext, key) {
+  return sealBlob(encrypt(plaintext, key));
+}
+
 /**
  * @param {string} blobBase64
  * @param {Buffer} key
@@ -41,6 +105,7 @@ function open(blobBase64, key) {
   if (typeof blobBase64 !== 'string' || blobBase64.length === 0) {
     throw new Error('[conn-infra-secrets] open requires a non-empty base64 blob.');
   }
+  assertKey(key);
   const blob = Buffer.from(blobBase64, 'base64');
   if (blob.length < IV_BYTES + AUTH_TAG_BYTES) {
     throw new Error('[conn-infra-secrets] Blob too short - not a valid sealed secret.');
@@ -53,4 +118,14 @@ function open(blobBase64, key) {
   return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString('utf8');
 }
 
-module.exports = { loadMasterKey, open, ALGORITHM, KEY_BYTES, IV_BYTES, AUTH_TAG_BYTES };
+module.exports = {
+  loadMasterKey,
+  encrypt,
+  sealBlob,
+  seal,
+  open,
+  ALGORITHM,
+  KEY_BYTES,
+  IV_BYTES,
+  AUTH_TAG_BYTES
+};

package/src/index.js

@@ -25,6 +25,23 @@ const { loadMasterKey, open } = require('./crypto');
 // Meta owns the projection; its StateConnector prefixes keys with `state:meta:`.
 const DEFAULT_KEY_PREFIX = 'state:meta:secret:';
 
+// biz-meta stores tenant-wide secrets with workspace_id 0 (`TENANT_WIDE = 0` in
+// meta/src/handlers/secrets.js) and projects them under the `-` segment. The
+// reader must apply the identical mapping — a caller that legitimately passes 0
+// would otherwise read `:0:`, a key nothing ever writes. Omitted/null means the
+// same thing on the writing side, so all four spellings collapse to `-`.
+const TENANT_WIDE = 0;
+
+/**
+ * @param {number|string|null|undefined} workspaceId
+ * @returns {string} the key segment: `-` for tenant-wide, the id otherwise
+ */
+function workspaceSegment(workspaceId) {
+  if (workspaceId === null || workspaceId === undefined) return '-';
+  if (workspaceId === TENANT_WIDE || workspaceId === String(TENANT_WIDE)) return '-';
+  return String(workspaceId);
+}
+
 class SecretResolutionError extends Error {
   constructor(code, message) {
     super(message);
@@ -37,8 +54,7 @@ function projectionKey(tenantId, workspaceId, ref, keyPrefix = DEFAULT_KEY_PREFI
   if (tenantId === undefined || tenantId === null) {
     throw new SecretResolutionError('SECRET_SCOPE_MISSING', '[conn-infra-secrets] tenant_id is required to resolve a secret.');
   }
-  const ws = (workspaceId === null || workspaceId === undefined) ? '-' : String(workspaceId);
-  return `${keyPrefix}${tenantId}:${ws}:${ref}`;
+  return `${keyPrefix}${tenantId}:${workspaceSegment(workspaceId)}:${ref}`;
 }
 
 class SecretsConnector {
@@ -103,7 +119,7 @@ class SecretsConnector {
     if (blob === null || blob === undefined) {
       throw new SecretResolutionError(
         'SECRET_NOT_FOUND',
-        `[conn-infra-secrets] Secret ref "${name}" not found for scope ${key} - Fix: set it via the api_secrets admin API.`
+        `[conn-infra-secrets] Secret ref "${name}" not found for scope ${key} - Fix: set it via the biz-meta set-secret operation.`
       );
     }
     try {
@@ -125,8 +141,7 @@ class SecretsConnector {
 class MockSecretsConnector {
   constructor() { this.store = new Map(); this.connected = true; }
   static _k(scope, name) {
-    const ws = (scope.workspace_id === null || scope.workspace_id === undefined) ? '-' : String(scope.workspace_id);
-    return `secret:${scope.tenant_id}:${ws}:${name}`;
+    return `secret:${scope.tenant_id}:${workspaceSegment(scope.workspace_id)}:${name}`;
   }
   seed(scope, name, value) { this.store.set(MockSecretsConnector._k(scope, name), value); return this; }
   async connect() { this.connected = true; return true; }