@wildo-ai/saas-backend-lib 1.1.1 → 1.1.3

package/dist/esm/security/connected-accounts/utils/provider-credential-envelope.backend.utils.js

@@ -0,0 +1,277 @@
+/**
+ * Sealing an OWNER's provider credential at rest — an organization's, or a person's own.
+ *
+ * ## What this is for
+ *
+ * A credential toward a third party is stored in the application's own database, in a row its owner
+ * can create over HTTP. A database backup, a snapshot handed to a support engineer, or a read
+ * replica reached through an unrelated defect would otherwise expose every stored vendor credential
+ * in plaintext. Sealing them does not make the store safe to lose — nothing does — but it means
+ * losing the store is not the same event as losing every tenant's and every person's Slack, CRM and
+ * SMTP access.
+ *
+ * ## The key is the platform's existing material, deliberately
+ *
+ * `secrets.security.session.encryptionKey` is provisioned for every application by the platform
+ * (apps-manager mints it, the schema requires at least 32 characters, and readiness refuses an
+ * application without one). Introducing a second key here would mean a second thing to provision, a
+ * second thing to rotate, and a second way for an application to be half-configured — and the first
+ * application to hit that would discover it as "my credentials cannot be decrypted", after the
+ * values were already stored.
+ *
+ * The base key is NOT used directly. It is domain-separated through SHA-256 so this subsystem's key
+ * is unrelated to the session subsystem's, and to the SIEM delivery subsystem's, even though all
+ * three derive from the same material. Without the separator, a weakness or an oracle in one becomes
+ * a weakness in the others.
+ *
+ * ## AES-256-GCM, and why authentication is the load-bearing half
+ *
+ * GCM authenticates as well as encrypts, so a modified ciphertext FAILS rather than decrypting to
+ * garbage. That matters more than the confidentiality here: an attacker with write access to the
+ * store but not the key must not be able to flip a tenant's credential to a value of their choosing,
+ * or to swap tenant A's sealed credential into tenant B's row and have it silently work. The
+ * associated data below closes the second half of that.
+ *
+ * ## The envelope BINDS the row's identity
+ *
+ * The additional authenticated data is the owner, the provider and the slug. Moving a sealed value
+ * to a different owner, a different provider or a different slug therefore makes it fail to open —
+ * the seal is not merely "this is a secret", it is "this is THIS owner's secret for THIS provider".
+ * Cut-and-paste of ciphertext between rows is the attack a plain AES-GCM envelope would let through,
+ * and it is exactly the attack a shared multi-tenant table invites.
+ *
+ * ## The SCOPE separates the KEY, not the associated data
+ *
+ * An organization's credential and a person's own credential are sealed under DIFFERENT derived
+ * keys, selected by `ownerScope`. Two reasons, and the second is why it is the key rather than one
+ * more field in the associated data.
+ *
+ * A key split is strictly stronger: with a scope field in the AAD, one derived key protects both
+ * populations, so anything that compromises it compromises both. With separate keys, a user
+ * envelope cannot be opened as an organization envelope even by an attacker who controls the AAD.
+ *
+ * And it PRESERVES what is already stored. Adding a component to the associated data changes the
+ * AAD of every organization envelope ever written, so every credential in every live application
+ * would stop opening the moment this file changed — the failure would surface as "my Slack
+ * integration broke", far from the edit that caused it. Selecting the key domain by scope leaves
+ * the organization derivation and the organization AAD byte-identical, so existing rows are
+ * untouched by construction rather than by care.
+ *
+ * ## A second implementation exists, and this is not it
+ *
+ * `siem-webhook-delivery.backend.service.ts` carries a private AES-256-GCM envelope with the same
+ * shape and its own domain separator. It is deliberately NOT reused or refactored here: that file
+ * belongs to another workstream's territory, its envelope binds no associated data, and it tolerates
+ * plaintext for rows written before it existed — a tolerance this subsystem must not inherit.
+ * Converging the two is real work with a real migration, and it is recorded as such rather than done
+ * opportunistically inside a security slice.
+ */
+import { createCipheriv, createDecipheriv, createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { ExternalProvider_Connection_OwnerScope } from '@wildo-ai/external-connectors-models';
+/**
+ * Domain separators, one per owner scope. Changing one of these strings makes every credential
+ * stored under it unopenable, so they are versioned constants rather than descriptions: if a
+ * derivation ever has to change, the new scheme gets a new prefix and a migration, never an edit
+ * here.
+ *
+ * The ORGANIZATION value predates the USER scope and is reproduced exactly — every organization
+ * credential in every live application is sealed under it.
+ *
+ * Total over the two scopes that reach a store. APPLICATION is deliberately absent rather than
+ * mapped to something: the application's own credential lives in the deployment environment and
+ * never enters this module, so a call arriving with that scope is a routing defect, and giving it a
+ * key would let the defect store a row instead of announcing itself.
+ */
+const PROVIDER_CREDENTIAL_KEY_DOMAINS = {
+    [ExternalProvider_Connection_OwnerScope.ORGANIZATION]: 'wildo:organization-provider-credential:v1',
+    [ExternalProvider_Connection_OwnerScope.USER]: 'wildo:user-provider-credential:v1',
+};
+/**
+ * Envelope prefix. Present so a stored value can be RECOGNISED as sealed without attempting to
+ * decrypt it — which is what lets the write path refuse to persist an unsealed value, rather than
+ * discovering the problem at read time when the plaintext is already at rest.
+ */
+export const PROVIDER_CREDENTIAL_ENVELOPE_PREFIX = 'wildo-sealed:aes-256-gcm:';
+/** 96 bits — the GCM nonce size every implementation agrees on. */
+const IV_BYTE_LENGTH = 12;
+const AUTH_TAG_BYTE_LENGTH = 16;
+/**
+ * An even-length run of hex digits and nothing else.
+ *
+ * Even-length because two hex characters encode one byte — an odd-length component cannot have come
+ * from `Buffer.toString('hex')`, and `Buffer.from` would drop the trailing nibble without complaint.
+ */
+const STRICT_HEX = /^(?:[0-9a-fA-F]{2})+$/;
+/**
+ * The separator inside the associated data.
+ *
+ * A NUL, not a colon, and that is what makes the encoding injective: with a `:` join,
+ * `('org', 'a:b', 'c')` and `('org', 'a', 'b:c')` produce IDENTICAL associated data, so a sealed
+ * value could be moved between two rows whose identities differ only in where a colon falls. A NUL
+ * cannot appear in any of the three components — they come from an id generator and from
+ * schema-validated identifiers — so no two distinct identities can collide.
+ */
+const BINDING_SEPARATOR = '\u0000';
+/** Raised when a sealed value cannot be sealed or opened. Never carries the value or any part of it. */
+export class ProviderCredentialEnvelopeError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ProviderCredentialEnvelopeError';
+    }
+}
+/**
+ * Derive this subsystem's 32-byte key for one owner scope from the platform's base key material.
+ *
+ * The refusal on a short or absent base key is deliberate and loud. The alternative — deriving from
+ * whatever is there — would produce a working seal from a misconfigured application, and every
+ * credential stored under it would be protected by a key an attacker could guess. A configuration
+ * error must not be survivable here.
+ *
+ * The refusal on an unknown scope is the same posture applied to the routing question: a scope with
+ * no domain must not silently fall back to another scope's key, because that would seal a person's
+ * credential under the tenant key and make it openable by the wrong half of the system.
+ */
+function deriveProviderCredentialKey(baseEncryptionKey, ownerScope) {
+    if (typeof baseEncryptionKey !== 'string' || baseEncryptionKey.length < 32) {
+        throw new ProviderCredentialEnvelopeError('Cannot seal or open a provider credential: the application\'s '
+            + 'secrets.security.session.encryptionKey is absent or shorter than the 32 characters the platform '
+            + 'guarantees. This is a provisioning fault, not a runtime condition — an application reaching this '
+            + 'point would store credentials under a guessable key.');
+    }
+    const domain = PROVIDER_CREDENTIAL_KEY_DOMAINS[ownerScope];
+    if (!domain) {
+        throw new ProviderCredentialEnvelopeError(`Cannot seal or open a provider credential owned at scope '${ownerScope}': only ORGANIZATION and USER `
+            + 'credentials are stored. An APPLICATION credential lives in the deployment environment and never '
+            + 'reaches this module, so arriving here with one is a resolution defect rather than a missing key.');
+    }
+    return createHash('sha256').update(`${domain}:${baseEncryptionKey}`).digest();
+}
+/**
+ * The additional authenticated data — the row identity, unambiguously encoded.
+ *
+ * The SCOPE is deliberately not a component: it selects the key instead (module JSDoc), which both
+ * separates the two populations more strongly and leaves the encoding of an organization row exactly
+ * as it was before the USER scope existed.
+ */
+function encodeBinding(binding) {
+    return Buffer.from([binding.ownerId, binding.providerRef, binding.secretSlug].join(BINDING_SEPARATOR), 'utf8');
+}
+/** Whether a stored value is a sealed envelope. Cheap, and does not need the key. */
+export function isSealedProviderCredential(value) {
+    return typeof value === 'string' && value.startsWith(PROVIDER_CREDENTIAL_ENVELOPE_PREFIX);
+}
+/**
+ * Seal a plaintext credential for storage.
+ *
+ * Format: `wildo-sealed:aes-256-gcm:<iv hex>:<auth tag hex>:<ciphertext hex>`.
+ */
+export function sealProviderCredential(plaintext, baseEncryptionKey, binding) {
+    if (typeof plaintext !== 'string' || plaintext.length === 0) {
+        throw new ProviderCredentialEnvelopeError('Refusing to seal an empty provider credential.');
+    }
+    // Sealing an already-sealed value would double-wrap it, and the second open would return an
+    // envelope string that a provider would then receive as its credential. Refuse rather than nest.
+    if (isSealedProviderCredential(plaintext)) {
+        throw new ProviderCredentialEnvelopeError('Refusing to seal a value that is already a sealed envelope — double-sealing would hand the envelope '
+            + 'itself to the provider on the next open.');
+    }
+    const key = deriveProviderCredentialKey(baseEncryptionKey, binding.ownerScope);
+    const iv = randomBytes(IV_BYTE_LENGTH);
+    const cipher = createCipheriv('aes-256-gcm', key, iv);
+    cipher.setAAD(encodeBinding(binding));
+    const ciphertext = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
+    const authTag = cipher.getAuthTag();
+    return `${PROVIDER_CREDENTIAL_ENVELOPE_PREFIX}${iv.toString('hex')}:${authTag.toString('hex')}:${ciphertext.toString('hex')}`;
+}
+/**
+ * Open a sealed credential.
+ *
+ * Every failure — a malformed envelope, a wrong key, a tampered ciphertext, a value lifted from
+ * another tenant's row — raises the SAME error type with a message that names the row and nothing
+ * else. Distinguishing the causes in the message would tell an attacker holding write access which
+ * of their manipulations got closer.
+ *
+ * Plaintext is REFUSED rather than passed through. The SIEM sibling tolerates it because it has rows
+ * predating its own encryption; this subsystem shipped sealed, so a plaintext value in the store can
+ * only mean the write path was bypassed — a fact worth failing on, not one worth quietly working
+ * around.
+ */
+export function openProviderCredential(sealedValue, baseEncryptionKey, binding) {
+    const rowDescription = `${binding.ownerScope} '${binding.ownerId}', provider '${binding.providerRef}', slug '${binding.secretSlug}'`;
+    if (!isSealedProviderCredential(sealedValue)) {
+        throw new ProviderCredentialEnvelopeError(`Stored provider credential for ${rowDescription} is not a sealed envelope. Credentials are sealed on `
+            + 'write, so an unsealed value means the row was written by something other than the credential write '
+            + 'path. Rotate it through the credential resource.');
+    }
+    const parts = sealedValue.slice(PROVIDER_CREDENTIAL_ENVELOPE_PREFIX.length).split(':');
+    if (parts.length !== 3) {
+        throw new ProviderCredentialEnvelopeError(`Provider credential for ${rowDescription} cannot be opened.`);
+    }
+    const [ivHex, authTagHex, ciphertextHex] = parts;
+    try {
+        // STRICT hex first, before any decoding. `Buffer.from(value, 'hex')` does not throw on invalid
+        // input — it silently STOPS at the first non-hex character and returns the prefix it managed to
+        // decode. So a stored envelope with trailing garbage would decode to exactly the original bytes
+        // and open successfully, and a component with junk in the middle would decode to a short buffer
+        // that the length checks below might still accept.
+        //
+        // That is not a break of the seal (GCM still authenticates the bytes it is given, so nobody can
+        // CHANGE the credential this way) but it does mean a value that is not what was written could be
+        // accepted as if it were. This module's posture everywhere else is that a stored value which the
+        // write path could not have produced is a fault worth failing on, and this is the same rule.
+        // Found by a pin whose "tampered" fixture appended non-hex characters and opened anyway.
+        if (!STRICT_HEX.test(ivHex) || !STRICT_HEX.test(authTagHex) || !STRICT_HEX.test(ciphertextHex)) {
+            throw new Error('malformed envelope components');
+        }
+        const iv = Buffer.from(ivHex, 'hex');
+        const authTag = Buffer.from(authTagHex, 'hex');
+        const ciphertext = Buffer.from(ciphertextHex, 'hex');
+        // `createDecipheriv` accepts a wrong-length IV for GCM, and a wrong-length tag is rejected only
+        // at `final()`. Both are checked here: a truncated tag is the classic GCM forgery attempt, and it
+        // should be refused before any decryption work happens.
+        if (iv.length !== IV_BYTE_LENGTH || authTag.length !== AUTH_TAG_BYTE_LENGTH || ciphertext.length === 0) {
+            throw new Error('malformed envelope components');
+        }
+        const key = deriveProviderCredentialKey(baseEncryptionKey, binding.ownerScope);
+        const decipher = createDecipheriv('aes-256-gcm', key, iv);
+        decipher.setAAD(encodeBinding(binding));
+        decipher.setAuthTag(authTag);
+        const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString('utf8');
+        if (plaintext.length === 0) {
+            throw new Error('empty plaintext');
+        }
+        return plaintext;
+    }
+    catch (error) {
+        // The cause is deliberately NOT propagated: a crypto-layer message is uninformative to an
+        // operator and informative to an attacker probing the envelope.
+        if (error instanceof ProviderCredentialEnvelopeError) {
+            throw error;
+        }
+        throw new ProviderCredentialEnvelopeError(`Provider credential for ${rowDescription} cannot be opened. Either it was sealed under different key `
+            + 'material, or the stored value has been altered. Rotate the credential through the credential resource.');
+    }
+}
+/**
+ * Whether two sealed envelopes are byte-identical, WITHOUT opening either.
+ *
+ * Returns false whenever it cannot tell — which, because the IV is random per seal, is almost always
+ * for two independent seals of the same secret. That is the honest answer and the reason this
+ * exists: the write path needs to know whether the stored value actually changed so it can emit a
+ * rotation event rather than a set event, and the only alternative was to open both and compare
+ * plaintexts, which puts two secrets in memory to answer a bookkeeping question. A false negative
+ * costs a slightly noisier audit trail; opening the values costs the property this module exists to
+ * hold.
+ */
+export function sealedProviderCredentialsAreIdentical(left, right) {
+    if (!isSealedProviderCredential(left) || !isSealedProviderCredential(right)) {
+        return false;
+    }
+    const leftBuffer = Buffer.from(left, 'utf8');
+    const rightBuffer = Buffer.from(right, 'utf8');
+    if (leftBuffer.length !== rightBuffer.length) {
+        return false;
+    }
+    return timingSafeEqual(leftBuffer, rightBuffer);
+}
+//# sourceMappingURL=provider-credential-envelope.backend.utils.js.map

package/dist/esm/security/connected-accounts/utils/provider-credential-envelope.backend.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-credential-envelope.backend.utils.js","sourceRoot":"","sources":["../../../../../../src/security/connected-accounts/utils/provider-credential-envelope.backend.utils.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Sealing an OWNER's provider credential at rest — an organization's, or a person's own.\n *\n * ## What this is for\n *\n * A credential toward a third party is stored in the application's own database, in a row its owner\n * can create over HTTP. A database backup, a snapshot handed to a support engineer, or a read\n * replica reached through an unrelated defect would otherwise expose every stored vendor credential\n * in plaintext. Sealing them does not make the store safe to lose — nothing does — but it means\n * losing the store is not the same event as losing every tenant's and every person's Slack, CRM and\n * SMTP access.\n *\n * ## The key is the platform's existing material, deliberately\n *\n * `secrets.security.session.encryptionKey` is provisioned for every application by the platform\n * (apps-manager mints it, the schema requires at least 32 characters, and readiness refuses an\n * application without one). Introducing a second key here would mean a second thing to provision, a\n * second thing to rotate, and a second way for an application to be half-configured — and the first\n * application to hit that would discover it as \"my credentials cannot be decrypted\", after the\n * values were already stored.\n *\n * The base key is NOT used directly. It is domain-separated through SHA-256 so this subsystem's key\n * is unrelated to the session subsystem's, and to the SIEM delivery subsystem's, even though all\n * three derive from the same material. Without the separator, a weakness or an oracle in one becomes\n * a weakness in the others.\n *\n * ## AES-256-GCM, and why authentication is the load-bearing half\n *\n * GCM authenticates as well as encrypts, so a modified ciphertext FAILS rather than decrypting to\n * garbage. That matters more than the confidentiality here: an attacker with write access to the\n * store but not the key must not be able to flip a tenant's credential to a value of their choosing,\n * or to swap tenant A's sealed credential into tenant B's row and have it silently work. The\n * associated data below closes the second half of that.\n *\n * ## The envelope BINDS the row's identity\n *\n * The additional authenticated data is the owner, the provider and the slug. Moving a sealed value\n * to a different owner, a different provider or a different slug therefore makes it fail to open —\n * the seal is not merely \"this is a secret\", it is \"this is THIS owner's secret for THIS provider\".\n * Cut-and-paste of ciphertext between rows is the attack a plain AES-GCM envelope would let through,\n * and it is exactly the attack a shared multi-tenant table invites.\n *\n * ## The SCOPE separates the KEY, not the associated data\n *\n * An organization's credential and a person's own credential are sealed under DIFFERENT derived\n * keys, selected by `ownerScope`. Two reasons, and the second is why it is the key rather than one\n * more field in the associated data.\n *\n * A key split is strictly stronger: with a scope field in the AAD, one derived key protects both\n * populations, so anything that compromises it compromises both. With separate keys, a user\n * envelope cannot be opened as an organization envelope even by an attacker who controls the AAD.\n *\n * And it PRESERVES what is already stored. Adding a component to the associated data changes the\n * AAD of every organization envelope ever written, so every credential in every live application\n * would stop opening the moment this file changed — the failure would surface as \"my Slack\n * integration broke\", far from the edit that caused it. Selecting the key domain by scope leaves\n * the organization derivation and the organization AAD byte-identical, so existing rows are\n * untouched by construction rather than by care.\n *\n * ## A second implementation exists, and this is not it\n *\n * `siem-webhook-delivery.backend.service.ts` carries a private AES-256-GCM envelope with the same\n * shape and its own domain separator. It is deliberately NOT reused or refactored here: that file\n * belongs to another workstream's territory, its envelope binds no associated data, and it tolerates\n * plaintext for rows written before it existed — a tolerance this subsystem must not inherit.\n * Converging the two is real work with a real migration, and it is recorded as such rather than done\n * opportunistically inside a security slice.\n */\n\nimport { createCipheriv, createDecipheriv, createHash, randomBytes, timingSafeEqual } from 'node:crypto';\n\nimport { ExternalProvider_Connection_OwnerScope } from '@wildo-ai/external-connectors-models';\n\n/**\n * Domain separators, one per owner scope. Changing one of these strings makes every credential\n * stored under it unopenable, so they are versioned constants rather than descriptions: if a\n * derivation ever has to change, the new scheme gets a new prefix and a migration, never an edit\n * here.\n *\n * The ORGANIZATION value predates the USER scope and is reproduced exactly — every organization\n * credential in every live application is sealed under it.\n *\n * Total over the two scopes that reach a store. APPLICATION is deliberately absent rather than\n * mapped to something: the application's own credential lives in the deployment environment and\n * never enters this module, so a call arriving with that scope is a routing defect, and giving it a\n * key would let the defect store a row instead of announcing itself.\n */\nconst PROVIDER_CREDENTIAL_KEY_DOMAINS: Readonly<Record<\n  ExternalProvider_Connection_OwnerScope.ORGANIZATION | ExternalProvider_Connection_OwnerScope.USER,\n  string\n>> = {\n  [ExternalProvider_Connection_OwnerScope.ORGANIZATION]: 'wildo:organization-provider-credential:v1',\n  [ExternalProvider_Connection_OwnerScope.USER]: 'wildo:user-provider-credential:v1',\n};\n\n/**\n * Envelope prefix. Present so a stored value can be RECOGNISED as sealed without attempting to\n * decrypt it — which is what lets the write path refuse to persist an unsealed value, rather than\n * discovering the problem at read time when the plaintext is already at rest.\n */\nexport const PROVIDER_CREDENTIAL_ENVELOPE_PREFIX = 'wildo-sealed:aes-256-gcm:';\n\n/** 96 bits — the GCM nonce size every implementation agrees on. */\nconst IV_BYTE_LENGTH = 12;\nconst AUTH_TAG_BYTE_LENGTH = 16;\n\n/**\n * An even-length run of hex digits and nothing else.\n *\n * Even-length because two hex characters encode one byte — an odd-length component cannot have come\n * from `Buffer.toString('hex')`, and `Buffer.from` would drop the trailing nibble without complaint.\n */\nconst STRICT_HEX = /^(?:[0-9a-fA-F]{2})+$/;\n\n/**\n * The separator inside the associated data.\n *\n * A NUL, not a colon, and that is what makes the encoding injective: with a `:` join,\n * `('org', 'a:b', 'c')` and `('org', 'a', 'b:c')` produce IDENTICAL associated data, so a sealed\n * value could be moved between two rows whose identities differ only in where a colon falls. A NUL\n * cannot appear in any of the three components — they come from an id generator and from\n * schema-validated identifiers — so no two distinct identities can collide.\n */\nconst BINDING_SEPARATOR = '\\u0000';\n\n/** Raised when a sealed value cannot be sealed or opened. Never carries the value or any part of it. */\nexport class ProviderCredentialEnvelopeError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'ProviderCredentialEnvelopeError';\n  }\n}\n\n/**\n * The row identity a sealed value is bound to. All four are required — see the module JSDoc.\n *\n * `ownerId` is the organization id or the user id, per `ownerScope`. One field rather than two\n * optional ones, because exactly one owner exists per row and a shape with two nullable ids can\n * represent a row with neither — a state the seal would then bind to nothing.\n */\nexport interface ProviderCredentialEnvelopeBinding {\n  ownerScope: ExternalProvider_Connection_OwnerScope.ORGANIZATION | ExternalProvider_Connection_OwnerScope.USER;\n  ownerId: string;\n  providerRef: string;\n  secretSlug: string;\n}\n\n/**\n * Derive this subsystem's 32-byte key for one owner scope from the platform's base key material.\n *\n * The refusal on a short or absent base key is deliberate and loud. The alternative — deriving from\n * whatever is there — would produce a working seal from a misconfigured application, and every\n * credential stored under it would be protected by a key an attacker could guess. A configuration\n * error must not be survivable here.\n *\n * The refusal on an unknown scope is the same posture applied to the routing question: a scope with\n * no domain must not silently fall back to another scope's key, because that would seal a person's\n * credential under the tenant key and make it openable by the wrong half of the system.\n */\nfunction deriveProviderCredentialKey(\n  baseEncryptionKey: string,\n  ownerScope: ProviderCredentialEnvelopeBinding['ownerScope'],\n): Buffer {\n  if (typeof baseEncryptionKey !== 'string' || baseEncryptionKey.length < 32) {\n    throw new ProviderCredentialEnvelopeError(\n      'Cannot seal or open a provider credential: the application\\'s '\n      + 'secrets.security.session.encryptionKey is absent or shorter than the 32 characters the platform '\n      + 'guarantees. This is a provisioning fault, not a runtime condition — an application reaching this '\n      + 'point would store credentials under a guessable key.',\n    );\n  }\n  const domain = PROVIDER_CREDENTIAL_KEY_DOMAINS[ownerScope];\n  if (!domain) {\n    throw new ProviderCredentialEnvelopeError(\n      `Cannot seal or open a provider credential owned at scope '${ownerScope}': only ORGANIZATION and USER `\n      + 'credentials are stored. An APPLICATION credential lives in the deployment environment and never '\n      + 'reaches this module, so arriving here with one is a resolution defect rather than a missing key.',\n    );\n  }\n  return createHash('sha256').update(`${domain}:${baseEncryptionKey}`).digest();\n}\n\n/**\n * The additional authenticated data — the row identity, unambiguously encoded.\n *\n * The SCOPE is deliberately not a component: it selects the key instead (module JSDoc), which both\n * separates the two populations more strongly and leaves the encoding of an organization row exactly\n * as it was before the USER scope existed.\n */\nfunction encodeBinding(binding: ProviderCredentialEnvelopeBinding): Buffer {\n  return Buffer.from(\n    [binding.ownerId, binding.providerRef, binding.secretSlug].join(BINDING_SEPARATOR),\n    'utf8',\n  );\n}\n\n/** Whether a stored value is a sealed envelope. Cheap, and does not need the key. */\nexport function isSealedProviderCredential(value: string | undefined | null): boolean {\n  return typeof value === 'string' && value.startsWith(PROVIDER_CREDENTIAL_ENVELOPE_PREFIX);\n}\n\n/**\n * Seal a plaintext credential for storage.\n *\n * Format: `wildo-sealed:aes-256-gcm:<iv hex>:<auth tag hex>:<ciphertext hex>`.\n */\nexport function sealProviderCredential(\n  plaintext: string,\n  baseEncryptionKey: string,\n  binding: ProviderCredentialEnvelopeBinding,\n): string {\n  if (typeof plaintext !== 'string' || plaintext.length === 0) {\n    throw new ProviderCredentialEnvelopeError('Refusing to seal an empty provider credential.');\n  }\n  // Sealing an already-sealed value would double-wrap it, and the second open would return an\n  // envelope string that a provider would then receive as its credential. Refuse rather than nest.\n  if (isSealedProviderCredential(plaintext)) {\n    throw new ProviderCredentialEnvelopeError(\n      'Refusing to seal a value that is already a sealed envelope — double-sealing would hand the envelope '\n      + 'itself to the provider on the next open.',\n    );\n  }\n\n  const key = deriveProviderCredentialKey(baseEncryptionKey, binding.ownerScope);\n  const iv = randomBytes(IV_BYTE_LENGTH);\n  const cipher = createCipheriv('aes-256-gcm', key, iv);\n  cipher.setAAD(encodeBinding(binding));\n\n  const ciphertext = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);\n  const authTag = cipher.getAuthTag();\n\n  return `${PROVIDER_CREDENTIAL_ENVELOPE_PREFIX}${iv.toString('hex')}:${authTag.toString('hex')}:${ciphertext.toString('hex')}`;\n}\n\n/**\n * Open a sealed credential.\n *\n * Every failure — a malformed envelope, a wrong key, a tampered ciphertext, a value lifted from\n * another tenant's row — raises the SAME error type with a message that names the row and nothing\n * else. Distinguishing the causes in the message would tell an attacker holding write access which\n * of their manipulations got closer.\n *\n * Plaintext is REFUSED rather than passed through. The SIEM sibling tolerates it because it has rows\n * predating its own encryption; this subsystem shipped sealed, so a plaintext value in the store can\n * only mean the write path was bypassed — a fact worth failing on, not one worth quietly working\n * around.\n */\nexport function openProviderCredential(\n  sealedValue: string,\n  baseEncryptionKey: string,\n  binding: ProviderCredentialEnvelopeBinding,\n): string {\n  const rowDescription =\n    `${binding.ownerScope} '${binding.ownerId}', provider '${binding.providerRef}', slug '${binding.secretSlug}'`;\n\n  if (!isSealedProviderCredential(sealedValue)) {\n    throw new ProviderCredentialEnvelopeError(\n      `Stored provider credential for ${rowDescription} is not a sealed envelope. Credentials are sealed on `\n      + 'write, so an unsealed value means the row was written by something other than the credential write '\n      + 'path. Rotate it through the credential resource.',\n    );\n  }\n\n  const parts = sealedValue.slice(PROVIDER_CREDENTIAL_ENVELOPE_PREFIX.length).split(':');\n  if (parts.length !== 3) {\n    throw new ProviderCredentialEnvelopeError(`Provider credential for ${rowDescription} cannot be opened.`);\n  }\n  const [ivHex, authTagHex, ciphertextHex] = parts as [string, string, string];\n\n  try {\n    // STRICT hex first, before any decoding. `Buffer.from(value, 'hex')` does not throw on invalid\n    // input — it silently STOPS at the first non-hex character and returns the prefix it managed to\n    // decode. So a stored envelope with trailing garbage would decode to exactly the original bytes\n    // and open successfully, and a component with junk in the middle would decode to a short buffer\n    // that the length checks below might still accept.\n    //\n    // That is not a break of the seal (GCM still authenticates the bytes it is given, so nobody can\n    // CHANGE the credential this way) but it does mean a value that is not what was written could be\n    // accepted as if it were. This module's posture everywhere else is that a stored value which the\n    // write path could not have produced is a fault worth failing on, and this is the same rule.\n    // Found by a pin whose \"tampered\" fixture appended non-hex characters and opened anyway.\n    if (!STRICT_HEX.test(ivHex) || !STRICT_HEX.test(authTagHex) || !STRICT_HEX.test(ciphertextHex)) {\n      throw new Error('malformed envelope components');\n    }\n\n    const iv = Buffer.from(ivHex, 'hex');\n    const authTag = Buffer.from(authTagHex, 'hex');\n    const ciphertext = Buffer.from(ciphertextHex, 'hex');\n\n    // `createDecipheriv` accepts a wrong-length IV for GCM, and a wrong-length tag is rejected only\n    // at `final()`. Both are checked here: a truncated tag is the classic GCM forgery attempt, and it\n    // should be refused before any decryption work happens.\n    if (iv.length !== IV_BYTE_LENGTH || authTag.length !== AUTH_TAG_BYTE_LENGTH || ciphertext.length === 0) {\n      throw new Error('malformed envelope components');\n    }\n\n    const key = deriveProviderCredentialKey(baseEncryptionKey, binding.ownerScope);\n    const decipher = createDecipheriv('aes-256-gcm', key, iv);\n    decipher.setAAD(encodeBinding(binding));\n    decipher.setAuthTag(authTag);\n\n    const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]).toString('utf8');\n    if (plaintext.length === 0) {\n      throw new Error('empty plaintext');\n    }\n    return plaintext;\n  } catch (error) {\n    // The cause is deliberately NOT propagated: a crypto-layer message is uninformative to an\n    // operator and informative to an attacker probing the envelope.\n    if (error instanceof ProviderCredentialEnvelopeError) {\n      throw error;\n    }\n    throw new ProviderCredentialEnvelopeError(\n      `Provider credential for ${rowDescription} cannot be opened. Either it was sealed under different key `\n      + 'material, or the stored value has been altered. Rotate the credential through the credential resource.',\n    );\n  }\n}\n\n/**\n * Whether two sealed envelopes are byte-identical, WITHOUT opening either.\n *\n * Returns false whenever it cannot tell — which, because the IV is random per seal, is almost always\n * for two independent seals of the same secret. That is the honest answer and the reason this\n * exists: the write path needs to know whether the stored value actually changed so it can emit a\n * rotation event rather than a set event, and the only alternative was to open both and compare\n * plaintexts, which puts two secrets in memory to answer a bookkeeping question. A false negative\n * costs a slightly noisier audit trail; opening the values costs the property this module exists to\n * hold.\n */\nexport function sealedProviderCredentialsAreIdentical(left: string, right: string): boolean {\n  if (!isSealedProviderCredential(left) || !isSealedProviderCredential(right)) {\n    return false;\n  }\n  const leftBuffer = Buffer.from(left, 'utf8');\n  const rightBuffer = Buffer.from(right, 'utf8');\n  if (leftBuffer.length !== rightBuffer.length) {\n    return false;\n  }\n  return timingSafeEqual(leftBuffer, rightBuffer);\n}\n"]}

package/dist/esm/security/connected-accounts/utils/stored-credential-value.backend.utils.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Turning what a credential row STORES into what goes on the wire.
+ *
+ * Two things can be sealed into `secretValue`, and they are spent differently:
+ *
+ * - a credential a person PASTED, which is already the wire value;
+ * - an OAuth2 grant a vendor MINTED, whose wire value is one field of a JSON document.
+ *
+ * This is the single place that distinction is resolved. It exists as one function rather than a
+ * branch in each store because both stores — organization and user — hold both shapes, and an
+ * invariant applied at one of its two call sites is this repository's most repeated defect. The
+ * failure it prevents is specific and silent: a store that returned the opened plaintext directly
+ * would put `wildo-oauth2-grant:{"kind":…}` on the wire as a bearer token, and the vendor's 401
+ * would name a credential problem rather than a serialization one.
+ *
+ * assurance-control: WILDO.IDENTITY.DELEGATED_AUTHORIZATION — the token actually presented to a
+ * third party is derived from the stored grant rather than from whatever the field happens to hold.
+ */
+import { type ProviderOAuth2Grant } from '@wildo-ai/saas-models';
+/** Raised when a stored credential cannot be turned into a wire value. Never carries the value. */
+export declare class StoredCredentialValueError extends Error {
+    constructor(message: string);
+}
+export interface ResolvedStoredCredential {
+    /**
+     * What goes in the Authorization header.
+     *
+     * Empty string when {@link needsRefresh} is set — there is no honest wire value for a grant that
+     * must be renewed first, and returning the expired token would let a caller that ignored the flag
+     * send it. A caller must branch on `needsRefresh` before reading this.
+     */
+    readonly wireValue: string;
+    /**
+     * The grant is expiring and a refresher is available: the caller must renew it, persist the
+     * result, and use the renewed access token.
+     *
+     * A FLAG rather than a refresh performed here, because renewing needs the provider contract and
+     * the application's registration while persisting needs the table and the envelope key — and this
+     * function is a pure transformation with neither.
+     */
+    readonly needsRefresh?: true;
+    /**
+     * The grant it came from, when it came from one. Carried out so a caller can record what the
+     * vendor granted, or refresh it — and ABSENT for a pasted credential, which is what lets a caller
+     * tell the two apart without re-parsing.
+     */
+    readonly grant?: ProviderOAuth2Grant;
+}
+/**
+ * Resolve the opened plaintext of one credential row into the value a request should carry.
+ *
+ * @param plaintext the opened envelope contents — already decrypted, never the sealed form.
+ * @param describeRow how to name the row in a refusal. Never the value, and never the owner's id
+ *   alone: an operator reading a log needs the provider and slug to act.
+ */
+export declare function resolveStoredCredentialValue(plaintext: string, describeRow: string, 
+/**
+ * Whether the caller can actually renew an expiring grant.
+ *
+ * Passed in rather than assumed, so the two outcomes stay distinguishable: with a refresher this
+ * returns `needsRefresh` and the caller renews; without one it REFUSES, naming the missing
+ * subsystem. Defaulting to "yes" would have a store with no refresher return `needsRefresh` and
+ * then dereference a refresher it does not hold.
+ */
+canRefresh?: boolean): ResolvedStoredCredential;
+//# sourceMappingURL=stored-credential-value.backend.utils.d.ts.map

package/dist/esm/security/connected-accounts/utils/stored-credential-value.backend.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stored-credential-value.backend.utils.d.ts","sourceRoot":"","sources":["../../../../../../src/security/connected-accounts/utils/stored-credential-value.backend.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAGL,KAAK,mBAAmB,EACzB,MAAM,uBAAuB,CAAC;AAE/B,mGAAmG;AACnG,qBAAa,0BAA2B,SAAQ,KAAK;gBACvC,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,WAAW,wBAAwB;IACvC;;;;;;OAMG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;;;OAOG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,IAAI,CAAC;IAC7B;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,mBAAmB,CAAC;CACtC;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM;AACnB;;;;;;;GAOG;AACH,UAAU,UAAQ,GACjB,wBAAwB,CAmC1B"}

package/dist/esm/security/connected-accounts/utils/stored-credential-value.backend.utils.js

@@ -0,0 +1,75 @@
+/**
+ * Turning what a credential row STORES into what goes on the wire.
+ *
+ * Two things can be sealed into `secretValue`, and they are spent differently:
+ *
+ * - a credential a person PASTED, which is already the wire value;
+ * - an OAuth2 grant a vendor MINTED, whose wire value is one field of a JSON document.
+ *
+ * This is the single place that distinction is resolved. It exists as one function rather than a
+ * branch in each store because both stores — organization and user — hold both shapes, and an
+ * invariant applied at one of its two call sites is this repository's most repeated defect. The
+ * failure it prevents is specific and silent: a store that returned the opened plaintext directly
+ * would put `wildo-oauth2-grant:{"kind":…}` on the wire as a bearer token, and the vendor's 401
+ * would name a credential problem rather than a serialization one.
+ *
+ * assurance-control: WILDO.IDENTITY.DELEGATED_AUTHORIZATION — the token actually presented to a
+ * third party is derived from the stored grant rather than from whatever the field happens to hold.
+ */
+import { parseProviderOAuth2Grant, providerOAuth2GrantNeedsRefresh, } from '@wildo-ai/saas-models';
+/** Raised when a stored credential cannot be turned into a wire value. Never carries the value. */
+export class StoredCredentialValueError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'StoredCredentialValueError';
+    }
+}
+/**
+ * Resolve the opened plaintext of one credential row into the value a request should carry.
+ *
+ * @param plaintext the opened envelope contents — already decrypted, never the sealed form.
+ * @param describeRow how to name the row in a refusal. Never the value, and never the owner's id
+ *   alone: an operator reading a log needs the provider and slug to act.
+ */
+export function resolveStoredCredentialValue(plaintext, describeRow, 
+/**
+ * Whether the caller can actually renew an expiring grant.
+ *
+ * Passed in rather than assumed, so the two outcomes stay distinguishable: with a refresher this
+ * returns `needsRefresh` and the caller renews; without one it REFUSES, naming the missing
+ * subsystem. Defaulting to "yes" would have a store with no refresher return `needsRefresh` and
+ * then dereference a refresher it does not hold.
+ */
+canRefresh = false) {
+    // Throws when the value announces itself as a grant and is not one — deliberately not caught. A
+    // credential claiming a shape it does not have was written by something other than the exchange,
+    // and falling back to "treat it as pasted" would send the malformed document itself as a token.
+    const grant = parseProviderOAuth2Grant(plaintext);
+    if (grant === undefined) {
+        return { wireValue: plaintext };
+    }
+    if (providerOAuth2GrantNeedsRefresh(grant)) {
+        if (canRefresh) {
+            return { wireValue: '', grant, needsRefresh: true };
+        }
+        // Fail CLOSED, and name the missing subsystem rather than the credential.
+        //
+        // The alternative — send it anyway and let the vendor reject it — was rejected: the 401 comes
+        // back as an authentication failure, the row is stamped INVALID, and the person reading their
+        // connections is told their credential is bad when it is merely stale. That is a false statement
+        // about their account, and it points them at reconnecting rather than at the refresh that does
+        // not run.
+        //
+        // The population is NO LONGER empty. This was written when nothing could store a grant, so the
+        // refusal was unreachable; the authorization exchange has since landed and real grants are
+        // stored, which makes this the live answer whenever a store is constructed without a refresher.
+        // The engine's container always binds one — pinned in `container-boot-graph-resolves.test.ts`,
+        // because the injection is `@optional()` and an absent binding is otherwise silent for about an
+        // hour. So reaching this in a running application means the wiring is wrong, not the credential.
+        throw new StoredCredentialValueError(`The OAuth2 grant for ${describeRow} has expired or is within the refresh window, and no token `
+            + 'refresher is wired to renew it. The stored credential is not at fault — reconnecting would '
+            + 'work, and so would the refresh exchange once it exists.');
+    }
+    return { wireValue: grant.accessToken, grant };
+}
+//# sourceMappingURL=stored-credential-value.backend.utils.js.map

package/dist/esm/security/connected-accounts/utils/stored-credential-value.backend.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stored-credential-value.backend.utils.js","sourceRoot":"","sources":["../../../../../../src/security/connected-accounts/utils/stored-credential-value.backend.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EACL,wBAAwB,EACxB,+BAA+B,GAEhC,MAAM,uBAAuB,CAAC;AAE/B,mGAAmG;AACnG,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IACnD,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,4BAA4B,CAAC;IAC3C,CAAC;CACF;AA4BD;;;;;;GAMG;AACH,MAAM,UAAU,4BAA4B,CAC1C,SAAiB,EACjB,WAAmB;AACnB;;;;;;;GAOG;AACH,UAAU,GAAG,KAAK;IAElB,gGAAgG;IAChG,iGAAiG;IACjG,gGAAgG;IAChG,MAAM,KAAK,GAAG,wBAAwB,CAAC,SAAS,CAAC,CAAC;IAClD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QACxB,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC;IAClC,CAAC;IAED,IAAI,+BAA+B,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3C,IAAI,UAAU,EAAE,CAAC;YACf,OAAO,EAAE,SAAS,EAAE,EAAE,EAAE,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;QACtD,CAAC;QACD,0EAA0E;QAC1E,EAAE;QACF,8FAA8F;QAC9F,8FAA8F;QAC9F,iGAAiG;QACjG,+FAA+F;QAC/F,WAAW;QACX,EAAE;QACF,+FAA+F;QAC/F,2FAA2F;QAC3F,gGAAgG;QAChG,+FAA+F;QAC/F,gGAAgG;QAChG,iGAAiG;QACjG,MAAM,IAAI,0BAA0B,CAClC,wBAAwB,WAAW,6DAA6D;cAC9F,6FAA6F;cAC7F,yDAAyD,CAC5D,CAAC;IACJ,CAAC;IAED,OAAO,EAAE,SAAS,EAAE,KAAK,CAAC,WAAW,EAAE,KAAK,EAAE,CAAC;AACjD,CAAC","sourcesContent":["/**\n * Turning what a credential row STORES into what goes on the wire.\n *\n * Two things can be sealed into `secretValue`, and they are spent differently:\n *\n * - a credential a person PASTED, which is already the wire value;\n * - an OAuth2 grant a vendor MINTED, whose wire value is one field of a JSON document.\n *\n * This is the single place that distinction is resolved. It exists as one function rather than a\n * branch in each store because both stores — organization and user — hold both shapes, and an\n * invariant applied at one of its two call sites is this repository's most repeated defect. The\n * failure it prevents is specific and silent: a store that returned the opened plaintext directly\n * would put `wildo-oauth2-grant:{\"kind\":…}` on the wire as a bearer token, and the vendor's 401\n * would name a credential problem rather than a serialization one.\n *\n * assurance-control: WILDO.IDENTITY.DELEGATED_AUTHORIZATION — the token actually presented to a\n * third party is derived from the stored grant rather than from whatever the field happens to hold.\n */\n\nimport {\n  parseProviderOAuth2Grant,\n  providerOAuth2GrantNeedsRefresh,\n  type ProviderOAuth2Grant,\n} from '@wildo-ai/saas-models';\n\n/** Raised when a stored credential cannot be turned into a wire value. Never carries the value. */\nexport class StoredCredentialValueError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = 'StoredCredentialValueError';\n  }\n}\n\nexport interface ResolvedStoredCredential {\n  /**\n   * What goes in the Authorization header.\n   *\n   * Empty string when {@link needsRefresh} is set — there is no honest wire value for a grant that\n   * must be renewed first, and returning the expired token would let a caller that ignored the flag\n   * send it. A caller must branch on `needsRefresh` before reading this.\n   */\n  readonly wireValue: string;\n  /**\n   * The grant is expiring and a refresher is available: the caller must renew it, persist the\n   * result, and use the renewed access token.\n   *\n   * A FLAG rather than a refresh performed here, because renewing needs the provider contract and\n   * the application's registration while persisting needs the table and the envelope key — and this\n   * function is a pure transformation with neither.\n   */\n  readonly needsRefresh?: true;\n  /**\n   * The grant it came from, when it came from one. Carried out so a caller can record what the\n   * vendor granted, or refresh it — and ABSENT for a pasted credential, which is what lets a caller\n   * tell the two apart without re-parsing.\n   */\n  readonly grant?: ProviderOAuth2Grant;\n}\n\n/**\n * Resolve the opened plaintext of one credential row into the value a request should carry.\n *\n * @param plaintext the opened envelope contents — already decrypted, never the sealed form.\n * @param describeRow how to name the row in a refusal. Never the value, and never the owner's id\n *   alone: an operator reading a log needs the provider and slug to act.\n */\nexport function resolveStoredCredentialValue(\n  plaintext: string,\n  describeRow: string,\n  /**\n   * Whether the caller can actually renew an expiring grant.\n   *\n   * Passed in rather than assumed, so the two outcomes stay distinguishable: with a refresher this\n   * returns `needsRefresh` and the caller renews; without one it REFUSES, naming the missing\n   * subsystem. Defaulting to \"yes\" would have a store with no refresher return `needsRefresh` and\n   * then dereference a refresher it does not hold.\n   */\n  canRefresh = false,\n): ResolvedStoredCredential {\n  // Throws when the value announces itself as a grant and is not one — deliberately not caught. A\n  // credential claiming a shape it does not have was written by something other than the exchange,\n  // and falling back to \"treat it as pasted\" would send the malformed document itself as a token.\n  const grant = parseProviderOAuth2Grant(plaintext);\n  if (grant === undefined) {\n    return { wireValue: plaintext };\n  }\n\n  if (providerOAuth2GrantNeedsRefresh(grant)) {\n    if (canRefresh) {\n      return { wireValue: '', grant, needsRefresh: true };\n    }\n    // Fail CLOSED, and name the missing subsystem rather than the credential.\n    //\n    // The alternative — send it anyway and let the vendor reject it — was rejected: the 401 comes\n    // back as an authentication failure, the row is stamped INVALID, and the person reading their\n    // connections is told their credential is bad when it is merely stale. That is a false statement\n    // about their account, and it points them at reconnecting rather than at the refresh that does\n    // not run.\n    //\n    // The population is NO LONGER empty. This was written when nothing could store a grant, so the\n    // refusal was unreachable; the authorization exchange has since landed and real grants are\n    // stored, which makes this the live answer whenever a store is constructed without a refresher.\n    // The engine's container always binds one — pinned in `container-boot-graph-resolves.test.ts`,\n    // because the injection is `@optional()` and an absent binding is otherwise silent for about an\n    // hour. So reaching this in a running application means the wiring is wrong, not the credential.\n    throw new StoredCredentialValueError(\n      `The OAuth2 grant for ${describeRow} has expired or is within the refresh window, and no token `\n      + 'refresher is wired to renew it. The stored credential is not at fault — reconnecting would '\n      + 'work, and so would the refresh exchange once it exists.',\n    );\n  }\n\n  return { wireValue: grant.accessToken, grant };\n}\n"]}

package/dist/esm/security/consumable-tokens/batches/consumable-tokens-cleanup.batch.backend.service.d.ts

@@ -7,7 +7,24 @@
  * 3. Hard delete cleanup-eligible exhausted BOUNDED_REUSE tokens
  * 4. Hard delete cleanup-eligible revoked tokens older than 7 days
  *
- * Uses bulk `deleteMany` operations for performance at scale.
+ * Uses the infrastructure tier's bulk `deleteManyForInfrastructure` door for performance at scale.
+ *
+ * ## ADAPTER-NEUTRAL, and it was not until 2026-09-01
+ *
+ * `ConsumableTokenBackendService` moved off the native MongoDB collection onto the adapter-neutral
+ * repositories plane on 2026-08-25. This batch — the resource's only other database caller — was the
+ * one call site that migration missed, and it kept resolving `MongoDBService`, taking
+ * `getConnection()` and issuing four raw `collection.deleteMany(...)`.
+ *
+ * The consequence was invisible for as long as every application ran a mongod BESIDE PostgreSQL:
+ * tokens were written to whichever store the resource is bound to, and the sweep reaped them from
+ * Mongo. `wonder-crm` — PostgreSQL on both planes, no mongod at all — is the first application where
+ * the two disagree, and there the fail-closed throw below fired every six hours from the day it was
+ * created, so the framework's only credential-retention sweep had never run: spent password-reset,
+ * invitation, email-verification and magic-link rows accumulate with nothing to remove them.
+ *
+ * `.claude/rules/invariant-call-site-enumeration.md` is the shape — an invariant applied at one of
+ * its N sites, where the miss is silent because the surviving site is the one nobody watches.
  *
  * Integration with Queue System:
  * - Registered as a core engine batch in StartApplicationBackendService

package/dist/esm/security/consumable-tokens/batches/consumable-tokens-cleanup.batch.backend.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"consumable-tokens-cleanup.batch.backend.service.d.ts","sourceRoot":"","sources":["../../../../../../src/security/consumable-tokens/batches/consumable-tokens-cleanup.batch.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAAE,iCAAiC,EAAE,MAAM,4FAA4F,CAAC;AA6B/I;;;;GAIG;AACH,wBAAgB,kCAAkC,IAAI,UAAU,CAAC,OAAO,iCAAiC,CAAC,CAmKzG"}
+{"version":3,"file":"consumable-tokens-cleanup.batch.backend.service.d.ts","sourceRoot":"","sources":["../../../../../../src/security/consumable-tokens/batches/consumable-tokens-cleanup.batch.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAGH,OAAO,EAAE,iCAAiC,EAAE,MAAM,4FAA4F,CAAC;AAuC/I;;;;GAIG;AACH,wBAAgB,kCAAkC,IAAI,UAAU,CAAC,OAAO,iCAAiC,CAAC,CAsLzG"}