Skip to content

feat: allow a whole Bitwarden Secrets Manager project in one config section, with clear rules when a secret also has its own entry #177

Closed

Description

@groupsky

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

  1. Config. A new section names a bws store and a project, with clients and 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 "one never per id" check of section 14 cannot run for secrets the broker has not seen.

  2. Name. A client asks for a project secret as SECTION/KEY, where KEY is the secret's key in Bitwarden, for example nodkey 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 a KEY that 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/KEY can be up to 129 bytes. Proposed: raise api.MaxName for secret names to 129, and keep each part at 64 at most.

  3. Lookup. The broker runs bws secret list PROJECT --output json --color no (it checks first that PROJECT is a UUID) and finds the secret by key. Then it gets the secret by ID as today, and checks that the key and projectId in 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 list returns the values of all secrets in the project. The broker reads only id, key and projectId, and clears the whole answer. The table "what the broker runs" in section 16 gets the new command.

  4. 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

  1. Same secret in a project and in a [secret.*] entry: the entry wins, completely. After the broker turns SECTION/KEY into a UUID, it looks for a [secret.*] entry with that UUID in any bws store. Two stores can use the same machine account, so the store is not part of the match. If there is one entry, its clients, ask, window, preapprove and standing apply, and the project rule is not used at all. Nothing is merged. A client that is in the project's clients but not in the entry's clients is refused. The entry may be looser than the project rule (for example window when the project says always): 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.
  2. Two secrets with the same key in 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.
  3. 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.
  4. 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 for ci/KEY does not hand it out. A standing grant works the same way. When point 5 applies, the entry's own grants are used, as today.
  5. 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.
  6. 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 list brings all values of the project into the broker's memory for a short time.

Done when

  • DESIGN.md has the [project.*] section, the SECTION/KEY names, the lookup, the message and points 5 to 10. Section 16 has the secret list command.
  • 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 another bws store (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 get answer 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/KEY does not hand out a different secret that now has that key. A test with a rename.
  • A SECTION/KEY of 129 bytes works, and longer names and parts are refused. Tests at the limit.
  • The broker reads only id, key and projectId from secret list and clears the answer. A test with a fake bws.
  • 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

  1. groupsky commented on Nov 15, 2026

    @groupsky
    ContributorAuthor

    hq-jobs nodkey-177-build (run r-20261115-194012-428a)

    Built in #185, squash merged as 9d6cb8a. Evidence for each "Done when" box:

    • DESIGN.md: section 14 "Projects" (the [project.*] section, SECTION/KEY names, lookup, message, which rule wins, grants per ID, a secret that leaves the project), reload rules 2 and 5, and the section 16 table with bws secret list and the array rule.
    • THREAT-MODEL.md: T49 (write access to the project), T50 (a key shown in the message), T51 (secret list brings all values into memory). docs/setup.md: "bws: allow a whole project", with the "Can read" step.
    • Hands out a project secret by SECTION/KEY, refuses a key not in the project: TestProjectSecret, TestProjectSecretRefused (internal/broker/projects_test.go).
    • A [secret.*] entry with the same UUID wins: TestProjectEntryWins (subtests stricter, looser, two entries, another bws store); TestProjectRuleFor in internal/config.
    • Duplicate key refused with an audit entry: TestProjectDuplicateKey.
    • Key or project in the get answer differs from the list: TestProjectGetDiffers; store level TestBWSFetchListed.
    • ask = "never" and one project in two sections stop the start: TestProjectConfigRefused (internal/config; loadBroker is the same code for start, reload and nodkey broker check).
    • Reload that adds an entry ends the old project grant: TestProjectReloadAddsEntry, TestSameProjectSecret. A reload with one project in two sections is refused: TestProjectConfigRefused (the reload loads the config with loadBroker, so the same check refuses it).
    • A 15-minute grant does not hand out a renamed secret: TestProjectGrantRename.
    • 129 bytes works, longer names and parts refused: TestProjectSecretLimits, TestParseSecretName, TestCaps, TestPreapproveCaps, TestRunUsage.
    • Reads only id, key, projectId and clears the answer, with a fake bws: TestBWSListSecrets, TestReadListClears, TestParseBWSListBad.
    • Security review by .claude/agents/security-reviewer.md: three findings (made-up keys in the audit log on some deny paths, no per-client cap while bws secret list runs, two names for one secret). All fixed before the commit, with TestProjectMadeUpKeysNotLogged and TestProjectSameSecretTwice; the second pass found nothing open.

    Pre-approvals and standing grants work for project secrets too (TestProjectPreapprove). No release was made.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions