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

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

@@ -0,0 +1,387 @@
+/**
+ * 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.
+ */
+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 UserProviderCredentialStoreBackendService = class UserProviderCredentialStoreBackendService {
+    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 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.
+     */
+    async resolveUserCredential(query) {
+        const row = await this.readCredentialRow(query);
+        if (!row) {
+            return undefined;
+        }
+        // A disabled credential is treated as absent — which here means the call REFUSES, because there
+        // is nothing to fall through to. That is the intended shape: someone who switches their own
+        // connection off is asking the application to stop acting as them, and the honest outcome is an
+        // integration that stops rather than one that quietly continues under another identity.
+        if (row.enabled === false) {
+            this.logger.debug?.('[user-provider-credential] credential is disabled; treating as absent', { userId: query.userId, providerRef: query.providerRef, secretSlug: query.secretSlug });
+            return undefined;
+        }
+        const plaintext = openProviderCredential(row.secretValue, this.appConfigService.secrets.security.session.encryptionKey, {
+            ownerScope: ExternalProvider_Connection_OwnerScope.USER,
+            ownerId: query.userId,
+            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 = `user '${query.userId}', 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.USER,
+                    ownerId: query.userId,
+                    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 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.
+     */
+    async readCredentialRow(query) {
+        return this.systemAccess.readAsSystem(CoreResourceType.USER_PROVIDER_CREDENTIALS, {
+            userId: query.userId,
+            providerRef: query.providerRef,
+            secretSlug: query.secretSlug,
+        }, { scopeContext: { userId: query.userId } });
+    }
+    /**
+     * 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.
+     */
+    async recordCredentialUse(use) {
+        await this.emitUseAudit(use);
+        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.USER_PROVIDER_CREDENTIALS, use.credentialId, patch, {
+                scopeContext: { userId: use.userId },
+                /*
+                 * `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?.('[user-provider-credential] failed to record credential use', {
+                userId: use.userId,
+                providerRef: use.providerRef,
+                secretSlug: use.secretSlug,
+                credentialId: use.credentialId,
+                error: describeCaughtError(error),
+            });
+        }
+    }
+    async emitUseAudit(use) {
+        if (!this.auditLogs) {
+            return;
+        }
+        try {
+            await this.auditLogs.logUserProviderCredentialUsed({
+                userId: use.userId,
+                providerRef: use.providerRef,
+                secretSlug: use.secretSlug,
+                // Constant rather than a parameter: there is exactly one place a person's credential can come
+                // from. Threading it through the caller would invite a future one to pass something else.
+                resolvedFrom: ProviderCredentialResolutionSource.USER_CREDENTIAL,
+                credentialId: use.credentialId,
+            });
+        }
+        catch (error) {
+            this.logger.warn?.('[user-provider-credential] failed to emit credential-use audit event', {
+                userId: use.userId,
+                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 (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.
+     */
+    async storeGrant(query, grant, connectionParameters) {
+        const existing = await this.readCredentialRow(query);
+        const secretValue = serializeProviderOAuth2Grant(grant);
+        const scopeContext = { userId: query.userId };
+        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.USER_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.USER_PROVIDER_CREDENTIALS, {
+            userId: query.userId,
+            providerRef: query.providerRef,
+            secretSlug: query.secretSlug,
+            secretValue,
+            ...(connectionParameters === undefined ? {} : { connectionParameters }),
+        }, { scopeContext });
+        await this.emitConnectionGranted(query, grant, created._id, false);
+        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.USER_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: { userId: query.userId },
+                        // 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?.('[user-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.logUserProviderConnectionGranted({
+                userId: query.userId,
+                providerRef: query.providerRef,
+                secretSlug: query.secretSlug,
+                credentialId,
+                grantedScopes: grant.grantedScopes,
+                accountRef: grant.accountRef,
+                replacedExistingConnection,
+            });
+        }
+        catch (error) {
+            this.logger.warn?.('[user-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.USER_PROVIDER_CREDENTIALS, credentialId, { secretValue: serializeProviderOAuth2Grant(renewed) }, { scopeContext: { userId: query.userId } });
+    }
+    /**
+     * 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) {
+        return error instanceof ProviderCredentialEnvelopeError;
+    }
+};
+UserProviderCredentialStoreBackendService = __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])
+], UserProviderCredentialStoreBackendService);
+export { UserProviderCredentialStoreBackendService };
+//# sourceMappingURL=user-provider-credential-store.backend.service.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"user-provider-credential-store.backend.service.js","sourceRoot":"","sources":["../../../../../../src/security/connected-accounts/services/user-provider-credential-store.backend.service.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The user-provider-credential STORE — the port implementation the registry consults for a PERSON's\n * own credential.\n *\n * ## What makes the isolation structural rather than a filter\n *\n * The same three independent mechanisms as the organization store, and none of them is a predicate\n * somebody has to remember to write at each call site:\n *\n * 1. **The owner FK is injected by the context machinery.** The read goes through `readAsSystem`\n *    with the user in the system scope map, so `buildContextualFilter` adds the clause itself. A\n *    caller cannot omit it, because the caller never writes it.\n * 2. **The filter names the user explicitly as well.** Belt and braces, deliberately: the contextual\n *    filter is injected by a mechanism that exists TWICE (a Mongo implementation and a PostgreSQL\n *    one), so a regression in one adapter is a bypass in that adapter alone. The explicit clause is\n *    adapter-independent and would still scope the read.\n * 3. **The envelope is BOUND to the row identity, under a key derived for the USER scope.** Even a\n *    read that returned another person's row — or a tenant's — would fail to OPEN it. This is the\n *    one that holds when the other two are wrong, which is why it exists.\n *\n * ## Why this is a separate service rather than the organization store with an owner parameter\n *\n * The read is the same shape and everything around it differs. There is no fallback (a person who\n * has connected nothing gets a refusal, never the deployment's shared principal). There is no\n * administrative variant, so the actor and the subject are always the same identity and the audit\n * events say so. And the resource is a composition under `USERS` rather than under `ORGANIZATIONS`,\n * so the scope map, the cascade and the erasure semantics are a different set throughout.\n *\n * A single service parameterised by owner would carry every one of those as a branch, and the\n * branch a reader most needs to trust — \"is a fallback reachable from here?\" — would be the one\n * spelled as an `if`.\n *\n * assurance-control: WILDO.IDENTITY.DELEGATED_AUTHORIZATION — a user's delegated authority toward a\n * third party is read only for that user.\n */\n\nimport { inject, injectable, optional } from 'inversify';\nimport {\n  CoreResourceType,\n  ProviderCredentialResolutionSource,\n  ProviderCredentialValidationState,\n  serializeProviderOAuth2Grant,\n  type ProviderOAuth2Grant,\n  type UserProviderCredential,\n} from '@wildo-ai/saas-models';\n\nimport { ExternalProvider_Connection_DelegationMode, ExternalProvider_Connection_OwnerScope } from '@wildo-ai/external-connectors-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 { AppConfigurationService } from '~wildo-backend-lib/config/services/app-configuration.backend.service';\nimport type { SystemAccessBackendService } from '~wildo-backend-lib/base-classes/services/services/system-access.backend.service';\nimport type { AuditLogsBackendService } from '~wildo-backend-lib/compliance/audit-trails/services/audit-logs.backend.service';\nimport { describeCaughtError } from '~wildo-backend-lib/errors/utils/error-log-level-classification.backend.utils';\n\nimport {\n  ProviderCredentialEnvelopeError,\n  openProviderCredential,\n} from '../utils/provider-credential-envelope.backend.utils';\nimport { resolveStoredCredentialValue } from '../utils/stored-credential-value.backend.utils';\nimport { providerOAuth2GrantWasPermanentlyRejected } from './provider-oauth2-exchange.backend';\nimport type { ProviderOAuth2RefresherPort } from '../provider-oauth2-refresher.port';\nimport type {\n  UserProviderCredentialQuery,\n  UserProviderCredentialResolution,\n  UserProviderCredentialResolverPort,\n} from '../user-provider-credential-resolver.port';\n\n@injectable()\nexport class UserProviderCredentialStoreBackendService implements UserProviderCredentialResolverPort {\n  constructor(\n    @inject(SAAS_SERVICE_TYPES.Logger) private readonly logger: LoggerService,\n    @inject(SAAS_SERVICE_TYPES.AppConfigService) private readonly appConfigService: AppConfigurationService,\n    @inject(SAAS_SERVICE_TYPES.SystemAccessService) private readonly systemAccess: SystemAccessBackendService,\n    /**\n     * OPTIONAL and lazily used, mirroring `SystemAccessBackendService`'s own treatment of it: audit\n     * emission must never be the reason a provider call fails, and a minimal test container must\n     * still be able to construct this service.\n     */\n    @inject(SAAS_SERVICE_TYPES.AuditLogsService) @optional() private readonly auditLogs?: AuditLogsBackendService,\n    /**\n     * Appended LAST, deliberately: a parameter inserted mid-signature silently reassigns every\n     * positional argument after it, and this constructor is called positionally by several harnesses.\n     *\n     * OPTIONAL, and its absence is not a degradation — a store without one resolves every pasted\n     * credential and every non-expiring token exactly as before. Only an EXPIRING grant needs it, and\n     * that case refuses by name rather than sending a stale token.\n     */\n    @inject(SAAS_SERVICE_TYPES.ProviderOAuth2Refresher) @optional() private readonly refresher?: ProviderOAuth2RefresherPort,\n  ) {}\n\n  /**\n   * The person's own credential, opened, or `undefined` when they have not connected this provider.\n   *\n   * See the port's JSDoc for why \"absent\" returns and \"present but unopenable\" throws.\n   */\n  public async resolveUserCredential(\n    query: UserProviderCredentialQuery,\n  ): Promise<UserProviderCredentialResolution | undefined> {\n    const row = await this.readCredentialRow(query);\n    if (!row) {\n      return undefined;\n    }\n\n    // A disabled credential is treated as absent — which here means the call REFUSES, because there\n    // is nothing to fall through to. That is the intended shape: someone who switches their own\n    // connection off is asking the application to stop acting as them, and the honest outcome is an\n    // integration that stops rather than one that quietly continues under another identity.\n    if (row.enabled === false) {\n      this.logger.debug?.(\n        '[user-provider-credential] credential is disabled; treating as absent',\n        { userId: query.userId, providerRef: query.providerRef, secretSlug: query.secretSlug },\n      );\n      return undefined;\n    }\n\n    const plaintext = openProviderCredential(\n      row.secretValue,\n      this.appConfigService.secrets.security.session.encryptionKey,\n      {\n        ownerScope: ExternalProvider_Connection_OwnerScope.USER,\n        ownerId: query.userId,\n        providerRef: query.providerRef,\n        secretSlug: query.secretSlug,\n      },\n    );\n\n    // What is STORED is not always what goes on the wire: an OAuth2 grant is a JSON document whose\n    // access token is one field. Returning the plaintext directly would put that document on the\n    // wire as a bearer token, and the vendor's 401 would name a credential problem rather than a\n    // serialization one. One shared resolver, because both stores hold both shapes.\n    const describeRow = `user '${query.userId}', provider '${query.providerRef}', slug '${query.secretSlug}'`;\n    const resolved = resolveStoredCredentialValue(plaintext, describeRow, this.refresher !== undefined);\n    if (resolved.needsRefresh) {\n      // The renewal round trip and the write-back, in that order. The exchange belongs to the\n      // refresher (it needs the contract and the application's registration); persisting belongs\n      // here (it needs the table, the envelope key and the scope map). Neither half is where the\n      // other's inputs are, which is why this is two components rather than one.\n      const renewed = await this.renewOrRetire(row._id, query, {\n        providerRef: query.providerRef,\n        secretSlug: query.secretSlug,\n        target: {\n          ownerScope: ExternalProvider_Connection_OwnerScope.USER,\n          ownerId: query.userId,\n          delegation: ExternalProvider_Connection_DelegationMode.SERVICE,\n        },\n        grant: resolved.grant!,\n        // From the ROW. The authorization record that first held these expired ten minutes after\n        // the connect; a templated token URL is still templated an hour later, so without this a\n        // Microsoft or regional connection renews into `needs a value for 'cloud'`.\n        connectionParameters: row.connectionParameters,\n      });\n      await this.persistRenewedGrant(query, row._id, renewed);\n      return { value: renewed.accessToken, credentialId: row._id };\n    }\n\n    return { value: resolved.wireValue, credentialId: row._id };\n  }\n\n  /**\n   * The scoped read.\n   *\n   * `readAsSystem` rather than an ordinary repository read, for the reason the organization sibling\n   * documents: a provider call legitimately happens on a batch, a queue consumer or a webhook return\n   * leg, none of which carries the person's own session, and all of which must still resolve their\n   * credential. The user travels in the system scope map, which is the channel the contextual filter\n   * actually consumes.\n   */\n  private async readCredentialRow(\n    query: UserProviderCredentialQuery,\n  ): Promise<UserProviderCredential | null> {\n    return this.systemAccess.readAsSystem<UserProviderCredential>(\n      CoreResourceType.USER_PROVIDER_CREDENTIALS,\n      {\n        userId: query.userId,\n        providerRef: query.providerRef,\n        secretSlug: query.secretSlug,\n      },\n      { scopeContext: { userId: query.userId } },\n    );\n  }\n\n  /**\n   * Record that a credential was spent, and what the provider thought of it.\n   *\n   * Best-effort in both halves and deliberately so: the outbound provider call has already happened\n   * by the time this runs, and failing the caller because a bookkeeping write did not land would\n   * turn a successful integration into an error. Every failure is logged with the row named.\n   */\n  public async recordCredentialUse(use: {\n    userId: string;\n    providerRef: string;\n    secretSlug: string;\n    credentialId: string;\n    /** What the provider said. Absent means the outcome is not yet known to the caller. */\n    outcome?: { accepted: boolean; providerMessage?: string };\n  }): Promise<void> {\n    await this.emitUseAudit(use);\n\n    const now = new Date();\n    const patch: Record<string, unknown> = { lastUsedAt: now };\n    if (use.outcome) {\n      patch.validationState = use.outcome.accepted\n        ? ProviderCredentialValidationState.VALID\n        : ProviderCredentialValidationState.INVALID;\n      patch.lastValidatedAt = now;\n      // Truncated to the schema's own bound. The provider's message describes the CREDENTIAL's\n      // status and must never be derived from the credential itself — a caller passing the secret\n      // here would publish it to a client-readable field, which is why this is documented at the\n      // one place a provider string enters the row.\n      patch.validationError = use.outcome.accepted\n        ? undefined\n        : (use.outcome.providerMessage ?? '').slice(0, 500) || undefined;\n    }\n\n    try {\n      await this.systemAccess.updateAsSystem(\n        CoreResourceType.USER_PROVIDER_CREDENTIALS,\n        use.credentialId,\n        patch,\n        {\n          scopeContext: { userId: use.userId },\n          /*\n           * `lastUsedAt`, `lastValidatedAt` and `validationError` are all\n           * `.excludeFromCreate().excludeFromUpdate()`, so the repository's strict `requestDto.parse`\n           * drops them before persistence unless they are allow-listed here.\n           *\n           * The automatic diff that populates this list covers fields a custom-impl PREFIX hook\n           * injected — which is how `secretSetAt` reaches the row on a write. Nothing populates it\n           * for a payload a caller passes directly, which is what this is, so the omission was\n           * silent in the worst way: `validationState` is NOT excluded and moved correctly, so the\n           * row went INVALID while the timestamp and the provider's explanation of WHY vanished.\n           * A person looking at a credential marked invalid with no reason and no last-use time is\n           * being told less than the code believes it recorded.\n           */\n          preserveServerInjectedFields: ['lastUsedAt', 'lastValidatedAt', 'validationError'],\n        },\n      );\n    } catch (error) {\n      this.logger.warn?.(\n        '[user-provider-credential] failed to record credential use',\n        {\n          userId: use.userId,\n          providerRef: use.providerRef,\n          secretSlug: use.secretSlug,\n          credentialId: use.credentialId,\n          error: describeCaughtError(error),\n        },\n      );\n    }\n  }\n\n  private async emitUseAudit(use: {\n    userId: string;\n    providerRef: string;\n    secretSlug: string;\n    credentialId: string;\n  }): Promise<void> {\n    if (!this.auditLogs) {\n      return;\n    }\n    try {\n      await this.auditLogs.logUserProviderCredentialUsed({\n        userId: use.userId,\n        providerRef: use.providerRef,\n        secretSlug: use.secretSlug,\n        // Constant rather than a parameter: there is exactly one place a person's credential can come\n        // from. Threading it through the caller would invite a future one to pass something else.\n        resolvedFrom: ProviderCredentialResolutionSource.USER_CREDENTIAL,\n        credentialId: use.credentialId,\n      });\n    } catch (error) {\n      this.logger.warn?.(\n        '[user-provider-credential] failed to emit credential-use audit event',\n        {\n          userId: use.userId,\n          providerRef: use.providerRef,\n          error: describeCaughtError(error),\n        },\n      );\n    }\n  }\n\n\n  /**\n   * Record a grant the authorization exchange just minted, replacing one already stored.\n   *\n   * The plaintext goes in and the resource's own WRITE DOOR seals it — the same hook that seals a\n   * credential a person types, and the same reason `persistRenewedGrant` hands over plaintext:\n   * `createAsSystem` / `updateAsSystem` reach the SERVICE tier, so a pre-sealed value arrives at\n   * that hook and the envelope refuses to double-seal.\n   *\n   * ## Reconnecting REPLACES rather than adding a second row\n   *\n   * The business key is (userId, providerRef, secretSlug) and it is UNIQUE, so a second connect would\n   * violate the index. Read-then-write is a race, and the honest statement is that the index is what\n   * decides it: two simultaneous connects mean one of them loses, which is the correct outcome —\n   * a person who authorized twice gets one connection, not two half-connections.\n   *\n   * @returns the credential row's id, so the caller can name it in an audit event.\n   */\n  public async storeGrant(\n    query: UserProviderCredentialQuery,\n    grant: ProviderOAuth2Grant,\n    connectionParameters?: Readonly<Record<string, string>>,\n  ): Promise<string> {\n    const existing = await this.readCredentialRow(query);\n    const secretValue = serializeProviderOAuth2Grant(grant);\n    const scopeContext = { userId: query.userId };\n\n    if (existing) {\n      // `connectionParameters` is `.excludeFromUpdate()` — it describes the ACCOUNT the grant is\n      // for, and re-authorizing against a different directory is a different connection. A\n      // reconnect that changed them would point the refresh somewhere the token was not issued.\n      await this.systemAccess.updateAsSystem(\n        CoreResourceType.USER_PROVIDER_CREDENTIALS,\n        existing._id,\n        {\n          secretValue,\n          enabled: true,\n          // Clearing the mark is part of reconnecting, not a separate concern. A row retired by\n          // `renewOrRetire` would otherwise keep `validationState: INVALID` forever — so somebody\n          // who did exactly what the screen told them to do would reconnect successfully and still\n          // be shown a broken connection.\n          validationState: ProviderCredentialValidationState.UNVALIDATED,\n          validationError: undefined,\n        },\n        { scopeContext, preserveServerInjectedFields: ['validationError'] },\n      );\n      await this.emitConnectionGranted(query, grant, existing._id, true);\n      return existing._id;\n    }\n\n    const created = await this.systemAccess.createAsSystem<UserProviderCredential>(\n      CoreResourceType.USER_PROVIDER_CREDENTIALS,\n      {\n        userId: query.userId,\n        providerRef: query.providerRef,\n        secretSlug: query.secretSlug,\n        secretValue,\n        ...(connectionParameters === undefined ? {} : { connectionParameters }),\n      },\n      { scopeContext },\n    );\n    await this.emitConnectionGranted(query, grant, created._id, false);\n    return created._id;\n  }\n\n  /**\n   * Renew the grant, and RETIRE the connection when the vendor says it is finished.\n   *\n   * Without this the refresh call was unguarded, and the failure was slow and silent in the worst\n   * direction. A vendor that permanently rejects a refresh token — the person removed the app at the\n   * vendor, an administrator revoked it, the token aged past its absolute lifetime — throws, the\n   * error propagates out of the resolve, and NOTHING touches the row. `validationState` stays where\n   * it was, so the connected-accounts screen goes on showing the account as connected, every call\n   * fails identically forever, and the person is never told the one thing they could act on.\n   *\n   * Only `invalid_grant` retires a connection, and the exclusions are the substantive part. A\n   * transport failure, a bare 500 or an unparseable body means the vendor said NOTHING about the\n   * grant, and retiring a working connection because we could not reach a vendor for thirty seconds\n   * would be a self-inflicted outage. `invalid_client` is excluded for a different reason: it is the\n   * APPLICATION's own registration being rejected, one operator's misconfiguration affecting every\n   * connection at once — marking each person's account invalid would blame all of them for something\n   * none of them can fix.\n   *\n   * The mark is best-effort and the ORIGINAL error is always re-thrown: the caller needs the real\n   * cause, and a bookkeeping write that failed must not replace it with a different story.\n   */\n  private async renewOrRetire(\n    credentialId: string,\n    query: UserProviderCredentialQuery,\n    request: Parameters<ProviderOAuth2RefresherPort['refreshGrant']>[0],\n  ): Promise<ProviderOAuth2Grant> {\n    try {\n      return await this.refresher!.refreshGrant(request);\n    } catch (error) {\n      if (providerOAuth2GrantWasPermanentlyRejected(error)) {\n        try {\n          await this.systemAccess.updateAsSystem(\n            CoreResourceType.USER_PROVIDER_CREDENTIALS,\n            credentialId,\n            {\n              validationState: ProviderCredentialValidationState.INVALID,\n              lastValidatedAt: new Date(),\n              // The vendor's own code, and nothing derived from the credential. This field is\n              // CLIENT-READABLE, so anything token-shaped reaching it would publish a secret onto\n              // the screen that displays it.\n              validationError: 'The provider rejected the stored authorization (invalid_grant). Reconnect the account.',\n            },\n            {\n              scopeContext: { userId: query.userId },\n              // Both of these are `.excludeFromUpdate()`; without the allow-list the row would go\n              // INVALID carrying no reason and no timestamp — see `recordCredentialUse`.\n              preserveServerInjectedFields: ['lastValidatedAt', 'validationError'],\n            },\n          );\n        } catch (markError) {\n          this.logger.warn?.(\n            '[user-provider-credential] a grant was permanently rejected and the row could not be marked',\n            { providerRef: query.providerRef, secretSlug: query.secretSlug, credentialId, error: describeCaughtError(markError) },\n          );\n        }\n      }\n      throw error;\n    }\n  }\n\n  /**\n   * Record that a delegated authorization was GRANTED, distinct from the row's own `_SET` event.\n   *\n   * Emitted HERE and nowhere else, because this is the only place that holds the three facts an\n   * auditor wants and the row does not: the scopes the vendor actually issued, which account they\n   * were issued for, and whether this replaced a connection that already existed. By the time the\n   * resource's own write hook sees the row, the value is sealed and none of it is recoverable.\n   *\n   * Best-effort, like every other emission on this path. The grant is already stored and the person\n   * has already authorized it; failing their connection because a trail write did not land would\n   * turn a completed authorization into an error and invite them to grant it a second time.\n   */\n  private async emitConnectionGranted(\n    query: UserProviderCredentialQuery,\n    grant: ProviderOAuth2Grant,\n    credentialId: string,\n    replacedExistingConnection: boolean,\n  ): Promise<void> {\n    if (!this.auditLogs) {\n      return;\n    }\n    try {\n      await this.auditLogs.logUserProviderConnectionGranted({\n        userId: query.userId,\n        providerRef: query.providerRef,\n        secretSlug: query.secretSlug,\n        credentialId,\n        grantedScopes: grant.grantedScopes,\n        accountRef: grant.accountRef,\n        replacedExistingConnection,\n      });\n    } catch (error) {\n      this.logger.warn?.(\n        '[user-provider-credential] a connection was granted and the audit event could not be emitted',\n        { providerRef: query.providerRef, secretSlug: query.secretSlug, credentialId, error: describeCaughtError(error) },\n      );\n    }\n  }\n\n  /**\n   * Persist a renewed grant through the resource's own WRITE door.\n   *\n   * The plaintext goes in and the CUSTOM IMPLEMENTATION seals it — the same hook that seals a\n   * credential a person types. Sealing here instead would be a second sealing site for one\n   * invariant, and it does not merely duplicate: `updateAsSystem` reaches the service tier, so a\n   * pre-sealed value arrives at that hook and the envelope REFUSES it (\"double-sealing would hand\n   * the envelope itself to the provider\"). Every refresh would have thrown at the write-back.\n   *\n   * `secretSetAt` therefore moves, and that is correct rather than tolerated: the field is defined\n   * as \"when the stored VALUE last changed\", and a renewal changes it. An earlier version of this\n   * method held it still on the theory that it should mean \"when a HUMAN last supplied a value\" —\n   * that is a different field, and inventing the behaviour without the field was the error.\n   *\n   * NOT best-effort. A refresh that is not persisted happens again on every call, and against a\n   * vendor that rotates the refresh token each one invalidates the last — so the connection breaks\n   * while every individual exchange succeeds.\n   */\n  private async persistRenewedGrant(\n    query: UserProviderCredentialQuery,\n    credentialId: string,\n    renewed: ProviderOAuth2Grant,\n  ): Promise<void> {\n    await this.systemAccess.updateAsSystem(\n      CoreResourceType.USER_PROVIDER_CREDENTIALS,\n      credentialId,\n      { secretValue: serializeProviderOAuth2Grant(renewed) },\n      { scopeContext: { userId: query.userId } },\n    );\n  }\n\n  /**\n   * Turn an envelope failure into the operator-facing statement.\n   *\n   * Exposed so the registry can distinguish \"this person has no credential\" from \"they HAVE one and\n   * it is broken\" without importing the envelope's error type and re-deriving the distinction. One\n   * definition, one meaning.\n   */\n  public static isUnopenableCredential(error: unknown): error is ProviderCredentialEnvelopeError {\n    return error instanceof ProviderCredentialEnvelopeError;\n  }\n}\n"]}

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

@@ -0,0 +1,45 @@
+/**
+ * The WRITE path for a PERSON's own provider credential: seal on the way in, audit on the way out.
+ *
+ * ## Without this file the resource stores plaintext
+ *
+ * The schema declares `secretValue` as `.isWriteOnlySecret()`, which governs how the value is
+ * PRESENTED (redacted at the client boundary, and a round-tripped mask means "keep the stored
+ * secret"). It says nothing about how the value is STORED — a write-only-secret field lands in the
+ * database exactly as the client typed it. Sealing it is this hook's job, and it is the only place
+ * that job is done, so a credential reaching persistence unsealed means this registration did not
+ * resolve.
+ *
+ * ⚠️ A custom implementation resolves by an EXACT operation-path key embedding the resource, the
+ * operation, the variant TYPE and the default/variant-key slot. A registration naming a combination
+ * the resource configuration does not declare resolves nothing and silently never runs, while the
+ * route still answers 200 — here that would mean every person's third-party key persisted in
+ * plaintext behind a green suite. The pins assert these registrations against the REAL resource
+ * configuration for that reason.
+ *
+ * ## What differs from the organization sibling, and why each difference is substantive
+ *
+ * - **No `setByUserId`.** The organization's row records WHICH administrator wrote it, because
+ *   several can. This resource declares no administrative variant at all, so the author is always
+ *   the owner and a separate field could only ever repeat `userId` — while inviting a future reader
+ *   to believe the two can differ.
+ * - **The DELETE reason is `OWNER_REVOKED`, not `ADMINISTRATOR_REVOKED`.** Same door, different
+ *   meaning: nobody but the holder can reach it.
+ * - **The cascade door destroys evidence that matters more.** When a subject is erased, the
+ *   `USERS → USER_PROVIDER_CREDENTIALS` composition removes these rows through the RAW repository,
+ *   bypassing the service tier exactly as the organization purge does. The consequence is sharper
+ *   here: the deletion event is what an operator produces when asked whether an erasure reached the
+ *   person's third-party credentials, and the cascade cannot emit one. `USER_DELETED` records that
+ *   the subject was erased; what is missing is the enumeration of WHICH vendors they had connected.
+ *   This is the SAME defect as the organization purge's, at a second site — one cascade-tier audit
+ *   hook fixes both — and it is recorded on issue #365 rather than left for a reader to discover
+ *   from an absence. `ProviderCredentialDeletionReason.USER_ERASED` exists for the event that hook
+ *   will emit; nothing can emit it today.
+ *
+ * assurance-control: WILDO.IDENTITY.DELEGATED_AUTHORIZATION — a user authorizes, rotates and
+ * withdraws delegated access to a named third party.
+ */
+import { type ResourceCustomServiceImplementationFactory } from '../../../base-classes/services/services/resource-operation-custom-implementation.factory.backend';
+/** Every write door of the user-provider-credential resource. */
+export declare function createUserProviderCredentialFactories(): ResourceCustomServiceImplementationFactory[];
+//# sourceMappingURL=user-provider-credentials.custom-impl.backend.service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"user-provider-credentials.custom-impl.backend.service.d.ts","sourceRoot":"","sources":["../../../../../../src/security/connected-accounts/services/user-provider-credentials.custom-impl.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAkBH,OAAO,EAEL,KAAK,0CAA0C,EAChD,MAAM,4GAA4G,CAAC;AAwUpH,iEAAiE;AACjE,wBAAgB,qCAAqC,IAAI,0CAA0C,EAAE,CAMpG"}