@veloxts/auth 0.8.0 → 0.8.1

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @veloxts/auth
 
+## 0.8.1
+
+### Patch Changes
+
+- feat: add business logic primitives for B2B SaaS apps
+- Updated dependencies
+  - @veloxts/core@0.8.1
+  - @veloxts/router@0.8.1
+
 ## 0.8.0
 
 ### Minor Changes

package/dist/index.d.ts

@@ -8,7 +8,7 @@
  * @module @veloxts/auth
  */
 export { AUTH_VERSION } from './plugin.js';
-export type { AdapterAuthContext, AuthConfig, AuthContext, AuthMiddlewareOptions, BaseAuthContext, GuardDefinition, GuardFunction, HashConfig, JwtConfig, NativeAuthContext, PolicyAction, PolicyDefinition, RateLimitConfig, TokenPair, TokenPayload, User, } from './types.js';
+export type { AdapterAuthContext, AuthConfig, AuthContext, AuthMiddlewareOptions, BaseAuthContext, GuardDefinition, GuardFunction, HashConfig, JwtConfig, NativeAuthContext, PolicyAction, PolicyActionParams, PolicyActionRef, PolicyDefinition, PolicyObject, RateLimitConfig, TokenPair, TokenPayload, User, } from './types.js';
 export { AuthError } from './types.js';
 export { AUTH_REGISTERED, checkDoubleRegistration, decorateAuth, getRequestAuth, getRequestUser, setRequestAuth, } from './decoration.js';
 export type { TokenStore } from './jwt.js';

package/dist/policies.d.ts

@@ -2,20 +2,22 @@
  * Resource-level authorization policies for @veloxts/auth
  * @module auth/policies
  */
-import type { PolicyAction, PolicyDefinition, User } from './types.js';
+import type { PolicyAction, PolicyDefinition, PolicyObject, User } from './types.js';
 /**
  * Registers a policy for a resource type
  *
  * @example
  * ```typescript
- * registerPolicy('Post', {
- *   view: (user, post) => true, // Anyone can view
- *   update: (user, post) => user.id === post.authorId,
- *   delete: (user, post) => user.id === post.authorId || user.role === 'admin',
+ * const PostPolicy = definePolicy<User, Post>('Post', {
+ *   view: () => true,
+ *   update: ({ user, resource }) => user.id === resource.authorId,
+ *   delete: ({ user, resource }) => user.id === resource.authorId || user.role === 'admin',
  * });
+ *
+ * registerPolicy(PostPolicy);
  * ```
  */
-export declare function registerPolicy<TUser = User, TResource = unknown>(resourceName: string, policy: PolicyDefinition<TUser, TResource>): void;
+export declare function registerPolicy<TUser = User, TResource = unknown>(policyOrName: string | PolicyObject<TUser, TResource>, policy?: PolicyDefinition<TUser, TResource>): void;
 /**
  * Gets a registered policy by resource name
  */
@@ -29,19 +31,24 @@ export declare function clearPolicies(): void;
  *
  * @example
  * ```typescript
- * const PostPolicy = definePolicy<User, Post>({
+ * const PostPolicy = definePolicy<User, Post>('Post', {
  *   view: () => true,
- *   create: (user) => user.emailVerified,
- *   update: (user, post) => user.id === post.authorId,
- *   delete: (user, post) => user.id === post.authorId || user.role === 'admin',
- *   publish: (user, post) => user.role === 'editor' && user.id === post.authorId,
+ *   create: ({ user }) => user.emailVerified,
+ *   update: ({ user, resource }) => user.id === resource.authorId,
+ *   delete: ({ user, resource }) => user.id === resource.authorId || user.role === 'admin',
+ *   publish: ({ user, resource }) => user.role === 'editor' && user.id === resource.authorId,
  * });
  *
+ * // Each action is a PolicyActionRef:
+ * PostPolicy.update.actionName   // 'update'
+ * PostPolicy.update.resourceName // 'Post'
+ * PostPolicy.update.check(user, post) // boolean | Promise<boolean>
+ *
  * // Register it
- * registerPolicy('Post', PostPolicy);
+ * registerPolicy(PostPolicy);
  * ```
  */
-export declare function definePolicy<TUser = User, TResource = unknown>(actions: PolicyDefinition<TUser, TResource>): PolicyDefinition<TUser, TResource>;
+export declare function definePolicy<TUser = User, TResource = unknown, const TResourceName extends string = string>(resourceName: TResourceName, actions: PolicyDefinition<TUser, TResource>): PolicyObject<TUser, TResource, TResourceName>;
 /**
  * Checks if a user can perform an action on a resource
  *
@@ -76,10 +83,10 @@ export declare function authorize<TResource = unknown>(user: User | null | undef
  * ```typescript
  * const CommentPolicy = createPolicyBuilder<User, Comment>()
  *   .allow('view', () => true)
- *   .allow('create', (user) => user.emailVerified)
- *   .allow('update', (user, comment) => user.id === comment.authorId)
- *   .allow('delete', (user, comment) =>
- *     user.id === comment.authorId || user.role === 'admin'
+ *   .allow('create', ({ user }) => user.emailVerified)
+ *   .allow('update', ({ user, resource }) => user.id === resource.authorId)
+ *   .allow('delete', ({ user, resource }) =>
+ *     user.id === resource.authorId || user.role === 'admin'
  *   )
  *   .build();
  * ```

package/dist/policies.js

@@ -2,7 +2,7 @@
  * Resource-level authorization policies for @veloxts/auth
  * @module auth/policies
  */
-import { createLogger } from '@veloxts/core';
+import { createLogger, ForbiddenError } from '@veloxts/core';
 const log = createLogger('auth');
 // ============================================================================
 // Policy Registry
@@ -17,15 +17,37 @@ const policyRegistry = new Map();
  *
  * @example
  * ```typescript
- * registerPolicy('Post', {
- *   view: (user, post) => true, // Anyone can view
- *   update: (user, post) => user.id === post.authorId,
- *   delete: (user, post) => user.id === post.authorId || user.role === 'admin',
+ * const PostPolicy = definePolicy<User, Post>('Post', {
+ *   view: () => true,
+ *   update: ({ user, resource }) => user.id === resource.authorId,
+ *   delete: ({ user, resource }) => user.id === resource.authorId || user.role === 'admin',
  * });
+ *
+ * registerPolicy(PostPolicy);
  * ```
  */
-export function registerPolicy(resourceName, policy) {
-    policyRegistry.set(resourceName, policy);
+export function registerPolicy(policyOrName, policy) {
+    if (typeof policyOrName === 'string') {
+        // Legacy: registerPolicy('Post', policyDef)
+        if (policy) {
+            policyRegistry.set(policyOrName, policy);
+        }
+    }
+    else {
+        // New: registerPolicy(PostPolicy) — extracts resourceName and rebuilds definition
+        const policyObj = policyOrName;
+        const definition = {};
+        for (const key of Object.keys(policyObj)) {
+            if (key === 'resourceName')
+                continue;
+            const ref = policyObj[key];
+            if (ref && typeof ref === 'object' && 'check' in ref && 'actionName' in ref) {
+                const actionRef = ref;
+                definition[key] = ({ user, resource }) => actionRef.check(user, resource);
+            }
+        }
+        policyRegistry.set(policyObj.resourceName, definition);
+    }
 }
 /**
  * Gets a registered policy by resource name
@@ -47,20 +69,41 @@ export function clearPolicies() {
  *
  * @example
  * ```typescript
- * const PostPolicy = definePolicy<User, Post>({
+ * const PostPolicy = definePolicy<User, Post>('Post', {
  *   view: () => true,
- *   create: (user) => user.emailVerified,
- *   update: (user, post) => user.id === post.authorId,
- *   delete: (user, post) => user.id === post.authorId || user.role === 'admin',
- *   publish: (user, post) => user.role === 'editor' && user.id === post.authorId,
+ *   create: ({ user }) => user.emailVerified,
+ *   update: ({ user, resource }) => user.id === resource.authorId,
+ *   delete: ({ user, resource }) => user.id === resource.authorId || user.role === 'admin',
+ *   publish: ({ user, resource }) => user.role === 'editor' && user.id === resource.authorId,
  * });
  *
+ * // Each action is a PolicyActionRef:
+ * PostPolicy.update.actionName   // 'update'
+ * PostPolicy.update.resourceName // 'Post'
+ * PostPolicy.update.check(user, post) // boolean | Promise<boolean>
+ *
  * // Register it
- * registerPolicy('Post', PostPolicy);
+ * registerPolicy(PostPolicy);
  * ```
  */
-export function definePolicy(actions) {
-    return actions;
+export function definePolicy(resourceName, actions) {
+    const result = {
+        resourceName,
+    };
+    for (const [actionName, handler] of Object.entries(actions)) {
+        if (handler) {
+            const actionHandler = handler;
+            const ref = {
+                actionName,
+                resourceName,
+                check: (user, resource) => {
+                    return actionHandler({ user, resource: resource });
+                },
+            };
+            result[actionName] = ref;
+        }
+    }
+    return result;
 }
 // ============================================================================
 // Authorization Checks
@@ -92,7 +135,7 @@ export async function can(user, action, resourceName, resource) {
         // Action not defined = deny by default
         return false;
     }
-    return actionHandler(user, resource);
+    return actionHandler({ user, resource: resource });
 }
 /**
  * Checks if a user cannot perform an action (inverse of can)
@@ -113,9 +156,7 @@ export async function cannot(user, action, resourceName, resource) {
 export async function authorize(user, action, resourceName, resource) {
     const allowed = await can(user, action, resourceName, resource);
     if (!allowed) {
-        const error = new Error(`Unauthorized: cannot ${action} ${resourceName}${resource ? ` (id: ${resource.id ?? 'unknown'})` : ''}`);
-        error.statusCode = 403;
-        throw error;
+        throw new ForbiddenError(`Unauthorized: cannot ${action} ${resourceName}${resource ? ` (id: ${resource.id ?? 'unknown'})` : ''}`);
     }
 }
 // ============================================================================
@@ -128,10 +169,10 @@ export async function authorize(user, action, resourceName, resource) {
  * ```typescript
  * const CommentPolicy = createPolicyBuilder<User, Comment>()
  *   .allow('view', () => true)
- *   .allow('create', (user) => user.emailVerified)
- *   .allow('update', (user, comment) => user.id === comment.authorId)
- *   .allow('delete', (user, comment) =>
- *     user.id === comment.authorId || user.role === 'admin'
+ *   .allow('create', ({ user }) => user.emailVerified)
+ *   .allow('update', ({ user, resource }) => user.id === resource.authorId)
+ *   .allow('delete', ({ user, resource }) =>
+ *     user.id === resource.authorId || user.role === 'admin'
  *   )
  *   .build();
  * ```
@@ -160,7 +201,7 @@ class PolicyBuilder {
      * Assumes resource has a userId or authorId field
      */
     allowOwner(action, ownerField = 'userId') {
-        this.actions[action] = (user, resource) => {
+        this.actions[action] = ({ user, resource }) => {
             const ownerId = resource?.[ownerField];
             return ownerId === user.id;
         };
@@ -170,7 +211,7 @@ class PolicyBuilder {
      * Allows action for owner OR users with specific role
      */
     allowOwnerOr(action, roles, ownerField = 'userId') {
-        this.actions[action] = (user, resource) => {
+        this.actions[action] = ({ user, resource }) => {
             const ownerId = resource?.[ownerField];
             const userRole = user.role;
             const isOwner = ownerId === user.id;
@@ -202,7 +243,7 @@ class PolicyBuilder {
  * and owner-only for regular users
  */
 export function createOwnerOrAdminPolicy(ownerField = 'userId') {
-    const isOwnerOrAdmin = (user, resource) => {
+    const isOwnerOrAdmin = ({ user, resource, }) => {
         if (user.role === 'admin') {
             return true;
         }
@@ -231,7 +272,7 @@ export function createReadOnlyPolicy() {
  * Creates a policy for admin-only resources
  */
 export function createAdminOnlyPolicy() {
-    const isAdmin = (user) => user.role === 'admin';
+    const isAdmin = ({ user }) => user.role === 'admin';
     return {
         view: isAdmin,
         create: isAdmin,

package/dist/types.d.ts

@@ -286,11 +286,20 @@ export interface GuardDefinition<TContext = unknown> {
     /** HTTP status code on failure (default: 403) */
     statusCode?: number;
 }
+/**
+ * Parameters passed to a policy action handler
+ */
+export interface PolicyActionParams<TUser = User, TResource = unknown> {
+    /** The authenticated user performing the action */
+    user: TUser;
+    /** The resource being acted upon (optional for create-like actions) */
+    resource: TResource;
+}
 /**
  * Policy action handler
  * Returns true if user can perform action on resource
  */
-export type PolicyAction<TUser = User, TResource = unknown> = (user: TUser, resource: TResource) => boolean | Promise<boolean>;
+export type PolicyAction<TUser = User, TResource = unknown> = (params: PolicyActionParams<TUser, TResource>) => boolean | Promise<boolean>;
 /**
  * Policy definition with named actions
  */
@@ -306,6 +315,31 @@ export interface PolicyDefinition<TUser = User, TResource = unknown> {
     /** Custom actions */
     [action: string]: PolicyAction<TUser, TResource> | undefined;
 }
+/**
+ * A reference to a single policy action with its metadata.
+ *
+ * Returned as a property on a PolicyObject for each defined action.
+ * Can be used for introspection or passed to authorization helpers.
+ */
+export interface PolicyActionRef<TUser = unknown, TResource = unknown, TResourceName extends string = string> {
+    /** The name of the action (e.g., 'update', 'delete') */
+    readonly actionName: string;
+    /** The name of the resource this policy applies to (e.g., 'Post') */
+    readonly resourceName: TResourceName;
+    /** Execute the policy check for this action */
+    readonly check: (user: TUser, resource?: TResource) => boolean | Promise<boolean>;
+}
+/**
+ * A policy object returned by definePolicy.
+ *
+ * Contains the resource name and each action as a PolicyActionRef.
+ */
+export type PolicyObject<TUser = User, TResource = unknown, TResourceName extends string = string, TActions extends string = string> = {
+    /** The resource name this policy applies to */
+    readonly resourceName: TResourceName;
+} & {
+    readonly [K in TActions]: PolicyActionRef<TUser, TResource, TResourceName>;
+};
 /**
  * Auth middleware options
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veloxts/auth",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Authentication and authorization system for VeloxTS framework",
   "type": "module",
   "main": "dist/index.js",
@@ -60,9 +60,9 @@
   },
   "dependencies": {
     "@fastify/cookie": "11.0.2",
-    "fastify": "5.7.4",
-    "@veloxts/core": "0.8.0",
-    "@veloxts/router": "0.8.0"
+    "fastify": "5.8.2",
+    "@veloxts/core": "0.8.1",
+    "@veloxts/router": "0.8.1"
   },
   "peerDependencies": {
     "argon2": ">=0.30.0",
@@ -82,11 +82,11 @@
   },
   "devDependencies": {
     "@types/bcrypt": "6.0.0",
-    "@vitest/coverage-v8": "4.0.18",
+    "@vitest/coverage-v8": "4.1.0",
     "typescript": "5.9.3",
-    "vitest": "4.0.18",
-    "@veloxts/testing": "0.8.0",
-    "@veloxts/validation": "0.8.0"
+    "vitest": "4.1.0",
+    "@veloxts/testing": "0.8.1",
+    "@veloxts/validation": "0.8.1"
   },
   "keywords": [
     "velox",