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

package/dist/download/download.js

@@ -0,0 +1,384 @@
+/** Download a final purchase grant with Range retries and checked chunks. */
+import { copy, equal, parseHeader, sha256, TAG } from '../envelope/pay2.js';
+import { AnnonError } from '../errors.js';
+import { HTTP_RETRY_MAX_WAIT_SECONDS, MAX_PAY2_BYTES } from '../limits.js';
+import { parseRetryAfterMs, sleep } from '../net/retry.js';
+import { BUYER_PROOF_HEADER, purchaseProof, sameResource } from './proof.js';
+export class DownloadError extends AnnonError {
+    code;
+    retryAfterSeconds;
+    purchaseId;
+    fileId;
+    constructor(code, message = code) {
+        super(code, message);
+        this.code = code;
+        this.name = 'DownloadError';
+    }
+}
+const fail = (code, message) => {
+    throw new DownloadError(code, message);
+};
+/**
+ * Gated downloads go over HTTPS only: on plain HTTP anyone on the path reads the body or races the
+ * buyer with the intercepted authorization. Plain HTTP only for this machine, in development.
+ */
+export function secureUrl(url) {
+    const u = new URL(url);
+    const local = u.hostname === 'localhost' || u.hostname === '127.0.0.1' || u.hostname === '[::1]';
+    if (u.protocol !== 'https:' && !(u.protocol === 'http:' && local)) {
+        throw new TypeError(`${url} must be https`);
+    }
+    return u;
+}
+const b64json = (s) => {
+    try {
+        return s === null
+            ? null
+            : JSON.parse(new TextDecoder().decode(Uint8Array.from(atob(s), (c) => c.charCodeAt(0))));
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * The file as a stream: the header first, then each chunk once its hash matches. Throws
+ * `DownloadError`; a broken connection is retried from the last checked chunk.
+ */
+export function download(o) {
+    secureUrl(o.url);
+    const header = copy(o.header);
+    const h = parseHeader(header);
+    const lengths = Array.from({ length: h.n - 1 }, (_, i) => i === 0
+        ? h.metaLen + TAG
+        : i === 1 && h.previewLen > 0
+            ? h.previewLen + TAG
+            : 2 ** h.chunkLog2 + TAG);
+    const limit = Math.min(o.maxBytes ?? MAX_PAY2_BYTES, MAX_PAY2_BYTES);
+    const sizeCheck = (size) => {
+        if (size > limit)
+            fail('too_large', 'File exceeds the 50 MB size limit.');
+    };
+    sizeCheck(header.length + lengths.reduce((sum, n) => sum + n, 0) + TAG);
+    const maxLast = 2 ** h.chunkLog2 + TAG;
+    const fetcher = o.fetch ?? globalThis.fetch;
+    // Cancelling aborts any request in flight and stops before the next signature or request.
+    const abort = new AbortController();
+    const cancelExternal = () => {
+        abort.abort();
+        void activeReader?.cancel().catch(() => { });
+    };
+    if (o.signal?.aborted)
+        fail('cancelled');
+    const cleanup = () => o.signal?.removeEventListener('abort', cancelExternal);
+    const live = () => {
+        if (abort.signal.aborted)
+            fail('cancelled');
+    };
+    async function untilAbort(pending) {
+        let stop = () => { };
+        const cancelled = new Promise((_resolve, reject) => {
+            stop = () => reject(new DownloadError('cancelled'));
+            abort.signal.addEventListener('abort', stop, { once: true });
+            if (abort.signal.aborted)
+                stop();
+        });
+        try {
+            return await Promise.race([pending, cancelled]);
+        }
+        finally {
+            abort.signal.removeEventListener('abort', stop);
+        }
+    }
+    async function wait(ms) {
+        await untilAbort(o.wait ? o.wait(ms) : sleep(ms, abort.signal));
+    }
+    let waitedMs = 0;
+    let chunk = 0; // next chunk to check
+    let offset = header.length; // its first byte in the file
+    let sentHeader = false;
+    let retries = o.retries ?? 3;
+    // The buyer proof only for the URL the payment names: never for another host's.
+    // It signs the advertised `resource.url` octets, which the host checks, not the request's spelling.
+    const payment = o.payment;
+    let named = '';
+    if (payment) {
+        const u = b64json(payment.header)?.resource?.url;
+        if (typeof u !== 'string' || !sameResource(u, o.url)) {
+            throw new TypeError('the payment names another resource than the file URL');
+        }
+        named = u;
+    }
+    o.signal?.addEventListener('abort', cancelExternal, { once: true });
+    // Where the current response ends, when the host says (Content-Range or Content-Length).
+    let pos = 0;
+    let end;
+    const get = (headers, start) => {
+        live();
+        // No redirects: one could move the request to plain HTTP or another host.
+        // No cookies either: the grant proof travels in `Annon-Buyer-Proof` (x402-annon.md section 9).
+        return untilAbort(fetcher(o.url, {
+            redirect: 'error',
+            credentials: 'omit',
+            signal: abort.signal,
+            headers: { ...headers, range: `bytes=${start}-` },
+        }).then(async (response) => {
+            if (abort.signal.aborted)
+                await response.body?.cancel().catch(() => { });
+            return response;
+        }));
+    };
+    const body = (r) => r.body && (r.status === 200 || r.status === 206);
+    /** Every retry proves the same purchase grant to this URL. */
+    async function authorized() {
+        let start = offset;
+        const proof = purchaseProof(o.proof.secret, named || o.url, o.proof.purchase_id, o.proof.grant);
+        for (let i = 0;; i++) {
+            const r = await get({
+                [BUYER_PROOF_HEADER]: proof,
+                ...(payment ? { 'PAYMENT-SIGNATURE': payment.header } : {}),
+            }, start);
+            if (abort.signal.aborted) {
+                await r.body?.cancel().catch(() => { });
+                live();
+            }
+            if (body(r))
+                return { response: r, start };
+            if (r.status === 416 && start > header.length) {
+                await r.body?.cancel().catch(() => { });
+                start = header.length;
+                continue;
+            }
+            const pending = r.status === 503 || r.status === 402 || r.status === 429;
+            let code = r.status === 429 ? 'rate_limited' : r.status === 503 ? 'unavailable' : 'settlement_pending';
+            let seconds;
+            if ([429, 403, 503].includes(r.status)) {
+                // Read only a bounded control response, never an unbounded error document.
+                const reader = r.body?.getReader();
+                try {
+                    const parts = [];
+                    let size = 0;
+                    if (reader)
+                        for (;;) {
+                            const part = await untilAbort(reader.read());
+                            if (part.done)
+                                break;
+                            size += part.value.length;
+                            if (size > 8192)
+                                break;
+                            parts.push(part.value);
+                        }
+                    if (size <= 8192) {
+                        const all = new Uint8Array(size);
+                        let at = 0;
+                        for (const part of parts) {
+                            all.set(part, at);
+                            at += part.length;
+                        }
+                        const value = JSON.parse(new TextDecoder().decode(all));
+                        if ((r.status === 429 &&
+                            (value.error === 'download_limited' || value.error === 'download_in_progress')) ||
+                            (r.status === 403 && value.error === 'not_sponsored') ||
+                            (r.status === 503 && value.error === 'relayer_unavailable'))
+                            code = value.error;
+                        if (typeof value.retryAfterSeconds === 'number' &&
+                            Number.isFinite(value.retryAfterSeconds) &&
+                            value.retryAfterSeconds >= 0 &&
+                            Number.isSafeInteger(Math.ceil(value.retryAfterSeconds)))
+                            seconds = Math.ceil(value.retryAfterSeconds);
+                    }
+                }
+                catch {
+                    /* Unknown control responses still follow the bounded overload policy. */
+                }
+                finally {
+                    await reader?.cancel().catch(() => { });
+                }
+            }
+            else
+                await r.body?.cancel().catch(() => { });
+            const after = parseRetryAfterMs(r.headers.get('Retry-After'), (o.now?.() ?? Date.now() / 1000) * 1000);
+            if (after !== undefined)
+                seconds = Math.max(seconds ?? 0, Math.ceil(after / 1000));
+            const delayed = () => Object.assign(new DownloadError(code), {
+                fileId: o.fileId,
+                purchaseId: o.proof.purchase_id,
+                ...(seconds === undefined ? {} : { retryAfterSeconds: seconds }),
+            });
+            if (code === 'download_limited' || code === 'not_sponsored')
+                throw delayed();
+            if (!pending)
+                return fail('not_authorized', `the host answered ${r.status}`);
+            const delay = Math.max(1, seconds ?? (r.status === 402 ? 3 : 5)) * 1000;
+            if (i + 1 >= (o.settleTries ?? 40) ||
+                delay > HTTP_RETRY_MAX_WAIT_SECONDS * 1000 - waitedMs ||
+                delay > HTTP_RETRY_MAX_WAIT_SECONDS * 1000)
+                throw delayed();
+            waitedMs += delay;
+            await wait(delay);
+        }
+    }
+    async function request() {
+        const { response: r, start } = await authorized();
+        const length = Number(r.headers.get('content-length') ?? Number.NaN);
+        const total = Number((/\/(\d+)$/.exec(r.headers.get('content-range') ?? '') ?? [])[1]);
+        try {
+            sizeCheck(r.status === 200 ? length : start + length);
+            if (r.status === 206)
+                sizeCheck(total);
+        }
+        catch (error) {
+            await r.body?.cancel().catch(() => { });
+            throw error;
+        }
+        const source = r.body.getReader();
+        let received = r.status === 200 ? 0 : start;
+        const reader = {
+            cancel: () => source.cancel(),
+            async read() {
+                const result = await source.read();
+                live();
+                if (!result.done) {
+                    received += result.value.length;
+                    try {
+                        sizeCheck(received);
+                    }
+                    catch (error) {
+                        await source.cancel().catch(() => { });
+                        throw error;
+                    }
+                }
+                return result;
+            },
+        };
+        // Retain immediately, so external cancellation also interrupts header skipping.
+        activeReader = reader;
+        // A host without Range support sends everything: skip what was already checked.
+        if (r.status === 200) {
+            const length = Number(r.headers.get('content-length') ?? Number.NaN);
+            end = Number.isSafeInteger(length) ? length : undefined;
+            pos = offset;
+            return { reader, rest: await skip(reader, offset, header) };
+        }
+        const range = /^bytes (\d+)-(\d+)\/(\d+|\*)$/.exec(r.headers.get('content-range') ?? '');
+        // RFC 9110 section 14.4: first <= last < complete length, or the range is invalid.
+        if (!range ||
+            Number(range[1]) !== start ||
+            Number(range[2]) < start ||
+            (range[3] !== '*' && Number(range[2]) >= Number(range[3]))) {
+            await reader.cancel().catch(() => { });
+            return fail('bad_response', 'the host resumed from another offset');
+        }
+        end = Number(range[2]) + 1;
+        sizeCheck(end);
+        pos = offset;
+        return {
+            reader,
+            rest: start < offset ? await skip(reader, offset - start, new Uint8Array(0)) : new Uint8Array(0),
+        };
+    }
+    let reader;
+    let activeReader;
+    let pending = new Uint8Array(0);
+    async function read(n, eofOk) {
+        n = Math.min(n, Math.max(0, limit - offset) + 1);
+        const out = new Uint8Array(n);
+        let at = 0;
+        while (at < n) {
+            if (pending.length === 0 && !reader) {
+                const got = await request();
+                reader = got.reader;
+                pending = got.rest;
+            }
+            if (pending.length === 0) {
+                const r = await reader.read();
+                if (r.done) {
+                    // Retried: a connection can end cleanly in the middle, also before the end it announced.
+                    if (eofOk && (end === undefined || pos >= end))
+                        break;
+                    throw new Error('the connection ended early');
+                }
+                pending = r.value;
+            }
+            const take = Math.min(n - at, pending.length);
+            out.set(pending.subarray(0, take), at);
+            pending = pending.subarray(take);
+            at += take;
+            pos += take;
+        }
+        return out.subarray(0, at);
+    }
+    return new ReadableStream({
+        async pull(controller) {
+            live();
+            if (!sentHeader) {
+                sentHeader = true;
+                controller.enqueue(copy(header));
+                return;
+            }
+            for (;;) {
+                try {
+                    // The last chunk is the rest of the file: one byte over its maximum means bytes follow.
+                    const last = chunk === h.n - 1;
+                    const wire = await read(last ? maxLast + 1 : lengths[chunk], last);
+                    // Spec 6, step 4: a seller can sign a hash of a malformed last chunk, so its length is
+                    // checked on its own; one byte over the maximum is also a byte after the file.
+                    if (last && (wire.length < TAG || wire.length > maxLast)) {
+                        fail('file_mismatch', 'the last chunk has a wrong length, or bytes follow it');
+                    }
+                    if (!equal(await sha256(wire), h.hashes[chunk])) {
+                        fail('file_mismatch', `chunk ${chunk} is not the one the header names`);
+                    }
+                    controller.enqueue(wire);
+                    chunk++;
+                    offset += wire.length;
+                    if (last) {
+                        cleanup();
+                        controller.close();
+                        await reader?.cancel().catch(() => { });
+                    }
+                    return;
+                }
+                catch (e) {
+                    // Only a broken connection is retried: fetch's network TypeError, a stream error, or
+                    // an early end. A mismatch, a refusal or a cancellation ends the download.
+                    await activeReader?.cancel().catch(() => { });
+                    reader = undefined;
+                    pending = new Uint8Array(0);
+                    if (abort.signal.aborted) {
+                        cleanup();
+                        fail('cancelled');
+                    }
+                    if (e instanceof DownloadError || retries-- <= 0) {
+                        // Final: abort every request of this download, including a response rejected
+                        // before its reader was kept.
+                        abort.abort();
+                        cleanup();
+                        throw e;
+                    }
+                }
+            }
+        },
+        async cancel() {
+            abort.abort();
+            cleanup();
+            await activeReader?.cancel().catch(() => { });
+        },
+    }, { highWaterMark: 0 });
+}
+/** Drops the first `n` bytes; returns what came after them in the same read. */
+async function skip(reader, n, header) {
+    // Note: a host without Range costs bandwidth on a resume, not memory.
+    let left = n;
+    for (;;) {
+        const r = await reader.read();
+        if (r.done)
+            throw new Error('the connection ended before the resume point');
+        const at = n - left;
+        const check = Math.min(r.value.length, left, Math.max(0, header.length - at));
+        if (!equal(r.value.subarray(0, check), header.subarray(at, at + check)))
+            fail('file_mismatch', 'the host sent another header');
+        if (r.value.length >= left)
+            return r.value.subarray(left);
+        left -= r.value.length;
+    }
+}

package/dist/download/host.d.ts

@@ -0,0 +1,56 @@
+import { PayError } from '../pay/base.js';
+import { type SettleOptions } from '../pay/settle.js';
+export type HostRecord = import('../pay/settle.js').SellerRecord;
+export interface DownloadInput {
+    network: string;
+    contract: string;
+    purchaseId: string;
+    fileId: string;
+    version: string;
+    size: number;
+    headerLength: number;
+    start: number;
+    range: boolean;
+}
+export interface DownloadDelivery {
+    wrote(offset: number): Promise<void>;
+    prepare(): Promise<void>;
+    finish(): Promise<void>;
+    interrupt(): Promise<void>;
+}
+export type DownloadReservation = {
+    ok: true;
+    delivery: DownloadDelivery;
+} | {
+    ok: false;
+    status: 416 | 429;
+    code: 'bad_request' | 'download_limited' | 'download_in_progress';
+    retryAfterSeconds?: number;
+};
+export interface DownloadAccounting {
+    reserve(input: DownloadInput): Promise<DownloadReservation>;
+}
+export interface FileHostOptions extends SettleOptions {
+    /** Host-only diagnostics; never included in the HTTP response. */
+    onPaymentError?(error: PayError): void | Promise<void>;
+    headerHash: string;
+    downloads?: DownloadAccounting;
+    settlementPollSeconds?: number;
+    file: {
+        size: number;
+        headerLength?: number;
+        read(start: number): ReadableStream<Uint8Array>;
+    };
+}
+export interface HostRequest {
+    headers: {
+        get(name: string): string | null;
+    };
+}
+export interface HostResponse {
+    status: number;
+    headers: Record<string, string>;
+    body?: ReadableStream<Uint8Array>;
+    delivery?: DownloadDelivery;
+}
+export declare function serveFile(req: HostRequest, o: FileHostOptions): Promise<HostResponse>;

package/dist/download/host.js

@@ -0,0 +1,161 @@
+/** Downloads are authorized only by a final purchase grant (§9). */
+import { isTransient } from '../errors.js';
+import { getFile, getGrant, getPurchase } from '../near/rpc.js';
+import { PayError } from '../pay/base.js';
+import { paymentRequired } from '../pay/seller.js';
+import { paymentResponse, settle } from '../pay/settle.js';
+import { BUYER_PROOF_HEADER, readPurchaseProof, verifyBuyerProof } from './proof.js';
+const b64json = (v) => btoa(String.fromCharCode(...new TextEncoder().encode(JSON.stringify(v))));
+export async function serveFile(req, o) {
+    const headers = { 'Cache-Control': 'no-store' };
+    const file = await getFile(o.nearRpc, o.contractId, o.fileId);
+    if (!file)
+        return { status: 404, headers };
+    if (file.takenDown !== null)
+        return { status: 410, headers };
+    const payload = req.headers.get('PAYMENT-SIGNATURE');
+    if (payload) {
+        try {
+            const settled = await settle(payload, o);
+            headers['PAYMENT-RESPONSE'] = b64json(paymentResponse(settled));
+            if (settled.state === 'pending')
+                headers['Retry-After'] = String(o.settlementPollSeconds ?? 10);
+        }
+        catch (e) {
+            if (!(e instanceof PayError))
+                throw e;
+            try {
+                void Promise.resolve(o.onPaymentError?.(e)).catch(() => { });
+            }
+            catch {
+                // Diagnostics must not change the payment response.
+            }
+            const code = e.code;
+            const retry = e.retryAfterSeconds ??
+                (code === 'settlement_pending' || code === 'facilitator_busy' || code === 'unavailable'
+                    ? (o.settlementPollSeconds ?? 10)
+                    : code === 'relayer_unavailable'
+                        ? 30
+                        : undefined);
+            const status = code === 'not_sponsored'
+                ? 403
+                : code === 'settlement_pending' ||
+                    code === 'facilitator_busy' ||
+                    code === 'unavailable' ||
+                    code === 'relayer_unavailable'
+                    ? 503
+                    : isTransient(e)
+                        ? 502
+                        : code === 'payment_id_conflict'
+                            ? 409
+                            : 400;
+            const message = code === 'route_unavailable'
+                ? 'This file does not support the selected payment route.'
+                : code === 'settlement_pending'
+                    ? 'Settlement is pending. Try again later.'
+                    : code === 'not_sponsored'
+                        ? 'This file is not sponsored.'
+                        : code === 'relayer_unavailable'
+                            ? 'Relayer is temporarily unavailable.'
+                            : 'Payment could not be completed.';
+            return {
+                status,
+                headers: {
+                    ...headers,
+                    'Content-Type': 'application/json',
+                    ...(retry === undefined ? {} : { 'Retry-After': String(retry) }),
+                },
+                body: new Response(JSON.stringify({
+                    error: code,
+                    message,
+                    ...(retry === undefined ? {} : { retryAfterSeconds: retry }),
+                })).body,
+            };
+        }
+    }
+    const proof = readPurchaseProof(req.headers.get(BUYER_PROOF_HEADER));
+    if (proof) {
+        const p = await getPurchase(o.nearRpc, o.contractId, proof.purchase_id);
+        if (p && p.file_id === o.fileId && proof.grant < p.grants) {
+            const g = await getGrant(o.nearRpc, o.contractId, proof.purchase_id, proof.grant);
+            if (g && verifyBuyerProof(g.buyer_key, o.url, proof.signature))
+                return serve(req, o, headers, proof.purchase_id, file.terms?.network ?? 'near:mainnet');
+        }
+    }
+    return {
+        status: 402,
+        headers: {
+            ...headers,
+            'PAYMENT-REQUIRED': b64json(paymentRequired(o, file, file.terms.base?.usdc ?? '')),
+        },
+    };
+}
+/** `200` with the whole file, or `206` from a `Range: bytes=<start>-` offset. */
+async function serve(req, o, headers, purchaseId, network) {
+    const size = o.file.size;
+    const rawRange = req.headers.get('Range');
+    const range = /^bytes=(\d+)-$/.exec(rawRange ?? '');
+    const start = range ? Number(range[1]) : 0;
+    const base = {
+        ...headers,
+        'Cache-Control': 'private, no-store',
+        'Content-Type': 'application/octet-stream',
+        'Accept-Ranges': 'bytes',
+    };
+    if ((rawRange !== null && !range) || !Number.isSafeInteger(start) || start >= size) {
+        return { status: 416, headers: { ...base, 'Content-Range': `bytes */${size}` } };
+    }
+    const reservation = await o.downloads?.reserve({
+        network,
+        contract: o.contractId,
+        purchaseId,
+        fileId: o.fileId,
+        version: o.headerHash,
+        size,
+        headerLength: o.file.headerLength ?? 0,
+        start,
+        range: !!range,
+    });
+    if (reservation && !reservation.ok) {
+        if (reservation.status === 416)
+            return { status: 416, headers: { ...base, 'Content-Range': `bytes */${size}` } };
+        const retry = reservation.retryAfterSeconds;
+        const message = reservation.code === 'download_limited'
+            ? 'Download limit reached. Wait before downloading again.'
+            : 'A download is already in progress.';
+        return {
+            status: 429,
+            headers: {
+                ...headers,
+                'Content-Type': 'application/json',
+                ...(retry === undefined ? {} : { 'Retry-After': String(retry) }),
+            },
+            body: new Response(JSON.stringify({
+                error: reservation.code,
+                message,
+                purchaseId,
+                fileId: o.fileId,
+                ...(retry === undefined ? {} : { retryAfterSeconds: retry }),
+            })).body,
+        };
+    }
+    let body;
+    try {
+        body = o.file.read(start);
+    }
+    catch (error) {
+        if (reservation?.ok)
+            await reservation.delivery.interrupt();
+        throw error;
+    }
+    return {
+        ...(reservation?.ok ? { delivery: reservation.delivery } : {}),
+        status: range ? 206 : 200,
+        headers: {
+            ...base,
+            'Content-Length': String(size - start),
+            ...(range ? { 'Content-Range': `bytes ${start}-${size - 1}/${size}` } : {}),
+        },
+        body,
+    };
+}

package/dist/download/http.d.ts

@@ -0,0 +1,23 @@
+/** Shared exact-origin CORS policy for the file host and relayer. */
+import { type FileHostOptions, type HostResponse } from './host.js';
+export declare const DEFAULT_ORIGINS: readonly ["https://annon.dev", "https://www.annon.dev"];
+export interface CorsPolicy {
+    origins: readonly string[];
+    methods: string;
+    headers: string;
+    expose: string;
+    maxAge: number;
+}
+export declare function corsPolicy(allowed?: readonly string[], previews?: readonly string[], service?: 'host' | 'relayer', maxAge?: number): CorsPolicy;
+export declare function corsHeaders(origin: string | null | undefined, allowed?: readonly string[], expose?: string): Record<string, string>;
+export declare function preflight(headers: {
+    get(name: string): string | null;
+}, policy?: CorsPolicy): HostResponse;
+export declare function hasContentType(value: string | null | undefined, expected: 'application/json' | 'application/octet-stream'): boolean;
+export interface HttpHostOptions extends FileHostOptions {
+    allowedOrigins?: readonly string[];
+    previewOrigins?: readonly string[];
+}
+export declare function handle(method: string, headers: {
+    get(name: string): string | null;
+}, o: HttpHostOptions): Promise<HostResponse>;