Archigov · docs
  1. Docs
  2. Project

Security Model

How Archigov protects identities, secrets, records and evidence — and how to report a vulnerability.

#Design Principles

  • Least privilege by default. Every mutating API route not explicitly opened requires the platform admin capability; a new route is closed until someone opens it deliberately.
  • Segregation of duties by construction. The platform admin runs the instance and holds no governance right. Approving and deciding come only from board seats, and an author never acts on their own item.
  • Read-only integrations. Azure and Azure DevOps are read with metadata-only, read-only identities. Archigov never writes to your estate or backlog.
  • Evidence you can check. Records are hash-chained and evidence packs are signed, so tampering is detectable by a third party.

#Identity

  • Entra mode uses OpenID Connect with PKCE. The ID token's signature (via the tenant's published keys), issuer, tenant, audience, expiry and nonce are verified. Users are identified by tenant and object id, never by email.
  • Sessions are HMAC-signed cookies, HttpOnly, and Secure when APP_BASE_URL is HTTPS. The signing secret is SESSION_SECRET or a generated file in DATA_DIR/keys.
  • Local mode is for a trusted network only: it lets a caller choose their identity. Do not expose a local-mode instance to an untrusted network.
  • The Azure DevOps service hook authenticates with its own shared secret; calls without it are refused.

#Secrets

SecretWhere it livesProtections
Azure, Entra, DevOps credentialsEnvironment onlyNever stored in the database
AI provider keysEnvironment (preferred) or the databaseAES-256-GCM at rest; never returned by the API, never audited, never exported, never echoed in errors
Master secret keyARCHIGOV_SECRET_KEY or DATA_DIR/keys/secret.keyExcluded from backups and replicas
Evidence-signing private keyDATA_DIR/keys/evidence-signing.key (0600)Never leaves the instance; the public key is published
Session secretSESSION_SECRET or DATA_DIR/keys/session.secret—

Database backups and Litestream replicas therefore carry only ciphertext for stored AI keys.

#Records

  • Every governance act, setting change and sign-in writes an audit row with actor and role, chained by SHA-256. GET /api/audit/verify detects any alteration.
  • Board-session minutes are hashed into the chain when a session closes; positions on declared items are then frozen.
  • Human closures of findings keep the name and reason; a finding whose condition persists reopens.

#AI

AI is off by default, per feature. AI output is labelled ai and unverified, its citations must resolve or are discarded, and it never transitions state — a named human's audited act does. With Ollama or an endpoint in your own tenant, no content leaves your network.

#Operating Securely

  • Run with AUTH_MODE=entra behind TLS, with APP_BASE_URL set to the HTTPS URL.
  • Keep secrets in an env file or secret store; set ARCHIGOV_SECRET_KEY from that store.
  • Back up /data/keys separately and securely.
  • Restrict /api/hooks/* to Azure DevOps' egress if your network allows.
  • Rotate credentials if you suspect exposure; rotating the master key requires re-entering stored AI keys.

Note

Rate limiting on /api/auth/* and /api/hooks/*, and server-side session revocation, are on the roadmap. Until then, place the instance behind a reverse proxy or gateway that rate-limits those paths.

#Reporting a Vulnerability

Please report suspected vulnerabilities privately to hello@archigov.com with "Security" in the subject, rather than in a public issue. Include the version, the steps to reproduce and the impact you observed. You will receive an acknowledgement, and a fix will be coordinated with you before public disclosure.