Server Endpoints

Server Endpoints

Table of Contents

1. Introduction
2. API Architecture Overview
3. General Endpoints
4. Simple Mode Endpoints
5. Advanced Mode Endpoints
6. Authentication Flows
7. Security Considerations
8. Frontend Integration
9. Error Handling
10. Rate Limiting and Protection

Introduction

The Post-Quantum WebAuthn Platform provides a comprehensive RESTful API for WebAuthn authentication using the FIDO2 library. The platform supports both simple and advanced authentication modes, with built-in post-quantum cryptographic algorithm support and extensive metadata service capabilities.

The server is built on Flask and provides endpoints for credential registration, authentication, metadata management, and cryptographic operations. All endpoints follow RESTful principles and use JSON for request/response payloads.

API Architecture Overview

The server follows a modular architecture with separate route handlers for different authentication modes:

graph TB
subgraph "Flask Application"
App[Flask App]
Config[Configuration]
end
subgraph "Route Modules"
General[General Routes]
Simple[Simple Mode Routes]
Advanced[Advanced Mode Routes]
end
subgraph "Core Services"
Storage[Credential Storage]
Attestation[Attestation Verification]
Metadata[Metadata Service]
Crypto[Cryptographic Operations]
end
App --> General
App --> Simple
App --> Advanced
General --> Metadata
Simple --> Storage
Simple --> Attestation
Advanced --> Storage
Advanced --> Attestation
Storage --> Crypto
Attestation --> Crypto

Loading

Diagram sources

• server/server/app.py
• server/server/config.py

Section sources

• server/server/app.py
• server/server/config.py

General Endpoints

Metadata Management Endpoints

GET /api/mds/metadata/base

Retrieves the base verified FIDO Metadata Service (MDS) snapshot.

Request:

• Method: GET
• Headers: None required
• Query Parameters: None

Response:

{
  "entries": [
    {
      "aaid": "string",
      "aaguid": "string",
      "description": "string",
      "authenticatorVersion": "string",
      "upv": [{"version": "string", "effectiveDate": "string"}],
      "statusReports": [
        {
          "status": "string",
          "effectiveDate": "string",
          "authenticatorVersion": "string"
        }
      ],
      "metadataStatement": {
        "legalHeader": "string",
        "aaid": "string",
        "aaguid": "string",
        "description": "string",
        "authenticatorVersion": "string",
        "upv": [{"version": "string", "effectiveDate": "string"}],
        "authenticationAlgorithms": ["string"],
        "publicKeyAlgAndEncodings": ["string"],
        "attestationTypes": ["string"],
        "userVerificationDetails": [[{"methods": ["string"]}]],
        "keyProtection": "string",
        "matcherProtection": "string",
        "cryptoStrength": "string",
        "attachmentHint": "string",
        "tcDisplay": "string",
        "attestationRootCertificates": ["string"],
        "icon": "string"
      }
    }
  ]
}

Status Codes:

• 200: Success
• 404: Verified metadata snapshot not available
• 500: Verified metadata snapshot is corrupted

GET /api/mds/metadata/custom

Lists custom uploaded metadata entries.

Request:

• Method: GET
• Headers: None required
• Query Parameters: None

Response:

{
  "items": [
    {
      "filename": "string",
      "originalFilename": "string",
      "size": "string",
      "lastModified": "string",
      "contentType": "string",
      "contentHash": "string",
      "entries": [
        {
          "aaid": "string",
          "aaguid": "string",
          "description": "string",
          "authenticatorVersion": "string",
          "upv": [{"version": "string", "effectiveDate": "string"}],
          "statusReports": [
            {
              "status": "string",
              "effectiveDate": "string",
              "authenticatorVersion": "string"
            }
          ]
        }
      ]
    }
  ]
}

POST /api/mds/metadata/upload

Uploads custom metadata files for processing.

Request:

• Method: POST
• Headers: Content-Type: multipart/form-data
• Body: Form data with files field containing JSON files

Response:

{
  "items": [
    {
      "filename": "string",
      "originalFilename": "string",
      "size": "string",
      "lastModified": "string",
      "contentType": "string",
      "contentHash": "string",
      "entries": [
        {
          "aaid": "string",
          "aaguid": "string",
          "description": "string",
          "authenticatorVersion": "string",
          "upv": [{"version": "string", "effectiveDate": "string"}],
          "statusReports": [
            {
              "status": "string",
              "effectiveDate": "string",
              "authenticatorVersion": "string"
            }
          ]
        }
      ]
    }
  ],
  "errors": ["string"]
}

DELETE /api/mds/metadata/custom/{stored_filename}

Deletes a custom metadata entry.

Request:

• Method: DELETE
• Path Parameters: stored_filename - The filename of the metadata entry to delete

Response:

{
  "deleted": true
}

Codec Endpoints

POST /api/codec

Performs encoding/decoding operations on WebAuthn payloads.

Request:

{
  "payload": "string",
  "mode": "decode", // or "encode"
  "format": "cbor"  // when mode is "encode"
}

Response:

{
  "decoded": "string",
  "encoded": "string"
}

POST /api/decode

Decodes WebAuthn payloads.

Request:

{
  "payload": "string"
}

Response:

{
  "decoded": "string"
}

POST /api/mds/decode-certificate

Decodes X.509 certificates from attestation statements.

Request:

{
  "certificate": "string"
}

Response:

{
  "details": {
    "subject": "string",
    "issuer": "string",
    "serialNumber": "string",
    "validFrom": "string",
    "validTo": "string",
    "publicKey": {
      "algorithm": "string",
      "keySize": "string",
      "curve": "string"
    }
  }
}

Credential Management Endpoints

POST /api/deletepub

Deletes public key material for a user.

Request:

{
  "email": "string"
}

Response:

{
  "status": "OK"
}

GET /api/downloadcred

Downloads credential data for a user.

Request:

• Method: GET
• Query Parameters: email - The user's email address

Response: Returns a binary file containing pickled credential data.

Section sources

• server/server/routes/general.py

Simple Mode Endpoints

Registration Endpoints

POST /api/register/begin

Initiates the credential registration process.

Request:

{
  "credentials": [
    {
      "credentialId": "string",
      "aaguid": "string",
      "publicKey": "string",
      "algorithm": -7,
      "signCount": 0,
      "email": "string",
      "type": "simple"
    }
  ]
}

Response:

{
  "publicKey": {
    "challenge": "string",
    "rp": {
      "id": "string",
      "name": "string"
    },
    "user": {
      "id": "string",
      "name": "string",
      "displayName": "string"
    },
    "pubKeyCredParams": [
      {
        "type": "public-key",
        "alg": -7
      }
    ],
    "timeout": 90000,
    "attestation": "none",
    "authenticatorSelection": {
      "authenticatorAttachment": "cross-platform",
      "requireResidentKey": false,
      "userVerification": "discouraged"
    }
  },
  "__session_state": "string"
}

POST /api/register/complete

Completes the credential registration process.

Request:

{
  "id": "string",
  "rawId": "string",
  "response": {
    "attestationObject": "string",
    "clientDataJSON": "string"
  },
  "__session_state": "string"
}

Response:

{
  "status": "OK",
  "algo": "ES256 (ECDSA)",
  "storedCredential": {
    "type": "simple",
    "email": "string",
    "userName": "string",
    "displayName": "string",
    "credentialId": "string",
    "aaguid": "string",
    "publicKey": "string",
    "signCount": 0,
    "createdAt": "number",
    "attestationFormat": "string",
    "properties": {}
  },
  "relyingParty": {
    "attestationFmt": "string",
    "createdAt": "string",
    "credentialId": "string",
    "publicKeyAlgorithm": -7
  }
}

Authentication Endpoints

POST /api/authenticate/begin

Initiates the authentication process.

Request:

{
  "credentials": [
    {
      "credentialId": "string",
      "aaguid": "string",
      "publicKey": "string",
      "algorithm": -7,
      "signCount": 0,
      "email": "string",
      "type": "simple"
    }
  ]
}

Response:

{
  "publicKey": {
    "challenge": "string",
    "rpId": "string",
    "allowCredentials": [
      {
        "id": "string",
        "type": "public-key"
      }
    ],
    "timeout": 90000,
    "userVerification": "discouraged"
  },
  "__session_state": "string"
}

POST /api/authenticate/complete

Completes the authentication process.

Request:

{
  "id": "string",
  "rawId": "string",
  "response": {
    "authenticatorData": "string",
    "clientDataJSON": "string",
    "signature": "string",
    "userHandle": "string"
  },
  "__session_state": "string"
}

Response:

{
  "status": "OK",
  "authenticatedCredentialId": "string",
  "signCount": 123
}

Credential Listing Endpoint

GET/DELETE /api/credentials

Manages user credentials.

GET Request: Lists all stored credentials for the current session.

Response:

[
  {
    "email": "string",
    "credentialId": "string",
    "userName": "string",
    "displayName": "string",
    "algorithm": -7,
    "type": "WebAuthn",
    "createdAt": "number",
    "signCount": 0,
    "aaguid": "string",
    "flags": {
      "up": true,
      "uv": true,
      "at": true,
      "ed": false,
      "be": false,
      "bs": false
    },
    "attestationFormat": "string",
    "authenticatorAttachment": "cross-platform",
    "residentKey": false,
    "largeBlob": false
  }
]

DELETE Request: Removes all credentials for the current session.

Response:

{
  "status": "OK",
  "removed": 5
}

Section sources

• server/server/routes/simple.py

Advanced Mode Endpoints

Registration Endpoints

POST /api/advanced/register/begin

Initiates advanced credential registration with custom options.

Request:

{
  "publicKey": {
    "rp": {
      "id": "string",
      "name": "string"
    },
    "user": {
      "id": "string",
      "name": "string",
      "displayName": "string"
    },
    "challenge": "string",
    "pubKeyCredParams": [
      {
        "type": "public-key",
        "alg": -50
      }
    ],
    "timeout": 90000,
    "attestation": "none",
    "authenticatorSelection": {
      "authenticatorAttachment": "cross-platform",
      "requireResidentKey": false,
      "userVerification": "preferred"
    },
    "extensions": {
      "credProps": true,
      "minPinLength": true,
      "largeBlob": {
        "support": "write"
      }
    }
  }
}

Response:

{
  "publicKey": {
    "challenge": "string",
    "rp": {
      "id": "string",
      "name": "string"
    },
    "user": {
      "id": "string",
      "name": "string",
      "displayName": "string"
    },
    "pubKeyCredParams": [
      {
        "type": "public-key",
        "alg": -50
      }
    ],
    "timeout": 90000,
    "attestation": "none",
    "authenticatorSelection": {
      "authenticatorAttachment": "cross-platform",
      "requireResidentKey": false,
      "userVerification": "preferred"
    },
    "extensions": {
      "credProps": true,
      "minPinLength": true,
      "largeBlob": {
        "support": "write"
      }
    }
  },
  "__session_state": "string",
  "warnings": ["string"]
}

POST /api/advanced/register/complete

Completes advanced credential registration.

Request:

{
  "__credential_response": {
    "id": "string",
    "rawId": "string",
    "response": {
      "attestationObject": "string",
      "clientDataJSON": "string"
    }
  },
  "__session_state": "string"
}

Response:

{
  "status": "OK",
  "storedCredential": {
    "type": "advanced",
    "email": "string",
    "userName": "string",
    "displayName": "string",
    "credentialId": "string",
    "aaguid": "string",
    "publicKey": "string",
    "signCount": 0,
    "createdAt": "number",
    "attestationFormat": "string",
    "properties": {}
  },
  "relyingParty": {
    "attestationFmt": "string",
    "createdAt": "string",
    "credentialId": "string",
    "publicKeyAlgorithm": -50
  }
}

Authentication Endpoints

POST /api/advanced/authenticate/begin

Initiates advanced authentication with custom options.

Request:

{
  "publicKey": {
    "rpId": "string",
    "challenge": "string",
    "allowCredentials": [
      {
        "id": "string",
        "type": "public-key"
      }
    ],
    "timeout": 90000,
    "userVerification": "preferred",
    "extensions": {
      "prf": {
        "eval": {
          "first": "string",
          "second": "string"
        }
      }
    }
  }
}

Response:

{
  "publicKey": {
    "challenge": "string",
    "rpId": "string",
    "allowCredentials": [
      {
        "id": "string",
        "type": "public-key"
      }
    ],
    "timeout": 90000,
    "userVerification": "preferred",
    "extensions": {
      "prf": {
        "eval": {
          "first": "string",
          "second": "string"
        }
      }
    }
  },
  "__session_state": "string"
}

POST /api/advanced/authenticate/complete

Completes advanced authentication.

Request:

{
  "__assertion_response": {
    "id": "string",
    "rawId": "string",
    "response": {
      "authenticatorData": "string",
      "clientDataJSON": "string",
      "signature": "string",
      "userHandle": "string"
    }
  },
  "__session_state": "string"
}

Response:

{
  "status": "OK",
  "authenticatedCredentialId": "string",
  "signCount": 123
}

Section sources

• server/server/routes/advanced.py

Authentication Flows

Simple Mode Flow

sequenceDiagram
participant Client as Frontend Client
participant Server as WebAuthn Server
participant Authenticator as Authenticator Device
Client->>Server : POST /api/register/begin
Server-->>Client : Registration Options
Client->>Authenticator : Create Credential
Authenticator-->>Client : Credential Response
Client->>Server : POST /api/register/complete
Server->>Server : Verify Attestation
Server-->>Client : Registration Result
Client->>Server : POST /api/authenticate/begin
Server-->>Client : Authentication Options
Client->>Authenticator : Authenticate
Authenticator-->>Client : Assertion Response
Client->>Server : POST /api/authenticate/complete
Server->>Server : Verify Signature
Server-->>Client : Authentication Result

Loading

Diagram sources

• server/server/static/scripts/simple/auth-simple.js
• server/server/routes/simple.py

Advanced Mode Flow

sequenceDiagram
participant Client as Frontend Client
participant Server as WebAuthn Server
participant Authenticator as Authenticator Device
Client->>Server : POST /api/advanced/register/begin
Server-->>Client : Custom Registration Options
Client->>Authenticator : Create Credential with Extensions
Authenticator-->>Client : Credential Response
Client->>Server : POST /api/advanced/register/complete
Server->>Server : Verify Attestation & Extensions
Server-->>Client : Registration Result
Client->>Server : POST /api/advanced/authenticate/begin
Server-->>Client : Custom Authentication Options
Client->>Authenticator : Authenticate with Extensions
Authenticator-->>Client : Assertion Response
Client->>Server : POST /api/advanced/authenticate/complete
Server->>Server : Verify Signature & Extensions
Server-->>Client : Authentication Result

Loading

Diagram sources

• server/server/static/scripts/advanced/auth-advanced.js
• server/server/routes/advanced.py

Security Considerations

Input Validation

All endpoints implement comprehensive input validation:

• JSON Schema Validation: Requests are validated against expected schemas
• Binary Data Validation: Base64, hexadecimal, and CBOR data is properly encoded/decoded
• Parameter Sanitization: User inputs are sanitized to prevent injection attacks
• Type Checking: All parameters are checked for correct types

Session Protection

• Secure Session Management: Sessions use secure cookies with appropriate attributes
• State Validation: All registration/authentication states are validated
• CSRF Protection: Implemented through session-based CSRF tokens
• Session Expiration: Sessions expire after timeout periods

Cryptographic Security

• Post-Quantum Algorithms: Supports ML-DSA algorithms (-50, -49, -48) for quantum resistance
• Strong Randomness: Uses cryptographically secure random number generators
• Secure Key Storage: Private keys are securely stored and never exposed
• Algorithm Negotiation: Supports both classical and post-quantum algorithms

Attestation Verification

The server performs comprehensive attestation verification:

• Certificate Chain Validation: Verifies certificate trust chains
• Root Certificate Pinning: Validates against known root certificates
• AAGUID Matching: Ensures authenticator identity matches metadata
• RP ID Hash Verification: Validates relying party identifier

Section sources

• server/server/attestation.py
• server/server/config.py

Frontend Integration

JavaScript Integration

The server provides seamless integration with JavaScript clients through well-defined APIs:

Simple Mode Integration

• Direct API Calls: Simple endpoints for straightforward integration
• Automatic State Management: Session state is handled automatically
• Error Handling: Comprehensive error reporting with user-friendly messages

Advanced Mode Integration

• Customizable Options: Full control over registration/authentication parameters
• Extension Support: Complete support for WebAuthn extensions
• Real-time Validation: Immediate feedback on configuration errors

Authentication Libraries

The server works with standard WebAuthn libraries:

• webauthn-json: Standard WebAuthn JSON ponyfill
• FIDO2 Library: Underlying FIDO2 implementation
• Custom Extensions: Support for proprietary extensions

Section sources

• server/server/static/scripts/simple/auth-simple.js
• server/server/static/scripts/advanced/auth-advanced.js

Error Handling

Standard Error Responses

All endpoints return standardized error responses:

{
  "error": "Error description",
  "code": "ERROR_CODE",
  "details": "Additional error details"
}

Common Error Codes

Status Code	Error Type	Description
400	BAD_REQUEST	Invalid request format or missing required parameters
404	NOT_FOUND	Resource not found
500	INTERNAL_ERROR	Server-side error during processing
501	NOT_IMPLEMENTED	Feature not supported

Authentication-Specific Errors

• STATE_EXPIRED: Authentication state has expired
• INVALID_SIGNATURE: Signature verification failed
• INVALID_CHALLENGE: Challenge validation failed
• UNKNOWN_CREDENTIAL: Credential not found

Error Recovery

The server provides mechanisms for error recovery:

• State Reset: Authentication states can be reset
• Retry Logic: Built-in retry mechanisms for transient failures
• Graceful Degradation: Fallback to simpler authentication modes

Rate Limiting and Protection

Built-in Protections

The server implements several security protections:

• Challenge Validation: Each authentication requires a fresh challenge
• Signature Counter: Monitors signature counts to detect replay attacks
• Duplicate Detection: Prevents credential reuse attacks
• Timeout Enforcement: Limits authentication ceremony duration

Session Management

• Secure Cookies: Sessions use secure, HTTP-only cookies
• Session Rotation: Sessions are rotated periodically
• Cross-Site Request Forgery: Protection against CSRF attacks
• Session Timeout: Automatic session expiration

Monitoring and Logging

The server provides comprehensive logging:

• Authentication Events: Logs all authentication attempts
• Error Tracking: Detailed error logging for debugging
• Performance Metrics: Tracks API response times
• Security Events: Monitors suspicious activities

Section sources

• server/server/storage.py
• server/server/config.py