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

package/dist/settle-near/terms.js

@@ -0,0 +1,89 @@
+/** Borsh commitments and seller texts, near-settlement.md §3. */
+import { account, bytes, compare, concat, exactKeys, hash, le, network, str, uint, usdc, utc, } from './codec.js';
+import { encodeIdentity, identityText } from './identity.js';
+export const BASE_USDC = '0x833589fcd6edb6e08f4c7c32d4f71b54bda02913';
+export const NEAR_USDC = '17208628f84f5d6ad33f0da3bbbeb27ffcb398eac501a31bd6ad2011e36133a1';
+const price = (p) => {
+    const n = uint(p, 128);
+    if (n === 0n)
+        throw new RangeError('price must be positive');
+    return le(n, 16);
+};
+export function encodeTerms(t, assets = {}) {
+    exactKeys(t, [
+        'network',
+        'contract',
+        'file_id',
+        'seller',
+        'pay2_version',
+        'cipher_hash',
+        'moderator',
+        'near',
+        'base',
+    ]);
+    exactKeys(t.near, ['token', 'price', 'recipients', 'remainder']);
+    if (t.base !== null) {
+        exactKeys(t.base, ['usdc', 'price', 'pay_to']);
+        if (t.base.usdc !== (assets.baseUsdc ?? BASE_USDC))
+            throw new TypeError('invalid Base USDC');
+    }
+    network(t.network);
+    account(t.contract);
+    if (t.pay2_version !== 2)
+        throw new TypeError('unsupported PAY2 version');
+    const n = t.near;
+    account(n.token);
+    if (((assets.nearUsdc !== undefined || t.network === 'near:mainnet') &&
+        n.token !== (assets.nearUsdc ?? NEAR_USDC)) ||
+        n.recipients.length < 1 ||
+        n.recipients.length > 8 ||
+        !Number.isInteger(n.remainder) ||
+        n.remainder < 0 ||
+        n.remainder >= n.recipients.length)
+        throw new TypeError('invalid NEAR terms');
+    let prev;
+    let sum = 0;
+    const recipients = n.recipients.map((r) => {
+        exactKeys(r, ['identity', 'bps']);
+        const id = encodeIdentity(r.identity);
+        if (prev && compare(prev, id) >= 0)
+            throw new TypeError('recipients must be distinct and Borsh sorted');
+        prev = id;
+        if (!Number.isInteger(r.bps) || r.bps <= 0 || r.bps > 10000)
+            throw new TypeError('invalid bps');
+        sum += r.bps;
+        return concat(id, le(r.bps, 2));
+    });
+    if (sum !== 10000)
+        throw new TypeError('bps must sum to 10000');
+    return concat(str(t.network), str(t.contract), bytes(t.file_id, 32), encodeIdentity(t.seller), le(t.pay2_version, 1), bytes(t.cipher_hash, 32), t.moderator === null ? le(0, 1) : concat(le(1, 1), str(account(t.moderator))), str(n.token), price(n.price), le(recipients.length, 4), ...recipients, le(n.remainder, 1), t.base === null
+        ? le(0, 1)
+        : concat(le(1, 1), bytes(t.base.usdc, 20), price(t.base.price), bytes(t.base.pay_to, 20)));
+}
+export const termsHash = (t, assets) => hash('annon/terms/v2', encodeTerms(t, assets));
+export function registerTextV2(t, sellerKey, deadline, assets) {
+    const commitment = termsHash(t, assets);
+    bytes(sellerKey, 48);
+    return [
+        'Annon: list a file for sale',
+        'Signing this lets whoever holds the seller key below open the file.',
+        `contract: ${t.contract}`,
+        `file: ${t.file_id}`,
+        `seller: ${identityText(t.seller)}`,
+        `price: ${usdc(t.near.price)} USDC on NEAR`,
+        ...t.near.recipients.map((r) => `split: ${identityText(r.identity)} ${(r.bps / 100).toFixed(2)}%`),
+        `remainder: ${identityText(t.near.recipients[t.near.remainder].identity)}`,
+        t.base ? `base: ${usdc(t.base.price)} USDC on Base to ${t.base.pay_to}` : 'base: none',
+        `cipher: ${t.cipher_hash}`,
+        `moderator: ${t.moderator ?? '(none)'}`,
+        `terms: ${commitment}`,
+        `seller key: ${sellerKey}`,
+        `valid until: ${utc(deadline)}`,
+    ].join('\n');
+}
+export function publishTextV2(contract, fileId, headerHash) {
+    account(contract);
+    bytes(fileId, 32);
+    bytes(headerHash, 32);
+    return `Annon: publish a file\ncontract: ${contract}\nfile: ${fileId}\nheader: ${headerHash}`;
+}

package/dist/shops/discovery.d.ts

@@ -0,0 +1,95 @@
+import { type AnnonErrorCode } from '../errors.js';
+import { type Terms } from '../settle-near/terms.js';
+export interface ShopRules {
+    text: string;
+    uploadsPerPersonPerDay?: number;
+    attemptsPerPersonPerDay?: number;
+    fileLifetimeDays?: number | null;
+    maxFileBytes?: number;
+}
+export interface ShopManifest {
+    rules?: ShopRules;
+    version: 1;
+    name: string;
+    shopUrl: string;
+    network: 'near:mainnet';
+    contract: string;
+    relayer: string;
+    host: string;
+    catalog: {
+        url: string;
+        format: 'annon-catalog-array-v1';
+        search: 'client';
+    };
+}
+/** Deployment facts approved in local configuration, never copied from remote documents. */
+export interface ShopProfile {
+    network: 'near:mainnet';
+    contract: string;
+    nearRpc: string;
+    baseRpc?: string;
+    relayer: string;
+    host: string;
+}
+export interface ConfiguredShop {
+    manifest: string;
+    id?: string;
+    profile?: ShopProfile;
+}
+export interface DiscoveryConfig {
+    shopDirectoryUrl?: string;
+    shops?: ConfiguredShop[];
+    defaultShop?: string;
+}
+export interface Shop {
+    manifest: string;
+    id?: string;
+    info: ShopManifest;
+    trusted: boolean;
+}
+export interface ShopFailure {
+    manifest: string;
+    id?: string;
+    trusted: boolean;
+    error: AnnonErrorCode;
+}
+export interface CatalogEntry {
+    name: string;
+    fileId: string;
+    title: string;
+    description: string;
+    url: string;
+    header: string;
+    byteSize: number;
+    plaintextSize: number;
+    createdAt: number;
+    expiresAt: number | null;
+    termsHash: string;
+    terms: Terms;
+    salesStopped: boolean;
+    takenDown: boolean;
+}
+export interface DiscoveryQuery {
+    search?: string;
+    limit?: number;
+    offset?: number;
+}
+export interface CatalogQuery extends DiscoveryQuery {
+    shop?: string;
+}
+export interface DiscoveryPage<T> {
+    items: T[];
+    total: number;
+    nextOffset: number | null;
+}
+export declare function canonicalManifestUrl(value: string): string;
+export declare function validateDiscoveryConfig(value: unknown): DiscoveryConfig;
+export declare function readShop(shop: ConfiguredShop, fetcher?: typeof fetch): Promise<Shop>;
+export declare function listShops(config?: DiscoveryConfig, query?: DiscoveryQuery, fetcher?: typeof fetch): Promise<DiscoveryPage<Shop | ShopFailure>>;
+export declare function catalog(config: DiscoveryConfig, query?: CatalogQuery, fetcher?: typeof fetch): Promise<DiscoveryPage<CatalogEntry> & {
+    shop?: {
+        manifest: string;
+        name: string;
+    };
+    rules?: ShopRules;
+}>;

package/dist/shops/discovery.js

@@ -0,0 +1,384 @@
+import { AnnonError, present, toPublicError } from '../errors.js';
+import { MAX_PAY2_BYTES, MAX_PLAINTEXT_BYTES } from '../limits.js';
+import { account, bytes, exactKeys } from '../settle-near/codec.js';
+import { termsHash } from '../settle-near/terms.js';
+const MANIFEST_PATH = '/.well-known/annon-shop.json';
+function https(value) {
+    if (typeof value !== 'string')
+        throw new TypeError('invalid URL');
+    const url = new URL(value);
+    if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash)
+        throw new TypeError('invalid discovery URL');
+    return url.href;
+}
+function origin(value) {
+    const url = new URL(https(value));
+    if (url.pathname !== '/')
+        throw new TypeError('service must be an origin');
+    return url.origin;
+}
+export function canonicalManifestUrl(value) {
+    return new URL(MANIFEST_PATH, https(value)).href;
+}
+const alias = (value) => typeof value === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(value);
+function object(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new TypeError('invalid object');
+    return value;
+}
+function text(value) {
+    if (typeof value !== 'string')
+        throw new TypeError('invalid text');
+}
+function integer(value, max = Number.MAX_SAFE_INTEGER) {
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0 || value > max)
+        throw new TypeError('invalid integer');
+}
+export function validateDiscoveryConfig(value) {
+    try {
+        const c = object(value);
+        const out = {};
+        if (c.shopDirectoryUrl !== undefined)
+            out.shopDirectoryUrl = https(c.shopDirectoryUrl);
+        if (c.shops !== undefined) {
+            if (!Array.isArray(c.shops) || c.shops.length > 100)
+                throw new TypeError('invalid shops');
+            const ids = new Set();
+            const urls = new Set();
+            out.shops = c.shops.map((item) => {
+                const s = object(item);
+                exactKeys(s, ['manifest', ...['id', 'profile'].filter((key) => Object.hasOwn(s, key))]);
+                const manifest = canonicalManifestUrl(s.manifest);
+                if (urls.has(manifest))
+                    throw new TypeError('duplicate shop');
+                urls.add(manifest);
+                const shop = { manifest };
+                if (s.id !== undefined) {
+                    if (!alias(s.id) || ids.has(s.id))
+                        throw new TypeError('invalid alias');
+                    ids.add(s.id);
+                    shop.id = s.id;
+                }
+                if (s.profile !== undefined) {
+                    const p = object(s.profile);
+                    exactKeys(p, [
+                        'network',
+                        'contract',
+                        'nearRpc',
+                        'relayer',
+                        'host',
+                        ...(Object.hasOwn(p, 'baseRpc') ? ['baseRpc'] : []),
+                    ]);
+                    if (p.network !== 'near:mainnet')
+                        throw new TypeError('invalid profile network');
+                    shop.profile = {
+                        network: p.network,
+                        contract: account(p.contract),
+                        nearRpc: https(p.nearRpc),
+                        ...(p.baseRpc !== undefined ? { baseRpc: https(p.baseRpc) } : {}),
+                        relayer: origin(p.relayer),
+                        host: origin(p.host),
+                    };
+                }
+                return shop;
+            });
+        }
+        if (c.defaultShop !== undefined) {
+            text(c.defaultShop);
+            if (!out.shops?.some((s) => s.id === c.defaultShop || s.manifest === c.defaultShop))
+                throw new TypeError('unknown default shop');
+            out.defaultShop = c.defaultShop;
+        }
+        return out;
+    }
+    catch (cause) {
+        throw new AnnonError('invalid_config', undefined, { cause });
+    }
+}
+function validateRules(value) {
+    const r = object(value);
+    const keys = [
+        'uploadsPerPersonPerDay',
+        'attemptsPerPersonPerDay',
+        'fileLifetimeDays',
+        'maxFileBytes',
+    ];
+    exactKeys(r, ['text', ...keys.filter((key) => Object.hasOwn(r, key))]);
+    text(r.text);
+    if (!r.text.trim() ||
+        new TextEncoder().encode(r.text).byteLength > 4096 ||
+        /[\p{Cc}\p{Cs}\u2028\u2029]|(?![\u200c\u200d])\p{Cf}/u.test(r.text))
+        throw new TypeError('invalid rules text');
+    for (const key of keys) {
+        if (!Object.hasOwn(r, key))
+            continue;
+        if (key === 'fileLifetimeDays' && r[key] === null)
+            continue;
+        integer(r[key]);
+    }
+    return r;
+}
+function validateManifest(value) {
+    const m = object(value);
+    exactKeys(m, [
+        'version',
+        'name',
+        'shopUrl',
+        'network',
+        'contract',
+        'relayer',
+        'host',
+        'catalog',
+        ...(Object.hasOwn(m, 'rules') ? ['rules'] : []),
+    ]);
+    const c = object(m.catalog);
+    exactKeys(c, ['url', 'format', 'search']);
+    if (m.version !== 1 ||
+        m.network !== 'near:mainnet' ||
+        c.format !== 'annon-catalog-array-v1' ||
+        c.search !== 'client')
+        throw new TypeError('unsupported manifest');
+    text(m.name);
+    if (!m.name.trim())
+        throw new TypeError('missing shop name');
+    const host = origin(m.host);
+    const url = https(c.url);
+    if (new URL(url).origin !== host)
+        throw new TypeError('catalog origin mismatch');
+    return {
+        version: 1,
+        ...(Object.hasOwn(m, 'rules') ? { rules: validateRules(m.rules) } : {}),
+        name: m.name,
+        shopUrl: https(m.shopUrl),
+        network: m.network,
+        contract: account(m.contract),
+        relayer: origin(m.relayer),
+        host,
+        catalog: { url, format: c.format, search: c.search },
+    };
+}
+async function json(url, max, fetcher) {
+    try {
+        const r = await fetcher(https(url), {
+            credentials: 'omit',
+            redirect: 'error',
+            cache: 'no-store',
+            signal: AbortSignal.timeout(10000),
+        });
+        if (r.status !== 200 || r.redirected || (r.url && r.url !== url) || !r.body)
+            throw new AnnonError('bad_response');
+        const reader = r.body.getReader();
+        try {
+            if (Number(r.headers.get('content-length')) > max)
+                throw new AnnonError('too_large');
+            let size = 0;
+            const parts = [];
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                size += value.byteLength;
+                if (size > max)
+                    throw new AnnonError('too_large');
+                parts.push(value);
+            }
+            const all = new Uint8Array(size);
+            let offset = 0;
+            for (const part of parts) {
+                all.set(part, offset);
+                offset += part.byteLength;
+            }
+            try {
+                return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(all));
+            }
+            catch (cause) {
+                throw new AnnonError('invalid_record', undefined, { cause });
+            }
+        }
+        finally {
+            await reader.cancel().catch(() => { });
+        }
+    }
+    catch (cause) {
+        if (cause instanceof AnnonError)
+            throw cause;
+        throw new AnnonError('transport', undefined, { cause });
+    }
+}
+export async function readShop(shop, fetcher = globalThis.fetch) {
+    const manifest = canonicalManifestUrl(shop.manifest);
+    let info;
+    try {
+        const raw = object(await json(manifest, 65536, fetcher));
+        const p = shop.profile;
+        if (p &&
+            (raw.network !== p.network ||
+                raw.contract !== p.contract ||
+                origin(raw.relayer) !== p.relayer ||
+                origin(raw.host) !== p.host ||
+                (raw.nearRpc !== undefined && https(raw.nearRpc) !== p.nearRpc) ||
+                (raw.baseRpc !== undefined && https(raw.baseRpc) !== p.baseRpc)))
+            throw new AnnonError('config_conflict');
+        info = validateManifest(raw);
+    }
+    catch (cause) {
+        if (cause instanceof AnnonError)
+            throw cause;
+        throw new AnnonError('invalid_record', undefined, { cause });
+    }
+    return {
+        manifest,
+        ...(shop.id !== undefined ? { id: shop.id } : {}),
+        info,
+        trusted: shop.profile !== undefined,
+    };
+}
+function paging(query) {
+    const { limit = 20, offset = 0, search = '' } = query;
+    if (!Number.isSafeInteger(limit) ||
+        limit < 1 ||
+        limit > 100 ||
+        !Number.isSafeInteger(offset) ||
+        offset < 0 ||
+        typeof search !== 'string')
+        throw new AnnonError('invalid_arguments');
+    return { limit, offset, search: search.toLowerCase() };
+}
+function page(all, { limit, offset }) {
+    const items = all.slice(offset, offset + limit);
+    const nextOffset = offset + items.length < all.length ? offset + items.length : null;
+    return { items, total: all.length, nextOffset };
+}
+async function configuredShops(config, fetcher) {
+    const shops = [...(config.shops ?? [])];
+    if (config.shopDirectoryUrl) {
+        const d = await json(config.shopDirectoryUrl, 262144, fetcher);
+        try {
+            exactKeys(d, ['version', 'shops']);
+            if (d.version !== 1 || !Array.isArray(d.shops))
+                throw new TypeError('invalid directory');
+            if (d.shops.length > 100)
+                throw new AnnonError('too_large');
+            for (const entry of d.shops) {
+                exactKeys(entry, ['manifest']);
+                const manifest = canonicalManifestUrl(entry.manifest);
+                if (!shops.some((s) => s.manifest === manifest))
+                    shops.push({ manifest });
+            }
+        }
+        catch (cause) {
+            if (cause instanceof AnnonError)
+                throw cause;
+            throw new AnnonError('invalid_record', undefined, { cause });
+        }
+    }
+    return shops;
+}
+export async function listShops(config = {}, query = {}, fetcher = globalThis.fetch) {
+    const q = paging(query);
+    const c = validateDiscoveryConfig(config);
+    const shops = await configuredShops(c, fetcher);
+    const all = new Array(shops.length);
+    let next = 0;
+    const results = await Promise.allSettled(Array.from({ length: Math.min(4, shops.length) }, async () => {
+        while (next < shops.length) {
+            const index = next++;
+            const shop = present(shops[index]);
+            try {
+                all[index] = await readShop(shop, fetcher);
+            }
+            catch (error) {
+                if (shop.profile && error instanceof AnnonError && error.code === 'config_conflict')
+                    throw error;
+                all[index] = {
+                    manifest: shop.manifest,
+                    ...(shop.id !== undefined ? { id: shop.id } : {}),
+                    trusted: !!shop.profile,
+                    error: toPublicError(error).code,
+                };
+            }
+        }
+    }));
+    for (const result of results)
+        if (result.status === 'rejected')
+            throw result.reason;
+    return page(all.filter((shop) => ('info' in shop ? shop.info.name : (shop.id ?? shop.manifest))
+        .toLowerCase()
+        .includes(q.search)), q);
+}
+function validateCatalog(value, shop) {
+    if (!Array.isArray(value))
+        throw new TypeError('invalid catalog');
+    if (value.length > 10000)
+        throw new AnnonError('too_large');
+    return value.map((item) => {
+        exactKeys(item, [
+            'name',
+            'fileId',
+            'title',
+            'description',
+            'url',
+            'header',
+            'byteSize',
+            'plaintextSize',
+            'createdAt',
+            'expiresAt',
+            'termsHash',
+            'terms',
+            'salesStopped',
+            'takenDown',
+        ]);
+        for (const key of ['name', 'title', 'description'])
+            text(item[key]);
+        bytes(item.fileId, 32);
+        bytes(item.termsHash, 32);
+        for (const key of ['url', 'header'])
+            if (new URL(https(item[key])).origin !== shop.host)
+                throw new AnnonError('config_conflict');
+        integer(item.byteSize, MAX_PAY2_BYTES);
+        integer(item.plaintextSize, MAX_PLAINTEXT_BYTES);
+        integer(item.createdAt);
+        if (item.expiresAt !== null) {
+            integer(item.expiresAt);
+            if (item.expiresAt < item.createdAt)
+                throw new TypeError('invalid expiry');
+        }
+        if (typeof item.salesStopped !== 'boolean' || typeof item.takenDown !== 'boolean')
+            throw new TypeError('invalid listing flags');
+        const terms = item.terms;
+        if (terms.contract !== shop.contract || terms.network !== shop.network)
+            throw new AnnonError('config_conflict');
+        if (terms.file_id !== item.fileId || termsHash(terms) !== item.termsHash)
+            throw new TypeError('invalid catalog terms');
+        return item;
+    });
+}
+export async function catalog(config, query = {}, fetcher = globalThis.fetch) {
+    const q = paging(query);
+    const c = validateDiscoveryConfig(config);
+    const selected = query.shop ?? c.defaultShop;
+    if (typeof selected !== 'string' || !selected)
+        throw new AnnonError('invalid_arguments');
+    const local = c.shops?.find((s) => s.id === selected || s.manifest === selected);
+    const found = local ?? (await configuredShops(c, fetcher)).find((s) => s.manifest === selected);
+    if (!found)
+        throw new AnnonError('invalid_arguments');
+    const shop = await readShop(found, fetcher);
+    let all;
+    try {
+        all = validateCatalog(await json(shop.info.catalog.url, 8388608, fetcher), shop.info);
+    }
+    catch (cause) {
+        if (cause instanceof AnnonError)
+            throw cause;
+        throw new AnnonError('invalid_record', undefined, { cause });
+    }
+    all = all.filter((e) => [e.name, e.title, e.description].some((s) => s.toLowerCase().includes(q.search)));
+    all.sort((a, b) => b.createdAt - a.createdAt || (a.fileId < b.fileId ? -1 : a.fileId > b.fileId ? 1 : 0));
+    return {
+        ...page(all, q),
+        ...(shop.info.rules
+            ? { shop: { manifest: shop.manifest, name: shop.info.name }, rules: shop.info.rules }
+            : {}),
+    };
+}

package/dist/wallet/account-only.d.ts

@@ -0,0 +1,11 @@
+/** Never supply contractId/methodNames: MyNearWallet otherwise generates a local secret. */
+export declare function signInAccountOnly(wallet: {
+    signOut?: () => Promise<void>;
+    signIn(params: {
+        contractId?: string;
+    }): Promise<{
+        accountId: string;
+    }[]>;
+}): Promise<{
+    accountId: string;
+}[]>;

package/dist/wallet/account-only.js

@@ -0,0 +1,6 @@
+/** Never supply contractId/methodNames: MyNearWallet otherwise generates a local secret. */
+export async function signInAccountOnly(wallet) {
+    // A reused loopback origin may contain older connector authority. Never let it sign silently.
+    await wallet.signOut?.();
+    return wallet.signIn({});
+}

package/dist/wallet/uncertain.d.ts

@@ -0,0 +1,8 @@
+import { AnnonError } from '../errors.js';
+/** Public evidence to retain whenever a submitted NEAR transaction cannot be confirmed. */
+export declare class TransactionUncertain extends AnnonError {
+    readonly txHash: string;
+    readonly purchaseId?: string | undefined;
+    readonly code = "transaction_uncertain";
+    constructor(txHash: string, purchaseId?: string | undefined);
+}

package/dist/wallet/uncertain.js

@@ -0,0 +1,13 @@
+import { AnnonError } from '../errors.js';
+/** Public evidence to retain whenever a submitted NEAR transaction cannot be confirmed. */
+export class TransactionUncertain extends AnnonError {
+    txHash;
+    purchaseId;
+    code = 'transaction_uncertain';
+    constructor(txHash, purchaseId) {
+        super('transaction_uncertain', 'Transaction submission is uncertain. Check the saved purchase and transaction hash before retrying.');
+        this.txHash = txHash;
+        this.purchaseId = purchaseId;
+        this.name = 'TransactionUncertain';
+    }
+}