@signet-auth/mcp-server 0.3.0

package/dist/src/index.d.ts

@@ -0,0 +1 @@
+export { verifyRequest, type VerifyOptions, type VerifyResult } from './verify-request.js';

package/dist/src/index.js

@@ -0,0 +1 @@
+export { verifyRequest } from './verify-request.js';

package/dist/src/verify-request.d.ts

@@ -0,0 +1,20 @@
+export interface VerifyOptions {
+    /** List of trusted "ed25519:<base64>" pubkeys.
+     *  If omitted and requireSignature=true, ALL signed requests are rejected. */
+    trustedKeys?: string[];
+    /** Reject unsigned requests. Default: true. */
+    requireSignature?: boolean;
+    /** Max age of receipt in seconds. Default: 300 (5 min). */
+    maxAge?: number;
+    /** If set, receipt.action.target must match this value. */
+    expectedTarget?: string;
+}
+export interface VerifyResult {
+    ok: boolean;
+    signerName?: string;
+    signerPubkey?: string;
+    error?: string;
+}
+export declare function verifyRequest(request: {
+    params?: Record<string, unknown>;
+}, options: VerifyOptions): VerifyResult;

package/dist/src/verify-request.js

@@ -0,0 +1,84 @@
+import { verify } from '@signet-auth/core';
+const CLOCK_SKEW_TOLERANCE_MS = 30_000; // 30 seconds
+export function verifyRequest(request, options) {
+    const requireSig = options.requireSignature ?? true;
+    const maxAgeMs = (options.maxAge ?? 300) * 1000;
+    // 1. Extract _meta._signet
+    const meta = request.params?._meta;
+    const signet = meta?._signet;
+    // 2. Check presence
+    if (!signet) {
+        if (requireSig) {
+            return { ok: false, error: 'unsigned request' };
+        }
+        return { ok: true };
+    }
+    // 3. Validate receipt shape
+    const s = signet;
+    if (!s['v'] || !s['sig'] || !s['action'] || !s['signer'] || !s['ts']) {
+        return { ok: false, error: 'malformed receipt' };
+    }
+    const receipt = signet;
+    // 4. Verify signature
+    // receipt.signer.pubkey has "ed25519:" prefix; verify() takes bare base64
+    const prefixedPubkey = receipt.signer.pubkey;
+    const barePubkey = prefixedPubkey.startsWith('ed25519:')
+        ? prefixedPubkey.slice('ed25519:'.length)
+        : prefixedPubkey;
+    try {
+        const valid = verify(receipt, barePubkey);
+        if (!valid) {
+            return { ok: false, error: 'invalid signature' };
+        }
+    }
+    catch {
+        return { ok: false, error: 'invalid signature' };
+    }
+    // 5. Check trusted keys (using prefixed format to match receipt.signer.pubkey)
+    const trustedKeys = options.trustedKeys ?? [];
+    if (!trustedKeys.includes(prefixedPubkey)) {
+        return { ok: false, error: `untrusted signer: ${prefixedPubkey}` };
+    }
+    // 6. Check freshness (ts is guaranteed by shape check above)
+    const receiptTime = new Date(receipt.ts).getTime();
+    const now = Date.now();
+    if (isNaN(receiptTime)) {
+        return { ok: false, error: 'invalid receipt timestamp' };
+    }
+    if (receiptTime < now - maxAgeMs) {
+        return { ok: false, error: 'receipt too old' };
+    }
+    if (receiptTime > now + CLOCK_SKEW_TOLERANCE_MS) {
+        return { ok: false, error: 'receipt from future' };
+    }
+    // 7. Check target
+    if (options.expectedTarget && receipt.action.target !== options.expectedTarget) {
+        return {
+            ok: false,
+            error: `target mismatch: expected ${options.expectedTarget}, got ${receipt.action.target}`,
+        };
+    }
+    // 8. Anti-staple: receipt.action.tool must match request.params.name
+    const requestTool = request.params?.['name'];
+    if (requestTool !== undefined && receipt.action.tool !== requestTool) {
+        return {
+            ok: false,
+            error: `tool mismatch: receipt signed for "${receipt.action.tool}", request is for "${requestTool}"`,
+        };
+    }
+    // 9. Anti-staple: receipt.action.params must match request.params.arguments
+    const requestArgs = request.params?.['arguments'];
+    if (requestArgs !== undefined || receipt.action.params !== undefined) {
+        const signedParams = JSON.stringify(receipt.action.params ?? null);
+        const actualParams = JSON.stringify(requestArgs ?? null);
+        if (signedParams !== actualParams) {
+            return { ok: false, error: 'params mismatch: signed params differ from request arguments' };
+        }
+    }
+    // All checks pass
+    return {
+        ok: true,
+        signerName: receipt.signer.name,
+        signerPubkey: receipt.signer.pubkey,
+    };
+}

package/dist/tests/server.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/tests/server.test.js

@@ -0,0 +1,179 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { generateKeypair, sign } from '@signet-auth/core';
+import { verifyRequest } from '../src/index.js';
+describe('@signet-auth/mcp-server verifyRequest', () => {
+    const kp = generateKeypair();
+    const kp2 = generateKeypair();
+    function makeAction(tool, args) {
+        return {
+            tool,
+            params: args,
+            params_hash: '',
+            target: 'mcp://test-server',
+            transport: 'stdio',
+        };
+    }
+    function signedRequest(tool, args) {
+        const action = makeAction(tool, args);
+        const receipt = sign(kp.secretKey, action, 'test-agent', 'owner');
+        return {
+            params: {
+                name: tool,
+                arguments: args,
+                _meta: { _signet: receipt },
+            },
+        };
+    }
+    // Use prefixed format (matching receipt.signer.pubkey) for trustedKeys
+    function trustedKey(receipt) {
+        return receipt.signer.pubkey;
+    }
+    it('test_verify_valid_signature — trusted key, valid sig → ok: true', () => {
+        const req = signedRequest('echo', { message: 'hello' });
+        const receipt = (req.params._meta._signet);
+        const result = verifyRequest(req, { trustedKeys: [trustedKey(receipt)] });
+        assert.strictEqual(result.ok, true, `Expected ok: true, got error: ${result.error}`);
+    });
+    it('test_verify_untrusted_key — valid sig but key not in trustedKeys → ok: false', () => {
+        const req = signedRequest('echo', { message: 'hello' });
+        // Use kp2 pubkey (prefixed) as trusted — won't match kp's pubkey
+        const fakeReceipt = sign(kp2.secretKey, makeAction('echo', {}), 'other', 'owner');
+        const result = verifyRequest(req, { trustedKeys: [trustedKey(fakeReceipt)] });
+        assert.strictEqual(result.ok, false);
+        assert(result.error?.includes('untrusted'), `Expected 'untrusted' in error, got: ${result.error}`);
+    });
+    it('test_verify_invalid_signature — tampered _signet.sig → ok: false', () => {
+        const req = signedRequest('echo', { message: 'hello' });
+        const receipt = req.params._meta._signet;
+        // Tamper with the signature
+        const tamperedReceipt = { ...receipt, sig: 'ed25519:AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=' };
+        const tamperedReq = {
+            params: {
+                ...req.params,
+                _meta: { _signet: tamperedReceipt },
+            },
+        };
+        const result = verifyRequest(tamperedReq, { trustedKeys: [receipt.signer.pubkey] });
+        assert.strictEqual(result.ok, false);
+        assert(result.error?.includes('invalid signature'), `Expected 'invalid signature', got: ${result.error}`);
+    });
+    it('test_verify_unsigned_required — no _signet + requireSignature=true → ok: false', () => {
+        const req = { params: { name: 'echo', arguments: { message: 'hello' } } };
+        const result = verifyRequest(req, { requireSignature: true, trustedKeys: [] });
+        assert.strictEqual(result.ok, false);
+        assert(result.error?.includes('unsigned'), `Expected 'unsigned' in error, got: ${result.error}`);
+    });
+    it('test_verify_unsigned_optional — no _signet + requireSignature=false → ok: true', () => {
+        const req = { params: { name: 'echo', arguments: { message: 'hello' } } };
+        const result = verifyRequest(req, { requireSignature: false, trustedKeys: [] });
+        assert.strictEqual(result.ok, true);
+    });
+    it('test_verify_returns_signer_info — ok: true has signerName + signerPubkey', () => {
+        const req = signedRequest('echo', { message: 'hello' });
+        const receipt = req.params._meta._signet;
+        const result = verifyRequest(req, { trustedKeys: [trustedKey(receipt)] });
+        assert.strictEqual(result.ok, true);
+        assert.strictEqual(result.signerName, 'test-agent');
+        assert(result.signerPubkey?.startsWith('ed25519:'), `Expected prefixed pubkey, got: ${result.signerPubkey}`);
+    });
+    it('test_verify_expired_receipt — maxAge=0 causes "receipt too old"', async () => {
+        const req = signedRequest('echo', { message: 'hello' });
+        const receipt = req.params._meta._signet;
+        // Use maxAge=0 so any receipt is immediately expired (0 seconds allowed)
+        // Wait a tiny bit to ensure time has passed
+        await new Promise((resolve) => setTimeout(resolve, 5));
+        const result = verifyRequest(req, { trustedKeys: [trustedKey(receipt)], maxAge: 0 });
+        assert.strictEqual(result.ok, false);
+        assert(result.error?.includes('receipt too old'), `Expected 'receipt too old', got: ${result.error}`);
+    });
+    it('test_verify_target_mismatch — expectedTarget differs → ok: false', () => {
+        const req = signedRequest('echo', { message: 'hello' });
+        const receipt = req.params._meta._signet;
+        const result = verifyRequest(req, {
+            trustedKeys: [trustedKey(receipt)],
+            expectedTarget: 'mcp://different-server',
+        });
+        assert.strictEqual(result.ok, false);
+        assert(result.error?.includes('target mismatch'), `Expected 'target mismatch', got: ${result.error}`);
+    });
+    it('test_verify_malformed_signet — _signet is garbage → ok: false, "malformed"', () => {
+        const req = {
+            params: {
+                name: 'echo',
+                arguments: { message: 'hello' },
+                _meta: { _signet: { garbage: true, random: 'data' } },
+            },
+        };
+        const result = verifyRequest(req, { trustedKeys: [] });
+        assert.strictEqual(result.ok, false);
+        assert(result.error?.includes('malformed'), `Expected 'malformed' in error, got: ${result.error}`);
+    });
+    it('test_verify_tool_mismatch — receipt for "echo" on request for "delete" → ok: false', () => {
+        // Sign for "echo" but attach to a "delete" request
+        const action = makeAction('echo', { message: 'hello' });
+        const receipt = sign(kp.secretKey, action, 'test-agent', 'owner');
+        const req = {
+            params: {
+                name: 'delete', // different tool
+                arguments: { message: 'hello' },
+                _meta: { _signet: receipt },
+            },
+        };
+        const result = verifyRequest(req, { trustedKeys: [receipt.signer.pubkey] });
+        assert.strictEqual(result.ok, false);
+        assert(result.error?.includes('tool mismatch'), `Expected 'tool mismatch', got: ${result.error}`);
+    });
+    it('test_verify_params_mismatch — receipt with {a:1} but request has {a:2} → ok: false', () => {
+        // Sign for {a: 1} but attach to request with {a: 2}
+        const action = makeAction('echo', { a: 1 });
+        const receipt = sign(kp.secretKey, action, 'test-agent', 'owner');
+        const req = {
+            params: {
+                name: 'echo',
+                arguments: { a: 2 }, // different args
+                _meta: { _signet: receipt },
+            },
+        };
+        const result = verifyRequest(req, { trustedKeys: [receipt.signer.pubkey] });
+        assert.strictEqual(result.ok, false);
+        assert(result.error?.includes('params mismatch'), `Expected 'params mismatch', got: ${result.error}`);
+    });
+    it('test_verify_no_request_args — receipt signed with params, request has no arguments key → params mismatch', () => {
+        // Sign with params {x: 1} but request omits the arguments key entirely
+        const action = makeAction('echo', { x: 1 });
+        const receipt = sign(kp.secretKey, action, 'test-agent', 'owner');
+        const req = {
+            params: {
+                name: 'echo',
+                // no 'arguments' key — requestArgs will be undefined
+                _meta: { _signet: receipt },
+            },
+        };
+        const result = verifyRequest(req, { trustedKeys: [receipt.signer.pubkey] });
+        // receipt.action.params is {x:1}, requestArgs is undefined → mismatch
+        assert.strictEqual(result.ok, false);
+        assert(result.error?.includes('params mismatch'), `Expected 'params mismatch', got: ${result.error}`);
+    });
+    it('test_verify_malformed_no_ts — _signet missing ts field → ok: false, "malformed"', () => {
+        // Construct a receipt-like object without ts to exercise the shape check for ts
+        const req = {
+            params: {
+                name: 'echo',
+                arguments: { message: 'hello' },
+                _meta: {
+                    _signet: {
+                        v: 1,
+                        sig: 'ed25519:AAAA',
+                        action: { tool: 'echo', params: {}, params_hash: '', target: '', transport: 'stdio' },
+                        signer: { name: 'agent', pubkey: 'ed25519:AAAA', owner: '' },
+                        // ts intentionally omitted
+                    },
+                },
+            },
+        };
+        const result = verifyRequest(req, { trustedKeys: [] });
+        assert.strictEqual(result.ok, false);
+        assert(result.error?.includes('malformed'), `Expected 'malformed' in error, got: ${result.error}`);
+    });
+});

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@signet-auth/mcp-server",
+  "version": "0.3.0",
+  "description": "Server-side verification for Signet cryptographic action receipts",
+  "type": "module",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "files": ["dist/"],
+  "scripts": {
+    "build": "npx tsc",
+    "test": "npx tsc && node --test dist/tests/server.test.js"
+  },
+  "dependencies": {
+    "@signet-auth/core": "file:../signet-core"
+  },
+  "devDependencies": {
+    "@types/node": "^22",
+    "typescript": "^5"
+  },
+  "license": "Apache-2.0 OR MIT"
+}