# iamevanyt/electron-webauthn-native architecture

> Architecture diagram of the GitHub repository iamevanyt/electron-webauthn-native, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/iamevanyt/electron-webauthn-native
- Repository: https://github.com/iamevanyt/electron-webauthn-native

## Overview

##### Project type and purpose
- This is a native Node/Electron library (NPM package) that provides WebAuthn/Passkey support by binding into Rust code via NAPI-RS.
- It targets Electron apps on macOS, Windows, and Linux and leverages platform-specific authentication APIs (Touch ID, Face ID, Windows Hello, etc.).

##### File structure
- Top-level “index.js”/“index.d.ts” : the JavaScript/TypeScript entry point and type definitions.
- “src/lib.rs” + “src/platform/*.rs” : Rust core logic and per-OS modules.
- “build.rs” & Cargo.toml : Rust build script and configuration.
- “npm/<platform>/…” folders : prebuilt native binaries for each OS/arch.
- CI/CD files (.github/workflows/CI.yml) and release config (.cargo/config.toml, yarnrc).
- Test folder: __test__/webauthn-flow.spec.mjs

##### README for additional insights
- Confirms use of NAPI-RS to expose Rust functions as async JS functions: createCredential() and getCredential().
- Specifies platform APIs: ASAuthorization (macOS), Windows Hello, generic Linux WebAuthn.
- Describes build & packaging with electron-builder and prebuilt binaries for multiple targets.

##### Main components and their interactions
a. Electron Application (Consumer)
– Calls JS API: createCredential(), getCredential()
b. JS / TypeScript Wrapper
– index.js exports functions
– index.d.ts provides types
– Uses NAPI-RS under the hood to call into native Rust
c. NAPI-RS Binding Layer
– Auto-generated glue that converts JS calls into Rust FFI calls
d. Rust Core Library (lib.rs)
– Implements WebAuthn logic, orchestrates platform modules, marshals data
e. Platform Modules (macos.rs, windows via cfg, linux generic in unknown.rs)
– Each module invokes the respective OS’s native authenticator APIs
f. Native OS Authenticator APIs
– macOS: ASAuthorization framework, Secure Enclave
– Windows: Windows Hello APIs
– Linux: libfido2 or generic WebAuthn libraries
g. Hardware Backends
– Touch ID sensor, Face ID, security keys, Apple Watch, TPM, etc.
h. Packaging / CI / Distribution
– build.rs and Cargo.toml compile the Rust code
– CI workflow builds & publishes per-platform binaries under npm/…
– electron-builder entitlements and packaging

##### Architectural patterns and principles
- Layered design: JS layer → NAPI layer → Rust core → platform modules → native APIs
- Plug-in style for platform modules using Rust’s conditional compilation (cfg)
- Single responsibility: each module handles one platform’s specifics
- Pre-build artifacts: provides zero-install binaries for every target

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layers and main flow
    subgraph "Electron Layer"
        direction TB
        ElectronApp["Electron Application\n(createCredential(), getCredential())"]:::js
        click ElectronApp "https://github.com/iamevanyt/electron-webauthn-native/blob/main/index.js"
        click ElectronApp "https://github.com/iamevanyt/electron-webauthn-native/blob/main/index.d.ts"
    end

    subgraph "JS Wrapper" 
        direction TB
        JSAPI["index.js\n(exports createCredential(), getCredential())"]:::js
        JSTD["index.d.ts\n(type definitions)"]:::js
        click JSAPI "https://github.com/iamevanyt/electron-webauthn-native/blob/main/index.js"
        click JSTD "https://github.com/iamevanyt/electron-webauthn-native/blob/main/index.d.ts"
    end

    subgraph "NAPI-RS Binding Layer"
        direction TB
        NAPI["NAPI-RS Glue"]:::rust
        click NAPI "https://github.com/iamevanyt/electron-webauthn-native/blob/main/src/lib.rs"
    end

    subgraph "Rust Core Library"
        direction TB
        RustCore["src/lib.rs\n(Core WebAuthn Logic)"]:::rust
        click RustCore "https://github.com/iamevanyt/electron-webauthn-native/blob/main/src/lib.rs"
    end

    subgraph "Platform Modules" 
        direction TB
        ModReg["Module Registry\n(src/platform/mod.rs)"]:::platform
        MacOSMod["macos.rs\n(macOS Module)"]:::platform
        LinuxMod["unknown.rs\n(Linux Generic Module)"]:::platform
        click ModReg "https://github.com/iamevanyt/electron-webauthn-native/blob/main/src/platform/mod.rs"
        click MacOSMod "https://github.com/iamevanyt/electron-webauthn-native/blob/main/src/platform/macos.rs"
        click LinuxMod "https://github.com/iamevanyt/electron-webauthn-native/blob/main/src/platform/unknown.rs"
    end

    subgraph "Native OS APIs"
        direction TB
        MacAPI["ASAuthorization\n(macOS)"]:::native
        WinAPI["Windows Hello\n(Windows)"]:::native
        LinAPI["libfido2 / WebAuthn\n(Linux)"]:::native
    end

    subgraph "Hardware Backends"
        direction TB
        TouchID["Touch ID, Face ID,\nSecurity Keys, TPM"]:::hw
    end

    %% Call flow arrows
    ElectronApp -->|"calls"| JSAPI
    JSAPI -->|"N-API Call"| NAPI
    NAPI -->|"FFI"| RustCore
    RustCore -->|"dispatch"| ModReg
    ModReg -->|"cfg → select"| MacOSMod
    ModReg -->|"cfg → select"| LinuxMod
    MacOSMod -->|"uses"| MacAPI
    LinuxMod -->|"uses"| LinAPI
    MacAPI -->|"hardware interaction"| TouchID
    WinAPI -->|"hardware interaction"| TouchID
    LinAPI -->|"hardware interaction"| TouchID

    %% Build, CI, Distribution & Testing
    subgraph "Build & CI/CD"
        direction TB
        BuildScript["build.rs\n(Cargo build)"]:::rust
        CargoCfg["Cargo.toml\n(crate config)"]:::rust
        CargoConf[".cargo/config.toml"]:::rust
        CIWorkflow["CI Workflow\n(.github/workflows/CI.yml)"]:::native
        click BuildScript "https://github.com/iamevanyt/electron-webauthn-native/blob/main/build.rs"
        click CargoCfg "https://github.com/iamevanyt/electron-webauthn-native/blob/main/Cargo.toml"
        click CargoConf "https://github.com/iamevanyt/electron-webauthn-native/blob/main/.cargo/config.toml"
        click CIWorkflow "https://github.com/iamevanyt/electron-webauthn-native/blob/main/.github/workflows/CI.yml"
    end

    subgraph "Distribution Artifacts"
        direction TB
        NPMDarwinARM["npm/darwin-arm64"]:::native
        NPMDarwinX64["npm/darwin-x64"]:::native
        NPMLinux["npm/linux-x64-gnu"]:::native
        NPMWinARM["npm/win32-arm64-msvc"]:::native
        NPMWinX64["npm/win32-x64-msvc"]:::native
        click NPMDarwinARM "https://github.com/iamevanyt/electron-webauthn-native/blob/main/npm/darwin-arm64/package.json"
        click NPMDarwinARM "https://github.com/iamevanyt/electron-webauthn-native/blob/main/npm/darwin-arm64/README.md"
        click NPMDarwinX64 "https://github.com/iamevanyt/electron-webauthn-native/blob/main/npm/darwin-x64/package.json"
        click NPMDarwinX64 "https://github.com/iamevanyt/electron-webauthn-native/blob/main/npm/darwin-x64/README.md"
        click NPMLinux "https://github.com/iamevanyt/electron-webauthn-native/blob/main/npm/linux-x64-gnu/package.json"
        click NPMLinux "https://github.com/iamevanyt/electron-webauthn-native/blob/main/npm/linux-x64-gnu/README.md"
        click NPMWinARM "https://github.com/iamevanyt/electron-webauthn-native/blob/main/npm/win32-arm64-msvc/package.json"
        click NPMWinARM "https://github.com/iamevanyt/electron-webauthn-native/blob/main/npm/win32-arm64-msvc/README.md"
        click NPMWinX64 "https://github.com/iamevanyt/electron-webauthn-native/blob/main/npm/win32-x64-msvc/package.json"
        click NPMWinX64 "https://github.com/iamevanyt/electron-webauthn-native/blob/main/npm/win32-x64-msvc/README.md"
    end

    CIWorkflow -->|triggers build| BuildScript
    BuildScript & CargoCfg & CargoConf -->|produce| NPMDarwinARM & NPMDarwinX64 & NPMLinux & NPMWinARM & NPMWinX64

    subgraph "Testing & Tooling"
        direction TB
        Tests["webauthn-flow.spec.mjs\n(end-to-end tests)"]:::native
        PackageJSON["package.json"]:::native
        NpmIgnore[".npmignore"]:::native
        YarnCfg[".yarnrc.yml\n& yarn-4.9.2.cjs"]:::native
        RustFmt["rustfmt.toml"]:::native
        click Tests "https://github.com/iamevanyt/electron-webauthn-native/blob/main/__test__/webauthn-flow.spec.mjs"
        click PackageJSON "https://github.com/iamevanyt/electron-webauthn-native/blob/main/package.json"
        click NpmIgnore "https://github.com/iamevanyt/electron-webauthn-native/blob/main/.npmignore"
        click YarnCfg "https://github.com/iamevanyt/electron-webauthn-native/blob/main/.yarnrc.yml"
        click YarnCfg "https://github.com/iamevanyt/electron-webauthn-native/blob/main/.yarn/releases/yarn-4.9.2.cjs"
        click RustFmt "https://github.com/iamevanyt/electron-webauthn-native/blob/main/rustfmt.toml"
    end

    %% Styles
    classDef js fill:#cce5ff,stroke:#3399ff,color:#000
    classDef rust fill:#ccffcc,stroke:#33cc33,color:#000
    classDef platform fill:#ffebcc,stroke:#ff9900,color:#000
    classDef native fill:#e0e0e0,stroke:#999999,color:#000
    classDef hw fill:#333,stroke:#000,color:#fff
```
