@attest-dev/sdk 0.1.0-beta.1

package/dist/mcp.d.ts

@@ -0,0 +1,312 @@
+/**
+ * @attest-dev/sdk/mcp — Attest credential enforcement middleware for MCP servers.
+ *
+ * Wraps any MCP server instance and enforces Attest credential checking on
+ * every tool call before the underlying handler executes.
+ *
+ * ## Two-line integration
+ *
+ * ```ts
+ * import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+ * import { withAttest } from "@attest-dev/sdk/mcp";
+ *
+ * const server = new McpServer({ name: "my-tools", version: "1.0.0" });
+ * const protectedServer = withAttest(server, {
+ *   issuerUri: "https://api.attest.dev",
+ * });
+ *
+ * // Register tools exactly as before — every call is now credential-gated.
+ * protectedServer.tool("send_email", "Send an email", schema, handler);
+ * ```
+ *
+ * ## How it works
+ *
+ * `withAttest` monkey-patches `server.tool()` so each registered handler is
+ * wrapped with a credential check closure.  On every tool call the closure:
+ *
+ * 1. Extracts the Attest JWT from `extra.authInfo.token` (set by the MCP
+ *    auth middleware) or `extra.meta?.attest_token`.
+ * 2. Verifies the JWT offline against the issuer's JWKS (cached per TTL).
+ * 3. Maps the tool name to a Attest scope string via `scopeForTool()`.
+ * 4. Confirms the credential's `att_scope` covers the required scope.
+ * 5. Calls the Attest revocation endpoint to confirm the JTI is still live.
+ * 6. If all checks pass, executes the original handler.
+ * 7. If any check fails, returns a structured `attest_violation` error.
+ * 8. Fire-and-forgets an audit event to the Attest server regardless of
+ *    outcome.
+ */
+/** Minimal shape of the auth info injected by the MCP auth middleware. */
+interface McpAuthInfo {
+    /** Raw bearer token string (the Attest JWT). */
+    token: string;
+    clientId?: string;
+    scopes?: string[];
+    expiresAt?: Date;
+    extra?: Record<string, unknown>;
+}
+/** Minimal shape of the extra argument passed to every MCP tool handler. */
+interface McpRequestExtra {
+    /** Populated by MCP auth middleware from the Authorization header. */
+    authInfo?: McpAuthInfo | undefined;
+    /** Arbitrary metadata; agents may pass attest_token here explicitly. */
+    meta?: Record<string, unknown> | undefined;
+    signal?: AbortSignal;
+    sessionId?: string;
+    requestId?: string | number;
+}
+/**
+ * Minimal interface for any object that behaves like an MCP server.
+ * `withAttest` accepts anything with a `tool()` method.
+ */
+export interface McpServerLike {
+    tool: (...args: unknown[]) => unknown;
+    [key: string]: unknown;
+}
+/** The decoded Attest JWT claims threaded through the MCP request. */
+export interface AttestContext {
+    /** Unique identifier for this credential. */
+    jti: string;
+    /** Task tree ID shared across the entire delegation chain. */
+    att_tid: string;
+    /** Delegation depth (0 = root credential). */
+    att_depth: number;
+    /** Granted permission scopes in "resource:action" form. */
+    att_scope: string[];
+    /** Human user who initiated the task. */
+    att_uid: string;
+    /** Raw JWT string. */
+    token: string;
+}
+/** Emitted to `onViolation` when a tool call is blocked. */
+export interface ScopeViolationEvent {
+    /** MCP tool name that was blocked. */
+    toolName: string;
+    /** Attest scope required by this tool. */
+    requiredScope: string;
+    /** Scopes actually present in the credential (empty if no credential). */
+    grantedScope: string[];
+    /** Violation category. */
+    reason: 'no_credential' | 'credential_expired' | 'credential_revoked' | 'scope_violation' | 'invalid_credential' | 'audit_failure';
+    /** Credential JTI if available. */
+    jti?: string;
+    /** Task ID if available. */
+    taskId?: string;
+    /** ISO timestamp of the violation. */
+    timestamp: string;
+}
+/**
+ * Options for `withAttest`.
+ */
+export interface AttestMcpOptions {
+    /**
+     * URI of the Attest server used to fetch JWKS and check revocation.
+     * @example "https://api.attest.dev"
+     */
+    issuerUri: string;
+    /**
+     * How long (in seconds) to cache the JWKS before re-fetching.
+     * Longer values reduce latency; shorter values pick up key rotations faster.
+     * @default 3600
+     */
+    jwksCacheTTL?: number;
+    /**
+     * When `true` (the default), tool calls without a valid Attest credential
+     * are blocked and a `attest_violation` error is returned.
+     *
+     * When `false`, violations are logged via `onViolation` but the tool call
+     * proceeds.  Useful for gradual rollouts or debugging.
+     * @default true
+     */
+    requireCredential?: boolean;
+    /**
+     * Called synchronously when any scope check fails.
+     * Use this to emit metrics, write logs, or trigger alerts.
+     */
+    onViolation?: (event: ScopeViolationEvent) => void;
+    /**
+     * Per-tool scope overrides.  Keys are exact MCP tool names; values are
+     * Attest scope strings.  Overrides the automatic `scopeForTool()` mapping.
+     *
+     * @example
+     * toolScopeMap: {
+     *   "send_message": "gmail:send",
+     *   "query_db":     "postgres:read",
+     * }
+     */
+    toolScopeMap?: Record<string, string>;
+    /**
+     * How long (in seconds) to cache revocation status for each JTI.
+     * Revocation is eventually consistent; a short TTL (5-30 s) balances
+     * latency against revocation lag.  Set to 0 to disable caching.
+     * @default 10
+     */
+    revocationCacheTTL?: number;
+    /**
+     * Called when an audit POST to the Attest server fails.
+     * Receives the underlying error and the event payload that was not delivered.
+     *
+     * Use this to implement a retry queue, write to a fallback log, or page
+     * on-call for compliance-critical deployments.
+     *
+     * If omitted, failures are surfaced via `onViolation` (with
+     * `reason: "audit_failure"`) and, if that is also unset, via
+     * `console.warn` — audit failures are never silently dropped.
+     *
+     * @example
+     * ```ts
+     * onAuditError: (err, event) => {
+     *   retryQueue.push({ event, attempts: 0 });
+     *   logger.error("audit delivery failed", { err, jti: event.jti });
+     * }
+     * ```
+     */
+    onAuditError?: (error: Error, event: AuditPayload) => void;
+}
+/** Structured error payload returned in the tool response body on violation. */
+export interface AttestViolationError {
+    error: 'attest_violation';
+    reason: ScopeViolationEvent['reason'];
+    detail: string;
+    jti?: string;
+    taskId?: string;
+}
+/**
+ * Optional Attest-specific options passed as the final argument to
+ * `protectedServer.tool()`.  The MCP SDK never sees this object — it is
+ * extracted and consumed by the `withAttest` wrapper before forwarding
+ * the remaining arguments.
+ *
+ * @example
+ * ```ts
+ * protectedServer.tool("gh_create_issue", schema, handler, {
+ *   requiredScope: "github:write",
+ * });
+ * ```
+ */
+export interface AttestToolOptions {
+    /**
+     * Explicit Attest scope string required to call this tool.
+     * Overrides the automatic `scopeForTool()` mapping.
+     * Use this for non-standard tool names or when the auto-mapping would
+     * produce a misleading scope.
+     *
+     * @example "github:write"
+     * @example "stripe:charge"
+     */
+    requiredScope?: string;
+}
+/**
+ * Maps an MCP tool name to a Attest scope string using a convention-based
+ * approach.  The tool name is split on the first underscore: the part before
+ * becomes the action; the rest (joined with `:`) becomes the resource.
+ *
+ * Action aliases:
+ * - `create`, `update`, `write`, `put`, `patch` → `write`
+ * - `remove`, `destroy`                         → `delete`
+ * - `run`, `invoke`                             → `execute`
+ * - `get`, `fetch`, `list`, `search`, `query`   → `read`
+ *
+ * @example
+ * scopeForTool("send_email")          // "email:send"
+ * scopeForTool("read_file")           // "file:read"
+ * scopeForTool("delete_calendar_event") // "calendar_event:delete"
+ * scopeForTool("create_user")         // "user:write"
+ * scopeForTool("run_query")           // "query:execute"
+ */
+export declare function scopeForTool(toolName: string, overrides?: Record<string, string>): string;
+/**
+ * The audit event payload sent to `POST /v1/audit` on the Attest server.
+ * Passed to `onAuditError` when delivery fails so the caller can retry or
+ * write to a fallback log.
+ */
+export interface AuditPayload {
+    event_type: 'verified' | 'revoked';
+    jti: string;
+    att_tid?: string | undefined;
+    att_uid?: string | undefined;
+    agent_id: string;
+    scope: string[];
+    meta?: Record<string, string> | undefined;
+}
+/**
+ * Wraps an MCP server instance and enforces Attest credential checking on
+ * every tool call.
+ *
+ * Returns the **same** server object with its `tool()` method patched in place,
+ * typed as the original server type so all other methods remain accessible.
+ *
+ * @param server  Any object with a `tool()` method (e.g. `new McpServer(...)`).
+ * @param options Attest enforcement options.
+ * @returns       The patched server (same reference, same type).
+ *
+ * @example
+ * ```ts
+ * import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+ * import { withAttest } from "@attest-dev/sdk/mcp";
+ *
+ * const server = new McpServer({ name: "my-tools", version: "1.0.0" });
+ * const protectedServer = withAttest(server, {
+ *   issuerUri: "https://api.attest.dev",
+ * });
+ *
+ * protectedServer.tool("send_email", schema, async (args, extra) => {
+ *   // Only reached when the caller holds a valid credential
+ *   // with "email:send" in its att_scope.
+ *   return { content: [{ type: "text", text: "sent!" }] };
+ * });
+ * ```
+ */
+export declare function withAttest<T extends McpServerLike>(server: T, options: AttestMcpOptions): T;
+/**
+ * Decodes the Attest JWT in `extra` and returns a typed `AttestContext`
+ * without performing any cryptographic verification.
+ *
+ * Useful inside tool handlers when you want to read the credential's claims
+ * (e.g. `att_uid`, `att_tid`) after `withAttest` has already enforced them.
+ *
+ * @returns `null` when no Attest credential is present.
+ *
+ * @example
+ * ```ts
+ * protectedServer.tool("send_email", schema, async (args, extra) => {
+ *   const ctx = getAttestContext(extra);
+ *   console.log("acting on behalf of", ctx?.att_uid);
+ *   ...
+ * });
+ * ```
+ */
+export declare function getAttestContext(extra: McpRequestExtra): AttestContext | null;
+/**
+ * Returns the scope registry for a server that has been wrapped with
+ * `withAttest` — a map of every registered tool name to its resolved
+ * Attest scope string.
+ *
+ * Use this to build a scope discovery endpoint so credential issuers can
+ * query what scopes a server requires without out-of-band coordination.
+ *
+ * @example
+ * ```ts
+ * // Express / Hono / any HTTP framework:
+ * app.get("/.well-known/attest-scopes", (_req, res) => {
+ *   res.json({ tools: getAttestScopes(protectedServer) });
+ * });
+ *
+ * // Response:
+ * // {
+ * //   "tools": {
+ * //     "send_email":      "email:send",
+ * //     "read_file":       "file:read",
+ * //     "gh_create_issue": "github:write"
+ * //   }
+ * // }
+ * ```
+ *
+ * Tools that have not yet been registered (i.e. `server.tool()` hasn't been
+ * called for them yet) will not appear in the result.  Call this after all
+ * tools are registered, not during server startup.
+ *
+ * @returns A plain `Record<string, string>` safe to serialize directly as JSON.
+ */
+export declare function getAttestScopes(server: McpServerLike): Record<string, string>;
+export {};
+//# sourceMappingURL=mcp.d.ts.map

package/dist/mcp.d.ts.map

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