@zackbart/connecta 0.37.0 → 0.38.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (183) hide show
  1. package/CHANGELOG.md +80 -0
  2. package/README.md +2 -2
  3. package/bin/connecta.mjs +1 -39
  4. package/bin/version.mjs +1 -1
  5. package/dist/access-tokens.js +2 -4
  6. package/dist/agent-identity.js +1 -1
  7. package/dist/auth/clerk-sdk/generated.js +2 -1
  8. package/dist/auth/cloudflare-access.d.ts +3 -1
  9. package/dist/auth/cloudflare-access.js +22 -11
  10. package/dist/auth/downstream-oauth.js +195 -270
  11. package/dist/auth/downstream-revocation.js +1 -1
  12. package/dist/auth/oauth-grant.js +11 -0
  13. package/dist/auth/oauth-token-response.js +1 -1
  14. package/dist/auth/vercel-agent.js +2 -1
  15. package/dist/auth-elicitation.js +2 -2
  16. package/dist/branding.d.ts +1 -15
  17. package/dist/branding.js +2 -2
  18. package/dist/bytes.js +42 -0
  19. package/dist/call-admission-context.js +2 -5
  20. package/dist/call-admission.js +5 -0
  21. package/dist/call-recovery.js +0 -3
  22. package/dist/catalog-cache.js +26 -7
  23. package/dist/catalog-fingerprint.js +2 -18
  24. package/dist/catalog-revision.js +9 -0
  25. package/dist/catalog-service.js +51 -20
  26. package/dist/config-defaults.d.ts +1 -0
  27. package/dist/config-defaults.js +1 -0
  28. package/dist/config-schema.d.ts +1 -1
  29. package/dist/config-schema.js +6 -2
  30. package/dist/config.d.ts +41 -14
  31. package/dist/config.js +21 -71
  32. package/dist/connector-caller.js +1 -1
  33. package/dist/connectors/api-connector.js +4 -3
  34. package/dist/connectors/guarded-fetch.d.ts +0 -6
  35. package/dist/connectors/guarded-fetch.js +1 -11
  36. package/dist/connectors/remote-mcp.js +93 -69
  37. package/dist/connectors/resource-uri.js +0 -4
  38. package/dist/credentials.js +3 -0
  39. package/dist/d1.d.ts +0 -89
  40. package/dist/d1.js +0 -34
  41. package/dist/downstream-input.js +2 -2
  42. package/dist/execute.js +161 -116
  43. package/dist/executor-result.js +2 -1
  44. package/dist/executors/quickjs-runtime.js +2 -25
  45. package/dist/executors/quickjs.js +1 -1
  46. package/dist/guest-runtime.js +5 -3
  47. package/dist/guest-types.d.ts +5 -5
  48. package/dist/http/client.js +1 -1
  49. package/dist/http/errors.js +2 -2
  50. package/dist/http/json-schema.js +1 -1
  51. package/dist/http/node-transport.js +0 -1
  52. package/dist/http/oauth.js +1 -1
  53. package/dist/http/paging.js +6 -9
  54. package/dist/http/provider.js +1 -1
  55. package/dist/http/safety.js +1 -1
  56. package/dist/http/services.js +1 -8
  57. package/dist/http/tools.js +1 -7
  58. package/dist/http/vendor.js +7 -7
  59. package/dist/identity.js +2 -6
  60. package/dist/index.js +1 -2
  61. package/dist/invocation-auth.js +2 -1
  62. package/dist/invocation.js +8 -2
  63. package/dist/meta-tools.js +27 -27
  64. package/dist/native-tools.js +2 -1
  65. package/dist/oauth-handoff.js +2 -2
  66. package/dist/operation-vocabulary.js +1 -1
  67. package/dist/operator-record.d.ts +8 -2
  68. package/dist/operator-record.js +18 -50
  69. package/dist/operator-ui/contract.d.ts +4 -2
  70. package/dist/operator-ui/generated.js +3 -3
  71. package/dist/operator-ui/model.d.ts +7 -2
  72. package/dist/program-writes.js +3 -8
  73. package/dist/provider-call.js +0 -7
  74. package/dist/provider.d.ts +1 -1
  75. package/dist/providers/_shared/google/kit.js +1 -6
  76. package/dist/providers/_shared/google/service-account.js +1 -3
  77. package/dist/providers/_shared/google/workspace.d.ts +1 -1
  78. package/dist/providers/_shared/guide.js +3 -0
  79. package/dist/providers/_shared/json.js +12 -0
  80. package/dist/providers/_shared/rest/compact-index.js +1 -1
  81. package/dist/providers/_shared/rest/kit.js +1 -3
  82. package/dist/providers/_shared/rest/operation-index.js +1 -3
  83. package/dist/providers/_shared/rest/value-safety.js +26 -28
  84. package/dist/providers/breeze/api.js +2 -7
  85. package/dist/providers/breeze/index.js +4 -2
  86. package/dist/providers/breeze/tools.js +3 -4
  87. package/dist/providers/ccb/api.js +1 -6
  88. package/dist/providers/ccb/index.js +2 -1
  89. package/dist/providers/ccb/tools.js +1 -6
  90. package/dist/providers/cloudflare/api.js +2 -2
  91. package/dist/providers/cloudflare/index.js +2 -1
  92. package/dist/providers/cloudflare/safety.js +3 -3
  93. package/dist/providers/docs/tools.js +2 -10
  94. package/dist/providers/drive/tools.js +12 -25
  95. package/dist/providers/forms/tools.js +1 -9
  96. package/dist/providers/gmail/tools.js +5 -21
  97. package/dist/providers/overflow/api.js +1 -3
  98. package/dist/providers/overflow/index.js +2 -1
  99. package/dist/providers/overflow/tools.js +3 -7
  100. package/dist/providers/planning-center/api.js +2 -1
  101. package/dist/providers/planning-center/lib/constants.d.ts +1 -1
  102. package/dist/providers/planning-center/lib/json-api.js +1 -9
  103. package/dist/providers/planning-center/tools.js +2 -1
  104. package/dist/providers/sheets/tools.js +1 -9
  105. package/dist/providers/slides/tools.js +4 -13
  106. package/dist/providers/stripe/index.js +2 -1
  107. package/dist/providers/stripe/safety.js +2 -2
  108. package/dist/providers/tithely/api.js +2 -7
  109. package/dist/providers/tithely/index.js +3 -2
  110. package/dist/providers/tithely/tools.js +7 -5
  111. package/dist/providers/vercel/api.js +1 -6
  112. package/dist/providers/vercel/lib/pin.js +1 -1
  113. package/dist/providers/vercel/safety.js +1 -1
  114. package/dist/providers/vercel/tools.js +2 -1
  115. package/dist/redaction-marker.js +2 -2
  116. package/dist/registry.d.ts +4 -1
  117. package/dist/registry.js +35 -22
  118. package/dist/request-principal.js +15 -2
  119. package/dist/request-state.js +2 -2
  120. package/dist/routes/access-tokens.js +1 -1
  121. package/dist/routes/activity-disclosure.js +1 -1
  122. package/dist/routes/connect.js +2 -2
  123. package/dist/routes/credentials.js +1 -1
  124. package/dist/routes/dispatch.js +10 -0
  125. package/dist/routes/mcp.js +23 -21
  126. package/dist/routes/oauth-management.js +1 -1
  127. package/dist/routes/operator.js +53 -7
  128. package/dist/routes/shared.d.ts +8 -8
  129. package/dist/routes/shared.js +22 -15
  130. package/dist/routes/ui-config.js +6 -6
  131. package/dist/routes/ui-data.js +2 -2
  132. package/dist/routes/ui.js +9 -4
  133. package/dist/runtime/call-admission.js +1 -1
  134. package/dist/runtime/call.js +1 -1
  135. package/dist/runtime/settlement.js +1 -1
  136. package/dist/runtime/shared-read.js +2 -15
  137. package/dist/sent-secrets.d.ts +14 -6
  138. package/dist/sent-secrets.js +231 -85
  139. package/dist/server.js +4 -4
  140. package/dist/skills.js +8 -35
  141. package/dist/sqlite.d.ts +0 -19
  142. package/dist/sqlite.js +2 -83
  143. package/dist/storage/keys.js +29 -124
  144. package/dist/storage/sql-native.js +14 -111
  145. package/dist/storage/sql.d.ts +1 -24
  146. package/dist/storage/sql.js +1 -12
  147. package/dist/tool-error.js +4 -0
  148. package/dist/types.d.ts +4 -3
  149. package/dist/ui.js +3 -0
  150. package/dist/url-safety.js +0 -4
  151. package/dist/usage-guide.js +2 -2
  152. package/dist/version.d.ts +1 -1
  153. package/dist/version.js +1 -1
  154. package/dist/worker.js +1 -1
  155. package/documentation/README.md +6 -42
  156. package/documentation/architecture.md +190 -507
  157. package/documentation/auth.md +172 -58
  158. package/documentation/code-mode.md +98 -66
  159. package/documentation/deploying.md +19 -40
  160. package/documentation/integrating.md +8 -19
  161. package/documentation/meta-tools.md +23 -6
  162. package/documentation/migration-0.33.md +5 -5
  163. package/documentation/migration-0.34.md +2 -4
  164. package/documentation/migration-retired-layouts.md +74 -0
  165. package/documentation/operator-tests.md +19 -119
  166. package/documentation/operator-ui.md +46 -8
  167. package/documentation/provider-auth-migration.md +4 -10
  168. package/documentation/provider-migration-0.29.md +4 -15
  169. package/examples/worker/AGENTS.md +4 -6
  170. package/examples/worker/README.md +20 -115
  171. package/guides/connecting-agents.md +7 -30
  172. package/guides/how-it-works.md +2 -2
  173. package/guides/safety-and-trust.md +4 -1
  174. package/package.json +19 -19
  175. package/templates/node/README.md +9 -26
  176. package/templates/node/package.json +1 -1
  177. package/dist/auth/oauth-v2-migration.js +0 -135
  178. package/dist/provider-call-facts.d.ts +0 -115
  179. package/dist/provider-call.d.ts +0 -112
  180. package/dist/storage/d1-copy.js +0 -255
  181. package/dist/storage/sql-schema.d.ts +0 -6
  182. package/examples/worker/kv-to-d1.wrangler.jsonc +0 -26
  183. package/examples/worker/scripts/copy-kv-to-d1.mjs +0 -162
@@ -115,8 +115,8 @@ unbounded data.
115
115
 
116
116
  With meta-tools, one discovered read can use a direct call. Finding an unfamiliar
117
117
  action, combining several calls, or reducing a large answer belongs in a program.
118
- On a writable endpoint, a program may also change data. The AI app decides
119
- whether to ask for approval before running it.
118
+ On a writable endpoint, a program may also change data; see
119
+ [approval boundaries](./safety-and-trust.md#read-only-blocks-actions-that-change-data).
120
120
 
121
121
  The [endpoint workflow](../documentation/operating.md) and
122
122
  [code reference](../documentation/code-mode.md) explain the mechanics.
@@ -71,7 +71,10 @@ or contradictory read hints count as writes, but a service can mislabel an
71
71
  action and an operator can override its label. Use restricted service
72
72
  credentials as another boundary where possible.
73
73
 
74
- The AI app owns approvals. It may ask based on an earlier tool label. If a
74
+ The Eve helper defaults to unattended authorized writes. For interactive use,
75
+ `gateWrites: true` asks before tools not marked read-only; an explicit Eve
76
+ approval policy takes precedence. The AI app owns approvals. It may ask based
77
+ on an earlier tool label. If a
75
78
  read becomes a write, a writable pool can execute it without a fresh
76
79
  approval; a read-only pool refuses it. Connecta does not pause a program to
77
80
  ask a person partway through.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zackbart/connecta",
3
- "version": "0.37.0",
3
+ "version": "0.38.0",
4
4
  "type": "module",
5
5
  "sideEffects": false,
6
6
  "description": "One MCP to rule them all — a single MCP endpoint aggregating many downstream connectors behind a code-first surface of six meta-tools.",
@@ -191,7 +191,6 @@
191
191
  "check:declarations": "node scripts/check-declarations.mjs --dist .",
192
192
  "check:bundle": "node scripts/bundle-size.mjs",
193
193
  "providers:check": "tsx scripts/drift-check.mjs --specs --manual",
194
- "drift:check": "tsx scripts/drift-check.mjs",
195
194
  "eval:selftest": "tsx eval/selftest.ts",
196
195
  "eval:agent": "tsx eval/run-agent.ts",
197
196
  "eval:smoke": "tsx eval/run-smoke.ts",
@@ -257,31 +256,32 @@
257
256
  "devDependencies": {
258
257
  "@clerk/backend": "3.12.0",
259
258
  "@cloudflare/codemode": "^0.5.0",
260
- "@cloudflare/vitest-pool-workers": "^0.18.8",
261
- "@cloudflare/workers-types": "^4.20250101.0 || ^5.0.0",
259
+ "@cloudflare/vitest-plugin": "^1.4.3",
260
+ "@cloudflare/workers-types": "5.20260804.1",
262
261
  "@effect/platform-node": "4.0.5",
263
262
  "@fontsource-variable/hanken-grotesk": "^5.3.0",
264
263
  "@fontsource-variable/jetbrains-mono": "^5.3.0",
265
- "@playwright/test": "^1.62.0",
266
- "@radix-ui/react-dialog": "^1.2.0",
267
- "@radix-ui/react-tabs": "^1.1.22",
268
- "@tanstack/react-router": "^1.170.41",
269
- "@types/node": "^22.0.0",
264
+ "@playwright/test": "^1.64.1",
265
+ "@radix-ui/react-dialog": "^1.3.1",
266
+ "@radix-ui/react-tabs": "^1.2.1",
267
+ "@tanstack/react-router": "^1.170.44",
268
+ "@types/node": "^22.20.5",
270
269
  "@types/react": "^19.3.0",
271
270
  "@types/react-dom": "^19.3.0",
272
271
  "alchemy": "2.0.0-beta.83",
273
272
  "cmdk": "^1.1.1",
274
- "esbuild": "^0.28.0",
275
- "knip": "^6.29.0",
276
- "oxfmt": "0.72.0",
277
- "oxlint": "^1.76.0",
273
+ "esbuild": "^0.28.2",
274
+ "knip": "^6.41.0",
275
+ "oxfmt": "0.73.0",
276
+ "oxlint": "^1.88.0",
278
277
  "quickjs-emscripten": "^0.32.0",
279
- "react": "^19.3.0",
280
- "react-dom": "^19.3.0",
281
- "tsx": "^4.23.1",
282
- "typescript": "^5.9.3",
278
+ "react": "^19.3.1",
279
+ "react-dom": "^19.3.1",
280
+ "tsx": "^4.23.15",
281
+ "typescript": "^6.0.3",
283
282
  "undici": "6.29.1",
284
- "vitest": "^4.1.6",
285
- "wrangler": "^4.114.0"
283
+ "vite": "^8.3.4",
284
+ "vitest": "^5.0.4",
285
+ "wrangler": "^4.151.0"
286
286
  }
287
287
  }
@@ -19,19 +19,9 @@ npm start
19
19
  ```
20
20
 
21
21
  Keep the template's pinned `undici` dependency and its `listen` import from
22
- `@zackbart/connecta/node`. `listen` installs the owned HTTP transport used by
23
- every maintained-provider request, reads included, remote MCP writes, and
24
- downstream OAuth token, registration and revocation POSTs.
25
- Without `listen()`, maintained-provider writes, reviewed POST reads and remote
26
- MCP writes are refused before sending; downstream OAuth credential POSTs also
27
- require the owned sender. It connects directly by default. For an HTTP(S) CONNECT
28
- proxy, configure `listen(connecta, { port, proxy: "http://proxy.example.com:8080" })`
29
- in `src/index.ts`. Ambient proxy variables and host dispatchers do not configure
30
- the owned sender. Remote MCP reads and OAuth discovery GETs retain native fetch
31
- and need their own host proxy policy. An uncertain refresh requires fresh
32
- authorization rather than replaying the spent token. See
33
- [Node transport requirements](https://github.com/zackbart/connecta/blob/main/documentation/deploying.md#start-on-node)
34
- for proxy credentials and TLS trust.
22
+ `@zackbart/connecta/node`. Follow the
23
+ [Node transport and proxy requirements](https://github.com/zackbart/connecta/blob/main/documentation/deploying.md#start-on-node)
24
+ when changing `src/index.ts` or configuring egress.
35
25
 
36
26
  The manifest approves only `esbuild@0.28.2` to run its install script. `tsx`
37
27
  uses esbuild to run this TypeScript source, so that script is part of the
@@ -128,19 +118,12 @@ first use, and commits one row per write. Back it up as one file, together
128
118
  with its `-wal` file while the server runs. Node 22 and 23 print an
129
119
  experimental-feature warning for `node:sqlite` once at startup.
130
120
 
131
- Upgrading from 0.28, which kept state in `.connecta-state.json`: stop the
132
- server, then copy the old file into the database once, before the first start:
133
-
134
- ```sh
135
- npx connecta migrate-state .connecta-state.json .connecta.sqlite
136
- ```
137
-
138
- In the container, mount the old file and import it into the volume:
139
- `docker compose run --rm -v "$PWD/.connecta-state.json:/import/state.json:ro"
140
- connecta npx connecta migrate-state /import/state.json /data/connecta.sqlite`. It copies every live entry with its expiry, keeps any
141
- key the database already holds, and never changes the old file; delete that
142
- once the deployment is verified. The 0.28 activity log
143
- (`.connecta-activity.jsonl`) is not imported; history starts fresh.
121
+ Upgrading from the pre-SQLite JSON state format requires importing it with
122
+ Connecta 0.37.1 before installing the release that removes migrations. The
123
+ current package has no `importStateFile` or `connecta migrate-state`; SQLite
124
+ never reads `.connecta-state.json`. Follow the installed package's
125
+ `documentation/migration-retired-layouts.md`, including opening every OAuth
126
+ grant on 0.37.1, before changing the pin.
144
127
 
145
128
  A build with no lockfile in the context resolves the pinned Connecta version
146
129
  itself, and a lockfile npm writes inside the image never reaches this project.
@@ -18,7 +18,7 @@
18
18
  },
19
19
  "dependencies": {
20
20
  "@clerk/backend": "^3.12.0",
21
- "@zackbart/connecta": "0.37.0",
21
+ "@zackbart/connecta": "0.38.0",
22
22
  "quickjs-emscripten": "0.32.0",
23
23
  "undici": "6.29.1"
24
24
  },
@@ -1,135 +0,0 @@
1
- import { runEdge } from "../runtime/run.js";
2
- import { oauthV2Keys } from "../storage/keys.js";
3
- import { authAll, authCall, authFlow, authInvoke, authMap, authMethod, authProgram, authStorage, registerAuth, } from "./native.js";
4
- function plainObject(value) {
5
- return value !== null && typeof value === "object" && !Array.isArray(value);
6
- }
7
- function parse(raw) {
8
- try {
9
- return JSON.parse(raw);
10
- }
11
- catch {
12
- return undefined;
13
- }
14
- }
15
- /** The issuer a discovery record names, as the SDK derives it. */
16
- export function discoveryIssuer(state) {
17
- if (!plainObject(state) || typeof state.authorizationServerUrl !== "string")
18
- return undefined;
19
- const metadata = state.authorizationServerMetadata;
20
- const issuer = plainObject(metadata) && typeof metadata.issuer === "string" ? metadata.issuer : state.authorizationServerUrl;
21
- return issuer === "" ? undefined : issuer;
22
- }
23
- /**
24
- * Layout 2's grant in this namespace, or nothing when it holds none.
25
- *
26
- * Only issuer-stamped envelopes (`connectaOAuthVersion: 2`, written since
27
- * v0.9.0) of the active generation are read; anything older, and any value
28
- * the vault cannot open, is left behind, as layout 2's own flow entry would
29
- * have retired it. A grant is kept only when every credential carries a
30
- * stamp, the stamps agree, and they name the server the generation's
31
- * discovery names, if any; otherwise it migrates empty and needs consent.
32
- * One-shot consent state (pending URL, verifier, state) is not carried.
33
- */
34
- export function readV2Grant(storage, sealer) {
35
- return runEdge(authProgram(readV2GrantNative, [storage, sealer]));
36
- }
37
- const readV2GrantNative = /* @__PURE__ */ registerAuth(readV2Grant, function (storage, sealer) {
38
- return authFlow(function* () {
39
- const keys = (yield authCall(listV2Keys, [storage]));
40
- if (keys.length === 0)
41
- return undefined;
42
- const generation = (yield authStorage(storage, "get", [oauthV2Keys.generation])) ?? "legacy";
43
- if (generation.startsWith("disconnected:"))
44
- return { disconnected: true, body: {} };
45
- if (!generation.startsWith("v2:") && generation !== "legacy") {
46
- // An unfinished reset, or a numeric generation from before epochs.
47
- return { disconnected: false, body: {} };
48
- }
49
- const epoch = generation === "legacy" ? null : generation;
50
- const read = authMethod((field) => {
51
- return authFlow(function* () {
52
- const physicalKey = oauthV2Keys.value(field, epoch);
53
- const raw = (yield authStorage(storage, "get", [physicalKey]));
54
- if (raw === null)
55
- return undefined;
56
- let parsed = parse(raw);
57
- if (plainObject(parsed) && parsed.connectaOAuthSealed === 1 && typeof parsed.sealed === "string") {
58
- if (!sealer)
59
- return undefined;
60
- try {
61
- parsed = parse((yield authInvoke(sealer, "open", [physicalKey, parsed.sealed])));
62
- }
63
- catch {
64
- return undefined;
65
- }
66
- }
67
- if (plainObject(parsed) &&
68
- parsed.connectaOAuthVersion === 2 &&
69
- parsed.generation === generation &&
70
- (parsed.issuer === undefined || typeof parsed.issuer === "string") &&
71
- (parsed.binding === undefined || typeof parsed.binding === "string")) {
72
- return {
73
- value: parsed.value,
74
- ...(parsed.issuer !== undefined ? { issuer: parsed.issuer } : {}),
75
- ...(parsed.binding !== undefined ? { binding: parsed.binding } : {}),
76
- ...(parsed.carried === true ? { carried: true } : {}),
77
- };
78
- }
79
- // Layout 2 wrote discovery bare under the legacy generation.
80
- return field === oauthV2Keys.field.discovery && epoch === null && discoveryIssuer(parsed)
81
- ? { value: parsed }
82
- : undefined;
83
- });
84
- });
85
- const [client, tokens, discovery] = (yield authAll([
86
- authCall(read, [oauthV2Keys.field.client]),
87
- authCall(read, [oauthV2Keys.field.tokens]),
88
- authCall(read, [oauthV2Keys.field.discovery]),
89
- ], false));
90
- const named = discovery ? discoveryIssuer(discovery.value) : undefined;
91
- const credentials = [client, tokens].filter((value) => value !== undefined);
92
- const issuer = credentials[0]?.issuer ?? named;
93
- const consistent = credentials.every((value) => value.issuer !== undefined && value.issuer === issuer && plainObject(value.value)) &&
94
- (named === undefined || named === issuer);
95
- if (!consistent || issuer === undefined)
96
- return { disconnected: false, body: {} };
97
- return {
98
- disconnected: false,
99
- body: {
100
- issuer,
101
- ...(client
102
- ? {
103
- client: {
104
- value: client.value,
105
- ...(client.binding !== undefined ? { binding: client.binding } : {}),
106
- ...(client.carried ? { carried: true } : {}),
107
- },
108
- }
109
- : {}),
110
- ...(tokens ? { tokens: tokens.value } : {}),
111
- ...(discovery && named !== undefined ? { discovery: discovery.value } : {}),
112
- },
113
- };
114
- });
115
- });
116
- /** Only historical families are removed, never grants, flows, or leases. */
117
- function listV2Keys(storage) {
118
- return runEdge(authProgram(listV2KeysNative, [storage]));
119
- }
120
- const listV2KeysNative = /* @__PURE__ */ registerAuth(listV2Keys, function (storage) {
121
- return authFlow(function* () {
122
- return (yield authStorage(storage, "list", [oauthV2Keys.scan])).filter((key) => oauthV2Keys.family.prefixes.some((prefix) => key.startsWith(prefix)));
123
- });
124
- });
125
- /** Return true only when every historical key was deleted. */
126
- export function deleteV2Keys(storage) {
127
- return runEdge(authProgram(deleteV2KeysNative, [storage]));
128
- }
129
- const deleteV2KeysNative = /* @__PURE__ */ registerAuth(deleteV2Keys, function (storage) {
130
- return authFlow(function* () {
131
- const keys = (yield authCall(listV2Keys, [storage]));
132
- const results = (yield authMap(keys, (key) => authStorage(storage, "delete", [key]), true));
133
- return results.every((result) => result.status === "fulfilled");
134
- });
135
- });
@@ -1,115 +0,0 @@
1
- import { ConnectorCallError } from "./errors.js";
2
- import type { Connector } from "./types.js";
3
- export interface ProviderRequest {
4
- readonly dispatched: boolean;
5
- readonly status?: number;
6
- auxiliary: boolean;
7
- /** A kit auxiliary declared as a read lacked physical GET/HEAD proof at dispatch. */
8
- readonly blocksAuxiliaryProof?: true;
9
- provider: string;
10
- /** The HTTP method it was sent with, when its channel knows it. */
11
- readonly method?: string;
12
- /** Positive operation/tool evidence; an HTTP method alone proves no read. */
13
- classification?: "read" | "write" | undefined;
14
- /** Remote MCP's source class said write, recorded at physical dispatch. */
15
- readonly sourceWrite?: true;
16
- /** The genuine, legal idempotency key the vendor honors that it carried; nothing else. */
17
- key?: string;
18
- /**
19
- * Its answer was a 401 that the transport's reviewed `authBeforeExecution`
20
- * evidence covers: the vendor rejected the credential before it acted on
21
- * the request. Only that makes a 401 a refusal (`servedRefusal`).
22
- */
23
- authBeforeExecution?: true;
24
- /**
25
- * Its answer was a 401, and a renewal then replaced the credential it sent
26
- * with a different one ({@link renewedAfterUnauthorized}). The 401 no
27
- * longer needs the operator's recovery. The single `settleWrite` decider
28
- * still reports unknown, without the handoff (Q8).
29
- */
30
- readonly renewed?: true;
31
- }
32
- export type CallTool = Connector["callTool"];
33
- interface Boundary {
34
- /** The api() or remoteMcp() object whose own code enters the logical call. */
35
- boundary: object;
36
- own: CallTool;
37
- }
38
- export declare function originalCallIdentity(connector: object): object;
39
- export declare function boundaryFor(connector: object): Boundary | undefined;
40
- export declare function delegatorFor(connector: object): CallTool | undefined;
41
- /** A physical send owns its fields permanently; its own answer is recorded once. */
42
- export declare function recordRequestField(request: ProviderRequest, field: keyof ProviderRequest, value: unknown): void;
43
- export declare function recordProviderResponse(request: ProviderRequest, status: number): void;
44
- /**
45
- * Declare that every request the connector's handlers send goes through a
46
- * channel the call ledger records: a guarded transport, `ctx.fetch`, or
47
- * `ctx.oauth.fetch`. Only then does an empty ledger prove that a failed
48
- * write never left. Maintained providers declare it; an arbitrary `api()`
49
- * handler can reach the network some other way, so its ledger proves nothing.
50
- */
51
- export declare function tracksEveryRequest<T extends object>(connector: T): T;
52
- export declare function tracksRequests(connector: object): boolean;
53
- /**
54
- * Declare a maintained connector whose `callTool` hands each call to at most
55
- * one api() or remoteMcp() boundary and sends nothing else that could apply
56
- * it (GitHub). Only then may that boundary's verdict stand for the call. The
57
- * object and its function are recorded now, at construction: a later
58
- * assignment to the property, or a copy of the object, declares nothing.
59
- */
60
- export declare function delegatesEachCall<T extends Connector>(connector: T): T;
61
- /**
62
- * Record a just-built api() or remoteMcp() object as a boundary, with its
63
- * published `callTool`. Its own code then names the same object, from its
64
- * closure, in {@link enterProviderBoundary}.
65
- */
66
- export declare function providerBoundary(connector: Connector): void;
67
- /**
68
- * `alias` serves `base` itself (`defineProvider`'s inheriting stamp), so it
69
- * takes `base`'s recorded identities. Only construction code calls this.
70
- */
71
- export declare function aliasCallIdentity(alias: object, base: object): void;
72
- /**
73
- * Whether a served HTTP status says the request was refused, not applied: a
74
- * 4xx other than 408. A 408 is a timeout, whose request may have been acted
75
- * on; a 2xx or 5xx never proves a write unapplied. A 401 passes here, and
76
- * `servedRefusal` still asks for the vendor's reviewed evidence.
77
- */
78
- export declare function refusedStatus(status: number | undefined): boolean;
79
- /**
80
- * Refusal provenance, recorded where the answer is observed: the request was
81
- * served a refusing status (`refusedStatus`) and the mapper failed on it. An
82
- * error code alone is never this evidence.
83
- */
84
- export declare function vendorRefusal<T>(error: T, request: ProviderRequest): T;
85
- /** An authorization verdict, the kind that keeps the `authorize_connector` handoff. */
86
- export declare function authorizationFailure(error: unknown): error is ConnectorCallError;
87
- /**
88
- * The authorization verdict `request`'s own 401 answer was mapped to, as
89
- * {@link vendorRefusal} recorded it. Undefined when nothing mapped that
90
- * answer, such as a body past the ceiling.
91
- */
92
- export declare function unauthorizedAnswer(request: ProviderRequest): ConnectorCallError | undefined;
93
- /**
94
- * A renewal answered `request`'s own 401 (a refresh, a login, a fresh token
95
- * minted) with `fresh`, a credential other than `sent`, the one the request
96
- * carried: that 401 no longer needs the operator's recovery (Q8). It names
97
- * the one request it answered and never marks another. A renewal that hands
98
- * back the credential the request already sent (an earlier recovery reused)
99
- * renewed nothing.
100
- */
101
- export declare function renewedAfterUnauthorized(request: ProviderRequest | undefined, sent: string, fresh: string): void;
102
- export declare function refusalRequest(error: unknown): ProviderRequest | undefined;
103
- export declare function knownProviderFailure<T>(error: T): T;
104
- export declare function isKnownProviderFailure(error: unknown): boolean;
105
- /** Withdraw a verdict that does not hold for the call that reports it. */
106
- export declare function forgetProviderFailure(error: object): void;
107
- /** Preserve internal verdicts and resend advice through redaction and provider recovery wording. */
108
- export declare function carryProviderFailure<T>(from: unknown, to: T): T;
109
- /** Mark a verdict that already accounts for a write's 401 in its own words. */
110
- export declare function explainedUnauthorizedVerdict<T>(error: T): T;
111
- export declare function explainsUnauthorized(error: unknown): boolean;
112
- /** Mark a verdict the Q8 decision made, final for every step after it. */
113
- export declare function settledWrite<T>(error: T): T;
114
- export declare function isSettledWrite(error: unknown): boolean;
115
- export {};
@@ -1,112 +0,0 @@
1
- import { type ProviderRequest, type CallTool } from "./provider-call-facts.js";
2
- import type { ConnectorContext } from "./types.js";
3
- export interface ProviderCall {
4
- requests: ProviderRequest[];
5
- classification?: "read" | "write" | undefined;
6
- /** The handler settled: its outcome may be reported, so nothing more leaves. */
7
- closed: boolean;
8
- /** The calls of api() boundaries entered beneath this one's handler. */
9
- nested: ProviderCall[];
10
- /** The call whose handler entered this one; undefined for the outermost. */
11
- parent?: ProviderCall;
12
- }
13
- export interface LogicalCall {
14
- target: object;
15
- entered: CallTool;
16
- boundaries: object[];
17
- /** Every resource request dispatched under it, once per dispatch, from any ledger. */
18
- sent: ProviderRequest[];
19
- /** Auxiliary GET/HEAD dispatches without method overrides, apart from resource writes and auth POSTs. */
20
- auxiliaryReads: ProviderRequest[];
21
- /** A kit auxiliary declared as a read dispatched without physical read proof. */
22
- nonReadAuxiliaryDispatched: boolean;
23
- }
24
- export declare function providerCallContext(ctx: ConnectorContext, classification?: "read" | "write"): ConnectorContext;
25
- /** Whether `ctx`'s call was entered by another api() boundary's handler. */
26
- export declare function nestedProviderCall(ctx: ConnectorContext): boolean;
27
- export declare function providerRequests(ctx: ConnectorContext): readonly ProviderRequest[] | undefined;
28
- /**
29
- * Every request the ledgers of api() boundaries nested beneath `ctx`'s call
30
- * recorded, at any depth: an inner call's 401 still decides the outer's
31
- * write (Q8), whatever the outer handler made of the inner's failure.
32
- */
33
- export declare function nestedProviderRequests(ctx: ConnectorContext): ProviderRequest[];
34
- /**
35
- * End the call's ledger before its outcome is decided. A request still in
36
- * flight already counts as dispatched; one that has not left yet (a sibling
37
- * still reading its credential, say) is refused by {@link dispatchProviderRequest}
38
- * and never leaves after the failure is reported.
39
- */
40
- export declare function closeProviderCall(ctx: ConnectorContext): void;
41
- /**
42
- * Refuse every request after its request scope ends, before credential reads
43
- * and again immediately before dispatch. Resource requests also require an
44
- * open call. Auxiliary requests (token mints, lookups) may outlive that call,
45
- * but never their request.
46
- */
47
- export declare function assertProviderCallOpen(ctx: ConnectorContext, provider: string, auxiliary: boolean): void;
48
- /** Record that a request leaves now; synchronous with the send that follows it. */
49
- export declare function dispatchProviderRequest(ctx: ConnectorContext | undefined, request: ProviderRequest, headers?: HeadersInit, method?: string | undefined): void;
50
- export declare function recordingFetch<T extends object>(send: T): T;
51
- export declare function isRecordingFetch(send: object | undefined): boolean;
52
- export declare function handoffProviderRequest(init: RequestInit, request: ProviderRequest): void;
53
- export declare function takeProviderHandoff(init: RequestInit): ProviderRequest | undefined;
54
- export declare function bindProviderResponse(response: object, request: ProviderRequest, owner: ProviderRequest | undefined): void;
55
- export declare function responseProviderRequest(response: object, owner: ProviderRequest): ProviderRequest | undefined;
56
- export declare function providerRequest(ctx: ConnectorContext, auxiliary: boolean, provider: string, sent?: {
57
- method?: string;
58
- key?: string;
59
- classification?: "read" | "write";
60
- }): ProviderRequest;
61
- /**
62
- * The invocation opens one logical call on the context it hands a connector,
63
- * naming the exact object and `callTool` function it is about to invoke.
64
- */
65
- export declare function openLogicalCall(ctx: ConnectorContext, target: object, entered: CallTool): LogicalCall;
66
- /**
67
- * An api() or remoteMcp() boundary was entered under `ctx`'s logical call.
68
- * `boundary` is the object it was built as, from its own closure, never `this`.
69
- */
70
- export declare function enterProviderBoundary(ctx: ConnectorContext, boundary: object): void;
71
- /**
72
- * Whether a failure's known mark holds for its whole logical call (INV-9).
73
- * A boundary marks a write known only when every request it dispatched is
74
- * proven unapplied, so the mark stands when that boundary owned the call
75
- * ({@link ownsLogicalCall}) and at most one boundary was entered. A wrapper
76
- * that composed several calls, or could send around them, never inherits an
77
- * inner verdict.
78
- */
79
- export declare function knownCallFailure(call: LogicalCall | undefined, error: unknown): boolean;
80
- /**
81
- * Positive proof that a complete tracked call dispatched only auxiliaries,
82
- * including a recorded resource read (positive GET/HEAD evidence). An
83
- * authentication POST alone is not evidence of that call's resource work:
84
- * token mints can be shared with callers whose ledgers did not send them.
85
- * An empty resource ledger is not this proof: even a declared api() entry
86
- * can report a timeout and recovery facts without recording any dispatch.
87
- * Keep those calls conservative rather than inferring an auxiliary failure
88
- * from the absence of a resource request. Wrappers and untracked boundaries
89
- * cannot borrow an inner call's observations.
90
- */
91
- export declare function onlyAuxiliaryRequests(call: LogicalCall | undefined): boolean;
92
- /**
93
- * Whether reusing `key` with the exact original arguments cannot repeat any
94
- * write of `ctx`'s logical call, the one basis for key-reuse advice (INV-9).
95
- * It holds only when the call entered exactly one boundary, which owned it
96
- * and tracks every request, and sent exactly one write, carrying `key`. A
97
- * request counts as a read only with positive classification and a recorded
98
- * GET or HEAD ({@link readRequest}). An inner request's key never speaks for a composite,
99
- * a wrapper, a second write, or an earlier unrelated request.
100
- */
101
- export declare function keyProtectsCall(call: LogicalCall | undefined, key: string | undefined): boolean;
102
- /** Positive read evidence, with GET/HEAD as #902's additional conservative bound. */
103
- export declare function readRequest(request: Pick<ProviderRequest, "classification" | "method">, headers?: HeadersInit): boolean;
104
- export declare function providerFetch(ctx: ConnectorContext, provider: string, auxiliary: boolean, send: typeof fetch): typeof fetch;
105
- /** Whether an invocation opened the logical call `ctx` belongs to; it then settles Q8 itself. */
106
- export declare function inLogicalCall(ctx: object): boolean;
107
- /**
108
- * Every resource request dispatched under `ctx`'s logical call, from any
109
- * ledger, nested ones included; undefined outside one.
110
- */
111
- export declare function logicalCallRequests(ctx: object | undefined): readonly ProviderRequest[] | undefined;
112
- export { recordProviderResponse, tracksEveryRequest, tracksRequests, delegatesEachCall, providerBoundary, refusedStatus, vendorRefusal, authorizationFailure, unauthorizedAnswer, renewedAfterUnauthorized, refusalRequest, knownProviderFailure, isKnownProviderFailure, forgetProviderFailure, explainedUnauthorizedVerdict, explainsUnauthorized, settledWrite, isSettledWrite, type ProviderRequest, } from "./provider-call-facts.js";