@defdone/annon 0.0.0-stage → 0.1.0-alpha.1

package/dist/pay/backup.d.ts

@@ -0,0 +1,70 @@
+/** Portable purchase backups and encrypted CAS storage. The 32-byte secret is user-held randomness. */
+import { type HostedCheckpoint } from '../api/sharing.js';
+import { type BrowserPurchaseIndex, type BrowserReceipt, type BrowserRecoveryArchiveIndex, type StoredBrowserPurchase } from '../browser/record.js';
+import type { PurchaseRecord } from './purchase.js';
+import { type Store, type Versioned } from './store.js';
+export interface RecoveryRecord extends Versioned {
+    kind: 'recovery';
+    purchase_id: string;
+    file_id: string;
+    recovery: import('../settle-near/identity.js').Identity;
+    buyerSecret: string;
+    fresh_key: string;
+    nonce: string;
+    deadline: number;
+    grant: number | null;
+}
+export interface SellRecord extends Versioned {
+    hosting?: HostedCheckpoint;
+    storageBudget?: string;
+    storageFunding?: 'pending' | 'funded' | 'refused';
+    kind: 'sell';
+    terms: import('../settle-near/terms.js').Terms;
+    /** Immutable Base split provenance. Recipients and bps come from terms.near;
+     * totalAllocation is 10000 and distributionIncentive is 0. Fixed before registration. */
+    baseSplit: {
+        address: string;
+        kind: 'push' | 'pull';
+        salt: string;
+    } | null;
+    published?: boolean;
+    fileKey: string | null;
+    sellerSecret: string | null;
+    deadline: number;
+    name: string;
+    mime: string;
+    previewLen: number;
+    ckdSecret: string | null;
+}
+export interface SellerKeyRecord extends Versioned {
+    kind: 'seller-key';
+    file_id: string;
+    seller: import('../settle-near/identity.js').Identity;
+    buyerSecret: string | null;
+    deadline: number;
+}
+export interface EncryptedRecord extends Versioned {
+    backup: string;
+}
+export declare const newBackupSecret: () => Uint8Array<ArrayBuffer>;
+export declare function validatePurchaseRecord(r: PurchaseRecord): void;
+export declare const exportPurchase: (record: PurchaseRecord, secret: Uint8Array) => Promise<string>;
+export declare const importPurchase: (file: string, secret: Uint8Array) => Promise<PurchaseRecord>;
+export declare const exportRecovery: (record: RecoveryRecord, secret: Uint8Array) => Promise<string>;
+export declare const importRecovery: (file: string, secret: Uint8Array) => Promise<RecoveryRecord>;
+export declare const encryptedPurchaseStore: (raw: Store<EncryptedRecord>, secret: Uint8Array) => Store<PurchaseRecord>;
+export declare const encryptedRecoveryStore: (raw: Store<EncryptedRecord>, secret: Uint8Array) => Store<RecoveryRecord>;
+export declare const exportSell: (record: SellRecord, secret: Uint8Array) => Promise<string>;
+export declare const importSell: (file: string, secret: Uint8Array) => Promise<SellRecord>;
+export declare const encryptedSellStore: (raw: Store<EncryptedRecord>, secret: Uint8Array) => Store<SellRecord>;
+export declare const exportSellerKey: (record: SellerKeyRecord, secret: Uint8Array) => Promise<string>;
+export declare function importSellerKey(file: string, secret: Uint8Array): Promise<SellerKeyRecord>;
+export declare const encryptedSellerKeyStore: (raw: Store<EncryptedRecord>, secret: Uint8Array) => Store<SellerKeyRecord>;
+/** Browser workflow records use the same authenticated encryption and CAS binding as purchases. */
+export declare const exportBrowserReceipt: (record: BrowserReceipt, secret: Uint8Array) => Promise<string>;
+export declare function importBrowserReceipt(file: string, secret: Uint8Array): Promise<BrowserReceipt>;
+export declare const encryptedBrowserIndexStore: (raw: Store<EncryptedRecord>, secret: Uint8Array) => Store<BrowserPurchaseIndex>;
+export declare const encryptedBrowserPurchaseStore: (raw: Store<EncryptedRecord>, secret: Uint8Array) => Store<StoredBrowserPurchase>;
+/** Prepare ciphertext outside an IndexedDB transaction; bind it to the same CAS context. */
+export declare function sealBrowserRecord(name: string, record: BrowserPurchaseIndex | StoredBrowserPurchase | BrowserRecoveryArchiveIndex, secret: Uint8Array): Promise<EncryptedRecord>;
+export declare const encryptedRecoveryArchiveIndexStore: (raw: Store<EncryptedRecord>, secret: Uint8Array) => Store<BrowserRecoveryArchiveIndex>;

package/dist/pay/backup.js

@@ -0,0 +1,402 @@
+/** Portable purchase backups and encrypted CAS storage. The 32-byte secret is user-held randomness. */
+import { validateHostedRecord } from '../api/sharing.js';
+import { purchaseStates, } from '../browser/record.js';
+import { concat, copy } from '../envelope/pay2.js';
+import { AnnonError } from '../errors.js';
+import { keyFromSecret } from '../keys/near-ckd.js';
+import { bytes, exactKeys, hex, uint, usdc, utf8 } from '../settle-near/codec.js';
+import { identityJson } from '../settle-near/identity.js';
+import { baseNonceV2, buildPurchaseMessage, purchaseId } from '../settle-near/purchase.js';
+import { checkNext } from './store.js';
+const subtle = globalThis.crypto.subtle;
+const MAX_BYTES = 2 * 1024 * 1024;
+const TAG = 'annon/purchase-backup/v1';
+function validateRecord(r) {
+    if ('kind' in r && r.kind === 'browser-recovery-archives') {
+        bytes(r.purchaseId, 32);
+        if (r.id !== `recovery-archives:${r.purchaseId}` ||
+            !Number.isSafeInteger(r.revision) ||
+            r.revision < 0 ||
+            !Array.isArray(r.names) ||
+            new Set(r.names).size !== r.names.length ||
+            r.names.some((name) => typeof name !== 'string' ||
+                !name.startsWith(`recovery:${r.purchaseId}:revision:`) ||
+                !/^[0-9]+$/.test(name.slice(name.lastIndexOf(':') + 1))))
+            throw new TypeError('invalid recovery archive index');
+        return;
+    }
+    if ('kind' in r && r.kind === 'browser-purchase') {
+        validateBrowserPurchase(r);
+        return;
+    }
+    if ('kind' in r && r.kind === 'browser-purchase-index') {
+        if (r.id !== 'browser-index' ||
+            !Number.isSafeInteger(r.revision) ||
+            r.revision < 0 ||
+            !Array.isArray(r.entries) ||
+            new Set(r.entries.map((e) => e.id)).size !== r.entries.length)
+            throw new TypeError('invalid browser purchase index');
+        for (const entry of r.entries) {
+            if (!/^[a-zA-Z0-9_-]{1,128}$/.test(entry.id) ||
+                !Number.isSafeInteger(entry.revision) ||
+                entry.revision < 0 ||
+                !purchaseStates.includes(entry.state) ||
+                !['near', 'base', '1click'].includes(entry.route) ||
+                !Number.isSafeInteger(entry.createdAt) ||
+                !Number.isSafeInteger(entry.updatedAt) ||
+                entry.createdAt < 0 ||
+                entry.updatedAt < entry.createdAt)
+                throw new TypeError('invalid browser index entry');
+            bytes(entry.fileId, 32);
+            if (entry.purchaseId !== undefined)
+                bytes(entry.purchaseId, 32);
+            const url = new URL(entry.resourceUrl);
+            if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password)
+                throw new TypeError('invalid resource URL');
+            if (Object.keys(entry).some((key) => ![
+                'id',
+                'revision',
+                'fileId',
+                'route',
+                'state',
+                'resourceUrl',
+                'purchaseId',
+                'createdAt',
+                'updatedAt',
+            ].includes(key)))
+                throw new TypeError('index must contain metadata only');
+        }
+        if (utf8.encode(JSON.stringify(r)).length > MAX_BYTES)
+            throw new TypeError('browser index too large');
+        return;
+    }
+    if ('kind' in r && r.kind === 'browser-receipt') {
+        exactKeys(r, ['kind', 'entry']);
+        validateBrowserPurchase(r.entry);
+        return;
+    }
+    if ('kind' in r && r.kind === 'seller-key') {
+        exactKeys(r, ['kind', 'id', 'revision', 'file_id', 'seller', 'buyerSecret', 'deadline']);
+        if (r.id !== `seller-key:${r.file_id}` ||
+            !Number.isSafeInteger(r.revision) ||
+            r.revision < 0 ||
+            !Number.isSafeInteger(r.deadline) ||
+            r.deadline < 0)
+            throw new TypeError('invalid seller key record');
+        bytes(r.file_id, 32);
+        if (r.buyerSecret !== null)
+            keyFromSecret(bytes(r.buyerSecret, 32));
+        identityJson(r.seller);
+        return;
+    }
+    if ('kind' in r && r.kind === 'sell') {
+        validateHostedRecord(r);
+        if (!Object.hasOwn(r, 'baseSplit') ||
+            !(r.baseSplit === null ||
+                (r.baseSplit &&
+                    /^0x[0-9a-f]{40}$/.test(r.baseSplit.address) &&
+                    ['push', 'pull'].includes(r.baseSplit.kind) &&
+                    /^0x[0-9a-f]{64}$/.test(r.baseSplit.salt))))
+            throw new TypeError('invalid Base split provenance');
+        if (r.id !== `sell:${r.terms.file_id}` ||
+            !Number.isSafeInteger(r.revision) ||
+            r.revision < 0 ||
+            !Number.isSafeInteger(r.deadline) ||
+            r.deadline < 0)
+            throw new TypeError('invalid sell record');
+        if (r.storageBudget !== undefined &&
+            (!/^[1-9][0-9]*$/.test(r.storageBudget) || BigInt(r.storageBudget) >= 2n ** 128n))
+            throw new TypeError('invalid sell storage budget');
+        if (r.storageFunding !== undefined &&
+            (!r.storageBudget || !['pending', 'funded', 'refused'].includes(r.storageFunding)))
+            throw new TypeError('invalid sell funding state');
+        if (r.published === true) {
+            if (r.fileKey !== null || r.sellerSecret !== null || r.ckdSecret !== null)
+                throw new TypeError('published sell retains secrets');
+        }
+        else {
+            bytes(r.fileKey, 32);
+            bytes(r.sellerSecret, 32);
+        }
+        if (r.ckdSecret !== null)
+            bytes(r.ckdSecret, 48);
+        return;
+    }
+    if ('kind' in r && r.kind === 'recovery') {
+        bytes(r.purchase_id, 32);
+        bytes(r.file_id, 32);
+        bytes(r.nonce, 32);
+        if (r.id !== `recovery:${r.purchase_id}` ||
+            hex(keyFromSecret(bytes(r.buyerSecret, 32)).publicKeyBytes) !== r.fresh_key ||
+            !Number.isSafeInteger(r.deadline) ||
+            r.deadline < 0 ||
+            !Number.isSafeInteger(r.revision) ||
+            r.revision < 0 ||
+            !(r.grant === null || (Number.isInteger(r.grant) && r.grant >= 0 && r.grant <= 0xffffffff)))
+            throw new TypeError('invalid recovery record');
+        identityJson(r.recovery);
+    }
+    else
+        validatePurchaseRecord(r);
+}
+function validateBrowserPurchase(entry) {
+    if (!/^[a-zA-Z0-9_-]{1,128}$/.test(entry.id) ||
+        !Number.isSafeInteger(entry.revision) ||
+        entry.revision < 0 ||
+        !purchaseStates.includes(entry.state) ||
+        !['near', 'base', '1click'].includes(entry.route) ||
+        typeof entry.header !== 'string' ||
+        !/^0x(?:[0-9a-f]{2}){1,65536}$/.test(entry.header) ||
+        (entry.needsProof !== undefined && typeof entry.needsProof !== 'boolean') ||
+        !['not_submitted', 'uncertain', 'submitted'].includes(entry.submission))
+        throw new TypeError('invalid browser purchase');
+    if (entry.paymentStarted !== undefined && typeof entry.paymentStarted !== 'boolean')
+        throw new TypeError('invalid payment boundary');
+    if (entry.lease &&
+        (!/^[a-zA-Z0-9_-]{1,128}$/.test(entry.lease.owner) ||
+            !Number.isSafeInteger(entry.lease.expiresAt) ||
+            entry.lease.expiresAt < 0))
+        throw new TypeError('invalid purchase lease');
+    if (entry.recoveryArchives !== undefined) {
+        if (!Array.isArray(entry.recoveryArchives) ||
+            new Set(entry.recoveryArchives.map((r) => r.revision)).size !== entry.recoveryArchives.length)
+            throw new TypeError('invalid recovery archives');
+        for (const archive of entry.recoveryArchives) {
+            if (archive.kind !== 'recovery')
+                throw new TypeError('invalid recovery archive');
+            validate(archive);
+            if (!entry.purchase ||
+                archive.purchase_id !== entry.purchase.id ||
+                archive.file_id !== entry.fileId)
+                throw new TypeError('recovery archive mismatch');
+        }
+    }
+    bytes(entry.fileId, 32);
+    if (uint(entry.maxPrice, 128) === 0n)
+        throw new TypeError('invalid browser price');
+    const url = new URL(entry.resourceUrl);
+    if (!['https:', 'http:'].includes(url.protocol) || url.username || url.password)
+        throw new TypeError('invalid resource URL');
+    if (entry.purchase) {
+        validatePurchaseRecord(entry.purchase);
+        if (entry.purchase.purchase.file_id !== entry.fileId ||
+            entry.purchase.purchase.route !== (entry.route === 'base' ? 'base-usdc' : 'near-usdc') ||
+            entry.purchase.payment.route !== entry.route)
+            throw new TypeError('browser purchase mismatch');
+    }
+    if (entry.recovery) {
+        validate(entry.recovery);
+        if (!entry.purchase ||
+            entry.recovery.purchase_id !== entry.purchase.id ||
+            entry.recovery.file_id !== entry.fileId)
+            throw new TypeError('browser recovery mismatch');
+    }
+    if (entry.checkpoint &&
+        (!entry.purchase ||
+            !Number.isSafeInteger(entry.checkpoint.attempts) ||
+            entry.checkpoint.attempts < 0 ||
+            !Number.isSafeInteger(entry.checkpoint.errors) ||
+            entry.checkpoint.errors < 0))
+        throw new TypeError('invalid browser checkpoint');
+}
+function validate(r) {
+    try {
+        validateRecord(r);
+    }
+    catch (cause) {
+        throw new AnnonError('invalid_record', 'Invalid encrypted record.', { cause });
+    }
+}
+export const newBackupSecret = () => crypto.getRandomValues(new Uint8Array(32));
+function secretKey(secret) {
+    if (!(secret instanceof Uint8Array) || secret.length !== 32)
+        throw new TypeError('backup secret must be 32 random bytes held by the user');
+    return subtle.importKey('raw', copy(secret), 'HKDF', false, ['deriveKey']);
+}
+async function derive(secret, salt) {
+    return subtle.deriveKey({ name: 'HKDF', hash: 'SHA-256', salt: copy(salt), info: utf8.encode(TAG) }, await secretKey(secret), { name: 'AES-GCM', length: 256 }, false, ['encrypt', 'decrypt']);
+}
+export function validatePurchaseRecord(r) {
+    try {
+        checkPurchaseRecord(r);
+    }
+    catch (cause) {
+        throw new AnnonError('invalid_record', 'Invalid purchase record.', { cause });
+    }
+}
+function checkPurchaseRecord(r) {
+    if (typeof r.recoveryProved !== 'boolean')
+        throw new TypeError('invalid recovery proof checkpoint');
+    if (r?.schemaVersion !== 2 ||
+        !Object.hasOwn(r, 'quote') ||
+        !(r.quote === null ||
+            (r.quote &&
+                typeof r.quote === 'object' &&
+                r.quote.request &&
+                r.quote.response &&
+                r.quote.deposit)) ||
+        !r.payment ||
+        !['near', 'base', '1click'].includes(r.payment.route) ||
+        (r.payment.route === 'base') !== (r.purchase.route === 'base-usdc') ||
+        r.payment.amountBaseUnits !== r.purchase.price ||
+        r.payment.amountUsdc !== usdc(BigInt(r.purchase.price)) ||
+        r.payment.network !== r.purchase.network ||
+        r.payment.asset?.symbol !== 'USDC' ||
+        r.payment.asset.id !== r.purchase.asset ||
+        !Number.isSafeInteger(r.revision) ||
+        r.revision < 0 ||
+        r.id !==
+            purchaseId(r.purchase, r.purchase.route === 'base-usdc'
+                ? { baseUsdc: r.purchase.asset }
+                : { nearUsdc: r.purchase.asset }) ||
+        r.message !==
+            buildPurchaseMessage(r.purchase, r.purchase.route === 'base-usdc'
+                ? { baseUsdc: r.purchase.asset }
+                : { nearUsdc: r.purchase.asset }) ||
+        hex(keyFromSecret(bytes(r.buyerSecret, 32)).publicKeyBytes) !== r.purchase.buyer_key ||
+        identityJson(r.recovery) !== identityJson(r.purchase.recovery) ||
+        (r.paymentState !== undefined && !['expired', 'canceled'].includes(r.paymentState)) ||
+        !Array.isArray(r.attempts) ||
+        !r.terms ||
+        r.terms.network !== r.purchase.network ||
+        r.terms.usdc !== r.purchase.asset ||
+        r.terms.price !== r.purchase.price ||
+        r.terms.nonce !== (r.purchase.route === 'base-usdc' ? baseNonceV2(r.id) : r.purchase.nonce) ||
+        r.terms.contractId !== r.purchase.contract ||
+        r.terms.fileId !== r.purchase.file_id ||
+        r.terms.buyerKey !== r.purchase.buyer_key ||
+        r.terms.headerHash !== r.checkedHeaderHash)
+        throw new TypeError('invalid purchase record');
+    bytes(r.checkedHeaderHash, 32);
+    if (utf8.encode(JSON.stringify(r)).length > MAX_BYTES)
+        throw new TypeError('purchase record too large');
+}
+async function encrypt(r, secret, context = '') {
+    validate(r);
+    const salt = crypto.getRandomValues(new Uint8Array(32));
+    const iv = crypto.getRandomValues(new Uint8Array(12));
+    const ciphertext = await subtle.encrypt({
+        name: 'AES-GCM',
+        iv,
+        additionalData: concat(utf8.encode(TAG), utf8.encode(context)),
+        tagLength: 128,
+    }, await derive(secret, salt), utf8.encode(JSON.stringify(r)));
+    const out = {
+        format: 'annon-purchase-backup',
+        v: 1,
+        kdf: 'HKDF-SHA256',
+        salt: hex(salt),
+        iv: hex(iv),
+        ciphertext: hex(new Uint8Array(ciphertext)),
+    };
+    return JSON.stringify(out);
+}
+async function decrypt(file, secret, context = '') {
+    if (typeof file !== 'string' || file.length > MAX_BYTES * 2 + 1024)
+        throw new TypeError('backup too large');
+    const b = JSON.parse(file);
+    exactKeys(b, ['format', 'v', 'kdf', 'salt', 'iv', 'ciphertext']);
+    if (b.format !== 'annon-purchase-backup' ||
+        b.v !== 1 ||
+        b.kdf !== 'HKDF-SHA256' ||
+        typeof b.ciphertext !== 'string' ||
+        !/^0x(?:[0-9a-f]{2}){16,}$/.test(b.ciphertext))
+        throw new TypeError('unsupported backup format');
+    const raw = bytes(b.ciphertext, (b.ciphertext.length - 2) / 2);
+    const plain = await subtle.decrypt({
+        name: 'AES-GCM',
+        iv: bytes(b.iv, 12),
+        additionalData: concat(utf8.encode(TAG), utf8.encode(context)),
+        tagLength: 128,
+    }, await derive(secret, bytes(b.salt, 32)), raw);
+    const r = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(plain));
+    validate(r);
+    return r;
+}
+export const exportPurchase = (record, secret) => encrypt(record, secret);
+export const importPurchase = async (file, secret) => {
+    const r = await decrypt(file, secret);
+    if ('kind' in r)
+        throw new TypeError('not a purchase');
+    return r;
+};
+export const exportRecovery = (record, secret) => encrypt(record, secret);
+export const importRecovery = async (file, secret) => {
+    const r = await decrypt(file, secret);
+    if (!('kind' in r) || r.kind !== 'recovery')
+        throw new TypeError('not a recovery');
+    return r;
+};
+/** Wrap memory, IndexedDB, fileStore or an existing durable store; keep only ciphertext at rest. */
+function encryptedStore(raw, secret) {
+    if (secret.length !== 32)
+        throw new TypeError('backup secret must be 32 bytes');
+    const key = copy(secret);
+    const context = (name, v) => JSON.stringify([name, v.id, v.revision]);
+    return {
+        async load(name) {
+            const encrypted = await raw.load(name);
+            if (!encrypted)
+                return null;
+            const r = await decrypt(encrypted.backup, key, context(name, encrypted));
+            if (!('id' in r) || r.id !== encrypted.id || r.revision !== encrypted.revision)
+                throw new Error('encrypted record metadata mismatch');
+            return r;
+        },
+        async compareAndSet(name, expected, next) {
+            checkNext(expected, next);
+            const value = next
+                ? {
+                    id: next.id,
+                    revision: next.revision,
+                    backup: await encrypt(next, key, context(name, next)),
+                }
+                : null;
+            return raw.compareAndSet(name, expected, value);
+        },
+    };
+}
+export const encryptedPurchaseStore = (raw, secret) => encryptedStore(raw, secret);
+export const encryptedRecoveryStore = (raw, secret) => encryptedStore(raw, secret);
+export const exportSell = (record, secret) => encrypt(record, secret);
+export const importSell = async (file, secret) => {
+    const r = await decrypt(file, secret);
+    if (!('kind' in r) || r.kind !== 'sell')
+        throw new TypeError('not a sell record');
+    return r;
+};
+export const encryptedSellStore = (raw, secret) => encryptedStore(raw, secret);
+export const exportSellerKey = (record, secret) => encrypt(record, secret);
+export async function importSellerKey(file, secret) {
+    try {
+        const record = await decrypt(file, secret);
+        if (!('kind' in record) || record.kind !== 'seller-key')
+            throw new AnnonError('invalid_record');
+        return record;
+    }
+    catch (cause) {
+        if (cause instanceof AnnonError && cause.code === 'invalid_record')
+            throw cause;
+        throw new AnnonError('invalid_record', undefined, { cause });
+    }
+}
+export const encryptedSellerKeyStore = (raw, secret) => encryptedStore(raw, secret);
+/** Browser workflow records use the same authenticated encryption and CAS binding as purchases. */
+export const exportBrowserReceipt = (record, secret) => encrypt(record, secret);
+export async function importBrowserReceipt(file, secret) {
+    const record = await decrypt(file, secret);
+    if (!('kind' in record) || record.kind !== 'browser-receipt')
+        throw new AnnonError('invalid_record');
+    return record;
+}
+export const encryptedBrowserIndexStore = (raw, secret) => encryptedStore(raw, secret);
+export const encryptedBrowserPurchaseStore = (raw, secret) => encryptedStore(raw, secret);
+/** Prepare ciphertext outside an IndexedDB transaction; bind it to the same CAS context. */
+export async function sealBrowserRecord(name, record, secret) {
+    return {
+        id: record.id,
+        revision: record.revision,
+        backup: await encrypt(record, secret, JSON.stringify([name, record.id, record.revision])),
+    };
+}
+export const encryptedRecoveryArchiveIndexStore = (raw, secret) => encryptedStore(raw, secret);

package/dist/pay/base.d.ts

@@ -0,0 +1,135 @@
+import { AnnonError } from '../errors.js';
+import { type Authorization } from './eip3009.js';
+import type { PurchaseRecord } from './purchase.js';
+export type PayErrorCode = 
+/** The RPC couldn't be reached or answered something malformed; safe to retry. */
+'transport' | 'base_rpc_rate_limited' | 'refused'
+/** The payment request or the registration don't allow this purchase; nothing was signed. */
+ | 'storage_required' | 'unknown_file' | 'taken_down' | 'sales_stopped' | 'unknown_moderator' | 'price_mismatch' | 'price_above_max' | 'file_storage_low' | 'protocol_fee_above_max' | 'recipient_mismatch' | 'file_mismatch' | 'network_mismatch' | 'token_mismatch'
+/** The offer's transfer method isn't the one the registration needs. */
+ | 'method_mismatch'
+/** The payment request names an Annon contract this client doesn't trust. */
+ | 'untrusted_contract'
+/** The PAY2 header (or the public file) isn't the registered file signed by its seller. */
+ | 'file_invalid' | 'route_unavailable' | 'bad_requirements' | 'insufficient_balance' | 'smart_wallet_unsupported'
+/** The wallet's answer isn't a signature USDC accepts from this buyer. */
+ | 'bad_signature'
+/** USDC refused the signed authorization in a dry run (the RPC saw it; see `PayError.purchase`). */
+ | 'payment_rejected'
+/** This wallet has an open purchase of this file: follow `nextStep` of the recorded one. */
+ | 'purchase_open'
+/** The purchase record changed under this writer (another tab or process): load it again. */
+ | 'store_conflict'
+/** A seller: this payment id came with another payload before (HTTP 409). */
+ | 'payment_id_conflict'
+/** A seller: the settlement of this purchase is under way or unclear; send the same payload later. */
+ | 'settlement_pending' | 'not_sponsored' | 'wrong_identity' | 'relayer_unavailable' | 'facilitator_busy' | 'unavailable'
+/** A seller: this purchase can no longer be paid (expired or canceled, finalized). */
+ | 'payment_expired';
+export declare class PayError extends AnnonError {
+    readonly code: PayErrorCode;
+    /**
+     * Set when the wallet had already signed: the authorization may have reached an RPC and could
+     * still be settled. The purchase stays open: follow `nextStep`.
+     */
+    purchase?: PurchaseRecord;
+    retryAfterSeconds?: number;
+    constructor(code: PayErrorCode, message?: string);
+}
+/** A typed RPC rate limit; callers retry through isTransient. */
+export declare class BaseRpcRateLimited extends PayError {
+    constructor();
+}
+export declare const fail: (code: PayErrorCode, message?: string) => never;
+interface Head {
+    number: number;
+    timestamp: number;
+    /** 0x and lowercase, when the RPC gave it. */
+    hash?: string;
+}
+/** The latest block, after checking the RPC is on Base mainnet. */
+export declare function head(url: string): Promise<Head>;
+/** A block by number or tag (`latest`, `safe`, `finalized`). */
+export declare function block(url: string, at: number | 'latest' | 'safe' | 'finalized'): Promise<Head>;
+/** A transaction's receipt as the RPC returns it; null while the transaction is unknown. */
+export declare const getReceipt: (url: string, txHash: string) => Promise<unknown>;
+/** A view call at `block` that returns one 32-byte word. */
+export declare function viewWord(url: string, to: string, data: string, block: number): Promise<string>;
+export declare const balanceOf: (url: string, usdc: string, owner: string, block: number) => Promise<bigint>;
+/** USDC's `authorizationState`: true once the nonce was used *or* canceled. A hint, not proof. */
+export declare const authorizationState: (url: string, usdc: string, authorizer: string, nonce: string, block: number) => Promise<boolean>;
+/** Whether an address has code: a contract, or an EOA delegated with EIP-7702. */
+/** The runtime code at `address`, lowercase hex; `0x` for none. */
+export declare function getCode(url: string, address: string, block: number): Promise<string>;
+export declare const hasCode: (url: string, address: string, block: number) => Promise<boolean>;
+/** `transferWithAuthorization(from, to, value, after, before, nonce, v, r, s)`. */
+export declare function authorizationCall(a: Authorization, signature: string): string;
+/**
+ * Runs the signed authorization against USDC without sending it: signature, nonce, validity
+ * window, balance and blacklist, all by USDC's own code.
+ */
+export declare function dryRun(url: string, usdc: string, a: Authorization, signature: string): Promise<void>;
+/**
+ * The RLP header of the block `hash`, rebuilt from the RPC's fields and checked to hash to it.
+ * `unlock` takes it for a file whose sales were stopped: the contract reads the payment's time
+ * from it. A header with a field this SDK doesn't know fails here, never on NEAR.
+ */
+export declare function blockHeader(url: string, hash: string): Promise<string>;
+/** A log as the contract's `unlock` takes it (NEAR MPC's `EvmLog`). */
+export interface EvmLog {
+    address: string;
+    block_hash: string;
+    block_number: number;
+    data: string;
+    log_index: number;
+    removed: boolean;
+    topics: string[];
+    transaction_hash: string;
+    transaction_index: number;
+}
+/** What a purchase expects to find on Base: the job saved before the buyer signed. */
+export interface Expected {
+    usdc: string;
+    /** The registered `pay_to`. */
+    to: string;
+    from: string;
+    /** The signed nonce. */
+    nonce: string;
+    price: bigint;
+}
+/**
+ * The logs of this purchase in a transaction receipt, exactly as `unlock` checks them: USDC's
+ * `AuthorizationUsed` for the nonce and the `Transfer` to `pay_to` right after it. Null when the
+ * receipt holds no such payment.
+ */
+export declare function paymentLogs(receipt: unknown, e: Expected): EvmLog[] | null;
+export type PaymentStatus = 
+/** On Base: `logs` go to `unlock`; `logIndex` identifies its first proved log. */
+{
+    state: 'paid';
+    txHash: string;
+    logIndex: number;
+    logs: EvmLog[];
+}
+/** Not on Base yet and still valid: wait, or send the same header again. */
+ | {
+    state: 'pending';
+}
+/** Can never be paid: a new purchase with a new one-time key is safe. */
+ | {
+    state: 'expired';
+} | {
+    state: 'canceled';
+};
+/**
+ * Where a signed purchase stands, found by its nonce alone, so a lost transaction hash loses
+ * nothing. `block` is the head when it was signed. A payment counts as soon as it is in a block;
+ * `expired` and `canceled` only from the finalized chain, because a new purchase follows them and
+ * a reorg must not turn that into a second payment. `authorizationState` is only read to catch an
+ * RPC that misses logs.
+ */
+export declare function paymentStatus(url: string, e: Expected & {
+    block: number;
+    validBefore: bigint;
+}): Promise<PaymentStatus>;
+export {};