nara-auth-rbac

Auth & RBAC

Procedural guidance for modifying the local/reference Auth provider, session/RBAC behavior, or application-level Auth composition.

Scope: provider work, not reusable-Feature coupling

A reusable Feature must NOT directly depend on Auth implementation — not on its routes, services, repositories, tables, or session helpers. When a reusable Feature needs identity or authorization behavior it does not own, it declares a typed host requirement instead:

Reusable Feature
→ declares typed host requirements

Application binding
→ adapts host requirements

Chosen Auth provider
→ fulfills those requirements

Concretely: Users never imports Auth. Users declares UsersServerHost / UsersWebHost; src/app/bindings/users.server.ts and src/app/bindings/users.web.ts adapt those requirements to the selected Auth provider. Swapping the provider means writing a new binding, never editing the Feature. There is no DI container, service locator, or provider registry — bindings are plain TypeScript values passed to explicit factory arguments and route props.

Ownership

The Auth provider owns identity end to end:

Auth provider
→ identity
→ credentials
→ sessions
→ roles/permissions
→ provider-level authorization APIs

In the reference application that is src/features/auth/ (contract.ts, server/accounts.ts, server/service.ts, server/access.ts, server/repository.ts, plus routes). Other capabilities reach accounts only through the provider's public boundary or through a typed host requirement adapted in an application-owned binding — never through direct SQL on Auth-owned tables. Full model: ../../../ARCHITECTURE.md and ../../../docs/v3/database-lifecycle.md.

Host-requirement pattern (for reusable Features)

Declare the capability the Feature needs but does not own. The real UsersServerHost is the reference shape:

import type { UsersServerHost } from '@/features/users/server/host';

export function createUserRoutes(host: UsersServerHost) {
  // Resolve the actor through the host, never through Auth imports.
  const actor = host.resolveActor(sessionToken);
  if (!actor) return unauthorized(context);
  if (!host.canManageUsers(actor.id, 'edit')) return forbidden(context);
  if (rolesChanged && !host.canAssignRoles(actor.id)) return forbidden(context);
}