Skip to main content
Status: Accepted Date: 2026-02-06 Deciders: Reflections Maintainers

​
Context

The API exposes reflection-scoped and public routes. Unauthorized data access risk is high unless every protected route consistently applies authentication and role checks.

​
Decision

Use Hono as the API boundary and require route-level security discipline:
  • Protected route groups call authMiddleware().
  • Reflection/resource-scoped handlers call requireReflectionRole or requireResourceRole.
  • Public routes are explicitly isolated in dedicated route modules.
  • Global error mapping in app.onError standardizes response shapes.

​
Alternatives considered

​
Alternative 1: Framework-level global auth with route exceptions

Pros:
  • Less repeated middleware declarations.
Cons:
  • Exception paths become easy to misconfigure.
  • Harder to reason about per-route role requirements.

​
Alternative 2: Inline auth checks in each handler without shared helpers

Pros:
  • Local visibility of checks.
Cons:
  • Duplication and inconsistent enforcement.
  • Higher chance of drift in permission semantics.

​
Alternative 3: GraphQL gateway with resolver-level policies

Pros:
  • Centralized schema contract and policy hooks.
Cons:
  • Significant complexity increase for current REST surface.
  • Migration cost without clear short-term benefit.

​
Consequences

Benefits:
  • Predictable, reviewable authn/authz pattern across routes.
  • Clear public vs protected API boundary.
  • Centralized error transformation for stable client behavior.
Costs:
  • Requires sustained route review discipline.
  • Middleware/setup repetition across route modules.

​
Implementation notes

  • API composition and global middleware are defined in the main API entrypoint.
  • Route security patterns follow a consistent middleware-first approach across all route modules.
  • Public endpoints are intentionally grouped in a dedicated public route module.