client

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: May 4, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package client exposes the public FIDO SDK facade built on top of transport sessions, middleware, and protocol-specific raw invokers.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrSessionRequired reports that client construction requires a transport session.
	ErrSessionRequired = errors.New("client: session is required")
	// ErrRawInvokerRequired reports that raw invoker options cannot be nil.
	ErrRawInvokerRequired = errors.New("client: raw invoker is required")
	// ErrMiddlewareRequired reports that middleware options cannot be nil.
	ErrMiddlewareRequired = errors.New("client: middleware is required")
	// ErrInteractionHandlerRequired reports that interaction options cannot be nil.
	ErrInteractionHandlerRequired = errors.New("client: interaction handler is required")
	// ErrTraceRecorderRequired reports that tracing options cannot be nil.
	ErrTraceRecorderRequired = errors.New("client: trace recorder is required")
	// ErrPINRequired reports that the requested flow requires a PIN value.
	ErrPINRequired = errors.New("client: pin is required")
	// ErrNewPINRequired reports that the requested flow requires a replacement PIN value.
	ErrNewPINRequired = errors.New("client: new pin is required")
	// ErrNoCapableProtocol reports that no registered protocol probe succeeded.
	ErrNoCapableProtocol = errors.New("client: no capable protocol detected")
)

Functions

func Supported 

func Supported(candidate Client, family protocol.Family) bool

Supported reports whether the client configuration includes a raw invoker for the family.

Types

type AuthenticationRequest 

type AuthenticationRequest struct {
	ChallengeHash []byte
	RPID          string
	Selection     AuthenticatorSelection

	CTAP1 *CTAP1AuthenticationOptions
	CTAP2 *CTAP2AuthenticationOptions
}

AuthenticationRequest describes a semantic authentication flow with protocol-specific overrides.

type AuthenticationResult 

type AuthenticationResult struct {
	Protocol     ProtocolFamily
	CredentialID []byte
	Signature    []byte
	SignCount    uint32
	UserPresent  bool
	UserVerified bool

	RawCTAP1 *ctap1.AuthenticateResponse
	RawCTAP2 *ctap2.GetAssertionResponse
}

AuthenticationResult contains normalized authentication details plus raw protocol responses.

type AuthenticatorCapabilities 

type AuthenticatorCapabilities struct {
	ResidentKey                 bool `json:"residentKey,omitempty"`
	CredentialManagement        bool `json:"credentialManagement,omitempty"`
	CredentialManagementPreview bool `json:"credentialManagementPreview,omitempty"`
}

AuthenticatorCapabilities describes normalized authenticator-management support.

type AuthenticatorInfo 

type AuthenticatorInfo = ctap2.GetInfoResponse

AuthenticatorInfo aliases the raw authenticatorGetInfo response for CTAP2 callers.

type AuthenticatorSelection 

type AuthenticatorSelection struct {
	UserPresence     Requirement
	UserVerification UserVerificationPolicy
}

AuthenticatorSelection declares common policy applied before protocol-specific overrides.

type AuthenticatorTransport 

type AuthenticatorTransport string

AuthenticatorTransport identifies one credential transport in the public facade API. 

const (
	// AuthenticatorTransportUSB reports USB transport support.
	AuthenticatorTransportUSB AuthenticatorTransport = "usb"
	// AuthenticatorTransportNFC reports NFC transport support.
	AuthenticatorTransportNFC AuthenticatorTransport = "nfc"
	// AuthenticatorTransportBLE reports BLE transport support.
	AuthenticatorTransportBLE AuthenticatorTransport = "ble"
	// AuthenticatorTransportInternal reports a platform-bound authenticator.
	AuthenticatorTransportInternal AuthenticatorTransport = "internal"
)

type BioEnrollment 

type BioEnrollment struct {
	FriendlyName string `json:"friendlyName,omitempty"`
}

BioEnrollment describes one provisioned biometric enrollment.

type BioManager 

type BioManager interface {
	Supported(ctx context.Context) (bool, error)
	Enrollments(ctx context.Context, authorization UVAuthorization) ([]BioEnrollment, error)
}

BioManager exposes CTAP2 bio-enrollment capabilities.

type CTAP1AuthenticationOptions 

type CTAP1AuthenticationOptions struct {
	AppIDHash []byte
	KeyHandle []byte
	Control   ctap1.Control
}

CTAP1AuthenticationOptions contains CTAP1-specific authentication overrides.

type CTAP1Capabilities 

type CTAP1Capabilities struct {
	Version string `json:"version,omitempty"`
}

CTAP1Capabilities describes the detected CTAP1 capability baseline.

type CTAP1RegistrationOptions 

type CTAP1RegistrationOptions struct {
	AppIDHash []byte
}

CTAP1RegistrationOptions contains CTAP1-specific registration overrides.

type CTAP2AuthenticationOptions 

type CTAP2AuthenticationOptions struct {
	AllowList []CredentialDescriptor
}

CTAP2AuthenticationOptions contains CTAP2-specific authentication overrides.

type CTAP2Client 

type CTAP2Client interface {
	Info(ctx context.Context) (*AuthenticatorInfo, error)
	PIN() PINManager
	Credentials() CredentialManager
	Bio() BioManager
	Reset(ctx context.Context) error
}

CTAP2Client exposes CTAP2-specific management and administration operations.

type CTAP2RegistrationOptions 

type CTAP2RegistrationOptions struct {
	RPName               string
	ResidentKey          bool
	CredentialParameters []CredentialParameter
	ExcludeList          []CredentialDescriptor
}

CTAP2RegistrationOptions contains CTAP2-specific registration overrides.

type CTAP2UnavailableError 

type CTAP2UnavailableError struct {
	Device transport.DeviceDescriptor
}

CTAP2UnavailableError reports that the selected authenticator does not expose CTAP2.

func (*CTAP2UnavailableError) Error 

func (err *CTAP2UnavailableError) Error() string

Error returns the missing-CTAP2 message.

type Capabilities 

type Capabilities struct {
	Protocols     ProtocolCapabilities      `json:"protocols"`
	Authenticator AuthenticatorCapabilities `json:"authenticator"`
	Verification  VerificationCapabilities  `json:"verification"`
	Interaction   InteractionCapabilities   `json:"interaction"`

	RawCTAP1 *CTAP1Capabilities     `json:"rawCtap1,omitempty"`
	RawCTAP2 *ctap2.GetInfoResponse `json:"rawCtap2,omitempty"`
}

Capabilities describes detected authenticator support in a stable public shape.

func (*Capabilities) HasCTAP1 

func (caps *Capabilities) HasCTAP1() bool

HasCTAP1 reports whether CTAP1 support has been detected.

func (*Capabilities) HasCTAP2 

func (caps *Capabilities) HasCTAP2() bool

HasCTAP2 reports whether CTAP2 support has been detected.

func (*Capabilities) PreferredProtocol 

func (caps *Capabilities) PreferredProtocol() (protocol.Family, bool)

PreferredProtocol reports the highest-preference detected protocol family.

type Client 

type Client interface {
	Device() transport.DeviceDescriptor
	Capabilities(ctx context.Context) (*Capabilities, error)
	CTAP2(ctx context.Context) (CTAP2Client, error)
	Register(ctx context.Context, request RegistrationRequest) (*RegistrationResult, error)
	Authenticate(ctx context.Context, request AuthenticationRequest) (*AuthenticationResult, error)
	InvokeRaw(ctx context.Context, family protocol.Family, command byte, payload []byte) ([]byte, error)
	Close() error
}

Client is the public FIDO SDK facade.

func New 

func New(session transport.Session, options ...Option) (Client, error)

New creates a client facade over the supplied transport session.

type CredentialDescriptor 

type CredentialDescriptor struct {
	Type       string
	ID         []byte
	Transports []AuthenticatorTransport
}

CredentialDescriptor identifies an existing credential in the public facade API.

type CredentialListResult 

type CredentialListResult struct {
	ExistingResidentCredentialsCount             uint64                   `json:"existingResidentCredentialsCount,omitempty"`
	MaxPossibleRemainingResidentCredentialsCount uint64                   `json:"maxPossibleRemainingResidentCredentialsCount,omitempty"`
	Credentials                                  []DiscoverableCredential `json:"credentials"`
}

CredentialListResult contains credential-management metadata and the enumerated credentials.

type CredentialManager 

type CredentialManager interface {
	List(ctx context.Context, authorization UVAuthorization) (*CredentialListResult, error)
	Delete(ctx context.Context, credential CredentialDescriptor, authorization UVAuthorization) error
}

CredentialManager exposes CTAP2 credential-management operations.

type CredentialParameter 

type CredentialParameter struct {
	Type string
	Alg  int64
}

CredentialParameter describes one requested public-key credential algorithm in the public facade API.

type Device 

type Device = transport.DeviceDescriptor

Device aliases the public transport device descriptor for facade consumers.

type DeviceNotFoundError 

type DeviceNotFoundError struct {
	DeviceID string
}

DeviceNotFoundError reports that the requested device could not be resolved.

func (*DeviceNotFoundError) Error 

func (err *DeviceNotFoundError) Error() string

Error returns the missing-device message.

type DiscoverableCredential 

type DiscoverableCredential struct {
	RP           ctap2.RelyingPartyEntity `json:"rp"`
	RPIDHash     []byte                   `json:"rpIdHash,omitempty"`
	User         ctap2.UserEntity         `json:"user"`
	Credential   CredentialDescriptor     `json:"credential"`
	CredProtect  uint64                   `json:"credProtect,omitempty"`
	LargeBlobKey []byte                   `json:"largeBlobKey,omitempty"`
}

DiscoverableCredential describes one resident credential returned by credential management.

type DuplicateRawInvokerError 

type DuplicateRawInvokerError struct {
	Family protocol.Family
}

DuplicateRawInvokerError reports an attempt to register multiple invokers for the same protocol.

func (*DuplicateRawInvokerError) Error 

func (err *DuplicateRawInvokerError) Error() string

Error returns the duplicate invoker message.

type InteractionCapabilities 

type InteractionCapabilities struct {
	UserPresence        bool `json:"userPresence,omitempty"`
	UserVerification    bool `json:"userVerification,omitempty"`
	BuiltInUV           bool `json:"builtInUv,omitempty"`
	NFCImplicitPresence bool `json:"nfcImplicitPresence,omitempty"`
}

InteractionCapabilities describes normalized interaction requirements.

type InteractionEvent 

type InteractionEvent struct {
	Kind      InteractionKind `json:"kind"`
	Operation string          `json:"operation,omitempty"`
	Protocol  ProtocolFamily  `json:"protocol,omitempty"`
	Transport transport.Kind  `json:"transport,omitempty"`
	Message   string          `json:"message,omitempty"`
	Retryable bool            `json:"retryable,omitempty"`
}

InteractionEvent describes one authenticator interaction requirement.

type InteractionHandler 

type InteractionHandler interface {
	OnInteraction(ctx context.Context, event InteractionEvent)
	RequestPIN(ctx context.Context, req PINRequest) (Secret, error)
}

InteractionHandler receives user-interaction events and PIN prompts.

type InteractionKind 

type InteractionKind string

InteractionKind identifies the current interaction state. 

const (
	// InteractionAwaitingUserPresence reports that the authenticator is waiting for user presence.
	InteractionAwaitingUserPresence InteractionKind = "awaiting-user-presence"
	// InteractionAwaitingUserVerification reports that the authenticator is waiting for user verification.
	InteractionAwaitingUserVerification InteractionKind = "awaiting-user-verification"
	// InteractionAwaitingPIN reports that the platform needs a PIN value.
	InteractionAwaitingPIN InteractionKind = "awaiting-pin"
	// InteractionProcessing reports that an authenticator command is in progress.
	InteractionProcessing InteractionKind = "processing"
	// InteractionReinsertRequired reports that the authenticator must be reinserted or tapped again.
	InteractionReinsertRequired InteractionKind = "reinsert-required"
)

type Locator 

type Locator interface {
	List(ctx context.Context) ([]Device, error)
	Open(ctx context.Context, deviceID string, options ...Option) (Client, error)
}

Locator discovers devices and opens client sessions without exposing transport internals to callers.

func NewDefaultLocator 

func NewDefaultLocator(options ...LocatorOption) (Locator, error)

NewDefaultLocator builds the default public locator for local authenticators.

By default it enables USB HID only. NFC/PCSC discovery is an explicit opt-in through WithNFC(true) because probing PC/SC readers can have side effects for other smart-card stacks already using the same token.

func NewTransportLocator 

func NewTransportLocator(backends ...transport.Backend) (Locator, error)

NewTransportLocator creates a client-facing locator on top of registered transport backends.

type LocatorOption added in v0.2.0 

type LocatorOption func(*locatorOptions)

LocatorOption configures the behavior of NewDefaultLocator.

func WithNFC added in v0.2.0 

func WithNFC(enabled bool) LocatorOption

WithNFC enables or disables NFC/PCSC discovery for NewDefaultLocator.

func WithUSB added in v0.2.0 

func WithUSB(enabled bool) LocatorOption

WithUSB enables or disables USB HID discovery for NewDefaultLocator.

type Option 

type Option func(*config) error

Option mutates the client configuration during construction.

func WithDefaultCTAP2RawInvoker 

func WithDefaultCTAP2RawInvoker() Option

WithDefaultCTAP2RawInvoker registers only the built-in CTAP2 raw invoker.

func WithDefaultRawInvokers 

func WithDefaultRawInvokers() Option

WithDefaultRawInvokers registers the built-in CTAP1 and CTAP2 raw invokers.

func WithInteraction 

func WithInteraction(handler InteractionHandler) Option

WithInteraction registers one interaction handler for user-presence and PIN prompts.

func WithMiddleware 

func WithMiddleware(wrapper middleware.Middleware) Option

WithMiddleware appends one middleware to the client exchange chain.

func WithRawInvoker 

func WithRawInvoker(invoker RawInvoker) Option

WithRawInvoker registers one protocol-specific raw invoker.

func WithTrace 

func WithTrace(recorder *TraceRecorder, options ...TraceOptions) Option

WithTrace records raw request and response metadata through the client middleware chain.

Sensitive CTAP2 commands are redacted by default. Pass TraceOptions{RedactSecrets:false} only for deliberate low-level debugging.

type PINManager 

type PINManager interface {
	Status(ctx context.Context) (*PINStatus, error)
	Set(ctx context.Context, newPIN Secret) error
	Change(ctx context.Context, currentPIN Secret, newPIN Secret) error
}

PINManager exposes CTAP2 ClientPIN operations.

type PINRequest 

type PINRequest struct {
	Operation string             `json:"operation,omitempty"`
	Protocol  ProtocolFamily     `json:"protocol,omitempty"`
	Transport transport.Kind     `json:"transport,omitempty"`
	Method    VerificationMethod `json:"method,omitempty"`
	Message   string             `json:"message,omitempty"`
}

PINRequest describes one PIN prompt initiated by the SDK.

type PINRetries 

type PINRetries struct {
	PINRetries      uint64
	UVRetries       uint64
	PowerCycleState bool
}

PINRetries describes the authenticator retry counters reported by ClientPIN.

type PINStatus 

type PINStatus struct {
	Configured       bool   `json:"configured"`
	Retries          uint64 `json:"retries,omitempty"`
	UVRetries        uint64 `json:"uvRetries,omitempty"`
	PowerCycleNeeded bool   `json:"powerCycleNeeded,omitempty"`
}

PINStatus summarizes the current PIN configuration state.

type ProtocolCapabilities 

type ProtocolCapabilities struct {
	CTAP1     bool           `json:"ctap1"`
	CTAP2     bool           `json:"ctap2"`
	Preferred ProtocolFamily `json:"preferred,omitempty"`
}

ProtocolCapabilities describes normalized protocol support for the selected authenticator.

type ProtocolFamily 

type ProtocolFamily = protocol.Family

ProtocolFamily aliases the public protocol-family type for facade consumers. 

const (
	// FamilyCTAP1 identifies the CTAP1/U2F protocol family.
	FamilyCTAP1 ProtocolFamily = protocol.FamilyCTAP1
	// FamilyCTAP2 identifies the CTAP2 protocol family.
	FamilyCTAP2 ProtocolFamily = protocol.FamilyCTAP2
)

type RawInvoker 

type RawInvoker interface {
	Protocol() protocol.Family
	InvokeRaw(ctx context.Context, exchange middleware.ExchangeFunc, command byte, payload []byte) ([]byte, error)
}

RawInvoker handles raw command invocation for one protocol family.

type RegistrationRequest 

type RegistrationRequest struct {
	ChallengeHash []byte
	RPID          string
	User          User
	Selection     AuthenticatorSelection

	CTAP1 *CTAP1RegistrationOptions
	CTAP2 *CTAP2RegistrationOptions
}

RegistrationRequest describes a semantic registration flow with protocol-specific overrides.

type RegistrationResult 

type RegistrationResult struct {
	Protocol          ProtocolFamily
	CredentialID      []byte
	AttestationFormat string
	UserPresent       bool
	UserVerified      bool

	RawCTAP1 *ctap1.RegisterResponse
	RawCTAP2 *ctap2.MakeCredentialResponse
}

RegistrationResult contains normalized registration details plus raw protocol responses.

type Requirement 

type Requirement string

Requirement describes how strongly an operation should request a capability. 

const (
	// RequirementDiscouraged avoids requesting the capability.
	RequirementDiscouraged Requirement = "discouraged"
	// RequirementPreferred uses the protocol default behavior.
	RequirementPreferred Requirement = "preferred"
	// RequirementRequired explicitly requests the capability.
	RequirementRequired Requirement = "required"
)

type Secret 

type Secret []byte

Secret holds sensitive caller-provided bytes such as authenticator PINs.

Prefer constructing Secret values from byte slices so interactive flows can avoid transient string copies in memory. Secret values are mutable so callers can wipe them after use. The SDK copies secrets at API boundaries when it needs to retain a value beyond validation.

func NewSecret 

func NewSecret(value []byte) Secret

NewSecret copies bytes into a wipeable secret value.

func NewSecretString 

func NewSecretString(value string) Secret

NewSecretString copies a string into a wipeable secret value.

func (Secret) Clone 

func (secret Secret) Clone() Secret

Clone returns a copy of the secret bytes.

func (Secret) Empty 

func (secret Secret) Empty() bool

Empty reports whether the secret has no bytes.

func (Secret) Wipe 

func (secret Secret) Wipe()

Wipe overwrites the bytes currently held by this Secret value.

type TraceDirection 

type TraceDirection string

TraceDirection identifies whether a recorded payload was outbound or inbound. 

const (
	// TraceDirectionRequest marks outbound transport payloads.
	TraceDirectionRequest TraceDirection = "request"
	// TraceDirectionResponse marks inbound transport payloads.
	TraceDirectionResponse TraceDirection = "response"
)

type TraceEvent 

type TraceEvent struct {
	Direction TraceDirection `json:"direction"`
	Payload   []byte         `json:"payload"`
	Redacted  bool           `json:"redacted,omitempty"`
	Command   byte           `json:"command,omitempty"`
	Length    int            `json:"length,omitempty"`
}

TraceEvent captures one exchanged payload for diagnostics.

type TraceOptions 

type TraceOptions struct {
	// RedactSecrets hides CTAP payloads likely to contain PIN, pinUvAuthToken,
	// credential-management, or other sensitive authenticator material.
	RedactSecrets bool
}

TraceOptions configures payload tracing.

type TraceRecorder 

type TraceRecorder struct {
	// contains filtered or unexported fields
}

TraceRecorder stores payload traces captured through client middleware.

func NewTraceRecorder 

func NewTraceRecorder() *TraceRecorder

NewTraceRecorder creates a trace recorder for CLI and debugging flows.

func (*TraceRecorder) Events 

func (recorder *TraceRecorder) Events() []TraceEvent

Events returns a stable copy of the recorded trace events.

type TransportPreference added in v0.2.0 

type TransportPreference struct {
	USB bool
	NFC bool
}

TransportPreference controls which transports NewDefaultLocator enables.

type UVAuthorization 

type UVAuthorization struct {
	PIN    Secret             `json:"-"`
	Method VerificationMethod `json:"method,omitempty"`
}

UVAuthorization describes one explicit authorization input for CTAP2 management.

type UnsupportedProtocolError 

type UnsupportedProtocolError struct {
	Family protocol.Family
}

UnsupportedProtocolError reports that the client has no raw invoker for the requested protocol.

func (*UnsupportedProtocolError) Error 

func (err *UnsupportedProtocolError) Error() string

Error returns the unsupported protocol message.

type User 

type User struct {
	ID          []byte
	Name        string
	DisplayName string
}

User identifies the account bound to a registration request.

type UserVerificationPolicy 

type UserVerificationPolicy string

UserVerificationPolicy declares how strongly an operation should require user verification. 

const (
	// UserVerificationDiscouraged allows operations to proceed without user verification.
	UserVerificationDiscouraged UserVerificationPolicy = "discouraged"
	// UserVerificationPreferred requests user verification when it is available.
	UserVerificationPreferred UserVerificationPolicy = "preferred"
	// UserVerificationRequired requires user verification for the operation to proceed.
	UserVerificationRequired UserVerificationPolicy = "required"
)

type VerificationCapabilities 

type VerificationCapabilities struct {
	ClientPIN          bool `json:"clientPin,omitempty"`
	BuiltInUV          bool `json:"builtInUv,omitempty"`
	PinUVAuthToken     bool `json:"pinUvAuthToken,omitempty"`
	BioEnrollment      bool `json:"bioEnrollment,omitempty"`
	UVRetriesAvailable bool `json:"uvRetriesAvailable,omitempty"`
}

VerificationCapabilities describes normalized user-verification support.

type VerificationMethod 

type VerificationMethod string

VerificationMethod identifies one authenticator-side user-verification method. 

const (
	// VerificationMethodPIN identifies ClientPIN verification.
	VerificationMethodPIN VerificationMethod = "pin"
	// VerificationMethodBuiltInUV identifies a built-in authenticator verifier.
	VerificationMethodBuiltInUV VerificationMethod = "built-in-uv"
)

Source Files

View all Source files

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.