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

package/dist/download/upload.js

@@ -0,0 +1,408 @@
+/** Seller-authorized encrypted hosting. No plaintext or file key is sent to the host. */
+import { base64urlnopad } from '@scure/base';
+import { bodyHash, chunkCount, previewLimit, sha256 } from '../envelope/pay2.js';
+import { AnnonError, isAnnonErrorCode, toPublicError } from '../errors.js';
+import { verifyNearMessage } from '../near/nep413.js';
+import { parseReservation } from '../relay/reservation.js';
+import { account, bytes, exactKeys, hex, network } from '../settle-near/codec.js';
+import { identityJson, identityText, parseIdentity, verifyAuthorization, } from '../settle-near/identity.js';
+import { termsHash } from '../settle-near/terms.js';
+export const uploadText = (i) => [
+    'Annon: reserve encrypted file hosting',
+    `network: ${i.network}`,
+    `contract: ${i.contract}`,
+    `seller: ${identityText(i.seller)}`,
+    `file: ${i.fileId}`,
+    `cipher: ${i.cipherHash}`,
+    `terms: ${i.termsHash}`,
+    `bytes: ${i.byteSize}`,
+    `plaintext bytes: ${i.plaintextSize}`,
+    `header bytes: ${i.headerSize}`,
+    `host: ${i.hostOrigin}`,
+    `metadata: ${i.metadataHash}`,
+    `nonce: ${i.nonce}`,
+    `expires: ${i.expiresAt}`,
+].join('\n');
+const utf8 = new TextEncoder();
+export function uploadOrigin(value) {
+    const url = new URL(value);
+    if (url.protocol !== 'https:' || url.origin !== value || url.username || url.password)
+        throw new AnnonError('bad_request', 'Invalid upload origin.');
+    return value;
+}
+export function normalizeMetadata(input) {
+    exactKeys(input, ['filename', 'title', 'description']);
+    const out = {};
+    for (const [key, max] of [
+        ['filename', 255],
+        ['title', 120],
+        ['description', 500],
+    ]) {
+        const raw = input[key];
+        if (typeof raw !== 'string')
+            throw new AnnonError('bad_request', 'Invalid upload metadata.');
+        const value = raw.normalize('NFC');
+        if (/[\p{Cc}\p{Cs}\p{Cf}\p{Zl}\p{Zp}]/u.test(value) ||
+            utf8.encode(value).length > max ||
+            (key !== 'description' && !value))
+            throw new AnnonError('bad_request', 'Invalid upload metadata.');
+        out[key] = value;
+    }
+    if (/[\\/]/.test(out.filename) || out.filename === '.' || out.filename === '..')
+        throw new AnnonError('bad_request', 'Invalid upload filename.');
+    return out;
+}
+export async function metadataHash(metadata) {
+    const m = normalizeMetadata(metadata);
+    return hex(await sha256(utf8.encode(JSON.stringify([m.filename, m.title, m.description]))));
+}
+export function parseUploadIntent(input) {
+    exactKeys(input, [
+        'network',
+        'contract',
+        'seller',
+        'fileId',
+        'cipherHash',
+        'termsHash',
+        'byteSize',
+        'plaintextSize',
+        'headerSize',
+        'hostOrigin',
+        'metadataHash',
+        'nonce',
+        'expiresAt',
+    ]);
+    const i = input;
+    network(i.network);
+    account(i.contract);
+    uploadOrigin(i.hostOrigin);
+    const seller = parseIdentity(i.seller);
+    if (seller.kind !== i.seller.kind || seller.id !== i.seller.id)
+        throw new AnnonError('bad_request', 'Noncanonical seller.');
+    for (const k of ['fileId', 'cipherHash', 'termsHash', 'metadataHash', 'nonce'])
+        bytes(i[k], 32);
+    for (const k of ['byteSize', 'plaintextSize', 'headerSize', 'expiresAt'])
+        if (!Number.isSafeInteger(i[k]) || i[k] < 0)
+            throw new AnnonError('bad_request', 'Invalid upload size or time.');
+    if (i.byteSize <= i.headerSize ||
+        i.headerSize < 1 ||
+        i.headerSize > 65536 ||
+        i.plaintextSize > 50_000_000 ||
+        i.byteSize > 50_086_016)
+        throw new AnnonError('bad_request', 'Invalid upload size.');
+    return { ...structuredClone(i), seller };
+}
+export function parseUploadAuth(input) {
+    if (!input || typeof input !== 'object')
+        throw new AnnonError('bad_request', 'Invalid upload authorization.');
+    if ('kind' in input && input.kind === 'near') {
+        exactKeys(input, ['kind', 'accountId', 'publicKey', 'signature']);
+        const near = input;
+        if (typeof near.accountId !== 'string' ||
+            typeof near.publicKey !== 'string' ||
+            typeof near.signature !== 'string')
+            throw new AnnonError('bad_request', 'Invalid upload authorization.');
+    }
+    else {
+        exactKeys(input, ['kind', 'sig']);
+        if (input.kind !== 'evm' && input.kind !== 'solana')
+            throw new AnnonError('bad_request', 'Invalid upload authorization.');
+        bytes(input.sig, input.kind === 'evm' ? 65 : 64);
+    }
+    return structuredClone(input);
+}
+export function parseUpload(input) {
+    exactKeys(input, ['intent', 'terms', 'manifest', 'metadata', 'auth']);
+    const intent = parseUploadIntent(input.intent);
+    exactKeys(input.manifest, [
+        'version',
+        'chunkLog2',
+        'metaLen',
+        'previewLen',
+        'n',
+        'keyCommitments',
+        'chunkHashes',
+    ]);
+    const m = input.manifest;
+    if (![m.chunkLog2, m.metaLen, m.previewLen, m.n].every(Number.isSafeInteger) ||
+        m.version !== 2 ||
+        m.chunkLog2 < 16 ||
+        m.chunkLog2 > 24 ||
+        m.metaLen < 256 ||
+        m.metaLen > 4096 ||
+        m.metaLen % 256 !== 0 ||
+        m.previewLen < 0 ||
+        m.previewLen > previewLimit(intent.plaintextSize) ||
+        m.n < 2 ||
+        m.n > 1024 ||
+        m.n !== chunkCount(intent.plaintextSize, m.previewLen, m.chunkLog2) ||
+        !Array.isArray(m.keyCommitments) ||
+        m.keyCommitments.length !== (m.previewLen > 0 ? 2 : 1) ||
+        !Array.isArray(m.chunkHashes) ||
+        m.chunkHashes.length !== m.n)
+        throw new AnnonError('bad_request', 'Invalid upload manifest.');
+    for (const h of [...m.keyCommitments, ...m.chunkHashes])
+        bytes(h, 32);
+    if (intent.headerSize !==
+        206 + utf8.encode(intent.contract).length + 32 * (m.keyCommitments.length + m.n) ||
+        intent.byteSize - intent.headerSize !== intent.plaintextSize + m.metaLen + 16 * m.n)
+        throw new AnnonError('bad_request', 'Invalid upload framing.');
+    return {
+        intent,
+        terms: structuredClone(input.terms),
+        manifest: structuredClone(m),
+        metadata: normalizeMetadata(input.metadata),
+        auth: parseUploadAuth(input.auth),
+    };
+}
+export async function verifyUploadAuthorization(a, o) {
+    const i = parseUploadIntent(a.intent), auth = parseUploadAuth(a.auth);
+    if (i.network !== o.network ||
+        i.contract !== o.contract ||
+        i.hostOrigin !== o.hostOrigin ||
+        i.expiresAt <= o.now ||
+        i.expiresAt > o.now + (o.authSeconds ?? 600) ||
+        auth.kind !== i.seller.kind)
+        throw new AnnonError('bad_request', 'Invalid upload authorization.');
+    if (auth.kind === 'near') {
+        await verifyNearMessage(i.seller.id, { message: uploadText(i), recipient: i.hostOrigin, nonce: bytes(i.nonce, 32) }, auth, o.nearRpc);
+    }
+    else if (!verifyAuthorization(i.seller, uploadText(i), auth))
+        throw new AnnonError('bad_request', 'Invalid upload signature.');
+}
+export async function verifyUpload(input, o) {
+    const r = parseUpload(input), i = r.intent, t = r.terms;
+    if (t.network !== i.network ||
+        t.contract !== i.contract ||
+        t.file_id !== i.fileId ||
+        t.cipher_hash !== i.cipherHash ||
+        t.pay2_version !== 2 ||
+        identityJson(t.seller) !== identityJson(i.seller) ||
+        termsHash(t, o.assets) !== i.termsHash ||
+        (await metadataHash(r.metadata)) !== i.metadataHash ||
+        hex(await bodyHash({
+            ...r.manifest,
+            fileId: bytes(i.fileId, 32),
+            commits: r.manifest.keyCommitments.map((h) => bytes(h, 32)),
+            hashes: r.manifest.chunkHashes.map((h) => bytes(h, 32)),
+        })) !== i.cipherHash)
+        throw new AnnonError('bad_request', 'Invalid upload binding.');
+    await verifyUploadAuthorization(r, o);
+}
+export function encodeUploadAuthorization(input) {
+    const value = base64urlnopad.encode(utf8.encode(JSON.stringify({
+        intent: parseUploadIntent(input.intent),
+        auth: parseUploadAuth(input.auth),
+    })));
+    if (value.length > 8192)
+        throw new AnnonError('bad_request', 'Upload authorization is too large.');
+    return value;
+}
+export function decodeUploadAuthorization(value, max = 8192) {
+    if (value.length > max || !/^[A-Za-z0-9_-]+$/.test(value))
+        throw new AnnonError('bad_request', 'Invalid upload authorization.');
+    const a = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(base64urlnopad.decode(value)));
+    exactKeys(a, ['intent', 'auth']);
+    return { intent: parseUploadIntent(a.intent), auth: parseUploadAuth(a.auth) };
+}
+const failure = (code, retryAfterSeconds) => {
+    const safe = toPublicError({ code, retryAfterSeconds });
+    return {
+        ok: false,
+        error: Object.assign(new AnnonError(code), safe.retryAfterSeconds === undefined ? {} : { retryAfterSeconds: safe.retryAfterSeconds }),
+    };
+};
+function createdResponse(value, origin, expectedId) {
+    exactKeys(value, ['uploadId', 'state', 'expiresAt', 'bodyUrl', 'headerUrl']);
+    const v = value;
+    if (!/^[a-f0-9]{64}$/.test(v.uploadId) ||
+        (expectedId !== undefined && v.uploadId !== expectedId) ||
+        v.state !== 'receiving' ||
+        !Number.isSafeInteger(v.expiresAt) ||
+        v.expiresAt < 0 ||
+        v.bodyUrl !== `${origin}/v1/uploads/${v.uploadId}/body` ||
+        v.headerUrl !== `${origin}/v1/uploads/${v.uploadId}/header`)
+        throw new AnnonError('bad_request', 'Invalid upload response.');
+    return v;
+}
+function reservedResponse(value, id, intent) {
+    exactKeys(value, ['uploadId', 'state', 'reservation']);
+    const v = value;
+    const r = parseReservation(v.reservation);
+    if (v.uploadId !== id ||
+        v.state !== 'reserved' ||
+        r.uploadId !== id ||
+        identityJson(r.seller) !== identityJson(intent.seller))
+        throw new AnnonError('bad_request', 'Invalid upload response.');
+    for (const key of [
+        'network',
+        'contract',
+        'fileId',
+        'termsHash',
+        'cipherHash',
+        'byteSize',
+        'plaintextSize',
+        'headerSize',
+        'metadataHash',
+        'hostOrigin',
+    ])
+        if (r[key] !== intent[key])
+            throw new AnnonError('bad_request', 'Invalid upload response.');
+    return { ...v, reservation: r };
+}
+function publishedResponse(value, intent) {
+    exactKeys(value, ['fileId', 'url', 'header', 'expiresAt']);
+    const v = value;
+    const url = `${intent.hostOrigin}/f/${intent.fileId.slice(2)}`;
+    if (v.fileId !== intent.fileId ||
+        v.url !== url ||
+        v.header !== `${url}/header` ||
+        (v.expiresAt !== null && (!Number.isSafeInteger(v.expiresAt) || v.expiresAt < 0)))
+        throw new AnnonError('bad_request', 'Invalid upload response.');
+    return v;
+}
+function splitResponse(value) {
+    if (value === null)
+        return null;
+    exactKeys(value, ['state', 'address', 'kind', 'salt', 'txHash']);
+    if ((value.state !== 'pending' && value.state !== 'ready') ||
+        typeof value.address !== 'string' ||
+        !/^0x[0-9a-fA-F]{40}$/.test(value.address) ||
+        value.kind !== 'push' ||
+        value.salt !== `0x${'00'.repeat(32)}` ||
+        (value.txHash !== null &&
+            (typeof value.txHash !== 'string' || !/^0x[0-9a-f]{64}$/.test(value.txHash))))
+        throw new AnnonError('bad_request');
+    return value;
+}
+function statusResponse(value, id, intent) {
+    if (!value || typeof value !== 'object' || !('baseSplit' in value))
+        throw new AnnonError('bad_request');
+    const { baseSplit, ...state } = value;
+    const split = splitResponse(baseSplit);
+    if ('state' in state && state.state === 'receiving')
+        return { ...createdResponse(state, intent.hostOrigin, id), baseSplit: split };
+    if ('state' in state && state.state === 'reserved')
+        return { ...reservedResponse(state, id, intent), baseSplit: split };
+    exactKeys(state, ['uploadId', 'state', 'result']);
+    if (state.uploadId !== id || state.state !== 'published')
+        throw new AnnonError('bad_request');
+    return {
+        uploadId: id,
+        state: 'published',
+        result: publishedResponse(state.result, intent),
+        baseSplit: split,
+    };
+}
+export class UploadClient {
+    origin;
+    fetcher;
+    constructor(origin, options = {}) {
+        this.origin = uploadOrigin(origin);
+        this.fetcher = options.fetch ?? fetch;
+    }
+    async request(path, method, body, authorization, validate) {
+        try {
+            return await this.requestJson(path, method, body, authorization, validate);
+        }
+        catch {
+            return failure('operation_failed');
+        }
+    }
+    async requestJson(path, method, body, authorization, validate) {
+        const response = await this.fetcher(`${this.origin}${path}`, {
+            method,
+            credentials: 'omit',
+            redirect: 'error',
+            signal: AbortSignal.timeout(method === 'PUT' ? 1800000 : 5000),
+            headers: {
+                ...(body === undefined
+                    ? {}
+                    : { 'Content-Type': method === 'PUT' ? 'application/octet-stream' : 'application/json' }),
+                ...(authorization
+                    ? { 'Annon-Upload-Authorization': encodeUploadAuthorization(authorization) }
+                    : {}),
+            },
+            ...(body === undefined ? {} : { body }),
+            ...(body instanceof ReadableStream ? { duplex: 'half' } : {}),
+        });
+        if (response.redirected ||
+            response.headers.get('content-type')?.split(';')[0]?.trim().toLowerCase() !==
+                'application/json') {
+            await response.body?.cancel();
+            return failure('operation_failed');
+        }
+        const reader = response.body?.getReader();
+        if (!reader)
+            return failure('operation_failed');
+        const parts = [];
+        let size = 0;
+        try {
+            while (true) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                size += value.length;
+                if (size > 131072)
+                    throw new AnnonError('bad_request', 'Upload response is too large.');
+                parts.push(value);
+            }
+        }
+        finally {
+            await reader.cancel();
+            reader.releaseLock();
+        }
+        const bytes = new Uint8Array(size);
+        let at = 0;
+        for (const p of parts) {
+            bytes.set(p, at);
+            at += p.length;
+        }
+        const value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+        if (isAnnonErrorCode(value?.error))
+            return failure(value.error, value.retryAfterSeconds);
+        if (response.ok) {
+            try {
+                if (!validate)
+                    throw new AnnonError('bad_request');
+                return { ok: true, value: validate(value, response.status) };
+            }
+            catch {
+                return failure('operation_failed');
+            }
+        }
+        const code = isAnnonErrorCode(value?.error) ? value.error : 'operation_failed';
+        return failure(code, code === 'operation_failed' ? undefined : value.retryAfterSeconds);
+    }
+    path(id) {
+        if (!/^[a-f0-9]{64}$/.test(id))
+            throw new AnnonError('bad_request', 'Invalid upload ID.');
+        return `/v1/uploads/${id}`;
+    }
+    create(request) {
+        return this.request('/v1/uploads', 'POST', JSON.stringify(parseUpload(request)), undefined, (value) => value && typeof value === 'object' && 'baseSplit' in value
+            ? statusResponse(value, value.uploadId, request.intent)
+            : createdResponse(value, this.origin));
+    }
+    async body(id, auth, body) {
+        return this.request(`${this.path(id)}/body`, 'PUT', body, auth, (value) => reservedResponse(value, id, auth.intent));
+    }
+    async header(id, auth, header) {
+        return this.request(`${this.path(id)}/header`, 'PUT', header, auth, (value) => publishedResponse(value, auth.intent));
+    }
+    async status(id, auth) {
+        return this.request(this.path(id), 'GET', undefined, auth, (value) => statusResponse(value, id, auth.intent));
+    }
+    async baseSplit(id, auth, input) {
+        exactKeys(input, ['kind', 'salt']);
+        if (input.kind !== 'push' || input.salt !== `0x${'00'.repeat(32)}`)
+            throw new AnnonError('bad_request');
+        return this.request(`${this.path(id)}/base-split`, 'POST', JSON.stringify(input), auth, (value, status) => {
+            exactKeys(value, ['baseSplit']);
+            const baseSplit = splitResponse(value.baseSplit);
+            if (!baseSplit || status !== (baseSplit.state === 'pending' ? 202 : 200))
+                throw new AnnonError('bad_request');
+            return { baseSplit };
+        });
+    }
+}

package/dist/envelope/evm.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Whether `sig` (r ‖ s ‖ v, low s, v 27 or 28) is `address` signing `text` with EIP-191.
+ */
+export declare function signedBy(text: string, sig: Uint8Array, address: string): boolean;

package/dist/envelope/evm.js

@@ -0,0 +1,32 @@
+import { secp256k1 } from '@noble/curves/secp256k1.js';
+import { keccak_256 } from '@noble/hashes/sha3.js';
+import { hexDigits as toHex } from '../bytes.js';
+const utf8 = new TextEncoder();
+const concat = (...parts) => Uint8Array.from(parts.flatMap((p) => Array.from(p)));
+/**
+ * Whether `sig` (r ‖ s ‖ v, low s, v 27 or 28) is `address` signing `text` with EIP-191.
+ */
+export function signedBy(text, sig, address) {
+    return signerOf(text, sig) === address.toLowerCase();
+}
+/**
+ * The address that signed `text` with EIP-191 (r ‖ s ‖ v, low s, v 27 or 28), lowercase 0x, or
+ * null for a signature that recovers to nobody.
+ */
+function signerOf(text, sig) {
+    if (sig.length !== 65 || (sig[64] !== 27 && sig[64] !== 28))
+        return null;
+    const s = BigInt(`0x${toHex(sig.subarray(32, 64))}`);
+    if (s > secp256k1.Point.Fn.ORDER / 2n)
+        return null;
+    const t = utf8.encode(text);
+    const digest = keccak_256(concat(utf8.encode(`\x19Ethereum Signed Message:\n${t.length}`), t));
+    try {
+        const recovered = concat(new Uint8Array([(sig[64] ?? 27) - 27]), sig.subarray(0, 64));
+        const pub = secp256k1.Point.fromBytes(secp256k1.recoverPublicKey(recovered, digest, { prehash: false }));
+        return `0x${toHex(keccak_256(pub.toBytes(false).subarray(1)).subarray(12))}`;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/envelope/pay2.d.ts

@@ -0,0 +1,176 @@
+import { AnnonError } from '../errors.js';
+import { type Identity } from '../settle-near/identity.js';
+export type Bytes = Uint8Array<ArrayBuffer>;
+export type Pay2ErrorCode = 'bad_magic' | 'unsupported_version' | 'bad_chunk_size' | 'header_too_large' | 'bad_header' | 'bad_stanza' | 'file_id_mismatch' | 'cipher_hash_mismatch' | 'seller_signature_invalid' | 'bad_body_length' | 'chunk_hash_mismatch' | 'no_usable_stanza' | 'key_unwrap_failed' | 'header_mac_invalid' | 'chunk_invalid' | 'meta_invalid' | 'preview_invalid';
+export declare class Pay2Error extends AnnonError {
+    readonly code: Pay2ErrorCode;
+    constructor(code: Pay2ErrorCode, message?: string);
+}
+export interface FileMeta {
+    name: string;
+    mime: string;
+    size: number;
+}
+/** What the contract holds for the file (`get_file`), which the bytes are checked against. */
+export interface Listing {
+    fileId: string | Uint8Array;
+    cipherHash: string | Uint8Array;
+    /** Registered seller; an EVM address is accepted as API shorthand. */
+    seller: string | Identity;
+    /** NEAR v2 only: SHA256(header without its 65-byte trailer), read at finality. */
+    publishedHeaderHash?: string | Uint8Array;
+    /** Registered version, always 2. */
+    pay2Version?: 2;
+}
+export interface PreviewPackage {
+    v: 1;
+    header: string;
+    chunks: {
+        index: number;
+        key: string;
+        data: string;
+    }[];
+}
+export declare const MAGIC: number[];
+export declare const FIXED = 54;
+export declare const TAG = 16;
+export declare const MAX_HEADER = 65536;
+export declare const MAX_CHUNKS = 1024;
+export declare const MAX_META = 4096;
+export declare const MAC = 32;
+export declare const SIG = 65;
+export declare const NEAR_CKD = "near-ckd/v1";
+export declare function concat(...parts: Uint8Array[]): Bytes;
+export declare function int(value: number, bytes: 1 | 2 | 4 | 8): Bytes;
+export declare const equal: (a: Uint8Array, b: Uint8Array) => boolean;
+export declare const copy: (b: Uint8Array) => Bytes;
+export declare function sha256(...parts: Uint8Array[]): Promise<Bytes>;
+/** Derives 32 bytes. `ikm` is raw bytes or an HKDF key, so an unwrapped `K` never leaves WebCrypto. */
+declare function hkdf(ikm: Uint8Array | CryptoKey, salt: Uint8Array, info: Uint8Array | string): Promise<Uint8Array<ArrayBuffer>>;
+export declare const chunkKey: (K: Uint8Array | CryptoKey, fileId: Uint8Array, i: number) => Promise<Uint8Array<ArrayBuffer>>;
+/** Spec 2: binds a revealable chunk key, since AES-GCM alone doesn't commit to its key. */
+export declare const commitment: (k: Uint8Array) => Promise<Bytes>;
+declare function gcm(mode: 'encrypt' | 'decrypt', key: Uint8Array, last: boolean, data: Uint8Array): Promise<Uint8Array<ArrayBuffer>>;
+export { gcm, hkdf };
+export declare const wrapKeyFor: (ckdSecret: Uint8Array, fileId: Uint8Array, usage: KeyUsage) => Promise<CryptoKey>;
+/** Spec 3: binds the layout fields known before `register`, the commitments and the hash list. */
+export declare const bodyHash: (h: Pick<Header, "chunkLog2" | "fileId" | "metaLen" | "previewLen" | "n" | "commits" | "hashes"> & {
+    version?: 2;
+}) => Promise<Bytes>;
+export { signedBy } from './evm.js';
+interface Header {
+    version: 2;
+    authKind: 0 | 1 | 2;
+    chunkLog2: number;
+    fileId: Bytes;
+    metaLen: number;
+    previewLen: number;
+    n: number;
+    commits: Bytes[];
+    hashes: Bytes[];
+    prefixLen: number;
+    headerLen: number;
+    stanzas: {
+        type: string;
+        body: Bytes;
+    }[];
+}
+/** Spec 6, step 1. With `prefixOnly`, stops after the hash list (a preview package). */
+export declare function parseHeader(b: Bytes, prefixOnly?: boolean): Header;
+/** Spec 5.1: `u8 len ‖ contractId ‖ wrapped K (40)`. */
+export declare function nearCkd(body: Bytes): {
+    contractId: string;
+    wrapped: Bytes;
+} | undefined;
+/** Spec 3: the chunk count a file of `size` bytes must have. */
+export declare const chunkCount: (size: number, previewLen: number, chunkLog2: number) => number;
+/** Spec 3.1, and the checks against the header that need only the metadata. */
+export declare function parseMeta(piece: Bytes, h: Header): FileMeta;
+export interface Inspected {
+    fileId: Bytes;
+    /** Whether a `near-ckd/v1` stanza names the trusted contract; `open` needs one. */
+    usable: boolean;
+    /** The header, signature included: the bytes `info.header` serves (x402-annon.md section 7). */
+    header: Bytes;
+    /** `SHA256(header)`, which the download challenge names. */
+    headerHash: Bytes;
+}
+/**
+ * Spec 6, steps 1 to 4: needs no key, so a client can run it before paying when the bytes are
+ * public. Throws `Pay2Error`.
+ */
+export declare function inspect(file: Uint8Array, listing: Listing, contractId: string): Promise<Inspected>;
+/**
+ * Spec 6, steps 1 to 3, on the header alone: what a client checks before paying when only the
+ * header is public (x402-annon.md section 7). `header` must be exactly the header, with no body bytes.
+ * It proves which bytes the buyer pays for, not that a host holds them. Throws `Pay2Error`.
+ */
+export declare function inspectHeader(header: Uint8Array, listing: Listing, contractId: string): Promise<Inspected>;
+/** Spec 6, steps 1 to 3. */
+export declare function checkSigned(b: Bytes, listing: Listing, contractId: string): Promise<Header>;
+export interface OpenOptions {
+    /** The contract's registration of this file. */
+    listing: Listing;
+    /** The Annon contract the client trusts. Never taken from the file or a link. */
+    contractId: string;
+    /** Returns the 48-byte CKD point for this file; called only after steps 1 to 5 pass. */
+    ckdSecret: (fileId: Uint8Array) => Promise<Uint8Array>;
+}
+/** Spec 6, all steps. Returns nothing unless every check passes. */
+export declare function open(file: Uint8Array, opts: OpenOptions): Promise<{
+    meta: FileMeta;
+    data: Bytes;
+}>;
+export interface SealOptions {
+    /** Select the registered seller authentication kind before sealing. Version is always 2. */
+    version?: 2;
+    authKind?: 0 | 1 | 2;
+    fileId: Uint8Array;
+    name: string;
+    mime: string;
+    /** Bytes of the file shown as a verified preview; 0 (default) means none. Spec 3 caps it. */
+    previewLen?: number;
+    /** Spec 3: 22 (4 MiB) unless the file needs more than 1024 chunks. */
+    chunkLog2?: number;
+}
+export interface FinishOptions {
+    contractId: string;
+    ckdSecret: Uint8Array;
+    seller: string | Identity;
+    /** EVM: EIP-191; Solana: Wallet Standard result including the exact signed message. */
+    sign?: (text: string) => Promise<string | Uint8Array | {
+        signature: Uint8Array;
+        signedMessage: Uint8Array;
+    }>;
+}
+/** @internal Shared by buffered and streaming encoders. */
+export declare function sealAuth(opts: SealOptions): {
+    version: 2;
+    authKind: 0 | 1 | 2;
+};
+/** @internal Build and check the fixed-width authentication trailer. */
+export declare function finishTrailer(version: 2, authKind: 0 | 1 | 2, opts: FinishOptions, fileId: Uint8Array, headerHash: Uint8Array): Promise<Uint8Array>;
+export interface Sealed {
+    fileId: Bytes;
+    /** Goes into `register` as `cipher_hash`. */
+    cipherHash: Bytes;
+    /**
+     * Once `register` has returned the CKD point: writes the `near-ckd/v1` stanza and the MAC, then
+     * asks the seller's wallet to sign `publishText` (EIP-191) and checks the signature.
+     */
+    finish(opts: FinishOptions): Promise<Bytes>;
+    /**
+     * The preview package (spec 7), after `finish`. Publishes those chunks' keys: only when the
+     * seller asks.
+     */
+    preview(show: {
+        meta?: boolean;
+        data?: boolean;
+    }): Promise<PreviewPackage>;
+}
+/** Encrypts a file under a fresh random key. */
+export declare function seal(data: Uint8Array, opts: SealOptions): Promise<Sealed>;
+/** Encrypts with a caller-supplied fresh key, including deterministic replay. Never reuse it for another file. */
+export declare function sealWithKey(K: Uint8Array, data: Uint8Array, opts: SealOptions): Promise<Sealed>;
+/** Spec 3: at most 64 KiB and a tenth of the file. */
+export declare const previewLimit: (size: number) => number;