@marinoscar/platform-api 0.0.0-stage → 0.1.0-next.11

package/dist/core/crypto/secret-cipher.js

@@ -0,0 +1,511 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ORG_CREDENTIAL_DOMAIN_PREFIX = exports.USER_CREDENTIAL_DOMAIN_PREFIX = void 0;
+exports.isCanonicalUuid = isCanonicalUuid;
+exports.encryptSecret = encryptSecret;
+exports.decryptSecret = decryptSecret;
+exports.assertEncryptionKeyConfigured = assertEncryptionKeyConfigured;
+exports.deriveSigningKey = deriveSigningKey;
+exports.userCredentialPurpose = userCredentialPurpose;
+exports.orgCredentialPurpose = orgCredentialPurpose;
+const node_crypto_1 = require("node:crypto");
+// =============================================================================
+// AES-256-GCM Secret Cipher  (issues #114, epic #108)
+// =============================================================================
+//
+// The primitive underneath every runtime-configured secret this application
+// will ever store. Deploy-time secrets (JWT_SECRET, GOOGLE_CLIENT_SECRET)
+// correctly live in the environment; this module exists for the other kind —
+// an SMTP password or an SES secret access key an administrator types into a
+// form, which cannot come from an env var because it needs a redeploy to
+// change.
+//
+// Payload layout (concatenated, then base64-encoded into one opaque string):
+//
+//     [iv: 12 bytes][authTag: 16 bytes][ciphertext: variable]
+//
+// Self-describing on purpose: a single `text` column holds the whole thing, so
+// the IV and the auth tag can never be stored in separate columns and drift
+// away from the ciphertext they authenticate.
+//
+// Key source: SECRETS_ENCRYPTION_KEY, a base64-encoded 32 bytes.
+// Generate with: openssl rand -base64 32
+//
+// MOVED INTO @marinoscar/platform-api/core (issue #698) BYTE-COMPATIBLE: the
+// env var name, the sub-key label, the IV/tag lengths, the payload layout and
+// every error text are unchanged. A ciphertext written by the app before the
+// move decrypts after it (apps/api/test/platform/secret-cipher-compat.spec.ts).
+//
+// THIS MODULE MUST NOT LOG. Every value passing through it is either a secret,
+// a key, or a key-derived value; a Logger here is a plaintext leak waiting for
+// someone to raise the log level. Errors carry lengths and variable names only.
+// =============================================================================
+/**
+ * 96 bits. The GCM-standard IV size, and not an arbitrary choice: at exactly 12
+ * bytes the spec uses the IV directly as the initial counter block, while any
+ * other length is folded through GHASH first. Twelve is the well-analysed path
+ * and the one every other implementation interoperates on.
+ */
+const IV_LENGTH = 12;
+/**
+ * 128 bits — the full GCM tag. Node will happily accept a truncated tag (as
+ * short as 4 bytes) via `setAuthTag`, and a shorter tag means proportionally
+ * cheaper forgery. We always write and read exactly 16.
+ */
+const AUTH_TAG_LENGTH = 16;
+/** AES-256 key size, for both the master key and every derived sub-key. */
+const KEY_LENGTH = 32;
+const KEY_ENV_VAR = 'SECRETS_ENCRYPTION_KEY';
+/**
+ * Fixed, versioned label prefix for sub-key derivation. The `v1` is the hook
+ * for ever changing the derivation scheme: bumping it changes every derived
+ * key, which makes existing ciphertexts undecryptable, so it must only move
+ * together with a re-encryption migration.
+ */
+const SUBKEY_LABEL_PREFIX = 'enterpriseappbase:secret-cipher:v1:';
+/**
+ * Fixed, versioned label prefix for MAC (signing) sub-keys (issue #822).
+ * Never change it: it is part of every derived signing key, so a different
+ * label invalidates every outstanding token signed under it. It differs from
+ * {@link SUBKEY_LABEL_PREFIX} at a fixed position (`signing-key` vs
+ * `secret-cipher`), so no signing purpose can ever produce an encryption
+ * sub-key, or the reverse.
+ */
+const SIGNING_SUBKEY_LABEL_PREFIX = 'enterpriseappbase:signing-key:v1:';
+/**
+ * First segment of every owner-bound sub-key domain (issue #387). See
+ * {@link userCredentialPurpose}. System purposes may not contain `:` at all
+ * (the reference app enforces it in `credentials/credential-internals.ts`),
+ * so no system purpose can begin with this.
+ *
+ * @stability stable
+ * @example
+ * ```ts
+ * purpose.startsWith(USER_CREDENTIAL_DOMAIN_PREFIX); // an owner-bound domain
+ * ```
+ */
+exports.USER_CREDENTIAL_DOMAIN_PREFIX = 'user:';
+/**
+ * First segment of every organization-bound sub-key domain (issue #735). See
+ * {@link orgCredentialPurpose}. Like {@link USER_CREDENTIAL_DOMAIN_PREFIX}, no
+ * system purpose can begin with it, because a system purpose may not contain
+ * `:`; and it cannot collide with a user domain, whose first segment differs.
+ *
+ * @stability stable
+ * @example
+ * ```ts
+ * purpose.startsWith(ORG_CREDENTIAL_DOMAIN_PREFIX); // an organization-bound domain
+ * ```
+ */
+exports.ORG_CREDENTIAL_DOMAIN_PREFIX = 'org:';
+/**
+ * A canonical UUID: lowercase hex, 8-4-4-4-12. Postgres and Prisma both
+ * render `uuid` values this way, so an id read back from the database always
+ * matches; an uppercase or brace-wrapped spelling of the same id does not.
+ */
+const CANONICAL_UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+/**
+ * Is `value` a canonical (lowercase, hyphenated) UUID string?
+ *
+ * @param value - Anything.
+ * @returns `true` for `8-4-4-4-12` lowercase hex, the spelling Postgres and
+ *   Prisma render.
+ * @stability stable
+ * @example
+ * ```ts
+ * isCanonicalUuid('00000000-0000-4000-8000-000000000001'); // true
+ * isCanonicalUuid('00000000-0000-4000-8000-00000000000A'); // false (uppercase)
+ * ```
+ */
+function isCanonicalUuid(value) {
+    return typeof value === 'string' && CANONICAL_UUID_PATTERN.test(value);
+}
+/**
+ * Strict base64 (standard alphabet, canonical padding). We validate the *text*
+ * rather than trusting the decode, because `Buffer.from(x, 'base64')` silently
+ * skips characters it does not recognise — `"not a real key!!!"` decodes to
+ * some bytes rather than failing, and a typo'd key that happened to decode to
+ * 32 bytes would be accepted as valid and silently encrypt everything under
+ * the wrong key.
+ */
+const BASE64_PATTERN = /^[A-Za-z0-9+/]+={0,2}$/;
+/**
+ * Build the operator-facing error for a bad key. The audience is someone
+ * configuring a deployment, not someone reading this source, so the message
+ * names the variable and hands over the exact generation command.
+ *
+ * `reason` describes the *shape* of the failure (absent, not base64, wrong
+ * length) and may contain a byte count, never any bytes: an operator needs to
+ * know "24 bytes, expected 32" to fix their key, and a length is not key
+ * material. Nothing derived from the key value itself may appear here.
+ */
+function keyConfigError(reason) {
+    return new Error(`${KEY_ENV_VAR} ${reason}. It must be a base64-encoded ${KEY_LENGTH}-byte key. ` +
+        `Generate one with: openssl rand -base64 ${KEY_LENGTH}`);
+}
+/**
+ * The master key, read once and cached for the life of the process.
+ *
+ * Caching is deliberate — the key cannot change without a restart, and re-
+ * reading `process.env` on every decrypt would only add a way for a late
+ * mutation of the environment to silently split the ciphertexts written before
+ * it from the ones written after.
+ *
+ * Consequence for tests: changing `process.env.SECRETS_ENCRYPTION_KEY` after
+ * this module has been touched has no effect. Use `jest.resetModules()` and
+ * re-`require` the module to exercise a different key.
+ */
+let cachedMasterKey = null;
+function getMasterKey() {
+    if (cachedMasterKey)
+        return cachedMasterKey;
+    const raw = process.env[KEY_ENV_VAR];
+    if (!raw) {
+        throw keyConfigError('is not set');
+    }
+    // .env files and container orchestrators routinely leave a trailing newline
+    // or stray space on a value. That is an operator typo we can absorb safely —
+    // whitespace carries no information for a base64 key — and refusing it would
+    // burn someone's afternoon on an invisible character.
+    const trimmed = raw.trim();
+    if (!BASE64_PATTERN.test(trimmed)) {
+        throw keyConfigError('is not valid base64');
+    }
+    const key = Buffer.from(trimmed, 'base64');
+    if (key.length !== KEY_LENGTH) {
+        throw keyConfigError(`decoded to ${key.length} bytes`);
+    }
+    cachedMasterKey = key;
+    return cachedMasterKey;
+}
+/**
+ * Derived sub-keys, cached by purpose.
+ *
+ * A derived key is a pure function of two values that are both fixed for the
+ * life of the process (the master key and the purpose string), so the cache
+ * can never go stale — and it is only ever populated through `deriveKey`,
+ * which resolves the master key first, so an unconfigured key still throws
+ * before anything lands here.
+ *
+ * The purpose set is a small, closed vocabulary chosen by callers in code
+ * ('smtp', 'oauth', …), not user input, so this Map cannot grow unboundedly.
+ *
+ * OWNER-BOUND DOMAINS ARE NOT CACHED (issue #387). A per-user domain
+ * (`userCredentialPurpose()` below) is one string per user × purpose, and a
+ * per-organization one (`orgCredentialPurpose()`, #735) one per org × purpose:
+ * that is exactly the open-ended vocabulary this cache must not hold: it would grow
+ * with the user base for the life of the process and keep one derived key per
+ * user resident in the heap. One HMAC-SHA256 per decrypt costs microseconds.
+ *
+ * NOR IS ANY OTHER ROW-BOUND DOMAIN (issue #730). A purpose that binds a row
+ * (`sharing.link:<grantId>`, one per link share) is just as open-ended. System
+ * purposes contain no `:` (the reference app enforces it), so a purpose WITH
+ * one is never cached: `user:` domains and row-bound domains alike. The
+ * derivation itself is unchanged, so every existing ciphertext still decrypts.
+ */
+const derivedKeyCache = new Map();
+/**
+ * Derive the 32-byte key actually used for a given purpose.
+ *
+ * WHY NOT JUST USE THE MASTER KEY: domain separation. Every purpose gets an
+ * independent key, so a ciphertext lifted out of one column and pasted into
+ * another — an attacker with a SQL write but not the key, or a bug that copies
+ * a row across tables — fails authentication instead of decrypting into a
+ * context where it means something else. Without this, the only thing standing
+ * between an SMTP password blob and being read as, say, an OAuth client secret
+ * is whichever code happens to parse it. That is a lateral-movement control,
+ * and it is the whole reason `purpose` is a required parameter rather than an
+ * option with a default.
+ *
+ * WHY HMAC-SHA256 AND NOT scrypt/argon2/PBKDF2: those are *password* KDFs, and
+ * their slowness exists to punish guessing a low-entropy input. The input here
+ * is already 32 bytes of `openssl rand` output — there is nothing to brute
+ * force — so a slow KDF would buy zero security and add latency to every
+ * decrypt. HMAC over a fixed label keyed by a full-entropy secret is the
+ * standard construction for exactly this case (it is HKDF's extract step).
+ *
+ * WHY THE LABEL IS SAFE TO CONCATENATE: `purpose` is the final field of the
+ * label, so distinct purposes always produce distinct labels — the prefix is
+ * constant and cannot be shifted into it. If a second variable field were ever
+ * added *after* the purpose, this would need explicit length-prefixing to stop
+ * ('ab', 'c') and ('a', 'bc') from colliding onto one key.
+ */
+function deriveKey(purpose) {
+    // An empty or non-string purpose would silently collapse every domain onto a
+    // single key, quietly removing the separation above while everything still
+    // appeared to work. Reject it loudly. The check is a runtime one despite the
+    // `string` type because a plain-JS caller, a JSON round-trip, or an
+    // undefined config value can all deliver something else here.
+    if (typeof purpose !== 'string' || purpose.length === 0) {
+        throw new Error('encryptSecret/decryptSecret require a non-empty purpose string (e.g. "smtp").');
+    }
+    // Only the closed vocabulary of system purposes ('smtp', 'oauth', ...) is
+    // cached; owner- and row-bound domains (user:, org:, ...) carry a `:` (see
+    // the cache's comment).
+    const cacheable = !purpose.startsWith(exports.USER_CREDENTIAL_DOMAIN_PREFIX) &&
+        !purpose.startsWith(exports.ORG_CREDENTIAL_DOMAIN_PREFIX) &&
+        !purpose.includes(':');
+    if (cacheable) {
+        const cached = derivedKeyCache.get(purpose);
+        if (cached)
+            return cached;
+    }
+    const derived = (0, node_crypto_1.createHmac)('sha256', getMasterKey())
+        .update(`${SUBKEY_LABEL_PREFIX}${purpose}`)
+        .digest();
+    if (cacheable)
+        derivedKeyCache.set(purpose, derived);
+    return derived;
+}
+/**
+ * Encrypt `plaintext` under the purpose-bound sub-key for `purpose`.
+ *
+ * Returns a base64 string carrying its own IV and auth tag — safe to put
+ * straight into a `text` column.
+ *
+ * @param plaintext - The secret, as UTF-8 text.
+ * @param purpose - The sub-key domain: a short fixed string per kind of
+ *   secret (`'smtp'`), or {@link userCredentialPurpose} for a per-user one.
+ * @returns base64 of `[iv: 12 bytes][authTag: 16 bytes][ciphertext]`.
+ * @throws if the key is missing/malformed, or `purpose` is empty.
+ * @stability stable
+ * @example
+ * ```ts
+ * const stored = encryptSecret(password, 'smtp');
+ * ```
+ */
+function encryptSecret(plaintext, purpose) {
+    const key = deriveKey(purpose);
+    // A FRESH RANDOM IV ON EVERY CALL — never a counter, never a hash of the
+    // plaintext, never reused. This is the single most destructive mistake
+    // available in GCM: reusing an IV under the same key does not merely leak
+    // the XOR of the two plaintexts, it exposes the GHASH subkey and lets an
+    // attacker forge auth tags for that key outright. Deriving the IV from the
+    // plaintext would do exactly that for two equal secrets.
+    //
+    // It is also what keeps the store from leaking equality: two credentials
+    // holding the same password must not produce the same ciphertext, or the
+    // table answers "do these two accounts share a password?" to anyone who can
+    // read it.
+    const iv = (0, node_crypto_1.randomBytes)(IV_LENGTH);
+    const cipher = (0, node_crypto_1.createCipheriv)('aes-256-gcm', key, iv, {
+        authTagLength: AUTH_TAG_LENGTH,
+    });
+    const ciphertext = Buffer.concat([
+        cipher.update(plaintext, 'utf8'),
+        cipher.final(),
+    ]);
+    // getAuthTag() is only valid after final(); reading it earlier returns a tag
+    // that does not cover the whole message.
+    const authTag = cipher.getAuthTag();
+    return Buffer.concat([iv, authTag, ciphertext]).toString('base64');
+}
+/**
+ * Decrypt a payload produced by `encryptSecret` under the SAME `purpose`.
+ *
+ * Any tampering — a flipped bit in the IV, the tag, or the ciphertext — and
+ * any purpose mismatch fails here rather than returning plausible garbage.
+ * That is the entire reason this is GCM and not CBC: an unauthenticated mode
+ * would hand back corrupted bytes that then get used as an SMTP password.
+ *
+ * @param payload - A string returned by {@link encryptSecret}.
+ * @param purpose - The same purpose it was encrypted under.
+ * @returns The plaintext.
+ * @throws if the key is missing/malformed, `purpose` is empty, the payload is
+ *         truncated, or authentication fails.
+ * @stability stable
+ * @example
+ * ```ts
+ * const password = decryptSecret(row.encryptedValue, 'smtp');
+ * ```
+ */
+function decryptSecret(payload, purpose) {
+    const key = deriveKey(purpose);
+    // Invalid base64 is not rejected up front here (unlike the key, where a typo
+    // must be caught at configuration time): `Buffer.from` skips unrecognised
+    // characters, and whatever survives is caught by the length check below or
+    // by the auth tag. The tag — not input parsing — is what makes a payload
+    // trustworthy, so there is nothing to gain by pre-screening the encoding.
+    const buf = Buffer.from(payload, 'base64');
+    // A payload shorter than the header cannot be ours. Check BEFORE slicing:
+    // `subarray` clamps out-of-range indices instead of throwing, so a truncated
+    // input would silently yield a short IV and an empty tag and fail somewhere
+    // deeper with a far less obvious error. Equality is allowed — a 28-byte
+    // payload is the legitimate encryption of an empty string.
+    if (buf.length < IV_LENGTH + AUTH_TAG_LENGTH) {
+        throw new Error(`Malformed encrypted payload: expected at least ${IV_LENGTH + AUTH_TAG_LENGTH} bytes, got ${buf.length}.`);
+    }
+    const iv = buf.subarray(0, IV_LENGTH);
+    const authTag = buf.subarray(IV_LENGTH, IV_LENGTH + AUTH_TAG_LENGTH);
+    const ciphertext = buf.subarray(IV_LENGTH + AUTH_TAG_LENGTH);
+    try {
+        const decipher = (0, node_crypto_1.createDecipheriv)('aes-256-gcm', key, iv, {
+            authTagLength: AUTH_TAG_LENGTH,
+        });
+        decipher.setAuthTag(authTag);
+        return Buffer.concat([
+            decipher.update(ciphertext),
+            decipher.final(), // verifies the auth tag; throws if it does not match
+        ]).toString('utf8');
+    }
+    catch {
+        // Deliberately swallow the underlying error and throw a flat one instead.
+        //
+        // Two reasons. First, a caught error can be logged by a caller along with
+        // its `cause`, and we will not risk anything derived from the key or the
+        // partially-decrypted plaintext travelling out of this module in a stack.
+        // Second, a wrong purpose, a wrong key and a tampered byte are all the
+        // same event to the caller — "this payload is not readable here" — and
+        // distinguishing them only helps someone probing.
+        //
+        // The empty catch binding is intentional: there is nothing here we are
+        // willing to inspect or forward.
+        throw new Error('Failed to decrypt secret: the payload is corrupt, was encrypted under a different purpose, or the encryption key has changed.');
+    }
+}
+/**
+ * Throw unless `SECRETS_ENCRYPTION_KEY` is present and well-formed.
+ *
+ * Exists so startup can fail on a bad key instead of the first administrator
+ * who tries to save a credential — a misconfiguration should surface in the
+ * deploy logs, not as a 500 weeks later. Wiring this into bootstrap is #116;
+ * this issue only provides the check.
+ *
+ * Also warms the cache, so the first real encrypt does not pay for validation.
+ *
+ * @throws the operator-facing key error (names the variable, the shape of the
+ *   failure and the generation command; never key material).
+ * @stability stable
+ * @example
+ * ```ts
+ * assertEncryptionKeyConfigured(); // throws if SECRETS_ENCRYPTION_KEY is unusable
+ * ```
+ */
+function assertEncryptionKeyConfigured() {
+    getMasterKey();
+}
+/**
+ * Signing sub-keys, cached by purpose. Same reasoning as `derivedKeyCache`:
+ * the purpose is a code constant, never user input, so the map stays small.
+ */
+const signingKeyCache = new Map();
+/**
+ * A 32-byte HMAC key for `purpose`, derived from `SECRETS_ENCRYPTION_KEY`
+ * (issue #822).
+ *
+ * For server-signed, short-lived tokens (a download link, a one-time URL)
+ * that need a deployment secret without a new environment variable: the
+ * master key is already mandatory and validated at startup, and the label
+ * `enterpriseappbase:signing-key:v1:` keeps every signing domain independent
+ * of every encryption domain, so a signing key can never decrypt a stored
+ * credential.
+ *
+ * Derivation: `HMAC-SHA256(masterKey, "enterpriseappbase:signing-key:v1:" + purpose)`.
+ * The label is permanent. Rotating the master key invalidates every
+ * outstanding token, which for minutes-long tokens is the desired behaviour.
+ *
+ * `purpose` is a code constant (`'android-app-download'`), never user input:
+ * derived keys are cached per purpose for the life of the process. Never log
+ * or return the key.
+ *
+ * @param purpose - The signing domain: a short fixed string per kind of token.
+ * @returns A 32-byte key for `createHmac('sha256', key)`.
+ * @throws if the key is missing/malformed (the same operator-facing error as
+ *   {@link assertEncryptionKeyConfigured}), or `purpose` is empty.
+ * @stability stable
+ * @example
+ * ```ts
+ * const mac = createHmac('sha256', deriveSigningKey('android-app-download'))
+ *   .update(payload)
+ *   .digest('base64url');
+ * ```
+ */
+function deriveSigningKey(purpose) {
+    if (typeof purpose !== 'string' || purpose.length === 0) {
+        throw new Error('deriveSigningKey requires a non-empty purpose string.');
+    }
+    const cached = signingKeyCache.get(purpose);
+    if (cached)
+        return cached;
+    const derived = (0, node_crypto_1.createHmac)('sha256', getMasterKey())
+        .update(`${SIGNING_SUBKEY_LABEL_PREFIX}${purpose}`)
+        .digest();
+    signingKeyCache.set(purpose, derived);
+    return derived;
+}
+/**
+ * The owner-bound sub-key domain for a PER-USER credential (issue #387):
+ * `user:<userId>:<purpose>`.
+ *
+ * Pass the result as the `purpose` argument of {@link encryptSecret} /
+ * {@link decryptSecret}; those functions are unchanged. Binding the owner into
+ * the domain means a ciphertext copied from user A's row into user B's row —
+ * a SQL write, a bug copying rows — fails GCM authentication rather than
+ * handing B the use of A's key. The system store's domain is the bare purpose;
+ * this is the same construction with the owner prepended.
+ *
+ * WHY THE STRING DECOMPOSES ONE WAY ONLY:
+ *   - `userId` must be a canonical UUID: fixed length, no `:`, one spelling
+ *     per id (an uppercase variant would otherwise derive a second key for
+ *     the same user and strand every row written under the first).
+ *   - `purpose` must not contain `:`, so the final segment is unambiguous.
+ *   - System purposes may not contain `:` either, so no system purpose can
+ *     equal, or begin with, `user:` — the two key spaces cannot collide.
+ * Together that makes (userId, purpose) → domain injective, which is what the
+ * concatenation in `deriveKey` relies on.
+ *
+ * @throws a plain Error (no values in it) on a non-canonical id or a bad
+ *         purpose. Callers validate first and report their own 400; this is
+ *         the backstop that keeps a malformed domain from ever deriving a key.
+ * @param userId - The owner: a canonical UUID.
+ * @param purpose - The kind of secret; non-empty, no `:`.
+ * @returns `user:<userId>:<purpose>`.
+ * @stability stable
+ * @example
+ * ```ts
+ * const stored = encryptSecret(apiKey, userCredentialPurpose(userId, 'ai_user_key'));
+ * ```
+ */
+function userCredentialPurpose(userId, purpose) {
+    if (!isCanonicalUuid(userId)) {
+        throw new Error('userCredentialPurpose requires a canonical (lowercase, hyphenated) UUID userId.');
+    }
+    if (typeof purpose !== 'string' || purpose.length === 0 || purpose.includes(':')) {
+        throw new Error('userCredentialPurpose requires a non-empty purpose containing no ":".');
+    }
+    return `${exports.USER_CREDENTIAL_DOMAIN_PREFIX}${userId}:${purpose}`;
+}
+/**
+ * The organization-bound sub-key domain for an organization's own credential
+ * (issue #735): `org:<orgId>:<purpose>`, the organization counterpart of
+ * {@link userCredentialPurpose}. Binding the owner into the domain means a
+ * ciphertext copied from organization A's row into organization B's row (a SQL
+ * write, a bug copying rows) fails GCM authentication rather than handing B
+ * the use of A's key.
+ *
+ * The string decomposes one way only, for the reasons given on
+ * {@link userCredentialPurpose}: `orgId` is a canonical UUID, `purpose` has no
+ * `:`, and the `org:` and `user:` prefixes differ, so (orgId, purpose) → domain
+ * is injective and disjoint from every user and system domain.
+ *
+ * @throws a plain Error (no values in it) on a non-canonical id or a bad
+ *         purpose. Callers validate first and report their own error.
+ * @param orgId - The owning organization: a canonical UUID.
+ * @param purpose - The kind of secret; non-empty, no `:`.
+ * @returns `org:<orgId>:<purpose>`.
+ * @stability stable
+ * @example
+ * ```ts
+ * const stored = encryptSecret(apiKey, orgCredentialPurpose(orgId, 'ai'));
+ * ```
+ */
+function orgCredentialPurpose(orgId, purpose) {
+    if (!isCanonicalUuid(orgId)) {
+        throw new Error('orgCredentialPurpose requires a canonical (lowercase, hyphenated) UUID orgId.');
+    }
+    if (typeof purpose !== 'string' || purpose.length === 0 || purpose.includes(':')) {
+        throw new Error('orgCredentialPurpose requires a non-empty purpose containing no ":".');
+    }
+    return `${exports.ORG_CREDENTIAL_DOMAIN_PREFIX}${orgId}:${purpose}`;
+}
+//# sourceMappingURL=secret-cipher.js.map

package/dist/core/crypto/secret-cipher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-cipher.js","sourceRoot":"","sources":["../../../src/core/crypto/secret-cipher.ts"],"names":[],"mappings":"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"}

package/dist/core/data-access/access-reason.registry.d.ts

@@ -0,0 +1,95 @@
+import { type Registry } from '../registry/registry';
+/**
+ * The platform's own access reasons, in the order they were introduced.
+ *
+ * - `backup` / `restore`: the database dump and its replay.
+ * - `purge`: deleting rows across organisations (storage purge, user and
+ *   factory reset).
+ * - `doctor`: read-only health checks that count rows across organisations.
+ * - `retention`: the retention purge handlers.
+ * - `admin-aggregate`: deployment-wide administrator views and aggregates, and
+ *   display-only reads such as another user's avatar.
+ * - `migration-tooling`: seeds and migration helpers.
+ * - `link-resolution`: resolving a link-share token: ONE row of `grants`, by
+ *   its unique token hash, before any organization is known.
+ * - `export`: the data-export sources and the export file lookups.
+ *
+ * @stability experimental
+ */
+export declare const BUILTIN_SYSTEM_ACCESS_REASONS: readonly ["backup", "restore", "purge", "doctor", "retention", "admin-aggregate", "migration-tooling", "link-resolution", "export"];
+/**
+ * One of the platform's own access reasons. See {@link BUILTIN_SYSTEM_ACCESS_REASONS}.
+ *
+ * @stability experimental
+ */
+export type BuiltinSystemAccessReason = (typeof BUILTIN_SYSTEM_ACCESS_REASONS)[number];
+/**
+ * The pattern every access reason id matches: lower-case, 3 to 48 characters,
+ * starting with a letter (`transcript-reindex`).
+ *
+ * @stability experimental
+ */
+export declare const SYSTEM_ACCESS_REASON_ID_PATTERN: RegExp;
+/**
+ * One registered access reason.
+ *
+ * @stability experimental
+ * @example
+ * ```ts
+ * const reason: SystemAccessReasonDef = {
+ *   id: 'transcript-reindex',
+ *   description: 'The transcript re-index job rebuilds search rows across organizations.',
+ * };
+ * ```
+ */
+export interface SystemAccessReasonDef {
+    /** The reason id. See {@link SYSTEM_ACCESS_REASON_ID_PATTERN}. */
+    readonly id: string;
+    /** One sentence: which work needs the bypass and why it cannot run scoped. Shown by the Doctor and in docs. */
+    readonly description: string;
+}
+/**
+ * Every registered access reason: the platform's nine first (in
+ * {@link BUILTIN_SYSTEM_ACCESS_REASONS} order), then the app's. Frozen once the
+ * application has bootstrapped.
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+export declare const systemAccessReasonRegistry: Registry<SystemAccessReasonDef>;
+/**
+ * Registers an access reason an app's own system work runs under. Call it at
+ * module load, before the application is created; a duplicate id (including a
+ * built-in one) throws.
+ *
+ * This only makes the label valid. It does not let any file reach the system
+ * Prisma client: that stays the allowlist in
+ * `apps/api/test/tenancy/system-injection-boundary.spec.ts`.
+ *
+ * @param reason - the id and a one-sentence description.
+ * @throws RegistryError `INVALID_ID`, `INVALID_ENTRY`, `DUPLICATE_ID` or `FROZEN`.
+ *
+ * @example
+ * ```ts
+ * // apps/api/src/app-registrations/core.ts
+ * registerSystemAccessReason({
+ *   id: 'transcript-reindex',
+ *   description: 'Rebuilds the transcript search rows of every organization.',
+ * });
+ * // then, in a job handler: runAsSystem(systemPrisma, 'transcript-reindex', (tx) => ...)
+ * ```
+ *
+ * @extensionPoint registry
+ * @stability experimental
+ */
+export declare function registerSystemAccessReason(reason: SystemAccessReasonDef): void;
+/**
+ * Whether `value` is a registered access reason.
+ *
+ * @param value - anything; a non-string is never a reason.
+ * @returns `true` for a registered id.
+ *
+ * @stability experimental
+ */
+export declare function isSystemAccessReason(value: unknown): value is string;
+//# sourceMappingURL=access-reason.registry.d.ts.map

package/dist/core/data-access/access-reason.registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"access-reason.registry.d.ts","sourceRoot":"","sources":["../../../src/core/data-access/access-reason.registry.ts"],"names":[],"mappings":"AAwBA,OAAO,EAAkB,KAAK,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAErE;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,6BAA6B,qIAU/B,CAAC;AAEZ;;;;GAIG;AACH,MAAM,MAAM,yBAAyB,GAAG,CAAC,OAAO,6BAA6B,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvF;;;;;GAKG;AACH,eAAO,MAAM,+BAA+B,QAA2B,CAAC;AAExE;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,qBAAqB;IACpC,kEAAkE;IAClE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,+GAA+G;IAC/G,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,EAAE,QAAQ,CAAC,qBAAqB,CASrE,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,qBAAqB,GAAG,IAAI,CAE9E;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAEpE"}