stackchan-atoms3r

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.

Changes land on main through pull requests, which are public while in progress; the branch is not squashed into periodic releases only.

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

PROJECT_VER in the top-level CMakeLists.txt is the single authority: ESP-IDF places it in the application descriptor and the device.describe command reads it back, so a running device reports its own version. Releases are tagged with v + that value, currently v0.1.0. tools/check-invariants.py fails the build when any copy of the version disagrees with PROJECT_VER, and CI checks the tag against it on a tag push.

Semantic Versioning. The current version is 0.1.0, and CHANGELOG.md states that interfaces may change before 1.0.0 and that breaking changes are called out.

Each release is tagged in git as v<version>, for example v0.1.0. The tag is derived from PROJECT_VER rather than typed, and CI rejects a tag that disagrees with it. https://github.com/kkdev92/stackchan-atoms3r/tags

Non-trivial release notes file in repository: https://github.com/kkdev92/stackchan-atoms3r/blob/main/CHANGELOG.md.

There have been no publicly known vulnerabilities in this project, so no release notes have had any to identify. v0.1.0 is the first public release.

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

GitHub Issues, with bug report and feature request templates in .github/ISSUE_TEMPLATE/. https://github.com/kkdev92/stackchan-atoms3r/issues

No bug reports have been submitted yet -- the repository became public recently and the issue tracker is empty. The tracker is open and monitored by the maintainer, and SECURITY.md states that reports are acknowledged when possible. This answer will be worth re-checking once reports have actually arrived.

No enhancement requests have been submitted yet; the issue tracker is open, has a feature request template, and is monitored. The project is still making enhancements.

GitHub Issues keeps a public, searchable archive of reports and their discussion. https://github.com/kkdev92/stackchan-atoms3r/issues?q=is%3Aissue

SECURITY.md describes the process: GitHub Private Vulnerability Reporting first, a maintainer email as a fallback, a request not to open a public issue before assessment, and instructions to strip tokens, credentials and raw core dumps from reports. https://github.com/kkdev92/stackchan-atoms3r/blob/main/SECURITY.md

GitHub Private Vulnerability Reporting is enabled on the repository, which gives a private channel that does not disclose the report. A maintainer email address is documented as a fallback. https://github.com/kkdev92/stackchan-atoms3r/security/advisories/new

No vulnerability has been reported in the last 6 months, so there is no response time to report.

Non-trivial build file in repository: https://github.com/kkdev92/stackchan-atoms3r/blob/main/CMakeLists.txt.

Non-trivial build file in repository: https://github.com/kkdev92/stackchan-atoms3r/blob/main/CMakeLists.txt.

The build uses PlatformIO (Apache-2.0), ESP-IDF (Apache-2.0), CMake (BSD-3-Clause) and the GCC-based xtensa-esp32s3 toolchain, all FLOSS and all runnable on a FLOSS operating system. CI builds on ubuntu-latest.

An automated suite of 409 host test cases across 31 Unity suites in src/test/, run with pio test -e native. It builds only src/core, which by design contains no ESP-IDF, so the whole decision layer is tested on a PC with no board attached. An emulator lane additionally boots the real firmware image under QEMU and fails unless the startup log shows the self-checks passing. Both run in CI on every pull request. https://github.com/kkdev92/stackchan-atoms3r/blob/main/.github/workflows/ci.yml

pio test -e native runs the whole host suite. tools/check.ps1 runs the invariant, test, analysis, build and emulator lanes together. Both are documented in CONTRIBUTING.md.

Measured rather than estimated. A coverage lane runs the host suites instrumented and merges the result. On src/core, the decision layer that holds every policy decision in the firmware, the most recent CI run reports 93.2% of lines (1858 of 1993), 82.6% of branches (1057 of 1279) and 99.7% of functions (297 of 298). tools/check-coverage.py produces those figures on every pull request and fails the build if line coverage falls below 90% or branch coverage below 80%, so the claim cannot quietly stop being true; the floors are the durable part, the exact percentages move a little with the compiler version. The code outside src/core is the hardware-facing layer, which an emulator boot check exercises instead.

GitHub Actions runs the invariant check, the host tests, cppcheck, clang-tidy, CodeQL, three firmware builds and the QEMU boot check on every pull request and every push to main, and all of them are required status checks on main. https://github.com/kkdev92/stackchan-atoms3r/blob/main/.github/workflows/ci.yml

CONTRIBUTING.md states the policy: a behavior change should include a test when the behavior can be exercised without hardware, and a bug fix should preferably include a test that fails before the fix. https://github.com/kkdev92/stackchan-atoms3r/blob/main/CONTRIBUTING.md

The functionality described in the v0.1.0 release notes arrived together with the 409-case host suite that covers it -- every core component has a matching test suite, including the command registry, request router, conversation, SSE parser, WAV handling, access token and provisioning scope. Hardware-dependent behavior that cannot run on the host is instead covered by the emulator boot check.

The Tests section of CONTRIBUTING.md documents the expectation and how to satisfy it, including the test_native_ directory naming rule and the guidance to use fixed inputs and observable results rather than timing-dependent assertions. https://github.com/kkdev92/stackchan-atoms3r/blob/main/CONTRIBUTING.md

The host environment, which compiles the whole decision layer, sets -Wall -Wextra -Wpedantic -Werror=return-type in platformio.ini. The firmware environments do not add warning flags of their own and take ESP-IDF's default set; what holds them is that CI fails any firmware build whose log contains a warning arising from src/core, src/main or src/platform. cppcheck and clang-tidy also run over src/core on every pull request.

CI treats any warning from this project's own sources as a failure: each firmware build greps its build log for warnings under src/core, src/main and src/platform and fails the job if one appears. cppcheck runs with --fail-on-defect=medium and --fail-on-defect=high. main is green.

As strict as is practical here. Warnings are enabled broadly (-Wall -Wextra -Wpedantic on the host) and, rather than a blanket -Werror that would also fail on third-party headers, CI fails the build on any warning arising from this project's own sources while leaving vendored ESP-IDF and component code out of scope. That is the boundary a firmware project can actually hold.

The maintainer is the sole primary developer and designed the firmware around the Saltzer and Schroeder principles. Concretely, in this code base: complete mediation -- RequestRouter::route checks the token before it reads or parses the body, with the comment that parsing before authorising would expose the parser to anyone who can reach the port, and every command goes through that one path; fail-safe defaults -- an unset token matches nothing rather than everything, and provisioning_allowed returns false when the access point is down or the arrival interface is unknown; least privilege -- provisioning routes are reachable only through the setup access point, never from the station interface; limited attack surface -- one authenticated route with a registry of ten commands, a body size cap, and no telemetry service; economy of mechanism -- the decision layer holds no platform APIs at all, which keeps it small enough to test exhaustively on a host; open design -- the protocol, threat model and token handling are fully documented in SECURITY.md and docs/api/device-interface.md, and security rests on the token rather than on secrecy of the design; input validation with allowlists -- command names are matched against a registry and an unreadable request id is treated as absent rather than truncated. Separation of privilege and least common mechanism are the weakest of the eight here: a single bearer token is single-factor, which SECURITY.md states plainly. https://github.com/kkdev92/stackchan-atoms3r/blob/main/SECURITY.md

Common error classes for networked C++ firmware, each with the countermeasure used here. Buffer overflow -- the request body is rejected above a fixed cap, parsing writes into fixed-size buffers with an explicit length argument, and cppcheck, clang-tidy and CodeQL (extended query suite, c-cpp) run on every pull request. Missing authentication -- every command passes through a single token check that runs before the body is parsed. Missing authorization -- provisioning is restricted to requests that arrived on the setup access point interface. Timing side channel on credential comparison -- AccessToken::matches compares all characters with no early return, so the number that matched does not show up in how long the rejection took. Injection -- there is no shell, SQL or HTML sink; JSON fields are looked up by name and unescaped into bounded buffers, and command names are matched against a registry allowlist. Credential leakage -- secret scanning with push protection is enabled, .gitignore excludes local secret and log files, and SECURITY.md warns that serial logs are sensitive because the token is printed when created or rotated. Denial of service through a stuck wait -- waits are bounded by deadlines and cancellation is delivered independently of queues, both enforced as design invariants.