@zackbart/connecta 0.5.0 → 0.6.1

package/README.md

@@ -2,9 +2,28 @@
 
 ![A monochrome clay Connecta hub joining many tools](./assets/connecta-clay-hero.png)
 
-One MCP to rule them all. A single MCP endpoint that aggregates many downstream
-connectors — remote MCP servers and plain HTTP APIs — and presents agents a fixed
-set of **nine meta-tools** instead of hundreds of individual tools.
+One MCP endpoint in front of all your connectors. Agents see nine tools instead
+of hundreds, and each client is configured once instead of once per integration.
+
+## The problem
+
+An agent connected to N MCP servers pays for all N before it does anything. Every
+server's tool list is injected into the context window at connect time — hundreds
+of definitions and their schemas, nearly all irrelevant to the task actually at
+hand. That budget is spent whether the model calls one of them or none, and it
+comes out of the same window the work needs.
+
+The second cost is configuration. Every client — Claude, Cursor, whatever comes
+next — has to be pointed at each server separately, with its own auth for each.
+Adding an integration means touching every client; rotating one token means
+finding every place it was pasted.
+
+## What connecta is
+
+One MCP endpoint you deploy — Cloudflare Worker, Node, or Docker — that
+aggregates your downstream connectors behind a fixed set of **nine meta-tools**.
+A connector is either a remote MCP server that connecta proxies, or a plain HTTP
+API with hand-written tool definitions and a fetch handler.
 
 ```
                                         ┌── remoteMcp("notion")   → mcp.notion.com
@@ -13,14 +32,96 @@ Claude / Cursor ── MCP ──▶  connecta ───┼── remoteMcp("lin
                                         └── api("internal")       → fetch(...)
 ```
 
-The agent always sees exactly nine tools; it searches when it needs something and
-describes only what it will call. Progressive disclosure is the point. Connectors
-are declared in TypeScript (config as code — adding one is a code change + deploy,
-no database of integrations), and the same fetch-based core runs on **Node** and
-**Cloudflare Workers**. Optionally, **code mode** adds a tenth tool that runs
-model-written orchestration code in a sandbox.
-
-## Installation
+Rather than receiving every tool up front, the agent discovers what it needs.
+`search_tools` returns ranked matches for a query and `describe_tools` returns
+schemas — compact by default, raw JSON Schema on request — for only the
+addresses it is about to call. `call_tool`,
+`batch_call`, and `call_destructive_tool` invoke them by address
+(`<connectorId>.<toolName>`). `list_connectors` reports what exists and whether
+it is reachable, `authorize_connector` starts a downstream OAuth flow,
+`get_result` pages through a result too large to return inline, and `skills`
+hands the model a short guide to choosing among the rest.
+
+That is the entire surface. The agent's context holds nine tool definitions
+whether ten tools sit behind them or a thousand — and the client holds one URL
+and one credential, no matter how many services that URL fans out to.
+
+An optional tenth meta-tool, `execute_code`, runs model-written async JavaScript
+in a sandbox with no network, filesystem, or environment access — only the
+explicitly read-only tools as callable globals — turning a loop, a join across
+connectors, or a filter over a large response into one round trip instead of a
+dozen. Configure no `executor` and connecta is exactly the nine-tool server.
+
+## Why it's shaped this way
+
+**Config as code, one deployment per tenant.** Connectors are declared in
+TypeScript. Adding one is a code change and a deploy — no database of
+integrations, no registration API, no runtime admin. A deployment is a small
+config file you can read in one sitting and review in a pull request, not a
+platform to administer.
+
+**Credentials stay server-side.** Downstream tokens live in an AES-GCM encrypted
+vault over the deployment's own storage, with the key held outside it. A
+connector reaches its own credential through `ctx.credential`; `/ui`, the
+meta-tools, and the code sandbox only ever see masked metadata. Rotating a token
+is an operator action rather than a redeploy — though writing to the vault is
+deliberately narrower than everything else, requiring a Clerk-authenticated
+operator on a same-origin request, so a bearer-only deployment cannot administer
+credentials from the browser. Which tools exist is still code either way.
+
+**Read-only is fail-closed.** Only tools explicitly annotated `readOnlyHint:
+true` are reachable through `call_tool`, `batch_call`, and the sandbox. Missing,
+false, or contradictory annotations do not get the benefit of the doubt: they
+require `call_destructive_tool`, which is itself annotated so the MCP host can
+put the question to a human. Connecta makes the boundary visible; approval is
+the host's job.
+
+**Toolkits scope what a team sees.** A deployment belongs to an org; a toolkit
+is a named view over its registry for one group inside that org — support sees
+Zendesk and Notion, exec also sees Gmail. A client selects one with
+`?toolkit=support` on the MCP URL, and a credential can be bound so it opens
+that view and nothing else. Inside a scoped session an out-of-scope address
+fails exactly as a nonexistent one does. Two teams, one deployment. Who gets in
+at all is the prior question: a static bearer token, or Clerk — where
+`allowedDomains: ["acme.com"]` admits anyone whose verified primary email is on
+your domain without enumerating users, and a `gate` hook handles what a domain
+rule cannot express. Both fail closed, and each one configured must pass.
+
+**Activity records the fact, not the payload.** The optional activity store logs
+which resolved tool ran, for whom, and how it went — never arguments, results,
+generated code, search text, or raw error messages. The exclusion is structural
+rather than a redaction pass: the event type has nowhere to put a payload, which
+is what keeps an operations log from becoming something worth stealing.
+
+**An operator dashboard that can only look.** `GET /ui` is a read-only status
+page with no build step: connector health, tool counts, downstream authorization
+links, credential controls, and an activity tab when a store is configured. It
+displays state and administers credentials; it cannot change what an agent is
+allowed to call. Credentials connecta stores are also probed for liveness
+proactively — using each connector's own test or status hook, never a downstream
+tool call — so a dead token surfaces as `auth_required` with the URL to open on
+`/ui` and in `list_connectors` before an agent's real call trips over it.
+
+## When not to use it
+
+Connecta is deliberately small, and declines several tempting shapes.
+It is **not multi-tenant** — one deployment is one tenant, with one registry and
+one credential store, and toolkits are scoped views rather than tenants. There
+is **no policy engine**, no approvals, and no pauses — access decisions are
+fixed ones connecta already knows how to answer (is this tool read-only, may
+this credential open this toolkit), not rules you author. There is **no runtime
+administration** — you cannot add a connector from a browser or an API. It
+aggregates **tools only**, not MCP resources or prompts, and it will not ingest
+a **GraphQL** schema, because generating hundreds of low-quality tool
+definitions is the problem the nine meta-tools exist to solve. OpenAPI is a
+softer no: not built in today, not refused either, and tracked as
+[issue #26](https://github.com/zackbart/connecta/issues/26). If you want a
+hosted multi-tenant integration platform with an approval workflow, this is the
+wrong shape; the
+[non-goals](https://github.com/zackbart/connecta/blob/main/docs/decisions.md#non-goals)
+say so at more length.
+
+## Getting started
 
 Node deployments require Node.js 20.9 or newer.
 
@@ -28,277 +129,68 @@ Node deployments require Node.js 20.9 or newer.
 npm install @zackbart/connecta
 ```
 
-Provider and runtime integrations remain consumer-owned. Install only the
-optional packages a deployment uses—for example:
-
-```sh
-npm install @clerk/backend          # optional Clerk auth adapter
-npm install quickjs-emscripten      # optional Node code-mode executor
-npm install @cloudflare/codemode    # optional Worker code-mode executor
-```
-
-## The nine meta-tools
-
-A tool **address** is `<connectorId>.<toolName>` (e.g. `notion.search`).
-
-| Tool | Input | Returns |
-| --- | --- | --- |
-| `list_connectors` | `{ probe? }` | live (`probe: true`, default) or cached health, tool count, and recent real-call observations |
-| `skills` | `{ name? }` | lists or fetches the concise `usage` guide for choosing among the meta-tools, plus any operator-authored per-connector guide (`connector:<connectorId>`) |
-| `search_tools` | `{ query?, connector?, limit?, offset?, fullDescriptions?, includeSchemas? }` | ranked, paginated matches; optionally includes compact/raw schemas to remove a round trip |
-| `describe_tools` | `{ addresses[], format?, fullDescriptions? }` | names, descriptions, input/output schemas, and behavior annotations |
-| `call_tool` | `{ address, args?, fields?, resultMode?, timeoutMs?, maxRetries?, diagnostics? }` | invokes only tools explicitly annotated `readOnlyHint: true` |
-| `call_destructive_tool` | same as `call_tool` | invokes unannotated, write-capable, or destructive tools through a host-visible approval boundary |
-| `authorize_connector` | `{ connector, force? }` | starts (or with `force`, restarts) the downstream OAuth flow; returns the `authorizationUrl` to open |
-| `get_result` | `{ id, offset?, maxBytes? }` | a byte-slice page of a truncated result — `{ text, offset, nextOffset?, totalBytes }`; `maxBytes` is a whole number of bytes >= 1 |
-| `batch_call` | `{ calls, resultMode?, timeoutMs?, maxRetries? }` | 1–10 parallel calls sharing request-scoped clients, with attempts/timing/errors |
-| `execute_code` *(optional)* | `{ code }` | result + logs of bounded async JS orchestration over explicitly read-only tools; registered only when an `executor` is configured |
-
-## Package vs. deployments
-
-This repository owns the reusable package. Each deployment should be a small,
-separate Worker project that pins an exact package version and owns only its
-connector configuration, auth policy, domain, bindings, migrations, and secrets.
-[`examples/worker/`](./examples/worker/) is the starting template.
-
-## Quickstart — Cloudflare Worker
-
-```ts
-import { DynamicWorkerExecutor } from "@cloudflare/codemode";
-import { bearerToken, createConnecta, remoteMcp } from "@zackbart/connecta";
-import { clerkAuth } from "@zackbart/connecta/auth/clerk";
-import { cloudflareKvStorage } from "./cloudflare-kv.js";
-
-const build = (env: Env) =>
-  createConnecta({
-    publicUrl: env.PUBLIC_URL,
-    storage: cloudflareKvStorage(env.CONNECTA_KV),
-    // Code mode (optional): needs a `worker_loaders` binding in wrangler.jsonc.
-    executor: new DynamicWorkerExecutor({ loader: env.LOADER }),
-    auth: [
-      bearerToken(env.CONNECTA_TOKEN),
-      clerkAuth({
-        publishableKey: env.CLERK_PUBLISHABLE_KEY,
-        secretKey: env.CLERK_SECRET_KEY,
-        publicUrl: env.PUBLIC_URL,
-      }),
-    ],
-    connectors: [
-      remoteMcp("notion", {
-        url: "https://mcp.notion.com/mcp",
-        auth: { type: "headers", headers: { Authorization: `Bearer ${env.NOTION_TOKEN}` } },
-      }),
-    ],
-  });
-
-// Lazy per-isolate singleton: keeps only serializable tool/catalog data warm.
-let connecta: ReturnType<typeof build> | undefined;
-
-export default {
-  fetch(request: Request, env: Env): Promise<Response> {
-    connecta ??= build(env);
-    return connecta.fetch(request);
-  },
-};
-```
-
-Deployable example: [`examples/worker/`](./examples/worker/).
-Its Cloudflare KV and D1 implementations are deployment-owned examples over the
-generic `KVStorage` and `ActivityStore` contracts; they are not package exports.
-
-`clerkAuth` is an optional adapter. Install `@clerk/backend` and import it from
-`@zackbart/connecta/auth/clerk` only in deployments that use Clerk. Other
-identity providers can implement the exported `InboundAuth` interface.
-
-## Quickstart — Node
+A minimal server with one hand-written connector:
 
 ```ts
 import { api, bearerToken, createConnecta } from "@zackbart/connecta";
 import { fileStorage, listen } from "@zackbart/connecta/node";
-import { quickJsExecutor } from "@zackbart/connecta/quickjs";
 
 const connecta = createConnecta({
   storage: fileStorage("./.connecta-state.json"), // or memoryStorage()
-  auth: bearerToken(process.env.CONNECTA_TOKEN!),
-  executor: quickJsExecutor(), // code mode (optional): QuickJS/WASM sandbox
+  auth: bearerToken(process.env.CONNECTA_TOKEN ?? "dev-token"),
   connectors: [
     api("time", {
-      description: "Time — clock utilities",
-      tools: [{
-        name: "get_now",
-        description: "Return the current ISO timestamp.",
-        inputSchema: { type: "object", properties: {} },
-        annotations: { readOnlyHint: true },
-        handler: async () => ({ now: new Date().toISOString() }),
-      }],
+      description: "Time — current timestamp",
+      tools: [
+        {
+          name: "get_now",
+          description: "Return the current time as an ISO 8601 timestamp.",
+          inputSchema: { type: "object", properties: {} },
+          annotations: { readOnlyHint: true },
+          handler: async () => ({ now: new Date().toISOString() }),
+        },
+      ],
     }),
   ],
 });
 
-listen(connecta, 8787); // http://localhost:8787/mcp
-```
-
-Example: [`examples/node/`](./examples/node/). Docker (single-service compose
-stack): [`examples/docker/`](./examples/docker/).
-
-## Toolkits — one deployment, many teams
-
-A deployment belongs to an org. Optional **toolkits** give each group of team
-members its own scoped view of the same registry, so different teams no longer
-need separate deployments:
-
-```ts
-createConnecta({
-  connectors: [zendesk, notion, gmail],
-  auth: bearerToken(env.CONNECTA_TOKEN),
-  toolkits: {
-    support: { connectors: ["zendesk", "notion"] },
-    exec: {
-      connectors: ["zendesk", "notion", "gmail"],
-      excludeTools: ["gmail.send_message"], // finer grain than a connector id
-    },
-  },
-});
-```
-
-A client picks one at connect time: `https://…/mcp?toolkit=support`. Inside a
-scoped session **every** meta-tool — search, describe, call, batch, skills,
-authorize, `get_result`, and `execute_code` host calls — behaves as if
-out-of-scope connectors and tools do not exist, and an out-of-scope address
-fails identically to a nonexistent one. No `?toolkit=` ⇒ the full registry, as
-before; an unknown name is an error, never a silent fallback.
-
-A toolkit scopes **visibility, not identity**: any authenticated client may
-select any toolkit, or omit the parameter and see everything, so a credential
-shared by two teams gives both teams every view. Binding a member to a toolkit
-belongs in `auth`, which stays the access check; enforcing that binding is a
-deliberate follow-up
-([issue #37](https://github.com/zackbart/connecta/issues/37)). Details:
-[docs §16](./docs/documentation.md#16-toolkits-scoped-views).
-
-## Code mode
-
-With an `executor` configured, the model can write an async function instead of
-making one `call_tool` round trip per step — loops, joins across connectors,
-filtering big responses down in-sandbox before they hit the context window:
-
-```js
-async () => {
-  const pages = await notion.search({ query: "roadmap" });
-  return pages.results.map((p) => p.title);
-}
-```
-
-The sandbox has **no** network/filesystem/env — only explicitly read-only
-connector globals and
-`connecta.call`, `connecta.batch`, `connecta.search`, and `connecta.describe`;
-credentials stay host-side. A run may make at most 20 host calls, a
-`connecta.batch` may contain at most 10 calls, and every host call has a
-15-second deadline. Executors:
-`DynamicWorkerExecutor` (`@cloudflare/codemode`,
-Workers, Worker Loader binding — open beta) or `quickJsExecutor()`
-(`@zackbart/connecta/quickjs`, QuickJS-in-WASM, runs anywhere). Omit the `executor` and
-connecta is exactly the nine-tool server. Details:
-[docs §13](./docs/documentation.md#13-code-mode-execute_code).
-
-## Credentials in `/ui`
-
-API connectors can declare one operator-managed credential or a named set of
-credential fields. Connecta renders
-Add / Replace / Test / Remove controls inside that connector's `/ui` card,
-encrypts the values with AES-GCM, and stores only ciphertext in the deployment's
-existing `KVStorage`. Credentials are available only to the connector through
-`ctx.credential.get()`, `get(name)`, or `getAll()`; they are never returned by
-`/ui`, MCP tools, or code mode.
-
-```ts
-api("example", {
-  description: "Example — authenticated API",
-  credential: {
-    label: "API token",
-    description: "Token used for outbound Example API requests.",
-  },
-  tools: [{
-    name: "get_profile",
-    description: "Get the authenticated Example profile.",
-    inputSchema: { type: "object", properties: {} },
-    annotations: { readOnlyHint: true },
-    handler: async (_args, ctx) => {
-      const token = await ctx.credential?.get();
-      if (!token) throw new Error("Example API token is not configured.");
-      return fetch("https://api.example.com/profile", {
-        headers: { Authorization: `Bearer ${token}` },
-      }).then((response) => response.json());
-    },
-  }],
-})
-```
-
-Set `credentialEncryptionKey` on `createConnecta` to a base64-encoded 32-byte
-key held in the runtime's secret store (`openssl rand -base64 32`) — a connector
-that declares a credential without one fails at construction rather than booting
-with an unusable vault. Credential mutation routes require the configured Clerk
-provider and a same-origin browser request; the static inbound bearer cannot
-administer the vault.
-
-Connecta does not bundle service-specific HTTP API connectors. Package consumers
-define them with `api()` (or implement `Connector` directly), keeping endpoint,
-credential, and tool choices in the consuming project.
-
-## Payload-free tool activity
-
-Connecta can record which resolved downstream tools were actually invoked
-without storing their arguments, results, generated code, search text, or raw
-errors. Supply a vendor-neutral `activity` store:
-
-```ts
-const events: ToolCallActivityEvent[] = [];
-
-const connecta = createConnecta({
-  connectors,
-  activity: {
-    record(event) {
-      events.push(event);
-    },
-    async list({ limit }) {
-      return { events: events.slice(-limit).reverse() };
-    },
-  },
-});
+listen(connecta, 8787); // MCP at http://localhost:8787/mcp, status at /ui
 ```
 
-One final event is emitted for each resolved connector call made through
-`call_tool`, `call_destructive_tool`, `batch_call`, or `execute_code`; retries
-remain one event with an `attempts` count. Implementing `list` enables the
-authenticated Activity tab in `/ui`; `activityReadGate` can narrow reads
-further. Writes are best-effort and never change a tool result. Clerk calls
-carry the Clerk user ID; shared bearer calls are honestly labeled as bearer
-unless `bearerToken(secret, { subjectId })` assigns that credential a stable
-subject. On Workers, pass `ctx` through to `connecta.fetch(request, env, ctx)`
-so async writes settle on `waitUntil`.
-[`examples/worker/src/d1-activity.ts`](./examples/worker/src/d1-activity.ts) is
-a complete D1 implementation with keyset paging and a retention pass.
-
-## Operator dashboard
-
-`GET /ui` is a read-only dashboard with no build step: connector health, tool
-counts and descriptions with a client-side filter, downstream authorization
-links, the credential controls above, and an Activity tab when an activity store
-is configured. The shell is open because it carries no data; everything it shows
-comes from `/ui/data`, behind the same auth gate as `/mcp`. With Clerk
-configured it signs operators in through Clerk's hosted portal; a bearer-only
-deployment falls back to a pasted token.
-
-Every deployment-facing label and mark on `/ui` and the OAuth result pages comes
-from `ConnectaConfig.branding` — `productName`, `ownerName`, their URLs,
-`description`, `pageTitle`, `themeColor`, and `favicon` — each falling back to a
-neutral Connecta default. Nothing about the operator is baked into the package.
+Point an MCP client at `http://localhost:8787/mcp` with an
+`Authorization: Bearer` header and it will see the nine meta-tools, with
+`time.get_now` discoverable through `search_tools`.
+
+Runnable deployments live in
+[`examples/`](https://github.com/zackbart/connecta/tree/main/examples):
+[`worker/`](https://github.com/zackbart/connecta/tree/main/examples/worker) is a
+deployable Cloudflare Worker with KV and D1 adapters, and the template to copy
+for a real deployment;
+[`node/`](https://github.com/zackbart/connecta/tree/main/examples/node) adds
+toolkits and code mode to the server above;
+[`docker/`](https://github.com/zackbart/connecta/tree/main/examples/docker) is a
+single-service compose stack. Anything beyond the core is installed only by the
+deployments that use it: `@clerk/backend` and `quickjs-emscripten` are optional
+peer dependencies, reached through the `/auth/clerk` and `/quickjs` subpaths,
+and a Worker using code mode brings its own `@cloudflare/codemode`. Connecta
+ships no service-specific connectors:
+endpoint, credential, and tool choices stay in your project, declared with
+`remoteMcp()` and `api()`.
 
 ## Learn more
 
-- **[`docs/documentation.md`](./docs/documentation.md)** — how everything works: architecture,
-  the meta-tools, connectors and their usage guides, inbound auth, downstream
-  OAuth, storage, running it (Node / Workers / Docker), Clerk setup, testing,
-  troubleshooting, code mode, the status UI, activity history, and toolkits.
-- **[`docs/design.md`](./docs/design.md)** — why it's built this way, and the non-goals.
-- **[`CHANGELOG.md`](./CHANGELOG.md)** — what changed in each release.
+- **[Documentation](https://github.com/zackbart/connecta/blob/main/docs/documentation.md)**
+  — the reference manual: architecture, connectors, inbound auth and downstream
+  OAuth, storage, Clerk setup, testing, and troubleshooting. Start with the
+  [meta-tools reference](https://github.com/zackbart/connecta/blob/main/docs/documentation.md#3-meta-tools-reference),
+  the [config options](https://github.com/zackbart/connecta/blob/main/docs/documentation.md#8-running-it),
+  [code mode](https://github.com/zackbart/connecta/blob/main/docs/documentation.md#13-code-mode-execute_code),
+  [toolkits](https://github.com/zackbart/connecta/blob/main/docs/documentation.md#16-toolkits-scoped-views),
+  or [credential health](https://github.com/zackbart/connecta/blob/main/docs/documentation.md#17-credential-health-proactive-liveness-checks).
+- **[Decisions](https://github.com/zackbart/connecta/blob/main/docs/decisions.md)**
+  — what connecta refuses to be, which alternatives lost and why, and the
+  invariants a change must preserve.
+- **[CHANGELOG](https://github.com/zackbart/connecta/blob/main/CHANGELOG.md)** —
+  what changed in each release.
+- **[SECURITY](https://github.com/zackbart/connecta/blob/main/SECURITY.md)** —
+  supported versions and how to report a vulnerability.

package/dist/auth/bearer.d.ts

@@ -1,10 +1,17 @@
+import { type ToolkitBindingOptions } from "../toolkits.js";
 import type { InboundAuth } from "../types.js";
+export interface BearerTokenOptions extends ToolkitBindingOptions {
+    /** Stable identity for this credential, used on activity events. */
+    subjectId?: string;
+}
 /**
  * Static bearer-token inbound auth. Constant-time compares the Bearer token
  * against `secret`. Checked BEFORE the Clerk gate in the server; a mismatch
  * falls through so a co-configured Clerk provider can still admit the request.
+ *
+ * `toolkits` binds the token to named toolkits (§16): one `bearerToken(...)` per
+ * team credential, each naming the view that team may open. Omit it and the
+ * token stays unbound — every declared toolkit plus the full registry.
  */
-export declare function bearerToken(secret: string, options?: {
-    subjectId?: string;
-}): InboundAuth;
+export declare function bearerToken(secret: string, options?: BearerTokenOptions): InboundAuth;
 //# sourceMappingURL=bearer.d.ts.map

package/dist/auth/bearer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bearer.d.ts","sourceRoot":"","sources":["../../src/auth/bearer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAc,WAAW,EAAE,MAAM,aAAa,CAAC;AAiB3D;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GACnC,WAAW,CA4Bb"}
+{"version":3,"file":"bearer.d.ts","sourceRoot":"","sources":["../../src/auth/bearer.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,qBAAqB,EAC3B,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAc,WAAW,EAAE,MAAM,aAAa,CAAC;AAiB3D,MAAM,WAAW,kBAAmB,SAAQ,qBAAqB;IAC/D,oEAAoE;IACpE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,kBAAuB,GAC/B,WAAW,CAiDb"}

package/dist/auth/bearer.js

@@ -1,3 +1,4 @@
+import { resolveToolkitBinding, } from "../toolkits.js";
 const encoder = new TextEncoder();
 /** Constant-time byte comparison. Differing lengths still iterate to reduce leak. */
 function timingSafeEqual(a, b) {
@@ -17,11 +18,31 @@ function timingSafeEqual(a, b) {
  * Static bearer-token inbound auth. Constant-time compares the Bearer token
  * against `secret`. Checked BEFORE the Clerk gate in the server; a mismatch
  * falls through so a co-configured Clerk provider can still admit the request.
+ *
+ * `toolkits` binds the token to named toolkits (§16): one `bearerToken(...)` per
+ * team credential, each naming the view that team may open. Omit it and the
+ * token stays unbound — every declared toolkit plus the full registry.
  */
 export function bearerToken(secret, options = {}) {
     const secretBytes = encoder.encode(secret);
+    const toolkitBinding = resolveToolkitBinding(options.subjectId
+        ? `bearerToken (subjectId "${options.subjectId}")`
+        : "bearerToken", options);
+    if (toolkitBinding && !options.subjectId) {
+        // A bound token stands for one team, and both surfaces that report on it —
+        // the 403 refusal log (§16) and activity events (§15) — can only say
+        // "bearer" without a subjectId. With several bound tokens that makes an
+        // operator unable to tell which credential was refused, or whose call
+        // succeeded. console.warn (as the Clerk adapter does) because an adapter is
+        // constructed before `createConnecta` has a logger to hand it.
+        console.warn("[connecta] bearerToken is bound to toolkits " +
+            `(${toolkitBinding.toolkits.join(", ") || "unscoped only"}) but has no ` +
+            "subjectId: refusal logs and activity events cannot say which " +
+            "credential they came from. Pass { subjectId: \"<team>\" }.");
+    }
     return {
         kind: "bearer",
+        ...(toolkitBinding ? { toolkitBinding } : {}),
         authorize(request) {
             const header = request.headers.get("authorization") ?? "";
             const match = /^Bearer\s+(.+)$/i.exec(header);

package/dist/auth/bearer.js.map

@@ -1 +1 @@
-{"version":3,"file":"bearer.js","sourceRoot":"","sources":["../../src/auth/bearer.ts"],"names":[],"mappings":"AAEA,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;AAElC,qFAAqF;AACrF,SAAS,eAAe,CAAC,CAAa,EAAE,CAAa;IACnD,IAAI,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC;QAC1B,IAAI,CAAC,GAAG,CAAC,CAAC;QACV,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC;QACvC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE;YAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;QAC3D,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACpD,OAAO,CAAC,KAAK,CAAC,CAAC;AACjB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CACzB,MAAc,EACd,UAAkC,EAAE;IAEpC,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC3C,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,SAAS,CAAC,OAAO;YACf,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,IAAI,EAAE,CAAC;YAC1D,MAAM,KAAK,GAAG,kBAAkB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAC9C,IAAI,KAAK,IAAI,eAAe,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,WAAW,CAAC,EAAE,CAAC;gBACpE,OAAO;oBACL,EAAE,EAAE,IAAI;oBACR,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBAC/D,CAAC;YACJ,CAAC;YACD,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,QAAQ,EAAE,IAAI,QAAQ,CACpB,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC,EACzC;oBACE,MAAM,EAAE,GAAG;oBACX,OAAO,EAAE;wBACP,cAAc,EAAE,kBAAkB;wBAClC,kBAAkB,EAAE,QAAQ;qBAC7B;iBACF,CACF;aACF,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"bearer.js","sourceRoot":"","sources":["../../src/auth/bearer.ts"],"names":[],"mappings":"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"}

package/dist/auth/clerk.d.ts

@@ -1,20 +1,45 @@
 import { createClerkClient } from "@clerk/backend";
+import { type ToolkitBindingOptions } from "../toolkits.js";
 import type { InboundAuth } from "../types.js";
 type ClerkClient = ReturnType<typeof createClerkClient>;
-export interface ClerkAuthOptions {
+export interface ClerkAuthOptions extends ToolkitBindingOptions {
     publishableKey: string;
     secretKey: string;
     /** Public base URL of this deployment. Defaults to the request origin. */
     publicUrl?: string;
+    /**
+     * Email domains this deployment admits, e.g. `["acme.com"]`. An
+     * authenticated user whose verified primary email is not on one of them is
+     * rejected exactly like a `gate` rejection. Matching is exact on the whole
+     * domain and case-insensitive: `acme.com` admits neither `evil-acme.com` nor
+     * `mail.acme.com` — spell a subdomain out to allow it. Entries must be ASCII
+     * (punycode for an internationalized domain) and are validated at
+     * construction. Absent ⇒ every authenticated user passes this check, as
+     * before the option existed. Governs Clerk sign-in only: a co-configured
+     * `bearerToken` has no email to read and is admitted without a domain check.
+     */
+    allowedDomains?: readonly string[];
     /** Optional allow-list hook. Return false to reject an authenticated user. */
     gate?: (userId: string, clerk: ClerkClient) => boolean | Promise<boolean>;
     /** Advertised scopes in protected-resource metadata. */
     scopes?: string[];
-    /** Optional hosted Account Portal sign-in URL for `/ui`. */
+    /** Optional hosted Account Portal sign-in URL for `/ui`. Absolute https only. */
     signInUrl?: string;
-    /** Optional hosted Account Portal sign-up URL for `/ui`. */
+    /** Optional hosted Account Portal sign-up URL for `/ui`. Absolute https only. */
     signUpUrl?: string;
 }
+/**
+ * Clerk inbound auth.
+ *
+ * `allowedDomains` and `gate` decide WHO is admitted (both must pass);
+ * `toolkits` decides WHICH view the admitted user gets.
+ *
+ * `toolkits` binds every user this provider admits to those toolkits (§16). For
+ * a per-team split, configure one `clerkAuth(...)` per team — the same keys, a
+ * `gate` naming that team's users, and that team's `toolkits`. The server tries
+ * providers in order and the first that admits the user supplies the binding, so
+ * a user one gate rejects falls through to the next.
+ */
 export declare function clerkAuth(opts: ClerkAuthOptions): InboundAuth;
 export {};
 //# sourceMappingURL=clerk.d.ts.map

package/dist/auth/clerk.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"clerk.d.ts","sourceRoot":"","sources":["../../src/auth/clerk.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,KAAK,EAAc,WAAW,EAAE,MAAM,aAAa,CAAC;AAE3D,KAAK,WAAW,GAAG,UAAU,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAExD,MAAM,WAAW,gBAAgB;IAC/B,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1E,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA6BD,wBAAgB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,WAAW,CA8K7D"}
+{"version":3,"file":"clerk.d.ts","sourceRoot":"","sources":["../../src/auth/clerk.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAEL,KAAK,qBAAqB,EAC3B,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAc,WAAW,EAAE,MAAM,aAAa,CAAC;AAE3D,KAAK,WAAW,GAAG,UAAU,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAExD,MAAM,WAAW,gBAAiB,SAAQ,qBAAqB;IAC7D,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;;;;;OAUG;IACH,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,8EAA8E;IAC9E,IAAI,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1E,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iFAAiF;IACjF,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA0ID;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,WAAW,CA0O7D"}