@openagentid/mcp 0.1.0 → 0.2.0

package/dist/types.d.ts

@@ -7,8 +7,8 @@
  * 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.
+ * Use the workspace adapters for the current SDK. These interfaces also
+ * support applications that supply their own signing and verification authority.
  */
 /**
  * A decentralized identifier following the `did:oas:*` method or any other
@@ -53,14 +53,19 @@ interface VerifiedIdentity {
     claims: Readonly<Record<string, unknown>>;
 }
 /**
- * The verifier interface — implemented by `@openagentid/sdk` (production) and
- * by the in-memory test agent shipped here.
+ * Verifier adapter contract — supplied by createWorkspaceMcpServer or an
+ * application-owned identity authority.
  *
  * 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>;
+    verify(identity: OpenAgentRequestIdentity, requiredScopes: ReadonlyArray<string>, 
+    /** Original wire arguments before tool schema defaults/transforms; scopes are derived from parsed arguments. */
+    request?: {
+        toolName: string;
+        args: unknown;
+    }): Promise<VerifiedIdentity>;
 }
 /**
  * Minimal Agent surface — only the parts of the OpenAgent SDK Agent that
@@ -73,7 +78,7 @@ interface Agent {
      * 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>;
+    signRequest(toolName: string, audience?: Did, args?: Record<string, unknown>): Promise<OpenAgentRequestIdentity>;
 }
 /**
  * Result envelope returned by an authenticated tool call. The `auditId` is
@@ -138,7 +143,7 @@ type ErrorHook = (input: {
  */
 interface OpenAgentMcpConfig {
     /** The agent that owns this MCP server (used for outbound signing). */
-    agent: Agent;
+    agent: Pick<Agent, 'did' | 'verifier'>;
     /**
      * Per-tool required scope set. Defaults to
      * `(toolName) => [`mcp:${toolName}:invoke`]`.

package/dist/types.js.map

@@ -1 +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"]}
+{"version":3,"sources":["../src/types.ts"],"names":[],"mappings":";AAqMO,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 * Use the workspace adapters for the current SDK. These interfaces also\n * support applications that supply their own signing and verification authority.\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 * Verifier adapter contract — supplied by createWorkspaceMcpServer or an\n * application-owned identity authority.\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    /** Original wire arguments before tool schema defaults/transforms; scopes are derived from parsed arguments. */\n    request?: { toolName: string; args: unknown },\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    args?: Record<string, unknown>,\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: Pick<Agent, 'did' | 'verifier'>;\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/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@openagentid/mcp",
-  "version": "0.1.0",
-  "description": "OpenAgent middleware for the Model Context Protocol — adds OAS identity, Arsenal capability tokens, and AEGIS authorization to any MCP server in three lines.",
+  "version": "0.2.0",
+  "description": "OpenAgent middleware for the Model Context Protocol \u2014 adds OAS identity, Arsenal capability tokens, and AEGIS authorization to any MCP server in three lines.",
   "license": "Apache-2.0 OR MIT",
-  "author": "L1fe AI <eng@l1fe.ai>",
+  "author": "L1fe Labs, Inc. <eng@l1fe.ai>",
   "homepage": "https://openagent.id/docs/integrations/mcp",
   "repository": {
     "type": "git",
@@ -72,19 +72,22 @@
   },
   "peerDependencies": {
     "@modelcontextprotocol/sdk": "^1.27.0",
-    "@openagentid/sdk": "^0.1.0"
+    "@openagentid/sdk": "^0.7.2"
   },
   "peerDependenciesMeta": {
-    "@openagentid/sdk": { "optional": true }
+    "@openagentid/sdk": {
+      "optional": true
+    }
   },
   "devDependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",
     "@types/node": "^20.11.30",
-    "@vitest/coverage-v8": "^1.6.0",
+    "@vitest/coverage-v8": "^3.2.6",
     "tsup": "^8.0.2",
     "typescript": "^5.4.5",
-    "vitest": "^1.6.0",
-    "zod": "^3.23.8"
+    "vitest": "^3.2.6",
+    "zod": "^3.23.8",
+    "@openagentid/sdk": "0.7.2"
   },
   "keywords": [
     "openagent",