@1sat/cli 0.0.120 → 0.0.121

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1sat/cli",
-  "version": "0.0.120",
+  "version": "0.0.121",
   "description": "CLI for 1Sat Ordinals SDK",
   "type": "module",
   "main": "./dist/cli.js",
@@ -27,11 +27,12 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "@1sat/actions": "0.0.224",
+    "@1sat/actions": "0.0.225",
     "@1sat/client": "0.0.55",
     "@1sat/types": "0.0.48",
-    "@1sat/wallet-node": "0.0.78",
-    "@1sat/wallet-server": "0.0.55",
+    "@1sat/wallet": "0.0.112",
+    "@1sat/wallet-node": "0.0.79",
+    "@1sat/wallet-server": "0.0.56",
     "@bopen-io/messagebox-server": "^1.3.2",
     "@bsv/sdk": "^2.6.0",
     "@bsv/wallet-toolbox": "npm:@bopen-io/wallet-toolbox@2.6.2-brc153.5",

package/src/commands/permissions.ts

@@ -0,0 +1,269 @@
+/**
+ * `1sat permissions` — what apps on `1sat serve wallet-api` may do.
+ *
+ * The endpoint never asks: a request it has no grant for is denied, and
+ * the error names the `1sat permissions grant …` command that would allow
+ * it. This command is the other half of that loop.
+ *
+ * Everything here works directly on the JSON grant store
+ * (`<dataDir>/permissions-<chain>.json`), so it needs no key, no wallet
+ * and no running server. The manager reads that file on every check, so a
+ * grant written while `1sat serve wallet-api` is running takes effect on
+ * the app's next call — no restart.
+ */
+
+import { normalizeOriginator } from '@1sat/wallet'
+import type { StoredGrant } from '@1sat/wallet'
+import type { GlobalFlags } from '../args.js'
+import { extractFlag, hasFlag } from '../args.js'
+import { ensureDataDir } from '../config.js'
+import { printCommandHelp } from '../help.js'
+import { fatal, formatLabel, formatValue, output } from '../output.js'
+import {
+	type GrantFlags,
+	type GrantSpec,
+	describeKey,
+	grantCommand,
+	specId,
+	specsFromFlags,
+} from '../wallet-api/grants.js'
+import {
+	FilePermissionStore,
+	permissionStorePath,
+} from '../wallet-api/permission-store.js'
+
+export async function handlePermissionsCommand(
+	args: string[],
+	opts: GlobalFlags,
+): Promise<void> {
+	const [subcommand, ...rest] = args
+
+	switch (subcommand) {
+		case 'list':
+		case 'ls': // deprecated alias
+			return permissionsList(rest, opts)
+		case 'grant':
+			return permissionsGrant(rest, opts)
+		case 'revoke':
+			return permissionsRevoke(rest, opts)
+		default:
+			printCommandHelp('permissions', opts.json)
+			if (subcommand && subcommand !== 'help') {
+				process.exit(1)
+			}
+	}
+}
+
+/** The store `1sat serve wallet-api` reads on this chain. */
+function openStore(opts: GlobalFlags): {
+	store: FilePermissionStore
+	path: string
+} {
+	const path = permissionStorePath(ensureDataDir(), opts.chain)
+	return { store: new FilePermissionStore(path), path }
+}
+
+/** `1sat permissions grant`, with the global flags this invocation used. */
+function commandPrefix(opts: GlobalFlags): string {
+	return opts.chain === 'test'
+		? '1sat --chain test permissions grant'
+		: '1sat permissions grant'
+}
+
+function grantFlags(args: string[]): GrantFlags {
+	return {
+		protocol: extractFlag(args, '--protocol'),
+		level: extractFlag(args, '--level'),
+		counterparty:
+			extractFlag(args, '--counterparty') ?? extractFlag(args, '--verifier'),
+		privileged: hasFlag(args, '--privileged'),
+		basket: extractFlag(args, '--basket'),
+		label: extractFlag(args, '--label'),
+		certificate: extractFlag(args, '--certificate'),
+		fields: extractFlag(args, '--fields'),
+		spending: extractFlag(args, '--spending'),
+	}
+}
+
+/** Flags of this command that take no value. */
+const BOOLEAN_FLAGS = new Set(['--privileged', '--all'])
+
+/** First non-flag argument, skipping the values flags consume. */
+function firstPositional(args: string[]): string | undefined {
+	for (let i = 0; i < args.length; i++) {
+		const arg = args[i]
+		if (arg.startsWith('--')) {
+			if (!BOOLEAN_FLAGS.has(arg)) i++
+			continue
+		}
+		return arg
+	}
+	return undefined
+}
+
+function toSpec(grant: StoredGrant): GrantSpec {
+	return grant.authorizedAmount != null
+		? { key: grant.key, authorizedAmount: grant.authorizedAmount }
+		: { key: grant.key }
+}
+
+async function permissionsList(
+	args: string[],
+	opts: GlobalFlags,
+): Promise<void> {
+	const { store, path } = openStore(opts)
+	const origin = firstPositional(args)
+	const filter = origin ? { originator: normalizeOriginator(origin) } : {}
+	const grants = await store.listGrants(filter)
+
+	if (opts.json) {
+		output(grants, opts)
+		return
+	}
+
+	if (grants.length === 0) {
+		output(
+			origin
+				? `No grants for ${normalizeOriginator(origin)} in ${path}`
+				: `No grants in ${path}`,
+			opts,
+		)
+		return
+	}
+
+	const byOrigin = new Map<string, StoredGrant[]>()
+	for (const grant of grants) {
+		const list = byOrigin.get(grant.key.originator) ?? []
+		list.push(grant)
+		byOrigin.set(grant.key.originator, list)
+	}
+
+	for (const name of [...byOrigin.keys()].sort()) {
+		console.log(`\n${formatValue(name)}`)
+		for (const grant of byOrigin.get(name) ?? []) {
+			const expiry =
+				grant.expiry > 0
+					? ` expires ${new Date(grant.expiry * 1000).toISOString()}`
+					: ''
+			console.log(
+				`  ${describeKey(toSpec(grant))}${formatLabel(expiry)}${formatLabel(
+					grant.reason ? ` — ${grant.reason}` : '',
+				)}`,
+			)
+		}
+	}
+	console.log(`\n  ${grants.length} grant(s) in ${path}`)
+}
+
+async function permissionsGrant(
+	args: string[],
+	opts: GlobalFlags,
+): Promise<void> {
+	const origin = firstPositional(args)
+	if (!origin) fatal('Missing <origin>. See `1sat permissions --help`')
+
+	let specs: GrantSpec[]
+	try {
+		specs = specsFromFlags(origin, grantFlags(args))
+	} catch (err) {
+		return fatal((err as Error).message)
+	}
+
+	const { store, path } = openStore(opts)
+	const now = Date.now()
+	for (const spec of specs) {
+		await store.putGrant({
+			key: spec.key,
+			expiry: 0,
+			grantedAt: now,
+			...(spec.authorizedAmount != null
+				? { authorizedAmount: spec.authorizedAmount }
+				: {}),
+		})
+	}
+
+	if (opts.json) {
+		output(
+			{
+				granted: specs.map((spec) => ({
+					id: specId(spec),
+					key: spec.key,
+					authorizedAmount: spec.authorizedAmount,
+				})),
+				store: path,
+			},
+			opts,
+		)
+		return
+	}
+
+	for (const spec of specs) {
+		console.log(`granted ${describeKey(spec)}`)
+	}
+	console.log(
+		`\n  ${specs.length} grant(s) written to ${path}. A running \`1sat serve wallet-api\` picks them up on the app's next call.`,
+	)
+}
+
+async function permissionsRevoke(
+	args: string[],
+	opts: GlobalFlags,
+): Promise<void> {
+	const origin = firstPositional(args)
+	if (!origin) fatal('Missing <origin>. See `1sat permissions --help`')
+	const originator = normalizeOriginator(origin)
+	const { store, path } = openStore(opts)
+
+	if (hasFlag(args, '--all')) {
+		const removed = await store.deleteAllForOriginator(originator)
+		if (opts.json) {
+			output({ originator, removed, store: path }, opts)
+			return
+		}
+		output(`revoked ${removed} grant(s) for ${originator}`, opts)
+		return
+	}
+
+	let specs: GrantSpec[]
+	try {
+		specs = specsFromFlags(origin, grantFlags(args))
+	} catch (err) {
+		return fatal(
+			`${(err as Error).message}. Pass --all to revoke everything for an origin.`,
+		)
+	}
+
+	const removed: GrantSpec[] = []
+	const missing: GrantSpec[] = []
+	for (const spec of specs) {
+		if (await store.findGrant(spec.key)) {
+			await store.deleteGrant(spec.key)
+			removed.push(spec)
+		} else {
+			missing.push(spec)
+		}
+	}
+
+	if (opts.json) {
+		output(
+			{
+				revoked: removed.map((spec) => ({ id: specId(spec), key: spec.key })),
+				notFound: missing.map((spec) => ({ id: specId(spec), key: spec.key })),
+				store: path,
+			},
+			opts,
+		)
+		return
+	}
+
+	for (const spec of removed) console.log(`revoked ${describeKey(spec)}`)
+	for (const spec of missing) {
+		console.log(
+			`no such grant: ${describeKey(spec)} (grant it with \`${grantCommand(
+				spec,
+				commandPrefix(opts),
+			)}\`)`,
+		)
+	}
+	console.log(`\n  ${removed.length} grant(s) removed from ${path}`)
+}

package/src/commands/serve.ts

@@ -4,6 +4,7 @@
  *   1sat serve              Host server (storage + accounts + paymail + messagebox) + monitor
  *   1sat serve wallet       Wallet storage server only
  *   1sat serve monitor      Monitor daemon only
+ *   1sat serve wallet-api   App-facing BRC-100 endpoint (headless; grants come from `1sat permissions`)
  *
  * The server wraps the same wallet instance the CLI uses. Storage, active
  * remote, and backups all come from `~/.1sat/cli/config.json` via the same
@@ -25,15 +26,12 @@ import {
 	createNodeWallet,
 } from '@1sat/wallet-node'
 import {
-	type BRC100WalletHandle,
 	KnexAccountStore,
 	KnexHandleCertStore,
 	KnexPendingStore,
 	createHostServer,
 	createWalletServer,
-	startBRC100Server,
 } from '@1sat/wallet-server'
-import type { Wallet, WalletInterface } from '@bsv/sdk'
 import type { PrivateKey } from '@bsv/sdk'
 import { initLogger } from 'evlog'
 import knexLib from 'knex'
@@ -57,6 +55,9 @@ import {
 	createAccountsConfigLoader,
 	resolveRateProvider,
 } from '../repricer/index.js'
+import { startWalletApi } from '../wallet-api/endpoint.js'
+import { GRANT_COMMAND } from '../wallet-api/grants.js'
+import { permissionStorePath } from '../wallet-api/permission-store.js'
 
 const DEFAULT_HOST = '127.0.0.1'
 const DEFAULT_PORT = 8100
@@ -276,7 +277,7 @@ async function runWithStorage(
 	// wallet-api serves only the app-facing BRC-100 endpoint: no storage
 	// server, no accounts, no monitor.
 	if (mode === 'wallet-api') {
-		const dapp = await startDappEndpoint(walletResult)
+		const dapp = await startDappEndpoint(walletResult, resolved)
 		return {
 			stop: async () => {
 				await dapp.close()
@@ -562,36 +563,18 @@ function waitForShutdown(): Promise<void> {
 const DEFAULT_DAPP_HOST = '127.0.0.1'
 const DEFAULT_DAPP_PORT = 3321
 
-/**
- * Wrap the CLI's wallet (wallet-toolbox client) as a BRC100WalletHandle.
- * The toolbox Wallet already implements the 28 BRC-100 methods with the
- * `(args, originator)` signature the dApps send.
- */
-function walletApiHandle(wallet: Wallet): BRC100WalletHandle {
-	return {
-		async call(method, args, origin) {
-			const iface = wallet as unknown as WalletInterface
-			const fn = (iface 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 await fn.call(iface, args, origin)
-		},
-	}
-}
-
 /**
  * Start the app-facing BRC-100 HTTP endpoint (the interface dApps like
  * wallet-desktop's :3321 server speak; see bitplan and other BRC-100
- * clients). Headless by design: sensitive methods are auto-approved with a
- * console line unless `server.dapp.approve` is set, in which case each one
- * must be confirmed on the TTY.
+ * clients). See `../wallet-api/endpoint.ts` for what is served: a
+ * permissions manager around the CLI wallet, grants kept in
+ * `<dataDir>/permissions-<chain>.json`, and every ungranted request denied
+ * on the spot with the `1sat permissions grant` command that would allow
+ * it. Nothing is ever asked on this terminal.
  */
 async function startDappEndpoint(
 	walletResult: NodeWalletResult,
+	resolved: ResolvedServe,
 ): Promise<{ close: () => Promise<void> }> {
 	const config = loadConfig()
 	const dapp = config.server?.dapp ?? {}
@@ -602,46 +585,26 @@ async function startDappEndpoint(
 			? Number(process.env.ONESAT_DAPP_PORT)
 			: DEFAULT_DAPP_PORT)
 
-	const approve = dapp.approve === true
-
-	const handle = await startBRC100Server({
+	const storePath = permissionStorePath(resolved.dataDir, resolved.chain)
+	// Denials print the command that would allow them, so it has to carry
+	// the chain when this is not the default one.
+	const grantCommandPrefix =
+		resolved.chain === 'test'
+			? '1sat --chain test permissions grant'
+			: GRANT_COMMAND
+	const api = await startWalletApi({
+		wallet: walletResult.wallet,
+		storePath,
 		host,
 		port,
-		wallet: walletApiHandle(walletResult.wallet),
-		approvalPolicy: approve
-			? async ({ method, origin, args }) => {
-					const { confirm, isCancel } = await import('@clack/prompts')
-					console.log(`\n[brc-100] ${method} requested by ${origin}`)
-					console.log(`          ${JSON.stringify(args).slice(0, 400)}`)
-					const ok = await confirm({
-						message: `Approve ${method}?`,
-					})
-					if (isCancel(ok) || !ok) {
-						throw new Error('User denied permission')
-					}
-				}
-			: undefined,
-		onEvent: (event) => {
-			if (event.event === 'brc100_sensitive') {
-				const trustNote = event.trusted
-					? ' (trusted)'
-					: approve
-						? ''
-						: ' (auto-approved)'
-				console.log(
-					`[brc-100] sensitive ${event.method} from ${event.origin}${trustNote}`,
-				)
-			}
-		},
+		grantCommandPrefix,
 	})
 
 	console.log(`[wallet-api] BRC-100 app endpoint on http://${host}:${port}`)
+	console.log(`[wallet-api] permission grants: ${storePath}`)
 	console.log(
-		approve
-			? '[wallet-api] sensitive methods require TTY confirmation'
-			: '[wallet-api] sensitive methods are AUTO-APPROVED (headless). ' +
-					'Set server.dapp.approve=true to require confirmation.',
+		'[wallet-api] ungranted requests are denied; the error names the `1sat permissions grant` command that allows them',
 	)
 
-	return { close: async () => await handle.close() }
+	return { close: () => api.close() }
 }

package/src/config.ts

@@ -156,14 +156,15 @@ export interface ServerConfig {
 	messagebox?: ServerMessageboxConfig
 	/**
 	 * Application-facing BRC-100 endpoint (`1sat serve wallet-api`):
-	 * dApp connectivity for the CLI wallet (encrypt/decrypt/sign/create-action).
-	 * Defaults: 127.0.0.1:3321, headless auto-approval of sensitive methods.
+	 * dApp connectivity for the CLI wallet. Defaults to 127.0.0.1:3321.
+	 * Each app origin is limited to the permissions granted to it with
+	 * `1sat permissions grant`; anything else is denied on the spot. The
+	 * endpoint never prompts and there is no setting that approves
+	 * without a grant.
 	 */
 	dapp?: {
 		host?: string
 		port?: number
-		/** Require TTY confirmation for sensitive methods. Default false. */
-		approve?: boolean
 	}
 	/** Paymail settings for the unified host. */
 	paymail?: ServerPaymailConfig

package/src/context.ts

@@ -5,6 +5,11 @@
  * not run in-process (avoids toolbox/console noise on the TTY). After the
  * wallet is destroyed, a detached `__monitor-once` child may run against the
  * same storage with logs in <dataDir>/monitor.log.
+ *
+ * The context's wallet is the permissions manager called as the CLI's admin
+ * originator, not the raw toolbox wallet: checks are bypassed, transaction
+ * metadata is encrypted at rest and decrypted on the way back. See
+ * `wallet-api/admin.ts`.
  */
 
 import { type OneSatContext, createContext } from '@1sat/actions'
@@ -12,6 +17,11 @@ import { type NodeWalletResult, createNodeWallet } from '@1sat/wallet-node'
 import type { PrivateKey } from '@bsv/sdk'
 import { ensureDataDir, loadConfig } from './config.js'
 import { spawnDetachedMonitorOnce } from './monitor-once.js'
+import { adminWallet } from './wallet-api/admin.js'
+import {
+	FilePermissionStore,
+	permissionStorePath,
+} from './wallet-api/permission-store.js'
 
 /** Extended context that includes cleanup */
 export interface CliContext {
@@ -52,7 +62,17 @@ export async function loadContext(
 		skipInitialMonitor: true,
 	})
 
-	const ctx = createContext(walletResult.wallet, {
+	// Commands talk to the wallet through the permissions manager as the
+	// admin originator: checks are bypassed, and transaction metadata is
+	// encrypted and decrypted the same way the served endpoint does it. The
+	// store is the same file `1sat permissions` and the endpoint use, so
+	// nothing here can disagree with what the endpoint enforces.
+	const wallet = adminWallet(
+		walletResult.wallet,
+		new FilePermissionStore(permissionStorePath(dataDir, opts.chain)),
+	)
+
+	const ctx = createContext(wallet, {
 		services: walletResult.services,
 		chain: opts.chain,
 		dataDir,

package/src/help.ts

@@ -757,7 +757,88 @@ export const COMMANDS: CommandSpec[] = [
 			{
 				name: 'wallet-api',
 				description:
-					'App-facing BRC-100 wallet endpoint only (headless, default port 3321)',
+					'App-facing BRC-100 wallet endpoint only (headless, default port 3321). Ungranted requests are denied with the `1sat permissions grant` command that would allow them',
+			},
+		],
+	},
+	{
+		group: 'Server',
+		name: 'permissions',
+		description:
+			"What apps on `1sat serve wallet-api` may do. Grants live in <dataDir>/permissions-<chain>.json; the endpoint reads the file on every check, so a grant applies to the app's next call without a restart. Works with the server stopped or running and needs no wallet key.",
+		subcommands: [
+			{
+				name: 'list',
+				description: 'Show grants, grouped by app origin',
+				positional: '[<origin>]',
+			},
+			{
+				name: 'grant',
+				description:
+					'Allow an app one or more permissions. Selectors may be combined in one call.',
+				positional: '<origin>',
+				args: [
+					{
+						flag: '--protocol',
+						values: '<name>',
+						description: 'Protocol name; requires --level',
+					},
+					{
+						flag: '--level',
+						values: '<0|1|2>',
+						description: 'Protocol security level',
+					},
+					{
+						flag: '--counterparty',
+						values: '<hex|self|anyone>',
+						description:
+							"Counterparty for a level 0/2 protocol (default self; ignored at level 1), or a certificate's verifier (also --verifier)",
+					},
+					{
+						flag: '--privileged',
+						description:
+							'Grant the privileged variant of a protocol/certificate',
+					},
+					{ flag: '--basket', values: '<name>', description: 'Basket access' },
+					{
+						flag: '--label',
+						values: '<name>',
+						description:
+							'Action label (a level-1 `action label <name>` protocol)',
+					},
+					{
+						flag: '--certificate',
+						values: '<type>',
+						description: 'Certificate type; requires --fields',
+					},
+					{
+						flag: '--fields',
+						values: '<a,b>',
+						description: 'Certificate fields that may be disclosed',
+					},
+					{
+						flag: '--spending',
+						values: '<satoshis>',
+						description:
+							'Monthly spending cap; month-to-date spend is read from action history on every check',
+					},
+				],
+			},
+			{
+				name: 'revoke',
+				description: 'Remove matching grants, or every grant for an origin',
+				positional: '<origin>',
+				args: [
+					{
+						flag: '--all',
+						description: 'Remove every grant for the origin',
+					},
+					{
+						flag: '--protocol',
+						values: '<name>',
+						description: 'Same selectors as `grant`',
+					},
+				],
 			},
 		],
 	},

package/src/main.ts

@@ -21,6 +21,7 @@ import { handleMcpProxyCommand } from './commands/mcp-proxy.js'
 import { handleMessageboxCommand } from './commands/messagebox.js'
 import { handleOpnsCommand } from './commands/opns.js'
 import { handleOrdinalsCommand } from './commands/ordinals.js'
+import { handlePermissionsCommand } from './commands/permissions.js'
 import { handleRemoteCommand } from './commands/remote.js'
 import { handleServeCommand } from './commands/serve.js'
 import { handleSocialCommand } from './commands/social.js'
@@ -151,6 +152,10 @@ async function main(): Promise<void> {
 			await handleServeCommand(rest, flags)
 			break
 
+		case 'permissions':
+			await handlePermissionsCommand(rest, flags)
+			break
+
 		case 'storage':
 			await handleStorageCommand(rest, flags)
 			break