@velajs/authz 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+## 1.0.1
+
+### Patch Changes
+
+- 307ff5e: Modernize the package build, validation, and release toolchain.
+
+All notable changes to `@velajs/authz` are documented here. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## 1.0.0
+
+Initial release — the framework-agnostic permission/role engine for Vela.
+
+### Added
+
+- **`Identity` / `PermissionResolver`** — the model at the core. `Identity` is who is asking (all fields optional, so `{}` and `anonymous` are valid zero-privilege identities); `PermissionResolver` is the single seam that resolves an identity to its granted-permission `Set` (sync or async). `anonymous` (`{ roles: [] }`, frozen) is the fail-closed default when no session is present.
+- **`defineRole` / `definePermission`** — declare the role→permission table. `defineRole(name, permissions)` copies the permissions array, so the returned `RoleDef` never aliases the caller's input; `definePermission(name)` names a permission for the optional allow-list.
+- **`createAuthz`** — builds an `Authz` (`{ can, resolver }`) over a role table or a custom `resolver`. Passing a `permissions` allow-list turns typos into a build-time error: `createAuthz` throws when a role grants an **undeclared** (non-wildcard) permission.
+- **Fail-closed `can()` + wildcards** — `can(identity, permission, resolver)` (and the bound `authz.can`) default to **deny**. No session, unknown role, missing permission, or a resolver that **throws** all deny — there is no allow-on-error path. On the **granted** side, `*` grants everything and `resource:*` grants any action under that resource (e.g. `posts:*` grants `posts:delete`).
+- **`anyOf` / `allOf` / `hasPerm` / `mask`** — composition + masking over a `Policy` (a plain predicate over a context and a resource). `anyOf` is OR/read semantics (empty → **denied**); `allOf` is AND/write semantics (empty → vacuously true); `hasPerm(authz, permission)` bridges a capability check into a `Policy` reading only `ctx.identity`; `mask(fn)` wraps a field transform so a throw redacts to `null` instead of leaking the raw value. A policy that throws inside `anyOf`/`allOf` denies that branch — it can never allow.
+- **`@velajs/authz/vela` — `AuthzModule`** — optional Vela integration behind a subpath. Built on `@velajs/vela`'s `defineModule`, `AuthzModule.forRoot(options)` provides an `Authz` instance (`createAuthz(options)`) under the `AUTHZ` token and exports it for other modules to inject. `@velajs/vela` is an **optional** peer dependency — the core engine has no framework coupling.
+
+### Notes
+
+- Zero runtime dependencies; ESM; `sideEffects: false`; edge-runtime safe (no `node:*`, `Buffer`, or `process`).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kauan Guesser
+
+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,119 @@
+# @velajs/authz
+
+Framework-agnostic permission/role engine for Vela: `defineRole`, fail-closed `can()`, composition + masking helpers. **Zero runtime dependencies, edge-runtime safe** (no `node:*`, no `Buffer`, no `process`).
+
+## Why
+
+Authorization is one decision — *"is this identity allowed to do this?"* — that has to be answered identically across HTTP, WebSocket, live queries, and background jobs. This package is that single answer. It resolves an `Identity` to a set of granted permissions and decides `can()` **fail-closed**: absent a session, the [`anonymous`](#identity) zero-privilege identity is used and nothing is granted.
+
+The core is a plain function library — no decorators, no container, no framework coupling. Optional [Vela integration](#vela-integration) lives behind a subpath.
+
+## Install
+
+```sh
+pnpm add @velajs/authz
+```
+
+## Quick start
+
+```ts
+import { createAuthz, defineRole } from '@velajs/authz';
+
+const authz = createAuthz({
+  roles: [
+    defineRole('editor', ['posts:read', 'posts:write']),
+    defineRole('admin', ['*']),
+  ],
+});
+
+await authz.can({ roles: ['editor'] }, 'posts:write'); // true
+await authz.can({ roles: ['editor'] }, 'posts:delete'); // false
+await authz.can({ roles: ['admin'] }, 'anything:at:all'); // true (wildcard)
+```
+
+## The model
+
+- **`Identity`** — who is asking. All fields optional, so `{}` and `anonymous` are valid zero-privilege identities.
+- **`defineRole(name, permissions)` / `definePermission(name)`** — declare the role→permission table. `defineRole` copies the permissions array, so the returned `RoleDef` never aliases the caller's input.
+- **`createAuthz(options)`** — builds an `Authz` over a role table (or a custom `resolver`). Returns `{ can, resolver }`. If you pass a `permissions` allow-list, `createAuthz` throws when a role grants an **undeclared** (non-wildcard) permission — a build-time guard against typos.
+- **`can(identity, permission, resolver)`** — the standalone fail-closed check; `authz.can(identity, permission)` is the same check bound to the built resolver.
+
+```ts
+interface Identity {
+  userId?: string;
+  roles?: string[];
+  claims?: Record<string, unknown>;
+}
+
+interface PermissionResolver {
+  grants(identity: Identity): Set<string> | Promise<Set<string>>;
+}
+```
+
+`anonymous` is the zero-privilege identity (`{ roles: [] }`, frozen) — the fail-closed default when no session is present.
+
+## Wildcards
+
+A granted permission string matches the requested permission when:
+
+- it is `*` — grants **everything**;
+- it equals the requested permission exactly (e.g. `posts:write`);
+- it is `resource:*` — grants **any action** under that resource (e.g. `posts:*` grants `posts:delete`).
+
+Wildcards live on the **granted** side (what a role holds), not the requested side.
+
+## Fail-closed rules
+
+Authorization defaults to **deny**. Every ambiguous or broken path denies rather than leaks:
+
+- No session → use `anonymous` → grants nothing.
+- Unknown role / missing permission → denied.
+- A resolver that **throws** → denied (there is no allow-on-error path).
+- **`anyOf()` with no policies → denied** (nothing grants access).
+- A policy that **throws** inside `anyOf`/`allOf` → that branch is denied; it can never allow.
+- **`mask`** whose transform throws → redacts to `null`, never leaks the raw value.
+
+(`allOf()` with no policies is vacuously `true` — an empty AND — but an empty OR denies.)
+
+## Composition + masking
+
+`Policy` is a plain predicate over a context and a resource:
+
+```ts
+type Policy<C = { identity: Identity }, R = unknown> =
+  (ctx: C, resource: R) => boolean | Promise<boolean>;
+```
+
+Combine capability checks with resource-level rules (ownership, tenancy, state):
+
+- **`anyOf(...policies)`** — OR, read semantics. Any policy granting → allowed. Empty → denied.
+- **`allOf(...policies)`** — AND, write semantics. All must allow.
+- **`hasPerm(authz, permission)`** — bridge a capability check into a `Policy` that reads only `ctx.identity`.
+- **`mask(fn)`** — wrap a field transform so a throw redacts to `null` instead of leaking.
+
+```ts
+import { anyOf, allOf, hasPerm, mask } from '@velajs/authz';
+
+const isOwner = (ctx: { identity: { userId?: string } }, post: { authorId: string }) =>
+  ctx.identity.userId === post.authorId;
+
+// A reader may see a post if they own it OR hold posts:read.
+const canRead = anyOf(isOwner, hasPerm(authz, 'posts:read'));
+
+// A writer must own it AND hold posts:write.
+const canWrite = allOf(isOwner, hasPerm(authz, 'posts:write'));
+
+await canRead({ identity: { userId: 'u1', roles: [] } }, { authorId: 'u1' }); // true
+
+// Redact a sensitive field, fail-closed to null on any error.
+const lastFour = mask((_ctx: unknown, r: { ssn: string }) => r.ssn.slice(-4));
+lastFour({}, { ssn: '123456789' }); // '6789'
+```
+
+## Vela integration
+
+Optional. `@velajs/authz/vela` wires the engine into a Vela app. `@velajs/vela` is an **optional** peer dependency — the core engine has no framework coupling and runs anywhere (edge, Node, Workers, Deno, Bun).
+
+## License
+
+MIT © Kauan Guesser

package/dist/authz-BX3wL_WR.d.ts

@@ -0,0 +1,37 @@
+//#region src/identity.d.ts
+interface Identity {
+  userId?: string;
+  roles?: string[];
+  claims?: Record<string, unknown>;
+}
+/** The zero-privilege identity. Fail-closed default when no session is present. */
+declare const anonymous: Identity;
+interface PermissionResolver {
+  grants(identity: Identity): Set<string> | Promise<Set<string>>;
+}
+//#endregion
+//#region src/roles.d.ts
+interface RoleDef {
+  readonly name: string;
+  readonly permissions: readonly string[];
+}
+interface PermissionDef {
+  readonly name: string;
+}
+declare const defineRole: (name: string, permissions: readonly string[]) => RoleDef;
+declare const definePermission: (name: string) => PermissionDef;
+//#endregion
+//#region src/authz.d.ts
+interface Authz {
+  can(identity: Identity, permission: string): Promise<boolean>;
+  readonly resolver: PermissionResolver;
+}
+interface CreateAuthzOptions {
+  roles?: RoleDef[];
+  permissions?: PermissionDef[];
+  resolver?: PermissionResolver;
+}
+declare const createAuthz: (options?: CreateAuthzOptions) => Authz;
+//#endregion
+export { RoleDef as a, Identity as c, PermissionDef as i, PermissionResolver as l, CreateAuthzOptions as n, definePermission as o, createAuthz as r, defineRole as s, Authz as t, anonymous as u };
+//# sourceMappingURL=authz-BX3wL_WR.d.ts.map

package/dist/authz-DXUrOWVO.js

@@ -0,0 +1,50 @@
+//#region src/can.ts
+/** Does the granted set satisfy `permission`, honoring wildcards? */
+const granted = (grants, permission) => {
+	if (grants.has("*") || grants.has(permission)) return true;
+	const colon = permission.indexOf(":");
+	if (colon > 0 && grants.has(`${permission.slice(0, colon)}:*`)) return true;
+	return false;
+};
+/**
+* The fail-closed capability check. Resolves the identity's granted permissions
+* via the resolver and matches `permission` (exact or wildcard). A resolver
+* that throws denies — there is no allow-on-error path.
+*/
+const can = async (identity, permission, resolver) => {
+	try {
+		const grants = await resolver.grants(identity);
+		return granted(grants, permission);
+	} catch {
+		return false;
+	}
+};
+//#endregion
+//#region src/authz.ts
+const isWildcard = (p) => p === "*" || p.endsWith(":*");
+/** Build a role→permission resolver over a role table (no module globals). */
+const roleResolver = (roles) => {
+	const byRole = /* @__PURE__ */ new Map();
+	for (const r of roles) byRole.set(r.name, r.permissions);
+	return { grants(identity) {
+		const out = /* @__PURE__ */ new Set();
+		for (const name of identity.roles ?? []) for (const perm of byRole.get(name) ?? []) out.add(perm);
+		return out;
+	} };
+};
+const createAuthz = (options = {}) => {
+	const roles = options.roles ?? [];
+	if (options.permissions) {
+		const declared = new Set(options.permissions.map((p) => p.name));
+		for (const role of roles) for (const perm of role.permissions) if (!isWildcard(perm) && !declared.has(perm)) throw new Error(`role '${role.name}' grants undeclared permission '${perm}'`);
+	}
+	const resolver = options.resolver ?? roleResolver(roles);
+	return {
+		resolver,
+		can: (identity, permission) => can(identity, permission, resolver)
+	};
+};
+//#endregion
+export { can as n, createAuthz as t };
+
+//# sourceMappingURL=authz-DXUrOWVO.js.map

package/dist/authz-DXUrOWVO.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authz-DXUrOWVO.js","names":[],"sources":["../src/can.ts","../src/authz.ts"],"sourcesContent":["import type { Identity, PermissionResolver } from './identity';\n\n/** Does the granted set satisfy `permission`, honoring wildcards? */\nconst granted = (grants: Set<string>, permission: string): boolean => {\n  if (grants.has('*') || grants.has(permission)) return true;\n  const colon = permission.indexOf(':');\n  if (colon > 0 && grants.has(`${permission.slice(0, colon)}:*`)) return true;\n  return false;\n};\n\n/**\n * The fail-closed capability check. Resolves the identity's granted permissions\n * via the resolver and matches `permission` (exact or wildcard). A resolver\n * that throws denies — there is no allow-on-error path.\n */\nexport const can = async (\n  identity: Identity,\n  permission: string,\n  resolver: PermissionResolver,\n): Promise<boolean> => {\n  try {\n    const grants = await resolver.grants(identity);\n    return granted(grants, permission);\n  } catch {\n    return false;\n  }\n};\n","import { can } from './can';\nimport type { Identity, PermissionResolver } from './identity';\nimport type { PermissionDef, RoleDef } from './roles';\n\nexport interface Authz {\n  can(identity: Identity, permission: string): Promise<boolean>;\n  readonly resolver: PermissionResolver;\n}\n\nexport interface CreateAuthzOptions {\n  roles?: RoleDef[];\n  permissions?: PermissionDef[];\n  resolver?: PermissionResolver;\n}\n\nconst isWildcard = (p: string): boolean => p === '*' || p.endsWith(':*');\n\n/** Build a role→permission resolver over a role table (no module globals). */\nconst roleResolver = (roles: RoleDef[]): PermissionResolver => {\n  const byRole = new Map<string, readonly string[]>();\n  for (const r of roles) byRole.set(r.name, r.permissions);\n  return {\n    grants(identity: Identity): Set<string> {\n      const out = new Set<string>();\n      for (const name of identity.roles ?? []) {\n        for (const perm of byRole.get(name) ?? []) out.add(perm);\n      }\n      return out;\n    },\n  };\n};\n\nexport const createAuthz = (options: CreateAuthzOptions = {}): Authz => {\n  const roles = options.roles ?? [];\n  if (options.permissions) {\n    const declared = new Set(options.permissions.map((p) => p.name));\n    for (const role of roles) {\n      for (const perm of role.permissions) {\n        if (!isWildcard(perm) && !declared.has(perm)) {\n          throw new Error(`role '${role.name}' grants undeclared permission '${perm}'`);\n        }\n      }\n    }\n  }\n  const resolver = options.resolver ?? roleResolver(roles);\n  return {\n    resolver,\n    can: (identity, permission) => can(identity, permission, resolver),\n  };\n};\n"],"mappings":";;AAGA,MAAM,WAAW,QAAqB,eAAgC;CACpE,IAAI,OAAO,IAAI,GAAG,KAAK,OAAO,IAAI,UAAU,GAAG,OAAO;CACtD,MAAM,QAAQ,WAAW,QAAQ,GAAG;CACpC,IAAI,QAAQ,KAAK,OAAO,IAAI,GAAG,WAAW,MAAM,GAAG,KAAK,EAAE,GAAG,GAAG,OAAO;CACvE,OAAO;AACT;;;;;;AAOA,MAAa,MAAM,OACjB,UACA,YACA,aACqB;CACrB,IAAI;EACF,MAAM,SAAS,MAAM,SAAS,OAAO,QAAQ;EAC7C,OAAO,QAAQ,QAAQ,UAAU;CACnC,QAAQ;EACN,OAAO;CACT;AACF;;;ACXA,MAAM,cAAc,MAAuB,MAAM,OAAO,EAAE,SAAS,IAAI;;AAGvE,MAAM,gBAAgB,UAAyC;CAC7D,MAAM,yBAAS,IAAI,IAA+B;CAClD,KAAK,MAAM,KAAK,OAAO,OAAO,IAAI,EAAE,MAAM,EAAE,WAAW;CACvD,OAAO,EACL,OAAO,UAAiC;EACtC,MAAM,sBAAM,IAAI,IAAY;EAC5B,KAAK,MAAM,QAAQ,SAAS,SAAS,CAAC,GACpC,KAAK,MAAM,QAAQ,OAAO,IAAI,IAAI,KAAK,CAAC,GAAG,IAAI,IAAI,IAAI;EAEzD,OAAO;CACT,EACF;AACF;AAEA,MAAa,eAAe,UAA8B,CAAC,MAAa;CACtE,MAAM,QAAQ,QAAQ,SAAS,CAAC;CAChC,IAAI,QAAQ,aAAa;EACvB,MAAM,WAAW,IAAI,IAAI,QAAQ,YAAY,KAAK,MAAM,EAAE,IAAI,CAAC;EAC/D,KAAK,MAAM,QAAQ,OACjB,KAAK,MAAM,QAAQ,KAAK,aACtB,IAAI,CAAC,WAAW,IAAI,KAAK,CAAC,SAAS,IAAI,IAAI,GACzC,MAAM,IAAI,MAAM,SAAS,KAAK,KAAK,kCAAkC,KAAK,EAAE;CAIpF;CACA,MAAM,WAAW,QAAQ,YAAY,aAAa,KAAK;CACvD,OAAO;EACL;EACA,MAAM,UAAU,eAAe,IAAI,UAAU,YAAY,QAAQ;CACnE;AACF"}

package/dist/index.d.ts

@@ -0,0 +1,30 @@
+import { a as RoleDef, c as Identity, i as PermissionDef, l as PermissionResolver, n as CreateAuthzOptions, o as definePermission, r as createAuthz, s as defineRole, t as Authz, u as anonymous } from "./authz-BX3wL_WR.js";
+//#region src/can.d.ts
+/**
+ * The fail-closed capability check. Resolves the identity's granted permissions
+ * via the resolver and matches `permission` (exact or wildcard). A resolver
+ * that throws denies — there is no allow-on-error path.
+ */
+declare const can: (identity: Identity, permission: string, resolver: PermissionResolver) => Promise<boolean>;
+//#endregion
+//#region src/policy.d.ts
+type Policy<C = {
+  identity: Identity;
+}, R = unknown> = (ctx: C, resource: R) => boolean | Promise<boolean>;
+/** OR — read semantics. Any policy granting → allowed. Empty → denied. */
+declare const anyOf: (...policies: Policy<{
+  identity: Identity;
+}, never>[]) => Policy;
+/** AND — write semantics. All must allow. Empty → allowed (vacuous truth). */
+declare const allOf: (...policies: Policy<{
+  identity: Identity;
+}, never>[]) => Policy;
+/** Bridge a capability check into a Policy reading only ctx.identity. */
+declare const hasPerm: (authz: Authz, permission: string) => Policy<{
+  identity: Identity;
+}>;
+/** Fail-closed field transform: a throwing mask redacts to null, never leaks. */
+declare const mask: <C, R, T>(fn: (ctx: C, record: R) => T) => ((ctx: C, record: R) => T | null);
+//#endregion
+export { type Authz, type CreateAuthzOptions, type Identity, type PermissionDef, type PermissionResolver, type Policy, type RoleDef, allOf, anonymous, anyOf, can, createAuthz, definePermission, defineRole, hasPerm, mask };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,44 @@
+import { n as can, t as createAuthz } from "./authz-DXUrOWVO.js";
+//#region src/identity.ts
+/** The zero-privilege identity. Fail-closed default when no session is present. */
+const anonymous = Object.freeze({ roles: Object.freeze([]) });
+//#endregion
+//#region src/roles.ts
+const defineRole = (name, permissions) => ({
+	name,
+	permissions: [...permissions]
+});
+const definePermission = (name) => ({ name });
+//#endregion
+//#region src/policy.ts
+const runSafe = async (p, ctx, resource) => {
+	try {
+		return await p(ctx, resource) === true;
+	} catch {
+		return false;
+	}
+};
+/** OR — read semantics. Any policy granting → allowed. Empty → denied. */
+const anyOf = (...policies) => async (ctx, resource) => {
+	for (const p of policies) if (await runSafe(p, ctx, resource)) return true;
+	return false;
+};
+/** AND — write semantics. All must allow. Empty → allowed (vacuous truth). */
+const allOf = (...policies) => async (ctx, resource) => {
+	for (const p of policies) if (!await runSafe(p, ctx, resource)) return false;
+	return true;
+};
+/** Bridge a capability check into a Policy reading only ctx.identity. */
+const hasPerm = (authz, permission) => (ctx) => authz.can(ctx.identity, permission);
+/** Fail-closed field transform: a throwing mask redacts to null, never leaks. */
+const mask = (fn) => (ctx, record) => {
+	try {
+		return fn(ctx, record);
+	} catch {
+		return null;
+	}
+};
+//#endregion
+export { allOf, anonymous, anyOf, can, createAuthz, definePermission, defineRole, hasPerm, mask };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/identity.ts","../src/roles.ts","../src/policy.ts"],"sourcesContent":["export interface Identity {\n  userId?: string;\n  roles?: string[];\n  claims?: Record<string, unknown>;\n}\n\n/** The zero-privilege identity. Fail-closed default when no session is present. */\nexport const anonymous: Identity = Object.freeze({\n  roles: Object.freeze([] as string[]) as string[],\n});\n\nexport interface PermissionResolver {\n  grants(identity: Identity): Set<string> | Promise<Set<string>>;\n}\n","export interface RoleDef {\n  readonly name: string;\n  readonly permissions: readonly string[];\n}\nexport interface PermissionDef {\n  readonly name: string;\n}\n\nexport const defineRole = (name: string, permissions: readonly string[]): RoleDef => ({\n  name,\n  permissions: [...permissions],\n});\n\nexport const definePermission = (name: string): PermissionDef => ({ name });\n","import type { Authz } from './authz';\nimport type { Identity } from './identity';\n\nexport type Policy<C = { identity: Identity }, R = unknown> = (\n  ctx: C,\n  resource: R,\n) => boolean | Promise<boolean>;\n\nconst runSafe = async (\n  p: Policy<{ identity: Identity }, never>,\n  ctx: unknown,\n  resource: unknown,\n): Promise<boolean> => {\n  try {\n    return (await (p as Policy<unknown, unknown>)(ctx, resource)) === true;\n  } catch {\n    return false; // a throwing policy never allows\n  }\n};\n\n/** OR — read semantics. Any policy granting → allowed. Empty → denied. */\nexport const anyOf =\n  (...policies: Policy<{ identity: Identity }, never>[]): Policy =>\n  async (ctx, resource) => {\n    for (const p of policies) if (await runSafe(p, ctx, resource)) return true;\n    return false;\n  };\n\n/** AND — write semantics. All must allow. Empty → allowed (vacuous truth). */\nexport const allOf =\n  (...policies: Policy<{ identity: Identity }, never>[]): Policy =>\n  async (ctx, resource) => {\n    for (const p of policies) if (!(await runSafe(p, ctx, resource))) return false;\n    return true;\n  };\n\n/** Bridge a capability check into a Policy reading only ctx.identity. */\nexport const hasPerm =\n  (authz: Authz, permission: string): Policy<{ identity: Identity }> =>\n  (ctx) =>\n    authz.can(ctx.identity, permission);\n\n/** Fail-closed field transform: a throwing mask redacts to null, never leaks. */\nexport const mask =\n  <C, R, T>(fn: (ctx: C, record: R) => T): ((ctx: C, record: R) => T | null) =>\n  (ctx, record) => {\n    try {\n      return fn(ctx, record);\n    } catch {\n      return null;\n    }\n  };\n"],"mappings":";;;AAOA,MAAa,YAAsB,OAAO,OAAO,EAC/C,OAAO,OAAO,OAAO,CAAC,CAAa,EACrC,CAAC;;;ACDD,MAAa,cAAc,MAAc,iBAA6C;CACpF;CACA,aAAa,CAAC,GAAG,WAAW;AAC9B;AAEA,MAAa,oBAAoB,UAAiC,EAAE,KAAK;;;ACLzE,MAAM,UAAU,OACd,GACA,KACA,aACqB;CACrB,IAAI;EACF,OAAQ,MAAO,EAA+B,KAAK,QAAQ,MAAO;CACpE,QAAQ;EACN,OAAO;CACT;AACF;;AAGA,MAAa,SACV,GAAG,aACJ,OAAO,KAAK,aAAa;CACvB,KAAK,MAAM,KAAK,UAAU,IAAI,MAAM,QAAQ,GAAG,KAAK,QAAQ,GAAG,OAAO;CACtE,OAAO;AACT;;AAGF,MAAa,SACV,GAAG,aACJ,OAAO,KAAK,aAAa;CACvB,KAAK,MAAM,KAAK,UAAU,IAAI,CAAE,MAAM,QAAQ,GAAG,KAAK,QAAQ,GAAI,OAAO;CACzE,OAAO;AACT;;AAGF,MAAa,WACV,OAAc,gBACd,QACC,MAAM,IAAI,IAAI,UAAU,UAAU;;AAGtC,MAAa,QACD,QACT,KAAK,WAAW;CACf,IAAI;EACF,OAAO,GAAG,KAAK,MAAM;CACvB,QAAQ;EACN,OAAO;CACT;AACF"}

package/dist/vela/index.d.ts

@@ -0,0 +1,38 @@
+import { n as CreateAuthzOptions, t as Authz } from "../authz-BX3wL_WR.js";
+import { InjectionToken } from "@velajs/vela";
+//#region src/vela/tokens.d.ts
+/**
+ * The auto-provided options bag passed to {@link AuthzModule}.forRoot. Distinct
+ * from {@link AUTHZ} — this token carries the raw {@link CreateAuthzOptions},
+ * the built {@link Authz} instance lives under {@link AUTHZ}.
+ */
+declare const AUTHZ_OPTIONS: InjectionToken<CreateAuthzOptions>;
+/** The built {@link Authz} instance provided and exported by {@link AuthzModule}. */
+declare const AUTHZ: InjectionToken<Authz>;
+//#endregion
+//#region src/vela/authz.module.d.ts
+/**
+ * Built on `@velajs/vela`'s `defineModule` engine (the same pattern as vela's
+ * own `ErrorsModule`). `defineModule` mints the `forRoot`/`forRootAsync`
+ * statics and auto-provides the options bag under {@link AUTHZ_OPTIONS}; `setup`
+ * turns those options into the built {@link AUTHZ} instance and exports it.
+ */
+declare const ConfigurableModuleClass: import("@velajs/vela").ConfigurableModuleClassType<CreateAuthzOptions, "forRoot", "create", {
+  isGlobal?: boolean;
+}>;
+/**
+ * Vela module for `@velajs/authz`. `AuthzModule.forRoot(options)` provides an
+ * {@link Authz} instance (`createAuthz(options)`) under the {@link AUTHZ} token
+ * and exports it for other modules to inject.
+ *
+ * ```ts
+ * @Module({
+ *   imports: [AuthzModule.forRoot({ roles: [defineRole('editor', ['posts:write'])] })],
+ * })
+ * class AppModule {}
+ * ```
+ */
+declare class AuthzModule extends ConfigurableModuleClass {}
+//#endregion
+export { AUTHZ, AUTHZ_OPTIONS, AuthzModule };
+//# sourceMappingURL=index.d.ts.map

package/dist/vela/index.js

@@ -0,0 +1,47 @@
+import { t as createAuthz } from "../authz-DXUrOWVO.js";
+import { InjectionToken, defineModule } from "@velajs/vela";
+//#region src/vela/tokens.ts
+/**
+* The auto-provided options bag passed to {@link AuthzModule}.forRoot. Distinct
+* from {@link AUTHZ} — this token carries the raw {@link CreateAuthzOptions},
+* the built {@link Authz} instance lives under {@link AUTHZ}.
+*/
+const AUTHZ_OPTIONS = new InjectionToken("AUTHZ_OPTIONS");
+/** The built {@link Authz} instance provided and exported by {@link AuthzModule}. */
+const AUTHZ = new InjectionToken("AUTHZ");
+//#endregion
+//#region src/vela/authz.module.ts
+/**
+* Built on `@velajs/vela`'s `defineModule` engine (the same pattern as vela's
+* own `ErrorsModule`). `defineModule` mints the `forRoot`/`forRootAsync`
+* statics and auto-provides the options bag under {@link AUTHZ_OPTIONS}; `setup`
+* turns those options into the built {@link AUTHZ} instance and exports it.
+*/
+const { ConfigurableModuleClass } = defineModule({
+	name: "Authz",
+	optionsToken: AUTHZ_OPTIONS,
+	setup: ({ options }) => ({
+		providers: [{
+			provide: AUTHZ,
+			useValue: createAuthz(options)
+		}],
+		exports: [AUTHZ]
+	})
+});
+/**
+* Vela module for `@velajs/authz`. `AuthzModule.forRoot(options)` provides an
+* {@link Authz} instance (`createAuthz(options)`) under the {@link AUTHZ} token
+* and exports it for other modules to inject.
+*
+* ```ts
+* @Module({
+*   imports: [AuthzModule.forRoot({ roles: [defineRole('editor', ['posts:write'])] })],
+* })
+* class AppModule {}
+* ```
+*/
+var AuthzModule = class extends ConfigurableModuleClass {};
+//#endregion
+export { AUTHZ, AUTHZ_OPTIONS, AuthzModule };
+
+//# sourceMappingURL=index.js.map

package/dist/vela/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/vela/tokens.ts","../../src/vela/authz.module.ts"],"sourcesContent":["import { InjectionToken } from '@velajs/vela';\nimport type { Authz, CreateAuthzOptions } from '../authz';\n\n/**\n * The auto-provided options bag passed to {@link AuthzModule}.forRoot. Distinct\n * from {@link AUTHZ} — this token carries the raw {@link CreateAuthzOptions},\n * the built {@link Authz} instance lives under {@link AUTHZ}.\n */\nexport const AUTHZ_OPTIONS = new InjectionToken<CreateAuthzOptions>('AUTHZ_OPTIONS');\n\n/** The built {@link Authz} instance provided and exported by {@link AuthzModule}. */\nexport const AUTHZ = new InjectionToken<Authz>('AUTHZ');\n","import { defineModule } from '@velajs/vela';\nimport { createAuthz } from '../authz';\nimport type { CreateAuthzOptions } from '../authz';\nimport { AUTHZ, AUTHZ_OPTIONS } from './tokens';\n\n/**\n * Built on `@velajs/vela`'s `defineModule` engine (the same pattern as vela's\n * own `ErrorsModule`). `defineModule` mints the `forRoot`/`forRootAsync`\n * statics and auto-provides the options bag under {@link AUTHZ_OPTIONS}; `setup`\n * turns those options into the built {@link AUTHZ} instance and exports it.\n */\nconst { ConfigurableModuleClass } = defineModule<CreateAuthzOptions>({\n  name: 'Authz',\n  // Reuse the public AUTHZ_OPTIONS token for the auto-provided options bag,\n  // kept DISTINCT from the AUTHZ instance token below.\n  optionsToken: AUTHZ_OPTIONS,\n  setup: ({ options }) => ({\n    providers: [{ provide: AUTHZ, useValue: createAuthz(options) }],\n    exports: [AUTHZ],\n  }),\n});\n\n/**\n * Vela module for `@velajs/authz`. `AuthzModule.forRoot(options)` provides an\n * {@link Authz} instance (`createAuthz(options)`) under the {@link AUTHZ} token\n * and exports it for other modules to inject.\n *\n * ```ts\n * @Module({\n *   imports: [AuthzModule.forRoot({ roles: [defineRole('editor', ['posts:write'])] })],\n * })\n * class AppModule {}\n * ```\n */\nexport class AuthzModule extends ConfigurableModuleClass {}\n"],"mappings":";;;;;;;;AAQA,MAAa,gBAAgB,IAAI,eAAmC,eAAe;;AAGnF,MAAa,QAAQ,IAAI,eAAsB,OAAO;;;;;;;;;ACAtD,MAAM,EAAE,4BAA4B,aAAiC;CACnE,MAAM;CAGN,cAAc;CACd,QAAQ,EAAE,eAAe;EACvB,WAAW,CAAC;GAAE,SAAS;GAAO,UAAU,YAAY,OAAO;EAAE,CAAC;EAC9D,SAAS,CAAC,KAAK;CACjB;AACF,CAAC;;;;;;;;;;;;;AAcD,IAAa,cAAb,cAAiC,wBAAwB,CAAC"}

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@velajs/authz",
+  "version": "1.0.1",
+  "description": "Framework-agnostic permission/role engine for Vela: defineRole, fail-closed can(), composition + masking helpers",
+  "keywords": [
+    "authorization",
+    "authz",
+    "framework",
+    "permissions",
+    "rbac",
+    "vela"
+  ],
+  "homepage": "https://github.com/velajs/authz#readme",
+  "bugs": {
+    "url": "https://github.com/velajs/authz/issues"
+  },
+  "license": "MIT",
+  "author": "ksh",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/velajs/authz.git"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./vela": {
+      "types": "./dist/vela/index.d.ts",
+      "import": "./dist/vela/index.js"
+    }
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@changesets/cli": "^2.31.0",
+    "@velajs/vela": "^1.19.0",
+    "oxfmt": "^0.58.0",
+    "oxlint": "^1.73.0",
+    "publint": "^0.3.21",
+    "tsdown": "^0.22.4",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "peerDependencies": {
+    "@velajs/vela": ">=1.11.0"
+  },
+  "peerDependenciesMeta": {
+    "@velajs/vela": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit -p tsconfig.test.json",
+    "lint": "oxlint .",
+    "format": "oxfmt .",
+    "format:check": "oxfmt --check .",
+    "publint": "publint",
+    "attw": "attw --pack . --profile esm-only",
+    "changeset": "changeset",
+    "version-packages": "changeset version",
+    "release": "pnpm build && changeset publish",
+    "verify": "pnpm lint && pnpm format:check && pnpm build && pnpm typecheck && pnpm test && pnpm publint && pnpm attw"
+  }
+}