@wildo-ai/saas-models 1.1.5 → 1.1.6

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

@@ -51,7 +51,7 @@ export var ProviderCredentialValidationState;
  * Why a write door refused to store a credential VALUE under the slot it named — the stable,
  * client-branchable `code` every door carries (#624).
  *
- * A stored row is keyed `(owner, providerRef, secretSlug)` on the provider's secrets-contract KEY, and
+ * 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.
@@ -74,9 +74,9 @@ export var ProviderCredentialSlotWriteRefusal;
      */
     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.
+     * 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 = {}));
@@ -98,8 +98,8 @@ export var ProviderConnectionFactProvenance;
 })(ProviderConnectionFactProvenance || (ProviderConnectionFactProvenance = {}));
 /** One value in a credential row's `connectionFacts`. */
 export const ProviderConnectionFactSchema = z.strictObject({
-    value: z.string(),
-    provenance: z.enum(ProviderConnectionFactProvenance),
+    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.
@@ -244,19 +244,27 @@ export var ProviderCredentialDeletionReason;
     ProviderCredentialDeletionReason["USER_DELETED"] = "user_deleted";
 })(ProviderCredentialDeletionReason || (ProviderCredentialDeletionReason = {}));
 /**
- * The fields that IDENTIFY a credential within its tenant.
- *
- * 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.
+ * 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.
+ *
+ * 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 (provider, secret slug) pair.
+ * The organization's credential for one (connection, secret slug) pair.
  *
  * ## The scope identifier is TOP-LEVEL and stays that way
  *
@@ -280,8 +288,24 @@ 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 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
@@ -312,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
@@ -366,7 +397,7 @@ export const OrganizationProviderCredentialSchema = z.object({
     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
@@ -382,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
@@ -391,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.
  *
@@ -430,8 +464,16 @@ 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 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. */
@@ -445,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(),
@@ -486,7 +535,7 @@ export const UserProviderCredentialSchema = z.object({
     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.
@@ -500,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.
@@ -650,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.

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 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"]}
+{"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, connectionRef, 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`, `connectionRef` or `secretSlug` for an existing row. The sealed\n   * value is bound to the connection and the slot, and `providerRef` records which ref created the row, so a row\n   * cannot move: a credential for another slot or connection is a new row, and the old one is 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().describe(\"The fact's value, such as a tenant id or an instance URL.\"),\n  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.\"),\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/** @wildo_source:part:start saas.models.provider-credential-identity facet:layer:shared facet:audience:app-developer */\n/**\n * Where a stored credential LIVES: the connection it belongs to and the slot within it (#1670).\n *\n * The owner is not part of it because every caller already holds the owner from its own trusted scope;\n * this is the half the provider registry answers. `ExternalProvidersRegistryBackendService.resolveCredentialAddress`\n * is the ONE producer, so \"which row does a call through ref R spend\" has one answer on every read path.\n */\nexport interface ProviderCredentialAddress {\n  /**\n   * The CONNECTION the credential belongs to — the key component that used to be the provider ref.\n   * Today every ref is its own connection, so this equals the ref; #1725 lets an application declare\n   * several refs of one vendor as one connection, and then every ref of it resolves the same row.\n   */\n  readonly connectionRef: string;\n  /** The provider's secrets-contract KEY — see `canonicalCredentialSlug` (#624). */\n  readonly secretSlug: string;\n}\n\n/**\n * The fields that IDENTIFY a credential within its tenant: `(organizationId, connectionRef, secretSlug)`.\n *\n * One tenant holds at most one credential per (CONNECTION, slug) — not per provider ref (#1670). A\n * connection is the unit a vendor grant belongs to: by default every provider ref is its own connection\n * (`connectionRef` = `providerRef`), and a vendor served by several refs (an engine part plus add-on\n * packages) can hold ONE grant that all of them spend. Keying on the ref made that impossible — two refs\n * of one vendor could never share a stored credential, whatever the client side did.\n *\n * Exported rather than repeated so the uniqueness contract, the resolver's lookup and the tests cannot\n * drift apart — three copies of a compound key is how two of them come to disagree about what identity\n * means. The sealed value binds the same three components (the connection, never the ref), so a row's\n * key and its seal always name one identity.\n */\nexport const ORGANIZATION_PROVIDER_CREDENTIAL_IDENTITY_FIELDS = [\n  'organizationId',\n  'connectionRef',\n  'secretSlug',\n] as const;\n/** @wildo_source:part:end saas.models.provider-credential-identity */\n\n/**\n * The organization's credential for one (connection, 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   * NOT the row's identity since #1670: it records which ref's connect flow (or write) CREATED the row,\n   * and `connectionRef` below is what the row is keyed and sealed on. A reconnect through another ref of\n   * the same connection replaces the value and leaves this unchanged.\n   */\n  providerRef: z.string().min(1).max(200).isDBIndexed().isSummaryField().excludeFromUpdate(),\n\n  /**\n   * The CONNECTION this credential belongs to — the row's identity, where `providerRef` records only which\n   * ref's connect flow (or write) CREATED it (#1670).\n   *\n   * Derived by the server from `providerRef` through the provider registry's connection mapping, never\n   * supplied by a client: `.excludeFromCreate()` because a caller naming a connection would choose which\n   * grant its value lands beside, and `.excludeFromUpdate()` because the sealed value binds it — a row\n   * cannot move to another connection, only be replaced (`CREDENTIAL_SLOT_IMMUTABLE`). Every ref is its own\n   * connection until an application declares otherwise (#1725), so today it always equals `providerRef`,\n   * and every row stored before the field existed was backfilled to exactly that.\n   */\n  connectionRef: z.string().min(1).max(200).isDBIndexed().isSummaryField().excludeFromCreate().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  /**\n   * What the last USE of this credential proved — written only by the credential store after a provider accepted\n   * or rejected it (#1809). Excluded from create and update like its three siblings, so the owner cannot declare a\n   * credential VALID that no provider ever accepted, or clear an INVALID the resolver recorded.\n   */\n  validationState: z\n    .enum(ProviderCredentialValidationState)\n    .default(ProviderCredentialValidationState.UNVALIDATED)\n    .isDBIndexed()\n    .isSummaryField()\n    .excludeFromCreate()\n    .excludeFromUpdate(),\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 (connection, 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/** @wildo_source:part:start saas.models.provider-credential-identity facet:layer:shared facet:audience:app-developer */\n/**\n * The fields that IDENTIFY a credential within its OWNER: `(userId, connectionRef, secretSlug)` — keyed on\n * the CONNECTION, never the provider ref, as the organization-owned sibling explains (#1670).\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  'connectionRef',\n  'secretSlug',\n] as const;\n/** @wildo_source:part:end saas.models.provider-credential-identity */\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  /**\n   * As the organization-owned sibling: an OPEN string, because the provider set is not closed. Records which\n   * ref's connect flow (or write) CREATED the row; the row's identity is `connectionRef` (#1670).\n   */\n  providerRef: z.string().min(1).max(200).isDBIndexed().isSummaryField().excludeFromUpdate(),\n\n  /**\n   * The CONNECTION this credential belongs to — the row's identity (#1670). Server-derived from `providerRef`,\n   * never client-supplied, and immutable because the seal binds it; see the organization-owned sibling.\n   */\n  connectionRef: z.string().min(1).max(200).isDBIndexed().isSummaryField().excludeFromCreate().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  /**\n   * What the last USE of this credential proved — written only by the credential store after a provider accepted\n   * or rejected it (#1809). Excluded from create and update like its three siblings, so the owner cannot declare a\n   * credential VALID that no provider ever accepted, or clear an INVALID the resolver recorded.\n   */\n  validationState: z\n    .enum(ProviderCredentialValidationState)\n    .default(ProviderCredentialValidationState.UNVALIDATED)\n    .isDBIndexed()\n    .isSummaryField()\n    .excludeFromCreate()\n    .excludeFromUpdate(),\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 (connection, 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, connectionRef, 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  /**\n   * An identifier minted when the person AUTHORIZES — at the code exchange — and carried unchanged through every\n   * renewal (#1725). A reconnect mints a new one.\n   *\n   * It is what a cached token of another resource audience is bound to: a Dataverse token minted from this grant's\n   * refresh token belongs to THIS authorization, and a reconnect — possibly to a different Microsoft account, on the\n   * same row — must never be answered from the previous authorization's cache. The row's id cannot do this (a\n   * reconnect updates the row in place) and the refresh token cannot either (Microsoft replaces it on every use).\n   * Absent on a grant stored before #1725, which then binds its cache entries to the row instead.\n   */\n  grantId: z.string().min(1).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"]}

package/dist/esm/security/credential-rotation-grace.shared.utils.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The credential-rotation rules every surface must agree on: whether a reissued credential's PREVIOUS secret still
+ * authenticates, and whether a credential has passed its expiry.
+ *
+ * They live here, in the shared models, because the backend is not their only reader. The request-auth handlers
+ * decide with them, and a screen that shows an operator a rotated key must answer the same question — "does the
+ * old secret still work?" — the same way, or it shows a dead secret as live, or a live one as nothing. Moved from
+ * `saas-backend-lib`'s `credential-rotation-grace.backend.utils.ts`, which now delegates here.
+ */
+/**
+ * Whether a credential's PREVIOUS secret — moved into the rotation-grace slot when the credential
+ * was reissued — is still inside its grace window and may therefore still authenticate.
+ *
+ * `invalidationDate` is written by the ROTATE / REGENERATE reissue handlers on both api-keys and
+ * OAuth clients, and its three states carry distinct semantics:
+ *
+ * - `null` / `undefined` → **open-ended overlap**. This is what REGENERATE writes: the reissue is
+ *   ADDITIVE — it mints a new secret WITHOUT invalidating the prior one, so the prior secret keeps
+ *   authenticating until the NEXT reissue. REGENERATE is therefore NOT a way to cut off a leaked
+ *   secret: to revoke a compromised credential you must either REVOKE it (status → non-ACTIVE,
+ *   which fails the `status === ACTIVE` gate every caller applies to the resolved record) or ROTATE
+ *   with an explicit invalidation date. This open-endedness is deliberate, not a bug.
+ * - a FUTURE date → still valid — a bounded overlap window (e.g. a ROTATE handover deadline).
+ * - `now` / a PAST date → expired.
+ *
+ * Callers MUST additionally require the resolved record's `status === ACTIVE`, so a
+ * deactivated/expired credential's previous secret never authenticates regardless of this window.
+ *
+ * SINGLE SOURCE OF TRUTH shared by the api-key request-auth handlers, the OAuth-client
+ * direct-secret handlers, the `/oauth/token` client-secret exchange, and the screens that show a
+ * rotated credential ({@link isPreviousCredentialSecretAccepted}) — they MUST agree on grace
+ * semantics, so the check lives here once rather than being copied per call site.
+ */
+export declare function isRotationGraceWindowOpen(invalidationDate?: Date | null): boolean;
+/**
+ * Whether a credential (api-key / OAuth client) has passed its `expiresAt`. `null`/`undefined` =
+ * no expiry set = never expires.
+ *
+ * Enforced at AUTH-TIME on every machine front, and that is where the enforcement STAYS.
+ *
+ * There IS an `EXPIRED` producer since 2026-09-08 — the nightly credential-expiry sweep (#413)
+ * dispatches each resource's `expire` verb — but it is BOOKKEEPING, never the control. It always
+ * lags: a credential that elapses at 09:00 still reads ACTIVE until 02:30 the next morning. This
+ * check is what makes that lag harmless, so a caller must never replace it with a `status` test.
+ * Do that and the sweep's lag becomes an authorization hole rather than a stale display, and
+ * `expiresAt` plus the `EXTEND_EXPIRY` operation go back to being decorative. Callers apply it
+ * alongside the ACTIVE gate:
+ * `!record || record.status !== ACTIVE || isCredentialExpired(record.expiresAt)`. SINGLE SOURCE OF
+ * TRUTH shared by the api-key + OAuth-client request-auth handlers and the `/oauth/token` exchange.
+ */
+export declare function isCredentialExpired(expiresAt?: Date | null): boolean;
+/**
+ * Whether a reissued credential's PREVIOUS secret would authenticate right now — the answer a screen owes an
+ * operator after a rotation, and the same three gates the request-auth handlers apply to a match on the previous
+ * secret: its grace window is open ({@link isRotationGraceWindowOpen}), the credential is ACTIVE, and it has not
+ * passed its expiry ({@link isCredentialExpired}).
+ *
+ * Why a screen needs it rather than the raw fields: the fields alone mislead in both directions. After a
+ * REGENERATE the invalidation date is empty and the old secret works indefinitely, so a screen that hides empty
+ * rows shows nothing at the riskiest moment; after a default ROTATE the date is the rotation instant and the old
+ * secret is dead, yet its prefix is still stored.
+ */
+export declare function isPreviousCredentialSecretAccepted(credential: {
+    hasPreviousSecret: boolean;
+    previousSecretInvalidationDate?: Date | null;
+    isActive: boolean;
+    expiresAt?: Date | null;
+}): boolean;
+//# sourceMappingURL=credential-rotation-grace.shared.utils.d.ts.map

package/dist/esm/security/credential-rotation-grace.shared.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential-rotation-grace.shared.utils.d.ts","sourceRoot":"","sources":["../../../../src/security/credential-rotation-grace.shared.utils.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,yBAAyB,CAAC,gBAAgB,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,OAAO,CAGjF;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,CAAC,EAAE,IAAI,GAAG,IAAI,GAAG,OAAO,CAGpE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kCAAkC,CAAC,UAAU,EAAE;IAC7D,iBAAiB,EAAE,OAAO,CAAC;IAC3B,8BAA8B,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;IAC7C,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;CACzB,GAAG,OAAO,CAOV"}