go-ctap/kit is a reusable Go runtime for applications that work with local FIDO2 authenticators. It provides device discovery, safe multi-step workflows, typed results, user interaction callbacks, and stable errors.

The library is the shared runtime used by the go-ctap application family. It can be used by desktop, command-line, and terminal applications, but it does not contain any user interface code.

The runtime is built on go-ctap/ctap and supports authenticator features from CTAP 2.0 through CTAP 2.3. Each operation still depends on the capabilities reported by the connected authenticator.

Main features include:

• authenticator inspection and CTAP conformance reports;
• PIN setup and change;
• built-in user verification and biometric enrollment;
• authenticator configuration and factory reset;
• resident credential listing, update, and deletion;
• large-blob reading, writing, deletion, and garbage collection;
• WebAuthn credential creation and assertion;
• progressive vendor device identity resolution;
• FIDO Metadata Service (MDS3) lookup and verification;
• operation progress events and interaction callbacks;
• bounded and redacted CTAP diagnostic logs.

This repository is a library, not a CLI. It does not provide command parsing, prompts, confirmation screens, tables, JSON rendering, or product-specific workflows. Applications must provide those parts.

BLE and hybrid transports are not part of this runtime.

go get github.com/go-ctap/kit@latest

See go.mod for the required Go version.

The example below discovers authenticators, opens the first one, and reads its public information. A real application should let the user choose when more than one device is available.

package main

import (
	"context"
	"fmt"
	"log"

	ctapkit "github.com/go-ctap/kit"
	"github.com/go-ctap/kit/transport"
)

func main() {
	ctx := context.Background()

	inventory, err := ctapkit.OpenInventory(ctx, transport.ModeAuto)
	if err != nil {
		log.Fatal(err)
	}
	defer inventory.Close()

	snapshot := inventory.Snapshot()
	if len(snapshot.Devices) == 0 {
		log.Fatal("no FIDO2 authenticator found")
	}

	authenticator, err := inventory.OpenAuthenticator(
		ctx,
		snapshot.Devices[0].Attachment.ID,
	)
	if err != nil {
		log.Fatal(err)
	}
	defer func() {
		if err := authenticator.Close(); err != nil {
			log.Printf("close authenticator: %v", err)
		}
	}()

	inspection, err := authenticator.Inspect(ctx)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("attachment: %s\n", inspection.Device.Attachment.ID)
	fmt.Printf("versions: %v\n", inspection.Info.Versions)
	fmt.Printf("AAGUID: %s\n", inspection.Info.AAGUID)
}

Inventory.Snapshot publishes attachments immediately. Vendor identity arrives later through full snapshot events from Inventory.Events without changing the attachment ID or list order. HID authenticators can open while that optional identity is still resolving. Smart-card opens wait for the resolver to release its exclusive PC/SC access. DeviceIdentity.Details is a tagged collection of provider-specific reports; the Yubico section includes device-information properties that do not belong in the normalized identity fields.

A normal application follows this lifecycle:

1. Open one ctapkit.Inventory for a fixed transport mode.
2. Choose an attachment from its snapshot.
3. Open it with Inventory.OpenAuthenticator.
4. Run typed operations on the returned *ctapkit.Authenticator.
5. Close the authenticator when selection changes, then close the inventory when the application exits.

An Inventory owns transport monitoring and independent identity-resolution tasks for its attachments. An Authenticator owns one open transport channel, its token cache, and its close and cancellation state. It runs one complete workflow at a time. This prevents two multi-command operations on the same channel from mixing with each other.

Credential-list and configuration workflows read current state per operation. Large-blob workflows are the deliberate exception: ListLargeBlobs refreshes private in-memory inventory for the selected open authenticator, and read, preview, and mutation operations reuse that inventory. A successful mutation updates the retained large-blob array. Credential mutations, WebAuthn large-blob writes, and factory reset invalidate the inventory so the next large-blob operation reloads it. Dry runs leave it unchanged, and an explicit ListLargeBlobs always refreshes it. The state never crosses the authenticator boundary, and its credential keys are cleared on invalidation, refresh, and close.

Authenticator.Close is safe to call more than once or while another goroutine is using the authenticator. It cancels the active operation, clears owned secret state, and closes the transport.

The root ctapkit package is the public runtime facade. Operation inputs and results are typed DTOs from the model packages.

Operation methods return concrete result values. When an operation returns an error, its result is always the zero value, regardless of whether the workflow had already started. A populated result is returned only for a successful workflow, including preview-only dry runs; outputs may leave a nested mutation result nil for previews.

Large-blob behavior follows CTAP 2.3 section 6.10. ReadLargeBlob returns the credential's opaque bytes without interpreting their application format. A successful missing state means either that no largeBlobKey was returned for the credential or that no conforming array entry authenticated with that key. Once an entry authenticates, a DEFLATE or origSize failure is an operation error and the read report is zero.

DecodeLargeBlob is a pure helper for interpreting successfully read bytes as UTF-8, JSON, or CBOR. Decode failures return a zero decode result. ListLargeBlobs is the diagnostic array view: entries are matched, orphaned, nonconforming, or corrupt. Here corrupt means that AEAD authentication matched an enumerated credential but DEFLATE or origSize validation failed. Garbage collection follows the narrower CTAP rule: it retains every AEAD-matched entry, including one with corrupt compressed data, and removes each conforming entry that fails authentication with all valid enumerated largeBlobKey values. If the serialized array's trailing integrity hash is invalid, the runtime discards it and observes the CTAP initial empty array, as required for a corrupt or torn write.

Some operations need a PIN, built-in user verification, or a physical touch. Pass ctapkit.WithInteractionHandler to the operation that may need this input. The handler receives a typed model.InteractionRequest and returns a typed model.InteractionResponse.

Progress is separate from interaction. Pass ctapkit.WithEventSink to receive typed model.OperationEvent values, such as credential enumeration or biometric sample progress.

Both callbacks belong to one operation. The runtime does not store them on the open authenticator. This makes request ownership and cancellation easier for applications with several tasks or windows.

The default verification flow prefers built-in user verification when the authenticator supports it and falls back to PIN when CTAP allows this. To ask for PIN first, pass:

ctapkit.WithVerificationFlow(ctapkit.VerificationFlowPIN)

The authenticator always makes the final decision about whether a verification method succeeds.

ctapkit.VerifyMakeCredential and ctapkit.VerifyGetAssertion perform local structural and signature verification. They correlate the operation input with the runtime result and return a compact verified, failed, or unavailable summary. Verification does not use the network, clock, MDS, or an application trust policy.

These helpers do not replace relying-party validation of the WebAuthn ceremony. The application still owns expected challenge and origin checks, client-data type policy, and attestation trust decisions. Applications can obtain verified FIDO metadata separately with github.com/go-ctap/mds.

Mutating operations return a typed preview before they change authenticator state. Many operation DTOs also have a DryRun field.

output, err := authenticator.DeleteCredential(
	ctx,
	credentials.DeleteOperation{
		CredentialIDHex: credentialID,
		DryRun:          true,
	},
)

For a dry run, the preview is filled and the mutation result is nil. The consumer must show warnings, ask for confirmation when needed, and decide whether to run the real operation. The runtime does not implement product confirmation rules.

Public failures use model/failure. Each known error has a stable code and a recovery category. CTAP errors can also include the command, subcommand, and status that caused the failure.

result, err := authenticator.ListCredentials(ctx)
if err != nil {
	if failure.IsCode(err, failure.CodeInteractionHandlerRequired) {
		// Run the operation again with an interaction handler.
	}

	snapshot := failure.Snapshot(err)
	_ = result
	_ = snapshot
}

Use failure.IsCode for application decisions. Do not parse err.Error(). The full wire format and recovery rules are described in docs/error-contract.md.

Create a journal and pass it when the authenticator is opened:

journal := ctapkit.NewLogJournal()

authenticator, err := ctapkit.OpenAuthenticator(
	ctx,
	device,
	ctapkit.WithLogJournal(journal),
)
if err != nil {
	return err
}

batch := journal.Read(0)

The journal stores a bounded, in-memory list of CTAP exchanges. Request and response CBOR is decoded through known protocol types and sensitive fields are redacted. It is useful for debugging, but it is not a byte-exact wire capture. Unknown CBOR fields may be missing.

Diagnostic records can still contain device, relying-party, user, credential, or biometric identifiers. Treat them as sensitive data.

Packages under internal contain runtime implementation details and are not a public API.

• Always close Authenticator when it is no longer needed.
• Treat authenticator state as changeable between commands.
• Do not log or store PINs, PIN/UV tokens, credential secrets, or large-blob payloads.
• PIN fields in public configuration operation DTOs are omitted during JSON encoding.
• Runtime-owned PIN/UV token buffers are wiped when they are released.
• A dry run is a preview, not authorization to run a mutation.
• Credential deletion, large-blob deletion, and factory reset need clear confirmation in the consuming application.
• Many displayless authenticators require factory reset soon after power-up. Ask for confirmation before reconnecting or power-cycling the device.
• One opened authenticator runs its own workflows one at a time. It does not create a process-wide or device-wide lock.

More lifecycle details are available in docs/current-runtime-flows.md.

Run the default checks with:

go test ./... -count=1
go vet ./...

For authenticator lifecycle, interaction, token, or synchronization changes, also run:

go test -race ./... -count=1

Hardware-dependent behavior must not be required by the default test suite.

• go-ctap/ctap
• go-ctap/hid
• go-ctap/windows-proxy
• Client to Authenticator Protocol 2.0
• Client to Authenticator Protocol 2.1
• Client to Authenticator Protocol 2.2
• Client to Authenticator Protocol 2.3
• Web Authentication Level 3