@4mica/sdk 0.5.0

package/dist/signing.d.ts

@@ -0,0 +1,106 @@
+import { PaymentGuaranteeRequestClaims, PaymentSignature, SigningScheme } from './models';
+/**
+ * ClientEvmSigner - Used by x402 clients to sign payment authorizations
+ * This is typically a LocalAccount or wallet that holds private keys
+ * and can sign EIP-712 typed data for payment authorizations
+ */
+export type EvmSigner = {
+    readonly address: `0x${string}`;
+    signTypedData(message: {
+        domain: Record<string, unknown>;
+        types: Record<string, unknown>;
+        primaryType: string;
+        message: Record<string, unknown>;
+    }): Promise<`0x${string}`>;
+    signMessage(message: {
+        message: string;
+    }): Promise<`0x${string}`>;
+};
+export declare function createLocalSigner(privateKey: string): EvmSigner;
+export declare class CorePublicParameters {
+    publicKey: Uint8Array;
+    contractAddress: string;
+    ethereumHttpRpcUrl: string;
+    eip712Name: string;
+    eip712Version: string;
+    chainId: number;
+    constructor(publicKey: Uint8Array, contractAddress: string, ethereumHttpRpcUrl: string, eip712Name: string, eip712Version: string, chainId: number);
+    static fromRpc(payload: Record<string, unknown>): CorePublicParameters;
+}
+export declare const GUARANTEE_EIP712_TYPES: {
+    readonly EIP712Domain: readonly [{
+        readonly name: "name";
+        readonly type: "string";
+    }, {
+        readonly name: "version";
+        readonly type: "string";
+    }, {
+        readonly name: "chainId";
+        readonly type: "uint256";
+    }];
+    readonly SolGuaranteeRequestClaimsV1: readonly [{
+        readonly name: "user";
+        readonly type: "address";
+    }, {
+        readonly name: "recipient";
+        readonly type: "address";
+    }, {
+        readonly name: "tabId";
+        readonly type: "uint256";
+    }, {
+        readonly name: "reqId";
+        readonly type: "uint256";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }, {
+        readonly name: "asset";
+        readonly type: "address";
+    }, {
+        readonly name: "timestamp";
+        readonly type: "uint64";
+    }];
+};
+export type GuaranteeTypedData = {
+    types: typeof GUARANTEE_EIP712_TYPES;
+    primaryType: 'SolGuaranteeRequestClaimsV1';
+    domain: {
+        name: string;
+        version: string;
+        chainId: number;
+    };
+    message: {
+        user: string;
+        recipient: string;
+        tabId: bigint;
+        reqId: bigint;
+        amount: bigint;
+        asset: string;
+        timestamp: bigint;
+    };
+};
+export type GuaranteeTypedDataValidationOptions = {
+    expectedChainId?: number;
+    expectedSigner?: string;
+    expectedRecipient?: string;
+};
+export type GuaranteeSigningContextOptions = {
+    signerAddress?: string;
+    signerChainId?: number;
+};
+export declare function validateGuaranteeTypedData(payload: {
+    domain: Record<string, unknown>;
+    types: Record<string, Array<{
+        name: string;
+        type: string;
+    }>>;
+    message: Record<string, unknown>;
+}, options?: GuaranteeTypedDataValidationOptions): void;
+export declare function validateGuaranteeSigningContext(params: CorePublicParameters, claims: PaymentGuaranteeRequestClaims, options?: GuaranteeSigningContextOptions): void;
+export declare function buildGuaranteeTypedData(params: CorePublicParameters, claims: PaymentGuaranteeRequestClaims): GuaranteeTypedData;
+export declare function encodeGuaranteeEip191(claims: PaymentGuaranteeRequestClaims): string;
+export declare class PaymentSigner {
+    private signer;
+    constructor(signer: EvmSigner);
+    signRequest(params: CorePublicParameters, claims: PaymentGuaranteeRequestClaims, scheme?: SigningScheme): Promise<PaymentSignature>;
+}

package/dist/signing.js

@@ -0,0 +1,223 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PaymentSigner = exports.GUARANTEE_EIP712_TYPES = exports.CorePublicParameters = void 0;
+exports.createLocalSigner = createLocalSigner;
+exports.validateGuaranteeTypedData = validateGuaranteeTypedData;
+exports.validateGuaranteeSigningContext = validateGuaranteeSigningContext;
+exports.buildGuaranteeTypedData = buildGuaranteeTypedData;
+exports.encodeGuaranteeEip191 = encodeGuaranteeEip191;
+const ethers_1 = require("ethers");
+const errors_1 = require("./errors");
+const models_1 = require("./models");
+const utils_1 = require("./utils");
+function createLocalSigner(privateKey) {
+    privateKey = (0, utils_1.normalizePrivateKey)(privateKey);
+    const wallet = new ethers_1.Wallet(privateKey);
+    return {
+        address: wallet.address,
+        signTypedData: async (message) => {
+            const signature = await wallet.signTypedData(message.domain, { [message.primaryType]: message.types[message.primaryType] }, message.message);
+            return signature;
+        },
+        signMessage: async ({ message }) => {
+            const signature = await wallet.signMessage(message);
+            return signature;
+        },
+    };
+}
+class CorePublicParameters {
+    constructor(publicKey, contractAddress, ethereumHttpRpcUrl, eip712Name, eip712Version, chainId) {
+        this.publicKey = publicKey;
+        this.contractAddress = contractAddress;
+        this.ethereumHttpRpcUrl = ethereumHttpRpcUrl;
+        this.eip712Name = eip712Name;
+        this.eip712Version = eip712Version;
+        this.chainId = chainId;
+    }
+    static fromRpc(payload) {
+        const pkRaw = payload.public_key ?? payload.publicKey;
+        const pk = typeof pkRaw === 'string'
+            ? (0, ethers_1.getBytes)(pkRaw)
+            : pkRaw instanceof Uint8Array
+                ? pkRaw
+                : Array.isArray(pkRaw)
+                    ? Uint8Array.from(pkRaw)
+                    : new Uint8Array();
+        return new CorePublicParameters(pk, String(payload.contract_address ?? payload.contractAddress ?? ''), String(payload.ethereum_http_rpc_url ?? payload.ethereumHttpRpcUrl ?? ''), (payload.eip712_name ?? payload.eip712Name ?? '4Mica'), (payload.eip712_version ?? payload.eip712Version ?? '1'), Number(payload.chain_id ?? payload.chainId));
+    }
+}
+exports.CorePublicParameters = CorePublicParameters;
+exports.GUARANTEE_EIP712_TYPES = {
+    EIP712Domain: [
+        { name: 'name', type: 'string' },
+        { name: 'version', type: 'string' },
+        { name: 'chainId', type: 'uint256' },
+    ],
+    SolGuaranteeRequestClaimsV1: [
+        { name: 'user', type: 'address' },
+        { name: 'recipient', type: 'address' },
+        { name: 'tabId', type: 'uint256' },
+        { name: 'reqId', type: 'uint256' },
+        { name: 'amount', type: 'uint256' },
+        { name: 'asset', type: 'address' },
+        { name: 'timestamp', type: 'uint64' },
+    ],
+};
+const isRecord = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+const fieldsMatch = (actual, expected) => {
+    if (!Array.isArray(actual) || actual.length !== expected.length)
+        return false;
+    const norm = (list) => list.map((item) => `${item.name}:${item.type}`).sort();
+    const actualSet = new Set(norm(actual));
+    return norm(expected).every((key) => actualSet.has(key));
+};
+const parseChainId = (value) => {
+    if (typeof value === 'bigint')
+        return Number(value);
+    if (typeof value === 'number')
+        return value;
+    if (typeof value === 'string' && value.trim())
+        return Number(value);
+    return Number.NaN;
+};
+const ensureBigIntish = (value, label) => {
+    try {
+        BigInt(value);
+    }
+    catch {
+        throw new utils_1.ValidationError(`${label} must be a numeric value`);
+    }
+};
+function validateGuaranteeTypedData(payload, options = {}) {
+    if (!isRecord(payload)) {
+        throw new utils_1.ValidationError('typed data payload is required');
+    }
+    if (!isRecord(payload.domain)) {
+        throw new utils_1.ValidationError('domain is required');
+    }
+    if (!isRecord(payload.types)) {
+        throw new utils_1.ValidationError('types are required');
+    }
+    if (!isRecord(payload.message)) {
+        throw new utils_1.ValidationError('message is required');
+    }
+    const types = payload.types;
+    if (!fieldsMatch(types.SolGuaranteeRequestClaimsV1, exports.GUARANTEE_EIP712_TYPES.SolGuaranteeRequestClaimsV1)) {
+        throw new utils_1.ValidationError('Unexpected struct fields for SolGuaranteeRequestClaimsV1');
+    }
+    const message = payload.message;
+    const requiredFields = ['user', 'recipient', 'tabId', 'reqId', 'amount', 'asset', 'timestamp'];
+    if (requiredFields.some((field) => !(field in message))) {
+        throw new utils_1.ValidationError('message is missing required SolGuaranteeRequestClaimsV1 fields');
+    }
+    const user = (0, utils_1.normalizeAddress)(message.user);
+    const recipient = (0, utils_1.normalizeAddress)(message.recipient);
+    (0, utils_1.normalizeAddress)(message.asset);
+    if (options.expectedSigner) {
+        if ((0, utils_1.normalizeAddress)(options.expectedSigner) !== user) {
+            throw new utils_1.ValidationError('message.user must match signer address');
+        }
+    }
+    if (options.expectedRecipient) {
+        if ((0, utils_1.normalizeAddress)(options.expectedRecipient) !== recipient) {
+            throw new utils_1.ValidationError('message.recipient must match expected recipient');
+        }
+    }
+    ensureBigIntish(message.tabId, 'tabId');
+    ensureBigIntish(message.reqId, 'reqId');
+    ensureBigIntish(message.amount, 'amount');
+    ensureBigIntish(message.timestamp, 'timestamp');
+    if (options.expectedChainId !== undefined) {
+        const domainChainId = parseChainId(payload.domain.chainId);
+        if (!Number.isFinite(domainChainId)) {
+            throw new utils_1.ValidationError('domain.chainId is required for typed data signatures');
+        }
+        if (Number(domainChainId) !== Number(options.expectedChainId)) {
+            throw new utils_1.ValidationError(`domain.chainId mismatch; expected ${options.expectedChainId}, got ${domainChainId}`);
+        }
+    }
+}
+function validateGuaranteeSigningContext(params, claims, options = {}) {
+    if (options.signerAddress) {
+        const signer = (0, utils_1.normalizeAddress)(options.signerAddress);
+        const user = (0, utils_1.normalizeAddress)(claims.userAddress);
+        if (signer !== user) {
+            throw new utils_1.ValidationError(`address mismatch: signer ${options.signerAddress} != claims.user_address ${claims.userAddress}`);
+        }
+    }
+    if (options.signerChainId !== undefined) {
+        const signerChainId = Number(options.signerChainId);
+        if (!Number.isFinite(signerChainId)) {
+            throw new utils_1.ValidationError('signer chain id is invalid');
+        }
+        if (Number(params.chainId) !== signerChainId) {
+            throw new utils_1.ValidationError(`chain id mismatch: expected ${params.chainId}, got ${signerChainId}`);
+        }
+    }
+}
+function buildGuaranteeTypedData(params, claims) {
+    return {
+        types: exports.GUARANTEE_EIP712_TYPES,
+        primaryType: 'SolGuaranteeRequestClaimsV1',
+        domain: {
+            name: params.eip712Name,
+            version: params.eip712Version,
+            chainId: params.chainId,
+        },
+        message: {
+            user: claims.userAddress,
+            recipient: claims.recipientAddress,
+            tabId: claims.tabId,
+            reqId: claims.reqId,
+            amount: claims.amount,
+            asset: claims.assetAddress,
+            timestamp: BigInt(claims.timestamp),
+        },
+    };
+}
+function encodeGuaranteeEip191(claims) {
+    const payload = ethers_1.AbiCoder.defaultAbiCoder().encode(['address', 'address', 'uint256', 'uint256', 'uint256', 'address', 'uint64'], [
+        claims.userAddress,
+        claims.recipientAddress,
+        claims.tabId,
+        claims.reqId,
+        claims.amount,
+        claims.assetAddress,
+        claims.timestamp,
+    ]);
+    return payload;
+}
+class PaymentSigner {
+    constructor(signer) {
+        this.signer = signer;
+    }
+    async signRequest(params, claims, scheme = models_1.SigningScheme.EIP712) {
+        try {
+            validateGuaranteeSigningContext(params, claims, { signerAddress: this.signer.address });
+            if (scheme === models_1.SigningScheme.EIP712) {
+                const typed = buildGuaranteeTypedData(params, claims);
+                const signature = await this.signer.signTypedData({
+                    domain: typed.domain,
+                    types: { SolGuaranteeRequestClaimsV1: typed.types.SolGuaranteeRequestClaimsV1 },
+                    primaryType: typed.primaryType,
+                    message: typed.message,
+                });
+                return { signature, scheme };
+            }
+            if (scheme === models_1.SigningScheme.EIP191) {
+                const message = encodeGuaranteeEip191(claims);
+                const signature = await this.signer.signMessage({ message });
+                return { signature, scheme };
+            }
+            throw new errors_1.SigningError(`unsupported signing scheme: ${scheme}`);
+        }
+        catch (err) {
+            if (err instanceof utils_1.ValidationError) {
+                throw new errors_1.SigningError(err.message);
+            }
+            const message = err instanceof Error ? err.message : String(err);
+            throw new errors_1.SigningError(message);
+        }
+    }
+}
+exports.PaymentSigner = PaymentSigner;