Threat model

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

Date: 2026-08-29 Version modeled: 0.1.0-beta.1

Executive summary

PPOps deliberately removes spending authority from the reconciler, so its highest risks are confidentiality and payment-integrity failures rather than direct fund withdrawal: theft of the viewing or merchant-signing keys, false or withheld state from RPC/PPOI dependencies, compromise of the large pinned RAILGUN dependency graph, and exposure or substitution of recovery bundles. The Bearer API is acceptable only under the assumed single-merchant local/private deployment; direct Internet exposure would materially raise authentication and denial-of-service risk. Evidence anchors: src/railgun/engine.ts (RailgunViewOnlyEngine.start), src/runtime.ts (PPOpsRuntime.create) and src/api/app.ts (createApiApp).

Scope and assumptions

In scope:

• Production runtime under src/, including the Hono API, CLI, configuration, SQLite repositories, EIP-712 descriptor, view-only RAILGUN engine/scanner, reconciliation, webhook delivery, runtime lock and recovery commands.
• Deployment controls in Dockerfile and docker-compose.yml.
• Build and dependency boundary in package.json, package-lock.json and .github/workflows/ci.yml.
• Tests and gate scripts only as evidence; they are not modeled as production entry points.
• The independently executed tools/ppops-payer harness at the shared repository, supply-chain and signed-request boundary only. Its payer host and spending wallet remain outside the merchant-runtime trust domain.

Out of scope:

• Correctness of RAILGUN contracts, circuits, cryptography, PPOI protocol and upstream nodes beyond how PPOps consumes them.
• A globally observing timing adversary, payer endpoint compromise, voluntary merchant disclosure, post-payment spending behavior and operating-system or hypervisor compromise.
• Payer mnemonic custody, public self-signer custody and operating-system state on the separate payer host.
• Hardhat and the files under patches/; they reproduce a controlled upstream gate and are not runtime dependencies.

Assumptions used because no correction was received after the context check-in:

• One merchant controls each instance; there is no tenant boundary inside PPOps.
• The API binds to loopback, or Docker publishes it only on host loopback. It is not directly exposed to the Internet.
• The merchant operator controls configuration and secret-file paths. RPC/PPOI services and blockchain inputs remain externally trustable only to the degree documented below.
• The merchant backend can protect the single administrative Bearer token and verify webhook replay windows/event IDs.
• Host filesystem access controls and disk/backup protection exist outside the application; PPOps SQLite is not application-level encrypted.

Open questions that would materially change risk ranking:

• Will any pilot put PPOps behind a public reverse proxy, share an instance between merchants, or accept requests from untrusted browser clients?
• Will the pilot use mainnet/value-bearing funds, and what payment volume and maximum tolerable confirmation delay apply?
• Are host disks and off-host backups encrypted and access-audited, and can the merchant signer be moved to a KMS/HSM after beta?

If the first answer is yes, TM-002 and TM-008 become high priority and this beta profile must add proxy authentication/TLS, per-client authorization, rate limits and abuse monitoring before exposure.

System model

Primary components

• CLI and daemon: parses a fixed command/option set, loads configuration and secrets, acquires a single-process lock, starts the engine and Hono server, and schedules scans. Evidence: src/cli.ts (main, serve, init) and src/runtime.ts (PPOpsRuntime.create).
• Authenticated API: creates and reads intents, exposes settlement/event state and verifies descriptors. It uses secure headers, a 64 KiB body limit, Zod schemas and constant-time Bearer-token digest comparison. Evidence: src/api/app.ts (createApiApp) and src/security/auth.ts (bearerTokenMatches).
• Intent and descriptor engine: creates random references/nonces, signs EIP-712 descriptors with an independent merchant identity key and verifies them against an expected signer plus instance policy. Evidence: src/intents/service.ts (IntentService.create, verifyDescriptor) and src/security/descriptor.ts.
• View-only RAILGUN engine/scanner: imports a shareable viewing key, rejects full-wallet/signing access, synchronizes TXOs and reduces strict encrypted memos to opaque references. Evidence: src/railgun/engine.ts (RailgunViewOnlyEngine) and src/railgun/scanner.ts (RailgunScanner).
• Reconciler and stores: persists commercial metadata/projections/outbox in SQLite and encrypted RAILGUN state in LevelDOWN. It credits only matched, finalized and PPOI-spendable settlements. Evidence: src/db/database.ts, src/reconciliation/service.ts and src/reconciliation/projection.ts.
• Webhook worker: sends persisted event JSON to one operator-configured URL over HTTPS with HMAC, timestamp and event ID, disabling redirects. Evidence: src/events/webhook.ts (WebhookDeliveryService).
• Recovery tooling: creates offline checksum-inventoried backups, optionally containing secret values, and restores only after profile/fingerprint checks. Evidence: src/backup.ts (createBackup, restoreBackup).

Data flows and trust boundaries

• Merchant backend → API: commercial reference, atomic amount, expiry and Bearer credential cross local HTTP. All operational routes require one Bearer token; request bodies are limited and Zod-validated. PPOps has bounded in-memory per-source limits, but no application TLS, per-client roles or distributed rate limiter. Evidence: src/api/app.ts and src/security/rate-limit.ts.
• API → intent engine → SQLite: validated commercial metadata crosses an in-process boundary and is written through parameterized SQLite statements. File/directory modes restrict other local users, but commercial metadata is plaintext at the application layer. Evidence: src/intents/service.ts and src/db/database.ts (insertIntent).
• Private files → runtime: configuration, wallet state, viewing capability, API token, merchant signing key, RAILGUN DB key and optional webhook key cross the local filesystem boundary. They must be bounded regular files owned by the current user without group/other access on POSIX. PPOps rejects symlinks, opens with O_NOFOLLOW where available and rechecks the opened descriptor identity before parsing; secret values are validated and never API-returned. Evidence: src/security/private-file.ts, src/security/secrets.ts and src/runtime.ts.
• PPOps → payer: an EIP-712 descriptor and encrypted-memo reference leave the merchant host through the public checkout/request endpoint or a local request file. Authenticity depends on the payer obtaining the expected signer independently. The reference payer verifies every duplicated request field, serializes wallet access with a local runtime lock and reserves an intent in an owner-only write-ahead submission journal before broadcasting. Gate A records a precomputed signed transaction hash; Gate B records the bounded fee identity, payer, exact encrypted-submission quote fingerprint and nullifiers before Waku submission. After proof generation, a configured RPC majority must simulate the exact populated calldata before any encrypted-request or journal effect. Before simulation, a read-only admission check rejects inputs held by another active journal record; the later reservation rechecks the same policy. A quote may rotate only when Broadcaster, token and fee rate remain identical. A Waku-returned hash remains untrusted metadata until the full payer wallet derives the canonical transaction hash from those nullifiers. Recovery precedes every explicit ambiguity retry; a retry must preserve the signed request, payer and complete nullifier set, exclude all previously attempted Broadcaster identities and remain within a three-retry cap. A different intent cannot reserve any unresolved nullifier. Evidence: src/security/descriptor.ts, tools/ppops-payer/src/request.ts, tools/ppops-payer/src/security/runtime-lock.ts and tools/ppops-payer/src/security/submission-journal.ts.
• Payer → RAILGUN/blockchain: the payer submits the private transfer. Public chain artifacts are outside PPOps control; the privacy gate demonstrates that the plaintext reference/memo is absent from the V2 commitment leaf. Evidence: scripts/encrypted-memo-leaf-gate.ts, artifacts/privacy-report.json and tools/ppops-payer/src/railgun/broadcaster-transfer.ts. Broadcaster mode also crosses operator-pinned fee-signer, DNS/Waku and selected-Broadcaster trust boundaries; it does not claim network-layer anonymity or relay availability. An earlier value-bearing lineage reached two selected identities without a usable response and remains reserved. A later isolated lineage resolved a canonical transaction and completed Gate B on its first submission; that success does not remove these metadata or availability dependencies.
• RAILGUN runtime ↔ RPC/PPOI: encrypted chain history, receipts, block tags, PPOI statuses and timing cross outbound HTTPS/JSON-RPC and SDK-specific protocols. PPOps validates configured chain/deployment identity and fails payment credit closed unless finality and spendability agree. Receipt, block and finalized-height reads use a majority quorum across configured RPCs; PPOps still does not verify cryptographic RPC proofs and inherits PPOI trust. Evidence: src/railgun/engine.ts, src/railgun/scanner.ts and src/railgun/rpc-quorum.ts.
• Reconciler → SQLite outbox → merchant webhook: payment state crosses local SQLite and then outbound HTTPS. HMAC authenticates integrity/origin but does not hide payload from the webhook receiver; at-least-once delivery requires receiver-side timestamp and event-ID dedupe. Evidence: src/events/webhook.ts and src/db/database.ts (outbox_events).
• Operator → CLI/config/backup: trusted operator arguments and JSON select local paths, endpoints and recovery targets. Schemas, non-overlapping path checks, runtime locking, no-overwrite defaults, path inventory and move-aside restore reduce accidents; a malicious operator already controls the instance. Evidence: src/config.ts, src/cli.ts, src/security/runtime-lock.ts and src/backup.ts.
• Developers/registry → build: npm packages, GitHub Actions and the Docker base image cross the software-supply-chain boundary. Versions are locked and CI is read-only for verification; Actions and the base image are immutable pinned, high/critical advisories fail CI and a CycloneDX SBOM is retained. The pinned RAILGUN tree still carries moderate/low advisories and a large legacy surface. Evidence: package-lock.json, .github/workflows/ci.yml, Dockerfile and docs/OPERATIONAL-PROFILE.md.

Diagram

flowchart LR
  subgraph PayerZone
    Payer["Payer wallet"]
  end
  subgraph MerchantHost
    Backend["Merchant backend"]
    API["Authenticated API"]
    Core["Intent reconciler"]
    Scanner["View only scanner"]
    SQL["SQLite outbox"]
    Level["Encrypted LevelDB"]
    Secrets["Secret files"]
  end
  subgraph ExternalServices
    Chain["RAILGUN chain"]
    RPC["RPC provider"]
    POI["PPOI service"]
    Hook["Webhook receiver"]
  end
  Backend -->|Bearer HTTP| API
  API --> Core
  Secrets --> Core
  Secrets --> Scanner
  Core -->|Signed descriptor| Payer
  Payer -->|Private transfer| Chain
  Chain --> RPC
  RPC --> Scanner
  POI --> Scanner
  Scanner --> Level
  Scanner --> Core
  Core --> SQL
  SQL -->|HTTPS HMAC| Hook

Assets and security objectives

Attacker model

Capabilities

• A remote blockchain participant can send arbitrary incoming RAILGUN notes and strict-looking random PPOps memo references to the merchant receiver.
• RPC/PPOI providers can observe source IP/timing, omit or delay data, return inconsistent responses or become unavailable.
• A network attacker can target a mistakenly exposed API or webhook path; under the assumed deployment, the operational API is not directly Internet-routable.
• A local unprivileged user, malware, stolen backup recipient or compromised dependency may attempt to read files or execute within the PPOps process.
• A supply-chain attacker can target npm dependencies, mutable CI actions, downloaded RAILGUN artifacts or container bases.

Non-capabilities

• The ordinary remote attacker does not initially possess the API token, expected merchant signer, host filesystem access or operator-controlled configuration.
• PPOps never receives a RAILGUN mnemonic/spending key, so compromise of the intended process alone does not directly authorize spending.
• The model does not assume a break of EIP-712/ECDSA, RAILGUN encryption or hash primitives.
• The operator is trusted. An operator who deliberately changes keys, endpoints or binaries already controls the security outcome.

Entry points and attack surfaces

Top abuse paths

1. Steal the payment graph: compromise the merchant host or an unencrypted recovery bundle → read the shareable viewing key/LevelDB → decrypt historical receiver notes and correlate opaque references with local SQLite → disclose merchant payment history, even though spending remains impossible (TM-001, TM-006, TM-010).
2. Redirect future payments: obtain the merchant EIP-712 signing key → sign a valid-looking descriptor with an attacker receiver → exploit a payer that trusts only the recovered key and not an independently pinned merchant profile → receive future payments (TM-003).
3. Abuse an accidentally public API: discover a non-loopback deployment → steal/brute-force/recover the single Bearer token from another component → enumerate invoice-linked state or create fraudulent intents → cause metadata loss or payment confusion (TM-002).
4. Manipulate settlement availability/integrity: operate or compromise a majority of the selected RPC providers or the PPOI path → omit receipts, delay finality or feed misleading spendability state → keep legitimate orders unpaid or subvert an inherited trust boundary (TM-004, TM-009).
5. Exploit the dependency boundary: publish/compromise a transitively loaded RAILGUN/GraphQL/Web3 package or artifact path → obtain code execution in the daemon → read viewing/signing/API keys and alter SQLite events (TM-005).
6. Substitute or corrupt a backup: gain write access to recovery media → replace both files and the unauthenticated checksum manifest → restore stale or attacker-chosen state, or steal a bundle created with --include-secrets → cause privacy disclosure and operational takeover (TM-006).
7. Replay merchant events: capture a valid HMAC webhook request at or after the receiving backend → replay it to a receiver that ignores timestamp and event-ID dedupe → duplicate fulfillment even though PPOps outbox state is idempotent (TM-007).
8. Exhaust reconciliation capacity: send many decryptable notes with strict-looking unknown references or flood an exposed API with requests → force wallet decryption, RPC calls, SQLite growth or CPU/memory pressure → delay legitimate payment confirmation (TM-008).
9. Trigger a semantic false state: exploit a newly changed TXO/PPOI field, settlement-identity collision or projection regression not covered by the pinned gate → cross the paid threshold incorrectly or emit a misleading reversal/confirmation (TM-009).
10. Exploit ambiguous relay state: lose or forge a Broadcaster response after Waku submission → tempt the operator to create a fresh payment with inputs that may already be in flight → double-pay or permanently strand the local workflow. The payer instead reserves nullifiers before Waku, recovers first, permits only bounded conflicting same-nullifier variants through previously unattempted identities and then requires manual review. Before any reservation or Waku effect, the payer rejects cross-intent input overlap and a strict RPC majority must simulate the exact final populated calldata (TM-003, TM-004, TM-009).

Threat model table

Criticality calibration

• Critical: plausible compromise with no special operator mistake that either enables direct loss across deployments or silently subverts all payment decisions. Examples: a pre-auth remote-code-execution path in a publicly reachable default daemon; a dependency compromise distributed in an official image that exfiltrates all keys; accepting a RAILGUN spending key and exposing a remote spend path. No current threat is ranked critical under the local-only and no-spending-key assumptions.
• High: compromise of a central privacy/integrity asset or sustained false payment decisions requiring a realistic foothold. Examples: viewing-key exfiltration (TM-001), merchant-signer theft (TM-003), dependency code execution (TM-005), or provider manipulation/semantic false confirmation (TM-004/TM-009).
• Medium: bounded metadata, fulfillment or availability impact with existing controls or deployment-dependent prerequisites. Examples: replay at a poorly implemented webhook receiver (TM-007), note/API resource exhaustion (TM-008), local plaintext SQLite disclosure (TM-010), or API-token abuse while loopback remains enforced (TM-002).
• Low: small information or noisy operational effects with easy recovery. Examples: learning only ready/starting from health, rejected malformed descriptors, or failed unauthenticated requests that reveal no merchant data.

Focus paths for security review

Quality check

• Covered HTTP, CLI, config, secrets, wallet state, chain TXOs, RPC/PPOI, artifact paths, webhook, mainnet evidence, restore and build entry points.
• Represented every identified trust boundary in at least one threat.
• Separated production/runtime behavior from CI, Docker and gate/test code.
• Recorded the explicit non-response to the deployment check-in and marked public-exposure conclusions conditional.
• Stated open questions that can change likelihood/priority.
• Anchored existing controls and gaps to repository paths/symbols without including secret values.