@zackbart/connecta 0.24.3 → 0.24.4

package/documentation/storage-and-credentials.md

@@ -1,254 +0,0 @@
-# Storage and credentials
-
-The core `KVStorage` contract supports `get`, `set`, and `delete`; adapters may
-also implement `list(prefix)`. Core uses storage for connector state, catalogs,
-and result paging. The vault is an explicit independent option:
-
-```ts
-import { encryptedCredentialVault } from "@zackbart/connecta/credentials";
-
-createConnecta({
-  connectors,
-  executor,
-  storage,
-  vault: encryptedCredentialVault(storage, encryptionKey),
-});
-```
-
-`encryptionKey` is a base64 32-byte AES key. The factory implements the
-root-exported `CredentialVault` contract. Core depends on the contract without
-importing the encrypted implementation; deployments may supply their own.
-A replacement must isolate both connector id and optional owner, preserve
-metadata-only reads for the UI, and keep plaintext confined to host credential
-resolution. The built-in AES-GCM implementation binds connector and owner into
-authenticated encryption context. Sharing a backend is not permission to share
-a principal's credentials.
-
-Connectors declare a human-managed `credential` slot in code. The vault exposes
-read access only through that connector's `ctx.credential`. Values, masked
-values, call arguments, and raw errors never enter model recovery or activity.
-Omitting the vault leaves literal deployment-provided secrets and downstream
-OAuth available, but declared vault slots cannot be managed.
-
-Credentials fail at use. Proactive liveness probing remains removed by
-[the 0.9 decision](../ethos.md). Operator-triggered tests and local credential
-shape checks remain. `authorize_connector` returns a human credential handoff
-only when both a vault and the UI are configured. Without either, recovery is
-`unavailable` and explains the missing configuration.
-
-A static bearer may invoke a connector but never mutate its auth as a browser
-user. Interactive users need visibility plus `credentialAdministration` for
-shared auth or `personalConnection` for their own personal auth. Both management
-permissions default to none. Saving, testing, replacing, or removing a value
-never returns it. The vault is read for each call, so a saved replacement takes
-effect without restarting the deployment.
-
-## Result storage
-
-Direct-call result paging uses the same KV interface with a 15-minute TTL.
-`results.maxStashBytes` defaults to 8 MiB of stored paging envelopes, including
-base64 overhead; `results.maxStashEntries` defaults to 64. Both are
-non-negative safe integers, and zero disables stashing. One registry accounts
-for all subjects and reserves capacity for pending writes. A full stash keeps
-the successful call's preview and returns a paging-unavailable notice, without
-a result id. Expired entries are deleted on later stash attempts before their
-capacity is reused, even when the backend only expires entries on read.
-A deletion failure keeps the reservation. Limits apply to writes by one
-runtime; they do not coordinate other processes or Worker isolates, or count
-entries left by a previous runtime.
-
-The memory store also checks up to 16 existing keys on each `set`, rotating
-through live keys so expired entries that nobody reads are eventually removed.
-There are no timers or background sweeps. Paging values use an ASCII base64
-envelope so only the requested bytes need decoding after the KV read. The
-storage adapter's format and interface stay unchanged.
-
-## File storage
-
-`fileStorage` is a single-process development store. It loads one snapshot and
-rewrites the whole state synchronously on each mutation, including result
-stashes. It acquires an exclusive `<path>.lock` before loading, so a second
-instance or process opening the same path fails with the holder's pid instead
-of overwriting a stale snapshot. An unref'd timer refreshes the lock's mtime
-every 15 seconds. A heartbeat older than 60 seconds expires regardless of pid,
-so a container restart cannot leave a reused pid holding the file forever.
-The lock records the host/PID namespace as well as the pid. Within that same
-namespace, a dead pid permits immediate recovery; a matching current pid is
-live only when the in-process registry owns that lock. Other namespaces and
-older locks without namespace metadata rely on heartbeat expiry.
-
-Recovery uses a serialized `.lock.reclaim` guard, which also expires after
-60 seconds if its process crashes or pauses. An incomplete lock likewise
-becomes recoverable after 60 seconds. A holder paused long enough to lose its
-lock fails subsequent writes with "lock was lost". Writes check ownership
-before changing state and again before rename; reads use the loaded snapshot
-without filesystem lock checks. This remains an advisory development store
-on a shared local filesystem, not a distributed storage adapter.
-
-The returned store's `close()` releases the lock and refuses further operations.
-Process exit also releases it, including Node `listen()`'s SIGTERM/SIGINT
-shutdown. Each write uses a unique, exclusively created temp file, and the
-state file's JSON format is unchanged.
-
-Expired entries are removed before each write. Large direct-call results therefore increase both
-retained state and write cost. Use `execute_code` to reduce read-only results
-before returning them, and choose a storage adapter suited to the deployment.
-
-## Storage continuity
-
-This module extraction changes no encrypted record keys, owner partitions, or
-OAuth storage format. Reuse the existing storage and encryption key when
-constructing `encryptedCredentialVault`. Keep connector ids, principal ids, and
-identity namespaces unchanged. Losing the encryption key makes old vault
-values unreadable; changing identity context selects another personal partition.
-
-Removed Connecta-issued token records remain inert in storage. This upgrade
-does not delete them, convert them to another credential, or migrate their
-clients automatically.
-
-## Shared and personal auth
-
-Connector auth defaults to `authScope: "shared"`. Its credential, OAuth state,
-tokens, catalog cache, and connector storage belong to the deployment. Set
-`authScope: "personal"` when every human principal needs a separate downstream
-account:
-
-```ts
-remoteMcp("linear", {
-  url: "https://mcp.linear.app/mcp",
-  authScope: "personal",
-  auth: { type: "oauth" },
-});
-```
-
-Personal connectors disappear from a request that has no stable human
-principal. For a principal that can see one, connecta partitions connector
-storage, encrypted vault records, catalog caches, OAuth generations, and
-observed result shapes under an opaque SHA-256 identity key. Results used by
-`get_result` are partitioned by the authenticated subject independently of
-activity configuration. Open deployments and providers that supply no identity
-share one results partition. See [the partition and paging contract](./meta-tools.md#result-representation).
-
-Literal `auth: { type: "headers" }` cannot be personal because its secret lives
-in deployment code. `remoteMcp()` refuses that combination at construction.
-Use operator-managed credential auth or OAuth instead.
-
-## A remote MCP connector's static credential
-
-`remoteMcp()` accepts a third auth shape beside OAuth and literal headers:
-
-```ts
-remoteMcp("revenuecat_bepresent", {
-  url: "https://mcp.revenuecat.ai/mcp",
-  auth: { type: "credential", credential: { label: "API v2 secret key" } },
-});
-```
-
-The connector, its endpoint, and the credential *slot* stay declared in code;
-only the secret arrives through the connection UI at `/`. That is the same boundary
-`api()` has always had, and the reason a project-wide key no longer has to be a
-Worker secret or an environment variable
-([#439](https://github.com/zackbart/connecta/issues/439)).
-
-`header` defaults to `Authorization` and `scheme` to `Bearer`. `scheme: null`
-sends the stored value verbatim, which is what Linear's personal API keys
-expect. A scheme whose last token is `Basic` declares HTTP Basic credentials, so
-the stored `user:secret` is base64-encoded first — `"Basic"` produces
-`Basic <base64>`, and Mixpanel's documented `"Bearer Basic"` produces
-`Bearer Basic <base64>`. There is one reserved `value` field and no multi-field
-header composition: named `credential.fields` are refused at construction.
-
-A stored value is checked before anything frames it: a line break or other
-control character — what a key pasted across two lines leaves behind — is
-refused as `auth_required` with a message naming the problem and never the
-value. That check exists because the runtime that rejects such a header quotes
-the whole offending value back in its `TypeError`, and that message would
-otherwise reach the agent, the operator page, and the activity log. Behind it,
-any error whose message quotes the credential or the header it became is
-discarded whole and replaced; nothing is masked or truncated, because a
-redaction that keeps part of a secret is still a leak.
-
-An empty slot is not a boot failure and not a silently absent connector. The
-connector is present, its status reads `auth_required`, calls fail with the same
-typed error a missing OAuth grant produces, and `authorize_connector` returns
-a connection UI handoff at `/` when UI and vault are configured. Without either,
-it returns `unavailable` and explains what is missing.
-
-The vault is read before any cached downstream client is trusted, so a rotation
-lands on the next call rather than the next deploy. Connecta compares a SHA-256
-digest of the value the cached client connected with; a different digest closes
-that client and reconnects. The plaintext lives in the connect attempt's local
-scope, never on connector state, never in a log, and never in a status or error
-message. A cleartext `http://` destination warns at construction here exactly as
-it does for literal headers — who owns the secret changed, not what the wire
-carries.
-
-The connection UI Test action connects with the stored value and reports how many
-tools the downstream served. That is the whole honest check for a proxy: which
-account, project, or mode the key reaches is the provider's answer, not
-Connecta's.
-
-## Downstream OAuth
-
-`remoteMcp()` stores dynamic client registration, tokens, PKCE material, state,
-and the pending authorization URL in the connector's storage namespace.
-Registration and token envelopes are bound to the validated authorization
-server `issuer`. An unbound pre-0.9 envelope is upgraded in place on its first
-issuer-aware read, preserving the existing grant.
-
-For personal OAuth, the authorization handoff also stores a 15-minute mapping
-from a SHA-256 digest of `state` to the principal partition. The public callback
-uses that mapping before it verifies state or exchanges the code. Neither the
-browser nor a callback parameter can select a principal. The callback deletes
-the mapping before it exchanges the code, so a second callback cannot replay
-the principal handoff in strongly consistent storage. Cloudflare KV deletion
-is eventually consistent, so handoff consumption there is best-effort across
-PoPs; the downstream authorization code remains single-use. If the callback
-request also carries an interactive identity, Connecta refuses it when that
-principal did not start the flow.
-
-If later discovery resolves a different issuer, Connecta does not send the old
-client identifier or tokens to it. The provider publishes a new generation
-epoch, makes every older credential namespace unreadable, cleans up the retired
-values, and lets the SDK begin registration and authorization again. The same
-epoch fence prevents an older isolate or late token exchange from resurrecting
-the retired grant.
-
-The OAuth callback verifies the one-shot `state` first, then hands the complete
-query string—including RFC 9207 `iss`—to the SDK transport. One-shot state,
-verifier, and pending URL are cleared only after a successful exchange.
-
-Within one `remoteMcp()` runtime, one request scope owns refresh-token
-redemption for an OAuth generation. Concurrent scopes wait for the owner's
-token save or bounded failure, then either read storage again or receive that
-failure. A scope that had already read the retired refresh token reuses the
-newly stored rotating token locally instead of sending the retired value
-upstream. Force reauthorization retires the old generation's gate, and a
-failed flow releases ownership for a later attempt. The coordinator retains
-only a completion signal and one temporary owner-abort listener until that
-exact flight settles, never the token response or downstream transport. A
-follower may stop waiting when its own request is cancelled without cancelling
-the owner or poisoning the generation for later callers. If the owner's
-credential mutation fails, joined callers receive that same bounded failure
-instead of waking to redeem the unchanged token; a later independent call may
-retry. Non-success and malformed token responses settle current waiters at the
-fetch boundary, before any later authorization callback can itself fail.
-Cancelling the owner aborts its fetch and fails current joiners rather than
-promoting one: once a request reaches the authorization server, repeating its
-old refresh token is not known to be safe. If that cancellation lands while
-the valid response's credential write is already running, a same-generation
-attempt receives `temporarily_unavailable` until the exact write succeeds or
-fails. This mutation marker contains no retained promise; force
-reauthorization removes it when the old generation becomes unreadable.
-An additional opaque success identity lets a request recognize a refresh that
-completed after its issuer-aware token read even when the authorization server
-returned byte-identical credentials. The identity is generation-scoped and is
-discarded with the retired generation. Every authoritative storage-generation
-read also retires coordinator state from other epochs, so an externally
-advanced generation cannot be overwritten in runtime state by late old work.
-
-This guarantee is runtime-local. `KVStorage` has no atomic lock or
-compare-and-set operation, so separate processes or Worker isolates can still
-redeem the same refresh token concurrently. Generation envelopes continue to
-fence their writes, but Connecta does not claim cross-isolate exactly-once
-refresh.

package/documentation/stripe.md

@@ -1,262 +0,0 @@
-# Stripe prebuilt connection
-
-Import `stripe()` independently from `@zackbart/connecta/providers/stripe`. It
-wraps [Stripe's hosted MCP server](https://docs.stripe.com/mcp) with OAuth by
-default, account-scoped mode guidance, a conservative admission policy, a
-task-oriented usage guide, and a vetted safety classification. It adds no
-provider dependency and is not reachable from Connecta's root entry.
-
-```ts
-import { stripe } from "@zackbart/connecta/providers/stripe";
-
-const billing = stripe("stripe", {
-  purpose: "Revenue, disputes, and refunds across our Stripe organization",
-  instructions: "Never refund above $500 without a human in the loop.",
-});
-```
-
-The `id` owns the ordinary connector namespaces. Choose a connector boundary
-for its credential or OAuth session and business purpose — not automatically
-for each Stripe account. One OAuth session may cover live and sandbox accounts
-in the same Stripe organization. Use separate connectors when the credential
-or business purpose differs.
-
-`purpose` is required because it tells an agent where the deployment intends
-to route a question. The connector id, title, and purpose are configuration,
-not proof of which account the authenticated Stripe session will use. Account
-`instructions` are appended to the maintained guide and cannot change the
-connector's safety classification.
-
-## OAuth mode belongs to the selected account
-
-Do not pass `mode` for OAuth. Stripe's `list_available_accounts_or_orgs` returns
-each available account with its `stripe_context` and `livemode`. The same OAuth
-session can return both `livemode: true` and `livemode: false` results.
-
-The served guide tells agents to call that tool before each account-scoped
-operation. They select the intended result and carry its exact `stripe_context`
-and `livemode` unchanged. Connector id, title, purpose, and OAuth identity are
-routing hints. They never prove the account or mode. Ambiguity stops the call.
-
-OAuth metadata therefore stays neutral:
-
-- the default title is `Stripe`;
-- the description says `live and sandbox accounts`;
-- the guide warns that live writes move real money and sandbox writes change
-  test data;
-- admission uses the stricter sandbox ceiling, because Connecta cannot select
-  a different connector policy after the account-scoped call begins.
-
-`mode` remains required for `headers` auth. A restricted key has one fixed live
-or sandbox scope. Its title, description, guide, and admission policy keep the
-fixed-mode behavior. Construction still throws when a recognizable key prefix
-contradicts its declared mode.
-
-For OAuth, deploy one connector for the session:
-
-```ts
-connectors: [
-  stripe("stripe", {
-    purpose: "Live and sandbox billing for our Stripe organization",
-  }),
-]
-```
-
-## Authentication
-
-OAuth is the default and the option Stripe recommends: it supports dynamic
-client registration and PKCE, and each connector instance keeps its own flow
-and tokens in connector-scoped storage. Stripe's current
-[session-management documentation](https://docs.stripe.com/mcp#manage-mcp-client-sessions)
-says one OAuth session can be tied to more than one account in the same Stripe
-organization. It does not say every session has multiple accounts.
-
-That scope changes what an agent must prove before an account-scoped call. It
-calls `list_available_accounts_or_orgs`, resolves the intended result, and
-carries its exact `stripe_context` and `livemode`. If more than one account
-fits, the agent stops and asks.
-
-Stripe also accepts a
-[restricted API key](https://docs.stripe.com/keys#create-restricted-api-key) as
-a bearer token for headless agents:
-
-```ts
-stripe("stripe_sandbox", {
-  mode: "sandbox",
-  purpose: "Automated billing rehearsal",
-  auth: {
-    type: "headers",
-    headers: { Authorization: `Bearer ${env.STRIPE_RESTRICTED_KEY}` },
-  },
-});
-```
-
-Use a restricted key, not a secret key, and scope it to the operations the
-agent actually needs; Stripe's own guidance is to "limit your agent's access to
-exactly the functionality it requires". Keep it in the runtime's secret store.
-
-The same key can come from the connection UI at `/` instead:
-
-```ts
-stripe("stripe_sandbox", {
-  mode: "sandbox",
-  purpose: "Automated billing rehearsal",
-  auth: { type: "credential" },
-});
-```
-
-`mode` is required either way — a static key answers for exactly one
-environment and cannot report which. The literal-header form is checked against
-the key's `_live_`/`_test_` prefix at construction; an operator-managed key is
-not in the deployment file to read, so the declared mode stands alone and a key
-pointed at the other environment fails at Stripe. Declare the mode carefully:
-that check is the one guard Connecta can offer, and this shape does not get it.
-See
-[storage and credentials](./storage-and-credentials.md#a-remote-mcp-connectors-static-credential).
-
-Organization accounts in one OAuth session are not Stripe Connect connected
-accounts. Connect platforms can act as a connected account with
-`connectedAccount`, which adds Stripe's documented `Stripe-Account` header at
-connector construction. Stripe does not support OAuth for connected-account
-calls, and `Stripe-Account` is a second header beside the credential's own,
-which the operator-managed shape does not assemble — so this requires a
-restricted key through `headers` auth and throws otherwise:
-
-```ts
-stripe("merchant_42", {
-  mode: "production",
-  purpose: "Billing questions for the merchant on account 42",
-  connectedAccount: "acct_1234567890",
-  auth: {
-    type: "headers",
-    headers: { Authorization: `Bearer ${env.STRIPE_PLATFORM_KEY}` },
-  },
-});
-```
-
-Administrators must enable MCP access in the Stripe Dashboard. A connector that
-boots but cannot list tools is usually a dashboard toggle, not a bad key.
-
-## The eleven tools, and what they are classified as
-
-Stripe currently serves eleven tools. Seven are reads:
-
-`stripe_api_search`, `stripe_api_details`, `stripe_api_read`,
-`get_balance_summary`, `list_available_accounts_or_orgs`,
-`manage_stripe_accounts`, and `search_stripe_documentation`.
-
-Four are writes:
-
-`stripe_api_write` is destructive. `stripe_implementation_planner`,
-`stripe_analytics`, and `send_stripe_mcp_feedback` are additive.
-
-Two of those deserve a sentence. `stripe_api_read` is a read because Stripe
-documents it as the `GET` half of a generic pair — the tool is the read
-boundary, not whichever endpoint an agent names inside it, and its sibling
-`stripe_api_write` carries every `POST`, `PATCH`, `PUT`, and `DELETE`.
-`stripe_implementation_planner` creates and continues provider-side guide
-state. `stripe_analytics` combines retrieval with query-run creation behind one
-tool. Stripe marks both not read-only and not destructive, so Connecta records
-them as additive writes. They leave `destructiveHint` unset. Their explicit
-`readOnlyHint: false` already routes them through `call_destructive_tool`, and
-asserting destruction would misstate their effect.
-
-That classification fills in downstream silence and otherwise preserves
-explicit annotations. The current server annotates all eleven tools, while the
-manifest records what this release reviewed and exposes later contradictions.
-A tool on the read allowlist arriving with
-`destructiveHint: true` or `readOnlyHint: false` keeps exactly what the
-downstream said and stays behind `call_destructive_tool`. A tool on neither
-maintained list arriving with `readOnlyHint: true` keeps that too, and stays
-callable from `execute_code`. Both are the downstream telling you this release's
-allowlist is stale, and on a name no release has reviewed its word is the only
-evidence there is. One narrow fail-closed exception applies to a name this
-release reviewed and filed destructive: `stripe_api_write` claiming
-`readOnlyHint: true` is a downstream bug rather than news, and stays on the
-approval path.
-
-An unfamiliar tool that annotates nothing fails closed onto
-`call_destructive_tool` until a Connecta release reviews it. That is not
-hypothetical here: Stripe's own MCP page still carries a `create_customer`
-example that its tool table no longer lists. Whatever the server actually
-serves, an unclassified and unannotated `create_customer` lands on the approval
-path. Expect the undocumented Treasury tools Stripe alludes to to arrive
-unclassified as well — annotated ones will be taken at their word.
-
-The upshot is that this connection's tool list is not a fixed set, and the usage
-guide tells the agent so: search this connector for what it actually exposes
-rather than assuming a documented tool is present. The guide also names the id
-discipline the downstream schemas cannot enforce — Stripe ids are typed
-prefixes (`cus_`, `sub_`, `ch_`, `pi_`, `in_`, `acct_`), a plausible-looking one
-belongs to a different object or to nobody, and the id a write takes comes from
-`stripe_api_search` or a list read rather than from a guess.
-
-Account selection comes before that object-id rule. The served guide names
-`list_available_accounts_or_orgs`, `stripe_context`, and `livemode`, and tells
-the agent to stop when the account, mode, or selector is ambiguous. It keeps
-organization-account selection separate from the restricted-key-only Connect
-path, so an agent cannot repair uncertainty by fabricating `Stripe-Account` as
-a tool argument.
-
-The guide also carries the reduction advice the generic schemas cannot (P7):
-a list or search read that returns full objects belongs inside `execute_code`,
-projected to the fields the question needs before `return`, because an
-unprojected list truncates and a projected one keeps customer PII out of the
-transcript. It names Stripe search's per-resource field set — charges search
-has no `payment_intent` field, so the path is the PaymentIntent's
-`latest_charge` — and the account → search → details → read sequence as one
-program rather than four turns, and it names `outcome`, `failure_code`, and
-`failure_message` on the charge as the answer to "why did this payment fail".
-
-Stripe publishes no stability or deprecation policy for this tool set and
-invites tool requests by email, so treat the list as unversioned. `get_balance_summary`
-is Treasury, which Stripe labels public preview and gates behind an access
-request — expect it to be absent unless the account is allowlisted, and expect
-the other Treasury tools Stripe alludes to but does not document to arrive
-unclassified.
-
-## Rate limits
-
-Stripe documents no rate limit specific to the MCP server. The connection
-therefore transcribes the account limit that MCP traffic spends
-([rate limits](https://docs.stripe.com/rate-limits)): **100 requests per second
-in live mode, 25 in a sandbox**, and any single endpoint is capped at 25 per
-second regardless of mode. OAuth uses 25 calls per second and concurrency 4,
-the safe bound for a session that can reach either mode. Fixed live credentials
-use 100 calls per second and concurrency 8. Fixed sandbox credentials use 25
-and concurrency 4. Stripe
-documents that per-account and per-endpoint concurrency limits exist, and
-surface as `429` with a `Stripe-Rate-Limited-Reason` of `global-concurrency` or
-`endpoint-concurrency`, but publishes no number.
-
-As with every connector policy this is a **best-effort approximation** of the
-provider's limit, not an enforcement of it. Each runtime keeps its own counter,
-so N Worker isolates or Node processes serving one deployment can each admit up
-to the stated rate, and the same Stripe account may be spending its budget on
-traffic Connecta never sees. Discovery traffic is outside connector call
-admission and still needs restrained use.
-
-## What is not verified
-
-Stripe's MCP documentation is silent on one thing this connection had to reason
-about rather than read:
-
-- **Whether pagination cursors and `Idempotency-Key` are passable through
-  `stripe_api_read` / `stripe_api_write`.** The conventions in the usage guide
-  are Stripe's documented API conventions; how they thread through the generic
-  tools' arguments is not documented. The guide states them because an agent
-  that ignores them is wrong either way.
-
-`npm run drift:check -- --docs --provider stripe` compares Stripe's official
-16-tool table with the vetted manifest and checks the hosted endpoint plus OAuth
-support. `list_available_accounts_or_orgs` and `manage_stripe_accounts` remain
-classified from an authenticated review even though the current public table
-does not list them. The command prints that discrepancy without treating docs
-silence as proof that a live account no longer serves them.
-
-## Conventions
-
-This connection is audited against
-[the provider conventions](./provider-conventions.md). Its verdict per
-convention, including every recorded exception, is the Stripe section of
-[the provider audit](https://github.com/zackbart/connecta/blob/main/records/provider-audit.md).