General Application Endpoints

General Application Endpoints

Table of Contents

1. Introduction
2. Authentication and Session Management
3. Metadata Service (MDS) Endpoints
4. Payload Encoding/Decoding Endpoints
5. Credential Management Endpoints
6. Security Considerations
7. Error Handling
8. Examples and Usage Patterns

Introduction

The Post-Quantum WebAuthn Platform provides a comprehensive set of API endpoints for managing WebAuthn metadata, encoding/decoding payloads, and handling credential operations. These endpoints support both the standard FIDO2 WebAuthn protocol and post-quantum cryptographic capabilities.

The platform implements a robust session-based architecture for metadata management, ensuring isolation between different users and providing persistent storage for custom metadata entries. All endpoints follow RESTful principles and return JSON-formatted responses with appropriate HTTP status codes.

Authentication and Session Management

Session-Based Architecture

The platform uses a cookie-based session system for metadata isolation and persistence. Each user session maintains separate metadata storage to prevent cross-user contamination.

sequenceDiagram
participant Client as "Client Browser"
participant Server as "WebAuthn Server"
participant Storage as "Session Storage"
Client->>Server : First Request
Server->>Storage : Create Session
Storage-->>Server : Session ID
Server->>Client : Set Session Cookie
Client->>Server : Subsequent Requests
Server->>Storage : Access Session Data
Storage-->>Server : Session Metadata
Server-->>Client : API Response

Loading

Diagram sources

• server/server/metadata.py
• server/server/session_metadata_store.py

Session Security Features

Feature	Description	Implementation
Secure Cookies	HTTPS-only cookies with SameSite protection	Configurable based on request context
Session Isolation	Separate metadata storage per session	UUID-based session identifiers
Automatic Cleanup	Inactive session removal	14-day inactivity threshold
Cross-Site Protection	CSRF prevention through session validation	Cookie-based authentication

Section sources

• server/server/metadata.py
• server/server/session_metadata_store.py

Metadata Service (MDS) Endpoints

Base Metadata Endpoint

Retrieves the verified FIDO Metadata Service snapshot.

Endpoint: GET /api/mds/metadata/base

Request Headers:

• Accept: application/json (optional)

Response Schema:

{
  "legalHeader": "string",
  "no": "number",
  "nextUpdate": "date-string",
  "entries": [
    {
      "aaguid": "string",
      "metadataStatement": {
        "description": "string",
        "authenticatorVersion": "number",
        "schema": "number",
        "upv": [],
        "attestationTypes": [],
        "userVerificationDetails": [],
        "keyProtection": [],
        "matcherProtection": [],
        "attachmentHint": [],
        "tcDisplay": [],
        "attestationRootCertificates": []
      },
      "statusReports": [],
      "timeOfLastStatusChange": "date-string",
      "attestationCertificateKeyIdentifiers": []
    }
  ]
}

HTTP Status Codes:

• 200 OK: Successfully retrieved metadata
• 404 Not Found: Verified metadata snapshot unavailable
• 500 Internal Server Error: Corrupted metadata file

Section sources

• server/server/routes/general.py

Custom Metadata Management

List Custom Metadata Entries

Endpoint: GET /api/mds/metadata/custom

Authentication: Required (session cookie)

Response Schema:

{
  "items": [
    {
      "entry": {
        "aaguid": "string",
        "metadataStatement": {},
        "statusReports": [],
        "timeOfLastStatusChange": "date-string",
        "attestationCertificateKeyIdentifiers": []
      },
      "source": {
        "storedFilename": "string",
        "originalFilename": "string",
        "uploadedAt": "datetime-string",
        "modifiedAt": "datetime-string"
      },
      "legalHeader": "string"
    }
  ]
}

Upload Custom Metadata

Endpoint: POST /api/mds/metadata/upload

Content Type: multipart/form-data

Request Parameters:

• files[]: JSON files containing metadata entries (multiple files supported)

Response Schema:

{
  "items": [
    {
      "entry": {},
      "source": {
        "storedFilename": "string",
        "originalFilename": "string",
        "uploadedAt": "datetime-string"
      }
    }
  ],
  "errors": ["string"]
}

Validation Rules:

• Files must have .json extension
• Content must be valid UTF-8
• JSON must be a valid object or array of objects
• Each entry must be a valid metadata statement

Delete Custom Metadata

Endpoint: DELETE /api/mds/metadata/custom/{filename}

Path Parameters:

• filename: Stored filename of the metadata entry

Response Schema:

{
  "deleted": true
}

HTTP Status Codes:

• 200 OK: Successfully deleted
• 404 Not Found: Metadata entry not found
• 400 Bad Request: Invalid filename or session error

Section sources

• server/server/routes/general.py

Metadata Bootstrap Process

The platform implements a sophisticated metadata bootstrap process for efficient loading and caching.

flowchart TD
Start([Server Startup]) --> CheckCache["Check Cached Snapshot"]
CheckCache --> CacheExists{"Cache Available?"}
CacheExists --> |Yes| LoadCache["Load from Cache"]
CacheExists --> |No| Download["Download Metadata"]
Download --> Parse["Parse Metadata"]
Parse --> Validate["Validate Structure"]
Validate --> StoreCache["Store in Cache"]
StoreCache --> Complete["Bootstrap Complete"]
LoadCache --> Complete
Complete --> Ready["Ready for Requests"]

Loading

Diagram sources

• server/server/routes/general.py
• server/server/metadata.py

Section sources

• server/server/routes/general.py
• server/server/metadata.py

Payload Encoding/Decoding Endpoints

Codec Endpoint

Unified encoding/decoding endpoint supporting multiple formats.

Endpoint: POST /api/codec

Request Schema:

{
  "payload": "string",
  "mode": "decode|encode",
  "format": "string"
}

Supported Formats:

• json: JSON encoding/decoding
• cbor: Canonical CBOR encoding
• ctap-webauthn: CTAP/WebAuthn binary format
• client-data: WebAuthn client data
• auth-data: Authenticator data
• attestation-object: Attestation object
• x509: X.509 certificate
• public-key-credential: Public key credential
• der: DER-encoded certificate
• pem: PEM-encoded certificate
• cose: COSE format

Response Schema:

{
  "success": true,
  "type": "string",
  "data": {},
  "malformed": ["string"]
}

Decode Endpoint

Specialized decoding endpoint for various WebAuthn formats.

Endpoint: POST /api/decode

Request Schema:

{
  "payload": "string"
}

Response Schema:

{
  "format": "string",
  "inputEncoding": "string",
  "decoded": {},
  "binary": {
    "hex": "string",
    "base64": "string",
    "base64url": "string",
    "bytes": ["number"]
  }
}

Certificate Decoding Endpoint

Decodes X.509 certificates from various formats.

Endpoint: POST /api/mds/decode-certificate

Request Schema:

{
  "certificate": "string"
}

Response Schema:

{
  "details": {
    "subject": "string",
    "issuer": "string",
    "serialNumber": "string",
    "validity": {
      "notBefore": "datetime-string",
      "notAfter": "datetime-string"
    },
    "keyUsage": ["string"],
    "extendedKeyUsage": ["string"],
    "basicConstraints": {
      "ca": "boolean",
      "pathLenConstraint": "number"
    }
  }
}

Section sources

• server/server/routes/general.py
• server/server/decoder/encode.py
• server/server/decoder/decode.py

Credential Management Endpoints

Delete Public Credentials

Removes stored credentials for a specific email address.

Endpoint: POST /api/deletepub

Request Schema:

{
  "email": "string"
}

Response Schema:

{
  "status": "OK"
}

Download Credentials

Downloads credential data as a binary file.

Endpoint: GET /api/downloadcred

Query Parameters:

• email: Email address of the credential owner

Response:

• Content-Type: application/octet-stream
• Attachment: {email}_credential_data.pkl
• Body: Pickled credential data

HTTP Status Codes:

• 200 OK: Successfully downloaded
• 400 Bad Request: Missing email parameter
• 404 Not Found: No credentials found

Section sources

• server/server/routes/general.py

Security Considerations

File Type Validation

The platform implements comprehensive file validation for metadata uploads:

Validation Type	Implementation	Purpose
Extension Check	.json file extension enforcement	Prevents malicious file types
Content Validation	UTF-8 encoding verification	Ensures readable content
Structure Validation	JSON object/array validation	Maintains data integrity
Size Limits	Configurable upload limits	Prevents resource exhaustion

Input Sanitization

flowchart TD
Input["Raw Input"] --> Validate["Input Validation"]
Validate --> Sanitize["Sanitization"]
Sanitize --> Normalize["Normalization"]
Normalize --> Process["Processing"]
Validate --> |Invalid| Reject["Reject Request"]
Sanitize --> |Malformed| Clean["Clean Data"]
Clean --> Process

Loading

Diagram sources

• server/server/metadata.py
• server/server/routes/general.py

Protection Against Unauthorized Access

Session Isolation:

• Each user has isolated metadata storage
• Session cookies prevent cross-session access
• Automatic session cleanup prevents stale data

File Access Control:

• Path traversal prevention in filenames
• Directory enumeration protection
• Secure file permissions

Rate Limiting Considerations:

• Session activity tracking
• Automatic cleanup of inactive sessions
• Configurable cleanup intervals

Section sources

• server/server/metadata.py
• server/server/session_metadata_store.py

Error Handling

Standard Error Responses

All endpoints follow consistent error response patterns:

{
  "error": "Human-readable error message",
  "details": "Additional context (optional)"
}

HTTP Status Code Guidelines

Status Code	Usage	Example Scenarios
400 Bad Request	Invalid request format or parameters	Missing JSON, invalid file format
404 Not Found	Resource not found	Non-existent metadata entry
422 Unprocessable Entity	Valid format but invalid content	Malformed JSON, invalid certificate
500 Internal Server Error	Server-side failures	Storage errors, processing failures

Metadata-Specific Errors

Upload Failures:

• No JSON files were provided: Empty upload request
• Failed to read {filename}: {error}: File read errors
• {filename} is not valid UTF-8 JSON: Encoding issues
• {filename}: {error}: JSON parsing errors

Session Errors:

• No active metadata session: Session timeout or invalid cookie
• Unable to establish metadata session identifier: Server configuration issue

Section sources

• server/server/routes/general.py
• server/server/metadata.py

Examples and Usage Patterns

Metadata Upload Example

curl -X POST \
  -H "Content-Type: multipart/form-data" \
  -F "files=@metadata1.json" \
  -F "files=@metadata2.json" \
  http://localhost:5000/api/mds/metadata/upload

Response:

{
  "items": [
    {
      "entry": {
        "aaguid": "12345678-1234-1234-1234-123456789abc",
        "metadataStatement": {
          "description": "Test Authenticator",
          "authenticatorVersion": 1
        }
      },
      "source": {
        "storedFilename": "abc123def456.json",
        "originalFilename": "metadata1.json",
        "uploadedAt": "2024-01-15T10:30:00Z"
      }
    }
  ],
  "errors": []
}

Certificate Decoding Example

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"certificate": "-----BEGIN CERTIFICATE-----\nMIIC...\n-----END CERTIFICATE-----"}' \
  http://localhost:5000/api/mds/decode-certificate

Response:

{
  "details": {
    "subject": "CN=test.example.com",
    "issuer": "CN=Test CA",
    "serialNumber": "1234567890abcdef",
    "validity": {
      "notBefore": "2024-01-01T00:00:00Z",
      "notAfter": "2025-01-01T00:00:00Z"
    }
  }
}

Credential Management Example

# Delete credentials
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"email": "user@example.com"}' \
  http://localhost:5000/api/deletepub

# Download credentials
curl -H "Cookie: fido.mds.session=abc123" \
  "http://localhost:5000/api/downloadcred?email=user@example.com" \
  --output user_credentials.pkl

Codec Usage Examples

JSON to CBOR Conversion:

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "payload": "{\"test\": \"value\", \"number\": 42}",
    "mode": "encode",
    "format": "cbor"
  }' \
  http://localhost:5000/api/codec

Binary Data Decoding:

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "payload": "AAECAwQFBgcICQoLDA0ODxAREhMUFRYXGBkaGxwdHh8="
  }' \
  http://localhost:5000/api/decode

Section sources

• tests/test_metadata_sessions.py
• server/server/routes/general.py