@mandatum/sdk 1.0.0

package/README.md

@@ -0,0 +1,212 @@
+# @mandatum/sdk
+
+> **Zero-trust authorization and spending limits for AI agents.** One line of code to verify permissions, enforce budgets, and generate tamper-proof audit receipts.
+
+[![npm](https://img.shields.io/npm/v/@mandatum/sdk)](https://www.npmjs.com/package/@mandatum/sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+## Install
+
+```bash
+npm install @mandatum/sdk
+```
+
+## Quick Start
+
+```javascript
+import { Mandatum } from '@mandatum/sdk';
+
+const mandatum = new Mandatum({
+  apiKey: 'mdt_live_xxxxxxxxxxxxxxxx',
+  baseUrl: 'https://mandatum-fbg9.onrender.com', // or your self-hosted URL
+});
+
+// ─── 1. Register an Agent ───────────────────────────────
+const agent = await mandatum.agents.create({
+  name: 'PaymentBot',
+  type: 'payment',
+  delegator: 'cfo@yourcompany.com',
+});
+
+// ─── 2. Create a Spending Policy ────────────────────────
+const policy = await mandatum.policies.create({
+  name: 'cloud-budget',
+  resource: 'payments',
+  actions: ['payments:execute'],
+  constraints: {
+    max_amount: 5000,
+    daily_limit: 10000,
+    currency: 'INR',
+  },
+});
+await mandatum.policies.assign(agent.id, policy.id);
+
+// ─── 3. Issue a Scoped Token ────────────────────────────
+const { token } = await mandatum.tokens.issue({
+  agentId: agent.id,
+  scopes: ['payments:execute'],
+  constraints: { max_amount: 5000, currency: 'INR' },
+  expiresIn: '1h',
+});
+
+// ─── 4. The 1-Line Permission Gate ─────────────────────
+const result = await mandatum.check(token, 'payments:execute', {
+  amount: 350,
+  currency: 'INR',
+  vendor: 'DigitalOcean',
+});
+
+if (result.allowed) {
+  console.log('✅ Approved — receipt:', result.receipt.receiptId);
+  // Proceed with payment
+} else {
+  console.log('❌ Blocked:', result.reason);
+}
+```
+
+## Core Concepts
+
+### The Permission Gate
+
+Every agent action goes through `mandatum.check()`. It verifies the JWT signature (Ed25519), checks scopes, evaluates spending constraints, enforces rate limits, and returns a cryptographically signed receipt — all in one call.
+
+```javascript
+const result = await mandatum.check(token, action, context);
+// result.allowed   → boolean
+// result.reason    → why it was blocked (if denied)
+// result.receipt   → { receiptId, signature, timestamp }
+// result.checks    → detailed constraint evaluations
+// result.rateLimit → current usage stats
+```
+
+### Quick Boolean Check
+
+If you just need a true/false gate:
+
+```javascript
+if (await mandatum.isAllowed(token, 'email:send', { to: 'user@example.com' })) {
+  sendEmail();
+}
+```
+
+## API Reference
+
+### `new Mandatum(config)`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `apiKey` | `string` | *required* | Your API key (`mdt_live_...`) |
+| `baseUrl` | `string` | `http://localhost:3001` | Mandatum API URL |
+| `timeout` | `number` | `10000` | Request timeout in ms |
+
+### Agents
+
+```javascript
+mandatum.agents.create({ name, type, delegator, description })
+mandatum.agents.list({ status, search, environment })
+mandatum.agents.get(id)
+mandatum.agents.suspend(id)
+mandatum.agents.revoke(id)           // cascading — revokes all child agents + tokens
+mandatum.agents.spend(id, { amount, currency, vendor, category })
+mandatum.agents.spending(id)         // returns today/total spent + remaining budget
+```
+
+### Tokens
+
+```javascript
+mandatum.tokens.issue({ agentId, scopes, constraints, expiresIn })
+mandatum.tokens.verify(token, action, context)
+mandatum.tokens.revoke(jti)
+mandatum.tokens.list({ agentId, status })
+```
+
+### Policies
+
+```javascript
+mandatum.policies.create({ name, resource, actions, constraints })
+mandatum.policies.list()
+mandatum.policies.get(id)
+mandatum.policies.assign(agentId, policyId)
+```
+
+### Audit
+
+```javascript
+mandatum.audit.list({ limit, agentId })
+mandatum.audit.verifyChain()         // verify hash-chain integrity
+mandatum.audit.getReceipt(eventId)   // get signed receipt for an event
+```
+
+## Payment Gateway Wrappers
+
+Pre-built wrappers that call `mandatum.check()` before creating payments:
+
+### Razorpay
+
+```javascript
+import { MandatumRazorpay } from '@mandatum/sdk/payments/razorpay';
+
+const pay = new MandatumRazorpay(razorpayClient, mandatum, agent.id);
+
+const result = await pay.createPayment({
+  amount: 50000, // paise
+  currency: 'INR',
+  description: 'Cloud hosting',
+});
+// Automatically checks limits → creates Razorpay order → records spending
+```
+
+### Stripe
+
+```javascript
+import { MandatumStripe } from '@mandatum/sdk/payments/stripe';
+
+const pay = new MandatumStripe(stripeClient, mandatum, agent.id);
+
+const result = await pay.createPaymentIntent({
+  amount: 5000, // cents
+  currency: 'usd',
+});
+```
+
+## Local Verification (Sub-1ms)
+
+For latency-critical paths, verify token signatures locally without a network round-trip:
+
+```javascript
+const mandatum = new Mandatum({
+  apiKey: 'mdt_live_...',
+  localVerification: true, // fetches public key on init
+});
+
+// check() now verifies the signature locally first,
+// then calls the server only for constraint evaluation
+```
+
+## Error Handling
+
+All errors throw `MandatumError` with a `code` property:
+
+```javascript
+import { MandatumError } from '@mandatum/sdk';
+
+try {
+  await mandatum.check(token, 'payments:execute', { amount: 999999 });
+} catch (err) {
+  if (err instanceof MandatumError) {
+    console.log(err.code);    // 'RATE_LIMIT_MINUTE', 'TIMEOUT', 'API_ERROR'
+    console.log(err.status);  // HTTP status code (if applicable)
+  }
+}
+```
+
+## Security
+
+- All tokens are **Ed25519-signed JWTs** — tamper-proof and verifiable with the public key
+- API keys are **SHA-256 hashed** before storage — Mandatum never stores raw keys
+- Audit events are **hash-chained** — any tampering breaks the chain
+- Receipts are **cryptographically signed** — non-repudiable proof of authorization
+
+## License
+
+MIT © [Mandatum](https://mandatumio.vercel.app)

package/index.js

@@ -0,0 +1,318 @@
+/**
+ * @mandatum/sdk — Mandatum SDK for Agent Platforms
+ *
+ * Install: npm install @mandatum/sdk
+ *
+ * Usage:
+ *   import { Mandatum } from '@mandatum/sdk';
+ *   const m = new Mandatum({ apiKey: 'mdt_live_...' });
+ *
+ *   // The 1-line permission gate
+ *   const ok = await m.check(token, 'payments:execute', { amount: 350 });
+ *   if (ok.allowed) { ... }
+ */
+
+class MandatumError extends Error {
+    constructor(message, code, status) {
+        super(message);
+        this.name = 'MandatumError';
+        this.code = code;
+        this.status = status;
+    }
+}
+
+export class Mandatum {
+    /**
+     * @param {object} config
+     * @param {string} config.apiKey - Mandatum API key (mdt_live_...)
+     * @param {string} [config.baseUrl] - API base URL (default: https://api.mandatum.io)
+     * @param {number} [config.timeout] - Request timeout in ms (default: 10000)
+     * @param {boolean} [config.localVerification] - Enable local token verification (default: false)
+     */
+    constructor({ apiKey, baseUrl, timeout = 10000, localVerification = false } = {}) {
+        if (!apiKey) throw new MandatumError('API key is required', 'MISSING_API_KEY');
+        this.apiKey = apiKey;
+        this.baseUrl = (baseUrl || 'http://localhost:3001').replace(/\/$/, '');
+        this.timeout = timeout;
+
+        // Sub-modules
+        this.agents = new AgentsAPI(this);
+        this.tokens = new TokensAPI(this);
+        this.policies = new PoliciesAPI(this);
+        this.audit = new AuditAPI(this);
+
+        // Local verification — store as ready promise (no async in constructor)
+        this._localVerifierReady = localVerification
+            ? this._initLocalVerifier()
+            : Promise.resolve();
+    }
+
+    /**
+     * ─── THE 1-LINE PERMISSION GATE ───────────────────────
+     *
+     * Call this before every agent action.
+     * Returns { allowed, reason, receipt, checks }
+     *
+     * @param {string} token - The agent's JWT token
+     * @param {string} action - What the agent wants to do (e.g., 'payments:execute')
+     * @param {object} [context] - Action context (amount, currency, vendor, etc.)
+     * @returns {Promise<object>}
+     *
+     * @example
+     *   const result = await mandatum.check(agentToken, 'payments:execute', {
+     *     amount: 350,
+     *     currency: 'INR',
+     *     vendor: 'DigitalOcean'
+     *   });
+     *
+     *   if (result.allowed) {
+     *     // Proceed with payment
+     *     razorpay.pay(350);
+     *   } else {
+     *     console.log('Blocked:', result.reason);
+     *   }
+     */
+    async check(token, action, context = {}) {
+        // Use local verification if available (sub-1ms)
+        if (this._localVerifier) {
+            const local = await this._localVerifier.verify(token);
+            if (!local.valid) {
+                return { allowed: false, valid: false, reason: local.error, code: local.code };
+            }
+            // Local can't check constraints fully — call server for that
+        }
+
+        const result = await this._request('POST', '/tokens/verify', { token, action, context });
+        const CHECK_DEFAULTS = {
+            allowed: false, valid: false, agent: undefined, delegator: undefined,
+            reason: null, receipt: null, checks: [], scopes: [],
+            constraints: {}, expiresAt: undefined, error: null, code: null,
+        };
+        return { ...CHECK_DEFAULTS, ...result };
+    }
+
+    /**
+     * Quick permission check — returns just true/false
+     */
+    async isAllowed(token, action, context = {}) {
+        const result = await this.check(token, action, context);
+        return result.allowed === true;
+    }
+
+    /**
+     * Get server health status
+     */
+    async health() {
+        return this._request('GET', '/health', null, false);
+    }
+
+    /**
+     * Get server public key (for local verification)
+     */
+    async getPublicKey() {
+        return this._request('GET', '/.well-known/public-key', null, false);
+    }
+
+    // ─── Internal HTTP Client ─────────────────────────────
+
+    async _request(method, path, body, authenticated = true) {
+        const url = `${this.baseUrl}/v1${path}`;
+        const headers = { 'Content-Type': 'application/json' };
+
+        if (authenticated) {
+            headers['Authorization'] = `Bearer ${this.apiKey}`;
+        }
+
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+        try {
+            const res = await fetch(url, {
+                method,
+                headers,
+                body: body ? JSON.stringify(body) : undefined,
+                signal: controller.signal,
+            });
+
+            clearTimeout(timeoutId);
+            const data = await res.json();
+
+            if (!res.ok) {
+                throw new MandatumError(
+                    data.error || data.message || `HTTP ${res.status}`,
+                    data.code || 'API_ERROR',
+                    res.status
+                );
+            }
+
+            return data;
+        } catch (err) {
+            clearTimeout(timeoutId);
+            if (err.name === 'AbortError') {
+                throw new MandatumError('Request timed out', 'TIMEOUT');
+            }
+            if (err instanceof MandatumError) throw err;
+            throw new MandatumError(err.message, 'NETWORK_ERROR');
+        }
+    }
+
+    async _initLocalVerifier() {
+        try {
+            const { LocalVerifier } = await import('./local-verifier.js');
+            this._localVerifier = new LocalVerifier(this);
+            await this._localVerifier.init();
+        } catch (err) {
+            console.warn('Mandatum: Local verification not available, using remote only');
+        }
+    }
+}
+
+// ─── Agents Sub-API ─────────────────────────────────────
+
+class AgentsAPI {
+    constructor(client) { this.client = client; }
+
+    /**
+     * Register a new AI agent.
+     * Generates an Ed25519 key pair on the server.
+     *
+     * @param {object} params
+     * @param {string} params.name - Agent name
+     * @param {string} params.type - Agent type (payment, email, calendar, etc.)
+     * @param {string} [params.description]
+     * @param {string} [params.delegator] - Human who authorized this agent
+     */
+    async create({ name, type, description, delegator }) {
+        return this.client._request('POST', '/agents', { name, type, description, delegator });
+    }
+
+    /** List all agents */
+    async list(params = {}) {
+        const qs = new URLSearchParams(params).toString();
+        return this.client._request('GET', `/agents${qs ? '?' + qs : ''}`);
+    }
+
+    /** Get agent details (includes keys, policies, tokens, activity) */
+    async get(id) {
+        return this.client._request('GET', `/agents/${id}`);
+    }
+
+    /** Update agent status (active, suspended, revoked) */
+    async update(id, body) {
+        return this.client._request('PATCH', `/agents/${id}`, body);
+    }
+
+    /** Suspend an agent */
+    async suspend(id) { return this.update(id, { status: 'suspended' }); }
+
+    /** Revoke an agent (and all its tokens) */
+    async revoke(id) { return this.update(id, { status: 'revoked' }); }
+
+    /**
+     * Record a spending event — the SDK calls this before/after payment.
+     * Returns { allowed, eventId, amount, spending } or { allowed: false, reason }.
+     *
+     * @param {string} id - Agent ID
+     * @param {object} params
+     * @param {number} params.amount - Spending amount
+     * @param {string} [params.currency] - Currency (default: INR)
+     * @param {string} [params.vendor] - Vendor name
+     * @param {string} [params.category] - Category (e.g., 'cloud', 'groceries')
+     * @param {string} [params.description] - Human-readable description
+     *
+     * @example
+     *   const result = await mandatum.agents.spend('agt_abc123', {
+     *     amount: 350, currency: 'INR', vendor: 'DigitalOcean'
+     *   });
+     *   if (result.allowed) { // proceed with payment }
+     */
+    async spend(id, { amount, currency, vendor, category, description } = {}) {
+        return this.client._request('POST', `/agents/${id}/spend`, {
+            amount, currency, vendor, category, description,
+        });
+    }
+
+    /**
+     * Get spending summary for an agent.
+     * Returns today/total spent, remaining budget, recent events.
+     */
+    async spending(id) {
+        return this.client._request('GET', `/agents/${id}/spending`);
+    }
+}
+
+// ─── Tokens Sub-API ─────────────────────────────────────
+
+class TokensAPI {
+    constructor(client) { this.client = client; }
+
+    /**
+     * Issue a signed JWT token for an agent.
+     *
+     * @param {object} params
+     * @param {string} params.agentId - Agent to issue token for
+     * @param {string[]} params.scopes - Allowed actions
+     * @param {object} [params.constraints] - Limits (max_amount, currency, etc.)
+     * @param {string} [params.expiresIn] - Duration ('15m', '1h', '30d')
+     */
+    async issue({ agentId, scopes, constraints, policyId, expiresIn }) {
+        return this.client._request('POST', '/tokens/issue', {
+            agentId, scopes, constraints, policyId, expiresIn,
+        });
+    }
+
+    /**
+     * Verify a token (signature + constraints + revocation).
+     * This is what mandatum.check() calls internally.
+     */
+    async verify(token, action, context) {
+        return this.client._request('POST', '/tokens/verify', { token, action, context });
+    }
+
+    /** Revoke a token immediately */
+    async revoke(jti) {
+        return this.client._request('POST', '/tokens/revoke', { jti });
+    }
+
+    /** List all tokens */
+    async list(params = {}) {
+        const qs = new URLSearchParams(params).toString();
+        return this.client._request('GET', `/tokens${qs ? '?' + qs : ''}`);
+    }
+}
+
+// ─── Policies Sub-API ───────────────────────────────────
+
+class PoliciesAPI {
+    constructor(client) { this.client = client; }
+
+    async create({ name, resource, actions, constraints, description }) {
+        return this.client._request('POST', '/policies', { name, resource, actions, constraints, description });
+    }
+
+    async list() { return this.client._request('GET', '/policies'); }
+
+    async get(id) { return this.client._request('GET', `/policies/${id}`); }
+
+    async assign(agentId, policyId) {
+        return this.client._request('POST', '/policies/assign', { agentId, policyId });
+    }
+}
+
+// ─── Audit Sub-API ──────────────────────────────────────
+
+class AuditAPI {
+    constructor(client) { this.client = client; }
+
+    async list(params = {}) {
+        const qs = new URLSearchParams(params).toString();
+        return this.client._request('GET', `/audit${qs ? '?' + qs : ''}`);
+    }
+
+    async verifyChain() { return this.client._request('GET', '/audit/verify-chain'); }
+
+    async getReceipt(eventId) { return this.client._request('GET', `/audit/${eventId}/receipt`); }
+}
+
+export default Mandatum;
+export { MandatumError };

package/local-verifier.js

@@ -0,0 +1,102 @@
+/**
+ * Local Token Verifier
+ *
+ * Verifies Mandatum JWT tokens locally without a network call.
+ * Caches the server's Ed25519 public key and verifies signatures in <1ms.
+ *
+ * Limitations:
+ *   - Cannot check revocation locally (needs server for real-time revocation)
+ *   - Cannot evaluate complex constraints
+ *   - Best used as a fast pre-check; fall back to server for full verification
+ *
+ * Usage:
+ *   const m = new Mandatum({ apiKey: '...', localVerification: true });
+ *   // SDK automatically uses local verification when possible
+ */
+
+import * as jose from 'jose';
+
+export class LocalVerifier {
+    constructor(client) {
+        this.client = client;
+        this.publicKey = null;
+        this.publicKeyPem = null;
+        this.lastRefresh = 0;
+        this.refreshInterval = 5 * 60 * 1000; // Refresh public key every 5 minutes
+    }
+
+    /**
+     * Initialize: fetch and cache the server's Ed25519 public key.
+     */
+    async init() {
+        await this.refreshPublicKey();
+        console.log('Mandatum: Local verification initialized (sub-1ms token checks)');
+    }
+
+    /**
+     * Refresh the cached public key from the server.
+     */
+    async refreshPublicKey() {
+        try {
+            const data = await this.client.getPublicKey();
+            this.publicKeyPem = data.publicKey;
+            this.publicKey = await jose.importSPKI(data.publicKey, 'EdDSA');
+            this.lastRefresh = Date.now();
+        } catch (err) {
+            console.warn('Mandatum: Failed to refresh public key:', err.message);
+        }
+    }
+
+    /**
+     * Verify a token locally.
+     * Checks: signature validity, expiration, issuer.
+     * Does NOT check: revocation, complex constraints.
+     *
+     * @param {string} token - JWT string
+     * @returns {Promise<object>} { valid, payload, error }
+     */
+    async verify(token) {
+        // Refresh key if stale
+        if (Date.now() - this.lastRefresh > this.refreshInterval) {
+            await this.refreshPublicKey();
+        }
+
+        if (!this.publicKey) {
+            return { valid: false, error: 'No public key cached', code: 'NO_PUBLIC_KEY' };
+        }
+
+        try {
+            const { payload } = await jose.jwtVerify(token, this.publicKey, {
+                issuer: 'mandatum.io',
+            });
+
+            return {
+                valid: true,
+                payload,
+                agent: payload.sub,
+                scopes: payload.scopes,
+                constraints: payload.constraints,
+                delegator: payload.delegator,
+                expiresAt: new Date(payload.exp * 1000).toISOString(),
+                _note: 'Verified locally. Revocation status not checked — use server verify for full check.',
+            };
+        } catch (err) {
+            if (err.code === 'ERR_JWT_EXPIRED') {
+                return { valid: false, error: 'Token expired', code: 'TOKEN_EXPIRED' };
+            }
+            if (err.code === 'ERR_JWS_SIGNATURE_VERIFICATION_FAILED') {
+                return { valid: false, error: 'Invalid signature', code: 'INVALID_SIGNATURE' };
+            }
+            return { valid: false, error: err.message, code: 'VERIFICATION_FAILED' };
+        }
+    }
+
+    /**
+     * Decode a token without verifying (for debugging).
+     */
+    decode(token) {
+        return jose.decodeJwt(token);
+    }
+}
+
+export default LocalVerifier;

package/package.json

@@ -0,0 +1,48 @@
+{
+    "name": "@mandatum/sdk",
+    "version": "1.0.0",
+    "description": "Zero-trust authorization and spending limits for AI agents. Ed25519-signed JWTs, policy enforcement, and payment gating in one line.",
+    "type": "module",
+    "main": "index.js",
+    "exports": {
+        ".": "./index.js",
+        "./local": "./local-verifier.js",
+        "./payments/razorpay": "./payments/razorpay.js",
+        "./payments/stripe": "./payments/stripe.js"
+    },
+    "files": [
+        "index.js",
+        "local-verifier.js",
+        "payments/",
+        "README.md"
+    ],
+    "keywords": [
+        "ai",
+        "agents",
+        "security",
+        "authorization",
+        "jwt",
+        "ed25519",
+        "spending-limits",
+        "razorpay",
+        "stripe",
+        "payments",
+        "mandatum"
+    ],
+    "author": "Mandatum <hello@mandatum.io>",
+    "license": "MIT",
+    "homepage": "https://mandatumio.vercel.app",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/sagevedant/mandatum"
+    },
+    "bugs": {
+        "url": "https://github.com/sagevedant/mandatum/issues"
+    },
+    "dependencies": {
+        "jose": "^6.1.3"
+    },
+    "engines": {
+        "node": ">=18.0.0"
+    }
+}

package/payments/razorpay.js

@@ -0,0 +1,118 @@
+/**
+ * Mandatum Razorpay Payment Wrapper
+ *
+ * Wraps Razorpay API calls with Mandatum authorization.
+ * The agent must get approval from Mandatum before any payment goes through.
+ *
+ * @example
+ *   import Razorpay from 'razorpay';
+ *   import { Mandatum } from '@mandatum/sdk';
+ *   import { MandatumRazorpay } from '@mandatum/sdk/payments/razorpay';
+ *
+ *   const razorpay = new Razorpay({ key_id: '...', key_secret: '...' });
+ *   const mandatum = new Mandatum({ apiKey: 'mdt_live_...' });
+ *
+ *   const pay = new MandatumRazorpay(razorpay, mandatum, 'agt_abc123');
+ *   const result = await pay.createPayment({ amount: 50000, currency: 'INR' });
+ *   // Mandatum checks limits FIRST, then Razorpay creates the payment
+ */
+
+export class MandatumRazorpay {
+    /**
+     * @param {object} razorpayClient - Initialized Razorpay instance
+     * @param {object} mandatumClient - Initialized Mandatum SDK instance
+     * @param {string} agentId - The agent making the payment
+     */
+    constructor(razorpayClient, mandatumClient, agentId) {
+        this.razorpay = razorpayClient;
+        this.mandatum = mandatumClient;
+        this.agentId = agentId;
+    }
+
+    /**
+     * Create a payment — checks Mandatum limits first.
+     *
+     * @param {object} params
+     * @param {number} params.amount - Amount in smallest currency unit (paise for INR)
+     * @param {string} [params.currency='INR'] - Currency
+     * @param {string} [params.description] - Payment description
+     * @param {object} [params.notes] - Razorpay notes
+     * @returns {Promise<{ allowed: boolean, payment?: object, reason?: string, eventId: string }>}
+     */
+    async createPayment({ amount, currency = 'INR', description, notes, ...rest }) {
+        // Convert paise to rupees for Mandatum (Razorpay uses paise, Mandatum uses rupees)
+        const amountInRupees = amount / 100;
+
+        // Step 1: Check with Mandatum
+        const approval = await this.mandatum.agents.spend(this.agentId, {
+            amount: amountInRupees,
+            currency,
+            vendor: 'razorpay',
+            category: 'payment',
+            description: description || `Razorpay payment of ${currency} ${amountInRupees}`,
+        });
+
+        if (!approval.allowed) {
+            return {
+                allowed: false,
+                reason: approval.reason,
+                eventId: approval.eventId,
+                spending: approval.spending,
+            };
+        }
+
+        // Step 2: Mandatum approved — proceed with Razorpay
+        try {
+            const payment = await this.razorpay.orders.create({
+                amount,
+                currency,
+                notes: { ...notes, mandatum_event_id: approval.eventId },
+                ...rest,
+            });
+
+            return {
+                allowed: true,
+                payment,
+                eventId: approval.eventId,
+                spending: approval.spending,
+            };
+        } catch (err) {
+            // Payment failed after Mandatum approved — should ideally refund the spending event
+            return {
+                allowed: true,
+                paymentFailed: true,
+                error: err.message,
+                eventId: approval.eventId,
+            };
+        }
+    }
+
+    /**
+     * Create a payment link — checks Mandatum limits first.
+     */
+    async createPaymentLink({ amount, currency = 'INR', description, customer, ...rest }) {
+        const amountInRupees = amount / 100;
+
+        const approval = await this.mandatum.agents.spend(this.agentId, {
+            amount: amountInRupees,
+            currency,
+            vendor: 'razorpay',
+            category: 'payment-link',
+            description: description || `Payment link for ${currency} ${amountInRupees}`,
+        });
+
+        if (!approval.allowed) {
+            return { allowed: false, reason: approval.reason, eventId: approval.eventId };
+        }
+
+        const link = await this.razorpay.paymentLink.create({
+            amount, currency, description, customer,
+            notes: { mandatum_event_id: approval.eventId },
+            ...rest,
+        });
+
+        return { allowed: true, paymentLink: link, eventId: approval.eventId };
+    }
+}
+
+export default MandatumRazorpay;

package/payments/stripe.js

@@ -0,0 +1,109 @@
+/**
+ * Mandatum Stripe Payment Wrapper
+ *
+ * Wraps Stripe API calls with Mandatum authorization.
+ *
+ * @example
+ *   import Stripe from 'stripe';
+ *   import { Mandatum } from '@mandatum/sdk';
+ *   import { MandatumStripe } from '@mandatum/sdk/payments/stripe';
+ *
+ *   const stripe = new Stripe('sk_live_...');
+ *   const mandatum = new Mandatum({ apiKey: 'mdt_live_...' });
+ *
+ *   const pay = new MandatumStripe(stripe, mandatum, 'agt_abc123');
+ *   const result = await pay.createPaymentIntent({ amount: 5000, currency: 'usd' });
+ */
+
+export class MandatumStripe {
+    constructor(stripeClient, mandatumClient, agentId) {
+        this.stripe = stripeClient;
+        this.mandatum = mandatumClient;
+        this.agentId = agentId;
+    }
+
+    /**
+     * Create a PaymentIntent — checks Mandatum limits first.
+     *
+     * @param {object} params
+     * @param {number} params.amount - Amount in smallest currency unit (cents for USD)
+     * @param {string} [params.currency='usd'] - Currency
+     * @param {string} [params.description] - Payment description
+     * @param {object} [params.metadata] - Stripe metadata
+     */
+    async createPaymentIntent({ amount, currency = 'usd', description, metadata, ...rest }) {
+        // Convert cents to dollars for Mandatum
+        const amountInMajor = amount / 100;
+
+        const approval = await this.mandatum.agents.spend(this.agentId, {
+            amount: amountInMajor,
+            currency: currency.toUpperCase(),
+            vendor: 'stripe',
+            category: 'payment',
+            description: description || `Stripe payment of ${currency.toUpperCase()} ${amountInMajor}`,
+        });
+
+        if (!approval.allowed) {
+            return {
+                allowed: false,
+                reason: approval.reason,
+                eventId: approval.eventId,
+                spending: approval.spending,
+            };
+        }
+
+        try {
+            const paymentIntent = await this.stripe.paymentIntents.create({
+                amount,
+                currency,
+                description,
+                metadata: { ...metadata, mandatum_event_id: approval.eventId },
+                ...rest,
+            });
+
+            return {
+                allowed: true,
+                paymentIntent,
+                eventId: approval.eventId,
+                spending: approval.spending,
+            };
+        } catch (err) {
+            return {
+                allowed: true,
+                paymentFailed: true,
+                error: err.message,
+                eventId: approval.eventId,
+            };
+        }
+    }
+
+    /**
+     * Create a Checkout Session — checks Mandatum limits first.
+     */
+    async createCheckoutSession({ lineItems, totalAmount, currency = 'usd', ...rest }) {
+        const amountInMajor = totalAmount / 100;
+
+        const approval = await this.mandatum.agents.spend(this.agentId, {
+            amount: amountInMajor,
+            currency: currency.toUpperCase(),
+            vendor: 'stripe',
+            category: 'checkout',
+            description: `Stripe checkout for ${currency.toUpperCase()} ${amountInMajor}`,
+        });
+
+        if (!approval.allowed) {
+            return { allowed: false, reason: approval.reason, eventId: approval.eventId };
+        }
+
+        const session = await this.stripe.checkout.sessions.create({
+            line_items: lineItems,
+            mode: 'payment',
+            metadata: { mandatum_event_id: approval.eventId },
+            ...rest,
+        });
+
+        return { allowed: true, session, eventId: approval.eventId };
+    }
+}
+
+export default MandatumStripe;