friendflix

Repository on GitHub, which provides public git repositories with URLs.

Repository on GitHub, which uses git. git can track the changes, who made them, and when they were made.

Repository on GitHub, which uses git. git is distributed.

Version Numbers plus Major Version Names e.g Aranicini

Non-trivial release notes file in repository: https://github.com/LetsManu/friendflix/blob/main/CHANGELOG.md.

Non-trivial SECURITY[.md] file found file in repository: https://github.com/LetsManu/friendflix/blob/main/SECURITY.md. [osps_do_02_01]

GitHub Issues: https://github.com/LetsManu/friendflix/issues (bug report and feature request templates; security reports go privately via SECURITY.md).

No external bug reports have been submitted yet (project is new). Bug reports are tracked in GitHub Issues (https://github.com/LetsManu/friendflix/issues) and the maintainer acknowledges every report; the process is described in CONTRIBUTING.md.

No external enhancement requests have been submitted yet (project is new). Enhancement requests are tracked in GitHub Issues via the feature request template (https://github.com/LetsManu/friendflix/issues/new/choose); the maintainer responds to every request.

All bug reports, enhancement requests and responses are kept in GitHub Issues, which is public and searchable: https://github.com/LetsManu/friendflix/issues?q=is%3Aissue

The vulnerability reporting process is published in SECURITY.md: https://github.com/LetsManu/friendflix/blob/main/SECURITY.md (private reporting via GitHub Security Advisories, response within a week). It is also linked from the README and CONTRIBUTING.md.

SECURITY.md explains how to report privately: use GitHub private vulnerability reporting (repository → Security → “Report a vulnerability”), which is visible only to the maintainers: https://github.com/LetsManu/friendflix/blob/main/SECURITY.md. Direct form: https://github.com/LetsManu/friendflix/security/advisories/new

No vulnerability reports have been received in the last 6 months. SECURITY.md commits to a first response within 7 days, which is within the 14-day requirement.

The project is built with npm workspaces and Docker. npm ci && npm run build builds backend, gateway and web from source; each service has a Dockerfile, and docker compose build builds all images. CI (GitHub Actions, https://github.com/LetsManu/friendflix/blob/main/.github/workflows/ci.yml) rebuilds everything from source on every pull request and push to main. Setup instructions: https://github.com/LetsManu/friendflix/blob/main/docs/setup.md

The build uses only common, widely used tools: Node.js with npm (workspaces), TypeScript (tsc), Vite/SvelteKit for the web app, and Docker / Docker Compose for the images. CI runs on GitHub Actions.

All build tools are FLOSS: Node.js (MIT), npm (Artistic-2.0), TypeScript (Apache-2.0), Vite and SvelteKit (MIT), esbuild (MIT), Docker Engine / Moby and BuildKit (Apache-2.0), Docker Compose (Apache-2.0). The base image is Alpine Linux. No proprietary tool is required to build.

The test suites are part of the repository and released under AGPL-3.0: Vitest unit and integration tests for backend, gateway and web, Node test-runner tests for scripts, and Playwright end-to-end tests (e2e/). How to run them is documented in CONTRIBUTING.md (https://github.com/LetsManu/friendflix/blob/main/CONTRIBUTING.md#checks-to-run-before-opening-a-pr: npm test, npm run e2e). CI runs them on every pull request: https://github.com/LetsManu/friendflix/blob/main/.github/workflows/ci.yml

Tests run with the standard Node.js/npm command npm test from the repository root, which runs every workspace’s test script. End-to-end tests run with npm run e2e (Playwright).
https://github.com/LetsManu/friendflix/blob/main/CONTRIBUTING.md

The test suites are broad: about 900 backend tests, 230 gateway tests, 600 web unit tests and 57 Playwright end-to-end spec files covering the main user flows (login, profiles, player, downloads, casting, admin, kids mode, TV mode, phone layouts). Every bug fix comes with a regression test (CONTRIBUTING.md). Line/branch coverage is not measured yet.

GitHub Actions CI runs on every pull request and every push to main: lint, typecheck, unit tests on Node 22 and 26, Playwright end-to-end tests, Docker image builds with Trivy scanning, gitleaks secret scanning, a DAST baseline scan and CodeQL. Changes are integrated through small pull requests, several per day. https://github.com/LetsManu/friendflix/actions/workflows/ci.yml

CONTRIBUTING.md states the test policy: “New behaviour comes with tests; bug fixes come with a test that fails without the fix.” Unit tests use Vitest, user-visible flows get Playwright end-to-end tests. https://github.com/LetsManu/friendflix/blob/main/CONTRIBUTING.md#requirements-for-acceptable-contributions

Recent major changes all added tests in the same pull request, for example:

LetsManu/friendflix#113–LetsManu/friendflix#115 (AirPlay): rewritten airplay controller tests plus a stream-probe sanitizer test.
LetsManu/friendflix#114 (AirPlay loop fix): 14 new tests that reproduce the loop and fail without the fix.
LetsManu/friendflix#119 (cast compatibility): gateway tests for the compatibility playlist and the linear attribute parser, backend tests for the cast HLS URL, client fallback tests.
Block 21 (detail page / TMDB, OMDb): backend tests for keys, caching, the 401 pause, the OMDb budget and visibility filters, plus e2e specs.

See https://github.com/LetsManu/friendflix/pulls?q=is%3Apr+is%3Amerged

The instructions for change proposals (CONTRIBUTING.md, “Pull requests” and “Requirements for acceptable contributions” → Tests) require tests for new behaviour and a failing-first test for bug fixes, and list the checks to run before opening a pull request: https://github.com/LetsManu/friendflix/blob/main/CONTRIBUTING.md

TypeScript runs in strict mode with noUncheckedIndexedAccess (tsconfig.base.json), and npm run typecheck (tsc --noEmit for every package; svelte-check for the web app) must pass. ESLint uses the @eslint/js recommended and typescript-eslint recommended rule sets (eslint.config.js). CI runs npm run lint and npm run typecheck on every pull request and fails on any error. CodeQL adds static analysis on top. https://github.com/LetsManu/friendflix/blob/main/eslint.config.js

Warnings are treated as errors in practice: CI fails on any ESLint or TypeScript error, so main always lints and typechecks clean. CodeQL findings are fixed in the pull request that triggers them, for example the polynomial-regex alert in #119 (replaced by a linear parser with a regression test) and earlier findings on URL checks, key hashing and regex injection. Trivy image findings are fixed by base-image and package updates (#116).

TypeScript runs in its strictest common configuration (strict plus noUncheckedIndexedAccess) and ESLint uses the recommended rule sets; any finding fails CI. Only two rules are relaxed, each documented in eslint.config.js: no-explicit-any, because external JSON is validated at the boundary, and no-control-regex, which is needed for input sanitising. CodeQL runs its default security queries on every pull request.

The design follows established secure-design principles:

Least privilege: containers run read-only, non-root, with all capabilities dropped. The web app never gets the Docker socket, and each role has its own library and bitrate limits.
Complete mediation: every media request goes through a separate gateway that asks the backend to authorize it. Media-server credentials never reach the browser.
Fail-safe defaults: new devices need approval, cast tokens are scoped to one item, session and device, are short-lived, pinned to the client address and revocable, and an unknown or failed authorization means deny.
Defense in depth: OIDC SSO, CSP, rate limits, input validation with zod, playlist URI sanitizing and secrets encrypted at rest.
Economy of mechanism / open design: small, focused services and documented security behaviour in docs/ and SECURITY.md.

The maintainer reviews the threat model per feature, and the CI security tooling (CodeQL, Trivy, gitleaks, DAST, Scorecard) backs it up.

The maintainer knows the common web-application weaknesses (OWASP Top 10, CWE Top 25) and the mitigations used here:

Broken access control / IDOR: every API route checks the session, role and profile, and every media path is authorized by the gateway, scoped to item and media source.
Injection (SQL, regex, header): parameterized SQL queries only; input validation with zod; no user input in regular expressions (CodeQL-checked); linear parsers for untrusted text.
XSS: Svelte escaping by default, a strict Content-Security-Policy, and no {@html} with user data.
CSRF: SameSite cookies and origin checks on state-changing requests.
SSRF / open redirects: playlist URIs are resolved and pinned to the gateway origin, upstream redirects are refused, and external fetches go to fixed hosts with timeouts.
Authentication and session flaws: OIDC SSO, device approval, and short-lived, scoped, revocable cast tokens, stored only as hashes.
Sensitive data exposure: secrets encrypted at rest, tokens never logged, media-server credentials kept server-side.
Vulnerable dependencies and misconfiguration: Dependabot, Trivy, pinned base images, hardened containers.
Denial of service: rate limits, size caps on playlists and bodies, timeouts.

Only published, expert-reviewed algorithms and protocols are used: AES-256-GCM (NIST SP 800-38D) for secrets at rest, scrypt (RFC 7914) for profile PINs, SHA-256 and HMAC-SHA256 (FIPS 180-4, RFC 2104) for token hashes and signed URLs, CSPRNG tokens via crypto.randomBytes, OpenID Connect with PKCE (RFC 7636) for login, Web Push encryption with VAPID (RFC 8291, RFC 8292), and TLS for transport. No custom algorithms or protocols.

FriendFlix implements no cryptography itself. All cryptographic functions come from Node.js node:crypto, which is backed by OpenSSL (AES-GCM, scrypt, SHA-256, HMAC, CSPRNG, constant-time comparison), and from dedicated libraries: openid-client for OIDC/PKCE and web-push for Web Push encryption. TLS is handled by the reverse proxy.

All cryptographic functionality uses FLOSS: Node.js node:crypto with OpenSSL (Apache-2.0), openid-client (MIT), web-push (MPL-2.0), and TLS through FLOSS reverse proxies (nginx / Nginx Proxy Manager, Caddy, Traefik). The OIDC provider can be FLOSS as well, for example Authentik. No proprietary crypto component is required.

All defaults meet or exceed the NIST minimums through 2030 (112-bit security):

AES-256-GCM for secrets at rest. APP_ENC_KEY must be exactly 32 bytes, otherwise the server refuses to start, so shorter keys cannot be configured.
SHA-256 / HMAC-SHA256.
scrypt with a 128-bit salt and 256-bit output for PINs.
256-bit random tokens.
Web Push with VAPID on ECDSA P-256 (128-bit security).

OIDC token signatures come from the identity provider; Authentik defaults to RS256 with 4096-bit keys. TLS is terminated by the reverse proxy, whose configuration can disable weak ciphers and short keys.

No broken algorithms or inappropriate modes are used in any security mechanism. Encryption uses AES-256 in GCM mode (authenticated, random 96-bit IV per message); hashing and MACs use SHA-256 / HMAC-SHA256; PINs use scrypt; randomness comes from the OS CSPRNG. No MD4, MD5, DES, RC4, ECB or Dual_EC_DRBG. SHA-1 appears once, only to build a non-security cache key for language lists (backend/src/routes/media.ts), where collision resistance does not matter.

No security mechanism depends on algorithms or modes with known serious weaknesses: no SHA-1, no CBC, no RSA PKCS#1 v1.5 encryption. Encryption uses AES-256-GCM, hashing and MACs use SHA-256 / HMAC-SHA256, and PINs use scrypt. The only former SHA-1 use, a non-security cache key, was switched to SHA-256 (LetsManu/friendflix#121).

FriendFlix implements no key agreement of its own.

Transport: TLS is terminated by the reverse proxy (Nginx Proxy Manager / nginx / Caddy / Traefik). Current defaults negotiate TLS 1.3 or ECDHE suites, which always provide perfect forward secrecy.
Web Push: payloads are encrypted per RFC 8291 with a fresh ephemeral ECDH key for every message, so a later compromise of long-term keys does not reveal past messages.

Ein Hinweis: In den Proxy-Vorlagen unter deploy/ stehen keine expliziten TLS-Einstellungen, das Projekt verlässt sich auf die modernen Voreinstellungen der Proxys. Die sind heute sicher. Wenn du

FriendFlix does not store passwords for authenticating its users: sign-in is delegated to an OpenID Connect provider (e.g. Authentik), which handles password storage. The only user-chosen secret FriendFlix stores is the optional profile PIN, hashed with scrypt and a random per-PIN salt (backend/src/crypto.ts, hashPin) and verified in constant time.

FriendFlix also creates, for each user, a random service account on the media server (Jellyfin). Its password is generated by FriendFlix (192-bit random), never seen or chosen by a person, and must be presented to Jellyfin, so it is stored encrypted with AES-256-GCM rather than hashed.

All keys, tokens, nonces and salts come from the operating system’s CSPRNG via Node.js crypto.randomBytes:

AES-GCM IVs (96-bit)
scrypt salts (128-bit)
session, CSRF, cast and image tokens (256-bit)
invite / party codes
generated service-account passwords

Math.random is used only for non-security purposes: UI animations, SVG element ids, list shuffling, and a numeric suffix on duplicate usernames.

Distribution channels use HTTPS exclusively. [osps_br_03_02]

The project never retrieves hashes over plain HTTP. Releases are distributed as container images from GitHub Container Registry over HTTPS and addressed by digest. Images carry SLSA provenance and an SBOM attestation from the CI build. Base images in the Dockerfiles are pinned by sha256 digest, and npm verifies lockfile integrity hashes (sha512) for every package fetched over HTTPS.

No known vulnerabilities of medium or higher severity are unpatched. npm audit reports 0 vulnerabilities in production and development dependencies. Dependabot opens update PRs weekly. Trivy scans every image in CI and fails on fixed HIGH/CRITICAL findings; the recent zlib (MEDIUM) finding was fixed within a day by pinning base images and running apk upgrade (LetsManu/friendflix#116). CodeQL findings are fixed in the PR that introduces them.

Critical and high findings block merging: CI fails on any fixable CRITICAL/HIGH Trivy finding, and on new high-severity CodeQL alerts in a pull request. They are fixed before release, usually the same day; for example, the high-severity CodeQL alert in LetsManu/friendflix#119 was fixed within minutes. Reported vulnerabilities get a first answer within 7 days (SECURITY.md), and a fix ships as a patch release once available.

No working credentials are in the repository. Secrets are passed at runtime through environment variables or Docker secrets (*_FILE), and .env files are git-ignored (only .env.example with placeholders is committed). gitleaks scans every pull request and push in CI and runs as a pre-commit hook. The few entries in .gitleaksignore are deliberately fake test values used in unit tests.

CodeQL (GitHub code scanning, javascript-typescript and actions queries) runs on every pull request and every push to main, so every release has been analysed; new high-severity alerts block the merge. ESLint with the typescript-eslint rules and OpenSSF Scorecard run as well. Release images are built only from main after these checks pass.

CodeQL’s default JavaScript/TypeScript security queries look for common web vulnerabilities (CWE-based): injection, XSS, path traversal, SSRF, ReDoS / polynomial regex, insecure randomness, weak crypto, incomplete URL sanitisation and more. Its findings have led to fixes in this project, for example the polynomial regex in LetsManu/friendflix#119 and URL-substring checks and a weak key hash in earlier PRs. Its actions queries check the GitHub workflows for injection and permission problems.

CodeQL findings of medium or higher severity are fixed in the pull request that introduces them, before merge. Recent examples are the polynomial regex in LetsManu/friendflix#119, and an incomplete URL-substring check, a weak hash for a key, unsafe HTML tag stripping and regex injection in earlier PRs, each fixed the same day. No open medium-or-higher CodeQL alerts remain on main.

CodeQL and ESLint run on every pull request and every push to main, so every commit that reaches main is analysed. OpenSSF Scorecard also runs on a schedule.

Dynamic analysis runs on every pull request and every push to main, so on every release:

OWASP ZAP baseline scan (DAST): runs against the built web app in CI (dast job in ci.yml).
Playwright end-to-end tests: exercise the running application, including auth, access control and kids-mode restrictions.
Integration tests: run the backend and gateway against real PostgreSQL/Redis and mocked upstreams.
Trivy: scans the built container images.

FriendFlix is written entirely in memory-safe languages: TypeScript/JavaScript on Node.js, and Svelte. The project contains no C or C++ code.

Tests run with many assertions enabled:

Unit and integration tests (Vitest): assert results, error paths and security properties, for example that tokens never appear in logs and that access is denied across profiles.
End-to-end tests (Playwright): assert UI state and network behaviour; the test build runs with development checks and source maps.
Runtime validation: zod schemas validate every API input and fail loudly in tests.

Production builds (NODE_ENV=production) leave out these test-only checks.

Medium and higher findings from dynamic analysis block merging and are fixed before release. The OWASP ZAP baseline scan fails the CI dast job on new warnings, and failing Playwright or integration tests block the PR. Findings from these scans led to hardened security headers and CSP. No confirmed medium-or-higher dynamic-analysis finding is open.