How Fluxer Handles the .well-known/fluxer Discovery Document for Instance Validation

Fluxer publishes a canonical /.well-known/fluxer endpoint on every instance that returns a JSON discovery document containing API endpoints, federation status, and public keys, enabling automated validation by clients and federated services.

Fluxer implements a standards-based instance discovery mechanism through the .well-known/fluxer endpoint that every instance must publish. This discovery document serves as the authoritative source for API locations, feature flags, and cryptographic credentials required for secure federation. According to the fluxerapp/fluxer source code, the implementation spans both the TypeScript API service and the Erlang relay system to ensure reliable validation across the network.

Endpoint Implementation and Middleware

The discovery endpoint is defined in packages/api/src/instance/InstanceController.tsx. According to lines 35-48 of the source, the controller registers the route at /.well-known/fluxer using a standard HTTP GET handler and applies RateLimitMiddleware to prevent abuse.

The response schema is enforced with WellKnownFluxerResponse, ensuring type safety and consistent JSON structure. The implementation automatically sets the Access-Control-Allow-Origin: * header to enable cross-origin requests from web-based clients and federated instances.

The route is wired into the Hono server in fluxer_server/src/Routes.tsx at line 130, making the endpoint available immediately upon server startup without additional configuration.

Discovery Document Structure

The JSON response aggregates configuration from the global Config object and runtime instance settings. The document contains several critical sections:

• API Versioning: The api_code_version field indicates the server software version
• Endpoint URLs: Absolute URLs for the client API, gateway, media server, and public endpoints
• Feature Flags: Captcha configuration, SMS MFA availability, and other capability toggles
• Operational Limits: Rate limiting thresholds and quota information
• Federation Metadata: When enabled, includes the instance's public key and OAuth 2.0 discovery endpoints

The public_key object uses the X25519 algorithm for federation identity verification, containing id, algorithm, and public_key_base64 fields. The oauth2 section provides the authorization and token endpoints required for federated authentication flows.

Instance Validation and Caching

The Erlang relay system consumes this document to validate and locate Fluxer instances. In fluxer_relay/src/relay/fluxer_relay_instance_discovery.erl (lines 62-75 and 120-144), the discover_gateway/1 function implements a robust caching mechanism to minimize network overhead.

The validation process follows these steps:

1. Check the ETS cache for existing gateway information for the target domain
2. On cache miss, perform an HTTP GET to https://{instanceDomain}/.well-known/fluxer
3. Parse the JSON response and extract the gateway endpoint URL
4. Cache the parsed result for five minutes before allowing expiration

If the HTTP request fails, returns invalid JSON, or lacks a valid gateway URL, the relay returns an error tuple, preventing connection to misconfigured or non-existent instances.

Working with the Discovery Document

Fetching the Document via HTTP

Clients can retrieve the discovery document using standard HTTP requests:

curl -s https://myinstance.example.com/.well-known/fluxer | jq .

A typical response includes:

{
  "api_code_version": "2026.0.0",
  "endpoints": {
    "api": "https://api.myinstance.example.com",
    "gateway": "https://gateway.myinstance.example.com",
    "media": "https://media.myinstance.example.com"
  },
  "features": {
    "sms_mfa_enabled": true
  },
  "federation": {
    "enabled": true,
    "version": "1"
  },
  "public_key": {
    "id": "https://myinstance.example.com/.well-known/fluxer#main-key",
    "algorithm": "x25519",
    "public_key_base64": "ABCD..."
  }
}

Validating Instances in Erlang

Services can validate and locate gateways programmatically:

{ok, GatewayInfo} = fluxer_relay_instance_discovery:discover_gateway("myinstance.example.com").

The GatewayInfo map contains host, port, and use_tls fields extracted from the discovery document's gateway endpoint.

Extending Discovery with Custom Features

To expose new capabilities to clients, modify packages/api/src/Config.tsx:

export const Config = {
  features: {
    new_feature_enabled: true,
    // Existing flags...
  },
};

The InstanceController automatically includes Config.features in the discovery response, making the new flag visible to all clients without requiring changes to the route handler.

Summary

• The /.well-known/fluxer endpoint is implemented in packages/api/src/instance/InstanceController.tsx with rate limiting via RateLimitMiddleware and CORS headers for cross-origin access
• The discovery document contains API versioning, endpoint URLs, feature flags, rate limits, and federation credentials including X25519 public keys
• The Erlang relay in fluxer_relay_instance_discovery.erl caches discovery results for five minutes in ETS to optimize validation performance
• Configuration changes propagate automatically through the global Config object, requiring no code changes to update the discovery document

Frequently Asked Questions

What information does the .well-known/fluxer discovery document contain?

The document returns a JSON object containing the api_code_version, endpoint URLs for API, gateway, and media services, feature flags such as sms_mfa_enabled, operational limits, and federation metadata. When federation is enabled, it also includes the instance's public key and OAuth 2.0 endpoint URLs required for secure inter-instance communication.

How does Fluxer prevent abuse of the discovery endpoint?

The InstanceController applies RateLimitMiddleware to the /.well-known/fluxer route to limit request frequency. This prevents denial-of-service attacks against the discovery mechanism while still allowing legitimate clients and federated instances to perform validation.

How long does the relay cache discovery document results?

The Erlang relay implementation caches successful discovery results for five minutes in an ETS table. This reduces redundant HTTP requests to target instances while ensuring that gateway information remains reasonably fresh for routing decisions.

Can I customize the discovery document for my Fluxer instance?

Yes. By modifying the Config object in packages/api/src/Config.tsx, you can add custom feature flags or adjust endpoint URLs. The InstanceController automatically incorporates these changes into the discovery document response without requiring modifications to the route handler or response schema.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}