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

package/dist/node/signer-mock.js

@@ -0,0 +1,79 @@
+/** Reference in-memory adapter for tests/provider integrations; inject signing and policy. */
+import { json } from './signing.js';
+const canonical = (x) => x && typeof x === 'object'
+    ? Array.isArray(x)
+        ? `[${x.map(canonical)}]`
+        : `{${Object.keys(x)
+            .sort()
+            .map((k) => `${JSON.stringify(k)}:${canonical(x[k])}`)
+            .join(',')}}`
+    : JSON.stringify(x);
+export function signerMock(o) {
+    const requests = new Map();
+    const handle = async (request) => {
+        if (request.headers.get('authorization') !== `Bearer ${o.credential}`)
+            return new Response(null, { status: 401 });
+        const path = new URL(request.url).pathname;
+        if (path === '/v1/capabilities' && request.method === 'GET')
+            return Response.json({
+                version: 1,
+                account: o.account,
+                chain: o.chain,
+                operations: o.operations,
+            });
+        let id;
+        if (path === '/v1/requests' && request.method === 'POST') {
+            const q = (await request.json());
+            if (q.version !== 1 ||
+                !/^[a-zA-Z0-9-]{1,100}$/.test(q.id) ||
+                q.account !== o.account ||
+                q.chain !== o.chain ||
+                !o.operations.includes(q.operation) ||
+                !Number.isSafeInteger(q.expiresAt) ||
+                q.expiresAt <= Date.now())
+                return new Response(null, { status: 400 });
+            id = q.id;
+            const exact = canonical(q);
+            const old = requests.get(id);
+            if (old && old.exact !== exact)
+                return new Response(null, { status: 409 });
+            if (!old) {
+                // Claim before awaiting provider approval, so duplicate requests cannot sign twice.
+                requests.set(id, { exact, q, status: 'pending' });
+                const result = await o.approve(JSON.parse(json(q)));
+                const entry = requests.get(id);
+                if (!entry)
+                    throw new Error('missing claimed request');
+                if (result === 'pending' || result === 'rejected')
+                    entry.status = result;
+                else {
+                    entry.status = 'approved';
+                    entry.result = result;
+                }
+            }
+        }
+        else if (request.method === 'GET' && path.startsWith('/v1/requests/'))
+            id = path.slice('/v1/requests/'.length);
+        else
+            return new Response(null, { status: 404 });
+        const entry = requests.get(id);
+        if (!entry)
+            return new Response(null, { status: 404 });
+        if (entry.q.expiresAt <= Date.now())
+            return new Response(null, { status: 410 });
+        return Response.json({ version: 1, id, status: entry.status, ...(entry.result ? { result: entry.result } : {}) }, { headers: { 'cache-control': 'no-store' } });
+    };
+    return Object.assign(handle, {
+        decide(id, result) {
+            const entry = requests.get(id);
+            if (entry?.status !== 'pending' || entry.q.expiresAt <= Date.now())
+                throw new Error('no pending approval');
+            if (result === 'rejected')
+                entry.status = 'rejected';
+            else {
+                entry.status = 'approved';
+                entry.result = result;
+            }
+        },
+    });
+}

package/dist/node/signer-wallet.d.ts

@@ -0,0 +1,8 @@
+import { type SignerConfig } from './agent.js';
+import type { BrowserSession } from './browser-login.js';
+import type { Input } from './cli.js';
+import type { Config } from './config.js';
+import { type Keychain } from './keychain.js';
+import { type Environment, type LocalWallet } from './wallets.js';
+export declare function assertSignerInput(o: Partial<Input>): void;
+export declare function configuredWallet(s: SignerConfig, c: Config, o: Input, env: Environment, keychain: Keychain, browser: () => Promise<BrowserSession>, terms: () => unknown): Promise<LocalWallet>;

package/dist/node/signer-wallet.js

@@ -0,0 +1,149 @@
+import { readFile } from 'node:fs/promises';
+import { sha256 } from '@noble/hashes/sha2.js';
+import { base58, base64 } from '@scure/base';
+import { Account, actions, PublicKey } from 'near-api-js';
+import { signNearUpload } from '../browser/wallets.js';
+import { proveNearControl } from '../near/nep413.js';
+import { rpcReply, txOutcome } from '../near/rpc.js';
+import { parseIdentity } from '../settle-near/identity.js';
+import { parsePurchaseMessage, purchaseId } from '../settle-near/purchase.js';
+import { TransactionUncertain } from '../wallet/uncertain.js';
+import { nearSelectorWallet } from '../wallet/wallet.js';
+import { validateSigner } from './agent.js';
+import { AdapterError } from './errors.js';
+import { decodeKeychain } from './keychain.js';
+import { remoteSigner, signingRequest, verifySigningResult, } from './signing.js';
+import { loadWallet } from './wallets.js';
+export function assertSignerInput(o) {
+    if (o.evmKeyFile !== undefined || o.nearKeyFile !== undefined || o.solanaKeyFile !== undefined)
+        throw new AdapterError('signer_init_only', 'Key-file overrides are refused with a configured signer.', 2);
+}
+export async function configuredWallet(s, c, o, env, keychain, browser, terms) {
+    assertSignerInput(o);
+    validateSigner(s);
+    if (s.mode === 'file' || s.mode === 'env' || s.mode === 'keychain') {
+        const key = s.mode === 'file'
+            ? (await readFile(s.file, 'utf8')).trim()
+            : s.mode === 'env'
+                ? env[s.name]
+                : decodeKeychain(await keychain.read(s.entry));
+        const keyEnv = s.kind === 'evm'
+            ? 'ANNON_EVM_PRIVATE_KEY'
+            : s.kind === 'near'
+                ? 'ANNON_NEAR_CREDENTIALS'
+                : 'ANNON_SOLANA_KEYPAIR';
+        return loadWallet({
+            ...o,
+            wallet: s.kind,
+            ...(s.identity ? { recovery: `${s.identity.kind}:${s.identity.id}` } : {}),
+        }, { [keyEnv]: key }, c.nearRpc, keychain);
+    }
+    const id = parseIdentity(s.identity);
+    const session = s.mode === 'browser' ? await browser() : undefined;
+    const transport = s.mode === 'remote'
+        ? remoteSigner({
+            url: s.url,
+            credential: async () => 'env' in s.credential
+                ? (env[s.credential.env] ?? '')
+                : await keychain.read(s.credential.keychain),
+        })
+        : undefined;
+    const sign = async (operation, payload) => {
+        const q = signingRequest(operation, id.kind === 'evm' ? 'eip155:8453' : c.network, id.id, payload);
+        q.terms = terms();
+        const verify = (r) => verifySigningResult(q, r, c.nearRpc);
+        if (transport)
+            return transport(q, verify);
+        if (!session)
+            throw new Error('missing browser session');
+        return session.request(q, verify);
+    };
+    if (id.kind === 'evm')
+        return {
+            identity: id,
+            address: id.id,
+            authorize: async (message) => ({
+                kind: 'evm',
+                sig: (await sign('evm.personalSign', { message })).signature,
+            }),
+            signTypedData: async (data) => (await sign('evm.signTypedData', data)).signature,
+        };
+    if (id.kind !== 'near')
+        throw new Error('browser/remote Solana signing is not supported');
+    const signMessage = async (p) => (await sign('near.nep413', p));
+    const wallet = nearSelectorWallet({
+        getAccounts: async () => [{ accountId: id.id }],
+        signAndSendTransaction: async (tx) => {
+            const fc = tx.actions[0]?.params;
+            if (!fc)
+                throw new Error('missing action');
+            let payload = {
+                receiverId: tx.receiverId,
+                method: fc.methodName,
+                args: fc.args,
+                gas: fc.gas,
+                deposit: fc.deposit,
+            };
+            if (s.mode === 'remote') {
+                if (!s.publicKey)
+                    throw new Error('remote NEAR transactions require the public key in config');
+                // Transport exception near_api_remote_signer: Account builds the unsigned transaction.
+                // Its provider uses the third-party Node fetch transport for nonce and block lookup.
+                const unsigned = await new Account(id.id, c.nearRpc).createTransaction({
+                    receiverId: tx.receiverId,
+                    publicKey: PublicKey.fromString(s.publicKey),
+                    actions: [
+                        actions.functionCall(fc.methodName, fc.args, BigInt(fc.gas), BigInt(fc.deposit)),
+                    ],
+                });
+                payload = { ...payload, transaction: base64.encode(unsigned.encode()) };
+            }
+            const msg = fc.args.msg;
+            const purchase = fc.methodName === 'ft_transfer_call' && msg
+                ? purchaseId(parsePurchaseMessage(msg))
+                : undefined;
+            let knownHash;
+            try {
+                const result = await sign('near.signTransaction', payload);
+                let hash = result.txHash;
+                if (result.signedTransaction) {
+                    const { decodeSignedTransaction } = await import('near-api-js');
+                    hash = base58.encode(sha256(decodeSignedTransaction(base64.decode(result.signedTransaction)).transaction.encode()));
+                    knownHash = hash;
+                    const sent = await rpcReply(c.nearRpc, 'send_tx', {
+                        signed_tx_base64: result.signedTransaction,
+                        wait_until: 'FINAL',
+                    });
+                    if (sent.error)
+                        throw new TransactionUncertain(hash, purchase);
+                    await verifySigningResult(signingRequest('near.signTransaction', c.network, id.id, payload), { txHash: hash }, c.nearRpc);
+                }
+                if (!hash)
+                    throw new Error('missing transaction hash');
+                knownHash = hash;
+                const out = await txOutcome(c.nearRpc, hash, id.id, tx.receiverId, 'FINAL', {
+                    method: fc.methodName,
+                    args: fc.args,
+                });
+                if (out.state === 'released')
+                    return out.answer;
+                if (out.state === 'done')
+                    return out.value;
+                throw new TransactionUncertain(hash, purchase);
+            }
+            catch (error) {
+                if (error instanceof TransactionUncertain)
+                    throw new TransactionUncertain(error.txHash, purchase);
+                if (knownHash)
+                    throw new TransactionUncertain(knownHash, purchase);
+                throw error;
+            }
+        },
+    }, id.id, 
+    // Browser NEAR wallets return NEP-413 signatures in the page, so the payload has no callbackUrl.
+    (text, context) => proveNearControl(id.id, text, context, signMessage));
+    return {
+        ...wallet,
+        signUpload: (intent) => signNearUpload({ getAccounts: async () => [{ accountId: id.id }], signMessage }, intent, c.nearRpc),
+    };
+}

package/dist/node/signing.d.ts

@@ -0,0 +1,29 @@
+export type Operation = 'near.nep413' | 'near.signTransaction' | 'evm.personalSign' | 'evm.signTypedData';
+export interface SigningRequest {
+    version: 1;
+    id: string;
+    operation: Operation;
+    chain: string;
+    account: string;
+    expiresAt: number;
+    payload: unknown;
+    terms?: unknown;
+}
+export type SigningResult = {
+    signature?: string;
+    account?: string;
+    publicKey?: string;
+    accountId?: string;
+    signedTransaction?: string;
+    txHash?: string;
+};
+export declare const json: (v: unknown) => string;
+export declare function signingRequest(operation: Operation, chain: string, account: string, payload: unknown, ttl?: number): SigningRequest;
+/** Both transports use this verifier; no response is evidence merely because it was approved. */
+export declare function verifySigningResult(q: SigningRequest, r: SigningResult, nearRpc: string): Promise<void>;
+export declare function remoteSigner(o: {
+    url: string;
+    credential: () => Promise<string>;
+    fetch?: typeof fetch;
+    wait?: (ms: number) => Promise<void>;
+}): (q: SigningRequest, verify: (r: SigningResult) => Promise<void>) => Promise<SigningResult>;

package/dist/node/signing.js

@@ -0,0 +1,200 @@
+import { randomUUID } from 'node:crypto';
+import { ed25519 } from '@noble/curves/ed25519.js';
+import { sha256 } from '@noble/hashes/sha2.js';
+import { base58, base64 } from '@scure/base';
+import { decodeSignedTransaction } from 'near-api-js';
+import { verifyTypedData } from 'viem';
+import { isTransient } from '../errors.js';
+import { verifyNearMessage } from '../near/nep413.js';
+import { isFullAccessKey, readOutcome, rpcReply } from '../near/rpc.js';
+import { sleep } from '../net/retry.js';
+import { parseIdentity, verifyAuthorization } from '../settle-near/identity.js';
+import { TransactionUncertain } from '../wallet/uncertain.js';
+export const json = (v) => JSON.stringify(v, (_, x) => typeof x === 'bigint' ? String(x) : x instanceof Uint8Array ? [...x] : x);
+export function signingRequest(operation, chain, account, payload, ttl = 120000) {
+    return {
+        version: 1,
+        id: randomUUID(),
+        operation,
+        chain,
+        account,
+        expiresAt: Date.now() + ttl,
+        payload: JSON.parse(json(payload)),
+    };
+}
+/** Both transports use this verifier; no response is evidence merely because it was approved. */
+export async function verifySigningResult(q, r, nearRpc) {
+    if (Date.now() >= q.expiresAt)
+        throw new Error('signing request expired');
+    if (q.operation.startsWith('evm.')) {
+        const identity = parseIdentity({ kind: 'evm', id: q.account });
+        if (!/^eip155:[1-9][0-9]*$/.test(q.chain) || typeof r.signature !== 'string')
+            throw new Error('invalid EVM response');
+        if (q.operation === 'evm.personalSign') {
+            const p = q.payload;
+            if (typeof p.message !== 'string' ||
+                !verifyAuthorization(identity, p.message, { kind: 'evm', sig: r.signature }))
+                throw new Error('signature mismatch');
+        }
+        else {
+            const p = q.payload;
+            if (`eip155:${p.domain?.chainId}` !== q.chain ||
+                !(await verifyTypedData({ ...p, address: identity.id, signature: r.signature })))
+                throw new Error('typed data signature or chain mismatch');
+        }
+        return;
+    }
+    if (!['near:mainnet', 'near:testnet', 'near:sandbox'].includes(q.chain))
+        throw new Error('invalid NEAR chain');
+    if (q.operation === 'near.nep413') {
+        const p = q.payload;
+        await verifyNearMessage(q.account, { ...p, nonce: Uint8Array.from(p.nonce) }, r, nearRpc);
+        return;
+    }
+    const p = q.payload;
+    if (r.signedTransaction) {
+        if (!p.transaction)
+            throw new Error('missing exact unsigned transaction');
+        const signed = decodeSignedTransaction(base64.decode(r.signedTransaction));
+        const tx = signed.transaction;
+        const publicKey = tx.publicKey.toString();
+        const fc = tx.actions[0]?.functionCall;
+        const sameArgs = (a, b) => {
+            const stable = (v) => v && typeof v === 'object'
+                ? Array.isArray(v)
+                    ? `[${v.map(stable)}]`
+                    : `{${Object.keys(v)
+                        .sort()
+                        .map((k) => `${JSON.stringify(k)}:${stable(v[k])}`)
+                        .join(',')}}`
+                : JSON.stringify(v);
+            return stable(a) === stable(b);
+        };
+        if (tx.receiverId !== p.receiverId ||
+            tx.actions.length !== 1 ||
+            !fc ||
+            fc.methodName !== p.method ||
+            String(fc.gas) !== p.gas ||
+            String(fc.deposit) !== p.deposit ||
+            !sameArgs(JSON.parse(new TextDecoder().decode(Uint8Array.from(fc.args))), p.args))
+            throw new Error('unsigned transaction action mismatch');
+        if (base64.encode(tx.encode()) !== p.transaction ||
+            tx.signerId !== q.account ||
+            !publicKey.startsWith('ed25519:') ||
+            !ed25519.verify(Uint8Array.from(signed.signature.ed25519Signature?.data ?? []), sha256(tx.encode()), base58.decode(publicKey.slice(8)), { zip215: false }) ||
+            !(await isFullAccessKey(nearRpc, q.account, publicKey)))
+            throw new Error('signed transaction mismatch');
+        return;
+    }
+    if (!r.txHash)
+        throw new Error('missing transaction evidence');
+    let reply;
+    try {
+        // Verify one independently fetched result, avoiding a second inconsistent RPC snapshot.
+        reply = await rpcReply(nearRpc, 'tx', {
+            tx_hash: r.txHash,
+            sender_account_id: q.account,
+            wait_until: 'FINAL',
+        });
+    }
+    catch (error) {
+        if (isTransient(error))
+            throw new TransactionUncertain(r.txHash);
+        throw error;
+    }
+    const t = reply.result;
+    if (reply.error) {
+        if (['UNKNOWN_TRANSACTION', 'TIMEOUT_ERROR', 'INTERNAL_ERROR'].includes(reply.error.cause?.name ?? reply.error.name ?? ''))
+            throw new TransactionUncertain(r.txHash);
+        throw new Error('transaction RPC rejected the evidence');
+    }
+    if (t?.final_execution_status !== 'FINAL')
+        throw new TransactionUncertain(r.txHash);
+    const fc = t.transaction?.actions?.[0]?.FunctionCall;
+    if (String(fc?.gas) !== p.gas || fc?.deposit !== p.deposit)
+        throw new Error('transaction gas/deposit mismatch');
+    // Semantic rejections must never become nearSubmission evidence. readOutcome also checks
+    // hash, signer, receiver, method, args and execution status on this same finalized response.
+    const result = readOutcome(t, p.receiverId, {
+        txHash: r.txHash,
+        signer: q.account,
+        method: p.method,
+        args: p.args,
+    });
+    if (result.state === 'pending')
+        throw new TransactionUncertain(r.txHash);
+    if (!['done', 'released'].includes(result.state))
+        throw new Error('transaction did not succeed');
+}
+export function remoteSigner(o) {
+    const u = new URL(o.url);
+    if (u.protocol !== 'https:' ||
+        u.username ||
+        u.password ||
+        u.search ||
+        u.hash ||
+        (u.pathname !== '/' && u.pathname !== ''))
+        throw new TypeError('signer must be an HTTPS origin without credentials');
+    const fetcher = o.fetch ?? fetch;
+    return async (q, verify) => {
+        const credential = await o.credential();
+        if (!credential || /[\r\n]/.test(credential))
+            throw new Error('signer credential required');
+        const call = async (path, body) => {
+            if (Date.now() >= q.expiresAt)
+                throw new Error('signing request expired');
+            const res = await fetcher(new URL(path, u).href, {
+                method: body === undefined ? 'GET' : 'POST',
+                headers: { authorization: `Bearer ${credential}`, 'content-type': 'application/json' },
+                redirect: 'error',
+                credentials: 'omit',
+                cache: 'no-store',
+                signal: AbortSignal.timeout(Math.max(1, Math.min(20000, q.expiresAt - Date.now()))),
+                ...(body === undefined ? {} : { body: json(body) }),
+            });
+            if (!res.ok)
+                throw new Error('signer unavailable');
+            return res.json();
+        };
+        const c = await call('/v1/capabilities');
+        if (c.version !== 1 ||
+            c.account !== q.account ||
+            c.chain !== q.chain ||
+            !Array.isArray(c.operations) ||
+            !c.operations.includes(q.operation))
+            throw new Error('signer capability mismatch');
+        let r;
+        // Only transport failures retry creation. Every attempt uses the same immutable request/id.
+        const exact = JSON.parse(json(q));
+        for (let attempt = 0;; attempt++) {
+            try {
+                r = await call('/v1/requests', exact);
+                break;
+            }
+            catch (error) {
+                if (!(error instanceof TypeError ||
+                    (error instanceof Error && ['TimeoutError', 'AbortError'].includes(error.name))) ||
+                    attempt >= 2 ||
+                    Date.now() >= q.expiresAt)
+                    throw error;
+                await (o.wait ?? sleep)(1000);
+            }
+        }
+        for (;;) {
+            if (r.version !== 1 || r.id !== q.id)
+                throw new Error('signer response mismatch');
+            if (r.status === 'rejected')
+                throw new Error('signer rejected request');
+            if (r.status === 'approved') {
+                if (!r.result)
+                    throw new Error('missing signer result');
+                await verify(r.result);
+                return r.result;
+            }
+            if (r.status !== 'pending')
+                throw new Error('invalid signer status');
+            await (o.wait ?? sleep)(1000);
+            r = await call(`/v1/requests/${encodeURIComponent(q.id)}`);
+        }
+    };
+}

package/dist/node/storage-commands.d.ts

@@ -0,0 +1,11 @@
+import type { CommandSession, RequestContext } from './command-context.js';
+/** `budget`: the file's available purchase storage and what one more purchase needs. */
+declare function fileBudget(ctx: RequestContext): Promise<Record<string, unknown>>;
+/**
+ * `fund`, first step: a NEAR owner funds the file directly. Returns nothing for other wallets,
+ * which fund through the SDK once it is ready; the loaded wallet stays selected for that step.
+ */
+declare function fundWithNearWallet(ctx: RequestContext): Promise<Record<string, unknown> | undefined>;
+/** `fund` through the SDK, for owners that are not NEAR wallets. */
+declare function fund(ctx: CommandSession): Promise<Record<string, unknown>>;
+export { fileBudget, fund, fundWithNearWallet };

package/dist/node/storage-commands.js

@@ -0,0 +1,50 @@
+/** File purchase storage: `budget` reads what a file has left, `fund` adds to it. */
+import { fileStorageBalance } from '../near/rpc.js';
+import { fundFileStorage } from '../wallet/wallet.js';
+import { fail, isId } from './adapter-checks.js';
+import { nearAmount } from './amounts.js';
+import { usage } from './errors.js';
+import { loadWallet } from './wallets.js';
+/** `budget`: the file's available purchase storage and what one more purchase needs. */
+async function fileBudget(ctx) {
+    const { c, o } = ctx;
+    if (!o.target || !isId(o.target))
+        throw usage();
+    const budget = await fileStorageBalance(c.nearRpc, c.contractId, o.target);
+    return {
+        fileId: o.target,
+        available: budget.available.toString(),
+        admissionRequirement: budget.admissionRequirement.toString(),
+    };
+}
+/**
+ * `fund`, first step: a NEAR owner funds the file directly. Returns nothing for other wallets,
+ * which fund through the SDK once it is ready; the loaded wallet stays selected for that step.
+ */
+async function fundWithNearWallet(ctx) {
+    const { c, d, env, o } = ctx;
+    if (d.agent)
+        return fail('human_only', 'File funding requires a human CLI session.', 2);
+    if (!o.target || !isId(o.target))
+        throw usage();
+    const text = o.fundAmount;
+    if (!text)
+        return fail('invalid_arguments', 'Provide the NEAR amount to allocate.', 2);
+    const owner = await (d.wallet ?? loadWallet)({ ...o, network: c.network }, env, c.nearRpc);
+    ctx.selected = owner;
+    if (owner.identity.kind === 'near') {
+        if (!('call' in owner))
+            return fail('near_wallet_required', 'File funding requires a NEAR wallet.', 2);
+        await fundFileStorage(owner, c.contractId, o.target, nearAmount(text));
+        return { fileId: o.target, fundedNear: text };
+    }
+}
+/** `fund` through the SDK, for owners that are not NEAR wallets. */
+async function fund(ctx) {
+    const { o, sdk, wallet } = ctx;
+    if (!o.target || !o.fundAmount)
+        throw usage();
+    await sdk.fund(o.target, nearAmount(o.fundAmount), await wallet());
+    return { fileId: o.target, fundedNear: o.fundAmount };
+}
+export { fileBudget, fund, fundWithNearWallet };

package/dist/node/sync-dir.d.ts

@@ -0,0 +1 @@
+export declare function syncDir(dir: string): Promise<void>;

package/dist/node/sync-dir.js

@@ -0,0 +1,11 @@
+/** Sync a directory after an atomic filesystem update. */
+import { open } from 'node:fs/promises';
+export async function syncDir(dir) {
+    const d = await open(dir, 'r');
+    try {
+        await d.sync();
+    }
+    finally {
+        await d.close();
+    }
+}

package/dist/node/wallets.d.ts

@@ -0,0 +1,13 @@
+import type { UploadAuth, UploadIntent } from '../download/upload.js';
+import type { SplitCall } from '../pay/split.js';
+import { type IdentityWallet } from '../wallet/wallet.js';
+import type { Input } from './cli.js';
+import { type Keychain } from './keychain.js';
+export type Environment = Record<string, string | undefined>;
+export type LocalWallet = IdentityWallet & {
+    signUpload?: (intent: UploadIntent) => Promise<UploadAuth>;
+    sendBase?: (call: SplitCall, rpc: string) => Promise<void>;
+};
+export declare function identity(value: string): import("../settle-near/identity.js").Identity;
+export declare function readBackupSecret(o: Partial<Input>, env: Environment): Promise<Uint8Array>;
+export declare function loadWallet(o: Partial<Input>, env: Environment, nearRpc: string, keychain?: Keychain): Promise<LocalWallet>;