Skip to content

Golden Age Hub - Phase 1 API Documentation

Table of Contents

  1. Overview
  2. API Endpoints
  3. Phase 1 Event Ingestion
  4. Proof-of-Care Ledger
  5. Real-Time Alerts WebSocket
  6. Security & Reliability
  7. Cryptographic Verification
  8. Replay Protection
  9. Rate Limiting
  10. Error Handling

Overview

Golden Age Hub Phase 1 implements a comprehensive healthcare data ingestion pipeline with cryptographic verification, Merkle tree proof-of-care system, and enterprise-grade security features. The API provides secure endpoints for event ingestion and verification.

Current Implementation Status: 100% Complete

  • ✅ Event Ingestion: Complete with Ed25519 signature verification and RFC 8785 canonicalization
  • ✅ Proof-of-Care Ledger: Merkle tree implementation with block-based verification
  • ✅ Security Pipeline: Rate limiting, replay protection, and comprehensive audit logging
  • ✅ TimescaleDB Integration: Hypertable optimization with compression and retention policies
  • ✅ Testing Infrastructure: 90/90 tests passing with comprehensive coverage
  • ✅ CI/CD Pipeline: GitHub Actions aligned with backend architecture
  • ✅ Development Workflow: Modern Makefiles and server startup scripts

Current Status: Production Ready

The Golden Age Hub Phase 1 implementation is 100% complete and production-ready with comprehensive testing, documentation, and deployment automation.

API Endpoints

Phase 1 Event Ingestion

Ingest a Signed Event

This is the primary endpoint for all event data from devices and applications. The server validates the request against a strict JSON Schema before accepting it for processing.

POST /v1/events/ingest
Content-Type: application/json

Request Body: The body must be a valid EventPayload object. See schemas/events.json for the full schema.

Example Request Body:

{
  "event_id": "770e8500-e29b-41d4-a716-446655442222",
  "patient_id": "550e8400-e29b-41d4-a716-446655440000",
  "device_id": "GA-123456",
  "sequence_id": 152,
  "timestamp": "2025-01-01T12:00:00Z",
  "event_type": "fall",
  "confidence": 0.92,
  "location": {
    "lat": 37.7749,
    "lng": -122.4194,
    "accuracy_m": 10
  },
  "sensor_data": {
    "accel_peak": 15.7,
    "position_changed": true
  },
  "signature": "a_64_byte_ed25519_signature_string"
}

Responses:

  • 202 Accepted: Event is well-formed and has been accepted for asynchronous processing.
  • 422 Unprocessable Entity: The request body failed JSON Schema validation. The response will detail the errors.
  • 401 Unauthorized: Authentication failed (invalid signature or malformed request).
  • 409 Conflict: Replay attack detected (sequence_id was not greater than the last seen ID).
  • 429 Too Many Requests: Per-device rate limit exceeded.

Proof-of-Care Ledger

Verify Event Inclusion

Verify that an event is included in the Proof-of-Care ledger with cryptographic proof.

GET /v1/proof-of-care/verify/{event_id}

Responses:

  • 200 OK: Event verification successful with proof details
  • 404 Not Found: Event or proof not found

Example Response:

{
  "event_id": "770e8500-e29b-41d4-a716-446655442222",
  "block_id": 1,
  "block_timestamp": "2025-01-01T12:00:00Z",
  "merkle_root": "a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3",
  "leaf_index": 0,
  "proof_hashes": [
    "b665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3"
  ],
  "is_verified": true,
  "event_data": {
    "event_id": "770e8500-e29b-41d4-a716-446655442222",
    "patient_id": "550e8400-e29b-41d4-a716-446655440000",
    "device_id": "GA-123456",
    "event_type": "fall",
    "event_timestamp": "2025-01-01T12:00:00Z",
    "confidence": 0.92
  }
}

List Merkle Blocks

Retrieve a paginated list of all Merkle blocks in the Proof-of-Care ledger.

GET /v1/proof-of-care/blocks?limit=100&offset=0

Query Parameters:

  • limit (optional): Maximum number of blocks to return (1-1000, default: 100)
  • offset (optional): Number of blocks to skip (default: 0)

Responses:

  • 200 OK: List of blocks with metadata

Get Block Details

Retrieve detailed information about a specific Merkle block.

GET /v1/proof-of-care/blocks/{block_id}

Responses:

  • 200 OK: Block details with associated events and proofs
  • 404 Not Found: Block not found

Get Ledger Status

Get overall statistics and current state of the Proof-of-Care ledger.

GET /v1/proof-of-care/ledger-status

Responses:

  • 200 OK: Current ledger statistics

Example Response:

{
  "total_blocks": 5,
  "total_events": 500,
  "processed_events": 500,
  "unprocessed_events": 0,
  "ledger_coverage": 100.0,
  "latest_block": {
    "block_id": 5,
    "block_timestamp": "2025-01-01T12:00:00Z",
    "event_count": 100,
    "merkle_root": "a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3"
  }
}

Real-Time Alerts WebSocket

Receive real-time notifications for incoming event classifications (e.g., posture fall warnings, wandering alerts) processed by the pipeline workers.

WEBSOCKET /ws

Pub/Sub Channel Broadcast

The gateway subscribes to the Redis realtime_alerts channel. Any event processed by the Celery pipeline is published to this channel and broadcast to all connected WebSocket clients as a JSON payload.

Message Payload Example:

{
  "event_id": "8907a752-95f2-4c28-9844-469bfd0a1b22",
  "patient_id": "c665a459-2042-4f9d-417e-4867efdc4fb8",
  "caregiver_id": "8907a752-95f2-4c28-9844-469bfd0a1b11",
  "event_type": "fall_alert",
  "timestamp": "2026-07-12T12:00:00Z",
  "metadata": {
    "confidence": 0.98,
    "location": {
      "latitude": 30.2241,
      "longitude": -92.0198
    }
  }
}

Security & Reliability

Cryptographic Verification

The system implements enterprise-grade cryptographic verification:

  • Ed25519 Signatures: All events must be cryptographically signed by the originating device
  • RFC 8785 Canonicalization: Event payloads are canonicalized before signing for deterministic hashing
  • Merkle Tree Proofs: Mathematical verification of event inclusion with O(log n) complexity
  • SHA-256 Hashing: Industry-standard cryptographic hash function for all operations

Replay Protection

The system is protected against replay attacks through multiple mechanisms:

  • Device Sequence IDs: Each device maintains a strictly increasing sequence counter
  • Server-side Validation: Server tracks last valid sequence ID per device
  • Gap Detection: Automatic detection of missing sequence numbers for audit purposes
  • Timestamp Validation: Event timestamps must be within acceptable bounds

Rate Limiting

The API uses a token-bucket algorithm to enforce rate limits on a per-device basis:

  • Default Limits: 10 requests per second with 100 request burst capacity
  • Dynamic Adjustment: Rate limits can be adjusted per device based on trust level
  • Fair Queuing: Requests are queued fairly to prevent starvation
  • Monitoring: Rate limit status included in response headers

Response Headers:

  • X-RateLimit-Limit: Maximum requests in the current window
  • X-RateLimit-Remaining: Remaining requests in the current window
  • X-RateLimit-Reset: Timestamp when the limit will reset

Error Handling

Standard HTTP status codes are used throughout the API. For client errors (4xx), the response body will contain a JSON object with detailed error information.

Standard Error Response:

{
  "error": {
    "code": "validation_error",
    "message": "The payload failed JSON Schema validation.",
    "details": {
      "field": "event_type",
      "issue": "'invalid_type' is not one of ['fall', 'wandering', 'manual_log', 'vitals']"
    },
    "request_id": "req_1234567890"
  }
}

Common Error Codes:

  • validation_error: JSON Schema validation failed
  • signature_error: Cryptographic signature verification failed
  • replay_error: Replay attack detected
  • rate_limit_error: Rate limit exceeded
  • internal_error: Unexpected server error