Operator security

This manual targets 0.1.0-beta.3. Read the source and availability policy before installing. Historical reports retain their original scope.

This document is the onboarding security checklist. The root SECURITY.md defines the project security policy and reporting process; THREAT-MODEL.md is the detailed design analysis.

Trust domains

merchant wallet device             PPOps host                 payer host
----------------------             ----------                 ----------
receiver spending key              viewing key only           payer mnemonic
receiver seed/backups       X       API/signing/HMAC keys      spending wallet
                                     local reconciliation       submission journal

The merchant spending wallet and payer never belong on the PPOps host.

Merchant secret inventory

PPOps uses separate files for:

• RAILGUN shareable viewing key: reads the receiver’s private history;
• API token: authenticates merchant API callers;
• merchant EIP-712 signing key: signs payment descriptors;
• RAILGUN database-encryption key: protects local Wallet SDK state at rest;
• webhook HMAC key: authenticates outbound events.

Use independent random values. Keep files regular, non-symlink, owner-only (0600), excluded from Git and backups unless an explicit encrypted recovery procedure includes them.

The viewing key cannot spend, but exposure discloses private financial metadata. It cannot be revoked for an existing wallet. Treat a compromise as a privacy incident and move future receiving activity to a newly created receiver outside PPOps.

Non-negotiable rules

• Never give PPOps a seed phrase, spending key, full wallet export, or payer wallet backup.
• Never pass secrets as CLI arguments or URLs.
• Never log invoice/customer data, viewing material, memo references, or credential-bearing provider URLs.
• Never accept a descriptor signer solely because the descriptor names it.
• Never mark OBSERVED, FINALIZED, MATCHED, or a public receipt as paid.
• Never weaken finality, PPOI, matching, RPC majority, or idempotency to improve availability.
• Never retry an ambiguous payer submission blindly.
• Never fulfill a webhook before raw-body HMAC, timestamp, schema, event-ID, intent mapping, and deduplication checks.

Descriptor identity

The merchant signs each descriptor with a key independent of the RAILGUN spending key. A payer must pin the expected signer through a merchant-controlled channel outside the checkout URL. Examples include a signed website configuration, verified integration settings, or a previously pinned operator record.

API and checkout exposure

Bind to 127.0.0.1 by default. Keep Bearer-authenticated /v1 endpoints private. Expose payer checkout routes only through TLS and an explicit reverse-proxy allowlist.

Checkout IDs are high-entropy capabilities but not authentication for merchant operations. Use no-store/no-referrer headers and do not include checkout URLs in analytics, support tickets, or public evidence.

Fulfillment

Treat PPOps as a payment oracle with strict state criteria, not an authorization to spend. The merchant backend must:

1. verify HMAC over the raw body;
2. enforce a short timestamp tolerance;
3. validate event schema and header/body event-ID equality;
4. resolve the PPOps intent to its local order;
5. insert the event ID under a unique constraint;
6. fulfill and commit atomically;
7. return 2xx for already applied valid duplicates.

Operational safety

• Use three independent RPC origins when possible.
• Monitor readiness, scan age/failures, outbox pending/dead letters, memory, disk, and restarts.
• Stop and drain scans before backups or upgrades.
• Test isolated restore, including access to the separately stored secrets.
• Rotate API/webhook/signing identities deliberately and distribute a new expected signer before invalidating the old channel.
• Keep evidence metadata-minimal. Redaction after publishing is not a privacy control.

Current limitations

• The payer needs RAILGUN-compatible spending software and existing Spendable private liquidity.
• The initial shield/PPOI onboarding experience can be slow.
• Broadcaster availability and network-layer anonymity are not guaranteed by PPOps.
• PPOps has been verified with mainnet pilot tests; independent security reviews can be conducted as part of ongoing hardening.
• PPOps protects reconciliation metadata; RAILGUN provides payment privacy.

Report vulnerabilities using the private process in the root security policy.