Initial curated itworx-knowledge-hub source from 3b1751d0d9dee551aa6994eee0093704dc334817

docs/12-auth-security.md

@@ -0,0 +1,203 @@
+# Authentication and security design
+
+## Threat posture
+
+The service is private and self-hosted but must assume:
+
+- the reverse-proxy endpoint may become internet reachable;
+- an authenticated low-privilege account can be malicious;
+- imported Markdown and files are untrusted;
+- database or backup theft is possible;
+- API tokens can leak;
+- container compromise must not automatically expose the host.
+
+The complete threat register is in `docs/26-threat-model.md`.
+
+## First-run owner setup
+
+First-run setup is intentionally available without a separate installation code. The
+endpoint remains a tightly bounded one-time operation:
+
+1. Expose only that setup is required.
+2. Require the new workspace and owner credentials over the setup form.
+3. Protect the mutation with CSRF validation and a setup-specific rate limit.
+4. Atomically create installation, workspace, owner and settings.
+5. Permanently disable first-run registration after successful completion.
+6. Audit successful completion without recording passwords or tokens.
+
+The setup endpoint must not be exposed through an internet-facing reverse proxy before
+owner setup is complete. Complete setup over the trusted LAN or HTTPS endpoint, then
+configure the reverse proxy and create the first backup.
+
+## Password authentication
+
+Use ASP.NET Core Identity or an equivalent reviewed implementation.
+
+Policy:
+
+- minimum 12 characters by default;
+- allow password-manager generated long passphrases;
+- maximum input bound high enough for passphrases;
+- no arbitrary composition rules;
+- check against a small bundled common-password denylist where feasible without an
+  outbound service;
+- adaptive, versioned password hashing;
+- transparent rehash on successful login when policy changes;
+- generic authentication failure;
+- exponential/threshold lockout;
+- session/security stamp invalidation after password reset or account disable.
+
+## Operator-issued recovery
+
+No email provider is required.
+
+1. Administrator or local operator issues a single-use recovery token.
+2. Token has at least 256 bits of entropy, a short expiry and one-use state.
+3. Store only a verifier.
+4. Deliver through an operator-visible channel.
+5. Prefer a URL fragment so the raw token never enters access logs:
+   `https://knowledge.example/#/recover/<token>`.
+6. Client posts the token body to the API.
+7. Successful reset consumes the token and invalidates sessions.
+8. Record safe audit metadata.
+
+For the final administrator, provide a documented container operator command that creates
+a recovery token without database surgery.
+
+## Browser sessions
+
+- Secure cookie in HTTPS production.
+- HttpOnly.
+- SameSite=Lax or stricter based on tested flows.
+- Bounded idle and absolute lifetime.
+- Session rotation after authentication/privilege change.
+- Anti-forgery token on all cookie-authenticated mutations.
+- No auth tokens in localStorage.
+- Logout invalidates server-side session/security state where implemented.
+- Concurrent session view/revocation is desirable in M1.
+
+## Authorization
+
+Authorization is workspace- and resource-aware.
+
+- Reader: view/search permitted content.
+- Editor: reader plus content/project creation and editing.
+- Administrator: editor plus users, imports, backup, retention, audit and service accounts.
+- Service account: scopes plus explicitly assigned workspace/content access; no role
+  inheritance.
+
+Rules are enforced in Application use cases and query specifications. Endpoint attributes
+alone are insufficient.
+
+Tests cover:
+
+- unauthenticated access;
+- role escalation;
+- object-ID substitution;
+- cross-workspace access even though UI exposes one workspace;
+- trashed/private content;
+- attachment and revision access;
+- project context aggregation;
+- disabled users and revoked tokens.
+
+## Service-account tokens
+
+Format contains a non-secret public ID/prefix and a random secret. Store only a verifier.
+
+- Show once.
+- Optional expiry.
+- Multiple independently revocable tokens per account.
+- Named purpose and last-used time.
+- Explicit scopes.
+- Immediate revocation.
+- Constant-time verification.
+- Rate limit failed token authentication.
+- Never accept token in query string.
+- Never log the authorization header.
+
+A database compromise should not make offline token recovery feasible because secrets are
+uniform random 256-bit values.
+
+## CSRF, CORS and origins
+
+- Browser API is same-origin in production.
+- CORS disabled unless a specific trusted integration requires it.
+- Anti-forgery for cookie mutation.
+- Bearer-token calls do not use cookies.
+- Validate configured public/base URL.
+- Proxy headers accepted only from configured trusted proxy networks.
+- Host filtering enabled.
+
+## Content security
+
+Recommended production headers:
+
+- Content-Security-Policy with no unsafe inline script;
+- `frame-ancestors 'none'` unless explicitly required;
+- `object-src 'none'`;
+- `base-uri 'self'`;
+- `form-action 'self'`;
+- HSTS at reverse proxy after HTTPS validation;
+- X-Content-Type-Options;
+- Referrer-Policy;
+- Permissions-Policy.
+
+Rendered Markdown disallows raw HTML and unsafe URLs. Mermaid uses strict mode. Uploads
+are not served as executable same-origin content.
+
+## Secrets and encryption
+
+- Secrets enter through mounted secret files or environment variables.
+- ASP.NET data-protection keys persist outside the read-only root filesystem.
+- Production data-protection keys should be protected with an operator-managed secret
+  where supported.
+- Backup encryption is operator-configurable and must not rely on a key stored only inside
+  the backup.
+- API tokens, passwords and bootstrap/recovery secrets are never recoverable from the DB.
+- Do not pretend application-level encryption protects against a fully compromised
+  running application; document the threat boundary.
+
+## Logging and privacy
+
+Never log:
+
+- passwords;
+- raw tokens;
+- cookies/session IDs;
+- CSRF tokens;
+- page bodies by default;
+- attachment content;
+- full recovery/bootstrap links;
+- database connection strings.
+
+Use safe IDs, correlation IDs and redacted structured properties. Audit retention and
+diagnostic-log retention are separate.
+
+## Rate limits and abuse controls
+
+At minimum isolate policies for:
+
+- setup/login/recovery;
+- failed bearer authentication;
+- global search;
+- upload;
+- import/export/backup;
+- expensive project-context requests.
+
+Return a generic response that does not confirm account/content existence.
+
+## Security verification
+
+Release requires:
+
+- dependency vulnerability scan;
+- secret scan;
+- container scan;
+- authorization matrix tests;
+- CSRF tests;
+- XSS corpus;
+- malicious upload/path corpus;
+- session/token lifecycle tests;
+- security header test;
+- non-root/read-only container evidence;
+- independent security review.