From 12f80fdc53714f1e404a4a15283db66eb5887c26 Mon Sep 17 00:00:00 2001 From: Eric Meehan Date: Thu, 22 Oct 2026 02:09:07 -0400 Subject: [PATCH] Private CLI workflow for reviewed depowit operations --- docs/postgres-financial-storage.md | 15 +++++ docs/production-plan.md | 2 + scripts/custody-db.ts | 51 +++++++++++++++- server/market/custody-db-args.ts | 30 ++++++++++ server/market/monero-deposit-review-config.ts | 58 +++++++++++++++++++ tests/custody-db-args.test.ts | 19 ++++++ tests/monero-deposit-review-config.test.ts | 58 +++++++++++++++++++ 7 files changed, 231 insertions(+), 2 deletions(-) create mode 100755 server/market/custody-db-args.ts create mode 100755 server/market/monero-deposit-review-config.ts create mode 100755 tests/custody-db-args.test.ts create mode 100755 tests/monero-deposit-review-config.test.ts diff --git a/docs/postgres-financial-storage.md b/docs/postgres-financial-storage.md index 83bc344..c249141 100755 --- a/docs/postgres-financial-storage.md +++ b/docs/postgres-financial-storage.md @@ -100,3 +100,18 @@ Verified: restricted runtime authorization; deferred balance constraints; fracti Final evidence: TypeScript/Vite test-image build passed; **149 existing regression tests and 10 isolated PostgreSQL integration tests passed**, zero failures/skips. PostgreSQL fixture resources were removed after testing. Existing user data directories and deployed node database settings were not switched. This verifies the current sandbox implementation, not production acceptance. **Not closed:** live Monero and NFT settlement; production dataset/SLOs and pool contention benchmarks; audit scheduling and very-large-history startup cost; normalized durable real-deposit/withdrawal/compensation states; account recovery/second factor; external security/accounting review; coordinated node/financial/treasury backup; deployment TLS drills, PITR and failover rehearsal; funded exposure/fee/loss policies; legal/operations sign-off. The scalable database choice does not turn the existing sandbox into a production custodian. + +### Reviewed Monero pending-credit operations (sandbox only) + +`npm run custody:db -- ACTION` now supports these explicit, non-HTTP actions for the pending-credit ledger stage: + +- `deposit-prepare-credit WALLET_FINGERPRINT OBSERVATION_ID` emits the exact review subject for an eligible, currently observed output. +- `deposit-stage-credit APPROVAL_JSON_FILE` verifies the allow-listed reviewer signature and records the amount in a non-spendable pending liability. +- `deposit-prepare-release CREDIT_UUID` emits the current output and unresolved-hold snapshot. +- `deposit-release APPROVAL_JSON_FILE` moves the matching liability to `available` after a distinct reviewer signature. +- `deposit-reconcile-holds WALLET_FINGERPRINT` records unseen/changed/reappeared observations as append-only holds. +- `deposit-prepare-resolve-hold CREDIT_UUID HOLD_UUID` and `deposit-resolve-hold APPROVAL_JSON_FILE` resolve a hold only after a fresh eligible observation and a new reviewer signature. + +The operator must separately provision the coordinator role with action `grant-monero-credit-runtime ROLE`; database migration remains explicit. The review policy comes from `WIKIDECK_MONERO_DEPOSIT_REVIEW_POLICY_FILE`, an owner-only JSON file containing only approved reviewer owner public-key hashes, a confirmation floor (at least 10 in this sandbox policy), and maximum observer age. Approval JSON files are bounded, absolute-path, regular files opened without following symlinks, and owner-only on POSIX. **These review-file commands currently refuse Windows** because the implementation cannot verify Windows ACLs; run them only in a secured POSIX environment. No reviewer private key is loaded by the application: snapshots are emitted for external signing and signed approval files are then submitted back to the CLI. Two-argument commands parse both identifiers explicitly. These CLI actions do not enable scanning, an HTTP endpoint, an unattended worker, or live deposits. + +The added `tests/custody-db-args.test.ts` verifies two-argument IDs are preserved in the proper positions and rejects missing, empty, unknown, or extra arguments. `tests/monero-deposit-review-config.test.ts` checks strict policy parsing, approval-file bounds, POSIX owner-only permissions, no-follow/symlink rejection, and fail-closed Windows behavior. Full offline validation passed **194/194**; PostgreSQL integration passed **36/36** after the operator workflow changes. These tests verify offline command/config boundaries only; no operator keys or live RPC were used. diff --git a/docs/production-plan.md b/docs/production-plan.md index f016399..71bb1a2 100755 --- a/docs/production-plan.md +++ b/docs/production-plan.md @@ -30,6 +30,8 @@ Status: active engineering plan; **not launch or payment authorization**. Update **Reviewed pending-deposit ledger stage (2026-10-21):** schema v5 adds immutable per-output credit records and append-only observation-event holds; schema v6 adds append-only reviewer-signed release and hold-resolution records; v7 permits one signed release to resolve multiple holds while retaining one-time hold identity. A separate, non-HTTP coordinator verifies registered beneficiary allocation, observation freshness/unlock/confirmation/double-spend state, and an allow-listed P-256 reviewer signature. It can first stage an output into a non-spendable `deposit-pending` liability, then separately release that amount into `available` under another signed review bound to the current output and every unresolved hold. Reorg/disappearance/re-inclusion events create scoped holds; new purchases and withdrawals for that beneficiary are blocked while any remain unresolved. Holds can be resolved only after the output is again observed, unlocked, sufficiently confirmed, and signed off; journals are never reversed automatically. The dedicated coordinator DB role is explicitly provisioned using `grant-monero-credit-runtime` and remains separate from observer and custody-runtime roles. This remains isolated sandbox ledger machinery, not proof of treasury backing: no API/startup integration, reviewer key provisioning, continuous scan/hold worker, production deposit activation, withdrawal signer/worker, or live sale settlement exists. Validation: test image build passed; offline suite **190/190 passed**; disposable PostgreSQL integration suite **36/36 passed**. Tests cover schema upgrades, pending-credit review, concurrent duplicate release/reorg resolution, scoped spending holds, and cleanup of the disposable fixture. No external network or funds used. +**Offline deposit-review operator commands (2026-10-21):** `custody-db` now has explicit prepare/stage/release/reorg-hold/review-resolution actions, with exact argument-count checks and idempotent coordinator calls. They consume an owner-protected review-policy file and bounded signed-approval files; reviewer private keys are never loaded by the app. POSIX owner-only permissions and no-follow opens are required; these file operations refuse Windows until ACL verification is implemented. The existing `IS_MAINNET` guard keeps the CLI sandbox-only. This is an operator rehearsal interface, not a public deposit endpoint or live payment activation. Added argument-parser and protected-file tests; full offline suite passed **194/194** and PostgreSQL integration **36/36**. + ## 1A. MVP release boundary — proposed safe first production-hosted release The apartment/single-operator constraint changes the rollout and availability claims, not the safety evidence required to hold customer funds or valuable assets. Recommended MVP: **a public, clearly labeled non-monetary beta on the existing testnet**, with real XMR completely disabled, no custodial balances/deposits/withdrawals, and marketplace checkout/delivery disabled for valuable assets. Keep mining, browsing and wallet use only if they are explicitly described as experimental and users accept that data/ownership may be lost. This would be a production-hosted beta, **not mainnet production**, a custody MVP, or an independently secured chain. diff --git a/scripts/custody-db.ts b/scripts/custody-db.ts index 94b69f6..d371d0d 100755 --- a/scripts/custody-db.ts +++ b/scripts/custody-db.ts @@ -7,11 +7,21 @@ import { importSqliteCustody } from '../server/market/custody-import.ts'; import { PostgresCustody } from '../server/market/postgres-custody.ts'; import { IS_MAINNET } from '../shared/network.ts'; import { resolveCustodyIncident } from '../server/market/custody-incident.ts'; +import { loadMoneroDepositReviewApproval, loadMoneroDepositReviewPolicy } from '../server/market/monero-deposit-review-config.ts'; +import { parseCustodyDbArguments } from '../server/market/custody-db-args.ts'; +import { prepareDepositCreditReview, postReviewedDepositPendingCredit, prepareDepositCreditReleaseReview, + releaseReviewedDepositCredit, reconcileDepositCreditReorgHolds, prepareDepositReorgResolution, + resolveReleasedDepositReorgHold, type DepositCreditApproval, type DepositCreditReleaseApproval, + type DepositReorgResolutionApproval } from '../server/market/monero-deposit-credit.ts'; // Explicit operator task, never invoked by node startup. No passwords or database URLs printed. if (IS_MAINNET) throw new Error('Only sandbox financial schema operations are implemented'); -const [action, argument] = process.argv.slice(2); -if (!['migrate', 'grant-runtime', 'grant-monero-credit-runtime', 'import-sqlite', 'audit', 'resolve-integrity'].includes(action)) throw new Error('Expected migrate, grant-runtime ROLE, grant-monero-credit-runtime ROLE, import-sqlite DATA_DIR, audit, or resolve-integrity EVIDENCE_UUID'); +const commandArgs = process.argv.slice(2); +const depositActions = ['deposit-prepare-credit', 'deposit-stage-credit', 'deposit-prepare-release', 'deposit-release', + 'deposit-reconcile-holds', 'deposit-prepare-resolve-hold', 'deposit-resolve-hold']; +const custodyActions = ['migrate', 'grant-runtime', 'grant-monero-credit-runtime', 'import-sqlite', 'audit', 'resolve-integrity']; +const { action, argument, extraArgument } = parseCustodyDbArguments(commandArgs); +if (!custodyActions.includes(action) && !depositActions.includes(action)) throw new Error('Unsupported custody operation'); try { const config = await postgresConfig(); if (action === 'audit') { @@ -27,6 +37,43 @@ try { console.log('Separate reviewed pending-credit coordinator grants applied; no credentials printed and no live deposits enabled.'); } if (action === 'resolve-integrity') console.log(JSON.stringify(await resolveCustodyIncident(pool, argument ?? ''))); + if (depositActions.includes(action)) { + const policy = await loadMoneroDepositReviewPolicy(); + if (action === 'deposit-prepare-credit') { + if (!argument || !extraArgument) throw new Error('Expected deposit-prepare-credit WALLET_FINGERPRINT OBSERVATION_ID'); + console.log(JSON.stringify(await prepareDepositCreditReview(pool, argument, extraArgument, policy))); + } + if (action === 'deposit-stage-credit') { + if (!argument || extraArgument) throw new Error('Expected deposit-stage-credit APPROVAL_JSON_FILE'); + const approval = await loadMoneroDepositReviewApproval(argument); + // The coordinator validates the exact approval schema/signature before any write. + console.log(JSON.stringify(await postReviewedDepositPendingCredit(pool, approval as DepositCreditApproval, policy))); + } + if (action === 'deposit-prepare-release') { + if (!argument || extraArgument) throw new Error('Expected deposit-prepare-release CREDIT_UUID'); + console.log(JSON.stringify(await prepareDepositCreditReleaseReview(pool, argument, policy))); + } + if (action === 'deposit-release') { + if (!argument || extraArgument) throw new Error('Expected deposit-release APPROVAL_JSON_FILE'); + const approval = await loadMoneroDepositReviewApproval(argument); + // The coordinator validates the exact approval schema/signature before any write. + console.log(JSON.stringify(await releaseReviewedDepositCredit(pool, approval as DepositCreditReleaseApproval, policy))); + } + if (action === 'deposit-reconcile-holds') { + if (!argument || extraArgument) throw new Error('Expected deposit-reconcile-holds WALLET_FINGERPRINT'); + console.log(JSON.stringify({ holdsCreated: await reconcileDepositCreditReorgHolds(pool, argument) })); + } + if (action === 'deposit-prepare-resolve-hold') { + if (!argument || !extraArgument) throw new Error('Expected deposit-prepare-resolve-hold CREDIT_UUID HOLD_UUID'); + console.log(JSON.stringify(await prepareDepositReorgResolution(pool, argument, extraArgument, policy))); + } + if (action === 'deposit-resolve-hold') { + if (!argument || extraArgument) throw new Error('Expected deposit-resolve-hold APPROVAL_JSON_FILE'); + const approval = await loadMoneroDepositReviewApproval(argument); + // The coordinator validates the exact approval schema/signature before any write. + console.log(JSON.stringify(await resolveReleasedDepositReorgHold(pool, approval as DepositReorgResolutionApproval, policy))); + } + } if (action === 'import-sqlite') { if (!argument) throw new Error('Stopped source node DATA_DIR required'); const directory = resolve(argument); diff --git a/server/market/custody-db-args.ts b/server/market/custody-db-args.ts new file mode 100755 index 0000000..5a4c852 --- /dev/null +++ b/server/market/custody-db-args.ts @@ -0,0 +1,30 @@ +export const CUSTODY_DB_ACTION_ARGUMENT_COUNTS = { + migrate: 0, + 'grant-runtime': 1, + 'grant-monero-credit-runtime': 1, + 'import-sqlite': 1, + audit: 0, + 'resolve-integrity': 1, + 'deposit-prepare-credit': 2, + 'deposit-stage-credit': 1, + 'deposit-prepare-release': 1, + 'deposit-release': 1, + 'deposit-reconcile-holds': 1, + 'deposit-prepare-resolve-hold': 2, + 'deposit-resolve-hold': 1, +} as const; + +export type CustodyDbAction = keyof typeof CUSTODY_DB_ACTION_ARGUMENT_COUNTS; +export type CustodyDbArguments = { action: CustodyDbAction; argument?: string; extraArgument?: string }; + +export function parseCustodyDbArguments(args: readonly string[]): CustodyDbArguments { + const [action, ...values] = args; + if (!action || !Object.hasOwn(CUSTODY_DB_ACTION_ARGUMENT_COUNTS, action)) { + throw new Error(`Expected one of: ${Object.keys(CUSTODY_DB_ACTION_ARGUMENT_COUNTS).join(', ')}`); + } + const count = CUSTODY_DB_ACTION_ARGUMENT_COUNTS[action as CustodyDbAction]; + if (values.length !== count || values.some(value => value.length === 0)) { + throw new Error(`Invalid argument count for custody operation: ${action}`); + } + return { action: action as CustodyDbAction, argument: values[0], extraArgument: values[1] }; +} diff --git a/server/market/monero-deposit-review-config.ts b/server/market/monero-deposit-review-config.ts new file mode 100755 index 0000000..5072446 --- /dev/null +++ b/server/market/monero-deposit-review-config.ts @@ -0,0 +1,58 @@ +import { constants } from 'node:fs'; +import { open } from 'node:fs/promises'; +import { isAbsolute } from 'node:path'; +import { z } from 'zod'; +import type { DepositCreditPolicy } from './monero-deposit-credit.ts'; + +const MAX_REVIEW_CONFIG_BYTES = 4096; +const MAX_APPROVAL_BYTES = 64 * 1024; +const reviewerPolicySchema = z.object({ + approvedReviewerOwners: z.array(z.string().regex(/^[a-f0-9]{64}$/)).min(1).max(8), + minimumConfirmations: z.number().int().min(10).max(100_000), + maximumObservationAgeMs: z.number().int().min(10_000).max(15 * 60_000), +}).strict().superRefine((value, context) => { + if (new Set(value.approvedReviewerOwners).size !== value.approvedReviewerOwners.length) { + context.addIssue({ code: 'custom', message: 'Reviewer owner allowlist must not contain duplicates' }); + } +}); + +async function readPrivateJson(path: string, maximumBytes: number): Promise { + if (process.platform === 'win32') throw new Error('Owner-only ACL verification is unavailable on Windows'); + if (!isAbsolute(path)) throw new Error('Review files require an absolute path'); + const file = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW); + try { + const info = await file.stat(); + if (!info.isFile() || info.size < 1 || info.size > maximumBytes) { + throw new Error('Review file must be a bounded regular file'); + } + if ((info.mode & 0o077) !== 0) { + throw new Error('Review file permissions must be owner-only'); + } + const chunks: Buffer[] = []; + let total = 0, position = 0; + while (total <= maximumBytes) { + const chunk = Buffer.allocUnsafe(Math.min(4096, maximumBytes + 1 - total)); + const { bytesRead } = await file.read(chunk, 0, chunk.length, position); + if (bytesRead === 0) break; + total += bytesRead; position += bytesRead; + if (total > maximumBytes) throw new Error('Review file exceeds byte limit'); + chunks.push(chunk.subarray(0, bytesRead)); + } + const text = new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks)); + return JSON.parse(text) as unknown; + } finally { await file.close(); } +} + +/** Public keys/policy only; no reviewer private key is loaded by the application. */ +export async function loadMoneroDepositReviewPolicy(env: NodeJS.ProcessEnv = process.env): Promise { + const path = env.WIKIDECK_MONERO_DEPOSIT_REVIEW_POLICY_FILE; + if (!path) throw new Error('Monero deposit review policy file is required'); + try { return reviewerPolicySchema.parse(await readPrivateJson(path, MAX_REVIEW_CONFIG_BYTES)); } + catch { throw new Error('Invalid or inaccessible protected Monero deposit review policy'); } +} + +/** Signed approvals are bearer authorizations, so read only owner-protected regular files. */ +export async function loadMoneroDepositReviewApproval(path: string): Promise { + try { return await readPrivateJson(path, MAX_APPROVAL_BYTES); } + catch { throw new Error('Invalid or inaccessible protected Monero deposit review approval'); } +} diff --git a/tests/custody-db-args.test.ts b/tests/custody-db-args.test.ts new file mode 100755 index 0000000..36f1922 --- /dev/null +++ b/tests/custody-db-args.test.ts @@ -0,0 +1,19 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { parseCustodyDbArguments } from '../server/market/custody-db-args.ts'; + +test('custody database CLI parses two-argument deposit operations without shifting arguments', () => { + assert.deepEqual(parseCustodyDbArguments(['deposit-prepare-credit', 'a'.repeat(64), `${'b'.repeat(64)}:${'c'.repeat(64)}`]), { + action: 'deposit-prepare-credit', argument: 'a'.repeat(64), extraArgument: `${'b'.repeat(64)}:${'c'.repeat(64)}`, + }); + assert.deepEqual(parseCustodyDbArguments(['deposit-prepare-resolve-hold', 'credit-id', 'hold-id']), { + action: 'deposit-prepare-resolve-hold', argument: 'credit-id', extraArgument: 'hold-id', + }); +}); + +test('custody database CLI rejects unknown, missing, empty, and excess arguments', () => { + for (const args of [[], ['unknown'], ['audit', 'extra'], ['deposit-prepare-credit', 'wallet'], + ['deposit-prepare-credit', 'wallet', 'observation', 'extra'], ['deposit-release', '']]) { + assert.throws(() => parseCustodyDbArguments(args)); + } +}); diff --git a/tests/monero-deposit-review-config.test.ts b/tests/monero-deposit-review-config.test.ts new file mode 100755 index 0000000..e38368f --- /dev/null +++ b/tests/monero-deposit-review-config.test.ts @@ -0,0 +1,58 @@ +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { chmod, mkdtemp, rm, symlink, writeFile } from 'node:fs/promises'; +import { tmpdir } from 'node:os'; +import { join } from 'node:path'; +import { loadMoneroDepositReviewApproval, loadMoneroDepositReviewPolicy } from '../server/market/monero-deposit-review-config.ts'; + +const owner = 'a'.repeat(64); + +async function privateFile(path: string, content: string) { + await writeFile(path, content, { mode: 0o600 }); + await chmod(path, 0o600); +} + +test('deposit review policy requires an owner-only protected file and strict bounds', async t => { + if (process.platform === 'win32') { + await assert.rejects(loadMoneroDepositReviewPolicy({ WIKIDECK_MONERO_DEPOSIT_REVIEW_POLICY_FILE: 'C:\\private\\policy.json' }), /Invalid or inaccessible/); + return; + } + const directory = await mkdtemp(join(tmpdir(), 'wikideck-deposit-review-')); + t.after(() => rm(directory, { recursive: true, force: true })); + const policyPath = join(directory, 'policy.json'); + const env = { WIKIDECK_MONERO_DEPOSIT_REVIEW_POLICY_FILE: policyPath }; + const valid = { approvedReviewerOwners: [owner], minimumConfirmations: 10, maximumObservationAgeMs: 120_000 }; + await assert.rejects(loadMoneroDepositReviewPolicy({}), /required/); + await privateFile(policyPath, JSON.stringify(valid)); + assert.deepEqual(await loadMoneroDepositReviewPolicy(env), valid); + + await privateFile(policyPath, JSON.stringify({ ...valid, unexpected: true })); + await assert.rejects(loadMoneroDepositReviewPolicy(env), /Invalid or inaccessible/); + await privateFile(policyPath, JSON.stringify({ ...valid, minimumConfirmations: 2 })); + await assert.rejects(loadMoneroDepositReviewPolicy(env), /Invalid or inaccessible/); + + await privateFile(policyPath, JSON.stringify(valid)); await chmod(policyPath, 0o644); + await assert.rejects(loadMoneroDepositReviewPolicy(env), /Invalid or inaccessible/); + await rm(policyPath); + await symlink(join(directory, 'missing-target.json'), policyPath); + await assert.rejects(loadMoneroDepositReviewPolicy(env), /Invalid or inaccessible/); +}); + +test('deposit approval file loader requires an absolute, bounded, private regular file', async t => { + if (process.platform === 'win32') { + await assert.rejects(loadMoneroDepositReviewApproval('C:\\private\\approval.json'), /Invalid or inaccessible/); + return; + } + const directory = await mkdtemp(join(tmpdir(), 'wikideck-deposit-approval-')); + t.after(() => rm(directory, { recursive: true, force: true })); + const approvalPath = join(directory, 'approval.json'); + const approval = { version: 1, signature: 'signed-review-fixture' }; + await assert.rejects(loadMoneroDepositReviewApproval('relative-approval.json'), /protected Monero deposit review approval/); + await privateFile(approvalPath, JSON.stringify(approval)); + assert.deepEqual(await loadMoneroDepositReviewApproval(approvalPath), approval); + + await privateFile(approvalPath, 'x'.repeat(64 * 1024 + 1)); + await assert.rejects(loadMoneroDepositReviewApproval(approvalPath), /protected Monero deposit review approval/); + await privateFile(approvalPath, '{malformed'); + await assert.rejects(loadMoneroDepositReviewApproval(approvalPath), /protected Monero deposit review approval/); +});