first commit

deploy/ADMIN-MANAGEMENT.md

@@ -0,0 +1,106 @@
+# Central management deployment and operating model
+
+The administrator interface is a separate web application served by the management
+service. The managed browser is a device client, not an administrative trust
+boundary. Opening the console in an enterprise browser does not grant permissions:
+the backend authenticates the administrator and authorizes every API operation.
+
+## Deployment topology
+
+Run the Node management service under a dedicated service identity with access only
+to its protected data directory. Bind `HOST=127.0.0.1` and publish it through the
+organization's HTTPS reverse proxy on an administrative hostname. Set `PUBLIC_URL`
+to that exact HTTPS origin, including the port if applicable. Keep port 4310 off
+public interfaces and make administrative access subject to corporate network and
+identity controls. The service does not terminate TLS itself.
+
+Do not add permissive CORS or weaken the existing CSP. Forward the original Origin
+header unchanged; origin validation must compare it to `PUBLIC_URL`. The service
+uses secure, HTTP-only, SameSite session cookies on HTTPS and does not trust proxy
+headers for user identity. Configure the TLS proxy to issue HSTS after the HTTPS
+deployment has been validated. Do not use the loopback HTTP development URL for a
+remote deployment.
+
+Register the exact `${PUBLIC_URL}/auth/callback` redirect with the corporate OIDC
+provider. Require MFA or phishing-resistant authentication at the identity provider.
+Use distinct administrator, operator and auditor groups. An employee's browser
+enrollment permission must not grant an administrative role.
+
+## Deployment credentials and keys
+
+Supply secrets through protected service configuration rather than frontend files,
+URLs or policy documents. Protect the SQLite database, signing keys, backups, ICAPS
+client keys and SIEM credentials with service-account ACLs and encrypted storage.
+The development `.env` file is not a production secret distribution mechanism.
+
+Require the protected management channel, and deploy its pinned ML-DSA public key
+to browser installations through a trusted endpoint-management channel:
+
+```text
+REQUIRE_PQ_MANAGEMENT_CHANNEL=true
+SAFETYNET_REQUIRE_CHANNEL_PIN=true
+SAFETYNET_CHANNEL_SIGNATURE_KEY_FILE=C:/ProgramData/SafetyNet/management-public.pem
+```
+
+This public key is not a secret. Confirm its fingerprint independently of the
+browser enrollment response. The custom policy envelope adds application-level
+protection over HTTPS; it does not replace TLS, identity verification or independent
+cryptographic review. Enrollment, audit and AI endpoints still rely on HTTPS.
+
+## Operator workflow
+
+1. Verify fleet last-seen times, policy version distribution, inspector configuration
+   and SIEM delivery state in the overview. A configured feature is not evidence that
+   every deployed device has exercised it successfully.
+2. Start from a policy template and review its proposed additions. Preserve the
+   customer's existing proxy, VPN, DNS and ICAPS trust configuration.
+3. Edit a draft, review changed policy paths, and publish with the displayed version.
+   A version conflict requires reloading and reviewing the current policy.
+4. Teach document references using authorized source documents. Persisted teaching
+   features are hashes and, when configured, local vectors; the source document is
+   not retained. Inspect completeness before approving partial coverage.
+5. Validate allowed and blocked transfers with a controlled receiver before enabling
+   a new detection threshold across a company. A block test alone does not establish
+   an acceptable false-positive rate.
+6. Use managed bookmarks for intranet destinations. User bookmark read/edit access
+   and user editing permissions are centrally governed and enforced by the backend.
+7. Export audit events to the existing SIEM using its supported authenticated
+   ingestion format. Exercise receiver failure and cursor resumption.
+
+The present rollout publishes one organization-wide policy. Group assignments,
+canary deployment rings, independent approval, SCIM, key rotation and retention
+automation remain tracked implementation work; the console must not imply they are
+already available.
+
+## Local inspector containment
+
+On Windows the inspector applies an unnamed, non-inheritable Job Object before
+importing parsers or model code. It limits the complete process tree to four
+processes and 4 GiB committed memory, denies breakaway, and terminates descendant
+model workers when the inspector exits or is killed. Failure to attach the boundary
+fails inspector startup. The browser checks the startup capability declaration.
+
+The HTTP broker now keeps parsers outside its own process. Each document request
+launches a separate AppContainer worker, attests its actual token and zero
+capabilities, and exchanges bytes over bounded anonymous pipes. Only its approved
+source, Python and local model trees receive read/execute grants for the specific
+package SID. Nested jobs terminate leftover model workers. Native probes establish
+private-file read denial, runtime write denial, TCP/UDP transmission denial and
+child-token inheritance for the tested installation.
+
+Windows still provides package-private storage and some system resources. Do not
+claim that all possible writes or exploit classes are excluded. Protected Program
+Files deployments need installer/service-provisioned package-SID ACLs; ordinary
+users cannot be expected to change installation DACLs. Runtime preparation and
+packaging explicitly provision these ACLs; normal startup only verifies access
+and fails closed when permissions are missing. External
+or linked runtime/model trees are rejected. Production installer preparation and
+independent sandbox bypass testing remain release gates.
+
+## Release gates
+
+Track the exhaustive requirement matrix in `docs/requirements-audit.md`. Complete
+native transfer coverage and parser isolation, customer integration testing, signed
+installers and updates, and an independent security assessment before production
+deployment. The unpacked Windows executable is a developer build with required
+side resources, not a production installer.