@nwire/rbac 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Gefter / 200apps Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,84 @@
+# @nwire/rbac
+
+> Declarative permissions powered by [CASL](https://casl.js.org) — `defineAbility` + middleware + `can()` resolver.
+
+## What it does
+
+Wraps CASL behind a small Nwire surface. `defineAbility((user, { allow, deny }) => {...})` declares what each role can do; `rbacPlugin` auto-enforces tuple `action.policy`; `can("update", "Post")` gates resolvers declaratively; `ctx.ability()` works inside any handler for instance-level checks. Pairs with `@nwire/auth` so `ctx.envelope.user` is the input.
+
+## Install
+
+```bash
+pnpm add @nwire/rbac @nwire/auth
+```
+
+## Quick start
+
+```ts
+import { defineAbility, rbacPlugin, can } from "@nwire/rbac";
+import { identityPlugin } from "@nwire/auth";
+import { defineApp, defineAction } from "@nwire/forge";
+import { httpInterface, post } from "@nwire/http";
+
+export const buildAbility = defineAbility((user, { allow, deny }) => {
+  if (!user) return;
+  if (user.roles?.includes("admin")) {
+    allow("manage", "all");
+    return;
+  }
+  allow("read", "Post");
+  allow("create", "Post");
+  allow("update", "Post", { authorId: user.id });
+  allow("delete", "Post", { authorId: user.id });
+});
+
+defineApp("my-app", {
+  plugins: [identityPlugin({ adapter }), rbacPlugin({ buildAbility })],
+});
+
+httpInterface()
+  .wire(post("/posts/:id", { policy: ["update", "Post"] }), async ({ input }) => {
+    /* ... */
+  })
+  .run();
+```
+
+## API surface
+
+- `defineAbility(setup)` — declare permissions per user.
+- `rbacPlugin({ buildAbility })` — plug into `createApp`.
+- `can(action, subject)` / `cannot(action, subject)` — handler middleware.
+- `abilityFromCtx(ctx)` / `subject(type, obj)` — programmatic checks.
+- `conditionsFor(ability, action, type)` — get Mongo-style conditions for query filters.
+
+## When to use
+
+Any app that needs per-role authorization beyond `action.policy` strings. Fits L3 and up. Pair with `@nwire/auth` so users come from a real IdP.
+
+## Standalone use
+
+For developers using `@nwire/rbac` **without the rest of Nwire** — pair it with any TypeScript project, any container, any HTTP framework.
+
+```ts
+// See the package's main entry (src/) for the standalone surface.
+// The exports below work without @nwire/app or @nwire/forge.
+import {} from /* ...standalone exports... */ "@nwire/rbac";
+```
+
+## Within nwire-app
+
+For developers using this package as part of the Nwire stack — register it via `app.use(...)` or it auto-wires when you compose `createApp({ modules })`.
+
+```ts
+import { createApp } from "@nwire/forge";
+
+const app = createApp({
+  /* ...config... */
+});
+// Adapter/plugin wiring happens here when applicable.
+```
+
+## See also
+
+- [Architecture sketch §05 — Adapters tier](../../architecture-sketch.html#packages)
+- Sibling packages: [@nwire/auth](../nwire-auth), [@nwire/auth-better-auth](../nwire-auth-better-auth), [@nwire/auth-logto](../nwire-auth-logto)

package/dist/__tests__/polish.test.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Tests for the Phase 62.5 polish layer:
+ *   - typed permission strings (autocomplete-friendly)
+ *   - composable resolvers (.or, .and, .not, ownedBy, sameTenant)
+ *   - structured errors (OwnershipMismatchError, ScopeMissingError, ...)
+ *   - conditionsFor (CASL rulesToQuery surface)
+ */
+export {};
+//# sourceMappingURL=polish.test.d.ts.map

package/dist/__tests__/polish.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"polish.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/polish.test.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/__tests__/polish.test.js

@@ -0,0 +1,130 @@
+/**
+ * Tests for the Phase 62.5 polish layer:
+ *   - typed permission strings (autocomplete-friendly)
+ *   - composable resolvers (.or, .and, .not, ownedBy, sameTenant)
+ *   - structured errors (OwnershipMismatchError, ScopeMissingError, ...)
+ *   - conditionsFor (CASL rulesToQuery surface)
+ */
+import { describe, it, expect } from "vitest";
+import { permission, parsePermission, resolver, ownedBy, sameTenant, authorize, conditionsFor, defineAbility, ActionDeniedError, OwnershipMismatchError, RoleMissingError, isOwnershipMismatchError, } from "../rbac";
+describe("permission() — typed strings", () => {
+    it("produces resource:action format", () => {
+        expect(permission("update", "Post")).toBe("update:Post");
+    });
+    it("parses back to a tuple", () => {
+        expect(parsePermission("update:Post")).toEqual(["update", "Post"]);
+    });
+});
+describe("resolver — composable predicates", () => {
+    const alice = { id: "u-a", email: "a@x" };
+    const bob = { id: "u-b", email: "b@x" };
+    it("base predicate works", async () => {
+        const isOwner = resolver((u, p) => u.id === p.authorId);
+        expect(await isOwner(alice, { id: "1", authorId: alice.id })).toBe(true);
+        expect(await isOwner(alice, { id: "1", authorId: bob.id })).toBe(false);
+    });
+    it(".or combines with disjunction", async () => {
+        const isOwner = resolver((u, p) => u.id === p.authorId);
+        const isAdmin = resolver((u) => u.roles?.includes("admin") ?? false);
+        const canEdit = isOwner.or(isAdmin);
+        const admin = { id: "u-x", email: "x@x", roles: ["admin"] };
+        expect(await canEdit(alice, { id: "1", authorId: bob.id })).toBe(false);
+        expect(await canEdit(admin, { id: "1", authorId: bob.id })).toBe(true);
+    });
+    it(".and combines with conjunction", async () => {
+        const isOwner = resolver((u, p) => u.id === p.authorId);
+        const inTeam = resolver((u, p) => Boolean(p.teamId) && u.tenant === p.teamId);
+        const both = isOwner.and(inTeam);
+        const alice2 = { ...alice, tenant: "t-1" };
+        expect(await both(alice2, { id: "1", authorId: alice.id, teamId: "t-1" })).toBe(true);
+        expect(await both(alice2, { id: "1", authorId: alice.id, teamId: "t-2" })).toBe(false);
+        expect(await both(alice2, { id: "1", authorId: bob.id, teamId: "t-1" })).toBe(false);
+    });
+    it(".not negates the predicate", async () => {
+        const isOwner = resolver((u, p) => u.id === p.authorId);
+        const isNotOwner = isOwner.not();
+        expect(await isNotOwner(alice, { id: "1", authorId: bob.id })).toBe(true);
+        expect(await isNotOwner(alice, { id: "1", authorId: alice.id })).toBe(false);
+    });
+    it("ownedBy shorthand reads from configurable field", async () => {
+        const own = ownedBy("authorId");
+        expect(await own(alice, { id: "1", authorId: alice.id })).toBe(true);
+        expect(await own(alice, { id: "1", authorId: bob.id })).toBe(false);
+    });
+    it("sameTenant shorthand reads tenant/tenantId", async () => {
+        const same = sameTenant();
+        const u = { id: "u", email: "u@x", tenant: "t-1" };
+        expect(await same(u, { tenantId: "t-1" })).toBe(true);
+        expect(await same(u, { tenantId: "t-2" })).toBe(false);
+    });
+    it("authorize() throws OwnershipMismatchError when rule denies", async () => {
+        const own = ownedBy();
+        await expect(authorize(alice, "update", { authorId: bob.id }, own, { subjectName: "Post" })).rejects.toBeInstanceOf(OwnershipMismatchError);
+    });
+    it("authorize() throws for null user", async () => {
+        const own = ownedBy();
+        await expect(authorize(null, "update", { authorId: "x" }, own)).rejects.toBeInstanceOf(OwnershipMismatchError);
+    });
+    it("authorize() resolves when rule allows", async () => {
+        const own = ownedBy();
+        await expect(authorize(alice, "update", { authorId: alice.id }, own)).resolves.toBeUndefined();
+    });
+});
+describe("structured errors", () => {
+    it("ActionDeniedError carries action + subject + reason", () => {
+        const e = new ActionDeniedError({ action: "delete", subject: "Post", userId: "u" });
+        expect(e.action).toBe("delete");
+        expect(e.subject).toBe("Post");
+        expect(e.denialReason).toBe("denied");
+        expect(e.message).toMatch(/delete Post/);
+    });
+    it("OwnershipMismatchError narrows denialReason", () => {
+        const e = new OwnershipMismatchError({ action: "edit", subject: "Post" });
+        expect(e.denialReason).toBe("ownership-mismatch");
+        expect(isOwnershipMismatchError(e)).toBe(true);
+    });
+    it("RoleMissingError carries the required role", () => {
+        const e = new RoleMissingError({ action: "view", subject: "Admin", requiredRole: "admin" });
+        expect(e.requiredRole).toBe("admin");
+        expect(e.denialReason).toBe("role-missing");
+    });
+    it("all subclasses are catchable as ActionDeniedError", () => {
+        const e = new OwnershipMismatchError({ action: "x", subject: "Y" });
+        expect(e instanceof ActionDeniedError).toBe(true);
+    });
+});
+describe("conditionsFor — CASL rulesToQuery surface", () => {
+    const buildAbility = defineAbility((user, { allow }) => {
+        if (!user)
+            return;
+        if (user.roles?.includes("admin")) {
+            allow("manage", "all");
+            return;
+        }
+        allow("read", "Post");
+        allow("update", "Post", { authorId: user.id });
+    });
+    it("returns an empty object when an unrestricted rule allows", () => {
+        // CASL's rulesToQuery returns `{}` (no conditions) when ANY rule
+        // is unrestricted — i.e. the user may read every row.
+        const ability = buildAbility({ id: "alice", email: "a@x" });
+        const q = conditionsFor(ability, "read", "Post");
+        expect(q).toEqual({});
+    });
+    it("returns conditional query when only some rows allowed", () => {
+        const ability = buildAbility({ id: "alice", email: "a@x" });
+        const q = conditionsFor(ability, "update", "Post");
+        expect(q).toEqual({ $or: [{ authorId: "alice" }] });
+    });
+    it("returns null when no rules allow", () => {
+        const ability = buildAbility(null);
+        const q = conditionsFor(ability, "read", "Post");
+        expect(q).toBeNull();
+    });
+    it("admin gets unrestricted query via manage:all", () => {
+        const ability = buildAbility({ id: "x", email: "x@x", roles: ["admin"] });
+        const q = conditionsFor(ability, "delete", "Post");
+        expect(q).toEqual({});
+    });
+});
+//# sourceMappingURL=polish.test.js.map

package/dist/__tests__/polish.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"polish.test.js","sourceRoot":"","sources":["../../src/__tests__/polish.test.ts"],"names":[],"mappings":"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"}

package/dist/__tests__/rbac.test.d.ts

@@ -0,0 +1,15 @@
+/**
+ * RBAC integration — proves CASL is wired correctly through the framework:
+ *
+ *   - `defineAbility` builds an Ability factory.
+ *   - `rbacPlugin` registers it + installs dispatch middleware.
+ *   - Actions with tuple `policy: [verb, subject]` get auto-enforced.
+ *   - Programmatic `abilityFromCtx(ctx)` works inside handlers.
+ *   - `subject(name, instance)` lets us check instance-level conditions.
+ *
+ * The Koa per-route gate (`canKoa`) has its own end-to-end coverage in
+ * @nwire/auth's `routes.test.ts` — the http builder lifts the container
+ * onto `ctx.state._container` so `canKoa` can resolve `buildAbility`.
+ */
+export {};
+//# sourceMappingURL=rbac.test.d.ts.map

package/dist/__tests__/rbac.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rbac.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/rbac.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG"}

package/dist/__tests__/rbac.test.js

@@ -0,0 +1,139 @@
+/**
+ * RBAC integration — proves CASL is wired correctly through the framework:
+ *
+ *   - `defineAbility` builds an Ability factory.
+ *   - `rbacPlugin` registers it + installs dispatch middleware.
+ *   - Actions with tuple `policy: [verb, subject]` get auto-enforced.
+ *   - Programmatic `abilityFromCtx(ctx)` works inside handlers.
+ *   - `subject(name, instance)` lets us check instance-level conditions.
+ *
+ * The Koa per-route gate (`canKoa`) has its own end-to-end coverage in
+ * @nwire/auth's `routes.test.ts` — the http builder lifts the container
+ * onto `ctx.state._container` so `canKoa` can resolve `buildAbility`.
+ */
+import { describe, it, expect } from "vitest";
+import { z } from "zod";
+import { createApp, defineAction, defineHandler, defineModule, seedEnvelope, } from "@nwire/forge";
+import { ForbiddenError } from "@nwire/auth";
+import { defineAbility, rbacPlugin, abilityFor, abilityFromCtx, subject, } from "../rbac";
+// ─── Shared fixtures ─────────────────────────────────────────────
+const buildAbility = defineAbility((user, { allow }) => {
+    if (!user)
+        return; // anonymous: nothing allowed
+    if (user.roles?.includes("admin")) {
+        allow("manage", "all");
+        return;
+    }
+    allow("read", "Post");
+    allow("create", "Post");
+    allow("update", "Post", { authorId: user.id });
+    allow("delete", "Post", { authorId: user.id });
+});
+const admin = { id: "u-admin", email: "a@x", roles: ["admin"] };
+const alice = { id: "u-alice", email: "alice@x" };
+const bob = { id: "u-bob", email: "bob@x" };
+describe("@nwire/rbac — pure ability layer", () => {
+    it("anonymous user gets no permissions", () => {
+        const a = abilityFor(buildAbility, null);
+        expect(a.can("read", "Post")).toBe(false);
+    });
+    it("admin can manage all subjects", () => {
+        const a = abilityFor(buildAbility, admin);
+        expect(a.can("delete", "Post")).toBe(true);
+        expect(a.can("manage", "Anything")).toBe(true);
+    });
+    it("author can update their own posts but not someone else's", () => {
+        const a = abilityFor(buildAbility, alice);
+        expect(a.can("create", "Post")).toBe(true);
+        const alicesPost = subject("Post", { id: "p1", authorId: alice.id });
+        const bobsPost = subject("Post", { id: "p2", authorId: bob.id });
+        expect(a.can("update", alicesPost)).toBe(true);
+        expect(a.can("update", bobsPost)).toBe(false);
+        expect(a.cannot("delete", bobsPost)).toBe(true);
+    });
+});
+// ─── Plugin integration ──────────────────────────────────────────
+const empty = defineModule("empty", {});
+describe("@nwire/rbac — rbacPlugin enforces action.policy", () => {
+    it("allows action when user has the ability", async () => {
+        const created = defineAction({
+            name: "posts.create",
+            schema: z.object({ title: z.string() }),
+            policy: ["create", "Post"],
+        });
+        const createdHandler = defineHandler(created, async () => undefined);
+        const m = defineModule("posts", { actions: [created], handlers: [createdHandler] });
+        const app = createApp({
+            modules: [m],
+            plugins: [rbacPlugin({ buildAbility })],
+        });
+        await app.start();
+        // alice has create-Post permission → resolves
+        await expect(app.runtime.dispatch(created, { title: "hello" }, seedEnvelope({ user: alice, userId: alice.id }))).resolves.not.toThrow();
+        await app.stop();
+    });
+    it("denies action when user lacks the ability", async () => {
+        const deleted = defineAction({
+            name: "posts.delete",
+            schema: z.object({ id: z.string() }),
+            policy: ["delete", "Post"],
+        });
+        const deletedHandler = defineHandler(deleted, async () => undefined);
+        const m = defineModule("posts", { actions: [deleted], handlers: [deletedHandler] });
+        const app = createApp({
+            modules: [m],
+            plugins: [rbacPlugin({ buildAbility })],
+        });
+        await app.start();
+        // anonymous has no permissions → throws ForbiddenError
+        await expect(app.runtime.dispatch(deleted, { id: "p1" })).rejects.toThrow(ForbiddenError);
+        await app.stop();
+    });
+    it("allows action when policy is omitted entirely", async () => {
+        const open = defineAction({
+            name: "posts.list",
+            schema: z.object({}),
+        });
+        const openHandler = defineHandler(open, async () => undefined);
+        const m = defineModule("posts", { actions: [open], handlers: [openHandler] });
+        const app = createApp({
+            modules: [m],
+            plugins: [rbacPlugin({ buildAbility })],
+        });
+        await app.start();
+        // anonymous + no policy → allowed
+        await expect(app.runtime.dispatch(open, {})).resolves.not.toThrow();
+        await app.stop();
+    });
+});
+// ─── Programmatic ctx.ability access ─────────────────────────────
+describe("@nwire/rbac — abilityFromCtx for programmatic checks", () => {
+    it("handler can call abilityFromCtx and check an instance with subject()", async () => {
+        let observed = {};
+        const inspect = defineAction({
+            name: "posts.inspect",
+            schema: z.object({ postId: z.string() }),
+        });
+        const inspectHandler = defineHandler(inspect, async (_input, ctx) => {
+            const ability = abilityFromCtx(ctx);
+            const alicesPost = subject("Post", { id: "p1", authorId: alice.id });
+            const bobsPost = subject("Post", { id: "p2", authorId: bob.id });
+            observed = {
+                canUpdateAlices: ability.can("update", alicesPost),
+                canUpdateBobs: ability.can("update", bobsPost),
+            };
+            return undefined;
+        });
+        const m = defineModule("posts", { actions: [inspect], handlers: [inspectHandler] });
+        const app = createApp({
+            modules: [m],
+            plugins: [rbacPlugin({ buildAbility })],
+        });
+        await app.start();
+        await app.runtime.dispatch(inspect, { postId: "p1" }, seedEnvelope({ user: alice, userId: alice.id }));
+        expect(observed.canUpdateAlices).toBe(true);
+        expect(observed.canUpdateBobs).toBe(false);
+        await app.stop();
+    });
+});
+//# sourceMappingURL=rbac.test.js.map

package/dist/__tests__/rbac.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rbac.test.js","sourceRoot":"","sources":["../../src/__tests__/rbac.test.ts"],"names":[],"mappings":"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"}

package/dist/errors.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Structured permission errors — the synthesis's "Why behind the No".
+ *
+ * Generic `Forbidden` is fine for a 403, but tells the UI nothing about
+ * WHY. With structured errors the API can surface "you don't own this
+ * post" vs "your plan doesn't allow this" vs "your role lacks the
+ * permission" — much better UX than a flat "denied".
+ *
+ *   try {
+ *     await authorize(user, "delete", post);
+ *   } catch (e) {
+ *     if (e instanceof OwnershipMismatchError) showOwnerNotice();
+ *     else if (e instanceof RoleMissingError) showRoleNotice(e.requiredRole);
+ *     else throw e;
+ *   }
+ *
+ * All extend `ActionDeniedError` so a single catch handles them uniformly
+ * when the UI doesn't care about the reason.
+ */
+import { ForbiddenError } from "@nwire/auth";
+export interface ActionDeniedFields {
+    readonly action: string;
+    readonly subject: string;
+    readonly userId?: string;
+    readonly reason?: string;
+}
+/** Discriminator field on subclasses; lets `switch (e.denialReason)` work. */
+export type DenialReason = "denied" | "ownership-mismatch" | "scope-missing" | "role-missing";
+/**
+ * The base — every permission denial extends this so a single
+ * `catch (e instanceof ActionDeniedError)` works uniformly. The parent
+ * `ForbiddenError` keeps its `$kind: "auth.forbidden"` (HTTP 403); we
+ * add `denialReason` so subclasses can narrow without conflicting.
+ */
+export declare class ActionDeniedError extends ForbiddenError {
+    readonly denialReason: DenialReason;
+    readonly action: string;
+    readonly subject: string;
+    readonly userId?: string;
+    readonly reason?: string;
+    constructor(fields: ActionDeniedFields);
+}
+/**
+ * Specialized — the user has the right role/scope but isn't related to
+ * the instance (e.g., not the owner of this Post). UI hint: "this is
+ * someone else's resource."
+ */
+export declare class OwnershipMismatchError extends ActionDeniedError {
+    readonly denialReason: "ownership-mismatch";
+    readonly expectedOwnerId?: string;
+    constructor(fields: ActionDeniedFields & {
+        readonly expectedOwnerId?: string;
+    });
+}
+/**
+ * Specialized — the user lacks the required scope (OAuth-style fine-
+ * grained capability). UI hint: "your app integration needs to request
+ * this scope".
+ */
+export declare class ScopeMissingError extends ActionDeniedError {
+    readonly denialReason: "scope-missing";
+    readonly requiredScope: string;
+    constructor(fields: ActionDeniedFields & {
+        readonly requiredScope: string;
+    });
+}
+/**
+ * Specialized — the user lacks the required role (RBAC). UI hint:
+ * "ask your admin to elevate your role".
+ */
+export declare class RoleMissingError extends ActionDeniedError {
+    readonly denialReason: "role-missing";
+    readonly requiredRole: string;
+    constructor(fields: ActionDeniedFields & {
+        readonly requiredRole: string;
+    });
+}
+export declare const isOwnershipMismatchError: (x: unknown) => x is OwnershipMismatchError;
+export declare const isScopeMissingError: (x: unknown) => x is ScopeMissingError;
+export declare const isRoleMissingError: (x: unknown) => x is RoleMissingError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAG,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,8EAA8E;AAC9E,MAAM,MAAM,YAAY,GACpB,QAAQ,GACR,oBAAoB,GACpB,eAAe,GACf,cAAc,CAAC;AAEnB;;;;;GAKG;AACH,qBAAa,iBAAkB,SAAQ,cAAc;IACnD,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAY;IAC/C,QAAQ,CAAC,MAAM,EAAG,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;gBAEb,MAAM,EAAE,kBAAkB;CAQvC;AAED;;;;GAIG;AACH,qBAAa,sBAAuB,SAAQ,iBAAiB;IAC3D,SAAkB,YAAY,EAAG,oBAAoB,CAAU;IAC/D,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;gBACtB,MAAM,EAAE,kBAAkB,GAAG;QAAE,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;KAAE;CAK/E;AAED;;;;GAIG;AACH,qBAAa,iBAAkB,SAAQ,iBAAiB;IACtD,SAAkB,YAAY,EAAG,eAAe,CAAU;IAC1D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;gBACnB,MAAM,EAAE,kBAAkB,GAAG;QAAE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;KAAE;CAK5E;AAED;;;GAGG;AACH,qBAAa,gBAAiB,SAAQ,iBAAiB;IACrD,SAAkB,YAAY,EAAG,cAAc,CAAU;IACzD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;gBAClB,MAAM,EAAE,kBAAkB,GAAG;QAAE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;KAAE;CAK3E;AAED,eAAO,MAAM,wBAAwB,GAAI,GAAG,OAAO,KAAG,CAAC,IAAI,sBACtB,CAAC;AACtC,eAAO,MAAM,mBAAmB,GAAI,GAAG,OAAO,KAAG,CAAC,IAAI,iBACtB,CAAC;AACjC,eAAO,MAAM,kBAAkB,GAAI,GAAG,OAAO,KAAG,CAAC,IAAI,gBACtB,CAAC"}

package/dist/errors.js

@@ -0,0 +1,86 @@
+/**
+ * Structured permission errors — the synthesis's "Why behind the No".
+ *
+ * Generic `Forbidden` is fine for a 403, but tells the UI nothing about
+ * WHY. With structured errors the API can surface "you don't own this
+ * post" vs "your plan doesn't allow this" vs "your role lacks the
+ * permission" — much better UX than a flat "denied".
+ *
+ *   try {
+ *     await authorize(user, "delete", post);
+ *   } catch (e) {
+ *     if (e instanceof OwnershipMismatchError) showOwnerNotice();
+ *     else if (e instanceof RoleMissingError) showRoleNotice(e.requiredRole);
+ *     else throw e;
+ *   }
+ *
+ * All extend `ActionDeniedError` so a single catch handles them uniformly
+ * when the UI doesn't care about the reason.
+ */
+import { ForbiddenError } from "@nwire/auth";
+/**
+ * The base — every permission denial extends this so a single
+ * `catch (e instanceof ActionDeniedError)` works uniformly. The parent
+ * `ForbiddenError` keeps its `$kind: "auth.forbidden"` (HTTP 403); we
+ * add `denialReason` so subclasses can narrow without conflicting.
+ */
+export class ActionDeniedError extends ForbiddenError {
+    denialReason = "denied";
+    action;
+    subject;
+    userId;
+    reason;
+    constructor(fields) {
+        super(fields.reason ?? `Not allowed to ${fields.action} ${fields.subject}`);
+        this.name = "ActionDeniedError";
+        this.action = fields.action;
+        this.subject = fields.subject;
+        this.userId = fields.userId;
+        this.reason = fields.reason;
+    }
+}
+/**
+ * Specialized — the user has the right role/scope but isn't related to
+ * the instance (e.g., not the owner of this Post). UI hint: "this is
+ * someone else's resource."
+ */
+export class OwnershipMismatchError extends ActionDeniedError {
+    denialReason = "ownership-mismatch";
+    expectedOwnerId;
+    constructor(fields) {
+        super({ ...fields, reason: fields.reason ?? "Not the owner of this resource" });
+        this.name = "OwnershipMismatchError";
+        this.expectedOwnerId = fields.expectedOwnerId;
+    }
+}
+/**
+ * Specialized — the user lacks the required scope (OAuth-style fine-
+ * grained capability). UI hint: "your app integration needs to request
+ * this scope".
+ */
+export class ScopeMissingError extends ActionDeniedError {
+    denialReason = "scope-missing";
+    requiredScope;
+    constructor(fields) {
+        super({ ...fields, reason: fields.reason ?? `Missing scope: ${fields.requiredScope}` });
+        this.name = "ScopeMissingError";
+        this.requiredScope = fields.requiredScope;
+    }
+}
+/**
+ * Specialized — the user lacks the required role (RBAC). UI hint:
+ * "ask your admin to elevate your role".
+ */
+export class RoleMissingError extends ActionDeniedError {
+    denialReason = "role-missing";
+    requiredRole;
+    constructor(fields) {
+        super({ ...fields, reason: fields.reason ?? `Missing role: ${fields.requiredRole}` });
+        this.name = "RoleMissingError";
+        this.requiredRole = fields.requiredRole;
+    }
+}
+export const isOwnershipMismatchError = (x) => x instanceof OwnershipMismatchError;
+export const isScopeMissingError = (x) => x instanceof ScopeMissingError;
+export const isRoleMissingError = (x) => x instanceof RoleMissingError;
+//# sourceMappingURL=errors.js.map

package/dist/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAgB7C;;;;;GAKG;AACH,MAAM,OAAO,iBAAkB,SAAQ,cAAc;IAC1C,YAAY,GAAiB,QAAQ,CAAC;IACtC,MAAM,CAAU;IAChB,OAAO,CAAS;IAChB,MAAM,CAAU;IAChB,MAAM,CAAU;IAEzB,YAAY,MAA0B;QACpC,KAAK,CAAC,MAAM,CAAC,MAAM,IAAI,kBAAkB,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;QAC5E,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,MAAM,GAAI,MAAM,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QAC9B,IAAI,CAAC,MAAM,GAAI,MAAM,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,MAAM,GAAI,MAAM,CAAC,MAAM,CAAC;IAC/B,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,sBAAuB,SAAQ,iBAAiB;IACzC,YAAY,GAAG,oBAA6B,CAAC;IACtD,eAAe,CAAU;IAClC,YAAY,MAAkE;QAC5E,KAAK,CAAC,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,gCAAgC,EAAE,CAAC,CAAC;QAChF,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,IAAI,CAAC,eAAe,GAAG,MAAM,CAAC,eAAe,CAAC;IAChD,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,iBAAkB,SAAQ,iBAAiB;IACpC,YAAY,GAAG,eAAwB,CAAC;IACjD,aAAa,CAAS;IAC/B,YAAY,MAA+D;QACzE,KAAK,CAAC,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,kBAAkB,MAAM,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC;QACxF,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,IAAI,CAAC,aAAa,GAAG,MAAM,CAAC,aAAa,CAAC;IAC5C,CAAC;CACF;AAED;;;GAGG;AACH,MAAM,OAAO,gBAAiB,SAAQ,iBAAiB;IACnC,YAAY,GAAG,cAAuB,CAAC;IAChD,YAAY,CAAS;IAC9B,YAAY,MAA8D;QACxE,KAAK,CAAC,EAAE,GAAG,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,iBAAiB,MAAM,CAAC,YAAY,EAAE,EAAE,CAAC,CAAC;QACtF,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC,YAAY,CAAC;IAC1C,CAAC;CACF;AAED,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,CAAU,EAA+B,EAAE,CAClF,CAAC,YAAY,sBAAsB,CAAC;AACtC,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,CAAU,EAA0B,EAAE,CACxE,CAAC,YAAY,iBAAiB,CAAC;AACjC,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAU,EAAyB,EAAE,CACtE,CAAC,YAAY,gBAAgB,CAAC"}