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

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

@@ -0,0 +1,358 @@
+/**
+ * The WRITE path for an organization's 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 credential persisted in plaintext behind a
+ * green suite. The pins in `__tests__/organization-provider-credentials-write-path.backend.test.ts`
+ * assert these registrations against the REAL resource configuration for that reason.
+ *
+ * ## The DELETE doors — enumerated, because only one of them reaches this file
+ *
+ * | Door | Path | This hook |
+ * |---|---|---|
+ * | A tenant administrator revoking a credential | service tier, `DELETE` default variant | RUNS |
+ * | The ORGANIZATIONS purge cascade (both the batch's route-less default door and the super-admin's `admin` door reach the same cascade) | `deleteChildrenImmediate` → the RAW repository | does NOT run |
+ *
+ * Door 2 is not an oversight and not a hole in the ERASURE: the cascade removes the rows, which is
+ * what matters, and `services-registry-handler.backend.service.ts` documents the raw-repository
+ * route explicitly ("VARIANT-AGNOSTIC CASCADE: the onParentDelete teardown deletes children directly
+ * through the RAW repository"). What door 2 has no way to produce is a per-credential AUDIT event,
+ * because the service tier — where custom implementations live — is bypassed entirely. Emitting one
+ * would need a cascade-tier audit hook in the framework, which is outside this resource. The tenant
+ * purge is itself audited as `ORGANIZATION_DELETED`, so the destruction is on the record; what is
+ * missing is the enumeration of WHICH third parties the tenant held credentials for at that moment.
+ * Recorded as its own issue rather than left for a reader to discover from an absence.
+ */
+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 { resolveAuditActorId } from '../../../compliance/audit-trails/utils/audit-actor.backend.utils.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 row identity for a write.
+ *
+ * The three parts come from three DIFFERENT places, and that is the reason this is a function rather
+ * than three property reads:
+ *
+ * - `organizationId` is injected by the context machinery from the request SCOPE, so on CREATE it is
+ *   not in the input payload at all. The execution context's context-resource map is the
+ *   authoritative channel — the same one `buildContextualFilter` and `enrichDataWithContext` read —
+ *   which is what makes the seal bind to the tenant the framework will actually store the row under,
+ *   rather than to one a caller could name in a body field.
+ * - `providerRef` / `secretSlug` are client-supplied on CREATE and `.excludeFromUpdate()` afterwards,
+ *   so on UPDATE they must come from the pre-fetched current row.
+ */
+function resolveWriteIdentity(input, executionContext, utils) {
+    const current = utils.currentObject;
+    // 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 tenant the
+    // row will actually be stored under.
+    //
+    // A `payload.organizationId` fallback was here and was REMOVED: it fails safe (a seal bound to a
+    // body-supplied tenant 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. With no fallback, a context that
+    // cannot name the tenant is a REFUSAL — see below.
+    const organizationId = (typeof current?.organizationId === 'string' && current.organizationId)
+        || executionContext.getContextResourceId?.(coreResourceShared_FieldIdentifier[CoreResourceType.ORGANIZATIONS]);
+    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 organizationId !== 'string' || !organizationId || !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 an organization provider credential: the row identity is incomplete. All three of '
+                    + 'organizationId, providerRef and secretSlug must be resolvable, because the seal is bound to them. '
+                    + 'The organization is read from the execution scope or the stored row, never from the request body.',
+                hasOrganizationId: Boolean(organizationId),
+                hasProviderRef: Boolean(providerRef),
+                hasSecretSlug: Boolean(secretSlug),
+            },
+        });
+    }
+    return { organizationId, providerRef, secretSlug };
+}
+/**
+ * Seal `secretValue` if the write carries one.
+ *
+ * An ABSENT `secretValue` is normal on UPDATE and must pass through untouched: the framework strips
+ * the field when a client echoes back the redaction mask, which is how "edit the description without
+ * retyping the secret" works. Re-sealing nothing would be harmless; treating absence as an error
+ * would break the ordinary edit.
+ */
+function sealIncomingSecret(input, executionContext, utils, container) {
+    const payload = input ?? undefined;
+    const incoming = payload?.secretValue;
+    // ABSENT means "no change", and only absent. `null` is deliberately NOT treated as absent and
+    // falls through to the refusal below.
+    //
+    // That distinction became load-bearing the moment `secretValue` was declared authoritative: an
+    // authoritative field's post-prefix value is always carried past the repository's strict re-parse,
+    // so passing a `null` through here would push it INTO persistence rather than letting the schema
+    // reject it. The row would then hold a null where `z.string().min(1)` is required, and every
+    // later read would throw in `transformOutput` — a write that answers success and leaves the row
+    // permanently unreadable.
+    if (incoming === undefined) {
+        return payload;
+    }
+    // Defence in depth. The framework strips the mask sentinel before this hook runs, so reaching here
+    // with the mask means that strip did not happen — and sealing the mask would store the literal
+    // bullet characters as the tenant's credential, then hand them to a vendor.
+    if (incoming === WRITE_ONLY_SECRET_MASK) {
+        const { secretValue: _discarded, ...rest } = payload;
+        return rest;
+    }
+    if (typeof incoming !== 'string' || incoming.length === 0) {
+        throw utils.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {
+            customMessageReference: ErrorCustomMessageReference.VALIDATION,
+            context: { message: 'An organization provider credential value must be a non-empty string.' },
+        });
+    }
+    const identity = resolveWriteIdentity(payload, executionContext, utils);
+    const appConfig = container.get(SAAS_SERVICE_TYPES.AppConfigService);
+    const actingUserId = executionContext?.initiatorIds?.userId;
+    return {
+        ...payload,
+        secretValue: sealProviderCredential(incoming, appConfig.secrets.security.session.encryptionKey, {
+            ownerScope: ExternalProvider_Connection_OwnerScope.ORGANIZATION,
+            ownerId: identity.organizationId,
+            providerRef: identity.providerRef,
+            secretSlug: identity.secretSlug,
+        }),
+        // Server-owned provenance. Both are `.excludeFromCreate().excludeFromUpdate()`, so returning them
+        // here is what carries them past the strict re-parse — the same mechanism api-key minting uses
+        // for its hashed material, and declared explicitly in `authoritativeFields` below.
+        secretSetAt: new Date(),
+        // Only when there IS an acting user. Writing the key with an `undefined` value would preserve an
+        // explicit `undefined` past the re-parse rather than leaving the field absent, and "absent"
+        // is the honest representation of a write with no human behind it.
+        ...(actingUserId ? { setByUserId: actingUserId } : {}),
+    };
+}
+/**
+ * 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 tenant their write
+ * failed when it did not.
+ */
+async function emitCredentialWriteAudit(container, 
+/**
+ * WHICH grant event this write is. Typed as the audit vocabulary's own two members rather than a
+ * bespoke `'set' | 'rotated'` pair: the distinction already has a named runtime source, and a
+ * second spelling of it would be a closed vocabulary with no home and one more thing to keep in
+ * step with the event names.
+ */
+eventType, row, previousSecretSetAt, executionContext, utils) {
+    if (!row || typeof row._id !== 'string' || typeof row.organizationId !== 'string') {
+        utils.logger.error?.('An organization 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);
+        const common = {
+            organizationId: row.organizationId,
+            providerRef: row.providerRef,
+            secretSlug: row.secretSlug,
+            credentialId: row._id,
+        };
+        if (eventType === CoreAuditableEventType.ORGANIZATION_PROVIDER_CREDENTIAL_SET) {
+            await auditLogs.logOrganizationProviderCredentialSet({ ...common, setBy: resolveAuditActorId(executionContext) }, executionContext);
+        }
+        else {
+            await auditLogs.logOrganizationProviderCredentialRotated({
+                ...common,
+                rotatedBy: resolveAuditActorId(executionContext),
+                previousSecretSetAt: previousSecretSetAt?.toISOString(),
+            }, executionContext);
+        }
+    }
+    catch (error) {
+        utils.logger.error?.('Failed to emit the organization provider credential audit event', {
+            eventType,
+            credentialId: row._id,
+            ...projectCaughtErrorLogFields(error),
+        });
+    }
+}
+/**
+ * CREATE — the tenant grants this application authority toward a third party for the first time.
+ */
+function createCredentialCreateFactory() {
+    const factory = (_registry, container) => createResourceCustomServiceImplementation({
+        operationPath: {
+            resourceIdentifier: CoreResourceType.ORG_PROVIDER_CREDENTIALS,
+            operationIdentifier: CoreResourceOperation.CREATE,
+            variantType: ResourceOperationVariantType.API_CALL,
+            isOperationDefault: true,
+        },
+        debugLabel: 'organizationProviderCredentials.create.seal-and-audit',
+        /**
+         * The three 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 — MCP `callTool` forwards its
+         * arguments with no strict parse — 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 `secretSetAt` / `setByUserId` that would silently lose the provenance of a credential,
+         * which is the first thing an incident asks for. 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', 'setByUserId'],
+        handlers: {
+            prefixCoreOperations: async (_id, input, executionContext, _operationPath, utils) => sealIncomingSecret(input, executionContext, utils, container),
+            postfixCoreOperations: async (_id, created, executionContext, _operationPath, utils) => {
+                await emitCredentialWriteAudit(container, CoreAuditableEventType.ORGANIZATION_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
+ * changes the description emits nothing: a rotation event on a description change would make the
+ * one signal a compromise investigation depends on unusable.
+ */
+function createCredentialUpdateFactory() {
+    const factory = (_registry, container) => createResourceCustomServiceImplementation({
+        operationPath: {
+            resourceIdentifier: CoreResourceType.ORG_PROVIDER_CREDENTIALS,
+            operationIdentifier: CoreResourceOperation.UPDATE,
+            variantType: ResourceOperationVariantType.API_CALL,
+            isOperationDefault: true,
+        },
+        debugLabel: 'organizationProviderCredentials.update.seal-and-audit',
+        /**
+         * The three 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 — MCP `callTool` forwards its
+         * arguments with no strict parse — 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 `secretSetAt` / `setByUserId` that would silently lose the provenance of a credential,
+         * which is the first thing an incident asks for. 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', 'setByUserId'],
+        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.ORGANIZATION_PROVIDER_CREDENTIAL_ROTATED, updated, bridge.previousSecretSetAt, executionContext, utils);
+                }
+                return updated;
+            },
+        },
+    });
+    return factory;
+}
+/**
+ * DELETE — a tenant administrator revoking the grant.
+ *
+ * `ADMINISTRATOR_REVOKED` unconditionally, and that is CORRECT rather than an assumption: the
+ * cascade door never reaches this hook (see the module header), so every delete that arrives here is
+ * a deliberate service-tier revocation. 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.ORG_PROVIDER_CREDENTIALS,
+            operationIdentifier: CoreResourceOperation.DELETE,
+            variantType: ResourceOperationVariantType.API_CALL,
+            isOperationDefault: true,
+        },
+        debugLabel: 'organizationProviderCredentials.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?.organizationId || !credentialId) {
+                    utils.logger.error?.('An organization 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.logOrganizationProviderCredentialDeleted({
+                        organizationId: snapshot.organizationId,
+                        providerRef: snapshot.providerRef,
+                        secretSlug: snapshot.secretSlug,
+                        credentialId,
+                        reason: ProviderCredentialDeletionReason.ADMINISTRATOR_REVOKED,
+                        deletedBy: resolveAuditActorId(executionContext),
+                    }, executionContext);
+                }
+                catch (error) {
+                    utils.logger.error?.('Failed to emit the organization 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 organization-provider-credential resource. */
+export function createOrganizationProviderCredentialFactories() {
+    return [
+        createCredentialCreateFactory(),
+        createCredentialUpdateFactory(),
+        createCredentialDeleteFactory(),
+    ];
+}
+//# sourceMappingURL=organization-provider-credentials.custom-impl.backend.service.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"organization-provider-credentials.custom-impl.backend.service.js","sourceRoot":"","sources":["../../../../../../src/security/connected-accounts/services/organization-provider-credentials.custom-impl.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAGH,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,gBAAgB,EAChB,SAAS,EACT,2BAA2B,EAC3B,gCAAgC,EAChC,4BAA4B,EAC5B,sBAAsB,EACtB,kCAAkC,GAEnC,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,sCAAsC,EAAE,MAAM,sCAAsC,CAAC;AAE9F,OAAO,EACL,yCAAyC,GAE1C,MAAM,4GAA4G,CAAC;AAIpH,OAAO,EAAE,kBAAkB,EAAE,MAAM,gDAAgD,CAAC;AAGpF,OAAO,EAAE,mBAAmB,EAAE,MAAM,4EAA4E,CAAC;AACjH,OAAO,EAAE,2BAA2B,EAAE,MAAM,8EAA8E,CAAC;AAE3H,OAAO,EAAE,sBAAsB,EAAE,MAAM,qDAAqD,CAAC;AAS7F;;;;;;;;;;;;;GAaG;AACH,SAAS,oBAAoB,CAC3B,KAA0C,EAC1C,gBAAuC,EACvC,KAAmD;IAEnD,MAAM,OAAO,GAAG,KAAK,CAAC,aAA2D,CAAC;IAElF,qEAAqE;IACrE,EAAE;IACF,6FAA6F;IAC7F,2FAA2F;IAC3F,kGAAkG;IAClG,qCAAqC;IACrC,EAAE;IACF,iGAAiG;IACjG,4FAA4F;IAC5F,gGAAgG;IAChG,gGAAgG;IAChG,mDAAmD;IACnD,MAAM,cAAc,GAClB,CAAC,OAAO,OAAO,EAAE,cAAc,KAAK,QAAQ,IAAI,OAAO,CAAC,cAAc,CAAC;WACpE,gBAAgB,CAAC,oBAAoB,EAAE,CAAC,kCAAkC,CAAC,gBAAgB,CAAC,aAAa,CAAU,CAAC,CAAC;IAE1H,MAAM,WAAW,GACf,CAAC,OAAO,KAAK,EAAE,WAAW,KAAK,QAAQ,IAAI,KAAK,CAAC,WAAW,CAAC;WAC1D,CAAC,OAAO,OAAO,EAAE,WAAW,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAElF,MAAM,UAAU,GACd,CAAC,OAAO,KAAK,EAAE,UAAU,KAAK,QAAQ,IAAI,KAAK,CAAC,UAAU,CAAC;WACxD,CAAC,OAAO,OAAO,EAAE,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAEhF,IAAI,OAAO,cAAc,KAAK,QAAQ,IAAI,CAAC,cAAc,IAAI,CAAC,WAAW,IAAI,CAAC,UAAU,EAAE,CAAC;QACzF,8FAA8F;QAC9F,uFAAuF;QACvF,MAAM,KAAK,CAAC,YAAY,CAAC,UAAU,CAAC,SAAS,CAAC,aAAa,EAAE,gBAAgB,EAAE;YAC7E,sBAAsB,EAAE,2BAA2B,CAAC,aAAa;YACjE,OAAO,EAAE;gBACP,OAAO,EACL,gGAAgG;sBAC9F,oGAAoG;sBACpG,mGAAmG;gBACvG,iBAAiB,EAAE,OAAO,CAAC,cAAc,CAAC;gBAC1C,cAAc,EAAE,OAAO,CAAC,WAAW,CAAC;gBACpC,aAAa,EAAE,OAAO,CAAC,UAAU,CAAC;aACnC;SACF,CAAC,CAAC;IACL,CAAC;IAED,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,UAAU,EAAE,CAAC;AACrD,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,kBAAkB,CACzB,KAA0C,EAC1C,gBAAuC,EACvC,KAAmD,EACnD,SAAoB;IAEpB,MAAM,OAAO,GAAG,KAAK,IAAI,SAAS,CAAC;IACnC,MAAM,QAAQ,GAAG,OAAO,EAAE,WAAW,CAAC;IAEtC,8FAA8F;IAC9F,sCAAsC;IACtC,EAAE;IACF,+FAA+F;IAC/F,mGAAmG;IACnG,iGAAiG;IACjG,6FAA6F;IAC7F,gGAAgG;IAChG,0BAA0B;IAC1B,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,mGAAmG;IACnG,+FAA+F;IAC/F,4EAA4E;IAC5E,IAAI,QAAQ,KAAK,sBAAsB,EAAE,CAAC;QACxC,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE,GAAG,IAAI,EAAE,GAAG,OAAkC,CAAC;QAChF,OAAO,IAAI,CAAC;IACd,CAAC;IAED,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1D,MAAM,KAAK,CAAC,YAAY,CAAC,UAAU,CAAC,SAAS,CAAC,UAAU,EAAE,gBAAgB,EAAE;YAC1E,sBAAsB,EAAE,2BAA2B,CAAC,UAAU;YAC9D,OAAO,EAAE,EAAE,OAAO,EAAE,uEAAuE,EAAE;SAC9F,CAAC,CAAC;IACL,CAAC;IAED,MAAM,QAAQ,GAAG,oBAAoB,CAAC,OAAO,EAAE,gBAAgB,EAAE,KAAK,CAAC,CAAC;IACxE,MAAM,SAAS,GAAG,SAAS,CAAC,GAAG,CAA0B,kBAAkB,CAAC,gBAAgB,CAAC,CAAC;IAE9F,MAAM,YAAY,GAAG,gBAAgB,EAAE,YAAY,EAAE,MAAM,CAAC;IAE5D,OAAO;QACL,GAAG,OAAO;QACV,WAAW,EAAE,sBAAsB,CACjC,QAAQ,EACR,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,aAAa,EAChD;YACE,UAAU,EAAE,sCAAsC,CAAC,YAAY;YAC/D,OAAO,EAAE,QAAQ,CAAC,cAAc;YAChC,WAAW,EAAE,QAAQ,CAAC,WAAW;YACjC,UAAU,EAAE,QAAQ,CAAC,UAAU;SAChC,CACF;QACD,kGAAkG;QAClG,+FAA+F;QAC/F,mFAAmF;QACnF,WAAW,EAAE,IAAI,IAAI,EAAE;QACvB,iGAAiG;QACjG,4FAA4F;QAC5F,mEAAmE;QACnE,GAAG,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACvD,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,KAAK,UAAU,wBAAwB,CACrC,SAAoB;AACpB;;;;;GAKG;AACH,SAE0E,EAC1E,GAA+C,EAC/C,mBAAqC,EACrC,gBAAuC,EACvC,KAAmD;IAEnD,IAAI,CAAC,GAAG,IAAI,OAAO,GAAG,CAAC,GAAG,KAAK,QAAQ,IAAI,OAAO,GAAG,CAAC,cAAc,KAAK,QAAQ,EAAE,CAAC;QAClF,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,CAClB,+GAA+G,EAC/G,EAAE,SAAS,EAAE,CACd,CAAC;QACF,OAAO;IACT,CAAC;IAED,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,SAAS,CAAC,GAAG,CAA0B,kBAAkB,CAAC,gBAAgB,CAAC,CAAC;QAC9F,MAAM,MAAM,GAAG;YACb,cAAc,EAAE,GAAG,CAAC,cAAc;YAClC,WAAW,EAAE,GAAG,CAAC,WAAW;YAC5B,UAAU,EAAE,GAAG,CAAC,UAAU;YAC1B,YAAY,EAAE,GAAG,CAAC,GAAG;SACtB,CAAC;QACF,IAAI,SAAS,KAAK,sBAAsB,CAAC,oCAAoC,EAAE,CAAC;YAC9E,MAAM,SAAS,CAAC,oCAAoC,CAClD,EAAE,GAAG,MAAM,EAAE,KAAK,EAAE,mBAAmB,CAAC,gBAAgB,CAAC,EAAE,EAC3D,gBAAgB,CACjB,CAAC;QACJ,CAAC;aAAM,CAAC;YACN,MAAM,SAAS,CAAC,wCAAwC,CACtD;gBACE,GAAG,MAAM;gBACT,SAAS,EAAE,mBAAmB,CAAC,gBAAgB,CAAC;gBAChD,mBAAmB,EAAE,mBAAmB,EAAE,WAAW,EAAE;aACxD,EACD,gBAAgB,CACjB,CAAC;QACJ,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,iEAAiE,EAAE;YACtF,SAAS;YACT,YAAY,EAAE,GAAG,CAAC,GAAG;YACrB,GAAG,2BAA2B,CAAC,KAAK,CAAC;SACtC,CAAC,CAAC;IACL,CAAC;AACH,CAAC;AAED;;GAEG;AACH,SAAS,6BAA6B;IACpC,MAAM,OAAO,GAAG,CAAC,SAA0C,EAAE,SAAoB,EAAE,EAAE,CACnF,yCAAyC,CAAC;QACxC,aAAa,EAAE;YACb,kBAAkB,EAAE,gBAAgB,CAAC,wBAAwB;YAC7D,mBAAmB,EAAE,qBAAqB,CAAC,MAAM;YACjD,WAAW,EAAE,4BAA4B,CAAC,QAAQ;YAClD,kBAAkB,EAAE,IAAI;SACzB;QACD,UAAU,EAAE,uDAAuD;QACnE;;;;;;;;;;;;;;WAcG;QACH,mBAAmB,EAAE,CAAC,aAAa,EAAE,aAAa,EAAE,aAAa,CAAC;QAClE,QAAQ,EAAE;YACR,oBAAoB,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,KAAK,EAAE,EAAE,CAClF,kBAAkB,CAAC,KAA4C,EAAE,gBAAgB,EAAE,KAAK,EAAE,SAAS,CAAC;YACtG,qBAAqB,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,KAAK,EAAE,EAAE;gBACrF,MAAM,wBAAwB,CAC5B,SAAS,EACT,sBAAsB,CAAC,oCAAoC,EAC3D,OAAqD,EACrD,SAAS,EACT,gBAAgB,EAChB,KAAK,CACN,CAAC;gBACF,OAAO,OAAO,CAAC;YACjB,CAAC;SACF;KACF,CAAC,CAAC;IACL,OAAO,OAAgE,CAAC;AAC1E,CAAC;AAED;;;;;;GAMG;AACH,SAAS,6BAA6B;IACpC,MAAM,OAAO,GAAG,CAAC,SAA0C,EAAE,SAAoB,EAAE,EAAE,CACnF,yCAAyC,CAAC;QACxC,aAAa,EAAE;YACb,kBAAkB,EAAE,gBAAgB,CAAC,wBAAwB;YAC7D,mBAAmB,EAAE,qBAAqB,CAAC,MAAM;YACjD,WAAW,EAAE,4BAA4B,CAAC,QAAQ;YAClD,kBAAkB,EAAE,IAAI;SACzB;QACD,UAAU,EAAE,uDAAuD;QACnE;;;;;;;;;;;;;;WAcG;QACH,mBAAmB,EAAE,CAAC,aAAa,EAAE,aAAa,EAAE,aAAa,CAAC;QAClE,QAAQ,EAAE;YACR,oBAAoB,EAAE,KAAK,EAAE,GAAG,EAAE,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,KAAK,EAAE,EAAE;gBAClF,MAAM,MAAM,GAAG,kBAAkB,CAC/B,KAA4C,EAC5C,gBAAgB,EAChB,KAAK,EACL,SAAS,CACV,CAAC;gBACF,2FAA2F;gBAC3F,2FAA2F;gBAC3F,qBAAqB,CAAC,GAAG,CAAC,gBAAgB,EAAE;oBAC1C,OAAO,EAAE,MAAM,EAAE,WAAW,KAAK,SAAS;oBAC1C,mBAAmB,EAAG,KAAK,CAAC,aAA4D,EAAE,WAAW;iBACtG,CAAC,CAAC;gBACH,OAAO,MAAM,CAAC;YAChB,CAAC;YACD,qBAAqB,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,KAAK,EAAE,EAAE;gBACrF,MAAM,MAAM,GAAG,qBAAqB,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;gBAC3D,qBAAqB,CAAC,MAAM,CAAC,gBAAgB,CAAC,CAAC;gBAC/C,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;oBACpB,MAAM,wBAAwB,CAC5B,SAAS,EACT,sBAAsB,CAAC,wCAAwC,EAC/D,OAAqD,EACrD,MAAM,CAAC,mBAAmB,EAC1B,gBAAgB,EAChB,KAAK,CACN,CAAC;gBACJ,CAAC;gBACD,OAAO,OAAO,CAAC;YACjB,CAAC;SACF;KACF,CAAC,CAAC;IACL,OAAO,OAAgE,CAAC;AAC1E,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,6BAA6B;IACpC,MAAM,OAAO,GAAG,CAAC,SAA0C,EAAE,SAAoB,EAAE,EAAE,CACnF,yCAAyC,CAAC;QACxC,aAAa,EAAE;YACb,kBAAkB,EAAE,gBAAgB,CAAC,wBAAwB;YAC7D,mBAAmB,EAAE,qBAAqB,CAAC,MAAM;YACjD,WAAW,EAAE,4BAA4B,CAAC,QAAQ;YAClD,kBAAkB,EAAE,IAAI;SACzB;QACD,UAAU,EAAE,8CAA8C;QAC1D,QAAQ,EAAE;YACR,qBAAqB,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,gBAAgB,EAAE,cAAc,EAAE,KAAK,EAAE,EAAE;gBACnF,6FAA6F;gBAC7F,yDAAyD;gBACzD,MAAM,QAAQ,GAAG,KAAK,CAAC,aAA2D,CAAC;gBACnF,MAAM,YAAY,GAAG,QAAQ,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;gBAEhF,IAAI,CAAC,QAAQ,EAAE,cAAc,IAAI,CAAC,YAAY,EAAE,CAAC;oBAC/C,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,CAClB,iHAAiH,EACjH,EAAE,eAAe,EAAE,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,EAAE,EAAE,CAC7D,CAAC;oBACF,OAAO,MAAM,CAAC;gBAChB,CAAC;gBAED,IAAI,CAAC;oBACH,MAAM,SAAS,GAAG,SAAS,CAAC,GAAG,CAA0B,kBAAkB,CAAC,gBAAgB,CAAC,CAAC;oBAC9F,MAAM,SAAS,CAAC,wCAAwC,CACtD;wBACE,cAAc,EAAE,QAAQ,CAAC,cAAc;wBACvC,WAAW,EAAE,QAAQ,CAAC,WAAW;wBACjC,UAAU,EAAE,QAAQ,CAAC,UAAU;wBAC/B,YAAY;wBACZ,MAAM,EAAE,gCAAgC,CAAC,qBAAqB;wBAC9D,SAAS,EAAE,mBAAmB,CAAC,gBAAgB,CAAC;qBACjD,EACD,gBAAgB,CACjB,CAAC;gBACJ,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,0EAA0E,EAAE;wBAC/F,YAAY;wBACZ,GAAG,2BAA2B,CAAC,KAAK,CAAC;qBACtC,CAAC,CAAC;gBACL,CAAC;gBACD,OAAO,MAAM,CAAC;YAChB,CAAC;SACF;KACF,CAAC,CAAC;IACL,OAAO,OAAgE,CAAC;AAC1E,CAAC;AAED;;;;;GAKG;AACH,MAAM,qBAAqB,GAAG,IAAI,OAAO,EAA4D,CAAC;AAEtG,yEAAyE;AACzE,MAAM,UAAU,6CAA6C;IAC3D,OAAO;QACL,6BAA6B,EAAE;QAC/B,6BAA6B,EAAE;QAC/B,6BAA6B,EAAE;KAChC,CAAC;AACJ,CAAC","sourcesContent":["/**\n * The WRITE path for an organization's provider credential: seal on the way in, audit on the way\n * 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 credential persisted in plaintext behind a\n * green suite. The pins in `__tests__/organization-provider-credentials-write-path.backend.test.ts`\n * assert these registrations against the REAL resource configuration for that reason.\n *\n * ## The DELETE doors — enumerated, because only one of them reaches this file\n *\n * | Door | Path | This hook |\n * |---|---|---|\n * | A tenant administrator revoking a credential | service tier, `DELETE` default variant | RUNS |\n * | The ORGANIZATIONS purge cascade (both the batch's route-less default door and the super-admin's `admin` door reach the same cascade) | `deleteChildrenImmediate` → the RAW repository | does NOT run |\n *\n * Door 2 is not an oversight and not a hole in the ERASURE: the cascade removes the rows, which is\n * what matters, and `services-registry-handler.backend.service.ts` documents the raw-repository\n * route explicitly (\"VARIANT-AGNOSTIC CASCADE: the onParentDelete teardown deletes children directly\n * through the RAW repository\"). What door 2 has no way to produce is a per-credential AUDIT event,\n * because the service tier — where custom implementations live — is bypassed entirely. Emitting one\n * would need a cascade-tier audit hook in the framework, which is outside this resource. The tenant\n * purge is itself audited as `ORGANIZATION_DELETED`, so the destruction is on the record; what is\n * missing is the enumeration of WHICH third parties the tenant held credentials for at that moment.\n * Recorded as its own issue rather than left for a reader to discover from an absence.\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 OrganizationProviderCredential,\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 { resolveAuditActorId } from '~wildo-backend-lib/compliance/audit-trails/utils/audit-actor.backend.utils';\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 CredentialWriteIdentity {\n  organizationId: string;\n  providerRef: string;\n  secretSlug: string;\n}\n\n/**\n * Resolve the row identity for a write.\n *\n * The three parts come from three DIFFERENT places, and that is the reason this is a function rather\n * than three property reads:\n *\n * - `organizationId` is injected by the context machinery from the request SCOPE, so on CREATE it is\n *   not in the input payload at all. The execution context's context-resource map is the\n *   authoritative channel — the same one `buildContextualFilter` and `enrichDataWithContext` read —\n *   which is what makes the seal bind to the tenant the framework will actually store the row under,\n *   rather than to one a caller could name in a body field.\n * - `providerRef` / `secretSlug` are client-supplied on CREATE and `.excludeFromUpdate()` afterwards,\n *   so on UPDATE they must come from the pre-fetched current row.\n */\nfunction resolveWriteIdentity(\n  input: Record<string, unknown> | undefined,\n  executionContext: ExecutionContext<any>,\n  utils: ResourceOperation_CustomImplementation_Utils,\n): CredentialWriteIdentity {\n  const current = utils.currentObject as OrganizationProviderCredential | undefined;\n\n  // Two sources, and the request BODY is deliberately not one of them.\n  //\n  // On UPDATE the stored row is authoritative — it is what the framework already persisted. On\n  // CREATE the execution context's context-resource map is, because that is the same channel\n  // `enrichDataWithContext` reads when it injects the scope FK, so the seal binds to the tenant the\n  // row will actually be stored under.\n  //\n  // A `payload.organizationId` fallback was here and was REMOVED: it fails safe (a seal bound to a\n  // body-supplied tenant is simply unopenable later, so the outcome is a denial rather than a\n  // disclosure) but it is still the request choosing what the seal binds to, which is exactly the\n  // authorship this hook exists to keep out of a caller's hands. With no fallback, a context that\n  // cannot name the tenant is a REFUSAL — see below.\n  const organizationId =\n    (typeof current?.organizationId === 'string' && current.organizationId)\n    || executionContext.getContextResourceId?.(coreResourceShared_FieldIdentifier[CoreResourceType.ORGANIZATIONS] 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 organizationId !== 'string' || !organizationId || !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 an organization provider credential: the row identity is incomplete. All three of '\n          + 'organizationId, providerRef and secretSlug must be resolvable, because the seal is bound to them. '\n          + 'The organization is read from the execution scope or the stored row, never from the request body.',\n        hasOrganizationId: Boolean(organizationId),\n        hasProviderRef: Boolean(providerRef),\n        hasSecretSlug: Boolean(secretSlug),\n      },\n    });\n  }\n\n  return { organizationId, providerRef, secretSlug };\n}\n\n/**\n * Seal `secretValue` if the write carries one.\n *\n * An ABSENT `secretValue` is normal on UPDATE and must pass through untouched: the framework strips\n * the field when a client echoes back the redaction mask, which is how \"edit the description without\n * retyping the secret\" works. Re-sealing nothing would be harmless; treating absence as an error\n * would break the ordinary edit.\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 payload = input ?? undefined;\n  const incoming = payload?.secretValue;\n\n  // ABSENT means \"no change\", and only absent. `null` is deliberately NOT treated as absent and\n  // falls through to the refusal below.\n  //\n  // That distinction became load-bearing the moment `secretValue` was declared authoritative: an\n  // authoritative field's post-prefix value is always carried past the repository's strict re-parse,\n  // so passing a `null` through here would push it INTO persistence rather than letting the schema\n  // reject it. The row would then hold a null where `z.string().min(1)` is required, and every\n  // later read would throw in `transformOutput` — a write that answers success and leaves the row\n  // permanently unreadable.\n  if (incoming === undefined) {\n    return payload;\n  }\n\n  // Defence in depth. The framework strips the mask sentinel before this hook runs, so reaching here\n  // with the mask means that strip did not happen — and sealing the mask would store the literal\n  // bullet characters as the tenant's credential, then hand them to a vendor.\n  if (incoming === WRITE_ONLY_SECRET_MASK) {\n    const { secretValue: _discarded, ...rest } = payload as Record<string, unknown>;\n    return rest;\n  }\n\n  if (typeof incoming !== 'string' || incoming.length === 0) {\n    throw utils.errorBuilder.buildError(ErrorType.VALIDATION, executionContext, {\n      customMessageReference: ErrorCustomMessageReference.VALIDATION,\n      context: { message: 'An organization provider credential value must be a non-empty string.' },\n    });\n  }\n\n  const identity = resolveWriteIdentity(payload, executionContext, utils);\n  const appConfig = container.get<AppConfigurationService>(SAAS_SERVICE_TYPES.AppConfigService);\n\n  const actingUserId = executionContext?.initiatorIds?.userId;\n\n  return {\n    ...payload,\n    secretValue: sealProviderCredential(\n      incoming,\n      appConfig.secrets.security.session.encryptionKey,\n      {\n        ownerScope: ExternalProvider_Connection_OwnerScope.ORGANIZATION,\n        ownerId: identity.organizationId,\n        providerRef: identity.providerRef,\n        secretSlug: identity.secretSlug,\n      },\n    ),\n    // Server-owned provenance. Both are `.excludeFromCreate().excludeFromUpdate()`, so returning them\n    // here is what carries them past the strict re-parse — the same mechanism api-key minting uses\n    // for its hashed material, and declared explicitly in `authoritativeFields` below.\n    secretSetAt: new Date(),\n    // Only when there IS an acting user. Writing the key with an `undefined` value would preserve an\n    // explicit `undefined` past the re-parse rather than leaving the field absent, and \"absent\"\n    // is the honest representation of a write with no human behind it.\n    ...(actingUserId ? { setByUserId: actingUserId } : {}),\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 tenant their write\n * failed when it did not.\n */\nasync function emitCredentialWriteAudit(\n  container: Container,\n  /**\n   * WHICH grant event this write is. Typed as the audit vocabulary's own two members rather than a\n   * bespoke `'set' | 'rotated'` pair: the distinction already has a named runtime source, and a\n   * second spelling of it would be a closed vocabulary with no home and one more thing to keep in\n   * step with the event names.\n   */\n  eventType:\n    | typeof CoreAuditableEventType.ORGANIZATION_PROVIDER_CREDENTIAL_SET\n    | typeof CoreAuditableEventType.ORGANIZATION_PROVIDER_CREDENTIAL_ROTATED,\n  row: OrganizationProviderCredential | 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.organizationId !== 'string') {\n    utils.logger.error?.(\n      'An organization 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    const common = {\n      organizationId: row.organizationId,\n      providerRef: row.providerRef,\n      secretSlug: row.secretSlug,\n      credentialId: row._id,\n    };\n    if (eventType === CoreAuditableEventType.ORGANIZATION_PROVIDER_CREDENTIAL_SET) {\n      await auditLogs.logOrganizationProviderCredentialSet(\n        { ...common, setBy: resolveAuditActorId(executionContext) },\n        executionContext,\n      );\n    } else {\n      await auditLogs.logOrganizationProviderCredentialRotated(\n        {\n          ...common,\n          rotatedBy: resolveAuditActorId(executionContext),\n          previousSecretSetAt: previousSecretSetAt?.toISOString(),\n        },\n        executionContext,\n      );\n    }\n  } catch (error) {\n    utils.logger.error?.('Failed to emit the organization provider credential audit event', {\n      eventType,\n      credentialId: row._id,\n      ...projectCaughtErrorLogFields(error),\n    });\n  }\n}\n\n/**\n * CREATE — the tenant grants this application authority toward a third party for the first time.\n */\nfunction createCredentialCreateFactory(): ResourceCustomServiceImplementationFactory {\n  const factory = (_registry: ResourcesRegistryBackendService, container: Container) =>\n    createResourceCustomServiceImplementation({\n      operationPath: {\n        resourceIdentifier: CoreResourceType.ORG_PROVIDER_CREDENTIALS,\n        operationIdentifier: CoreResourceOperation.CREATE,\n        variantType: ResourceOperationVariantType.API_CALL,\n        isOperationDefault: true,\n      },\n      debugLabel: 'organizationProviderCredentials.create.seal-and-audit',\n      /**\n       * The three 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 — MCP `callTool` forwards its\n       * arguments with no strict parse — puts it into the snapshot, the hook's value is then not\n       * classified as introduced, and the repository strips it while the operation answers success.\n       *\n       * For `secretSetAt` / `setByUserId` that would silently lose the provenance of a credential,\n       * which is the first thing an incident asks for. For `secretValue` the declaration says the\n       * thing that matters most in this file: whatever a caller sent, what reaches persistence is\n       * the POST-prefix value — the sealed envelope — and never the plaintext they supplied.\n       */\n      authoritativeFields: ['secretValue', 'secretSetAt', 'setByUserId'],\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.ORGANIZATION_PROVIDER_CREDENTIAL_SET,\n            created as OrganizationProviderCredential | 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 * changes the description emits nothing: a rotation event on a description change would make the\n * one signal a compromise investigation depends on unusable.\n */\nfunction createCredentialUpdateFactory(): ResourceCustomServiceImplementationFactory {\n  const factory = (_registry: ResourcesRegistryBackendService, container: Container) =>\n    createResourceCustomServiceImplementation({\n      operationPath: {\n        resourceIdentifier: CoreResourceType.ORG_PROVIDER_CREDENTIALS,\n        operationIdentifier: CoreResourceOperation.UPDATE,\n        variantType: ResourceOperationVariantType.API_CALL,\n        isOperationDefault: true,\n      },\n      debugLabel: 'organizationProviderCredentials.update.seal-and-audit',\n      /**\n       * The three 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 — MCP `callTool` forwards its\n       * arguments with no strict parse — puts it into the snapshot, the hook's value is then not\n       * classified as introduced, and the repository strips it while the operation answers success.\n       *\n       * For `secretSetAt` / `setByUserId` that would silently lose the provenance of a credential,\n       * which is the first thing an incident asks for. For `secretValue` the declaration says the\n       * thing that matters most in this file: whatever a caller sent, what reaches persistence is\n       * the POST-prefix value — the sealed envelope — and never the plaintext they supplied.\n       */\n      authoritativeFields: ['secretValue', 'secretSetAt', 'setByUserId'],\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 OrganizationProviderCredential | 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.ORGANIZATION_PROVIDER_CREDENTIAL_ROTATED,\n              updated as OrganizationProviderCredential | 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 — a tenant administrator revoking the grant.\n *\n * `ADMINISTRATOR_REVOKED` unconditionally, and that is CORRECT rather than an assumption: the\n * cascade door never reaches this hook (see the module header), so every delete that arrives here is\n * a deliberate service-tier revocation. If a future change routed a cascade through the service\n * tier, this constant would become a lie — which is why the door table above is pinned by a test\n * rather than left as prose.\n */\nfunction createCredentialDeleteFactory(): ResourceCustomServiceImplementationFactory {\n  const factory = (_registry: ResourcesRegistryBackendService, container: Container) =>\n    createResourceCustomServiceImplementation({\n      operationPath: {\n        resourceIdentifier: CoreResourceType.ORG_PROVIDER_CREDENTIALS,\n        operationIdentifier: CoreResourceOperation.DELETE,\n        variantType: ResourceOperationVariantType.API_CALL,\n        isOperationDefault: true,\n      },\n      debugLabel: 'organizationProviderCredentials.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 OrganizationProviderCredential | undefined;\n          const credentialId = snapshot?._id ?? (typeof id === 'string' ? id : undefined);\n\n          if (!snapshot?.organizationId || !credentialId) {\n            utils.logger.error?.(\n              'An organization 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.logOrganizationProviderCredentialDeleted(\n              {\n                organizationId: snapshot.organizationId,\n                providerRef: snapshot.providerRef,\n                secretSlug: snapshot.secretSlug,\n                credentialId,\n                reason: ProviderCredentialDeletionReason.ADMINISTRATOR_REVOKED,\n                deletedBy: resolveAuditActorId(executionContext),\n              },\n              executionContext,\n            );\n          } catch (error) {\n            utils.logger.error?.('Failed to emit the organization 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 organization-provider-credential resource. */\nexport function createOrganizationProviderCredentialFactories(): ResourceCustomServiceImplementationFactory[] {\n  return [\n    createCredentialCreateFactory(),\n    createCredentialUpdateFactory(),\n    createCredentialDeleteFactory(),\n  ];\n}\n"]}

package/dist/esm/security/connected-accounts/services/provider-oauth2-exchange.backend.d.ts

@@ -0,0 +1,160 @@
+/**
+ * The OAuth2 authorization-code exchange, as three pure-ish functions.
+ *
+ * This is the half of the connect flow that has no HTTP route, no session and no database: build the
+ * URL a person is sent to, turn the code they come back with into a grant, and renew a grant that is
+ * about to expire. The route, the state record and the store are a thin shell around it.
+ *
+ * Written as functions over an explicit contract rather than as a service with injected collaborators
+ * for one reason: every interesting failure here is a WRONG STRING — a placeholder that was never
+ * resolved, a scope set that silently shrank, a redirect URI that does not match the one registered.
+ * Those are answerable by a unit test only if the inputs are arguments, and they are the failures
+ * that reach a person as "the vendor says no" with nothing local to look at.
+ *
+ * ## What this deliberately does NOT do
+ *
+ * It does not store anything, does not read a credential, and does not decide WHO may connect. The
+ * connection target (whose account is being connected) and its admissibility are decided before this
+ * is reached, by the same two gates every other credential path goes through.
+ *
+ * assurance-control: WILDO.IDENTITY.DELEGATED_AUTHORIZATION — the authorization exchange by which a
+ * principal grants this application access to a third party on their behalf.
+ */
+import type { ProviderRestOAuth2 } from '@wildo-ai/external-connectors-models';
+import { type ProviderOAuth2Grant } from '@wildo-ai/saas-models';
+/** Raised when an exchange cannot be built or completed. Never carries a token or a client secret. */
+export declare class ProviderOAuth2ExchangeError extends Error {
+    /**
+     * The vendor's own OAuth2 error code, when the failure was one the vendor NAMED.
+     *
+     * Carried structurally rather than only inside the message, because one caller has to act on it
+     * differently from every other failure: a grant the vendor has permanently rejected must stop
+     * presenting itself as a working connection, while a token endpoint that was merely unreachable
+     * must not. Both arrive here as the same class, and a message substring is not something to branch
+     * a person's account state on.
+     *
+     * Absent for transport failures, unparseable bodies and bare HTTP statuses — cases where the
+     * vendor said nothing about the grant, and where assuming anything about it would be a guess.
+     */
+    readonly oauth2ErrorCode?: string;
+    constructor(message: string, oauth2ErrorCode?: string);
+}
+/**
+ * Is this failure the vendor saying the grant itself is finished?
+ *
+ * TRUE for exactly one code. `invalid_grant` is defined as an authorization grant or refresh token
+ * that is invalid, expired, revoked, or was issued to another client — every one of which is
+ * permanent for THIS connection and none of which a retry improves.
+ * spec-cite: RFC 6749 §5.2 (invalid_grant).
+ *
+ * Deliberately NOT `invalid_client`, and that exclusion is the substantive half. `invalid_client`
+ * means the APPLICATION's own registration was rejected — a wrong client secret, a deleted vendor
+ * app — which is an operator's problem affecting every connection at once. Treating it as a dead
+ * grant would mark every person's account invalid and invite them all to reconnect, which cannot
+ * work and would blame them for a misconfiguration they cannot see.
+ *
+ * Also FALSE for every failure the vendor did not name: a transport error, a non-JSON body, a bare
+ * 500. A vendor that was unreachable has said nothing about the grant, and a connection must not be
+ * retired on our inability to ask.
+ */
+export declare function providerOAuth2GrantWasPermanentlyRejected(error: unknown): boolean;
+/**
+ * The PKCE pair for one authorization attempt.
+ *
+ * PKCE is applied to EVERY exchange, including confidential-client ones that hold a secret, and that
+ * is a deliberate default rather than a requirement of the grant type. It costs one hash and it
+ * closes authorization-code interception, which is reachable here because the code arrives on a
+ * redirect through the person's own browser — a channel this application does not control.
+ * spec-cite: RFC 7636 §4.1–4.2 (code_verifier, code_challenge, S256).
+ */
+export interface ProviderOAuth2Pkce {
+    readonly verifier: string;
+    readonly challenge: string;
+    readonly method: 'S256';
+}
+export declare function createProviderOAuth2Pkce(): ProviderOAuth2Pkce;
+/**
+ * Compare two opaque values in constant time.
+ *
+ * Used for the `state` echo. A plain `===` leaks the position of the first differing byte through
+ * timing, and `state` is the CSRF defence for the whole flow: an attacker who can guess it can graft
+ * their own authorization code onto somebody else's connect attempt.
+ */
+export declare function providerOAuth2ValuesMatch(left: string, right: string): boolean;
+/** A fresh, unguessable `state` for one authorization attempt. */
+export declare function createProviderOAuth2State(): string;
+/**
+ * Resolve the `{placeholder}` holes an endpoint carries from the connection's own parameters.
+ *
+ * REFUSES on a missing value rather than leaving the brace in place. A URL still carrying
+ * `{tenantId}` is not a URL: it would be sent to the person's browser, fail to resolve as a
+ * hostname, and present as "the vendor is down" — a very long way from "nobody asked which
+ * directory". 21 of the 96 vendors that recovered both endpoints are in this population.
+ */
+export declare function resolveEndpointPlaceholders(url: string, connectionParameters: Readonly<Record<string, string>>, providerRef: string): string;
+export interface BuildAuthorizeUrlInput {
+    readonly oauth2: ProviderRestOAuth2;
+    readonly providerRef: string;
+    readonly clientId: string;
+    /** Where the vendor sends the person back. Must be byte-identical to what is registered there. */
+    readonly redirectUri: string;
+    readonly state: string;
+    readonly pkce: ProviderOAuth2Pkce;
+    /** Values for the endpoints' `{placeholders}`, supplied by whoever is connecting. */
+    readonly connectionParameters?: Readonly<Record<string, string>>;
+    /**
+     * Scopes to request. Falls back to the vendor's own catalogue-declared set.
+     *
+     * Overridable because the catalogue's set is what the SOURCE asked for across every action it
+     * described, which is routinely broader than one application needs — and an over-broad consent
+     * screen is a thing a person refuses.
+     */
+    readonly scopes?: readonly string[];
+}
+/**
+ * The URL a person is sent to in order to grant access.
+ *
+ * Query parameters are MERGED into whatever the vendor's own authorize URL already carries rather
+ * than appended blindly. That is not tidiness: Slack's catalogue-declared authorize URL arrives with
+ * a `?user_scope=…` query string baked in, so appending `?client_id=…` would produce a URL with two
+ * `?` and a vendor that rejects it. One vendor of 129 does this today, which is exactly the kind of
+ * single-instance shape that a naive concatenation gets wrong forever.
+ */
+export declare function buildProviderOAuth2AuthorizeUrl(input: BuildAuthorizeUrlInput): string;
+export interface TokenExchangeInput {
+    readonly oauth2: ProviderRestOAuth2;
+    readonly providerRef: string;
+    readonly clientId: string;
+    readonly clientSecret: string;
+    readonly connectionParameters?: Readonly<Record<string, string>>;
+    readonly fetchImpl?: typeof fetch;
+}
+/**
+ * Turn the authorization code into a grant.
+ *
+ * The client credentials go in the BODY (`client_secret_post`) rather than a Basic header. Both are
+ * specified and a server must support Basic, but the body form is what every major vendor's own
+ * documentation shows and what their sandboxes accept; a vendor that requires Basic is a per-vendor
+ * deviation for an authored supplement.
+ * spec-cite: RFC 6749 §2.3.1 (client_secret_basic is required of servers; the body form is permitted).
+ */
+export declare function exchangeProviderOAuth2Code(input: TokenExchangeInput & {
+    readonly code: string;
+    readonly redirectUri: string;
+    readonly pkceVerifier: string;
+}): Promise<ProviderOAuth2Grant>;
+/**
+ * Renew a grant that is expiring.
+ *
+ * Carries the PREVIOUS grant's refresh token forward when the vendor does not return a new one.
+ * That is the difference between a connection that survives and one that dies on its second
+ * refresh: some vendors rotate the refresh token on every use and return the replacement, and
+ * others return only an access token and expect the original refresh token to be reused. Dropping
+ * it in the second case leaves a grant that cannot be refreshed again, and the failure arrives an
+ * hour later with nothing pointing at this function.
+ * spec-cite: RFC 6749 §6 (the authorization server MAY issue a new refresh token).
+ */
+export declare function refreshProviderOAuth2Grant(input: TokenExchangeInput & {
+    readonly grant: ProviderOAuth2Grant;
+}): Promise<ProviderOAuth2Grant>;
+//# sourceMappingURL=provider-oauth2-exchange.backend.d.ts.map

package/dist/esm/security/connected-accounts/services/provider-oauth2-exchange.backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-oauth2-exchange.backend.d.ts","sourceRoot":"","sources":["../../../../../../src/security/connected-accounts/services/provider-oauth2-exchange.backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAIH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAC/E,OAAO,EAAgC,KAAK,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAE/F,sGAAsG;AACtG,qBAAa,2BAA4B,SAAQ,KAAK;IACpD;;;;;;;;;;;OAWG;IACH,SAAgB,eAAe,CAAC,EAAE,MAAM,CAAC;gBAE7B,OAAO,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM;CAKtD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,yCAAyC,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEjF;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,wBAAwB,IAAI,kBAAkB,CAU7D;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAK9E;AAED,kEAAkE;AAClE,wBAAgB,yBAAyB,IAAI,MAAM,CAElD;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CACzC,GAAG,EAAE,MAAM,EACX,oBAAoB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,EACtD,WAAW,EAAE,MAAM,GAClB,MAAM,CAaR;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,kGAAkG;IAClG,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,qFAAqF;IACrF,QAAQ,CAAC,oBAAoB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACjE;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED;;;;;;;;GAQG;AACH,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,sBAAsB,GAAG,MAAM,CAgCrF;AAaD,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,oBAAoB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACjE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CACnC;AAED;;;;;;;;GAQG;AACH,wBAAsB,0BAA0B,CAC9C,KAAK,EAAE,kBAAkB,GAAG;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GACjH,OAAO,CAAC,mBAAmB,CAAC,CAO9B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,0BAA0B,CAC9C,KAAK,EAAE,kBAAkB,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,mBAAmB,CAAA;CAAE,GAClE,OAAO,CAAC,mBAAmB,CAAC,CAoB9B"}