@vallum/manifest 0.0.0-prerelease

package/README.md

@@ -0,0 +1,8 @@
+# @vallum/manifest
+
+Versioned Agent Transaction Manifest schema and validator for Vallum.
+
+This package represents an agent action before policy or chain execution. It
+validates structure, required fields, expiry, budget, idempotency, simulation,
+human mandate, and receipt requirements. It does not make policy decisions,
+execute transactions, or carry secrets/private keys.

package/dist/ap2Mapping.d.ts

@@ -0,0 +1,69 @@
+import { type AgentTransactionManifest, type ManifestParty } from "./schema.js";
+export declare const AP2_CHECKOUT_MANDATE_VCT: "mandate.checkout.1";
+export declare const AP2_PAYMENT_MANDATE_VCT: "mandate.payment.1";
+export interface AP2Merchant {
+    readonly id: string;
+    readonly name: string;
+    readonly website?: string;
+}
+export interface AP2Amount {
+    readonly amount: number;
+    readonly currency: string;
+}
+export interface AP2PaymentInstrument {
+    readonly id: string;
+    readonly type: string;
+    readonly description?: string;
+}
+export interface AP2CheckoutMandate {
+    readonly vct: string;
+    readonly checkout_jwt: string;
+    readonly checkout_hash: string;
+    readonly iat?: number;
+    readonly exp?: number;
+}
+export interface AP2PaymentMandate {
+    readonly vct: string;
+    readonly transaction_id: string;
+    readonly payment_mandate_id?: string;
+    readonly payee: AP2Merchant;
+    readonly payment_amount: AP2Amount;
+    readonly payment_instrument: AP2PaymentInstrument;
+    readonly execution_date?: string;
+    readonly risk_data?: Record<string, unknown>;
+    readonly iat?: number;
+    readonly exp?: number;
+}
+export interface AP2TrustedSurface {
+    readonly id: string;
+    readonly nonAgentic: boolean;
+}
+export interface AP2MandateBundle {
+    readonly mode: "direct" | "autonomous";
+    readonly checkoutMandate: AP2CheckoutMandate;
+    readonly paymentMandate: AP2PaymentMandate;
+    readonly trustedSurface: AP2TrustedSurface;
+    readonly disputeEvidenceReference?: string;
+}
+export interface AP2ManifestMappingContext {
+    readonly agent: ManifestParty;
+    readonly owner: ManifestParty;
+    readonly wallet?: AgentTransactionManifest["wallet"];
+    readonly packageId: string;
+    readonly module?: string;
+    readonly functionName: string;
+    readonly templateId?: string;
+    readonly templateVersion?: string;
+    readonly displayName?: string;
+    readonly maxGasBudget: number;
+    readonly idempotencyKey: string;
+    readonly now?: Date;
+    readonly simulationHash?: string;
+}
+export type AP2MappingErrorCode = "UNSUPPORTED_AP2_MANDATE_VERSION" | "TRUSTED_SURFACE_MUST_BE_NON_AGENTIC" | "MANDATE_REFERENCE_MISMATCH" | "AP2_MANDATE_EXPIRED" | "INVALID_AP2_MANDATE";
+export declare class AP2MappingError extends Error {
+    readonly code: AP2MappingErrorCode;
+    constructor(code: AP2MappingErrorCode, message: string);
+}
+export declare function mapAP2MandatesToManifest(bundle: AP2MandateBundle, context: AP2ManifestMappingContext): AgentTransactionManifest;
+export declare function ap2PaymentMandateId(mandate: AP2PaymentMandate): string;

package/dist/ap2Mapping.js

@@ -0,0 +1,130 @@
+import { AGENT_TRANSACTION_MANIFEST_VERSION, } from "./schema.js";
+export const AP2_CHECKOUT_MANDATE_VCT = "mandate.checkout.1";
+export const AP2_PAYMENT_MANDATE_VCT = "mandate.payment.1";
+export class AP2MappingError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "AP2MappingError";
+    }
+}
+export function mapAP2MandatesToManifest(bundle, context) {
+    validateBundle(bundle, context.now ?? new Date());
+    const action = {
+        packageId: context.packageId,
+        ...(context.module ? { module: context.module } : {}),
+        functionName: context.functionName,
+        ...(context.templateId ? { templateId: context.templateId } : {}),
+        ...(context.templateVersion ? { templateVersion: context.templateVersion } : {}),
+        ...(context.displayName ? { displayName: context.displayName } : {}),
+    };
+    const paymentId = ap2PaymentMandateId(bundle.paymentMandate);
+    return {
+        version: AGENT_TRANSACTION_MANIFEST_VERSION,
+        agent: context.agent,
+        owner: context.owner,
+        ...(context.wallet ? { wallet: context.wallet } : {}),
+        intent: `Execute AP2 payment mandate ${paymentId} for checkout ${bundle.checkoutMandate.checkout_hash}`,
+        spend: {
+            maxGasBudget: context.maxGasBudget,
+            maxPayment: {
+                amount: String(bundle.paymentMandate.payment_amount.amount),
+                asset: bundle.paymentMandate.payment_amount.currency,
+            },
+        },
+        action,
+        counterparty: {
+            id: `ap2:${bundle.paymentMandate.payee.id}`,
+        },
+        scope: [
+            "standard:ap2",
+            `ap2:mode:${bundle.mode}`,
+            `ap2:checkout:${bundle.checkoutMandate.checkout_hash}`,
+            `ap2:payment:${paymentId}`,
+            "ap2:trusted-surface:non-agentic",
+        ],
+        expiresAt: expiryFor(bundle).toISOString(),
+        idempotencyKey: context.idempotencyKey,
+        simulation: {
+            required: true,
+            status: "passed",
+            hash: context.simulationHash ?? "sha256:ap2-mock-simulation",
+        },
+        receipt: {
+            required: true,
+            templateId: "receipt:ap2:v1",
+        },
+        humanMandate: {
+            required: true,
+            mandateId: paymentId,
+        },
+        refundPolicy: {
+            type: "refund_to_owner",
+        },
+        metadata: {
+            ap2CheckoutMandateVct: bundle.checkoutMandate.vct,
+            ap2PaymentMandateVct: bundle.paymentMandate.vct,
+            ap2Mode: bundle.mode,
+            ap2CheckoutHash: bundle.checkoutMandate.checkout_hash,
+            ap2PaymentMandateId: paymentId,
+            ap2PaymentTransactionId: bundle.paymentMandate.transaction_id,
+            ap2PayeeId: bundle.paymentMandate.payee.id,
+            ap2TrustedSurfaceId: bundle.trustedSurface.id,
+            ap2TrustedSurfaceNonAgentic: String(bundle.trustedSurface.nonAgentic),
+            ...(bundle.disputeEvidenceReference ? { ap2DisputeEvidenceReference: bundle.disputeEvidenceReference } : {}),
+        },
+    };
+}
+export function ap2PaymentMandateId(mandate) {
+    return mandate.payment_mandate_id ?? mandate.transaction_id;
+}
+function validateBundle(bundle, now) {
+    if (bundle.checkoutMandate.vct !== AP2_CHECKOUT_MANDATE_VCT) {
+        throw new AP2MappingError("UNSUPPORTED_AP2_MANDATE_VERSION", `Unsupported AP2 mandate version: ${bundle.checkoutMandate.vct}.`);
+    }
+    if (bundle.paymentMandate.vct !== AP2_PAYMENT_MANDATE_VCT) {
+        throw new AP2MappingError("UNSUPPORTED_AP2_MANDATE_VERSION", `Unsupported AP2 mandate version: ${bundle.paymentMandate.vct}.`);
+    }
+    if (bundle.trustedSurface.nonAgentic !== true) {
+        throw new AP2MappingError("TRUSTED_SURFACE_MUST_BE_NON_AGENTIC", "AP2 Trusted Surface must be represented as non-agentic.");
+    }
+    if (bundle.paymentMandate.transaction_id !== bundle.checkoutMandate.checkout_hash) {
+        throw new AP2MappingError("MANDATE_REFERENCE_MISMATCH", "AP2 payment mandate transaction_id must match the checkout mandate hash.");
+    }
+    validateRequiredFields(bundle);
+    if (expiryFor(bundle).getTime() <= now.getTime()) {
+        throw new AP2MappingError("AP2_MANDATE_EXPIRED", "AP2 mandate expiry is in the past.");
+    }
+}
+function validateRequiredFields(bundle) {
+    requireNonEmpty(bundle.checkoutMandate.checkout_jwt, "checkoutMandate.checkout_jwt");
+    requireNonEmpty(bundle.checkoutMandate.checkout_hash, "checkoutMandate.checkout_hash");
+    requireNonEmpty(bundle.paymentMandate.transaction_id, "paymentMandate.transaction_id");
+    requireNonEmpty(bundle.paymentMandate.payee?.id, "paymentMandate.payee.id");
+    requireNonEmpty(bundle.paymentMandate.payee?.name, "paymentMandate.payee.name");
+    requireNonEmpty(bundle.paymentMandate.payment_instrument?.id, "paymentMandate.payment_instrument.id");
+    requireNonEmpty(bundle.paymentMandate.payment_instrument?.type, "paymentMandate.payment_instrument.type");
+    requireNonEmpty(bundle.paymentMandate.payment_amount?.currency, "paymentMandate.payment_amount.currency");
+    if (typeof bundle.paymentMandate.payment_amount?.amount !== "number" ||
+        !Number.isInteger(bundle.paymentMandate.payment_amount.amount) ||
+        bundle.paymentMandate.payment_amount.amount < 0) {
+        throw new AP2MappingError("INVALID_AP2_MANDATE", "AP2 payment amount must be a non-negative integer.");
+    }
+    if (!/^[A-Z]{3}$/.test(bundle.paymentMandate.payment_amount.currency)) {
+        throw new AP2MappingError("INVALID_AP2_MANDATE", "AP2 payment currency must be an ISO-4217 code.");
+    }
+}
+function expiryFor(bundle) {
+    const expiries = [bundle.checkoutMandate.exp, bundle.paymentMandate.exp]
+        .filter((value) => typeof value === "number" && Number.isFinite(value));
+    if (expiries.length === 0) {
+        throw new AP2MappingError("INVALID_AP2_MANDATE", "AP2 mandates must include an expiry.");
+    }
+    return new Date(Math.min(...expiries) * 1000);
+}
+function requireNonEmpty(value, path) {
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new AP2MappingError("INVALID_AP2_MANDATE", `AP2 mandate field ${path} is required.`);
+    }
+}

package/dist/fixtures.d.ts

@@ -0,0 +1,2 @@
+import { type AgentTransactionManifest } from "./schema.js";
+export declare function validManifestFixture(): AgentTransactionManifest;

package/dist/fixtures.js

@@ -0,0 +1,58 @@
+import { AGENT_TRANSACTION_MANIFEST_VERSION } from "./schema.js";
+export function validManifestFixture() {
+    return {
+        version: AGENT_TRANSACTION_MANIFEST_VERSION,
+        agent: {
+            id: "agent:quote-bot",
+            address: "0x1111111111111111111111111111111111111111111111111111111111111111",
+        },
+        owner: {
+            id: "owner:alice",
+        },
+        wallet: {
+            walletId: "wallet_demo_1",
+            signerRef: "signer_ref_demo_1",
+        },
+        intent: "Open a verifier-release escrow for quote fulfillment.",
+        spend: {
+            maxGasBudget: 50_000_000,
+            maxPayment: {
+                amount: "10.00",
+                asset: "USD",
+            },
+        },
+        action: {
+            packageId: "0x2222222222222222222222222222222222222222222222222222222222222222",
+            module: "escrow",
+            functionName: "open_escrow",
+            templateId: "escrow_v1",
+            templateVersion: "1.0.0",
+            displayName: "Open escrow",
+        },
+        counterparty: {
+            id: "provider:quote-service",
+            address: "0x3333333333333333333333333333333333333333333333333333333333333333",
+        },
+        scope: ["contract:escrow", "action:open_escrow"],
+        expiresAt: "2026-06-10T13:00:00.000Z",
+        idempotencyKey: "idem_quote_bot_20260610_0001",
+        simulation: {
+            required: true,
+            status: "passed",
+            hash: "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+        },
+        receipt: {
+            required: true,
+            templateId: "receipt:escrow:v1",
+        },
+        humanMandate: {
+            required: false,
+        },
+        refundPolicy: {
+            type: "refund_to_owner",
+        },
+        metadata: {
+            purpose: "test-fixture",
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./ap2Mapping.js";
+export * from "./fixtures.js";
+export * from "./schema.js";
+export * from "./validate.js";
+export * from "./x402Mapping.js";

package/dist/index.js

@@ -0,0 +1,5 @@
+export * from "./ap2Mapping.js";
+export * from "./fixtures.js";
+export * from "./schema.js";
+export * from "./validate.js";
+export * from "./x402Mapping.js";

package/dist/schema.d.ts

@@ -0,0 +1,55 @@
+export declare const AGENT_TRANSACTION_MANIFEST_VERSION: "agent-tx-manifest/v1";
+export interface ManifestParty {
+    readonly id: string;
+    readonly address?: string;
+}
+export interface ManifestSpend {
+    readonly maxGasBudget: number;
+    readonly maxPayment?: {
+        readonly amount: string;
+        readonly asset: string;
+    };
+}
+export interface ManifestAction {
+    readonly packageId: string;
+    readonly module?: string;
+    readonly functionName: string;
+    readonly templateId?: string;
+    readonly templateVersion?: string;
+    readonly displayName?: string;
+}
+export interface ManifestSimulation {
+    readonly required: boolean;
+    readonly status?: "pending" | "passed" | "failed";
+    readonly hash?: string;
+}
+export interface ManifestReceiptRequirement {
+    readonly required: boolean;
+    readonly templateId?: string;
+}
+export interface AgentTransactionManifest {
+    readonly version: typeof AGENT_TRANSACTION_MANIFEST_VERSION;
+    readonly agent: ManifestParty;
+    readonly owner: ManifestParty;
+    readonly wallet?: {
+        readonly walletId?: string;
+        readonly signerRef?: string;
+    };
+    readonly intent: string;
+    readonly spend: ManifestSpend;
+    readonly action: ManifestAction;
+    readonly counterparty: ManifestParty;
+    readonly scope: readonly string[];
+    readonly expiresAt: string;
+    readonly idempotencyKey: string;
+    readonly simulation: ManifestSimulation;
+    readonly receipt: ManifestReceiptRequirement;
+    readonly humanMandate?: {
+        readonly required: boolean;
+        readonly mandateId?: string;
+    };
+    readonly refundPolicy?: {
+        readonly type: "none" | "refund_to_owner" | "refund_to_agent_wallet";
+    };
+    readonly metadata?: Record<string, string>;
+}

package/dist/schema.js

@@ -0,0 +1 @@
+export const AGENT_TRANSACTION_MANIFEST_VERSION = "agent-tx-manifest/v1";

package/dist/validate.d.ts

@@ -0,0 +1,19 @@
+import { type AgentTransactionManifest } from "./schema.js";
+export type ManifestValidationErrorCode = "MANIFEST_NOT_OBJECT" | "UNSUPPORTED_VERSION" | "REQUIRED_FIELD_MISSING" | "FIELD_INVALID" | "MANIFEST_EXPIRED" | "MANIFEST_TOO_LARGE" | "SECRET_FIELD_NOT_ALLOWED";
+export interface ManifestValidationError {
+    readonly code: ManifestValidationErrorCode;
+    readonly path: string;
+    readonly message: string;
+}
+export type ManifestValidationResult = {
+    readonly ok: true;
+    readonly manifest: AgentTransactionManifest;
+} | {
+    readonly ok: false;
+    readonly errors: readonly ManifestValidationError[];
+};
+export interface ManifestValidationOptions {
+    readonly now?: Date;
+    readonly maxBytes?: number;
+}
+export declare function validateAgentTransactionManifest(value: unknown, options?: ManifestValidationOptions): ManifestValidationResult;

package/dist/validate.js

@@ -0,0 +1,98 @@
+import { AGENT_TRANSACTION_MANIFEST_VERSION } from "./schema.js";
+const DEFAULT_MAX_BYTES = 16 * 1024;
+export function validateAgentTransactionManifest(value, options = {}) {
+    const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+    if (byteLength(value) > maxBytes) {
+        return fail("MANIFEST_TOO_LARGE", "$", `Manifest exceeds ${maxBytes} bytes.`);
+    }
+    if (!isRecord(value)) {
+        return fail("MANIFEST_NOT_OBJECT", "$", "Manifest must be a JSON object.");
+    }
+    if (value.version !== AGENT_TRANSACTION_MANIFEST_VERSION) {
+        return fail("UNSUPPORTED_VERSION", "$.version", "Manifest version is unsupported.");
+    }
+    const manifest = value;
+    const errors = [];
+    rejectSecretFields(errors, value);
+    requireParty(errors, manifest.agent, "$.agent");
+    requireParty(errors, manifest.owner, "$.owner");
+    requireParty(errors, manifest.counterparty, "$.counterparty");
+    requireNonEmptyString(errors, manifest.intent, "$.intent");
+    requirePositiveNumber(errors, manifest.spend?.maxGasBudget, "$.spend.maxGasBudget");
+    requireNonEmptyString(errors, manifest.action?.packageId, "$.action.packageId");
+    requireNonEmptyString(errors, manifest.action?.functionName, "$.action.functionName");
+    requireOptionalNonEmptyString(errors, manifest.action?.templateId, "$.action.templateId");
+    requireOptionalNonEmptyString(errors, manifest.action?.templateVersion, "$.action.templateVersion");
+    requireNonEmptyString(errors, manifest.idempotencyKey, "$.idempotencyKey");
+    requireNonEmptyString(errors, manifest.expiresAt, "$.expiresAt");
+    requireArrayOfStrings(errors, manifest.scope, "$.scope");
+    if (typeof manifest.expiresAt === "string" && manifest.expiresAt.trim() !== "") {
+        const expiresAt = Date.parse(manifest.expiresAt);
+        if (Number.isNaN(expiresAt)) {
+            push(errors, "FIELD_INVALID", "$.expiresAt", "Expiry must be an ISO timestamp.");
+        }
+        else if (expiresAt <= (options.now ?? new Date()).getTime()) {
+            push(errors, "MANIFEST_EXPIRED", "$.expiresAt", "Manifest is expired.");
+        }
+    }
+    if (typeof manifest.simulation?.required !== "boolean") {
+        push(errors, "REQUIRED_FIELD_MISSING", "$.simulation.required", "Simulation requirement is required.");
+    }
+    if (typeof manifest.receipt?.required !== "boolean") {
+        push(errors, "REQUIRED_FIELD_MISSING", "$.receipt.required", "Receipt requirement is required.");
+    }
+    return errors.length > 0 ? { ok: false, errors } : { ok: true, manifest };
+}
+function rejectSecretFields(errors, value, path = "$") {
+    for (const [key, child] of Object.entries(value)) {
+        const childPath = `${path}.${key}`;
+        if (isSecretField(key)) {
+            push(errors, "SECRET_FIELD_NOT_ALLOWED", childPath, "Manifest must not contain secret or raw signing material.");
+        }
+        if (isRecord(child)) {
+            rejectSecretFields(errors, child, childPath);
+        }
+    }
+}
+function requireParty(errors, value, path) {
+    if (!isRecord(value)) {
+        push(errors, "REQUIRED_FIELD_MISSING", path, "Party object is required.");
+        return;
+    }
+    requireNonEmptyString(errors, value.id, `${path}.id`);
+}
+function requireNonEmptyString(errors, value, path) {
+    if (typeof value !== "string" || value.trim() === "") {
+        push(errors, "REQUIRED_FIELD_MISSING", path, "Required string field is missing.");
+    }
+}
+function requireOptionalNonEmptyString(errors, value, path) {
+    if (value !== undefined && (typeof value !== "string" || value.trim() === "")) {
+        push(errors, "FIELD_INVALID", path, "Optional string field must be non-empty when present.");
+    }
+}
+function requirePositiveNumber(errors, value, path) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+        push(errors, "REQUIRED_FIELD_MISSING", path, "Required positive number field is missing.");
+    }
+}
+function requireArrayOfStrings(errors, value, path) {
+    if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || item.trim() === "")) {
+        push(errors, "FIELD_INVALID", path, "Field must be an array of non-empty strings.");
+    }
+}
+function fail(code, path, message) {
+    return { ok: false, errors: [{ code, path, message }] };
+}
+function push(errors, code, path, message) {
+    errors.push({ code, path, message });
+}
+function isRecord(value) {
+    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function byteLength(value) {
+    return Buffer.byteLength(JSON.stringify(value) ?? "null", "utf8");
+}
+function isSecretField(key) {
+    return /^(seed|mnemonic|privateKey|private_key|rawKeypair|raw_keypair|rawTransactionBytes|raw_transaction_bytes|userSignature|user_signature|sponsorKey|sponsor_key|appApiKey|app_api_key|bearerToken|bearer_token|paymentCredential|payment_credential)$/i.test(key);
+}

package/dist/x402Mapping.d.ts

@@ -0,0 +1,49 @@
+import { type AgentTransactionManifest, type ManifestParty } from "./schema.js";
+export declare const X402_SUPPORTED_VERSION: 2;
+export interface X402ResourceInfo {
+    readonly url: string;
+    readonly description?: string;
+    readonly mimeType?: string;
+    readonly serviceName?: string;
+    readonly tags?: readonly string[];
+    readonly iconUrl?: string;
+}
+export interface X402PaymentRequirements {
+    readonly scheme: string;
+    readonly network: string;
+    readonly asset: string;
+    readonly amount: string;
+    readonly payTo: string;
+    readonly maxTimeoutSeconds: number;
+    readonly extra: Record<string, unknown>;
+}
+export interface X402PaymentRequired {
+    readonly x402Version: number;
+    readonly error?: string;
+    readonly resource: X402ResourceInfo;
+    readonly accepts: readonly X402PaymentRequirements[];
+    readonly extensions?: Record<string, unknown>;
+}
+export interface X402ManifestMappingContext {
+    readonly agent: ManifestParty;
+    readonly owner: ManifestParty;
+    readonly wallet?: AgentTransactionManifest["wallet"];
+    readonly packageId: string;
+    readonly module?: string;
+    readonly functionName: string;
+    readonly templateId?: string;
+    readonly templateVersion?: string;
+    readonly displayName?: string;
+    readonly maxGasBudget: number;
+    readonly idempotencyKey: string;
+    readonly now?: Date;
+    readonly acceptedIndex?: number;
+    readonly supportedSchemes?: readonly string[];
+    readonly simulationHash?: string;
+}
+export type X402MappingErrorCode = "UNSUPPORTED_X402_VERSION" | "UNSUPPORTED_X402_SCHEME" | "NO_SUPPORTED_PAYMENT_REQUIREMENT" | "INVALID_X402_REQUIREMENT";
+export declare class X402MappingError extends Error {
+    readonly code: X402MappingErrorCode;
+    constructor(code: X402MappingErrorCode, message: string);
+}
+export declare function mapX402PaymentRequiredToManifest(paymentRequired: X402PaymentRequired, context: X402ManifestMappingContext): AgentTransactionManifest;

package/dist/x402Mapping.js

@@ -0,0 +1,109 @@
+import { AGENT_TRANSACTION_MANIFEST_VERSION, } from "./schema.js";
+export const X402_SUPPORTED_VERSION = 2;
+export class X402MappingError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "X402MappingError";
+    }
+}
+export function mapX402PaymentRequiredToManifest(paymentRequired, context) {
+    if (paymentRequired.x402Version !== X402_SUPPORTED_VERSION) {
+        throw new X402MappingError("UNSUPPORTED_X402_VERSION", `Unsupported x402 protocol version: ${paymentRequired.x402Version}.`);
+    }
+    const acceptedIndex = context.acceptedIndex ?? 0;
+    if (!Number.isInteger(acceptedIndex) || acceptedIndex < 0) {
+        throw new X402MappingError("INVALID_X402_REQUIREMENT", "x402 accepted payment requirement index is invalid.");
+    }
+    const requirement = paymentRequired.accepts.at(acceptedIndex);
+    if (!requirement) {
+        throw new X402MappingError("NO_SUPPORTED_PAYMENT_REQUIREMENT", "x402 response did not include a payment requirement.");
+    }
+    validateRequirement(paymentRequired.resource, requirement);
+    validateSupportedScheme(requirement, context.supportedSchemes ?? ["exact"]);
+    const action = {
+        packageId: context.packageId,
+        ...(context.module ? { module: context.module } : {}),
+        functionName: context.functionName,
+        ...(context.templateId ? { templateId: context.templateId } : {}),
+        ...(context.templateVersion ? { templateVersion: context.templateVersion } : {}),
+        ...(context.displayName ? { displayName: context.displayName } : {}),
+    };
+    const now = context.now ?? new Date();
+    return {
+        version: AGENT_TRANSACTION_MANIFEST_VERSION,
+        agent: context.agent,
+        owner: context.owner,
+        ...(context.wallet ? { wallet: context.wallet } : {}),
+        intent: `Pay x402 resource ${paymentRequired.resource.url}`,
+        spend: {
+            maxGasBudget: context.maxGasBudget,
+            maxPayment: {
+                amount: requirement.amount,
+                asset: `${requirement.network}/${requirement.asset}`,
+            },
+        },
+        action,
+        counterparty: {
+            id: `x402:${requirement.payTo}`,
+            address: requirement.payTo,
+        },
+        scope: [
+            "standard:x402",
+            `x402:scheme:${requirement.scheme}`,
+            `x402:network:${requirement.network}`,
+            `x402:resource:${paymentRequired.resource.url}`,
+        ],
+        expiresAt: new Date(now.getTime() + requirement.maxTimeoutSeconds * 1000).toISOString(),
+        idempotencyKey: context.idempotencyKey,
+        simulation: {
+            required: true,
+            status: "passed",
+            hash: context.simulationHash ?? "sha256:x402-mock-simulation",
+        },
+        receipt: {
+            required: true,
+            templateId: "receipt:x402:v2",
+        },
+        humanMandate: {
+            required: false,
+        },
+        refundPolicy: {
+            type: "refund_to_owner",
+        },
+        metadata: {
+            x402Version: String(paymentRequired.x402Version),
+            x402Scheme: requirement.scheme,
+            x402Network: requirement.network,
+            x402Asset: requirement.asset,
+            x402ResourceUrl: paymentRequired.resource.url,
+            x402PayTo: requirement.payTo,
+            x402PaymentAmount: requirement.amount,
+        },
+    };
+}
+function validateRequirement(resource, requirement) {
+    requireNonEmpty(resource.url, "resource.url");
+    requireNonEmpty(requirement.scheme, "accepts[].scheme");
+    requireNonEmpty(requirement.network, "accepts[].network");
+    requireNonEmpty(requirement.asset, "accepts[].asset");
+    requireNonEmpty(requirement.amount, "accepts[].amount");
+    requireNonEmpty(requirement.payTo, "accepts[].payTo");
+    if (!/^[a-z0-9]+:[A-Za-z0-9.-]+$/.test(requirement.network)) {
+        throw new X402MappingError("INVALID_X402_REQUIREMENT", "x402 payment requirement network must be a CAIP-2 network identifier.");
+    }
+    if (!Number.isFinite(requirement.maxTimeoutSeconds) || requirement.maxTimeoutSeconds <= 0) {
+        throw new X402MappingError("INVALID_X402_REQUIREMENT", "x402 payment requirement maxTimeoutSeconds must be a positive number.");
+    }
+}
+function validateSupportedScheme(requirement, supportedSchemes) {
+    if (!supportedSchemes.includes(requirement.scheme)) {
+        throw new X402MappingError("UNSUPPORTED_X402_SCHEME", `Unsupported x402 payment scheme: ${requirement.scheme}.`);
+    }
+}
+function requireNonEmpty(value, path) {
+    if (typeof value !== "string" || value.trim() === "") {
+        throw new X402MappingError("INVALID_X402_REQUIREMENT", `x402 payment requirement ${path} is required.`);
+    }
+}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@vallum/manifest",
+  "version": "0.0.0-prerelease",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "license": "Apache-2.0",
+  "description": "Versioned Agent Transaction Manifest schema and validator for Vallum.",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "LICENSE",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  }
+}