Credentials — Storage Mode Taxonomy¶

pkg/credentials is the shared taxonomy for how GTB — and tools built on GTB — persist user-supplied secrets. It defines three storage modes, a Backend interface, a capability check (KeychainAvailable), a live-reachability probe (Probe), and two sentinel errors. Consumers include the interactive setup wizards (pkg/setup/ai, pkg/setup/github), the runtime credential resolvers (pkg/chat, pkg/vcs), the doctor subsystem, and the config masker.

The OS-keychain implementation lives in a dedicated subpackage (gitlab.com/phpboyscout/go-tool-base/pkg/credentials/keychain). Downstream tools opt in by blank-importing that package from their cmd/*/main; regulated or air-gapped consumers omit the import, run with the stub backend, and Go's linker dead-code elimination keeps go-keyring, godbus, and wincred out of their linked binary. SBOM tools that inspect the compiled artefact (syft, cyclonedx-gomod on the linked binary) see a clean dependency surface in that case.

Storage Modes¶

Three Mode values are supported:

ModeEnvVar is the recommended default and the only mode permitted under CI=true. ModeLiteral is supported for backward compatibility and throwaway environments; the setup wizard refuses it under CI and the doctor credentials.no-literal check warns on its presence.

API¶

import (
    "context"

    "gitlab.com/phpboyscout/go-tool-base/pkg/credentials"
)

// Which modes can this build offer to the user?
modes := credentials.AvailableModes()
// -> without keychain subpackage imported: [ModeEnvVar, ModeLiteral]
// -> with keychain subpackage imported:   [ModeEnvVar, ModeKeychain, ModeLiteral]

// Is a keychain-capable backend registered?
if credentials.KeychainAvailable() {
    // ModeKeychain is a possible option — but still gate the UI
    // on Probe() before offering it, because a headless Linux host
    // without a Secret Service provider or a locked macOS keychain
    // will reject writes at use time.
}

// Is the keychain reachable right now? Performs a canary
// Set→Get→Delete round-trip. Short-circuits to false when the stub
// backend is installed, so callers can use Probe alone as the gate.
// Pass a bounded context to guard against remote backends that hang.
ctx, cancel := context.WithTimeout(parentCtx, 5*time.Second)
defer cancel()
if credentials.Probe(ctx) {
    // offer ModeKeychain in the setup UI
}

// Backend operations. Fail with ErrCredentialUnsupported under the
// stub backend; wired to go-keyring when the keychain subpackage is
// imported.
err := credentials.Store(ctx, "mytool", "github.auth", secret)
token, err := credentials.Retrieve(ctx, "mytool", "github.auth")
err = credentials.Delete(ctx, "mytool", "github.auth")

The returned slice from AvailableModes is always ordered: env-var first, keychain (if available) next, literal last. Callers that present modes to the user can render them in this order without additional sorting. Probe is idempotent and safe to call from any goroutine.

Backend interface¶

type Backend interface {
    Store(ctx context.Context, service, account, secret string) error
    Retrieve(ctx context.Context, service, account string) (string, error) // must return ErrCredentialNotFound on a clean miss
    Delete(ctx context.Context, service, account string) error             // idempotent
    Available() bool
}

// Swap the active backend — typically during main() init.
credentials.RegisterBackend(myBackend)

Every method takes a context.Context so remote-store backends (Hashicorp Vault, AWS SSM, 1Password Connect) honour deadlines and cancellation. OS-keychain backends accept the context for interface uniformity but don't propagate it — platform APIs (Keychain Services, Secret Service, Credential Manager) don't expose cancellation. See docs/how-to/custom-credential-backend.md for a worked example implementing a custom backend.

The zero-dep default backend is stubBackend; every call returns ErrCredentialUnsupported. credtest.MemoryBackend (in pkg/credentials/credtest) is an in-process implementation useful for unit tests of resolvers and setup flows without touching the host keychain.

Sentinel Errors¶

Both wrap cleanly with errors.Is / errors.As and neither embeds credential material in its message.

Activating the keychain backend¶

To activate OS keychain support in a tool built on GTB:

// cmd/mytool/main.go
import (
    _ "gitlab.com/phpboyscout/go-tool-base/pkg/credentials/keychain"  // registers Backend at init
    // …
)

The blank import runs the subpackage's init(), which calls credentials.RegisterBackend with a go-keyring-backed Backend. From that point on, KeychainAvailable() reports true, AvailableModes() includes ModeKeychain, and Probe() performs its live round-trip.

Tools that want to strip keychain support from a regulated build remove the blank import (or put it in a dedicated file like cmd/mytool/keychain.go that's easy to delete per build). With no import, Go's linker dead-code elimination keeps go-keyring, godbus, and wincred out of the binary — nothing reaches a D-Bus session bus, and the SBOM of the linked artefact is clean. The same mechanism gates keychain in cmd/gtb itself: deleting cmd/gtb/keychain.go and rebuilding produces a keychain-free gtb binary.

Note: the go-keyring dep chain is listed in the root module's go.mod as // indirect because cmd/gtb uses it by default. A binary-level SBOM remains the source of truth for what's actually linked into a specific artefact — source-level SBOMs generated from go.sum alone will show the full chain and require filtering against build-graph reachability.

Consumers¶

Trust Model¶

Full trust-model guidance is in docs/development/security-decisions.md.

Spec and Status¶

Phases 1 and 2 of 2026-04-02-credential-storage-hardening.md are implemented: env-var reference as the default, keychain mode behind an opt-in subpackage import with Probe()-gated wizard UX, and Bitbucket JSON-blob support. Phase 3 (the config migrate-credentials command and the GitHub OAuth+display-once flow) is still pending.