Security testing

bag is open for security testing, and findings are welcome. This page says what to test, how to test in good faith and how to report. The security policy is the authority: where this page and the policy differ, the policy is right. The policy is bag.dev/security (SECURITY.md on main, the same in the 0.1.2 commit).

What the call covers#

bag is a security preview of version 0 of the wire format: no outside cryptographic review has signed, and nothing says “reviewed” until a reviewer signs. Expect findings, and expect the draft to change because of them.

The call covers version 0.2.1: the npm package @usebag/bag 0.2.1, built from the published commit 87fca427c02a37c17e2d524960fcbb06414f054a that the install guide names, and the source at that commit in the public repository.

In scope, in the policy’s words: the specification (spec/SPEC.md), the reference implementation (packages/, crates/), the reference relay (ac-relay), and the test vectors and adversarial cases when they are wrong or let a flawed reader pass.

Out of scope: deployments run by others (their relays, hosts, key storage and configuration), and the third-party software bag depends on, which you should report to its own maintainers.

The site, the records the project serves and the telemetry endpoint take reports, not active testing. In the policy’s words:

Reports about the project’s other services are welcome, but active testing against them is out of scope: the site https://bag.dev with its install guide, the .well-known and handle records the project serves, and the telemetry endpoint https://telemetry.bag.dev.

Where to start#

• The threat model, prepared for an outside reviewer. Every security claim in it cites the specification or the code, and where a claim is weaker than it first reads, it says so. Its line numbers refer to the 2026-10-29 assembly; some have moved, so search by the named file and function.
• The summary of two adversarial review rounds: the findings, what was done about each, and what is built and what is deferred. The two review rounds covered the 2026-10-29 assembly; the short pairing code, multiple identities and telemetry have had no round yet.
• Section 10 of the specification, “Security considerations”, the authority on what the protocol does and does not protect.
• Set up a client by hand and Run your own relay, for an installation of your own to test against.

What this release does not include, as the repository’s install guide (docs/partner-install.md) lists it in section 7:

• the internal notes that code comments cite (design notes, studies, plans, an operations guide, review rounds, drafts). A comment that points to a file you do not have is a note; nothing needs it to build or run;
• installer or service files for the relay or for the record keep command. The packaged forms are the relay’s container image and the npm package;
• the macOS keychain custody works on macOS only; the file custody works everywhere.

Testing in good faith#

The public relays are in scope too. In the policy’s words:

The two public relays, https://relay1.bag.dev and https://relay2.bag.dev (README.md, “Public relays”), are run by the project, not by others, and are in scope: you may test them in good faith, within this policy. Against them, do no load, availability or volume testing; each is a single machine that other people use, so test limits on a relay you run yourself (docs/self-host.md). Do not access, change or keep other people’s data, and do not use social engineering on anyone.

Run your own relay sets one up. The policy’s safe harbour:

If you research in good faith and within this policy, we will not report you to law enforcement and will not pursue you for it. This is our word only; we cannot speak for anyone else.

How to report#

Report privately through the repository’s Security tab (“Report a vulnerability”, GitHub’s private vulnerability reporting), or by mail to security@bag.dev. Please do not open a public issue or pull request for a vulnerability.

Include:

• what you found and which part it is in (the spec section, a package or crate, the relay);
• the version or commit you tested (npx --yes --package=@usebag/bag@0.2.1 bag --version prints both);
• steps or a small program that reproduces it, and what you expected instead;
• what an attacker gains, and what they need first (a network position, a stolen key, a malicious relay).

Do not send private keys, real session keys, captured mail from systems you do not own, or anyone’s personal data. A test key generated for the report is fine.

What happens next#

The project aims to acknowledge a report within 7 days, and works to coordinated disclosure at 90 days from the report. After the acknowledgement it tells you whether it can reproduce the issue, and what it plans to do. Please give it time to fix an issue before you publish details: a date is agreed with you. If a fix needs a change to the wire format, it ships as a new wire version with a public note.

No bounty, and thanks#

In the policy’s words:

There is no bounty: we pay nothing for reports. With your consent we credit you publicly, by the name you give us, in the thanks list, docs/thanks.md. Without it, we name no one.

The thanks list is docs/thanks.md in the public repository.