@openagentid/mcp 0.1.0

package/dist/skills.d.ts

@@ -0,0 +1,87 @@
+import { SkillsPolicyDecision, SkillsPolicyHook } from './types.js';
+export { VerifiedIdentity } from './types.js';
+
+/**
+ * Skills policy support for @openagentid/mcp.
+ *
+ * MCP tools and SKILLS.md entries describe the same thing: a capability
+ * an agent can invoke. When an MCP server exposes a tool that proxies
+ * skill invocation (typically named `invoke_skill` or any name a host
+ * application configures), the middleware consults a skills policy
+ * before allowing the call. This file provides the helper that picks the
+ * right policy for a given call and a small built-in store implementation
+ * suitable for tests and reference implementations.
+ */
+
+/**
+ * Tool name prefixes that the middleware treats as skill-like by default.
+ * Host applications can override the matcher entirely via
+ * {@link createSkillsPolicy}.
+ */
+declare const DEFAULT_SKILL_TOOL_NAMES: ReadonlyArray<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".
+ */
+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.
+ */
+interface SkillsPolicyStore {
+    lookup(skillName: string): Promise<SkillsRule | null> | SkillsRule | null;
+}
+/**
+ * Trivial in-memory store useful in tests and as a starting point for
+ * production stores.
+ */
+declare class InMemorySkillsPolicyStore implements SkillsPolicyStore {
+    private readonly rules;
+    constructor(rules?: ReadonlyArray<SkillsRule>);
+    lookup(skillName: string): SkillsRule | null;
+    /** Returns a NEW store with the given rule applied (immutable update). */
+    withRule(rule: SkillsRule): InMemorySkillsPolicyStore;
+}
+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;
+}
+/**
+ * Build a {@link SkillsPolicyHook} from a store and matching options.
+ *
+ * The returned hook always allows tools that are not skill-like; it only
+ * consults the store when {@link CreateSkillsPolicyOptions.isSkillTool}
+ * returns true.
+ */
+declare function createSkillsPolicy(options: CreateSkillsPolicyOptions): SkillsPolicyHook;
+/**
+ * Compose two skills policy hooks. The combined hook denies if either
+ * underlying hook denies; allow decisions from `first` are forwarded to
+ * `second`.
+ */
+declare function combineSkillsPolicies(first: SkillsPolicyHook, second: SkillsPolicyHook): SkillsPolicyHook;
+
+export { type CreateSkillsPolicyOptions, DEFAULT_SKILL_TOOL_NAMES, InMemorySkillsPolicyStore, SkillsPolicyDecision, SkillsPolicyHook, type SkillsPolicyStore, type SkillsRule, combineSkillsPolicies, createSkillsPolicy };

package/dist/skills.js

@@ -0,0 +1,91 @@
+// src/skills.ts
+var DEFAULT_SKILL_TOOL_NAMES = [
+  "invoke_skill",
+  "run_skill",
+  "execute_skill",
+  "skill.invoke",
+  "skill.run"
+];
+var InMemorySkillsPolicyStore = class _InMemorySkillsPolicyStore {
+  rules;
+  constructor(rules = []) {
+    this.rules = new Map(rules.map((rule) => [rule.skillName, rule]));
+  }
+  lookup(skillName) {
+    return this.rules.get(skillName) ?? null;
+  }
+  /** Returns a NEW store with the given rule applied (immutable update). */
+  withRule(rule) {
+    const next = new Map(this.rules);
+    next.set(rule.skillName, rule);
+    return new _InMemorySkillsPolicyStore([...next.values()]);
+  }
+};
+function createSkillsPolicy(options) {
+  const isSkillTool = options.isSkillTool ?? ((toolName) => DEFAULT_SKILL_TOOL_NAMES.includes(toolName));
+  const extractSkillName = options.extractSkillName ?? defaultExtractSkillName;
+  const defaultDecision = options.defaultDecision ?? {
+    allow: true
+  };
+  return async ({
+    toolName,
+    args,
+    identity
+  }) => {
+    if (!isSkillTool(toolName)) {
+      return defaultDecision;
+    }
+    const skillName = extractSkillName(args);
+    if (skillName === null) {
+      return {
+        allow: false,
+        reason: `Skill tool '${toolName}' invoked without a skill name`
+      };
+    }
+    const rule = await Promise.resolve(options.store.lookup(skillName));
+    if (rule === null) {
+      return {
+        allow: false,
+        reason: `No policy entry for skill '${skillName}'`
+      };
+    }
+    if (rule.dids === null) {
+      return { allow: true };
+    }
+    if (rule.dids.includes(identity.did)) {
+      return { allow: true };
+    }
+    return {
+      allow: false,
+      reason: rule.reason ?? `DID '${identity.did}' is not authorized for skill '${skillName}'`
+    };
+  };
+}
+function defaultExtractSkillName(args) {
+  if (args === null || typeof args !== "object") {
+    return null;
+  }
+  const record = args;
+  const skill = record["skill"];
+  if (typeof skill === "string" && skill.length > 0) {
+    return skill;
+  }
+  const skillName = record["skillName"];
+  if (typeof skillName === "string" && skillName.length > 0) {
+    return skillName;
+  }
+  return null;
+}
+function combineSkillsPolicies(first, second) {
+  return async (input) => {
+    const a = await Promise.resolve(first(input));
+    if (!a.allow) {
+      return a;
+    }
+    return Promise.resolve(second(input));
+  };
+}
+
+export { DEFAULT_SKILL_TOOL_NAMES, InMemorySkillsPolicyStore, combineSkillsPolicies, createSkillsPolicy };
+//# sourceMappingURL=skills.js.map
+//# sourceMappingURL=skills.js.map

package/dist/skills.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/skills.ts"],"names":[],"mappings":"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","file":"skills.js","sourcesContent":["/**\n * Skills policy support for @openagentid/mcp.\n *\n * MCP tools and SKILLS.md entries describe the same thing: a capability\n * an agent can invoke. When an MCP server exposes a tool that proxies\n * skill invocation (typically named `invoke_skill` or any name a host\n * application configures), the middleware consults a skills policy\n * before allowing the call. This file provides the helper that picks the\n * right policy for a given call and a small built-in store implementation\n * suitable for tests and reference implementations.\n */\n\nimport { SkillsPolicyDecision, SkillsPolicyHook } from './types.js';\n\n/**\n * Tool name prefixes that the middleware treats as skill-like by default.\n * Host applications can override the matcher entirely via\n * {@link createSkillsPolicy}.\n */\nexport const DEFAULT_SKILL_TOOL_NAMES: ReadonlyArray<string> = [\n  'invoke_skill',\n  'run_skill',\n  'execute_skill',\n  'skill.invoke',\n  'skill.run',\n];\n\n/**\n * A single rule describing whether a `(skillName, did)` pair is allowed.\n * `null` for `dids` means \"any verified caller\". An empty array means\n * \"no caller\".\n */\nexport interface SkillsRule {\n  skillName: string;\n  /** DIDs allowed to invoke this skill, or `null` for any. */\n  dids: ReadonlyArray<string> | null;\n  /** Optional reason emitted when the rule denies a call. */\n  reason?: string;\n}\n\n/**\n * Policy store interface — implementations may be in-memory, file-backed\n * by `SKILLS.md`, or fetched from a remote service.\n */\nexport interface SkillsPolicyStore {\n  lookup(skillName: string): Promise<SkillsRule | null> | SkillsRule | null;\n}\n\n/**\n * Trivial in-memory store useful in tests and as a starting point for\n * production stores.\n */\nexport class InMemorySkillsPolicyStore implements SkillsPolicyStore {\n  private readonly rules: Map<string, SkillsRule>;\n\n  constructor(rules: ReadonlyArray<SkillsRule> = []) {\n    this.rules = new Map(rules.map((rule) => [rule.skillName, rule]));\n  }\n\n  lookup(skillName: string): SkillsRule | null {\n    return this.rules.get(skillName) ?? null;\n  }\n\n  /** Returns a NEW store with the given rule applied (immutable update). */\n  withRule(rule: SkillsRule): InMemorySkillsPolicyStore {\n    const next = new Map(this.rules);\n    next.set(rule.skillName, rule);\n    return new InMemorySkillsPolicyStore([...next.values()]);\n  }\n}\n\nexport interface CreateSkillsPolicyOptions {\n  /** The store backing skill lookups. */\n  store: SkillsPolicyStore;\n  /**\n   * Returns true when a tool call should be checked against the skills\n   * policy. Defaults to matching the tool name against\n   * {@link DEFAULT_SKILL_TOOL_NAMES}.\n   */\n  isSkillTool?: (toolName: string) => boolean;\n  /**\n   * Extracts the skill name from the tool's arguments. Defaults to\n   * reading `args.skill` or `args.skillName`.\n   */\n  extractSkillName?: (args: unknown) => string | null;\n  /**\n   * Default decision when no rule matches. Defaults to `{ allow: true }`\n   * to keep non-skill tools unaffected.\n   */\n  defaultDecision?: SkillsPolicyDecision;\n}\n\n/**\n * Build a {@link SkillsPolicyHook} from a store and matching options.\n *\n * The returned hook always allows tools that are not skill-like; it only\n * consults the store when {@link CreateSkillsPolicyOptions.isSkillTool}\n * returns true.\n */\nexport function createSkillsPolicy(\n  options: CreateSkillsPolicyOptions,\n): SkillsPolicyHook {\n  const isSkillTool =\n    options.isSkillTool ??\n    ((toolName: string) => DEFAULT_SKILL_TOOL_NAMES.includes(toolName));\n  const extractSkillName =\n    options.extractSkillName ?? defaultExtractSkillName;\n  const defaultDecision: SkillsPolicyDecision = options.defaultDecision ?? {\n    allow: true,\n  };\n\n  return async ({\n    toolName,\n    args,\n    identity,\n  }): Promise<SkillsPolicyDecision> => {\n    if (!isSkillTool(toolName)) {\n      return defaultDecision;\n    }\n\n    const skillName = extractSkillName(args);\n    if (skillName === null) {\n      return {\n        allow: false,\n        reason: `Skill tool '${toolName}' invoked without a skill name`,\n      };\n    }\n\n    const rule = await Promise.resolve(options.store.lookup(skillName));\n    if (rule === null) {\n      return {\n        allow: false,\n        reason: `No policy entry for skill '${skillName}'`,\n      };\n    }\n\n    if (rule.dids === null) {\n      return { allow: true };\n    }\n\n    if (rule.dids.includes(identity.did)) {\n      return { allow: true };\n    }\n\n    return {\n      allow: false,\n      reason:\n        rule.reason ??\n        `DID '${identity.did}' is not authorized for skill '${skillName}'`,\n    };\n  };\n}\n\nfunction defaultExtractSkillName(args: unknown): string | null {\n  if (args === null || typeof args !== 'object') {\n    return null;\n  }\n  const record = args as Record<string, unknown>;\n  const skill = record['skill'];\n  if (typeof skill === 'string' && skill.length > 0) {\n    return skill;\n  }\n  const skillName = record['skillName'];\n  if (typeof skillName === 'string' && skillName.length > 0) {\n    return skillName;\n  }\n  return null;\n}\n\n/**\n * Compose two skills policy hooks. The combined hook denies if either\n * underlying hook denies; allow decisions from `first` are forwarded to\n * `second`.\n */\nexport function combineSkillsPolicies(\n  first: SkillsPolicyHook,\n  second: SkillsPolicyHook,\n): SkillsPolicyHook {\n  return async (input): Promise<SkillsPolicyDecision> => {\n    const a = await Promise.resolve(first(input));\n    if (!a.allow) {\n      return a;\n    }\n    return Promise.resolve(second(input));\n  };\n}\n\n/** Re-exported for convenience. */\nexport type {\n  SkillsPolicyHook,\n  SkillsPolicyDecision,\n  VerifiedIdentity,\n} from './types.js';\n"]}

package/dist/types.cjs

@@ -0,0 +1,10 @@
+'use strict';
+
+// src/types.ts
+var defaultScopeFormat = (toolName) => `mcp:${toolName}:invoke`;
+var defaultRequireScopes = (toolName) => [defaultScopeFormat(toolName)];
+
+exports.defaultRequireScopes = defaultRequireScopes;
+exports.defaultScopeFormat = defaultScopeFormat;
+//# sourceMappingURL=types.cjs.map
+//# sourceMappingURL=types.cjs.map

package/dist/types.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts"],"names":[],"mappings":";;;AAkMO,IAAM,kBAAA,GAAqB,CAAC,QAAA,KACjC,CAAA,IAAA,EAAO,QAAQ,CAAA,OAAA;AAMV,IAAM,uBAAuB,CAAC,QAAA,KACnC,CAAC,kBAAA,CAAmB,QAAQ,CAAC","file":"types.cjs","sourcesContent":["/**\n * Public types for @openagentid/mcp.\n *\n * These interfaces describe the contract the middleware expects from an\n * OpenAgent {@link Agent} instance and the surrounding configuration. They are\n * defined locally so the package can be installed without `@openagentid/sdk` in\n * tests, in CI, and in environments where the host application brings its own\n * verifier implementation.\n *\n * The real `@openagentid/sdk` exports types that are structurally compatible\n * with these — there is no runtime dependency.\n */\n\n/**\n * A decentralized identifier following the `did:oas:*` method or any other\n * DID method understood by the configured verifier.\n */\nexport type Did = string;\n\n/**\n * The four pieces of metadata an MCP request carries about the calling\n * agent. Populated by the {@link createClientInterceptor} on the call site\n * and consumed by the server middleware.\n */\nexport interface OpenAgentRequestIdentity {\n  /** Caller's DID — typically `did:oas:...`. */\n  did: Did;\n  /**\n   * A signed challenge response or capability token (Arsenal ACT) the\n   * server can verify offline. Format is opaque to the middleware.\n   */\n  proof: string;\n  /**\n   * Optional bearer-style nonce. Servers may require it for replay\n   * protection. Verifiers MUST treat the value as untrusted until\n   * verification succeeds.\n   */\n  nonce?: string;\n  /**\n   * Free-form context the verifier may use (issuer DID, audience, scopes\n   * the caller claims). Always validated against the verifier's policy.\n   */\n  context?: Record<string, unknown>;\n}\n\n/**\n * The result of running the auth pipeline against an incoming MCP request.\n * Available to post-call hooks and audit log emitters.\n */\nexport interface VerifiedIdentity {\n  did: Did;\n  scopes: ReadonlyArray<string>;\n  /** Audit identifier echoed back to the caller in result `_meta`. */\n  auditId: string;\n  /** Verifier-issued claims about the caller. */\n  claims: Readonly<Record<string, unknown>>;\n}\n\n/**\n * The verifier interface — implemented by `@openagentid/sdk` (production) and\n * by the in-memory test agent shipped here.\n *\n * Implementations MUST be deterministic for a given input and MUST NOT\n * mutate the request identity object.\n */\nexport interface IdentityVerifier {\n  verify(\n    identity: OpenAgentRequestIdentity,\n    requiredScopes: ReadonlyArray<string>,\n  ): Promise<VerifiedIdentity>;\n}\n\n/**\n * Minimal Agent surface — only the parts of the OpenAgent SDK Agent that\n * the MCP middleware actually needs.\n */\nexport interface Agent {\n  did: Did;\n  verifier: IdentityVerifier;\n  /**\n   * Sign an outbound MCP call so the receiving server can verify the\n   * caller. Returns the identity envelope to attach as `_meta.openagent`.\n   */\n  signRequest(\n    toolName: string,\n    audience?: Did,\n  ): Promise<OpenAgentRequestIdentity>;\n}\n\n/**\n * Result envelope returned by an authenticated tool call. The `auditId` is\n * pushed into `_meta.openagent.audit_id` on the response, so callers can\n * correlate logs end-to-end.\n */\nexport interface AuditedResultMeta {\n  audit_id: string;\n  verified_did: Did;\n  scopes: ReadonlyArray<string>;\n}\n\n/** Per-tool scope deriver. */\nexport type ScopeDeriver = (\n  toolName: string,\n  args: unknown,\n) => ReadonlyArray<string>;\n\n/**\n * Hook signature for the skills policy. The hook receives the tool name,\n * the arguments, and the verified identity, and decides whether the call\n * should be allowed.\n */\nexport type SkillsPolicyHook = (input: {\n  toolName: string;\n  args: unknown;\n  identity: VerifiedIdentity;\n}) => Promise<SkillsPolicyDecision> | SkillsPolicyDecision;\n\nexport interface SkillsPolicyDecision {\n  allow: boolean;\n  reason?: string;\n}\n\n/**\n * Hook fired before a tool body executes — after the identity has been\n * verified and the skills policy has approved the call.\n */\nexport type PreCallHook = (input: {\n  toolName: string;\n  args: unknown;\n  identity: VerifiedIdentity;\n}) => Promise<void> | void;\n\n/**\n * Hook fired after a tool body executes successfully. Use it for audit\n * logging, metrics, and trace propagation. Throwing from this hook does\n * NOT roll back the tool call.\n */\nexport type PostCallHook = (input: {\n  toolName: string;\n  args: unknown;\n  identity: VerifiedIdentity;\n  durationMs: number;\n  result: unknown;\n}) => Promise<void> | void;\n\n/**\n * Hook fired when the tool body or any earlier middleware step throws.\n * The middleware re-throws the error after running this hook so MCP\n * clients still observe the original failure mode.\n */\nexport type ErrorHook = (input: {\n  toolName: string;\n  args: unknown;\n  identity: VerifiedIdentity | null;\n  error: unknown;\n}) => Promise<void> | void;\n\n/**\n * Configuration for {@link withOpenAgent}.\n */\nexport interface OpenAgentMcpConfig {\n  /** The agent that owns this MCP server (used for outbound signing). */\n  agent: Agent;\n  /**\n   * Per-tool required scope set. Defaults to\n   * `(toolName) => [`mcp:${toolName}:invoke`]`.\n   */\n  requireScopes?: ScopeDeriver;\n  /**\n   * If true (default), tool calls without an `_meta.openagent.identity`\n   * envelope are rejected. Set to false to opt-in to permissive mode for\n   * local development — the middleware will still run hooks but skip\n   * verification.\n   */\n  requireIdentity?: boolean;\n  /** Optional skills policy hook. */\n  skillsPolicy?: SkillsPolicyHook;\n  /** Optional pre-call hook. */\n  preCall?: PreCallHook;\n  /** Optional post-call hook for audit/log emission. */\n  postCall?: PostCallHook;\n  /** Optional error hook. */\n  onError?: ErrorHook;\n  /**\n   * Override the default `mcp:<tool>:invoke` scope format. Receives the\n   * tool name and returns the canonical scope string.\n   */\n  scopeFormat?: (toolName: string) => string;\n}\n\n/**\n * Default scope format used when {@link OpenAgentMcpConfig.scopeFormat} is\n * not supplied.\n */\nexport const defaultScopeFormat = (toolName: string): string =>\n  `mcp:${toolName}:invoke`;\n\n/**\n * Default scope deriver used when {@link OpenAgentMcpConfig.requireScopes}\n * is not supplied.\n */\nexport const defaultRequireScopes = (toolName: string): ReadonlyArray<string> =>\n  [defaultScopeFormat(toolName)];\n"]}

package/dist/types.d.cts

@@ -0,0 +1,179 @@
+/**
+ * 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.
+ */
+type Did = 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.
+ */
+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>;
+}
+/**
+ * The result of running the auth pipeline against an incoming MCP request.
+ * Available to post-call hooks and audit log emitters.
+ */
+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>>;
+}
+/**
+ * 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.
+ */
+interface IdentityVerifier {
+    verify(identity: OpenAgentRequestIdentity, requiredScopes: ReadonlyArray<string>): Promise<VerifiedIdentity>;
+}
+/**
+ * Minimal Agent surface — only the parts of the OpenAgent SDK Agent that
+ * the MCP middleware actually needs.
+ */
+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.
+ */
+interface AuditedResultMeta {
+    audit_id: string;
+    verified_did: Did;
+    scopes: ReadonlyArray<string>;
+}
+/** Per-tool scope deriver. */
+type ScopeDeriver = (toolName: string, args: unknown) => ReadonlyArray<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.
+ */
+type SkillsPolicyHook = (input: {
+    toolName: string;
+    args: unknown;
+    identity: VerifiedIdentity;
+}) => Promise<SkillsPolicyDecision> | SkillsPolicyDecision;
+interface SkillsPolicyDecision {
+    allow: boolean;
+    reason?: string;
+}
+/**
+ * Hook fired before a tool body executes — after the identity has been
+ * verified and the skills policy has approved the call.
+ */
+type PreCallHook = (input: {
+    toolName: string;
+    args: unknown;
+    identity: VerifiedIdentity;
+}) => Promise<void> | void;
+/**
+ * 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.
+ */
+type PostCallHook = (input: {
+    toolName: string;
+    args: unknown;
+    identity: VerifiedIdentity;
+    durationMs: number;
+    result: unknown;
+}) => Promise<void> | void;
+/**
+ * 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.
+ */
+type ErrorHook = (input: {
+    toolName: string;
+    args: unknown;
+    identity: VerifiedIdentity | null;
+    error: unknown;
+}) => Promise<void> | void;
+/**
+ * Configuration for {@link withOpenAgent}.
+ */
+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;
+}
+/**
+ * Default scope format used when {@link OpenAgentMcpConfig.scopeFormat} is
+ * not supplied.
+ */
+declare const defaultScopeFormat: (toolName: string) => string;
+/**
+ * Default scope deriver used when {@link OpenAgentMcpConfig.requireScopes}
+ * is not supplied.
+ */
+declare const defaultRequireScopes: (toolName: string) => ReadonlyArray<string>;
+
+export { type Agent, type AuditedResultMeta, type Did, type ErrorHook, type IdentityVerifier, type OpenAgentMcpConfig, type OpenAgentRequestIdentity, type PostCallHook, type PreCallHook, type ScopeDeriver, type SkillsPolicyDecision, type SkillsPolicyHook, type VerifiedIdentity, defaultRequireScopes, defaultScopeFormat };

package/dist/types.d.ts

@@ -0,0 +1,179 @@
+/**
+ * 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.
+ */
+type Did = 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.
+ */
+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>;
+}
+/**
+ * The result of running the auth pipeline against an incoming MCP request.
+ * Available to post-call hooks and audit log emitters.
+ */
+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>>;
+}
+/**
+ * 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.
+ */
+interface IdentityVerifier {
+    verify(identity: OpenAgentRequestIdentity, requiredScopes: ReadonlyArray<string>): Promise<VerifiedIdentity>;
+}
+/**
+ * Minimal Agent surface — only the parts of the OpenAgent SDK Agent that
+ * the MCP middleware actually needs.
+ */
+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.
+ */
+interface AuditedResultMeta {
+    audit_id: string;
+    verified_did: Did;
+    scopes: ReadonlyArray<string>;
+}
+/** Per-tool scope deriver. */
+type ScopeDeriver = (toolName: string, args: unknown) => ReadonlyArray<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.
+ */
+type SkillsPolicyHook = (input: {
+    toolName: string;
+    args: unknown;
+    identity: VerifiedIdentity;
+}) => Promise<SkillsPolicyDecision> | SkillsPolicyDecision;
+interface SkillsPolicyDecision {
+    allow: boolean;
+    reason?: string;
+}
+/**
+ * Hook fired before a tool body executes — after the identity has been
+ * verified and the skills policy has approved the call.
+ */
+type PreCallHook = (input: {
+    toolName: string;
+    args: unknown;
+    identity: VerifiedIdentity;
+}) => Promise<void> | void;
+/**
+ * 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.
+ */
+type PostCallHook = (input: {
+    toolName: string;
+    args: unknown;
+    identity: VerifiedIdentity;
+    durationMs: number;
+    result: unknown;
+}) => Promise<void> | void;
+/**
+ * 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.
+ */
+type ErrorHook = (input: {
+    toolName: string;
+    args: unknown;
+    identity: VerifiedIdentity | null;
+    error: unknown;
+}) => Promise<void> | void;
+/**
+ * Configuration for {@link withOpenAgent}.
+ */
+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;
+}
+/**
+ * Default scope format used when {@link OpenAgentMcpConfig.scopeFormat} is
+ * not supplied.
+ */
+declare const defaultScopeFormat: (toolName: string) => string;
+/**
+ * Default scope deriver used when {@link OpenAgentMcpConfig.requireScopes}
+ * is not supplied.
+ */
+declare const defaultRequireScopes: (toolName: string) => ReadonlyArray<string>;
+
+export { type Agent, type AuditedResultMeta, type Did, type ErrorHook, type IdentityVerifier, type OpenAgentMcpConfig, type OpenAgentRequestIdentity, type PostCallHook, type PreCallHook, type ScopeDeriver, type SkillsPolicyDecision, type SkillsPolicyHook, type VerifiedIdentity, defaultRequireScopes, defaultScopeFormat };

package/dist/types.js

@@ -0,0 +1,7 @@
+// src/types.ts
+var defaultScopeFormat = (toolName) => `mcp:${toolName}:invoke`;
+var defaultRequireScopes = (toolName) => [defaultScopeFormat(toolName)];
+
+export { defaultRequireScopes, defaultScopeFormat };
+//# sourceMappingURL=types.js.map
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts"],"names":[],"mappings":";AAkMO,IAAM,kBAAA,GAAqB,CAAC,QAAA,KACjC,CAAA,IAAA,EAAO,QAAQ,CAAA,OAAA;AAMV,IAAM,uBAAuB,CAAC,QAAA,KACnC,CAAC,kBAAA,CAAmB,QAAQ,CAAC","file":"types.js","sourcesContent":["/**\n * Public types for @openagentid/mcp.\n *\n * These interfaces describe the contract the middleware expects from an\n * OpenAgent {@link Agent} instance and the surrounding configuration. They are\n * defined locally so the package can be installed without `@openagentid/sdk` in\n * tests, in CI, and in environments where the host application brings its own\n * verifier implementation.\n *\n * The real `@openagentid/sdk` exports types that are structurally compatible\n * with these — there is no runtime dependency.\n */\n\n/**\n * A decentralized identifier following the `did:oas:*` method or any other\n * DID method understood by the configured verifier.\n */\nexport type Did = string;\n\n/**\n * The four pieces of metadata an MCP request carries about the calling\n * agent. Populated by the {@link createClientInterceptor} on the call site\n * and consumed by the server middleware.\n */\nexport interface OpenAgentRequestIdentity {\n  /** Caller's DID — typically `did:oas:...`. */\n  did: Did;\n  /**\n   * A signed challenge response or capability token (Arsenal ACT) the\n   * server can verify offline. Format is opaque to the middleware.\n   */\n  proof: string;\n  /**\n   * Optional bearer-style nonce. Servers may require it for replay\n   * protection. Verifiers MUST treat the value as untrusted until\n   * verification succeeds.\n   */\n  nonce?: string;\n  /**\n   * Free-form context the verifier may use (issuer DID, audience, scopes\n   * the caller claims). Always validated against the verifier's policy.\n   */\n  context?: Record<string, unknown>;\n}\n\n/**\n * The result of running the auth pipeline against an incoming MCP request.\n * Available to post-call hooks and audit log emitters.\n */\nexport interface VerifiedIdentity {\n  did: Did;\n  scopes: ReadonlyArray<string>;\n  /** Audit identifier echoed back to the caller in result `_meta`. */\n  auditId: string;\n  /** Verifier-issued claims about the caller. */\n  claims: Readonly<Record<string, unknown>>;\n}\n\n/**\n * The verifier interface — implemented by `@openagentid/sdk` (production) and\n * by the in-memory test agent shipped here.\n *\n * Implementations MUST be deterministic for a given input and MUST NOT\n * mutate the request identity object.\n */\nexport interface IdentityVerifier {\n  verify(\n    identity: OpenAgentRequestIdentity,\n    requiredScopes: ReadonlyArray<string>,\n  ): Promise<VerifiedIdentity>;\n}\n\n/**\n * Minimal Agent surface — only the parts of the OpenAgent SDK Agent that\n * the MCP middleware actually needs.\n */\nexport interface Agent {\n  did: Did;\n  verifier: IdentityVerifier;\n  /**\n   * Sign an outbound MCP call so the receiving server can verify the\n   * caller. Returns the identity envelope to attach as `_meta.openagent`.\n   */\n  signRequest(\n    toolName: string,\n    audience?: Did,\n  ): Promise<OpenAgentRequestIdentity>;\n}\n\n/**\n * Result envelope returned by an authenticated tool call. The `auditId` is\n * pushed into `_meta.openagent.audit_id` on the response, so callers can\n * correlate logs end-to-end.\n */\nexport interface AuditedResultMeta {\n  audit_id: string;\n  verified_did: Did;\n  scopes: ReadonlyArray<string>;\n}\n\n/** Per-tool scope deriver. */\nexport type ScopeDeriver = (\n  toolName: string,\n  args: unknown,\n) => ReadonlyArray<string>;\n\n/**\n * Hook signature for the skills policy. The hook receives the tool name,\n * the arguments, and the verified identity, and decides whether the call\n * should be allowed.\n */\nexport type SkillsPolicyHook = (input: {\n  toolName: string;\n  args: unknown;\n  identity: VerifiedIdentity;\n}) => Promise<SkillsPolicyDecision> | SkillsPolicyDecision;\n\nexport interface SkillsPolicyDecision {\n  allow: boolean;\n  reason?: string;\n}\n\n/**\n * Hook fired before a tool body executes — after the identity has been\n * verified and the skills policy has approved the call.\n */\nexport type PreCallHook = (input: {\n  toolName: string;\n  args: unknown;\n  identity: VerifiedIdentity;\n}) => Promise<void> | void;\n\n/**\n * Hook fired after a tool body executes successfully. Use it for audit\n * logging, metrics, and trace propagation. Throwing from this hook does\n * NOT roll back the tool call.\n */\nexport type PostCallHook = (input: {\n  toolName: string;\n  args: unknown;\n  identity: VerifiedIdentity;\n  durationMs: number;\n  result: unknown;\n}) => Promise<void> | void;\n\n/**\n * Hook fired when the tool body or any earlier middleware step throws.\n * The middleware re-throws the error after running this hook so MCP\n * clients still observe the original failure mode.\n */\nexport type ErrorHook = (input: {\n  toolName: string;\n  args: unknown;\n  identity: VerifiedIdentity | null;\n  error: unknown;\n}) => Promise<void> | void;\n\n/**\n * Configuration for {@link withOpenAgent}.\n */\nexport interface OpenAgentMcpConfig {\n  /** The agent that owns this MCP server (used for outbound signing). */\n  agent: Agent;\n  /**\n   * Per-tool required scope set. Defaults to\n   * `(toolName) => [`mcp:${toolName}:invoke`]`.\n   */\n  requireScopes?: ScopeDeriver;\n  /**\n   * If true (default), tool calls without an `_meta.openagent.identity`\n   * envelope are rejected. Set to false to opt-in to permissive mode for\n   * local development — the middleware will still run hooks but skip\n   * verification.\n   */\n  requireIdentity?: boolean;\n  /** Optional skills policy hook. */\n  skillsPolicy?: SkillsPolicyHook;\n  /** Optional pre-call hook. */\n  preCall?: PreCallHook;\n  /** Optional post-call hook for audit/log emission. */\n  postCall?: PostCallHook;\n  /** Optional error hook. */\n  onError?: ErrorHook;\n  /**\n   * Override the default `mcp:<tool>:invoke` scope format. Receives the\n   * tool name and returns the canonical scope string.\n   */\n  scopeFormat?: (toolName: string) => string;\n}\n\n/**\n * Default scope format used when {@link OpenAgentMcpConfig.scopeFormat} is\n * not supplied.\n */\nexport const defaultScopeFormat = (toolName: string): string =>\n  `mcp:${toolName}:invoke`;\n\n/**\n * Default scope deriver used when {@link OpenAgentMcpConfig.requireScopes}\n * is not supplied.\n */\nexport const defaultRequireScopes = (toolName: string): ReadonlyArray<string> =>\n  [defaultScopeFormat(toolName)];\n"]}