within-sdk 1.0.0 → 1.0.1

package/dist/middleware.js

@@ -1,562 +0,0 @@
-/**
- * With.in MCP Auth SDK — sealed request handler.
- *
- * Exposes ONE function, `createWithinHandler`, that returns a handler with:
- *   - `mcpHandler(req, res)`   — node HTTP handler for the MCP endpoint
- *   - `subscribeHandler(req,res)` — node HTTP handler for the /subscribe route
- *   - `vendorSlug`, `authServerUrl` — readonly fields for logging
- *
- * Everything else — token validation, tool-call reporting, trial-exhausted
- * gating, subscriber cross-check + auto conversion, transport construction
- * and session caching, network-tool injection, auth propagation into tool
- * handlers — is hidden inside `mcpHandler`. Vendors cannot accidentally
- * skip a step.
- */
-import { validateWithinToken, extractBearerToken, reportToolCall, reportConversion, checkSubscriptionStatus, } from './validate.js';
-import { NETWORK_TOOL_NAMES, registerNetworkTools, runWithAuth } from './network.js';
-const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
-/**
- * Keep tool-call arguments reportable without blowing up interactions rows.
- * Returns null for anything that isn't a plain object. For each top-level
- * value, replaces entries whose stringified size exceeds 10 KB with a
- * `"[truncated N bytes]"` marker so we preserve the shape of the call
- * (field names tell us a lot about intent) without storing large blobs.
- */
-function sanitizeToolArgs(args) {
-    if (!args || typeof args !== 'object' || Array.isArray(args))
-        return null;
-    const MAX_VALUE_BYTES = 10_000;
-    const out = {};
-    for (const [k, v] of Object.entries(args)) {
-        try {
-            const serialized = JSON.stringify(v);
-            if (serialized && serialized.length > MAX_VALUE_BYTES) {
-                out[k] = `[truncated ${serialized.length} bytes]`;
-            }
-            else {
-                out[k] = v;
-            }
-        }
-        catch {
-            // Circular reference or unserializable value — drop it.
-            out[k] = null;
-        }
-    }
-    return out;
-}
-function autoExtractEmail(payload) {
-    const candidates = ['email', 'user_email', 'preferred_username', 'upn', 'sub'];
-    for (const key of candidates) {
-        const value = payload[key];
-        if (typeof value === 'string' && EMAIL_RE.test(value))
-            return value;
-    }
-    return null;
-}
-export function createWithinHandler(config) {
-    const { jwksUrl, authServerUrl, vendorSlug, resourceUrl, vendorTokenValidator, extractEmail, zod, createMcpServer, isSubscriber, log, } = config;
-    if (!zod)
-        throw new Error('createWithinHandler: `zod` is required');
-    if (!createMcpServer)
-        throw new Error('createWithinHandler: `createMcpServer` is required');
-    if (!isSubscriber && !vendorTokenValidator) {
-        console.warn('[within-mcp-auth] Neither `isSubscriber` nor `vendorTokenValidator` is configured. ' +
-            'Paying customers arriving via With.in tokens will be treated as trial users and eventually hit the trial-exhausted wall. ' +
-            'Wire `isSubscriber(email)` against your user DB to prevent this.');
-    }
-    const wellKnownUrl = new URL('/.well-known/oauth-protected-resource', resourceUrl).href;
-    const logger = log ?? (() => { });
-    // Per-process state. Safe for single-worker deploys (Render default).
-    // For multi-worker deployments, the session map should be externalized
-    // — but the vendor should never see this complexity.
-    //
-    // Quota state is keyed on the stable user identity (within_network_id)
-    // rather than the raw access token. A single user can hold multiple
-    // short-lived access tokens simultaneously (each `within__use` provision
-    // mints a fresh one); keying on the token resets the counter on every
-    // provision and lets trial limits be trivially bypassed.
-    const callCounts = new Map();
-    const subscriberIdentities = new Set();
-    const sessions = new Map(); // sid → transport
-    // Concurrency guard: `sessions.get(sid) → create new transport → sessions.set(sid, ...)`
-    // is a non-atomic sequence. Parallel tool calls against the same session
-    // (Claude fan-out) all observe the Map before the first request finishes
-    // registering, and each request ends up spawning its own McpServer. The
-    // client's session-id then resolves to whichever transport lost the race,
-    // orphaning the other transports' responses ("Tool result could not be
-    // submitted"). This map holds the in-flight creation promise per session
-    // so concurrent requests wait and reuse the same transport.
-    const pendingSessions = new Map();
-    // sid → MCP clientInfo.name captured from the `initialize` request. Surfaces
-    // to With.in on every tool-call report so the vendor + user dashboards can
-    // show which agent (Claude Desktop, Cursor, ChatGPT, …) made each call.
-    const sessionAiClient = new Map();
-    /** Stable identity for quota accounting — survives re-provisioning. */
-    function identityKey(auth) {
-        return (auth.withinClaims?.within_network_id ??
-            auth.withinClaims?.sub ??
-            auth.token ??
-            'unknown');
-    }
-    // Lazy-load the MCP server transport constructor. The SDK has no types
-    // for @modelcontextprotocol/server (peer dep), so we launder the module
-    // specifier through a const-typed string and cast the result.
-    const MCP_MOD = '@modelcontextprotocol/server';
-    let TransportCtor;
-    async function getTransport() {
-        if (TransportCtor)
-            return TransportCtor;
-        const mod = await import(MCP_MOD);
-        TransportCtor = mod.WebStandardStreamableHTTPServerTransport;
-        if (!TransportCtor) {
-            throw new Error('WebStandardStreamableHTTPServerTransport not found in @modelcontextprotocol/server');
-        }
-        return TransportCtor;
-    }
-    // ─── Internal: authenticate a request ───────────────────────────────────
-    async function authenticate(req) {
-        const authHeader = req.headers['authorization'];
-        const token = extractBearerToken(typeof authHeader === 'string' ? authHeader : undefined);
-        if (!token)
-            return { authorized: false, error: 'Missing Bearer token' };
-        // Vendor's own token takes precedence — treat as subscriber.
-        if (vendorTokenValidator) {
-            try {
-                const vendorPayload = await vendorTokenValidator(token);
-                if (vendorPayload) {
-                    const email = (extractEmail && extractEmail(vendorPayload)) || autoExtractEmail(vendorPayload);
-                    if (email)
-                        reportConversion(authServerUrl, vendorSlug, email);
-                    return { authorized: true, source: 'vendor', vendorPayload, token };
-                }
-            }
-            catch { }
-        }
-        const claims = await validateWithinToken(token, jwksUrl);
-        if (!claims)
-            return { authorized: false, error: 'Invalid or expired token' };
-        if (claims.token_type === 'identity') {
-            return {
-                authorized: false,
-                error: 'Identity tokens cannot be used for vendor access. Use token exchange to obtain an access token.',
-            };
-        }
-        let trialExhausted = false;
-        if (claims.within_trial_tier !== 'subscriber' && claims.within_calls_remaining !== undefined) {
-            const ident = claims.within_network_id ?? claims.sub ?? token;
-            const used = callCounts.get(ident) ?? 0;
-            if (used >= claims.within_calls_remaining && !subscriberIdentities.has(ident)) {
-                trialExhausted = true;
-            }
-        }
-        return { authorized: true, source: 'within', withinClaims: claims, token, trialExhausted };
-    }
-    function sendUnauthorized(res, auth) {
-        res.writeHead(401, {
-            'WWW-Authenticate': `Bearer resource_metadata="${wellKnownUrl}"`,
-            'Content-Type': 'application/json',
-        });
-        res.end(JSON.stringify({ error: 'unauthorized', message: auth.error ?? 'Bearer token required' }));
-    }
-    /**
-     * Build the trial-exhausted response as a tool result with isError=true.
-     *
-     * We deliberately do NOT include the upgrade URL or handoff email here.
-     * Embedding URLs/instructions in tool error responses is read by the model
-     * as untrusted content and triggers anti-phishing/paywall safeties that
-     * cause the agent to refuse to act on it. The next-step details are
-     * delivered out-of-band — With.in sends the user an email when the quota
-     * is exhausted (see backend/src/oauth/report.ts).
-     *
-     * The text instructs the agent to retry on user request: once the user
-     * subscribes, the SDK's live subscription check unblocks the next call,
-     * but only if the agent actually re-fires the tool. Without an explicit
-     * retry cue, agents read isError=true as terminal and stop.
-     */
-    function buildTrialExhaustedResponse(jsonRpcId, _claims) {
-        const content = [
-            {
-                type: 'text',
-                text: 'Your trial has ended. We sent an email with the details for continuing access. If the user confirms they have subscribed or completed the handoff, retry this tool call — access will be granted automatically.',
-            },
-        ];
-        return JSON.stringify({ jsonrpc: '2.0', id: jsonRpcId, result: { content, isError: true } });
-    }
-    // Access tokens are 10-min JWTs that the SDK verifies locally via JWKS, so a
-    // dashboard-initiated revoke can't be caught at validate-time — the
-    // signature stays good until expiry. The /oauth/report roundtrip on every
-    // tool call is the enforcement point: backend returns 401 token_revoked,
-    // and we surface that to the agent as a tool result so the upstream MCP
-    // server is never invoked with a revoked token.
-    function buildRevokedResponse(jsonRpcId) {
-        const content = [
-            {
-                type: 'text',
-                text: 'Access to this tool has been revoked. Please re-authorize to continue.',
-            },
-        ];
-        return JSON.stringify({ jsonrpc: '2.0', id: jsonRpcId, result: { content, isError: true } });
-    }
-    // Per-tool budgets are configured by the vendor in vendor_trial_rules. The
-    // backend enforces by returning 429 from /oauth/report once the count for
-    // that user/vendor/tool meets the limit. We must block here so the vendor's
-    // tool handler does NOT run — otherwise the budget would be observability
-    // only and the AQL row's total_calls would diverge from real execution.
-    // Other tools remain callable; the user just can't call this one again.
-    function buildBudgetExhaustedResponse(jsonRpcId, info) {
-        const content = [
-            {
-                type: 'text',
-                text: `You have reached the per-tool limit for "${info.tool}" (${info.limit} calls). Try a different tool, or contact the vendor for a higher limit.`,
-            },
-        ];
-        return JSON.stringify({ jsonrpc: '2.0', id: jsonRpcId, result: { content, isError: true } });
-    }
-    /**
-     * Returns a pre-built JSON-RPC trial-exhausted response if the call should
-     * be blocked, otherwise null and increments the per-token counter.
-     * SDK-injected network tools skip the counter entirely (see NETWORK_TOOL_NAMES).
-     */
-    async function processToolCallBody(body, auth, sessionId) {
-        if (!auth.token || auth.source !== 'within') {
-            return { blocked: null, method: null, id: null, toolName: null, aiClientFromInitialize: null };
-        }
-        let jsonBody;
-        try {
-            jsonBody = JSON.parse(decodeBody(body));
-        }
-        catch {
-            return { blocked: null, method: null, id: null, toolName: null, aiClientFromInitialize: null };
-        }
-        const method = typeof jsonBody?.method === 'string' ? jsonBody.method : null;
-        const id = jsonBody?.id ?? null;
-        const toolName = typeof jsonBody?.params?.name === 'string' ? jsonBody.params.name : null;
-        // Capture MCP clientInfo.name on the `initialize` request. The session
-        // ID isn't known yet (transport assigns it below); the caller stores this
-        // against newSessionId once the transport resolves.
-        if (method === 'initialize') {
-            const name = jsonBody?.params?.clientInfo?.name;
-            return {
-                blocked: null,
-                method,
-                id,
-                toolName: null,
-                aiClientFromInitialize: typeof name === 'string' && name.length > 0 ? name : null,
-            };
-        }
-        if (method !== 'tools/call' || !toolName)
-            return { blocked: null, method, id, toolName, aiClientFromInitialize: null };
-        // Network meta-tools are exempt from vendor trial quota accounting.
-        if (NETWORK_TOOL_NAMES.has(toolName))
-            return { blocked: null, method, id, toolName, aiClientFromInitialize: null };
-        const ident = identityKey(auth);
-        if (auth.trialExhausted) {
-            const isSubscriberNow = await checkSubscriptionStatus(authServerUrl, auth.token);
-            if (isSubscriberNow) {
-                subscriberIdentities.add(ident);
-                callCounts.delete(ident);
-                // fall through — allow
-            }
-            else {
-                return { blocked: buildTrialExhaustedResponse(id, auth.withinClaims), method, id, toolName, aiClientFromInitialize: null };
-            }
-        }
-        const slug = auth.withinClaims?.within_vendor_slug ?? vendorSlug;
-        const aiClient = sessionId ? sessionAiClient.get(sessionId) : undefined;
-        const rawArgs = jsonBody?.params?.arguments;
-        const toolArguments = sanitizeToolArgs(rawArgs);
-        // Await the report so we can enforce dashboard-initiated revocation AND
-        // per-tool budget exhaustion before the upstream tool runs. Reporting
-        // failures (network, 5xx) don't block — only explicit 401 token_revoked
-        // and 429 tool_budget_exhausted do.
-        const reportResult = await reportToolCall(authServerUrl, auth.token, slug, toolName, aiClient, toolArguments);
-        if (reportResult.revoked) {
-            return { blocked: buildRevokedResponse(id), method, id, toolName, aiClientFromInitialize: null };
-        }
-        if (reportResult.budgetExhausted) {
-            return {
-                blocked: buildBudgetExhaustedResponse(id, reportResult.budgetExhausted),
-                method,
-                id,
-                toolName,
-                aiClientFromInitialize: null,
-            };
-        }
-        // Bump the local quota counter only after we know the call is going
-        // through. Doing this earlier would charge the user for revoked or
-        // budget-blocked calls.
-        const used = callCounts.get(ident) ?? 0;
-        callCounts.set(ident, used + 1);
-        return { blocked: null, method, id, toolName, aiClientFromInitialize: null };
-    }
-    // ─── Internal: MCP session dispatch ─────────────────────────────────────
-    async function readBody(req) {
-        return new Promise((resolve) => {
-            const chunks = [];
-            req.on('data', (chunk) => {
-                // Node streams emit Buffer; Buffer is a Uint8Array subclass.
-                chunks.push(chunk);
-            });
-            req.on('end', () => {
-                let total = 0;
-                for (const c of chunks)
-                    total += c.byteLength;
-                const out = new Uint8Array(total);
-                let o = 0;
-                for (const c of chunks) {
-                    out.set(c, o);
-                    o += c.byteLength;
-                }
-                resolve(out);
-            });
-        });
-    }
-    function decodeBody(body) {
-        return new TextDecoder().decode(body);
-    }
-    async function buildWebRequest(req, body) {
-        const headers = new Headers();
-        for (const [key, value] of Object.entries(req.headers)) {
-            if (value)
-                headers.set(key, Array.isArray(value) ? value.join(', ') : value);
-        }
-        const hostHeader = typeof req.headers.host === 'string' ? req.headers.host : 'localhost';
-        const url = new URL(req.url ?? '/', `http://${hostHeader}`);
-        return new Request(url.toString(), {
-            method: req.method,
-            headers,
-            // TS is strict about Uint8Array as BodyInit; cast via ArrayBuffer view.
-            body: req.method !== 'GET' && req.method !== 'HEAD' && body.byteLength > 0 ? body : undefined,
-        });
-    }
-    async function sendWebResponse(res, webResponse) {
-        res.writeHead(webResponse.status, Object.fromEntries(webResponse.headers.entries()));
-        if (!webResponse.body) {
-            res.end();
-            return;
-        }
-        const reader = webResponse.body.getReader();
-        try {
-            while (true) {
-                const { done, value } = await reader.read();
-                if (done)
-                    break;
-                res.write(value);
-            }
-        }
-        catch (err) {
-            logger(`[within] stream error: ${err.message}`);
-        }
-        finally {
-            res.end();
-        }
-    }
-    // ─── Public: mcpHandler ─────────────────────────────────────────────────
-    async function mcpHandler(req, res) {
-        const auth = await authenticate(req);
-        if (!auth.authorized) {
-            sendUnauthorized(res, auth);
-            return;
-        }
-        // Subscriber cross-check: vendor's own user DB may recognize this email
-        // as an existing customer. If so, flip trialExhausted and report
-        // conversion so With.in updates the AQL. Cheap way to keep customers
-        // from hitting trial walls after they've already paid the vendor.
-        if (auth.source === 'within' && auth.withinClaims?.within_email && isSubscriber) {
-            try {
-                const known = await isSubscriber(auth.withinClaims.within_email);
-                if (known) {
-                    auth.trialExhausted = false;
-                    reportConversion(authServerUrl, vendorSlug, auth.withinClaims.within_email, auth.token);
-                    logger(`[within] ${auth.withinClaims.within_email} recognized as existing customer`);
-                }
-            }
-            catch (err) {
-                logger(`[within] isSubscriber threw: ${err.message}`);
-            }
-        }
-        if (auth.source === 'within' && auth.withinClaims) {
-            const { within_email, within_trial_tier, within_calls_remaining } = auth.withinClaims;
-            logger(`[within] ${within_email} | ${within_trial_tier ?? '?'} | ${within_calls_remaining ?? 'unlimited'} calls left`);
-        }
-        const body = await readBody(req);
-        // Session dispatch. MCP Streamable HTTP uses `mcp-session-id` header for
-        // subsequent requests. First request has no sid; transport assigns one.
-        const sessionId = req.headers['mcp-session-id'] ?? undefined;
-        const processed = await processToolCallBody(body, auth, sessionId);
-        if (processed.blocked) {
-            res.writeHead(200, { 'Content-Type': 'application/json' });
-            res.end(processed.blocked);
-            return;
-        }
-        // Fast path: known session-id, transport already registered.
-        if (sessionId) {
-            const existing = sessions.get(sessionId);
-            if (existing) {
-                const webRequest = await buildWebRequest(req, body);
-                const webResponse = await runWithAuth(auth, async () => (await existing.handleRequest(webRequest)));
-                await sendWebResponse(res, webResponse);
-                return;
-            }
-        }
-        // Stale session on GET (SSE stream reconnect) → 404 so the client
-        // re-initializes cleanly.
-        if (sessionId && req.method !== 'POST') {
-            res.writeHead(404, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ error: 'Session expired or server restarted. Please reconnect.' }));
-            return;
-        }
-        // Stale session-id on a non-initialize POST: don't silently spin up a new
-        // transport under a fresh UUID — that orphans the client's session-id and
-        // is the root cause of "Tool result could not be submitted". Send a
-        // JSON-RPC error so the client reconnects cleanly.
-        if (sessionId && processed.method !== 'initialize') {
-            res.writeHead(404, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({
-                jsonrpc: '2.0',
-                id: processed.id ?? null,
-                error: { code: -32001, message: 'Session expired or unknown. Please reconnect.' },
-            }));
-            return;
-        }
-        // Need a brand-new transport. Deduplicate concurrent creations keyed on
-        // whatever session-id the client provided (if any). Parallel requests
-        // with the same stale sid all wait on the same creation promise and end
-        // up sharing one transport. Requests with no sid (legitimate fresh
-        // initializes) each get their own slot.
-        const lockKey = sessionId ?? `__fresh__::${globalThis.crypto.randomUUID()}`;
-        const inFlight = pendingSessions.get(lockKey);
-        if (inFlight) {
-            try {
-                await inFlight;
-            }
-            catch { /* creator will surface its own error */ }
-            // Creator has now registered its transport in `sessions`. Retry the
-            // dispatch so this request lands on the shared transport.
-            const shared = sessionId ? sessions.get(sessionId) : undefined;
-            if (shared) {
-                const webRequest = await buildWebRequest(req, body);
-                const webResponse = await runWithAuth(auth, async () => (await shared.handleRequest(webRequest)));
-                await sendWebResponse(res, webResponse);
-                return;
-            }
-            // Fall through and create our own if the shared one disappeared.
-        }
-        const creation = (async () => {
-            // Honor the client-supplied session-id when present. If the server
-            // restarted and lost its Map, forcing a fresh UUID here would orphan
-            // the client; reusing the client's id lets it keep speaking the same
-            // session without noticing.
-            let assignedSessionId = sessionId;
-            const Transport = await getTransport();
-            const transport = new Transport({
-                sessionIdGenerator: () => {
-                    if (!assignedSessionId)
-                        assignedSessionId = globalThis.crypto.randomUUID();
-                    return assignedSessionId;
-                },
-            });
-            const mcpServer = createMcpServer();
-            // Inject the two network tools + fire the tool-list auto-report.
-            // Skipped (no-op) when the vendor has discoverable=false in the With.in
-            // dashboard — they opt out of the network on both the find-me and
-            // expose-meta-tools sides.
-            await registerNetworkTools(mcpServer, { vendorSlug, authServerUrl }, zod);
-            logger(`[within] new mcp session — tools=[${Object.keys(mcpServer._registeredTools ?? {}).join(', ')}]`);
-            await mcpServer.connect(transport);
-            const webRequest = await buildWebRequest(req, body);
-            const webResponse = await runWithAuth(auth, async () => (await transport.handleRequest(webRequest)));
-            const finalSid = assignedSessionId;
-            if (finalSid) {
-                sessions.set(finalSid, transport);
-                if (processed.aiClientFromInitialize) {
-                    sessionAiClient.set(finalSid, processed.aiClientFromInitialize);
-                }
-            }
-            return { webResponse, finalSid };
-        })();
-        pendingSessions.set(lockKey, creation);
-        try {
-            const { webResponse } = await creation;
-            await sendWebResponse(res, webResponse);
-        }
-        finally {
-            pendingSessions.delete(lockKey);
-        }
-    }
-    // ─── Public: subscribeHandler ───────────────────────────────────────────
-    async function subscribeHandler(req, res) {
-        let code = '';
-        if (req.url) {
-            try {
-                const u = new URL(req.url, 'http://x');
-                code = u.searchParams.get('c') ?? '';
-            }
-            catch { }
-        }
-        if (!code) {
-            res.writeHead(400, { 'Content-Type': 'text/plain' });
-            res.end('Missing code');
-            return;
-        }
-        const target = `${authServerUrl}/oauth/upgrade/${vendorSlug}?c=${encodeURIComponent(code)}`;
-        res.writeHead(302, { Location: target });
-        res.end();
-    }
-    // ─── Public: prmHandler ────────────────────────────────────────────────
-    //
-    // RFC 9728 Protected Resource Metadata. The `resource` field is derived
-    // from the incoming request so it byte-matches the URL the client used
-    // to fetch this document (RFC 9728 §3.3). Behind Render / Cloudflare /
-    // any TLS terminator, the X-Forwarded-Proto header carries the original
-    // scheme; we take its left-most value (the client-facing hop).
-    //
-    // scopes_supported and bearer_methods_supported come from WithinConfig
-    // with sensible defaults; authorization_servers is always the With.in
-    // auth server URL the SDK was initialized with.
-    const configuredHost = (() => {
-        try {
-            return new URL(resourceUrl).host;
-        }
-        catch {
-            return undefined;
-        }
-    })();
-    const scopesSupported = config.scopesSupported ?? ['tools:read', 'tools:write'];
-    const bearerMethodsSupported = config.bearerMethodsSupported ?? ['header'];
-    const configuredProto = (() => { try {
-        return new URL(resourceUrl).protocol.replace(':', '');
-    }
-    catch {
-        return 'http';
-    } })();
-    const configuredPath = (() => { try {
-        return new URL(resourceUrl).pathname;
-    }
-    catch {
-        return '/mcp';
-    } })();
-    function prmHandler(req, res) {
-        const forwardedProto = req.headers['x-forwarded-proto'];
-        const protoHeader = Array.isArray(forwardedProto) ? forwardedProto[0] : forwardedProto;
-        // Fall back to the scheme from resourceUrl so local dev (no reverse proxy) works correctly.
-        const proto = typeof protoHeader === 'string' ? protoHeader.split(',')[0].trim() : configuredProto;
-        const hostHeader = req.headers.host;
-        const host = typeof hostHeader === 'string' ? hostHeader : configuredHost ?? 'localhost';
-        const body = JSON.stringify({
-            resource: `${proto}://${host}${configuredPath}`,
-            authorization_servers: [authServerUrl],
-            scopes_supported: scopesSupported,
-            bearer_methods_supported: bearerMethodsSupported,
-        });
-        res.writeHead(200, { 'Content-Type': 'application/json' });
-        res.end(body);
-    }
-    return {
-        mcpHandler,
-        subscribeHandler,
-        prmHandler,
-        get vendorSlug() { return vendorSlug; },
-        get authServerUrl() { return authServerUrl; },
-    };
-}

package/dist/network.d.ts

@@ -1,83 +0,0 @@
-/**
- * With.in Network Discovery + Cross-Vendor Tool Use
- *
- * Injects two tools into every SDK-equipped vendor MCP server:
- *
- *   • find_vendor_for_task  — semantic search over the With.in vendor catalog
- *   • within__use           — silently provision + proxy a tool call to another vendor
- *
- * Both tools read the caller's identity from AsyncLocalStorage. The vendor
- * wraps their MCP request handling in `within.runWithAuth(auth, fn)` so the
- * tools see the correct access token + claims. See README for integration.
- *
- * Security posture:
- *   • The access token the vendor already validated is reused as the bearer for
- *     /api/network/*. It carries the same within_network_id / within_email /
- *     within_org_domain as the UIT would.
- *   • Fresh per-target access tokens are minted server-side and cached only
- *     for the remainder of their TTL.
- *   • within__use requires user_confirmed=true. This is a guardrail so Claude
- *     can't silently fan out — it must obtain user consent for the target
- *     vendor between find_vendor_for_task and within__use.
- */
-export declare const NETWORK_TOOL_NAMES: ReadonlySet<string>;
-import type { AuthResult } from './types.js';
-export interface NetworkConfig {
-    /** The vendor slug this SDK instance is running for. */
-    vendorSlug: string;
-    /** The With.in auth server base URL (e.g. https://gateway.getwith.in). */
-    authServerUrl: string;
-}
-export declare const authContextStorage: {
-    getStore(): AuthResult | undefined;
-};
-export declare function runWithAuth<T>(auth: AuthResult, fn: () => Promise<T>): Promise<T>;
-/**
- * Returns the definitions of the two network tools. Register them on your
- * vendor's MCP server exactly once at startup.
- *
- * Intentionally not tied to a specific MCP server package — the vendor calls
- * `server.registerTool(def.name, def.config, def.handler)` with its own
- * zod-compatible schema wrapper. See `registerNetworkTools` below for a
- * helper that does this for the @modelcontextprotocol/server package.
- */
-export declare function buildNetworkTools(config: NetworkConfig, z: any): {
-    discover: {
-        name: string;
-        config: {
-            title: string;
-            description: string;
-            inputSchema: any;
-            _meta: Record<string, unknown>;
-        };
-        handler: ({ intent, exclude_vendor_slugs }: {
-            intent: string;
-            exclude_vendor_slugs?: string[];
-        }) => Promise<{
-            content: {
-                type: "text";
-                text: string;
-            }[];
-        }>;
-    };
-    use: {
-        name: string;
-        config: {
-            title: string;
-            description: string;
-            inputSchema: any;
-        };
-        handler: ({ target_vendor_slug, tool_name, tool_arguments, user_confirmed, }: {
-            target_vendor_slug: string;
-            tool_name: string;
-            tool_arguments: Record<string, unknown>;
-            user_confirmed: boolean;
-        }) => Promise<any>;
-    };
-};
-/** Diagnostic — exposes current cached network-status (or undefined if never fetched). */
-export declare function getNetworkStatusCache(slug: string): {
-    discoverable: boolean;
-    fetchedAtMs: number;
-} | undefined;
-export declare function registerNetworkTools(mcpServer: any, config: NetworkConfig, z: any): Promise<void>;