page wrnexusauthz {
  seo {
    title = "@wrnexus/authz"
    description = "Role, permission, policy, and authorization guards."
  }

  view {
    <div class="docs-shell">
      <SkipLink label="Skip to content" href="#main" class="docs-skip-link" />
      <header class="topbar">
        <a class="brand" href="/"><span>W</span> WRNexusJS</a>
        <nav aria-label="Primary"><a href="/getting-started">Get started</a><a href="/packages">Packages</a><a href="/components">Components</a><a href="/language">Language</a><a href="/architecture">Architecture</a></nav>
        <div class="topbar-actions"><a class="preview-pill" href="/access">Private preview · v0.3.2</a><button data-wire-theme-toggle class="theme-button" aria-label="Toggle color theme" title="Toggle color theme">◐</button></div>
      </header>
      <div class="mobile-doc-nav"><details><summary>Browse documentation</summary><nav><a href="/getting-started">Get started</a><a href="/packages">Packages</a><a href="/components">Components</a><a href="/language">Language</a><a href="/architecture">Architecture</a><a href="/tutorial">Tutorial</a><a href="/guides/project-structure">Guides</a><a href="/examples">Examples</a><a href="/search">Search</a></nav></details></div>
      <main class="portal-main docs-layout">
      <article id="main" class="documentation prose standalone package-document"><nav class="breadcrumbs" aria-label="Breadcrumb"><a href="/">Home</a><span>/</span><a href="/packages">Packages</a><span>/</span><span aria-current="page">@wrnexus/authz</span></nav><section class="doc-intro"><span class="eyebrow">Security · Package reference</span><h1>@wrnexus/authz</h1><p>Role, permission, policy, and authorization guards.</p><div class="doc-meta"><span>v0.3.2</span><span>Private registry</span><span>Security</span></div><section id="access" class="access-callout"><h2>Install the package</h2><p>After WorkRoot approves private registry access, install the release-aligned package:</p><pre><code>bun add @wrnexus/authz@0.3.2</code><button type="button" class="copy-button" aria-label="Copy installation command">Copy</button></pre><p><a href="/access">Request preview access</a>. Never put registry tokens in source control.</p></section></section><section id="guide"><blockquote>Composable authorization for WRNexusJS — role-based (RBAC), policy-based (PBAC), and attribute-based (ABAC) access control that reduces to a boolean check plus an <code>authorize()</code> guard.</blockquote>
<p>Part of the <strong>WRNexusJS</strong> framework — an SSR-first, Bun-native full-stack web framework.</p>
<h3 id="overview">Overview</h3>
<p><code>@wrnexus/authz</code> is a small, server-side authorization toolkit. It gives you three interchangeable models — RBAC (roles → permissions), PBAC (policy predicates), and ABAC (attribute matchers) — that all collapse to a <code>boolean | Promise&lt;boolean&gt;</code> decision. Wrap any decision in a <code>Middleware</code> guard (<code>authorize</code>, <code>requireRole</code>, <code>requirePermission</code>) to protect WRNexusJS routes. Reach for it whenever a route or action needs to be gated on who the user is, what roles they hold, or attributes of the user and the resource. It plugs into <code>@wrnexus/core</code> by reading <code>ctx.user</code> as the authorization subject.</p>
<pre data-language="bash"><code>bun add @wrnexus/authz</code></pre>
<blockquote>Private package — the machine must be authenticated to the <code>wrnexus</code> npm org</blockquote>
<blockquote>(a read token in <code>~/.npmrc</code>). Requires <strong>Bun</strong> (Node is not supported).</blockquote>
<h3 id="api">API</h3>
<p>The package has a single entry point (<code>@wrnexus/authz</code>) exporting the following.</p>
<h4 id="types">Types</h4>
<div class="table-wrap"><table>
<thead><tr><th>Symbol</th><th>Description</th></tr></thead>
<tbody><tr><td><code>Subject</code></td><td>The authorized principal: <code>&#123; id?: string; roles?: string[]; [attribute: string]: unknown &#125;</code>.</td></tr><tr><td><code>Rbac</code></td><td>An RBAC checker: <code>&#123; can(subject, permission): boolean; permissionsFor(roles): Set&lt;string&gt; &#125;</code>.</td></tr><tr><td><code>Policy&lt;S = Subject, R = unknown&gt;</code></td><td>A predicate `(subject: S, resource?: R) =&gt; boolean \</td><td>Promise&lt;boolean&gt;`.</td></tr></tbody></table></div>
<h4 id="rbac">RBAC</h4>
<h4 id="definerbac-roles-record-string-string-rbac"><code>defineRbac(roles: Record&lt;string, string[]&gt;): Rbac</code></h4>
<p>Builds an RBAC checker from a role → permissions map. Supported permission forms:</p>
<ul>
<li><code>&quot;*&quot;</code> — grants every permission.</li>
<li><code>&quot;ns:*&quot;</code> — namespace wildcard (e.g. <code>&quot;post:*&quot;</code> grants <code>&quot;post:write&quot;</code>).</li>
<li><code>&quot;role:&lt;name&gt;&quot;</code> — inherits all permissions of another role (resolved recursively, cycle-safe).</li>
</ul>
<p>The returned <code>Rbac</code> provides:</p>
<ul>
<li><code>can(subject, permission)</code> — <code>true</code> if any of <code>subject.roles</code> grants <code>permission</code> (honouring <code>*</code> and namespace wildcards). Returns <code>false</code> when the subject has no roles.</li>
<li><code>permissionsFor(roles)</code> — the resolved <code>Set&lt;string&gt;</code> of all permissions granted to a set of roles.</li>
</ul>
<h4 id="hasrole-subject-subject-undefined-required-string-boolean"><code>hasRole(subject: Subject | undefined, ...required: string[]): boolean</code></h4>
<p><code>true</code> if the subject holds <strong>all</strong> of the given roles.</p>
<h4 id="pbac-abac-combinators">PBAC / ABAC combinators</h4>
<ul>
<li><code>any&lt;S, R&gt;(...policies: Policy&lt;S, R&gt;[]): Policy&lt;S, R&gt;</code> — allow if <strong>any</strong> policy passes (OR); awaits async policies.</li>
<li><code>all&lt;S, R&gt;(...policies: Policy&lt;S, R&gt;[]): Policy&lt;S, R&gt;</code> — allow only if <strong>all</strong> policies pass (AND); awaits async policies.</li>
<li><code>attr&lt;S extends Subject&gt;(name: string, match: unknown | ((value: unknown) =&gt; boolean)): Policy&lt;S&gt;</code> — ABAC helper that allows when <code>subject[name]</code> equals <code>match</code>, or when <code>match</code> is a function, when <code>match(value)</code> is truthy.</li>
</ul>
<h4 id="guards-middleware">Guards (middleware)</h4>
<p>Each guard returns a <code>@wrnexus/core</code> <code>Middleware</code>. A denied request short-circuits with <code>Response.json(&#123; ok: false, error: &quot;Forbidden&quot; &#125;, &#123; status: 403 &#125;)</code>.</p>
<ul>
<li><code>authorize(policy: (ctx: Context) =&gt; boolean | Promise&lt;boolean&gt;): Middleware</code> — runs <code>policy</code> against the request <code>Context</code>; calls <code>next()</code> when it resolves truthy, otherwise returns 403.</li>
<li><code>requireRole(...roles: string[]): Middleware</code> — allows when <code>ctx.user</code> holds <strong>any</strong> of the listed roles.</li>
<li><code>requirePermission(rbac: Rbac, permission: string): Middleware</code> — allows when <code>rbac.can(ctx.user, permission)</code> is <code>true</code>.</li>
</ul>
<h3 id="usage">Usage</h3>
<h4 id="rbac-2">RBAC</h4>
<pre data-language="ts"><code>import &#123; defineRbac, hasRole &#125; from &quot;@wrnexus/authz&quot;;

const rbac = defineRbac(&#123;
  admin: [&quot;*&quot;],
  editor: [&quot;post:read&quot;, &quot;post:write&quot;],
  viewer: [&quot;post:read&quot;],
  // role inheritance: lead gets everything an editor has, plus post:publish
  lead: [&quot;role:editor&quot;, &quot;post:publish&quot;],
&#125;);

const user = &#123; id: &quot;u1&quot;, roles: [&quot;editor&quot;] &#125;;

rbac.can(user, &quot;post:write&quot;); // true
rbac.can(user, &quot;post:delete&quot;); // false
rbac.permissionsFor([&quot;lead&quot;]); // Set &#123; &quot;post:read&quot;, &quot;post:write&quot;, &quot;post:publish&quot; &#125;
hasRole(user, &quot;editor&quot;); // true</code></pre>
<h4 id="guarding-routes">Guarding routes</h4>
<pre data-language="ts"><code>import &#123; authorize, requireRole, requirePermission, defineRbac &#125; from &quot;@wrnexus/authz&quot;;

const rbac = defineRbac(&#123; admin: [&quot;*&quot;], editor: [&quot;post:read&quot;, &quot;post:write&quot;] &#125;);

// Only admins or editors
app.get(&quot;/dashboard&quot;, requireRole(&quot;admin&quot;, &quot;editor&quot;), handler);

// Requires a specific permission
app.post(&quot;/posts&quot;, requirePermission(rbac, &quot;post:write&quot;), handler);

// Arbitrary policy over the request context
app.delete(
  &quot;/posts/:id&quot;,
  authorize((ctx) =&gt; hasRole(ctx.user, &quot;admin&quot;)),
  handler,
);</code></pre>
<h4 id="pbac-abac-policies">PBAC / ABAC policies</h4>
<pre data-language="ts"><code>import &#123; any, all, attr, authorize, type Policy &#125; from &quot;@wrnexus/authz&quot;;

interface User &#123;
  id: string;
  department?: string;
  roles?: string[];
&#125;
interface Post &#123;
  authorId: string;
&#125;

// Ownership policy (subject + resource)
const ownsPost: Policy&lt;User, Post&gt; = (u, post) =&gt; u.id === post?.authorId;

// ABAC: attribute equality, or a predicate
const inEngineering = attr&lt;User&gt;(&quot;department&quot;, &quot;engineering&quot;);
const isVerified = attr&lt;User&gt;(&quot;verified&quot;, (v) =&gt; v === true);

// Compose: allow if the user owns the post OR is in engineering AND verified
const canEdit = any(ownsPost, all(inEngineering, isVerified));

app.put(
  &quot;/posts/:id&quot;,
  authorize((ctx) =&gt; canEdit(ctx.user as User, loadPost(ctx))),
  handler,
);</code></pre>
<h3 id="requirements-notes">Requirements / Notes</h3>
<ul>
<li><strong>Bun-only</strong> — like the rest of WRNexusJS, this package targets the Bun runtime; Node is not supported.</li>
<li>Works with [<code>@wrnexus/core</code>](../core) — the guards return <code>Middleware</code> and read the subject from <code>ctx.user</code> on the request <code>Context</code>. Both types are imported from <code>@wrnexus/core</code>.</li>
<li>Policy combinators (<code>any</code>, <code>all</code>) and <code>authorize</code> are async-aware, so policies may return a <code>Promise&lt;boolean&gt;</code> (e.g. for a database ownership check).</li>
</ul></section><section id="api" class="api"><h2>Complete TypeScript API</h2><p>Generated from the exact installed package declarations.</p><pre data-language="typescript"><code>import &#123; Context, Middleware &#125; from '@wrnexus/core';

/**
 * @wrnexus/authz — authorization: role-based (RBAC), policy-based (PBAC), and
 * attribute-based (ABAC). Compose freely; all three reduce to a boolean check
 * plus an `authorize()` guard middleware.
 *
 *   const rbac = defineRbac(&#123; admin: [&quot;*&quot;], editor: [&quot;post:read&quot;, &quot;post:write&quot;] &#125;);
 *   rbac.can(user, &quot;post:write&quot;);
 *
 *   // PBAC/ABAC: a policy is a predicate over subject + resource + attributes
 *   const ownsPost: Policy&lt;User, Post&gt; = (u, post) =&gt; u.id === post.authorId;
 *   authorize((ctx) =&gt; ownsPost(ctx.user, resource))  // middleware
 */

interface Subject &#123;
    id?: string;
    roles?: string[];
    [attribute: string]: unknown;
&#125;
interface Rbac &#123;
    /** True if any of the subject's roles grants `permission` (supports &quot;*&quot; and &quot;ns:*&quot;). */
    can(subject: Subject | undefined, permission: string): boolean;
    /** All permissions granted to a set of roles. */
    permissionsFor(roles: string[]): Set&lt;string&gt;;
&#125;
/** Build an RBAC checker from a role → permissions map. */
declare function defineRbac(roles: Record&lt;string, string[]&gt;): Rbac;
/** True if the subject has ALL of the given roles. */
declare function hasRole(subject: Subject | undefined, ...required: string[]): boolean;
/** A policy predicate: subject (+ optional resource/attributes) → allowed. */
type Policy&lt;S = Subject, R = unknown&gt; = (subject: S, resource?: R) =&gt; boolean | Promise&lt;boolean&gt;;
/** Combine policies: allow if ANY passes (OR). */
declare function any&lt;S, R&gt;(...policies: Policy&lt;S, R&gt;[]): Policy&lt;S, R&gt;;
/** Combine policies: allow only if ALL pass (AND). */
declare function all&lt;S, R&gt;(...policies: Policy&lt;S, R&gt;[]): Policy&lt;S, R&gt;;
/** ABAC helper: allow when an attribute matches (equality or predicate). */
declare function attr&lt;S extends Subject&gt;(name: string, match: unknown | ((value: unknown) =&gt; boolean)): Policy&lt;S&gt;;
/** Guard a route with a policy over `ctx` (reads `ctx.user` as the subject). */
declare function authorize(policy: (ctx: Context) =&gt; boolean | Promise&lt;boolean&gt;): Middleware;
/** Guard requiring one of the given roles. */
declare function requireRole(...roles: string[]): Middleware;
/** Guard requiring an RBAC permission. */
declare function requirePermission(rbac: Rbac, permission: string): Middleware;

export &#123; type Policy, type Rbac, type Subject, all, any, attr, authorize, defineRbac, hasRole, requirePermission, requireRole &#125;;
</code></pre></section><section id="examples" class="examples"><h2>Examples</h2><p>Copy-ready examples from the installed package documentation.</p><div class="example-grid"><article class="example-card"><h3>RBAC</h3><pre data-language="ts"><code>import &#123; defineRbac, hasRole &#125; from &quot;@wrnexus/authz&quot;;

const rbac = defineRbac(&#123;
  admin: [&quot;*&quot;],
  editor: [&quot;post:read&quot;, &quot;post:write&quot;],
  viewer: [&quot;post:read&quot;],
  // role inheritance: lead gets everything an editor has, plus post:publish
  lead: [&quot;role:editor&quot;, &quot;post:publish&quot;],
&#125;);

const user = &#123; id: &quot;u1&quot;, roles: [&quot;editor&quot;] &#125;;

rbac.can(user, &quot;post:write&quot;); // true
rbac.can(user, &quot;post:delete&quot;); // false
rbac.permissionsFor([&quot;lead&quot;]); // Set &#123; &quot;post:read&quot;, &quot;post:write&quot;, &quot;post:publish&quot; &#125;
hasRole(user, &quot;editor&quot;); // true</code></pre></article><article class="example-card"><h3>Guarding routes</h3><pre data-language="ts"><code>import &#123; authorize, requireRole, requirePermission, defineRbac &#125; from &quot;@wrnexus/authz&quot;;

const rbac = defineRbac(&#123; admin: [&quot;*&quot;], editor: [&quot;post:read&quot;, &quot;post:write&quot;] &#125;);

// Only admins or editors
app.get(&quot;/dashboard&quot;, requireRole(&quot;admin&quot;, &quot;editor&quot;), handler);

// Requires a specific permission
app.post(&quot;/posts&quot;, requirePermission(rbac, &quot;post:write&quot;), handler);

// Arbitrary policy over the request context
app.delete(
  &quot;/posts/:id&quot;,
  authorize((ctx) =&gt; hasRole(ctx.user, &quot;admin&quot;)),
  handler,
);</code></pre></article><article class="example-card"><h3>PBAC / ABAC policies</h3><pre data-language="ts"><code>import &#123; any, all, attr, authorize, type Policy &#125; from &quot;@wrnexus/authz&quot;;

interface User &#123;
  id: string;
  department?: string;
  roles?: string[];
&#125;
interface Post &#123;
  authorId: string;
&#125;

// Ownership policy (subject + resource)
const ownsPost: Policy&lt;User, Post&gt; = (u, post) =&gt; u.id === post?.authorId;

// ABAC: attribute equality, or a predicate
const inEngineering = attr&lt;User&gt;(&quot;department&quot;, &quot;engineering&quot;);
const isVerified = attr&lt;User&gt;(&quot;verified&quot;, (v) =&gt; v === true);

// Compose: allow if the user owns the post OR is in engineering AND verified
const canEdit = any(ownsPost, all(inEngineering, isVerified));

app.put(
  &quot;/posts/:id&quot;,
  authorize((ctx) =&gt; canEdit(ctx.user as User, loadPost(ctx))),
  handler,
);</code></pre></article></div></section></article>
      <aside class="on-this-page"><h2>On this page</h2><nav><a class="toc-level-2" href="#guide">Guide</a><a class="toc-level-3" href="#overview">Overview</a><a class="toc-level-3" href="#api">API</a><a class="toc-level-4" href="#types">Types</a><a class="toc-level-4" href="#rbac">RBAC</a><a class="toc-level-4" href="#definerbac-roles-record-string-string-rbac">defineRbac(roles: Record&lt;string, string[]&gt;): Rbac</a><a class="toc-level-4" href="#hasrole-subject-subject-undefined-required-string-boolean">hasRole(subject: Subject | undefined, ...required: string[]): boolean</a><a class="toc-level-4" href="#pbac-abac-combinators">PBAC / ABAC combinators</a><a class="toc-level-4" href="#guards-middleware">Guards (middleware)</a><a class="toc-level-3" href="#usage">Usage</a><a class="toc-level-4" href="#rbac-2">RBAC</a><a class="toc-level-4" href="#guarding-routes">Guarding routes</a><a class="toc-level-4" href="#pbac-abac-policies">PBAC / ABAC policies</a><a class="toc-level-3" href="#requirements-notes">Requirements / Notes</a><a class="toc-level-2" href="#api">Complete API</a><a class="toc-level-2" href="#examples">Examples</a></nav></aside>
    </main>
      <footer><div class="footer-brand"><span class="footer-mark" aria-hidden="true">W</span><p><strong>WRNexusJS 0.3.2</strong><span>Complete API documentation generated from installed package declarations.</span></p></div><nav aria-label="Footer"><a href="/packages">All packages</a><a href="/getting-started">Get started</a><a href="/security">Security</a><a href="/support">Support</a><a href="/llms.txt">AI guide</a></nav><p class="footer-meta">Private Developer Preview · Bun-native</p></footer>
      <BackToTop />
    </div>
  }
}
