Repository navigation
Description
Why
Today each secret needs its own [secret.NAME] entry in broker.toml, with the UUID of the secret (DESIGN.md section 14). To let agents use a new secret, the owner must add an entry and reload the broker. For a bws store this repeats a choice that Bitwarden already holds: a machine account sees only the projects the owner gave it.
The owner wants to allow a whole Secrets Manager project in one config section. Putting a secret into the project is then the "allow" step, with no config edit. This is the same idea as the collection of #103, for bws.
Proposal
-
Config. A new section names a
bwsstore and a project, withclientsand one rule for every secret in the project:[project.ci] store = "main" # a bws store project = "00000000-0000-0000-0000-000000000000" clients = ["laptop"] ask = "window" window = "15m" # preapprove and standing as for [secret.*]
ask = "never"is an error in a[project.*]section. It would make every secret in the project tap-free, also secrets added later, and the "oneneverperid" check of section 14 cannot run for secrets the broker has not seen. -
Name. A client asks for a project secret as
SECTION/KEY, whereKEYis the secret'skeyin Bitwarden, for examplenodkey run --secret GH_TOKEN=ci/GITHUB_TOKEN -- .... The broker splits the name at the/; a name with two or more/is refused. A plain name without/is always a[secret.*]entry, so the two kinds of names cannot clash. The key is matched exactly, also in upper and lower case. Only aKEYthat follows the name rule of section 14 can be asked for; other secrets in the project are skipped, and their key is never shown.SECTION/KEYcan be up to 129 bytes. Proposed: raiseapi.MaxNamefor secret names to 129, and keep each part at 64 at most. -
Lookup. The broker runs
bws secret list PROJECT --output json --color no(it checks first thatPROJECTis a UUID) and finds the secret bykey. Then it gets the secret by ID as today, and checks that thekeyandprojectIdin that answer are the same as in the list. If not (for example a rename between the two calls), it denies. Section 16 changes for this one command: the answer is a JSON array, not one object, and it is capped at 1 MiB like any other answer, so a project that is too big is denied. The setup guide says: keep a project small, or split it.secret listreturns the values of all secrets in the project. The broker reads onlyid,keyandprojectId, and clears the whole answer. The table "what the broker runs" in section 16 gets the new command. -
Message. The tap message shows
ci/GITHUB_TOKEN, that it comes from a project rule, and the last 8 characters of the secret's UUID. The key is read from Bitwarden, not sent by the client.
When the rules conflict
- Same secret in a project and in a
[secret.*]entry: the entry wins, completely. After the broker turnsSECTION/KEYinto a UUID, it looks for a[secret.*]entry with that UUID in anybwsstore. Two stores can use the same machine account, so the store is not part of the match. If there is one entry, itsclients,ask,window,preapproveandstandingapply, and the project rule is not used at all. Nothing is merged. A client that is in the project'sclientsbut not in the entry'sclientsis refused. The entry may be looser than the project rule (for examplewindowwhen the project saysalways): the owner wrote it for that one secret. If two or more entries have that UUID, the request is denied: there is no clear winner. - Two secrets with the same
keyin one project: deny. Bitwarden does not keep secret names unique, even inside one project. The broker cannot tell which one is meant, so it refuses the request and writes an audit entry with the section and the key, never a value. - The same project in two sections (in one store or in two stores): an error at start and at reload. Project UUIDs are compared in lower case. One secret would get two rules with no clear winner.
- Grants are for one secret ID, not for a name. This is new work in the grant core. Today a grant is kept per (client, config section name) (
internal/approval/state.go). For a project secret, the grant and the pre-approval are kept per (client, project section, secret UUID). The key is turned into a UUID when the grant is made, and each use is checked against that UUID. So if someone gives a different secret the old key, a grant forci/KEYdoes not hand it out. A standing grant works the same way. When point 5 applies, the entry's own grants are used, as today. - A secret that leaves the project is no longer found by
SECTION/KEY. An explicit[secret.*]entry for it keeps working while the machine account can still read it. - Reload (section 14) runs the checks of points 1 and 7 again. A grant stays only if the new config still gives the same rule. A project grant for a secret that now has its own
[secret.*]entry ends.
Threats to add to THREAT-MODEL.md
- Anyone who can write to the project changes what agents can get, with no config change: they can add a secret, or give a key to a different secret. The setup guide must say: the broker's machine account gets "Can read" only, and only the owner may write to the project. Grants are per UUID (point 8), and the tap message shows the end of the UUID.
- A key is typed by whoever can write to the project, and it is shown in the tap message. Only keys that follow the name rule are shown.
secret listbrings all values of the project into the broker's memory for a short time.
Done when
- DESIGN.md has the
[project.*]section, theSECTION/KEYnames, the lookup, the message and points 5 to 10. Section 16 has thesecret listcommand. - THREAT-MODEL.md has the threats above. docs/setup.md shows how to allow a project, with the "Can read" step.
- The broker hands out a secret of the project by
SECTION/KEY, and refuses a key that is not in the project. A test for each. - A
[secret.*]entry with the same UUID overrides the project rule: a test where it is stricter (a client is refused) and one where it is looser. Tests for two entries with that UUID (denied) and for an entry in anotherbwsstore (it still wins). - A duplicate key in the project is refused with an audit entry. A test.
- A test where the key or the project in the
getanswer differs from the list: denied. -
ask = "never"in a[project.*], and the same project in two sections, stop the broker at start. A test for each. - After a reload that adds a
[secret.*]entry for a project secret, the old project grant no longer works. After a reload that puts one project in two sections, the reload is refused. A test for each. - A 15-minute grant for
ci/KEYdoes not hand out a different secret that now has that key. A test with a rename. - A
SECTION/KEYof 129 bytes works, and longer names and parts are refused. Tests at the limit. - The broker reads only
id,keyandprojectIdfromsecret listand clears the answer. A test with a fakebws. - It gets the security review, as every change does.
Related: #103 (the same idea for a Bitwarden collection; its per-item rule follows the same answer, see the comment there), #29 / #173 / #174 (config reload and config from git).
Activity
groupsky commentedon Nov 15, 2026
hq-jobs
nodkey-177-build(runr-20261115-194012-428a)Built in #185, squash merged as 9d6cb8a. Evidence for each "Done when" box:
[project.*]section,SECTION/KEYnames, lookup, message, which rule wins, grants per ID, a secret that leaves the project), reload rules 2 and 5, and the section 16 table withbws secret listand the array rule.secret listbrings all values into memory). docs/setup.md: "bws: allow a whole project", with the "Can read" step.SECTION/KEY, refuses a key not in the project:TestProjectSecret,TestProjectSecretRefused(internal/broker/projects_test.go).[secret.*]entry with the same UUID wins:TestProjectEntryWins(subtests stricter, looser, two entries, another bws store);TestProjectRuleForin internal/config.TestProjectDuplicateKey.getanswer differs from the list:TestProjectGetDiffers; store levelTestBWSFetchListed.ask = "never"and one project in two sections stop the start:TestProjectConfigRefused(internal/config;loadBrokeris the same code for start, reload andnodkey broker check).TestProjectReloadAddsEntry,TestSameProjectSecret. A reload with one project in two sections is refused:TestProjectConfigRefused(the reload loads the config withloadBroker, so the same check refuses it).TestProjectGrantRename.TestProjectSecretLimits,TestParseSecretName,TestCaps,TestPreapproveCaps,TestRunUsage.id,key,projectIdand clears the answer, with a fakebws:TestBWSListSecrets,TestReadListClears,TestParseBWSListBad..claude/agents/security-reviewer.md: three findings (made-up keys in the audit log on some deny paths, no per-client cap whilebws secret listruns, two names for one secret). All fixed before the commit, withTestProjectMadeUpKeysNotLoggedandTestProjectSameSecretTwice; the second pass found nothing open.Pre-approvals and standing grants work for project secrets too (
TestProjectPreapprove). No release was made.