beads/docs/reference
Vishnu J 102372dabd
fix(notion): keep notion.token out of the Dolt database (#6676) (#6724)
* fix(notion): keep notion.token out of the Dolt database (#6676)

notion.token was missing from YamlOnlyKeys, so `bd config set
notion.token` (the command `bd notion status` recommends) wrote the
token to the Dolt config table, whose contents `bd dolt push` sends to
the remote. The git-tracked-config guard never fired for it either,
because checkSecretGitTracked only considers yaml-only keys.

- Add notion.token to YamlOnlyKeys, next to github.token, gitlab.token,
  jira.api_token and ado.pat, so `bd config set` writes it to
  config.yaml and refuses a git-tracked config.yaml.
- Map notion.token to NOTION_TOKEN in secretKeyEnvVarHints so that
  refusal suggests the variable bd actually reads, not BD_NOTION_TOKEN.
- notion.ResolveAuth now reads config.yaml first, then the database,
  then NOTION_TOKEN. The database read is kept only so a token stored
  by an older bd keeps authenticating after an upgrade.
- resolveNotionAuth's no-store fallback goes through ResolveAuth, so a
  config.yaml token is found even when no store is open.
- The proxied `bd serve` settings integration test used notion.token as
  its credential-bearing key and read it back with `bd config get`,
  which now reads config.yaml; it uses notes.api_token instead.
- The DB-backed-secret guard test used notion.token as its example of a
  non-yaml secret key; it uses custom.api_token instead.
- Docs list notion.token with the other yaml-only secrets, and the
  quickstart leads with NOTION_TOKEN because `bd init` in a git repo
  leaves config.yaml tracked.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* fix(config,notion): delete leaked secret rows on unset; name the legacy auth source

Maintainer review fixes for #6724 (GH#6676).

Finding 1 (major, PR-introduced): moving notion.token into YamlOnlyKeys made
`bd config unset notion.token` return before the store, so a workspace that had
already leaked the token into the pushed config table lost its only bd-side
remover — exactly the population the PR exists to protect. configUnsetCmd now
best-effort deletes the database row for yaml-only SECRET keys and reports which
copies it removed. It is keyed on IsYamlOnlyKey+IsSecretKey rather than on
notion.token, so it closes the gap for the whole class; measured, that is at
least ado.pat, github.token, gitlab.token, jira.api_token, linear.api_key,
linear.oauth_client_secret and notion.token, plus whatever the prefix rules
(`ai.`, `sync.`, `federation.`, ...) admit. Non-secret yaml-only keys are gated
out before the store is opened, so an ordinary `bd config unset routing.mode`
still costs no database open. It reads before deleting because DeleteConfig
reports no miss, so the common never-leaked workspace stays silent instead of
announcing a removal that did not happen.

Finding 2 (major, pre-existing class): internal/notion/auth.go asserted "It must
never be written to the database" as an unqualified invariant while
PUT /v0/beads/config/notion.token still writes that row with no refusal. Scoped
the comment to the CLI door and named the HTTP/dashboard door as the known
remaining hole. Closing that door is deliberately NOT attempted here: it is a
cross-tracker change at workapi.ValidateSettingWrite/SetSetting on a
pre-existing surface, and belongs where every tracker credential gets the rule
at once.

Finding 3 (minor): the config.yaml token and the legacy row both reported
`config_token`, collapsing the safe case with the leaked one. Added
AuthSourceDatabaseLegacy plus a `bd notion status` rotation warning — the only
signal that gives the CHANGELOG's rotation advice an addressee.

Finding 4 (minor): pinned the end-to-end shape `bd config set` actually writes.
The finding cited internal/config/config.go:653 (setNestedKey), which is
SaveConfigValue's writer and not on this path — SetYamlConfig routes through
updateYamlKey/updateNestedYamlKey — but its conclusion held: the written shape
is nested. The new test drives the real writer rather than a second fixture, and
both its assertions were proven live by mutation (breaking the config.yaml read
trips the round-trip; forcing the flat fallback trips the non-vacuity guard,
while the round-trip alone still passed, which is why that guard exists).

Finding 5 (nit): both "not configured" errors led with `bd config set
notion.token`, which the new git-tracked refusal rejects in the default
post-`bd init` layout. They now lead with `export NOTION_TOKEN`, matching the
quickstart's ordering.

Also corrected the CHANGELOG, which still claimed unset clears config.yaml only.

Validation: ./internal/notion and ./internal/config green under `env -u
BEADS_DIR`. The cmd/bd notion/config tests are green except
TestConfigValidateReadOnlyIsHermetic and
TestGetNotionConfigReadsDBPathWhenStoreUnset, which fail identically at the PR
head with these fixes stashed (A/B in this same worktree) — ambient, not
introduced here.

--- Iteration 2 review fixes (one major, three minors, one nit) ---

Finding 1 (major, introduced by the iteration-1 fixup above): the cleanup
reached the store through openWorkspaceConfig -> ensureDirectMode ->
ensureStoreActive, which is open-OR-CREATE. So `bd config unset <yaml-only
secret>` in a workspace holding only .beads/config.yaml created a 2.1 MB
embedded Dolt database and flipped it out of db-less mode for every later
command -- from a command whose contract is "edit a YAML file", silently and
with exit 0. It also contradicted configCommandCanRunWithoutStore, which
classifies this exact invocation as runnable with no store precisely when
beads.FindDatabasePath() is empty. unsetLeakedSecretRow now returns early
rather than reach an open-OR-CREATE store in a workspace that has no database to
reach. The proxied route is exempt rather than gated --
proxiedWorkspaceConfig reaches an already-connected provider and creates
nothing, and a server-mode workspace legitimately has no local database
directory for FindDatabasePath to find, so gating it on the local path would
silently disable the cleanup exactly where the row is most replicated. Iteration 3 finishes
that thought: the same is true of the DIRECT server-mode route, which this gate
still skipped.

Finding 2 (minor): the remover ran only if the YAML unset succeeded first,
which skipped it for the population it exists for -- no config.yaml, or a shape
UnsetYamlConfig refuses. Base deleted the row there and the fixup did not, while
`bd notion status` names this very command as the remover. The cleanup now runs
either way, and a failed YAML unset carries the row's fate in its error instead
of telling the user to run `bd init` while a credential sits in the pushed
table.

Finding 3 (minor): a failed DELETE of a row the read had found was rendered as
"Could not check the database ..." under a JSON key asserting unreachability --
the one outcome that is certain, reported as the inconclusive one.
removeStoredSecretRow now returns the found bit alongside the error, and the
delete-failure case gets its own message and its own JSON keys
(database_row_present / database_delete_failed), carrying the rotation warning.

Finding 4 (minor): nothing pinned the command -> cleanup wiring; deleting the
call left every test green. The yaml-only branch is now runConfigUnsetYamlOnly
and four new tests drive configUnsetCmd itself against a recording settings
surface: the row is read, deleted and reported; a non-secret yaml-only key
touches the config plane zero times; --json carries the new keys; and .beads/ is
byte-unchanged (config.yaml aside) after unsetting a secret with no database
present.

Finding 5 (nit): CHANGELOG and docs/reference/configuration.md described the
dual removal unconditionally. Both now say the database half is best effort and
name the cases where it is skipped or refused.

Every new pin proven by mutation, one at a time, each failing only with its fix
removed: dropping the FindDatabasePath gate takes the no-database test into
embeddeddolt.OpenSQL (it really does provision); re-gating the cleanup behind
the YAML unset leaves the row undeleted and unmentioned; replacing the command's
cleanup call with a zero value drops the report and the --json field; returning
false for `present` on a failed delete puts database_unreachable back.

Complexity ledger flat by construction: worst_changed stays
showConfigYAMLOverrides at cyclomatic 17 / cognitive 29, which this PR does not
touch and which measures identically at the base blob. The extracted
runConfigUnsetYamlOnly is 6/9 and the three report helpers are at most 5/2.

Iteration 2 validation: ./internal/notion and ./internal/config green under
`env -u BEADS_DIR`; all nine cmd/bd leaked-secret/notion-auth tests green, one
-run per invocation (a batched regex shares rootCmd and produces false reds);
the CGO_ENABLED=0 gms_pure_go cmd/bd test binary still compiles (the new test
file is untagged, so it carries its own tree-snapshot helper rather than the
cgo-tagged twin); scripts/check-doc-flags.sh and `go test -tags=gms_pure_go
./test/docsync` pass for the docs edit.

--- Iteration 3 review fixes (two minors, both on the gate itself) ---

Finding 1 (minor, introduced by the iteration-2 gate above): "not proxied and no
local database directory" over-fires. findDatabaseInBeadsDir answers on
metadata.json plus embeddeddolt/ and dolt/, and it skips the stat for server mode
only when metadata.json is present -- so a metadata-less server workspace, whose
host comes from config.yaml or BEADS_DOLT_SERVER_HOST (main.go, GH#3545, the
shape gc provisions on every `gc-beads-bd start`), reports "" while its row sits
on the shared server, replicated to every remote it pushed to. The skip was not
buying anything there either: PersistentPreRun has already CONNECTED that
workspace's store, and ensureStoreActive early-returns on an active store without
opening or creating anything. For notion.token this was a narrow regression of a
base capability -- at base that key was not yaml-only, so `bd config unset
notion.token` took the database branch and deleted the row. The seven
pre-existing yaml-only secrets never had a remover at base, so for them the skip
withheld only new coverage, which is what holds this at minor. The gate is now
mayProvisionDatabase, which asks about the store before the disk; each arm that
returns false is a route where the database is already open -- proxied, or a
store already active and tracked, which is provably non-provisioning because it
is ensureStoreActive's own no-op arm.

Finding 2 (minor): neither arm of that gate had a behavioral test. Deleting the
!usesProxiedServer() clause left all four command-level tests green, and it is
the only thing keeping the cleanup alive for proxied workspaces, which have no
local database directory by construction -- the clause a later simplification is
most likely to read as redundant was the one clause nothing defended.
TestConfigUnsetCleansTheRowWithNoLocalDatabaseDirectory now pins both arms as the
mirror of TestConfigUnsetDoesNotProvisionADatabase: "no local database directory"
is the state all three share, so the route to the database is the only thing that
distinguishes them.

Both arms mutation-proved, one at a time, each red on exactly one subtest while
the four pre-existing command-level tests stayed green under both mutations:
deleting the active-store arm reproduces the finding verbatim (GetSetting calls =
[], UnsetSetting calls = [] for a connected server workspace, exit 0); deleting
the !usesProxiedServer() arm leaves the proxied workspace's row never looked for.
That second half -- the pre-existing suite staying green -- is the claim Finding 2
rests on, and only a run under the mutation can state it.

The CHANGELOG's "skipped where there is no database to hold a row" and the
matching sentence in docs/reference/configuration.md asserted exactly what the
gate got wrong; both now say it is skipped only where reaching the row would mean
creating a database, and that a server-mode or proxied workspace whose database
is simply not on local disk still gets the cleanup.

Complexity ledger still flat: worst_changed stays showConfigYAMLOverrides at
cyclomatic 17 / cognitive 29 (untouched, identical at the base blob), and
extracting the gate took unsetLeakedSecretRow from 6/5 to 5/4 with
mayProvisionDatabase at 4/3.

Iteration 3 validation: gofmt clean, `go build ./cmd/bd/`, `go vet ./cmd/bd/` and
`git diff --check` clean; the six leaked-secret/notion-auth tests and the four
command-level tests all green against the real fix, one -run per invocation under
a private TMPDIR (a batched regex shares rootCmd and produces false reds; a
sibling suite's sweep deletes shared temp roots mid-run); the CGO_ENABLED=0
gms_pure_go cmd/bd test binary still compiles; scripts/check-doc-flags.sh,
scripts/check-doc-freshness.sh and `go test -tags=gms_pure_go ./test/docsync`
pass for the docs edit (no new links, anchors or headings, so the render check
does not apply).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Julian Knutsen <julianknutsen@users.noreply.github.com>
2026-09-27 14:53:11 -07:00
..
advanced.md docs(events): document the events journal and bd events (bd-opisf) 2026-08-09 01:58:17 +00:00
antivirus.md docs: apply PR #4722 review feedback to user docs 2026-07-12 11:06:57 -07:00
configuration.md fix(notion): keep notion.token out of the Dolt database (#6676) (#6724) 2026-09-27 14:53:11 -07:00
events-journal.md fix(events): journal delete and cascade dep_remove rows carry the request actor; notice when reading a disabled journal (#5985) (#6061) 2026-08-29 04:14:23 -07:00
faq.md docs(troubleshooting): document the two native-Windows integration traps (#5838) 2026-08-20 05:41:39 -07:00
git-integration.md Accept uutils coreutils timeout in generated hooks, and check the shims against real implementations (#6561) 2026-09-27 03:38:45 -07:00
index.md docs(events): document the events journal and bd events (bd-opisf) 2026-08-09 01:58:17 +00:00
json-schema.md fix(contracts): JSON contract fixes before 1.3.0 freezes them — string revision tokens, --set-metadata scalar typing, create --json nano timestamps (#6053) 2026-08-29 05:20:27 +00:00
observability.md refactor(telemetry): adopt standard OTel SDK env vars with BD_OTEL_* back-compat (#3859) 2026-08-03 00:05:06 -07:00
protected-branches.md docs: apply PR #4722 review feedback to user docs 2026-07-12 11:06:57 -07:00
troubleshooting.md Accept uutils coreutils timeout in generated hooks, and check the shims against real implementations (#6561) 2026-09-27 03:38:45 -07:00
worktrees.md fix(init): bootstrap Git in the selected project directory (#6459) 2026-09-27 13:16:05 -07:00