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

package/dist/esm/security/connected-accounts/services/user-provider-credentials.custom-impl.backend.service.js

@@ -0,0 +1,291 @@
+/**
+ * The WRITE path for a PERSON's own provider credential: seal on the way in, audit on the way out.
+ *
+ * ## Without this file the resource stores plaintext
+ *
+ * The schema declares `secretValue` as `.isWriteOnlySecret()`, which governs how the value is
+ * PRESENTED (redacted at the client boundary, and a round-tripped mask means "keep the stored
+ * secret"). It says nothing about how the value is STORED — a write-only-secret field lands in the
+ * database exactly as the client typed it. Sealing it is this hook's job, and it is the only place
+ * that job is done, so a credential reaching persistence unsealed means this registration did not
+ * resolve.
+ *
+ * ⚠️ A custom implementation resolves by an EXACT operation-path key embedding the resource, the
+ * operation, the variant TYPE and the default/variant-key slot. A registration naming a combination
+ * the resource configuration does not declare resolves nothing and silently never runs, while the
+ * route still answers 200 — here that would mean every person's third-party key persisted in
+ * plaintext behind a green suite. The pins assert these registrations against the REAL resource
+ * configuration for that reason.
+ *
+ * ## What differs from the organization sibling, and why each difference is substantive
+ *
+ * - **No `setByUserId`.** The organization's row records WHICH administrator wrote it, because
+ *   several can. This resource declares no administrative variant at all, so the author is always
+ *   the owner and a separate field could only ever repeat `userId` — while inviting a future reader
+ *   to believe the two can differ.
+ * - **The DELETE reason is `OWNER_REVOKED`, not `ADMINISTRATOR_REVOKED`.** Same door, different
+ *   meaning: nobody but the holder can reach it.
+ * - **The cascade door destroys evidence that matters more.** When a subject is erased, the
+ *   `USERS → USER_PROVIDER_CREDENTIALS` composition removes these rows through the RAW repository,
+ *   bypassing the service tier exactly as the organization purge does. The consequence is sharper
+ *   here: the deletion event is what an operator produces when asked whether an erasure reached the
+ *   person's third-party credentials, and the cascade cannot emit one. `USER_DELETED` records that
+ *   the subject was erased; what is missing is the enumeration of WHICH vendors they had connected.
+ *   This is the SAME defect as the organization purge's, at a second site — one cascade-tier audit
+ *   hook fixes both — and it is recorded on issue #365 rather than left for a reader to discover
+ *   from an absence. `ProviderCredentialDeletionReason.USER_ERASED` exists for the event that hook
+ *   will emit; nothing can emit it today.
+ *
+ * assurance-control: WILDO.IDENTITY.DELEGATED_AUTHORIZATION — a user authorizes, rotates and
+ * withdraws delegated access to a named third party.
+ */
+import { CoreAuditableEventType, CoreResourceOperation, CoreResourceType, ErrorType, ErrorCustomMessageReference, ProviderCredentialDeletionReason, ResourceOperationVariantType, WRITE_ONLY_SECRET_MASK, coreResourceShared_FieldIdentifier, } from '@wildo-ai/saas-models';
+import { ExternalProvider_Connection_OwnerScope } from '@wildo-ai/external-connectors-models';
+import { createResourceCustomServiceImplementation, } from '../../../base-classes/services/services/resource-operation-custom-implementation.factory.backend.js';
+import { SAAS_SERVICE_TYPES } from '../../../inject/models/service-types.js';
+import { projectCaughtErrorLogFields } from '../../../errors/utils/error-log-level-classification.backend.utils.js';
+import { sealProviderCredential } from '../utils/provider-credential-envelope.backend.utils.js';
+/**
+ * Resolve the identity the seal binds to.
+ *
+ * Two sources, and the request BODY is deliberately not one of them. On UPDATE the stored row is
+ * authoritative — it is what the framework already persisted. On CREATE the execution context's
+ * context-resource map is, because that is the same channel `enrichDataWithContext` reads when it
+ * injects the scope FK, so the seal binds to the person the row will actually be stored under.
+ *
+ * A `payload.userId` fallback is absent for the organization sibling's reason: it would fail safe
+ * (a seal bound to a body-supplied owner is simply unopenable later, so the outcome is a denial
+ * rather than a disclosure) but it is still the REQUEST choosing what the seal binds to, which is
+ * exactly the authorship this hook exists to keep out of a caller's hands.
+ */
+function resolveWriteIdentity(input, executionContext, utils) {
+    const current = utils.currentObject;
+    const userId = (typeof current?.userId === 'string' && current.userId)
+        || executionContext.getContextResourceId?.(coreResourceShared_FieldIdentifier[CoreResourceType.USERS]);
+    const providerRef = (typeof input?.providerRef === 'string' && input.providerRef)
+        || (typeof current?.providerRef === 'string' ? current.providerRef : undefined);
+    const secretSlug = (typeof input?.secretSlug === 'string' && input.secretSlug)
+        || (typeof current?.secretSlug === 'string' ? current.secretSlug : undefined);
+    if (typeof userId !== 'string' || !userId || !providerRef || !secretSlug) {
+        // Fail CLOSED. Sealing under a partial identity would produce a credential bound to the wrong
+        // row — unopenable at resolution time, and indistinguishable then from a tampered one.
+        throw utils.errorBuilder.buildError(ErrorType.CONFIGURATION, executionContext, {
+            customMessageReference: ErrorCustomMessageReference.CONFIGURATION,
+            context: {
+                message: 'Cannot seal a user provider credential: the row identity is incomplete. All three of userId, '
+                    + 'providerRef and secretSlug must be resolvable, because the seal is bound to them. The user is '
+                    + 'read from the execution scope or the stored row, never from the request body.',
+                hasUserId: Boolean(userId),
+                hasProviderRef: Boolean(providerRef),
+                hasSecretSlug: Boolean(secretSlug),
+            },
+        });
+    }
+    return { userId, providerRef, secretSlug };
+}
+/**
+ * Seal an incoming secret, or return nothing when the write carries none.
+ *
+ * The mask is what makes an ordinary metadata edit safe: a client that read the row back received
+ * `WRITE_ONLY_SECRET_MASK` in place of the value, and sending it back means "keep what is stored".
+ * Sealing the mask would replace a working credential with the literal string of bullet characters.
+ */
+function sealIncomingSecret(input, executionContext, utils, container) {
+    const incoming = input?.secretValue;
+    if (typeof incoming !== 'string' || incoming.length === 0 || incoming === WRITE_ONLY_SECRET_MASK) {
+        return undefined;
+    }
+    const identity = resolveWriteIdentity(input, executionContext, utils);
+    const appConfig = container.get(SAAS_SERVICE_TYPES.AppConfigService);
+    return {
+        ...input,
+        secretValue: sealProviderCredential(incoming, appConfig.secrets.security.session.encryptionKey, {
+            ownerScope: ExternalProvider_Connection_OwnerScope.USER,
+            ownerId: identity.userId,
+            providerRef: identity.providerRef,
+            secretSlug: identity.secretSlug,
+        }),
+        // Server-owned provenance. `.excludeFromCreate().excludeFromUpdate()`, so returning it here is
+        // what carries it past the strict re-parse, declared explicitly in `authoritativeFields` below.
+        secretSetAt: new Date(),
+    };
+}
+/**
+ * Emit the lifecycle event for a completed write.
+ *
+ * Best-effort in the same posture as every other audit emission in the engine: the credential has
+ * already been written, and turning a logging failure into a 500 would tell the person their write
+ * failed when it did not.
+ */
+async function emitCredentialWriteAudit(container, eventType, row, previousSecretSetAt, executionContext, utils) {
+    if (!row || typeof row._id !== 'string' || typeof row.userId !== 'string') {
+        utils.logger.error?.('A user provider credential was written but the row could not be identified — audit event not emitted', { eventType });
+        return;
+    }
+    try {
+        const auditLogs = container.get(SAAS_SERVICE_TYPES.AuditLogsService);
+        // `userId` is taken from the ROW, not from the initiator. They are the same identity here by
+        // construction, and reading the row is what keeps that true if a future variant ever lets them
+        // differ: the event must name whose credential it is, never who happened to make the call.
+        const common = {
+            userId: row.userId,
+            providerRef: row.providerRef,
+            secretSlug: row.secretSlug,
+            credentialId: row._id,
+        };
+        if (eventType === CoreAuditableEventType.USER_PROVIDER_CREDENTIAL_SET) {
+            await auditLogs.logUserProviderCredentialSet(common, executionContext);
+        }
+        else {
+            await auditLogs.logUserProviderCredentialRotated({ ...common, previousSecretSetAt: previousSecretSetAt?.toISOString() }, executionContext);
+        }
+    }
+    catch (error) {
+        utils.logger.error?.('Failed to emit the user provider credential audit event', {
+            eventType,
+            credentialId: row._id,
+            ...projectCaughtErrorLogFields(error),
+        });
+    }
+}
+/** CREATE — the person connects an account at a third party for the first time. */
+function createCredentialCreateFactory() {
+    const factory = (_registry, container) => createResourceCustomServiceImplementation({
+        operationPath: {
+            resourceIdentifier: CoreResourceType.USER_PROVIDER_CREDENTIALS,
+            operationIdentifier: CoreResourceOperation.CREATE,
+            variantType: ResourceOperationVariantType.API_CALL,
+            isOperationDefault: true,
+        },
+        debugLabel: 'userProviderCredentials.create.seal-and-audit',
+        /**
+         * The two fields this hook OWNS, declared rather than inferred.
+         *
+         * `preserveServerInjectedFields` is normally derived by diffing the prefix output against a
+         * snapshot of the payload keys taken BEFORE the prefix ran, so only keys the hook INTRODUCED
+         * survive the repository's strict re-parse. That inference has a documented hole: a caller
+         * reaching the service tier with the key already present puts it into the snapshot, the hook's
+         * value is then not classified as introduced, and the repository strips it while the operation
+         * answers success.
+         *
+         * For `secretValue` the declaration says the thing that matters most in this file: whatever a
+         * caller sent, what reaches persistence is the POST-prefix value — the sealed envelope — and
+         * never the plaintext they supplied.
+         */
+        authoritativeFields: ['secretValue', 'secretSetAt'],
+        handlers: {
+            prefixCoreOperations: async (_id, input, executionContext, _operationPath, utils) => sealIncomingSecret(input, executionContext, utils, container),
+            postfixCoreOperations: async (_id, created, executionContext, _operationPath, utils) => {
+                await emitCredentialWriteAudit(container, CoreAuditableEventType.USER_PROVIDER_CREDENTIAL_SET, created, undefined, executionContext, utils);
+                return created;
+            },
+        },
+    });
+    return factory;
+}
+/**
+ * UPDATE — a rotation, or an ordinary metadata edit.
+ *
+ * The two are distinguished by whether the write actually carried a NEW secret. An edit that only
+ * toggles `enabled` emits nothing: a rotation event on a metadata change would make the one signal
+ * a compromise investigation depends on unusable.
+ */
+function createCredentialUpdateFactory() {
+    const factory = (_registry, container) => createResourceCustomServiceImplementation({
+        operationPath: {
+            resourceIdentifier: CoreResourceType.USER_PROVIDER_CREDENTIALS,
+            operationIdentifier: CoreResourceOperation.UPDATE,
+            variantType: ResourceOperationVariantType.API_CALL,
+            isOperationDefault: true,
+        },
+        debugLabel: 'userProviderCredentials.update.seal-and-audit',
+        authoritativeFields: ['secretValue', 'secretSetAt'],
+        handlers: {
+            prefixCoreOperations: async (_id, input, executionContext, _operationPath, utils) => {
+                const sealed = sealIncomingSecret(input, executionContext, utils, container);
+                // Bridge to the postfix, keyed by this operation's execution context. Carries only WHETHER
+                // the value moved and WHEN the previous one was set — never a secret, in either direction.
+                ROTATION_BRIDGE_BY_EC.set(executionContext, {
+                    rotated: sealed?.secretValue !== undefined,
+                    previousSecretSetAt: utils.currentObject?.secretSetAt,
+                });
+                return sealed;
+            },
+            postfixCoreOperations: async (_id, updated, executionContext, _operationPath, utils) => {
+                const bridge = ROTATION_BRIDGE_BY_EC.get(executionContext);
+                ROTATION_BRIDGE_BY_EC.delete(executionContext);
+                if (bridge?.rotated) {
+                    await emitCredentialWriteAudit(container, CoreAuditableEventType.USER_PROVIDER_CREDENTIAL_ROTATED, updated, bridge.previousSecretSetAt, executionContext, utils);
+                }
+                return updated;
+            },
+        },
+    });
+    return factory;
+}
+/**
+ * DELETE — the person disconnecting their own account.
+ *
+ * `OWNER_REVOKED` unconditionally, and that is CORRECT rather than an assumption: the erasure
+ * cascade never reaches this hook (see the module header), so every delete that arrives here is a
+ * deliberate service-tier revocation by the only party who can reach the door. If a future change
+ * routed a cascade through the service tier, this constant would become a lie — which is why the
+ * door table above is pinned by a test rather than left as prose.
+ */
+function createCredentialDeleteFactory() {
+    const factory = (_registry, container) => createResourceCustomServiceImplementation({
+        operationPath: {
+            resourceIdentifier: CoreResourceType.USER_PROVIDER_CREDENTIALS,
+            operationIdentifier: CoreResourceOperation.DELETE,
+            variantType: ResourceOperationVariantType.API_CALL,
+            isOperationDefault: true,
+        },
+        debugLabel: 'userProviderCredentials.delete.audit',
+        handlers: {
+            postfixCoreOperations: async (id, result, executionContext, _operationPath, utils) => {
+                // The pre-deletion snapshot: after the row is gone, the provider and slug are unrecoverable,
+                // so an event naming only the id would identify nothing.
+                const snapshot = utils.currentObject;
+                const credentialId = snapshot?._id ?? (typeof id === 'string' ? id : undefined);
+                if (!snapshot?.userId || !credentialId) {
+                    utils.logger.error?.('A user provider credential was deleted but the subject could not be resolved — audit event not emitted', { addressedIdType: Array.isArray(id) ? 'array' : typeof id });
+                    return result;
+                }
+                try {
+                    const auditLogs = container.get(SAAS_SERVICE_TYPES.AuditLogsService);
+                    await auditLogs.logUserProviderCredentialDeleted({
+                        userId: snapshot.userId,
+                        providerRef: snapshot.providerRef,
+                        secretSlug: snapshot.secretSlug,
+                        credentialId,
+                        reason: ProviderCredentialDeletionReason.OWNER_REVOKED,
+                    }, executionContext);
+                }
+                catch (error) {
+                    utils.logger.error?.('Failed to emit the user provider credential deletion audit event', {
+                        credentialId,
+                        ...projectCaughtErrorLogFields(error),
+                    });
+                }
+                return result;
+            },
+        },
+    });
+    return factory;
+}
+/**
+ * Prefix→postfix bridge for the UPDATE hook, keyed by the per-operation execution-context instance.
+ *
+ * A `WeakMap` so an abandoned operation cannot retain the entry, mirroring the api-key mint bridge.
+ * It deliberately carries no secret: only a boolean and a timestamp cross it.
+ */
+const ROTATION_BRIDGE_BY_EC = new WeakMap();
+/** Every write door of the user-provider-credential resource. */
+export function createUserProviderCredentialFactories() {
+    return [
+        createCredentialCreateFactory(),
+        createCredentialUpdateFactory(),
+        createCredentialDeleteFactory(),
+    ];
+}
+//# sourceMappingURL=user-provider-credentials.custom-impl.backend.service.js.map

package/dist/esm/security/connected-accounts/services/user-provider-credentials.custom-impl.backend.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-provider-credentials.custom-impl.backend.service.js","sourceRoot":"","sources":["../../../../../../src/security/connected-accounts/services/user-provider-credentials.custom-impl.backend.service.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The WRITE path for a PERSON's own provider credential: seal on the way in, audit on the way out.\n *\n * ## Without this file the resource stores plaintext\n *\n * The schema declares `secretValue` as `.isWriteOnlySecret()`, which governs how the value is\n * PRESENTED (redacted at the client boundary, and a round-tripped mask means \"keep the stored\n * secret\"). It says nothing about how the value is STORED — a write-only-secret field lands in the\n * database exactly as the client typed it. Sealing it is this hook's job, and it is the only place\n * that job is done, so a credential reaching persistence unsealed means this registration did not\n * resolve.\n *\n * ⚠️ A custom implementation resolves by an EXACT operation-path key embedding the resource, the\n * operation, the variant TYPE and the default/variant-key slot. A registration naming a combination\n * the resource configuration does not declare resolves nothing and silently never runs, while the\n * route still answers 200 — here that would mean every person's third-party key persisted in\n * plaintext behind a green suite. The pins assert these registrations against the REAL resource\n * configuration for that reason.\n *\n * ## What differs from the organization sibling, and why each difference is substantive\n *\n * - **No `setByUserId`.** The organization's row records WHICH administrator wrote it, because\n *   several can. This resource declares no administrative variant at all, so the author is always\n *   the owner and a separate field could only ever repeat `userId` — while inviting a future reader\n *   to believe the two can differ.\n * - **The DELETE reason is `OWNER_REVOKED`, not `ADMINISTRATOR_REVOKED`.** Same door, different\n *   meaning: nobody but the holder can reach it.\n * - **The cascade door destroys evidence that matters more.** When a subject is erased, the\n *   `USERS → USER_PROVIDER_CREDENTIALS` composition removes these rows through the RAW repository,\n *   bypassing the service tier exactly as the organization purge does. The consequence is sharper\n *   here: the deletion event is what an operator produces when asked whether an erasure reached the\n *   person's third-party credentials, and the cascade cannot emit one. `USER_DELETED` records that\n *   the subject was erased; what is missing is the enumeration of WHICH vendors they had connected.\n *   This is the SAME defect as the organization purge's, at a second site — one cascade-tier audit\n *   hook fixes both — and it is recorded on issue #365 rather than left for a reader to discover\n *   from an absence. `ProviderCredentialDeletionReason.USER_ERASED` exists for the event that hook\n *   will emit; nothing can emit it today.\n *\n * assurance-control: WILDO.IDENTITY.DELEGATED_AUTHORIZATION — a user authorizes, rotates and\n * withdraws delegated access to a named third party.\n */\n\nimport type { Container } from 'inversify';\nimport {\n  CoreAuditableEventType,\n  CoreResourceOperation,\n  CoreResourceType,\n  ErrorType,\n  ErrorCustomMessageReference,\n  ProviderCredentialDeletionReason,\n  ResourceOperationVariantType,\n  WRITE_ONLY_SECRET_MASK,\n  coreResourceShared_FieldIdentifier,\n  type UserProviderCredential,\n} from '@wildo-ai/saas-models';\n\nimport { ExternalProvider_Connection_OwnerScope } from '@wildo-ai/external-connectors-models';\n\nimport {\n  createResourceCustomServiceImplementation,\n  type ResourceCustomServiceImplementationFactory,\n} from '~wildo-backend-lib/base-classes/services/services/resource-operation-custom-implementation.factory.backend';\nimport type { ResourceOperation_CustomImplementation_Utils } from '~wildo-backend-lib/base-classes/services/services/resource-operation-custom-implementation-base.backend.service';\nimport type { ResourcesRegistryBackendService } from '~wildo-backend-lib/resources/services/resources-registry.backend.service';\nimport type { ExecutionContext } from '~wildo-backend-lib/runtime/models/execution-context.backend.schemas';\nimport { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';\nimport type { AppConfigurationService } from '~wildo-backend-lib/config/services/app-configuration.backend.service';\nimport type { AuditLogsBackendService } from '~wildo-backend-lib/compliance/audit-trails/services/audit-logs.backend.service';\nimport { projectCaughtErrorLogFields } from '~wildo-backend-lib/errors/utils/error-log-level-classification.backend.utils';\n\nimport { sealProviderCredential } from '../utils/provider-credential-envelope.backend.utils';\n\n/** The row identity the seal binds to, resolved from whichever channel actually carries each part. */\ninterface UserCredentialWriteIdentity {\n  userId: string;\n  providerRef: string;\n  secretSlug: string;\n}\n\n/**\n * Resolve the identity the seal binds to.\n *\n * Two sources, and the request BODY is deliberately not one of them. On UPDATE the stored row is\n * authoritative — it is what the framework already persisted. On CREATE the execution context's\n * context-resource map is, because that is the same channel `enrichDataWithContext` reads when it\n * injects the scope FK, so the seal binds to the person the row will actually be stored under.\n *\n * A `payload.userId` fallback is absent for the organization sibling's reason: it would fail safe\n * (a seal bound to a body-supplied owner is simply unopenable later, so the outcome is a denial\n * rather than a disclosure) but it is still the REQUEST choosing what the seal binds to, which is\n * exactly the authorship this hook exists to keep out of a caller's hands.\n */\nfunction resolveWriteIdentity(\n  input: Record<string, unknown> | undefined,\n  executionContext: ExecutionContext<any>,\n  utils: ResourceOperation_CustomImplementation_Utils,\n): UserCredentialWriteIdentity {\n  const current = utils.currentObject as UserProviderCredential | undefined;\n\n  const userId =\n    (typeof current?.userId === 'string' && current.userId)\n    || executionContext.getContextResourceId?.(coreResourceShared_FieldIdentifier[CoreResourceType.USERS] as never);\n\n  const providerRef =\n    (typeof input?.providerRef === 'string' && input.providerRef)\n    || (typeof current?.providerRef === 'string' ? current.providerRef : undefined);\n\n  const secretSlug =\n    (typeof input?.secretSlug === 'string' && input.secretSlug)\n    || (typeof current?.secretSlug === 'string' ? current.secretSlug : undefined);\n\n  if (typeof userId !== 'string' || !userId || !providerRef || !secretSlug) {\n    // Fail CLOSED. Sealing under a partial identity would produce a credential bound to the wrong\n    // row — unopenable at resolution time, and indistinguishable then from a tampered one.\n    throw utils.errorBuilder.buildError(ErrorType.CONFIGURATION, executionContext, {\n      customMessageReference: ErrorCustomMessageReference.CONFIGURATION,\n      context: {\n        message:\n          'Cannot seal a user provider credential: the row identity is incomplete. All three of userId, '\n          + 'providerRef and secretSlug must be resolvable, because the seal is bound to them. The user is '\n          + 'read from the execution scope or the stored row, never from the request body.',\n        hasUserId: Boolean(userId),\n        hasProviderRef: Boolean(providerRef),\n        hasSecretSlug: Boolean(secretSlug),\n      },\n    });\n  }\n\n  return { userId, providerRef, secretSlug };\n}\n\n/**\n * Seal an incoming secret, or return nothing when the write carries none.\n *\n * The mask is what makes an ordinary metadata edit safe: a client that read the row back received\n * `WRITE_ONLY_SECRET_MASK` in place of the value, and sending it back means \"keep what is stored\".\n * Sealing the mask would replace a working credential with the literal string of bullet characters.\n */\nfunction sealIncomingSecret(\n  input: Record<string, unknown> | undefined,\n  executionContext: ExecutionContext<any>,\n  utils: ResourceOperation_CustomImplementation_Utils,\n  container: Container,\n): Record<string, unknown> | undefined {\n  const incoming = input?.secretValue;\n  if (typeof incoming !== 'string' || incoming.length === 0 || incoming === WRITE_ONLY_SECRET_MASK) {\n    return undefined;\n  }\n\n  const identity = resolveWriteIdentity(input, executionContext, utils);\n  const appConfig = container.get<AppConfigurationService>(SAAS_SERVICE_TYPES.AppConfigService);\n\n  return {\n    ...input,\n    secretValue: sealProviderCredential(\n      incoming,\n      appConfig.secrets.security.session.encryptionKey,\n      {\n        ownerScope: ExternalProvider_Connection_OwnerScope.USER,\n        ownerId: identity.userId,\n        providerRef: identity.providerRef,\n        secretSlug: identity.secretSlug,\n      },\n    ),\n    // Server-owned provenance. `.excludeFromCreate().excludeFromUpdate()`, so returning it here is\n    // what carries it past the strict re-parse, declared explicitly in `authoritativeFields` below.\n    secretSetAt: new Date(),\n  };\n}\n\n/**\n * Emit the lifecycle event for a completed write.\n *\n * Best-effort in the same posture as every other audit emission in the engine: the credential has\n * already been written, and turning a logging failure into a 500 would tell the person their write\n * failed when it did not.\n */\nasync function emitCredentialWriteAudit(\n  container: Container,\n  eventType:\n    | typeof CoreAuditableEventType.USER_PROVIDER_CREDENTIAL_SET\n    | typeof CoreAuditableEventType.USER_PROVIDER_CREDENTIAL_ROTATED,\n  row: UserProviderCredential | undefined,\n  previousSecretSetAt: Date | undefined,\n  executionContext: ExecutionContext<any>,\n  utils: ResourceOperation_CustomImplementation_Utils,\n): Promise<void> {\n  if (!row || typeof row._id !== 'string' || typeof row.userId !== 'string') {\n    utils.logger.error?.(\n      'A user provider credential was written but the row could not be identified — audit event not emitted',\n      { eventType },\n    );\n    return;\n  }\n\n  try {\n    const auditLogs = container.get<AuditLogsBackendService>(SAAS_SERVICE_TYPES.AuditLogsService);\n    // `userId` is taken from the ROW, not from the initiator. They are the same identity here by\n    // construction, and reading the row is what keeps that true if a future variant ever lets them\n    // differ: the event must name whose credential it is, never who happened to make the call.\n    const common = {\n      userId: row.userId,\n      providerRef: row.providerRef,\n      secretSlug: row.secretSlug,\n      credentialId: row._id,\n    };\n    if (eventType === CoreAuditableEventType.USER_PROVIDER_CREDENTIAL_SET) {\n      await auditLogs.logUserProviderCredentialSet(common, executionContext);\n    } else {\n      await auditLogs.logUserProviderCredentialRotated(\n        { ...common, previousSecretSetAt: previousSecretSetAt?.toISOString() },\n        executionContext,\n      );\n    }\n  } catch (error) {\n    utils.logger.error?.('Failed to emit the user provider credential audit event', {\n      eventType,\n      credentialId: row._id,\n      ...projectCaughtErrorLogFields(error),\n    });\n  }\n}\n\n/** CREATE — the person connects an account at a third party for the first time. */\nfunction createCredentialCreateFactory(): ResourceCustomServiceImplementationFactory {\n  const factory = (_registry: ResourcesRegistryBackendService, container: Container) =>\n    createResourceCustomServiceImplementation({\n      operationPath: {\n        resourceIdentifier: CoreResourceType.USER_PROVIDER_CREDENTIALS,\n        operationIdentifier: CoreResourceOperation.CREATE,\n        variantType: ResourceOperationVariantType.API_CALL,\n        isOperationDefault: true,\n      },\n      debugLabel: 'userProviderCredentials.create.seal-and-audit',\n      /**\n       * The two fields this hook OWNS, declared rather than inferred.\n       *\n       * `preserveServerInjectedFields` is normally derived by diffing the prefix output against a\n       * snapshot of the payload keys taken BEFORE the prefix ran, so only keys the hook INTRODUCED\n       * survive the repository's strict re-parse. That inference has a documented hole: a caller\n       * reaching the service tier with the key already present puts it into the snapshot, the hook's\n       * value is then not classified as introduced, and the repository strips it while the operation\n       * answers success.\n       *\n       * For `secretValue` the declaration says the thing that matters most in this file: whatever a\n       * caller sent, what reaches persistence is the POST-prefix value — the sealed envelope — and\n       * never the plaintext they supplied.\n       */\n      authoritativeFields: ['secretValue', 'secretSetAt'],\n      handlers: {\n        prefixCoreOperations: async (_id, input, executionContext, _operationPath, utils) =>\n          sealIncomingSecret(input as Record<string, unknown> | undefined, executionContext, utils, container),\n        postfixCoreOperations: async (_id, created, executionContext, _operationPath, utils) => {\n          await emitCredentialWriteAudit(\n            container,\n            CoreAuditableEventType.USER_PROVIDER_CREDENTIAL_SET,\n            created as UserProviderCredential | undefined,\n            undefined,\n            executionContext,\n            utils,\n          );\n          return created;\n        },\n      },\n    });\n  return factory as unknown as ResourceCustomServiceImplementationFactory;\n}\n\n/**\n * UPDATE — a rotation, or an ordinary metadata edit.\n *\n * The two are distinguished by whether the write actually carried a NEW secret. An edit that only\n * toggles `enabled` emits nothing: a rotation event on a metadata change would make the one signal\n * a compromise investigation depends on unusable.\n */\nfunction createCredentialUpdateFactory(): ResourceCustomServiceImplementationFactory {\n  const factory = (_registry: ResourcesRegistryBackendService, container: Container) =>\n    createResourceCustomServiceImplementation({\n      operationPath: {\n        resourceIdentifier: CoreResourceType.USER_PROVIDER_CREDENTIALS,\n        operationIdentifier: CoreResourceOperation.UPDATE,\n        variantType: ResourceOperationVariantType.API_CALL,\n        isOperationDefault: true,\n      },\n      debugLabel: 'userProviderCredentials.update.seal-and-audit',\n      authoritativeFields: ['secretValue', 'secretSetAt'],\n      handlers: {\n        prefixCoreOperations: async (_id, input, executionContext, _operationPath, utils) => {\n          const sealed = sealIncomingSecret(\n            input as Record<string, unknown> | undefined,\n            executionContext,\n            utils,\n            container,\n          );\n          // Bridge to the postfix, keyed by this operation's execution context. Carries only WHETHER\n          // the value moved and WHEN the previous one was set — never a secret, in either direction.\n          ROTATION_BRIDGE_BY_EC.set(executionContext, {\n            rotated: sealed?.secretValue !== undefined,\n            previousSecretSetAt: (utils.currentObject as UserProviderCredential | undefined)?.secretSetAt,\n          });\n          return sealed;\n        },\n        postfixCoreOperations: async (_id, updated, executionContext, _operationPath, utils) => {\n          const bridge = ROTATION_BRIDGE_BY_EC.get(executionContext);\n          ROTATION_BRIDGE_BY_EC.delete(executionContext);\n          if (bridge?.rotated) {\n            await emitCredentialWriteAudit(\n              container,\n              CoreAuditableEventType.USER_PROVIDER_CREDENTIAL_ROTATED,\n              updated as UserProviderCredential | undefined,\n              bridge.previousSecretSetAt,\n              executionContext,\n              utils,\n            );\n          }\n          return updated;\n        },\n      },\n    });\n  return factory as unknown as ResourceCustomServiceImplementationFactory;\n}\n\n/**\n * DELETE — the person disconnecting their own account.\n *\n * `OWNER_REVOKED` unconditionally, and that is CORRECT rather than an assumption: the erasure\n * cascade never reaches this hook (see the module header), so every delete that arrives here is a\n * deliberate service-tier revocation by the only party who can reach the door. If a future change\n * routed a cascade through the service tier, this constant would become a lie — which is why the\n * door table above is pinned by a test rather than left as prose.\n */\nfunction createCredentialDeleteFactory(): ResourceCustomServiceImplementationFactory {\n  const factory = (_registry: ResourcesRegistryBackendService, container: Container) =>\n    createResourceCustomServiceImplementation({\n      operationPath: {\n        resourceIdentifier: CoreResourceType.USER_PROVIDER_CREDENTIALS,\n        operationIdentifier: CoreResourceOperation.DELETE,\n        variantType: ResourceOperationVariantType.API_CALL,\n        isOperationDefault: true,\n      },\n      debugLabel: 'userProviderCredentials.delete.audit',\n      handlers: {\n        postfixCoreOperations: async (id, result, executionContext, _operationPath, utils) => {\n          // The pre-deletion snapshot: after the row is gone, the provider and slug are unrecoverable,\n          // so an event naming only the id would identify nothing.\n          const snapshot = utils.currentObject as UserProviderCredential | undefined;\n          const credentialId = snapshot?._id ?? (typeof id === 'string' ? id : undefined);\n\n          if (!snapshot?.userId || !credentialId) {\n            utils.logger.error?.(\n              'A user provider credential was deleted but the subject could not be resolved — audit event not emitted',\n              { addressedIdType: Array.isArray(id) ? 'array' : typeof id },\n            );\n            return result;\n          }\n\n          try {\n            const auditLogs = container.get<AuditLogsBackendService>(SAAS_SERVICE_TYPES.AuditLogsService);\n            await auditLogs.logUserProviderCredentialDeleted(\n              {\n                userId: snapshot.userId,\n                providerRef: snapshot.providerRef,\n                secretSlug: snapshot.secretSlug,\n                credentialId,\n                reason: ProviderCredentialDeletionReason.OWNER_REVOKED,\n              },\n              executionContext,\n            );\n          } catch (error) {\n            utils.logger.error?.('Failed to emit the user provider credential deletion audit event', {\n              credentialId,\n              ...projectCaughtErrorLogFields(error),\n            });\n          }\n          return result;\n        },\n      },\n    });\n  return factory as unknown as ResourceCustomServiceImplementationFactory;\n}\n\n/**\n * Prefix→postfix bridge for the UPDATE hook, keyed by the per-operation execution-context instance.\n *\n * A `WeakMap` so an abandoned operation cannot retain the entry, mirroring the api-key mint bridge.\n * It deliberately carries no secret: only a boolean and a timestamp cross it.\n */\nconst ROTATION_BRIDGE_BY_EC = new WeakMap<object, { rotated: boolean; previousSecretSetAt?: Date }>();\n\n/** Every write door of the user-provider-credential resource. */\nexport function createUserProviderCredentialFactories(): ResourceCustomServiceImplementationFactory[] {\n  return [\n    createCredentialCreateFactory(),\n    createCredentialUpdateFactory(),\n    createCredentialDeleteFactory(),\n  ];\n}\n"]}

package/dist/esm/security/connected-accounts/user-provider-credential-resolver.port.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The port the provider registry consults for a PERSON's own credential.
+ *
+ * ## Why this is a second port and not a parameter on the organization's
+ *
+ * The two answer the same shape of question and mean different things, and the differences are the
+ * kind that a shared port would have to represent as optional fields — which is how a caller ends
+ * up able to describe a row that cannot exist.
+ *
+ * - **The owner differs, and so does the guarantee upstream.** An organization id reaches the
+ *   organization port from a tenant scope that several administrators share. A user id reaches this
+ *   one from the initiator's own identity, and there is no legitimate case where one person's call
+ *   resolves another person's credential — so a port that accepted either would be accepting an
+ *   argument whose safe range differs per member.
+ * - **There is no fallback here, at all.** The organization's resolution has a documented second
+ *   place to look when a tenant has set nothing (the deployment environment, refused by the current
+ *   target resolver but still meaningful in the older per-organization path). A person's credential
+ *   has none: spending the deployment's shared principal on behalf of somebody who did not connect
+ *   an account would attribute the act to the wrong party at the vendor, and the vendor's own record
+ *   is the one that survives us.
+ *
+ * ## What `undefined` means, and what it must never mean
+ *
+ * `undefined` is "this person has not connected this provider" — an ordinary state, and the answer
+ * a caller turns into a refusal naming what to connect. Anything else THROWS: a row that exists and
+ * cannot be opened must never be reported as an absent one, because the two are indistinguishable to
+ * the caller and only one of them is safe to treat as "nothing configured".
+ */
+import type { ProviderCredentialResolutionSource } from '@wildo-ai/saas-models';
+/** Which credential is being asked for. Every field is required — there is no wildcard lookup. */
+export interface UserProviderCredentialQuery {
+    /**
+     * The person. Supplied by the CALLER from the initiator's own identity, never parsed out of a
+     * request payload — the port has no way to verify it, so the guarantee has to hold upstream, and
+     * the envelope binding below is what keeps a mistake there from becoming a disclosure.
+     */
+    userId: string;
+    providerRef: string;
+    /** The slug in the provider's `secretsContract`, the same identifier the env projection names. */
+    secretSlug: string;
+}
+/** A credential that was found, opened, and is spendable. */
+export interface UserProviderCredentialResolution {
+    /** The plaintext credential. Never logged, never stored, never returned to a client. */
+    value: string;
+    /** The row it came from, for the audit trail. */
+    credentialId: string;
+}
+export interface UserProviderCredentialResolverPort {
+    /**
+     * The person's own credential, or `undefined` when they have not connected this provider.
+     *
+     * See the module JSDoc for why absence returns and unopenability throws.
+     */
+    resolveUserCredential(query: UserProviderCredentialQuery): Promise<UserProviderCredentialResolution | undefined>;
+}
+/**
+ * Re-exported for the registry's own signatures so a consumer reading the resolution result does not
+ * have to reach into the models package for the one enum that describes it.
+ */
+export type { ProviderCredentialResolutionSource };
+//# sourceMappingURL=user-provider-credential-resolver.port.d.ts.map

package/dist/esm/security/connected-accounts/user-provider-credential-resolver.port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-provider-credential-resolver.port.d.ts","sourceRoot":"","sources":["../../../../../src/security/connected-accounts/user-provider-credential-resolver.port.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,kCAAkC,EAAE,MAAM,uBAAuB,CAAC;AAEhF,kGAAkG;AAClG,MAAM,WAAW,2BAA2B;IAC1C;;;;OAIG;IACH,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,kGAAkG;IAClG,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,6DAA6D;AAC7D,MAAM,WAAW,gCAAgC;IAC/C,wFAAwF;IACxF,KAAK,EAAE,MAAM,CAAC;IACd,iDAAiD;IACjD,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,kCAAkC;IACjD;;;;OAIG;IACH,qBAAqB,CACnB,KAAK,EAAE,2BAA2B,GACjC,OAAO,CAAC,gCAAgC,GAAG,SAAS,CAAC,CAAC;CAC1D;AAED;;;GAGG;AACH,YAAY,EAAE,kCAAkC,EAAE,CAAC"}

package/dist/esm/security/connected-accounts/user-provider-credential-resolver.port.js

@@ -0,0 +1,29 @@
+/**
+ * The port the provider registry consults for a PERSON's own credential.
+ *
+ * ## Why this is a second port and not a parameter on the organization's
+ *
+ * The two answer the same shape of question and mean different things, and the differences are the
+ * kind that a shared port would have to represent as optional fields — which is how a caller ends
+ * up able to describe a row that cannot exist.
+ *
+ * - **The owner differs, and so does the guarantee upstream.** An organization id reaches the
+ *   organization port from a tenant scope that several administrators share. A user id reaches this
+ *   one from the initiator's own identity, and there is no legitimate case where one person's call
+ *   resolves another person's credential — so a port that accepted either would be accepting an
+ *   argument whose safe range differs per member.
+ * - **There is no fallback here, at all.** The organization's resolution has a documented second
+ *   place to look when a tenant has set nothing (the deployment environment, refused by the current
+ *   target resolver but still meaningful in the older per-organization path). A person's credential
+ *   has none: spending the deployment's shared principal on behalf of somebody who did not connect
+ *   an account would attribute the act to the wrong party at the vendor, and the vendor's own record
+ *   is the one that survives us.
+ *
+ * ## What `undefined` means, and what it must never mean
+ *
+ * `undefined` is "this person has not connected this provider" — an ordinary state, and the answer
+ * a caller turns into a refusal naming what to connect. Anything else THROWS: a row that exists and
+ * cannot be opened must never be reported as an absent one, because the two are indistinguishable to
+ * the caller and only one of them is safe to treat as "nothing configured".
+ */
+//# sourceMappingURL=user-provider-credential-resolver.port.js.map

package/dist/esm/security/connected-accounts/user-provider-credential-resolver.port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-provider-credential-resolver.port.js","sourceRoot":"","sources":["../../../../../src/security/connected-accounts/user-provider-credential-resolver.port.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG","sourcesContent":["/**\n * The port the provider registry consults for a PERSON's own credential.\n *\n * ## Why this is a second port and not a parameter on the organization's\n *\n * The two answer the same shape of question and mean different things, and the differences are the\n * kind that a shared port would have to represent as optional fields — which is how a caller ends\n * up able to describe a row that cannot exist.\n *\n * - **The owner differs, and so does the guarantee upstream.** An organization id reaches the\n *   organization port from a tenant scope that several administrators share. A user id reaches this\n *   one from the initiator's own identity, and there is no legitimate case where one person's call\n *   resolves another person's credential — so a port that accepted either would be accepting an\n *   argument whose safe range differs per member.\n * - **There is no fallback here, at all.** The organization's resolution has a documented second\n *   place to look when a tenant has set nothing (the deployment environment, refused by the current\n *   target resolver but still meaningful in the older per-organization path). A person's credential\n *   has none: spending the deployment's shared principal on behalf of somebody who did not connect\n *   an account would attribute the act to the wrong party at the vendor, and the vendor's own record\n *   is the one that survives us.\n *\n * ## What `undefined` means, and what it must never mean\n *\n * `undefined` is \"this person has not connected this provider\" — an ordinary state, and the answer\n * a caller turns into a refusal naming what to connect. Anything else THROWS: a row that exists and\n * cannot be opened must never be reported as an absent one, because the two are indistinguishable to\n * the caller and only one of them is safe to treat as \"nothing configured\".\n */\n\nimport type { ProviderCredentialResolutionSource } from '@wildo-ai/saas-models';\n\n/** Which credential is being asked for. Every field is required — there is no wildcard lookup. */\nexport interface UserProviderCredentialQuery {\n  /**\n   * The person. Supplied by the CALLER from the initiator's own identity, never parsed out of a\n   * request payload — the port has no way to verify it, so the guarantee has to hold upstream, and\n   * the envelope binding below is what keeps a mistake there from becoming a disclosure.\n   */\n  userId: string;\n  providerRef: string;\n  /** The slug in the provider's `secretsContract`, the same identifier the env projection names. */\n  secretSlug: string;\n}\n\n/** A credential that was found, opened, and is spendable. */\nexport interface UserProviderCredentialResolution {\n  /** The plaintext credential. Never logged, never stored, never returned to a client. */\n  value: string;\n  /** The row it came from, for the audit trail. */\n  credentialId: string;\n}\n\nexport interface UserProviderCredentialResolverPort {\n  /**\n   * The person's own credential, or `undefined` when they have not connected this provider.\n   *\n   * See the module JSDoc for why absence returns and unopenability throws.\n   */\n  resolveUserCredential(\n    query: UserProviderCredentialQuery,\n  ): Promise<UserProviderCredentialResolution | undefined>;\n}\n\n/**\n * Re-exported for the registry's own signatures so a consumer reading the resolution result does not\n * have to reach into the models package for the one enum that describes it.\n */\nexport type { ProviderCredentialResolutionSource };\n"]}

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

@@ -0,0 +1,127 @@
+/**
+ * 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 { ExternalProvider_Connection_OwnerScope } from '@wildo-ai/external-connectors-models';
+/**
+ * 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 declare const PROVIDER_CREDENTIAL_ENVELOPE_PREFIX = "wildo-sealed:aes-256-gcm:";
+/** Raised when a sealed value cannot be sealed or opened. Never carries the value or any part of it. */
+export declare class ProviderCredentialEnvelopeError extends Error {
+    constructor(message: string);
+}
+/**
+ * The row identity a sealed value is bound to. All four are required — see the module JSDoc.
+ *
+ * `ownerId` is the organization id or the user id, per `ownerScope`. One field rather than two
+ * optional ones, because exactly one owner exists per row and a shape with two nullable ids can
+ * represent a row with neither — a state the seal would then bind to nothing.
+ */
+export interface ProviderCredentialEnvelopeBinding {
+    ownerScope: ExternalProvider_Connection_OwnerScope.ORGANIZATION | ExternalProvider_Connection_OwnerScope.USER;
+    ownerId: string;
+    providerRef: string;
+    secretSlug: string;
+}
+/** Whether a stored value is a sealed envelope. Cheap, and does not need the key. */
+export declare function isSealedProviderCredential(value: string | undefined | null): boolean;
+/**
+ * Seal a plaintext credential for storage.
+ *
+ * Format: `wildo-sealed:aes-256-gcm:<iv hex>:<auth tag hex>:<ciphertext hex>`.
+ */
+export declare function sealProviderCredential(plaintext: string, baseEncryptionKey: string, binding: ProviderCredentialEnvelopeBinding): string;
+/**
+ * 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 declare function openProviderCredential(sealedValue: string, baseEncryptionKey: string, binding: ProviderCredentialEnvelopeBinding): string;
+/**
+ * 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 declare function sealedProviderCredentialsAreIdentical(left: string, right: string): boolean;
+//# sourceMappingURL=provider-credential-envelope.backend.utils.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"provider-credential-envelope.backend.utils.d.ts","sourceRoot":"","sources":["../../../../../../src/security/connected-accounts/utils/provider-credential-envelope.backend.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmEG;AAIH,OAAO,EAAE,sCAAsC,EAAE,MAAM,sCAAsC,CAAC;AAwB9F;;;;GAIG;AACH,eAAO,MAAM,mCAAmC,8BAA8B,CAAC;AAyB/E,wGAAwG;AACxG,qBAAa,+BAAgC,SAAQ,KAAK;gBAC5C,OAAO,EAAE,MAAM;CAI5B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iCAAiC;IAChD,UAAU,EAAE,sCAAsC,CAAC,YAAY,GAAG,sCAAsC,CAAC,IAAI,CAAC;IAC9G,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;CACpB;AAmDD,qFAAqF;AACrF,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,OAAO,CAEpF;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,EACjB,iBAAiB,EAAE,MAAM,EACzB,OAAO,EAAE,iCAAiC,GACzC,MAAM,CAsBR;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,MAAM,EACnB,iBAAiB,EAAE,MAAM,EACzB,OAAO,EAAE,iCAAiC,GACzC,MAAM,CAkER;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qCAAqC,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAU1F"}