# truthly/pg-webauthn architecture

> Architecture diagram of the GitHub repository truthly/pg-webauthn, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/truthly/pg-webauthn
- Repository: https://github.com/truthly/pg-webauthn

## Overview

##### Main Components

a. Core Components:
- WebAuthn Extension Module (Central Component)
- Database Tables Layer
- Function Layer
- Enumeration Types Layer
- External Dependencies Layer

b. Integration Points:
- Browser/Client Interface
- PostgreSQL Core Integration
- External Dependencies Integration

**Client Layer (Browser)**
**↕️**
**WebAuthn Extension Interface**
**↕️**
**Core Processing Layer**
**↕️**
**Storage Layer**
**↕️**
**External Dependencies**

##### Specific Components

a. Tables (Storage Layer):
- credential_challenges
- credentials
- assertion_challenges
- assertions

b. Core Functions (Group by Flow):
- Sign-up Flow Functions:
- init_credential()
- store_credential()
- Sign-in Flow Functions:
- get_credentials()
- verify_assertion()
- Utility Functions:
- base64url_encode/decode
- parse_attestation_object
- parse_authenticator_data
- etc.

c. External Dependencies:
- pgcrypto
- pg_ecdsa_verify
- cbor

##### Flow Representations

a. Sign-up Flow:
**Browser → init_credential() → credential_challenges table**
**Browser → store_credential() → credentials table**

b. Sign-in Flow:
**Browser → get_credentials() → assertion_challenges table**
**Browser → verify_assertion() → assertions table**

##### Important Details

a. Security Flow Indicators:
- Challenge-response mechanisms
- Signature verification paths
- User verification requirements

b. Data Transformations:
- Base64URL encoding/decoding points
- CBOR processing points
- Cryptographic verification points

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph Client
        Browser["Browser/Client"]:::client
    end

    subgraph "WebAuthn Extension Interface"
        SignUpFlow["Sign-up Flow"]:::interface
        SignInFlow["Sign-in Flow"]:::interface
    end

    subgraph "Core Processing Layer"
        direction TB
        subgraph "Sign-up Functions"
            InitCred["init_credential()"]:::function
            StoreCred["store_credential()"]:::function
        end

        subgraph "Sign-in Functions"
            GetCred["get_credentials()"]:::function
            VerifyAssert["verify_assertion()"]:::function
        end

        subgraph "Utility Functions"
            Base64Encode["base64url_encode()"]:::utility
            Base64Decode["base64url_decode()"]:::utility
            ParseAttest["parse_attestation_object()"]:::utility
            ParseAuth["parse_authenticator_data()"]:::utility
            CoseEcdha["cose_ecdha_to_pkcs()"]:::utility
            DecodeAsn1["decode_asn1_der_signature()"]:::utility
        end

        subgraph "Security Verification"
            CredChallExp["credential_challenge_expiration()"]:::security
            AssertChallExp["assertion_challenge_expiration()"]:::security
            CredUserVerif["credential_challenge_user_verification()"]:::security
            AssertUserVerif["assertion_challenge_user_verification()"]:::security
        end
    end

    subgraph "Storage Layer"
        CredChallenges[(credential_challenges)]:::storage
        Credentials[(credentials)]:::storage
        AssertChallenges[(assertion_challenges)]:::storage
        Assertions[(assertions)]:::storage
    end

    subgraph "Enumeration Types"
        AttestPref["Attestation Preference"]:::enum
        CredType["Credential Type"]:::enum
        UserVerifReq["User Verification Requirement"]:::enum
    end

    subgraph "External Dependencies"
        PGCrypto["pgcrypto"]:::external
        ECDSAVerify["pg_ecdsa_verify"]:::external
        CBOR["cbor"]:::external
    end

    %% Relationships
    Browser --> SignUpFlow & SignInFlow
    SignUpFlow --> InitCred & StoreCred
    SignInFlow --> GetCred & VerifyAssert

    InitCred --> CredChallenges
    StoreCred --> Credentials
    GetCred --> AssertChallenges
    VerifyAssert --> Assertions

    InitCred & StoreCred & GetCred & VerifyAssert --> Base64Encode & Base64Decode
    StoreCred --> ParseAttest & ParseAuth
    VerifyAssert --> CoseEcdha & DecodeAsn1

    CredChallenges --> CredChallExp & CredUserVerif
    AssertChallenges --> AssertChallExp & AssertUserVerif

    %% Click Events
    click InitCred "https://github.com/truthly/pg-webauthn/blob/master/FUNCTIONS/init_credential.sql"
    click StoreCred "https://github.com/truthly/pg-webauthn/blob/master/FUNCTIONS/store_credential.sql"
    click GetCred "https://github.com/truthly/pg-webauthn/blob/master/FUNCTIONS/get_credentials.sql"
    click VerifyAssert "https://github.com/truthly/pg-webauthn/blob/master/FUNCTIONS/verify_assertion.sql"
    click Base64Encode "https://github.com/truthly/pg-webauthn/blob/master/FUNCTIONS/base64url_encode.sql"
    click Base64Decode "https://github.com/truthly/pg-webauthn/blob/master/FUNCTIONS/base64url_decode.sql"
    click ParseAttest "https://github.com/truthly/pg-webauthn/blob/master/FUNCTIONS/parse_attestation_object.sql"
    click ParseAuth "https://github.com/truthly/pg-webauthn/blob/master/FUNCTIONS/parse_authenticator_data.sql"
    click CoseEcdha "https://github.com/truthly/pg-webauthn/blob/master/FUNCTIONS/cose_ecdha_to_pkcs.sql"
    click DecodeAsn1 "https://github.com/truthly/pg-webauthn/blob/master/FUNCTIONS/decode_asn1_der_signature.sql"
    click CredChallenges "https://github.com/truthly/pg-webauthn/blob/master/TABLES/credential_challenges.sql"
    click Credentials "https://github.com/truthly/pg-webauthn/blob/master/TABLES/credentials.sql"
    click AssertChallenges "https://github.com/truthly/pg-webauthn/blob/master/TABLES/assertion_challenges.sql"
    click Assertions "https://github.com/truthly/pg-webauthn/blob/master/TABLES/assertions.sql"
    click AttestPref "https://github.com/truthly/pg-webauthn/blob/master/ENUMS/attestation_conveyance_preference.sql"
    click CredType "https://github.com/truthly/pg-webauthn/blob/master/ENUMS/credential_type.sql"
    click UserVerifReq "https://github.com/truthly/pg-webauthn/blob/master/ENUMS/user_verification_requirement.sql"
    click CredChallExp "https://github.com/truthly/pg-webauthn/blob/master/FUNCTIONS/credential_challenge_expiration.sql"
    click AssertChallExp "https://github.com/truthly/pg-webauthn/blob/master/FUNCTIONS/assertion_challenge_expiration.sql"
    click CredUserVerif "https://github.com/truthly/pg-webauthn/blob/master/FUNCTIONS/credential_challenge_user_verification.sql"
    click AssertUserVerif "https://github.com/truthly/pg-webauthn/blob/master/FUNCTIONS/assertion_challenge_user_verification.sql"

    %% Styles
    classDef client fill:#E1F5FE,stroke:#01579B
    classDef interface fill:#E8F5E9,stroke:#2E7D32
    classDef function fill:#F3E5F5,stroke:#7B1FA2
    classDef utility fill:#FFF3E0,stroke:#E65100
    classDef security fill:#FFEBEE,stroke:#C62828
    classDef storage fill:#E8EAF6,stroke:#1A237E
    classDef enum fill:#FCE4EC,stroke:#880E4F
    classDef external fill:#EFEBE9,stroke:#3E2723
```
