Require bearer token auth for facilitator server

[ponderingdemocritus]

This adds a composable bearer-token auth module for the facilitator server and wires it into startup for /verify and /settle. The server now requires BEARER_TOKEN or BEARER_TOKENS, and tests cover valid, invalid, and unprotected-route behavior. App composition was extended to accept pluggable modules so auth can be attached cleanly.

Summary by CodeRabbit

Release Notes

• New Features

  • Bearer token authentication support for protecting API endpoints, configurable via environment variables.
  • Modular architecture enabling extensible server functionality through pluggable modules.

• Tests

  • Added test coverage for bearer token authentication enforcement and protected/unprotected route access validation.

[coderabbitai]

📝 Walkthrough

Walkthrough

This pull request introduces bearer token authentication to the facilitator-server application. A new module system allows pluggable authentication middleware to be registered during app initialization. A bearer-token module validates authorization headers on protected endpoints, returning 401 responses for missing or invalid tokens.

Changes

Cohort / File(s)	Summary
App Module Infrastructure examples/facilitator-server/src/app.ts	Adds AppModule type and optional modules field to AppConfig. Refactors createApp to accept and register modules via baseApp.use(), enabling pluggable authentication and middleware composition.
Bearer Token Integration examples/facilitator-server/src/index.ts	Adds bearer token support via BEARER_TOKEN/BEARER_TOKENS environment variables. Constructs TOKENS array and integrates createBearerTokenModule with protected paths (/verify, /settle) into app initialization.
Bearer Token Module examples/facilitator-server/src/modules/bearer-token.ts	New file implementing bearer token authentication middleware. Exports BearerTokenModuleConfig interface and createBearerTokenModule function with token validation, path normalization, header parsing, and 401 response handling with WWW-Authenticate header.
Test Coverage examples/facilitator-server/tests/app.test.ts, examples/facilitator-server/tests/bearer-token-module.test.ts	New tests validating bearer authentication enforcement on protected routes (/verify) and comprehensive module tests covering valid tokens (200), unprotected routes (200), and invalid tokens (401) with proper WWW-Authenticate headers.

Sequence Diagram

sequenceDiagram
    participant Client
    participant Server as Elysia Server
    participant BearerModule as Bearer Token Module
    participant Handler as Route Handler

    Client->>Server: GET /verify (no auth header)
    Server->>BearerModule: validateRequest(/verify)
    BearerModule->>BearerModule: Check if /verify is protected
    BearerModule->>BearerModule: Parse Authorization header (missing)
    BearerModule->>Server: Return 401 Unauthorized
    Server->>Client: 401 + WWW-Authenticate: Bearer realm="facilitator"

    Client->>Server: GET /verify (valid token)
    Server->>BearerModule: validateRequest(/verify)
    BearerModule->>BearerModule: Check if /verify is protected
    BearerModule->>BearerModule: Parse & validate token
    BearerModule->>Server: Token valid, continue
    Server->>Handler: Route to handler
    Handler->>Server: 200 response
    Server->>Client: 200 OK

Loading

Estimated Code Review Effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 A module system hops into view,
Bearer tokens stand tall, strong and true,
Protected paths now guard the way,
With proper headers, come what may! 🔐

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: adding bearer token authentication requirement to the facilitator server, which is the core objective of this PR.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch ponderingdemocritus/pr

---

No actionable comments were generated in the recent review. 🎉

🧹 Recent nitpick comments

examples/facilitator-server/src/modules/bearer-token.ts (2)

48-50: unknown return type discards type safety and forces as any at the call site.

createBearerTokenModule returns a valid Elysia plugin (a function (app: Elysia) => Elysia). Typing it as unknown propagates an unsafe cast in app.ts (Line 152: baseApp.use(module as any)). Consider using a more descriptive type or the Elysia plugin signature.

Suggested improvement

-export function createBearerTokenModule(
-  config: BearerTokenModuleConfig
-): unknown {
+export function createBearerTokenModule(
+  config: BearerTokenModuleConfig
+): (app: Elysia) => Elysia {

And correspondingly in app.ts:

-export type AppModule = unknown;
+export type AppModule = (app: Elysia) => Elysia;

This would also let you remove the as any cast in app.ts Line 152.

---

37-42: Prefix matching on protected paths could inadvertently protect unrelated routes.

matchesProtectedPath matches any path that starts with a protected path followed by /. For example, if /settle is protected, then /settlement would not match (good), but /settle/anything would. This is likely intentional for sub-paths, but worth confirming it's the desired behavior since the current server only has flat routes.

examples/facilitator-server/src/index.ts (1)

14-15: Nit: Documentation says BEARER_TOKEN is "Required" but it's actually optional if BEARER_TOKENS is set.

Line 14 says "Required bearer token" but either BEARER_TOKEN or BEARER_TOKENS suffices. A small wording tweak (e.g., "Bearer token for /verify and /settle (or use BEARER_TOKENS)") would be clearer.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}