@wildo-ai/saas-backend-lib 1.1.2 → 1.1.4

package/dist/esm/security/connected-accounts/services/organization-provider-credential-store.backend.service.d.ts

@@ -0,0 +1,210 @@
+/**
+ * The organization-provider-credential STORE — the port implementation the registry consults.
+ *
+ * ## What makes the isolation structural rather than a filter
+ *
+ * Three independent mechanisms have to agree before a credential is handed back, and none of them
+ * is a predicate somebody has to remember to write at each call site:
+ *
+ * 1. **The scope FK is injected by the context machinery.** The read goes through `readAsSystem`
+ *    with the organization in the system scope map, so `buildContextualFilter` adds the tenant
+ *    clause itself. A caller cannot omit it, because the caller never writes it.
+ * 2. **The filter names the organization explicitly as well.** Belt and braces, deliberately: the
+ *    contextual filter is injected by a mechanism that exists TWICE (a Mongo implementation and a
+ *    PostgreSQL one), so a regression in one adapter is a bypass in that adapter alone. The explicit
+ *    clause is adapter-independent and would still scope the read.
+ * 3. **The envelope is BOUND to the row identity.** Even a read that returned another tenant's row
+ *    would fail to OPEN it — the associated data is the organization, provider and slug, so the seal
+ *    itself refuses. This is the one that holds when the other two are wrong, which is why it exists.
+ *
+ * ## The store never accepts a caller-supplied organization from a request
+ *
+ * `organizationId` arrives from the calling code's trusted execution scope. The port cannot verify
+ * it — nothing at this tier can — so the honest statement is that the guarantee holds one level up,
+ * and the envelope binding is what keeps a mistake there from becoming a cross-tenant credential
+ * disclosure rather than merely a failed read.
+ */
+import { ProviderCredentialResolutionSource, type ProviderOAuth2Grant } from '@wildo-ai/saas-models';
+import type { LoggerService } from '../../../monitoring/logger/services/logger.service';
+import type { AppConfigurationService } from '../../../config/services/app-configuration.backend.service';
+import type { SystemAccessBackendService } from '../../../base-classes/services/services/system-access.backend.service';
+import type { AuditLogsBackendService } from '../../../compliance/audit-trails/services/audit-logs.backend.service';
+import { ProviderCredentialEnvelopeError } from '../utils/provider-credential-envelope.backend.utils';
+import type { ProviderOAuth2RefresherPort } from '../provider-oauth2-refresher.port';
+import type { OrganizationProviderCredentialQuery, OrganizationProviderCredentialResolution, OrganizationProviderCredentialResolverPort } from '../organization-provider-credential-resolver.port';
+export declare class OrganizationProviderCredentialStoreBackendService implements OrganizationProviderCredentialResolverPort {
+    private readonly logger;
+    private readonly appConfigService;
+    private readonly systemAccess;
+    /**
+     * OPTIONAL and lazily used, mirroring `SystemAccessBackendService`'s own treatment of it: audit
+     * emission must never be the reason a provider call fails, and a minimal test container must
+     * still be able to construct this service.
+     */
+    private readonly auditLogs?;
+    /**
+     * Appended LAST, deliberately: a parameter inserted mid-signature silently reassigns every
+     * positional argument after it, and this constructor is called positionally by several harnesses.
+     *
+     * OPTIONAL, and its absence is not a degradation — a store without one resolves every pasted
+     * credential and every non-expiring token exactly as before. Only an EXPIRING grant needs it, and
+     * that case refuses by name rather than sending a stale token.
+     */
+    private readonly refresher?;
+    constructor(logger: LoggerService, appConfigService: AppConfigurationService, systemAccess: SystemAccessBackendService, 
+    /**
+     * OPTIONAL and lazily used, mirroring `SystemAccessBackendService`'s own treatment of it: audit
+     * emission must never be the reason a provider call fails, and a minimal test container must
+     * still be able to construct this service.
+     */
+    auditLogs?: AuditLogsBackendService, 
+    /**
+     * Appended LAST, deliberately: a parameter inserted mid-signature silently reassigns every
+     * positional argument after it, and this constructor is called positionally by several harnesses.
+     *
+     * OPTIONAL, and its absence is not a degradation — a store without one resolves every pasted
+     * credential and every non-expiring token exactly as before. Only an EXPIRING grant needs it, and
+     * that case refuses by name rather than sending a stale token.
+     */
+    refresher?: ProviderOAuth2RefresherPort);
+    /**
+     * The organization's own credential, opened, or `undefined` when the tenant has not set one.
+     *
+     * See the port's JSDoc for why "absent" returns and "present but unopenable" throws.
+     */
+    resolveOrganizationCredential(query: OrganizationProviderCredentialQuery): Promise<OrganizationProviderCredentialResolution | undefined>;
+    /**
+     * The row, read through the system door.
+     *
+     * `readAsSystem` bypasses the CALLER's role check, not the tenant boundary — an outbound provider
+     * call legitimately happens on a batch, a queue consumer or an anonymous webhook return leg, none
+     * of which holds an ORG_ADMIN role, and all of which must still resolve the tenant's credential.
+     * The organization travels in the system scope map, which is the channel both the contextual
+     * filter and the enrichment actually consume.
+     */
+    private readCredentialRow;
+    /**
+     * Record that a credential was spent, and what the provider thought of it.
+     *
+     * Best-effort in both halves and deliberately so: an outbound provider call has already happened
+     * by the time this runs, and failing the caller because a bookkeeping write did not land would
+     * turn a successful integration into an error. Every failure is logged with the row named.
+     *
+     * The audit event is emitted for BOTH sources, including the deployment-environment fallback,
+     * because "this tenant is silently acting as the shared principal" is the condition worth seeing
+     * and it is invisible if only the interesting case is recorded.
+     */
+    recordCredentialUse(use: {
+        organizationId: string;
+        providerRef: string;
+        secretSlug: string;
+        source: ProviderCredentialResolutionSource;
+        credentialId?: string;
+        /** What the provider said. Absent means the outcome is not yet known to the caller. */
+        outcome?: {
+            accepted: boolean;
+            providerMessage?: string;
+        };
+    }): Promise<void>;
+    private emitUseAudit;
+    /**
+     * Record a grant the authorization exchange just minted, replacing one already stored.
+     *
+     * The plaintext goes in and the resource's own WRITE DOOR seals it — the same hook that seals a
+     * credential a person types, and the same reason `persistRenewedGrant` hands over plaintext:
+     * `createAsSystem` / `updateAsSystem` reach the SERVICE tier, so a pre-sealed value arrives at
+     * that hook and the envelope refuses to double-seal.
+     *
+     * ## Reconnecting REPLACES rather than adding a second row
+     *
+     * The business key is (organizationId, providerRef, secretSlug) and it is UNIQUE, so a second connect would
+     * violate the index. Read-then-write is a race, and the honest statement is that the index is what
+     * decides it: two simultaneous connects mean one of them loses, which is the correct outcome —
+     * a person who authorized twice gets one connection, not two half-connections.
+     *
+     * @returns the credential row's id, so the caller can name it in an audit event.
+     */
+    storeGrant(query: OrganizationProviderCredentialQuery, grant: ProviderOAuth2Grant, connectionParameters?: Readonly<Record<string, string>>): Promise<string>;
+    /**
+     * Store a credential somebody TYPED, as opposed to one an exchange minted.
+     *
+     * The other half of `storeGrant`, and separate from it because the two differ in every way that
+     * matters: a grant is a JSON document with an expiry and a refresh token, this is one opaque value;
+     * a grant arrives from a vendor, this arrives from a person; a grant can be renewed, this can only
+     * be replaced. Serialising a typed key through the grant envelope would put
+     * `wildo-oauth2-grant:{...}` on the wire as a bearer token.
+     *
+     * PLAINTEXT to the write door, which seals. Handing a pre-sealed value to `createAsSystem` reaches
+     * the service tier where the sealing hook refuses to double-seal — so the write would throw after
+     * the person had already typed their key.
+     *
+     * Replaces rather than duplicates: the business key is (owner, provider, slug), so re-entering a
+     * rotated key is the ordinary case and a second create would violate the index. Re-entering also
+     * RE-ENABLES and clears any validation mark, because somebody who has just supplied a working key
+     * should not be shown a broken connection.
+     */
+    storeDeclaredSecret(query: OrganizationProviderCredentialQuery, secretValue: string): Promise<string>;
+    /**
+     * Renew the grant, and RETIRE the connection when the vendor says it is finished.
+     *
+     * Without this the refresh call was unguarded, and the failure was slow and silent in the worst
+     * direction. A vendor that permanently rejects a refresh token — the person removed the app at the
+     * vendor, an administrator revoked it, the token aged past its absolute lifetime — throws, the
+     * error propagates out of the resolve, and NOTHING touches the row. `validationState` stays where
+     * it was, so the connected-accounts screen goes on showing the account as connected, every call
+     * fails identically forever, and the person is never told the one thing they could act on.
+     *
+     * Only `invalid_grant` retires a connection, and the exclusions are the substantive part. A
+     * transport failure, a bare 500 or an unparseable body means the vendor said NOTHING about the
+     * grant, and retiring a working connection because we could not reach a vendor for thirty seconds
+     * would be a self-inflicted outage. `invalid_client` is excluded for a different reason: it is the
+     * APPLICATION's own registration being rejected, one operator's misconfiguration affecting every
+     * connection at once — marking each person's account invalid would blame all of them for something
+     * none of them can fix.
+     *
+     * The mark is best-effort and the ORIGINAL error is always re-thrown: the caller needs the real
+     * cause, and a bookkeeping write that failed must not replace it with a different story.
+     */
+    private renewOrRetire;
+    /**
+     * Record that a delegated authorization was GRANTED, distinct from the row's own `_SET` event.
+     *
+     * Emitted HERE and nowhere else, because this is the only place that holds the three facts an
+     * auditor wants and the row does not: the scopes the vendor actually issued, which account they
+     * were issued for, and whether this replaced a connection that already existed. By the time the
+     * resource's own write hook sees the row, the value is sealed and none of it is recoverable.
+     *
+     * Best-effort, like every other emission on this path. The grant is already stored and the person
+     * has already authorized it; failing their connection because a trail write did not land would
+     * turn a completed authorization into an error and invite them to grant it a second time.
+     */
+    private emitConnectionGranted;
+    /**
+     * Persist a renewed grant through the resource's own WRITE door.
+     *
+     * The plaintext goes in and the CUSTOM IMPLEMENTATION seals it — the same hook that seals a
+     * credential a person types. Sealing here instead would be a second sealing site for one
+     * invariant, and it does not merely duplicate: `updateAsSystem` reaches the service tier, so a
+     * pre-sealed value arrives at that hook and the envelope REFUSES it ("double-sealing would hand
+     * the envelope itself to the provider"). Every refresh would have thrown at the write-back.
+     *
+     * `secretSetAt` therefore moves, and that is correct rather than tolerated: the field is defined
+     * as "when the stored VALUE last changed", and a renewal changes it. An earlier version of this
+     * method held it still on the theory that it should mean "when a HUMAN last supplied a value" —
+     * that is a different field, and inventing the behaviour without the field was the error.
+     *
+     * NOT best-effort. A refresh that is not persisted happens again on every call, and against a
+     * vendor that rotates the refresh token each one invalidates the last — so the connection breaks
+     * while every individual exchange succeeds.
+     */
+    private persistRenewedGrant;
+    /**
+     * Turn an envelope failure into the operator-facing statement.
+     *
+     * Exposed so the registry can distinguish "this tenant has no credential" (fall through to the
+     * environment) from "this tenant HAS one and it is broken" (refuse, loudly) without importing the
+     * envelope's error type and re-deriving the distinction. One definition, one meaning.
+     */
+    static isUnopenableCredential(error: unknown): error is ProviderCredentialEnvelopeError;
+}
+//# sourceMappingURL=organization-provider-credential-store.backend.service.d.ts.map

package/dist/esm/security/connected-accounts/services/organization-provider-credential-store.backend.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"organization-provider-credential-store.backend.service.d.ts","sourceRoot":"","sources":["../../../../../src/security/connected-accounts/services/organization-provider-credential-store.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,EAEL,kCAAkC,EAGlC,KAAK,mBAAmB,EAEzB,MAAM,uBAAuB,CAAC;AAK/B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8DAA8D,CAAC;AAClG,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,sEAAsE,CAAC;AACpH,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,iFAAiF,CAAC;AAClI,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,gFAAgF,CAAC;AAG9H,OAAO,EACL,+BAA+B,EAEhC,MAAM,qDAAqD,CAAC;AAG7D,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,mCAAmC,CAAC;AACrF,OAAO,KAAK,EACV,mCAAmC,EACnC,wCAAwC,EACxC,0CAA0C,EAC3C,MAAM,mDAAmD,CAAC;AAE3D,qBACa,iDAAkD,YAAW,0CAA0C;IAE7E,OAAO,CAAC,QAAQ,CAAC,MAAM;IACb,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IAC9B,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7E;;;;OAIG;IACsD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC;IACpF;;;;;;;OAOG;IAC6D,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC;gBAjBvC,MAAM,EAAE,aAAa,EACX,gBAAgB,EAAE,uBAAuB,EACtC,YAAY,EAAE,0BAA0B;IACzG;;;;OAIG;IACuE,SAAS,CAAC,EAAE,uBAAuB;IAC7G;;;;;;;OAOG;IAC8E,SAAS,CAAC,EAAE,2BAA2B;IAG1H;;;;OAIG;IACU,6BAA6B,CACxC,KAAK,EAAE,mCAAmC,GACzC,OAAO,CAAC,wCAAwC,GAAG,SAAS,CAAC;IA6DhE;;;;;;;;OAQG;YACW,iBAAiB;IAc/B;;;;;;;;;;OAUG;IACU,mBAAmB,CAAC,GAAG,EAAE;QACpC,cAAc,EAAE,MAAM,CAAC;QACvB,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,MAAM,CAAC;QACnB,MAAM,EAAE,kCAAkC,CAAC;QAC3C,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,uFAAuF;QACvF,OAAO,CAAC,EAAE;YAAE,QAAQ,EAAE,OAAO,CAAC;YAAC,eAAe,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;KAC3D,GAAG,OAAO,CAAC,IAAI,CAAC;YA8DH,YAAY;IA+B1B;;;;;;;;;;;;;;;;OAgBG;IACU,UAAU,CACrB,KAAK,EAAE,mCAAmC,EAC1C,KAAK,EAAE,mBAAmB,EAC1B,oBAAoB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACtD,OAAO,CAAC,MAAM,CAAC;IA2ClB;;;;;;;;;;;;;;;;;OAiBG;IACU,mBAAmB,CAAC,KAAK,EAAE,mCAAmC,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAgClH;;;;;;;;;;;;;;;;;;;;OAoBG;YACW,aAAa;IAuC3B;;;;;;;;;;;OAWG;YACW,qBAAqB;IA2BnC;;;;;;;;;;;;;;;;;OAiBG;YACW,mBAAmB;IAajC;;;;;;OAMG;WACW,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,+BAA+B;CAG/F"}

package/dist/esm/security/connected-accounts/services/organization-provider-credential-store.backend.service.js

@@ -0,0 +1,423 @@
+/**
+ * The organization-provider-credential STORE — the port implementation the registry consults.
+ *
+ * ## What makes the isolation structural rather than a filter
+ *
+ * Three independent mechanisms have to agree before a credential is handed back, and none of them
+ * is a predicate somebody has to remember to write at each call site:
+ *
+ * 1. **The scope FK is injected by the context machinery.** The read goes through `readAsSystem`
+ *    with the organization in the system scope map, so `buildContextualFilter` adds the tenant
+ *    clause itself. A caller cannot omit it, because the caller never writes it.
+ * 2. **The filter names the organization explicitly as well.** Belt and braces, deliberately: the
+ *    contextual filter is injected by a mechanism that exists TWICE (a Mongo implementation and a
+ *    PostgreSQL one), so a regression in one adapter is a bypass in that adapter alone. The explicit
+ *    clause is adapter-independent and would still scope the read.
+ * 3. **The envelope is BOUND to the row identity.** Even a read that returned another tenant's row
+ *    would fail to OPEN it — the associated data is the organization, provider and slug, so the seal
+ *    itself refuses. This is the one that holds when the other two are wrong, which is why it exists.
+ *
+ * ## The store never accepts a caller-supplied organization from a request
+ *
+ * `organizationId` arrives from the calling code's trusted execution scope. The port cannot verify
+ * it — nothing at this tier can — so the honest statement is that the guarantee holds one level up,
+ * and the envelope binding is what keeps a mistake there from becoming a cross-tenant credential
+ * disclosure rather than merely a failed read.
+ */
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { inject, injectable, optional } from 'inversify';
+import { CoreResourceType, ProviderCredentialResolutionSource, ProviderCredentialValidationState, serializeProviderOAuth2Grant, } from '@wildo-ai/saas-models';
+import { ExternalProvider_Connection_DelegationMode, ExternalProvider_Connection_OwnerScope } from '@wildo-ai/external-connectors-models';
+import { SAAS_SERVICE_TYPES } from '../../../inject/models/service-types.js';
+import { describeCaughtError } from '../../../errors/utils/error-log-level-classification.backend.utils.js';
+import { ProviderCredentialEnvelopeError, openProviderCredential, } from '../utils/provider-credential-envelope.backend.utils.js';
+import { resolveStoredCredentialValue } from '../utils/stored-credential-value.backend.utils.js';
+import { providerOAuth2GrantWasPermanentlyRejected } from './provider-oauth2-exchange.backend.js';
+let OrganizationProviderCredentialStoreBackendService = class OrganizationProviderCredentialStoreBackendService {
+    logger;
+    appConfigService;
+    systemAccess;
+    auditLogs;
+    refresher;
+    constructor(logger, appConfigService, systemAccess, auditLogs, refresher) {
+        this.logger = logger;
+        this.appConfigService = appConfigService;
+        this.systemAccess = systemAccess;
+        this.auditLogs = auditLogs;
+        this.refresher = refresher;
+    }
+    /**
+     * The organization's own credential, opened, or `undefined` when the tenant has not set one.
+     *
+     * See the port's JSDoc for why "absent" returns and "present but unopenable" throws.
+     */
+    async resolveOrganizationCredential(query) {
+        const row = await this.readCredentialRow(query);
+        if (!row) {
+            return undefined;
+        }
+        // A disabled credential is a tenant's deliberate "do not spend this" and must read as ABSENT, so
+        // the registry falls through to the deployment environment exactly as it would for a tenant that
+        // never configured one. Throwing instead would make disabling a credential break the integration
+        // rather than park it, which is the opposite of what an operator reaches for during an incident.
+        if (row.enabled === false) {
+            this.logger.debug?.('[organization-provider-credential] credential is disabled; treating as absent', { organizationId: query.organizationId, providerRef: query.providerRef, secretSlug: query.secretSlug });
+            return undefined;
+        }
+        const plaintext = openProviderCredential(row.secretValue, this.appConfigService.secrets.security.session.encryptionKey, {
+            ownerScope: ExternalProvider_Connection_OwnerScope.ORGANIZATION,
+            ownerId: query.organizationId,
+            providerRef: query.providerRef,
+            secretSlug: query.secretSlug,
+        });
+        // What is STORED is not always what goes on the wire: an OAuth2 grant is a JSON document whose
+        // access token is one field. Returning the plaintext directly would put that document on the
+        // wire as a bearer token, and the vendor's 401 would name a credential problem rather than a
+        // serialization one. One shared resolver, because both stores hold both shapes.
+        const describeRow = `organization '${query.organizationId}', provider '${query.providerRef}', slug '${query.secretSlug}'`;
+        const resolved = resolveStoredCredentialValue(plaintext, describeRow, this.refresher !== undefined);
+        if (resolved.needsRefresh) {
+            // The renewal round trip and the write-back, in that order. The exchange belongs to the
+            // refresher (it needs the contract and the application's registration); persisting belongs
+            // here (it needs the table, the envelope key and the scope map). Neither half is where the
+            // other's inputs are, which is why this is two components rather than one.
+            const renewed = await this.renewOrRetire(row._id, query, {
+                providerRef: query.providerRef,
+                secretSlug: query.secretSlug,
+                target: {
+                    ownerScope: ExternalProvider_Connection_OwnerScope.ORGANIZATION,
+                    ownerId: query.organizationId,
+                    delegation: ExternalProvider_Connection_DelegationMode.SERVICE,
+                },
+                grant: resolved.grant,
+                // From the ROW. The authorization record that first held these expired ten minutes after
+                // the connect; a templated token URL is still templated an hour later, so without this a
+                // Microsoft or regional connection renews into `needs a value for 'cloud'`.
+                connectionParameters: row.connectionParameters,
+            });
+            await this.persistRenewedGrant(query, row._id, renewed);
+            return { value: renewed.accessToken, credentialId: row._id };
+        }
+        return { value: resolved.wireValue, credentialId: row._id };
+    }
+    /**
+     * The row, read through the system door.
+     *
+     * `readAsSystem` bypasses the CALLER's role check, not the tenant boundary — an outbound provider
+     * call legitimately happens on a batch, a queue consumer or an anonymous webhook return leg, none
+     * of which holds an ORG_ADMIN role, and all of which must still resolve the tenant's credential.
+     * The organization travels in the system scope map, which is the channel both the contextual
+     * filter and the enrichment actually consume.
+     */
+    async readCredentialRow(query) {
+        return this.systemAccess.readAsSystem(CoreResourceType.ORG_PROVIDER_CREDENTIALS, {
+            organizationId: query.organizationId,
+            providerRef: query.providerRef,
+            secretSlug: query.secretSlug,
+        }, { scopeContext: { organizationId: query.organizationId } });
+    }
+    /**
+     * Record that a credential was spent, and what the provider thought of it.
+     *
+     * Best-effort in both halves and deliberately so: an outbound provider call has already happened
+     * by the time this runs, and failing the caller because a bookkeeping write did not land would
+     * turn a successful integration into an error. Every failure is logged with the row named.
+     *
+     * The audit event is emitted for BOTH sources, including the deployment-environment fallback,
+     * because "this tenant is silently acting as the shared principal" is the condition worth seeing
+     * and it is invisible if only the interesting case is recorded.
+     */
+    async recordCredentialUse(use) {
+        await this.emitUseAudit(use);
+        // Only a tenant's OWN credential has a row to stamp. A deployment-environment resolution has
+        // nothing to write to, and inventing a row for it would create a credential the tenant never set.
+        if (use.source !== ProviderCredentialResolutionSource.ORGANIZATION_CREDENTIAL || !use.credentialId) {
+            return;
+        }
+        const now = new Date();
+        const patch = { lastUsedAt: now };
+        if (use.outcome) {
+            patch.validationState = use.outcome.accepted
+                ? ProviderCredentialValidationState.VALID
+                : ProviderCredentialValidationState.INVALID;
+            patch.lastValidatedAt = now;
+            // Truncated to the schema's own bound. The provider's message describes the CREDENTIAL's
+            // status and must never be derived from the credential itself — a caller passing the secret
+            // here would publish it to a client-readable field, which is why this is documented at the
+            // one place a provider string enters the row.
+            patch.validationError = use.outcome.accepted
+                ? undefined
+                : (use.outcome.providerMessage ?? '').slice(0, 500) || undefined;
+        }
+        try {
+            await this.systemAccess.updateAsSystem(CoreResourceType.ORG_PROVIDER_CREDENTIALS, use.credentialId, patch, {
+                scopeContext: { organizationId: use.organizationId },
+                /*
+                 * `lastUsedAt`, `lastValidatedAt` and `validationError` are all
+                 * `.excludeFromCreate().excludeFromUpdate()`, so the repository's strict `requestDto.parse`
+                 * drops them before persistence unless they are allow-listed here.
+                 *
+                 * The automatic diff that populates this list covers fields a custom-impl PREFIX hook
+                 * injected — which is how `secretSetAt` reaches the row on a write. Nothing populates it
+                 * for a payload a caller passes directly, which is what this is, so the omission was
+                 * silent in the worst way: `validationState` is NOT excluded and moved correctly, so the
+                 * row went INVALID while the timestamp and the provider's explanation of WHY vanished.
+                 * A person looking at a credential marked invalid with no reason and no last-use time is
+                 * being told less than the code believes it recorded.
+                 */
+                preserveServerInjectedFields: ['lastUsedAt', 'lastValidatedAt', 'validationError'],
+            });
+        }
+        catch (error) {
+            this.logger.warn?.('[organization-provider-credential] failed to record credential use', {
+                organizationId: use.organizationId,
+                providerRef: use.providerRef,
+                secretSlug: use.secretSlug,
+                credentialId: use.credentialId,
+                error: describeCaughtError(error),
+            });
+        }
+    }
+    async emitUseAudit(use) {
+        if (!this.auditLogs) {
+            return;
+        }
+        try {
+            await this.auditLogs.logOrganizationProviderCredentialUsed({
+                organizationId: use.organizationId,
+                providerRef: use.providerRef,
+                secretSlug: use.secretSlug,
+                resolvedFrom: use.source,
+                credentialId: use.credentialId,
+            });
+        }
+        catch (error) {
+            this.logger.warn?.('[organization-provider-credential] failed to emit credential-use audit event', {
+                organizationId: use.organizationId,
+                providerRef: use.providerRef,
+                error: describeCaughtError(error),
+            });
+        }
+    }
+    /**
+     * Record a grant the authorization exchange just minted, replacing one already stored.
+     *
+     * The plaintext goes in and the resource's own WRITE DOOR seals it — the same hook that seals a
+     * credential a person types, and the same reason `persistRenewedGrant` hands over plaintext:
+     * `createAsSystem` / `updateAsSystem` reach the SERVICE tier, so a pre-sealed value arrives at
+     * that hook and the envelope refuses to double-seal.
+     *
+     * ## Reconnecting REPLACES rather than adding a second row
+     *
+     * The business key is (organizationId, providerRef, secretSlug) and it is UNIQUE, so a second connect would
+     * violate the index. Read-then-write is a race, and the honest statement is that the index is what
+     * decides it: two simultaneous connects mean one of them loses, which is the correct outcome —
+     * a person who authorized twice gets one connection, not two half-connections.
+     *
+     * @returns the credential row's id, so the caller can name it in an audit event.
+     */
+    async storeGrant(query, grant, connectionParameters) {
+        const existing = await this.readCredentialRow(query);
+        const secretValue = serializeProviderOAuth2Grant(grant);
+        const scopeContext = { organizationId: query.organizationId };
+        if (existing) {
+            // `connectionParameters` is `.excludeFromUpdate()` — it describes the ACCOUNT the grant is
+            // for, and re-authorizing against a different directory is a different connection. A
+            // reconnect that changed them would point the refresh somewhere the token was not issued.
+            await this.systemAccess.updateAsSystem(CoreResourceType.ORG_PROVIDER_CREDENTIALS, existing._id, {
+                secretValue,
+                enabled: true,
+                // Clearing the mark is part of reconnecting, not a separate concern. A row retired by
+                // `renewOrRetire` would otherwise keep `validationState: INVALID` forever — so somebody
+                // who did exactly what the screen told them to do would reconnect successfully and still
+                // be shown a broken connection.
+                validationState: ProviderCredentialValidationState.UNVALIDATED,
+                validationError: undefined,
+            }, { scopeContext, preserveServerInjectedFields: ['validationError'] });
+            await this.emitConnectionGranted(query, grant, existing._id, true);
+            return existing._id;
+        }
+        const created = await this.systemAccess.createAsSystem(CoreResourceType.ORG_PROVIDER_CREDENTIALS, {
+            organizationId: query.organizationId,
+            providerRef: query.providerRef,
+            secretSlug: query.secretSlug,
+            secretValue,
+            ...(connectionParameters === undefined ? {} : { connectionParameters }),
+        }, { scopeContext });
+        await this.emitConnectionGranted(query, grant, created._id, false);
+        return created._id;
+    }
+    /**
+     * Store a credential somebody TYPED, as opposed to one an exchange minted.
+     *
+     * The other half of `storeGrant`, and separate from it because the two differ in every way that
+     * matters: a grant is a JSON document with an expiry and a refresh token, this is one opaque value;
+     * a grant arrives from a vendor, this arrives from a person; a grant can be renewed, this can only
+     * be replaced. Serialising a typed key through the grant envelope would put
+     * `wildo-oauth2-grant:{...}` on the wire as a bearer token.
+     *
+     * PLAINTEXT to the write door, which seals. Handing a pre-sealed value to `createAsSystem` reaches
+     * the service tier where the sealing hook refuses to double-seal — so the write would throw after
+     * the person had already typed their key.
+     *
+     * Replaces rather than duplicates: the business key is (owner, provider, slug), so re-entering a
+     * rotated key is the ordinary case and a second create would violate the index. Re-entering also
+     * RE-ENABLES and clears any validation mark, because somebody who has just supplied a working key
+     * should not be shown a broken connection.
+     */
+    async storeDeclaredSecret(query, secretValue) {
+        const existing = await this.readCredentialRow(query);
+        const scopeContext = { organizationId: query.organizationId };
+        if (existing) {
+            await this.systemAccess.updateAsSystem(CoreResourceType.ORG_PROVIDER_CREDENTIALS, existing._id, {
+                secretValue,
+                enabled: true,
+                validationState: ProviderCredentialValidationState.UNVALIDATED,
+                validationError: undefined,
+            }, { scopeContext, preserveServerInjectedFields: ['validationError'] });
+            return existing._id;
+        }
+        const created = await this.systemAccess.createAsSystem(CoreResourceType.ORG_PROVIDER_CREDENTIALS, {
+            organizationId: query.organizationId,
+            providerRef: query.providerRef,
+            secretSlug: query.secretSlug,
+            secretValue,
+        }, { scopeContext });
+        return created._id;
+    }
+    /**
+     * Renew the grant, and RETIRE the connection when the vendor says it is finished.
+     *
+     * Without this the refresh call was unguarded, and the failure was slow and silent in the worst
+     * direction. A vendor that permanently rejects a refresh token — the person removed the app at the
+     * vendor, an administrator revoked it, the token aged past its absolute lifetime — throws, the
+     * error propagates out of the resolve, and NOTHING touches the row. `validationState` stays where
+     * it was, so the connected-accounts screen goes on showing the account as connected, every call
+     * fails identically forever, and the person is never told the one thing they could act on.
+     *
+     * Only `invalid_grant` retires a connection, and the exclusions are the substantive part. A
+     * transport failure, a bare 500 or an unparseable body means the vendor said NOTHING about the
+     * grant, and retiring a working connection because we could not reach a vendor for thirty seconds
+     * would be a self-inflicted outage. `invalid_client` is excluded for a different reason: it is the
+     * APPLICATION's own registration being rejected, one operator's misconfiguration affecting every
+     * connection at once — marking each person's account invalid would blame all of them for something
+     * none of them can fix.
+     *
+     * The mark is best-effort and the ORIGINAL error is always re-thrown: the caller needs the real
+     * cause, and a bookkeeping write that failed must not replace it with a different story.
+     */
+    async renewOrRetire(credentialId, query, request) {
+        try {
+            return await this.refresher.refreshGrant(request);
+        }
+        catch (error) {
+            if (providerOAuth2GrantWasPermanentlyRejected(error)) {
+                try {
+                    await this.systemAccess.updateAsSystem(CoreResourceType.ORG_PROVIDER_CREDENTIALS, credentialId, {
+                        validationState: ProviderCredentialValidationState.INVALID,
+                        lastValidatedAt: new Date(),
+                        // The vendor's own code, and nothing derived from the credential. This field is
+                        // CLIENT-READABLE, so anything token-shaped reaching it would publish a secret onto
+                        // the screen that displays it.
+                        validationError: 'The provider rejected the stored authorization (invalid_grant). Reconnect the account.',
+                    }, {
+                        scopeContext: { organizationId: query.organizationId },
+                        // Both of these are `.excludeFromUpdate()`; without the allow-list the row would go
+                        // INVALID carrying no reason and no timestamp — see `recordCredentialUse`.
+                        preserveServerInjectedFields: ['lastValidatedAt', 'validationError'],
+                    });
+                }
+                catch (markError) {
+                    this.logger.warn?.('[organization-provider-credential] a grant was permanently rejected and the row could not be marked', { providerRef: query.providerRef, secretSlug: query.secretSlug, credentialId, error: describeCaughtError(markError) });
+                }
+            }
+            throw error;
+        }
+    }
+    /**
+     * Record that a delegated authorization was GRANTED, distinct from the row's own `_SET` event.
+     *
+     * Emitted HERE and nowhere else, because this is the only place that holds the three facts an
+     * auditor wants and the row does not: the scopes the vendor actually issued, which account they
+     * were issued for, and whether this replaced a connection that already existed. By the time the
+     * resource's own write hook sees the row, the value is sealed and none of it is recoverable.
+     *
+     * Best-effort, like every other emission on this path. The grant is already stored and the person
+     * has already authorized it; failing their connection because a trail write did not land would
+     * turn a completed authorization into an error and invite them to grant it a second time.
+     */
+    async emitConnectionGranted(query, grant, credentialId, replacedExistingConnection) {
+        if (!this.auditLogs) {
+            return;
+        }
+        try {
+            await this.auditLogs.logOrganizationProviderConnectionGranted({
+                organizationId: query.organizationId,
+                providerRef: query.providerRef,
+                secretSlug: query.secretSlug,
+                credentialId,
+                grantedScopes: grant.grantedScopes,
+                accountRef: grant.accountRef,
+                replacedExistingConnection,
+            });
+        }
+        catch (error) {
+            this.logger.warn?.('[organization-provider-credential] a connection was granted and the audit event could not be emitted', { providerRef: query.providerRef, secretSlug: query.secretSlug, credentialId, error: describeCaughtError(error) });
+        }
+    }
+    /**
+     * Persist a renewed grant through the resource's own WRITE door.
+     *
+     * The plaintext goes in and the CUSTOM IMPLEMENTATION seals it — the same hook that seals a
+     * credential a person types. Sealing here instead would be a second sealing site for one
+     * invariant, and it does not merely duplicate: `updateAsSystem` reaches the service tier, so a
+     * pre-sealed value arrives at that hook and the envelope REFUSES it ("double-sealing would hand
+     * the envelope itself to the provider"). Every refresh would have thrown at the write-back.
+     *
+     * `secretSetAt` therefore moves, and that is correct rather than tolerated: the field is defined
+     * as "when the stored VALUE last changed", and a renewal changes it. An earlier version of this
+     * method held it still on the theory that it should mean "when a HUMAN last supplied a value" —
+     * that is a different field, and inventing the behaviour without the field was the error.
+     *
+     * NOT best-effort. A refresh that is not persisted happens again on every call, and against a
+     * vendor that rotates the refresh token each one invalidates the last — so the connection breaks
+     * while every individual exchange succeeds.
+     */
+    async persistRenewedGrant(query, credentialId, renewed) {
+        await this.systemAccess.updateAsSystem(CoreResourceType.ORG_PROVIDER_CREDENTIALS, credentialId, { secretValue: serializeProviderOAuth2Grant(renewed) }, { scopeContext: { organizationId: query.organizationId } });
+    }
+    /**
+     * Turn an envelope failure into the operator-facing statement.
+     *
+     * Exposed so the registry can distinguish "this tenant has no credential" (fall through to the
+     * environment) from "this tenant HAS one and it is broken" (refuse, loudly) without importing the
+     * envelope's error type and re-deriving the distinction. One definition, one meaning.
+     */
+    static isUnopenableCredential(error) {
+        return error instanceof ProviderCredentialEnvelopeError;
+    }
+};
+OrganizationProviderCredentialStoreBackendService = __decorate([
+    injectable(),
+    __param(0, inject(SAAS_SERVICE_TYPES.Logger)),
+    __param(1, inject(SAAS_SERVICE_TYPES.AppConfigService)),
+    __param(2, inject(SAAS_SERVICE_TYPES.SystemAccessService)),
+    __param(3, inject(SAAS_SERVICE_TYPES.AuditLogsService)),
+    __param(3, optional()),
+    __param(4, inject(SAAS_SERVICE_TYPES.ProviderOAuth2Refresher)),
+    __param(4, optional()),
+    __metadata("design:paramtypes", [Function, Function, Function, Function, Object])
+], OrganizationProviderCredentialStoreBackendService);
+export { OrganizationProviderCredentialStoreBackendService };
+//# sourceMappingURL=organization-provider-credential-store.backend.service.js.map