@1sat/cli 0.0.120 → 0.0.121

package/src/wallet-api/admin.ts

@@ -0,0 +1,107 @@
+/**
+ * The CLI acting as the wallet itself.
+ *
+ * `LocalWalletPermissionsManager` lets its admin originator bypass every
+ * permission check, so `CLI_ADMIN_ORIGINATOR` must only ever be used by
+ * in-process code. The wallet-api router rejects any HTTP request whose
+ * origin normalizes to it, so an app cannot claim it. It is a
+ * hostname-shaped string that is stable under the manager's originator
+ * normalization (lowercase, no scheme, no port).
+ *
+ * The CLI's own commands go through a manager too, rather than the raw
+ * toolbox wallet. That is what keeps their output readable now that
+ * transaction metadata is encrypted at rest: the manager decrypts
+ * descriptions and custom instructions on the way back
+ * (`decryptListActionsMetadata` / `maybeDecryptMetadata`, which return
+ * values that were never encrypted unchanged), while the admin originator
+ * skips every grant check.
+ */
+
+import { PERMISSION_SCHEME_IDS } from '@1sat/types'
+import {
+	type IPermissionStore,
+	LocalWalletPermissionsManager,
+} from '@1sat/wallet'
+import type { WalletInterface } from '@bsv/sdk'
+
+export const CLI_ADMIN_ORIGINATOR = '1sat-cli.internal'
+
+/**
+ * Pass-through permission modules for every scheme the actions package can
+ * label with.
+ *
+ * `buildInputAssetLabel` puts `p <scheme> input id <id>` on any action that
+ * spends a basket asset, unconditionally — there is no opt-out on the action.
+ * The manager routes a `p ` label to `config.permissionModules[scheme]` and
+ * throws `Unsupported P-module scheme` when none is registered, so the CLI's
+ * own commands would fail on a label they have always emitted.
+ *
+ * A real module exists to describe an intent and apply it once a person
+ * approves. The admin originator bypasses every check and has no prompt
+ * surface, so there is nothing for it to do: passing the request and response
+ * through unchanged is what the raw toolbox wallet did before the CLI gained
+ * a manager.
+ */
+const adminPermissionModules = Object.fromEntries(
+	PERMISSION_SCHEME_IDS.map((scheme) => [
+		scheme,
+		{
+			onRequest: async (req: { args: object }) => ({ args: req.args }),
+			onResponse: async (res: unknown) => res,
+		},
+	]),
+)
+
+/**
+ * Wrap the toolbox wallet in a permissions manager the CLI calls as the
+ * admin originator.
+ *
+ * Every method is invoked with `CLI_ADMIN_ORIGINATOR` as the originator —
+ * the manager requires one for its checks and would otherwise throw
+ * "Originator is required for permission checks" on calls the CLI's own
+ * actions make without one.
+ *
+ * Metadata encryption is left at the toolbox default (on), the same as
+ * the served endpoint: the CLI writes encrypted descriptions and custom
+ * instructions and reads them back decrypted. Nothing downstream loses by
+ * that. `1sat serve wallet` is the wallet-toolbox *storage* interface, not
+ * a BRC-100 API — it moves opaque records and never interprets a
+ * description — and the wallet at the far end (wallet-desktop, the
+ * browser wallet, a remote CLI) runs its own permissions manager, which
+ * decrypts. Records written before this change stay readable: decryption
+ * is attempted unconditionally and `maybeDecryptMetadata` returns the
+ * original string when it fails.
+ */
+export function adminWallet(
+	wallet: WalletInterface,
+	store: IPermissionStore,
+): WalletInterface {
+	const manager = new LocalWalletPermissionsManager(
+		wallet,
+		CLI_ADMIN_ORIGINATOR,
+		{ permissionModules: adminPermissionModules },
+		{ store },
+	)
+	return withAdminOriginator(manager)
+}
+
+/**
+ * A `WalletInterface` view of `manager` that passes the admin originator on
+ * every call. BRC-100 methods all take `(args, originator?)`, so one proxy
+ * covers the surface without a per-method wrapper that would go stale as
+ * the interface grows.
+ */
+export function withAdminOriginator(manager: WalletInterface): WalletInterface {
+	return new Proxy(manager, {
+		get(target, property, receiver) {
+			const value = Reflect.get(target, property, receiver)
+			if (typeof value !== 'function') return value
+			return (args: unknown) =>
+				(value as (a: unknown, o: string) => unknown).call(
+					target,
+					args,
+					CLI_ADMIN_ORIGINATOR,
+				)
+		},
+	})
+}

package/src/wallet-api/deny.ts

@@ -0,0 +1,194 @@
+/**
+ * The wallet-api's answer to a permission it has not been granted.
+ *
+ * `1sat serve wallet-api` exists for agents and automation; a person who
+ * wants to be asked runs a graphical wallet. So there is no prompt and no
+ * auto-approve: anything the permission store does not already hold is
+ * denied on the spot. The agent driving the app never sees this process's
+ * terminal — it sees the app's error output — so the denial itself has to
+ * carry the fix, which is the exact `1sat permissions grant …` command for
+ * the permission that was refused.
+ *
+ * `WalletPermissionsManager.denyPermission` rejects the app's call with a
+ * fixed `Permission denied.`, so the command is recorded as the request is
+ * denied and swapped in at the HTTP boundary by `withDenialMessage`. The
+ * recording is scoped to the in-flight call with `AsyncLocalStorage`: the
+ * manager fires the permission event inside the same awaited chain as the
+ * call that needs it, so the handler and the boundary share a context even
+ * when several apps are being served at once.
+ */
+
+import { AsyncLocalStorage } from 'node:async_hooks'
+import {
+	type PermissionKey,
+	normalizeOriginator,
+	permissionKeyFromRequest,
+	permissionKeysFromGroup,
+} from '@1sat/wallet'
+import type {
+	CounterpartyPermissionEventHandler,
+	GroupedPermissionEventHandler,
+	GroupedPermissionRequest,
+	PermissionEventHandler,
+	PermissionRequest,
+	WalletPermissionsManagerCallbacks,
+} from '@bsv/wallet-toolbox'
+import { GRANT_COMMAND, type GrantSpec, grantCommand } from './grants.js'
+
+/** The subset of `WalletPermissionsManager` the denial handlers drive. */
+export interface PermissionDenyTarget {
+	bindCallback(
+		eventName: keyof WalletPermissionsManagerCallbacks,
+		handler:
+			| PermissionEventHandler
+			| GroupedPermissionEventHandler
+			| CounterpartyPermissionEventHandler,
+	): number
+	denyPermission(requestID: string): Promise<void>
+	denyGroupedPermission(requestID: string): Promise<void>
+}
+
+export interface DenyOptions {
+	/**
+	 * Command the message tells the caller to run, minus the origin and
+	 * selectors — carries global flags where they matter, e.g.
+	 * `1sat --chain test permissions grant`.
+	 */
+	grantCommandPrefix?: string
+	/** Request log sink. Defaults to `console.log`. */
+	log?: (line: string) => void
+}
+
+/** Messages recorded while one app-facing call is in flight. */
+const inFlight = new AsyncLocalStorage<string[]>()
+
+/** The manager's own code for a refusal, on the error it rejects with. */
+const DENIED_CODE = 'ERR_PERMISSION_DENIED'
+
+/**
+ * Bind every permission event to an immediate denial.
+ *
+ * Same set the removed terminal prompts bound: protocol, basket,
+ * certificate, spending authorization and the BRC-73 grouped request.
+ */
+export function bindPermissionDenials(
+	manager: PermissionDenyTarget,
+	options: DenyOptions = {},
+): void {
+	const prefix = options.grantCommandPrefix ?? GRANT_COMMAND
+	const log = options.log ?? ((line: string) => console.log(line))
+
+	const record = (origin: string, commands: string[]): void => {
+		const message = denialMessage(origin, commands)
+		inFlight.getStore()?.push(message)
+		log(`[wallet-api] ${message}`)
+	}
+
+	const single: PermissionEventHandler = async (request) => {
+		const origin = displayOrigin(request)
+		try {
+			record(origin, [grantCommand(specFromRequest(request), prefix)])
+		} catch (err) {
+			// An unreadable request still has to be denied; the app gets the
+			// manager's plain message rather than a hung call.
+			log(`[wallet-api] could not describe request: ${(err as Error).message}`)
+		}
+		await safely(log, 'deny', () => manager.denyPermission(request.requestID))
+	}
+
+	const grouped: GroupedPermissionEventHandler = async (request) => {
+		const origin = normalizeOriginator(request.originator)
+		try {
+			record(
+				origin,
+				specsFromGroupedRequest(request).map((spec) =>
+					grantCommand(spec, prefix),
+				),
+			)
+		} catch (err) {
+			log(`[wallet-api] could not describe request: ${(err as Error).message}`)
+		}
+		await safely(log, 'deny', () =>
+			manager.denyGroupedPermission(request.requestID),
+		)
+	}
+
+	manager.bindCallback('onProtocolPermissionRequested', single)
+	manager.bindCallback('onBasketAccessRequested', single)
+	manager.bindCallback('onCertificateAccessRequested', single)
+	manager.bindCallback('onSpendingAuthorizationRequested', single)
+	manager.bindCallback('onGroupedPermissionRequested', grouped)
+}
+
+/**
+ * Run one app-facing wallet call, replacing the manager's bare
+ * `Permission denied.` with the command that would allow it.
+ *
+ * Errors that are not denials pass through untouched, as does a denial the
+ * handlers could not describe.
+ */
+export async function withDenialMessage<T>(fn: () => Promise<T>): Promise<T> {
+	const messages: string[] = []
+	try {
+		return await inFlight.run(messages, fn)
+	} catch (err) {
+		const code = (err as { code?: unknown })?.code
+		if (code !== DENIED_CODE || messages.length === 0) throw err
+		const denied = new Error(messages.join(' ')) as Error & { code?: string }
+		denied.code = DENIED_CODE
+		throw denied
+	}
+}
+
+/** `permission denied for <origin>: run \`…\` and retry` */
+export function denialMessage(origin: string, commands: string[]): string {
+	const quoted = commands.map((c) => `\`${c}\``)
+	const list =
+		quoted.length > 1
+			? `${quoted.slice(0, -1).join(', ')} and ${quoted[quoted.length - 1]}`
+			: quoted[0]
+	return `permission denied for ${origin}: run ${list} and retry`
+}
+
+/** The grant a single permission request is asking for. */
+export function specFromRequest(
+	request: PermissionRequest & { requestID: string },
+): GrantSpec {
+	const key = permissionKeyFromRequest(
+		request as unknown as Parameters<typeof permissionKeyFromRequest>[0],
+	)
+	return key.type === 'spending'
+		? { key, authorizedAmount: request.spending?.satoshis ?? 0 }
+		: { key }
+}
+
+/** Every grant a BRC-73 grouped request is asking for. */
+export function specsFromGroupedRequest(
+	request: GroupedPermissionRequest,
+): GrantSpec[] {
+	const amount = request.permissions.spendingAuthorization?.amount ?? 0
+	return permissionKeysFromGroup(
+		request.originator,
+		request.permissions as unknown as Parameters<
+			typeof permissionKeysFromGroup
+		>[1],
+	).map((key: PermissionKey) =>
+		key.type === 'spending' ? { key, authorizedAmount: amount } : { key },
+	)
+}
+
+function displayOrigin(request: PermissionRequest): string {
+	return normalizeOriginator(request.originator)
+}
+
+async function safely(
+	log: (line: string) => void,
+	what: string,
+	fn: () => Promise<void>,
+): Promise<void> {
+	try {
+		await fn()
+	} catch (err) {
+		log(`[wallet-api] ${what} failed: ${(err as Error).message}`)
+	}
+}

package/src/wallet-api/endpoint.ts

@@ -0,0 +1,108 @@
+/**
+ * The app-facing BRC-100 endpoint `1sat serve wallet-api` runs.
+ *
+ * The served wallet is a `LocalWalletPermissionsManager` around the CLI's
+ * toolbox wallet: each app origin gets only what has been granted to it in
+ * the file store, and anything else is denied immediately — there is no
+ * prompt and no auto-approve. The denial names the `1sat permissions grant
+ * …` command that would allow the call, so the agent driving the app can
+ * read the fix out of the app's own error output. The manager's admin
+ * originator is reserved for the process itself; the router rejects it on
+ * the wire.
+ */
+
+import { LocalWalletPermissionsManager } from '@1sat/wallet'
+import {
+	type BRC100ServerHandle,
+	type BRC100WalletHandle,
+	startBRC100Server,
+} from '@1sat/wallet-server'
+import type { WalletInterface } from '@bsv/sdk'
+import type { PermissionsManagerConfig } from '@bsv/wallet-toolbox'
+import { CLI_ADMIN_ORIGINATOR } from './admin.js'
+import { bindPermissionDenials, withDenialMessage } from './deny.js'
+import { FilePermissionStore } from './permission-store.js'
+
+export interface WalletApiOptions {
+	/** The underlying (admin-surface) wallet; never served directly. */
+	wallet: WalletInterface
+	/** Path of the JSON grant store (see `permissionStorePath`). */
+	storePath: string
+	host: string
+	port: number
+	/**
+	 * Command a denial tells the caller to run, minus origin and selectors.
+	 * Defaults to `1sat permissions grant`; `serve` adds `--chain test`
+	 * where it matters.
+	 */
+	grantCommandPrefix?: string
+	/** Extra permissions-manager configuration (tests disable manifest lookups). */
+	managerConfig?: PermissionsManagerConfig
+	/** Request log sink. Defaults to `console.log`. */
+	log?: (line: string) => void
+}
+
+export interface WalletApiHandle {
+	server: BRC100ServerHandle
+	close(): Promise<void>
+}
+
+/**
+ * Expose a `WalletInterface` as a BRC100WalletHandle. The wallet handed in
+ * is the permissions manager, so every call is checked against the
+ * originator's grants before it reaches the toolbox wallet. A refusal
+ * leaves the manager as `Permission denied.`; `withDenialMessage` replaces
+ * it with the grant command recorded while the call was in flight.
+ */
+export function walletApiHandle(wallet: WalletInterface): BRC100WalletHandle {
+	return {
+		async call(method, args, origin) {
+			const fn = (wallet as unknown as Record<string, unknown>)[method] as (
+				a: unknown,
+				o: string,
+			) => Promise<unknown>
+			if (typeof fn !== 'function') {
+				throw new Error(`Method not available: ${method}`)
+			}
+			return withDenialMessage(() => fn.call(wallet, args, origin))
+		},
+	}
+}
+
+/** Wrap the wallet in a permissions manager and serve it over HTTP. */
+export async function startWalletApi(
+	options: WalletApiOptions,
+): Promise<WalletApiHandle> {
+	const log = options.log ?? ((line: string) => console.log(line))
+	const manager = new LocalWalletPermissionsManager(
+		options.wallet,
+		CLI_ADMIN_ORIGINATOR,
+		// Metadata encryption stays at the toolbox default (on): descriptions
+		// an app writes through this endpoint are encrypted at rest. The CLI's
+		// own commands read through a manager too (see `adminWallet`), which
+		// decrypts them again.
+		{ ...options.managerConfig },
+		{ store: new FilePermissionStore(options.storePath) },
+	)
+	bindPermissionDenials(manager, {
+		grantCommandPrefix: options.grantCommandPrefix,
+		log,
+	})
+
+	const server = await startBRC100Server({
+		host: options.host,
+		port: options.port,
+		adminOriginator: CLI_ADMIN_ORIGINATOR,
+		wallet: walletApiHandle(manager),
+		onEvent: (event) => {
+			if (event.event !== 'brc100_call') return
+			const line = `[wallet-api] ${event.method} from ${event.origin || '(no origin)'} -> ${event.status}`
+			log(event.error ? `${line}: ${event.error}` : line)
+		},
+	})
+
+	return {
+		server,
+		close: () => server.close(),
+	}
+}

package/src/wallet-api/grants.ts

@@ -0,0 +1,238 @@
+/**
+ * Permission grants as CLI arguments.
+ *
+ * One place translates between the three shapes a grant takes:
+ *
+ *  - the `PermissionKey` the store is indexed by,
+ *  - the `1sat permissions grant …` command line a person or an agent types,
+ *  - the one-line description `1sat permissions list` prints.
+ *
+ * The wallet-api denies every permission it has not been granted and puts
+ * the command that would allow it into the error, so the app driving the
+ * wallet can print it verbatim. That command is rendered here from the same
+ * `PermissionKey` the store would be asked for, which is what keeps the
+ * suggestion and the lookup from drifting apart.
+ */
+
+import {
+	type PermissionKey,
+	normalizeOriginator,
+	permissionKeyToString,
+} from '@1sat/wallet'
+
+/** Protocols named `action label <x>` are how the manager gates action labels. */
+const LABEL_PROTOCOL_PREFIX = 'action label '
+
+/** The command word the denial message and help text point at. */
+export const GRANT_COMMAND = '1sat permissions grant'
+
+/** A grant as the `permissions` command's flags describe it. */
+export interface GrantSpec {
+	key: PermissionKey
+	/** DSAP only — the monthly cap in satoshis. */
+	authorizedAmount?: number
+}
+
+/** Quote a flag value for a shell only when it needs it. */
+export function shellQuote(value: string): string {
+	if (value !== '' && /^[A-Za-z0-9_@%+=:,./-]+$/.test(value)) return value
+	return `"${value.replace(/(["\\$`])/g, '\\$1')}"`
+}
+
+/**
+ * Render the `1sat permissions grant …` command that would allow `key`.
+ *
+ * `prefix` carries any global flags the caller needs (`1sat --chain test
+ * permissions grant`), so the printed command works as-is on that chain.
+ */
+export function grantCommand(
+	spec: GrantSpec,
+	prefix: string = GRANT_COMMAND,
+): string {
+	const key = spec.key
+	const parts = [prefix, shellQuote(key.originator)]
+	switch (key.type) {
+		case 'protocol': {
+			if (
+				key.protocolLevel === 1 &&
+				key.protocolName.startsWith(LABEL_PROTOCOL_PREFIX)
+			) {
+				parts.push(
+					'--label',
+					shellQuote(key.protocolName.slice(LABEL_PROTOCOL_PREFIX.length)),
+				)
+				break
+			}
+			parts.push('--protocol', shellQuote(key.protocolName))
+			parts.push('--level', String(key.protocolLevel))
+			// Level 1 protocols are counterparty-less by definition (the key
+			// always holds ''), so naming one would only mislead.
+			if (key.protocolLevel !== 1 && key.counterparty) {
+				parts.push('--counterparty', shellQuote(key.counterparty))
+			}
+			if (key.privileged) parts.push('--privileged')
+			break
+		}
+		case 'basket':
+			parts.push('--basket', shellQuote(key.basket))
+			break
+		case 'certificate':
+			parts.push('--certificate', shellQuote(key.certType))
+			parts.push('--fields', shellQuote(key.fields.join(',')))
+			if (key.verifier) {
+				parts.push('--counterparty', shellQuote(key.verifier))
+			}
+			if (key.privileged) parts.push('--privileged')
+			break
+		case 'spending':
+			parts.push('--spending', String(spec.authorizedAmount ?? 0))
+			break
+	}
+	return parts.join(' ')
+}
+
+/** One-line description of a grant, for `1sat permissions list`. */
+export function describeKey(spec: GrantSpec): string {
+	const key = spec.key
+	switch (key.type) {
+		case 'protocol': {
+			if (
+				key.protocolLevel === 1 &&
+				key.protocolName.startsWith(LABEL_PROTOCOL_PREFIX)
+			) {
+				return `label    ${key.protocolName.slice(LABEL_PROTOCOL_PREFIX.length)}`
+			}
+			const bits = [`"${key.protocolName}" (level ${key.protocolLevel}`]
+			if (key.protocolLevel !== 1 && key.counterparty) {
+				bits.push(`, counterparty ${key.counterparty}`)
+			}
+			if (key.privileged) bits.push(', privileged')
+			return `protocol ${bits.join('')})`
+		}
+		case 'basket':
+			return `basket   "${key.basket}"`
+		case 'certificate':
+			return `cert     "${key.certType}" fields [${key.fields.join(', ')}]${
+				key.verifier ? ` to ${key.verifier}` : ''
+			}${key.privileged ? ' (privileged)' : ''}`
+		case 'spending':
+			return `spending up to ${spec.authorizedAmount ?? 0} sat per month`
+	}
+}
+
+/** Flags `1sat permissions grant` / `revoke` accept, already parsed. */
+export interface GrantFlags {
+	protocol?: string
+	level?: string
+	counterparty?: string
+	privileged: boolean
+	basket?: string
+	label?: string
+	certificate?: string
+	fields?: string
+	spending?: string
+}
+
+/**
+ * Turn parsed flags into the grants they name.
+ *
+ * Several selectors in one invocation produce several grants, so an app's
+ * whole set can be granted in one line. Throws with a usable message when a
+ * selector is incomplete; the caller reports it.
+ */
+export function specsFromFlags(origin: string, flags: GrantFlags): GrantSpec[] {
+	const originator = normalizeOriginator(origin)
+	if (!originator) throw new Error('An app origin is required')
+	const specs: GrantSpec[] = []
+
+	if (flags.protocol !== undefined || flags.label !== undefined) {
+		if (flags.protocol !== undefined && flags.label !== undefined) {
+			throw new Error('Use either --protocol or --label, not both')
+		}
+		const isLabel = flags.label !== undefined
+		const name = isLabel
+			? `${LABEL_PROTOCOL_PREFIX}${flags.label}`
+			: (flags.protocol as string)
+		if (!name.trim() || name === LABEL_PROTOCOL_PREFIX) {
+			throw new Error(
+				isLabel ? '--label requires a name' : '--protocol requires a name',
+			)
+		}
+		// A label is always a level-1 protocol upstream; --level would only
+		// let a caller write a key the manager never looks up.
+		const level = isLabel ? 1 : parseLevel(flags.level)
+		specs.push({
+			key: {
+				type: 'protocol',
+				originator,
+				privileged: flags.privileged,
+				protocolLevel: level,
+				protocolName: name,
+				counterparty: level === 1 ? '' : (flags.counterparty ?? 'self'),
+			},
+		})
+	}
+
+	if (flags.basket !== undefined) {
+		if (!flags.basket.trim()) throw new Error('--basket requires a name')
+		specs.push({
+			key: { type: 'basket', originator, basket: flags.basket },
+		})
+	}
+
+	if (flags.certificate !== undefined) {
+		if (!flags.certificate.trim()) {
+			throw new Error('--certificate requires a certificate type')
+		}
+		const fields = (flags.fields ?? '')
+			.split(',')
+			.map((f) => f.trim())
+			.filter((f) => f.length > 0)
+		if (fields.length === 0) {
+			throw new Error('--certificate requires --fields <a,b>')
+		}
+		specs.push({
+			key: {
+				type: 'certificate',
+				originator,
+				privileged: flags.privileged,
+				verifier: flags.counterparty ?? '',
+				certType: flags.certificate,
+				fields: fields.sort(),
+			},
+		})
+	}
+
+	if (flags.spending !== undefined) {
+		const satoshis = Number(flags.spending)
+		if (!Number.isInteger(satoshis) || satoshis <= 0) {
+			throw new Error('--spending requires a positive whole number of satoshis')
+		}
+		specs.push({
+			key: { type: 'spending', originator },
+			authorizedAmount: satoshis,
+		})
+	}
+
+	if (specs.length === 0) {
+		throw new Error(
+			'Nothing selected. Pass --protocol/--label, --basket, --certificate or --spending',
+		)
+	}
+	return specs
+}
+
+function parseLevel(value: string | undefined): 0 | 1 | 2 {
+	if (value === undefined) {
+		throw new Error('--protocol requires --level <0|1|2>')
+	}
+	if (value !== '0' && value !== '1' && value !== '2') {
+		throw new Error(`--level must be 0, 1 or 2 (got ${value})`)
+	}
+	return Number(value) as 0 | 1 | 2
+}
+
+/** Canonical id of a grant; two selectors naming the same grant share it. */
+export function specId(spec: GrantSpec): string {
+	return permissionKeyToString(spec.key)
+}