@vllnt/convex-helpers 0.1.0 → 0.1.1-canary.ba6c009

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Fixed
+
+- Fail closed on thrown or stalled MCP authorization hooks; bound auth/lifecycle
+  callbacks to 10 seconds and remove raw exception logging.
+- Add optional host-configured `AuthCtx.trustedIssuer` enforcement before identity
+  row callbacks, preserving the legacy single-issuer contract when omitted.
+- Reject unsafe preview patterns, localhost paths/normalization and control characters;
+  validate cookie origins instead of trusting a prefix.
+- Bound retargeting to 1000 rows with sequential callbacks and failure short-circuiting.
+- Remove release-note shell interpolation; gate stable dispatch to main and explicit
+  `RELEASE_ENABLED=true`, and remove workflow-wide write/OIDC privileges.
+- Patch development Handlebars and Vite/esbuild advisory paths; document the remaining
+  deepmerge-ts tooling advisory in `docs/READINESS.md`.
+
+- Convert MCP `int64` and `bytes` inputs to native Convex values and serialize native Convex
+  results with lossless tagged JSON.
+- Enforce resource argument validators before dispatch and reject unsafe mutation/action
+  timeouts that could report failure while non-cancellable side effects continue.
+
+### Changed
+
+- Document actual shipped APIs and host-owned identity/merge/CSRF boundaries; identity
+  integration fixtures now receive strict lint checks (legacy MCP fixtures remain excluded).
+
+- Refresh all direct dependencies to their latest compatible releases for canary validation.
+- Require `convex@^1.45.0` and update `convex-test` to `^0.0.56`.
+
+### Added
+
+- `./better-auth` — fail-closed trusted-origin parser + HTTPS cookie settings for `@convex-dev/better-auth` (does not import better-auth).
+- `./identity` — `getOrCreateFromAuth` / `requireFromAuth` / `retargetRows` host-`ctx` glue for anonymous sessions and anonymous→identified upgrades.
+- `./mcp` entry — expose Convex functions as MCP tools (`createMCPServer` + `query`/`mutation`/`action`/`resource`), default-deny auth, lifecycle hooks, validator→zod conversion, and optional HMAC-signed cursor pagination. Absorbed from `@vllnt/convex-mcp` (see ROADMAP `absorb-convex-mcp`). `@modelcontextprotocol/sdk` and `zod` are optional peer deps — the `./mcp` entry is tree-shakeable, so backend-only consumers pull neither. 100% test coverage retained (161 tests).
+
+## [0.1.0] - 2026-06-13
+
+### Added
+
+- Scaffolded to fleet Universal standard (type-B helpers library)
+- Seed root utilities: `asyncMap`, `pruneNull`, `nullThrows`, `NullDocumentError`
+- 100% test coverage gate via vitest thresholds
+- CI workflow, publish workflow, email-guard workflow
+- Full docs set: README, CHANGELOG, CONTRIBUTING, SECURITY, CODE_OF_CONDUCT
+- `llms.txt` and `llms-full.txt` for AI agent discovery

package/README.md

@@ -5,8 +5,8 @@
 
 # @vllnt/convex-helpers
 
-Typed host-side helpers for Convex backends — builders, errors, validators, relationships,
-pagination, HTTP, env, and observability.
+Typed Convex host-side utilities, trusted-origin and cookie configuration helpers,
+identity-row glue, and optional MCP tools.
 
 ```ts
 import { asyncMap, pruneNull, nullThrows } from "@vllnt/convex-helpers";
@@ -26,10 +26,11 @@ See [ROADMAP.md](./ROADMAP.md) for the planned module surface.
 - `asyncMap` — parallel async map that preserves order
 - `pruneNull` — filter null/undefined from arrays
 - `nullThrows` — non-null assertion with typed `NullDocumentError`
+- `./better-auth` — fail-closed trusted origins + HTTPS cookies for better-auth
+- `./identity` — identity-row lookup/bootstrap and bounded row-callback counting
 - `./mcp` — expose Convex functions as MCP tools (`createMCPServer` + `query`/`mutation`/`action`/`resource`), default-deny auth, optional cursor pagination
 - [planned] `./builders` — `customQuery`/`customMutation`/`customAction`/`customCtx`
 - [planned] `./errors` — typed `AppError` + HTTP-status map
-- [planned] `./auth` — provider-agnostic `requireIdentity`/`getCurrentSubject`
 - [planned] `./env` — `defineEnv(zodSchema)` cold-start validation
 - [planned] `./tracing` — span emit + `traceparent` propagation via `@vllnt/logger`
 - [planned] `./testing` — fixture factories + `withIdentity`
@@ -89,6 +90,78 @@ export const mcp = createMCPServer({
 export const { GET, POST } = mcp.handler();
 ```
 
+MCP auth and lifecycle callbacks have a 10-second deadline per callback. A thrown
+or timed-out `before` hook denies dispatch with a generic message. Auth failures
+also deny access generically. Success/error hooks cannot undo completed dispatch.
+Timeouts stop waiting, not the host callback; callbacks must avoid side effects.
+Raw errors are not logged by the library; hosts may observe hook context and must
+redact errors, arguments and credentials before logging. Resource failures are
+masked without raw logging.
+
+### Better-auth origins — `./better-auth`
+
+Fail-closed trusted-origin parsing and HTTPS cookie attributes. Does **not** import
+`better-auth` — the host still calls `betterAuth({...})`.
+
+```ts
+import {
+  cookieSettingsForSite,
+  trustedOriginsFromCsv,
+} from "@vllnt/convex-helpers/better-auth";
+
+const trustedOrigins = trustedOriginsFromCsv(
+  process.env.CONVEX_SITE_URL ?? "http://localhost:3211",
+  process.env.BETTER_AUTH_TRUSTED_ORIGINS ?? "",
+);
+```
+
+`parseTrustedOrigin` rejects credentials, paths, query/hash, controls and arbitrary
+wildcards. HTTP is allowed only for exact localhost/127.0.0.1 origins. An explicit
+`previewPattern` permits only HTTPS patterns shaped like
+`https://app-*-org.example.com` (one wildcard inside a prefixed/suffixed first label).
+The host must trust **every** deployment matched by its auth provider's wildcard
+semantics; syntax validation does not establish deployment ownership.
+Invalid extras are discarded; if none survive, the list helpers return `undefined`,
+so the host omits `trustedOrigins` and retains Better Auth defaults. They do not
+validate the host's entire auth configuration. `cookieSettingsForSite(siteUrl)`
+returns secure, HttpOnly, SameSite=None attributes for a valid HTTPS origin only;
+it does not replace CSRF/origin protection and is for hosts requiring cross-site cookies.
+
+### Identity — `./identity`
+
+Map `ctx.auth.getUserIdentity()` to a host row. The host must configure a trusted
+single issuer (subjects are issuer-local). To enforce it locally, pass
+`{ auth: ctx.auth, trustedIssuer: "https://your-trusted-issuer.example" }` as the
+helper context. A mismatched or missing issuer rejects before lookup/insert. The
+issuer must be host configuration, never a request argument. Omitting it preserves
+compatibility and relies on the host's single-issuer auth configuration.
+Provide callbacks bound to the same
+Convex mutation transaction, including the indexed lookup, for race-safe bootstrap.
+Every competing creator must use the same lookup. Actions or remote callbacks are
+not race-safe. `isAnonymous` reflects only a literal `true` JWT claim; missing/false
+claims do not prove a verified or identified account.
+
+`retargetRows(rows, apply)` processes at most 1000 rows sequentially, counts
+`patched`/`deleted`/`skipped`, and propagates failures without starting later rows.
+The host supplies bounded pages, authorization for both identities, conflict rules,
+continuation, transaction/rollback and logging. It is **not** a secure account merge.
+These helpers neither construct `betterAuth` nor install its anonymous plugin.
+
+```ts
+import { getOrCreateFromAuth, retargetRows } from "@vllnt/convex-helpers/identity";
+
+const user = await getOrCreateFromAuth(ctx, {
+  lookup: (subject) =>
+    ctx.db.query("users").withIndex("by_betterauth_id", (q) =>
+      q.eq("betterAuthId", subject),
+    ).unique(),
+  insert: async (subject) => {
+    const id = await ctx.db.insert("users", { betterAuthId: subject });
+    return (await ctx.db.get(id))!;
+  },
+});
+```
+
 Migrating from `@vllnt/convex-mcp`? Change the import to `@vllnt/convex-helpers/mcp` — the API is
 identical. See [docs/API.md](./docs/API.md#mcp-tools-mcp) for the full `./mcp` reference.
 
@@ -104,7 +177,11 @@ pnpm test:coverage   # must reach 100%
 ```
 
 Tests use [vitest](https://vitest.dev) with the node environment. 100% coverage is enforced via
-`vitest.config.mts` thresholds.
+`vitest.config.mts` thresholds. Identity integration tests use **convex-test mocks**;
+they do not prove real Better Auth sessions or anonymous plugin integration.
+The separate `scripts/local-identity-proof.mjs` passed 16 concurrent real local-backend
+bootstrap mutations with an injected synthetic identity (one row); this tests indexed
+OCC, not login. Consuming apps must verify their actual auth integration independently.
 
 ## Contributing
 

package/dist/better-auth.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Fail-closed origin and cookie helpers for `@convex-dev/better-auth`.
+ * Does not import better-auth — the host still constructs `betterAuth(...)`.
+ */
+export type CookieSettings = {
+    advanced: {
+        defaultCookieAttributes: {
+            httpOnly: true;
+            sameSite: "none";
+            secure: true;
+        };
+        useSecureCookies: true;
+    };
+};
+/**
+ * Parse one origin. HTTPS, no credentials/path/query/hash, no wildcards
+ * except an exact `previewPattern` (e.g. `https://app-*-org.vercel.app`).
+ */
+export declare function parseTrustedOrigin(origin: string, options?: {
+    previewPattern?: string;
+}): string | undefined;
+/**
+ * Merge `siteUrl` with extra origins. Returns `undefined` when nothing extra
+ * survived parsing — the host then omits `trustedOrigins`.
+ * `siteUrl` uses the same rules (localhost HTTP allowed).
+ */
+export declare function trustedOriginsFromList(siteUrl: string, extra: readonly string[], options?: {
+    previewPattern?: string;
+}): string[] | undefined;
+export declare function trustedOriginsFromCsv(siteUrl: string, csv: string, options?: {
+    previewPattern?: string;
+}): string[] | undefined;
+/** Secure cross-site cookies when `siteUrl` is HTTPS; otherwise `undefined`. */
+export declare function cookieSettingsForSite(siteUrl: string): CookieSettings | undefined;
+//# sourceMappingURL=better-auth.d.ts.map

package/dist/better-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"better-auth.d.ts","sourceRoot":"","sources":["../src/better-auth.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,EAAE;QACR,uBAAuB,EAAE;YACvB,QAAQ,EAAE,IAAI,CAAC;YACf,QAAQ,EAAE,MAAM,CAAC;YACjB,MAAM,EAAE,IAAI,CAAC;SACd,CAAC;QACF,gBAAgB,EAAE,IAAI,CAAC;KACxB,CAAC;CACH,CAAC;AAwDF;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;IAAE,cAAc,CAAC,EAAE,MAAM,CAAA;CAAO,GACxC,MAAM,GAAG,SAAS,CAwBpB;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,OAAO,GAAE;IAAE,cAAc,CAAC,EAAE,MAAM,CAAA;CAAO,GACxC,MAAM,EAAE,GAAG,SAAS,CAUtB;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,MAAM,EACX,OAAO,GAAE;IAAE,cAAc,CAAC,EAAE,MAAM,CAAA;CAAO,GACxC,MAAM,EAAE,GAAG,SAAS,CAEtB;AAED,gFAAgF;AAChF,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,GACd,cAAc,GAAG,SAAS,CAiB5B"}

package/dist/better-auth.js

@@ -0,0 +1,113 @@
+/**
+ * Fail-closed origin and cookie helpers for `@convex-dev/better-auth`.
+ * Does not import better-auth — the host still constructs `betterAuth(...)`.
+ */
+function hasControlCharacter(value) {
+    // Control-character detection is the point of this helper.
+    // eslint-disable-next-line no-control-regex -- C0 + DEL
+    return /[\u0000-\u001F\u007F]/u.test(value);
+}
+function isLocalHttp(origin) {
+    return (origin.startsWith("http://localhost") ||
+        origin.startsWith("http://127.0.0.1"));
+}
+function httpsOrigin(trimmed) {
+    try {
+        const url = new URL(trimmed);
+        if (url.protocol !== "https:" ||
+            url.username !== "" ||
+            url.password !== "" ||
+            url.pathname !== "/" ||
+            url.search !== "" ||
+            url.hash !== "" ||
+            (trimmed !== url.origin && trimmed !== `${url.origin}/`)) {
+            return undefined;
+        }
+        return url.origin;
+    }
+    catch {
+        return undefined;
+    }
+}
+function localHttpOrigin(trimmed) {
+    try {
+        const url = new URL(trimmed);
+        if (url.protocol !== "http:" ||
+            url.username !== "" ||
+            url.password !== "" ||
+            (url.hostname !== "localhost" && url.hostname !== "127.0.0.1") ||
+            url.pathname !== "/" ||
+            url.search !== "" ||
+            url.hash !== "" ||
+            (trimmed !== url.origin && trimmed !== `${url.origin}/`)) {
+            return undefined;
+        }
+        return url.origin;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Parse one origin. HTTPS, no credentials/path/query/hash, no wildcards
+ * except an exact `previewPattern` (e.g. `https://app-*-org.vercel.app`).
+ */
+export function parseTrustedOrigin(origin, options = {}) {
+    const trimmed = origin.trim();
+    if (trimmed === "")
+        return undefined;
+    if (hasControlCharacter(origin))
+        return undefined;
+    if (options.previewPattern !== undefined &&
+        trimmed === options.previewPattern &&
+        /^https:\/\/[a-z0-9]+(?:-[a-z0-9]+)*-\*-[a-z0-9]+(?:-[a-z0-9]+)*(?:\.[a-z0-9]+(?:-[a-z0-9]+)*){2,}$/u.test(trimmed)) {
+        return trimmed;
+    }
+    if (isLocalHttp(trimmed)) {
+        return localHttpOrigin(trimmed);
+    }
+    if (!trimmed.startsWith("https://") ||
+        trimmed.includes("*") ||
+        trimmed.includes("?")) {
+        return undefined;
+    }
+    return httpsOrigin(trimmed);
+}
+/**
+ * Merge `siteUrl` with extra origins. Returns `undefined` when nothing extra
+ * survived parsing — the host then omits `trustedOrigins`.
+ * `siteUrl` uses the same rules (localhost HTTP allowed).
+ */
+export function trustedOriginsFromList(siteUrl, extra, options = {}) {
+    const parsed = extra
+        .map((origin) => parseTrustedOrigin(origin, options))
+        .filter((origin) => origin !== undefined);
+    if (parsed.length === 0)
+        return undefined;
+    const site = parseTrustedOrigin(siteUrl, options);
+    if (site === undefined) {
+        return parsed;
+    }
+    return [site, ...parsed];
+}
+export function trustedOriginsFromCsv(siteUrl, csv, options = {}) {
+    return trustedOriginsFromList(siteUrl, csv.split(","), options);
+}
+/** Secure cross-site cookies when `siteUrl` is HTTPS; otherwise `undefined`. */
+export function cookieSettingsForSite(siteUrl) {
+    if (!siteUrl.startsWith("https://") ||
+        parseTrustedOrigin(siteUrl) === undefined) {
+        return undefined;
+    }
+    return {
+        advanced: {
+            defaultCookieAttributes: {
+                httpOnly: true,
+                sameSite: "none",
+                secure: true,
+            },
+            useSecureCookies: true,
+        },
+    };
+}
+//# sourceMappingURL=better-auth.js.map

package/dist/better-auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"better-auth.js","sourceRoot":"","sources":["../src/better-auth.ts"],"names":[],"mappings":"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"}

package/dist/identity.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Host-ctx identity glue: map `ctx.auth` to a host row, and retarget rows when
+ * an anonymous subject upgrades. Writes the **host's** tables — not a component.
+ */
+export type AuthIdentity = {
+    isAnonymous?: unknown;
+    issuer?: string;
+    subject: string;
+};
+export type AuthCtx = {
+    auth: {
+        getUserIdentity: () => Promise<AuthIdentity | null>;
+    };
+    /** Host-configured issuer; never accept this value from request arguments. */
+    trustedIssuer?: string;
+};
+export declare function isAnonymousIdentity(identity: AuthIdentity): boolean;
+export declare function requireIdentity(ctx: AuthCtx): Promise<AuthIdentity>;
+/**
+ * Query-side lookup. Returns null when unauthenticated or the host row is not
+ * there yet (BetterAuth `onCreate` can lag a fresh anonymous session).
+ */
+export declare function getFromAuth<T extends object>(ctx: AuthCtx, lookup: (subject: string) => Promise<null | T>): Promise<null | (T & {
+    isAnonymous: boolean;
+})>;
+export declare function requireFromAuth<T extends object>(ctx: AuthCtx, lookup: (subject: string) => Promise<null | T>): Promise<T & {
+    isAnonymous: boolean;
+}>;
+/**
+ * Mutation-side: look up the host row for the current identity, or insert it.
+ * Atomic when both callbacks use the SAME Convex mutation transaction,
+ * including an indexed lookup; every competing writer must use that lookup.
+ * Actions, remote calls and nontransactional callbacks do not provide uniqueness.
+ */
+export declare function getOrCreateFromAuth<T extends object>(ctx: AuthCtx, handlers: {
+    insert: (subject: string) => Promise<T>;
+    lookup: (subject: string) => Promise<null | T>;
+}): Promise<T & {
+    isAnonymous: boolean;
+}>;
+/**
+ * Process at most 1000 rows sequentially (one callback in flight).
+ * The host owns authorization, page size, continuation, conflict resolution and
+ * transaction boundaries. This is not an account merge or ownership check.
+ */
+export declare function retargetRows<T>(rows: readonly T[], apply: (row: T) => Promise<"deleted" | "patched" | "skipped">): Promise<{
+    deleted: number;
+    patched: number;
+    skipped: number;
+}>;
+//# sourceMappingURL=identity.d.ts.map

package/dist/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,MAAM,MAAM,YAAY,GAAG;IACzB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,OAAO,GAAG;IACpB,IAAI,EAAE;QACJ,eAAe,EAAE,MAAM,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;KACrD,CAAC;IACF,8EAA8E;IAC9E,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO,CAEnE;AAcD,wBAAsB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,CAAC,CAUzE;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAAC,CAAC,SAAS,MAAM,EAChD,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,GAAG,CAAC,CAAC,GAC7C,OAAO,CAAC,IAAI,GAAG,CAAC,CAAC,GAAG;IAAE,WAAW,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC,CAOhD;AAED,wBAAsB,eAAe,CAAC,CAAC,SAAS,MAAM,EACpD,GAAG,EAAE,OAAO,EACZ,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,GAAG,CAAC,CAAC,GAC7C,OAAO,CAAC,CAAC,GAAG;IAAE,WAAW,EAAE,OAAO,CAAA;CAAE,CAAC,CASvC;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,CAAC,SAAS,MAAM,EACxD,GAAG,EAAE,OAAO,EACZ,QAAQ,EAAE;IACR,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;IACxC,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC;CAChD,GACA,OAAO,CAAC,CAAC,GAAG;IAAE,WAAW,EAAE,OAAO,CAAA;CAAE,CAAC,CAKvC;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,IAAI,EAAE,SAAS,CAAC,EAAE,EAClB,KAAK,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,OAAO,CAAC,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC,GAC5D,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAchE"}

package/dist/identity.js

@@ -0,0 +1,80 @@
+/**
+ * Host-ctx identity glue: map `ctx.auth` to a host row, and retarget rows when
+ * an anonymous subject upgrades. Writes the **host's** tables — not a component.
+ */
+import { ConvexError } from "convex/values";
+export function isAnonymousIdentity(identity) {
+    return identity.isAnonymous === true;
+}
+function assertTrustedIssuer(ctx, identity) {
+    if (ctx.trustedIssuer !== undefined &&
+        identity.issuer !== ctx.trustedIssuer) {
+        throw new ConvexError({
+            code: "UNAUTHENTICATED",
+            message: "Untrusted issuer.",
+        });
+    }
+}
+export async function requireIdentity(ctx) {
+    const identity = await ctx.auth.getUserIdentity();
+    if (identity === null) {
+        throw new ConvexError({
+            code: "UNAUTHENTICATED",
+            message: "Sign-in required.",
+        });
+    }
+    assertTrustedIssuer(ctx, identity);
+    return identity;
+}
+/**
+ * Query-side lookup. Returns null when unauthenticated or the host row is not
+ * there yet (BetterAuth `onCreate` can lag a fresh anonymous session).
+ */
+export async function getFromAuth(ctx, lookup) {
+    const identity = await ctx.auth.getUserIdentity();
+    if (identity === null)
+        return null;
+    assertTrustedIssuer(ctx, identity);
+    const row = await lookup(identity.subject);
+    if (row === null)
+        return null;
+    return { ...row, isAnonymous: isAnonymousIdentity(identity) };
+}
+export async function requireFromAuth(ctx, lookup) {
+    const user = await getFromAuth(ctx, lookup);
+    if (user === null) {
+        throw new ConvexError({
+            code: "USER_NOT_INITIALIZED",
+            message: "User not initialized — the auth session may still be settling.",
+        });
+    }
+    return user;
+}
+/**
+ * Mutation-side: look up the host row for the current identity, or insert it.
+ * Atomic when both callbacks use the SAME Convex mutation transaction,
+ * including an indexed lookup; every competing writer must use that lookup.
+ * Actions, remote calls and nontransactional callbacks do not provide uniqueness.
+ */
+export async function getOrCreateFromAuth(ctx, handlers) {
+    const identity = await requireIdentity(ctx);
+    const existing = await handlers.lookup(identity.subject);
+    const row = existing ?? (await handlers.insert(identity.subject));
+    return { ...row, isAnonymous: isAnonymousIdentity(identity) };
+}
+/**
+ * Process at most 1000 rows sequentially (one callback in flight).
+ * The host owns authorization, page size, continuation, conflict resolution and
+ * transaction boundaries. This is not an account merge or ownership check.
+ */
+export async function retargetRows(rows, apply) {
+    if (rows.length > 1000) {
+        throw new RangeError("retargetRows accepts at most 1000 rows per page");
+    }
+    return rows.reduce(async (previous, row) => {
+        const counts = await previous;
+        const outcome = await apply(row);
+        return { ...counts, [outcome]: counts[outcome] + 1 };
+    }, Promise.resolve({ deleted: 0, patched: 0, skipped: 0 }));
+}
+//# sourceMappingURL=identity.js.map

package/dist/identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.js","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"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"}

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

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/mcp/auth.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CASlE;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,UAAU,GACf,OAAO,CACN;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,IAAI,CAAA;CAAE,GACrD;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CACvC,CAiCA"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/mcp/auth.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CASlE;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,UAAU,GACf,OAAO,CACN;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,IAAI,CAAA;CAAE,GACrD;IAAE,QAAQ,EAAE,QAAQ,CAAC;IAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CACvC,CA+CA"}

package/dist/mcp/auth.js

@@ -1,3 +1,4 @@
+import { policyCallback } from "./callback.js";
 export function extractApiKey(request) {
     const authHeader = request.headers.get("authorization");
     if (!authHeader)
@@ -17,20 +18,32 @@ export async function validateRequest(request, auth) {
             valid: false,
         };
     }
-    const isValid = await auth.validate(apiKey);
-    if (!isValid) {
+    try {
+        const isValid = await policyCallback(() => auth.validate(apiKey));
+        if (!isValid) {
+            return {
+                response: new Response(JSON.stringify({ error: "Invalid API key." }), {
+                    headers: { "Content-Type": "application/json" },
+                    status: 401,
+                }),
+                valid: false,
+            };
+        }
+        let convexToken;
+        if (auth.convexToken) {
+            const resolveToken = auth.convexToken;
+            convexToken = await policyCallback(() => resolveToken(apiKey));
+        }
+        return { apiKey, convexToken, valid: true };
+    }
+    catch {
         return {
-            response: new Response(JSON.stringify({ error: "Invalid API key." }), {
+            response: new Response(JSON.stringify({ error: "Authentication failed." }), {
                 headers: { "Content-Type": "application/json" },
                 status: 401,
             }),
             valid: false,
         };
     }
-    let convexToken;
-    if (auth.convexToken) {
-        convexToken = await auth.convexToken(apiKey);
-    }
-    return { apiKey, convexToken, valid: true };
 }
 //# sourceMappingURL=auth.js.map

package/dist/mcp/auth.js.map

@@ -1 +1 @@
-{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/mcp/auth.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,aAAa,CAAC,OAAgB;IAC5C,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IACxD,IAAI,CAAC,UAAU;QAAE,OAAO,SAAS,CAAC;IAElC,IAAI,UAAU,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QACrC,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC7B,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,OAAgB,EAChB,IAAgB;IAKhB,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IAEtC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO;YACL,QAAQ,EAAE,IAAI,QAAQ,CACpB,IAAI,CAAC,SAAS,CAAC;gBACb,KAAK,EACH,gEAAgE;aACnE,CAAC,EACF,EAAE,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CACjE;YACD,KAAK,EAAE,KAAK;SACb,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC5C,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO;YACL,QAAQ,EAAE,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,kBAAkB,EAAE,CAAC,EAAE;gBACpE,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;gBAC/C,MAAM,EAAE,GAAG;aACZ,CAAC;YACF,KAAK,EAAE,KAAK;SACb,CAAC;IACJ,CAAC;IAED,IAAI,WAA+B,CAAC;IACpC,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;QACrB,WAAW,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IAC/C,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;AAC9C,CAAC"}
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/mcp/auth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAG/C,MAAM,UAAU,aAAa,CAAC,OAAgB;IAC5C,MAAM,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IACxD,IAAI,CAAC,UAAU;QAAE,OAAO,SAAS,CAAC;IAElC,IAAI,UAAU,CAAC,UAAU,CAAC,SAAS,CAAC,EAAE,CAAC;QACrC,OAAO,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAC7B,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,OAAgB,EAChB,IAAgB;IAKhB,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;IAEtC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO;YACL,QAAQ,EAAE,IAAI,QAAQ,CACpB,IAAI,CAAC,SAAS,CAAC;gBACb,KAAK,EACH,gEAAgE;aACnE,CAAC,EACF,EAAE,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CACjE;YACD,KAAK,EAAE,KAAK;SACb,CAAC;IACJ,CAAC;IAED,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;QAClE,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO;gBACL,QAAQ,EAAE,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,kBAAkB,EAAE,CAAC,EAAE;oBACpE,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;oBAC/C,MAAM,EAAE,GAAG;iBACZ,CAAC;gBACF,KAAK,EAAE,KAAK;aACb,CAAC;QACJ,CAAC;QAED,IAAI,WAA+B,CAAC;QACpC,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACrB,MAAM,YAAY,GAAG,IAAI,CAAC,WAAW,CAAC;YACtC,WAAW,GAAG,MAAM,cAAc,CAAC,GAAG,EAAE,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC;QACjE,CAAC;QAED,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IAC9C,CAAC;IAAC,MAAM,CAAC;QACP,OAAO;YACL,QAAQ,EAAE,IAAI,QAAQ,CACpB,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,wBAAwB,EAAE,CAAC,EACnD;gBACE,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;gBAC/C,MAAM,EAAE,GAAG;aACZ,CACF;YACD,KAAK,EAAE,KAAK;SACb,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/mcp/callback.d.ts

@@ -0,0 +1,3 @@
+/** Bound host policy callbacks; timeout does not cancel host-owned work. */
+export declare function policyCallback<T>(callback: () => Promise<T> | T): Promise<T>;
+//# sourceMappingURL=callback.d.ts.map

package/dist/mcp/callback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"callback.d.ts","sourceRoot":"","sources":["../../src/mcp/callback.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,wBAAsB,cAAc,CAAC,CAAC,EACpC,QAAQ,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GAC7B,OAAO,CAAC,CAAC,CAAC,CAcZ"}

package/dist/mcp/callback.js

@@ -0,0 +1,18 @@
+/** Bound host policy callbacks; timeout does not cancel host-owned work. */
+export async function policyCallback(callback) {
+    let handle;
+    try {
+        return await Promise.race([
+            Promise.resolve().then(callback),
+            new Promise((_, reject) => {
+                handle = setTimeout(() => {
+                    reject(new Error("Policy callback timed out"));
+                }, 10_000);
+            }),
+        ]);
+    }
+    finally {
+        clearTimeout(handle);
+    }
+}
+//# sourceMappingURL=callback.js.map

package/dist/mcp/callback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"callback.js","sourceRoot":"","sources":["../../src/mcp/callback.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,QAA8B;IAE9B,IAAI,MAAiD,CAAC;IACtD,IAAI,CAAC;QACH,OAAO,MAAM,OAAO,CAAC,IAAI,CAAC;YACxB,OAAO,CAAC,OAAO,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC;YAChC,IAAI,OAAO,CAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE;gBAC/B,MAAM,GAAG,UAAU,CAAC,GAAG,EAAE;oBACvB,MAAM,CAAC,IAAI,KAAK,CAAC,2BAA2B,CAAC,CAAC,CAAC;gBACjD,CAAC,EAAE,MAAM,CAAC,CAAC;YACb,CAAC,CAAC;SACH,CAAC,CAAC;IACL,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,MAAM,CAAC,CAAC;IACvB,CAAC;AACH,CAAC"}

package/dist/mcp/resources/register.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../../src/mcp/resources/register.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,yCAAyC,CAAC;AAG3E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,KAAK,gBAAgB,GAAG;IACtB,UAAU,EAAE,UAAU,CAAC,OAAO,eAAe,CAAC,GAAG,SAAS,CAAC;IAC3D,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,WAAW,EAAE,WAAW,CAAC;IACzB,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GACrC,gBAAgB,EAAE,CAUpB;AAED,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,gBAAgB,EAAE,GAC5B,IAAI,CA4CN"}
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../../src/mcp/resources/register.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,EAAE,gBAAgB,EAAE,MAAM,yCAAyC,CAAC;AAG3E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,KAAK,gBAAgB,GAAG;IACtB,UAAU,EAAE,UAAU,CAAC,OAAO,eAAe,CAAC,GAAG,SAAS,CAAC;IAC3D,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,WAAW,EAAE,WAAW,CAAC;IACzB,QAAQ,EAAE,gBAAgB,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,GACrC,gBAAgB,EAAE,CAUpB;AAED,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,YAAY,EACpB,SAAS,EAAE,gBAAgB,EAAE,GAC5B,IAAI,CAuCN"}

package/dist/mcp/resources/register.js

@@ -31,13 +31,8 @@ export function registerResources(mcpServer, client, resources) {
                     ],
                 };
             }
-            catch (error) {
-                console.error("[convex-mcp] resource read failed", {
-                    error,
-                    resource: uriPattern,
-                });
-                // Mask the raw Convex error from the client (parity with the tool
-                // handler); the real error is logged server-side above.
+            catch {
+                // Do not log raw exceptions: provider errors may contain secrets.
                 throw new Error("Resource read failed");
             }
         });

package/dist/mcp/resources/register.js.map

@@ -1 +1 @@
-{"version":3,"file":"register.js","sourceRoot":"","sources":["../../../src/mcp/resources/register.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,yCAAyC,CAAC;AAE3E,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAYnD,MAAM,UAAU,gBAAgB,CAC9B,SAAsC;IAEtC,OAAO,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,EAAE,WAAW,CAAC,EAAE,EAAE,CAAC,CAAC;QACnE,UAAU,EAAE,WAAW,CAAC,IAAI;YAC1B,CAAC,CAAC,eAAe,CAAC,WAAW,CAAC,IAAI,CAAC;YACnC,CAAC,CAAC,SAAS;QACb,WAAW,EAAE,WAAW,CAAC,WAAW;QACpC,WAAW;QACX,QAAQ,EAAE,IAAI,gBAAgB,CAAC,UAAU,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QAC/D,UAAU;KACX,CAAC,CAAC,CAAC;AACN,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,SAAoB,EACpB,MAAoB,EACpB,SAA6B;IAE7B,KAAK,MAAM,EACT,UAAU,EACV,WAAW,EACX,WAAW,EACX,QAAQ,EACR,UAAU,GACX,IAAI,SAAS,EAAE,CAAC;QACf,SAAS,CAAC,QAAQ,CAChB,UAAU,EACV,QAAQ,EACR;YACE,WAAW;YACX,QAAQ,EAAE,kBAAkB;SAC7B,EACD,KAAK,EAAE,GAAG,EAAE,UAAmC,EAAE,EAAE;YACjD,IAAI,CAAC;gBACH,MAAM,mBAAmB,GACvB,UAAU,EAAE,KAAK,CAAC,UAAU,CAAC,IAAI,UAAU,CAAC;gBAC9C,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,KAAK,CAC/B,WAAW,CAAC,GAAG,EACf,mBAAmB,CACpB,CAAC;gBACF,OAAO;oBACL,QAAQ,EAAE;wBACR;4BACE,QAAQ,EAAE,kBAAkB;4BAC5B,IAAI,EAAE,eAAe,CAAC,MAAM,CAAC;4BAC7B,GAAG,EAAE,GAAG,CAAC,IAAI;yBACd;qBACF;iBACF,CAAC;YACJ,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,OAAO,CAAC,KAAK,CAAC,mCAAmC,EAAE;oBACjD,KAAK;oBACL,QAAQ,EAAE,UAAU;iBACrB,CAAC,CAAC;gBACH,kEAAkE;gBAClE,wDAAwD;gBACxD,MAAM,IAAI,KAAK,CAAC,sBAAsB,CAAC,CAAC;YAC1C,CAAC;QACH,CAAC,CACF,CAAC;IACJ,CAAC;AACH,CAAC"}
+{"version":3,"file":"register.js","sourceRoot":"","sources":["../../../src/mcp/resources/register.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,yCAAyC,CAAC;AAE3E,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAYnD,MAAM,UAAU,gBAAgB,CAC9B,SAAsC;IAEtC,OAAO,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,UAAU,EAAE,WAAW,CAAC,EAAE,EAAE,CAAC,CAAC;QACnE,UAAU,EAAE,WAAW,CAAC,IAAI;YAC1B,CAAC,CAAC,eAAe,CAAC,WAAW,CAAC,IAAI,CAAC;YACnC,CAAC,CAAC,SAAS;QACb,WAAW,EAAE,WAAW,CAAC,WAAW;QACpC,WAAW;QACX,QAAQ,EAAE,IAAI,gBAAgB,CAAC,UAAU,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QAC/D,UAAU;KACX,CAAC,CAAC,CAAC;AACN,CAAC;AAED,MAAM,UAAU,iBAAiB,CAC/B,SAAoB,EACpB,MAAoB,EACpB,SAA6B;IAE7B,KAAK,MAAM,EACT,UAAU,EACV,WAAW,EACX,WAAW,EACX,QAAQ,EACR,UAAU,GACX,IAAI,SAAS,EAAE,CAAC;QACf,SAAS,CAAC,QAAQ,CAChB,UAAU,EACV,QAAQ,EACR;YACE,WAAW;YACX,QAAQ,EAAE,kBAAkB;SAC7B,EACD,KAAK,EAAE,GAAG,EAAE,UAAmC,EAAE,EAAE;YACjD,IAAI,CAAC;gBACH,MAAM,mBAAmB,GACvB,UAAU,EAAE,KAAK,CAAC,UAAU,CAAC,IAAI,UAAU,CAAC;gBAC9C,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,KAAK,CAC/B,WAAW,CAAC,GAAG,EACf,mBAAmB,CACpB,CAAC;gBACF,OAAO;oBACL,QAAQ,EAAE;wBACR;4BACE,QAAQ,EAAE,kBAAkB;4BAC5B,IAAI,EAAE,eAAe,CAAC,MAAM,CAAC;4BAC7B,GAAG,EAAE,GAAG,CAAC,IAAI;yBACd;qBACF;iBACF,CAAC;YACJ,CAAC;YAAC,MAAM,CAAC;gBACP,kEAAkE;gBAClE,MAAM,IAAI,KAAK,CAAC,sBAAsB,CAAC,CAAC;YAC1C,CAAC;QACH,CAAC,CACF,CAAC;IACJ,CAAC;AACH,CAAC"}

package/dist/mcp/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AAiBA,OAAO,KAAK,EAAgB,eAAe,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAuB9E,wBAAgB,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,eAAe,CAwKrE"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAgB,eAAe,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAuB9E,wBAAgB,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,eAAe,CAyJrE"}

package/dist/mcp/server.js

@@ -5,7 +5,7 @@ import { validateRequest } from "./auth.js";
 import { createPaginationContext } from "./pagination/context.js";
 import { getOriginalToolsList, registerPaginationHandlers, registerTwoPhaseHandlers, } from "./pagination/handlers.js";
 import { prepareResources, registerResources } from "./resources/register.js";
-import { findToolsWithReservedArgs as findToolsWithReservedArguments, prepareTools, registerTools, } from "./tools/register.js";
+import { prepareTools, registerTools } from "./tools/register.js";
 function createDefaultClient(convexUrl, convexToken) {
     const client = new ConvexHttpClient(convexUrl);
     if (convexToken) {
@@ -49,18 +49,6 @@ export function createMCPServer(config) {
     const prepared = prepareTools(config.tools ?? {});
     const preparedRes = prepareResources(config.resources ?? {});
     const paginationCtx = createPaginationContext(config.pagination);
-    if (!hooks?.onToolCall) {
-        const stripped = findToolsWithReservedArguments(config.tools ?? {});
-        if (stripped.size > 0) {
-            const summary = [...stripped.entries()]
-                .map(([tool, keys]) => `${tool} (${keys.join(", ")})`)
-                .join("; ");
-            console.warn(`[convex-mcp] tools declare reserved \`_*\` args but no onToolCall hook is configured. ` +
-                `These args are stripped from the published schema and will never be injected, ` +
-                `so every dispatched call will fail Convex validation. ` +
-                `Configure hooks.onToolCall to inject them via extendArgs. Affected tools: ${summary}`);
-        }
-    }
     function createServerAndTransport(requestId, convexToken, apiKey) {
         const mcpServer = new McpServer({
             name: serverName,