System Security Best Practices

Type: Explanation
Audience: Admins and Developers
Related: docs/knowledge-base/security/authentication-flows.md, docs/knowledge-base/developer/architecture/backend/file-upload-rate-limiting.md

---

Für Admins

Was ist eine Sicherheitsverletzung?

Eine Sicherheitsverletzung ist ein Vorfall, bei dem Daten oder Funktionen unautorisiert beeinflusst werden. Typische Klassen:

• Injection (z. B. manipulierte Eingaben)
• Cross-Site-Scripting (XSS)
• Missbrauch von Zugriffsrechten
• Datenabfluss durch Fehlkonfiguration

Was Admins konkret beeinflussen koennen

Admins entwickeln keine Security-Features, koennen aber Konfiguration und Betrieb sicher halten:

1. Benutzer- und Rollenmanagement sauber pflegen.
2. Gesperrte Benutzer/Memberships zeitnah pruefen.
3. Ungewoehnliche Login- oder Aktivitaetsmuster beobachten.
4. Datei-Uploads organisatorisch steuern (erlaubte Formate/Prozesse definieren).
5. Datenschutzprozesse (Auskunft, Loeschung, Protokollierung) verbindlich leben.

Datei-Uploads aus Admin-Sicht

Empfehlungen fuer die Praxis:

• Nur notwendige Dateitypen zulassen.
• Keine ausfuehrbaren Formate fuer Fachprozesse akzeptieren.
• Benutzer ueber maximale Dateigroessen informieren.
• Bei Auffaelligkeiten Upload-Workflows temporär einschränken.

Technischer Ist-Stand (Backend):

• Upload-Middleware: express-fileupload
• Globales Dateigroessenlimit: 250 MB

Referenz:

• elbtalteamadmin-services/src/server.ts

Passwort- und Account-Sicherheit (Admin-Prozesse)

• Kein Teilen von Zugangsdaten.
• Bei Verdacht auf Kompromittierung: Passwort-Reset + Session-Beendigung.
• Sperrungen nicht als Dauerzustand nutzen, sondern mit Prozess dokumentieren.

Monitoring und Audit

Als Mindeststandard sollten Admins verfolgen:

• haeufige fehlgeschlagene Logins
• unerwartete Session-Abbrueche
• Sperrungen/Entsperrungen von Memberships
• auffaellige Datei-Uploads

Datenschutz-Kontext:

• Siehe admin-gdpr-guide.md fuer rechtliche Pflichten und Auskunftsprozesse.

---

For Developers

Input Validation

Shifty uses Zod schemas and endpoint-level validation.

Observed pattern:

• Request schemas are defined centrally in src/_schemas.
• Service handlers validate request body using schema-check helpers.
• Invalid request shapes produce controlled 400-style errors.

Examples and references:

• Auth request/response schema: elbtalteamadmin-services/src/_schemas/auth.ts
• Common validation helpers: elbtalteamadmin-services/src/_schemas/common.ts
• Service-level validation pattern: elbtalteamadmin-services/src/auth/login/service.ts

Recommended hard rules:

• Validate at route entry, never deep in business logic only.
• Use explicit enums and constrained shapes instead of permissive objects.
• Keep parsing errors generic in outward responses.

File Upload Security

Current implementation baseline

• Middleware: express-fileupload
• Global file size limit: 250 MB
• Parent path creation enabled

Reference:

• elbtalteamadmin-services/src/server.ts

Hardening checklist

1. Use whitelist MIME validation.
2. Do not trust client MIME only; verify file signature if handling risky formats.
3. Enforce per-endpoint lower limits than global defaults whenever possible.
4. Sanitize filenames and avoid path traversal risks.
5. Prefer generated IDs/paths for persisted files.
6. Process media through trusted pipeline (Sharp) for resizing/normalization.
7. Define retention/cleanup jobs for temporary or orphaned files.

Implementation references in repository docs and code:

• docs/knowledge-base/developer/architecture/backend/file-upload-rate-limiting.md
• elbtalteamadmin-services/src/server.ts

Note:

• This repository already documents Sharp-based processing patterns in developer architecture docs.

Password & Encryption

Important correction for this codebase:

• Password hashing uses Argon2id (hash-wasm), not bcrypt.

References:

• elbtalteamadmin-services/src/_utils/auth/password.ts
• password verification in login flow: elbtalteamadmin-services/src/auth/login/func.ts

Additional safeguards in auth pipeline:

• Refresh token is hashed with SHA-256 before persistence.
• JWT signing and verification uses jose.

References:

• elbtalteamadmin-services/src/auth/login/func.ts
• elbtalteamadmin-services/src/_utils/auth/jwt.ts

Transport security:

• Operate behind HTTPS/TLS in production and secure infrastructure.
• Keep secrets in environment variables only.

OWASP Top 10 mapping for Shifty

A01: Broken Access Control

Risk:

• Unauthorized access to admin or system routes.

Mitigation in Shifty:

• Role/teamRole checks in proxy middleware.

Reference:

• src/proxy.ts

A02: Cryptographic Failures

Risk:

• Weak password storage or weak token handling.

Mitigation in Shifty:

• Argon2id password hashing.
• JWT signing/verification via jose.
• Refresh token hashing before DB storage.

Reference:

• elbtalteamadmin-services/src/_utils/auth/password.ts
• elbtalteamadmin-services/src/_utils/auth/jwt.ts
• elbtalteamadmin-services/src/auth/login/func.ts

A03: Injection

Risk:

• Malicious input in API payloads.

Mitigation in Shifty:

• Schema-driven input validation with Zod.

Reference:

• elbtalteamadmin-services/src/_schemas/

A05: Security Misconfiguration

Risk:

• Overly permissive middleware, CORS, upload limits.

Mitigation in Shifty:

• Centralized server middleware and explicit endpoint registration.

Reference:

• elbtalteamadmin-services/src/server.ts

A07: Identification and Authentication Failures

Risk:

• Invalid refresh flows, stale sessions, weak session controls.

Mitigation in Shifty:

• Refresh-token validation and rotation.
• Session-restriction endpoint and unlock flow.

Reference:

• elbtalteamadmin-services/src/auth/login/func.ts
• elbtalteamadmin-services/src/auth/restrict-session/service.ts
• src/auth/context/auth-provider.tsx

A09: Security Logging and Monitoring Failures

Risk:

• Security incidents not traceable.

Mitigation in Shifty:

• Dedicated logs endpoints/models and operational logging patterns.

Reference:

• elbtalteamadmin-services/src/logs/

Safe response behavior

• Return generic auth errors to avoid user/account enumeration.
• Avoid leaking stack traces or token details in responses.
• Keep sensitive data out of logs.

Developer security checklist

• Validate all request bodies with schemas.
• Enforce role checks in protected operations.
• Never store raw passwords or raw refresh tokens.
• Prefer allowlists over deny lists for uploads.
• Keep endpoint limits and timeouts explicit.
• Review CORS and proxy assumptions before production rollout.

---

Verification Quicklist

• Für Admins and For Developers sections exist: yes.
• Input Validation, File Upload, Password, OWASP sections exist: yes.
• Code references point to repository files: yes.
• Password section reflects actual implementation (Argon2id): yes.