@octaviaflow/connector-crypto

Application-layer encryption of connector credentials at rest. Standalone, private (GitHub). Shared by Octaviaflow-Backend, Octaviaflow-CDC, and Octaviaflow-TRQE — every service that reads or writes ConnectorInstance.credentials.

Why: connector credentials are currently stored plaintext in Mongo. This package encrypts them before they touch the DB and decrypts them where the app actually uses them (preview, run, triggers, token refresh). The DB is never touched at the schema level and no migration script is required.

How it works

• AES-256-GCM, audited @noble primitives. No home-rolled crypto.
• Self-describing envelope stored in place of the raw object:

  { "__enc": 1, "kid": "v1", "iv": "<b64>", "ct": "<b64 ciphertext+tag>" }

• Backward-compatible — decryptCredentials() returns legacy plaintext unchanged. This is the whole reason no DB migration is needed: existing connectors keep working and become encrypted on their next save/reconnect.
• Idempotent — encryptCredentials() won't double-wrap an already-encrypted value.
• Rotation-ready — the kid lets the keyring hold multiple keys so old data still decrypts after a key rotation.

API

import {
  keyringFromEnv, encryptCredentials, decryptCredentials, isEncrypted, generateKeyBase64,
} from '@octaviaflow/connector-crypto';

const keyring = keyringFromEnv(); // reads CONNECTOR_CRED_KEY from env once at startup

// WRITE (connector.service create/update, OAuth token saves, TRQE refresh)
instance.credentials = encryptCredentials(plainCreds, keyring);

// READ-FOR-USE (executionStream, testConnection, CDC, TRQE, every connector service)
const creds = decryptCredentials(instance.credentials, keyring); // plaintext OR legacy passthrough

Key management

Mint a key and put it in SSM (prod/beta) and .env (local) — the same key across all three services:

bun run keygen          # prints a base64 32-byte key
# SSM:  /octaviaflow/{prod,beta}/connector-cred-key
# .env: CONNECTOR_CRED_KEY=<that base64 key>

Env forms:

• Single key (typical): CONNECTOR_CRED_KEY=<b64-32B> (optional CONNECTOR_CRED_KID=v1)
• Rotation: CONNECTOR_CRED_KEYS={"v1":"<b64>","v2":"<b64>"} + CONNECTOR_CRED_ACTIVE_KID=v2 (keep the old key in the map so old envelopes still decrypt; re-save connectors to migrate them to the new key).

If the key is missing, the keyring throws at startup — credentials are never silently stored in plaintext.

Rollout (no DB migration)

1. Ship decrypt capability + key to all 3 services first — a no-op while data is plaintext (decrypt passes plaintext through).
2. Then enable encrypt-on-write in Backend (+ TRQE token refresh).
3. Re-save / delete-and-reconnect existing connectors to encrypt them (fine with ~no customers). New writes are encrypted automatically.

This order guarantees no service ever reads ciphertext before it can decrypt it.

Consuming from GitHub

For local dev the services link this via file:; once pushed, switch to the GitHub ref (GitHub Packages registry or git+ssh://[email protected]/<org>/connector-crypto.git#<tag>).