Kuutti

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.

Every squash-merged pull request lands on main, the integration branch, and is deployed to staging at once; anyone can build and run that state. Releases are annotated tags on main.

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

Semantic version in the root package.json, mirrored into the three apps and checked in CI (pnpm check:version). The API names its build with the commit, for example 0.16.0-37a837c, unless built from a release tag vX.Y.Z.

Semantic Versioning 2.0.0 since 0.1.0: a pull request carrying a feature bumps MINOR, one carrying only fixes bumps PATCH, in that pull request (CLAUDE.md, Git section). 0.y.z until the first public release.

A release is an annotated tag vX.Y.Z on main, made by the maintainer (CONTRIBUTING.md, Releases); the tag retags the image main already built for that commit, deploys production and drafts the release. No release has been tagged yet (the project is at 0.y.z, before its first public release).

No release has been made yet. When the first tag vX.Y.Z is pushed, the release workflow (.github/workflows/release.yml) drafts a GitHub release with notes from the pull requests since the previous tag, which the maintainer edits into a human-readable summary and publishes.

No publicly known vulnerability has been reported or fixed yet, and no release has been made. A fixed vulnerability will be named in the release notes with its GitHub advisory; SECURITY.md credits the reporter in the advisory.

Bug reports are GitHub issues opened from the templates in .github/ISSUE_TEMPLATE/ (CONTRIBUTING.md, Issues). Vulnerabilities go through the private process in SECURITY.md instead: https://github.com/kuutti-ry/kuutti-app/blob/main/SECURITY.md

GitHub issues: https://github.com/kuutti-ry/kuutti-app/issues

Issues are acknowledged and acted on; after the pull request that works on one merges, the issue is closed with a comment naming the pull request, the commit and the version, or a comment says what is left and whose move it is (CLAUDE.md, Git section).

Enhancement requests get a reply. Some are declined by design: the README and CLAUDE.md name what the project will never build (scores, infinite feeds, paid boosts, ads), so a no comes with its reason.

GitHub issues and pull requests are public and searchable: https://github.com/kuutti-ry/kuutti-app/issues?q=

SECURITY.md: report privately through the GitHub vulnerability reporting form https://github.com/kuutti-ry/kuutti-app/security/advisories/new, with what was found, how to reproduce it, the affected commit, and any proof of concept. https://github.com/kuutti-ry/kuutti-app/blob/main/SECURITY.md

GitHub private vulnerability reporting is enabled on the repository (a private advisory draft over HTTPS); SECURITY.md points to it and asks not to use public issues. https://github.com/kuutti-ry/kuutti-app/security/advisories/new

SECURITY.md commits to an acknowledgement within 7 days and a status update once the report has been assessed. No vulnerability report has been received so far.

pnpm workspace: pnpm install --frozen-lockfile, then each app builds with FLOSS tools (tsup for the API, Vite for the moderation panel, Expo prebuild and the native toolchains for the app). The API image is built from apps/api/Dockerfile in CI.

Node 22, pnpm (via corepack) and Docker; nothing else is needed to build and run the whole stack locally (README, Run it locally).

Node, pnpm, tsup, Vite, Expo CLI, Docker and OpenTofu are all FLOSS. The cloud build service (EAS) is a convenience; a native build runs locally with the open-source Expo tooling.

Vitest for the API and the packages, running against a real PostgreSQL with a transaction rolled back per test; jest-expo for the React Native app; Gherkin specifications of the rules layer mapped to tests (ADR-002); Maestro end-to-end flows on simulators and emulators (apps/mobile/e2e, ADR-020).

pnpm test runs every suite from the repository root; pnpm test:coverage runs them against the coverage floors; pnpm e2e runs the Maestro flows; pnpm check:scenarios checks the Gherkin mapping.

Coverage floors per package, branches first, enforced in CI (ADR-021), the strictest on identity. About 3,500 test cases across the API, mobile app and packages, including property-based tests with fast-check and the end-to-end flows.

GitHub Actions on every push and pull request: typecheck, lint, tests, i18n, licences, audit, Gherkin mapping, schema drift, and a compose job with Postgres, the S3 stand-in and the mock bank (.github/workflows/ci.yml). The Maestro flows run on main and on labelled pull requests in four parallel jobs (e2e.yml).

CLAUDE.md, Testing, is the policy: tests at every level that applies, every route and every reachable branch with a test that asserts its outcome, a bug fix landing with the test that failed first. ADR-021 records it.

The per-package coverage floors fail CI when code arrives without tests, and a floor only goes up; pnpm check:scenarios fails on a rule scenario without a same-named test. Every pull request runs the whole suite.

Documented in CLAUDE.md (Testing section, the standing rules every contributor and agent loads) and ADR-021; the pull request template requires typecheck, lint and tests to pass, and CONTRIBUTING.md points to the rules.

TypeScript strict mode everywhere (tsconfig.base.json) and Biome lint with the recommended rules plus project rules (slice import boundaries, no inline user-facing strings), both on every pull request and in a pre-commit hook.

The typecheck and lint jobs fail the pull request on any error or warning, and main only takes green pull requests. The pre-commit hook runs Biome on the staged files so they are fixed before the push.

TypeScript strict is on in every package, with no any in exported signatures; Biome runs its recommended rule set as the floor and the project adds rules on top. Nothing is suppressed wholesale.

The primary developer wrote the project security checklist (docs/security-checklist.md) and its non-negotiable rules (CLAUDE.md): least privilege (every user-data query scoped by the session account id), fail-safe defaults, economy of mechanism (one box, no speculative layers), complete mediation at the API (uploads re-encoded server-side, no direct-to-storage path), secrets only in a parameter store, and never persisting the personal identity code.

docs/security-checklist.md follows the OWASP Top 10 categories (broken access control, misconfiguration, supply chain, cryptographic failures, injection, insecure design, authentication failures, integrity failures, logging failures, exceptional conditions) and is read before any change to identity, auth, uploads, signed URLs, events or infrastructure; a security review of the diff is required on those surfaces.

HMAC-SHA256 for the identity pseudonym, SHA-256 digests for stored tokens, TLS 1.2+ for transport, and OpenID Connect with signed JWTs for bank identification; all published, standard algorithms.

All cryptography goes through node:crypto (OpenSSL), the jose and openid-client libraries for JWT and OIDC, and the platform TLS stacks; the project implements no cryptographic primitive of its own.

node:crypto (OpenSSL), jose and openid-client are FLOSS, as is the TLS stack in Node; nothing proprietary is required.

HMAC-SHA256 with a 256-bit key held in SSM Parameter Store; session and moderator tokens are 32 random bytes (256 bits); TLS at CloudFront uses the TLSv1.2_2021 policy (ECDHE with AES-GCM or ChaCha20, certificates with RSA 2048 or P-256).

No MD5, SHA-1, RC4, DES, 3DES or similar anywhere in the code; SHA-256 and HMAC-SHA256 only, and TLS 1.2 or newer.

Defaults are TLS 1.2+ with the TLSv1.2_2021 CloudFront policy and SHA-256-based algorithms; no option to downgrade is exposed.

The public endpoints terminate TLS at CloudFront with the TLSv1.2_2021 policy, which offers only ECDHE (forward-secret) cipher suites; the origin behind it is Traefik with Let’s Encrypt certificates and TLS 1.2+ defaults, reachable over HTTPS from CloudFront only.

The project stores no passwords. Everyone, moderators included, signs in through Finnish bank identification (OpenID Connect via the Telia broker); sessions are random bearer tokens stored only as SHA-256 digests.

Every token, state and nonce comes from node:crypto randomBytes, a cryptographically secure generator; Math.random is not used for anything security-relevant.

Source over HTTPS from GitHub; the API image pulled by digest from the registry over HTTPS; the app through the App Store, Google Play and signed EAS Updates (ADR-004, code signing verified on the device).

Nothing is delivered with only an MD5 or unsigned hash; images are referenced by digest over HTTPS and EAS Updates carry a signature the app verifies.

No known unpatched vulnerability. Dependabot security updates open as soon as an alert appears, pnpm audit on high or above fails CI, and the dependency review workflow checks every pull request.

None known. Dependabot alerts, the dependency review and the weekly OpenSSF Scorecard run surface them, and a fix would be a pull request the same day.

TruffleHog scans every pushed range and the whole history weekly (.github/workflows/secret-scan.yml); GitHub push protection is on; .env files are gitignored and denied at tool level; every secret lives in SSM Parameter Store and is read at boot through the instance role.

TypeScript strict and Biome on every pull request; OpenSSF Scorecard on every push to main and weekly, with findings as code scanning alerts (scorecard.yml); pnpm audit and the dependency review workflow on every pull request.

Biome security and suspicious rule groups on every pull request, pnpm audit and the dependency review for vulnerable dependencies, and Scorecard for dangerous workflow patterns; a security review of every diff on the identity, auth, upload and signed-URL surfaces against docs/security-checklist.md.

The jobs fail the pull request and main only takes green ones; no medium or higher finding is open.

On every push and pull request, before the merge; Scorecard also weekly on main.

Property-based tests with fast-check fuzz the identity code (personal identity code parsing and HMAC derivation); the suites run against a real PostgreSQL, and the Maestro end-to-end flows exercise the built app on simulators and emulators before anything reaches a release.

The project is TypeScript on Node and React Native, memory-safe languages; it contains no C, C++ or other code that is unsafe by default.

Every boundary parses its input with zod schemas (packages/schema) in every build, not only in tests; database constraints hold the invariants; tests assert the outcome of every branch and error.

Nothing found by the property-based tests or the end-to-end flows is open; a bug a test finds gets its own change with the failing test first (CLAUDE.md, Testing).