@wildo-ai/saas-models 1.1.2 → 1.1.4

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

@@ -0,0 +1,530 @@
+/**
+ * Organization Provider Credentials — shared schemas.
+ *
+ * ## What this resource is, and what it is NOT
+ *
+ * It is an ORGANIZATION's OWN credential toward a third party: the Slack workspace token, the CRM
+ * API key, the SMTP password that belongs to THAT tenant. The organization is the third-party
+ * principal, and the credential is a service credential the tenant's administrator supplies.
+ *
+ * It is NOT a user's delegated OAuth grant. A delegated grant is a different object with a
+ * different lifetime (a refresh loop, a revocation the USER can perform, a consent record) and it
+ * lands as `connected accounts` beside this file — see issue #333. Merging the two would give one
+ * row two owners and two revocation semantics.
+ *
+ * ## Why it has to exist
+ *
+ * Before this resource, every provider secret resolved from `process.env` through the
+ * `SecretsContract`, so a credential was per-PROCESS and per-DEPLOYMENT. One application serving
+ * many organizations therefore had ONE Slack token for all of them, and the failure was silent in
+ * the worst direction: an operator sets one key and every tenant thereafter acts as the SAME
+ * third-party principal, with nothing anywhere saying so.
+ *
+ * ## The value is sealed, and this file is where that is stated
+ *
+ * `secretValue` holds an AES-256-GCM envelope, never the plaintext an operator typed. The seal is
+ * applied on the way in and opened only by the resolver — see
+ * `provider-credential-envelope.backend.utils.ts` for the envelope and its key derivation. The
+ * schema cannot enforce that (a string is a string), so the write path is what guarantees it and
+ * the pins are what keep it guaranteed.
+ */
+import { z } from 'zod';
+/**
+ * Whether the stored credential has been shown to work against the provider.
+ *
+ * A closed vocabulary rather than a boolean because "we have never tried" and "we tried and it
+ * failed" are different states with different operator actions, and a boolean would merge them
+ * into the same falsy answer. `UNVALIDATED` is the honest default: storing a credential proves
+ * only that somebody typed one.
+ */
+export var ProviderCredentialValidationState;
+(function (ProviderCredentialValidationState) {
+    /** Stored, never exercised against the provider. The state every credential starts in. */
+    ProviderCredentialValidationState["UNVALIDATED"] = "unvalidated";
+    /** The provider accepted it on its last use. */
+    ProviderCredentialValidationState["VALID"] = "valid";
+    /** The provider rejected it on its last use — the operator must rotate it. */
+    ProviderCredentialValidationState["INVALID"] = "invalid";
+})(ProviderCredentialValidationState || (ProviderCredentialValidationState = {}));
+/**
+ * The organization's credential for one (provider, secret slug) pair.
+ *
+ * ## The scope identifier is TOP-LEVEL and stays that way
+ *
+ * `organizationId` is the only `organizationId`-named path in this schema, and nothing nested may
+ * ever be named `organizationId` or `userId`. `buildContextualFilter` injects the scope FK by
+ * matching that field name at EVERY schema path, so a nested key of the same name adds a phantom
+ * exact-subdocument clause and the scoped read silently matches zero rows — a credential that
+ * exists and cannot be resolved, which reads exactly like a credential that was never set.
+ * `setByUserId` is deliberately spelled so it cannot be caught by that matcher.
+ */
+/**
+ * WHERE a resolved provider secret came from.
+ *
+ * The whole point of this slice is that the answer used to be unanswerable: every secret came from
+ * `process.env`, so "which principal did this tenant act as?" had one answer for every tenant and
+ * nothing recorded it. Making the source an explicit, closed value means an audit reader can see a
+ * tenant falling back to the shared deployment credential — the exact condition the resource exists
+ * to make visible — instead of having to infer it from an absence.
+ */
+export var ProviderCredentialResolutionSource;
+(function (ProviderCredentialResolutionSource) {
+    /** The organization's own credential row. The tenant acted as itself. */
+    ProviderCredentialResolutionSource["ORGANIZATION_CREDENTIAL"] = "organization_credential";
+    /**
+     * The deployment's env-projected `SecretsContract`. Legitimate — a single-tenant deployment, or a
+     * provider the operator intends every tenant to share — but never silent.
+     */
+    ProviderCredentialResolutionSource["DEPLOYMENT_ENVIRONMENT"] = "deployment_environment";
+    /**
+     * A PERSON's own credential row. The application acted as that individual.
+     *
+     * This member has no sibling fallback, and that asymmetry is deliberate rather than an omission.
+     * An organization with no credential of its own may legitimately fall through to the deployment's
+     * — an operator can intend every tenant to share one integration. A person cannot: the vendor
+     * attributes the act to whoever's token was spent, so acting for someone under the deployment's
+     * principal would put the wrong name on the record that outlives us. A person who has connected
+     * nothing gets a refusal, not a substitute.
+     */
+    ProviderCredentialResolutionSource["USER_CREDENTIAL"] = "user_credential";
+})(ProviderCredentialResolutionSource || (ProviderCredentialResolutionSource = {}));
+/** Why a credential row stopped existing. */
+export var ProviderCredentialDeletionReason;
+(function (ProviderCredentialDeletionReason) {
+    /** An administrator of the owning tenant removed it. */
+    ProviderCredentialDeletionReason["ADMINISTRATOR_REVOKED"] = "administrator_revoked";
+    /** The owning organization was purged and the composition cascade removed it with the tenant. */
+    ProviderCredentialDeletionReason["ORGANIZATION_PURGED"] = "organization_purged";
+    /** The person whose credential it was removed it themselves. */
+    ProviderCredentialDeletionReason["OWNER_REVOKED"] = "owner_revoked";
+    /**
+     * The owning user was erased and the composition cascade destroyed it with them.
+     *
+     * Distinct from `ORGANIZATION_PURGED` because this one is EVIDENCE: it is what an operator points
+     * at when asked whether a subject-erasure request reached the person's third-party credentials.
+     * Collapsing the two into a generic "cascade" would make that question unanswerable from the trail.
+     */
+    ProviderCredentialDeletionReason["USER_ERASED"] = "user_erased";
+})(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.
+ */
+export const ORGANIZATION_PROVIDER_CREDENTIAL_IDENTITY_FIELDS = [
+    'organizationId',
+    'providerRef',
+    'secretSlug',
+];
+export const OrganizationProviderCredentialSchema = z.object({
+    _id: z.string().min(1).isPrimaryKey().isSummaryField(),
+    /**
+     * The tenant that owns this credential. Injected by the context machinery from the request
+     * scope, never from a caller-supplied field — which is what makes the isolation structural
+     * rather than a filter somebody has to remember to write.
+     */
+    organizationId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate(),
+    /**
+     * The provider this credential authenticates toward (`slack`, `stripe`, a generated package's
+     * 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.
+     */
+    providerRef: z.string().min(1).max(200).isDBIndexed().isSummaryField().excludeFromUpdate(),
+    /**
+     * The slug in the provider's `secretsContract` that this value satisfies — the same identifier
+     * the deployment's env projection carries, so the two resolution places name the same thing.
+     * Immutable: re-pointing a stored secret at a different slug would silently hand one vendor
+     * credential to a different vendor field.
+     */
+    secretSlug: z.string().min(1).max(200).isDBIndexed().isSummaryField().excludeFromUpdate(),
+    /**
+     * The credential, SEALED.
+     *
+     * `.isWriteOnlySecret()` is the framework's write-then-masked contract and is exactly right
+     * here: the operator supplies and rotates the value, so it must stay in the CREATE/UPDATE
+     * request DTO; the framework redacts it to a placeholder at the client boundary, so no read
+     * ever returns it; and the backend keeps the stored content for its own resolution.
+     *
+     * `.isBackendOnly()` was rejected — it strips the field from the client DTO, so the operator's
+     * typed value is dropped before it is ever stored and the surface silently accepts nothing.
+     *
+     * What is PERSISTED is the envelope, never the plaintext. The write path seals it; a value that
+     * reaches persistence unsealed is a defect, not a tolerated legacy shape.
+     */
+    secretValue: z.string().min(1).isWriteOnlySecret(),
+    /**
+     * Whether this credential may be spent. An operator can park a credential without deleting it —
+     * which matters during an incident, where deleting is not reversible and disabling is.
+     */
+    enabled: z.boolean().default(true).isDBIndexed().isSummaryField(),
+    validationState: z
+        .enum(ProviderCredentialValidationState)
+        .default(ProviderCredentialValidationState.UNVALIDATED)
+        .isDBIndexed()
+        .isSummaryField(),
+    /**
+     * 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
+     * every other precaution in this file, because this field IS client-readable.
+     */
+    validationError: z.string().max(500).optional().excludeFromCreate().excludeFromUpdate(),
+    lastValidatedAt: z.date().optional().excludeFromCreate().excludeFromUpdate(),
+    lastUsedAt: z.date().optional().isDBIndexed().excludeFromCreate().excludeFromUpdate(),
+    /**
+     * WHO set it — the acting user's id, recorded for the audit trail.
+     *
+     * Deliberately NOT a registered `USERS` relationship. Declaring that edge would put a CREDENTIAL
+     * row on the Art. 15 subject-export graph, and a credential is precisely the class of row that
+     * must never reach a data subject. The id is recorded because "who set this" is the first
+     * question of any credential incident; the edge is withheld because the answer must not travel
+     * with a subject export.
+     */
+    setByUserId: z.string().min(1).optional().isDBIndexed().excludeFromCreate().excludeFromUpdate(),
+    /** When the stored VALUE last changed — distinct from `updatedAt`, which any field write moves. */
+    secretSetAt: z.date().optional().excludeFromCreate().excludeFromUpdate(),
+    /** Free-text operator note. Never a place for the value; enforced by the write-path pins. */
+    /**
+     * Answers for the `{placeholder}` holes this provider's OAuth2 endpoints carry — which cloud,
+     * which directory, which region.
+     *
+     * On the ROW rather than only in the connect flow, because a REFRESH needs them again. The
+     * authorization record that held them lives ten minutes; the token it produced is renewed for as
+     * long as the connection lasts, and a templated token URL is still templated an hour later.
+     * Without them here, every one of the 21 vendors whose endpoints carry a placeholder — Microsoft,
+     * Azure, and everything regional — would connect successfully and then fail its first renewal with
+     * `needs a value for 'cloud'`: the exact failure the placeholder machinery exists to prevent, one
+     * layer up.
+     *
+     * NOT secret, and deliberately client-readable: a tenant id is an identifier a person needs to see
+     * to recognise which account they connected. The secret half is the grant, and it is sealed.
+     *
+     * `.excludeFromUpdate()` — chosen at connect time, and they describe the ACCOUNT the grant is for.
+     * Changing them under a live grant would point the refresh at a different directory than the one
+     * that issued the token, failing at the vendor with nothing local explaining why. Reconnecting is
+     * the honest way to change them.
+     */
+    connectionParameters: z.record(z.string(), z.string()).optional().excludeFromUpdate(),
+    description: z.string().max(500).optional(),
+    createdAt: z.date().default(() => new Date()).isDBIndexed().isSummaryField().excludeFromCreate().excludeFromUpdate(),
+    updatedAt: z.date().default(() => new Date()).isDBIndexed().excludeFromCreate().excludeFromUpdate(),
+})
+    /**
+     * One credential per tenant per (provider, slug), enforced by a compound UNIQUE index rather
+     * than by a read-then-write.
+     *
+     * The race it closes is not academic: two administrators saving a rotated Slack token in the
+     * same minute would otherwise leave two rows, and the resolver would then pick one of them
+     * arbitrarily — so half the tenant's outbound calls would carry the old credential and nobody
+     * could tell which half.
+     *
+     * No `customMessageReference`: that option exists so an integrator can tell WHICH identity a
+     * duplicate violated, and this resource declares exactly one. A dedicated reference here would
+     * disambiguate nothing.
+     */
+    .businessKeySet([...ORGANIZATION_PROVIDER_CREDENTIAL_IDENTITY_FIELDS]);
+// =============================================================================
+// USER-OWNED CREDENTIALS
+// =============================================================================
+/**
+ * The fields that IDENTIFY a credential within its OWNER.
+ *
+ * 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
+ * to disagree about what identity means.
+ */
+export const USER_PROVIDER_CREDENTIAL_IDENTITY_FIELDS = [
+    'userId',
+    'providerRef',
+    'secretSlug',
+];
+/**
+ * A PERSON's own credential toward a third party — the key they authored for themselves.
+ *
+ * ## Why this is a separate resource and not a nullable column beside the organization's
+ *
+ * Wildo's tenancy is STRUCTURAL: the contextual filter injects the scope FK by matching a field name
+ * at every schema path, so a resource belongs to exactly one primary scope. One table holding both a
+ * nullable `organizationId` and a nullable `userId` would turn that structural guarantee into a
+ * filter somebody has to remember to write, on the one resource where forgetting it discloses a
+ * credential. Two resources, each scoped by construction, is the framework working as designed
+ * rather than a duplication.
+ *
+ * ## Not a delegated OAuth grant, and the difference is not subtle
+ *
+ * This is a key the user PASTED: they hold an account with the vendor and chose to let this
+ * application spend it. A delegated grant is the vendor minting a token because the user approved a
+ * consent screen, and it carries a refresh loop, an expiry and a revocation the vendor also honours.
+ * Merging them would give one row two lifecycles and two revocation semantics — see #333, which owns
+ * the second.
+ *
+ * ## Only the holder may spend it
+ *
+ * Not an administrator of their organization, and not a platform operator. Consent to STORE a
+ * personal key is not consent for somebody else to use it, and the vendor would record the act as
+ * the holder's own. The authorization side of that is
+ * `InitiatorMembershipConnectionTargetAuthorization`; this schema is what makes the row reachable
+ * only through the owner's own scope.
+ */
+export const UserProviderCredentialSchema = z.object({
+    _id: z.string().min(1).isPrimaryKey().isSummaryField(),
+    /**
+     * The person who owns this credential. Injected by the context machinery from the authenticated
+     * scope, never from a caller-supplied field — the same structural isolation the organization-owned
+     * 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. */
+    providerRef: z.string().min(1).max(200).isDBIndexed().isSummaryField().excludeFromUpdate(),
+    /** The slug in the provider's `secretsContract` this value satisfies. Immutable, for the same
+     * reason as the sibling: re-pointing a stored secret at a different slug would hand one vendor
+     * credential to a different vendor field. */
+    secretSlug: z.string().min(1).max(200).isDBIndexed().isSummaryField().excludeFromUpdate(),
+    /**
+     * The credential, SEALED — an AES-256-GCM envelope bound to this row's identity, never plaintext.
+     *
+     * `.isWriteOnlySecret()` for the same reason as the sibling: the holder supplies and rotates it, so
+     * it must survive into the CREATE/UPDATE request DTO, and the framework masks it at the client
+     * boundary so no read ever returns it.
+     */
+    secretValue: z.string().min(1).isWriteOnlySecret(),
+    enabled: z.boolean().default(true).isDBIndexed().isSummaryField(),
+    validationState: z
+        .enum(ProviderCredentialValidationState)
+        .default(ProviderCredentialValidationState.UNVALIDATED)
+        .isDBIndexed()
+        .isSummaryField(),
+    /** 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(),
+    lastValidatedAt: z.date().optional().excludeFromCreate().excludeFromUpdate(),
+    lastUsedAt: z.date().optional().isDBIndexed().excludeFromCreate().excludeFromUpdate(),
+    /** When the stored VALUE last changed — distinct from `updatedAt`, which any field write moves. */
+    secretSetAt: z.date().optional().excludeFromCreate().excludeFromUpdate(),
+    /** The holder's own note. Never a place for the value; enforced by the write-path pins. */
+    /**
+     * Answers for the `{placeholder}` holes this provider's OAuth2 endpoints carry — which cloud,
+     * which directory, which region.
+     *
+     * On the ROW rather than only in the connect flow, because a REFRESH needs them again. The
+     * authorization record that held them lives ten minutes; the token it produced is renewed for as
+     * long as the connection lasts, and a templated token URL is still templated an hour later.
+     * Without them here, every one of the 21 vendors whose endpoints carry a placeholder — Microsoft,
+     * Azure, and everything regional — would connect successfully and then fail its first renewal with
+     * `needs a value for 'cloud'`: the exact failure the placeholder machinery exists to prevent, one
+     * layer up.
+     *
+     * NOT secret, and deliberately client-readable: a tenant id is an identifier a person needs to see
+     * to recognise which account they connected. The secret half is the grant, and it is sealed.
+     *
+     * `.excludeFromUpdate()` — chosen at connect time, and they describe the ACCOUNT the grant is for.
+     * Changing them under a live grant would point the refresh at a different directory than the one
+     * that issued the token, failing at the vendor with nothing local explaining why. Reconnecting is
+     * the honest way to change them.
+     */
+    connectionParameters: z.record(z.string(), z.string()).optional().excludeFromUpdate(),
+    description: z.string().max(500).optional(),
+    createdAt: z.date().default(() => new Date()).isDBIndexed().isSummaryField().excludeFromCreate().excludeFromUpdate(),
+    updatedAt: z.date().default(() => new Date()).isDBIndexed().excludeFromCreate().excludeFromUpdate(),
+})
+    /**
+     * One credential per person per (provider, slug), enforced by a compound UNIQUE index rather than
+     * 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.
+     */
+    .businessKeySet([...USER_PROVIDER_CREDENTIAL_IDENTITY_FIELDS]);
+// ══════════════════════════════════════════════════════════════════════════════════════════════
+// OAUTH2 GRANTS
+//
+// A credential a vendor MINTS rather than one a person pastes. It rides in the same `secretValue`
+// field of the same two resources — sealed, as JSON — and that reuse is deliberate.
+//
+// ## Why the same rows rather than a third resource
+//
+// The identity is the same triple (owner, providerRef, 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.
+//
+// Note this is the OPPOSITE call from the one that split USER from ORGANIZATION, and the difference
+// is what makes both right: there the TENANCY differed, and tenancy in this framework is structural
+// — one table with a nullable owner would turn a structural guarantee into a filter somebody must
+// remember to write. Here nothing about ownership changes; a string becomes an object.
+// ══════════════════════════════════════════════════════════════════════════════════════════════
+/**
+ * What an authorization exchange gives back, as it is stored.
+ *
+ * Sealed as JSON into `secretValue`, so `.isWriteOnlySecret()` keeps masking it at the client
+ * boundary and the envelope keeps binding it to its row — both mechanisms work on a string and
+ * neither needs to know the string is structured.
+ */
+/**
+ * What SHAPE a sealed credential holds, once opened.
+ *
+ * One member today and a named vocabulary anyway, because the day a second sealed payload exists —
+ * a service-account key, a signed JWT assertion — the discriminant is what tells them apart, and a
+ * bare literal is where per-member explanation cannot live. It is also the value a reader needs to
+ * understand `PROVIDER_OAUTH2_GRANT_PREFIX`: the prefix is how the shape is recognised WITHOUT
+ * parsing, and this is what it recognises.
+ */
+/**
+ * Why a provider cannot be connected HERE, even though the vendor is in the catalogue.
+ *
+ * "Connectable" is a property of the DEPLOYMENT and not of the vendor, and conflating the two put a
+ * Connect button on a screen that could only ever fail. Asana supports OAuth2 perfectly well; this
+ * application has simply never registered with Asana, and no amount of pressing the button changes
+ * that.
+ *
+ * The two members lead to different actions by different people, which is the whole reason they are
+ * distinguished rather than collapsed into a boolean.
+ */
+/**
+ * HOW a connection to a provider is established — the shape of the act, which decides the screen.
+ *
+ * A connect surface cannot be one form. Granting consent at a vendor and typing a key are different
+ * acts with different inputs and different failure modes, and a screen that offered one button for
+ * both would be wrong for whichever it was not built around.
+ */
+export var ProviderAuthMethod;
+(function (ProviderAuthMethod) {
+    /** The authorization-code round trip: leave, consent at the vendor, come back with a grant. */
+    ProviderAuthMethod["OAUTH2_AUTHORIZATION_CODE"] = "oauth2-authorization-code";
+    /**
+     * A value somebody holds and types — an API key, a personal access token. The fields are DECLARED
+     * by the provider's secrets contract, so a screen names them rather than asking for a slug.
+     */
+    ProviderAuthMethod["DECLARED_SECRET"] = "declared-secret";
+})(ProviderAuthMethod || (ProviderAuthMethod = {}));
+export var ProviderConnectabilityBlocker;
+(function (ProviderConnectabilityBlocker) {
+    /**
+     * The vendor has no authorization flow in the catalogue: its credential is PASTED, not granted.
+     * Nothing is missing and nothing is broken — this provider is authored on the credential screen
+     * instead, and an application author is the one who acts.
+     */
+    ProviderConnectabilityBlocker["NO_AUTHORIZATION_FLOW"] = "no-authorization-flow";
+    /**
+     * The vendor has a flow and THIS DEPLOYMENT has not registered with it — no client id, or no client
+     * secret. An OPERATOR acts: register an application with the vendor and set the two environment
+     * variables the provider's contract names. Distinct from the above because the vendor is perfectly
+     * connectable and the gap is ours.
+     */
+    ProviderConnectabilityBlocker["APPLICATION_NOT_REGISTERED"] = "application-not-registered";
+})(ProviderConnectabilityBlocker || (ProviderConnectabilityBlocker = {}));
+export var ProviderStoredCredentialKind;
+(function (ProviderStoredCredentialKind) {
+    /** An OAuth2 grant: an access token, and what is needed to renew it. */
+    ProviderStoredCredentialKind["OAUTH2_GRANT"] = "oauth2-grant";
+})(ProviderStoredCredentialKind || (ProviderStoredCredentialKind = {}));
+export const ProviderOAuth2GrantSchema = z.object({
+    /**
+     * A discriminant, so an opened envelope announces which shape it is.
+     *
+     * Without it the reader would have to guess from whether the plaintext parses as JSON — and a
+     * pasted credential that happens to be JSON (a service-account key, which several vendors issue
+     * exactly that way) would be misread as a grant. A guess that is right almost always is the worst
+     * kind here, because the failure is a malformed Authorization header on somebody else's account.
+     */
+    kind: z.literal(ProviderStoredCredentialKind.OAUTH2_GRANT),
+    /** The token that actually goes on the wire. */
+    accessToken: z.string().min(1),
+    /**
+     * Present when the vendor issues one. Absent is normal and permanent for vendors that do not —
+     * Slack's bot tokens do not expire and have no refresh — so its absence must not read as an
+     * incomplete grant.
+     */
+    refreshToken: z.string().min(1).optional(),
+    /**
+     * When the access token stops being accepted, as an ISO instant.
+     *
+     * Optional because a non-expiring token genuinely has none. A grant with a refresh token and no
+     * expiry is refreshed only after the vendor rejects it, which is correct but slower than
+     * refreshing ahead of a known deadline.
+     */
+    expiresAt: z.iso.datetime().optional(),
+    /**
+     * What the vendor actually GRANTED, which is not always what was asked for.
+     *
+     * Recorded because the difference is invisible until a call fails: a vendor may issue a token for
+     * a subset of the requested scopes, and the resulting `missing_scope` arrives on an unrelated
+     * operation weeks later. Holding the granted set lets that be answered from the row.
+     */
+    grantedScopes: z.array(z.string()).optional(),
+    /**
+     * The vendor's own identifier for the account this grant is on — a Slack team id, a Google sub, a
+     * Microsoft tenant id.
+     *
+     * Not used for lookup and deliberately not part of the row's identity. It exists so a person
+     * reading their connections can tell WHICH account they connected, which a provider ref cannot
+     * answer for anyone who has two.
+     */
+    accountRef: z.string().optional(),
+});
+/**
+ * The marker that opens the sealed plaintext of a grant rather than a pasted credential.
+ *
+ * A prefix on the JSON rather than a field inside it, so the decision can be made without parsing —
+ * the same reason the envelope carries a prefix. Parsing first would mean feeding an arbitrary
+ * pasted credential to `JSON.parse` on every resolution.
+ */
+export const PROVIDER_OAUTH2_GRANT_PREFIX = 'wildo-oauth2-grant:';
+/** Whether an OPENED credential is a grant. Cheap, and does not parse. */
+export function isProviderOAuth2GrantPlaintext(plaintext) {
+    return plaintext.startsWith(PROVIDER_OAUTH2_GRANT_PREFIX);
+}
+/** Render a grant for sealing. The inverse of {@link parseProviderOAuth2Grant}. */
+export function serializeProviderOAuth2Grant(grant) {
+    return `${PROVIDER_OAUTH2_GRANT_PREFIX}${JSON.stringify(grant)}`;
+}
+/**
+ * Read a grant back, or `undefined` when the plaintext is an ordinary pasted credential.
+ *
+ * THROWS when the value announces itself as a grant and then does not parse or does not validate.
+ * That is the same posture the envelope takes toward a value the write path could not have
+ * produced: a credential which claims a shape it does not have is a fault worth failing on, never
+ * one worth falling back from — falling back would put a JSON blob on the wire as a bearer token.
+ */
+export function parseProviderOAuth2Grant(plaintext) {
+    if (!isProviderOAuth2GrantPlaintext(plaintext))
+        return undefined;
+    const body = plaintext.slice(PROVIDER_OAUTH2_GRANT_PREFIX.length);
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        throw new Error('A stored provider credential announces itself as an OAuth2 grant and is not valid JSON. It was '
+            + 'written by something other than the authorization exchange; reconnect the account.');
+    }
+    const result = ProviderOAuth2GrantSchema.safeParse(parsed);
+    if (!result.success) {
+        throw new Error('A stored provider credential announces itself as an OAuth2 grant but does not match the grant '
+            + 'shape. Reconnect the account rather than editing the row — the value on the wire would '
+            + 'otherwise be a fragment of a token.');
+    }
+    return result.data;
+}
+/**
+ * Whether a grant should be refreshed BEFORE it is spent.
+ *
+ * The skew is what makes this useful rather than decorative: a token that expires in two seconds is
+ * still "valid" and will have expired by the time the request reaches the vendor, so refreshing only
+ * on expiry guarantees a population of calls that fail for a reason nothing recorded. Sixty seconds
+ * is the industry's common floor and comfortably exceeds any plausible clock skew plus flight time.
+ *
+ * Returns false when there is no expiry — a non-expiring token is refreshed reactively, after the
+ * vendor rejects it, because there is no deadline to act ahead of.
+ */
+export const PROVIDER_OAUTH2_REFRESH_SKEW_SECONDS = 60;
+export function providerOAuth2GrantNeedsRefresh(grant, now = new Date()) {
+    if (grant.expiresAt === undefined)
+        return false;
+    const expiry = Date.parse(grant.expiresAt);
+    if (Number.isNaN(expiry))
+        return true;
+    return expiry - now.getTime() <= PROVIDER_OAUTH2_REFRESH_SKEW_SECONDS * 1000;
+}
+//# sourceMappingURL=provider-credentials.shared.schemas.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"provider-credentials.shared.schemas.js","sourceRoot":"","sources":["../../../../src/security/connected-accounts/provider-credentials.shared.schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;;GAOG;AACH,MAAM,CAAN,IAAY,iCAOX;AAPD,WAAY,iCAAiC;IAC3C,0FAA0F;IAC1F,gEAA2B,CAAA;IAC3B,gDAAgD;IAChD,oDAAe,CAAA;IACf,8EAA8E;IAC9E,wDAAmB,CAAA;AACrB,CAAC,EAPW,iCAAiC,KAAjC,iCAAiC,QAO5C;AAED;;;;;;;;;;;GAWG;AACH;;;;;;;;GAQG;AACH,MAAM,CAAN,IAAY,kCAmBX;AAnBD,WAAY,kCAAkC;IAC5C,yEAAyE;IACzE,yFAAmD,CAAA;IACnD;;;OAGG;IACH,uFAAiD,CAAA;IACjD;;;;;;;;;OASG;IACH,yEAAmC,CAAA;AACrC,CAAC,EAnBW,kCAAkC,KAAlC,kCAAkC,QAmB7C;AAED,6CAA6C;AAC7C,MAAM,CAAN,IAAY,gCAeX;AAfD,WAAY,gCAAgC;IAC1C,wDAAwD;IACxD,mFAA+C,CAAA;IAC/C,iGAAiG;IACjG,+EAA2C,CAAA;IAC3C,gEAAgE;IAChE,mEAA+B,CAAA;IAC/B;;;;;;OAMG;IACH,+DAA2B,CAAA;AAC7B,CAAC,EAfW,gCAAgC,KAAhC,gCAAgC,QAe3C;AAED;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,gDAAgD,GAAG;IAC9D,gBAAgB;IAChB,aAAa;IACb,YAAY;CACJ,CAAC;AAEX,MAAM,CAAC,MAAM,oCAAoC,GAAG,CAAC,CAAC,MAAM,CAAC;IAC3D,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,EAAE,CAAC,cAAc,EAAE;IAEtD;;;;OAIG;IACH,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,YAAY,EAAE,CAAC,cAAc,EAAE,CAAC,iBAAiB,EAAE;IAEnG;;;;;OAKG;IACH,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC,cAAc,EAAE,CAAC,iBAAiB,EAAE;IAE1F;;;;;OAKG;IACH,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC,cAAc,EAAE,CAAC,iBAAiB,EAAE;IAEzF;;;;;;;;;;;;;OAaG;IACH,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,iBAAiB,EAAE;IAElD;;;OAGG;IACH,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC,cAAc,EAAE;IAEjE,eAAe,EAAE,CAAC;SACf,IAAI,CAAC,iCAAiC,CAAC;SACvC,OAAO,CAAC,iCAAiC,CAAC,WAAW,CAAC;SACtD,WAAW,EAAE;SACb,cAAc,EAAE;IAEnB;;;;OAIG;IACH,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC,iBAAiB,EAAE,CAAC,iBAAiB,EAAE;IAEvF,eAAe,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,QAAQ,EAAE,CAAC,iBAAiB,EAAE,CAAC,iBAAiB,EAAE;IAC5E,UAAU,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,QAAQ,EAAE,CAAC,WAAW,EAAE,CAAC,iBAAiB,EAAE,CAAC,iBAAiB,EAAE;IAErF;;;;;;;;OAQG;IACH,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,WAAW,EAAE,CAAC,iBAAiB,EAAE,CAAC,iBAAiB,EAAE;IAE/F,mGAAmG;IACnG,WAAW,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,QAAQ,EAAE,CAAC,iBAAiB,EAAE,CAAC,iBAAiB,EAAE;IAExE,6FAA6F;IAC7F;;;;;;;;;;;;;;;;;;;OAmBG;IACH,oBAAoB,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,iBAAiB,EAAE;IAGrF,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;IAE3C,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,cAAc,EAAE,CAAC,iBAAiB,EAAE,CAAC,iBAAiB,EAAE;IACpH,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,iBAAiB,EAAE,CAAC,iBAAiB,EAAE;CACpG,CAAC;IACA;;;;;;;;;;;;OAYG;KACF,cAAc,CAAC,CAAC,GAAG,gDAAgD,CAAC,CAAC,CAAC;AAMzE,gFAAgF;AAChF,yBAAyB;AACzB,gFAAgF;AAEhF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,wCAAwC,GAAG;IACtD,QAAQ;IACR,aAAa;IACb,YAAY;CACJ,CAAC;AAEX;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAAC,CAAC,MAAM,CAAC;IACnD,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,EAAE,CAAC,cAAc,EAAE;IAEtD;;;;OAIG;IACH,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,YAAY,EAAE,CAAC,cAAc,EAAE,CAAC,iBAAiB,EAAE;IAE3F,iGAAiG;IACjG,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC,cAAc,EAAE,CAAC,iBAAiB,EAAE;IAE1F;;iDAE6C;IAC7C,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC,cAAc,EAAE,CAAC,iBAAiB,EAAE;IAEzF;;;;;;OAMG;IACH,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,iBAAiB,EAAE;IAElD,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC,cAAc,EAAE;IAEjE,eAAe,EAAE,CAAC;SACf,IAAI,CAAC,iCAAiC,CAAC;SACvC,OAAO,CAAC,iCAAiC,CAAC,WAAW,CAAC;SACtD,WAAW,EAAE;SACb,cAAc,EAAE;IAEnB;wCACoC;IACpC,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC,iBAAiB,EAAE,CAAC,iBAAiB,EAAE;IAEvF,eAAe,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,QAAQ,EAAE,CAAC,iBAAiB,EAAE,CAAC,iBAAiB,EAAE;IAC5E,UAAU,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,QAAQ,EAAE,CAAC,WAAW,EAAE,CAAC,iBAAiB,EAAE,CAAC,iBAAiB,EAAE;IAErF,mGAAmG;IACnG,WAAW,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,QAAQ,EAAE,CAAC,iBAAiB,EAAE,CAAC,iBAAiB,EAAE;IAExE,2FAA2F;IAC3F;;;;;;;;;;;;;;;;;;;OAmBG;IACH,oBAAoB,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,iBAAiB,EAAE;IAGrF,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,QAAQ,EAAE;IAE3C,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,cAAc,EAAE,CAAC,iBAAiB,EAAE,CAAC,iBAAiB,EAAE;IACpH,SAAS,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,WAAW,EAAE,CAAC,iBAAiB,EAAE,CAAC,iBAAiB,EAAE;CACpG,CAAC;IACA;;;;;OAKG;KACF,cAAc,CAAC,CAAC,GAAG,wCAAwC,CAAC,CAAC,CAAC;AAKjE,iGAAiG;AACjG,gBAAgB;AAChB,EAAE;AACF,kGAAkG;AAClG,oFAAoF;AACpF,EAAE;AACF,oDAAoD;AACpD,EAAE;AACF,oGAAoG;AACpG,mGAAmG;AACnG,oGAAoG;AACpG,2EAA2E;AAC3E,EAAE;AACF,oGAAoG;AACpG,oGAAoG;AACpG,kGAAkG;AAClG,uFAAuF;AACvF,iGAAiG;AAEjG;;;;;;GAMG;AACH;;;;;;;;GAQG;AACH;;;;;;;;;;GAUG;AACH;;;;;;GAMG;AACH,MAAM,CAAN,IAAY,kBAQX;AARD,WAAY,kBAAkB;IAC5B,+FAA+F;IAC/F,6EAAuD,CAAA;IACvD;;;OAGG;IACH,yDAAmC,CAAA;AACrC,CAAC,EARW,kBAAkB,KAAlB,kBAAkB,QAQ7B;AAED,MAAM,CAAN,IAAY,6BAcX;AAdD,WAAY,6BAA6B;IACvC;;;;OAIG;IACH,gFAA+C,CAAA;IAC/C;;;;;OAKG;IACH,0FAAyD,CAAA;AAC3D,CAAC,EAdW,6BAA6B,KAA7B,6BAA6B,QAcxC;AAkBD,MAAM,CAAN,IAAY,4BAGX;AAHD,WAAY,4BAA4B;IACtC,wEAAwE;IACxE,6DAA6B,CAAA;AAC/B,CAAC,EAHW,4BAA4B,KAA5B,4BAA4B,QAGvC;AAED,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,MAAM,CAAC;IAChD;;;;;;;OAOG;IACH,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,4BAA4B,CAAC,YAAY,CAAC;IAE1D,gDAAgD;IAChD,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAE9B;;;;OAIG;IACH,YAAY,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,EAAE;IAE1C;;;;;;OAMG;IACH,SAAS,EAAE,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE;IAEtC;;;;;;OAMG;IACH,aAAa,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;IAE7C;;;;;;;OAOG;IACH,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAClC,CAAC,CAAC;AAIH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,qBAAqB,CAAC;AAElE,0EAA0E;AAC1E,MAAM,UAAU,8BAA8B,CAAC,SAAiB;IAC9D,OAAO,SAAS,CAAC,UAAU,CAAC,4BAA4B,CAAC,CAAC;AAC5D,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,4BAA4B,CAAC,KAA0B;IACrE,OAAO,GAAG,4BAA4B,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,EAAE,CAAC;AACnE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,wBAAwB,CAAC,SAAiB;IACxD,IAAI,CAAC,8BAA8B,CAAC,SAAS,CAAC;QAAE,OAAO,SAAS,CAAC;IACjE,MAAM,IAAI,GAAG,SAAS,CAAC,KAAK,CAAC,4BAA4B,CAAC,MAAM,CAAC,CAAC;IAClE,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CACb,iGAAiG;cAC/F,oFAAoF,CACvF,CAAC;IACJ,CAAC;IACD,MAAM,MAAM,GAAG,yBAAyB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IAC3D,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,MAAM,IAAI,KAAK,CACb,gGAAgG;cAC9F,yFAAyF;cACzF,qCAAqC,CACxC,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,oCAAoC,GAAG,EAAE,CAAC;AAEvD,MAAM,UAAU,+BAA+B,CAAC,KAA0B,EAAE,MAAY,IAAI,IAAI,EAAE;IAChG,IAAI,KAAK,CAAC,SAAS,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IAChD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IAC3C,IAAI,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IACtC,OAAO,MAAM,GAAG,GAAG,CAAC,OAAO,EAAE,IAAI,oCAAoC,GAAG,IAAI,CAAC;AAC/E,CAAC","sourcesContent":["/**\n * Organization Provider Credentials — shared schemas.\n *\n * ## What this resource is, and what it is NOT\n *\n * It is an ORGANIZATION's OWN credential toward a third party: the Slack workspace token, the CRM\n * API key, the SMTP password that belongs to THAT tenant. The organization is the third-party\n * principal, and the credential is a service credential the tenant's administrator supplies.\n *\n * It is NOT a user's delegated OAuth grant. A delegated grant is a different object with a\n * different lifetime (a refresh loop, a revocation the USER can perform, a consent record) and it\n * lands as `connected accounts` beside this file — see issue #333. Merging the two would give one\n * row two owners and two revocation semantics.\n *\n * ## Why it has to exist\n *\n * Before this resource, every provider secret resolved from `process.env` through the\n * `SecretsContract`, so a credential was per-PROCESS and per-DEPLOYMENT. One application serving\n * many organizations therefore had ONE Slack token for all of them, and the failure was silent in\n * the worst direction: an operator sets one key and every tenant thereafter acts as the SAME\n * third-party principal, with nothing anywhere saying so.\n *\n * ## The value is sealed, and this file is where that is stated\n *\n * `secretValue` holds an AES-256-GCM envelope, never the plaintext an operator typed. The seal is\n * applied on the way in and opened only by the resolver — see\n * `provider-credential-envelope.backend.utils.ts` for the envelope and its key derivation. The\n * schema cannot enforce that (a string is a string), so the write path is what guarantees it and\n * the pins are what keep it guaranteed.\n */\n\nimport { z } from 'zod';\n\n/**\n * Whether the stored credential has been shown to work against the provider.\n *\n * A closed vocabulary rather than a boolean because \"we have never tried\" and \"we tried and it\n * failed\" are different states with different operator actions, and a boolean would merge them\n * into the same falsy answer. `UNVALIDATED` is the honest default: storing a credential proves\n * only that somebody typed one.\n */\nexport enum ProviderCredentialValidationState {\n  /** Stored, never exercised against the provider. The state every credential starts in. */\n  UNVALIDATED = 'unvalidated',\n  /** The provider accepted it on its last use. */\n  VALID = 'valid',\n  /** The provider rejected it on its last use — the operator must rotate it. */\n  INVALID = 'invalid',\n}\n\n/**\n * The organization's credential for one (provider, secret slug) pair.\n *\n * ## The scope identifier is TOP-LEVEL and stays that way\n *\n * `organizationId` is the only `organizationId`-named path in this schema, and nothing nested may\n * ever be named `organizationId` or `userId`. `buildContextualFilter` injects the scope FK by\n * matching that field name at EVERY schema path, so a nested key of the same name adds a phantom\n * exact-subdocument clause and the scoped read silently matches zero rows — a credential that\n * exists and cannot be resolved, which reads exactly like a credential that was never set.\n * `setByUserId` is deliberately spelled so it cannot be caught by that matcher.\n */\n/**\n * WHERE a resolved provider secret came from.\n *\n * The whole point of this slice is that the answer used to be unanswerable: every secret came from\n * `process.env`, so \"which principal did this tenant act as?\" had one answer for every tenant and\n * nothing recorded it. Making the source an explicit, closed value means an audit reader can see a\n * tenant falling back to the shared deployment credential — the exact condition the resource exists\n * to make visible — instead of having to infer it from an absence.\n */\nexport enum ProviderCredentialResolutionSource {\n  /** The organization's own credential row. The tenant acted as itself. */\n  ORGANIZATION_CREDENTIAL = 'organization_credential',\n  /**\n   * The deployment's env-projected `SecretsContract`. Legitimate — a single-tenant deployment, or a\n   * provider the operator intends every tenant to share — but never silent.\n   */\n  DEPLOYMENT_ENVIRONMENT = 'deployment_environment',\n  /**\n   * A PERSON's own credential row. The application acted as that individual.\n   *\n   * This member has no sibling fallback, and that asymmetry is deliberate rather than an omission.\n   * An organization with no credential of its own may legitimately fall through to the deployment's\n   * — an operator can intend every tenant to share one integration. A person cannot: the vendor\n   * attributes the act to whoever's token was spent, so acting for someone under the deployment's\n   * principal would put the wrong name on the record that outlives us. A person who has connected\n   * nothing gets a refusal, not a substitute.\n   */\n  USER_CREDENTIAL = 'user_credential',\n}\n\n/** Why a credential row stopped existing. */\nexport enum ProviderCredentialDeletionReason {\n  /** An administrator of the owning tenant removed it. */\n  ADMINISTRATOR_REVOKED = 'administrator_revoked',\n  /** The owning organization was purged and the composition cascade removed it with the tenant. */\n  ORGANIZATION_PURGED = 'organization_purged',\n  /** The person whose credential it was removed it themselves. */\n  OWNER_REVOKED = 'owner_revoked',\n  /**\n   * The owning user was erased and the composition cascade destroyed it with them.\n   *\n   * Distinct from `ORGANIZATION_PURGED` because this one is EVIDENCE: it is what an operator points\n   * at when asked whether a subject-erasure request reached the person's third-party credentials.\n   * Collapsing the two into a generic \"cascade\" would make that question unanswerable from the trail.\n   */\n  USER_ERASED = 'user_erased',\n}\n\n/**\n * The fields that IDENTIFY a credential within its tenant.\n *\n * One tenant holds at most one credential per (provider, slug). Exported rather than repeated so\n * the uniqueness contract, the resolver's lookup and the tests cannot drift apart — three copies\n * of a compound key is how two of them come to disagree about what identity means.\n */\nexport const ORGANIZATION_PROVIDER_CREDENTIAL_IDENTITY_FIELDS = [\n  'organizationId',\n  'providerRef',\n  'secretSlug',\n] as const;\n\nexport const OrganizationProviderCredentialSchema = z.object({\n  _id: z.string().min(1).isPrimaryKey().isSummaryField(),\n\n  /**\n   * The tenant that owns this credential. Injected by the context machinery from the request\n   * scope, never from a caller-supplied field — which is what makes the isolation structural\n   * rather than a filter somebody has to remember to write.\n   */\n  organizationId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate(),\n\n  /**\n   * The provider this credential authenticates toward (`slack`, `stripe`, a generated package's\n   * ref). An OPEN string, matching `ProviderRef`'s own openness — the whole point of the provider\n   * work is that the set is not closed, so a closed enum here would refuse every generated\n   * provider.\n   */\n  providerRef: z.string().min(1).max(200).isDBIndexed().isSummaryField().excludeFromUpdate(),\n\n  /**\n   * The slug in the provider's `secretsContract` that this value satisfies — the same identifier\n   * the deployment's env projection carries, so the two resolution places name the same thing.\n   * Immutable: re-pointing a stored secret at a different slug would silently hand one vendor\n   * credential to a different vendor field.\n   */\n  secretSlug: z.string().min(1).max(200).isDBIndexed().isSummaryField().excludeFromUpdate(),\n\n  /**\n   * The credential, SEALED.\n   *\n   * `.isWriteOnlySecret()` is the framework's write-then-masked contract and is exactly right\n   * here: the operator supplies and rotates the value, so it must stay in the CREATE/UPDATE\n   * request DTO; the framework redacts it to a placeholder at the client boundary, so no read\n   * ever returns it; and the backend keeps the stored content for its own resolution.\n   *\n   * `.isBackendOnly()` was rejected — it strips the field from the client DTO, so the operator's\n   * typed value is dropped before it is ever stored and the surface silently accepts nothing.\n   *\n   * What is PERSISTED is the envelope, never the plaintext. The write path seals it; a value that\n   * reaches persistence unsealed is a defect, not a tolerated legacy shape.\n   */\n  secretValue: z.string().min(1).isWriteOnlySecret(),\n\n  /**\n   * Whether this credential may be spent. An operator can park a credential without deleting it —\n   * which matters during an incident, where deleting is not reversible and disabling is.\n   */\n  enabled: z.boolean().default(true).isDBIndexed().isSummaryField(),\n\n  validationState: z\n    .enum(ProviderCredentialValidationState)\n    .default(ProviderCredentialValidationState.UNVALIDATED)\n    .isDBIndexed()\n    .isSummaryField(),\n\n  /**\n   * Why the last use failed, when it did. PROVIDER-supplied text about the CREDENTIAL's status —\n   * never the credential. A resolver writing anything derived from `secretValue` here would defeat\n   * every other precaution in this file, because this field IS client-readable.\n   */\n  validationError: z.string().max(500).optional().excludeFromCreate().excludeFromUpdate(),\n\n  lastValidatedAt: z.date().optional().excludeFromCreate().excludeFromUpdate(),\n  lastUsedAt: z.date().optional().isDBIndexed().excludeFromCreate().excludeFromUpdate(),\n\n  /**\n   * WHO set it — the acting user's id, recorded for the audit trail.\n   *\n   * Deliberately NOT a registered `USERS` relationship. Declaring that edge would put a CREDENTIAL\n   * row on the Art. 15 subject-export graph, and a credential is precisely the class of row that\n   * must never reach a data subject. The id is recorded because \"who set this\" is the first\n   * question of any credential incident; the edge is withheld because the answer must not travel\n   * with a subject export.\n   */\n  setByUserId: z.string().min(1).optional().isDBIndexed().excludeFromCreate().excludeFromUpdate(),\n\n  /** When the stored VALUE last changed — distinct from `updatedAt`, which any field write moves. */\n  secretSetAt: z.date().optional().excludeFromCreate().excludeFromUpdate(),\n\n  /** Free-text operator note. Never a place for the value; enforced by the write-path pins. */\n  /**\n   * Answers for the `{placeholder}` holes this provider's OAuth2 endpoints carry — which cloud,\n   * which directory, which region.\n   *\n   * On the ROW rather than only in the connect flow, because a REFRESH needs them again. The\n   * authorization record that held them lives ten minutes; the token it produced is renewed for as\n   * long as the connection lasts, and a templated token URL is still templated an hour later.\n   * Without them here, every one of the 21 vendors whose endpoints carry a placeholder — Microsoft,\n   * Azure, and everything regional — would connect successfully and then fail its first renewal with\n   * `needs a value for 'cloud'`: the exact failure the placeholder machinery exists to prevent, one\n   * layer up.\n   *\n   * NOT secret, and deliberately client-readable: a tenant id is an identifier a person needs to see\n   * to recognise which account they connected. The secret half is the grant, and it is sealed.\n   *\n   * `.excludeFromUpdate()` — chosen at connect time, and they describe the ACCOUNT the grant is for.\n   * Changing them under a live grant would point the refresh at a different directory than the one\n   * that issued the token, failing at the vendor with nothing local explaining why. Reconnecting is\n   * the honest way to change them.\n   */\n  connectionParameters: z.record(z.string(), z.string()).optional().excludeFromUpdate(),\n\n\n  description: z.string().max(500).optional(),\n\n  createdAt: z.date().default(() => new Date()).isDBIndexed().isSummaryField().excludeFromCreate().excludeFromUpdate(),\n  updatedAt: z.date().default(() => new Date()).isDBIndexed().excludeFromCreate().excludeFromUpdate(),\n})\n  /**\n   * One credential per tenant per (provider, slug), enforced by a compound UNIQUE index rather\n   * than by a read-then-write.\n   *\n   * The race it closes is not academic: two administrators saving a rotated Slack token in the\n   * same minute would otherwise leave two rows, and the resolver would then pick one of them\n   * arbitrarily — so half the tenant's outbound calls would carry the old credential and nobody\n   * could tell which half.\n   *\n   * No `customMessageReference`: that option exists so an integrator can tell WHICH identity a\n   * duplicate violated, and this resource declares exactly one. A dedicated reference here would\n   * disambiguate nothing.\n   */\n  .businessKeySet([...ORGANIZATION_PROVIDER_CREDENTIAL_IDENTITY_FIELDS]);\n\nexport type OrganizationProviderCredential = z.infer<typeof OrganizationProviderCredentialSchema>;\n\n\n\n// =============================================================================\n// USER-OWNED CREDENTIALS\n// =============================================================================\n\n/**\n * The fields that IDENTIFY a credential within its OWNER.\n *\n * Exported per owner rather than shared, because the compound key differs in its first component and\n * a single constant would have to be assembled by each side — which is how two copies of a key come\n * to disagree about what identity means.\n */\nexport const USER_PROVIDER_CREDENTIAL_IDENTITY_FIELDS = [\n  'userId',\n  'providerRef',\n  'secretSlug',\n] as const;\n\n/**\n * A PERSON's own credential toward a third party — the key they authored for themselves.\n *\n * ## Why this is a separate resource and not a nullable column beside the organization's\n *\n * Wildo's tenancy is STRUCTURAL: the contextual filter injects the scope FK by matching a field name\n * at every schema path, so a resource belongs to exactly one primary scope. One table holding both a\n * nullable `organizationId` and a nullable `userId` would turn that structural guarantee into a\n * filter somebody has to remember to write, on the one resource where forgetting it discloses a\n * credential. Two resources, each scoped by construction, is the framework working as designed\n * rather than a duplication.\n *\n * ## Not a delegated OAuth grant, and the difference is not subtle\n *\n * This is a key the user PASTED: they hold an account with the vendor and chose to let this\n * application spend it. A delegated grant is the vendor minting a token because the user approved a\n * consent screen, and it carries a refresh loop, an expiry and a revocation the vendor also honours.\n * Merging them would give one row two lifecycles and two revocation semantics — see #333, which owns\n * the second.\n *\n * ## Only the holder may spend it\n *\n * Not an administrator of their organization, and not a platform operator. Consent to STORE a\n * personal key is not consent for somebody else to use it, and the vendor would record the act as\n * the holder's own. The authorization side of that is\n * `InitiatorMembershipConnectionTargetAuthorization`; this schema is what makes the row reachable\n * only through the owner's own scope.\n */\nexport const UserProviderCredentialSchema = z.object({\n  _id: z.string().min(1).isPrimaryKey().isSummaryField(),\n\n  /**\n   * The person who owns this credential. Injected by the context machinery from the authenticated\n   * scope, never from a caller-supplied field — the same structural isolation the organization-owned\n   * sibling relies on, which is what makes \"another user's key\" unreachable rather than filtered.\n   */\n  userId: z.string().min(1).isDBIndexed().isForeignKey().isSummaryField().excludeFromUpdate(),\n\n  /** As the organization-owned sibling: an OPEN string, because the provider set is not closed. */\n  providerRef: z.string().min(1).max(200).isDBIndexed().isSummaryField().excludeFromUpdate(),\n\n  /** The slug in the provider's `secretsContract` this value satisfies. Immutable, for the same\n   * reason as the sibling: re-pointing a stored secret at a different slug would hand one vendor\n   * credential to a different vendor field. */\n  secretSlug: z.string().min(1).max(200).isDBIndexed().isSummaryField().excludeFromUpdate(),\n\n  /**\n   * The credential, SEALED — an AES-256-GCM envelope bound to this row's identity, never plaintext.\n   *\n   * `.isWriteOnlySecret()` for the same reason as the sibling: the holder supplies and rotates it, so\n   * it must survive into the CREATE/UPDATE request DTO, and the framework masks it at the client\n   * boundary so no read ever returns it.\n   */\n  secretValue: z.string().min(1).isWriteOnlySecret(),\n\n  enabled: z.boolean().default(true).isDBIndexed().isSummaryField(),\n\n  validationState: z\n    .enum(ProviderCredentialValidationState)\n    .default(ProviderCredentialValidationState.UNVALIDATED)\n    .isDBIndexed()\n    .isSummaryField(),\n\n  /** Why the last use failed. PROVIDER text about the CREDENTIAL, never anything derived from it —\n   * this field IS client-readable. */\n  validationError: z.string().max(500).optional().excludeFromCreate().excludeFromUpdate(),\n\n  lastValidatedAt: z.date().optional().excludeFromCreate().excludeFromUpdate(),\n  lastUsedAt: z.date().optional().isDBIndexed().excludeFromCreate().excludeFromUpdate(),\n\n  /** When the stored VALUE last changed — distinct from `updatedAt`, which any field write moves. */\n  secretSetAt: z.date().optional().excludeFromCreate().excludeFromUpdate(),\n\n  /** The holder's own note. Never a place for the value; enforced by the write-path pins. */\n  /**\n   * Answers for the `{placeholder}` holes this provider's OAuth2 endpoints carry — which cloud,\n   * which directory, which region.\n   *\n   * On the ROW rather than only in the connect flow, because a REFRESH needs them again. The\n   * authorization record that held them lives ten minutes; the token it produced is renewed for as\n   * long as the connection lasts, and a templated token URL is still templated an hour later.\n   * Without them here, every one of the 21 vendors whose endpoints carry a placeholder — Microsoft,\n   * Azure, and everything regional — would connect successfully and then fail its first renewal with\n   * `needs a value for 'cloud'`: the exact failure the placeholder machinery exists to prevent, one\n   * layer up.\n   *\n   * NOT secret, and deliberately client-readable: a tenant id is an identifier a person needs to see\n   * to recognise which account they connected. The secret half is the grant, and it is sealed.\n   *\n   * `.excludeFromUpdate()` — chosen at connect time, and they describe the ACCOUNT the grant is for.\n   * Changing them under a live grant would point the refresh at a different directory than the one\n   * that issued the token, failing at the vendor with nothing local explaining why. Reconnecting is\n   * the honest way to change them.\n   */\n  connectionParameters: z.record(z.string(), z.string()).optional().excludeFromUpdate(),\n\n\n  description: z.string().max(500).optional(),\n\n  createdAt: z.date().default(() => new Date()).isDBIndexed().isSummaryField().excludeFromCreate().excludeFromUpdate(),\n  updatedAt: z.date().default(() => new Date()).isDBIndexed().excludeFromCreate().excludeFromUpdate(),\n})\n  /**\n   * One credential per person per (provider, slug), enforced by a compound UNIQUE index rather than\n   * a read-then-write — the same race the organization-owned sibling closes, and for the same\n   * reason: two rows would leave the resolver picking one arbitrarily, so half the holder's outbound\n   * calls would carry a rotated-away credential and nothing would say which half.\n   */\n  .businessKeySet([...USER_PROVIDER_CREDENTIAL_IDENTITY_FIELDS]);\n\nexport type UserProviderCredential = z.infer<typeof UserProviderCredentialSchema>;\n\n\n// ══════════════════════════════════════════════════════════════════════════════════════════════\n// OAUTH2 GRANTS\n//\n// A credential a vendor MINTS rather than one a person pastes. It rides in the same `secretValue`\n// field of the same two resources — sealed, as JSON — and that reuse is deliberate.\n//\n// ## Why the same rows rather than a third resource\n//\n// The identity is the same triple (owner, providerRef, secretSlug), the ownership semantics are the\n// same, the authorization is the same, the erasure is the same, and the resolver already routes by\n// scope. Only the PAYLOAD differs. A separate resource would duplicate every one of those and force\n// each consumer to ask \"which store?\" before it could ask anything useful.\n//\n// Note this is the OPPOSITE call from the one that split USER from ORGANIZATION, and the difference\n// is what makes both right: there the TENANCY differed, and tenancy in this framework is structural\n// — one table with a nullable owner would turn a structural guarantee into a filter somebody must\n// remember to write. Here nothing about ownership changes; a string becomes an object.\n// ══════════════════════════════════════════════════════════════════════════════════════════════\n\n/**\n * What an authorization exchange gives back, as it is stored.\n *\n * Sealed as JSON into `secretValue`, so `.isWriteOnlySecret()` keeps masking it at the client\n * boundary and the envelope keeps binding it to its row — both mechanisms work on a string and\n * neither needs to know the string is structured.\n */\n/**\n * What SHAPE a sealed credential holds, once opened.\n *\n * One member today and a named vocabulary anyway, because the day a second sealed payload exists —\n * a service-account key, a signed JWT assertion — the discriminant is what tells them apart, and a\n * bare literal is where per-member explanation cannot live. It is also the value a reader needs to\n * understand `PROVIDER_OAUTH2_GRANT_PREFIX`: the prefix is how the shape is recognised WITHOUT\n * parsing, and this is what it recognises.\n */\n/**\n * Why a provider cannot be connected HERE, even though the vendor is in the catalogue.\n *\n * \"Connectable\" is a property of the DEPLOYMENT and not of the vendor, and conflating the two put a\n * Connect button on a screen that could only ever fail. Asana supports OAuth2 perfectly well; this\n * application has simply never registered with Asana, and no amount of pressing the button changes\n * that.\n *\n * The two members lead to different actions by different people, which is the whole reason they are\n * distinguished rather than collapsed into a boolean.\n */\n/**\n * HOW a connection to a provider is established — the shape of the act, which decides the screen.\n *\n * A connect surface cannot be one form. Granting consent at a vendor and typing a key are different\n * acts with different inputs and different failure modes, and a screen that offered one button for\n * both would be wrong for whichever it was not built around.\n */\nexport enum ProviderAuthMethod {\n  /** The authorization-code round trip: leave, consent at the vendor, come back with a grant. */\n  OAUTH2_AUTHORIZATION_CODE = 'oauth2-authorization-code',\n  /**\n   * A value somebody holds and types — an API key, a personal access token. The fields are DECLARED\n   * by the provider's secrets contract, so a screen names them rather than asking for a slug.\n   */\n  DECLARED_SECRET = 'declared-secret',\n}\n\nexport enum ProviderConnectabilityBlocker {\n  /**\n   * The vendor has no authorization flow in the catalogue: its credential is PASTED, not granted.\n   * Nothing is missing and nothing is broken — this provider is authored on the credential screen\n   * instead, and an application author is the one who acts.\n   */\n  NO_AUTHORIZATION_FLOW = 'no-authorization-flow',\n  /**\n   * The vendor has a flow and THIS DEPLOYMENT has not registered with it — no client id, or no client\n   * secret. An OPERATOR acts: register an application with the vendor and set the two environment\n   * variables the provider's contract names. Distinct from the above because the vendor is perfectly\n   * connectable and the gap is ours.\n   */\n  APPLICATION_NOT_REGISTERED = 'application-not-registered',\n}\n\n/**\n * One secret slot a provider declares, as a SCREEN needs it — never the value.\n *\n * Exists so nothing is typed by hand. The slug names the field, the environment variable tells an\n * operator exactly what to set, and `configured` lets a missing one be REPORTED rather than\n * discovered by pressing a button that fails.\n */\nexport interface ProviderSecretSlotView {\n  readonly slug: string;\n  readonly envVarName: string;\n  readonly required: boolean;\n  readonly description: string;\n  /** Whether the deployment supplies it. There is deliberately no field for the value. */\n  readonly configured: boolean;\n}\n\nexport enum ProviderStoredCredentialKind {\n  /** An OAuth2 grant: an access token, and what is needed to renew it. */\n  OAUTH2_GRANT = 'oauth2-grant',\n}\n\nexport const ProviderOAuth2GrantSchema = z.object({\n  /**\n   * A discriminant, so an opened envelope announces which shape it is.\n   *\n   * Without it the reader would have to guess from whether the plaintext parses as JSON — and a\n   * pasted credential that happens to be JSON (a service-account key, which several vendors issue\n   * exactly that way) would be misread as a grant. A guess that is right almost always is the worst\n   * kind here, because the failure is a malformed Authorization header on somebody else's account.\n   */\n  kind: z.literal(ProviderStoredCredentialKind.OAUTH2_GRANT),\n\n  /** The token that actually goes on the wire. */\n  accessToken: z.string().min(1),\n\n  /**\n   * Present when the vendor issues one. Absent is normal and permanent for vendors that do not —\n   * Slack's bot tokens do not expire and have no refresh — so its absence must not read as an\n   * incomplete grant.\n   */\n  refreshToken: z.string().min(1).optional(),\n\n  /**\n   * When the access token stops being accepted, as an ISO instant.\n   *\n   * Optional because a non-expiring token genuinely has none. A grant with a refresh token and no\n   * expiry is refreshed only after the vendor rejects it, which is correct but slower than\n   * refreshing ahead of a known deadline.\n   */\n  expiresAt: z.iso.datetime().optional(),\n\n  /**\n   * What the vendor actually GRANTED, which is not always what was asked for.\n   *\n   * Recorded because the difference is invisible until a call fails: a vendor may issue a token for\n   * a subset of the requested scopes, and the resulting `missing_scope` arrives on an unrelated\n   * operation weeks later. Holding the granted set lets that be answered from the row.\n   */\n  grantedScopes: z.array(z.string()).optional(),\n\n  /**\n   * The vendor's own identifier for the account this grant is on — a Slack team id, a Google sub, a\n   * Microsoft tenant id.\n   *\n   * Not used for lookup and deliberately not part of the row's identity. It exists so a person\n   * reading their connections can tell WHICH account they connected, which a provider ref cannot\n   * answer for anyone who has two.\n   */\n  accountRef: z.string().optional(),\n});\n\nexport type ProviderOAuth2Grant = z.infer<typeof ProviderOAuth2GrantSchema>;\n\n/**\n * The marker that opens the sealed plaintext of a grant rather than a pasted credential.\n *\n * A prefix on the JSON rather than a field inside it, so the decision can be made without parsing —\n * the same reason the envelope carries a prefix. Parsing first would mean feeding an arbitrary\n * pasted credential to `JSON.parse` on every resolution.\n */\nexport const PROVIDER_OAUTH2_GRANT_PREFIX = 'wildo-oauth2-grant:';\n\n/** Whether an OPENED credential is a grant. Cheap, and does not parse. */\nexport function isProviderOAuth2GrantPlaintext(plaintext: string): boolean {\n  return plaintext.startsWith(PROVIDER_OAUTH2_GRANT_PREFIX);\n}\n\n/** Render a grant for sealing. The inverse of {@link parseProviderOAuth2Grant}. */\nexport function serializeProviderOAuth2Grant(grant: ProviderOAuth2Grant): string {\n  return `${PROVIDER_OAUTH2_GRANT_PREFIX}${JSON.stringify(grant)}`;\n}\n\n/**\n * Read a grant back, or `undefined` when the plaintext is an ordinary pasted credential.\n *\n * THROWS when the value announces itself as a grant and then does not parse or does not validate.\n * That is the same posture the envelope takes toward a value the write path could not have\n * produced: a credential which claims a shape it does not have is a fault worth failing on, never\n * one worth falling back from — falling back would put a JSON blob on the wire as a bearer token.\n */\nexport function parseProviderOAuth2Grant(plaintext: string): ProviderOAuth2Grant | undefined {\n  if (!isProviderOAuth2GrantPlaintext(plaintext)) return undefined;\n  const body = plaintext.slice(PROVIDER_OAUTH2_GRANT_PREFIX.length);\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(body);\n  } catch {\n    throw new Error(\n      'A stored provider credential announces itself as an OAuth2 grant and is not valid JSON. It was '\n      + 'written by something other than the authorization exchange; reconnect the account.',\n    );\n  }\n  const result = ProviderOAuth2GrantSchema.safeParse(parsed);\n  if (!result.success) {\n    throw new Error(\n      'A stored provider credential announces itself as an OAuth2 grant but does not match the grant '\n      + 'shape. Reconnect the account rather than editing the row — the value on the wire would '\n      + 'otherwise be a fragment of a token.',\n    );\n  }\n  return result.data;\n}\n\n/**\n * Whether a grant should be refreshed BEFORE it is spent.\n *\n * The skew is what makes this useful rather than decorative: a token that expires in two seconds is\n * still \"valid\" and will have expired by the time the request reaches the vendor, so refreshing only\n * on expiry guarantees a population of calls that fail for a reason nothing recorded. Sixty seconds\n * is the industry's common floor and comfortably exceeds any plausible clock skew plus flight time.\n *\n * Returns false when there is no expiry — a non-expiring token is refreshed reactively, after the\n * vendor rejects it, because there is no deadline to act ahead of.\n */\nexport const PROVIDER_OAUTH2_REFRESH_SKEW_SECONDS = 60;\n\nexport function providerOAuth2GrantNeedsRefresh(grant: ProviderOAuth2Grant, now: Date = new Date()): boolean {\n  if (grant.expiresAt === undefined) return false;\n  const expiry = Date.parse(grant.expiresAt);\n  if (Number.isNaN(expiry)) return true;\n  return expiry - now.getTime() <= PROVIDER_OAUTH2_REFRESH_SKEW_SECONDS * 1000;\n}\n"]}

package/dist/esm/security/oauth-clients/oauth-clients-application.shared.resources-config.schemas.d.ts

@@ -15,7 +15,8 @@ import { ResourceRelationship } from '../../resources/resources.shared.schemas';
 import { CORE_APP_ROLES } from '../authorizations/roles.shared.schemas';
 export declare enum AppOAuthClients_Operations {
     ROTATE = "rotate",// Generate new secret and invalidate old one
-    REGENERATE = "regenerate"
+    REGENERATE = "regenerate",// Generate new secret without invalidating old one
+    EXPIRE = "expire"
 }
 type AppOAuthClientsCoreOperations = CoreResourceOperation.READ | CoreResourceOperation.LIST | CoreResourceOperation.SEARCH | CoreResourceOperation.CREATE | CoreResourceOperation.DELETE;
 export declare const appOAuthClientsResourceConfiguration_InitializationFactory: (resourcesRelationships: ResourceRelationship[]) => import("../..").ResourceConfiguration<typeof AppOAuthClients_Operations, AppOAuthClientsCoreOperations, z.ZodObject<{
@@ -39,6 +40,8 @@ export declare const appOAuthClientsResourceConfiguration_InitializationFactory:
     previousHashedSecret: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodString>>>>>;
     previousSecretPrefix: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodString>>>;
     previousSecretInvalidationDate: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodDate>>>;
+    registrationAccessTokenHash: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodString>>>>>;
+    registrationAccessTokenPrefix: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodOptional<z.ZodString>>>;
     registrationOrigin: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodDefault<z.ZodEnum<typeof import("./oauth-clients.shared.schemas").OAuthClientRegistrationOrigin>>>>>>>;
     scope: z.ZodLiteral<import("../..").ApiKeyScope.APPLICATION>;
     applicationId: import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<import("@wildo-ai/zod-decorators").DecoratedPrimitiveZodType<z.ZodString>>>>;