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

package/dist/esm/security/connected-accounts/services/provider-oauth2-refresher.backend.service.js

@@ -0,0 +1,153 @@
+/**
+ * The token refresher — the port implementation over the provider registry.
+ *
+ * It reads the provider's OAuth2 contract and the application's client registration, performs the
+ * refresh exchange, and hands the renewed grant back. It persists nothing: the store that asked owns
+ * the table.
+ *
+ * ## Single-flight, and why it is not an optimisation
+ *
+ * Concurrent calls for the SAME connection collapse onto one exchange. Skipping this would be a
+ * correctness defect, not a performance one, for vendors that ROTATE the refresh token: two
+ * simultaneous refreshes both present the same refresh token, the vendor issues two grants and
+ * invalidates the first, and whichever write lands second stores a token the vendor has already
+ * revoked. The connection then fails on its next call, with two successful-looking refreshes in the
+ * log and nothing saying which one broke it.
+ *
+ * ## What it does NOT cover, stated rather than implied
+ *
+ * The flight is IN-PROCESS. Two backend instances refreshing the same connection at the same instant
+ * still race, and against a rotating vendor one of them still loses. Closing that needs a
+ * distributed lock, which is a Redis round trip on a path that runs before every outbound call — a
+ * cost worth paying only once a real deployment shows the collision. The narrower in-process case is
+ * the common one by a wide margin, because a burst of calls for one connection almost always arrives
+ * at one instance.
+ *
+ * assurance-control: WILDO.IDENTITY.DELEGATED_AUTHORIZATION — delegated authority is renewed without
+ * a new act of consent, so the renewal is bounded by what the original grant carried.
+ */
+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 } from 'inversify';
+import { ExternalProvider_ExchangeProtocol_Kind, ProviderProtocolRuntimeKind } 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 { ProviderOAuth2ExchangeError, refreshProviderOAuth2Grant, } from './provider-oauth2-exchange.backend.js';
+let ProviderOAuth2RefresherBackendService = class ProviderOAuth2RefresherBackendService {
+    logger;
+    externalProvidersRegistry;
+    /**
+     * One in-flight exchange per connection, keyed by the whole identity.
+     *
+     * Entries are removed in a `finally`, so a failed refresh does not wedge the connection — the next
+     * call starts a fresh attempt rather than awaiting a promise that already rejected.
+     */
+    inFlight = new Map();
+    constructor(logger, externalProvidersRegistry) {
+        this.logger = logger;
+        this.externalProvidersRegistry = externalProvidersRegistry;
+    }
+    async refreshGrant(request) {
+        const key = this.flightKeyFor(request);
+        const existing = this.inFlight.get(key);
+        if (existing !== undefined) {
+            this.logger.debug?.('[oauth2-refresh] joining an in-flight refresh', {
+                providerRef: request.providerRef,
+                ownerScope: request.target.ownerScope,
+            });
+            return existing;
+        }
+        const flight = this.performRefresh(request).finally(() => {
+            this.inFlight.delete(key);
+        });
+        this.inFlight.set(key, flight);
+        return flight;
+    }
+    async performRefresh(request) {
+        const contract = this.externalProvidersRegistry.getProviderRuntimeContract(request.providerRef, ExternalProvider_ExchangeProtocol_Kind.REST_API);
+        if (contract?.kind !== ProviderProtocolRuntimeKind.REST || contract.oauth2 === undefined) {
+            throw new ProviderOAuth2ExchangeError(`Provider '${request.providerRef}' holds an OAuth2 grant but declares no OAuth2 contract, so there `
+                + 'is no token endpoint to refresh against. The stored grant was written against a different '
+                + 'provider definition than the one loaded now.');
+        }
+        // The application's registration with the vendor — the two values an operator genuinely pastes.
+        // They identify the INTEGRATION, never the end user, so they come from the deployment environment
+        // for every owner scope and are not per-connection.
+        const { clientIdSecretRef, clientSecretSecretRef } = contract.oauth2;
+        const clientId = clientIdSecretRef === undefined
+            ? undefined
+            : this.externalProvidersRegistry.getProviderSecret(request.providerRef, ExternalProvider_ExchangeProtocol_Kind.REST_API, clientIdSecretRef);
+        const clientSecret = clientSecretSecretRef === undefined
+            ? undefined
+            : this.externalProvidersRegistry.getProviderSecret(request.providerRef, ExternalProvider_ExchangeProtocol_Kind.REST_API, clientSecretSecretRef);
+        if (!clientId || !clientSecret) {
+            // Names the ENVIRONMENT, not the connection. A person whose token cannot be renewed because an
+            // operator has not configured the application's registration must not be told to reconnect —
+            // reconnecting would fail at the same step, for the same reason, having sent them to a vendor.
+            throw new ProviderOAuth2ExchangeError(`Provider '${request.providerRef}' cannot refresh a grant: the application's own OAuth2 registration `
+                + `is not configured. Set '${clientIdSecretRef ?? '(no client id declared)'}' and `
+                + `'${clientSecretSecretRef ?? '(no client secret declared)'}' in the deployment environment. `
+                + 'This is an application configuration gap, not a problem with the stored connection.');
+        }
+        try {
+            const renewed = await refreshProviderOAuth2Grant({
+                oauth2: contract.oauth2,
+                providerRef: request.providerRef,
+                clientId,
+                clientSecret,
+                connectionParameters: request.connectionParameters,
+                grant: request.grant,
+            });
+            this.logger.debug?.('[oauth2-refresh] grant renewed', {
+                providerRef: request.providerRef,
+                ownerScope: request.target.ownerScope,
+                // Whether the vendor rotated the refresh token — the fact that decides whether this
+                // connection survives its next renewal, and it is invisible anywhere else.
+                refreshTokenRotated: renewed.refreshToken !== request.grant.refreshToken,
+            });
+            return renewed;
+        }
+        catch (error) {
+            this.logger.warn?.('[oauth2-refresh] refresh failed', {
+                providerRef: request.providerRef,
+                ownerScope: request.target.ownerScope,
+                secretSlug: request.secretSlug,
+                error: describeCaughtError(error),
+            });
+            throw error;
+        }
+    }
+    /**
+     * The whole connection identity, so two owners of the same provider never share a flight.
+     *
+     * Keying on the provider alone would make one tenant's refresh satisfy another's call and return
+     * the wrong account's token — the exact cross-owner substitution the resolution path refuses.
+     */
+    flightKeyFor(request) {
+        return [
+            request.target.ownerScope,
+            request.target.ownerId ?? '-',
+            request.target.delegation,
+            request.providerRef,
+            request.secretSlug,
+        ].join('');
+    }
+};
+ProviderOAuth2RefresherBackendService = __decorate([
+    injectable(),
+    __param(0, inject(SAAS_SERVICE_TYPES.Logger)),
+    __param(1, inject(SAAS_SERVICE_TYPES.ExternalProvidersRegistryService)),
+    __metadata("design:paramtypes", [Function, Function])
+], ProviderOAuth2RefresherBackendService);
+export { ProviderOAuth2RefresherBackendService };
+//# sourceMappingURL=provider-oauth2-refresher.backend.service.js.map

package/dist/esm/security/connected-accounts/services/provider-oauth2-refresher.backend.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider-oauth2-refresher.backend.service.js","sourceRoot":"","sources":["../../../../../../src/security/connected-accounts/services/provider-oauth2-refresher.backend.service.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The token refresher — the port implementation over the provider registry.\n *\n * It reads the provider's OAuth2 contract and the application's client registration, performs the\n * refresh exchange, and hands the renewed grant back. It persists nothing: the store that asked owns\n * the table.\n *\n * ## Single-flight, and why it is not an optimisation\n *\n * Concurrent calls for the SAME connection collapse onto one exchange. Skipping this would be a\n * correctness defect, not a performance one, for vendors that ROTATE the refresh token: two\n * simultaneous refreshes both present the same refresh token, the vendor issues two grants and\n * invalidates the first, and whichever write lands second stores a token the vendor has already\n * revoked. The connection then fails on its next call, with two successful-looking refreshes in the\n * log and nothing saying which one broke it.\n *\n * ## What it does NOT cover, stated rather than implied\n *\n * The flight is IN-PROCESS. Two backend instances refreshing the same connection at the same instant\n * still race, and against a rotating vendor one of them still loses. Closing that needs a\n * distributed lock, which is a Redis round trip on a path that runs before every outbound call — a\n * cost worth paying only once a real deployment shows the collision. The narrower in-process case is\n * the common one by a wide margin, because a burst of calls for one connection almost always arrives\n * at one instance.\n *\n * assurance-control: WILDO.IDENTITY.DELEGATED_AUTHORIZATION — delegated authority is renewed without\n * a new act of consent, so the renewal is bounded by what the original grant carried.\n */\n\nimport { inject, injectable } from 'inversify';\nimport { ExternalProvider_ExchangeProtocol_Kind, ProviderProtocolRuntimeKind } from '@wildo-ai/external-connectors-models';\nimport type { ProviderOAuth2Grant } from '@wildo-ai/saas-models';\n\nimport { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';\nimport type { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';\nimport type { ExternalProvidersRegistryBackendService } from '~wildo-backend-lib/external-providers/services/external-providers-registry.backend.service';\nimport { describeCaughtError } from '~wildo-backend-lib/errors/utils/error-log-level-classification.backend.utils';\n\nimport {\n  ProviderOAuth2ExchangeError,\n  refreshProviderOAuth2Grant,\n} from './provider-oauth2-exchange.backend';\nimport type {\n  ProviderOAuth2RefreshRequest,\n  ProviderOAuth2RefresherPort,\n} from '../provider-oauth2-refresher.port';\n\n@injectable()\nexport class ProviderOAuth2RefresherBackendService implements ProviderOAuth2RefresherPort {\n  /**\n   * One in-flight exchange per connection, keyed by the whole identity.\n   *\n   * Entries are removed in a `finally`, so a failed refresh does not wedge the connection — the next\n   * call starts a fresh attempt rather than awaiting a promise that already rejected.\n   */\n  private readonly inFlight = new Map<string, Promise<ProviderOAuth2Grant>>();\n\n  constructor(\n    @inject(SAAS_SERVICE_TYPES.Logger) private readonly logger: LoggerService,\n    @inject(SAAS_SERVICE_TYPES.ExternalProvidersRegistryService)\n    private readonly externalProvidersRegistry: ExternalProvidersRegistryBackendService,\n  ) {}\n\n  public async refreshGrant(request: ProviderOAuth2RefreshRequest): Promise<ProviderOAuth2Grant> {\n    const key = this.flightKeyFor(request);\n    const existing = this.inFlight.get(key);\n    if (existing !== undefined) {\n      this.logger.debug?.('[oauth2-refresh] joining an in-flight refresh', {\n        providerRef: request.providerRef,\n        ownerScope: request.target.ownerScope,\n      });\n      return existing;\n    }\n\n    const flight = this.performRefresh(request).finally(() => {\n      this.inFlight.delete(key);\n    });\n    this.inFlight.set(key, flight);\n    return flight;\n  }\n\n  private async performRefresh(request: ProviderOAuth2RefreshRequest): Promise<ProviderOAuth2Grant> {\n    const contract = this.externalProvidersRegistry.getProviderRuntimeContract(\n      request.providerRef,\n      ExternalProvider_ExchangeProtocol_Kind.REST_API,\n    );\n    if (contract?.kind !== ProviderProtocolRuntimeKind.REST || contract.oauth2 === undefined) {\n      throw new ProviderOAuth2ExchangeError(\n        `Provider '${request.providerRef}' holds an OAuth2 grant but declares no OAuth2 contract, so there `\n        + 'is no token endpoint to refresh against. The stored grant was written against a different '\n        + 'provider definition than the one loaded now.',\n      );\n    }\n\n    // The application's registration with the vendor — the two values an operator genuinely pastes.\n    // They identify the INTEGRATION, never the end user, so they come from the deployment environment\n    // for every owner scope and are not per-connection.\n    const { clientIdSecretRef, clientSecretSecretRef } = contract.oauth2;\n    const clientId = clientIdSecretRef === undefined\n      ? undefined\n      : this.externalProvidersRegistry.getProviderSecret(\n        request.providerRef, ExternalProvider_ExchangeProtocol_Kind.REST_API, clientIdSecretRef,\n      );\n    const clientSecret = clientSecretSecretRef === undefined\n      ? undefined\n      : this.externalProvidersRegistry.getProviderSecret(\n        request.providerRef, ExternalProvider_ExchangeProtocol_Kind.REST_API, clientSecretSecretRef,\n      );\n\n    if (!clientId || !clientSecret) {\n      // Names the ENVIRONMENT, not the connection. A person whose token cannot be renewed because an\n      // operator has not configured the application's registration must not be told to reconnect —\n      // reconnecting would fail at the same step, for the same reason, having sent them to a vendor.\n      throw new ProviderOAuth2ExchangeError(\n        `Provider '${request.providerRef}' cannot refresh a grant: the application's own OAuth2 registration `\n        + `is not configured. Set '${clientIdSecretRef ?? '(no client id declared)'}' and `\n        + `'${clientSecretSecretRef ?? '(no client secret declared)'}' in the deployment environment. `\n        + 'This is an application configuration gap, not a problem with the stored connection.',\n      );\n    }\n\n    try {\n      const renewed = await refreshProviderOAuth2Grant({\n        oauth2: contract.oauth2,\n        providerRef: request.providerRef,\n        clientId,\n        clientSecret,\n        connectionParameters: request.connectionParameters,\n        grant: request.grant,\n      });\n      this.logger.debug?.('[oauth2-refresh] grant renewed', {\n        providerRef: request.providerRef,\n        ownerScope: request.target.ownerScope,\n        // Whether the vendor rotated the refresh token — the fact that decides whether this\n        // connection survives its next renewal, and it is invisible anywhere else.\n        refreshTokenRotated: renewed.refreshToken !== request.grant.refreshToken,\n      });\n      return renewed;\n    } catch (error) {\n      this.logger.warn?.('[oauth2-refresh] refresh failed', {\n        providerRef: request.providerRef,\n        ownerScope: request.target.ownerScope,\n        secretSlug: request.secretSlug,\n        error: describeCaughtError(error),\n      });\n      throw error;\n    }\n  }\n\n  /**\n   * The whole connection identity, so two owners of the same provider never share a flight.\n   *\n   * Keying on the provider alone would make one tenant's refresh satisfy another's call and return\n   * the wrong account's token — the exact cross-owner substitution the resolution path refuses.\n   */\n  private flightKeyFor(request: ProviderOAuth2RefreshRequest): string {\n    return [\n      request.target.ownerScope,\n      request.target.ownerId ?? '-',\n      request.target.delegation,\n      request.providerRef,\n      request.secretSlug,\n    ].join('\u0000');\n  }\n}\n"]}

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

@@ -0,0 +1,195 @@
+/**
+ * The user-provider-credential STORE — the port implementation the registry consults for a PERSON's
+ * own credential.
+ *
+ * ## What makes the isolation structural rather than a filter
+ *
+ * The same three independent mechanisms as the organization store, and none of them is a predicate
+ * somebody has to remember to write at each call site:
+ *
+ * 1. **The owner FK is injected by the context machinery.** The read goes through `readAsSystem`
+ *    with the user in the system scope map, so `buildContextualFilter` adds the clause itself. A
+ *    caller cannot omit it, because the caller never writes it.
+ * 2. **The filter names the user 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, under a key derived for the USER scope.** Even a
+ *    read that returned another person's row — or a tenant's — would fail to OPEN it. This is the
+ *    one that holds when the other two are wrong, which is why it exists.
+ *
+ * ## Why this is a separate service rather than the organization store with an owner parameter
+ *
+ * The read is the same shape and everything around it differs. There is no fallback (a person who
+ * has connected nothing gets a refusal, never the deployment's shared principal). There is no
+ * administrative variant, so the actor and the subject are always the same identity and the audit
+ * events say so. And the resource is a composition under `USERS` rather than under `ORGANIZATIONS`,
+ * so the scope map, the cascade and the erasure semantics are a different set throughout.
+ *
+ * A single service parameterised by owner would carry every one of those as a branch, and the
+ * branch a reader most needs to trust — "is a fallback reachable from here?" — would be the one
+ * spelled as an `if`.
+ *
+ * assurance-control: WILDO.IDENTITY.DELEGATED_AUTHORIZATION — a user's delegated authority toward a
+ * third party is read only for that user.
+ */
+import { 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 { UserProviderCredentialQuery, UserProviderCredentialResolution, UserProviderCredentialResolverPort } from '../user-provider-credential-resolver.port';
+export declare class UserProviderCredentialStoreBackendService implements UserProviderCredentialResolverPort {
+    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 person's own credential, opened, or `undefined` when they have not connected this provider.
+     *
+     * See the port's JSDoc for why "absent" returns and "present but unopenable" throws.
+     */
+    resolveUserCredential(query: UserProviderCredentialQuery): Promise<UserProviderCredentialResolution | undefined>;
+    /**
+     * The scoped read.
+     *
+     * `readAsSystem` rather than an ordinary repository read, for the reason the organization sibling
+     * documents: a provider call legitimately happens on a batch, a queue consumer or a webhook return
+     * leg, none of which carries the person's own session, and all of which must still resolve their
+     * credential. The user travels in the system scope map, which is the channel the contextual filter
+     * actually consumes.
+     */
+    private readCredentialRow;
+    /**
+     * Record that a credential was spent, and what the provider thought of it.
+     *
+     * Best-effort in both halves and deliberately so: the 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.
+     */
+    recordCredentialUse(use: {
+        userId: string;
+        providerRef: string;
+        secretSlug: string;
+        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 (userId, 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: UserProviderCredentialQuery, grant: ProviderOAuth2Grant, connectionParameters?: Readonly<Record<string, 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 person has no credential" from "they HAVE one and
+     * it is broken" without importing the envelope's error type and re-deriving the distinction. One
+     * definition, one meaning.
+     */
+    static isUnopenableCredential(error: unknown): error is ProviderCredentialEnvelopeError;
+}
+//# sourceMappingURL=user-provider-credential-store.backend.service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"user-provider-credential-store.backend.service.d.ts","sourceRoot":"","sources":["../../../../../../src/security/connected-accounts/services/user-provider-credential-store.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAGH,OAAO,EAKL,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,2BAA2B,EAC3B,gCAAgC,EAChC,kCAAkC,EACnC,MAAM,2CAA2C,CAAC;AAEnD,qBACa,yCAA0C,YAAW,kCAAkC;IAE7D,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,qBAAqB,CAChC,KAAK,EAAE,2BAA2B,GACjC,OAAO,CAAC,gCAAgC,GAAG,SAAS,CAAC;IA6DxD;;;;;;;;OAQG;YACW,iBAAiB;IAc/B;;;;;;OAMG;IACU,mBAAmB,CAAC,GAAG,EAAE;QACpC,MAAM,EAAE,MAAM,CAAC;QACf,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;QACrB,uFAAuF;QACvF,OAAO,CAAC,EAAE;YAAE,QAAQ,EAAE,OAAO,CAAC;YAAC,eAAe,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;KAC3D,GAAG,OAAO,CAAC,IAAI,CAAC;YAwDH,YAAY;IAgC1B;;;;;;;;;;;;;;;;OAgBG;IACU,UAAU,CACrB,KAAK,EAAE,2BAA2B,EAClC,KAAK,EAAE,mBAAmB,EAC1B,oBAAoB,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GACtD,OAAO,CAAC,MAAM,CAAC;IA2ClB;;;;;;;;;;;;;;;;;;;;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"}