chore: upstream opt-out build tag to ByteNess/keyring for the 1Password backends

[rianjs]

Commitment

Submit an upstream PR to ByteNess/keyring adding an opt-out build tag that excludes the 1Password backends at compile time. Decided 2026-06-11 during #55 execution; #55 documents the trade-off in working-with-secrets.md §1.10 in the meantime. We have read-only access to the upstream repo, so this is a fork-and-PR; ByteNess has historically been responsive.

Why

The keyring root package imports its 1Password openers unconditionally, so credstore → byteness/keyring → onepassword-sdk-go (pre-1.0) → extism/go-sdk → wazero (plus connect-sdk-go → jaeger-client-go, archived upstream) compiles into every consumer binary. Measured on slck (2026-06-11, keyring v1.9.3):

• 63 packages from these trees in go list -deps ./credstore
• 5,393 surviving symbols in the shipped binary — no dead-code elimination (init-registered openers)
• ~10.6 MB of attributable symbol bytes (go tool nm -size)

This is a credential library carrying a WASM runtime and a beta SDK on every consumer's security-audit surface, for backends our standard already declines to expose (working-with-secrets.md §1.10).

PR design (validated against v1.9.3 source)

The library uses a self-registration pattern: each backend file's init() adds itself to supportedBackends (keyring.go:54). The five op files (opcommon.go, opstandard.go, opconnect.go, opdesktop.go, opsrvaccount.go) are the only importers of the 1Password SDKs and already carry //go:build !freebsd. The PR:

1. Changes those files' constraint (plus _test.go siblings) to //go:build !freebsd && !keyring_no1password (final tag name at upstream's discretion — but it must be opt-out polarity so default builds are byte-for-byte unchanged).
2. Adds a CI smoke leg: go build -tags keyring_no1password ./... + go vet, so the gated variant can't rot.
3. README note documenting the tag.

Behavior under the tag: the op init()s never run, supportedBackends never gets the op entries, and requesting an op backend hits the existing "unsupported backend" error path — same as wincred-on-Linux today. The OPBackend constants and Config.OP* fields live in ungated files with no SDK imports, so there is no API change.

Generalization (optional, raise in the PR discussion)

Surveyed v1.9.3: the op trio is the only heavy tree. pass/passage shell out (stdlib only); kwallet/secret-service share the small dbus lib; wincred/keyctl are trivial. So a single keyring_no1password tag captures ~all the win today. If upstream prefers generality, a per-backend tag family (keyring_no<backend>) is the natural shape — worth offering as an alternative in the PR description, not worth building unprompted.

Known limits

• The tag removes compiled surface (binary size, govulncheck-reachable findings). The modules stay in the module graph / go.sum, so module-level dependabot alerts can still fire; only an upstream repo/module split would remove those.

After upstream merges

• Repin byteness/keyring in cli-common
• Add the tag to cli-common's CI build/test invocations
• Add the tag to each consumer CLI's Makefile, ci.yml, and .goreleaser flags: (rides the next repin train; update the §1.10 note in working-with-secrets.md to reflect the tag as the standard build configuration)

Refs: #55 (quantification + interim documentation), #54 (standards review that surfaced this).

[rianjs]

Draft issue text for ByteNess/keyring (not yet submitted — for review)

---

Title: Proposal: per-backend opt-out build tags for the cross-platform backends

What

We'd like to add a family of opt-out Go build tags — keyring_no<backend> — covering the backends that aren't already excluded by GOOS constraints, so downstream consumers can drop the backends they never use (and their dependency trees) from compilation. Default builds (no tags) remain byte-for-byte unchanged; each tag is purely subtractive for the consumer who opts out. The 1Password backends are the motivating case, but the per-backend convention means any future SDK-backed backend arrives with a gate by default instead of needing this conversation again.

Why

Backends self-register via init() and are imported unconditionally by the root keyring package, so the linker cannot dead-code-eliminate them — every importer compiles every cross-platform backend's full dependency tree, used or not.

The platform-specific backends are already effectively gated: keychain (darwin && !ios && cgo), wincred (windows), and secret-service/kwallet/keyctl (linux) never compile off-platform, so they need no tags. The backends below ride along in every build; this is what a consumer could opt out of:

Backend	Proposed tag	Third-party deps	Weight
op / op-connect / op-desktop	keyring_no1password (one tag — the trio shares opcommon.go and the SDK tree)	onepassword-sdk-go → extism/go-sdk → wazero, dylibso/observe-sdk → OTel protos; connect-sdk-go → jaeger-client-go + jaeger-lib + opentracing-go	A pre-1.0 SDK on the credential path; a full WebAssembly runtime (wazero); and jaeger-client-go, archived upstream — all permanently on the consumer's vuln-scan/audit surface despite never being callable. Measured on a real consumer binary (v1.9.3): 63 packages, 5,393 surviving symbols, ~10.6 MB.
file	keyring_nofile	dvsekhvalnov/jose2go, byteness/percent	jose2go is a JOSE crypto implementation with a prior security advisory (the PBES2 p2c denial-of-service, fixed in v1.6.0) — small in bytes, but crypto code is exactly what consumers' audits scrutinize. Valuable for OS-keyring-or-nothing deployments.
pass	keyring_nopass	none — shells out to the pass binary	No dependency tree; a few KB of wrapper code. Included for convention-completeness.
passage	keyring_nopassage	none — shells out to passage	Same.

(For anyone wondering about KeePass: KeePassXC speaks the Secret Service D-Bus API, so it's served by the existing linux-gated secret-service backend — no separate tree exists.)

Proposed change

The op files already carry a build constraint (//go:build !freebsd), so this follows the existing pattern:

1. Add the tag to each gated backend's files (and _test.go siblings): e.g. opcommon.go/opstandard.go/opconnect.go/opdesktop.go/opsrvaccount.go become //go:build !freebsd && !keyring_no1password; file.go gains //go:build !keyring_nofile; pass.go/passage.go gain the analogous constraint alongside their existing !windows.
2. Add one CI smoke leg building with all tags at once (go build -tags keyring_no1password,keyring_nofile,keyring_nopass,keyring_nopassage ./... + go vet), alongside the existing default build — the two extremes bracket every combination, since each tag only removes whole files and the gated files don't reference each other across tag groups.
3. README section documenting the tag family.

Under a tag, that backend's init() never runs, supportedBackends never gains its entry, and requesting it hits the existing "unsupported backend" error path — the same behavior as requesting an unavailable platform backend today. The BackendType constants and Config fields live in ungated files with no SDK imports, so there is no API change for anyone.

We're glad to submit this as a PR if the approach sounds acceptable — including the CI addition — and to adjust tag names/polarity to whatever convention you prefer (we'd only ask that the default stays opt-out, so existing consumers see zero change). If you'd rather take just the high-value gate, a keyring_no1password-only version of this PR is fine by us too.

---

Posting here for review before opening anything in the upstream repo. Edits welcome.

[rianjs]

Upstream proposal posted: ByteNess/keyring#93 (per-backend opt-out tag family, leading with keyring_no1password). Remaining on this issue: follow up with the implementation PR if the proposal is accepted, then the post-merge checklist in the body (repin, cli-common CI tags, consumer Makefile/ci/goreleaser -tags rollout).

[rianjs]

Plan: per-backend opt-out build tags (ByteNess/keyring#93)

Repo: ~/dev/keyring (fork rianjs/keyring, upstream ByteNess/keyring, main @ 82c097f / v1.10.2).
Ticket: ByteNess/keyring#93 — add a keyring_no<backend> opt-out
build-tag family for the cross-platform backends so consumers can drop unused backends
(and their dependency trees) at build time. Invariant for default (untagged) builds: no API,
behavior, or package-import-graph change (go.mod is untouched; pruning happens in
consumers' compiled-package deps, not the module graph) — the only delta to default-built artifacts is build
metadata (constraint headers shift debug line info), which go build/vet/test parity
plus an unchanged go list -deps . output verifies.

Verified ground truth (current main)

• Backends self-register via init() into supportedBackends (keyring.go:56); requesting
  an unregistered backend hits the existing "unsupported backend" error in Open.
• All BackendType constants and backendOrder live in ungated keyring.go; all Config
  fields live in ungated config.go. Neither imports any SDK → no API change under any tag.
• Current constraints: op source files //go:build !freebsd; pass.go/pass_test.go
!windows (with legacy // +build line in both); passage.go/passage_test.go !windows;
  file.go/file_test.go unconstrained.
• Gated-symbol usage in tests is exactly file-sibling-shaped:
  • op symbols: opstandard_test.go, opconnect_test.go, opdesktop_test.go,
    opsrvaccount_test.go, optestutil_test.go (op-only helpers), mocks_test.go
    (mockery-generated, mocks OPConnectClientAPI/OPStandardClientAPI, imports both
    1Password SDKs, currently has no constraint — latent freebsd test breakage today).
  • FileBackend/file internals: file_test.go only.
  • pass/passage internals: pass_test.go/passage_test.go only — except the shared
    helper runCmd (pass_test.go:16), which passage_test.go also calls. Under
    keyring_nopass alone, passage_test.go would fail to compile; runCmd must move to
    a neutral helper file.
• mocks_test.go is generated by mockery v3 (.mockery.yml, template: testify,
  force-file-write: true) — a hand-added constraint would be clobbered on regen, so the
  constraint must come from mockery's mock-build-tags config key.
• CI: test.yaml (linux/mac/windows, go test -race ./...), lint.yaml (go vet -all ./...
  3-OS matrix). No Makefile.

Changes

1. Build constraints (the core change)

Files	Constraint before	Constraint after
opcommon.go, opstandard.go, opconnect.go, opdesktop.go, opsrvaccount.go	//go:build !freebsd	//go:build !freebsd && !keyring_no1password
opstandard_test.go, opconnect_test.go, opdesktop_test.go, opsrvaccount_test.go, optestutil_test.go	(none)	//go:build !freebsd && !keyring_no1password
mocks_test.go	(none)	same, via .mockery.yml mock-build-tags: '!freebsd && !keyring_no1password' + regenerate (or hand-apply identical header if mockery unavailable locally; config key still committed so the next regen preserves it)
file.go, file_test.go	(none)	//go:build !keyring_nofile
pass.go, pass_test.go	!windows (+legacy +build)	//go:build !windows && !keyring_nopass (intentionally drop the legacy // +build line rather than updating it — go.mod is Go 1.26, far past the 1.17 cutoff; gofmt does not remove it on its own)
passage.go, passage_test.go	!windows	//go:build !windows && !keyring_nopassage
cmdtestutil_test.go (new)	—	//go:build !windows — receives runCmd moved verbatim from pass_test.go so passage_test.go compiles under keyring_nopass (only cross-tag-group reference found)

Test siblings get the same constraint as their sources because go vet -tags ... and
go test -tags ... typecheck _test.go files; ungated op tests would break the all-tags
CI leg (and are already broken on freebsd today — this fixes that ride-along, no extra scope).

2. Tag-gated regression test (new file optout_test.go)

//go:build keyring_no1password && keyring_nofile && keyring_nopass && keyring_nopassage

One test, TestOptOutTagsExcludeBackends, asserting for each of
OPBackend, OPConnectBackend, OPDesktopBackend, FileBackend, PassBackend,
PassageBackend:

• Open(Config{AllowedBackends: []BackendType{b}}) returns the unsupported-backend error
  (match the exact error text/type used in keyring.go), and
• AvailableBackends() does not contain b.

This is the only test that proves the tags actually de-register backends; it compiles to
nothing in default builds (zero default-build impact) and runs only in the new CI leg.

3. CI smoke leg (test.yaml, new job opt-out-tags)

Single ubuntu job, no extra apt deps (the gated test only exercises the in-process error path):

opt-out-tags:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v6
    - uses: actions/setup-go@v6
      with:
        go-version-file: 'go.mod'
        check-latest: true
    - run: go build -tags keyring_no1password,keyring_nofile,keyring_nopass,keyring_nopassage ./...
    - run: go vet -all -tags keyring_no1password,keyring_nofile,keyring_nopass,keyring_nopassage ./...
    - run: go test -race -run 'TestOptOutTagsExcludeBackends' -tags keyring_no1password,keyring_nofile,keyring_nopass,keyring_nopassage ./...

Rationale (from the issue): default build + all-tags build bracket every combination, since
each tag only removes whole files and no gated file may reference a symbol from a different
tag group. That precondition is established by the runCmd move above and verified
locally by the per-tag build+vet matrix (Verification step 3); CI carries only the two
bracket extremes. -run filter keeps the leg free of the pass/gnome-keyring setup the main
linux job needs.

4. README section

Short "Reducing the dependency surface (opt-out build tags)" section: the four tags, one-line
table (tag → backend(s) removed → headline deps dropped), example
go build -tags keyring_no1password ./..., and the note that excluded backends return the
standard unsupported-backend error and the API is unchanged.

Out of scope (surgical boundary)

• No changes to backend ordering, Config, error types, or any runtime logic.
• No go.mod changes — module graph pruning happens in consumers' builds; this repo's
  go.mod legitimately keeps all deps.
• No gating of platform backends (already GOOS-gated) and no winhello tag.
• No cli-common/consumer rollout (tracked separately in chore: upstream opt-out build tag to ByteNess/keyring for the 1Password backends #57).

Verification (each step has a concrete check)

1. Default build unchanged: go build ./... && go vet -all ./... && go test -race ./...
   pass exactly as on main (run on main first for a baseline; note any pre-existing
   env-dependent failures, e.g. missing pass/passage binaries on this machine), and
   go list -deps . output is identical to main's (default package import graph untouched).
2. All-tags leg locally: the three smoke-leg commands above exit 0; the new test runs
   and passes.
3. Each tag individually compiles and typechecks tests:
   go build -tags keyring_noX ./... && go vet -all -tags keyring_noX ./... && go test -run '^$' -tags keyring_noX ./...
   × 4 exits 0 (go test -run '^$' compiles the test binary without executing tests — the
   direct check that catches cross-tag-group test references like the runCmd case).
4. Dependency tree actually shrinks, including test deps:
   go list -deps -tags keyring_no1password . | grep -c -e 1password -e wazero -e jaeger -e extism → 0,
   and go list -deps -test -tags keyring_no1password . | grep -c -e 1password -e extism → 0
   (the -test form catches mocks_test.go still pulling the SDKs if its gate is wrong);
   both greps non-zero without the tag. Same shape for keyring_nofile vs jose2go.
5. Mockery regen stable: if mockery is runnable locally, regenerate and confirm
   git diff mocks_test.go is only the constraint header; otherwise confirm the committed
   header matches what mock-build-tags emits per mockery docs and note it in the PR.
6. CI: all existing jobs + the new leg green on the PR.

Delivery

• Branch feat/93-backend-opt-out-tags; commits reference #93.
• Review loop (Codex/TDD/daemon) runs on a fork-internal PR in rianjs/keyring to keep
  bot traffic off upstream; once converged and green, open the real PR
  ByteNess/keyring:main ← rianjs:feat/93-backend-opt-out-tags with a clean description
  ("Closes #93"-style wording per upstream convention — Fixes #93). Upstream merge is the
  maintainers' call; no merge step on our side.

[rianjs]

Implementation PR opened upstream: ByteNess/keyring#94 (CI green on the fork, incl. the new opt-out-tags leg). Once merged + released upstream, the post-merge checklist in the body kicks in: repin byteness/keyring, add the tags to cli-common CI, roll -tags into consumer Makefiles/ci/goreleaser.

[rianjs]

Rollout progress:

• ✅ Upstream shipped: byteness/keyring v1.11.0 contains the opt-out tags (feat: add per-backend opt-out build tags for the cross-platform backends ByteNess/keyring#94 merged).
• ✅ cli-common repinned to v1.11.0, CI now builds+tests credstore with keyring_no1password,keyring_nopassage, and working-with-secrets §1.10 makes the tag pair normative build configuration (chore: adopt byteness/keyring v1.11.0 opt-out tags as standard build configuration #59, released as v0.3.2).
• ⬜ Consumer rollout: bump cli-common → v0.3.2 and add -tags keyring_no1password,keyring_nopassage to Makefile / ci.yml / .goreleaser flags: in each CLI.

Tag-set rationale recorded in §1.10: keyring_nofile / keyring_nopass are excluded because credstore exposes the file and pass backends in cgo builds.