@1sat/cli 0.0.108 → 0.0.110

package/README.md

@@ -331,3 +331,20 @@ The CLI is pure Bun with no framework. Arg parsing is manual (`src/args.ts`). Bu
 ## License
 
 MIT
+
+### Authenticated HTTP requests
+
+`1sat authfetch <method> <url> [--body <json|@file>] [--header 'K: V']`
+uses the SDK's BRC-104 AuthFetch with CLI wallet keys. If the SDK reports
+missing response authentication headers, only GET and HEAD may retry using
+plain fetch for public reads. Other methods fail with an unknown-outcome
+warning: verify activity before retrying, since the server may already have
+executed the request.
+
+A 402 response requires interactive payment confirmation or explicit `--yes`.
+Without `--yes` and a terminal on both stdin and stdout, the command returns
+`approval_required` with exit status 1 and makes no payment retry. Use `--json`
+for structured output; `satoshis` is included only when the public payment
+header is a nonnegative safe integer of at most 16 decimal digits. Review the
+payment before rerunning with `--yes`; this authorizes the existing SDK payment
+flow. It does not impose a spending cap. `--quiet` suppresses output as usual.

package/dist/cli.js

@@ -1378,7 +1378,7 @@ var init_help = __esm(() => {
     {
       group: "Advanced",
       name: "authfetch",
-      description: "HTTP request with BRC-104 AuthFetch using CLI wallet keys. On 402, confirms payment unless --yes.",
+      description: "HTTP request with BRC-104 AuthFetch using CLI wallet keys. Only GET/HEAD retry public routes without auth. On 402, requires --yes or interactive confirmation; noninteractive calls return approval_required and exit nonzero.",
       positional: "<method> <url>",
       args: [
         {
@@ -1423,9 +1423,114 @@ var init_help = __esm(() => {
   ];
 });
 
+// src/commands/authfetch-request.ts
+import { AuthFetch } from "@bsv/sdk";
+function createApprovalAuth(wallet) {
+  let approved = false;
+  let submitted = false;
+  let currentRequest;
+  const guarded = new Proxy(wallet, {
+    get(target, property) {
+      if (property === "createAction")
+        return async (...args) => {
+          const satoshis = args[0].outputs?.reduce((sum, output2) => sum + output2.satoshis, 0) ?? 0;
+          if (!Number.isSafeInteger(satoshis) || satoshis <= 0)
+            throw new Error("Invalid HTTP payment amount");
+          if (approved === false)
+            throw new PaymentRequired(satoshis);
+          if (typeof approved === "number" && satoshis !== approved)
+            throw new Error("Payment amount changed; review the new quote before retrying");
+          if (submitted)
+            throw new Error("Payment already submitted; reconcile wallet activity before retrying");
+          submitted = true;
+          const result = await target.createAction(...args);
+          if (currentRequest?.retryCounter === 0)
+            currentRequest.retryCounter = 1;
+          return result;
+        };
+      if (property === "signAction")
+        return async () => {
+          throw new Error("Unexpected HTTP payment signing request");
+        };
+      const value = Reflect.get(target, property, target);
+      return typeof value === "function" ? value.bind(target) : value;
+    }
+  });
+  return {
+    auth: new AuthFetch(guarded),
+    prepareRequest: (config) => {
+      currentRequest = config;
+    },
+    authorizePayment: (satoshis) => {
+      approved = satoshis ?? true;
+    }
+  };
+}
+async function requestWithApproval(url, init, options, dependencies) {
+  const send = () => {
+    const config = {
+      ...init,
+      paymentRetryAttempts: 1,
+      ...init.method === "GET" || init.method === "HEAD" ? {} : { retryCounter: 1 }
+    };
+    dependencies.prepareRequest?.(config);
+    return dependencies.auth.fetch(url, config);
+  };
+  let res;
+  try {
+    res = await send();
+  } catch (error) {
+    if (error instanceof PaymentRequired) {
+      res = new Response(null, {
+        status: 402,
+        headers: { "x-bsv-payment-satoshis-required": String(error.satoshis) }
+      });
+    } else {
+      const missingAuthentication = error instanceof Error && /^Received HTTP \d{3}(?: [^\n]*)? from /.test(error.message) && (error.message.includes(` from ${url} without valid BSV authentication (missing headers: `) || error.message.includes(` from ${url} without valid BSV authentication (response lacked required BSV auth headers)`));
+      if (!missingAuthentication)
+        throw error;
+      if (init.method !== "GET" && init.method !== "HEAD") {
+        throw new Error("Authentication could not be verified. The request outcome may be unknown; verify activity before retrying.", { cause: error });
+      }
+      res = await dependencies.plainFetch(url, init);
+    }
+  }
+  if (res.status !== 402)
+    return res;
+  const amount = res.headers.get("x-bsv-payment-satoshis-required");
+  const value = amount !== null && /^\d{1,16}$/.test(amount) ? Number(amount) : Number.NaN;
+  const satoshis = Number.isSafeInteger(value) ? value : undefined;
+  const message = satoshis !== undefined ? `Pay ${satoshis} sats for ${init.method} ${url}?` : `Server requires payment (402) for ${init.method} ${url}. Continue?`;
+  if (!options.yes) {
+    if (!options.interactive) {
+      return {
+        error: "approval_required",
+        status: 402,
+        ok: false,
+        message: "Payment requires approval. Review the payment and rerun with --yes to authorize it, or run in an interactive terminal.",
+        ...satoshis !== undefined ? { satoshis } : {}
+      };
+    }
+    if (!await dependencies.confirmPayment(message)) {
+      throw new Error("Payment cancelled.");
+    }
+  }
+  dependencies.authorizePayment?.(satoshis);
+  return send();
+}
+var PaymentRequired;
+var init_authfetch_request = __esm(() => {
+  PaymentRequired = class PaymentRequired extends Error {
+    satoshis;
+    constructor(satoshis) {
+      super("Payment requires approval");
+      this.satoshis = satoshis;
+    }
+  };
+});
+
 // src/commands/authfetch.ts
 import { readFileSync as readFileSync5 } from "node:fs";
-import { AuthFetch } from "@bsv/sdk";
 import { confirm, isCancel as isCancel2 } from "@clack/prompts";
 async function handleAuthfetchCommand(args, opts) {
   if (!args[0] || args[0] === "help" || args.includes("--help") || args.includes("-h")) {
@@ -1494,36 +1599,29 @@ Unknown or missing method: ${method ?? ""}`);
     chain: opts.chain
   });
   try {
-    const auth = new AuthFetch(walletResult.wallet);
+    const { auth, authorizePayment, prepareRequest } = createApprovalAuth(walletResult.wallet);
     const init = {
       method,
       headers,
       ...body !== undefined ? { body } : {}
     };
-    let res;
-    try {
-      res = await auth.fetch(url, {
-        ...init,
-        paymentRetryAttempts: 0
-      });
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      if (/without valid BSV authentication/i.test(msg)) {
-        res = await fetch(url, init);
-      } else {
-        throw err;
-      }
-    }
-    if (res.status === 402) {
-      const satsHeader = res.headers.get("x-bsv-payment-satoshis-required");
-      const sats = satsHeader ? Number(satsHeader) : undefined;
-      const payMsg = sats != null && Number.isFinite(sats) ? `Pay ${sats} sats for ${method} ${url}?` : `Server requires payment (402) for ${method} ${url}. Continue?`;
-      if (!opts.yes) {
-        const ok = await confirm({ message: payMsg });
-        if (isCancel2(ok) || !ok)
-          fatal("Payment cancelled.");
+    const res = await requestWithApproval(url, init, {
+      yes: opts.yes,
+      interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY)
+    }, {
+      auth,
+      authorizePayment,
+      prepareRequest,
+      plainFetch: fetch,
+      confirmPayment: async (message) => {
+        const ok = await confirm({ message });
+        return !isCancel2(ok) && ok === true;
       }
-      res = await auth.fetch(url, init);
+    });
+    if ("error" in res) {
+      output(res, opts);
+      process.exitCode = 1;
+      return;
     }
     const text = await res.text();
     let parsed = text;
@@ -1562,6 +1660,7 @@ var init_authfetch = __esm(() => {
   init_help();
   init_keys();
   init_output();
+  init_authfetch_request();
   METHODS = new Set([
     "GET",
     "POST",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1sat/cli",
-  "version": "0.0.108",
+  "version": "0.0.110",
   "description": "CLI for 1Sat Ordinals SDK",
   "type": "module",
   "main": "./dist/cli.js",

package/src/commands/authfetch-request.ts

@@ -0,0 +1,152 @@
+import { AuthFetch, type WalletInterface } from '@bsv/sdk'
+
+class PaymentRequired extends Error {
+	constructor(readonly satoshis: number) {
+		super('Payment requires approval')
+	}
+}
+
+/** Enforce approval at the wallet boundary; SDK retry=0 does not disable payment. */
+export function createApprovalAuth(wallet: WalletInterface) {
+	let approved: false | number | true = false
+	let submitted = false
+	let currentRequest: { retryCounter?: number } | undefined
+	const guarded = new Proxy(wallet, {
+		get(target, property) {
+			if (property === 'createAction')
+				return async (...args: Parameters<WalletInterface['createAction']>) => {
+					const satoshis =
+						args[0].outputs?.reduce(
+							(sum, output) => sum + output.satoshis,
+							0,
+						) ?? 0
+					if (!Number.isSafeInteger(satoshis) || satoshis <= 0)
+						throw new Error('Invalid HTTP payment amount')
+					if (approved === false) throw new PaymentRequired(satoshis)
+					if (typeof approved === 'number' && satoshis !== approved)
+						throw new Error(
+							'Payment amount changed; review the new quote before retrying',
+						)
+					if (submitted)
+						throw new Error(
+							'Payment already submitted; reconcile wallet activity before retrying',
+						)
+					submitted = true
+					const result = await target.createAction(...args)
+					// A verified 402 reached the approved wallet boundary. Permit its
+					// one paid send, but not stale-session replay of that send.
+					if (currentRequest?.retryCounter === 0)
+						currentRequest.retryCounter = 1
+					return result
+				}
+			if (property === 'signAction')
+				return async () => {
+					throw new Error('Unexpected HTTP payment signing request')
+				}
+			const value = Reflect.get(target, property, target)
+			return typeof value === 'function' ? value.bind(target) : value
+		},
+	})
+	return {
+		auth: new AuthFetch(guarded),
+		prepareRequest: (config: { retryCounter?: number }) => {
+			currentRequest = config
+		},
+		authorizePayment: (satoshis?: number) => {
+			approved = satoshis ?? true
+		},
+	}
+}
+
+export interface PaymentApprovalRequired {
+	error: 'approval_required'
+	status: 402
+	ok: false
+	message: string
+	satoshis?: number
+}
+
+/** Keep request replay and payment decisions separate from wallet setup/output. */
+export async function requestWithApproval(
+	url: string,
+	init: RequestInit & { method: string },
+	options: { yes?: boolean; interactive: boolean },
+	dependencies: {
+		auth: Pick<AuthFetch, 'fetch'>
+		plainFetch: typeof fetch
+		confirmPayment: (message: string) => Promise<boolean>
+		authorizePayment?: (satoshis?: number) => void
+		prepareRequest?: (config: { retryCounter?: number }) => void
+	},
+): Promise<Response | PaymentApprovalRequired> {
+	const send = () => {
+		const config = {
+			...init,
+			paymentRetryAttempts: 1,
+			...(init.method === 'GET' || init.method === 'HEAD'
+				? {}
+				: { retryCounter: 1 }),
+		}
+		dependencies.prepareRequest?.(config)
+		return dependencies.auth.fetch(url, config)
+	}
+	let res: Response
+	try {
+		res = await send()
+	} catch (error) {
+		if (error instanceof PaymentRequired) {
+			res = new Response(null, {
+				status: 402,
+				headers: { 'x-bsv-payment-satoshis-required': String(error.satoshis) },
+			})
+		} else {
+			// Match only the SDK's known unauthenticated-response error, not
+			// transport, signature verification, or other authentication failures.
+			const missingAuthentication =
+				error instanceof Error &&
+				/^Received HTTP \d{3}(?: [^\n]*)? from /.test(error.message) &&
+				(error.message.includes(
+					` from ${url} without valid BSV authentication (missing headers: `,
+				) ||
+					error.message.includes(
+						` from ${url} without valid BSV authentication (response lacked required BSV auth headers)`,
+					))
+			if (!missingAuthentication) throw error
+			if (init.method !== 'GET' && init.method !== 'HEAD') {
+				throw new Error(
+					'Authentication could not be verified. The request outcome may be unknown; verify activity before retrying.',
+					{ cause: error },
+				)
+			}
+			res = await dependencies.plainFetch(url, init)
+		}
+	}
+
+	if (res.status !== 402) return res
+
+	const amount = res.headers.get('x-bsv-payment-satoshis-required')
+	const value =
+		amount !== null && /^\d{1,16}$/.test(amount) ? Number(amount) : Number.NaN
+	const satoshis = Number.isSafeInteger(value) ? value : undefined
+	const message =
+		satoshis !== undefined
+			? `Pay ${satoshis} sats for ${init.method} ${url}?`
+			: `Server requires payment (402) for ${init.method} ${url}. Continue?`
+	if (!options.yes) {
+		if (!options.interactive) {
+			return {
+				error: 'approval_required',
+				status: 402,
+				ok: false,
+				message:
+					'Payment requires approval. Review the payment and rerun with --yes to authorize it, or run in an interactive terminal.',
+				...(satoshis !== undefined ? { satoshis } : {}),
+			}
+		}
+		if (!(await dependencies.confirmPayment(message))) {
+			throw new Error('Payment cancelled.')
+		}
+	}
+	dependencies.authorizePayment?.(satoshis)
+	return send()
+}

package/src/commands/authfetch.ts

@@ -3,18 +3,18 @@
  *
  *   1sat authfetch <method> <url> [--body <json|@file>] [--header 'K: V']...
  *
- * Always authenticates. On 402 Payment Required, prompts unless --yes, then
- * AuthFetch pays and retries.
+ * Authenticates first; only GET/HEAD may retry public routes without auth.
+ * Payment requires --yes or interactive confirmation.
  */
 
 import { readFileSync } from 'node:fs'
-import { AuthFetch } from '@bsv/sdk'
 import { confirm, isCancel } from '@clack/prompts'
 import type { GlobalFlags } from '../args.js'
 import { loadContext } from '../context.js'
 import { printCommandHelp } from '../help.js'
 import { loadKey } from '../keys.js'
 import { fatal, output } from '../output.js'
+import { createApprovalAuth, requestWithApproval } from './authfetch-request.js'
 
 const METHODS = new Set([
 	'GET',
@@ -107,44 +107,37 @@ export async function handleAuthfetchCommand(
 	})
 
 	try {
-		const auth = new AuthFetch(walletResult.wallet)
+		const { auth, authorizePayment, prepareRequest } = createApprovalAuth(
+			walletResult.wallet,
+		)
 		const init = {
 			method,
 			headers,
 			...(body !== undefined ? { body } : {}),
 		}
 
-		let res: Response
-		try {
-			// Authenticate but do not auto-pay on first try (so we can confirm).
-			res = await auth.fetch(url, {
-				...init,
-				paymentRetryAttempts: 0,
-			})
-		} catch (err) {
-			// Public routes may return 200 without BSV auth headers; AuthFetch rejects those.
-			const msg = err instanceof Error ? err.message : String(err)
-			if (/without valid BSV authentication/i.test(msg)) {
-				res = await fetch(url, init)
-			} else {
-				throw err
-			}
-		}
-
-		if (res.status === 402) {
-			const satsHeader = res.headers.get('x-bsv-payment-satoshis-required')
-			const sats = satsHeader ? Number(satsHeader) : undefined
-			const payMsg =
-				sats != null && Number.isFinite(sats)
-					? `Pay ${sats} sats for ${method} ${url}?`
-					: `Server requires payment (402) for ${method} ${url}. Continue?`
-
-			if (!opts.yes) {
-				const ok = await confirm({ message: payMsg })
-				if (isCancel(ok) || !ok) fatal('Payment cancelled.')
-			}
-
-			res = await auth.fetch(url, init)
+		const res = await requestWithApproval(
+			url,
+			init,
+			{
+				yes: opts.yes,
+				interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+			},
+			{
+				auth,
+				authorizePayment,
+				prepareRequest,
+				plainFetch: fetch,
+				confirmPayment: async (message) => {
+					const ok = await confirm({ message })
+					return !isCancel(ok) && ok === true
+				},
+			},
+		)
+		if ('error' in res) {
+			output(res, opts)
+			process.exitCode = 1
+			return
 		}
 
 		const text = await res.text()

package/src/help.ts

@@ -763,7 +763,7 @@ export const COMMANDS: CommandSpec[] = [
 		group: 'Advanced',
 		name: 'authfetch',
 		description:
-			'HTTP request with BRC-104 AuthFetch using CLI wallet keys. On 402, confirms payment unless --yes.',
+			'HTTP request with BRC-104 AuthFetch using CLI wallet keys. Only GET/HEAD retry public routes without auth. On 402, requires --yes or interactive confirmation; noninteractive calls return approval_required and exit nonzero.',
 		positional: '<method> <url>',
 		args: [
 			{