@gera-services/mcp-gera-verify 1.0.0 → 1.2.0

package/README.md

@@ -39,6 +39,10 @@ with **no backend, no network, no auth**.
 | `get_trust_summary` | Aggregates the above into a short, **citation-ready sentence** (plus structured signals) for an agent to quote a grounded "what we can verify about X" answer. |
 | `issue_attestation` | **Gera Vouch.** Runs the same real verification and returns a **cryptographically signed (Ed25519) attestation receipt** an agent can present to a counterparty (who verifies it with the public key). Verdict is `pass` (a strong, source-attributed verifying signal exists) or `unverified` (not in our records — never a guess). A signed *proof-of-diligence receipt*; indemnity/underwriting is roadmap and is never implied. |
 | `get_vouch_public_key` | Returns the Ed25519 public key + `key_id` + verification recipe so **any party can independently verify** an `issue_attestation` receipt without trusting the transport. |
+| `issue_mandate` | **Gera Agent Mandate.** A human/business grants an agent a scoped, revocable, **Ed25519-signed spend mandate** (cap, currency, merchant allowlist, categories, expiry). Pure authorization — no money moves. |
+| `verify_mandate` | Verify a mandate before honouring an action: checks signature, expiry, spend cap, and merchant/category scope against the intended action. **Fails closed** — forged/expired/over-cap/out-of-scope all return `valid:false` with reasons. |
+| `issue_receipt` | **Gera Ledger.** After an agent acts, mint a **signed receipt** of what happened — optionally linking the Vouch attestation + Agent Mandate it acted under. A verifiable proof-of-action (not a settlement). |
+| `verify_receipt` | Verify a receipt's Ed25519 signature against the Gera issuer key — confirms Gera recorded the action, unaltered. Fails closed. |
 
 A typical agent flow: `check_business_trust` (or `get_trust_summary`) → drill
 into `lookup_food_hygiene` / `lookup_care_rating` / `verify_provider` for the

package/dist/mandate.d.ts

@@ -0,0 +1,33 @@
+export interface Mandate {
+    mandate_version: string;
+    grantor: string;
+    agent_id: string;
+    max_amount: number | null;
+    currency: string;
+    merchant_allowlist: string[];
+    categories: string[];
+    purpose: string | null;
+    issued_at: string;
+    expires_at: string;
+}
+export interface MandateCheck {
+    amount?: number;
+    merchant?: string;
+    category?: string;
+    at?: string;
+}
+/**
+ * Verify a signed mandate against an optional intended action. Returns each
+ * check plus an overall `valid`, with human-readable reasons. Honest: an invalid
+ * signature, expiry, over-cap amount, or out-of-scope merchant/category all
+ * fail closed — never assumed-OK.
+ */
+export declare function checkMandate(mandate: Mandate, signature_b64url: string, check?: MandateCheck): {
+    valid: boolean;
+    signature_valid: boolean;
+    not_expired: boolean;
+    within_cap: boolean;
+    merchant_in_scope: boolean;
+    category_in_scope: boolean;
+    reasons: string[];
+};

package/dist/mandate.js

@@ -0,0 +1,54 @@
+/**
+ * Gera Agent Mandate — scoped, revocable, signed spend authorizations.
+ *
+ * The permission boundary an AI agent must cross to act on a human's behalf: a
+ * human (or business) issues a signed mandate ("agent X may spend up to £200 at
+ * category Y until date Z"), and any executing party verifies the signature +
+ * scope before honouring an action. Pure authorization — no money moves here;
+ * this is the cryptographic permission layer.
+ *
+ * Reuses the Ed25519 signer in sign.ts (same issuer key as Gera Vouch).
+ */
+import { verifyAttestation } from './sign.js';
+const norm = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, ' ').trim();
+/**
+ * Verify a signed mandate against an optional intended action. Returns each
+ * check plus an overall `valid`, with human-readable reasons. Honest: an invalid
+ * signature, expiry, over-cap amount, or out-of-scope merchant/category all
+ * fail closed — never assumed-OK.
+ */
+export function checkMandate(mandate, signature_b64url, check = {}) {
+    const reasons = [];
+    const signature_valid = verifyAttestation(mandate, signature_b64url);
+    if (!signature_valid)
+        reasons.push('Signature does not verify against the Gera issuer key — the mandate is forged or altered.');
+    const now = check.at ? Date.parse(check.at) : Date.now();
+    const exp = Date.parse(mandate.expires_at);
+    const not_expired = Number.isFinite(exp) ? now <= exp : false;
+    if (!not_expired)
+        reasons.push(`Mandate expired (expires_at ${mandate.expires_at}).`);
+    let within_cap = true;
+    if (check.amount != null) {
+        within_cap = mandate.max_amount == null ? true : check.amount <= mandate.max_amount;
+        if (!within_cap)
+            reasons.push(`Amount ${check.amount} exceeds mandate cap ${mandate.max_amount} ${mandate.currency}.`);
+    }
+    let merchant_in_scope = true;
+    if (check.merchant != null && mandate.merchant_allowlist.length > 0) {
+        const want = norm(check.merchant);
+        merchant_in_scope = mandate.merchant_allowlist.some((m) => norm(m) === want);
+        if (!merchant_in_scope)
+            reasons.push(`Merchant "${check.merchant}" is not in the mandate allowlist.`);
+    }
+    let category_in_scope = true;
+    if (check.category != null && mandate.categories.length > 0) {
+        const want = norm(check.category);
+        category_in_scope = mandate.categories.some((c) => norm(c) === want);
+        if (!category_in_scope)
+            reasons.push(`Category "${check.category}" is not permitted by the mandate.`);
+    }
+    const valid = signature_valid && not_expired && within_cap && merchant_in_scope && category_in_scope;
+    if (valid)
+        reasons.push('Mandate is valid: signature verifies, not expired, and the action is within scope.');
+    return { valid, signature_valid, not_expired, within_cap, merchant_in_scope, category_in_scope, reasons };
+}

package/dist/server.js

@@ -23,7 +23,8 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 import { fhrs, cqc, doctors, providers, findByName, norm, } from './data.js';
-import { signAttestation, publicKeyInfo } from './sign.js';
+import { signAttestation, verifyAttestation, publicKeyInfo } from './sign.js';
+import { checkMandate } from './mandate.js';
 function asText(payload) {
     return {
         content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
@@ -408,6 +409,128 @@ export function registerTools(server) {
         description: 'Returns the Ed25519 public key (and key_id + verification recipe) used to sign Gera Vouch attestations, so any party can independently verify an issue_attestation receipt without trusting the transport.',
         inputSchema: {},
     }, async () => asText(publicKeyInfo()));
+    // ── Tool 8: issue_mandate (Gera Agent Mandate) ────────────────────────────
+    // The permission boundary an agent crosses to act on a human's behalf: issues
+    // a scoped, time-boxed, Ed25519-signed mandate token. No money moves — this is
+    // pure authorization the executing party verifies before honouring an action.
+    server.registerTool('issue_mandate', {
+        title: 'Gera Agent Mandate: issue a scoped, signed spend mandate',
+        description: 'A human or business grants an AI agent scoped, revocable authority ("agent X may spend up to N at category/merchant Y until date Z"). Returns a cryptographically signed mandate any executing party verifies with verify_mandate before honouring an action. Pure authorization — Gera moves no money here.',
+        inputSchema: {
+            grantor: z.string().describe('Who is granting authority (person or business).'),
+            agent_id: z.string().describe('Identifier of the agent the mandate is granted to.'),
+            max_amount: z.number().optional().describe('Spend cap per action in the given currency. Omit for no cap.'),
+            currency: z.string().optional().describe('ISO currency code, e.g. "GBP". Defaults to GBP.'),
+            merchant_allowlist: z.array(z.string()).optional().describe('Only these merchants are permitted. Omit for any.'),
+            categories: z.array(z.string()).optional().describe('Only these spend categories are permitted. Omit for any.'),
+            purpose: z.string().optional().describe('Human-readable purpose recorded in the mandate.'),
+            expires_at: z.string().optional().describe('ISO 8601 expiry. Defaults to 30 days from now.'),
+        },
+    }, async ({ grantor, agent_id, max_amount, currency, merchant_allowlist, categories, purpose, expires_at }) => {
+        const now = new Date();
+        const exp = expires_at ?? new Date(now.getTime() + 30 * 24 * 60 * 60 * 1000).toISOString();
+        const mandate = {
+            mandate_version: '0.1',
+            grantor,
+            agent_id,
+            max_amount: max_amount ?? null,
+            currency: currency ?? 'GBP',
+            merchant_allowlist: merchant_allowlist ?? [],
+            categories: categories ?? [],
+            purpose: purpose ?? null,
+            issued_at: now.toISOString(),
+            expires_at: exp,
+        };
+        const signature = signAttestation(mandate);
+        return asText({
+            mandate,
+            signature,
+            verify: 'Pass `mandate` + `signature.signature_b64url` (plus the intended amount/merchant/category) to verify_mandate. Public key from get_vouch_public_key.',
+            note: 'A signed mandate is a revocable authorization, not a payment. Revoke by maintaining a revocation list keyed on issued_at + agent_id (roadmap: hosted revocation registry).',
+        });
+    });
+    // ── Tool 9: verify_mandate ────────────────────────────────────────────────
+    server.registerTool('verify_mandate', {
+        title: 'Gera Agent Mandate: verify a mandate before acting',
+        description: 'Before honouring an agent action, verify its mandate: checks the Ed25519 signature, expiry, spend cap, and merchant/category scope against the intended action. Fails closed — a forged, expired, over-cap, or out-of-scope mandate returns valid:false with reasons. Never assumes OK.',
+        inputSchema: {
+            mandate: z.record(z.any()).describe('The mandate object returned by issue_mandate.'),
+            signature_b64url: z.string().describe('The signature.signature_b64url from issue_mandate.'),
+            amount: z.number().optional().describe('Intended spend amount to check against the cap.'),
+            merchant: z.string().optional().describe('Intended merchant to check against the allowlist.'),
+            category: z.string().optional().describe('Intended category to check against the permitted set.'),
+        },
+    }, async ({ mandate, signature_b64url, amount, merchant, category }) => {
+        const result = checkMandate(mandate, signature_b64url, { amount, merchant, category });
+        return asText({ ...result, honesty_note: HONESTY_NOTE });
+    });
+    // ── Tool 10: issue_receipt (Gera Ledger) ──────────────────────────────────
+    // Completes the spine chain (verify -> vouch -> mandate -> RECEIPT): once an
+    // agent takes an action, it mints a cryptographically signed receipt that the
+    // action happened, optionally linking the attestation/mandate it acted under.
+    // A verifiable proof-of-action; the hosted append-only registry + dispute
+    // resolution is roadmap (this is the stateless signed-receipt primitive).
+    server.registerTool('issue_receipt', {
+        title: 'Gera Ledger: issue a signed receipt for a completed agent action',
+        description: 'After an AI agent acts (books, pays, dispatches), mint a cryptographically signed receipt recording what happened, optionally referencing the Vouch attestation and/or Agent Mandate it acted under. Any party verifies it with verify_receipt + the public key from get_vouch_public_key. A verifiable proof-of-action — not a settlement; Gera moves no money here.',
+        inputSchema: {
+            action: z.string().describe('What the agent did, e.g. "booked a cleaner".'),
+            agent_id: z.string().describe('Identifier of the acting agent.'),
+            subject: z.string().describe('Who/what the action was taken on (merchant, provider, counterparty).'),
+            outcome: z.enum(['completed', 'failed', 'pending']).optional().describe('Action outcome. Defaults to completed.'),
+            amount: z.number().optional().describe('Amount involved, if any.'),
+            currency: z.string().optional().describe('ISO currency code. Defaults to GBP when amount is set.'),
+            mandate_signature: z.string().optional().describe('The mandate signature this action was authorised under (links the receipt to its mandate).'),
+            attestation_signature: z.string().optional().describe('The Vouch attestation signature relied on (links the receipt to its diligence).'),
+            evidence: z.array(z.string()).optional().describe('Evidence references (URLs, geo/photo/check-in IDs). Stored verbatim, not validated.'),
+            occurred_at: z.string().optional().describe('ISO 8601 time the action occurred. Defaults to now.'),
+        },
+    }, async ({ action, agent_id, subject, outcome, amount, currency, mandate_signature, attestation_signature, evidence, occurred_at }) => {
+        const now = new Date();
+        const receipt = {
+            receipt_version: '0.1',
+            issuer: 'Gera Ledger — a Gera Systems product (gera.services)',
+            action,
+            agent_id,
+            subject,
+            outcome: outcome ?? 'completed',
+            amount: amount ?? null,
+            currency: amount != null ? currency ?? 'GBP' : null,
+            references: {
+                mandate_signature: mandate_signature ?? null,
+                attestation_signature: attestation_signature ?? null,
+            },
+            evidence: evidence ?? [],
+            occurred_at: occurred_at ?? now.toISOString(),
+            issued_at: now.toISOString(),
+        };
+        const signature = signAttestation(receipt);
+        return asText({
+            receipt,
+            signature,
+            verify: 'Pass `receipt` + `signature.signature_b64url` to verify_receipt. Public key from get_vouch_public_key.',
+            note: 'A signed receipt proves Gera recorded this action as stated, as of issued_at. It is a proof-of-action, not a settlement or guarantee. A hosted, queryable append-only ledger + dispute resolution is on the roadmap.',
+        });
+    });
+    // ── Tool 11: verify_receipt ───────────────────────────────────────────────
+    server.registerTool('verify_receipt', {
+        title: 'Gera Ledger: verify a signed action receipt',
+        description: 'Verify a receipt from issue_receipt: checks the Ed25519 signature against the Gera issuer key. Returns signature_valid plus the receipt, so any party can confirm Gera recorded this action without trusting the transport. Fails closed on any alteration.',
+        inputSchema: {
+            receipt: z.record(z.any()).describe('The receipt object returned by issue_receipt.'),
+            signature_b64url: z.string().describe('The signature.signature_b64url from issue_receipt.'),
+        },
+    }, async ({ receipt, signature_b64url }) => {
+        const signature_valid = verifyAttestation(receipt, signature_b64url);
+        return asText({
+            signature_valid,
+            receipt,
+            result: signature_valid
+                ? 'Valid: Gera recorded this action as stated; the receipt has not been altered.'
+                : 'INVALID: signature does not verify — the receipt is forged or altered.',
+            honesty_note: HONESTY_NOTE,
+        });
+    });
 }
 /**
  * Construct a fully-configured Gera Verify McpServer (all tools registered).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gera-services/mcp-gera-verify",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Gera Verify MCP server — \"Proof-of-Real\": let AI agents check if a UK business / food establishment / care provider is real and how trustworthy it is, using real verified FSA food-hygiene, CQC care-registry and Gera verified-provider data. Offline, source-attributed, no auth. A Gera Systems product.",
   "license": "MIT",
   "type": "module",

package/server.json

@@ -2,7 +2,7 @@
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.geraservicesuk/mcp-gera-verify",
   "description": "Verify if a UK business, food establishment or care provider is real (FSA, CQC and Gera data), and issue a cryptographically signed attestation an AI agent can present before it acts (Gera Vouch).",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "repository": {
     "url": "https://github.com/geraservicesuk/globetura",
     "source": "github",
@@ -13,7 +13,7 @@
     {
       "registryType": "npm",
       "identifier": "@gera-services/mcp-gera-verify",
-      "version": "1.0.0",
+      "version": "1.2.0",
       "transport": {
         "type": "stdio"
       }