@onlineapps/conn-infra-secrets 1.0.0

package/README.md

@@ -0,0 +1,28 @@
+# @onlineapps/conn-infra-secrets
+
+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>`.
+
+Canonical design: [`api/docs/architecture/secretbox.md`](../../../docs/architecture/secretbox.md).
+
+## Usage (wired by ServiceWrapper)
+```js
+const SecretsConnector = require('@onlineapps/conn-infra-secrets');
+const secrets = new SecretsConnector({ redisUrl: process.env.REDIS_URL, masterKeyBase64: process.env.SECRETS_MASTER_KEY });
+await secrets.connect();
+// ContextBuilder facade calls: secrets.get(ref, { tenant_id, workspace_id })
+```
+
+Handlers only ever call `ctx.secrets.get(ref)`; the ContextBuilder facade injects
+the invocation scope.
+
+## Errors (no fallbacks)
+- `SECRET_NOT_FOUND` — no projection for the ref/scope.
+- `SECRET_DECRYPT_FAILED` — master key mismatch or corrupted blob.
+- `SECRET_SCOPE_MISSING` / `SECRET_REF_INVALID` — bad call.
+
+## Test
+`npm run test:unit` — decrypt round-trip, tamper/not-found, scope, mock.

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@onlineapps/conn-infra-secrets",
+  "version": "1.0.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"
+  },
+  "keywords": [
+    "secrets",
+    "secretbox",
+    "connector",
+    "redis",
+    "oa-drive"
+  ],
+  "author": "OA Drive Team",
+  "license": "MIT",
+  "dependencies": {
+    "ioredis": "^5.3.2"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
+  },
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/crypto.js

@@ -0,0 +1,56 @@
+'use strict';
+
+/**
+ * Minimal AES-256-GCM open() for the secrets connector.
+ *
+ * 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.
+ */
+
+const crypto = require('crypto');
+
+const ALGORITHM = 'aes-256-gcm';
+const KEY_BYTES = 32;
+const IV_BYTES = 12;
+const AUTH_TAG_BYTES = 16;
+
+function loadMasterKey(masterKeyBase64) {
+  if (typeof masterKeyBase64 !== 'string' || masterKeyBase64.length === 0) {
+    throw new Error(
+      '[conn-infra-secrets] Missing master key - base64-encoded 32-byte key required. ' +
+      'Fix: set SECRETS_MASTER_KEY (or pass explicit key).'
+    );
+  }
+  const key = Buffer.from(masterKeyBase64, 'base64');
+  if (key.length !== KEY_BYTES) {
+    throw new Error(
+      `[conn-infra-secrets] Invalid master key length - decoded ${key.length} bytes, expected ${KEY_BYTES}.`
+    );
+  }
+  return key;
+}
+
+/**
+ * @param {string} blobBase64
+ * @param {Buffer} key
+ * @returns {string} plaintext
+ */
+function open(blobBase64, key) {
+  if (typeof blobBase64 !== 'string' || blobBase64.length === 0) {
+    throw new Error('[conn-infra-secrets] open requires a non-empty base64 blob.');
+  }
+  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.');
+  }
+  const iv = blob.subarray(0, IV_BYTES);
+  const authTag = blob.subarray(IV_BYTES, IV_BYTES + AUTH_TAG_BYTES);
+  const ciphertext = blob.subarray(IV_BYTES + AUTH_TAG_BYTES);
+  const decipher = crypto.createDecipheriv(ALGORITHM, key, iv);
+  decipher.setAuthTag(authTag);
+  return Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString('utf8');
+}
+
+module.exports = { loadMasterKey, open, ALGORITHM, KEY_BYTES, IV_BYTES, AUTH_TAG_BYTES };

package/src/index.js

@@ -0,0 +1,147 @@
+'use strict';
+
+/**
+ * @onlineapps/conn-infra-secrets — resolves secrets for `ctx.secrets.get(ref)`.
+ *
+ * Reads the encrypted Redis projection written by biz-meta (SecretBox) and
+ * decrypts it in-process with the injected master key. This mirrors the platform
+ * hot-read pattern (entitlements/credits via Redis connector); the authoritative
+ * store (oagen_meta.secret) is owned by biz-meta and never touched on this path.
+ *
+ * Redis projection (see secretbox.md §5) — flat key (meta StateConnector has no
+ * hash ops), value = base64( iv || authTag || ciphertext ):
+ *   state:meta:secret:<tenant_id>:<workspace_id|->:<ref>
+ *
+ * Contract: get(name, scope) => Promise<string>. The ContextBuilder facade passes
+ * the invocation's { tenant_id, workspace_id } as scope. No fallbacks: a missing
+ * projection throws SECRET_NOT_FOUND; a bad blob throws SECRET_DECRYPT_FAILED.
+ *
+ * @see api/docs/architecture/secretbox.md
+ */
+
+const Redis = require('ioredis');
+const { loadMasterKey, open } = require('./crypto');
+
+// Meta owns the projection; its StateConnector prefixes keys with `state:meta:`.
+const DEFAULT_KEY_PREFIX = 'state:meta:secret:';
+
+class SecretResolutionError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'SecretResolutionError';
+    this.code = code;
+  }
+}
+
+function projectionKey(tenantId, workspaceId, ref, keyPrefix = DEFAULT_KEY_PREFIX) {
+  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}`;
+}
+
+class SecretsConnector {
+  /**
+   * @param {Object} config
+   * @param {string} config.redisUrl - redis://host:port (required)
+   * @param {string} config.masterKeyBase64 - base64 32-byte AES-256-GCM key (required)
+   * @param {string} [config.password] - Redis password
+   * @param {number} [config.db=0] - Redis database index
+   */
+  constructor(config = {}) {
+    if (!config.redisUrl) {
+      throw new Error('[conn-infra-secrets] redisUrl is required - Fix: pass REDIS_URL.');
+    }
+    this._key = loadMasterKey(config.masterKeyBase64);
+    this._keyPrefix = config.keyPrefix || DEFAULT_KEY_PREFIX;
+
+    let host = config.redisUrl;
+    let port = 6379;
+    if (config.redisUrl.startsWith('redis://')) {
+      const parsed = new URL(config.redisUrl);
+      host = parsed.hostname;
+      port = parseInt(parsed.port, 10) || 6379;
+    }
+    this._redisOptions = { host, port, password: config.password, db: config.db || 0, lazyConnect: true };
+    this.client = null;
+    this.connected = false;
+  }
+
+  async connect() {
+    if (this.connected) return true;
+    this.client = new Redis(this._redisOptions);
+    this.client.on('error', (err) => { /* surfaced on get() */ this._lastError = err; });
+    await this.client.connect();
+    this.connected = true;
+    return true;
+  }
+
+  async disconnect() {
+    if (this.client) {
+      await this.client.quit();
+      this.client = null;
+      this.connected = false;
+    }
+  }
+
+  /**
+   * Resolve a secret ref to plaintext for the given invocation scope.
+   * @param {string} name - opaque secret ref
+   * @param {{ tenant_id: number|string, workspace_id?: number|string|null }} [scope]
+   * @returns {Promise<string>}
+   */
+  async get(name, scope = {}) {
+    if (typeof name !== 'string' || name.length === 0) {
+      throw new SecretResolutionError('SECRET_REF_INVALID', '[conn-infra-secrets] secret ref must be a non-empty string.');
+    }
+    if (!this.client || !this.connected) {
+      throw new SecretResolutionError('SECRET_STORE_UNAVAILABLE', '[conn-infra-secrets] not connected - call connect() first.');
+    }
+    const key = projectionKey(scope.tenant_id, scope.workspace_id, name, this._keyPrefix);
+    const blob = await this.client.get(key);
+    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.`
+      );
+    }
+    try {
+      return open(blob, this._key);
+    } catch (err) {
+      throw new SecretResolutionError(
+        'SECRET_DECRYPT_FAILED',
+        `[conn-infra-secrets] Failed to decrypt secret "${name}" for scope ${key} - master key mismatch or corrupted blob.`
+      );
+    }
+  }
+
+  isConnected() { return this.connected; }
+}
+
+/**
+ * In-memory mock for tests — no Redis, no crypto. Seed with plain values.
+ */
+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}`;
+  }
+  seed(scope, name, value) { this.store.set(MockSecretsConnector._k(scope, name), value); return this; }
+  async connect() { this.connected = true; return true; }
+  async disconnect() { this.connected = false; }
+  isConnected() { return this.connected; }
+  async get(name, scope = {}) {
+    const v = this.store.get(MockSecretsConnector._k(scope, name));
+    if (v === undefined) throw new SecretResolutionError('SECRET_NOT_FOUND', `mock: ${name} not found`);
+    return v;
+  }
+}
+
+module.exports = SecretsConnector;
+module.exports.SecretsConnector = SecretsConnector;
+module.exports.MockSecretsConnector = MockSecretsConnector;
+module.exports.SecretResolutionError = SecretResolutionError;
+module.exports.projectionKey = projectionKey;
+module.exports.create = (config) => new SecretsConnector(config);