@zackbart/connecta 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to this package are documented here.
+
+## 0.1.0 — 2026-07-23
+
+- Initial public package release.
+- Generic API and remote MCP connector contracts.
+- Nine fixed meta-tools with progressive tool discovery and approval boundaries.
+- Optional sandboxed code mode for dependent read-only orchestration.
+- Generic storage, activity, authentication, and credential-management seams.
+- Node and Web-standard fetch runtimes.
+- Optional Clerk authentication adapter.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zackery Bartolome
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,249 @@
+# connecta
+
+![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.
+
+```
+                                        ┌── remoteMcp("notion")   → mcp.notion.com
+Claude / Cursor ── MCP ──▶  connecta ───┼── remoteMcp("linear")   → mcp.linear.app
+   sees 9 tools            /mcp         ├── api("resend")         → fetch(...)
+                                        └── 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
+
+Node deployments require Node.js 20.9 or newer.
+
+```sh
+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 |
+| `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 }` |
+| `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 {
+  api, 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
+
+```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
+  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() }),
+      }],
+    }),
+  ],
+});
+
+listen(connecta, 8787); // http://localhost:8787/mcp
+```
+
+Example: [`examples/node/`](./examples/node/). Docker (single-service compose
+stack): [`examples/docker/`](./examples/docker/).
+
+## 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`). 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() };
+    },
+  },
+});
+```
+
+One final event is emitted for each resolved connector call made through
+`call_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.
+
+## Learn more
+
+- **[`docs/documentation.md`](./docs/documentation.md)** — how everything works: architecture,
+  the meta-tools, connectors, inbound auth, downstream OAuth, storage, running it
+  (Node / Workers / Docker), Clerk setup, testing, troubleshooting.
+- **[`docs/design.md`](./docs/design.md)** — why it's built this way, and the non-goals.
+- **Status UI** — a read-only operator dashboard at `GET /ui` (open shell; data from the bearer/Clerk-gated `/ui/data`). See [§14](./docs/documentation.md#14-status-ui).

package/SECURITY.md

@@ -0,0 +1,25 @@
+# Security
+
+## Supported versions
+
+Security fixes are applied to the latest published minor release.
+
+## Reporting a vulnerability
+
+Please report suspected vulnerabilities through GitHub's private security
+advisory flow for this repository. Do not include secrets, credentials, or
+sensitive payloads in a public issue.
+
+## Dependency policy
+
+CI blocks high and critical production dependency advisories. Moderate findings
+are reviewed for reachability and recorded when an upstream package has not yet
+released a compatible fix.
+
+The initial release has one such upstream finding:
+`@modelcontextprotocol/sdk@1.29.0` declares `@hono/node-server` 1.x, which is
+covered by `GHSA-frvp-7c67-39w9`. The advisory affects Hono's Windows
+`serve-static` implementation. Connecta does not import that adapter or serve
+static files through Hono. npm's suggested fix downgrades the MCP SDK below
+security behavior Connecta relies on, so the package retains SDK 1.29.0 while
+tracking an upstream compatible release.

package/dist/activity.d.ts

@@ -0,0 +1,82 @@
+import type { Logger } from "./types.js";
+export type ActivityCallSource = "call_tool" | "call_destructive_tool" | "batch_call" | "execute_code";
+export type ActivityOutcome = "success" | "error" | "timeout";
+/**
+ * Authenticated identity attached to an activity event. `id` is intentionally
+ * optional: open deployments and shared bearer tokens cannot honestly identify
+ * a person.
+ */
+export interface ActivityActor {
+    kind: string;
+    id?: string;
+}
+/**
+ * Privacy-minimal history of one resolved downstream connector call.
+ *
+ * Arguments, results, generated code, search text, and raw errors are excluded
+ * by construction. Deployments that need a safe human summary can add a
+ * separate, explicit connector-level feature later.
+ */
+export interface ToolCallActivityEvent {
+    schemaVersion: 1;
+    id: string;
+    occurredAt: string;
+    requestId: string;
+    actor: ActivityActor;
+    connectorId: string;
+    toolName: string;
+    address: string;
+    source: ActivityCallSource;
+    outcome: ActivityOutcome;
+    durationMs: number;
+    attempts: number;
+    errorCode?: string;
+    serverName: string;
+    serverVersion: string;
+    deploymentId?: string;
+}
+export interface ActivityPage {
+    events: ToolCallActivityEvent[];
+    nextCursor?: string;
+}
+/** Write-only deployments can implement only this small, vendor-neutral seam. */
+export interface ActivitySink {
+    record(event: ToolCallActivityEvent): void | Promise<void>;
+}
+/** Optional read side used by Connecta's authenticated Activity UI. */
+export interface ActivityReader {
+    list(options: {
+        cursor?: string;
+        limit: number;
+    }): Promise<ActivityPage>;
+}
+export interface ActivityStore extends ActivitySink {
+    list?: ActivityReader["list"];
+}
+/** Reader implementations throw this for an opaque cursor they cannot decode. */
+export declare class InvalidActivityCursorError extends Error {
+    name: string;
+    constructor();
+}
+export type ActivityReadGate = (actor: ActivityActor) => boolean | Promise<boolean>;
+/** Request-scoped context shared by direct, batch, and code-mode call paths. */
+export interface ActivityRequestContext {
+    sink: ActivitySink;
+    actor: ActivityActor;
+    requestId: string;
+    serverInfo: {
+        name: string;
+        version: string;
+    };
+    deploymentId?: string;
+    defer?: (promise: Promise<unknown>) => void;
+    logger: Logger;
+}
+export type ActivityEventInput = Pick<ToolCallActivityEvent, "connectorId" | "toolName" | "address" | "source" | "outcome" | "durationMs" | "attempts" | "errorCode">;
+/**
+ * Best-effort by design: activity storage can never change a tool result.
+ * Workers attach async sinks to waitUntil; synchronous sinks such as Analytics
+ * Engine complete inline; Node promises remain detached from the response.
+ */
+export declare function recordToolActivity(context: ActivityRequestContext | undefined, input: ActivityEventInput): void;
+//# sourceMappingURL=activity.d.ts.map

package/dist/activity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity.d.ts","sourceRoot":"","sources":["../src/activity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEzC,MAAM,MAAM,kBAAkB,GAC1B,WAAW,GACX,uBAAuB,GACvB,YAAY,GACZ,cAAc,CAAC;AAEnB,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;AAE9D;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,CAAC,EAAE,MAAM,CAAC;CACb;AAED;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC,aAAa,EAAE,CAAC,CAAC;IACjB,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,aAAa,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,kBAAkB,CAAC;IAC3B,OAAO,EAAE,eAAe,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,qBAAqB,EAAE,CAAC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,iFAAiF;AACjF,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,KAAK,EAAE,qBAAqB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5D;AAED,uEAAuE;AACvE,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,OAAO,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CAC1E;AAED,MAAM,WAAW,aAAc,SAAQ,YAAY;IACjD,IAAI,CAAC,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;CAC/B;AAED,iFAAiF;AACjF,qBAAa,0BAA2B,SAAQ,KAAK;IAC1C,IAAI,SAAgC;;CAK9C;AAED,MAAM,MAAM,gBAAgB,GAAG,CAC7B,KAAK,EAAE,aAAa,KACjB,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAEhC,gFAAgF;AAChF,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,YAAY,CAAC;IACnB,KAAK,EAAE,aAAa,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC;IAC5C,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,kBAAkB,GAAG,IAAI,CACnC,qBAAqB,EACnB,aAAa,GACb,UAAU,GACV,SAAS,GACT,QAAQ,GACR,SAAS,GACT,YAAY,GACZ,UAAU,GACV,WAAW,CACd,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,sBAAsB,GAAG,SAAS,EAC3C,KAAK,EAAE,kBAAkB,GACxB,IAAI,CAkCN"}

package/dist/activity.js

@@ -0,0 +1,51 @@
+/** Reader implementations throw this for an opaque cursor they cannot decode. */
+export class InvalidActivityCursorError extends Error {
+    name = "InvalidActivityCursorError";
+    constructor() {
+        super("invalid activity cursor");
+    }
+}
+/**
+ * Best-effort by design: activity storage can never change a tool result.
+ * Workers attach async sinks to waitUntil; synchronous sinks such as Analytics
+ * Engine complete inline; Node promises remain detached from the response.
+ */
+export function recordToolActivity(context, input) {
+    if (!context)
+        return;
+    const event = {
+        schemaVersion: 1,
+        id: crypto.randomUUID(),
+        occurredAt: new Date().toISOString(),
+        requestId: context.requestId,
+        actor: context.actor,
+        connectorId: input.connectorId,
+        toolName: input.toolName,
+        address: input.address,
+        source: input.source,
+        outcome: input.outcome,
+        durationMs: Math.max(0, Math.trunc(input.durationMs)),
+        attempts: Math.max(1, Math.trunc(input.attempts)),
+        ...(input.errorCode ? { errorCode: input.errorCode } : {}),
+        serverName: context.serverInfo.name,
+        serverVersion: context.serverInfo.version,
+        ...(context.deploymentId
+            ? { deploymentId: context.deploymentId }
+            : {}),
+    };
+    try {
+        const result = context.sink.record(event);
+        if (!result || typeof result.then !== "function") {
+            return;
+        }
+        const pending = Promise.resolve(result).catch((error) => {
+            context.logger.warn("[connecta] activity record failed", error);
+        });
+        if (context.defer)
+            context.defer(pending);
+    }
+    catch (error) {
+        context.logger.warn("[connecta] activity record failed", error);
+    }
+}
+//# sourceMappingURL=activity.js.map

package/dist/activity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity.js","sourceRoot":"","sources":["../src/activity.ts"],"names":[],"mappings":"AAiEA,iFAAiF;AACjF,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IAC1C,IAAI,GAAG,4BAA4B,CAAC;IAE7C;QACE,KAAK,CAAC,yBAAyB,CAAC,CAAC;IACnC,CAAC;CACF;AA6BD;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAA2C,EAC3C,KAAyB;IAEzB,IAAI,CAAC,OAAO;QAAE,OAAO;IACrB,MAAM,KAAK,GAA0B;QACnC,aAAa,EAAE,CAAC;QAChB,EAAE,EAAE,MAAM,CAAC,UAAU,EAAE;QACvB,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACpC,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,QAAQ,EAAE,KAAK,CAAC,QAAQ;QACxB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,MAAM,EAAE,KAAK,CAAC,MAAM;QACpB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,UAAU,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;QACrD,QAAQ,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QACjD,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC1D,UAAU,EAAE,OAAO,CAAC,UAAU,CAAC,IAAI;QACnC,aAAa,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO;QACzC,GAAG,CAAC,OAAO,CAAC,YAAY;YACtB,CAAC,CAAC,EAAE,YAAY,EAAE,OAAO,CAAC,YAAY,EAAE;YACxC,CAAC,CAAC,EAAE,CAAC;KACR,CAAC;IACF,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC1C,IAAI,CAAC,MAAM,IAAI,OAAQ,MAA2B,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;YACvE,OAAO;QACT,CAAC;QACD,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;YACtD,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,mCAAmC,EAAE,KAAK,CAAC,CAAC;QAClE,CAAC,CAAC,CAAC;QACH,IAAI,OAAO,CAAC,KAAK;YAAE,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC5C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,mCAAmC,EAAE,KAAK,CAAC,CAAC;IAClE,CAAC;AACH,CAAC"}

package/dist/auth/bearer.d.ts

@@ -0,0 +1,10 @@
+import type { InboundAuth } from "../types.js";
+/**
+ * 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.
+ */
+export declare function bearerToken(secret: string, options?: {
+    subjectId?: string;
+}): InboundAuth;
+//# sourceMappingURL=bearer.d.ts.map

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

@@ -0,0 +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"}

package/dist/auth/bearer.js

@@ -0,0 +1,47 @@
+const encoder = new TextEncoder();
+/** Constant-time byte comparison. Differing lengths still iterate to reduce leak. */
+function timingSafeEqual(a, b) {
+    if (a.length !== b.length) {
+        let r = 1;
+        const n = Math.max(a.length, b.length);
+        for (let i = 0; i < n; i++)
+            r |= (a[i] ?? 0) ^ (b[i] ?? 0);
+        return false;
+    }
+    let r = 0;
+    for (let i = 0; i < a.length; i++)
+        r |= a[i] ^ b[i];
+    return r === 0;
+}
+/**
+ * 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.
+ */
+export function bearerToken(secret, options = {}) {
+    const secretBytes = encoder.encode(secret);
+    return {
+        kind: "bearer",
+        authorize(request) {
+            const header = request.headers.get("authorization") ?? "";
+            const match = /^Bearer\s+(.+)$/i.exec(header);
+            if (match && timingSafeEqual(encoder.encode(match[1]), secretBytes)) {
+                return {
+                    ok: true,
+                    ...(options.subjectId ? { subjectId: options.subjectId } : {}),
+                };
+            }
+            return {
+                ok: false,
+                response: new Response(JSON.stringify({ error: "unauthorized" }), {
+                    status: 401,
+                    headers: {
+                        "Content-Type": "application/json",
+                        "WWW-Authenticate": "Bearer",
+                    },
+                }),
+            };
+        },
+    };
+}
+//# sourceMappingURL=bearer.js.map

package/dist/auth/bearer.js.map

@@ -0,0 +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"}

package/dist/auth/clerk.d.ts

@@ -0,0 +1,20 @@
+import { createClerkClient } from "@clerk/backend";
+import type { InboundAuth } from "../types.js";
+type ClerkClient = ReturnType<typeof createClerkClient>;
+export interface ClerkAuthOptions {
+    publishableKey: string;
+    secretKey: string;
+    /** Public base URL of this deployment. Defaults to the request origin. */
+    publicUrl?: 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`. */
+    signInUrl?: string;
+    /** Optional hosted Account Portal sign-up URL for `/ui`. */
+    signUpUrl?: string;
+}
+export declare function clerkAuth(opts: ClerkAuthOptions): InboundAuth;
+export {};
+//# sourceMappingURL=clerk.d.ts.map

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

@@ -0,0 +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"}