# zig-ctap2

> Portable CTAP2/FIDO2 library in Zig -- direct USB HID communication with security keys

## Overview

zig-ctap2 is a standalone CTAP2/FIDO2 implementation in Zig that communicates directly with USB HID security keys (YubiKey, SoloKeys, etc.) without requiring platform authentication frameworks or restricted Apple entitlements.

## Key Facts

- Language: Zig 0.15.2+
- Platforms: macOS (IOKit), Linux (hidraw)
- License: Zlib OR MIT
- API: C FFI (16+ exported functions)
- Tested with: YubiKey 5C NFC

## C API Summary

All functions are blocking with timeouts and are thread-safe.

Core operations:
- ctap2_device_count() -- enumerate connected FIDO2 devices
- ctap2_make_credential() -- register a credential (raw CBOR)
- ctap2_get_assertion() -- authenticate (raw CBOR)
- ctap2_get_info() -- device capabilities

Parsed response variants:
- ctap2_make_credential_parsed() -- register + parse response
- ctap2_get_assertion_parsed() -- authenticate + parse response

PIN protocol v2:
- ctap2_get_pin_retries() -- check remaining retries
- ctap2_get_pin_token() -- ECDH + AES handshake for PIN token
- ctap2_make_credential_with_pin() -- PIN-authenticated registration
- ctap2_get_assertion_with_pin() -- PIN-authenticated assertion

Keepalive callbacks:
- ctap2_make_credential_with_keepalive() -- registration with user-touch callback
- ctap2_get_assertion_with_keepalive() -- assertion with user-touch callback

Utilities:
- ctap2_status_message() -- human-readable error messages
- ctap2_debug_last_ioreturn() -- last IOKit return code

## Architecture

Application -> C FFI (ffi.zig) -> CTAP2 commands (ctap2.zig) + PIN protocol (pin.zig) -> CBOR codec (cbor.zig) -> CTAPHID framing (ctaphid.zig) -> Platform HID (IOKit/hidraw)

## Source Files

- src/ffi.zig -- C FFI exports
- src/ctap2.zig -- CTAP2 command encoding + response parsing
- src/cbor.zig -- Minimal CBOR codec
- src/ctaphid.zig -- CTAPHID framing (64-byte packets)
- src/hid.zig -- Platform HID abstraction
- src/hid_macos.zig -- IOKit HID transport
- src/hid_linux.zig -- hidraw transport
- src/pin.zig -- PIN protocol v2
- include/ctap2.h -- C header

## Links

- Repository: https://github.com/Jesssullivan/zig-ctap2
- Documentation: https://jesssullivan.github.io/zig-ctap2/