itworx-knowledge-hub-Public/docs/12-auth-security.md

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.