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

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

@@ -0,0 +1,123 @@
+/**
+ * The record of ONE in-flight authorization attempt, from the redirect out to the callback back.
+ *
+ * ## Why this is ephemeral state and not a resource
+ *
+ * It exists for the seconds a person spends on a vendor's consent screen and is worthless
+ * afterwards. Deleting the whole store costs those people one retry and nothing else — the test
+ * `one-source-of-truth.md` applies: losing it costs TIME, never TRUTH, so it is a cache and must not
+ * become a table. A resource would also mean three migrations, a retention policy and an erasure
+ * question, for data whose correct lifetime is ten minutes.
+ *
+ * ## Single-use BY CONSTRUCTION, not by a flag
+ *
+ * Consumption is `GETDEL` — one round trip that returns the record and removes it atomically. So a
+ * replayed callback finds nothing, and there is no window in which two concurrent callbacks both
+ * read a record and both proceed. A `consumed: true` flag would have that window, and the attack it
+ * opens is real: an authorization code delivered twice is how a stolen code gets grafted onto a
+ * legitimate attempt.
+ *
+ * ## What it holds, and what it must never hold
+ *
+ * It holds the PKCE verifier, which is a secret for the length of the flow, and the connection
+ * target — whose account is being connected. It holds no token, because none exists yet.
+ *
+ * The TARGET is here rather than in the callback's query string for the reason the whole `state`
+ * mechanism exists: everything that comes back from the vendor arrives through the person's own
+ * browser and is therefore attacker-controllable. A callback that read the owner from its own URL
+ * would let somebody choose whose account a grant is stored against.
+ *
+ * assurance-control: WILDO.IDENTITY.DELEGATED_AUTHORIZATION — the authorization attempt is bound to
+ * the principal who started it.
+ */
+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 { SAAS_SERVICE_TYPES } from '../../../inject/models/service-types.js';
+/**
+ * Ten minutes.
+ *
+ * Long enough for somebody to read a consent screen, find the right account and sign in to the
+ * vendor if they were signed out. Short enough that an abandoned attempt — and the PKCE verifier
+ * inside it — does not sit in the cache for a day. Every major vendor's own authorization codes
+ * expire in this range, so a longer window would keep a record whose code is already dead.
+ */
+export const PROVIDER_OAUTH2_PENDING_TTL_SECONDS = 600;
+const KEY_PREFIX = 'oauth2-connect';
+let ProviderOAuth2PendingAuthorizationBackendService = class ProviderOAuth2PendingAuthorizationBackendService {
+    redis;
+    logger;
+    constructor(redis, logger) {
+        this.redis = redis;
+        this.logger = logger;
+    }
+    /**
+     * Remember one attempt against its `state`.
+     *
+     * The `state` IS the key. It is 32 random bytes, so it is unguessable, and using it directly means
+     * there is no second identifier that could get out of step with the one the vendor echoes back.
+     */
+    async remember(state, pending) {
+        await this.redis.set(this.keyFor(state), pending, { ttl: PROVIDER_OAUTH2_PENDING_TTL_SECONDS });
+        this.logger.debug?.('[oauth2-connect] authorization attempt recorded', {
+            providerRef: pending.providerRef,
+            ownerScope: pending.target.ownerScope,
+            // Never the state and never the verifier: both are secrets for the life of the record, and a
+            // debug log is the one place a secret most often escapes.
+        });
+    }
+    /**
+     * Take the attempt, removing it in the same round trip.
+     *
+     * `null` covers three situations a caller must treat identically — expired, already used, or never
+     * existed — and they MUST NOT be distinguished in any answer that reaches a browser. Telling an
+     * attacker that a `state` was valid but expired confirms they hold a real one.
+     */
+    async consume(state) {
+        return this.redis.getDel(this.keyFor(state));
+    }
+    /**
+     * Read the attempt WITHOUT taking it — for the callback, which must not consume.
+     *
+     * The callback authenticates nobody and finishes nothing; all it needs is the frontend to send the
+     * person back to, which is recorded here. Consuming there would burn the attempt before the
+     * authenticated half could redeem it, and that is not hypothetical: while the callback both
+     * consumed and authenticated, a failed authentication left the person unable even to retry — the
+     * state was already gone.
+     *
+     * The single-use guarantee is UNCHANGED and still lives in {@link consume}, which the completion
+     * route calls. This one hands back a copy and defends nothing on its own, so treat what it returns
+     * as unverified: it says an attempt with that `state` exists, never that this caller may finish it.
+     */
+    async peek(state) {
+        return this.redis.get(this.keyFor(state));
+    }
+    /**
+     * Namespaced, so nothing else in the cache can be addressed by supplying a crafted `state`.
+     *
+     * The state is used verbatim rather than hashed: it is already high-entropy and opaque, and
+     * hashing would only obscure which record a diagnostic is about while protecting nothing that the
+     * TTL does not already bound.
+     */
+    keyFor(state) {
+        return `${KEY_PREFIX}:${state}`;
+    }
+};
+ProviderOAuth2PendingAuthorizationBackendService = __decorate([
+    injectable(),
+    __param(0, inject(SAAS_SERVICE_TYPES.RedisService)),
+    __param(1, inject(SAAS_SERVICE_TYPES.Logger)),
+    __metadata("design:paramtypes", [Function, Function])
+], ProviderOAuth2PendingAuthorizationBackendService);
+export { ProviderOAuth2PendingAuthorizationBackendService };
+//# sourceMappingURL=provider-oauth2-pending-authorization.backend.service.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"provider-oauth2-pending-authorization.backend.service.js","sourceRoot":"","sources":["../../../../../src/security/connected-accounts/services/provider-oauth2-pending-authorization.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;;;;;;;;;;;;;AAEH,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAG/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,gDAAgD,CAAC;AAIpF;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,mCAAmC,GAAG,GAAG,CAAC;AAEvD,MAAM,UAAU,GAAG,gBAAgB,CAAC;AA0C7B,IAAM,gDAAgD,GAAtD,MAAM,gDAAgD;IAEC;IACN;IAFtD,YAC4D,KAAmB,EACzB,MAAqB;QADf,UAAK,GAAL,KAAK,CAAc;QACzB,WAAM,GAAN,MAAM,CAAe;IACxE,CAAC;IAEJ;;;;;OAKG;IACI,KAAK,CAAC,QAAQ,CAAC,KAAa,EAAE,OAA2C;QAC9E,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,EAAE,GAAG,EAAE,mCAAmC,EAAE,CAAC,CAAC;QAChG,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,iDAAiD,EAAE;YACrE,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC,UAAU;YACrC,6FAA6F;YAC7F,0DAA0D;SAC3D,CAAC,CAAC;IACL,CAAC;IAED;;;;;;OAMG;IACI,KAAK,CAAC,OAAO,CAAC,KAAa;QAChC,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAqC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IACnF,CAAC;IAED;;;;;;;;;;;;OAYG;IACI,KAAK,CAAC,IAAI,CAAC,KAAa;QAC7B,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAqC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAChF,CAAC;IAED;;;;;;OAMG;IACK,MAAM,CAAC,KAAa;QAC1B,OAAO,GAAG,UAAU,IAAI,KAAK,EAAE,CAAC;IAClC,CAAC;CACF,CAAA;AA5DY,gDAAgD;IAD5D,UAAU,EAAE;IAGR,WAAA,MAAM,CAAC,kBAAkB,CAAC,YAAY,CAAC,CAAA;IACvC,WAAA,MAAM,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAA;;GAHzB,gDAAgD,CA4D5D","sourcesContent":["/**\n * The record of ONE in-flight authorization attempt, from the redirect out to the callback back.\n *\n * ## Why this is ephemeral state and not a resource\n *\n * It exists for the seconds a person spends on a vendor's consent screen and is worthless\n * afterwards. Deleting the whole store costs those people one retry and nothing else — the test\n * `one-source-of-truth.md` applies: losing it costs TIME, never TRUTH, so it is a cache and must not\n * become a table. A resource would also mean three migrations, a retention policy and an erasure\n * question, for data whose correct lifetime is ten minutes.\n *\n * ## Single-use BY CONSTRUCTION, not by a flag\n *\n * Consumption is `GETDEL` — one round trip that returns the record and removes it atomically. So a\n * replayed callback finds nothing, and there is no window in which two concurrent callbacks both\n * read a record and both proceed. A `consumed: true` flag would have that window, and the attack it\n * opens is real: an authorization code delivered twice is how a stolen code gets grafted onto a\n * legitimate attempt.\n *\n * ## What it holds, and what it must never hold\n *\n * It holds the PKCE verifier, which is a secret for the length of the flow, and the connection\n * target — whose account is being connected. It holds no token, because none exists yet.\n *\n * The TARGET is here rather than in the callback's query string for the reason the whole `state`\n * mechanism exists: everything that comes back from the vendor arrives through the person's own\n * browser and is therefore attacker-controllable. A callback that read the owner from its own URL\n * would let somebody choose whose account a grant is stored against.\n *\n * assurance-control: WILDO.IDENTITY.DELEGATED_AUTHORIZATION — the authorization attempt is bound to\n * the principal who started it.\n */\n\nimport { inject, injectable } from 'inversify';\nimport type { ExternalProvider_ConnectionTarget } from '@wildo-ai/external-connectors-models';\n\nimport { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';\nimport type { RedisService } from '~wildo-backend-lib/databases/services/redis.service';\nimport type { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';\n\n/**\n * Ten minutes.\n *\n * Long enough for somebody to read a consent screen, find the right account and sign in to the\n * vendor if they were signed out. Short enough that an abandoned attempt — and the PKCE verifier\n * inside it — does not sit in the cache for a day. Every major vendor's own authorization codes\n * expire in this range, so a longer window would keep a record whose code is already dead.\n */\nexport const PROVIDER_OAUTH2_PENDING_TTL_SECONDS = 600;\n\nconst KEY_PREFIX = 'oauth2-connect';\n\nexport interface ProviderOAuth2PendingAuthorization {\n  /** Which provider is being connected. */\n  readonly providerRef: string;\n  /** The slot in the provider's secrets contract this grant will satisfy. */\n  readonly secretSlug: string;\n  /** WHOSE account is being connected. Never read back from the callback's URL. */\n  readonly target: ExternalProvider_ConnectionTarget;\n  /** The PKCE verifier, presented at the token exchange. Secret for the life of the record. */\n  readonly pkceVerifier: string;\n  /** The redirect URI sent at authorize; re-sent at the exchange and verified by the vendor. */\n  readonly redirectUri: string;\n  /** Values for the endpoints' `{placeholders}`, needed again to build the token URL. */\n  readonly connectionParameters?: Readonly<Record<string, string>>;\n  /**\n   * Who started the attempt, for the audit trail and for the callback's own authorization check.\n   *\n   * The callback re-checks that the person completing the flow is the person who began it. Without\n   * it, somebody who obtained a valid `state` could complete a connection while signed in as\n   * themselves and have the grant stored against the original initiator's target.\n   */\n  readonly initiatedByUserId?: string;\n  /**\n   * WHICH frontend the person came from, so the callback can send them back to it.\n   *\n   * Captured at START and carried here because the two legs reach the backend differently: the start\n   * leg is a FETCH from the application and carries Wildo's own headers, while the callback is a\n   * BROWSER NAVIGATION arriving from the vendor with none of them. Resolving the return URL at the\n   * callback from a header would therefore resolve nothing, and answering the browser with JSON —\n   * which this flow did until the omission was noticed — shows a person a raw payload instead of\n   * their settings screen.\n   *\n   * Optional because a caller that omits the header still gets a working CONNECTION; it only loses\n   * the redirect home, which is a worse experience rather than a broken one.\n   */\n  readonly frontendServiceName?: string;\n  /** When it was started, as an ISO instant — so an audit event can state how long consent took. */\n  readonly startedAt: string;\n}\n\n@injectable()\nexport class ProviderOAuth2PendingAuthorizationBackendService {\n  constructor(\n    @inject(SAAS_SERVICE_TYPES.RedisService) private readonly redis: RedisService,\n    @inject(SAAS_SERVICE_TYPES.Logger) private readonly logger: LoggerService,\n  ) {}\n\n  /**\n   * Remember one attempt against its `state`.\n   *\n   * The `state` IS the key. It is 32 random bytes, so it is unguessable, and using it directly means\n   * there is no second identifier that could get out of step with the one the vendor echoes back.\n   */\n  public async remember(state: string, pending: ProviderOAuth2PendingAuthorization): Promise<void> {\n    await this.redis.set(this.keyFor(state), pending, { ttl: PROVIDER_OAUTH2_PENDING_TTL_SECONDS });\n    this.logger.debug?.('[oauth2-connect] authorization attempt recorded', {\n      providerRef: pending.providerRef,\n      ownerScope: pending.target.ownerScope,\n      // Never the state and never the verifier: both are secrets for the life of the record, and a\n      // debug log is the one place a secret most often escapes.\n    });\n  }\n\n  /**\n   * Take the attempt, removing it in the same round trip.\n   *\n   * `null` covers three situations a caller must treat identically — expired, already used, or never\n   * existed — and they MUST NOT be distinguished in any answer that reaches a browser. Telling an\n   * attacker that a `state` was valid but expired confirms they hold a real one.\n   */\n  public async consume(state: string): Promise<ProviderOAuth2PendingAuthorization | null> {\n    return this.redis.getDel<ProviderOAuth2PendingAuthorization>(this.keyFor(state));\n  }\n\n  /**\n   * Read the attempt WITHOUT taking it — for the callback, which must not consume.\n   *\n   * The callback authenticates nobody and finishes nothing; all it needs is the frontend to send the\n   * person back to, which is recorded here. Consuming there would burn the attempt before the\n   * authenticated half could redeem it, and that is not hypothetical: while the callback both\n   * consumed and authenticated, a failed authentication left the person unable even to retry — the\n   * state was already gone.\n   *\n   * The single-use guarantee is UNCHANGED and still lives in {@link consume}, which the completion\n   * route calls. This one hands back a copy and defends nothing on its own, so treat what it returns\n   * as unverified: it says an attempt with that `state` exists, never that this caller may finish it.\n   */\n  public async peek(state: string): Promise<ProviderOAuth2PendingAuthorization | null> {\n    return this.redis.get<ProviderOAuth2PendingAuthorization>(this.keyFor(state));\n  }\n\n  /**\n   * Namespaced, so nothing else in the cache can be addressed by supplying a crafted `state`.\n   *\n   * The state is used verbatim rather than hashed: it is already high-entropy and opaque, and\n   * hashing would only obscure which record a diagnostic is about while protecting nothing that the\n   * TTL does not already bound.\n   */\n  private keyFor(state: string): string {\n    return `${KEY_PREFIX}:${state}`;\n  }\n}\n"]}

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

@@ -0,0 +1,54 @@
+/**
+ * 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.
+ */
+import type { ProviderOAuth2Grant } from '@wildo-ai/saas-models';
+import type { LoggerService } from '../../../monitoring/logger/services/logger.service';
+import type { ExternalProvidersRegistryBackendService } from '../../../external-providers/services/external-providers-registry.backend.service';
+import type { ProviderOAuth2RefreshRequest, ProviderOAuth2RefresherPort } from '../provider-oauth2-refresher.port';
+export declare class ProviderOAuth2RefresherBackendService implements ProviderOAuth2RefresherPort {
+    private readonly logger;
+    private readonly 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.
+     */
+    private readonly inFlight;
+    constructor(logger: LoggerService, externalProvidersRegistry: ExternalProvidersRegistryBackendService);
+    refreshGrant(request: ProviderOAuth2RefreshRequest): Promise<ProviderOAuth2Grant>;
+    private performRefresh;
+    /**
+     * 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.
+     */
+    private flightKeyFor;
+}
+//# sourceMappingURL=provider-oauth2-refresher.backend.service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"provider-oauth2-refresher.backend.service.d.ts","sourceRoot":"","sources":["../../../../../src/security/connected-accounts/services/provider-oauth2-refresher.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAIH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAGjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8DAA8D,CAAC;AAClG,OAAO,KAAK,EAAE,uCAAuC,EAAE,MAAM,4FAA4F,CAAC;AAO1J,OAAO,KAAK,EACV,4BAA4B,EAC5B,2BAA2B,EAC5B,MAAM,mCAAmC,CAAC;AAE3C,qBACa,qCAAsC,YAAW,2BAA2B;IAUlD,OAAO,CAAC,QAAQ,CAAC,MAAM;IAE1D,OAAO,CAAC,QAAQ,CAAC,yBAAyB;IAX5C;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmD;gBAGtB,MAAM,EAAE,aAAa,EAExD,yBAAyB,EAAE,uCAAuC;IAGxE,YAAY,CAAC,OAAO,EAAE,4BAA4B,GAAG,OAAO,CAAC,mBAAmB,CAAC;YAkBhF,cAAc;IAoE5B;;;;;OAKG;IACH,OAAO,CAAC,YAAY;CASrB"}

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('\u0000');
+    }
+};
+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,214 @@
+/**
+ * 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>;
+    /**
+     * 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: UserProviderCredentialQuery, 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 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;IAkExD;;;;;;;;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;;;;;;;;;;;;;;;;;OAiBG;IACU,mBAAmB,CAAC,KAAK,EAAE,2BAA2B,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAgC1G;;;;;;;;;;;;;;;;;;;;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"}