@dudousxd/nestjs-authz 0.2.0

package/dist/tokens.js

@@ -0,0 +1,31 @@
+/** Injection token holding the resolved {@link AuthzModuleOptions}. */
+export const AUTHZ_MODULE_OPTIONS = Symbol.for('@dudousxd/nestjs-authz:options');
+/** Injection token for the optional {@link ResourceResolver} registered by the app. */
+export const RESOURCE_RESOLVER = Symbol.for('@dudousxd/nestjs-authz:resource-resolver');
+/** Metadata key for `@Policy(Resource)` — stores the resource class on the policy. */
+export const POLICY_RESOURCE_METADATA = 'nestjs-authz:policy-resource';
+/** Metadata key for `@Can(ability, Resource?)` — stores the ability descriptor on a route. */
+export const CAN_METADATA = 'nestjs-authz:can';
+/**
+ * Cross-lib injection token for an optional {@link PermissionProvider} — the seam the
+ * RBAC adapter (`@dudousxd/nestjs-authz-typeorm`) registers so that a model-less,
+ * named ability (`gate.allows('posts.publish')`) is granted when the current user
+ * holds that persisted permission. This is the Laravel/spatie `Gate::before` grant.
+ *
+ * `Symbol.for(key)` uses the global symbol registry so an RBAC package registering
+ * this same key resolves to the SAME symbol instance without importing core internals.
+ * The token is consulted with `@Optional()` — when absent, the Gate behaves exactly
+ * as before (backward-compatible: unknown abilities still throw).
+ */
+export const PERMISSION_PROVIDER = Symbol.for('@dudousxd/nestjs-authz:permission-provider');
+/**
+ * Cross-lib injection token for the current-request context accessor, owned by
+ * `@dudousxd/nestjs-context`. We do NOT import nestjs-context — instead we share
+ * its well-known token by value so DI resolves the same provider when present.
+ *
+ * `Symbol.for(key)` uses the global symbol registry, so this resolves to the
+ * SAME symbol instance as nestjs-context's `tokens.ts` without any import.
+ * The key MUST stay byte-identical with nestjs-context's export.
+ */
+export const CONTEXT_ACCESSOR = Symbol.for('@dudousxd/nestjs-context:accessor');
+//# sourceMappingURL=tokens.js.map

package/dist/tokens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.js","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,MAAM,CAAC,MAAM,oBAAoB,GAAG,MAAM,CAAC,GAAG,CAAC,gCAAgC,CAAC,CAAC;AAEjF,uFAAuF;AACvF,MAAM,CAAC,MAAM,iBAAiB,GAAG,MAAM,CAAC,GAAG,CAAC,0CAA0C,CAAC,CAAC;AAExF,sFAAsF;AACtF,MAAM,CAAC,MAAM,wBAAwB,GAAG,8BAA8B,CAAC;AAEvE,8FAA8F;AAC9F,MAAM,CAAC,MAAM,YAAY,GAAG,kBAAkB,CAAC;AAE/C;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC,GAAG,CAAC,4CAA4C,CAAC,CAAC;AAE5F;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAC,GAAG,CAAC,mCAAmC,CAAC,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,97 @@
+import type { Type } from '@nestjs/common';
+import type { UserRef } from './context-accessor.js';
+import type { ResourceResolver } from './resource-resolver.js';
+/**
+ * A resource instance passed to policy methods. `unknown` because authz never
+ * inspects the resource itself — the policy method does.
+ */
+export type Resource = object;
+/**
+ * The current user as seen by a policy/gate. authz does not model the user; it
+ * is whatever the app's auth layer produced (or `undefined` when unauthenticated).
+ */
+export type User = unknown;
+/**
+ * A policy method: decides a single ability for a `(user, resource?)` pair.
+ * Class-level abilities (e.g. `create`) omit the resource. May be async.
+ */
+export type PolicyMethod = (user: User, resource?: Resource) => boolean | Promise<boolean>;
+/**
+ * Optional per-policy `before` hook. Runs before the ability method.
+ * - return `true`  → allow (short-circuit)
+ * - return `false` → deny (short-circuit)
+ * - return `void`/`undefined` → fall through to the ability method
+ */
+export type PolicyBeforeHook = (user: User, ability: string) => boolean | undefined | Promise<boolean | undefined>;
+/** A policy instance is an arbitrary object whose methods are abilities. */
+export type PolicyInstance = Record<string, unknown> & {
+    before?: PolicyBeforeHook;
+};
+/**
+ * An ad-hoc gate: a model-less ability resolved by name via `gate.define`.
+ */
+export type GateFn = (user: User, resource?: Resource) => boolean | Promise<boolean>;
+/**
+ * Global super-admin before-hook. Runs before any policy/gate; truthy → allow.
+ * `void`/`undefined`/`false` falls through to normal resolution.
+ */
+export type SuperAdminHook = (user: User, ability: string) => boolean | undefined | Promise<boolean | undefined>;
+export interface AuthzModuleOptions {
+    /**
+     * Policy classes to register explicitly. Each must be decorated with
+     * `@Policy(Resource)`. Auto-discovery of `@Policy` providers also works, so
+     * this is optional.
+     */
+    policies?: Array<Type<PolicyInstance>>;
+    /**
+     * Global super-admin before-hook applied to every authorization check. Return
+     * `true` to grant (e.g. super-admins). Returning `void`/`false` falls through.
+     *
+     * ⚠️ IMPORTANT — what `user` is: on the **context path** (no `forUser`), the
+     * `user` passed here is the raw {@link UserRef} from nestjs-context — just
+     * `{ type, id }`, NOT your hydrated user entity. So `superAdmin: u => u.isAdmin`
+     * will NOT fire from a route/`gate.allows(...)` unless you also configure
+     * {@link AuthzModuleOptions.resolveUser} to hydrate the full entity. On the
+     * explicit `gate.forUser(entity)` path you receive exactly what you passed.
+     */
+    superAdmin?: SuperAdminHook;
+    /**
+     * Optional hook to hydrate the full user entity from the context's
+     * {@link UserRef} (`{ type, id }`) before policies / `before` / `superAdmin`
+     * run. WITHOUT this hook, the context path passes only `{ type, id }` to those
+     * functions (it does not load your `User` row), so property checks such as
+     * `superAdmin: u => u.isAdmin` or `post.authorId === user.id` against a real
+     * column will not see hydrated fields. Provide `resolveUser` to load the entity
+     * (e.g. from your ORM) keyed by the ref. Returning `undefined` is treated as
+     * "no user" (deny path), identical to an anonymous request.
+     *
+     * Only affects the context path; `gate.forUser(entity)` always uses the value
+     * you pass directly and never invokes this hook.
+     */
+    resolveUser?: (ref: UserRef) => User | undefined | Promise<User | undefined>;
+    /**
+     * Override the default {@link ResourceResolver} used to load an instance for
+     * `@Can(ability, Resource)` routes. Defaults to {@link IdParamResourceResolver}
+     * (reads the route `:id` param), registered automatically by `forRoot`. Apps
+     * needing real ORM entities provide their own here (or bind the
+     * `RESOURCE_RESOLVER` token directly).
+     */
+    resourceResolver?: ResourceResolver;
+    /**
+     * Route param name the default {@link IdParamResourceResolver} reads to build
+     * the resource shim. Defaults to `'id'`. Ignored when {@link resourceResolver}
+     * is supplied.
+     */
+    idParam?: string;
+}
+export interface AuthzModuleOptionsFactory {
+    createAuthzOptions(): Promise<AuthzModuleOptions> | AuthzModuleOptions;
+}
+export interface AuthzModuleAsyncOptions {
+    imports?: unknown[];
+    useExisting?: Type<AuthzModuleOptionsFactory>;
+    useClass?: Type<AuthzModuleOptionsFactory>;
+    useFactory?: (...args: unknown[]) => Promise<AuthzModuleOptions> | AuthzModuleOptions;
+    inject?: unknown[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D;;;GAGG;AACH,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC;AAE9B;;;GAGG;AACH,MAAM,MAAM,IAAI,GAAG,OAAO,CAAC;AAE3B;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC,EAAE,QAAQ,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAE3F;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAC7B,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,MAAM,KACZ,OAAO,GAAG,SAAS,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAAC;AAExD,4EAA4E;AAC5E,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG;IACrD,MAAM,CAAC,EAAE,gBAAgB,CAAC;CAC3B,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,MAAM,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,CAAC,EAAE,QAAQ,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;AAErF;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,CAC3B,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,MAAM,KACZ,OAAO,GAAG,SAAS,GAAG,OAAO,CAAC,OAAO,GAAG,SAAS,CAAC,CAAC;AAExD,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC;IACvC;;;;;;;;;;OAUG;IACH,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B;;;;;;;;;;;;OAYG;IACH,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,IAAI,GAAG,SAAS,CAAC,CAAC;IAC7E;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,yBAAyB;IACxC,kBAAkB,IAAI,OAAO,CAAC,kBAAkB,CAAC,GAAG,kBAAkB,CAAC;CACxE;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,CAAC,EAAE,OAAO,EAAE,CAAC;IACpB,WAAW,CAAC,EAAE,IAAI,CAAC,yBAAyB,CAAC,CAAC;IAC9C,QAAQ,CAAC,EAAE,IAAI,CAAC,yBAAyB,CAAC,CAAC;IAC3C,UAAU,CAAC,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,kBAAkB,CAAC,GAAG,kBAAkB,CAAC;IACtF,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC;CACpB"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@dudousxd/nestjs-authz",
+  "version": "0.2.0",
+  "description": "NestJS authorization — Laravel-style Gates & Policies, @Can guard, resource resolver (zero DB).",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DavideCarvalho/nestjs-authz.git",
+    "directory": "packages/core"
+  },
+  "author": "Davi Carvalho <davi@goflip.ai>",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "peerDependencies": {
+    "@dudousxd/nestjs-context": ">=0.1.0",
+    "@nestjs/common": ">=10.0.0",
+    "@nestjs/core": ">=10.0.0",
+    "reflect-metadata": ">=0.1.13"
+  },
+  "peerDependenciesMeta": {
+    "@dudousxd/nestjs-context": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0",
+    "@nestjs/platform-express": "^11.0.0",
+    "@nestjs/testing": "^11.0.0",
+    "@types/express": "^4.17.21",
+    "@types/node": "^20.0.0",
+    "@types/supertest": "^6.0.2",
+    "express": "^4.19.2",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.1",
+    "supertest": "^7.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "nestjs",
+    "authorization",
+    "authz",
+    "gate",
+    "policy",
+    "acl",
+    "rbac"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}