@wildo-ai/saas-models 1.1.4 → 1.1.5

package/dist/esm/security/connected-accounts/provider-credentials.shared.schemas.js

@@ -24,7 +24,8 @@
  *
  * `secretValue` holds an AES-256-GCM envelope, never the plaintext an operator typed. The seal is
  * applied on the way in and opened only by the resolver — see
- * `provider-credential-envelope.backend.utils.ts` for the envelope and its key derivation. The
+ * `provider-credential-envelope.backend.utils.ts` for its key domains and binding, over the shared
+ * `bound-secret-envelope` core that does the sealing (#366). The
  * schema cannot enforce that (a string is a string), so the write path is what guarantees it and
  * the pins are what keep it guaranteed.
  */
@@ -47,17 +48,59 @@ export var ProviderCredentialValidationState;
     ProviderCredentialValidationState["INVALID"] = "invalid";
 })(ProviderCredentialValidationState || (ProviderCredentialValidationState = {}));
 /**
- * The organization's credential for one (provider, secret slug) pair.
+ * Why a write door refused to store a credential VALUE under the slot it named — the stable,
+ * client-branchable `code` every door carries (#624).
  *
- * ## The scope identifier is TOP-LEVEL and stays that way
+ * A stored row is keyed `(owner, providerRef, secretSlug)` on the provider's secrets-contract KEY, and
+ * every reader asks for that key. A value written under any other name is a secret nothing can ever
+ * read, and before these refusals the write reported success — which is how a regenerated provider,
+ * a free-text slug or a test script produced rows that looked connected and resolved as absent.
  *
- * `organizationId` is the only `organizationId`-named path in this schema, and nothing nested may
- * ever be named `organizationId` or `userId`. `buildContextualFilter` injects the scope FK by
- * matching that field name at EVERY schema path, so a nested key of the same name adds a phantom
- * exact-subdocument clause and the scoped read silently matches zero rows — a credential that
- * exists and cannot be resolved, which reads exactly like a credential that was never set.
- * `setByUserId` is deliberately spelled so it cannot be caught by that matcher.
+ * The member values are the wire codes the connect leg already answered with, so one vocabulary
+ * serves the connect leg, the resource's own CREATE / UPDATE doors and any client that branches.
  */
+export var ProviderCredentialSlotWriteRefusal;
+(function (ProviderCredentialSlotWriteRefusal) {
+    /**
+     * The provider's current secrets contract declares no slot by that name — under either of a slot's
+     * two names. Also the answer for a provider that is not registered at all, and for ROTATING a value
+     * into an existing row whose stored name is not a contract KEY — a retired name, or a spelling no
+     * reader asks for: a fresh secret sealed there is as unreadable as the old one.
+     */
+    ProviderCredentialSlotWriteRefusal["SECRET_SLUG_NOT_DECLARED"] = "SECRET_SLUG_NOT_DECLARED";
+    /**
+     * The slot exists but holds the APPLICATION's own registration (an OAuth2 client id or secret),
+     * which is authored in the deployment environment and never read from a credential row.
+     */
+    ProviderCredentialSlotWriteRefusal["SECRET_SLUG_NOT_A_CREDENTIAL"] = "SECRET_SLUG_NOT_A_CREDENTIAL";
+    /**
+     * An UPDATE named a different `providerRef` or `secretSlug` for an existing row. The sealed value is
+     * bound to both, so a row cannot move: a credential for another slot is a new row, and the old one is
+     * deleted.
+     */
+    ProviderCredentialSlotWriteRefusal["CREDENTIAL_SLOT_IMMUTABLE"] = "CREDENTIAL_SLOT_IMMUTABLE";
+})(ProviderCredentialSlotWriteRefusal || (ProviderCredentialSlotWriteRefusal = {}));
+/**
+ * How one connection fact got onto a credential row (#333, #1047). The distinction is what decides who may
+ * change it: an answer changes only when the person reconnects, a vendor report whenever the vendor
+ * reports it again.
+ */
+export var ProviderConnectionFactProvenance;
+(function (ProviderConnectionFactProvenance) {
+    /**
+     * Typed by the person connecting, for an endpoint or scope `{placeholder}` at the OAuth2 start — or, for a
+     * vendor whose credential is PASTED, for a `{placeholder}` of the REST base URL at the typed-credential store
+     * (#1097). Replaced only by reconnecting or re-entering the credential.
+     */
+    ProviderConnectionFactProvenance["ANSWERED_AT_CONNECT"] = "ANSWERED_AT_CONNECT";
+    /** Reported by the vendor in its token answer, at the authorization or at a refresh. A refresh may move it. */
+    ProviderConnectionFactProvenance["REPORTED_BY_VENDOR"] = "REPORTED_BY_VENDOR";
+})(ProviderConnectionFactProvenance || (ProviderConnectionFactProvenance = {}));
+/** One value in a credential row's `connectionFacts`. */
+export const ProviderConnectionFactSchema = z.strictObject({
+    value: z.string(),
+    provenance: z.enum(ProviderConnectionFactProvenance),
+});
 /**
  * WHERE a resolved provider secret came from.
  *
@@ -88,7 +131,73 @@ export var ProviderCredentialResolutionSource;
      */
     ProviderCredentialResolutionSource["USER_CREDENTIAL"] = "user_credential";
 })(ProviderCredentialResolutionSource || (ProviderCredentialResolutionSource = {}));
-/** Why a credential row stopped existing. */
+/**
+ * What telling the VENDOR achieved when a credential was removed (#545).
+ *
+ * A separate axis from {@link ProviderCredentialDeletionReason} on purpose: that one says why OUR
+ * COPY stopped existing, this one says whether the authorization itself was withdrawn where it
+ * lives. They were one question for as long as the answer was always "it was not".
+ *
+ * Every member is EVIDENCE, and none of them is control flow — the local delete proceeds whatever
+ * this says, because a vendor being unreachable must not stop somebody disconnecting.
+ */
+export var ProviderOAuth2RevocationOutcome;
+(function (ProviderOAuth2RevocationOutcome) {
+    /**
+     * The vendor answered 200.
+     *
+     * Under RFC 7009 that also covers a token the server did not recognise, which is the intended
+     * reading: the grant is gone either way.
+     * spec-cite: RFC 7009 §2.2 — *"The authorization server responds with HTTP status code 200 if the
+     * token has been revoked successfully or if the client submitted an invalid token"*.
+     */
+    ProviderOAuth2RevocationOutcome["REVOKED"] = "revoked";
+    /**
+     * Nothing was sent, and that is the ordinary case rather than a failure.
+     *
+     * Three situations share this member because they are one fact from the person's side — the vendor
+     * was not told: the provider declares no `rfc7009RevocationUrl`; the credential was a PASTED
+     * long-lived key rather than a grant, so there is nothing to revoke; or the grant carried no token.
+     */
+    ProviderOAuth2RevocationOutcome["NOT_DECLARED"] = "not_declared";
+    /** The application's own client registration for this vendor is unset, so nothing could be sent. */
+    ProviderOAuth2RevocationOutcome["NOT_CONFIGURED"] = "not_configured";
+    /** The endpoint could not be reached, or did not answer within the deadline. */
+    ProviderOAuth2RevocationOutcome["UNREACHABLE"] = "unreachable";
+    /** The endpoint answered, and not with 200. */
+    ProviderOAuth2RevocationOutcome["REFUSED"] = "refused";
+})(ProviderOAuth2RevocationOutcome || (ProviderOAuth2RevocationOutcome = {}));
+/** The wire values of {@link ProviderOAuth2RevocationOutcome}, for a Zod enum over them. */
+export const ProviderOAuth2RevocationOutcomeValues = ProviderOAuth2RevocationOutcome;
+/**
+ * Why a credential row stopped existing.
+ *
+ * ## Every member describes OUR COPY; whether the VENDOR was told is a SECOND axis (#545)
+ *
+ * Removing a credential deletes the token Wildo holds. Until 2026-09-18 it also did nothing else,
+ * so the GRANT survived at the vendor: the person's connected-accounts screen showed the application
+ * gone while Asana or Google still listed it as authorized, and a stored refresh token remained
+ * valid until it expired on the vendor's schedule — which, for a refresh token, is frequently never.
+ *
+ * That is stated HERE because this vocabulary is what an operator points at when asked whether an
+ * erasure reached someone's third-party credentials, and silence on a compliance surface reads as
+ * "done".
+ *
+ * **It is no longer silent.** Both deletion events now carry
+ * {@link ProviderOAuth2RevocationOutcome}, so the trail answers the vendor question separately from
+ * the local one. What that outcome can SAY still depends on the vendor: RFC 7009 is the only
+ * revocation standard and the vendors do not agree with it, so `google-drive` and `asana` declare an
+ * endpoint and are told, while Slack's `auth.revoke` (a Web API method) and GitHub's
+ * `DELETE /applications/{client_id}/token` (basic auth, JSON body) are not expressible as one and
+ * record `not_declared` rather than implying they were reached.
+ *
+ * An earlier revision of this block argued the mechanism should NOT be built, because *"no
+ * admissible provider declares one today, so the field would ship inert"*. That was true when it was
+ * written and stopped being true when `google-drive` gained an admissible USER connection: Google's
+ * `https://oauth2.googleapis.com/revoke` is RFC 7009-conformant, so the mechanism has a reachable
+ * user and a proven vendor. Kept as history rather than deleted, because the reasoning was sound and
+ * the thing that changed was the world, not the argument.
+ */
 export var ProviderCredentialDeletionReason;
 (function (ProviderCredentialDeletionReason) {
     /** An administrator of the owning tenant removed it. */
@@ -103,8 +212,36 @@ export var ProviderCredentialDeletionReason;
      * Distinct from `ORGANIZATION_PURGED` because this one is EVIDENCE: it is what an operator points
      * at when asked whether a subject-erasure request reached the person's third-party credentials.
      * Collapsing the two into a generic "cascade" would make that question unanswerable from the trail.
+     *
+     * **Who sets it:** the cascade observer, for a cascade declaring itself a `SUBJECT_ERASURE`. The record
+     * carries `deletedBy` = whoever EXECUTED the erasure (a person's id when one was carried on the erasure's
+     * context, else the `SYSTEM` sentinel), so the erased person is the record's SUBJECT and never its actor
+     * (#1088).
      */
     ProviderCredentialDeletionReason["USER_ERASED"] = "user_erased";
+    /**
+     * The owning user ROW was deleted outright and the composition cascade destroyed the credential with it (#1016).
+     *
+     * **Who sets it:** the user-credential parent-cascade removal observer
+     * (`registerUserProviderCredentialCascadeEvidence`), for a cascade that declares its cause as an ordinary parent
+     * delete of the `users` row. Two doors reach it today: an administrator's hard `DELETE` (`deletedBy` is that
+     * administrator), and the organization-member invitation sweep reaping an orphaned pending user under an internal
+     * context (`deletedBy` is the `SYSTEM` sentinel). The record carries `deletedBy`, resolved from the deleting
+     * execution context, so it names the principal who deleted the account rather than the person whose credential
+     * it was.
+     *
+     * **Distinct from `USER_ERASED`**, and the distinction is the reason this member exists: an erasure answers a
+     * data-subject request, keeps the person's row scrubbed and is evidence that the request reached their third-party
+     * credentials. A deletion asserts no such request. Recording it as `USER_ERASED` would forge erasure evidence;
+     * recording nothing left an account deletion that destroyed OAuth grants and API keys with no row naming them.
+     *
+     * **Distinct from `ORGANIZATION_PURGED`**: that is a tenant teardown removing the ORGANIZATION's credentials. This
+     * removes one PERSON's own credentials, which no organization owns.
+     *
+     * Named for what happened to the owner, not for who did it: the cascade cannot tell an administrator's delete from
+     * any other deletion of the row, and `deletedBy` is where the actor is stated.
+     */
+    ProviderCredentialDeletionReason["USER_DELETED"] = "user_deleted";
 })(ProviderCredentialDeletionReason || (ProviderCredentialDeletionReason = {}));
 /**
  * The fields that IDENTIFY a credential within its tenant.
@@ -118,6 +255,18 @@ export const ORGANIZATION_PROVIDER_CREDENTIAL_IDENTITY_FIELDS = [
     'providerRef',
     'secretSlug',
 ];
+/**
+ * The organization's credential for one (provider, secret slug) pair.
+ *
+ * ## The scope identifier is TOP-LEVEL and stays that way
+ *
+ * `organizationId` is the only `organizationId`-named path in this schema, and nothing nested may
+ * ever be named `organizationId` or `userId`. `buildContextualFilter` injects the scope FK by
+ * matching that field name at EVERY schema path, so a nested key of the same name adds a phantom
+ * exact-subdocument clause and the scoped read silently matches zero rows — a credential that
+ * exists and cannot be resolved, which reads exactly like a credential that was never set.
+ * `setByUserId` is deliberately spelled so it cannot be caught by that matcher.
+ */
 export const OrganizationProviderCredentialSchema = z.object({
     _id: z.string().min(1).isPrimaryKey().isSummaryField(),
     /**
@@ -134,10 +283,13 @@ export const OrganizationProviderCredentialSchema = z.object({
      */
     providerRef: z.string().min(1).max(200).isDBIndexed().isSummaryField().excludeFromUpdate(),
     /**
-     * The slug in the provider's `secretsContract` that this value satisfies — the same identifier
-     * the deployment's env projection carries, so the two resolution places name the same thing.
-     * Immutable: re-pointing a stored secret at a different slug would silently hand one vendor
-     * credential to a different vendor field.
+     * The provider's `secretsContract` KEY this value satisfies (`accessToken`, `clientSecret`) —
+     * NOT the slot's env-var spelling (`ASANA_ACCESS_TOKEN`), which is what the deployment's env
+     * projection carries and what a provider regeneration may rename. The two resolution places name
+     * the same SLOT by different names, and only the key is stable enough to key a durable row on
+     * (#624). Immutable: re-pointing a stored secret at a different slug would silently hand one vendor
+     * credential to a different vendor field — and the sealed value binds the slug, so a row stored
+     * under a name the provider no longer declares cannot be renamed, only replaced by reconnecting.
      */
     secretSlug: z.string().min(1).max(200).isDBIndexed().isSummaryField().excludeFromUpdate(),
     /**
@@ -187,26 +339,28 @@ export const OrganizationProviderCredentialSchema = z.object({
     secretSetAt: z.date().optional().excludeFromCreate().excludeFromUpdate(),
     /** Free-text operator note. Never a place for the value; enforced by the write-path pins. */
     /**
-     * Answers for the `{placeholder}` holes this provider's OAuth2 endpoints carry — which cloud,
-     * which directory, which region.
+     * Every fact about the connected ACCOUNT, each value carrying how it got here — see
+     * {@link ProviderConnectionFactProvenance} (#333, #1047).
      *
-     * On the ROW rather than only in the connect flow, because a REFRESH needs them again. The
-     * authorization record that held them lives ten minutes; the token it produced is renewed for as
-     * long as the connection lasts, and a templated token URL is still templated an hour later.
-     * Without them here, every one of the 21 vendors whose endpoints carry a placeholder — Microsoft,
-     * Azure, and everything regional — would connect successfully and then fail its first renewal with
-     * `needs a value for 'cloud'`: the exact failure the placeholder machinery exists to prevent, one
-     * layer up.
+     * ONE record for two sources, by decision: the answers a person typed for the endpoints'
+     * `{placeholder}` holes (which cloud, which directory, which region) — or, for a PASTED credential, for
+     * the REST base URL's holes at the typed-credential store (#1097) — and the facts the vendor
+     * reported in its token answer that operations consume (Salesforce's `instance_url`, Pipedrive's
+     * `api_domain`). Two records would let an operation read one and a refresh update the other.
      *
-     * NOT secret, and deliberately client-readable: a tenant id is an identifier a person needs to see
-     * to recognise which account they connected. The secret half is the grant, and it is sealed.
+     * On the ROW rather than only in the connect flow, because a REFRESH needs the answers again — a
+     * templated token URL is still templated an hour later — and every CALL needs a reported origin.
      *
-     * `.excludeFromUpdate()` — chosen at connect time, and they describe the ACCOUNT the grant is for.
-     * Changing them under a live grant would point the refresh at a different directory than the one
-     * that issued the token, failing at the vendor with nothing local explaining why. Reconnecting is
-     * the honest way to change them.
+     * NOT secret, and deliberately client-readable: a tenant id or an instance URL is how a person
+     * recognises which account they connected. The secret half is the grant, and it is sealed.
+     *
+     * `.excludeFromCreate().excludeFromUpdate()` — no CLIENT write may carry it, create included: the field holds
+     * a provenance the resolver trusts, and a pasted-credential create that could type `REPORTED_BY_VENDOR` would
+     * forge the one mark that decides where a request is sent (review F1). Answers change only by reconnecting, which REPLACES
+     * the record with the grant; vendor-reported facts are also rewritten by a refresh that reports them
+     * again. Both are server writes, allow-listed through `preserveServerInjectedFields`.
      */
-    connectionParameters: z.record(z.string(), z.string()).optional().excludeFromUpdate(),
+    connectionFacts: z.record(z.string(), ProviderConnectionFactSchema).optional().excludeFromCreate().excludeFromUpdate(),
     description: z.string().max(500).optional(),
     createdAt: z.date().default(() => new Date()).isDBIndexed().isSummaryField().excludeFromCreate().excludeFromUpdate(),
     updatedAt: z.date().default(() => new Date()).isDBIndexed().excludeFromCreate().excludeFromUpdate(),
@@ -278,9 +432,9 @@ export const UserProviderCredentialSchema = z.object({
     userId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate(),
     /** As the organization-owned sibling: an OPEN string, because the provider set is not closed. */
     providerRef: z.string().min(1).max(200).isDBIndexed().isSummaryField().excludeFromUpdate(),
-    /** The slug in the provider's `secretsContract` this value satisfies. Immutable, for the same
-     * reason as the sibling: re-pointing a stored secret at a different slug would hand one vendor
-     * credential to a different vendor field. */
+    /** The provider's `secretsContract` KEY this value satisfies — never the env-var spelling, as the
+     * sibling explains (#624). Immutable, for the same reason as the sibling: re-pointing a stored secret
+     * at a different slug would hand one vendor credential to a different vendor field. */
     secretSlug: z.string().min(1).max(200).isDBIndexed().isSummaryField().excludeFromUpdate(),
     /**
      * The credential, SEALED — an AES-256-GCM envelope bound to this row's identity, never plaintext.
@@ -305,26 +459,28 @@ export const UserProviderCredentialSchema = z.object({
     secretSetAt: z.date().optional().excludeFromCreate().excludeFromUpdate(),
     /** The holder's own note. Never a place for the value; enforced by the write-path pins. */
     /**
-     * Answers for the `{placeholder}` holes this provider's OAuth2 endpoints carry — which cloud,
-     * which directory, which region.
+     * Every fact about the connected ACCOUNT, each value carrying how it got here — see
+     * {@link ProviderConnectionFactProvenance} (#333, #1047).
+     *
+     * ONE record for two sources, by decision: the answers a person typed for the endpoints'
+     * `{placeholder}` holes (which cloud, which directory, which region) — or, for a PASTED credential, for
+     * the REST base URL's holes at the typed-credential store (#1097) — and the facts the vendor
+     * reported in its token answer that operations consume (Salesforce's `instance_url`, Pipedrive's
+     * `api_domain`). Two records would let an operation read one and a refresh update the other.
      *
-     * On the ROW rather than only in the connect flow, because a REFRESH needs them again. The
-     * authorization record that held them lives ten minutes; the token it produced is renewed for as
-     * long as the connection lasts, and a templated token URL is still templated an hour later.
-     * Without them here, every one of the 21 vendors whose endpoints carry a placeholder — Microsoft,
-     * Azure, and everything regional — would connect successfully and then fail its first renewal with
-     * `needs a value for 'cloud'`: the exact failure the placeholder machinery exists to prevent, one
-     * layer up.
+     * On the ROW rather than only in the connect flow, because a REFRESH needs the answers again — a
+     * templated token URL is still templated an hour later — and every CALL needs a reported origin.
      *
-     * NOT secret, and deliberately client-readable: a tenant id is an identifier a person needs to see
-     * to recognise which account they connected. The secret half is the grant, and it is sealed.
+     * NOT secret, and deliberately client-readable: a tenant id or an instance URL is how a person
+     * recognises which account they connected. The secret half is the grant, and it is sealed.
      *
-     * `.excludeFromUpdate()` — chosen at connect time, and they describe the ACCOUNT the grant is for.
-     * Changing them under a live grant would point the refresh at a different directory than the one
-     * that issued the token, failing at the vendor with nothing local explaining why. Reconnecting is
-     * the honest way to change them.
+     * `.excludeFromCreate().excludeFromUpdate()` — no CLIENT write may carry it, create included: the field holds
+     * a provenance the resolver trusts, and a pasted-credential create that could type `REPORTED_BY_VENDOR` would
+     * forge the one mark that decides where a request is sent (review F1). Answers change only by reconnecting, which REPLACES
+     * the record with the grant; vendor-reported facts are also rewritten by a refresh that reports them
+     * again. Both are server writes, allow-listed through `preserveServerInjectedFields`.
      */
-    connectionParameters: z.record(z.string(), z.string()).optional().excludeFromUpdate(),
+    connectionFacts: z.record(z.string(), ProviderConnectionFactSchema).optional().excludeFromCreate().excludeFromUpdate(),
     description: z.string().max(500).optional(),
     createdAt: z.date().default(() => new Date()).isDBIndexed().isSummaryField().excludeFromCreate().excludeFromUpdate(),
     updatedAt: z.date().default(() => new Date()).isDBIndexed().excludeFromCreate().excludeFromUpdate(),
@@ -413,6 +569,38 @@ export var ProviderConnectabilityBlocker;
      * connectable and the gap is ours.
      */
     ProviderConnectabilityBlocker["APPLICATION_NOT_REGISTERED"] = "application-not-registered";
+    /**
+     * An OAuth2 endpoint's HOST or ORIGIN — or the origin a SCOPE names (`{hostUrl}/.default`, #991) — is a
+     * placeholder the provider declares no allowance for, so no value can ever be admitted there (#623):
+     * the token endpoint receives the application's client secret, and a host is never taken from what
+     * somebody types. Nobody connecting can fix it; the provider needs a recorded host allowance.
+     */
+    ProviderConnectabilityBlocker["ENDPOINT_HOST_NOT_DECLARED"] = "endpoint-host-not-declared";
+    /**
+     * The provider's OAuth2 endpoint definition cannot be resolved safely whatever is supplied — a
+     * malformed template, an unresolved source expression, or an allowance that cannot apply where its
+     * placeholder sits. A provider-definition defect, not a deployment or account gap.
+     */
+    ProviderConnectabilityBlocker["ENDPOINT_DEFINITION_INVALID"] = "endpoint-definition-invalid";
+    /**
+     * The provider's OAuth2 origin is filled from this DEPLOYMENT's configured base URL (a self-hosted
+     * vendor such as Gitea), and that base URL is unset or unusable. An OPERATOR acts.
+     */
+    ProviderConnectabilityBlocker["DEPLOYMENT_BASE_URL_UNUSABLE"] = "deployment-base-url-unusable";
+    /**
+     * An OAuth2 endpoint host is filled from a deployment environment variable dedicated to it (Workday's
+     * `WORKDAY_AUTH_HOST` / `WORKDAY_API_HOST`, #992), and that variable is unset or not a DNS name. An
+     * OPERATOR acts; the variable is named in the catalogue entry's `missingRegistration`.
+     */
+    ProviderConnectabilityBlocker["DEPLOYMENT_CONFIGURED_HOST_UNUSABLE"] = "deployment-configured-host-unusable";
+    /**
+     * The vendor's credential is PASTED and its REST base URL forms its HOST or ORIGIN from a placeholder the
+     * provider declares no allowance for (`https://{subdomain}.vendor.com` with no `baseUrlHostAllowances`
+     * entry), so no answer the typed-credential store could collect is ever admitted and every call would
+     * refuse (#1097). Nobody connecting can fix it; the provider needs a recorded host allowance — the
+     * base-URL twin of `ENDPOINT_HOST_NOT_DECLARED`.
+     */
+    ProviderConnectabilityBlocker["BASE_URL_HOST_NOT_DECLARED"] = "base-url-host-not-declared";
 })(ProviderConnectabilityBlocker || (ProviderConnectabilityBlocker = {}));
 export var ProviderStoredCredentialKind;
 (function (ProviderStoredCredentialKind) {

package/dist/esm/security/connected-accounts/provider-credentials.shared.schemas.js.map

@@ -1 +1 @@
-{"version":3,"file":"provider-credentials.shared.schemas.js","sourceRoot":"","sources":["../../../../src/security/connected-accounts/provider-credentials.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Organization Provider Credentials — shared schemas.\n *\n * ## What this resource is, and what it is NOT\n *\n * It is an ORGANIZATION's OWN credential toward a third party: the Slack workspace token, the CRM\n * API key, the SMTP password that belongs to THAT tenant. The organization is the third-party\n * principal, and the credential is a service credential the tenant's administrator supplies.\n *\n * It is NOT a user's delegated OAuth grant. A delegated grant is a different object with a\n * different lifetime (a refresh loop, a revocation the USER can perform, a consent record) and it\n * lands as `connected accounts` beside this file — see issue #333. Merging the two would give one\n * row two owners and two revocation semantics.\n *\n * ## Why it has to exist\n *\n * Before this resource, every provider secret resolved from `process.env` through the\n * `SecretsContract`, so a credential was per-PROCESS and per-DEPLOYMENT. One application serving\n * many organizations therefore had ONE Slack token for all of them, and the failure was silent in\n * the worst direction: an operator sets one key and every tenant thereafter acts as the SAME\n * third-party principal, with nothing anywhere saying so.\n *\n * ## The value is sealed, and this file is where that is stated\n *\n * `secretValue` holds an AES-256-GCM envelope, never the plaintext an operator typed. The seal is\n * applied on the way in and opened only by the resolver — see\n * `provider-credential-envelope.backend.utils.ts` for the envelope and its key derivation. The\n * schema cannot enforce that (a string is a string), so the write path is what guarantees it and\n * the pins are what keep it guaranteed.\n */\n\nimport { z } from 'zod';\n\n/**\n * Whether the stored credential has been shown to work against the provider.\n *\n * A closed vocabulary rather than a boolean because \"we have never tried\" and \"we tried and it\n * failed\" are different states with different operator actions, and a boolean would merge them\n * into the same falsy answer. `UNVALIDATED` is the honest default: storing a credential proves\n * only that somebody typed one.\n */\nexport enum ProviderCredentialValidationState {\n  /** Stored, never exercised against the provider. The state every credential starts in. */\n  UNVALIDATED = 'unvalidated',\n  /** The provider accepted it on its last use. */\n  VALID = 'valid',\n  /** The provider rejected it on its last use — the operator must rotate it. */\n  INVALID = 'invalid',\n}\n\n/**\n * The organization's credential for one (provider, secret slug) pair.\n *\n * ## The scope identifier is TOP-LEVEL and stays that way\n *\n * `organizationId` is the only `organizationId`-named path in this schema, and nothing nested may\n * ever be named `organizationId` or `userId`. `buildContextualFilter` injects the scope FK by\n * matching that field name at EVERY schema path, so a nested key of the same name adds a phantom\n * exact-subdocument clause and the scoped read silently matches zero rows — a credential that\n * exists and cannot be resolved, which reads exactly like a credential that was never set.\n * `setByUserId` is deliberately spelled so it cannot be caught by that matcher.\n */\n/**\n * WHERE a resolved provider secret came from.\n *\n * The whole point of this slice is that the answer used to be unanswerable: every secret came from\n * `process.env`, so \"which principal did this tenant act as?\" had one answer for every tenant and\n * nothing recorded it. Making the source an explicit, closed value means an audit reader can see a\n * tenant falling back to the shared deployment credential — the exact condition the resource exists\n * to make visible — instead of having to infer it from an absence.\n */\nexport enum ProviderCredentialResolutionSource {\n  /** The organization's own credential row. The tenant acted as itself. */\n  ORGANIZATION_CREDENTIAL = 'organization_credential',\n  /**\n   * The deployment's env-projected `SecretsContract`. Legitimate — a single-tenant deployment, or a\n   * provider the operator intends every tenant to share — but never silent.\n   */\n  DEPLOYMENT_ENVIRONMENT = 'deployment_environment',\n  /**\n   * A PERSON's own credential row. The application acted as that individual.\n   *\n   * This member has no sibling fallback, and that asymmetry is deliberate rather than an omission.\n   * An organization with no credential of its own may legitimately fall through to the deployment's\n   * — an operator can intend every tenant to share one integration. A person cannot: the vendor\n   * attributes the act to whoever's token was spent, so acting for someone under the deployment's\n   * principal would put the wrong name on the record that outlives us. A person who has connected\n   * nothing gets a refusal, not a substitute.\n   */\n  USER_CREDENTIAL = 'user_credential',\n}\n\n/** Why a credential row stopped existing. */\nexport enum ProviderCredentialDeletionReason {\n  /** An administrator of the owning tenant removed it. */\n  ADMINISTRATOR_REVOKED = 'administrator_revoked',\n  /** The owning organization was purged and the composition cascade removed it with the tenant. */\n  ORGANIZATION_PURGED = 'organization_purged',\n  /** The person whose credential it was removed it themselves. */\n  OWNER_REVOKED = 'owner_revoked',\n  /**\n   * The owning user was erased and the composition cascade destroyed it with them.\n   *\n   * Distinct from `ORGANIZATION_PURGED` because this one is EVIDENCE: it is what an operator points\n   * at when asked whether a subject-erasure request reached the person's third-party credentials.\n   * Collapsing the two into a generic \"cascade\" would make that question unanswerable from the trail.\n   */\n  USER_ERASED = 'user_erased',\n}\n\n/**\n * The fields that IDENTIFY a credential within its tenant.\n *\n * One tenant holds at most one credential per (provider, slug). Exported rather than repeated so\n * the uniqueness contract, the resolver's lookup and the tests cannot drift apart — three copies\n * of a compound key is how two of them come to disagree about what identity means.\n */\nexport const ORGANIZATION_PROVIDER_CREDENTIAL_IDENTITY_FIELDS = [\n  'organizationId',\n  'providerRef',\n  'secretSlug',\n] as const;\n\nexport const OrganizationProviderCredentialSchema = z.object({\n  _id: z.string().min(1).isPrimaryKey().isSummaryField(),\n\n  /**\n   * The tenant that owns this credential. Injected by the context machinery from the request\n   * scope, never from a caller-supplied field — which is what makes the isolation structural\n   * rather than a filter somebody has to remember to write.\n   */\n  organizationId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate(),\n\n  /**\n   * The provider this credential authenticates toward (`slack`, `stripe`, a generated package's\n   * ref). An OPEN string, matching `ProviderRef`'s own openness — the whole point of the provider\n   * work is that the set is not closed, so a closed enum here would refuse every generated\n   * provider.\n   */\n  providerRef: z.string().min(1).max(200).isDBIndexed().isSummaryField().excludeFromUpdate(),\n\n  /**\n   * The slug in the provider's `secretsContract` that this value satisfies — the same identifier\n   * the deployment's env projection carries, so the two resolution places name the same thing.\n   * Immutable: re-pointing a stored secret at a different slug would silently hand one vendor\n   * credential to a different vendor field.\n   */\n  secretSlug: z.string().min(1).max(200).isDBIndexed().isSummaryField().excludeFromUpdate(),\n\n  /**\n   * The credential, SEALED.\n   *\n   * `.isWriteOnlySecret()` is the framework's write-then-masked contract and is exactly right\n   * here: the operator supplies and rotates the value, so it must stay in the CREATE/UPDATE\n   * request DTO; the framework redacts it to a placeholder at the client boundary, so no read\n   * ever returns it; and the backend keeps the stored content for its own resolution.\n   *\n   * `.isBackendOnly()` was rejected — it strips the field from the client DTO, so the operator's\n   * typed value is dropped before it is ever stored and the surface silently accepts nothing.\n   *\n   * What is PERSISTED is the envelope, never the plaintext. The write path seals it; a value that\n   * reaches persistence unsealed is a defect, not a tolerated legacy shape.\n   */\n  secretValue: z.string().min(1).isWriteOnlySecret(),\n\n  /**\n   * Whether this credential may be spent. An operator can park a credential without deleting it —\n   * which matters during an incident, where deleting is not reversible and disabling is.\n   */\n  enabled: z.boolean().default(true).isDBIndexed().isSummaryField(),\n\n  validationState: z\n    .enum(ProviderCredentialValidationState)\n    .default(ProviderCredentialValidationState.UNVALIDATED)\n    .isDBIndexed()\n    .isSummaryField(),\n\n  /**\n   * Why the last use failed, when it did. PROVIDER-supplied text about the CREDENTIAL's status —\n   * never the credential. A resolver writing anything derived from `secretValue` here would defeat\n   * every other precaution in this file, because this field IS client-readable.\n   */\n  validationError: z.string().max(500).optional().excludeFromCreate().excludeFromUpdate(),\n\n  lastValidatedAt: z.date().optional().excludeFromCreate().excludeFromUpdate(),\n  lastUsedAt: z.date().optional().isDBIndexed().excludeFromCreate().excludeFromUpdate(),\n\n  /**\n   * WHO set it — the acting user's id, recorded for the audit trail.\n   *\n   * Deliberately NOT a registered `USERS` relationship. Declaring that edge would put a CREDENTIAL\n   * row on the Art. 15 subject-export graph, and a credential is precisely the class of row that\n   * must never reach a data subject. The id is recorded because \"who set this\" is the first\n   * question of any credential incident; the edge is withheld because the answer must not travel\n   * with a subject export.\n   */\n  setByUserId: z.string().min(1).optional().isDBIndexed().excludeFromCreate().excludeFromUpdate(),\n\n  /** When the stored VALUE last changed — distinct from `updatedAt`, which any field write moves. */\n  secretSetAt: z.date().optional().excludeFromCreate().excludeFromUpdate(),\n\n  /** Free-text operator note. Never a place for the value; enforced by the write-path pins. */\n  /**\n   * Answers for the `{placeholder}` holes this provider's OAuth2 endpoints carry — which cloud,\n   * which directory, which region.\n   *\n   * On the ROW rather than only in the connect flow, because a REFRESH needs them again. The\n   * authorization record that held them lives ten minutes; the token it produced is renewed for as\n   * long as the connection lasts, and a templated token URL is still templated an hour later.\n   * Without them here, every one of the 21 vendors whose endpoints carry a placeholder — Microsoft,\n   * Azure, and everything regional — would connect successfully and then fail its first renewal with\n   * `needs a value for 'cloud'`: the exact failure the placeholder machinery exists to prevent, one\n   * layer up.\n   *\n   * NOT secret, and deliberately client-readable: a tenant id is an identifier a person needs to see\n   * to recognise which account they connected. The secret half is the grant, and it is sealed.\n   *\n   * `.excludeFromUpdate()` — chosen at connect time, and they describe the ACCOUNT the grant is for.\n   * Changing them under a live grant would point the refresh at a different directory than the one\n   * that issued the token, failing at the vendor with nothing local explaining why. Reconnecting is\n   * the honest way to change them.\n   */\n  connectionParameters: z.record(z.string(), z.string()).optional().excludeFromUpdate(),\n\n\n  description: z.string().max(500).optional(),\n\n  createdAt: z.date().default(() => new Date()).isDBIndexed().isSummaryField().excludeFromCreate().excludeFromUpdate(),\n  updatedAt: z.date().default(() => new Date()).isDBIndexed().excludeFromCreate().excludeFromUpdate(),\n})\n  /**\n   * One credential per tenant per (provider, slug), enforced by a compound UNIQUE index rather\n   * than by a read-then-write.\n   *\n   * The race it closes is not academic: two administrators saving a rotated Slack token in the\n   * same minute would otherwise leave two rows, and the resolver would then pick one of them\n   * arbitrarily — so half the tenant's outbound calls would carry the old credential and nobody\n   * could tell which half.\n   *\n   * No `customMessageReference`: that option exists so an integrator can tell WHICH identity a\n   * duplicate violated, and this resource declares exactly one. A dedicated reference here would\n   * disambiguate nothing.\n   */\n  .businessKeySet([...ORGANIZATION_PROVIDER_CREDENTIAL_IDENTITY_FIELDS]);\n\nexport type OrganizationProviderCredential = z.infer<typeof OrganizationProviderCredentialSchema>;\n\n\n\n// =============================================================================\n// USER-OWNED CREDENTIALS\n// =============================================================================\n\n/**\n * The fields that IDENTIFY a credential within its OWNER.\n *\n * Exported per owner rather than shared, because the compound key differs in its first component and\n * a single constant would have to be assembled by each side — which is how two copies of a key come\n * to disagree about what identity means.\n */\nexport const USER_PROVIDER_CREDENTIAL_IDENTITY_FIELDS = [\n  'userId',\n  'providerRef',\n  'secretSlug',\n] as const;\n\n/**\n * A PERSON's own credential toward a third party — the key they authored for themselves.\n *\n * ## Why this is a separate resource and not a nullable column beside the organization's\n *\n * Wildo's tenancy is STRUCTURAL: the contextual filter injects the scope FK by matching a field name\n * at every schema path, so a resource belongs to exactly one primary scope. One table holding both a\n * nullable `organizationId` and a nullable `userId` would turn that structural guarantee into a\n * filter somebody has to remember to write, on the one resource where forgetting it discloses a\n * credential. Two resources, each scoped by construction, is the framework working as designed\n * rather than a duplication.\n *\n * ## Not a delegated OAuth grant, and the difference is not subtle\n *\n * This is a key the user PASTED: they hold an account with the vendor and chose to let this\n * application spend it. A delegated grant is the vendor minting a token because the user approved a\n * consent screen, and it carries a refresh loop, an expiry and a revocation the vendor also honours.\n * Merging them would give one row two lifecycles and two revocation semantics — see #333, which owns\n * the second.\n *\n * ## Only the holder may spend it\n *\n * Not an administrator of their organization, and not a platform operator. Consent to STORE a\n * personal key is not consent for somebody else to use it, and the vendor would record the act as\n * the holder's own. The authorization side of that is\n * `InitiatorMembershipConnectionTargetAuthorization`; this schema is what makes the row reachable\n * only through the owner's own scope.\n */\nexport const UserProviderCredentialSchema = z.object({\n  _id: z.string().min(1).isPrimaryKey().isSummaryField(),\n\n  /**\n   * The person who owns this credential. Injected by the context machinery from the authenticated\n   * scope, never from a caller-supplied field — the same structural isolation the organization-owned\n   * sibling relies on, which is what makes \"another user's key\" unreachable rather than filtered.\n   */\n  userId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate(),\n\n  /** As the organization-owned sibling: an OPEN string, because the provider set is not closed. */\n  providerRef: z.string().min(1).max(200).isDBIndexed().isSummaryField().excludeFromUpdate(),\n\n  /** The slug in the provider's `secretsContract` this value satisfies. Immutable, for the same\n   * reason as the sibling: re-pointing a stored secret at a different slug would hand one vendor\n   * credential to a different vendor field. */\n  secretSlug: z.string().min(1).max(200).isDBIndexed().isSummaryField().excludeFromUpdate(),\n\n  /**\n   * The credential, SEALED — an AES-256-GCM envelope bound to this row's identity, never plaintext.\n   *\n   * `.isWriteOnlySecret()` for the same reason as the sibling: the holder supplies and rotates it, so\n   * it must survive into the CREATE/UPDATE request DTO, and the framework masks it at the client\n   * boundary so no read ever returns it.\n   */\n  secretValue: z.string().min(1).isWriteOnlySecret(),\n\n  enabled: z.boolean().default(true).isDBIndexed().isSummaryField(),\n\n  validationState: z\n    .enum(ProviderCredentialValidationState)\n    .default(ProviderCredentialValidationState.UNVALIDATED)\n    .isDBIndexed()\n    .isSummaryField(),\n\n  /** Why the last use failed. PROVIDER text about the CREDENTIAL, never anything derived from it —\n   * this field IS client-readable. */\n  validationError: z.string().max(500).optional().excludeFromCreate().excludeFromUpdate(),\n\n  lastValidatedAt: z.date().optional().excludeFromCreate().excludeFromUpdate(),\n  lastUsedAt: z.date().optional().isDBIndexed().excludeFromCreate().excludeFromUpdate(),\n\n  /** When the stored VALUE last changed — distinct from `updatedAt`, which any field write moves. */\n  secretSetAt: z.date().optional().excludeFromCreate().excludeFromUpdate(),\n\n  /** The holder's own note. Never a place for the value; enforced by the write-path pins. */\n  /**\n   * Answers for the `{placeholder}` holes this provider's OAuth2 endpoints carry — which cloud,\n   * which directory, which region.\n   *\n   * On the ROW rather than only in the connect flow, because a REFRESH needs them again. The\n   * authorization record that held them lives ten minutes; the token it produced is renewed for as\n   * long as the connection lasts, and a templated token URL is still templated an hour later.\n   * Without them here, every one of the 21 vendors whose endpoints carry a placeholder — Microsoft,\n   * Azure, and everything regional — would connect successfully and then fail its first renewal with\n   * `needs a value for 'cloud'`: the exact failure the placeholder machinery exists to prevent, one\n   * layer up.\n   *\n   * NOT secret, and deliberately client-readable: a tenant id is an identifier a person needs to see\n   * to recognise which account they connected. The secret half is the grant, and it is sealed.\n   *\n   * `.excludeFromUpdate()` — chosen at connect time, and they describe the ACCOUNT the grant is for.\n   * Changing them under a live grant would point the refresh at a different directory than the one\n   * that issued the token, failing at the vendor with nothing local explaining why. Reconnecting is\n   * the honest way to change them.\n   */\n  connectionParameters: z.record(z.string(), z.string()).optional().excludeFromUpdate(),\n\n\n  description: z.string().max(500).optional(),\n\n  createdAt: z.date().default(() => new Date()).isDBIndexed().isSummaryField().excludeFromCreate().excludeFromUpdate(),\n  updatedAt: z.date().default(() => new Date()).isDBIndexed().excludeFromCreate().excludeFromUpdate(),\n})\n  /**\n   * One credential per person per (provider, slug), enforced by a compound UNIQUE index rather than\n   * a read-then-write — the same race the organization-owned sibling closes, and for the same\n   * reason: two rows would leave the resolver picking one arbitrarily, so half the holder's outbound\n   * calls would carry a rotated-away credential and nothing would say which half.\n   */\n  .businessKeySet([...USER_PROVIDER_CREDENTIAL_IDENTITY_FIELDS]);\n\nexport type UserProviderCredential = z.infer<typeof UserProviderCredentialSchema>;\n\n\n// ══════════════════════════════════════════════════════════════════════════════════════════════\n// OAUTH2 GRANTS\n//\n// A credential a vendor MINTS rather than one a person pastes. It rides in the same `secretValue`\n// field of the same two resources — sealed, as JSON — and that reuse is deliberate.\n//\n// ## Why the same rows rather than a third resource\n//\n// The identity is the same triple (owner, providerRef, secretSlug), the ownership semantics are the\n// same, the authorization is the same, the erasure is the same, and the resolver already routes by\n// scope. Only the PAYLOAD differs. A separate resource would duplicate every one of those and force\n// each consumer to ask \"which store?\" before it could ask anything useful.\n//\n// Note this is the OPPOSITE call from the one that split USER from ORGANIZATION, and the difference\n// is what makes both right: there the TENANCY differed, and tenancy in this framework is structural\n// — one table with a nullable owner would turn a structural guarantee into a filter somebody must\n// remember to write. Here nothing about ownership changes; a string becomes an object.\n// ══════════════════════════════════════════════════════════════════════════════════════════════\n\n/**\n * What an authorization exchange gives back, as it is stored.\n *\n * Sealed as JSON into `secretValue`, so `.isWriteOnlySecret()` keeps masking it at the client\n * boundary and the envelope keeps binding it to its row — both mechanisms work on a string and\n * neither needs to know the string is structured.\n */\n/**\n * What SHAPE a sealed credential holds, once opened.\n *\n * One member today and a named vocabulary anyway, because the day a second sealed payload exists —\n * a service-account key, a signed JWT assertion — the discriminant is what tells them apart, and a\n * bare literal is where per-member explanation cannot live. It is also the value a reader needs to\n * understand `PROVIDER_OAUTH2_GRANT_PREFIX`: the prefix is how the shape is recognised WITHOUT\n * parsing, and this is what it recognises.\n */\n/**\n * Why a provider cannot be connected HERE, even though the vendor is in the catalogue.\n *\n * \"Connectable\" is a property of the DEPLOYMENT and not of the vendor, and conflating the two put a\n * Connect button on a screen that could only ever fail. Asana supports OAuth2 perfectly well; this\n * application has simply never registered with Asana, and no amount of pressing the button changes\n * that.\n *\n * The two members lead to different actions by different people, which is the whole reason they are\n * distinguished rather than collapsed into a boolean.\n */\n/**\n * HOW a connection to a provider is established — the shape of the act, which decides the screen.\n *\n * A connect surface cannot be one form. Granting consent at a vendor and typing a key are different\n * acts with different inputs and different failure modes, and a screen that offered one button for\n * both would be wrong for whichever it was not built around.\n */\nexport enum ProviderAuthMethod {\n  /** The authorization-code round trip: leave, consent at the vendor, come back with a grant. */\n  OAUTH2_AUTHORIZATION_CODE = 'oauth2-authorization-code',\n  /**\n   * A value somebody holds and types — an API key, a personal access token. The fields are DECLARED\n   * by the provider's secrets contract, so a screen names them rather than asking for a slug.\n   */\n  DECLARED_SECRET = 'declared-secret',\n}\n\nexport enum ProviderConnectabilityBlocker {\n  /**\n   * The vendor has no authorization flow in the catalogue: its credential is PASTED, not granted.\n   * Nothing is missing and nothing is broken — this provider is authored on the credential screen\n   * instead, and an application author is the one who acts.\n   */\n  NO_AUTHORIZATION_FLOW = 'no-authorization-flow',\n  /**\n   * The vendor has a flow and THIS DEPLOYMENT has not registered with it — no client id, or no client\n   * secret. An OPERATOR acts: register an application with the vendor and set the two environment\n   * variables the provider's contract names. Distinct from the above because the vendor is perfectly\n   * connectable and the gap is ours.\n   */\n  APPLICATION_NOT_REGISTERED = 'application-not-registered',\n}\n\n/**\n * One secret slot a provider declares, as a SCREEN needs it — never the value.\n *\n * Exists so nothing is typed by hand. The slug names the field, the environment variable tells an\n * operator exactly what to set, and `configured` lets a missing one be REPORTED rather than\n * discovered by pressing a button that fails.\n */\nexport interface ProviderSecretSlotView {\n  readonly slug: string;\n  readonly envVarName: string;\n  readonly required: boolean;\n  readonly description: string;\n  /** Whether the deployment supplies it. There is deliberately no field for the value. */\n  readonly configured: boolean;\n}\n\nexport enum ProviderStoredCredentialKind {\n  /** An OAuth2 grant: an access token, and what is needed to renew it. */\n  OAUTH2_GRANT = 'oauth2-grant',\n}\n\nexport const ProviderOAuth2GrantSchema = z.object({\n  /**\n   * A discriminant, so an opened envelope announces which shape it is.\n   *\n   * Without it the reader would have to guess from whether the plaintext parses as JSON — and a\n   * pasted credential that happens to be JSON (a service-account key, which several vendors issue\n   * exactly that way) would be misread as a grant. A guess that is right almost always is the worst\n   * kind here, because the failure is a malformed Authorization header on somebody else's account.\n   */\n  kind: z.literal(ProviderStoredCredentialKind.OAUTH2_GRANT),\n\n  /** The token that actually goes on the wire. */\n  accessToken: z.string().min(1),\n\n  /**\n   * Present when the vendor issues one. Absent is normal and permanent for vendors that do not —\n   * Slack's bot tokens do not expire and have no refresh — so its absence must not read as an\n   * incomplete grant.\n   */\n  refreshToken: z.string().min(1).optional(),\n\n  /**\n   * When the access token stops being accepted, as an ISO instant.\n   *\n   * Optional because a non-expiring token genuinely has none. A grant with a refresh token and no\n   * expiry is refreshed only after the vendor rejects it, which is correct but slower than\n   * refreshing ahead of a known deadline.\n   */\n  expiresAt: z.iso.datetime().optional(),\n\n  /**\n   * What the vendor actually GRANTED, which is not always what was asked for.\n   *\n   * Recorded because the difference is invisible until a call fails: a vendor may issue a token for\n   * a subset of the requested scopes, and the resulting `missing_scope` arrives on an unrelated\n   * operation weeks later. Holding the granted set lets that be answered from the row.\n   */\n  grantedScopes: z.array(z.string()).optional(),\n\n  /**\n   * The vendor's own identifier for the account this grant is on — a Slack team id, a Google sub, a\n   * Microsoft tenant id.\n   *\n   * Not used for lookup and deliberately not part of the row's identity. It exists so a person\n   * reading their connections can tell WHICH account they connected, which a provider ref cannot\n   * answer for anyone who has two.\n   */\n  accountRef: z.string().optional(),\n});\n\nexport type ProviderOAuth2Grant = z.infer<typeof ProviderOAuth2GrantSchema>;\n\n/**\n * The marker that opens the sealed plaintext of a grant rather than a pasted credential.\n *\n * A prefix on the JSON rather than a field inside it, so the decision can be made without parsing —\n * the same reason the envelope carries a prefix. Parsing first would mean feeding an arbitrary\n * pasted credential to `JSON.parse` on every resolution.\n */\nexport const PROVIDER_OAUTH2_GRANT_PREFIX = 'wildo-oauth2-grant:';\n\n/** Whether an OPENED credential is a grant. Cheap, and does not parse. */\nexport function isProviderOAuth2GrantPlaintext(plaintext: string): boolean {\n  return plaintext.startsWith(PROVIDER_OAUTH2_GRANT_PREFIX);\n}\n\n/** Render a grant for sealing. The inverse of {@link parseProviderOAuth2Grant}. */\nexport function serializeProviderOAuth2Grant(grant: ProviderOAuth2Grant): string {\n  return `${PROVIDER_OAUTH2_GRANT_PREFIX}${JSON.stringify(grant)}`;\n}\n\n/**\n * Read a grant back, or `undefined` when the plaintext is an ordinary pasted credential.\n *\n * THROWS when the value announces itself as a grant and then does not parse or does not validate.\n * That is the same posture the envelope takes toward a value the write path could not have\n * produced: a credential which claims a shape it does not have is a fault worth failing on, never\n * one worth falling back from — falling back would put a JSON blob on the wire as a bearer token.\n */\nexport function parseProviderOAuth2Grant(plaintext: string): ProviderOAuth2Grant | undefined {\n  if (!isProviderOAuth2GrantPlaintext(plaintext)) return undefined;\n  const body = plaintext.slice(PROVIDER_OAUTH2_GRANT_PREFIX.length);\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(body);\n  } catch {\n    throw new Error(\n      'A stored provider credential announces itself as an OAuth2 grant and is not valid JSON. It was '\n      + 'written by something other than the authorization exchange; reconnect the account.',\n    );\n  }\n  const result = ProviderOAuth2GrantSchema.safeParse(parsed);\n  if (!result.success) {\n    throw new Error(\n      'A stored provider credential announces itself as an OAuth2 grant but does not match the grant '\n      + 'shape. Reconnect the account rather than editing the row — the value on the wire would '\n      + 'otherwise be a fragment of a token.',\n    );\n  }\n  return result.data;\n}\n\n/**\n * Whether a grant should be refreshed BEFORE it is spent.\n *\n * The skew is what makes this useful rather than decorative: a token that expires in two seconds is\n * still \"valid\" and will have expired by the time the request reaches the vendor, so refreshing only\n * on expiry guarantees a population of calls that fail for a reason nothing recorded. Sixty seconds\n * is the industry's common floor and comfortably exceeds any plausible clock skew plus flight time.\n *\n * Returns false when there is no expiry — a non-expiring token is refreshed reactively, after the\n * vendor rejects it, because there is no deadline to act ahead of.\n */\nexport const PROVIDER_OAUTH2_REFRESH_SKEW_SECONDS = 60;\n\nexport function providerOAuth2GrantNeedsRefresh(grant: ProviderOAuth2Grant, now: Date = new Date()): boolean {\n  if (grant.expiresAt === undefined) return false;\n  const expiry = Date.parse(grant.expiresAt);\n  if (Number.isNaN(expiry)) return true;\n  return expiry - now.getTime() <= PROVIDER_OAUTH2_REFRESH_SKEW_SECONDS * 1000;\n}\n"]}
+{"version":3,"file":"provider-credentials.shared.schemas.js","sourceRoot":"","sources":["../../../../../src/security/connected-accounts/provider-credentials.shared.schemas.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Organization Provider Credentials — shared schemas.\n *\n * ## What this resource is, and what it is NOT\n *\n * It is an ORGANIZATION's OWN credential toward a third party: the Slack workspace token, the CRM\n * API key, the SMTP password that belongs to THAT tenant. The organization is the third-party\n * principal, and the credential is a service credential the tenant's administrator supplies.\n *\n * It is NOT a user's delegated OAuth grant. A delegated grant is a different object with a\n * different lifetime (a refresh loop, a revocation the USER can perform, a consent record) and it\n * lands as `connected accounts` beside this file — see issue #333. Merging the two would give one\n * row two owners and two revocation semantics.\n *\n * ## Why it has to exist\n *\n * Before this resource, every provider secret resolved from `process.env` through the\n * `SecretsContract`, so a credential was per-PROCESS and per-DEPLOYMENT. One application serving\n * many organizations therefore had ONE Slack token for all of them, and the failure was silent in\n * the worst direction: an operator sets one key and every tenant thereafter acts as the SAME\n * third-party principal, with nothing anywhere saying so.\n *\n * ## The value is sealed, and this file is where that is stated\n *\n * `secretValue` holds an AES-256-GCM envelope, never the plaintext an operator typed. The seal is\n * applied on the way in and opened only by the resolver — see\n * `provider-credential-envelope.backend.utils.ts` for its key domains and binding, over the shared\n * `bound-secret-envelope` core that does the sealing (#366). The\n * schema cannot enforce that (a string is a string), so the write path is what guarantees it and\n * the pins are what keep it guaranteed.\n */\n\nimport { z } from 'zod';\n\n/**\n * Whether the stored credential has been shown to work against the provider.\n *\n * A closed vocabulary rather than a boolean because \"we have never tried\" and \"we tried and it\n * failed\" are different states with different operator actions, and a boolean would merge them\n * into the same falsy answer. `UNVALIDATED` is the honest default: storing a credential proves\n * only that somebody typed one.\n */\nexport enum ProviderCredentialValidationState {\n  /** Stored, never exercised against the provider. The state every credential starts in. */\n  UNVALIDATED = 'unvalidated',\n  /** The provider accepted it on its last use. */\n  VALID = 'valid',\n  /** The provider rejected it on its last use — the operator must rotate it. */\n  INVALID = 'invalid',\n}\n\n/**\n * Why a write door refused to store a credential VALUE under the slot it named — the stable,\n * client-branchable `code` every door carries (#624).\n *\n * A stored row is keyed `(owner, providerRef, secretSlug)` on the provider's secrets-contract KEY, and\n * every reader asks for that key. A value written under any other name is a secret nothing can ever\n * read, and before these refusals the write reported success — which is how a regenerated provider,\n * a free-text slug or a test script produced rows that looked connected and resolved as absent.\n *\n * The member values are the wire codes the connect leg already answered with, so one vocabulary\n * serves the connect leg, the resource's own CREATE / UPDATE doors and any client that branches.\n */\nexport enum ProviderCredentialSlotWriteRefusal {\n  /**\n   * The provider's current secrets contract declares no slot by that name — under either of a slot's\n   * two names. Also the answer for a provider that is not registered at all, and for ROTATING a value\n   * into an existing row whose stored name is not a contract KEY — a retired name, or a spelling no\n   * reader asks for: a fresh secret sealed there is as unreadable as the old one.\n   */\n  SECRET_SLUG_NOT_DECLARED = 'SECRET_SLUG_NOT_DECLARED',\n  /**\n   * The slot exists but holds the APPLICATION's own registration (an OAuth2 client id or secret),\n   * which is authored in the deployment environment and never read from a credential row.\n   */\n  SECRET_SLUG_NOT_A_CREDENTIAL = 'SECRET_SLUG_NOT_A_CREDENTIAL',\n  /**\n   * An UPDATE named a different `providerRef` or `secretSlug` for an existing row. The sealed value is\n   * bound to both, so a row cannot move: a credential for another slot is a new row, and the old one is\n   * deleted.\n   */\n  CREDENTIAL_SLOT_IMMUTABLE = 'CREDENTIAL_SLOT_IMMUTABLE',\n}\n\n/**\n * How one connection fact got onto a credential row (#333, #1047). The distinction is what decides who may\n * change it: an answer changes only when the person reconnects, a vendor report whenever the vendor\n * reports it again.\n */\nexport enum ProviderConnectionFactProvenance {\n  /**\n   * Typed by the person connecting, for an endpoint or scope `{placeholder}` at the OAuth2 start — or, for a\n   * vendor whose credential is PASTED, for a `{placeholder}` of the REST base URL at the typed-credential store\n   * (#1097). Replaced only by reconnecting or re-entering the credential.\n   */\n  ANSWERED_AT_CONNECT = 'ANSWERED_AT_CONNECT',\n  /** Reported by the vendor in its token answer, at the authorization or at a refresh. A refresh may move it. */\n  REPORTED_BY_VENDOR = 'REPORTED_BY_VENDOR',\n}\n\n/** One value in a credential row's `connectionFacts`. */\nexport const ProviderConnectionFactSchema = z.strictObject({\n  value: z.string(),\n  provenance: z.enum(ProviderConnectionFactProvenance),\n});\n\nexport type ProviderConnectionFact = z.infer<typeof ProviderConnectionFactSchema>;\n\n/** A credential row's facts, keyed by fact name. */\nexport type ProviderConnectionFacts = Readonly<Record<string, ProviderConnectionFact>>;\n\n/**\n * WHERE a resolved provider secret came from.\n *\n * The whole point of this slice is that the answer used to be unanswerable: every secret came from\n * `process.env`, so \"which principal did this tenant act as?\" had one answer for every tenant and\n * nothing recorded it. Making the source an explicit, closed value means an audit reader can see a\n * tenant falling back to the shared deployment credential — the exact condition the resource exists\n * to make visible — instead of having to infer it from an absence.\n */\nexport enum ProviderCredentialResolutionSource {\n  /** The organization's own credential row. The tenant acted as itself. */\n  ORGANIZATION_CREDENTIAL = 'organization_credential',\n  /**\n   * The deployment's env-projected `SecretsContract`. Legitimate — a single-tenant deployment, or a\n   * provider the operator intends every tenant to share — but never silent.\n   */\n  DEPLOYMENT_ENVIRONMENT = 'deployment_environment',\n  /**\n   * A PERSON's own credential row. The application acted as that individual.\n   *\n   * This member has no sibling fallback, and that asymmetry is deliberate rather than an omission.\n   * An organization with no credential of its own may legitimately fall through to the deployment's\n   * — an operator can intend every tenant to share one integration. A person cannot: the vendor\n   * attributes the act to whoever's token was spent, so acting for someone under the deployment's\n   * principal would put the wrong name on the record that outlives us. A person who has connected\n   * nothing gets a refusal, not a substitute.\n   */\n  USER_CREDENTIAL = 'user_credential',\n}\n\n/**\n * What telling the VENDOR achieved when a credential was removed (#545).\n *\n * A separate axis from {@link ProviderCredentialDeletionReason} on purpose: that one says why OUR\n * COPY stopped existing, this one says whether the authorization itself was withdrawn where it\n * lives. They were one question for as long as the answer was always \"it was not\".\n *\n * Every member is EVIDENCE, and none of them is control flow — the local delete proceeds whatever\n * this says, because a vendor being unreachable must not stop somebody disconnecting.\n */\nexport enum ProviderOAuth2RevocationOutcome {\n  /**\n   * The vendor answered 200.\n   *\n   * Under RFC 7009 that also covers a token the server did not recognise, which is the intended\n   * reading: the grant is gone either way.\n   * spec-cite: RFC 7009 §2.2 — *\"The authorization server responds with HTTP status code 200 if the\n   * token has been revoked successfully or if the client submitted an invalid token\"*.\n   */\n  REVOKED = 'revoked',\n  /**\n   * Nothing was sent, and that is the ordinary case rather than a failure.\n   *\n   * Three situations share this member because they are one fact from the person's side — the vendor\n   * was not told: the provider declares no `rfc7009RevocationUrl`; the credential was a PASTED\n   * long-lived key rather than a grant, so there is nothing to revoke; or the grant carried no token.\n   */\n  NOT_DECLARED = 'not_declared',\n  /** The application's own client registration for this vendor is unset, so nothing could be sent. */\n  NOT_CONFIGURED = 'not_configured',\n  /** The endpoint could not be reached, or did not answer within the deadline. */\n  UNREACHABLE = 'unreachable',\n  /** The endpoint answered, and not with 200. */\n  REFUSED = 'refused',\n}\n\n/** The wire values of {@link ProviderOAuth2RevocationOutcome}, for a Zod enum over them. */\nexport const ProviderOAuth2RevocationOutcomeValues = ProviderOAuth2RevocationOutcome;\n\n/**\n * Why a credential row stopped existing.\n *\n * ## Every member describes OUR COPY; whether the VENDOR was told is a SECOND axis (#545)\n *\n * Removing a credential deletes the token Wildo holds. Until 2026-09-18 it also did nothing else,\n * so the GRANT survived at the vendor: the person's connected-accounts screen showed the application\n * gone while Asana or Google still listed it as authorized, and a stored refresh token remained\n * valid until it expired on the vendor's schedule — which, for a refresh token, is frequently never.\n *\n * That is stated HERE because this vocabulary is what an operator points at when asked whether an\n * erasure reached someone's third-party credentials, and silence on a compliance surface reads as\n * \"done\".\n *\n * **It is no longer silent.** Both deletion events now carry\n * {@link ProviderOAuth2RevocationOutcome}, so the trail answers the vendor question separately from\n * the local one. What that outcome can SAY still depends on the vendor: RFC 7009 is the only\n * revocation standard and the vendors do not agree with it, so `google-drive` and `asana` declare an\n * endpoint and are told, while Slack's `auth.revoke` (a Web API method) and GitHub's\n * `DELETE /applications/{client_id}/token` (basic auth, JSON body) are not expressible as one and\n * record `not_declared` rather than implying they were reached.\n *\n * An earlier revision of this block argued the mechanism should NOT be built, because *\"no\n * admissible provider declares one today, so the field would ship inert\"*. That was true when it was\n * written and stopped being true when `google-drive` gained an admissible USER connection: Google's\n * `https://oauth2.googleapis.com/revoke` is RFC 7009-conformant, so the mechanism has a reachable\n * user and a proven vendor. Kept as history rather than deleted, because the reasoning was sound and\n * the thing that changed was the world, not the argument.\n */\nexport enum ProviderCredentialDeletionReason {\n  /** An administrator of the owning tenant removed it. */\n  ADMINISTRATOR_REVOKED = 'administrator_revoked',\n  /** The owning organization was purged and the composition cascade removed it with the tenant. */\n  ORGANIZATION_PURGED = 'organization_purged',\n  /** The person whose credential it was removed it themselves. */\n  OWNER_REVOKED = 'owner_revoked',\n  /**\n   * The owning user was erased and the composition cascade destroyed it with them.\n   *\n   * Distinct from `ORGANIZATION_PURGED` because this one is EVIDENCE: it is what an operator points\n   * at when asked whether a subject-erasure request reached the person's third-party credentials.\n   * Collapsing the two into a generic \"cascade\" would make that question unanswerable from the trail.\n   *\n   * **Who sets it:** the cascade observer, for a cascade declaring itself a `SUBJECT_ERASURE`. The record\n   * carries `deletedBy` = whoever EXECUTED the erasure (a person's id when one was carried on the erasure's\n   * context, else the `SYSTEM` sentinel), so the erased person is the record's SUBJECT and never its actor\n   * (#1088).\n   */\n  USER_ERASED = 'user_erased',\n  /**\n   * The owning user ROW was deleted outright and the composition cascade destroyed the credential with it (#1016).\n   *\n   * **Who sets it:** the user-credential parent-cascade removal observer\n   * (`registerUserProviderCredentialCascadeEvidence`), for a cascade that declares its cause as an ordinary parent\n   * delete of the `users` row. Two doors reach it today: an administrator's hard `DELETE` (`deletedBy` is that\n   * administrator), and the organization-member invitation sweep reaping an orphaned pending user under an internal\n   * context (`deletedBy` is the `SYSTEM` sentinel). The record carries `deletedBy`, resolved from the deleting\n   * execution context, so it names the principal who deleted the account rather than the person whose credential\n   * it was.\n   *\n   * **Distinct from `USER_ERASED`**, and the distinction is the reason this member exists: an erasure answers a\n   * data-subject request, keeps the person's row scrubbed and is evidence that the request reached their third-party\n   * credentials. A deletion asserts no such request. Recording it as `USER_ERASED` would forge erasure evidence;\n   * recording nothing left an account deletion that destroyed OAuth grants and API keys with no row naming them.\n   *\n   * **Distinct from `ORGANIZATION_PURGED`**: that is a tenant teardown removing the ORGANIZATION's credentials. This\n   * removes one PERSON's own credentials, which no organization owns.\n   *\n   * Named for what happened to the owner, not for who did it: the cascade cannot tell an administrator's delete from\n   * any other deletion of the row, and `deletedBy` is where the actor is stated.\n   */\n  USER_DELETED = 'user_deleted',\n}\n\n/**\n * The fields that IDENTIFY a credential within its tenant.\n *\n * One tenant holds at most one credential per (provider, slug). Exported rather than repeated so\n * the uniqueness contract, the resolver's lookup and the tests cannot drift apart — three copies\n * of a compound key is how two of them come to disagree about what identity means.\n */\nexport const ORGANIZATION_PROVIDER_CREDENTIAL_IDENTITY_FIELDS = [\n  'organizationId',\n  'providerRef',\n  'secretSlug',\n] as const;\n\n/**\n * The organization's credential for one (provider, secret slug) pair.\n *\n * ## The scope identifier is TOP-LEVEL and stays that way\n *\n * `organizationId` is the only `organizationId`-named path in this schema, and nothing nested may\n * ever be named `organizationId` or `userId`. `buildContextualFilter` injects the scope FK by\n * matching that field name at EVERY schema path, so a nested key of the same name adds a phantom\n * exact-subdocument clause and the scoped read silently matches zero rows — a credential that\n * exists and cannot be resolved, which reads exactly like a credential that was never set.\n * `setByUserId` is deliberately spelled so it cannot be caught by that matcher.\n */\nexport const OrganizationProviderCredentialSchema = z.object({\n  _id: z.string().min(1).isPrimaryKey().isSummaryField(),\n\n  /**\n   * The tenant that owns this credential. Injected by the context machinery from the request\n   * scope, never from a caller-supplied field — which is what makes the isolation structural\n   * rather than a filter somebody has to remember to write.\n   */\n  organizationId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate(),\n\n  /**\n   * The provider this credential authenticates toward (`slack`, `stripe`, a generated package's\n   * ref). An OPEN string, matching `ProviderRef`'s own openness — the whole point of the provider\n   * work is that the set is not closed, so a closed enum here would refuse every generated\n   * provider.\n   */\n  providerRef: z.string().min(1).max(200).isDBIndexed().isSummaryField().excludeFromUpdate(),\n\n  /**\n   * The provider's `secretsContract` KEY this value satisfies (`accessToken`, `clientSecret`) —\n   * NOT the slot's env-var spelling (`ASANA_ACCESS_TOKEN`), which is what the deployment's env\n   * projection carries and what a provider regeneration may rename. The two resolution places name\n   * the same SLOT by different names, and only the key is stable enough to key a durable row on\n   * (#624). Immutable: re-pointing a stored secret at a different slug would silently hand one vendor\n   * credential to a different vendor field — and the sealed value binds the slug, so a row stored\n   * under a name the provider no longer declares cannot be renamed, only replaced by reconnecting.\n   */\n  secretSlug: z.string().min(1).max(200).isDBIndexed().isSummaryField().excludeFromUpdate(),\n\n  /**\n   * The credential, SEALED.\n   *\n   * `.isWriteOnlySecret()` is the framework's write-then-masked contract and is exactly right\n   * here: the operator supplies and rotates the value, so it must stay in the CREATE/UPDATE\n   * request DTO; the framework redacts it to a placeholder at the client boundary, so no read\n   * ever returns it; and the backend keeps the stored content for its own resolution.\n   *\n   * `.isBackendOnly()` was rejected — it strips the field from the client DTO, so the operator's\n   * typed value is dropped before it is ever stored and the surface silently accepts nothing.\n   *\n   * What is PERSISTED is the envelope, never the plaintext. The write path seals it; a value that\n   * reaches persistence unsealed is a defect, not a tolerated legacy shape.\n   */\n  secretValue: z.string().min(1).isWriteOnlySecret(),\n\n  /**\n   * Whether this credential may be spent. An operator can park a credential without deleting it —\n   * which matters during an incident, where deleting is not reversible and disabling is.\n   */\n  enabled: z.boolean().default(true).isDBIndexed().isSummaryField(),\n\n  validationState: z\n    .enum(ProviderCredentialValidationState)\n    .default(ProviderCredentialValidationState.UNVALIDATED)\n    .isDBIndexed()\n    .isSummaryField(),\n\n  /**\n   * Why the last use failed, when it did. PROVIDER-supplied text about the CREDENTIAL's status —\n   * never the credential. A resolver writing anything derived from `secretValue` here would defeat\n   * every other precaution in this file, because this field IS client-readable.\n   */\n  validationError: z.string().max(500).optional().excludeFromCreate().excludeFromUpdate(),\n\n  lastValidatedAt: z.date().optional().excludeFromCreate().excludeFromUpdate(),\n  lastUsedAt: z.date().optional().isDBIndexed().excludeFromCreate().excludeFromUpdate(),\n\n  /**\n   * WHO set it — the acting user's id, recorded for the audit trail.\n   *\n   * Deliberately NOT a registered `USERS` relationship. Declaring that edge would put a CREDENTIAL\n   * row on the Art. 15 subject-export graph, and a credential is precisely the class of row that\n   * must never reach a data subject. The id is recorded because \"who set this\" is the first\n   * question of any credential incident; the edge is withheld because the answer must not travel\n   * with a subject export.\n   */\n  setByUserId: z.string().min(1).optional().isDBIndexed().excludeFromCreate().excludeFromUpdate(),\n\n  /** When the stored VALUE last changed — distinct from `updatedAt`, which any field write moves. */\n  secretSetAt: z.date().optional().excludeFromCreate().excludeFromUpdate(),\n\n  /** Free-text operator note. Never a place for the value; enforced by the write-path pins. */\n  /**\n   * Every fact about the connected ACCOUNT, each value carrying how it got here — see\n   * {@link ProviderConnectionFactProvenance} (#333, #1047).\n   *\n   * ONE record for two sources, by decision: the answers a person typed for the endpoints'\n   * `{placeholder}` holes (which cloud, which directory, which region) — or, for a PASTED credential, for\n   * the REST base URL's holes at the typed-credential store (#1097) — and the facts the vendor\n   * reported in its token answer that operations consume (Salesforce's `instance_url`, Pipedrive's\n   * `api_domain`). Two records would let an operation read one and a refresh update the other.\n   *\n   * On the ROW rather than only in the connect flow, because a REFRESH needs the answers again — a\n   * templated token URL is still templated an hour later — and every CALL needs a reported origin.\n   *\n   * NOT secret, and deliberately client-readable: a tenant id or an instance URL is how a person\n   * recognises which account they connected. The secret half is the grant, and it is sealed.\n   *\n   * `.excludeFromCreate().excludeFromUpdate()` — no CLIENT write may carry it, create included: the field holds\n   * a provenance the resolver trusts, and a pasted-credential create that could type `REPORTED_BY_VENDOR` would\n   * forge the one mark that decides where a request is sent (review F1). Answers change only by reconnecting, which REPLACES\n   * the record with the grant; vendor-reported facts are also rewritten by a refresh that reports them\n   * again. Both are server writes, allow-listed through `preserveServerInjectedFields`.\n   */\n  connectionFacts: z.record(z.string(), ProviderConnectionFactSchema).optional().excludeFromCreate().excludeFromUpdate(),\n\n\n  description: z.string().max(500).optional(),\n\n  createdAt: z.date().default(() => new Date()).isDBIndexed().isSummaryField().excludeFromCreate().excludeFromUpdate(),\n  updatedAt: z.date().default(() => new Date()).isDBIndexed().excludeFromCreate().excludeFromUpdate(),\n})\n  /**\n   * One credential per tenant per (provider, slug), enforced by a compound UNIQUE index rather\n   * than by a read-then-write.\n   *\n   * The race it closes is not academic: two administrators saving a rotated Slack token in the\n   * same minute would otherwise leave two rows, and the resolver would then pick one of them\n   * arbitrarily — so half the tenant's outbound calls would carry the old credential and nobody\n   * could tell which half.\n   *\n   * No `customMessageReference`: that option exists so an integrator can tell WHICH identity a\n   * duplicate violated, and this resource declares exactly one. A dedicated reference here would\n   * disambiguate nothing.\n   */\n  .businessKeySet([...ORGANIZATION_PROVIDER_CREDENTIAL_IDENTITY_FIELDS]);\n\nexport type OrganizationProviderCredential = z.infer<typeof OrganizationProviderCredentialSchema>;\n\n\n\n// =============================================================================\n// USER-OWNED CREDENTIALS\n// =============================================================================\n\n/**\n * The fields that IDENTIFY a credential within its OWNER.\n *\n * Exported per owner rather than shared, because the compound key differs in its first component and\n * a single constant would have to be assembled by each side — which is how two copies of a key come\n * to disagree about what identity means.\n */\nexport const USER_PROVIDER_CREDENTIAL_IDENTITY_FIELDS = [\n  'userId',\n  'providerRef',\n  'secretSlug',\n] as const;\n\n/**\n * A PERSON's own credential toward a third party — the key they authored for themselves.\n *\n * ## Why this is a separate resource and not a nullable column beside the organization's\n *\n * Wildo's tenancy is STRUCTURAL: the contextual filter injects the scope FK by matching a field name\n * at every schema path, so a resource belongs to exactly one primary scope. One table holding both a\n * nullable `organizationId` and a nullable `userId` would turn that structural guarantee into a\n * filter somebody has to remember to write, on the one resource where forgetting it discloses a\n * credential. Two resources, each scoped by construction, is the framework working as designed\n * rather than a duplication.\n *\n * ## Not a delegated OAuth grant, and the difference is not subtle\n *\n * This is a key the user PASTED: they hold an account with the vendor and chose to let this\n * application spend it. A delegated grant is the vendor minting a token because the user approved a\n * consent screen, and it carries a refresh loop, an expiry and a revocation the vendor also honours.\n * Merging them would give one row two lifecycles and two revocation semantics — see #333, which owns\n * the second.\n *\n * ## Only the holder may spend it\n *\n * Not an administrator of their organization, and not a platform operator. Consent to STORE a\n * personal key is not consent for somebody else to use it, and the vendor would record the act as\n * the holder's own. The authorization side of that is\n * `InitiatorMembershipConnectionTargetAuthorization`; this schema is what makes the row reachable\n * only through the owner's own scope.\n */\nexport const UserProviderCredentialSchema = z.object({\n  _id: z.string().min(1).isPrimaryKey().isSummaryField(),\n\n  /**\n   * The person who owns this credential. Injected by the context machinery from the authenticated\n   * scope, never from a caller-supplied field — the same structural isolation the organization-owned\n   * sibling relies on, which is what makes \"another user's key\" unreachable rather than filtered.\n   */\n  userId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate(),\n\n  /** As the organization-owned sibling: an OPEN string, because the provider set is not closed. */\n  providerRef: z.string().min(1).max(200).isDBIndexed().isSummaryField().excludeFromUpdate(),\n\n  /** The provider's `secretsContract` KEY this value satisfies — never the env-var spelling, as the\n   * sibling explains (#624). Immutable, for the same reason as the sibling: re-pointing a stored secret\n   * at a different slug would hand one vendor credential to a different vendor field. */\n  secretSlug: z.string().min(1).max(200).isDBIndexed().isSummaryField().excludeFromUpdate(),\n\n  /**\n   * The credential, SEALED — an AES-256-GCM envelope bound to this row's identity, never plaintext.\n   *\n   * `.isWriteOnlySecret()` for the same reason as the sibling: the holder supplies and rotates it, so\n   * it must survive into the CREATE/UPDATE request DTO, and the framework masks it at the client\n   * boundary so no read ever returns it.\n   */\n  secretValue: z.string().min(1).isWriteOnlySecret(),\n\n  enabled: z.boolean().default(true).isDBIndexed().isSummaryField(),\n\n  validationState: z\n    .enum(ProviderCredentialValidationState)\n    .default(ProviderCredentialValidationState.UNVALIDATED)\n    .isDBIndexed()\n    .isSummaryField(),\n\n  /** Why the last use failed. PROVIDER text about the CREDENTIAL, never anything derived from it —\n   * this field IS client-readable. */\n  validationError: z.string().max(500).optional().excludeFromCreate().excludeFromUpdate(),\n\n  lastValidatedAt: z.date().optional().excludeFromCreate().excludeFromUpdate(),\n  lastUsedAt: z.date().optional().isDBIndexed().excludeFromCreate().excludeFromUpdate(),\n\n  /** When the stored VALUE last changed — distinct from `updatedAt`, which any field write moves. */\n  secretSetAt: z.date().optional().excludeFromCreate().excludeFromUpdate(),\n\n  /** The holder's own note. Never a place for the value; enforced by the write-path pins. */\n  /**\n   * Every fact about the connected ACCOUNT, each value carrying how it got here — see\n   * {@link ProviderConnectionFactProvenance} (#333, #1047).\n   *\n   * ONE record for two sources, by decision: the answers a person typed for the endpoints'\n   * `{placeholder}` holes (which cloud, which directory, which region) — or, for a PASTED credential, for\n   * the REST base URL's holes at the typed-credential store (#1097) — and the facts the vendor\n   * reported in its token answer that operations consume (Salesforce's `instance_url`, Pipedrive's\n   * `api_domain`). Two records would let an operation read one and a refresh update the other.\n   *\n   * On the ROW rather than only in the connect flow, because a REFRESH needs the answers again — a\n   * templated token URL is still templated an hour later — and every CALL needs a reported origin.\n   *\n   * NOT secret, and deliberately client-readable: a tenant id or an instance URL is how a person\n   * recognises which account they connected. The secret half is the grant, and it is sealed.\n   *\n   * `.excludeFromCreate().excludeFromUpdate()` — no CLIENT write may carry it, create included: the field holds\n   * a provenance the resolver trusts, and a pasted-credential create that could type `REPORTED_BY_VENDOR` would\n   * forge the one mark that decides where a request is sent (review F1). Answers change only by reconnecting, which REPLACES\n   * the record with the grant; vendor-reported facts are also rewritten by a refresh that reports them\n   * again. Both are server writes, allow-listed through `preserveServerInjectedFields`.\n   */\n  connectionFacts: z.record(z.string(), ProviderConnectionFactSchema).optional().excludeFromCreate().excludeFromUpdate(),\n\n\n  description: z.string().max(500).optional(),\n\n  createdAt: z.date().default(() => new Date()).isDBIndexed().isSummaryField().excludeFromCreate().excludeFromUpdate(),\n  updatedAt: z.date().default(() => new Date()).isDBIndexed().excludeFromCreate().excludeFromUpdate(),\n})\n  /**\n   * One credential per person per (provider, slug), enforced by a compound UNIQUE index rather than\n   * a read-then-write — the same race the organization-owned sibling closes, and for the same\n   * reason: two rows would leave the resolver picking one arbitrarily, so half the holder's outbound\n   * calls would carry a rotated-away credential and nothing would say which half.\n   */\n  .businessKeySet([...USER_PROVIDER_CREDENTIAL_IDENTITY_FIELDS]);\n\nexport type UserProviderCredential = z.infer<typeof UserProviderCredentialSchema>;\n\n\n// ══════════════════════════════════════════════════════════════════════════════════════════════\n// OAUTH2 GRANTS\n//\n// A credential a vendor MINTS rather than one a person pastes. It rides in the same `secretValue`\n// field of the same two resources — sealed, as JSON — and that reuse is deliberate.\n//\n// ## Why the same rows rather than a third resource\n//\n// The identity is the same triple (owner, providerRef, secretSlug), the ownership semantics are the\n// same, the authorization is the same, the erasure is the same, and the resolver already routes by\n// scope. Only the PAYLOAD differs. A separate resource would duplicate every one of those and force\n// each consumer to ask \"which store?\" before it could ask anything useful.\n//\n// Note this is the OPPOSITE call from the one that split USER from ORGANIZATION, and the difference\n// is what makes both right: there the TENANCY differed, and tenancy in this framework is structural\n// — one table with a nullable owner would turn a structural guarantee into a filter somebody must\n// remember to write. Here nothing about ownership changes; a string becomes an object.\n// ══════════════════════════════════════════════════════════════════════════════════════════════\n\n/**\n * What an authorization exchange gives back, as it is stored.\n *\n * Sealed as JSON into `secretValue`, so `.isWriteOnlySecret()` keeps masking it at the client\n * boundary and the envelope keeps binding it to its row — both mechanisms work on a string and\n * neither needs to know the string is structured.\n */\n/**\n * What SHAPE a sealed credential holds, once opened.\n *\n * One member today and a named vocabulary anyway, because the day a second sealed payload exists —\n * a service-account key, a signed JWT assertion — the discriminant is what tells them apart, and a\n * bare literal is where per-member explanation cannot live. It is also the value a reader needs to\n * understand `PROVIDER_OAUTH2_GRANT_PREFIX`: the prefix is how the shape is recognised WITHOUT\n * parsing, and this is what it recognises.\n */\n/**\n * Why a provider cannot be connected HERE, even though the vendor is in the catalogue.\n *\n * \"Connectable\" is a property of the DEPLOYMENT and not of the vendor, and conflating the two put a\n * Connect button on a screen that could only ever fail. Asana supports OAuth2 perfectly well; this\n * application has simply never registered with Asana, and no amount of pressing the button changes\n * that.\n *\n * The two members lead to different actions by different people, which is the whole reason they are\n * distinguished rather than collapsed into a boolean.\n */\n/**\n * HOW a connection to a provider is established — the shape of the act, which decides the screen.\n *\n * A connect surface cannot be one form. Granting consent at a vendor and typing a key are different\n * acts with different inputs and different failure modes, and a screen that offered one button for\n * both would be wrong for whichever it was not built around.\n */\nexport enum ProviderAuthMethod {\n  /** The authorization-code round trip: leave, consent at the vendor, come back with a grant. */\n  OAUTH2_AUTHORIZATION_CODE = 'oauth2-authorization-code',\n  /**\n   * A value somebody holds and types — an API key, a personal access token. The fields are DECLARED\n   * by the provider's secrets contract, so a screen names them rather than asking for a slug.\n   */\n  DECLARED_SECRET = 'declared-secret',\n}\n\nexport enum ProviderConnectabilityBlocker {\n  /**\n   * The vendor has no authorization flow in the catalogue: its credential is PASTED, not granted.\n   * Nothing is missing and nothing is broken — this provider is authored on the credential screen\n   * instead, and an application author is the one who acts.\n   */\n  NO_AUTHORIZATION_FLOW = 'no-authorization-flow',\n  /**\n   * The vendor has a flow and THIS DEPLOYMENT has not registered with it — no client id, or no client\n   * secret. An OPERATOR acts: register an application with the vendor and set the two environment\n   * variables the provider's contract names. Distinct from the above because the vendor is perfectly\n   * connectable and the gap is ours.\n   */\n  APPLICATION_NOT_REGISTERED = 'application-not-registered',\n  /**\n   * An OAuth2 endpoint's HOST or ORIGIN — or the origin a SCOPE names (`{hostUrl}/.default`, #991) — is a\n   * placeholder the provider declares no allowance for, so no value can ever be admitted there (#623):\n   * the token endpoint receives the application's client secret, and a host is never taken from what\n   * somebody types. Nobody connecting can fix it; the provider needs a recorded host allowance.\n   */\n  ENDPOINT_HOST_NOT_DECLARED = 'endpoint-host-not-declared',\n  /**\n   * The provider's OAuth2 endpoint definition cannot be resolved safely whatever is supplied — a\n   * malformed template, an unresolved source expression, or an allowance that cannot apply where its\n   * placeholder sits. A provider-definition defect, not a deployment or account gap.\n   */\n  ENDPOINT_DEFINITION_INVALID = 'endpoint-definition-invalid',\n  /**\n   * The provider's OAuth2 origin is filled from this DEPLOYMENT's configured base URL (a self-hosted\n   * vendor such as Gitea), and that base URL is unset or unusable. An OPERATOR acts.\n   */\n  DEPLOYMENT_BASE_URL_UNUSABLE = 'deployment-base-url-unusable',\n  /**\n   * An OAuth2 endpoint host is filled from a deployment environment variable dedicated to it (Workday's\n   * `WORKDAY_AUTH_HOST` / `WORKDAY_API_HOST`, #992), and that variable is unset or not a DNS name. An\n   * OPERATOR acts; the variable is named in the catalogue entry's `missingRegistration`.\n   */\n  DEPLOYMENT_CONFIGURED_HOST_UNUSABLE = 'deployment-configured-host-unusable',\n  /**\n   * The vendor's credential is PASTED and its REST base URL forms its HOST or ORIGIN from a placeholder the\n   * provider declares no allowance for (`https://{subdomain}.vendor.com` with no `baseUrlHostAllowances`\n   * entry), so no answer the typed-credential store could collect is ever admitted and every call would\n   * refuse (#1097). Nobody connecting can fix it; the provider needs a recorded host allowance — the\n   * base-URL twin of `ENDPOINT_HOST_NOT_DECLARED`.\n   */\n  BASE_URL_HOST_NOT_DECLARED = 'base-url-host-not-declared',\n}\n\n/**\n * One secret slot a provider declares, as a SCREEN needs it — never the value.\n *\n * Exists so nothing is typed by hand. The slug names the field, the environment variable tells an\n * operator exactly what to set, and `configured` lets a missing one be REPORTED rather than\n * discovered by pressing a button that fails.\n */\nexport interface ProviderSecretSlotView {\n  readonly slug: string;\n  readonly envVarName: string;\n  readonly required: boolean;\n  readonly description: string;\n  /** Whether the deployment supplies it. There is deliberately no field for the value. */\n  readonly configured: boolean;\n}\n\nexport enum ProviderStoredCredentialKind {\n  /** An OAuth2 grant: an access token, and what is needed to renew it. */\n  OAUTH2_GRANT = 'oauth2-grant',\n}\n\nexport const ProviderOAuth2GrantSchema = z.object({\n  /**\n   * A discriminant, so an opened envelope announces which shape it is.\n   *\n   * Without it the reader would have to guess from whether the plaintext parses as JSON — and a\n   * pasted credential that happens to be JSON (a service-account key, which several vendors issue\n   * exactly that way) would be misread as a grant. A guess that is right almost always is the worst\n   * kind here, because the failure is a malformed Authorization header on somebody else's account.\n   */\n  kind: z.literal(ProviderStoredCredentialKind.OAUTH2_GRANT),\n\n  /** The token that actually goes on the wire. */\n  accessToken: z.string().min(1),\n\n  /**\n   * Present when the vendor issues one. Absent is normal and permanent for vendors that do not —\n   * Slack's bot tokens do not expire and have no refresh — so its absence must not read as an\n   * incomplete grant.\n   */\n  refreshToken: z.string().min(1).optional(),\n\n  /**\n   * When the access token stops being accepted, as an ISO instant.\n   *\n   * Optional because a non-expiring token genuinely has none. A grant with a refresh token and no\n   * expiry is refreshed only after the vendor rejects it, which is correct but slower than\n   * refreshing ahead of a known deadline.\n   */\n  expiresAt: z.iso.datetime().optional(),\n\n  /**\n   * What the vendor actually GRANTED, which is not always what was asked for.\n   *\n   * Recorded because the difference is invisible until a call fails: a vendor may issue a token for\n   * a subset of the requested scopes, and the resulting `missing_scope` arrives on an unrelated\n   * operation weeks later. Holding the granted set lets that be answered from the row.\n   */\n  grantedScopes: z.array(z.string()).optional(),\n\n  /**\n   * The vendor's own identifier for the account this grant is on — a Slack team id, a Google sub, a\n   * Microsoft tenant id.\n   *\n   * Not used for lookup and deliberately not part of the row's identity. It exists so a person\n   * reading their connections can tell WHICH account they connected, which a provider ref cannot\n   * answer for anyone who has two.\n   */\n  accountRef: z.string().optional(),\n});\n\nexport type ProviderOAuth2Grant = z.infer<typeof ProviderOAuth2GrantSchema>;\n\n/**\n * The marker that opens the sealed plaintext of a grant rather than a pasted credential.\n *\n * A prefix on the JSON rather than a field inside it, so the decision can be made without parsing —\n * the same reason the envelope carries a prefix. Parsing first would mean feeding an arbitrary\n * pasted credential to `JSON.parse` on every resolution.\n */\nexport const PROVIDER_OAUTH2_GRANT_PREFIX = 'wildo-oauth2-grant:';\n\n/** Whether an OPENED credential is a grant. Cheap, and does not parse. */\nexport function isProviderOAuth2GrantPlaintext(plaintext: string): boolean {\n  return plaintext.startsWith(PROVIDER_OAUTH2_GRANT_PREFIX);\n}\n\n/** Render a grant for sealing. The inverse of {@link parseProviderOAuth2Grant}. */\nexport function serializeProviderOAuth2Grant(grant: ProviderOAuth2Grant): string {\n  return `${PROVIDER_OAUTH2_GRANT_PREFIX}${JSON.stringify(grant)}`;\n}\n\n/**\n * Read a grant back, or `undefined` when the plaintext is an ordinary pasted credential.\n *\n * THROWS when the value announces itself as a grant and then does not parse or does not validate.\n * That is the same posture the envelope takes toward a value the write path could not have\n * produced: a credential which claims a shape it does not have is a fault worth failing on, never\n * one worth falling back from — falling back would put a JSON blob on the wire as a bearer token.\n */\nexport function parseProviderOAuth2Grant(plaintext: string): ProviderOAuth2Grant | undefined {\n  if (!isProviderOAuth2GrantPlaintext(plaintext)) return undefined;\n  const body = plaintext.slice(PROVIDER_OAUTH2_GRANT_PREFIX.length);\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(body);\n  } catch {\n    throw new Error(\n      'A stored provider credential announces itself as an OAuth2 grant and is not valid JSON. It was '\n      + 'written by something other than the authorization exchange; reconnect the account.',\n    );\n  }\n  const result = ProviderOAuth2GrantSchema.safeParse(parsed);\n  if (!result.success) {\n    throw new Error(\n      'A stored provider credential announces itself as an OAuth2 grant but does not match the grant '\n      + 'shape. Reconnect the account rather than editing the row — the value on the wire would '\n      + 'otherwise be a fragment of a token.',\n    );\n  }\n  return result.data;\n}\n\n/**\n * Whether a grant should be refreshed BEFORE it is spent.\n *\n * The skew is what makes this useful rather than decorative: a token that expires in two seconds is\n * still \"valid\" and will have expired by the time the request reaches the vendor, so refreshing only\n * on expiry guarantees a population of calls that fail for a reason nothing recorded. Sixty seconds\n * is the industry's common floor and comfortably exceeds any plausible clock skew plus flight time.\n *\n * Returns false when there is no expiry — a non-expiring token is refreshed reactively, after the\n * vendor rejects it, because there is no deadline to act ahead of.\n */\nexport const PROVIDER_OAUTH2_REFRESH_SKEW_SECONDS = 60;\n\nexport function providerOAuth2GrantNeedsRefresh(grant: ProviderOAuth2Grant, now: Date = new Date()): boolean {\n  if (grant.expiresAt === undefined) return false;\n  const expiry = Date.parse(grant.expiresAt);\n  if (Number.isNaN(expiry)) return true;\n  return expiry - now.getTime() <= PROVIDER_OAUTH2_REFRESH_SKEW_SECONDS * 1000;\n}\n"]}