@zackbart/connecta 0.28.0 → 0.28.1

package/CHANGELOG.md

@@ -2,6 +2,179 @@
 
 All notable changes to this package are documented here.
 
+## 0.28.1 — 2026-10-05
+
+This patch adds six maintained connections for church operations and the
+downstream OAuth they needed. Planning Center, Overflow, Tithe.ly, Breeze ChMS,
+and Church Community Builder (Pushpay ChMS) are hand-written `api()` surfaces
+over their whole APIs, with every money-moving write behind approval; Basecamp
+proxies 37signals' hosted MCP server. Church Community Builder accepts only
+OAuth, so `api()` connectors can now declare a static OAuth 2.0
+authorization-code grant that reuses the `remoteMcp()` machinery. Each
+connection is a new opt-in provider subpath and the OAuth grant is opt-in per
+connector: existing imports, connector declarations, credentials, and
+deployment behavior do not change. Two fixes a deployment may notice: a forced
+OAuth restart no longer reuses a client registration the provider has deleted
+([#611](https://github.com/zackbart/connecta/issues/611)), and a failed OAuth
+code exchange is now logged as fixed text rather than the provider's message.
+Internally, the guarded transport can repeat a query key for an array value,
+and `api()`'s builder moved into its own module so OAuth stays out of bundles
+that never use it.
+
+### Added
+
+- **Downstream OAuth on `api()` connectors.** A hand-written connector can
+  declare `oauth: { authorizationEndpoint, tokenEndpoint, clientId,
+  clientSecret?, tokenEndpointAuthMethod?, scope?, pkce?, authorizationParams?,
+  tokenRequestHeaders?, apiOrigins }` for a REST API that accepts only the authorization code grant,
+  such as Church Community Builder. Nothing is discovered or registered: the
+  endpoints and the provider-issued client are configuration, and the client
+  secret comes from the deployment's environment and is never stored. Handlers
+  call `ctx.oauth.fetch(url, init)`, which sends the calling owner's token as a
+  bearer to a declared origin only, answers a 401 with one coordinated refresh
+  and one replay, and otherwise fails `auth_required`. The grant is the
+  `remoteMcp()` grant underneath — the same sealed epochs, shared and personal
+  ownership, rotating-refresh coordination, dead-versus-outage verdicts,
+  `/oauth/callback/<id>`, `authorize_connector`, and operator Connect,
+  Restart, and Disconnect. `oauth` and `credential` are exclusive on one
+  connector. See [downstream OAuth on `api()`](./documentation/auth.md#downstream-oauth-on-api).
+- **Church Community Builder (Pushpay ChMS) connection.**
+  `@zackbart/connecta/providers/ccb` exports `ccb(id, { purpose, environment,
+  mode, clientId, clientSecret, access?, scopes?, subdomain? })`, a
+  hand-written v2 REST connection over `api()`'s OAuth grant. `environment`
+  (`production` or `sandbox`) and `mode` (`system`, one church-wide grant an
+  administrator approves; `identity`, each person signing in as themselves
+  with a personal grant) are required, because CCB credentials do not cross
+  environments and the two modes reach different data. Twenty-four named reads
+  cover people and families, groups and participants, events and attendance,
+  forms and responses, processes and queues, scheduling, notes, and giving
+  metrics and pledges, with projections that drop allergies, giving
+  identifiers, and prayer requests unless `raw: true`. `ccb_api_get` and
+  `ccb_api_search` reach every GET and advanced search read-only, and
+  `ccb_api_mutate` ships only when a write scope is requested. A default
+  60-per-minute admission window per endpoint transcribes CCB's documented
+  limit, and `npm run providers:check -- --provider ccb` compares the 41
+  touched endpoints with Pushpay's published OpenAPI document. Clients are
+  issued by hand through Pushpay's API access request form.
+- **Maintained Planning Center connection.**
+  `@zackbart/connecta/providers/planning-center` exports `planningCenter(id,
+  options)`, a hand-written `api()` surface over Planning Center Online's REST
+  API with no SDK and no new dependency. Named tools cover the jobs church
+  staff run — People search, profiles, contact records, lists, workflows and
+  card actions, notes, custom fields, and form submissions; Services plans,
+  teams, schedules, songs, and scheduling; Groups memberships and events;
+  Check-Ins attendance; Calendar occurrences; Registrations signups; and Giving
+  donations, funds, batches, pledges, and recurring gifts as reads only — with
+  JSON:API flattened into lean records and `raw: true` beside them.
+  `pco_api_get` (read-only) and `pco_api_mutate` (always approval-gated) reach
+  every other endpoint, including every write that moves money. The credential
+  is a personal access token as two labeled fields, and the Test action names
+  the person and organization it acts as. Every request sends a reviewed
+  `X-PCO-API-Version` per product and a configurable `User-Agent`, and the
+  default call budget transcribes Planning Center's 100 requests per 20
+  seconds. `npm run providers:check -- --provider planning-center` compares
+  the touched endpoints with Planning Center's per-product OpenAPI documents
+  and reports a newly published version of any pinned product. Planning
+  Center's own hosted MCP server was considered and is not wrapped: its writes
+  stop at People.
+- **Maintained Overflow connection.** `@zackbart/connecta/providers/overflow`
+  ships 16 projected reads over contributions, deposits and their line items
+  and totals, refunds, chargebacks, donors, recurring gifts, payment methods,
+  campaigns, locations, Tap events, and webhook delivery logs, plus a
+  read-only GET hatch and a destructive JSON-mutation hatch that carries every
+  Overflow write — charges, payment authorization, refunds, recurring-gift
+  changes, and donor edits — to the host's approval prompt. `environment`
+  (`"production"` or `"staging"`) is required with no default, the credential
+  is one operator slot with `clientId` and `apiKey` fields, list rows keep
+  donor contact details and webhook payloads out unless `raw: true`, and the
+  default admission budget transcribes Overflow's 120 requests per minute per
+  client. `npm run providers:check -- --provider overflow` compares all 38
+  operations with the OpenAPI document Overflow publishes on staging.
+- A maintained Tithe.ly giving connection, `tithely(id, { purpose, environment })`
+  from `@zackbart/connecta/providers/tithely`: a hand-written `api()` surface
+  over Tithe.ly's v1 REST API. `environment` (`"live"` for tithe.ly, `"test"`
+  for tithelydev.com) is required with no default, because Tithe.ly's key pairs
+  are environment-specific and carry nothing that says which. The credential
+  slot takes the public and private keys as two fields, refuses an obviously
+  swapped pair without a request, and its Test action reports the organization
+  the keys reach; API access is by request through support@tithe.ly. Named
+  read-only tools cover organizations and their funds, donor accounts, charges
+  by organization or donor and created-date range, recurring gifts, and
+  payment-method metadata, with amounts as integer cents, dates as ISO 8601,
+  `hasMore` paging, and organization projections that omit payout bank and
+  legal-contact details. Every write moves money or donor payment state and is
+  reached only through the always-destructive, form-encoded
+  `tithely_api_mutate`; `tithely_api_get` reaches every v1 read. No call budget
+  is declared, since Tithe.ly publishes no rate limit.
+  `npm run providers:check -- --provider tithely` digests the OpenAPI snippet
+  each reference page embeds, for every documented v1 operation.
+- A maintained Breeze ChMS connection (Tithely Church Management since
+  2025-11-11) at `@zackbart/connecta/providers/breeze`:
+  `breeze(id, { subdomain, purpose })` binds one church's
+  `<subdomain>.breezechms.com` — validated as a single hostname label at
+  construction, so no argument can steer the API key elsewhere — with an
+  operator `Api-Key` slot tested against the account summary. Named reads cover
+  people, profile fields, tags, events, calendars, attendance, forms,
+  volunteers, the account log, and giving (`list_contributions`, `list_funds`,
+  which call endpoints Breeze stopped documenting in 2023 and still serves);
+  named writes add and update people, assign and unassign tags, and record a
+  check-in. Because Breeze sends writes as GET too, the escape hatches split by
+  endpoint rather than method: `breeze_api_get` admits only a reviewed
+  allowlist of read endpoints and their documented parameters, and the
+  destructive `breeze_api_mutate` reaches everything else. No admission budget
+  is declared, since Breeze documents no rate limit; drift is review-only,
+  since it publishes no machine-readable specification.
+- **`basecamp()` — a maintained Basecamp hosted-MCP connection** at
+  `@zackbart/connecta/providers/basecamp`, proxying
+  `https://mcp.basecamp.com/mcp` — a server 37signals runs but has not
+  documented or announced. OAuth only, and `clientMetadataUrl` is required:
+  Basecamp restricts dynamic client registration for HTTPS callbacks, so a
+  deployment hosts a Client ID Metadata Document listing
+  `<publicUrl>/oauth/callback/<id>`, and construction throws without one. A
+  grant reaches exactly one Basecamp account, chosen at consent, so the guide
+  leads with that, names `get_me` to confirm it, and a second account is a
+  second connector. All 227 tools in the live catalog are classified (105
+  read-only, 34 additive, 88 destructive); the four verdicts that part from the
+  server's own annotations, and `create_stream_ticket`'s agreement with its
+  read-only claim, are argued beside their rows. No access mode ships: the MCP
+  client requests the scope Basecamp's challenge names, so a `read` option
+  would be a label rather than a limit. Personal access tokens are not offered,
+  because nothing shows this endpoint accepts one. No default `callAdmission`:
+  Basecamp's limits are dynamic, multi-tier, and metered at its own server's
+  IP. With no public setup page or inventory, `npm run providers:check` reads
+  the server's OAuth discovery instead — the resource names the endpoint and
+  the authorization server still accepts metadata-document clients — and
+  catalog drift is runtime-only.
+
+### Fixed
+
+- **A forced OAuth restart can no longer wedge on a purged client
+  registration** ([#611](https://github.com/zackbart/connecta/issues/611)).
+  Restart already carried an issuer-bound dynamic registration into the new
+  epoch; it carried it unconditionally, and a provider that had forgotten the
+  client refuses it at consent without ever redirecting back, so every later
+  Restart reused the same dead client and only Disconnect escaped. A carried
+  client is now carried again only once a grant in its epoch proves the
+  provider still knows it, so two restarts in a row with no consent between
+  them register at most once more. A URL-based client (`clientMetadataUrl`)
+  and a client whose secret has expired are never carried. Continue no longer
+  hands back a pending consent URL whose client a callback's `invalid_client`
+  has dropped; it starts a flow that registers instead. Static `api()` OAuth
+  clients are configuration and unaffected.
+- **A refresh rotation saved after its request was cancelled keeps its
+  issuer.** When the token endpoint answered after the owning request left,
+  connecta persisted the rotated tokens itself but unbound, and the next
+  issuer-aware read adopted them for whichever authorization server the
+  connector named by then — so a connector repointed at another server would
+  send the rotated refresh token there. The recovery save now stamps the issuer
+  the refresh answered to, as the SDK's own save does, and a repointed connector
+  fences the grant instead.
+- **A failed OAuth code exchange no longer writes the provider's message to the
+  operator log.** The SDK quotes a token endpoint's `error_description` or raw
+  body, and a provider that echoes a `client_secret_post` request put the client
+  secret, code, and verifier in the log. The callback now logs fixed text and,
+  when the error carries one, a standard OAuth error code from an allowlist.
+
 ## 0.28.0 — 2026-10-04
 
 This minor release removes program pauses ([#672](https://github.com/zackbart/connecta/issues/672)).

package/README.md

@@ -64,11 +64,14 @@ Fifty issues in, one small object out. Your context window notices.
   services in a config file; your client never changes.
 - **Wrap any HTTP API by hand.** A few lines per tool. No OpenAPI conversion —
   generated tool sprawl is the problem, not the fix.
-- **Use maintained connections** for Cloudflare, Linear, Mixpanel, Notion,
-  RevenueCat, Stripe, and Vercel: known endpoints, auth defaults, and vetted
-  read/write classifications, imported one at a time. Cloudflare, Notion, and
-  Vercel each let the deployment choose their hand-written API interface or
-  official hosted MCP.
+- **Use maintained connections** for Basecamp, Breeze ChMS, Church Community
+  Builder, Cloudflare, Linear, Mixpanel, Notion, Overflow, Planning Center,
+  RevenueCat, Stripe, Tithe.ly, and Vercel: known endpoints, auth defaults, and
+  vetted read/write classifications, imported one at a time. Cloudflare,
+  Notion, and Vercel each let the deployment choose their hand-written API
+  interface or official hosted MCP. Planning Center, Overflow, Tithe.ly,
+  Breeze, and Church Community Builder are hand-written over their whole APIs,
+  with every money-moving write behind approval.
 - **Let the agent work in code.** Search, chain, filter, join, and reduce
   inside the sandbox instead of round-tripping every call through the model.
 - **Teach undeclared result shapes by using them.** Successful read-only calls

package/dist/artifacts/connector.js

@@ -6,7 +6,7 @@
 //
 // Who made each version comes from the caller core attached to the context,
 // never from arguments.
-import { api } from "../connectors/api.js";
+import { apiConnector as api } from "../connectors/api-connector.js";
 import { callerOf } from "../connector-caller.js";
 import { ConnectorCallError } from "../errors.js";
 import { resolveTheme } from "../branding.js";

package/dist/auth/downstream-oauth.js

@@ -2,7 +2,30 @@ import { UnauthorizedError } from "@modelcontextprotocol/client";
 import { Deferred, Effect } from "effect";
 import { retryAfterMs } from "../connectors/guarded-fetch.js";
 import { ConnectorCallError } from "../errors.js";
+import { attachOAuthPartition, oauthPartitionFor, retainOAuthPartition, } from "../oauth-partition.js";
+import { inheritOAuthSealer } from "../oauth-sealing.js";
 import { detach, fromSignal, runEdge } from "../runtime/run.js";
+/** RFC 6749 section 3.3: one or more scope tokens, separated by single spaces. */
+const OAUTH_SCOPE = /^[\x21\x23-\x5B\x5D-\x7E]+(?: [\x21\x23-\x5B\x5D-\x7E]+)*$/;
+/** Refuse, at construction, a configured scope no authorization server could parse. */
+export function assertOAuthScope(connectorId, scope) {
+    if (scope !== undefined && !OAUTH_SCOPE.test(scope)) {
+        throw new Error(`[connecta] connector "${connectorId}" OAuth scope must contain space-separated scope tokens.`);
+    }
+}
+/**
+ * The context an explicit authorization start runs under: allowed to begin
+ * consent, with a request scope of its own, carrying the registry's sealer and
+ * owner partition across the copy. Only `startAuth` builds one; status reads
+ * and calls never do, which is what keeps them from starting authorization.
+ */
+export function authorizingContext(ctx) {
+    return attachOAuthPartition(inheritOAuthSealer(ctx, {
+        ...ctx,
+        requestScope: ctx.requestScope ?? ctx,
+        allowAuthorization: true,
+    }), oauthPartitionFor(ctx));
+}
 /** A 256-bit random opaque value, hex-encoded — used for the OAuth `state`. */
 function randomState() {
     const bytes = new Uint8Array(32);
@@ -18,7 +41,7 @@ function timingSafeEqual(a, b) {
         diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
     return diff === 0;
 }
-const LEGACY_GENERATION = "legacy";
+export const LEGACY_GENERATION = "legacy";
 const ACTIVE_GENERATION_PREFIX = "v2:";
 const RESETTING_GENERATION_PREFIX = "reset:";
 const DISCONNECTED_GENERATION_PREFIX = "disconnected:";
@@ -592,6 +615,9 @@ export class OAuthRefreshCoordinator {
                 // reaches the token endpoint.
                 if (requestSignal?.aborted)
                     throw aborted(requestSignal);
+                // The authorization server this redemption answers to, fixed now: a
+                // recovery save outlives the SDK flow that would have stamped it.
+                const issuer = provider.refreshIssuer(generation);
                 const flight = {
                     outcome: Deferred.makeUnsafe(),
                     stopObservingOwnerAbort: () => { },
@@ -601,7 +627,7 @@ export class OAuthRefreshCoordinator {
                     recoveryPending: false,
                     settled: false,
                     releasePartition: this.retainWork(),
-                    persist: (tokens) => provider.saveAcceptedRefreshTokens(tokens, generation, flight),
+                    persist: (tokens) => provider.saveAcceptedRefreshTokens(tokens, generation, flight, issuer),
                 };
                 this.flights.set(generation, flight);
                 this.advanceStateRevision();
@@ -790,6 +816,25 @@ export class OAuthRefreshCoordinator {
         this.settle(generation, flight, { status: "retired" });
     }
 }
+/**
+ * One refresh coordinator per owner partition, for one connector runtime.
+ * Long-lived enough for distinct request scopes to join one token redemption;
+ * it owns no client, transport, or request state. Production contexts carry a
+ * stable registry partition; hand-written contexts coordinate by their shared
+ * storage object instead.
+ */
+export function refreshCoordinatorsByPartition() {
+    const coordinators = new WeakMap();
+    return (ctx) => {
+        const partition = oauthPartitionFor(ctx) ?? ctx.storage;
+        let coordinator = coordinators.get(partition);
+        if (!coordinator) {
+            coordinator = new OAuthRefreshCoordinator(() => retainOAuthPartition(partition));
+            coordinators.set(partition, coordinator);
+        }
+        return coordinator;
+    };
+}
 function storedOAuthValue(value) {
     if (!value || typeof value !== "object")
         return false;
@@ -798,6 +843,7 @@ function storedOAuthValue(value) {
         typeof candidate.generation === "string" &&
         (candidate.issuer === undefined || typeof candidate.issuer === "string") &&
         (candidate.binding === undefined || typeof candidate.binding === "string") &&
+        (candidate.carried === undefined || candidate.carried === true) &&
         "value" in candidate);
 }
 function legacyStoredOAuthValue(value) {
@@ -1012,6 +1058,11 @@ export class KvOAuthProvider {
             this.refreshCoordinator?.fail(owned.generation, owned.flight, error);
         }
     }
+    /** @internal The issuer this flow's issuer-aware read bound its refresh to. */
+    refreshIssuer(generation) {
+        const basis = this.refreshBasis;
+        return basis?.generation === generation ? basis.issuer : undefined;
+    }
     /** True when another request saved a refresh result after this flow's read. */
     refreshBasisChanged(current, generation) {
         const basis = this.refreshBasis;
@@ -1226,6 +1277,7 @@ export class KvOAuthProvider {
                     generation,
                     ...(parsed.issuer !== undefined ? { issuer: parsed.issuer } : {}),
                     ...(parsed.binding !== undefined ? { binding: parsed.binding } : {}),
+                    ...(parsed.carried === true ? { carried: true } : {}),
                     // Only a finite number is a time; anything else reads as untimed.
                     ...(typeof parsed.writtenAt === "number" &&
                         Number.isFinite(parsed.writtenAt)
@@ -1421,6 +1473,7 @@ export class KvOAuthProvider {
             this.refreshBasis = {
                 accessToken: tokens.access_token,
                 generation: refreshGeneration,
+                issuer: ctx.issuer,
                 ...(tokens.refresh_token !== undefined
                     ? { refreshToken: tokens.refresh_token }
                     : {}),
@@ -1438,9 +1491,16 @@ export class KvOAuthProvider {
             await this.persistTokens(tokens, ctx, false, owned);
         }
     }
-    /** @internal Commit an already redeemed rotation even after its request leaves. */
-    async saveAcceptedRefreshTokens(tokens, generation, flight) {
-        await this.persistAcceptedTokens(tokens, undefined, { generation, flight });
+    /**
+     * @internal Commit an already redeemed rotation even after its request
+     * leaves. A token response names no issuer, so the one the refreshed grant
+     * was bound to is stamped here as the SDK's own save would: an unbound
+     * rotation would read as legacy state and bind to whichever authorization
+     * server the connector names next.
+     */
+    async saveAcceptedRefreshTokens(tokens, generation, flight, issuer) {
+        const stamped = issuer !== undefined ? { ...tokens, issuer } : tokens;
+        await this.persistAcceptedTokens(stamped, issuer !== undefined ? { issuer } : undefined, { generation, flight });
     }
     persistAcceptedTokens(tokens, ctx, owned) {
         // The SDK can save the same response while cancellation recovery is
@@ -1542,13 +1602,27 @@ export class KvOAuthProvider {
      * direction to tolerate clock skew between isolates. A URL with no write
      * time — stored by an earlier release, or under a pre-envelope generation —
      * is treated as stale, so the caller starts a fresh flow instead.
+     *
+     * The URL must also still name the epoch's client. A callback whose code
+     * exchange the server refused with `invalid_client` leaves the URL behind
+     * but drops the client; handing that URL back would send the operator to a
+     * consent the server has already refused, where a fresh flow registers.
      */
     async reusablePendingAuthorizationUrl() {
         const pending = await this.readValue("oauth:pending", (raw) => raw);
-        if (pending?.writtenAt === undefined)
+        if (pending?.writtenAt === undefined ||
+            Math.abs(Date.now() - pending.writtenAt) >= PENDING_AUTHORIZATION_MAX_AGE_MS) {
+            return undefined;
+        }
+        let clientId;
+        try {
+            clientId = new URL(pending.value).searchParams.get("client_id");
+        }
+        catch {
             return undefined;
-        return Math.abs(Date.now() - pending.writtenAt) <
-            PENDING_AUTHORIZATION_MAX_AGE_MS
+        }
+        const client = await this.clientInformation();
+        return clientId !== null && client?.client_id === clientId
             ? pending.value
             : undefined;
     }
@@ -1616,24 +1690,13 @@ export class KvOAuthProvider {
     async performResetAuthorization(operatorDisconnected, preserveClient) {
         const nonce = crypto.randomUUID();
         const previous = await this.generation();
-        // Only an explicitly forced restart may carry a registration forward.
-        // Discovery is never copied: the SDK must select the authorization server
-        // again, then its issuer-aware clientInformation hook checks the issuer.
-        const priorClient = preserveClient && !operatorDisconnected && this.clientBinding
-            ? await this.readValue("oauth:client", (raw) => {
-                try {
-                    return JSON.parse(raw);
-                }
-                catch {
-                    return {};
-                }
-            })
-            : undefined;
-        const reusableClient = priorClient?.generation === previous &&
-            priorClient.issuer !== undefined &&
-            priorClient.binding === this.clientBinding &&
-            typeof priorClient.value?.client_id === "string"
-            ? priorClient
+        // Only an explicitly forced restart may carry a registration forward, and
+        // only one this connector registered: an operator disconnect, an issuer
+        // mismatch, and every unforced reset discard it. Discovery is never
+        // copied: the SDK must select the authorization server again, then its
+        // issuer-aware clientInformation hook checks the issuer.
+        const reusableClient = preserveClient && !operatorDisconnected && this.clientBinding
+            ? await this.carriableClient(previous)
             : undefined;
         const now = Date.now();
         const inherited = await this.cleanupBacklog(previous, now);
@@ -1678,10 +1741,17 @@ export class KvOAuthProvider {
         await this.storage.set("oauth:generation", active);
         this.refreshCoordinator?.retire(previous);
         if (reusableClient && !this.signal?.aborted) {
-            // readValue opened the old physical key; writeValue seals the plaintext
+            // readValue opened the old physical key; the write seals the plaintext
             // under the new one. Copying ciphertext would fail its AAD check.
             this.captureGeneration(active);
-            await this.writeValue("oauth:client", reusableClient.value, (value) => JSON.stringify(value), reusableClient.issuer, undefined, this.clientBinding);
+            await this.storeInGeneration("oauth:client", active, () => JSON.stringify({
+                connectaOAuthVersion: STORED_VALUE_VERSION,
+                generation: active,
+                issuer: reusableClient.issuer,
+                binding: reusableClient.binding,
+                carried: true,
+                value: reusableClient.value,
+            }));
         }
         // Delete the generation just retired: its values, then the lineage it
         // published, which the new epoch has copied. Then retry the newest few
@@ -1713,6 +1783,55 @@ export class KvOAuthProvider {
         if (failure)
             throw failure.reason;
     }
+    /**
+     * The registration a forced restart may copy out of `previous`, or nothing.
+     *
+     * It must have been registered in that epoch for this authorization server
+     * (an issuer stamp) under this connector's exact configuration, redirect
+     * URI, and client metadata (the binding), and it is read through this
+     * owner's own storage, so another principal's partition is never a source.
+     * Three registrations are never carried:
+     *
+     * - A URL-based client (`clientMetadataUrl`). Nothing was registered, so
+     *   nothing is saved by copying it, and leaving it behind makes the SDK ask
+     *   the freshly discovered metadata whether the server still accepts one.
+     * - One whose `client_secret_expires_at` has passed (RFC 7591: zero means
+     *   never). The token endpoint would refuse it.
+     * - One a previous restart carried that has not since earned a grant. The
+     *   SDK builds a consent URL locally and sends nothing that could answer
+     *   `invalid_client`, and RFC 6749 section 4.1.2.1 forbids an authorization
+     *   server from redirecting a client it does not recognize, so a forgotten
+     *   registration never reaches the callback. Tokens in the epoch are the
+     *   only proof the server still knows the client. Without them the second
+     *   restart registers again, which bounds a forgotten registration to one
+     *   refused consent rather than a restart loop only a disconnect escapes.
+     */
+    async carriableClient(previous) {
+        const prior = await this.readValue("oauth:client", (raw) => {
+            try {
+                return JSON.parse(raw);
+            }
+            catch {
+                return {};
+            }
+        });
+        const clientId = prior?.value?.client_id;
+        const expiresAt = prior?.value?.client_secret_expires_at;
+        if (prior?.generation !== previous ||
+            prior.issuer === undefined ||
+            prior.binding === undefined ||
+            prior.binding !== this.clientBinding ||
+            typeof clientId !== "string" ||
+            clientId === this.clientMetadataUrl ||
+            (typeof expiresAt === "number" && expiresAt > 0 && expiresAt * 1000 <= Date.now())) {
+            return undefined;
+        }
+        const carriable = { ...prior, issuer: prior.issuer, binding: prior.binding };
+        if (!prior.carried)
+            return carriable;
+        const earnedGrant = (await this.storage.get(oauthValueStorageKey("oauth:tokens", previous))) !== null;
+        return earnedGrant ? carriable : undefined;
+    }
     async invalidateCredentials(scope) {
         const endsRefresh = scope === "all" || scope === "tokens";
         try {