# cbb-sign — Rebuild Guide
# Cold Bore Ballistics LLC — Internal Reference
# Classification: Confidential
# Last Updated: 2026-06-12

> **Status: TARGET (pre-provisioning).** cbb-sign is not yet deployed. This is the intended from-scratch rebuild/disaster-recovery procedure; it is exercised once cbb-sign is live. It assumes no prior cbb-sign experience and assumes the reader has only basic Azure familiarity.

This guide owns **full from-scratch recovery**. It is the document a buyer's engineer (or future-you, with no memory of the build) uses to reconstruct cbb-sign without tribal knowledge. Resource facts come from `CBB_Sign_Architecture_Reference.md`; this document is the *procedure*.

---

## 0. Prerequisites

- Azure CLI (`az`) authenticated to the CBB subscription; Terraform installed.
- Access to the `cbb-infra` repo (Terraform) and the `cbb-sign` repo (app images) and the public fork repo (engine).
- Key Vault `kv-cbb-shared-prod` reachable (it holds every secret — nothing secret lives in code or state).
- The existing shared infrastructure (`services/shared/`, `services/scope-dope/`) applied — cbb-sign depends on `cae-cbb-prod`, `psql-cbb-prod`, `stcbbprod`, `crcbbprod`, `kv-cbb-shared-prod`, `snet-ca-prod`.

> If the *entire* CBB Azure footprint is gone, rebuild the shared layers first (see `Azure` infra docs + `DocuSeal_Rebuild_Guide.md`), then return here.

---

## 1. What Must Be Recovered

| Component | Recovery source | Notes |
|---|---|---|
| Container Apps (API, UI) | Terraform (`services/cbb/`) + images in ACR | Stateless — rebuilt from IaC + images |
| Engine (Engross) | `github.com/ColdBoreBallistics/engross` (public AGPL-3.0 fork) → rebuild image → ACR | Stateless container; config from KV |
| `cbb_sign` database | PostgreSQL backup/PITR on `psql-cbb-prod` | **Stateful — the audit trail.** See §4 |
| WORM certificates | `stcbbprod/cbb-sign-certs` | **Immutable — cannot be lost or altered while retention holds.** See §5 |
| Executed PDFs | OneDrive `Signed_Agreements/` | System of record for documents; independent of cbb-sign |
| Secrets | `kv-cbb-shared-prod` | Already present; nothing to recreate if KV survives |
| Entra app reg + groups | Terraform (`services/cbb/`) / Entra | Recreate via IaC; group memberships may need re-add |

The **only** truly cbb-sign-owned stateful data is the `cbb_sign` database (audit trail) and the WORM certs. Documents live in OneDrive; secrets in KV; everything else is stateless IaC.

---

## 2. Rebuild the Application Layer (stateless)

1. **Images.** Build and push (or confirm present in ACR):
   - `crcbbprod.azurecr.io/cbb-sign-api:<version>`
   - `crcbbprod.azurecr.io/cbb-sign-ui:<version>`
   - `crcbbprod.azurecr.io/engross/engross:cbb-<version>` (the Engross fork — from its public repo)
2. **Terraform.** In `cbb-infra/services/cbb/`, run `terraform plan` then `terraform apply` to recreate:
   - `ca-cbb-sign-api-prod`, `ca-cbb-sign-ui-prod` (+ env vars from KV references)
   - custom domains `sign.*`, `sign-api.*` + managed certs
   - KV Secrets User role assignments for both Container App identities
   - the Graph `Files.ReadWrite.All` grant on the API's managed identity
   - `app-cbb-sign` Entra app reg + the 3 RBAC groups
3. **DNS.** In `services/dns/`, ensure `sign`, `sign-api`, and the `asuid.*` TXT records exist (and the DocuSeal `sign` alias remains removed).

---

## 3. Recreate the WORM Container

1. In `services/scope-dope/` (which owns `stcbbprod`), ensure the `cbb-sign-certs` container exists.
2. **Immutability policy:** apply the time-based retention policy (1 yr to start) **only after legal-confirm is on record** (SPEC_audit §21.4). If recovering an existing deployment where the policy was already applied and the data survived (§5), do not re-apply.

> If certs already exist under an active immutability policy, they are intact by definition — WORM prevents their loss/alteration while retention holds. You are recreating the *container config*, not the data.

---

## 4. Recover the `cbb_sign` Database (audit trail)

The audit trail is the legal record — recover it carefully.

1. The `cbb_sign` database lives on `psql-cbb-prod` (Flexible Server). Use the server's **point-in-time restore (PITR)** or the latest automated backup to recover the database to the desired timestamp.
2. If restoring the whole server, restore to a new server and re-point cbb-sign's `DATABASE_URL` (KV `cbb-sign-database-url`) — or restore in place per Azure's PITR flow.
3. **Re-apply the append-only role grant** (`INSERT`/`SELECT` only on `audit_event`, no `UPDATE`/`DELETE`) and the immutability trigger — these are provisioning steps / Alembic migrations, so they come back with the migration run. Verify them (§6).
4. **Reconcile, if needed:** because cbb-sign is the system of record and DocuSeal's log is operational, the cbb-sign DB is authoritative. If a gap exists between the last good backup and the incident, cross-check against: (a) the WORM certificates (immutable, never lost) for completed signings, and (b) the executed PDFs in OneDrive. The certificates + OneDrive together let you confirm which signings completed even if recent DB rows were lost.

> Design property that helps here: the current-state tables can be rebuilt by replaying `audit_event`, and `audit_event` is corroborated by the immutable certs. The certs are the backstop the DB recovery leans on.

---

## 5. WORM Certificates — Why They Survive

The `cbb-sign-certs` container uses Azure immutable blob storage (time-based retention). While the retention period holds, certificates **cannot be deleted or modified** — not by an operator, not by a compromised credential, not by the application. Therefore, in any recovery scenario, the completion certificates for past signings are intact and are the trustworthy evidentiary backstop for reconstructing the audit trail (§4). This is the architectural reason cbb-sign keeps both an append-only DB *and* WORM certs.

---

## 6. Post-Rebuild Verification

1. **Login:** `https://sign.coldboreballisticsllc.com` authenticates via Entra; `/api/v1/me` returns your roles.
2. **Send a test one-off** to yourself; complete the signature; confirm:
   - executed PDF appears in OneDrive `Signed_Agreements/One-Off/` with the correct name,
   - a WORM cert is written to `cbb-sign-certs`,
   - the `request.filed` event appears in the request's audit timeline,
   - the completion notification fires.
3. **Immutability check:** as the app DB role, attempt an `UPDATE`/`DELETE` on `audit_event` — it must **fail** (grant + trigger). This is the SDLC's immutability test.
4. **Webhook:** confirm DocuSeal `completed` webhooks reach `sign-api.*` and are HMAC-verified.
5. **Engine:** confirm `esign.*` serves the engine and the in-app **offer-source link** points at the public fork (AGPL compliance — RISK-028).

---

## 7. Cutover-Specific Notes (first build vs. rebuild)

On the **first** build (not a recovery), additional one-time steps:
- Repoint the `sign` CNAME from DocuSeal to the cbb-sign UI and remove the alias from DocuSeal's custom-domain binding.
- Decommission `logic-docuseal-onedrive-prod` (+ its `azureblob` connection + failure alert) and delete `app-docuseal-sharepoint-prod`.
- Apply the WORM immutability policy only after legal-confirm.
- Enforce the "all sends via cbb-sign" policy (RISK-030).

---

## Estimated Recovery Time

| Scenario | Estimate |
|---|---|
| App layer only (Container Apps gone, DB+certs intact) | ~30–45 min (image build + `terraform apply` + smoke test) |
| Full cbb-sign rebuild incl. DB restore (shared infra intact) | ~1–2 hours (+ PITR restore time) |
| Full CBB Azure rebuild first | Add the shared-infra rebuild time (see Azure/DocuSeal rebuild guides) |

No tribal knowledge required — every step is IaC or a documented `az`/portal procedure.

---

## Document Control

| Field | Value |
|---|---|
| **Document owner** | `jschwefel@coldboreballisticsllc.com` |
| **Classification** | Confidential (`03_-_Confidential/`) |
| **Location** | `OneDrive/CBB_Corporate/03_-_Confidential/Infrastructure/CBB_Sign/CBB_Sign_Rebuild_Guide.md` |
| **Cross-references** | cbb-sign SPEC; `CBB_Sign_Architecture_Reference.md`; `CBB_Sign_Operating_Runbook.md`; `DocuSeal_Rebuild_Guide.md`; Azure infra docs |
| **Created** | 2026-06-12 |
| **Last updated** | 2026-06-12 |
| **Next full review due** | 2027-06-12 |

---

## Revision Control Block

| Rev | Date | Changed By | Reviewed By | Approved By | Summary |
|-----|------|------------|-------------|-------------|---------|
| DRAFT | 2026-06-12 | Claude Code (Opus 4.8) | — | — | Initial target-state rebuild/DR guide (pre-provisioning). Recovery inventory, app-layer rebuild, WORM container, `cbb_sign` DB restore with cert/OneDrive corroboration, immutability rationale + verification, cutover-sp