piree-merchant-middleware 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { pireeAgentVerifier } from './middleware.js';
+export type { VerifierOptions } from './middleware.js';
+export type { AgentRegistryEntry } from './registry.js';

package/dist/index.js

@@ -0,0 +1 @@
+export { pireeAgentVerifier } from './middleware.js';

package/dist/middleware.d.ts

@@ -0,0 +1,15 @@
+import { Request, Response, NextFunction } from 'express';
+import fetch from 'node-fetch';
+import { AgentRegistryEntry } from './registry.js';
+type FetchFn = typeof fetch;
+export interface VerifierOptions {
+    registryUrl: string;
+    header?: string;
+    refreshIntervalMs?: number;
+    onUnknownAgent?: 'reject' | 'allow' | 'log';
+    _fetchFn?: FetchFn;
+}
+export declare function pireeAgentVerifier(options: VerifierOptions): (req: Request & {
+    pireeAgent?: AgentRegistryEntry | null;
+}, res: Response, next: NextFunction) => void;
+export {};

package/dist/middleware.js

@@ -0,0 +1,40 @@
+import fetch from 'node-fetch';
+import { fetchFullRegistry } from './registry.js';
+export function pireeAgentVerifier(options) {
+    const { registryUrl, header = 'Piree-Agent-Id', refreshIntervalMs = 5 * 60 * 1000, onUnknownAgent = 'reject', _fetchFn = fetch, } = options;
+    let registry = new Map();
+    const headerLower = header.toLowerCase();
+    async function refresh() {
+        try {
+            registry = await fetchFullRegistry(registryUrl, _fetchFn);
+        }
+        catch (err) {
+            console.error('[piree-middleware] Registry refresh failed:', err.message);
+        }
+    }
+    refresh().then(() => {
+        setInterval(refresh, refreshIntervalMs).unref();
+    }).catch(err => {
+        console.error('[piree-middleware] Initial registry fetch failed:', err.message);
+    });
+    return function middleware(req, res, next) {
+        const agentId = req.headers[headerLower];
+        if (!agentId) {
+            return next();
+        }
+        const agent = registry.get(agentId);
+        if (agent) {
+            req.pireeAgent = agent;
+            return next();
+        }
+        if (onUnknownAgent === 'reject') {
+            res.status(401).json({ error: 'agent_not_trusted' });
+            return;
+        }
+        if (onUnknownAgent === 'log') {
+            console.warn(`[piree-middleware] Unverified agent: ${agentId}`);
+        }
+        req.pireeAgent = null;
+        return next();
+    };
+}

package/dist/registry.d.ts

@@ -0,0 +1,17 @@
+import fetch from 'node-fetch';
+import type { RequestInfo, RequestInit } from 'node-fetch';
+export interface AgentRegistryEntry {
+    credential_id: string;
+    agent_name: string;
+    org_did: string;
+    purpose: string;
+    scope_summary: {
+        categories: string[];
+        spend_limit_monthly: number;
+    };
+    agent_card_url: string;
+    valid_until: string;
+}
+type FetchFn = (url: RequestInfo, init?: RequestInit) => ReturnType<typeof fetch>;
+export declare function fetchFullRegistry(baseUrl: string, fetchFn?: FetchFn): Promise<Map<string, AgentRegistryEntry>>;
+export {};

package/dist/registry.js

@@ -0,0 +1,21 @@
+import fetch from 'node-fetch';
+export async function fetchFullRegistry(baseUrl, fetchFn = fetch) {
+    const registry = new Map();
+    let cursor = null;
+    do {
+        const url = new URL(`${baseUrl}/registry/v1/trusted-agents`);
+        if (cursor)
+            url.searchParams.set('cursor', cursor);
+        url.searchParams.set('limit', '100');
+        const resp = await fetchFn(url.toString());
+        if (!resp.ok) {
+            throw new Error(`Registry fetch failed with status ${resp.status}`);
+        }
+        const data = await resp.json();
+        for (const agent of data.agents) {
+            registry.set(agent.credential_id, agent);
+        }
+        cursor = data.next_cursor;
+    } while (cursor);
+    return registry;
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "piree-merchant-middleware",
+  "version": "1.0.0",
+  "description": "Express middleware that verifies Piree agent credentials against the public trusted-agents registry",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "cross-env NODE_OPTIONS=--experimental-vm-modules jest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "piree",
+    "agent",
+    "middleware",
+    "express",
+    "trust"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "node-fetch": "^3.3.2"
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.0",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^20.0.0",
+    "@types/supertest": "^7.2.0",
+    "cross-env": "^10.1.0",
+    "express": "^5.0.0",
+    "jest": "^30.4.0",
+    "supertest": "^7.2.2",
+    "ts-jest": "^29.4.11",
+    "typescript": "^5.4.0"
+  },
+  "jest": {
+    "preset": "ts-jest/presets/default-esm",
+    "testEnvironment": "node",
+    "extensionsToTreatAsEsm": [
+      ".ts"
+    ],
+    "moduleNameMapper": {
+      "^(\\.{1,2}/.*)\\.js$": "$1"
+    }
+  }
+}

package/src/__tests__/middleware.test.ts

@@ -0,0 +1,104 @@
+import { jest, describe, it, expect, beforeEach, afterEach } from '@jest/globals'
+import express, { Response } from 'express'
+import supertest from 'supertest'
+import { pireeAgentVerifier } from '../middleware.js'
+
+describe('pireeAgentVerifier middleware', () => {
+  function makeRegistryPage(agents: object[], nextCursor: string | null = null) {
+    const mockFetch = jest.fn<any>().mockResolvedValue({
+      ok: true,
+      json: jest.fn<any>().mockResolvedValue({
+        registry: 'piree.ai',
+        total: agents.length,
+        agents,
+        next_cursor: nextCursor,
+      }),
+    })
+    return mockFetch
+  }
+
+  function makeAgent(credentialId: string, agentName = 'test-agent') {
+    return {
+      credential_id: credentialId,
+      agent_name: agentName,
+      org_did: 'did:web:test.com',
+      purpose: 'autonomous-commerce-agent',
+      scope_summary: { categories: ['grocery'], spend_limit_monthly: 500000 },
+      agent_card_url: `https://api.piree.ai/api/v1/credentials/${credentialId}/agent-card`,
+      valid_until: '2027-06-07T00:00:00Z',
+    }
+  }
+
+  function buildApp(mockFetch: jest.Mock<any>, options: object) {
+    const app = express()
+    app.use(pireeAgentVerifier({ registryUrl: 'https://api.piree.ai', _fetchFn: mockFetch as any, ...options }))
+    app.get('/test', (req: any, res: Response) =>
+      res.json({ agent: req.pireeAgent?.agent_name ?? null })
+    )
+    return app
+  }
+
+  it('passes request and populates req.pireeAgent for known agent', async () => {
+    const CRED_ID = 'cred-123'
+    const mockFetch = makeRegistryPage([makeAgent(CRED_ID)])
+    const app = buildApp(mockFetch, { header: 'Piree-Agent-Id' })
+    await new Promise(resolve => setTimeout(resolve, 50))
+
+    const res = await supertest(app)
+      .get('/test')
+      .set('Piree-Agent-Id', CRED_ID)
+
+    expect(res.status).toBe(200)
+    expect(res.body.agent).toBe('test-agent')
+  })
+
+  it('returns 401 for unknown agent when onUnknownAgent=reject', async () => {
+    const mockFetch = makeRegistryPage([])
+    const app = buildApp(mockFetch, { onUnknownAgent: 'reject' })
+    await new Promise(resolve => setTimeout(resolve, 50))
+
+    const res = await supertest(app)
+      .get('/test')
+      .set('Piree-Agent-Id', 'unknown-cred-id')
+
+    expect(res.status).toBe(401)
+    expect(res.body.error).toBe('agent_not_trusted')
+  })
+
+  it('passes request with pireeAgent=null when onUnknownAgent=allow', async () => {
+    const mockFetch = makeRegistryPage([])
+    const app = buildApp(mockFetch, { onUnknownAgent: 'allow' })
+    await new Promise(resolve => setTimeout(resolve, 50))
+
+    const res = await supertest(app)
+      .get('/test')
+      .set('Piree-Agent-Id', 'unknown-cred')
+
+    expect(res.status).toBe(200)
+    expect(res.body.agent).toBeNull()
+  })
+
+  it('passes request normally when no Piree-Agent-Id header present', async () => {
+    const mockFetch = makeRegistryPage([])
+    const app = buildApp(mockFetch, {})
+    await new Promise(resolve => setTimeout(resolve, 50))
+
+    const res = await supertest(app).get('/test')
+    expect(res.status).toBe(200)
+  })
+
+  it('fails open when initial registry fetch fails', async () => {
+    const warnSpy = jest.spyOn(console, 'error').mockImplementation(() => {})
+    const mockFetch = jest.fn<any>().mockRejectedValue(new Error('Network error'))
+    const app = buildApp(mockFetch, { onUnknownAgent: 'reject' })
+    await new Promise(resolve => setTimeout(resolve, 50))
+
+    const res = await supertest(app)
+      .get('/test')
+      .set('Piree-Agent-Id', 'any-cred')
+
+    // Registry failed to load → empty registry → unknown agent → 401 (onUnknownAgent=reject)
+    expect(res.status).toBe(401)
+    warnSpy.mockRestore()
+  })
+})

package/src/index.ts

@@ -0,0 +1,3 @@
+export { pireeAgentVerifier } from './middleware.js'
+export type { VerifierOptions } from './middleware.js'
+export type { AgentRegistryEntry } from './registry.js'

package/src/middleware.ts

@@ -0,0 +1,71 @@
+import { Request, Response, NextFunction } from 'express'
+import fetch from 'node-fetch'
+import { fetchFullRegistry, AgentRegistryEntry } from './registry.js'
+
+type FetchFn = typeof fetch
+
+export interface VerifierOptions {
+  registryUrl: string
+  header?: string
+  refreshIntervalMs?: number
+  onUnknownAgent?: 'reject' | 'allow' | 'log'
+  _fetchFn?: FetchFn  // DI for testing — do not use in production
+}
+
+export function pireeAgentVerifier(options: VerifierOptions) {
+  const {
+    registryUrl,
+    header = 'Piree-Agent-Id',
+    refreshIntervalMs = 5 * 60 * 1000,
+    onUnknownAgent = 'reject',
+    _fetchFn = fetch,
+  } = options
+
+  let registry = new Map<string, AgentRegistryEntry>()
+  const headerLower = header.toLowerCase()
+
+  async function refresh(): Promise<void> {
+    try {
+      registry = await fetchFullRegistry(registryUrl, _fetchFn)
+    } catch (err) {
+      console.error('[piree-middleware] Registry refresh failed:', (err as Error).message)
+    }
+  }
+
+  refresh().then(() => {
+    setInterval(refresh, refreshIntervalMs).unref()
+  }).catch(err => {
+    console.error('[piree-middleware] Initial registry fetch failed:', (err as Error).message)
+  })
+
+  return function middleware(
+    req: Request & { pireeAgent?: AgentRegistryEntry | null },
+    res: Response,
+    next: NextFunction
+  ): void {
+    const agentId = req.headers[headerLower] as string | undefined
+
+    if (!agentId) {
+      return next()
+    }
+
+    const agent = registry.get(agentId)
+
+    if (agent) {
+      req.pireeAgent = agent
+      return next()
+    }
+
+    if (onUnknownAgent === 'reject') {
+      res.status(401).json({ error: 'agent_not_trusted' })
+      return
+    }
+
+    if (onUnknownAgent === 'log') {
+      console.warn(`[piree-middleware] Unverified agent: ${agentId}`)
+    }
+
+    req.pireeAgent = null
+    return next()
+  }
+}

package/src/registry.ts

@@ -0,0 +1,44 @@
+import fetch from 'node-fetch'
+import type { RequestInfo, RequestInit } from 'node-fetch'
+
+export interface AgentRegistryEntry {
+  credential_id: string
+  agent_name: string
+  org_did: string
+  purpose: string
+  scope_summary: { categories: string[]; spend_limit_monthly: number }
+  agent_card_url: string
+  valid_until: string
+}
+
+type FetchFn = (url: RequestInfo, init?: RequestInit) => ReturnType<typeof fetch>
+
+export async function fetchFullRegistry(
+  baseUrl: string,
+  fetchFn: FetchFn = fetch
+): Promise<Map<string, AgentRegistryEntry>> {
+  const registry = new Map<string, AgentRegistryEntry>()
+  let cursor: string | null = null
+
+  do {
+    const url = new URL(`${baseUrl}/registry/v1/trusted-agents`)
+    if (cursor) url.searchParams.set('cursor', cursor)
+    url.searchParams.set('limit', '100')
+
+    const resp = await fetchFn(url.toString())
+    if (!resp.ok) {
+      throw new Error(`Registry fetch failed with status ${resp.status}`)
+    }
+    const data = await resp.json() as {
+      agents: AgentRegistryEntry[]
+      next_cursor: string | null
+    }
+
+    for (const agent of data.agents) {
+      registry.set(agent.credential_id, agent)
+    }
+    cursor = data.next_cursor
+  } while (cursor)
+
+  return registry
+}

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist",
+    "declaration": true,
+    "strict": true,
+    "isolatedModules": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["src/**/__tests__/**"]
+}