aia-website/www/integrations/nixos/README.md

Inactive SOPS/age preparation, 2026-10-30

The owner selected SOPS, age and sops-nix. This directory is a template, not a host configuration. The development flake remains unchanged. No real recipient, key, encrypted secret or server user is supplied. No module is deployed.

Official references inspected for this pass:

• SOPS documentation
• sops-nix installation and secret permissions

SOPS encrypts configuration at rest. sops-nix can supply decrypted values at runtime under /run/secrets with explicit owners and modes. This does not make browser ciphertext or publicly served documents private.

Owner setup before activation

1. Supply the actual NixOS topology, host flake, deploy user, persisted key location, backup owner, HTTPS termination and resource-service identity.
2. Pin a reviewed github:Mic92/sops-nix input in that host flake; import inputs.sops-nix.nixosModules.sops and the reviewed template. Do not add the input to the Astro development flake just to evaluate a deployment sketch.
3. The owner generates independent developer/recovery and VPS age identities in private terminals. Record only public recipients in the reviewed SOPS creation rule. Use distinct recipients, never a placeholder recipient. Keep the VPS private identity on persistent root-controlled storage (0600), outside /nix/store, Git, the public static root and CI artifacts.
4. Encrypt the approved credential material using SOPS with both recipients. Review recipient access, least privilege and an offline recovery copy. SOPS encrypted files may enter a deployment repository only after owner approval.
5. Set aia.portalSecrets options explicitly, then evaluate the complete host configuration and test decryption on authorized nonproduction infrastructure. Runtime consumers use the generated .path, not Nix evaluation of plaintext.
6. Decide which service reloads after rotation. Rotate application credentials as well as SOPS recipients when revoking access: rewrapping alone does not invalidate an already copied password. Test recovery and key restoration.

Separate staff and management resource authorization

Keep original documents outside Astro public, dist, release archives and CDN roots. Proposed delivery namespaces are /staff-resources/ and /management-resources/; neither is implemented or considered working here. Use nginx auth_request to an approved authorization service or an equivalent server-enforced policy with individually revocable identities and staff and management roles. Staff credentials must not authorize management resources; management access to staff resources must be an explicit policy. Backend file locations must be internal, inaccessible through static aliases or alternate paths. Never trust a browser-provided role header.

A separate shared Basic Auth credential file per namespace can be considered only as an explicitly approved weaker interim model, not identity management or automatic role inheritance. The template prepares separate secret inputs without selecting that access model or installing an identity provider.

Use HTTPS, Cache-Control: private, no-store, no shared/CDN caching, and Referrer-Policy: no-referrer for protected delivery. Avoid credentials and sensitive resource paths in access/error logs; review monitoring and backups. Authorization failures must fail closed, including at proxy/cache boundaries. Test direct requests, alternate encodings, role crossover and rollback.

Distinct boundaries and release checks

• SOPS: deployment secrets at rest and controlled runtime access.
• Portal HTML: shared-code browser decryption, offline-guessable access friction.
• Documents: require server authorization even if URLs are encrypted in the UI.

The approved production portal build uses a non-public encrypted two-stream payload and retains the same browser-side decryption boundary. Approved non-PHI documents install separately into the VPS-owned staff/management directories; they are never copied into dist. Verify both protected namespaces, two-view separation, artifact exclusions, code rotation, restore and rollback before cutover. Revoking a static release cannot retract ciphertext or files already downloaded by visitors. Site cutover remains separately authorized.