WRNexusJS/docs/plans/2026-08-04-authz-permissions-design.md

Permissions system design (@wrnexus/authz)

Date: 2026-08-04 Status: approved, not yet implemented Supersedes: nothing — extends the existing @wrnexus/authz package

Problem

@wrnexus/authz today evaluates authorization but does not describe it. defineRbac() takes a literal object of roles, policies are anonymous closures, and nothing records which permissions exist. The consequences:

• No discoverability. Nothing can answer "what permissions does this system have?"
• No runtime assignment. Changing who is an admin requires a redeploy.
• No tenant awareness, despite core/src/tenant.ts already defining TenantMembership { tenantId, userId, roles[] } that authz never reads.
• No audit trail.
• Typos in permission strings fail silently as false.

The evaluation primitives are sound and stay: AuthorizationDecision, DecisionPolicy, owner, anyDecision, allDecisions, filterAuthorized, and the guard middleware.

Approach

Separate declaration (what permissions, roles, policies and attributes exist — static, typed, in code) from assignment (who holds what — dynamic, in a store). The existing package becomes the evaluation layer beneath both.

Rejected alternatives:

• Extend defineRbac in place. Half the work, but leaves discoverability, codegen, cross-app catalog and audit with nowhere to live.
• Adapter for OpenFGA / Cedar / SpiceDB. Better at relationship-heavy authorization, but puts a network dependency and a sidecar in the request path of a zero-dependency framework.

Module layout

@wrnexus/authz
  index.ts      existing surface (unchanged exports)
  advanced.ts   existing decision primitives (unchanged exports)
  registry.ts   defineAuthz() — permissions, roles, policies, attributes
  catalog.ts    discovery, merge, conflict detection; frozen at boot
  store.ts      PermissionStore interface, memory adapter, cachedPermissionStore()
  db.ts         dbPermissionStore(getDb()) — subpath export @wrnexus/authz/db
  engine.ts     subject -> effective permissions -> Decision
  guards.ts     route middleware, extended for resources
  audit.ts      AuthzAuditSink
  view.ts       can() exposed to .wrn `{#if}` expressions

Declaration

Declarations live in app/authz/*.ts, discovered the same way app/schemas/*.ts already is (packages/router/src/index.ts scans and populates router.schemas; this adds router.authz).

// app/authz/blog.ts
import { defineAuthz, owner } from "@wrnexus/authz";

export default defineAuthz({
  permissions: {
    "post:read": { title: "View posts", public: true },
    "post:write": { title: "Create and edit posts" },
    "post:delete": { title: "Delete posts", risk: "high" },
  },
  roles: {
    editor: ["post:*"],
    moderator: ["post:comment:*"],
    admin: ["role:editor", "role:moderator"],
  },
  policies: {
    ownsPost: owner("id", "authorId"),
  },
  attributes: {
    department: { description: "Subject's department, from the identity provider" },
  },
});

A permission declared public: true is granted to anonymous subjects. Every other permission denies when there is no authenticated user.

Catalog and cross-app scope

Declarations are static code, so sharing them across workspace apps needs no runtime distribution: the defineAuthz blocks live in the workspace's shared package (packages/shared, already scaffolded by wrnexus workspace) and every app imports them. They are identical by construction.

What is genuinely shared at runtime is assignments, and those live in the shared database behind PermissionStore.

wrnexus authz list is therefore introspection, not distribution: it walks every app in the workspace, merges catalogs, and reports the full permission/role/policy surface plus conflicts.

Merge rules:

• Two declarations of the same permission id with deep-equal metadata: no-op (lets shared packages re-declare freely).
• Two declarations of the same permission id whose metadata is not deep-equal: boot error naming both source files.
• The catalog is frozen after boot. Registration is not possible at request time.

Assignment store

interface AuthzScope {
  tenantId?: string;
}

interface SubjectAssignments {
  roles: string[];
  grants: string[]; // explicit allows, bypassing roles
  denies: string[]; // explicit denies, win over everything
}

interface PermissionStore {
  assignmentsFor(subjectId: string, scope?: AuthzScope): Promise<SubjectAssignments>;
  assignRole(subjectId: string, role: string, scope?: AuthzScope): Promise<void>;
  revokeRole(subjectId: string, role: string, scope?: AuthzScope): Promise<void>;
  grant(
    subjectId: string,
    permission: string,
    effect: "allow" | "deny",
    scope?: AuthzScope,
  ): Promise<void>;
  revokeGrant(subjectId: string, permission: string, scope?: AuthzScope): Promise<void>;
  listSubjects(scope?: AuthzScope): Promise<string[]>;
}

scope.tenantId is how this meets the existing TenantMembership. An assignment with no scope is global; a scoped assignment applies only within that tenant. Both are unioned for a request whose ctx.tenant is set.

Adapters:

• memoryPermissionStore() — tests and single-process development.
• dbPermissionStore(getDb()) — default; tables below.
• cachedPermissionStore(inner, { ttlMs, max }) — decorator exposing invalidate(subjectId, scope). Role changes must invalidate explicitly rather than wait out a TTL.

Tables

wrn_authz_assignment
  id, subject_id, scope, role, granted_by, created_at
  unique(subject_id, scope, role)

wrn_authz_grant
  id, subject_id, scope, permission, effect, granted_by, created_at
  unique(subject_id, scope, permission)

scope stores the tenant id, or the empty string for global. Migrations are scaffolded by wrnexus authz init, following the existing db/src/migrate.ts conventions.

Evaluation

How can() reaches a request

can is not added to the Context interface. @wrnexus/core must not depend on @wrnexus/authz — the same constraint that keeps getDb() off Context rather than introducing a core -> db cycle. Instead:

app.use(authzMiddleware({ store, catalog })); // stashes a resolver in ctx.locals
const allowed = await can(ctx, "post:delete", post); // imported from @wrnexus/authz

authzMiddleware puts the per-request resolver (with its memo table) into ctx.locals._authz; can(ctx, ...) reads it and throws a clear setup error if the middleware was not registered. Views get the bound form described under view integration.

Per request

1. Subject is ctx.user; scope is ctx.tenant.
2. store.assignmentsFor(subjectId, scope).
3. Registry expands roles into a permission set — wildcards at every depth (post:* and post:comment:* both grant post:comment:delete), role: inheritance, cycle-safe.
4. can(ctx, permission, resource?) checks the set, then runs any policy bound to that permission with the resource.
5. Result is an AuthorizationDecision; denials go to the audit sink.

Memoised per request. Precedence, highest first:

1. Explicit deny (store denies) — beats everything including *.
2. Policy denial.
3. Explicit grant or role-derived permission.
4. Default deny.

Failure behaviour

Every failure path denies.

Condition	Behaviour
Permission not in the registry	Throws in development, denies and audits in production
Store throws	Deny, audit, log. Never fail open.
Policy throws	Treated as a denial, logged with the policy name
No authenticated user	Deny, unless the permission is declared public

Audit

interface AuthzAuditEvent {
  subjectId?: string;
  scope?: AuthzScope;
  permission: string;
  allowed: boolean;
  reason?: string;
  policy?: string;
  at: number;
}
interface AuthzAuditSink {
  record(event: AuthzAuditEvent): void | Promise<void>;
}

Default sink is a no-op. Records denials only unless configured otherwise, to bound write volume on hot paths. Sink errors are logged and swallowed — auditing must never break a request.

Tooling

• wrnexus authz list — merged catalog across the workspace, with conflicts.
• wrnexus authz generate — emits app/authz/permissions.gen.ts exporting type Permission = "post:read" | "post:write" | .... can(), guardPermission(), and decideFor() all take a bare string and nothing consumes this union automatically — it exists to type your own helpers/constants against the registered catalog. Runs automatically in build.ts, mirroring regenerateQueries.
• wrnexus authz init — scaffolds the migration and a seed helper for default roles.
• Admin UI: .wrn components for listing subjects and assigning roles, shipped in @wrnexus/ui behind the existing eject mechanism.

Inter-app seam

Reserved for the inter-app communication system, specified but not built here:

exportSubjectContext(ctx): string      // signed, compact: subject id, scope, roles
importSubjectContext(token): Subject   // verified on the receiving app

An app calling another on a user's behalf propagates identity and roles rather than re-querying the store. The signing key and transport are the comms system's concern.

Security fix folded into this work

authorizeDecision currently returns the internal reason and policy name in the 403 body, disclosing policy structure to unauthenticated callers. This becomes opt-in via authorizeDecision(evaluate, { exposeReason: true }), defaulting to a bare { ok: false, error: "Forbidden" }.

Testing

• Store conformance suite — one shared set of tests run against both the memory and DB adapters so they cannot drift.
• Unit — wildcard expansion at depth, deny precedence, role-cycle termination, catalog merge conflicts, public-permission handling.
• Integration — guards return 403 for API and redirect for pages; {#if can(...)} omits markup server-side rather than hiding it with CSS.
• Security regression — unregistered permission denies in production; 403 body does not leak policy names unless opted in; store failure denies rather than allows.

Build order

1. registry.ts, catalog.ts, store.ts (memory), engine.ts, extended guards.ts.
2. Resource-level policies connected to filterAuthorized; audit.ts.
3. db.ts adapter, migrations, wrnexus authz init, codegen, wrnexus authz list.
4. .wrn view integration (can() inside {#if}).
5. Admin UI components.

Phase 4 is the only one whose shape is uncertain. The compiler supports {#if} at page level and nested, but exposing can() into that scope touches codegen (packages/compiler/src/codegen.ts). If it proves invasive, phases 1–3 ship on their own and view integration returns as its own design.

Out of scope

• Relationship-based authorization ("can edit because they're in the team that owns the doc"). Role and policy checks cover the intended cases; revisit if hierarchical resources appear.
• Permission delegation and time-bounded grants.
• Cross-workspace federation.