Add a separate scoped operator credential for pool accounting and payouts #31

New issue

Closed

opened 2026-08-27 21:03:17 +00:00 by ignotusnemo · 2 comments

ignotusnemo commented

2026-08-27 21:03:17 +00:00

(Migrated from github.com)

Problem

v1.0.3 correctly restricts the mining credential to paranoid_getBlockTemplate and paranoid_submitBlock. That hardening must remain unchanged.

However, a multi-host pool commonly separates prover/mining nodes, the wallet node, and the accounting/payout backend. Before v1.0.3, some deployments used the mining bearer token for wallet and inspection RPC calls over a protected LAN. After the mining scope was tightened, no remote credential can authorize those calls, while unauthenticated wallet RPC must not be exposed off-host.

Proposed interface

Add two optional daemon arguments:

--operator-key TOKEN
--operator-key-file FILE

The operator credential is independent from the mining credential and uses a fixed allowlist. It is intended for a trusted pool or exchange accounting and payout backend, not for miners or browsers.

Exact operator allowlist

paranoid_getChainInfo
paranoid_getTx
paranoid_getMempoolEntry
paranoid_validateAddress
paranoid_estimateFee
paranoid_estimateFeeDetailed
paranoid_verifyReceipt
paranoid_submitTxIntent
paranoid_walletStatus
paranoid_walletGetBalance
paranoid_walletMinedBlocks
paranoid_walletReceipts
paranoid_walletExportReceipt
paranoid_walletPlanSend
paranoid_walletSend
paranoid_walletPlanConsolidation
paranoid_walletConsolidate

Every unlisted current or future method must remain denied.

In particular, the operator credential must not authorize mining methods, paranoid_stop, wallet scanning/discovery, address management, or unbounded wallet history/UTXO listings.

Security requirements

The feature is disabled unless an operator key is explicitly configured.
Mining and operator tokens must be different and their scopes must never be combined.
The mining credential remains restricted to its existing two methods.
Tokens must contain at least 16 characters and no whitespace.
Key files must be regular owner-only files and must be opened without following symlinks.
A non-loopback RPC listener must refuse to start unless at least one scoped credential is configured.
Missing or incorrect bearer tokens receive HTTP 401.
Browser-originated requests remain rejected.
The operator token carries spending authority through walletSend; the daemon must warn that bearer authentication does not encrypt transport. Remote use requires a private firewall/VPN or an authenticated TLS/SSH tunnel.
The normal default remains unchanged: a node and parano1d-cli on the same host use loopback RPC without a password.

Acceptance tests

Each valid token is assigned exactly one role.
Mining token: both mining methods succeed; wallet/operator methods fail.
Operator token: every allowlisted method succeeds; mining, node-control, unlisted wallet-management, and unknown methods fail.
Wrong or missing token returns HTTP 401.
Equal mining/operator tokens are rejected at startup.
Insecure key-file permissions and symlinks are rejected.
Unauthenticated non-loopback RPC bind is rejected.
Unauthenticated loopback RPC remains fully compatible with the local CLI.

## Problem v1.0.3 correctly restricts the mining credential to `paranoid_getBlockTemplate` and `paranoid_submitBlock`. That hardening must remain unchanged. However, a multi-host pool commonly separates prover/mining nodes, the wallet node, and the accounting/payout backend. Before v1.0.3, some deployments used the mining bearer token for wallet and inspection RPC calls over a protected LAN. After the mining scope was tightened, no remote credential can authorize those calls, while unauthenticated wallet RPC must not be exposed off-host. ## Proposed interface Add two optional daemon arguments: - `--operator-key TOKEN` - `--operator-key-file FILE` The operator credential is independent from the mining credential and uses a fixed allowlist. It is intended for a trusted pool or exchange accounting and payout backend, not for miners or browsers. ## Exact operator allowlist - `paranoid_getChainInfo` - `paranoid_getTx` - `paranoid_getMempoolEntry` - `paranoid_validateAddress` - `paranoid_estimateFee` - `paranoid_estimateFeeDetailed` - `paranoid_verifyReceipt` - `paranoid_submitTxIntent` - `paranoid_walletStatus` - `paranoid_walletGetBalance` - `paranoid_walletMinedBlocks` - `paranoid_walletReceipts` - `paranoid_walletExportReceipt` - `paranoid_walletPlanSend` - `paranoid_walletSend` - `paranoid_walletPlanConsolidation` - `paranoid_walletConsolidate` Every unlisted current or future method must remain denied. In particular, the operator credential must not authorize mining methods, `paranoid_stop`, wallet scanning/discovery, address management, or unbounded wallet history/UTXO listings. ## Security requirements - The feature is disabled unless an operator key is explicitly configured. - Mining and operator tokens must be different and their scopes must never be combined. - The mining credential remains restricted to its existing two methods. - Tokens must contain at least 16 characters and no whitespace. - Key files must be regular owner-only files and must be opened without following symlinks. - A non-loopback RPC listener must refuse to start unless at least one scoped credential is configured. - Missing or incorrect bearer tokens receive HTTP 401. - Browser-originated requests remain rejected. - The operator token carries spending authority through `walletSend`; the daemon must warn that bearer authentication does not encrypt transport. Remote use requires a private firewall/VPN or an authenticated TLS/SSH tunnel. - The normal default remains unchanged: a node and `parano1d-cli` on the same host use loopback RPC without a password. ## Acceptance tests - Each valid token is assigned exactly one role. - Mining token: both mining methods succeed; wallet/operator methods fail. - Operator token: every allowlisted method succeeds; mining, node-control, unlisted wallet-management, and unknown methods fail. - Wrong or missing token returns HTTP 401. - Equal mining/operator tokens are rejected at startup. - Insecure key-file permissions and symlinks are rejected. - Unauthenticated non-loopback RPC bind is rejected. - Unauthenticated loopback RPC remains fully compatible with the local CLI.

ignotusnemo commented

2026-08-27 21:22:32 +00:00

(Migrated from github.com)

Implemented in github.com/ignotusnemo/parano1d@4be38fb4b5

Implemented in https://github.com/ignotusnemo/parano1d/commit/4be38fb4b547887d24a95de7732d18ef3ec45b8f

ignotusnemo commented

2026-08-28 07:44:30 +00:00

(Migrated from github.com)

Released in Parano1d v1.0.4 Mainnet. The operator credential and its fixed RPC allowlist are documented in JSON-RPC authentication.

Released in [Parano1d v1.0.4 Mainnet](https://github.com/ignotusnemo/parano1d/releases/tag/v1.0.4). The operator credential and its fixed RPC allowlist are documented in [JSON-RPC authentication](https://github.com/ignotusnemo/parano1d/blob/v1.0.4/docs/reference/rpc.md#authentication).