Changelog

All notable changes to the L8Server (Layr8 Cloud Node) project are documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

Code Quality Improvements (October 29, 2025)

These improvements were added during code review of the v4.0.0 release:

  • Added missing viewer role authorization test
  • Fixed superadmin role typo in test data (/global-group/ → /global-groups/)
  • Updated documentation to include :viewer in return values
  • Changed log level from info to debug for successful authorization (reduces log noise)
  • Made L8_NODE_ORG_SLUG required in production with runtime validation
  • Enhanced startup banner with key configuration details (environment, domain, org slug, ports, database, OpenTelemetry status)

[4.0.0] - 2025-10-18

Breaking Changes

  • Organization-Based Authorization: GraphQL API now requires JWT tokens with portal-org-roles claim
  • L8_NODE_ORG_SLUG: New required environment variable in production to identify licensed organization
  • Legacy Roles Removed: resource_access roles from Keycloak JWT are no longer used for authorization
  • Access Control: Users without valid organization roles (owner, admin, member, viewer, or superadmin) will be denied access

Features

  • Organization Authorization System

    • Added OrganizationAuthorizer module for organization-based access control
    • Supports hierarchical roles: superadmin (global), owner, admin, member, viewer (org-specific)
    • Runtime validation ensures production deployments are properly configured

  • Simplified Role Mapping

    • Reduced from 6+ legacy roles to 2 GraphQL roles: :admin (full access) and :viewer (read-only)
    • Clear separation between query (read) and mutation (write) operations

  • Enhanced Startup Banner

    • Displays key configuration details: environment, domain, org slug, ports, database, OpenTelemetry status
    • Security-conscious: excludes sensitive values (passwords, API keys, tokens)

Bug Fixes

  • Fixed typo in superadmin role path: /global-group/superadmin → /global-groups/superadmin

Improvements

  • Changed log level from info to debug for successful authorization (reduces production log noise)
  • Added comprehensive test coverage for organization authorization (18 tests)
  • Updated documentation to include :viewer role in all relevant places

Compatibility

  • Internal User system (database-backed roles) unchanged
  • API key authentication unchanged
  • Plugin authentication unchanged
  • Development/test environments work without L8_NODE_ORG_SLUG

[3.0.14] - 2025-10-18

This release consolidates work from July 21 - October 18, 2025, including security updates, OpenSSL compatibility fixes, and the foundation for organization-based authorization.

Security & Infrastructure (July 23, 2025)

  • Docker Base Image Migration:

    • Switched to Debian slim images with security updates
    • Later migrated to Alpine base images for OpenSSL compatibility

  • CVE Documentation and Assessment:

    • CVE-2023-45853: Documented as false positive
    • CVE-2025-4802: Documented as not applicable
    • CVE-2023-2953 (libldap): Documented as minor issue
    • CVE-2025-6020 (libpam): Documented as HIGH severity unfixed
    • CVE-2023-31484 (perl-base): Documented as minor issue

Features (October 18, 2025)

  • Organization Authorization Foundation: Added OrganizationAuthorizer module (preparation for v4.0.0)
  • MCP Design Documentation: Added design documentation for Model Context Protocol integration
  • Connection Monitoring (from July 21): L8-53 - Track connection status via gun_up/gun_down events

Improvements (October 18, 2025)

  • Enhanced debug logging and error handling for plugin channels
  • Improved DIDComm key lookup troubleshooting with additional logging
  • Better error handling in present_proof_v3 protocol

Refactoring (October 18, 2025)

  • Refactored DID document service injection logic for improved maintainability

Documentation

  • OpenSSL compatibility fix documentation
  • MCP over DIDComm design documents

[3.0.6] - 2025-07-16

Features

  • L8-53: Track connection status via gun_up/gun_down events for better connection monitoring (released July 21)

[3.0.5] - 2025-07-16

Features

  • L8-68: Add optional API Key to DID restriction for finer-grained access control
  • L8-89: Add domain information to structured log output

Bug Fixes

  • L8-88: Fix trust-ping protocol to respond when response_requested = true
  • L8-89: Fixed environment configuration issues

[3.0.4] - 2025-07-15

Features

  • L8-84: DID Whitelist/Blacklist System
    • Added simple whitelist/blacklist feature for DID-based access control
    • Support for wildcard patterns in whitelist/blacklist
    • In-memory cache for performance optimization
    • Extended to include GraphQL API authorization

Bug Fixes

  • L8-84: Fixed various GraphQL API bugs

Removed

  • L8-46: Removed getNodeConfig from GraphQL API for security

[3.0.3] - 2025-07-08

Features

  • L8-71: Add updateDid mutation to GraphQL API

[3.0.2] - 2025-07-08

Features

  • L8-64: Toolbox improvements and refactoring
  • L8-55: Updated getDid to include service section in DID Document

Refactoring

  • L8-15: Renamed TwinResolver to DidResolver (terminology consistency)

Bug Fixes

  • L8-56: Fixed getDid call
  • L8-51: Made API keys global to the node (no longer relying on user_id)

[3.0.0] - 2025-07-05

Breaking Changes

  • L8-3: Rights system renamed to Roles system (terminology change)
  • L8-33: Removed all geo-related functionality (queries, mutations, ping mutation)
  • L8-15: Renamed Twin concept to DID concept in GraphQL API
  • Treat compiler warnings as errors (improved code quality enforcement)

Features

  • L8-3: Introduced admin role; renamed required_roles.ex to role_mapping.ex
  • L8-1: Created getNodeInfo GraphQL query with startedAt field
  • L8-4: Add validation logic for DID deletion (prevent deletion of Node’s own DID)

Improvements

  • L8-45: GraphQL API returns NOT_AUTHORIZED instead of GENERIC_ERROR
  • L8-32: Updated error codes documentation and formatting
  • L8-34: Improved rate-limiting documentation
  • L8-48: Improved connection aliveness checking for gRPC transport with better test coverage

Removed

  • L8-31: Removed unused peer node code
  • L8-33: Removed geofencing/geo-related functionality

Bug Fixes

  • L8-41: Fixed flaky tests, cleaned up compiler warnings

[2.2.10] - 2025-06-16

Improvements

  • Dependencies update and testing improvements

[2.2.9] - 2025-06-20 to 2025-03-09

Security & Infrastructure

  • Docker Base Image Migration: Switched from Debian to Alpine base images for OpenSSL compatibility
  • Security Updates: Applied security updates and documented CVEs
    • CVE-2023-45853: Documented as false positive
    • CVE-2025-4802: Documented as not applicable
    • CVE-2023-2953 (libldap): Documented as minor issue
    • CVE-2025-6020 (libpam): Documented as HIGH severity unfixed
    • CVE-2023-31484 (perl-base): Documented as minor issue

Features

  • Keycloak Integration

    • Migrate ex_auth into l8_server directly
    • Update GraphQL API to authenticate JWT using Keycloak
    • Add environment variables for Keycloak configuration
    • Fix Keycloak authentication and validation issues

  • Database

    • Add L8Server.Repo.WithAutoReconnect module for improved resilience
    • Fix database connection configuration
    • Add backward compatibility with ExAuth.Repo migrations

Improvements

  • Structured Logging: Initial steps toward structured JSON logging
  • OpenTelemetry: Optional OTEL exporter functionality (configurable)
  • Web Server Migration: Upgrade from Cowboy to Bandit to resolve HTTP 431 response codes
  • Bump max header length to 32KB (later to 50KB for request line, 100KB for headers)
  • Fix database idle interval bug for Neon.tech databases

Bug Fixes

  • Fixed plugin channel authentication issues
  • Fixed graphql authentication and authorization
  • Fixed arm64 Docker image builds
  • Fixed GraphQL getNodeConfig types

Removed

  • Removed auth-related mutations from GraphQL API (security)

[2.2.5] - 2025-01-31

Architecture Refactoring

  • Three Endpoint Architecture: Split into Admin, Plugin, and Public endpoints

    • Admin Endpoint (port 4001): Management interface with GraphQL
    • Plugin Endpoint (port 4000): WebSocket connections for plugins
    • Public Endpoint (port 9000): DID document resolution and public APIs

  • Removed dependency on L8_NODE_BIND_ADDRESS

  • Tightened security on plugin endpoint

  • Cleaned up environment variables and port configuration

Features

  • Add get_users and get_ports to Toolbox

Bug Fixes

  • Fixed plugin reply handling with improved logging
  • Fixed gRPC ingress configuration

[2.2.2] - 2025-02-28 to 2025-02-21

Features

  • Observability

    • Added OpenTelemetry integration with tracing instrumentation
    • Added PromEx for Prometheus metrics
    • Instrumented plugin lifecycle: connect, disconnect, send, receive
    • Added tracing for DID document controller and resolution

  • Caching

    • Added DidDocCache module for DID document caching
    • Added DidWebServerCache for server-level caching
    • Improved performance for DID resolution

Improvements

  • Enhanced telemetry for plugin sessions, connections, and message passing
  • Improved debugging with SSL option logging for gRPC connections
  • Added ecto_dev_logger for database query logging in development

Removed

  • Cleaned out ExPub references

[2.2.0] - Earlier History

Initial Features

  • Core DIDComm Implementation

    • Message pipeline architecture
    • Support for DIDComm encryption and signing
    • Protocol handlers and message routing

  • Credential System

    • Verifiable credentials support
    • Credential chain of trust (Twin → Member → Network → Root)
    • Present Proof protocol (v3)

  • GraphQL API

    • Twin/DID management
    • Message sending and receiving
    • User and API key management
    • Rate limiting

  • Plugin System

    • WebSocket-based plugin connections
    • API key authentication for plugins
    • Protocol registration and message delivery

  • Database

    • PostgreSQL with Ecto
    • SSL support for production
    • Connection pooling and retry logic
    • Neon.tech compatibility

  • Transport Layers

    • HTTP transport for DIDComm
    • gRPC transport with SSL support
    • WebSocket for plugins

  • Development Tools

    • Toolbox module for interactive development
    • Seed data and test helpers
    • Script utilities

Infrastructure

  • Docker support with multi-stage builds
  • Docker image provenance for security
  • Environment configuration with Mahaul
  • Multiple deployment environments (dev, test, staging, prod)

Version History

4.x Series

  • v4.0.0 (2025-10-18): Organization-based authorization system (breaking)
    • Unreleased improvements (2025-10-29): Code review enhancements

3.x Series

  • v3.0.14 (2025-10-18): Security updates, OpenSSL compatibility, MCP documentation, organization auth foundation
    • Consolidates work from 2025-07-21 to 2025-10-18
    • Note: No v3.0.7-3.0.13 versions were released
  • v3.0.6 (2025-07-16): Connection status tracking via gun events
  • v3.0.5 (2025-07-16): API key DID restrictions, structured logging
  • v3.0.4 (2025-07-15): Whitelist/blacklist system with wildcards
  • v3.0.3 (2025-07-08): updateDid mutation
  • v3.0.2 (2025-07-08): Toolbox improvements, DidResolver rename
  • v3.0.0 (2025-07-05): Rights→Roles rename, remove geo features (breaking)

2.x Series

  • v2.2.10 (2025-06-16): Dependencies update and testing
  • v2.2.9 (2025-03-09): Plugin auth fixes
  • v2.2.8 (2025-03-09): Container image fix
  • v2.2.7 (2025-03-09): Tracer fixes
  • v2.2.6 (2025-02-28): Telemetry and metrics instrumentation
  • v2.2.5 (2025-01-31): Three endpoint architecture (Admin, Plugin, Public)
  • v2.2.4 (2025-01-31): Port and environment configuration cleanup
  • v2.2.3 (2025-01-30): Logging improvements
  • v2.2.2 (2025-01-29): gRPC ingress fix
  • v2.2.1 (2025-01-29): gRPC ingress logic
  • v2.2.0 (2025-01-29): Initial tracked release

Legend

  • Major Release: Significant new features or milestones
  • Breaking Changes: Changes that require action from users
  • Features: New functionality
  • Bug Fixes: Bug and issue fixes
  • Improvements: Enhancements to existing functionality
  • Refactoring: Code organization and cleanup
  • Removed: Deprecated or removed features
  • Security: Security fixes and improvements
  • Dependencies: Dependency updates
  • Documentation: Documentation improvements

Migration Guides

Migrating to v4.0.0

Required Actions:

  1. Set L8_NODE_ORG_SLUG: Add the organization slug environment variable

    export L8_NODE_ORG_SLUG=your-org-slug

  2. Update JWT Tokens: Ensure Keycloak JWT tokens include portal-org-roles claim with one of:

    • /organizations/{org-slug}/owner
    • /organizations/{org-slug}/admin
    • /organizations/{org-slug}/member
    • /organizations/{org-slug}/viewer
    • /global-groups/superadmin (for global access)

  3. Remove Legacy Roles: Remove any dependencies on resource_access roles from Keycloak configuration

  4. Test Authorization: Verify that authorized users can access GraphQL API and unauthorized users are rejected

Non-Breaking:

  • API key authentication continues to work unchanged
  • Internal user system (database roles) unchanged
  • Development/test environments can omit L8_NODE_ORG_SLUG

Migrating to v3.0.0

Required Actions:

  1. Terminology Changes:

    • Update references from “rights” to “roles” in code and configuration
    • Update references from “twin” to “DID” in GraphQL queries/mutations

  2. Remove Geo Features:

    • Remove any code using geo-related queries or mutations
    • Database schema preserved (data not deleted)

  3. Error Handling:

    • Update error handling to expect NOT_AUTHORIZED instead of GENERIC_ERROR

Migrating to v2.2.5

Required Actions:

  1. Update Environment Variables:

    • Remove L8_NODE_BIND_ADDRESS (no longer used)
    • Configure endpoint-specific ports if needed

  2. Update Client URLs:

    • Admin/GraphQL: Port 4001
    • Plugin WebSocket: Port 4000
    • Public/DID Resolution: Port 9000

Contributing

When adding entries to this changelog:

  1. Place new entries under the [Unreleased] section at the top
  2. Use the appropriate emoji/category for the change type
  3. Reference issue numbers when applicable (e.g., L8-123)
  4. Keep descriptions concise but informative
  5. Highlight breaking changes clearly