Store/Open core + in-memory backend (credstore §2.1)

[rianjs]

Tracks Jira INT-430 (child of epic INT-310). Second discrete unit of cli-common; builds on #1 (ref grammar, merged in #2).

Scope

• Store + Open(service string, opts *Options) (*Store, error) + (*Store).Close() error
• (*Store).Backend() (Backend, Source) reporting (required for later config show, §1.6)
• Options: AllowedKeys []string allowlist; Backend selector incl. BackendMemory
• Internal backend interface; in-memory backend with no disk side effects (§2.1 test/CI backend)
• Single-key ops: Get/Set/Delete/Exists(profile, key); SetOpt with Overwrite (§1.5)
• Profile/key syntax validation (reuse §1.3 ref helpers) + AllowedKeys enforcement on Set/Delete with a clear allowed-set error (§1.5.2)
• <service>/<profile>/<key> → ServiceName + <profile>/<key> Item.Key mapping modeled internally so real backends slot in later (§1.3)
• Tests against the in-memory backend (round-trip, overwrite semantics, allowlist rejection, validation)

Out of scope (later INT-310 units)

Real OS backends + auto/env/config selection (PR4), ListBundle/DeleteBundle, SetBundle atomicity (PR3), Linux fail-closed (PR5), redaction (PR6), migration helpers (PR7).

[rianjs]

INT-430 — cli-common: Store/Open core + in-memory backend (credstore §2.1)

Epic: INT-310. GitHub: #3. Builds on INT-429
(ref grammar, merged in PR #2). Standard: working-with-secrets.md §2.1
(API surface), §1.3 (service/profile/key mapping), §1.5/§1.5.2 (overwrite,
allowed-key enforcement).

Goal

The service-scoped Store plumbing and the in-memory backend, with
single-key operations and allowed-key enforcement. This is the foundation
every later unit (bundle ops, real OS backends, redaction, migration)
builds on. No OS-touching code in this unit.

One PR off feat/INT-430-store-memory-backend.

Scope

New files: credstore/store.go, credstore/memory.go,
credstore/store_test.go. Reuses ref.go's validSegment (same package)
for profile/key syntax — no duplication.

Types & API

type Backend string
const (
    BackendKeychain      Backend = "keychain"       // macOS — PR4
    BackendWinCred       Backend = "wincred"        // Windows — PR4
    BackendSecretService Backend = "secret-service" // Linux — PR4
    BackendFile          Backend = "file"           // encrypted file — PR4
    BackendMemory        Backend = "memory"         // tests/CI, no disk
)

type Source string
const (
    SourceAuto     Source = "auto"     // OS default — wired PR4
    SourceEnv      Source = "env"      // <SERVICE>_KEYRING_BACKEND — PR4
    SourceConfig   Source = "config"   // keyring.backend in config — PR4
    SourceExplicit Source = "explicit" // Options.Backend set by caller
)

type Options struct {
    AllowedKeys []string // §2.1/§1.5.2 allowlist; empty => syntax-only
    Backend     Backend  // only BackendMemory selectable this unit
}

type SetOpt func(*setOptions)
func WithOverwrite() SetOpt // §1.5 overwrite semantics

type Store struct { /* unexported */ }

func Open(service string, opts *Options) (*Store, error)
func (s *Store) Close() error
func (s *Store) Backend() (Backend, Source)
func (s *Store) Get(profile, key string) (string, error)
func (s *Store) Set(profile, key, value string, opts ...SetOpt) error
func (s *Store) Delete(profile, key string) error
func (s *Store) Exists(profile, key string) (bool, error)

Sentinels / typed errors (all errors.Is-matchable):
ErrNotFound, ErrExists, ErrStoreClosed, ErrBackendNotImplemented;
*KeyError{Key, Allowed} with ErrKeyNotAllowed sentinel and a message
listing the allowed set (§1.5.2). Profile/key/service syntax errors
reuse *RefError with Segment set to "service"|"profile"|"key".

Behavior

• Open(service, opts): validate service syntax (reuse
  validSegment → *RefError{Segment:"service"} on failure; nil/empty
  → error). Backend selection:
  • opts.Backend == BackendMemory → memory backend, SourceExplicit.
  • unset ("", or opts == nil) or any OS backend value → return
    ErrBackendNotImplemented naming the requested backend and pointing
    at BackendMemory. Deliberate fail-closed: production code must
    never silently fall back to an in-memory store; real selection is PR4.
• Item-key mapping (§1.3): internal joinItemKey(profile, key)
  validates each segment (validSegment) and returns profile + "/" + key or *RefError{Segment:"profile"|"key"}. This is the
  Item.Key = <profile>/<key> half of the standard's mapping; service
  is the ServiceName half (held on the Store for Backend() /
  future real backends).
• Set: validate profile+key syntax; enforce allowlist (if
  AllowedKeys non-empty and key ∉ set → *KeyError); if not
  WithOverwrite() and entry exists → ErrExists (per-key pre-write,
  §1.5; per-bundle atomic pre-write is PR3); else write.
• Delete: validate syntax; enforce allowlist (§1.5.2 lists
  Set/Delete); missing entry → ErrNotFound.
• Get / Exists: validate syntax only — not allowlist. §1.5.2
  enumerates Set/SetBundle/Delete for allowlist enforcement; read paths
  are intentionally not gated (a key written before an allowlist change
  must remain readable). Documented inline, traceable to §1.5.2.
• Get missing → ErrNotFound. Backend() → (BackendMemory, SourceExplicit).
• Close: zero stored values then drop the map; idempotent and safe
  to call repeatedly (§2.1). Any op after Close → ErrStoreClosed.
• Memory backend: map[string]string + sync.Mutex (race-safe;
  per-Store, created in Open). No disk side effects — the §2.1
  CI/test backend. Internal backend interface
  (get/set/delete/exists/kind) so PR4's real backends slot in unchanged.

Tests (store_test.go, table-driven, -race)

• Open: memory ok; nil opts → ErrBackendNotImplemented; unset/OS
  backend → ErrBackendNotImplemented; invalid/empty service →
  *RefError (Segment=="service").
• Round-trip Set→Get→Exists→Delete→Get(ErrNotFound).
• Set existing w/o overwrite → ErrExists; with WithOverwrite() →
  replaces; Get returns new value.
• Delete missing → ErrNotFound.
• Allowlist: Set/Delete disallowed key → errors.Is ErrKeyNotAllowed
  and message lists allowed set; Get/Exists of a disallowed-but-
  syntactically-valid key is not allowlist-blocked. Empty
  AllowedKeys → any valid key accepted.
• Invalid profile/key syntax (space, ., /, empty) → *RefError with
  correct Segment.
• Close idempotent (twice, no error); op after Close →
  ErrStoreClosed.
• Concurrency: parallel Set/Get under -race (no data race).

Verification

• go build ./..., go test -race ./..., golangci-lint run, gofmt -l
  (empty), tidy gate — all clean locally and in CI (still stdlib-only).
• All §1.11-relevant behaviors for this unit observable via the tests
  above; each test asserts a concrete error sentinel / value, not "works".

Out of scope (later INT-310 units)

Real OS backends + auto/env/config selection (PR4), ListBundle /
DeleteBundle, SetBundle atomicity + per-bundle pre-write (PR3), Linux
fail-closed (PR5), redaction (PR6), migration helpers (PR7), config show/clear surfaces, v0.1.0 tag.