Release Explorer

Release Notes

Overview

This release encompasses comprehensive backend enhancements across multiple Node.js/Express microservices forming the "FirstMate" platform. Key updates include robust JWT-based authentication and authorization with dynamic JWKS verification, fine-grained multi-tenant access control enforcement, organizational onboarding workflows with Stripe subscription integration, enriched contextual IAM propagation using continuation-local storage, repository management for enabling, disabling, refreshing, and analysis with async messaging via Redis streams, and advanced AI-driven features including question answering and branch naming leveraging large language models (LLMs).

New Features

  • Introduced organizational onboarding process with validation, API key generation, and subscription setup via Stripe integration.
  • Added backend REST API endpoints for securely managing organizational access rights, repository state changes, onboarding status, and user context updates.
  • Developed AI service endpoints integrating with LLMs for:
    • Generating branch names for change requests with prompt templates and retry logic.
    • Answering questions with categorized prompts, contextual data retrieval, and subscription validation.
    • Executing internal commands linked to organizational providers.
  • Integrated Redis Streams as an async service bus for scalable, decoupled processing of repository analysis commands and integration provider initialization.
  • Implemented a dedicated permission enforcement middleware supporting multi-permission arrays, public and internal endpoints, and provider-based role validations.

Improvements / Changes

  • Adopted middleware patterns that dynamically enforce fine-grained permission checks based on JWT tokens verified against remote JWKS endpoints, including handling provider-specific token sub parsing (e.g., Auth0).
  • Applied continuation-local-storage (CLS) namespaces to maintain enhanced IAM context (user, org, provider, requestId) propagated across async flows for consistent access and enriched logging.
  • Refined repository pattern abstractions for MongoDB data access with improved organization scoping and string-based key conversions.
  • Consolidated structured logging with pino, enriching all logs with IAM context, custom levels, and improved error serialization, including HTTP Axios errors.
  • Enhanced wildcard pattern matching for repository enable/disable operations via regex conversion.
  • Added robust error handling and domain-specific ApplicationErrors with unique codes for uniform API responses.
  • Improved JWT verification workflows to support asynchronous Promise-based verification with caching for JWKS keys.
  • Upgraded integration clients with base URL and headers pre-configuration for Git and other service APIs.
  • Reinforced data integrity by atomically updating nested access rights arrays in organization documents.
  • Strengthened permission validation logic to handle "ALL" wildcard access, FirstMate-specific prefixes, and nested role-based checks.
  • Added support for parsing and validating multiple API permissions per endpoint.
  • Optimized concurrent repository state updates and async calls with Promise.all for better resource handling.

Bug Fixes

  • Fixed errors related to missing or invalid JWT tokens causing improper authorization failures.
  • Resolved issues with token sub parsing for multi-part provider|providerId strings.
  • Addressed improper propagation of IAM context in asynchronous callbacks by binding CLS namespaces to request/response emitters.
  • Corrected handling of wildcard repository name patterns to include proper full-string matching.
  • Fixed potential missing request ID in logging context by generating fallback timestamp-based IDs.
  • Improved error serialization in logs to handle nested Axios error responses without losing stack traces.

Technical / Developer Notes

  • Each backend microservice extensively uses Express middleware returning wrapped handlers with detailed logging and error forwarding.
  • Repository implementations abstract MongoDB native driver calls with consistent conversion of ObjectId fields to strings for uniform querying.
  • JWT validation dynamically fetches signing keys from configured issuer JWKS endpoints via jwks-rsa client with internal caching.
  • The system expects token audiences and issuers to be configurable per environment.
  • Redis Streams are utilized instead of pub/sub for reliable, append-only event queuing keyed by organization ID and channel type.
  • ApplicationError class encapsulates error codes with messages, ensuring consistent error handling across modules.
  • AI agent integrations utilize Langchain prompt templates loaded from markdown files, enabling flexible context composition.
  • Logging is centralized via pino with hooks that inject IAM-related fields into each log entry, facilitating traceability in distributed environments.
  • Continuation-local-storage namespaces require explicit binding of Express request and response objects to propagate context throughout asynchronous operations.
  • Multiple microservices share conventions around provider and organization identification, user role validations, and middleware permission schemes.

Breaking Changes

  • Authorization middleware now requires explicit permission arrays per protected endpoint, altering middleware usage signatures.
  • Token sub parsing for provider and providerId separated by pipe | is mandatory for Auth0 tokens and similar providers.
  • Deprecated previous singular permission middleware in favor of granular multi-permission enforcement supporting FirstMate-specific prefixes.
  • Public endpoints should explicitly specify API_PERMISSIONS.PUBLIC_ENDPOINT in middleware to allow unauthenticated access.
  • Repository management endpoints enforce stricter wildcard pattern matching requiring full string regex conversion.
  • IAM context propagation relies on CLS namespaces binding; middleware usage needs adherence to binding request/response.
  • Error response format now standardized by ApplicationError codes; clients must handle updated error structures.

Acknowledgements / Contributors

  • Thanks to all backend engineers and DevOps team contributing to IAM security enhancements, MongoDB schema improvements, Redis Stream integration, AI agent feature development, and extensive testing efforts.
  • Gratitude for contributions improving logging clarity and error handling robustness across the platform services.