@wildo-ai/saas-models 1.1.4 → 1.1.6

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, connectionRef, 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`, `connectionRef` or `secretSlug` for an existing row. The sealed
+     * value is bound to the connection and the slot, and `providerRef` records which ref created the row, so a row
+     * cannot move: a credential for another slot or connection 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().describe("The fact's value, such as a tenant id or an instance URL."),
+    provenance: z.enum(ProviderConnectionFactProvenance).describe("Where the value came from: `ANSWERED_AT_CONNECT` was entered by the person connecting and changes only when they reconnect or re-enter the credential; `REPORTED_BY_VENDOR` came from the vendor's token response and may change at a token refresh."),
+});
 /**
  * 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,21 +212,69 @@ 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.
+ * The fields that IDENTIFY a credential within its tenant: `(organizationId, connectionRef, secretSlug)`.
+ *
+ * One tenant holds at most one credential per (CONNECTION, slug) — not per provider ref (#1670). A
+ * connection is the unit a vendor grant belongs to: by default every provider ref is its own connection
+ * (`connectionRef` = `providerRef`), and a vendor served by several refs (an engine part plus add-on
+ * packages) can hold ONE grant that all of them spend. Keying on the ref made that impossible — two refs
+ * of one vendor could never share a stored credential, whatever the client side did.
  *
- * One tenant holds at most one credential per (provider, slug). Exported rather than repeated so
- * the uniqueness contract, the resolver's lookup and the tests cannot drift apart — three copies
- * of a compound key is how two of them come to disagree about what identity means.
+ * Exported rather than repeated so the uniqueness contract, the resolver's lookup and the tests cannot
+ * drift apart — three copies of a compound key is how two of them come to disagree about what identity
+ * means. The sealed value binds the same three components (the connection, never the ref), so a row's
+ * key and its seal always name one identity.
  */
 export const ORGANIZATION_PROVIDER_CREDENTIAL_IDENTITY_FIELDS = [
     'organizationId',
-    'providerRef',
+    'connectionRef',
     'secretSlug',
 ];
+/** @wildo_source:part:end saas.models.provider-credential-identity */
+/**
+ * The organization's credential for one (connection, 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(),
     /**
@@ -131,13 +288,32 @@ export const OrganizationProviderCredentialSchema = z.object({
      * ref). An OPEN string, matching `ProviderRef`'s own openness — the whole point of the provider
      * work is that the set is not closed, so a closed enum here would refuse every generated
      * provider.
+     *
+     * NOT the row's identity since #1670: it records which ref's connect flow (or write) CREATED the row,
+     * and `connectionRef` below is what the row is keyed and sealed on. A reconnect through another ref of
+     * the same connection replaces the value and leaves this unchanged.
      */
     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 CONNECTION this credential belongs to — the row's identity, where `providerRef` records only which
+     * ref's connect flow (or write) CREATED it (#1670).
+     *
+     * Derived by the server from `providerRef` through the provider registry's connection mapping, never
+     * supplied by a client: `.excludeFromCreate()` because a caller naming a connection would choose which
+     * grant its value lands beside, and `.excludeFromUpdate()` because the sealed value binds it — a row
+     * cannot move to another connection, only be replaced (`CREDENTIAL_SLOT_IMMUTABLE`). Every ref is its own
+     * connection until an application declares otherwise (#1725), so today it always equals `providerRef`,
+     * and every row stored before the field existed was backfilled to exactly that.
+     */
+    connectionRef: z.string().min(1).max(200).isDBIndexed().isSummaryField().excludeFromCreate().excludeFromUpdate(),
+    /**
+     * 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(),
     /**
@@ -160,11 +336,18 @@ export const OrganizationProviderCredentialSchema = z.object({
      * which matters during an incident, where deleting is not reversible and disabling is.
      */
     enabled: z.boolean().default(true).isDBIndexed().isSummaryField(),
+    /**
+     * What the last USE of this credential proved — written only by the credential store after a provider accepted
+     * or rejected it (#1809). Excluded from create and update like its three siblings, so the owner cannot declare a
+     * credential VALID that no provider ever accepted, or clear an INVALID the resolver recorded.
+     */
     validationState: z
         .enum(ProviderCredentialValidationState)
         .default(ProviderCredentialValidationState.UNVALIDATED)
         .isDBIndexed()
-        .isSummaryField(),
+        .isSummaryField()
+        .excludeFromCreate()
+        .excludeFromUpdate(),
     /**
      * Why the last use failed, when it did. PROVIDER-supplied text about the CREDENTIAL's status —
      * never the credential. A resolver writing anything derived from `secretValue` here would defeat
@@ -187,32 +370,34 @@ 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).
+     *
+     * 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(),
 })
     /**
-     * One credential per tenant per (provider, slug), enforced by a compound UNIQUE index rather
+     * One credential per tenant per (connection, slug), enforced by a compound UNIQUE index rather
      * than by a read-then-write.
      *
      * The race it closes is not academic: two administrators saving a rotated Slack token in the
@@ -228,8 +413,10 @@ export const OrganizationProviderCredentialSchema = z.object({
 // =============================================================================
 // USER-OWNED CREDENTIALS
 // =============================================================================
+/** @wildo_source:part:start saas.models.provider-credential-identity facet:layer:shared facet:audience:app-developer */
 /**
- * The fields that IDENTIFY a credential within its OWNER.
+ * The fields that IDENTIFY a credential within its OWNER: `(userId, connectionRef, secretSlug)` — keyed on
+ * the CONNECTION, never the provider ref, as the organization-owned sibling explains (#1670).
  *
  * Exported per owner rather than shared, because the compound key differs in its first component and
  * a single constant would have to be assembled by each side — which is how two copies of a key come
@@ -237,9 +424,10 @@ export const OrganizationProviderCredentialSchema = z.object({
  */
 export const USER_PROVIDER_CREDENTIAL_IDENTITY_FIELDS = [
     'userId',
-    'providerRef',
+    'connectionRef',
     'secretSlug',
 ];
+/** @wildo_source:part:end saas.models.provider-credential-identity */
 /**
  * A PERSON's own credential toward a third party — the key they authored for themselves.
  *
@@ -276,11 +464,19 @@ export const UserProviderCredentialSchema = z.object({
      * sibling relies on, which is what makes "another user's key" unreachable rather than filtered.
      */
     userId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate(),
-    /** As the organization-owned sibling: an OPEN string, because the provider set is not closed. */
+    /**
+     * As the organization-owned sibling: an OPEN string, because the provider set is not closed. Records which
+     * ref's connect flow (or write) CREATED the row; the row's identity is `connectionRef` (#1670).
+     */
     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 CONNECTION this credential belongs to — the row's identity (#1670). Server-derived from `providerRef`,
+     * never client-supplied, and immutable because the seal binds it; see the organization-owned sibling.
+     */
+    connectionRef: z.string().min(1).max(200).isDBIndexed().isSummaryField().excludeFromCreate().excludeFromUpdate(),
+    /** 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.
@@ -291,11 +487,18 @@ export const UserProviderCredentialSchema = z.object({
      */
     secretValue: z.string().min(1).isWriteOnlySecret(),
     enabled: z.boolean().default(true).isDBIndexed().isSummaryField(),
+    /**
+     * What the last USE of this credential proved — written only by the credential store after a provider accepted
+     * or rejected it (#1809). Excluded from create and update like its three siblings, so the owner cannot declare a
+     * credential VALID that no provider ever accepted, or clear an INVALID the resolver recorded.
+     */
     validationState: z
         .enum(ProviderCredentialValidationState)
         .default(ProviderCredentialValidationState.UNVALIDATED)
         .isDBIndexed()
-        .isSummaryField(),
+        .isSummaryField()
+        .excludeFromCreate()
+        .excludeFromUpdate(),
     /** Why the last use failed. PROVIDER text about the CREDENTIAL, never anything derived from it —
      * this field IS client-readable. */
     validationError: z.string().max(500).optional().excludeFromCreate().excludeFromUpdate(),
@@ -305,32 +508,34 @@ 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(),
 })
     /**
-     * One credential per person per (provider, slug), enforced by a compound UNIQUE index rather than
+     * One credential per person per (connection, slug), enforced by a compound UNIQUE index rather than
      * a read-then-write — the same race the organization-owned sibling closes, and for the same
      * reason: two rows would leave the resolver picking one arbitrarily, so half the holder's outbound
      * calls would carry a rotated-away credential and nothing would say which half.
@@ -344,7 +549,7 @@ export const UserProviderCredentialSchema = z.object({
 //
 // ## Why the same rows rather than a third resource
 //
-// The identity is the same triple (owner, providerRef, secretSlug), the ownership semantics are the
+// The identity is the same triple (owner, connectionRef, secretSlug), the ownership semantics are the
 // same, the authorization is the same, the erasure is the same, and the resolver already routes by
 // scope. Only the PAYLOAD differs. A separate resource would duplicate every one of those and force
 // each consumer to ask "which store?" before it could ask anything useful.
@@ -413,6 +618,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) {
@@ -462,6 +699,17 @@ export const ProviderOAuth2GrantSchema = z.object({
      * answer for anyone who has two.
      */
     accountRef: z.string().optional(),
+    /**
+     * An identifier minted when the person AUTHORIZES — at the code exchange — and carried unchanged through every
+     * renewal (#1725). A reconnect mints a new one.
+     *
+     * It is what a cached token of another resource audience is bound to: a Dataverse token minted from this grant's
+     * refresh token belongs to THIS authorization, and a reconnect — possibly to a different Microsoft account, on the
+     * same row — must never be answered from the previous authorization's cache. The row's id cannot do this (a
+     * reconnect updates the row in place) and the refresh token cannot either (Microsoft replaces it on every use).
+     * Absent on a grant stored before #1725, which then binds its cache entries to the row instead.
+     */
+    grantId: z.string().min(1).optional(),
 });
 /**
  * The marker that opens the sealed plaintext of a grant rather than a pasted credential.