carbon-footprint-program

Repository on GitHub, which provides public git repositories with URLs: https://github.com/undp/carbon-footprint-program (visibility: public).

Repository on GitHub, which uses git. git records the author, committer and timestamp of every change, together with the full parent history.

Development happens in the open between releases: every change lands as a pull request merged to main, and those interim commits are public immediately rather than only at release time. 519 commits, 505 pull requests (425 of them merged) and 49 issues are publicly visible, and each release is cut from already-public main history rather than from a private branch.

Repository on GitHub, which uses git. git is a distributed version control system.

Every release has a unique identifier: an annotated git tag and a matching GitHub Release (1.1.1, 1.1.2, 1.2.0, 1.3.0, 1.3.1, 1.3.2, 1.4.0, 1.4.1, 1.4.2, 1.5.0, 1.6.0) — see https://github.com/undp/carbon-footprint-program/releases. The canonical version lives in the root package.json, is baked into the Docker image tag, and is exposed at runtime through the APP_VERSION value returned by the API health endpoint.

The project uses Semantic Versioning (MAJOR.MINOR.PATCH) and documents the increment rules at https://github.com/undp/carbon-footprint-program/blob/main/docs/release/versioning.md. The published tags follow SemVer (e.g. 1.4.1 → 1.4.2 for fixes, 1.5.0 → 1.6.0 for backward-compatible features).

Each release is identified by a git tag with the exact version number, and the tag is what the GitHub Release points at: https://github.com/undp/carbon-footprint-program/tags.

Every release publishes human-readable release notes as a GitHub Release: https://github.com/undp/carbon-footprint-program/releases. Each entry has a "What's Changed" summary grouped by area (e.g. "User Modules", infrastructure, dependencies) listing each merged change with its author and pull-request link — for example https://github.com/undp/carbon-footprint-program/releases/tag/1.6.0. Notes are provided for all eleven releases, 1.1.1 through 1.6.0.

No publicly known, CVE-assigned vulnerability in this project's own code has been fixed in any release to date, so there is nothing of that kind to enumerate. Dependency vulnerabilities are handled by Dependabot security updates, and the resulting pull requests appear by name in the "What's Changed" list of the release that includes them (see https://github.com/undp/carbon-footprint-program/releases). Should a vulnerability in the project's own code ever be fixed, SECURITY.md commits the maintainers to coordinated disclosure and the release notes will call it out.

The bug-reporting process is documented in three places: CONTRIBUTING.md "Reporting bugs & requesting features" https://github.com/undp/carbon-footprint-program/blob/main/CONTRIBUTING.md, .github/SUPPORT.md, which routes each kind of report to the right channel https://github.com/undp/carbon-footprint-program/blob/main/.github/SUPPORT.md, and structured issue forms at https://github.com/undp/carbon-footprint-program/issues/new/choose (bug report, feature request, refactor, DPG compliance). Security vulnerabilities are explicitly excluded from public issues and routed to the private process in https://github.com/undp/carbon-footprint-program/blob/main/SECURITY.md.

GitHub Issues is used as the issue tracker: https://github.com/undp/carbon-footprint-program/issues. It is backed by structured issue forms in .github/ISSUE_TEMPLATE/ (bug_report.yml, feature_request.yml, refactor.yml, dpg_compliance.yml) and a namespaced label taxonomy maintained as code in .github/labels.yml (type:, area:, priority:, status:), so reports are consistently classified and triaged.

Bug reports are consistently acknowledged and acted on. Of the 49 issues filed in the last 12 months, 18 are already closed, and bugs are typically triaged within a day — for example issue #547 (equivalence computed in the wrong unit) was filed 2026-07-28 and fixed and closed 2026-07-29 by PR #550. Every incoming report is labelled (type:bug, area:, priority:, status:triage), which is the acknowledgement step, and priority:critical bugs such as #395 and #391 were closed with fixes. To date no report has been left unanswered.

Enhancement requests are triaged the same way as bugs: they are labelled type:feature (or type:refactor / type:tech-debt), given an area and a priority, and either scheduled or answered in the thread. Several have been implemented and shipped — for example the "optional comment on approving a submission" request (PR #409, released in 1.6.0) and the provider-agnostic backend auth refactor (#398, closed 2026-07-09). Requests that conflict with the project's country-agnosticism principle are answered with that rationale, as documented in .github/SUPPORT.md.

The issue tracker is public, searchable and permanently archived at https://github.com/undp/carbon-footprint-program/issues?q=is%3Aissue, covering both open and closed issues. Pull-request discussions are similarly public at https://github.com/undp/carbon-footprint-program/pulls?q=is%3Apr, and GitHub Discussions is enabled for longer-form threads.

The vulnerability reporting process is published in https://github.com/undp/carbon-footprint-program/blob/main/SECURITY.md. The declared security contact is the maintainer team collectively — the @undp/carbon-footprint-program-maintainers GitHub team (see https://github.com/undp/carbon-footprint-program/blob/main/.github/CODEOWNERS and https://github.com/undp/carbon-footprint-program/blob/main/GOVERNANCE.md) — so handling a report never depends on one individual's availability. SECURITY.md states that vulnerabilities must not be reported through public issues, discussions or pull requests, names GitHub private vulnerability reporting as the private channel, tells a reporter who cannot use it to open a detail-free issue requesting a private channel, and gives an escalation path to the maintainer team after 5 business days. It also lists what to include in a report and the in-scope and out-of-scope components.

Private reporting is available through GitHub Private Vulnerability Reporting, which is enabled on the repository and reachable from the Security tab at https://github.com/undp/carbon-footprint-program/security/advisories. It is documented as the preferred channel in https://github.com/undp/carbon-footprint-program/blob/main/SECURITY.md. Reports go privately to the maintainer team collectively (@undp/carbon-footprint-program-maintainers) rather than to a named individual, which keeps the report, the discussion, the fix and any resulting advisory in one private place with no single point of failure. SECURITY.md explicitly asks reporters not to use public issues, discussions or pull requests, and offers a detail-free public issue as a way to request a private channel for anyone who cannot use GitHub PVR.

https://github.com/undp/carbon-footprint-program/blob/main/SECURITY.md publishes the maintainer team's commitment to acknowledge a vulnerability report within 3 business days — well inside the 14-day requirement — and tells reporters to escalate to the maintainer team if they have not heard back within 5 business days. It further commits to validating the issue, agreeing a remediation timeline with the reporter, and practising coordinated disclosure with credit unless the reporter prefers anonymity. In the interest of accuracy: this is the maintainer team's published working target, and formal ratification of the acknowledgement and remediation SLAs by UNDP as the owning organization is still in progress (tracked in issue #460).

The software is built from source with two standard commands: "pnpm install" then "pnpm build". The root package.json "build" script drives Turborepo, which builds the shared packages (@repo/types, constants, utils, database, storage), the Fastify API and the React/Vite web app in dependency order. Prerequisites and exact toolchain versions are pinned in .tool-versions and .nvmrc and documented in https://github.com/undp/carbon-footprint-program/blob/main/docs/development/local-setup.md. CI proves the build works from a clean checkout on every pull request via the required "Build" job in .github/workflows/ci.yml.

The build uses widely available, conventional tooling: Node.js, pnpm (workspaces), Turborepo, the TypeScript compiler (tsc), Vite for the web bundle, Prisma for schema/client generation, and Docker for containerization. There are no bespoke build tools to learn.

Every tool required to build the project is FLOSS: Node.js, pnpm, Turborepo, TypeScript, Vite, Prisma, ESLint, Prettier, Vitest and Docker. The project can be built and tested end to end on a FLOSS platform with no proprietary software; a docker-compose setup provides Postgres, Keycloak and MinIO as open-source local dependencies.

The project has an automated test suite documented at https://github.com/undp/carbon-footprint-program/blob/main/docs/development/testing.md. apps/api has 199 test files, of which 161 are integration tests that exercise real HTTP routes through Fastify's app.inject() against a real PostgreSQL instance provisioned with Testcontainers (plus Azurite and MinIO for the storage legs). apps/web adds 37 Vitest suites running under jsdom with React Testing Library. tools/seed has its own unit suite. The whole suite runs in CI on every pull request.

The suite runs with the standard single command "pnpm test" from the repository root (Turborepo fans it out to every workspace). Narrower entry points exist for convenience: "pnpm test:api", "pnpm test:web", "pnpm test:seed", and "pnpm test:api -- /<feature>" for a single feature.

The test suite covers most of the code and most of the functionality. apps/api — which holds essentially all of the business logic, including emission calculations, authorization, and the data layer — is gated in CI at 90% coverage for lines, statements, functions and branches, merged across the three test legs by the required "Coverage" job in .github/workflows/ci.yml. That gate is enforced on every pull request, so the figure is a floor rather than a snapshot, and every externally reachable endpoint has an integration test (161 integration test files exercising real HTTP routes against a real PostgreSQL instance via Testcontainers). Stated transparently: apps/web is covered by a smaller Vitest + jsdom + React Testing Library suite (37 files) over its logic layers — utils, hooks, stores, chatbot — behind an enforced floor that is deliberately ratcheted upward as tests are added, so a share of its render-heavy UI is not yet covered. The judgement recorded here is that a 90%-gated backend plus a growing frontend suite satisfies "most".

Continuous integration runs the full suite on every pull request to main via .github/workflows/ci.yml. "Test (base)", "Test (storage-azure)", "Test (storage-minio)", "Test (web)", "Seed Unit Tests" and "Coverage" are required status checks under branch protection, alongside Lint, Type Check, Format Check, Build, Audit, Zizmor, Secret Scan and Docs Link Check. See https://github.com/undp/carbon-footprint-program/actions/workflows/ci.yml.

The policy is written down in CONTRIBUTING.md under "Contribution acceptance criteria": "Test coverage — new features include integration tests" https://github.com/undp/carbon-footprint-program/blob/main/CONTRIBUTING.md#contribution-acceptance-criteria. docs/development/testing.md gives the concrete conventions for writing them, and the policy is mechanically enforced by the 90% merged-coverage gate in CI, which fails a pull request that adds logic without adding tests.

Tests accompany functional changes as a matter of course — apps/api currently carries 199 test files across 161 integration suites, grown alongside the features they cover, and apps/web has 37. The requirement is enforced rather than merely encouraged: the required "Coverage" check re-computes merged coverage across all three test legs and fails below 90% on lines, statements, functions and branches, so a feature pull request without matching tests cannot merge. Recent examples of test-only ratchets are PRs #509, #515 and #518.

The policy is documented in two places: the "Contribution acceptance criteria" section of https://github.com/undp/carbon-footprint-program/blob/main/CONTRIBUTING.md, and the testing guide at https://github.com/undp/carbon-footprint-program/blob/main/docs/development/testing.md, which explains the Vitest + Testcontainers setup, the app.inject() pattern, and the factory helpers a contributor should use when adding tests.

Compiler and linter warnings are enabled at a strict level. TypeScript runs with "strict": true (packages/typescript-config/base.json), and ESLint uses typescript-eslint's recommendedTypeChecked configuration (packages/eslint-config/base.ts), which requires full type information and therefore reports type-aware problems, not just syntactic ones. Both run over the whole monorepo via "pnpm lint" and "pnpm type-check".

There are no outstanding warnings, and the build enforces that: "pnpm lint" is invoked as "turbo run lint -- --max-warnings=0", so a single ESLint warning fails the required "Lint" status check, and "pnpm type-check" fails the required "Type Check" check on any TypeScript error. Both are required checks under branch protection, so warnings cannot accumulate on main.

Maximally strict settings are enabled rather than the defaults: TypeScript "strict": true, and typescript-eslint's recommendedTypeChecked ruleset, which needs a full type-checked program and catches classes of bug (unsafe any flow, floating promises, unnecessary conditionals) that non-type-aware linting cannot see. Prettier formatting is separately enforced by a required "Format Check" job.

The maintainer team collectively (@undp/carbon-footprint-program-maintainers — see https://github.com/undp/carbon-footprint-program/blob/main/.github/CODEOWNERS and https://github.com/undp/carbon-footprint-program/blob/main/GOVERNANCE.md) holds and applies the knowledge of how to design secure software; this is asserted for the team rather than for one individual, matching how the project is actually governed and reviewed. The design record is public under docs/security/ https://github.com/undp/carbon-footprint-program/tree/main/docs/security: authentication.md (OIDC/JWKS token verification), rbac.md and route-access-modes.md (role-based authorization applied per route), hardening.md (deployment topologies, TLS enforcement, HTTP security headers, input validation, upload controls), secrets.md (Azure Key Vault with managed identities, no credentials in code), sensitive-data.md, audit-logging.md, and github-actions-security.md. The principles are visible in the code, not just the docs: least privilege via per-route role guards; fail-closed defaults — the API refuses to boot in production unless JWKS_URI, JWKS_ISSUER and JWKS_AUDIENCE are set, rather than silently accepting tokens it cannot bind to this application (apps/api/src/config/environment.ts); defense in depth (helmet headers, then schema validation, then authorization, then audit logging); minimal attack surface; and no trust in client-supplied identity. CONTRIBUTING.md requires an explicit maintainer security review for any change to auth, authorization, file upload or database queries, which is how the knowledge is applied structurally rather than incidentally. Complementary documents are SECURITY.md and PRIVACY.md.

The maintainer team collectively (@undp/carbon-footprint-program-maintainers) holds this knowledge, and the codebase reflects it. Injection: all database access goes through Prisma's parameterized query builder; there is no string-concatenated SQL. Input validation: every request body, query and parameter is validated against a Zod schema at the route boundary (schemas live in packages/types), so unvalidated input never reaches business logic. Broken access control: authorization is enforced server-side by explicit requireAuth / requireRoles / requireOrganizationRole hooks per route, documented in docs/security/rbac.md and route-access-modes.md and covered by integration tests. XSS and header attacks: @fastify/helmet applies secure headers globally and React escapes by default. Insecure direct object references: domain access hooks verify organization membership before returning records. Secrets in code: Azure Key Vault with managed identities, plus GitHub secret scanning with push protection and a betterleaks CI gate over full git history. Race conditions and partial writes: multi-step mutations run inside Prisma transactions. These classes are also checked mechanically by CodeQL's security-and-quality suite on every push and pull request. The team also files its own hardening findings publicly rather than leaving them implicit — see issue #559, which pins an explicit JWT algorithms allowlist to close an algorithm-confusion surface found while preparing this badge.