@vinaystwt/xmpp-policy-engine 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xMPP contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/config/src/index.d.ts

@@ -0,0 +1,49 @@
+export declare const config: {
+    readonly nodeEnv: string;
+    readonly network: string;
+    readonly paymentExecutionMode: "mock" | "testnet";
+    readonly rpcUrl: string;
+    readonly networkPassphrase: string;
+    readonly gatewayPort: number;
+    readonly dashboardPort: number;
+    readonly dashboardGatewayUrl: string | undefined;
+    readonly dailyBudgetUsd: number;
+    readonly facilitatorUrl: string;
+    readonly wallet: {
+        readonly agentSecretKey: string | undefined;
+        readonly smartAccountContractId: string | undefined;
+        readonly smartAccountWasmHash: string;
+        readonly webauthnVerifierAddress: string;
+        readonly ed25519VerifierAddress: string;
+        readonly spendingLimitPolicyAddress: string;
+        readonly thresholdPolicyAddress: string;
+    };
+    readonly x402: {
+        readonly facilitatorUrl: string;
+        readonly facilitatorApiKey: string | undefined;
+        readonly maxTransactionFeeStroops: number;
+        readonly facilitatorPrivateKey: string | undefined;
+        readonly recipientAddress: string | undefined;
+    };
+    readonly mpp: {
+        readonly secretKey: string | undefined;
+        readonly recipientAddress: string | undefined;
+        readonly channelContractId: string | undefined;
+        readonly feeSponsorshipEnabled: boolean;
+        readonly feeSponsorship: {
+            readonly chargeEnabled: boolean;
+            readonly sessionEnabled: boolean;
+        };
+        readonly feeSponsorSecretKey: string | undefined;
+        readonly feeBumpSecretKey: string | undefined;
+    };
+    readonly services: {
+        readonly research: string;
+        readonly market: string;
+        readonly stream: string;
+    };
+    readonly contracts: {
+        readonly policyContractId: string | undefined;
+        readonly sessionRegistryContractId: string | undefined;
+    };
+};

package/dist/config/src/index.js

@@ -0,0 +1,117 @@
+import { config as loadEnv } from 'dotenv';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { z } from 'zod';
+const moduleDir = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(moduleDir, '../../../');
+loadEnv({ path: resolve(repoRoot, '.env') });
+loadEnv({ path: resolve(repoRoot, '.env.local'), override: true });
+loadEnv();
+const envSchema = z.object({
+    NODE_ENV: z.string().default('development'),
+    XMPP_NETWORK: z.string().default('stellar:testnet'),
+    XMPP_PAYMENT_EXECUTION_MODE: z.enum(['mock', 'testnet']).default('mock'),
+    XMPP_RPC_URL: z.string().default('https://soroban-testnet.stellar.org'),
+    XMPP_NETWORK_PASSPHRASE: z.string().default('Test SDF Network ; September 2015'),
+    XMPP_GATEWAY_PORT: z.coerce.number().default(4300),
+    XMPP_DASHBOARD_PORT: z.coerce.number().default(4310),
+    XMPP_DASHBOARD_GATEWAY_URL: z.string().optional(),
+    XMPP_DAILY_BUDGET_USD: z.coerce.number().default(0.5),
+    XMPP_AGENT_SECRET_KEY: z.string().optional(),
+    XMPP_SMART_ACCOUNT_CONTRACT_ID: z.string().optional(),
+    XMPP_SMART_ACCOUNT_WASM_HASH: z
+        .string()
+        .default('3e51f5b222dec74650f0b33367acb42a41ce497f72639230463070e666abba2c'),
+    XMPP_WEBAUTHN_VERIFIER_ADDRESS: z
+        .string()
+        .default('CATPTBRWVMH5ZCIKO5HN2F4FMPXVZEXC56RKGHRXCM7EEZGGXK7PICEH'),
+    XMPP_ED25519_VERIFIER_ADDRESS: z
+        .string()
+        .default('CAIKK32K3BZJYTWVTXHZFPIEEDBR6YCVTGPABH4UQUQ4XFA3OLYXG27G'),
+    XMPP_SPENDING_LIMIT_POLICY_ADDRESS: z
+        .string()
+        .default('CBYLPYZGLQ6JVY2IQ5P23QLQPR3KAMMKMZLNWG6RUUKJDNYGPLVHK7U4'),
+    XMPP_THRESHOLD_POLICY_ADDRESS: z
+        .string()
+        .default('CDDQLFG7CV74QHWPSP6NZIPNBR2PPCMTUVYCJF4P3ONDYHODRFGR7LWC'),
+    X402_FACILITATOR_URL: z.string().default('http://localhost:4022'),
+    X402_FACILITATOR_API_KEY: z.string().optional(),
+    X402_MAX_TRANSACTION_FEE_STROOPS: z.coerce.number().default(2000000),
+    X402_RECIPIENT_ADDRESS: z.string().optional(),
+    FACILITATOR_STELLAR_PRIVATE_KEY: z.string().optional(),
+    MPP_SECRET_KEY: z.string().optional(),
+    MPP_RECIPIENT_ADDRESS: z.string().optional(),
+    MPP_CHANNEL_CONTRACT_ID: z.string().optional(),
+    XMPP_ENABLE_MPP_FEE_SPONSORSHIP: z
+        .enum(['true', 'false'])
+        .default('false')
+        .transform((value) => value === 'true'),
+    XMPP_ENABLE_MPP_CHARGE_FEE_SPONSORSHIP: z
+        .enum(['true', 'false'])
+        .optional()
+        .transform((value) => value === 'true'),
+    XMPP_ENABLE_MPP_SESSION_FEE_SPONSORSHIP: z
+        .enum(['true', 'false'])
+        .optional()
+        .transform((value) => value === 'true'),
+    XMPP_MPP_FEE_SPONSOR_SECRET_KEY: z.string().optional(),
+    XMPP_MPP_FEE_BUMP_SECRET_KEY: z.string().optional(),
+    XMPP_RESEARCH_API_URL: z.string().default('http://localhost:4101'),
+    XMPP_MARKET_API_URL: z.string().default('http://localhost:4102'),
+    XMPP_STREAM_API_URL: z.string().default('http://localhost:4103'),
+    XMPP_POLICY_CONTRACT_ID: z.string().optional(),
+    XMPP_SESSION_REGISTRY_CONTRACT_ID: z.string().optional(),
+});
+const env = envSchema.parse(process.env);
+const mppFeeSponsorshipEnabled = env.XMPP_ENABLE_MPP_FEE_SPONSORSHIP;
+const mppChargeFeeSponsorshipEnabled = env.XMPP_ENABLE_MPP_CHARGE_FEE_SPONSORSHIP ?? mppFeeSponsorshipEnabled;
+const mppSessionFeeSponsorshipEnabled = env.XMPP_ENABLE_MPP_SESSION_FEE_SPONSORSHIP ?? mppFeeSponsorshipEnabled;
+export const config = {
+    nodeEnv: env.NODE_ENV,
+    network: env.XMPP_NETWORK,
+    paymentExecutionMode: env.XMPP_PAYMENT_EXECUTION_MODE,
+    rpcUrl: env.XMPP_RPC_URL,
+    networkPassphrase: env.XMPP_NETWORK_PASSPHRASE,
+    gatewayPort: env.XMPP_GATEWAY_PORT,
+    dashboardPort: env.XMPP_DASHBOARD_PORT,
+    dashboardGatewayUrl: env.XMPP_DASHBOARD_GATEWAY_URL,
+    dailyBudgetUsd: env.XMPP_DAILY_BUDGET_USD,
+    facilitatorUrl: env.X402_FACILITATOR_URL,
+    wallet: {
+        agentSecretKey: env.XMPP_AGENT_SECRET_KEY,
+        smartAccountContractId: env.XMPP_SMART_ACCOUNT_CONTRACT_ID,
+        smartAccountWasmHash: env.XMPP_SMART_ACCOUNT_WASM_HASH,
+        webauthnVerifierAddress: env.XMPP_WEBAUTHN_VERIFIER_ADDRESS,
+        ed25519VerifierAddress: env.XMPP_ED25519_VERIFIER_ADDRESS,
+        spendingLimitPolicyAddress: env.XMPP_SPENDING_LIMIT_POLICY_ADDRESS,
+        thresholdPolicyAddress: env.XMPP_THRESHOLD_POLICY_ADDRESS,
+    },
+    x402: {
+        facilitatorUrl: env.X402_FACILITATOR_URL,
+        facilitatorApiKey: env.X402_FACILITATOR_API_KEY,
+        maxTransactionFeeStroops: env.X402_MAX_TRANSACTION_FEE_STROOPS,
+        facilitatorPrivateKey: env.FACILITATOR_STELLAR_PRIVATE_KEY,
+        recipientAddress: env.X402_RECIPIENT_ADDRESS,
+    },
+    mpp: {
+        secretKey: env.MPP_SECRET_KEY,
+        recipientAddress: env.MPP_RECIPIENT_ADDRESS,
+        channelContractId: env.MPP_CHANNEL_CONTRACT_ID,
+        feeSponsorshipEnabled: mppFeeSponsorshipEnabled,
+        feeSponsorship: {
+            chargeEnabled: mppChargeFeeSponsorshipEnabled,
+            sessionEnabled: mppSessionFeeSponsorshipEnabled,
+        },
+        feeSponsorSecretKey: env.XMPP_MPP_FEE_SPONSOR_SECRET_KEY,
+        feeBumpSecretKey: env.XMPP_MPP_FEE_BUMP_SECRET_KEY,
+    },
+    services: {
+        research: env.XMPP_RESEARCH_API_URL,
+        market: env.XMPP_MARKET_API_URL,
+        stream: env.XMPP_STREAM_API_URL,
+    },
+    contracts: {
+        policyContractId: env.XMPP_POLICY_CONTRACT_ID,
+        sessionRegistryContractId: env.XMPP_SESSION_REGISTRY_CONTRACT_ID,
+    },
+};

package/dist/contract-runtime/src/index.d.ts

@@ -0,0 +1,44 @@
+import type { RouteKind, XmppAgentPolicySnapshot, XmppContractAgentTreasuryState, XmppContractTreasurySnapshot, XmppSessionRecord } from '@xmpp/types';
+export type PolicyRuntimeSnapshot = {
+    source: 'local' | 'contract' | 'fallback';
+    pauseFlag: boolean;
+    globalPolicy: {
+        maxSpendUsdCents: number;
+        allowUnknownServices: boolean;
+        allowPostAutopay: boolean;
+    } | null;
+    servicePolicy: {
+        serviceId: string;
+        enabled: boolean;
+        maxSpendUsdCents: number;
+        preferredRoute: string;
+        allowSessionReuse: boolean;
+    } | null;
+};
+export type AgentPolicyRuntimeSnapshot = {
+    source: 'local' | 'contract' | 'fallback';
+    agentPolicy: XmppAgentPolicySnapshot | null;
+};
+export type SessionRouteEventInput = {
+    sessionId: string;
+    serviceId: string;
+    route: RouteKind;
+    status: 'open' | 'reused' | 'closed';
+    callCount: number;
+    receiptId: string;
+    totalAmountUsdCents?: number;
+};
+export declare function getAgentPolicySnapshot(agentId: string): Promise<AgentPolicyRuntimeSnapshot>;
+export declare function listAgentPolicySnapshots(): Promise<XmppAgentPolicySnapshot[]>;
+export declare function getTreasurySnapshot(): Promise<XmppContractTreasurySnapshot | null>;
+export declare function getAgentTreasuryState(agentId: string): Promise<XmppContractAgentTreasuryState | null>;
+export declare function listAgentTreasuryStates(): Promise<XmppContractAgentTreasuryState[]>;
+export declare function getPolicyRuntimeSnapshot(serviceId?: string): Promise<PolicyRuntimeSnapshot>;
+export declare function recordTreasurySpend(input: {
+    agentId: string;
+    serviceId: string;
+    route: RouteKind;
+    amountUsdCents: number;
+}): Promise<XmppContractAgentTreasuryState | null>;
+export declare function recordSessionRouteEvent(input: SessionRouteEventInput): Promise<XmppSessionRecord | null>;
+export declare function listAgentSessions(): Promise<XmppSessionRecord[]>;

package/dist/contract-runtime/src/index.js

@@ -0,0 +1,364 @@
+import { Keypair } from '@stellar/stellar-sdk';
+import { Client, basicNodeSigner } from '@stellar/stellar-sdk/contract';
+import { config } from '@xmpp/config';
+import { logger } from '@xmpp/logger';
+let policyClientPromise;
+let sessionRegistryClientPromise;
+let policyClientDisabled = false;
+let sessionRegistryClientDisabled = false;
+function contractRuntimeEnabled() {
+    return process.env.VITEST !== 'true' && process.env.XMPP_DISABLE_CONTRACT_RUNTIME !== 'true';
+}
+function toNumber(value) {
+    return value == null ? 0 : Number(value);
+}
+function normalizeStringList(value) {
+    if (Array.isArray(value)) {
+        return value.map((entry) => String(entry));
+    }
+    if (value && typeof value === 'object' && Symbol.iterator in value) {
+        return [...value].map((entry) => String(entry));
+    }
+    return [];
+}
+function getAgentKeypair() {
+    if (!config.wallet.agentSecretKey) {
+        return null;
+    }
+    try {
+        return Keypair.fromSecret(config.wallet.agentSecretKey);
+    }
+    catch (error) {
+        logger.warn({ error }, '[xMPP] failed to parse agent secret key for contract runtime');
+        return null;
+    }
+}
+function getClientOptions(contractId) {
+    const keypair = getAgentKeypair();
+    if (!keypair) {
+        return null;
+    }
+    return {
+        contractId,
+        rpcUrl: config.rpcUrl,
+        networkPassphrase: config.networkPassphrase,
+        allowHttp: config.rpcUrl.startsWith('http://'),
+        publicKey: keypair.publicKey(),
+        ...basicNodeSigner(keypair, config.networkPassphrase),
+    };
+}
+async function createClient(contractId, label) {
+    const options = getClientOptions(contractId);
+    if (!options) {
+        logger.debug({ label }, '[xMPP] contract runtime disabled because no agent signer is available');
+        return null;
+    }
+    try {
+        return (await Client.from(options));
+    }
+    catch (error) {
+        logger.warn({ error, contractId, label }, '[xMPP] failed to create Soroban contract client');
+        return null;
+    }
+}
+function hasMethod(client, method, label) {
+    if (typeof client[method] === 'function') {
+        return true;
+    }
+    logger.warn({ label, method }, '[xMPP] contract method is unavailable on deployed contract');
+    return false;
+}
+async function getPolicyClient() {
+    if (!contractRuntimeEnabled() || !config.contracts.policyContractId || policyClientDisabled) {
+        return null;
+    }
+    policyClientPromise ??= createClient(config.contracts.policyContractId, 'policy');
+    const client = await policyClientPromise;
+    if (!client) {
+        policyClientDisabled = true;
+        return null;
+    }
+    if (!hasMethod(client, 'get_global_policy', 'policy') || !hasMethod(client, 'pause_flag', 'policy')) {
+        policyClientDisabled = true;
+        return null;
+    }
+    return client;
+}
+async function getSessionRegistryClient() {
+    if (!contractRuntimeEnabled() ||
+        !config.contracts.sessionRegistryContractId ||
+        sessionRegistryClientDisabled) {
+        return null;
+    }
+    sessionRegistryClientPromise ??= createClient(config.contracts.sessionRegistryContractId, 'session-registry');
+    const client = await sessionRegistryClientPromise;
+    if (!client) {
+        sessionRegistryClientDisabled = true;
+        return null;
+    }
+    if (!hasMethod(client, 'upsert_session', 'session-registry')) {
+        sessionRegistryClientDisabled = true;
+        return null;
+    }
+    return client;
+}
+function normalizeGlobalPolicy(policy) {
+    return {
+        maxSpendUsdCents: toNumber(policy.max_spend_usd_cents),
+        allowUnknownServices: policy.allow_unknown_services,
+        allowPostAutopay: policy.allow_post_autopay,
+    };
+}
+function normalizeServicePolicy(policy) {
+    if (!policy) {
+        return null;
+    }
+    return {
+        serviceId: policy.service_id,
+        enabled: policy.enabled,
+        maxSpendUsdCents: toNumber(policy.max_spend_usd_cents),
+        preferredRoute: policy.preferred_route,
+        allowSessionReuse: policy.allow_session_reuse,
+    };
+}
+function normalizeAgentPolicy(policy) {
+    if (!policy) {
+        return null;
+    }
+    return {
+        agentId: policy.agent_id,
+        enabled: policy.enabled,
+        dailyBudgetUsd: toNumber(policy.daily_budget_usd_cents) / 100,
+        allowedServices: normalizeStringList(policy.allowed_services),
+        preferredRoutes: normalizeStringList(policy.preferred_routes),
+        autopayMethods: normalizeStringList(policy.autopay_methods),
+        source: 'contract',
+    };
+}
+function normalizeTreasurySnapshot(snapshot) {
+    if (!snapshot) {
+        return null;
+    }
+    const sharedTreasuryUsd = toNumber(snapshot.shared_treasury_usd_cents) / 100;
+    const totalSpentUsd = toNumber(snapshot.total_spent_usd_cents) / 100;
+    return {
+        sharedTreasuryUsd,
+        totalSpentUsd,
+        remainingUsd: Math.max(0, sharedTreasuryUsd - totalSpentUsd),
+        paymentCount: Number(snapshot.payment_count ?? 0),
+        source: 'contract',
+    };
+}
+function normalizeAgentTreasuryState(state) {
+    if (!state) {
+        return null;
+    }
+    return {
+        agentId: state.agent_id,
+        spentUsd: toNumber(state.spent_usd_cents) / 100,
+        paymentCount: Number(state.payment_count ?? 0),
+        lastServiceId: state.last_service_id,
+        lastRoute: state.last_route,
+        source: 'contract',
+    };
+}
+function normalizeSessionRecord(record) {
+    return {
+        sessionId: String(record.session_id ?? ''),
+        serviceId: String(record.service_id ?? ''),
+        agent: String(record.agent ?? ''),
+        channelContractId: String(record.channel_contract_id ?? ''),
+        route: String(record.route ?? ''),
+        status: String(record.status ?? ''),
+        totalAmountUsdCents: toNumber(record.total_amount_usd_cents),
+        callCount: Number(record.call_count ?? 0),
+        lastReceiptId: String(record.last_receipt_id ?? ''),
+        updatedAtLedger: Number(record.updated_at_ledger ?? 0),
+    };
+}
+export async function getAgentPolicySnapshot(agentId) {
+    const client = await getPolicyClient();
+    if (!client || !hasMethod(client, 'get_agent_policy', 'policy')) {
+        return {
+            source: 'local',
+            agentPolicy: null,
+        };
+    }
+    try {
+        const tx = await client.get_agent_policy({ agent_id: agentId });
+        return {
+            source: 'contract',
+            agentPolicy: normalizeAgentPolicy(tx.result ?? null),
+        };
+    }
+    catch (error) {
+        logger.warn({ error, agentId }, '[xMPP] failed to read agent policy from contract, falling back');
+        return {
+            source: 'fallback',
+            agentPolicy: null,
+        };
+    }
+}
+export async function listAgentPolicySnapshots() {
+    const client = await getPolicyClient();
+    if (!client || !hasMethod(client, 'list_agent_policies', 'policy')) {
+        return [];
+    }
+    try {
+        const tx = await client.list_agent_policies();
+        const result = tx.result;
+        return Array.isArray(result)
+            ? result.filter((entry) => Boolean(entry)).flatMap((entry) => {
+                const normalized = normalizeAgentPolicy(entry);
+                return normalized ? [normalized] : [];
+            })
+            : [];
+    }
+    catch (error) {
+        logger.warn({ error }, '[xMPP] failed to list agent policies from contract');
+        return [];
+    }
+}
+export async function getTreasurySnapshot() {
+    const client = await getPolicyClient();
+    if (!client || !hasMethod(client, 'get_treasury_snapshot', 'policy')) {
+        return null;
+    }
+    try {
+        const tx = await client.get_treasury_snapshot();
+        return normalizeTreasurySnapshot(tx.result ?? null);
+    }
+    catch (error) {
+        logger.warn({ error }, '[xMPP] failed to read treasury snapshot from contract');
+        return null;
+    }
+}
+export async function getAgentTreasuryState(agentId) {
+    const client = await getPolicyClient();
+    if (!client || !hasMethod(client, 'get_agent_treasury_state', 'policy')) {
+        return null;
+    }
+    try {
+        const tx = await client.get_agent_treasury_state({ agent_id: agentId });
+        return normalizeAgentTreasuryState(tx.result ?? null);
+    }
+    catch (error) {
+        logger.warn({ error, agentId }, '[xMPP] failed to read agent treasury state from contract');
+        return null;
+    }
+}
+export async function listAgentTreasuryStates() {
+    const client = await getPolicyClient();
+    if (!client || !hasMethod(client, 'list_agent_treasury_states', 'policy')) {
+        return [];
+    }
+    try {
+        const tx = await client.list_agent_treasury_states();
+        const result = tx.result;
+        return Array.isArray(result)
+            ? result.flatMap((entry) => {
+                const normalized = normalizeAgentTreasuryState(entry);
+                return normalized ? [normalized] : [];
+            })
+            : [];
+    }
+    catch (error) {
+        logger.warn({ error }, '[xMPP] failed to list agent treasury states from contract');
+        return [];
+    }
+}
+export async function getPolicyRuntimeSnapshot(serviceId) {
+    const client = await getPolicyClient();
+    if (!client) {
+        return {
+            source: 'local',
+            pauseFlag: false,
+            globalPolicy: null,
+            servicePolicy: null,
+        };
+    }
+    try {
+        const globalPolicyTx = await client.get_global_policy();
+        const pauseFlagTx = await client.pause_flag();
+        const servicePolicyTx = serviceId && hasMethod(client, 'get_service_policy', 'policy')
+            ? await client.get_service_policy({ service_id: serviceId })
+            : null;
+        return {
+            source: 'contract',
+            pauseFlag: Boolean(pauseFlagTx.result),
+            globalPolicy: normalizeGlobalPolicy(globalPolicyTx.result),
+            servicePolicy: normalizeServicePolicy(servicePolicyTx?.result ?? null),
+        };
+    }
+    catch (error) {
+        logger.warn({ error, serviceId }, '[xMPP] failed to read policy from contract, falling back');
+        return {
+            source: 'fallback',
+            pauseFlag: false,
+            globalPolicy: null,
+            servicePolicy: null,
+        };
+    }
+}
+export async function recordTreasurySpend(input) {
+    const client = await getPolicyClient();
+    if (!client || !hasMethod(client, 'record_treasury_spend', 'policy')) {
+        return null;
+    }
+    try {
+        const tx = await client.record_treasury_spend({
+            agent_id: input.agentId,
+            service_id: input.serviceId,
+            route: input.route,
+            amount_usd_cents: BigInt(input.amountUsdCents),
+        });
+        const sent = await tx.signAndSend();
+        return normalizeAgentTreasuryState(sent.result);
+    }
+    catch (error) {
+        logger.warn({ error, input }, '[xMPP] failed to record treasury spend in contract');
+        return null;
+    }
+}
+export async function recordSessionRouteEvent(input) {
+    const client = await getSessionRegistryClient();
+    const keypair = getAgentKeypair();
+    if (!client || !keypair) {
+        return null;
+    }
+    try {
+        const tx = await client.upsert_session({
+            agent: keypair.publicKey(),
+            session_id: input.sessionId,
+            service_id: input.serviceId,
+            channel_contract_id: config.mpp.channelContractId ?? '',
+            route: input.route,
+            total_amount_usd_cents: BigInt(input.totalAmountUsdCents ?? 0),
+            call_count: input.callCount,
+            last_receipt_id: input.receiptId,
+            status: input.status,
+        });
+        const sent = await tx.signAndSend();
+        return normalizeSessionRecord(sent.result);
+    }
+    catch (error) {
+        logger.warn({ error, input }, '[xMPP] failed to write session route event to contract');
+        return null;
+    }
+}
+export async function listAgentSessions() {
+    const client = await getSessionRegistryClient();
+    const keypair = getAgentKeypair();
+    if (!client || !keypair || !hasMethod(client, 'list_agent_sessions', 'session-registry')) {
+        return [];
+    }
+    try {
+        const tx = await client.list_agent_sessions({ agent: keypair.publicKey() });
+        const result = tx.result;
+        return Array.isArray(result) ? result.map(normalizeSessionRecord) : [];
+    }
+    catch (error) {
+        logger.warn({ error }, '[xMPP] failed to list agent sessions from contract');
+        return [];
+    }
+}

package/dist/logger/src/index.d.ts

@@ -0,0 +1,2 @@
+import pino from 'pino';
+export declare const logger: pino.Logger<never, boolean>;

package/dist/logger/src/index.js

@@ -0,0 +1,18 @@
+import pino from 'pino';
+export const logger = pino({
+    name: 'xmpp',
+    level: process.env.LOG_LEVEL ?? 'info',
+    redact: {
+        paths: [
+            'req.headers.authorization',
+            'req.headers.x-api-key',
+            'req.headers.cookie',
+            'req.body.headers.authorization',
+            'req.body.headers.x-api-key',
+            'req.body.options.idempotencyKey',
+            'err.config.headers.authorization',
+            'err.config.headers.x-api-key',
+        ],
+        censor: '[REDACTED]',
+    },
+});

package/dist/policy-engine/src/index.d.ts

@@ -0,0 +1,8 @@
+import type { PolicyDecision } from '@xmpp/types';
+export declare function isAllowedDomain(url: string): boolean;
+export declare function evaluatePolicy(url: string): PolicyDecision;
+export declare function evaluatePolicyForRequest(input: {
+    url: string;
+    method?: string;
+    serviceId?: string;
+}): Promise<PolicyDecision>;

package/dist/policy-engine/src/index.js

@@ -0,0 +1,90 @@
+import { getPolicyRuntimeSnapshot } from '@xmpp/contract-runtime';
+const allowedHosts = new Set(['localhost', '127.0.0.1']);
+const blockedPathPrefixes = ['/admin', '/internal', '/unsafe'];
+export function isAllowedDomain(url) {
+    const parsed = new URL(url);
+    return allowedHosts.has(parsed.hostname);
+}
+export function evaluatePolicy(url) {
+    const parsed = new URL(url);
+    if (!allowedHosts.has(parsed.hostname)) {
+        return {
+            allowed: false,
+            reason: 'xMPP policy allows automatic payment only to approved local demo hosts.',
+            code: 'blocked-domain',
+        };
+    }
+    if (blockedPathPrefixes.some((prefix) => parsed.pathname.startsWith(prefix))) {
+        return {
+            allowed: false,
+            reason: 'xMPP policy blocks sensitive admin or unsafe routes from automatic payment.',
+            code: 'blocked-path',
+        };
+    }
+    return {
+        allowed: true,
+        reason: 'xMPP policy approved this request for automatic payment routing.',
+        code: 'allowed',
+        source: 'local',
+    };
+}
+export async function evaluatePolicyForRequest(input) {
+    const localDecision = evaluatePolicy(input.url);
+    if (!localDecision.allowed) {
+        return localDecision;
+    }
+    const runtime = await getPolicyRuntimeSnapshot(input.serviceId);
+    if (runtime.pauseFlag) {
+        return {
+            allowed: false,
+            reason: 'xMPP policy contract is paused for automatic payment execution.',
+            code: 'paused',
+            source: runtime.source,
+        };
+    }
+    const method = (input.method ?? 'GET').toUpperCase();
+    if (method !== 'GET' && input.serviceId == null) {
+        return {
+            allowed: false,
+            reason: 'xMPP requires an explicit service id before automatic payment can proceed on non-GET requests.',
+            code: 'blocked-service',
+            source: runtime.source,
+        };
+    }
+    if (method !== 'GET' && runtime.globalPolicy == null) {
+        return {
+            allowed: false,
+            reason: 'xMPP blocks automatic payment on non-GET routes unless policy explicitly enables it.',
+            code: 'blocked-method',
+            source: runtime.source,
+        };
+    }
+    if (method !== 'GET' && runtime.globalPolicy && !runtime.globalPolicy.allowPostAutopay) {
+        return {
+            allowed: false,
+            reason: 'xMPP policy blocks automatic payment on non-GET routes unless explicitly enabled.',
+            code: 'blocked-method',
+            source: runtime.source,
+        };
+    }
+    if (input.serviceId == null && runtime.globalPolicy && !runtime.globalPolicy.allowUnknownServices) {
+        return {
+            allowed: false,
+            reason: 'xMPP policy requires a known service id before automatic payment can proceed.',
+            code: 'blocked-service',
+            source: runtime.source,
+        };
+    }
+    if (runtime.servicePolicy && !runtime.servicePolicy.enabled) {
+        return {
+            allowed: false,
+            reason: 'xMPP service policy disabled automatic payment for this service.',
+            code: 'blocked-service',
+            source: runtime.source,
+        };
+    }
+    return {
+        ...localDecision,
+        source: runtime.source,
+    };
+}

package/dist/policy-engine/src/index.test.d.ts

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

package/dist/policy-engine/src/index.test.js

@@ -0,0 +1,21 @@
+import { describe, expect, it } from 'vitest';
+import { evaluatePolicy, isAllowedDomain } from './index.js';
+describe('policy engine', () => {
+    it('allows local demo services', () => {
+        expect(isAllowedDomain('http://localhost:4101/research?q=stellar')).toBe(true);
+        expect(evaluatePolicy('http://localhost:4101/research?q=stellar')).toMatchObject({ allowed: true, code: 'allowed' });
+    });
+    it('blocks non-local domains', () => {
+        expect(isAllowedDomain('https://example.com/paid')).toBe(false);
+        expect(evaluatePolicy('https://example.com/paid')).toMatchObject({
+            allowed: false,
+            code: 'blocked-domain',
+        });
+    });
+    it('blocks unsafe local admin routes', () => {
+        expect(evaluatePolicy('http://localhost:4102/admin/export')).toMatchObject({
+            allowed: false,
+            code: 'blocked-path',
+        });
+    });
+});

package/dist/types/src/index.d.ts

@@ -0,0 +1,343 @@
+export type RouteKind = 'x402' | 'mpp-charge' | 'mpp-session-open' | 'mpp-session-reuse';
+export type PaymentExecutionMode = 'mock' | 'testnet';
+export type PaymentExecutionStatus = 'mock-paid' | 'ready-for-testnet' | 'settled-testnet' | 'missing-config';
+export type RouteContext = {
+    url: string;
+    method: string;
+    serviceId?: string;
+    projectedRequests?: number;
+    streaming?: boolean;
+};
+export type ServiceCatalogEntry = {
+    serviceId: string;
+    displayName: string;
+    description: string;
+    baseUrl: string;
+    source?: 'static' | 'discovered' | 'hybrid' | 'fallback';
+    capabilities: {
+        x402: boolean;
+        mppCharge: boolean;
+        mppSession: boolean;
+    };
+    pricing: {
+        x402PerCallUsd: number;
+        mppChargePerCallUsd: number;
+        mppSessionOpenUsd: number;
+        mppSessionPerCallUsd: number;
+    };
+    routingHints: {
+        breakEvenCalls: number;
+        streamingPreferred: boolean;
+        preferredSingleCall: Extract<RouteKind, 'x402' | 'mpp-charge'>;
+    };
+};
+export type RouteScoreBreakdown = {
+    route: RouteKind;
+    supported: boolean;
+    estimatedTotalUsd: number;
+    savingsVsNaiveUsd: number;
+    totalScore: number;
+    reasons: string[];
+};
+export type RouteDecision = {
+    route: RouteKind;
+    reason: string;
+    score: number;
+    projectedRequests?: number;
+    estimatedTotalUsd?: number;
+    savingsVsNaiveUsd?: number;
+    service?: ServiceCatalogEntry;
+    breakdown?: RouteScoreBreakdown[];
+};
+export type ChallengeKind = 'x402' | 'mpp-charge' | 'mpp-session';
+export type PaymentChallenge = {
+    kind: ChallengeKind;
+    service: string;
+    amountUsd: number;
+    asset: 'USDC_TESTNET';
+    retryHeaderName: string;
+    retryHeaderValue: string;
+    sessionId?: string;
+};
+export type XmppFetchOptions = Omit<RouteContext, 'url' | 'method'> & {
+    agentId?: string;
+    maxAutoPayUsd?: number;
+    idempotencyKey?: string;
+};
+export type XmppAgentProfile = {
+    agentId: string;
+    displayName: string;
+    role: 'shared' | 'research' | 'market';
+    description: string;
+    dailyBudgetUsd: number;
+    allowedServices: string[];
+    preferredRoutes: RouteKind[];
+    autopayMethods: string[];
+    enabled?: boolean;
+    policySource?: 'local' | 'contract' | 'fallback' | 'merged';
+};
+export type XmppSignedReceipt = {
+    receiptId: string;
+    issuedAt: string;
+    network: string;
+    agent: string;
+    serviceId: string;
+    url: string;
+    method: string;
+    route: RouteKind;
+    amountUsd: number;
+    txHash?: string;
+    explorerUrl?: string;
+    paymentReference?: string;
+    signature: string;
+};
+export type XmppSmartAccountExecution = {
+    configured: boolean;
+    preferred: boolean;
+    supported: boolean;
+    used: boolean;
+    contractId?: string | null;
+    fallbackReason?: string;
+};
+export type PaymentExecutionMetadata = {
+    mode: PaymentExecutionMode;
+    status: PaymentExecutionStatus;
+    route: RouteKind;
+    receiptId: string;
+    missingConfig?: string[];
+    evidenceHeaders?: Record<string, string>;
+    signedReceipt?: XmppSignedReceipt;
+    settlementStrategy?: 'keypair' | 'smart-account' | 'keypair-fallback';
+    executionNote?: string;
+    feeSponsored?: boolean;
+    feeSponsorPublicKey?: string;
+    feeBumpPublicKey?: string;
+    smartAccount?: XmppSmartAccountExecution;
+};
+export type PolicyDecision = {
+    allowed: boolean;
+    reason: string;
+    code: 'allowed' | 'blocked-domain' | 'blocked-path' | 'blocked-method' | 'blocked-service' | 'blocked-agent' | 'blocked-budget' | 'blocked-idempotency' | 'paused';
+    source?: 'local' | 'contract' | 'fallback';
+};
+export type PaymentExecutionResult = {
+    response: Response;
+    metadata: PaymentExecutionMetadata;
+};
+export type XmppFetchMetadata = {
+    route: RouteKind;
+    challenge?: PaymentChallenge;
+    retried: boolean;
+    execution?: PaymentExecutionMetadata;
+    policy?: PolicyDecision;
+    budget?: XmppBudgetSnapshot;
+    idempotentReplay?: boolean;
+};
+export type XmppSessionRecord = {
+    sessionId: string;
+    serviceId: string;
+    agent: string;
+    channelContractId: string;
+    route: string;
+    status: string;
+    totalAmountUsdCents: number;
+    callCount: number;
+    lastReceiptId: string;
+    updatedAtLedger: number;
+};
+export type WorkflowEstimateStep = {
+    url: string;
+    method?: string;
+    serviceId?: string;
+    projectedRequests: number;
+    streaming?: boolean;
+};
+export type WorkflowEstimateLineItem = {
+    serviceId: string;
+    displayName: string;
+    route: RouteKind;
+    projectedRequests: number;
+    estimatedCostUsd: number;
+    savingsVsNaiveUsd: number;
+    reason: string;
+};
+export type WorkflowEstimateResult = {
+    totalEstimatedCostUsd: number;
+    naiveX402CostUsd: number;
+    savingsVsNaiveUsd: number;
+    breakdown: WorkflowEstimateLineItem[];
+};
+export type XmppBudgetSnapshot = {
+    agentId: string;
+    agentDisplayName: string;
+    agentSpentThisSessionUsd: number;
+    agentRemainingDailyBudgetUsd: number;
+    spentThisSessionUsd: number;
+    remainingDailyBudgetUsd: number;
+    callsThisService: number;
+    projectedCostIfRepeated5xUsd: number;
+    recommendation: string;
+};
+export type XmppRouteEvent = {
+    id: string;
+    timestamp: string;
+    agentId: string;
+    url: string;
+    method: string;
+    serviceId: string;
+    route: RouteKind;
+    status: 'settled' | 'denied' | 'preview';
+    amountUsd: number;
+    projectedRequests: number;
+    policyCode?: PolicyDecision['code'];
+    receiptId?: string;
+    txHash?: string;
+    explorerUrl?: string;
+    sessionId?: string;
+    signedReceipt?: XmppSignedReceipt;
+    feeSponsored?: boolean;
+    feeSponsorPublicKey?: string;
+    settlementStrategy?: PaymentExecutionMetadata['settlementStrategy'];
+    executionNote?: string;
+};
+export type XmppAgentStateSummary = {
+    agentId: string;
+    displayName: string;
+    role: XmppAgentProfile['role'];
+    description: string;
+    dailyBudgetUsd: number;
+    spentThisSessionUsd: number;
+    remainingDailyBudgetUsd: number;
+    routeCounts: Record<RouteKind, number>;
+    allowedServices: string[];
+    preferredRoutes: RouteKind[];
+    enabled?: boolean;
+    policySource?: XmppAgentProfile['policySource'];
+    autopayMethods?: string[];
+};
+export type XmppAgentPolicySnapshot = {
+    agentId: string;
+    enabled: boolean;
+    dailyBudgetUsd: number;
+    allowedServices: string[];
+    preferredRoutes: RouteKind[];
+    autopayMethods: string[];
+    source: 'contract' | 'local' | 'fallback';
+};
+export type XmppContractTreasurySnapshot = {
+    sharedTreasuryUsd: number;
+    totalSpentUsd: number;
+    remainingUsd: number;
+    paymentCount: number;
+    source: 'contract' | 'local' | 'fallback';
+};
+export type XmppContractAgentTreasuryState = {
+    agentId: string;
+    spentUsd: number;
+    paymentCount: number;
+    lastServiceId: string;
+    lastRoute: string;
+    source: 'contract' | 'local' | 'fallback';
+};
+export type XmppOperatorState = {
+    sharedTreasuryUsd: number;
+    sharedTreasuryRemainingUsd: number;
+    dailyBudgetUsd: number;
+    spentThisSessionUsd: number;
+    remainingDailyBudgetUsd: number;
+    sessionSavingsUsd: number;
+    routeCounts: Record<RouteKind, number>;
+    serviceSpendUsd: Record<string, number>;
+    serviceCallCounts: Record<string, number>;
+    agentProfiles: XmppAgentProfile[];
+    agentStates: XmppAgentStateSummary[];
+    contractAgentPolicies?: XmppAgentPolicySnapshot[];
+    contractTreasury?: XmppContractTreasurySnapshot | null;
+    contractAgentTreasuryStates?: XmppContractAgentTreasuryState[];
+    openSessions: Array<Pick<XmppSessionRecord, 'sessionId' | 'serviceId' | 'callCount'>>;
+    recentEvents: XmppRouteEvent[];
+};
+export type XmppReceiptVerificationResult = {
+    valid: boolean;
+    agent: string;
+    receiptId: string;
+};
+export type XmppWalletInfo = {
+    connected: boolean;
+    paymentExecutionMode: PaymentExecutionMode;
+    network: string;
+    rpcUrl: string;
+    agentPublicKey: string | null;
+    settlementStrategy: 'smart-account-ready' | 'smart-account-x402-preferred' | 'smart-account-partial-fallback' | 'keypair-live';
+    smartAccount: {
+        ready: boolean;
+        mode: 'inactive' | 'x402-only' | 'full';
+        routeCoverage: 'inactive' | 'x402-only';
+        demoReady: boolean;
+        guardedFallback: boolean;
+        contractId: string | null;
+        wasmHash: string;
+        webauthnVerifierAddress: string;
+        ed25519VerifierAddress: string;
+        spendingLimitPolicyAddress: string;
+        thresholdPolicyAddress: string;
+        preferredRoutes: RouteKind[];
+        fallbackRoutes: RouteKind[];
+        supportedRoutes: RouteKind[];
+        unsupportedRoutes: RouteKind[];
+        unsupportedReason: string | null;
+        configuredMaxTransactionFeeStroops: number;
+        effectiveMaxTransactionFeeStroops: number;
+        feeFloorApplied: boolean;
+        preflightFailures: string[];
+        coverageMessage: string;
+        message: string;
+        operatorNotes: string[];
+    };
+    feeSponsorship: {
+        enabled: boolean;
+        available: boolean;
+        mppChargeEnabled: boolean;
+        mppSessionEnabled: boolean;
+        sponsorPublicKey: string | null;
+        feeBumpPublicKey: string | null;
+        message: string;
+    };
+    missingSecrets: string[];
+    message: string;
+};
+export type XmppHealthStatus = {
+    ok: boolean;
+    service: string;
+    network: string;
+    paymentExecutionMode: PaymentExecutionMode;
+    services: Record<string, string>;
+    smartAccount: {
+        configured: boolean;
+        routeCoverage: 'inactive' | 'x402-only';
+        x402Preferred: boolean;
+        mppFallback: boolean;
+        demoReady: boolean;
+        guardedFallback: boolean;
+        unsupportedRoutes: RouteKind[];
+        unsupportedReason: string | null;
+        configuredMaxTransactionFeeStroops: number;
+        effectiveMaxTransactionFeeStroops: number;
+        feeFloorApplied: boolean;
+        preflightFailures: string[];
+    };
+};
+export type XmppCatalogResponse = {
+    services: ServiceCatalogEntry[];
+};
+export type XmppPolicyPreviewResponse = {
+    policy: PolicyDecision;
+    routePreview: RouteDecision;
+};
+export type XmppGatewayFetchResponse = {
+    status: number;
+    routePreview: RouteDecision;
+    payment?: XmppFetchMetadata;
+    responseHeaders: Record<string, string>;
+    body: unknown;
+};

package/dist/types/src/index.js

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

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@vinaystwt/xmpp-policy-engine",
+  "version": "0.1.0",
+  "description": "Service, budget, agent, and contract-aware policy evaluation for xMPP.",
+  "type": "module",
+  "license": "MIT",
+  "main": "dist/policy-engine/src/index.js",
+  "types": "dist/policy-engine/src/index.d.ts",
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "homepage": "https://github.com/Vinaystwt/xMPP#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Vinaystwt/xMPP.git",
+    "directory": "packages/policy-engine"
+  },
+  "bugs": {
+    "url": "https://github.com/Vinaystwt/xMPP/issues"
+  },
+  "keywords": [
+    "xmpp",
+    "policy",
+    "stellar",
+    "agents"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/policy-engine/src/index.d.ts",
+      "import": "./dist/policy-engine/src/index.js",
+      "default": "./dist/policy-engine/src/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "lint": "eslint src",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run --passWithNoTests"
+  },
+  "dependencies": {
+    "@vinaystwt/xmpp-contract-runtime": "0.1.0",
+    "@vinaystwt/xmpp-types": "0.1.0"
+  }
+}