Go Keyring

https://github.com/zalando/go-keyring
Admin
Go Keyring is an OS-agnostic library for setting, getting, and deleting secrets from the system...
Tokens:21,142
Snippets:292
Trust Score:8.3
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Shared Mock Setup

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/api-reference/mockrestore.md

Example of using a helper function to manage mock initialization and restoration across multiple tests.

```go
package myapp

import (
	"testing"
	"github.com/zalando/go-keyring"
)

func setupMockKeyring(t *testing.T) func() {
	keyring.MockInit()
	return func() {
		keyring.MockRestore()
	}
}

func TestFeatureA(t *testing.T) {
	defer setupMockKeyring(t)()
	// Test with mock
}

func TestFeatureB(t *testing.T) {
	defer setupMockKeyring(t)()
	// Test with mock, provider is fresh
}
```

--------------------------------

### Automatic Library Initialization

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/configuration.md

The library initializes automatically upon use, requiring no explicit setup or constructor calls.

```go
// Initialization is automatic; no setup required
password, err := keyring.Get("service", "user")
```

--------------------------------

### Set and Get secrets with go-keyring

Source: https://github.com/zalando/go-keyring/blob/master/README.md

Demonstrates basic usage of the keyring package to store and retrieve a password for a specific service and user.

```go
package main

import (
    "log"

    "github.com/zalando/go-keyring"
)

func main() {
    service := "my-app"
    user := "anon"
    password := "secret"

    // set password
    err := keyring.Set(service, user, password)
    if err != nil {
        log.Fatal(err)
    }

    // get password
    secret, err := keyring.Get(service, user)
    if err != nil {
        log.Fatal(err)
    }

    log.Println(secret)
}
```

--------------------------------

### Basic Mock Usage in Tests

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/api-reference/mockinit.md

Demonstrates initializing the mock provider and performing basic set and get operations within a test function.

```go
package myapp

import (
	"testing"
	"github.com/zalando/go-keyring"
)

func TestConfigWithCredentials(t *testing.T) {
	// Initialize mock provider
	keyring.MockInit()
	defer keyring.MockRestore()
	
	// Test code can now set and get credentials
	err := keyring.Set("test-service", "testuser", "testpass")
	if err != nil {
		t.Fatalf("Mock Set failed: %v", err)
	}
	
	password, err := keyring.Get("test-service", "testuser")
	if err != nil {
		t.Fatalf("Mock Get failed: %v", err)
	}
	
	if password != "testpass" {
		t.Errorf("Expected 'testpass', got %q", password)
	}
}
```

--------------------------------

### Data Round-Trip Preservation Example

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/platform-specifics.md

Illustrates how different platforms handle password byte preservation during the Set and Get cycle.

```text
Original: "password\nwith\nnewlines\nand\némojis🔒"
macOS:    base64 encode → store → retrieve → base64 decode → original
Windows:  store as bytes → retrieve as bytes → original
Linux:    UTF-8 detect → store → retrieve → original
```

--------------------------------

### func MockInit()

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/api-reference/mockinit.md

Initializes an in-memory mock provider for the keyring, replacing the platform-specific implementation. This allows tests to perform keyring operations like Set, Get, and Delete without interacting with the actual system keyring.

```APIDOC
## func MockInit()

### Description
Replaces the platform-specific keyring provider with an in-memory mock provider that stores credentials in a simple nested map structure. All subsequent calls to `Set`, `Get`, `Delete`, `DeleteAll`, and `ListUsers` operate on the mock store instead of the system keyring.

### Signature
`func MockInit()`

### Parameters
None

### Return Value
- **Type**: `void`
- **Description**: No return value.
```

--------------------------------

### Install Secret Service Dependencies

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/configuration.md

Commands to install necessary Secret Service providers and tools on various Linux distributions.

```bash
sudo apt-get install gnome-keyring
sudo apt-get install libsecret-tools  # optional: for secret-tool CLI
```

```bash
sudo dnf install gnome-keyring
sudo dnf install libsecret  # includes secret-tool
```

```bash
sudo pacman -S gnome-keyring
sudo pacman -S libsecret
```

--------------------------------

### Install secret-tool on Linux

Source: https://github.com/zalando/go-keyring/blob/master/README.md

Commands to install libsecret-tools on various Linux distributions.

```bash
# Debian/Ubuntu
sudo apt-get install libsecret-tools

# Fedora/RHEL
sudo dnf install libsecret

# Arch Linux
sudo pacman -S libsecret
```

--------------------------------

### Perform Basic Credential Operations

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/README.md

Standard methods for managing credentials including setting, getting, listing, and deleting entries.

```go
// Store a credential
err := keyring.Set("my-app", "username", "password")

// Retrieve a credential
password, err := keyring.Get("my-app", "username")

// List all stored users for a service
users, err := keyring.ListUsers("my-app")

// Delete a specific credential
err := keyring.Delete("my-app", "username")

// Delete all credentials for a service
err := keyring.DeleteAll("my-app")
```

--------------------------------

### Test with Mock Cleanup

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/api-reference/mockrestore.md

Example of using MockRestore within a standard Go test function.

```go
package myapp

import (
	"testing"
	"github.com/zalando/go-keyring"
)

func TestWithMockCleanup(t *testing.T) {
	keyring.MockInit()
	defer keyring.MockRestore()
	
	// Mock operations
	keyring.Set("service", "user", "password")
	// ... test assertions ...
}
```

--------------------------------

### Get Operation Data Flow

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/architecture.md

Describes the delegation and platform-specific retrieval steps when getting a credential.

```text
User: keyring.Get("github", "token")
  ↓
package.Get() delegates to provider.Get()
  ↓
macOS implementation:
  - Execute: security find-generic-password -s "github" -wa "token"
  - Decode: check for base64 prefix, decode if present
  - Return: decoded password string
  ↓
Windows implementation:
  - Look up: wincred.GetGenericCredential("github:token")
  - Extract: cred.CredentialBlob as string
  - Return: password string
  ↓
Linux/BSD implementation:
  - Open D-Bus session
  - Search: items with service="github" and username="token"
  - Get Secret: unlock item if needed
  - Extract: secret.Value as string
  - Return: password string
```

--------------------------------

### func Get(service, user string) (string, error)

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/api-reference/get.md

Retrieves a previously stored password from the system keyring. The function handles platform-specific implementation details and encoding automatically.

```APIDOC
## func Get(service, user string) (string, error)

### Description
Retrieves a previously stored password from the system keyring. The operation is transparent across platforms, handling platform-specific storage mechanisms and automatic decoding where applicable.

### Parameters
- **service** (string) - Required - Service identifier that was used to store the credential
- **user** (string) - Required - Username/account identifier that was used to store the credential

### Return Value
- **Type**: (string, error)
- **Description**: Returns the stored password/secret as a string and nil error on success. Returns empty string and ErrNotFound if credential does not exist. Returns empty string and error on keyring access failure.

### Error Conditions
- **ErrNotFound**: No credential found for the given service/user combination
- **Platform-specific error**: D-Bus connection failure, Credential Manager access denied
```

--------------------------------

### Get Function Signature

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/api-reference/get.md

The primary function signature for retrieving credentials.

```go
func Get(service, user string) (string, error)
```

--------------------------------

### Keyring Interface Methods

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/types.md

The Keyring interface defines the core methods for credential management, including setting, getting, deleting, and listing credentials.

```APIDOC
## Keyring Interface Methods

### Set(service, user, password string) error
Stores a credential in the keyring.

### Get(service, user string) (string, error)
Retrieves a credential from the keyring.

### Delete(service, user string) error
Removes a single credential from the keyring.

### DeleteAll(service string) error
Removes all credentials for a service.

### ListUsers(service string) ([]string, error)
Lists all usernames stored under a service.
```

--------------------------------

### func MockInitWithError(err error)

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/api-reference/mockinitwitherror.md

Initializes a mock provider that returns the specified error on all operations (Set, Get, Delete, DeleteAll, ListUsers). This is useful for testing error handling paths in code that uses go-keyring.

```APIDOC
## func MockInitWithError(err error)

### Description
Initializes a mock provider that returns the specified error on all operations (`Set`, `Get`, `Delete`, `DeleteAll`, `ListUsers`). This is useful for testing error handling paths in code that uses go-keyring.

### Parameters
- **err** (error) - Required - The error that all mock operations should return.

### Return Value
- **Type**: void
- **Description**: No return value. Replaces the global provider with an error-returning mock.

### Usage Example
```go
package myapp

import (
	"errors"
	"testing"
	"github.com/zalando/go-keyring"
)

func TestKeyringUnavailable(t *testing.T) {
	customErr := errors.New("keyring service not available")
	keyring.MockInitWithError(customErr)
	defer keyring.MockRestore()
	
	// All operations fail with the specified error
	err := keyring.Set("service", "user", "password")
	if !errors.Is(err, customErr) {
		t.Errorf("Expected customErr, got %v", err)
	}
}
```

--------------------------------

### Mock keyring behavior

Source: https://github.com/zalando/go-keyring/blob/master/README.md

Use MockInit to replace the OS-specific keyring provider with an in-memory implementation for testing purposes.

```go
package implementation

import (
    "testing"

    "github.com/zalando/go-keyring"
)

func TestMockedSetGet(t *testing.T) {
    keyring.MockInit()
    err := keyring.Set("service", "user", "password")
    if err != nil {
        t.Fatal(err)
    }

    p, err := keyring.Get("service", "user")
    if err != nil {
        t.Fatal(err)
    }

    if p != "password" {
        t.Error("password was not the expected string")
    }

}
```

--------------------------------

### Mock with Deferred Restore

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/api-reference/mockinit.md

Shows how to use the mock provider to store and list multiple credentials, ensuring cleanup with defer.

```go
package myapp

import (
	"testing"
	"github.com/zalando/go-keyring"
)

func TestMultipleUsers(t *testing.T) {
	keyring.MockInit()
	defer keyring.MockRestore()
	
	// Store multiple credentials
	for i := 1; i <= 3; i++ {
		user := fmt.Sprintf("user%d", i)
		pass := fmt.Sprintf("pass%d", i)
		if err := keyring.Set("service", user, pass); err != nil {
			t.Fatalf("Set failed for %s: %v", user, err)
		}
	}
	
	// List and verify
	users, err := keyring.ListUsers("service")
	if err != nil {
		t.Fatalf("ListUsers failed: %v", err)
	}
	
	if len(users) != 3 {
		t.Errorf("Expected 3 users, got %d", len(users))
	}
}
```

--------------------------------

### Basic usage of Set

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/api-reference/set.md

Demonstrates the standard implementation for storing a credential.

```go
package main

import (
	"log"
	"github.com/zalando/go-keyring"
)

func main() {
	err := keyring.Set("my-app", "john", "secret123")
	if err != nil {
		log.Fatal("Failed to store credential:", err)
	}
}
```

--------------------------------

### Run tests

Source: https://github.com/zalando/go-keyring/blob/master/README.md

Execute the standard Go test suite for the current operating system.

```bash
go test
```

--------------------------------

### Write and Read Credentials

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/platform-specifics.md

Demonstrates the process of creating, persisting, and retrieving credentials from the Windows Credential Manager.

```go
cred := wincred.NewGenericCredential(credName)
cred.UserName = username
cred.CredentialBlob = []byte(password)
cred.Write()  // Persists to Credential Manager registry
```

```go
cred, err := wincred.GetGenericCredential(credName)
password := string(cred.CredentialBlob)
```

--------------------------------

### Implement Fallback Provider

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/architecture.md

Returns an unsupported platform error for all operations when the OS is not supported.

```go
var ErrUnsupportedPlatform = errors.New("unsupported platform: " + runtime.GOOS)

func (fallbackServiceProvider) Set(service, user, pass string) error {
	return ErrUnsupportedPlatform
}
// Same for all other methods
```

--------------------------------

### Handling Unsupported Platform Errors

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/platform-specifics.md

Demonstrates how to detect the unsupported platform error and implement a fallback mechanism.

```go
password, err := keyring.Get("service", "user")
if errors.Is(err, keyring.ErrUnsupportedPlatform) {
	// Use environment variables or config files
	password = os.Getenv("APP_PASSWORD")
}
```

--------------------------------

### Test ErrSetDataTooBig

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/errors.md

Example test case verifying that setting an excessively long password triggers the expected error on supported platforms.

```go
// TestSetTooLong in keyring_test.go:26-36
extraLongPassword := "ba" + strings.Repeat("na", 5000)
err := Set(service, user, extraLongPassword)

if runtime.GOOS == "windows" || runtime.GOOS == "darwin" {
	if err != ErrSetDataTooBig {
		t.Errorf("Should have failed, got: %s", err)
	}
}
```

--------------------------------

### Enumerate multiple API tokens

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/api-reference/listusers.md

Advanced usage demonstrating how to list users and subsequently retrieve individual credentials, including error handling for unsupported platforms.

```go
package main

import (
	"errors"
	"log"
	"github.com/zalando/go-keyring"
)

func main() {
	service := "github-cli"
	
	users, err := keyring.ListUsers(service)
	if err != nil {
		if errors.Is(err, keyring.ErrUnsupportedPlatform) {
			log.Fatal("Keyring not supported on this system")
		}
		log.Fatal("Keyring error:", err)
	}
	
	// Try to use each stored credential
	for _, user := range users {
		token, err := keyring.Get(service, user)
		if err != nil {
			log.Printf("Warning: could not retrieve token for %s: %v\n", user, err)
			continue
		}
		
		// Use token for user
		log.Printf("Using token for: %s\n", user)
	}
}
```

--------------------------------

### MockInit()

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/DOCUMENTATION_SUMMARY.txt

Initializes the mock provider for testing purposes.

```APIDOC
## MockInit()

### Description
Initializes the mock provider for testing purposes, replacing the system keyring.
```

--------------------------------

### Implement Environment Variable Fallback

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/README.md

Retrieve credentials from the keyring with a fallback to environment variables if the platform is unsupported.

```go
func GetCredential(service, user string) (string, error) {
	password, err := keyring.Get(service, user)
	if err == nil {
		return password, nil
	}
	
	if errors.Is(err, keyring.ErrUnsupportedPlatform) {
		// Use environment variable as fallback
		if env := os.Getenv(strings.ToUpper(service) + "_PASSWORD"); env != "" {
			return env, nil
		}
	}
	
	return "", err
}
```

--------------------------------

### Basic Batch Deletion

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/api-reference/deleteall.md

Demonstrates the standard usage of DeleteAll to remove all credentials for a specified service.

```go
package main

import (
	"log"
	"github.com/zalando/go-keyring"
)

func main() {
	// Remove all credentials for a service
	err := keyring.DeleteAll("my-deprecated-app")
	if err != nil {
		log.Fatal("Failed to delete service credentials:", err)
	}
	log.Println("All credentials for service deleted")
}
```

--------------------------------

### Check Keyring Availability at Runtime

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/errors.md

A helper function to determine if the keyring is usable on the current platform.

```go
func canUseKeyring() (bool, string) {
	_, err := keyring.Get("test", "test")
	if errors.Is(err, keyring.ErrUnsupportedPlatform) {
		return false, err.Error()
	}
	return true, ""
}
```

--------------------------------

### Set Credentials with Descriptive Names

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/configuration.md

Use generic service names to avoid exposing user-specific information in the keyring.

```go
// Good
keyring.Set("github-cli", "pat-token", token)
keyring.Set("aws-sdk", "access-key", key)

// Avoid
keyring.Set("user123password", "admin", pwd)  // Exposes user info
```

--------------------------------

### Check Platform Support

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/README.md

Verify if the current platform supports keyring operations using ErrUnsupportedPlatform.

```go
_, err := keyring.Get("test", "test")
if errors.Is(err, keyring.ErrUnsupportedPlatform) {
	log.Fatal("Keyring not supported on this platform")
}
```

--------------------------------

### Implement Package-Level Facade

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/architecture.md

Public API functions delegate operations to the active global provider instance.

```go
func Set(service, user, password string) error {
	return provider.Set(service, user, password)
}
```

--------------------------------

### Testing with Mock Provider

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/configuration.md

Use the mock provider to perform keyring operations in-memory during tests when a system keyring is unavailable.

```go
import "github.com/zalando/go-keyring"

func TestWithMock(t *testing.T) {
	// Enable in-memory mock provider
	keyring.MockInit()
	defer keyring.MockRestore()
	
	// All operations use in-memory store
	keyring.Set("service", "user", "password")
	password, _ := keyring.Get("service", "user")
	// ...
}
```

--------------------------------

### Handle ErrUnsupportedPlatform

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/types.md

Check for ErrUnsupportedPlatform to implement alternative storage logic on unsupported systems.

```go
if errors.Is(err, keyring.ErrUnsupportedPlatform) {
	// Implement fallback credential storage method
}
```

--------------------------------

### Launch Seahorse GUI

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/configuration.md

Command to open the GNOME Keyring GUI for managing keyrings.

```bash
seahorse
```

--------------------------------

### Set with error handling

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/api-reference/set.md

Shows how to handle specific errors like data size limits or unsupported platforms.

```go
package main

import (
	"errors"
	"log"
	"github.com/zalando/go-keyring"
)

func main() {
	err := keyring.Set("api-client", "username", "verylongtoken")
	if err != nil {
		if errors.Is(err, keyring.ErrSetDataTooBig) {
			log.Fatal("Password too large for this platform")
		} else if errors.Is(err, keyring.ErrUnsupportedPlatform) {
			log.Fatal("Keyring not supported on this system")
		}
		log.Fatal("Keyring error:", err)
	}
}
```

--------------------------------

### MockInit Signature

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/api-reference/mockinit.md

The function signature for initializing the in-memory mock provider.

```go
func MockInit()
```

--------------------------------

### Build Commands for Supported Platforms

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/configuration.md

Standard build commands for various operating systems, noting the CGO requirement for BSD variants.

```bash
# macOS (automatic)
go build

# Linux
go build

# Windows
go build

# BSD variants (requires CGO)
CGO_ENABLED=1 go build
```

--------------------------------

### Test error handling for keyring unavailability

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/api-reference/mockinitwitherror.md

Demonstrates using MockInitWithError to verify that application code correctly handles a custom error returned by the keyring.

```go
package myapp

import (
	"errors"
	"testing"
	"github.com/zalando/go-keyring"
)

func TestKeyringUnavailable(t *testing.T) {
	customErr := errors.New("keyring service not available")
	keyring.MockInitWithError(customErr)
	defer keyring.MockRestore()
	
	// All operations fail with the specified error
	err := keyring.Set("service", "user", "password")
	if !errors.Is(err, customErr) {
		t.Errorf("Expected customErr, got %v", err)
	}
	
	_, err = keyring.Get("service", "user")
	if !errors.Is(err, customErr) {
		t.Errorf("Expected customErr, got %v", err)
	}
}
```

--------------------------------

### Import the Library

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/configuration.md

Import the package to access all exported functions and types at the package level.

```go
import "github.com/zalando/go-keyring"
```

--------------------------------

### Initialization Sequence Logic

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/architecture.md

The sequence of provider assignment during package initialization and runtime mocking.

```text
1. keyring.go: provider = fallbackServiceProvider{}
   (Fail-safe default)

2. Platform init() executes:
   - macOS (keyring_darwin.go:200-204):
     provider = macOSXKeychain{}
     restoreProvider = func() { provider = p }
   
   - Windows (keyring_windows.go:129-133):
     provider = windowsKeychain{}
     restoreProvider = func() { provider = p }
   
   - Linux/BSD (keyring_unix.go:215-219):
     provider = secretServiceProvider{}
     restoreProvider = func() { provider = p }

3. At runtime, MockInit() can replace provider with mockProvider
   and MockRestore() uses saved restoreProvider to switch back
```

--------------------------------

### List External Go Dependencies

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/README.md

Required external Go packages for cross-platform support.

```text
github.com/danieljoos/wincred v1.2.3  # Windows Credential Manager (Windows only)
github.com/godbus/dbus/v5 v5.2.2      # D-Bus (Linux/BSD only)
golang.org/x/sys v0.27.0               # Platform-specific syscalls (indirect)
```

--------------------------------

### List all stored users for a service

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/api-reference/listusers.md

Basic implementation for listing and iterating over all usernames associated with a specific service.

```go
package main

import (
	"log"
	"github.com/zalando/go-keyring"
)

func main() {
	users, err := keyring.ListUsers("my-cli-tool")
	if err != nil {
		log.Fatal("Failed to list users:", err)
	}
	
	if len(users) == 0 {
		log.Println("No stored credentials for this service")
		return
	}
	
	for _, user := range users {
		log.Printf("Stored user: %s\n", user)
	}
}
```

--------------------------------

### Fallback Implementation for Unsupported Platforms

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/platform-specifics.md

Defines the error returned when the platform is not supported by the keyring implementation.

```go
var ErrUnsupportedPlatform = errors.New("unsupported platform: " + runtime.GOOS)

func (fallbackServiceProvider) Set(service, user, pass string) error {
	return ErrUnsupportedPlatform
}
```

--------------------------------

### Basic MockRestore Usage

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/api-reference/mockrestore.md

Typical usage pattern for test cleanup using defer.

```go
keyring.MockInit()
defer keyring.MockRestore()
// ... test code ...
```

--------------------------------

### DeleteAll with Safety Handling

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/api-reference/deleteall.md

Shows how to implement manual validation and handle specific error types like ErrNotFound or ErrUnsupportedPlatform.

```go
package main

import (
	"errors"
	"log"
	"github.com/zalando/go-keyring"
)

func main() {
	service := "my-app"
	
	// Verify non-empty before deletion
	if service == "" {
		log.Fatal("Cannot delete with empty service name")
	}
	
	err := keyring.DeleteAll(service)
	if err != nil {
		if errors.Is(err, keyring.ErrNotFound) {
			log.Println("Empty service string provided")
		} else if errors.Is(err, keyring.ErrUnsupportedPlatform) {
			log.Fatal("Keyring not supported on this system")
		}
		log.Fatal("Keyring error:", err)
	}
	log.Println("Service cleanup complete")
}
```

--------------------------------

### Define Mock Provider Structure

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/architecture.md

Defines the in-memory storage structure for testing purposes.

```go
type mockProvider struct {
	mockStore map[string]map[string]string  // service -> user -> password
	mockError error                         // If set, all operations return this error
}
```

--------------------------------

### Map platform-specific errors to keyring.ErrNotFound

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/architecture.md

Demonstrates how to normalize platform-specific error responses into the standard ErrNotFound error type.

```go
if strings.Contains(string(out), "could not be found") {
	err = ErrNotFound
}
```

```go
if err == syscall.ERROR_NOT_FOUND {
	return "", ErrNotFound
}
```

```go
if len(results) == 0 {
	return "", ErrNotFound
}
```

--------------------------------

### Test resilience to temporary failures

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/api-reference/mockinitwitherror.md

Shows how to test application retry logic when the keyring returns a temporary error.

```go
package myapp

import (
	"errors"
	"testing"
	"github.com/zalando/go-keyring"
)

func TestRetryableKeyringFailure(t *testing.T) {
	tempErr := errors.New("d-bus connection lost")
	keyring.MockInitWithError(tempErr)
	defer keyring.MockRestore()
	
	// Application code should handle and retry
	for attempt := 0; attempt < 3; attempt++ {
		_, err := keyring.Get("api", "token")
		if err != nil {
			if attempt == 2 {
				t.Fatalf("All retries exhausted: %v", err)
			}
			// Simulate retry
			continue
		}
		break
	}
}
```

--------------------------------

### Build Tag Configuration

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/platform-specifics.md

Indicates that the macOS implementation is automatically selected by the Go compiler when targeting darwin.

```go
package keyring
// No explicit build tag - matched by default on darwin GOOS
```

--------------------------------

### Handle Large Credentials

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/configuration.md

Split tokens or keys exceeding 2KiB across multiple service/user pairs to avoid storage limits.

```go
if len(token) > 2000 {
	// Split across multiple service/user pairs
	keyring.Set("app", "token-1", token[:2000])
	keyring.Set("app", "token-2", token[2000:])
} else {
	keyring.Set("app", "token", token)
}
```

--------------------------------

### Cleanup Temporary Credentials

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/configuration.md

Use defer to ensure temporary credentials are removed after use.

```go
defer func() {
	keyring.Delete("app", "temp-user")
}()
```

--------------------------------

### Credential Retrieval with Error Handling

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/api-reference/get.md

Demonstrates handling specific error types like ErrNotFound or ErrUnsupportedPlatform during retrieval.

```go
package main

import (
	"errors"
	"log"
	"github.com/zalando/go-keyring"
)

func main() {
	token, err := keyring.Get("github-cli", "pat-token")
	if err != nil {
		if errors.Is(err, keyring.ErrNotFound) {
			log.Println("Token not found, please authenticate first")
			// Handle missing credential case
		} else if errors.Is(err, keyring.ErrUnsupportedPlatform) {
			log.Fatal("Keyring not supported on this system")
		}
		log.Fatal("Keyring error:", err)
	}
	// Use token
}
```

--------------------------------

### MockRestore()

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/DOCUMENTATION_SUMMARY.txt

Restores the original system provider after testing.

```APIDOC
## MockRestore()

### Description
Restores the original system provider after testing.
```

--------------------------------

### keyring.Get

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/README.md

Retrieves a credential from the system keyring.

```APIDOC
## keyring.Get(service string, user string) (string, error)

### Description
Retrieves the password associated with the provided service and user from the system keyring.

### Parameters
- **service** (string) - Required - The application identifier.
- **user** (string) - Required - The account identifier.

### Returns
- **password** (string) - The retrieved credential.
- **err** (error) - Returns keyring.ErrNotFound if the credential does not exist, or keyring.ErrUnsupportedPlatform if the platform is not supported.
```

--------------------------------

### Handle Keyring Errors

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/README.md

Check for specific error types like missing credentials or unsupported platforms to implement fallback logic.

```go
password, err := keyring.Get("service", "user")
if err != nil {
	if errors.Is(err, keyring.ErrNotFound) {
		// Credential not found
	} else if errors.Is(err, keyring.ErrUnsupportedPlatform) {
		// Fallback to environment variables
	} else {
		// Other error
	}
}
```

--------------------------------

### Handle ErrSetDataTooBig

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/errors.md

Demonstrates handling data size limits by compressing or modifying the input when ErrSetDataTooBig is returned.

```go
err := keyring.Set("app", "user", largePassword)
if err != nil {
	if errors.Is(err, keyring.ErrSetDataTooBig) {
		// Compress password, use token file, or split across entries
		shortPassword := compress(largePassword)
		err = keyring.Set("app", "user", shortPassword)
		if err != nil {
			log.Fatalf("Still too large: %v", err)
		}
	} else {
		log.Fatalf("Keyring error: %v", err)
	}
}
```

--------------------------------

### Define Build Tag

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/platform-specifics.md

Indicates that the code is automatically selected when the GOOS environment variable is set to windows.

```go
package keyring
// Implicit: matched when GOOS=windows (no explicit tag needed)
```

--------------------------------

### Perform Bulk Operations

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/README.md

Manage multiple credentials by deleting all entries for a service or iterating through stored users.

```go
// Delete all credentials for a service
err := keyring.DeleteAll("my-app")

// Enumerate and use all stored credentials
users, err := keyring.ListUsers("my-app")
for _, user := range users {
	password, err := keyring.Get("my-app", user)
	// Use password...
}
```

--------------------------------

### Create Secret Items

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/platform-specifics.md

Shows how to define attributes and create a new secret item within a collection.

```go
attributes := map[string]string{
	"username": user,
	"service":  service,
}

secret := ss.NewSecret(session.Path(), password)

collection.Call(collectionInterface+".CreateItem", 0,
	properties, secret, true).Store(&item, &prompt)
```

--------------------------------

### Size Validation Before Set Pattern

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/errors.md

Validate password length against platform-specific command-line limits on macOS and Windows before attempting to set the credential.

```go
func SafeSet(service, user, password string) error {
	// Pre-check on platforms with size limits
	if runtime.GOOS == "darwin" || runtime.GOOS == "windows" {
		cmd := fmt.Sprintf("add-generic-password -U -s %s -a %s -w %s",
			shellescape.Quote(service),
			shellescape.Quote(user),
			shellescape.Quote(password))
		if len(cmd) > 4096 {
			return keyring.ErrSetDataTooBig
		}
	}
	
	return keyring.Set(service, user, password)
}
```

--------------------------------

### Format Windows Credential Target

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/architecture.md

Combines service and username into a single string for the Windows Credential Manager.

```go
func (k windowsKeychain) credName(service, username string) string {
	return service + ":" + username  // e.g., "myapp:john"
}
```

--------------------------------

### Enforce Windows Credential Size Limits

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/architecture.md

Checks password and service string lengths against Windows Credential Manager constraints.

```go
if len(password) > 2560 {
	return ErrSetDataTooBig
}
if len(service) >= 512 {
	return ErrSetDataTooBig
}
if len(service) > 1024*30 {
	return ErrSetDataTooBig
}
```

--------------------------------

### Handle D-Bus Prompts

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/platform-specifics.md

Manages user interaction requirements by checking for prompt paths returned by D-Bus operations.

```go
err := s.object.Call(serviceInterface+".Unlock", 0, 
	[]dbus.ObjectPath{collection}).Store(&unlocked, &prompt)

// If prompt is not "/" path, user interaction is required
if prompt != dbus.ObjectPath("/") {
	handled, result, err := s.handlePrompt(prompt)
	// Waits for dbus signal indicating prompt completion
}
```

--------------------------------

### Initialize Global Provider

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/architecture.md

The global provider variable holds the active implementation and is initialized during package startup.

```go
var provider Keyring = fallbackServiceProvider{}
```

--------------------------------

### Conditional Compilation Build Tags

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/configuration.md

Build tag used in keyring_unix.go to enable Linux and BSD implementations.

```go
//go:build (dragonfly && cgo) || (freebsd && cgo) || linux || netbsd || openbsd
```

--------------------------------

### MockInitWithError Signature

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/api-reference/mockinitwitherror.md

The function signature for initializing the error-returning mock provider.

```go
func MockInitWithError(err error) 
```

--------------------------------

### List Users for a Service

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/platform-specifics.md

Filters credentials by prefix to extract and list all usernames associated with a specific service.

```go
prefix := k.credName(service, "")  // e.g., "my-app:"
var users []string

for _, cred := range creeds {
	if strings.HasPrefix(cred.TargetName, prefix) {
		username := strings.TrimPrefix(cred.TargetName, prefix)
		if username != "" {
			users = append(users, username)
		}
	}
}
```

--------------------------------

### Delete with error handling

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/api-reference/delete.md

Handling specific error cases like missing credentials or unsupported platforms.

```go
package main

import (
	"errors"
	"log"
	"github.com/zalando/go-keyring"
)

func main() {
	err := keyring.Delete("api-client", "api-key")
	if err != nil {
		if errors.Is(err, keyring.ErrNotFound) {
			log.Println("Credential not found, nothing to delete")
		} else if errors.Is(err, keyring.ErrUnsupportedPlatform) {
			log.Fatal("Keyring not supported on this system")
		}
		log.Fatal("Keyring error:", err)
	}
}
```

--------------------------------

### Keyring Interface Definition

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/types.md

The primary interface defining the public API for system keyring access.

```go
type Keyring interface {
	Set(service, user, password string) error
	Get(service, user string) (string, error)
	Delete(service, user string) error
	DeleteAll(service string) error
	ListUsers(service string) ([]string, error)
}
```

--------------------------------

### Simulating Errors with Mock Provider

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/configuration.md

Configure the mock provider to return specific errors to verify application error handling logic.

```go
import "github.com/zalando/go-keyring"

func TestErrorHandling(t *testing.T) {
	// Simulate all operations returning an error
	customErr := errors.New("keyring unavailable")
	keyring.MockInitWithError(customErr)
	defer keyring.MockRestore()
	
	_, err := keyring.Get("service", "user")
	// err will equal customErr
}
```

--------------------------------

### Interactive Session Management

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/platform-specifics.md

Uses stdin redirection to communicate with the security command-line tool in interactive mode.

```go
cmd := exec.Command(execPathKeychain, "-i")  // Interactive mode
stdIn, _ := cmd.StdinPipe()
cmd.Start()
// Write command via stdIn
io.WriteString(stdIn, command)
stdIn.Close()
cmd.Wait()
```

--------------------------------

### Define External Dependencies in go.mod

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/configuration.md

Lists the required external packages for Windows and Linux/BSD platforms, which are automatically handled during the build process.

```go
require (
	github.com/danieljoos/wincred v1.2.3  // Windows Credential Manager (Windows only)
	github.com/godbus/dbus/v5 v5.2.2      // D-Bus (Linux/BSD only)
)

require golang.org/x/sys v0.27.0 // indirect (conditional)
```

--------------------------------

### Handle ErrNotFound

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/errors.md

Demonstrates checking for ErrNotFound using errors.Is to trigger a fallback authentication flow.

```go
password, err := keyring.Get("myapp", "bob")
if err != nil {
	if errors.Is(err, keyring.ErrNotFound) {
		log.Println("Credential not found, prompt user to set it up")
		// Run authentication flow and call Set()
	} else {
		log.Fatalf("Keyring error: %v", err)
	}
}
```

--------------------------------

### Display Directory Structure

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/INDEX.md

Visual representation of the documentation file organization.

```text
output/
├── INDEX.md                          (this file)
├── README.md                         (overview & quick reference)
├── types.md                          (type definitions & interfaces)
├── errors.md                         (error reference & handling)
├── configuration.md                  (setup & configuration)
├── architecture.md                   (design & implementation)
├── platform-specifics.md             (platform-by-platform details)
└── api-reference/
    ├── set.md                        (Set function)
    ├── get.md                        (Get function)
    ├── delete.md                     (Delete function)
    ├── deleteall.md                  (DeleteAll function)
    ├── listusers.md                  (ListUsers function)
    ├── mockinit.md                   (MockInit function)
    ├── mockrestore.md                (MockRestore function)
    └── mockinitwitherror.md          (MockInitWithError function)
```

--------------------------------

### Error Detection for Missing Items

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/platform-specifics.md

Identifies missing keychain items by checking for specific error strings in the command output.

```go
if strings.Contains(string(out), "could not be found") {
	err = ErrNotFound
}
```

--------------------------------

### keyring.Set

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/README.md

Stores a credential in the system keyring for a specific service and user.

```APIDOC
## keyring.Set(service string, user string, password string) error

### Description
Stores a credential in the system keyring. The credential is associated with a service name and a user identifier.

### Parameters
- **service** (string) - Required - The application identifier.
- **user** (string) - Required - The account identifier.
- **password** (string) - Required - The secret to store.
```

--------------------------------

### Set function signature

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/api-reference/set.md

The function signature for storing credentials in the system keyring.

```go
func Set(service, user, password string) error
```

--------------------------------

### Basic Credential Retrieval

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/api-reference/get.md

Standard implementation for fetching a password using a service and username identifier.

```go
package main

import (
	"log"
	"github.com/zalando/go-keyring"
)

func main() {
	password, err := keyring.Get("my-app", "john")
	if err != nil {
		log.Fatal("Failed to retrieve credential:", err)
	}
	log.Println("Retrieved:", password)
}
```

--------------------------------

### Graceful Keyring Fallback Pattern

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/errors.md

Implement a fallback mechanism by checking for keyring.ErrNotFound and attempting to retrieve secrets from environment variables if the keyring is unavailable.

```go
func GetSecretWithFallback(service, user string) (string, error) {
	password, err := keyring.Get(service, user)
	if err == nil {
		return password, nil
	}
	
	// Check if keyring is unavailable
	if errors.Is(err, keyring.ErrNotFound) {
		// Only treat not-found as fallback trigger
		return "", err
	}
	
	// Log other errors but try fallback
	log.Printf("Keyring unavailable: %v", err)
	
	// Try environment variable
	if env := os.Getenv(service + "_PASSWORD"); env != "" {
		return env, nil
	}
	
	return "", fmt.Errorf("no credential found for %s", service)
}
```

--------------------------------

### Basic credential deletion

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/api-reference/delete.md

Standard implementation for removing a credential from the keyring.

```go
package main

import (
	"log"
	"github.com/zalando/go-keyring"
)

func main() {
	err := keyring.Delete("my-app", "john")
	if err != nil {
		log.Fatal("Failed to delete credential:", err)
	}
	log.Println("Credential deleted successfully")
}
```

--------------------------------

### Set Operation Data Flow

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/architecture.md

Describes the delegation and platform-specific execution steps when setting a credential.

```text
User: keyring.Set("github", "token", "ghp_...")
  ↓
package.Set() delegates to provider.Set()
  ↓
macOS implementation:
  - Prepare: base64 encode password
  - Build command: security add-generic-password -U -s "github" -a "token" -w "..."
  - Execute: via stdin to "security -i"
  - Check: command length <4096
  - Return: any errors
  ↓
Windows implementation:
  - Check size: password <2560, service <30KB
  - Create: NewGenericCredential("github:token")
  - Store: cred.CredentialBlob = password bytes
  - Persist: cred.Write() to Credential Manager
  ↓
Linux/BSD implementation:
  - Open D-Bus session
  - Create Secret with UTF-8 content type
  - Create item in login collection with attributes
  - Unlock if needed
  - Clean up session
```

--------------------------------

### Command Size Limit Check

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/platform-specifics.md

Validates command length before execution to prevent exceeding the shell command size limit.

```go
if len(command) > 4096 {
	return ErrSetDataTooBig
}
```

--------------------------------

### Manage Secret Service Sessions

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/platform-specifics.md

Demonstrates opening a plain-text session for encrypted communication and closing it after use.

```go
// Open session with "plain" algorithm
err := s.object.Call(serviceInterface+".OpenSession", 0, "plain", 
	dbus.MakeVariant("")).Store(&disregard, &sessionPath)

// Later: close session
s.Close(sessionPath)
```

--------------------------------

### Test platform error propagation

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/api-reference/mockinitwitherror.md

Verifies that the application correctly handles specific platform errors like ErrUnsupportedPlatform.

```go
package myapp

import (
	"testing"
	"github.com/zalando/go-keyring"
)

func TestUnsupportedPlatform(t *testing.T) {
	keyring.MockInitWithError(keyring.ErrUnsupportedPlatform)
	defer keyring.MockRestore()
	
	// Test that application gracefully handles unsupported platforms
	_, err := keyring.Get("service", "user")
	if err != keyring.ErrUnsupportedPlatform {
		t.Errorf("Expected ErrUnsupportedPlatform, got %v", err)
	}
}
```

--------------------------------

### Deduplicate and Sort User Lists

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/platform-specifics.md

Ensures deterministic ordering and removes duplicates from user lists.

```go
sort.Strings(users)
return slices.Compact(users)  // Go 1.21+
```

--------------------------------

### Detect Missing Credential Pattern

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/errors.md

Use errors.Is to check for keyring.ErrNotFound when retrieving credentials to distinguish between missing data and system errors.

```go
func GetOrSetup(service, user string) (string, error) {
	password, err := keyring.Get(service, user)
	if err != nil {
		if errors.Is(err, keyring.ErrNotFound) {
			return "", fmt.Errorf("credential not set; run setup first")
		}
		return "", err
	}
	return password, nil
}
```

--------------------------------

### ListUsers function signature

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/api-reference/listusers.md

The function signature for retrieving users from the system keyring.

```go
func ListUsers(service string) ([]string, error)
```

--------------------------------

### func ListUsers(service string) ([]string, error)

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/api-reference/listusers.md

Retrieves all unique usernames stored under a given service name in the system keyring. The results are returned sorted alphabetically and deduplicated.

```APIDOC
## func ListUsers(service string) ([]string, error)

### Description
Retrieves all unique usernames stored under a given service name in the system keyring. The results are returned sorted alphabetically and deduplicated.

### Parameters
- **service** (string) - Required - Service identifier to list users for

### Return Value
- **Type**: ([]string, error)
- **Description**: Returns a sorted slice of unique usernames/account identifiers stored for the service, and nil error on success. Returns empty slice and nil error if no credentials exist for the service. Returns nil slice and error on keyring access failure.

### Usage Example
```go
users, err := keyring.ListUsers("my-cli-tool")
if err != nil {
	log.Fatal("Failed to list users:", err)
}
```
```

--------------------------------

### keyring.ListUsers

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/README.md

Lists all users associated with a specific service.

```APIDOC
## keyring.ListUsers(service string) ([]string, error)

### Description
Retrieves a list of all user identifiers stored under a specific service name.

### Parameters
- **service** (string) - Required - The application identifier.
```

--------------------------------

### Define ErrUnsupportedPlatform

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/types.md

The error returned when the current operating system is not supported by the library.

```go
var ErrUnsupportedPlatform = errors.New("unsupported platform: " + runtime.GOOS)
```

--------------------------------

### Keychain Dump Parsing

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/platform-specifics.md

Extracts values from keychain dump output lines by locating key-value pairs.

```go
func parseDumpKeychainBlob(line string) string {
	idx := strings.Index(line, `="`)
	if idx == -1 {
		return ""
	}
	start := idx + 2
	end := strings.Index(line[start:], `"`)
	if end == -1 {
		return ""
	}
	return line[start : start+end]
}
```

--------------------------------

### ListUsers(service string) ([]string, error)

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/DOCUMENTATION_SUMMARY.txt

Lists all users associated with a specific service.

```APIDOC
## ListUsers(service string) ([]string, error)

### Description
Lists all users associated with a specific service.

### Parameters
- **service** (string) - Required - The service name to query.

### Returns
- **[]string** - A slice of usernames.
- **error** - Returns an error if the operation fails.
```

--------------------------------

### Enforce macOS Command Size Limits

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/architecture.md

Validates the length of the generated security CLI command to prevent execution errors.

```go
command := fmt.Sprintf("add-generic-password -U -s %s -a %s -w %s\n",
	shellescape.Quote(service),
	shellescape.Quote(username),
	shellescape.Quote(password))
if len(command) > 4096 {
	return ErrSetDataTooBig
}
```

--------------------------------

### Resolve Login Collection

Source: https://github.com/zalando/go-keyring/blob/master/_autodocs/platform-specifics.md

Implements a fallback strategy to locate the login collection via standard path or alias.

```go
func (s *secretServiceProvider) GetLoginCollection() dbus.BusObject {
	path := dbus.ObjectPath(collectionBasePath + "login")
	if err := s.CheckCollectionPath(path); err != nil {
		// Fallback to alias
		path = dbus.ObjectPath(loginCollectionAlias)
	}
	return s.Object(serviceName, path)
}
```
Tokens:
Raw