General Application Endpoints - FeitianTech/postquantum-webauthn-platform GitHub Wiki

General Application Endpoints

Introduction
Authentication and Session Management
Metadata Service (MDS) Endpoints
Payload Encoding/Decoding Endpoints
Credential Management Endpoints
Security Considerations
Error Handling
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

Diagram sources

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

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"]

Diagram sources

Section sources

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

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

Diagram sources

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

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

Examples and Usage Patterns

Metadata Upload Example

curl -X POST \
  -H "Content-Type: multipart/form-data" \
  -F "[email protected]" \
  -F "[email protected]" \
  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": "[email protected]"}' \
  http://localhost:5000/api/deletepub

# Download credentials
curl -H "Cookie: fido.mds.session=abc123" \
  "http://localhost:5000/api/[email protected]" \
  --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

General Application Endpoints - FeitianTech/postquantum-webauthn-platform GitHub Wiki

General Application Endpoints

Table of Contents

Introduction

Authentication and Session Management

Session-Based Architecture

Session Security Features

Metadata Service (MDS) Endpoints

Base Metadata Endpoint

Custom Metadata Management

List Custom Metadata Entries

Upload Custom Metadata

Delete Custom Metadata

Metadata Bootstrap Process

Payload Encoding/Decoding Endpoints

Codec Endpoint

Decode Endpoint

Certificate Decoding Endpoint

Credential Management Endpoints

Delete Public Credentials

Download Credentials

Security Considerations

File Type Validation

Input Sanitization

Protection Against Unauthorized Access

Error Handling

Standard Error Responses

HTTP Status Code Guidelines

Metadata-Specific Errors

Examples and Usage Patterns

Metadata Upload Example

Certificate Decoding Example

Credential Management Example

Codec Usage Examples