---
last_verified: 2026-05-30
verified_version: 0.1.34
owner: devops
freshness_days: 30
---

# Runbook — pvtcoms

> pvtcoms is serverless — there is no central service to operate. This runbook covers the build/release process, the
> (v2) optional oblivious relays, and incident response.

## Component health

| Component | Check | Expected |
|---|---|---|
| Rust core | `cargo test` | `test result: ok` |
| `arti` Tor bootstrap | client log / status API | circuits established within ~30 s |
| (v2) oblivious mailbox relay | health endpoint | reachable; stores opaque blobs only |
| (v2) iOS APNs notification relay | health endpoint | forwards encrypted envelopes; correlates nothing |

## Common operations

### Build & release
```bash
cargo test && cargo build --release
python3 scripts/docs/version_bump.py minor   # bump + sync versions
```

### View logs (must be secret-free)
```bash
RUST_LOG=info ./target/release/<bin>   # NEVER log plaintext/keys/tokens/IPs
```

## Incident response

### Severity levels
| Level | Definition | Response |
|---|---|---|
| P1 — Critical | Crypto/secret leak, key compromise, deanonymization vector | Immediate; rotate, disclose, patch |
| P2 — High | Message loss / ratchet desync, delivery broken | < 4 hours |
| P3 — Medium | Non-security functional bug | < 24 hours |
| P4 — Low | Cosmetic | Next milestone |

### Checklist
1. **Assess** — scope; is any secret/plaintext exposed? Is it a deanonymization vector?
2. **Mitigate** — patch/rotate/advise users; never weaken the threat model to "fix" UX.
3. **Communicate** — security advisory (coordinated disclosure).
4. **Resolve** — root-cause fix + regression test mapped to the threat model.
5. **Document** — incident note + ADR if it changes a decision.

## Troubleshooting

| Symptom | Check | Fix |
|---|---|---|
| Messages not arriving | recipient online? pull ran? token rotated? | recipient opens app to pull; verify token derivation |
| "Connecting over Tor…" stuck | `arti` bootstrap; network/censorship | retry; (v2) bridges/pluggable transports |
| Contact shows "unverified" | SAS not done | complete out-of-band SAS verification |