@buildbase/sdk 0.0.53 → 0.0.54

package/dist/mcp/index.d.ts

@@ -1,6 +1,35 @@
 import { z } from 'zod';
 
-/** MCP Server Card (SEP-1649 / SEP-2127), advertising a live MCP server. */
+/** An Agent Skill (Agent Skills Discovery RFC v0.2.0) published by this app. */
+interface AgentSkill {
+    /** Stable slug, e.g. `imejis-api`. */
+    name: string;
+    /** One-line human/agent-readable summary. */
+    description: string;
+    /** Full markdown content of the SKILL.md served for this skill. */
+    content: string;
+    /**
+     * Path the SKILL.md is served from. Defaults to
+     * `/.well-known/agent-skills/<name>/SKILL.md`.
+     */
+    path?: string;
+    /** Skill artifact kind. Defaults to `skill-md`. */
+    type?: 'skill-md' | 'archive';
+}
+/** One API described in an API Catalog (RFC 9727 / RFC 9264 linkset). */
+interface ApiCatalogApi {
+    /** Anchor URL identifying the API, e.g. `https://api.imejis.io`. */
+    anchor: string;
+    /** OpenAPI / machine-readable description URL (link rel `service-desc`). */
+    serviceDesc?: string;
+    /** Human documentation URL (link rel `service-doc`). */
+    serviceDoc?: string;
+    /** Health / status endpoint URL (link rel `status`). */
+    status?: string;
+    /** Optional human title for the API. */
+    title?: string;
+}
+/** MCP Server Card (SEP-1649 v1.0), advertising a live MCP server. */
 interface McpServerCard {
     /** Server name. */
     name: string;
@@ -10,13 +39,251 @@ interface McpServerCard {
     endpoint: string;
     /** Transport type. Defaults to `"streamable-http"`. */
     transport?: string;
-    /** Capabilities object, e.g. `{ tools: {}, resources: {} }`. */
+    /** MCP protocol version the server speaks. Defaults to `"2025-06-18"`. */
+    protocolVersion?: string;
+    /**
+     * Capability flags. Booleans per SEP-1649 v1.0; a legacy object value
+     * (e.g. `{ tools: {} }`) is normalized to booleans by presence.
+     */
     capabilities?: Record<string, unknown>;
     /** Optional human description. */
     description?: string;
     /** Documentation URL. */
     documentationUrl?: string;
 }
+/** One OAuth scope an app declares in its scope catalog. */
+interface AppScope {
+    /** Scope name, e.g. `designs:read`. */
+    name: string;
+    /** Human-readable description, shown on the consent screen. */
+    description: string;
+}
+/** One skill advertised on the A2A Agent Card. */
+interface A2ACardSkill {
+    id: string;
+    name: string;
+    description: string;
+    tags?: string[];
+}
+/**
+ * Overrides for the A2A Agent Card (`/.well-known/agent-card.json`). Every
+ * field is optional — the card is fully derived from `site` + `skills` by
+ * default. See {@link buildA2AAgentCard}.
+ */
+interface A2ACardConfig {
+    name?: string;
+    version?: string;
+    description?: string;
+    /** The endpoint agents connect to. Defaults to `siteUrl`. */
+    serviceUrl?: string;
+    /** Transport protocol advertised for `serviceUrl`. Defaults to `'http'`. */
+    transportProtocol?: string;
+    /** A2A capability flags. Defaults to `{ streaming: false, pushNotifications: false }`. */
+    capabilities?: Record<string, unknown>;
+    /** Skills; defaults to a mapping of `config.skills` (or a generic site skill). */
+    skills?: A2ACardSkill[];
+}
+/** One robots.txt policy group (a `User-agent:` block). */
+interface RobotsPolicy {
+    /** User-agent(s) this group applies to, e.g. `'*'` or `'GPTBot'`. */
+    userAgent: string | string[];
+    /** Paths to allow, e.g. `['/']`. */
+    allow?: string[];
+    /** Paths to disallow, e.g. `['/api/']`. */
+    disallow?: string[];
+    /** Optional `Crawl-delay` (non-standard but widely honored). */
+    crawlDelay?: number;
+}
+/**
+ * Content Signals (https://contentsignals.org) — declares how crawlers may use
+ * this site's content. Each flag renders as `<signal>=yes|no`; omitted flags
+ * are not emitted (unset = no preference expressed).
+ */
+interface ContentSignals {
+    /** May content be indexed for search? → `search=yes|no`. */
+    search?: boolean;
+    /** May content be used as AI input (RAG, grounding)? → `ai-input=yes|no`. */
+    aiInput?: boolean;
+    /** May content be used for AI training? → `ai-train=yes|no`. */
+    aiTrain?: boolean;
+}
+/** Configuration for `buildRobotsTxt`. Every field is optional. */
+interface RobotsConfig {
+    /** Policy groups. Defaults to `[{ userAgent: '*', allow: ['/'] }]`. */
+    policies?: RobotsPolicy[];
+    /**
+     * Stance toward known AI crawlers ({@link AI_BOT_USER_AGENTS}): `'allow'`
+     * (default — an explicit `Allow: /` group per bot, so readiness checkers see
+     * AI bots addressed), `'deny'` (a `Disallow: /` group per bot), or explicit
+     * per-bot policies for finer control.
+     */
+    aiBots?: 'allow' | 'deny' | RobotsPolicy[];
+    /** Content-Signal directive attached to the `User-agent: *` group. */
+    contentSignals?: ContentSignals;
+    /**
+     * Sitemap URLs. Defaults to `${siteUrl}/sitemap.xml` when `config.sitemap`
+     * is set; pass `[]` to emit no `Sitemap:` line.
+     */
+    sitemaps?: string[];
+}
+/** One URL entry for the generated sitemap.xml. */
+interface SitemapUrl {
+    /** Absolute URL, or a path resolved against `siteUrl`. */
+    loc: string;
+    /** ISO-8601 last-modified date. */
+    lastmod?: string;
+    changefreq?: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
+    /** 0.0–1.0. */
+    priority?: number;
+}
+/** Configuration for the agent-readiness discovery layer. */
+interface AgentReadyConfig {
+    /** BuildBase server base URL, e.g. `https://api.buildbase.app` (no trailing slash needed). */
+    serverUrl: string;
+    /** The org id (24-hex) whose agent-readiness config to serve. */
+    orgId: string;
+    /**
+     * This app's public origin, e.g. `https://imejis.io`. Used to build absolute
+     * URLs in the Agent Card and to match RFC 9728 resource paths.
+     */
+    siteUrl: string;
+    /** Static metadata for the Agent Card (`/.well-known/agent.json`). */
+    site: {
+        name: string;
+        description?: string;
+        /** Absolute URL to human/agent documentation. */
+        documentationUrl?: string;
+        /** Support/contact email surfaced on the Agent Card. */
+        contactEmail?: string;
+        /** Provider block; defaults to `{ name: site.name, url: siteUrl }`. */
+        provider?: {
+            name: string;
+            url: string;
+        };
+    };
+    /** Agent Skills to publish. Omit to skip the Agent Skills documents. */
+    skills?: AgentSkill[];
+    /**
+     * The app's OAuth scope catalog — the source of truth for `scopes_supported`
+     * in this app's RFC 9728 protected-resource metadata (served from your own
+     * origin). Declare real, per-app scopes here (`designs:read`,
+     * `render:execute`, …) instead of placeholders. A `protectedResources` entry
+     * without its own `scopes` list inherits every catalog scope name. Scopes are
+     * app-owned: the shared BuildBase authorization server stays scope-agnostic.
+     */
+    scopes?: AppScope[];
+    /** security.txt fields (RFC 9116). Omit to skip serving security.txt. */
+    security?: {
+        /** Contact URI(s) — email (`mailto:`) or URL. */
+        contact: string | string[];
+        /** ISO-8601 expiry; strongly recommended by RFC 9116. */
+        expires?: string;
+        /** Security policy URL. */
+        policy?: string;
+    };
+    /**
+     * API Catalog entries (RFC 9727), served at `/.well-known/api-catalog` as
+     * `application/linkset+json`. Omit to skip.
+     */
+    apiCatalog?: ApiCatalogApi[];
+    /**
+     * MCP Server Card (SEP-1649), served at `/.well-known/mcp/server-card.json`.
+     * Only set this when you actually run an MCP server — the card advertises a
+     * live transport endpoint. Omit to skip.
+     */
+    mcpServerCard?: McpServerCard;
+    /**
+     * Raw `/auth.md` content (agent registration/auth instructions). If omitted,
+     * `buildAuthMd` generates one from the OAuth metadata + site config.
+     */
+    authMd?: string;
+    /**
+     * Local `/llms.txt` content. Takes precedence over the org-authored llms.txt
+     * from the platform bundle — use when the app owns richer llms.txt content.
+     */
+    llmsTxt?: string;
+    /**
+     * Local `/llms-full.txt` content (llmstxt.org expanded document). Omit to
+     * skip serving it (or serve your own static file, which then wins).
+     */
+    llmsFullTxt?: string;
+    /**
+     * A2A Agent Card served at `/.well-known/agent-card.json`. Served by
+     * DEFAULT, derived from `site` + `skills`, so readiness scanners find a
+     * valid card with zero config. Pass `false` to disable, or an object to
+     * override any derived field.
+     */
+    a2aCard?: false | A2ACardConfig;
+    /**
+     * Web Bot Auth key directory (IETF WebBotAuth) served at
+     * `/.well-known/http-message-signatures-directory`. Only for apps whose own
+     * outbound bot/agent signs its requests — publish the JWKS public keys here
+     * so receiving sites can verify the signatures. Omitted = not served.
+     */
+    webBotAuth?: {
+        keys: Array<Record<string, unknown>>;
+    };
+    /**
+     * Extra literal documents served by {@link resolveAgentPath}, keyed by exact
+     * request path. The escape hatch for anything the SDK has no builder for —
+     * commerce discovery (x402, UCP, ACP, MPP), `/openapi.json`, future
+     * `.well-known` documents. A string value infers its content type from the
+     * path extension. Extra paths take precedence over built-in documents, so
+     * they can also override any SDK-generated document.
+     */
+    extraPaths?: Record<string, string | {
+        body: string;
+        contentType?: string;
+        status?: number;
+        cacheControl?: string;
+    }>;
+    /** robots.txt generation (`buildRobotsTxt`). Omitted = sane defaults. */
+    robots?: RobotsConfig;
+    /**
+     * URLs for a minimal generated sitemap.xml (`buildSitemap`). Omit when the
+     * app already generates sitemaps (e.g. next-sitemap) — the builder then
+     * returns null and your own files win.
+     */
+    sitemap?: {
+        urls: Array<string | SitemapUrl>;
+    };
+    /**
+     * RFC 9728 protected resources this app serves, defined locally (app-owned).
+     * When set, the SDK builds the `/.well-known/oauth-protected-resource`
+     * document from this config — `authorization_servers` is derived from
+     * `serverUrl`/`orgId` (the BuildBase issuer). Takes precedence over the
+     * platform bundle. Omit to fall back to the org-configured bundle.
+     */
+    protectedResources?: Array<{
+        /** The protected API's resource URI. Defaults to `siteUrl`. */
+        resource?: string;
+        /** Scopes this resource accepts (`scopes_supported`). */
+        scopes?: string[];
+        /** Human documentation URL (`resource_documentation`). */
+        documentationUrl?: string;
+        /** Bearer methods (`bearer_methods_supported`). Defaults to `['header']`. */
+        bearerMethods?: string[];
+    }>;
+    /** TTL (seconds) for cached platform fetches. Default 300 (5 min). */
+    cacheTtlSeconds?: number;
+    /**
+     * Timeout (ms) for platform fetches. Fail-soft on timeout, so a hung or slow
+     * BuildBase server can't hang discovery routes forever. Default 5000; set `0`
+     * to disable.
+     */
+    fetchTimeoutMs?: number;
+    /** Injectable fetch, mainly for testing. Defaults to the global `fetch`. */
+    fetch?: typeof fetch;
+}
+/** A rendered discovery document ready to become an HTTP response. */
+interface DiscoveryDocument {
+    status: number;
+    contentType: string;
+    body: string;
+    cacheControl: string;
+    /** Value for a `Vary` response header, when the body is negotiated. */
+    vary?: string;
+}
 
 /**
  * Built-in MCP tools mapping BuildBase capabilities to agent-callable tools.
@@ -1240,6 +1507,15 @@ interface CreateMcpHandlerConfig {
      * an Origin header (curl, server-to-server) always pass.
      */
     allowedOrigins?: string[];
+    /**
+     * CORS for browser-based MCP clients. Default **true**: emit
+     * `Access-Control-Allow-Origin: *` (safe for a Bearer-token API — no
+     * cookies are ever involved), or reflect the matching origin when
+     * `allowedOrigins` is set. Pass an origin array to allow only those, or
+     * `false` to emit no CORS headers at all. Preflight (OPTIONS) is answered
+     * automatically either way — no wrapper needed in your route.
+     */
+    cors?: boolean | string[];
     /**
      * Hard cap on the raw request-body size in bytes (DoS protection). Bodies
      * larger than this are rejected with 413 before parsing. Defaults to
@@ -1351,6 +1627,40 @@ declare class AppBridgeError extends Error {
     readonly code: string;
     constructor(code: string, message: string);
 }
+/**
+ * The user + grant context BuildBase sends to `applicationTokenUrl`. The app
+ * mints a token for this user; `resource` is the RFC 8707 audience(s) the token
+ * should be bound to (stamp them as `aud`), and `scope` is what the user granted.
+ * Unknown claims are preserved for forward-compatibility.
+ */
+interface AppTokenRequestClaims {
+    /** The user's id in the org. */
+    id: string;
+    email: string;
+    name?: string;
+    role?: string;
+    emailVerified?: boolean;
+    image?: string;
+    blocked?: boolean;
+    blockedReason?: string;
+    blockedAt?: string;
+    /** Which grant triggered this mint. */
+    grantType?: 'authorization_code' | 'refresh_token';
+    /** Scopes granted at authorization time. */
+    scope?: string[];
+    /** RFC 8707 resource indicator(s) — bind the minted token's `aud` to these. */
+    resource?: string[];
+    /** The OAuth2 client's display title. */
+    clientTitle?: string;
+    /**
+     * Per-user BuildBase session bound to this grant. Embed it ENCRYPTED in the
+     * token you mint (JWTs are signed, not encrypted) and never store it — your
+     * MCP/agent endpoints decrypt it per request to call BuildBase as this user
+     * (`buildbase.withSession(...)`). Fresh on every grant, including refresh.
+     */
+    sessionId?: string;
+    [claim: string]: unknown;
+}
 /** Options for {@link verifyClientJwt} (all optional; secure defaults). */
 interface VerifyClientJwtOptions {
     /** Allowed clock skew in seconds for `exp`/`nbf`. Default 60. */
@@ -1371,11 +1681,8 @@ interface VerifyClientJwtOptions {
  * its payload. Checks the signature (timing-safe), the algorithm, `exp`/`nbf`,
  * and — by default — that an `exp` is present at all. Optionally pins `iss`/`aud`.
  * Throws {@link AppBridgeError} on any failure.
- *
- * The third argument accepts either the legacy `clockToleranceSec` number or a
- * {@link VerifyClientJwtOptions} object.
  */
-declare function verifyClientJwt(token: string, clientSecret: string, optionsOrTolerance?: number | VerifyClientJwtOptions): Record<string, any>;
+declare function verifyClientJwt(token: string, clientSecret: string, options?: VerifyClientJwtOptions): Record<string, any>;
 /** Extract the token from an `Authorization: Bearer <token>` header. */
 declare function extractBearerToken(authorization: string | null | undefined): string | null;
 /**
@@ -1398,5 +1705,252 @@ declare function bearerChallenge(options: {
     body: string;
 };
 
-export { AppBridgeError, bearerChallenge, builtinMcpTools, createMcpHandler, defineMcpTool, extractBearerToken, selectBuiltinTools, signClientJwt, verifyClientJwt };
-export type { BuiltinMcpToolName, CreateMcpHandlerConfig, McpAuthInfo, McpBuildBaseClient, McpHandler, McpHttpRequest, McpHttpResponse, McpServerCard, McpToolAnnotations, McpToolContext, McpToolDefinition, ScopedActions };
+/**
+ * createAgentStack — the whole agent-readiness + MCP surface from ONE config.
+ *
+ * Everything the SDK can derive, it derives: the MCP endpoint, the server
+ * card, the RFC 9728 protected-resource metadata, the API-catalog entry, the
+ * BuildBase client, token verification (via `buildbaseAuth`), CORS, and the
+ * discovery `Link` header — so a consumer configures identity once and wires
+ * two routes. Every derived value stays overridable ("accelerate, never
+ * gate").
+ *
+ * @example Next.js App Router — complete agent support:
+ * ```ts
+ * // lib/agent.ts
+ * import { createAgentStack } from "@buildbase/sdk/mcp";
+ * export const agent = createAgentStack({
+ *   serverUrl: process.env.NEXT_PUBLIC_BUILDBASE_SERVER_URL!,
+ *   orgId: process.env.NEXT_PUBLIC_BUILDBASE_ORG_ID!,
+ *   siteUrl: "https://app.example.com",
+ *   site: { name: "My App" },
+ *   secret: process.env.SYSTEM_SECRET!,
+ * });
+ *
+ * // app/api/mcp/route.ts
+ * import { agent } from "@/lib/agent";
+ * export const { GET, POST, DELETE, OPTIONS } = agent.routes;
+ *
+ * // app/.well-known/[...path]/route.ts — and identical one-liners at
+ * // app/robots.txt/route.ts, app/auth.md/route.ts, app/security.txt/route.ts
+ * import { agent } from "@/lib/agent";
+ * export const GET = agent.serveAgentPath;
+ * ```
+ *
+ * @example Express / Hono / Bun — same stack, `handle`/`fetch` style:
+ * ```ts
+ * app.all("/api/mcp", async (req, res) => {
+ *   const r = await agent.mcp.handle({ method: req.method, headers: req.headers, body: req.body });
+ *   res.status(r.status).set(r.headers).send(r.body);
+ * });
+ * app.use(async (req, res, next) => {
+ *   const doc = await agent.resolvePath(req.path);
+ *   if (!doc) return next();
+ *   res.status(doc.status).set("Content-Type", doc.contentType).send(doc.body);
+ * });
+ * ```
+ */
+
+/** Configuration for {@link createAgentStack}. */
+interface AgentStackConfig {
+    /** BuildBase server base URL. */
+    serverUrl: string;
+    /** The org id. */
+    orgId: string;
+    /** This app's public origin, e.g. `https://app.example.com`. */
+    siteUrl: string;
+    /** Site identity for every discovery document. */
+    site: AgentReadyConfig['site'];
+    /**
+     * The app's token-signing secret — wires `buildbaseAuth` (verify + audience
+     * binding + `sid` decryption) automatically. Never sent anywhere. Omit only
+     * when supplying `mcp.auth` yourself.
+     */
+    secret?: string;
+    /**
+     * The app's OAuth scope catalog (see `AgentReadyConfig.scopes`) —
+     * `scopes_supported` in the protected-resource metadata reads from it.
+     */
+    scopes?: AppScope[];
+    /** MCP server options. All optional — omit the whole block for defaults. */
+    mcp?: {
+        /** Endpoint path on `siteUrl`. Default `/api/mcp`. */
+        path?: string;
+        /** Advertised server identity. Defaults to the site name, v1.0.0. */
+        serverInfo?: {
+            name: string;
+            version: string;
+        };
+        /** Your custom tools. */
+        tools?: McpToolDefinition<any, any>[];
+        /** Built-in tool selection. Default `'readonly'`. */
+        builtinTools?: CreateMcpHandlerConfig['builtinTools'];
+        /** Scopes advertised on the protected-resource metadata. */
+        scopes?: string[];
+        /** Your own BuildBase client; auto-created from serverUrl/orgId if omitted. */
+        buildbase?: McpBuildBaseClient;
+        /** Override the derived auth (e.g. `false` for local dev). */
+        auth?: CreateMcpHandlerConfig['auth'];
+        /** Any remaining `createMcpHandler` option, merged last. */
+        handler?: Partial<CreateMcpHandlerConfig>;
+    };
+    /**
+     * Any {@link AgentReadyConfig} field (robots, skills, llms.txt, security,
+     * a2aCard, extraPaths, …) — merged over the derived discovery config, so
+     * every derived value can be replaced.
+     */
+    discovery?: Partial<AgentReadyConfig>;
+}
+/** What {@link createAgentStack} returns. */
+interface AgentStack {
+    /** The MCP handler (`handle`/`fetch`/`listTools`/`serverCard`). */
+    mcp: McpHandler;
+    /** Absolute MCP endpoint URL. */
+    mcpEndpoint: string;
+    /** The fully derived discovery config (inspect or reuse in middleware). */
+    config: AgentReadyConfig;
+    /** Discovery `Link` header value for your middleware / edge responses. */
+    linkHeader: string;
+    /** Resolve any agent-facing path to a document (framework-agnostic). */
+    resolvePath(path: string): Promise<DiscoveryDocument | null>;
+    /** Web-standard discovery route: hand it any `Request`, get a `Response`. */
+    serveAgentPath(request: Request): Promise<Response>;
+    /**
+     * Web-standard MCP route handlers, ready to re-export from a route file:
+     * `export const { GET, POST, DELETE, OPTIONS } = agent.routes`.
+     */
+    routes: {
+        GET: (request: Request) => Promise<Response>;
+        POST: (request: Request) => Promise<Response>;
+        DELETE: (request: Request) => Promise<Response>;
+        OPTIONS: (request: Request) => Promise<Response>;
+    };
+}
+/**
+ * Build the complete agent stack — MCP server + discovery surface — from one
+ * config object. See the module doc for full wiring examples.
+ */
+declare function createAgentStack(stack: AgentStackConfig): AgentStack;
+
+/**
+ * BuildBase agent-auth presets (server-side, framework-agnostic).
+ *
+ * The BuildBase security model: the platform runs the OAuth2 flow (login,
+ * consent, PKCE, refresh) but the APP mints and verifies its own user tokens,
+ * signed with the app's own secret. The platform only relays the minted token
+ * to the agent — it never sees the secret, so it can neither forge nor decode
+ * an app token. The per-user BuildBase session travels inside the token only
+ * as an AES-256-GCM-encrypted `sid` claim, so it is never stored and never
+ * plaintext anywhere; access to it expires with the token.
+ *
+ * These presets make that model a one-liner on each side of the flow, and run
+ * entirely in the app's process — pure local crypto, zero platform calls:
+ *
+ *   • {@link mintAgentToken}  — inside your `applicationTokenUrl` handler:
+ *     signs the app JWT (HS256) with your secret, stamps `aud` from the RFC
+ *     8707 resource, and embeds the encrypted `sid` automatically.
+ *   • {@link buildbaseAuth}   — the `auth` config for `createMcpHandler`:
+ *     verifies the JWT, enforces audience binding, decrypts the `sid`, and
+ *     maps the claims to `McpAuthInfo`.
+ *
+ * @example The full loop:
+ * ```ts
+ * // applicationTokenUrl route — the platform calls this on every grant
+ * const { status, body } = await handleAppTokenRequest({
+ *   authorization: req.headers.get("authorization"),
+ *   clientSecret: process.env.BUILDBASE_CLIENT_SECRET!,
+ *   mintToken: (claims) => mintAgentToken({ claims, secret: process.env.SYSTEM_SECRET! }),
+ * });
+ *
+ * // MCP server — verifies what the route above minted
+ * const mcp = createMcpHandler({
+ *   buildbase,
+ *   auth: buildbaseAuth({ secret: process.env.SYSTEM_SECRET!, resource: "https://app.example.com/api/mcp" }),
+ * });
+ * ```
+ *
+ * AES-GCM comes from WebCrypto (`globalThis.crypto.subtle`) — Node 18+, Bun,
+ * Deno, edge runtimes, browsers. The wire format is
+ * `base64url(iv(12) || authTag(16) || ciphertext)` with the key derived as
+ * `SHA-256(secret + ":bb-session")`, byte-compatible with Node
+ * `createCipheriv("aes-256-gcm", ...)` implementations of the same layout.
+ */
+
+/** Encrypt/decrypt pair for the `sid` claim, bound to one app secret. */
+interface SessionRefCrypto {
+    /** Encrypt a BuildBase session id for embedding in an app JWT. */
+    encryptSessionRef(sessionId: string): Promise<string>;
+    /** Decrypt a `sid` claim. Returns null on any failure (wrong key, garbage). */
+    decryptSessionRef(ref: string): Promise<string | null>;
+}
+/**
+ * Session-ref crypto derived from the app's secret. Both sides of the loop
+ * ({@link mintAgentToken}, {@link buildbaseAuth}) use this internally — reach
+ * for it directly only when minting or verifying tokens by hand.
+ */
+declare function createSessionRefCrypto(secret: string): SessionRefCrypto;
+/** Options for {@link mintAgentToken}. */
+interface MintAgentTokenOptions {
+    /** The verified platform claims (from `handleAppTokenRequest`'s callback). */
+    claims: AppTokenRequestClaims;
+    /** The APP's token-signing secret. Never leaves this process. */
+    secret: string;
+    /** Token lifetime in seconds. Default 3600 — keep agent tokens short-lived. */
+    expiresInSec?: number;
+    /**
+     * App-specific claims merged into the token — e.g. a `workspaceId` resolved
+     * by your own user sync. Merged last, so they can override the defaults.
+     */
+    extraClaims?: Record<string, unknown>;
+}
+/**
+ * Mint the app's agent access token from a platform grant: HS256-signed with
+ * YOUR secret, `aud` bound to the granted RFC 8707 resource(s), scopes carried
+ * through, and the per-user BuildBase session embedded as an encrypted `sid`
+ * claim. The result plugs straight into `handleAppTokenRequest`'s `mintToken`.
+ */
+declare function mintAgentToken(options: MintAgentTokenOptions): Promise<{
+    token: string;
+    expiresIn: number;
+}>;
+/** Options for {@link buildbaseAuth}. */
+interface BuildBaseAuthOptions {
+    /** The APP's token-signing secret — the same one `mintAgentToken` used. */
+    secret: string;
+    /**
+     * The protected resource(s) this server IS. Enforces RFC 8707 audience
+     * binding — the token's `aud` must include one of these URIs. Pass an array
+     * when the server is addressable under more than one resource identifier
+     * (e.g. the canonical `<host>/mcp` plus the literal endpoint URL); the
+     * FIRST entry is the canonical one used to derive `resourceMetadataUrl`.
+     */
+    resource?: string | string[];
+    /**
+     * Explicit RFC 9728 metadata URL for the 401 challenge. Defaults to the
+     * path-derived `/.well-known/oauth-protected-resource<path>` of the first
+     * `resource`.
+     */
+    resourceMetadataUrl?: string;
+    /**
+     * Reject tokens that carry no `aud` claim at all. Default false: audience is
+     * enforced when present, and legacy audience-less tokens still work. Turn
+     * this on once every minted token is audience-bound.
+     */
+    requireAudience?: boolean;
+    /** Extra JWT verification options (clock tolerance, issuer pinning). */
+    verify?: Pick<VerifyClientJwtOptions, 'clockToleranceSec' | 'issuer'>;
+}
+/**
+ * The `auth` config for `createMcpHandler`, prewired for BuildBase-minted app
+ * tokens: HS256 verification with your secret, RFC 8707 audience binding,
+ * `sid` decryption to the BuildBase session, claim mapping to `McpAuthInfo`,
+ * and the derived RFC 9728 `resourceMetadataUrl`. Entirely local — the token
+ * and secret never leave this process.
+ */
+declare function buildbaseAuth(options: BuildBaseAuthOptions): {
+    verify: (token: string, req: McpHttpRequest) => Promise<McpAuthInfo | null>;
+    resourceMetadataUrl?: string;
+};
+
+export { AppBridgeError, bearerChallenge, buildbaseAuth, builtinMcpTools, createAgentStack, createMcpHandler, createSessionRefCrypto, defineMcpTool, extractBearerToken, mintAgentToken, selectBuiltinTools, signClientJwt, verifyClientJwt };
+export type { AgentStack, AgentStackConfig, BuildBaseAuthOptions, BuiltinMcpToolName, CreateMcpHandlerConfig, McpAuthInfo, McpBuildBaseClient, McpHandler, McpHttpRequest, McpHttpResponse, McpServerCard, McpToolAnnotations, McpToolContext, McpToolDefinition, MintAgentTokenOptions, ScopedActions, SessionRefCrypto };