@openagentid/mcp API

export declare const withOpenAgent: <T extends McpServerLike>(server: T, config: OpenAgentMcpConfig) => T;

export declare const ANONYMOUS_IDENTITY: VerifiedIdentity;

/**
 * Minimal McpServer surface used by the middleware. We avoid importing
 * concrete types from `@modelcontextprotocol/sdk` because peer-dep
 * versions vary across host applications and the SDK's own type exports
 * are subject to change. The shape below is the intersection of every
 * `1.x` McpServer release.
 */
export interface McpServerLike {
    tool(...args: unknown[]): unknown;
    registerTool(...args: unknown[]): unknown;
}

export declare const withOpenAgentClient: <T extends McpClientLike>(client: T, config: OpenAgentClientConfig) => T;

export declare const buildIdentityMeta: (identity: { did: string; proof: string; nonce?: string; context?: Record<string, unknown>; }) => Record<string, unknown>;

/**
 * Minimal MCP client surface used by the interceptor. Like the server
 * adapter, we describe just the methods we need to keep peer-dep
 * compatibility broad.
 */
export interface McpClientLike {
    callTool(params: {
        name: string;
        arguments?: Record<string, unknown>;
        _meta?: Record<string, unknown>;
    }, ...rest: unknown[]): Promise<unknown>;
}

export interface OpenAgentClientConfig {
    /** The agent doing the calling — used to sign each request. */
    agent: Agent;
    /**
     * Optional audience DID. When set, it is passed to
     * {@link Agent.signRequest} so the proof can be bound to a specific
     * server. Most production deployments should set this.
     */
    audience?: string;
    /**
     * Optional hook fired before every outbound call. Use it for client-
     * side metrics or to mutate the params (e.g., add tracing headers).
     * Returning a value replaces the params.
     */
    beforeCall?: (params: {
        name: string;
        arguments?: Record<string, unknown>;
        _meta?: Record<string, unknown>;
    }) => Promise<{
        name: string;
        arguments?: Record<string, unknown>;
        _meta?: Record<string, unknown>;
    } | void> | {
        name: string;
        arguments?: Record<string, unknown>;
        _meta?: Record<string, unknown>;
    } | void;
}

export declare class OpenAgentMcpError {
  code: McpErrorCodeValue;
  data: Record<string, unknown>;
  constructor(message: string, code: McpErrorCodeValue, data?: Record<string, unknown>): OpenAgentMcpError;
  toJsonRpcError(): { code: McpErrorCodeValue; message: string; data?: Record<string, unknown>; };
}

export declare class MissingIdentityError {
  constructor(toolName: string): MissingIdentityError;
}

export declare class IdentityVerificationError {
  constructor(toolName: string, cause: unknown): IdentityVerificationError;
}

export declare class AuthorizationDeniedError {
  constructor(toolName: string, requiredScopes: ReadonlyArray<string>, heldScopes: ReadonlyArray<string>): AuthorizationDeniedError;
}

export declare class SkillsPolicyDeniedError {
  constructor(toolName: string, reason: string | undefined): SkillsPolicyDeniedError;
}

export declare const McpErrorCode: { readonly InvalidRequest: -32600; readonly MethodNotFound: -32601; readonly InvalidParams: -32602; readonly InternalError: -32603; readonly ServerError: -32000; readonly AuthenticationFailed: -32001; readonly AuthorizationDenied: -32002; readonly SkillsPolicyDenied: -32003; };

export type McpErrorCodeValue = (typeof McpErrorCode)[keyof typeof McpErrorCode];

export declare const createSkillsPolicy: (options: CreateSkillsPolicyOptions) => SkillsPolicyHook;

export declare const combineSkillsPolicies: (first: SkillsPolicyHook, second: SkillsPolicyHook) => SkillsPolicyHook;

export declare class InMemorySkillsPolicyStore {
  constructor(rules?: ReadonlyArray<SkillsRule>): InMemorySkillsPolicyStore;
  lookup(skillName: string): SkillsRule | null;
  withRule(rule: SkillsRule): InMemorySkillsPolicyStore;
}

export declare const DEFAULT_SKILL_TOOL_NAMES: readonly string[];

/**
 * A single rule describing whether a `(skillName, did)` pair is allowed.
 * `null` for `dids` means "any verified caller". An empty array means
 * "no caller".
 */
export interface SkillsRule {
    skillName: string;
    /** DIDs allowed to invoke this skill, or `null` for any. */
    dids: ReadonlyArray<string> | null;
    /** Optional reason emitted when the rule denies a call. */
    reason?: string;
}

/**
 * Policy store interface — implementations may be in-memory, file-backed
 * by `SKILLS.md`, or fetched from a remote service.
 */
export interface SkillsPolicyStore {
    lookup(skillName: string): Promise<SkillsRule | null> | SkillsRule | null;
}

export interface CreateSkillsPolicyOptions {
    /** The store backing skill lookups. */
    store: SkillsPolicyStore;
    /**
     * Returns true when a tool call should be checked against the skills
     * policy. Defaults to matching the tool name against
     * {@link DEFAULT_SKILL_TOOL_NAMES}.
     */
    isSkillTool?: (toolName: string) => boolean;
    /**
     * Extracts the skill name from the tool's arguments. Defaults to
     * reading `args.skill` or `args.skillName`.
     */
    extractSkillName?: (args: unknown) => string | null;
    /**
     * Default decision when no rule matches. Defaults to `{ allow: true }`
     * to keep non-skill tools unaffected.
     */
    defaultDecision?: SkillsPolicyDecision;
}

/**
 * Minimal Agent surface — only the parts of the OpenAgent SDK Agent that
 * the MCP middleware actually needs.
 */
export interface Agent {
    did: Did;
    verifier: IdentityVerifier;
    /**
     * Sign an outbound MCP call so the receiving server can verify the
     * caller. Returns the identity envelope to attach as `_meta.openagent`.
     */
    signRequest(toolName: string, audience?: Did): Promise<OpenAgentRequestIdentity>;
}

/**
 * Result envelope returned by an authenticated tool call. The `auditId` is
 * pushed into `_meta.openagent.audit_id` on the response, so callers can
 * correlate logs end-to-end.
 */
export interface AuditedResultMeta {
    audit_id: string;
    verified_did: Did;
    scopes: ReadonlyArray<string>;
}

/**
 * Public types for @openagentid/mcp.
 *
 * These interfaces describe the contract the middleware expects from an
 * OpenAgent {@link Agent} instance and the surrounding configuration. They are
 * defined locally so the package can be installed without `@openagentid/sdk` in
 * tests, in CI, and in environments where the host application brings its own
 * verifier implementation.
 *
 * The real `@openagentid/sdk` exports types that are structurally compatible
 * with these — there is no runtime dependency.
 */
/**
 * A decentralized identifier following the `did:oas:*` method or any other
 * DID method understood by the configured verifier.
 */
export type Did = string;

/**
 * Hook fired when the tool body or any earlier middleware step throws.
 * The middleware re-throws the error after running this hook so MCP
 * clients still observe the original failure mode.
 */
export type ErrorHook = (input: {
    toolName: string;
    args: unknown;
    identity: VerifiedIdentity | null;
    error: unknown;
}) => Promise<void> | void;

/**
 * The verifier interface — implemented by `@openagentid/sdk` (production) and
 * by the in-memory test agent shipped here.
 *
 * Implementations MUST be deterministic for a given input and MUST NOT
 * mutate the request identity object.
 */
export interface IdentityVerifier {
    verify(identity: OpenAgentRequestIdentity, requiredScopes: ReadonlyArray<string>): Promise<VerifiedIdentity>;
}

/**
 * Configuration for {@link withOpenAgent}.
 */
export interface OpenAgentMcpConfig {
    /** The agent that owns this MCP server (used for outbound signing). */
    agent: Agent;
    /**
     * Per-tool required scope set. Defaults to
     * `(toolName) => [`mcp:${toolName}:invoke`]`.
     */
    requireScopes?: ScopeDeriver;
    /**
     * If true (default), tool calls without an `_meta.openagent.identity`
     * envelope are rejected. Set to false to opt-in to permissive mode for
     * local development — the middleware will still run hooks but skip
     * verification.
     */
    requireIdentity?: boolean;
    /** Optional skills policy hook. */
    skillsPolicy?: SkillsPolicyHook;
    /** Optional pre-call hook. */
    preCall?: PreCallHook;
    /** Optional post-call hook for audit/log emission. */
    postCall?: PostCallHook;
    /** Optional error hook. */
    onError?: ErrorHook;
    /**
     * Override the default `mcp:<tool>:invoke` scope format. Receives the
     * tool name and returns the canonical scope string.
     */
    scopeFormat?: (toolName: string) => string;
}

/**
 * The four pieces of metadata an MCP request carries about the calling
 * agent. Populated by the {@link createClientInterceptor} on the call site
 * and consumed by the server middleware.
 */
export interface OpenAgentRequestIdentity {
    /** Caller's DID — typically `did:oas:...`. */
    did: Did;
    /**
     * A signed challenge response or capability token (Arsenal ACT) the
     * server can verify offline. Format is opaque to the middleware.
     */
    proof: string;
    /**
     * Optional bearer-style nonce. Servers may require it for replay
     * protection. Verifiers MUST treat the value as untrusted until
     * verification succeeds.
     */
    nonce?: string;
    /**
     * Free-form context the verifier may use (issuer DID, audience, scopes
     * the caller claims). Always validated against the verifier's policy.
     */
    context?: Record<string, unknown>;
}

/**
 * Hook fired after a tool body executes successfully. Use it for audit
 * logging, metrics, and trace propagation. Throwing from this hook does
 * NOT roll back the tool call.
 */
export type PostCallHook = (input: {
    toolName: string;
    args: unknown;
    identity: VerifiedIdentity;
    durationMs: number;
    result: unknown;
}) => Promise<void> | void;

/**
 * Hook fired before a tool body executes — after the identity has been
 * verified and the skills policy has approved the call.
 */
export type PreCallHook = (input: {
    toolName: string;
    args: unknown;
    identity: VerifiedIdentity;
}) => Promise<void> | void;

/** Per-tool scope deriver. */
export type ScopeDeriver = (toolName: string, args: unknown) => ReadonlyArray<string>;

export interface SkillsPolicyDecision {
    allow: boolean;
    reason?: string;
}

/**
 * Hook signature for the skills policy. The hook receives the tool name,
 * the arguments, and the verified identity, and decides whether the call
 * should be allowed.
 */
export type SkillsPolicyHook = (input: {
    toolName: string;
    args: unknown;
    identity: VerifiedIdentity;
}) => Promise<SkillsPolicyDecision> | SkillsPolicyDecision;

/**
 * The result of running the auth pipeline against an incoming MCP request.
 * Available to post-call hooks and audit log emitters.
 */
export interface VerifiedIdentity {
    did: Did;
    scopes: ReadonlyArray<string>;
    /** Audit identifier echoed back to the caller in result `_meta`. */
    auditId: string;
    /** Verifier-issued claims about the caller. */
    claims: Readonly<Record<string, unknown>>;
}

export declare const defaultRequireScopes: (toolName: string) => ReadonlyArray<string>;

export declare const defaultScopeFormat: (toolName: string) => string;