Status: canonical security model (Phase 2, October 2026).

Suban handles market data, chain access and value-movement code. This document states the threat model, the controls that exist, and the gaps that are still open. It is deliberately conservative: a capability is not "secure" because it compiles.

Suban is currently testnet-first. No mainnet capital product should be considered safe until the gates in ROADMAP.md and the audit requirements in AUDIT-PROGRAM.md are met.

Do not open a public issue for a vulnerability that could move funds, leak keys or forge oracle data.

Use GitHub's private Security Advisories feature on the affected repository (Pi-Defi-world/Suban, Pi-Defi-world/suban-rpc, Pi-Defi-world/Suban-api, Pi-Defi-world/suban-controller). Include:

• affected repository, commit and deployment;
• reproduction steps or a proof of concept;
• impact (funds, oracle integrity, availability, data);
• whether the issue is already public.

If the advisory feature is unavailable, contact the repository maintainers through the private channel listed in the repository profile rather than a public issue. Do not test against third-party funds or accounts.

Internet ──► public read APIs (controller, API, RPC, indexer)
                  │  rate limits, validation, no writes
                  ▼
            control plane (controller admin, oracle signer, relayer)
                  │  shared secret / signing keys / isolated network
                  ▼
            Pi Horizon / Soroban RPC / Arc RPC

• Public reads and privileged operations are logically separated by authentication and must be separated by network policy in deployment.
• The controller admin key, oracle admin secret and relayer keys never belong in a frontend, public API process or container image.
• The relayer is a worker, not a public API. Its only listener is the metrics/health port.

• Control routes require CONTROLLER_ADMIN_API_KEY via x-api-key or Authorization: Bearer; comparison is constant-time; unset key returns 503, never falls open; per-IP rate limiting.
• Oracle publication is opt-in (ORACLE_PUSH_ENABLED=false by default) and requires ORACLE_CONTRACT_ID, ORACLE_ASSET*, ORACLE_ADMIN_SECRET.
• Only HEALTHY observations are published. Confidence is sent as a 0–100 integer, matching the contract.
• Every price carries schema_version, method_version, age_ms, is_fresh, source provenance and a trust snapshot.
• Per-asset circuit breakers prevent a single asset's failure from affecting another.
• SQLite persistence is fail-closed at startup if the store cannot be opened.

• mint_pusd does not trust a caller-supplied signature list. Every listed signer must be configured, unique and pass Soroban require_auth().
• Threshold, non-signer, duplicate, replay and missing-authorization cases are covered by tests.
• Arc→Stellar mint is explicitly disabled until signer authorization entries are implemented; the relayer cannot silently enable it.
• The relayer's only network listener is /metrics + /health on 9464.

• Public data routes support per-key quotas; keys are stored as SHA-256 hashes, usage is persisted per key, and exhausted keys receive 429 with Retry-After: 60.
• Admin routes require INDEXER_ADMIN_API_KEY; unset returns 503, never falls open. Admin routes are intended for a private network.
• Indexed queries read SQLite only. They never proxy live Horizon/RPC calls, so a 404 means "not indexed", not "not on chain".
• Every data response carries freshness; /health returns 503 when stale.
• Webhooks use a durable outbox, unique (subscription, event) delivery, HMAC-SHA256 signatures, a stable idempotency key and bounded exponential backoff. Secret values are omitted from list responses.
• The SQLite database contains webhook signing secrets and API-key usage; treat the file as a secret and restrict filesystem access.

• GitHub Actions in all four repositories: Rust workspace build/test, Go build/vet/test with a gated preflight package, SDK typecheck/test, service builds, secret scanning.
• Gitleaks scans the working tree as a blocking check and full history as a report-only check.
• suban-rpc pins ed25519-dalek = "=2.2.0", commits Cargo.lock and builds with --locked to prevent an unreviewed dependency graph.
• Production Node dependencies are audited on every CI run (npm audit --omit=dev --audit-level=high, pnpm audit --prod --audit-level=high), and Rust dependencies use rustsec/audit-check. Full/dev trees are reported, not silently ignored. The controller, API, SDK, indexer, relayer and escrow viewer are clean at production level; the controller was upgraded to @stellar/stellar-sdk@17.2.1 with patched axios, proxy-addr, form-data and path-to-regexp.
• Controller uses Node 22+ for better-sqlite3 prebuilt compatibility.

• Caddy/Cloudflare provide TLS at the edge; internal container traffic is HTTP and must remain on private networks.
• Incident severity, contacts and procedures: INCIDENT-RUNBOOK.md.
• Secret rotation and history purge: SECRET-ROTATION.md.
• Metrics and dashboards: OBSERVABILITY.md.

Accepted for now because Suban is testnet-first: internal HTTP between containers, single-region deployment, and log-only history scanning. These are not acceptable for mainnet capital.

1. One key, one purpose. Never reuse an oracle admin key as a relayer key.
2. Keys live in the deployment secret store or an isolated .env with strict permissions; never in git, images, CI logs or chat.
3. The controller admin secret is not an oracle signing secret and must not be distributed to API consumers.
4. Rotate on personnel change, suspected exposure or incident. Rotation is not complete until the old key is revoked and monitored.
5. Prefer hardware-backed or multisig signing for any mainnet value movement.
6. CI must never print secrets; use masked repository secrets.

Before any mainnet capital:

• Independent audit with published scope and remediation.
• All value-moving contracts in the root workspace and CI.
• Pause/stop path wired and tested.
• Authorization tests for every privileged entry point.
• Replay/idempotency tests for bridge and settlement paths.
• Upgrade/admin keys behind multisig or timelock.
• Deterministic risk formulas with test vectors (Phase 3).
• A staged rollout with caps and monitoring.

See AUDIT-PROGRAM.md for the audit scope and PRODUCTION-ROADMAP.md for the bridge production requirements.

• No secret in the diff; gitleaks passes.
• New privileged route has auth, rate limit, tests and a 503 fail-closed path when unconfigured.
• New external data source has timeout, freshness, error handling and a metric.
• New financial number has source, timestamp, freshness, confidence and method version.
• New contract entry point has authorization and replay tests.
• New dependency is pinned/locked and reviewed.
• Logs redact keys, signatures and full request bodies containing secrets.
• Docs updated in the same change as behavior.

Use INCIDENT-RUNBOOK.md. Severity definitions:

During an incident: stop the bleeding (disable push/relayer/pause), preserve evidence, rotate exposed keys, notify owners, then write a blameless postmortem with concrete follow-ups.

• ARCHITECTURE.md — trust boundaries and data flows.
• DATA-PLATFORM.md — indexed data security/freshness contract.
• SECRET-ROTATION.md — rotation and history purge.
• DEFERRED-OWNER-ACTIONS.md — owner-blocked follow-ups.
• INCIDENT-RUNBOOK.md — procedures and severity.
• AUDIT-PROGRAM.md — audit scope.
• PRODUCTION-ROADMAP.md — bridge production gates.
• OWNERSHIP.md — accountable owners.
• PLAN-EXECUTION.md — open defects and progress.