client

package module
v1.8.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 15, 2026 License: Apache-2.0 Imports: 53 Imported by: 10

README

Directory Golang SDK

Overview

Dir Golang SDK provides a simple way to interact with the Directory API. It allows developers to integrate and use Directory functionality from their applications with ease.

Features

The Directory SDK provides comprehensive access to all Directory APIs with a simple, intuitive interface:

Store API
  • Record Management: Push records to the store and pull them by reference
  • Metadata Operations: Look up record metadata without downloading full content
  • Data Lifecycle: Delete records permanently from the store
  • Referrer Support: Push and pull artifacts for existing records
  • Sync Management: Manage storage synchronization policies between Directory servers
Search API
  • Flexible Search: Search stored records using text, semantic, and structured queries
  • Advanced Filtering: Filter results by metadata, content type, and other criteria
Routing API
  • Network Publishing: Publish records to make them discoverable across the network
  • Content Discovery: List and query published records across the network
  • Network Management: Unpublish records to remove them from network discovery
Signing and Verification
  • Local Signing: Sign records locally using private keys or OIDC-based authentication.
  • Remote Verification: Verify record signatures using the Directory gRPC API
Developer Experience
  • Async Support: Non-blocking operations with streaming responses for large datasets
  • Error Handling: Comprehensive gRPC error handling with detailed error messages
  • Configuration: Flexible configuration via environment variables or direct instantiation

Installation

  1. Initialize the project:
go mod init example.com/myapp
  1. Add the SDK to your project:
go get github.com/agntcy/dir/client

Configuration

The SDK can be configured via environment variables or direct instantiation.

Environment Variables
Variable Description Default
DIRECTORY_CLIENT_SERVER_ADDRESS Directory server address 0.0.0.0:8888
DIRECTORY_CLIENT_AUTH_MODE Authentication mode: x509, jwt, or empty for insecure "" (insecure)
DIRECTORY_CLIENT_SPIFFE_SOCKET_PATH SPIFFE Workload API socket path ""
DIRECTORY_CLIENT_JWT_AUDIENCE JWT audience for JWT authentication ""
Authentication

The SDK supports multiple authentication modes:

1. Insecure (No Authentication)

For local development only. Not recommended for production.

Environment Variables:

export DIRECTORY_CLIENT_SERVER_ADDRESS="localhost:8888"
# AUTH_MODE is empty or not set

Code Example:

import (
    "context"
    "github.com/agntcy/dir/client"
)

ctx := context.Background()
config := &client.Config{
    ServerAddress: "localhost:8888",
    // AuthMode is empty - insecure connection
}
c, err := client.New(ctx, client.WithConfig(config))
if err != nil {
    // handle error
}
defer c.Close() // Always close to cleanup resources
2. X509 (X.509-SVID)

Recommended for production. Requires SPIRE agent.

Environment Variables:

export DIRECTORY_CLIENT_SERVER_ADDRESS="localhost:8888"
export DIRECTORY_CLIENT_AUTH_MODE="x509"
export DIRECTORY_CLIENT_SPIFFE_SOCKET_PATH="unix:///run/spire/agent-sockets/api.sock"

Code Example:

import (
    "context"
    "github.com/agntcy/dir/client"
)

ctx := context.Background()
config := &client.Config{
    ServerAddress:    "localhost:8888",
    AuthMode:         "x509",
    SpiffeSocketPath: "unix:///run/spire/agent-sockets/api.sock",
}
c, err := client.New(ctx, client.WithConfig(config))
if err != nil {
    // handle error
}
defer c.Close() // Always close to cleanup resources
3. JWT (JWT-SVID)

Alternative to X.509 for client authentication. Requires SPIRE agent.

Note: In JWT mode, the server presents its X.509-SVID via TLS for server authentication and encryption, while the client authenticates using a JWT-SVID. This provides both transport security and client authentication, following the official SPIFFE JWT pattern.

Environment Variables:

export DIRECTORY_CLIENT_SERVER_ADDRESS="localhost:8888"
export DIRECTORY_CLIENT_AUTH_MODE="jwt"
export DIRECTORY_CLIENT_SPIFFE_SOCKET_PATH="unix:///run/spire/agent-sockets/api.sock"
export DIRECTORY_CLIENT_JWT_AUDIENCE="spiffe://example.org/dir-server"

Code Example:

import (
    "context"
    "github.com/agntcy/dir/client"
)

ctx := context.Background()
config := &client.Config{
    ServerAddress:    "localhost:8888",
    AuthMode:         "jwt",
    SpiffeSocketPath: "unix:///run/spire/agent-sockets/api.sock",
    JWTAudience:      "spiffe://example.org/dir-server",
}
c, err := client.New(ctx, client.WithConfig(config))
if err != nil {
    // handle error
}
defer c.Close() // Always close to cleanup resources
4. OIDC (OpenID Connect)

For human users and CI/scripts authenticating via an OIDC provider (e.g. Dex).

Environment Variables:

export DIRECTORY_CLIENT_SERVER_ADDRESS="gateway.example.com:443"
export DIRECTORY_CLIENT_AUTH_MODE="oidc"
export DIRECTORY_CLIENT_AUTH_TOKEN="eyJhbG..."  # pre-issued JWT (optional; skips interactive login)

Interactive login (via CLI):

dirctl auth login --oidc-issuer=https://dex.example.com --oidc-client-id=dirctl

Code Example:

import (
    "context"
    "github.com/agntcy/dir/client"
)

ctx := context.Background()
config := &client.Config{
    ServerAddress: "gateway.example.com:443",
    AuthMode:      "oidc",
    AuthToken:     "eyJhbG...",  // or leave empty to use cached token from dirctl auth login
}
c, err := client.New(ctx, client.WithConfig(config))
if err != nil {
    // handle error
}
defer c.Close()

Getting Started

Prerequisites
  • Golang - Go programming language
1. Server Setup

Option A: Local Development Server

# Clone the repository and start the server using Taskfile
task server:start

Option B: Custom Server

# Set your Directory server address
export DIRECTORY_CLIENT_SERVER_ADDRESS="your-server:8888"
2. SDK Installation
# Add the Directory SDK
go get github.com/agntcy/dir/client

Documentation

Index

Constants

View Source 
const (
	DefaultEnvPrefix = "DIRECTORY_CLIENT"

	DefaultServerAddress = "0.0.0.0:8888"
	DefaultTlsSkipVerify = false
	DefaultCallbackPort  = 8484
	DefaultOAuthTimeout  = 5 * time.Minute
)
View Source 
const (
	// DefaultTokenCacheDir is the default directory for storing cached tokens (relative to home directory).
	// When XDG_CONFIG_HOME is set, tokens are stored at $XDG_CONFIG_HOME/dirctl instead.
	//nolint:gosec // G101: This is a directory path, not a credential
	DefaultTokenCacheDir = ".config/dirctl"

	// TokenCacheFile is the filename for the cached token.
	//nolint:gosec // G101: This is a filename, not a credential
	TokenCacheFile = "auth-token.json"

	// TokenCacheSubdir is where issuer-scoped token cache files are stored.
	TokenCacheSubdir = "tokens"

	// DefaultTokenValidityDuration is how long a token is considered valid if no expiry is set.
	DefaultTokenValidityDuration = 8 * time.Hour

	// TokenExpiryBuffer is how much time before actual expiry we consider a token expired.
	TokenExpiryBuffer = 5 * time.Minute
)
View Source 
const DefaultOIDCScopes = "openid email profile offline_access groups"

DefaultOIDCScopes are the OIDC scopes requested for interactive login.

Variables

View Source 
var (
	// ErrTokenCacheNotFound indicates that a specific token cache file does not exist.
	ErrTokenCacheNotFound = errors.New("token cache not found")

	// ErrNoCachedIssuer indicates that no issuer-scoped token cache could be selected.
	ErrNoCachedIssuer = errors.New("no cached OIDC issuer found")
)
View Source 
var DefaultConfig = Config{
	ServerAddress: DefaultServerAddress,
}
View Source 
var OIDC = &OIDCProvider{}

OIDC provides OIDC authentication flows.

Functions

This section is empty.

Types

type AmbiguousTokenCacheError added in v1.3.0 

type AmbiguousTokenCacheError struct {
	Issuers []string
}

AmbiguousTokenCacheError indicates multiple issuer-scoped caches exist and the caller must select one.

func (*AmbiguousTokenCacheError) Error added in v1.3.0 

func (e *AmbiguousTokenCacheError) Error() string

type AuthResult added in v1.2.0 

type AuthResult struct {
	AccessToken  string
	RefreshToken string
	TokenType    string
	ExpiresAt    time.Time
	IDToken      string
	Subject      string
	Email        string
	Name         string
}

AuthResult is the unified result from any OIDC authentication flow (PKCE or device).

type CachedIssuer added in v1.3.0 

type CachedIssuer struct {
	Issuer string
	Path   string
}

CachedIssuer describes one issuer-scoped cache file.

func ListCachedIssuers added in v1.3.0 

func ListCachedIssuers() ([]CachedIssuer, error)

ListCachedIssuers returns all issuer-scoped token caches on disk.

type CachedToken added in v1.0.0 

type CachedToken struct {
	// AccessToken is the authentication token.
	AccessToken string `json:"access_token"` // #nosec G117: intentional field - for cached token

	// TokenType is the token type (usually "bearer").
	TokenType string `json:"token_type,omitempty"`

	// Provider is the authentication provider (oidc, github, google, azure, etc.)
	Provider string `json:"provider,omitempty"`

	// Issuer is the OIDC issuer URL (for Provider=oidc). Enables multi-issuer support.
	Issuer string `json:"issuer,omitempty"`

	// RefreshToken is the refresh token, if the IdP returned one (for token refresh).
	RefreshToken string `json:"refresh_token,omitempty"` // #nosec G101: intentional field - for cached token

	// ExpiresAt is when the token expires.
	ExpiresAt time.Time `json:"expires_at,omitzero"`

	// User is the authenticated username (e.g. preferred_username or name for OIDC).
	User string `json:"user,omitempty"`

	// UserID is the provider-specific user ID (e.g. sub for OIDC).
	UserID string `json:"user_id,omitempty"`

	// Email is the user's email address.
	Email string `json:"email,omitempty"`

	// CreatedAt is when the token was cached.
	CreatedAt time.Time `json:"created_at"`
}

CachedToken represents a cached authentication token from any provider.

func RefreshExpiredCachedOIDCToken added in v1.4.0 

func RefreshExpiredCachedOIDCToken(ctx context.Context, cache *TokenCache, cachedToken *CachedToken, clientID string) (*CachedToken, error)

RefreshExpiredCachedOIDCToken refreshes an expired cached OIDC token and persists the updated cache atomically.

type Client 

type Client struct {
	storev1.StoreServiceClient
	routingv1.RoutingServiceClient
	searchv1.SearchServiceClient
	storev1.SyncServiceClient
	signv1.SignServiceClient
	eventsv1.EventServiceClient
	identityv1.IdentityServiceClient
	runtimev1.DiscoveryServiceClient
	// contains filtered or unexported fields
}

func New 

func New(ctx context.Context, opts ...Option) (*Client, error)

func (*Client) ClaimIdentity added in v1.8.0 

func (c *Client) ClaimIdentity(ctx context.Context, cid string, signer jws.Signer, opts ...identity.SignOption) (*identityv1.Claim, error)

ClaimIdentity signs a claim that the record with the given CID has the identity declared in its "agntcy.dir/identity" annotation, and pushes it to the record as a referrer. It returns the claim that was pushed. Pass identity.WithCertificate for a spiffe:// or ans:// subject, whose proof is a certificate.

The claim is stored unverified: it is checked later by the reconciler, and GetIdentityStatus reports the outcome.

func (*Client) ClaimOwnership added in v1.8.0 

func (c *Client) ClaimOwnership(ctx context.Context, cid string, signer jws.Signer, opts ...identity.SignOption) (*identityv1.Claim, error)

ClaimOwnership signs a claim that the record with the given CID is owned by the owner declared in its "agntcy.dir/owner" annotation, and pushes it to the record as a referrer. See ClaimIdentity.

func (*Client) Close 

func (c *Client) Close() error

func (*Client) CreateSync 

func (c *Client) CreateSync(ctx context.Context, remoteURL string, cids []string, opts *CreateSyncOptions) (string, error)

func (*Client) Delete 

func (c *Client) Delete(ctx context.Context, recordRef *corev1.RecordRef) error

Delete removes a record from the store using its reference.

func (*Client) DeleteBatch 

func (c *Client) DeleteBatch(ctx context.Context, recordRefs []*corev1.RecordRef) error

DeleteBatch removes multiple records from the store in a single stream for efficiency.

func (*Client) DeleteReferrer added in v1.2.0 

func (c *Client) DeleteReferrer(
	ctx context.Context,
	req *storev1.DeleteReferrerRequest,
) (*storev1.DeleteReferrerResponse, error)

func (*Client) DeleteStream 

func (c *Client) DeleteStream(ctx context.Context, refsCh <-chan *corev1.RecordRef) (streaming.StreamResult[emptypb.Empty], error)

DeleteStream provides efficient streaming delete operations using channels. Record references are sent as they become available and delete confirmations are returned as they're processed. This method maintains a single gRPC stream for all operations, dramatically improving efficiency.

func (*Client) DeleteSync 

func (c *Client) DeleteSync(ctx context.Context, syncID string) error

func (*Client) GetIdentityStatus added in v1.8.0 

func (c *Client) GetIdentityStatus(ctx context.Context, cid string) (*identityv1.GetIdentityStatusResponse, error)

GetIdentityStatus returns the last verification result of the identity and ownership claims of the record with the given CID. A claim with no result yet is unset in the response.

func (*Client) GetSync 

func (c *Client) GetSync(ctx context.Context, syncID string) (*storev1.GetSyncResponse, error)

func (*Client) GetWorkload added in v1.2.0 

func (c *Client) GetWorkload(ctx context.Context, workloadID string) (*runtimev1.Workload, error)

func (*Client) List 

func (c *Client) List(ctx context.Context, req *routingv1.ListRequest) (<-chan *routingv1.ListResponse, error)

func (*Client) ListSyncs 

func (c *Client) ListSyncs(ctx context.Context, req *storev1.ListSyncsRequest) (<-chan *storev1.ListSyncsItem, error)

func (*Client) ListWorkloads added in v1.2.0 

func (c *Client) ListWorkloads(ctx context.Context, labels map[string]string) ([]*runtimev1.Workload, error)

func (*Client) ListWorkloadsStream added in v1.2.0 

func (c *Client) ListWorkloadsStream(ctx context.Context, labels map[string]string) (streaming.StreamResult[runtimev1.Workload], error)

func (*Client) ListWorkloadsStreamWithRequest added in v1.8.0 

func (c *Client) ListWorkloadsStreamWithRequest(ctx context.Context, req *runtimev1.ListWorkloadsRequest) (streaming.StreamResult[runtimev1.Workload], error)

ListWorkloadsStreamWithRequest streams the workloads matching every filter set in req.

func (*Client) ListWorkloadsWithRequest added in v1.8.0 

func (c *Client) ListWorkloadsWithRequest(ctx context.Context, req *runtimev1.ListWorkloadsRequest) ([]*runtimev1.Workload, error)

ListWorkloadsWithRequest returns the workloads matching every filter set in req.

func (*Client) ListenStream 

func (c *Client) ListenStream(ctx context.Context, req *eventsv1.ListenRequest) (streaming.StreamResult[eventsv1.ListenResponse], error)

ListenStream streams events from the server with the specified filters.

Returns a StreamResult that provides structured channels for receiving events, errors, and completion signals.

Example - Listen to all events: 

result, err := client.ListenStream(ctx, &eventsv1.ListenRequest{})
if err != nil {
    return err
}

for {
    select {
    case resp := <-result.ResCh():
        event := resp.GetEvent()
        fmt.Printf("Event: %s - %s\n", event.Type, event.ResourceId)
    case err := <-result.ErrCh():
        return fmt.Errorf("stream error: %w", err)
    case <-result.DoneCh():
        return nil
    case <-ctx.Done():
        return ctx.Err()
    }
}

Example - Filter by event type: 

result, err := client.ListenStream(ctx, &eventsv1.ListenRequest{
    EventTypes: []eventsv1.EventType{
        eventsv1.EventType_EVENT_TYPE_RECORD_PUSHED,
        eventsv1.EventType_EVENT_TYPE_RECORD_PUBLISHED,
    },
})

Example - Filter by labels: 

result, err := client.ListenStream(ctx, &eventsv1.ListenRequest{
    LabelFilters: []string{"/skills/AI"},
})

func (*Client) Lookup 

func (c *Client) Lookup(ctx context.Context, recordRef *corev1.RecordRef) (*corev1.RecordMeta, error)

Lookup retrieves metadata for a record using its reference.

func (*Client) LookupBatch 

func (c *Client) LookupBatch(ctx context.Context, recordRefs []*corev1.RecordRef) ([]*corev1.RecordMeta, error)

LookupBatch retrieves metadata for multiple records in a single stream for efficiency.

func (*Client) LookupStream 

func (c *Client) LookupStream(ctx context.Context, refsCh <-chan *corev1.RecordRef) (streaming.StreamResult[corev1.RecordMeta], error)

LookupStream provides efficient streaming lookup operations using channels. Record references are sent as they become available and metadata is returned as it's processed. This method maintains a single gRPC stream for all operations, dramatically improving efficiency.

Uses sequential streaming pattern (Send → Recv → Send → Recv) which ensures strict ordering of request-response pairs.

func (*Client) Publish 

func (c *Client) Publish(ctx context.Context, req *routingv1.PublishRequest) error

func (*Client) Pull 

func (c *Client) Pull(ctx context.Context, recordRef *corev1.RecordRef) (*corev1.Record, error)

Pull retrieves a single record from the store using its reference. This is a convenience wrapper around PullBatch for single-record operations.

func (*Client) PullBatch 

func (c *Client) PullBatch(ctx context.Context, recordRefs []*corev1.RecordRef) ([]*corev1.Record, error)

PullBatch retrieves multiple records in a single stream for efficiency. This is a convenience method that accepts a slice and returns a slice, built on top of the streaming implementation for consistency.

func (*Client) PullPublicKeys added in v1.1.0 

func (c *Client) PullPublicKeys(ctx context.Context, recordRef *corev1.RecordRef) ([]string, error)

PullPublicKeys fetches all public key referrers for a record.

func (*Client) PullReferrer 

func (c *Client) PullReferrer(ctx context.Context, req *storev1.PullReferrerRequest) ([]*storev1.PullReferrerResponse, error)

PullReferrer retrieves all referrers using the PullReferrer RPC.

func (*Client) PullSignatures added in v1.1.0 

func (c *Client) PullSignatures(ctx context.Context, recordRef *corev1.RecordRef) ([]*signv1.Signature, error)

PullSignatures fetches all signature referrers for a record.

func (*Client) PullStream 

func (c *Client) PullStream(ctx context.Context, refsCh <-chan *corev1.RecordRef) (streaming.StreamResult[corev1.Record], error)

PullStream retrieves multiple records efficiently using a single bidirectional stream. This method is ideal for batch operations and takes full advantage of gRPC streaming. The input channel allows you to send record refs as they become available.

func (*Client) Push 

func (c *Client) Push(ctx context.Context, record *corev1.Record) (*corev1.RecordRef, error)

Push sends a complete record to the store and returns a record reference. This is a convenience wrapper around PushBatch for single-record operations. The record must be ≤4MB as per the v1 store service specification.

func (*Client) PushBatch 

func (c *Client) PushBatch(ctx context.Context, records []*corev1.Record) ([]*corev1.RecordRef, error)

PushBatch sends multiple records in a single stream for efficiency. This is a convenience method that accepts a slice and returns a slice, built on top of the streaming implementation for consistency.

func (*Client) PushReferrer 

func (c *Client) PushReferrer(ctx context.Context, req *storev1.PushReferrerRequest) (*storev1.PushReferrerResponse, error)

PushReferrer stores a signature using the PushReferrer RPC.

func (*Client) PushScanReport added in v1.6.0 

func (c *Client) PushScanReport(ctx context.Context, recordRef *corev1.RecordRef, report *securityv1.ScanReport) error

PushScanReport stores a ScanReport as a referrer attached to the given record. Failures are returned so the caller can decide whether to treat them as fatal.

func (*Client) PushStream 

func (c *Client) PushStream(ctx context.Context, recordsCh <-chan *corev1.Record) (streaming.StreamResult[corev1.RecordRef], error)

PushStream uploads multiple records efficiently using a single bidirectional stream. This method is ideal for batch operations and takes full advantage of gRPC streaming. The input channel allows you to send records as they become available.

func (*Client) Resolve added in v1.0.0 

func (c *Client) Resolve(ctx context.Context, name, version string) (*identityv1.ResolveResponse, error)

Resolve resolves a record name, with an optional version, to CIDs. Returns all matching records newest first; if version is empty, all versions.

func (*Client) SearchCIDs added in v0.5.6 

func (c *Client) SearchCIDs(ctx context.Context, req *searchv1.SearchCIDsRequest) (streaming.StreamResult[searchv1.SearchCIDsResponse], error)

SearchCIDs searches for record CIDs matching the given request.

func (*Client) SearchRecords added in v0.5.6 

func (c *Client) SearchRecords(ctx context.Context, req *searchv1.SearchRecordsRequest) (streaming.StreamResult[searchv1.SearchRecordsResponse], error)

SearchRecords searches for full records matching the given request.

func (*Client) SearchRouting 

func (c *Client) SearchRouting(ctx context.Context, req *routingv1.SearchRequest) (<-chan *routingv1.SearchResponse, error)

func (*Client) Sign 

func (c *Client) Sign(ctx context.Context, req *signv1.SignRequest) (*signv1.SignResponse, error)

Sign routes to the appropriate signing method based on provider type. This is the main entry point for signing operations.

func (*Client) Unpublish 

func (c *Client) Unpublish(ctx context.Context, req *routingv1.UnpublishRequest) error

func (*Client) Verify 

func (c *Client) Verify(ctx context.Context, req *signv1.VerifyRequest) (*signv1.VerifyResponse, error)

Verify verifies signatures for a record. When from_server is true, the result is the server's cached verification; when false, verification is performed locally.

type Config 

type Config struct {
	ServerAddress    string `json:"server_address,omitempty"     mapstructure:"server_address"`
	TlsSkipVerify    bool   `json:"tls_skip_verify,omitempty"    mapstructure:"tls_skip_verify"`
	TlsCertFile      string `json:"tls_cert_file,omitempty"      mapstructure:"tls_cert_file"`
	TlsKeyFile       string `json:"tls_key_file,omitempty"       mapstructure:"tls_key_file"`
	TlsCAFile        string `json:"tls_ca_file,omitempty"        mapstructure:"tls_ca_file"`
	SpiffeSocketPath string `json:"spiffe_socket_path,omitempty" mapstructure:"spiffe_socket_path"`
	SpiffeToken      string `json:"spiffe_token,omitempty"       mapstructure:"spiffe_token"`
	AuthMode         string `json:"auth_mode,omitempty"          mapstructure:"auth_mode"`
	JWTAudience      string `json:"jwt_audience,omitempty"       mapstructure:"jwt_audience"`

	// OIDC configuration (for interactive login)
	OIDCIssuer   string   `json:"oidc_issuer,omitempty"    mapstructure:"oidc_issuer"`
	OIDCClientID string   `json:"oidc_client_id,omitempty" mapstructure:"oidc_client_id"`
	OIDCScopes   []string `json:"oidc_scopes,omitempty"    mapstructure:"oidc_scopes"`

	// OIDCAudience is the audience requested when minting tokens on demand,
	// currently from the GitHub Actions OIDC endpoint.
	OIDCAudience string `json:"oidc_audience,omitempty" mapstructure:"oidc_audience"`

	// Pre-issued Bearer token for CI/scripts (skips interactive login)
	AuthToken string `json:"auth_token,omitempty" mapstructure:"auth_token"`
}

func LoadConfig 

func LoadConfig() (*Config, error)

type CreateSyncOptions added in v1.3.0 

type CreateSyncOptions struct {
	RemoteRegistryURL string
	RepositoryName    string
}

CreateSyncOptions holds optional parameters for creating a sync.

type DeviceFlowConfig added in v1.0.0 

type DeviceFlowConfig struct {
	Issuer       string
	ClientID     string
	Scopes       []string
	PollInterval time.Duration
	Timeout      time.Duration
	Output       io.Writer
}

DeviceFlowConfig holds configuration for the OAuth 2.0 Device Authorization Grant (RFC 8628).

type OIDCProvider added in v1.2.0 

type OIDCProvider struct{}

OIDCProvider groups OIDC-related methods.

func (*OIDCProvider) RefreshAccessToken added in v1.3.0 

func (*OIDCProvider) RefreshAccessToken(ctx context.Context, cfg *RefreshTokenConfig) (*AuthResult, error)

RefreshAccessToken exchanges a cached refresh token for fresh access credentials.

func (*OIDCProvider) RunDeviceFlow added in v1.2.0 

func (*OIDCProvider) RunDeviceFlow(ctx context.Context, cfg *DeviceFlowConfig) (*AuthResult, error)

RunDeviceFlow performs the OAuth 2.0 Device Authorization Grant (RFC 8628).

func (*OIDCProvider) RunPKCEFlow added in v1.2.0 

func (*OIDCProvider) RunPKCEFlow(ctx context.Context, cfg *PKCEConfig) (*AuthResult, error)

RunPKCEFlow performs the OIDC Authorization Code flow with PKCE.

type Option 

type Option func(*options) error

func WithConfig 

func WithConfig(config *Config) Option

func WithEnvConfig 

func WithEnvConfig() Option

type PKCEConfig added in v1.2.0 

type PKCEConfig struct {
	Issuer          string
	ClientID        string
	RedirectURI     string
	Scopes          []string
	CallbackPort    int
	SkipBrowserOpen bool
	Timeout         time.Duration
	Output          io.Writer
}

PKCEConfig holds configuration for the OIDC PKCE flow.

type RefreshTokenConfig added in v1.3.0 

type RefreshTokenConfig struct {
	Issuer       string
	ClientID     string
	RefreshToken string
	Timeout      time.Duration
}

RefreshTokenConfig holds configuration for the OAuth 2.0 refresh token grant.

type TokenCache added in v1.0.0 

type TokenCache struct {
	// CacheDir is the directory where tokens are stored.
	CacheDir string

	// CacheFile is the cache filename inside CacheDir.
	CacheFile string

	// Issuer is the issuer this cache is scoped to, if any.
	Issuer string
}

TokenCache manages cached authentication tokens from any provider.

func NewTokenCache added in v1.0.0 

func NewTokenCache() *TokenCache

NewTokenCache creates a new token cache with the default directory. Respects XDG_CONFIG_HOME environment variable for config directory location.

func NewTokenCacheForIssuer added in v1.3.0 

func NewTokenCacheForIssuer(issuer string) (*TokenCache, error)

NewTokenCacheForIssuer creates a token cache scoped to a specific issuer.

func NewTokenCacheWithDir added in v1.0.0 

func NewTokenCacheWithDir(dir string) *TokenCache

NewTokenCacheWithDir creates a new token cache with a custom directory.

func NewTokenCacheWithDirAndIssuer added in v1.3.0 

func NewTokenCacheWithDirAndIssuer(dir, issuer string) (*TokenCache, error)

NewTokenCacheWithDirAndIssuer creates a token cache for a specific issuer using a custom root directory.

func ResolveTokenCacheForIssuer added in v1.3.0 

func ResolveTokenCacheForIssuer(issuer string) (*TokenCache, error)

ResolveTokenCacheForIssuer resolves the appropriate token cache. If issuer is provided, the corresponding issuer-scoped cache is returned. If issuer is empty, the only available issuer cache is returned when exactly one exists. Returns ErrNoCachedIssuer when no issuer is provided and no caches exist.

func (*TokenCache) Clear added in v1.0.0 

func (c *TokenCache) Clear() error

Clear removes the cached token.

func (*TokenCache) GetCachePath added in v1.0.0 

func (c *TokenCache) GetCachePath() string

GetCachePath returns the full path to the token cache file.

func (*TokenCache) GetValidToken added in v1.0.0 

func (c *TokenCache) GetValidToken() (*CachedToken, error)

GetValidToken returns a valid cached token or nil if none exists.

func (*TokenCache) IsValid added in v1.0.0 

func (c *TokenCache) IsValid(token *CachedToken) bool

IsValid checks if a cached token is still valid. A token is considered valid if it exists and hasn't expired.

func (*TokenCache) Load added in v1.0.0 

func (c *TokenCache) Load() (*CachedToken, error)

Load loads the cached token from disk. Returns nil if no valid token is found.

func (*TokenCache) Save added in v1.0.0 

func (c *TokenCache) Save(token *CachedToken) error

Save saves a token to the cache.

func (*TokenCache) SaveAtomic added in v1.3.0 

func (c *TokenCache) SaveAtomic(token *CachedToken) error

SaveAtomic saves a token using atomic replacement to prevent partial cache writes.

type TokenCacheEntry added in v1.0.0 

type TokenCacheEntry = CachedToken

TokenCacheEntry is an alias for CachedToken (for compatibility).

Source Files

View all Source files

Directories

Path Synopsis
Package config loads reusable Directory client context configuration.
 Package config loads reusable Directory client context configuration.
utils
cosign
identity
Package identity signs and verifies identity.v1 Claims on top of the payload-agnostic client/utils/jws package.
 Package identity signs and verifies identity.v1 Claims on top of the payload-agnostic client/utils/jws package.
identity/resolvers
Package resolvers defines what an identity key resolver is.
 Package resolvers defines what an identity key resolver is.
identity/resolvers/ans
Package ansresolver resolves "ans://" subjects.
 Package ansresolver resolves "ans://" subjects.
identity/resolvers/did
identity/resolvers/dns
identity/resolvers/spiffe
identity/resolvers/wellknown
internal/testutil
Package testutil holds test fixtures shared by the jws, identity and resolver packages: key generators, PEM and certificate helpers, a fake fetcher, key assertions, and the sign-resolve-verify claim flow.
 Package testutil holds test fixtures shared by the jws, identity and resolver packages: key generators, PEM and certificate helpers, a fake fetcher, key assertions, and the sign-resolve-verify claim flow.
jws
Package jws signs and verifies detached-payload JWS (RFC 7515) signatures.
 Package jws signs and verifies detached-payload JWS (RFC 7515) signatures.
verify
Package verify provides signature verification types and logic (Fetcher, VerifyWithFetcher).
 Package verify provides signature verification types and logic (Fetcher, VerifyWithFetcher).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.