Broker Installation (Reference Implementation)

This is the official reference implementation for an IMAGXP Broker.

A Broker is a service that issues cryptographic "Visas" (JWTs) to AI Agents. These Visas are verified by Publishers to grant access.

Prerequisites

Node.js 18+
npm or yarn

1. Setup Project

Create a new directory and install dependencies:

mkdir my-imagxp-broker
cd my-imagxp-broker
npm init -y
npm install express jose @imagxp/protocol typescript ts-node @types/express @types/node

2. The Broker Code (`server.ts`)

Create a file named server.ts. This server has two main jobs:

Trust Endpoint: Host public keys at /.well-known/jwks.json.
Issuance Endpoint: Issue signed JWTs at /issue-visa.

import express from 'express';
import { SignJWT, generateKeyPair, exportJWK } from 'jose';
import { HEADERS, IMAGXP_VERSION } from '@imagxp/protocol';

const app = express();
const PORT = 3000;

// IN MEMORY KEYS (FOR DEMO ONLY)
// In production, load these from a secure KMS or .env
let PUBLIC_KEY_JWK: any;
let PRIVATE_KEY: any;

async function setupKeys() {
    const { publicKey, privateKey } = await generateKeyPair('ES256');
    PRIVATE_KEY = privateKey;
    PUBLIC_KEY_JWK = await exportJWK(publicKey);
    console.log("🔑 Keys generated.");
}

// 1. The Trust Endpoint (Publishers check this)
// This MUST be available at /.well-known/jwks.json
app.get('/.well-known/jwks.json', async (req, res) => {
    res.json({ keys: [ { ...PUBLIC_KEY_JWK, use: 'sig', kid: '1' } ] });
});

// 2. The Issuance Endpoint (Agents pay here)
app.post('/issue-visa', async (req, res) => {
    // START PAYMENT LOGIC (Stripe, Crypto, etc)
    const paymentSuccessful = true; // Replace with real check
    const agentId = "openai.com";
    const targetPublisher = "nytimes.com";
    // END PAYMENT LOGIC

    if (paymentSuccessful) {
        // Sign the Visa (IMAGXP-Compatible JWT)
        const token = await new SignJWT({
            payment_status: "paid",
            amount: 0.001,
            ver: IMAGXP_VERSION
        })
            .setProtectedHeader({ alg: 'ES256', kid: '1' })
            .setIssuedAt()
            .setIssuer('https://your-broker-domain.com') // MUST match Publisher config
            .setAudience(targetPublisher)
            .setExpirationTime('1h')
            .sign(PRIVATE_KEY);

        // Return the token. The Agent puts this in 'x-imagxp-credential'
        res.json({
            token,
            header_name: HEADERS.PAYMENT_CREDENTIAL
        });
    } else {
        res.status(402).json({ error: "Payment Required" });
    }
});

// Start
setupKeys().then(() => {
    app.listen(PORT, () => console.log(`Broker running on http://localhost:${PORT}`));
});

3. Run It

npx ts-node server.ts

4. How to Test

Simulate an Agent buying a Visa:

curl -X POST http://localhost:3000/issue-visa

Response:

{
  "token": "eyJhbGciOiJFUzI1NiIs...",
  "header_name": "x-imagxp-credential"
}