Contracts: insigzctl & the Break-Glass Token

The CLI command contracts and the security-critical break-glass token, made concrete (deferred in 51/62). The provisioning orchestrator (51) and control plane (62) execute against these.

insigzctl command contracts

A CLI + library used by the provisioning orchestrator and ops. Every command is idempotent and writes an audit record.

insigzctl migrate    --tenant=<slug> --to=latest|<version>
    → runs node-pg-migrate to target; exits 0 if already at target (idempotent). Forward-only.

insigzctl seed       --tenant=<slug> --blueprint=<maritime|energy|sanctions|research|academic>
    → upserts the connector catalog, default surfaces, ontology seed; safe to re-run.

insigzctl tenant     register   --slug=<s> --owner=<email> --plan=<tier> --region=<r>
                     suspend     --slug=<s> --reason=<text>
                     reinstate   --slug=<s>
                     decommission --slug=<s> --confirm=<slug>      (typed confirm; 30-day snapshot then destroy)
    → register is idempotent (creates-or-updates the control-plane tenant row).

insigzctl secret     rotate --slug=<s> --kind=db|jwt|provenance|claude
    → writes a new Secret Manager version + triggers a rolling Cloud Run restart; keeps prior version for the dual-key window.

insigzctl invite     --tenant=<s> --email=<e> --role=owner|admin|analyst|viewer

insigzctl healthz    --slug=<s>      → 0 if /healthz returns 200

Idempotency / rollback contract (per provisioning step — 51)

• Each step is safe to re-run: Terraform apply reconciles to desired state; insigzctl ops are upsert/no-op when already done.
• A failed step leaves no half-created resource the next run can't reconcile (the Error-409 cooldown demo is exactly this: retry succeeds).
• Rollback = terraform destroy of the partial module for a never-completed tenant; for a live tenant, forward-fix only (no destructive auto-rollback).
• The orchestrator (Cloud Workflows, decided) persists each step's status so a crash resumes, not restarts.

Break-glass token contract (security-critical — 62, 40, product §17)

When an operator enters a tenant's app to assist, the control plane mints a scoped token; the tenant app validates it before granting access.

// JWT, signed by the CONTROL PLANE's key (a key the tenant app trusts via JWKS)
{
  "iss": "control.insigz.com",
  "aud": "tenant:<slug>",              // bound to ONE tenant; rejected elsewhere
  "sub": "operator:<id>",              // the human operator
  "purpose": "break_glass",
  "reason": "investigating SUP-8821 reports export timeout",   // required, audited
  "scope": "read",                     // read-only (no writes/exports) for v0
  "exp": <iat + 15|30|60 min>,         // time-boxed; short
  "jti": "<uuid>",                     // single-use / revocable
  "iat": <…>
}

Tenant-app validation (all must pass): signature via the control-plane JWKS; aud === this tenant; purpose === break_glass; exp not past; jti not in the revocation set (Redis). The verified token maps to the operator-in-tenant principal (41) — a third principal type that carries no tenant role, is read-only, and is hard-denied write/export/publish in the policy engine; it can never satisfy the normal-user path (60 dual-issuer). On accept, the tenant app:

• mounts a read-only, banner-marked session ("OPERATOR BREAK-GLASS — <operator> — reason — expires <t>");
• writes an audit row on the tenant side too (so the customer sees who entered and why);
• auto-expires at exp and refuses writes/exports.

The control plane writes the matching flagged audit entry at mint time (product §17). Two-sided audit = the customer and the operator both have the record.

Gaps to close

• Decide whether break-glass ever allows scoped write (incident remediation) — v0 is read-only.
• Confirm the JWKS distribution (control plane publishes; tenants pin) and the revocation propagation latency.
• Define the per-step status schema the orchestrator persists.