@veloxts/auth 0.7.5 → 0.7.6

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @veloxts/auth
 
+## 0.7.6
+
+### Patch Changes
+
+- feat(router): custom access levels for the Resource API + advanced Architectural Patterns
+- Updated dependencies
+  - @veloxts/core@0.7.6
+  - @veloxts/router@0.7.6
+
 ## 0.7.5
 
 ### Patch Changes

package/dist/guards-narrowing.d.ts

@@ -48,7 +48,7 @@ export interface NarrowingGuard<TRequired, TGuaranteed> {
      *
      * When set, the procedure builder will automatically assign this
      * value to `ctx.__accessLevel` after the guard passes, enabling
-     * auto-projection with `.resource()`.
+     * auto-projection with `.expose()`.
      */
     accessLevel?: AccessLevel;
 }
@@ -134,7 +134,7 @@ export declare const authenticatedNarrow: NarrowingGuard<{
  *   .guardNarrow(adminNarrow)
  *   .query(({ ctx }) => {
  *     // ctx.user is typed as User with roles: string[]
- *     // When used with resource(), returns all fields including admin-only
+ *     // When used with expose(), returns all fields including admin-only
  *     const user = await ctx.db.user.findUnique({ where: { id } });
  *     return resource(user, UserSchema).forAdmin();
  *   });
@@ -166,6 +166,39 @@ export declare const adminNarrow: NarrowingGuard<{
 export declare function hasRoleNarrow(roles: string | string[]): NarrowingGuard<{
     user?: User;
 }, RoleNarrowedContext>;
+/**
+ * Creates a custom narrowing guard with a specified access level.
+ *
+ * Use this to create guards for custom access levels defined via
+ * `defineAccessLevels()`. The guard's `accessLevel` is used by
+ * `executeProcedure()` for automatic resource projection.
+ *
+ * @param level - The access level string (e.g., 'reviewer', 'moderator')
+ * @param check - Guard check function
+ * @param options - Optional guard configuration
+ * @returns NarrowingGuard with the specified access level
+ *
+ * @example
+ * ```typescript
+ * import { createNarrowingGuard } from '@veloxts/auth';
+ *
+ * const reviewerNarrow = createNarrowingGuard(
+ *   'reviewer',
+ *   async (ctx) => ctx.user?.roles?.includes('reviewer') ?? false,
+ *   { name: 'reviewer', message: 'Reviewer access required' }
+ * );
+ *
+ * procedure()
+ *   .guardNarrow(reviewerNarrow)
+ *   .expose(ArticleSchema)
+ *   .query(handler);
+ * ```
+ */
+export declare function createNarrowingGuard<TLevel extends string, TRequired = unknown, TGuaranteed = unknown>(level: TLevel, check: GuardFunction<TRequired>, options?: {
+    name?: string;
+    message?: string;
+    statusCode?: number;
+}): NarrowingGuard<TRequired, TGuaranteed>;
 /**
  * Extracts the narrowed context type from a NarrowingGuard.
  *

package/dist/guards-narrowing.js

@@ -52,7 +52,7 @@ export const authenticatedNarrow = {
     // Phantom type: value is never used at runtime, only carries type info.
     // The `undefined as unknown as T` pattern is standard for phantom types.
     _narrows: undefined,
-    // Runtime access level for auto-projection with .resource()
+    // Runtime access level for auto-projection with .expose()
     accessLevel: 'authenticated',
 };
 /**
@@ -70,7 +70,7 @@ export const authenticatedNarrow = {
  *   .guardNarrow(adminNarrow)
  *   .query(({ ctx }) => {
  *     // ctx.user is typed as User with roles: string[]
- *     // When used with resource(), returns all fields including admin-only
+ *     // When used with expose(), returns all fields including admin-only
  *     const user = await ctx.db.user.findUnique({ where: { id } });
  *     return resource(user, UserSchema).forAdmin();
  *   });
@@ -80,7 +80,7 @@ export const adminNarrow = {
     ...hasRoleBase('admin'),
     // Phantom type: carries type info for guardNarrow() and Resource API
     _narrows: undefined,
-    // Runtime access level for auto-projection with .resource()
+    // Runtime access level for auto-projection with .expose()
     accessLevel: 'admin',
 };
 /**
@@ -111,3 +111,44 @@ export function hasRoleNarrow(roles) {
         _narrows: undefined,
     };
 }
+// ============================================================================
+// Type Utilities
+// ============================================================================
+/**
+ * Creates a custom narrowing guard with a specified access level.
+ *
+ * Use this to create guards for custom access levels defined via
+ * `defineAccessLevels()`. The guard's `accessLevel` is used by
+ * `executeProcedure()` for automatic resource projection.
+ *
+ * @param level - The access level string (e.g., 'reviewer', 'moderator')
+ * @param check - Guard check function
+ * @param options - Optional guard configuration
+ * @returns NarrowingGuard with the specified access level
+ *
+ * @example
+ * ```typescript
+ * import { createNarrowingGuard } from '@veloxts/auth';
+ *
+ * const reviewerNarrow = createNarrowingGuard(
+ *   'reviewer',
+ *   async (ctx) => ctx.user?.roles?.includes('reviewer') ?? false,
+ *   { name: 'reviewer', message: 'Reviewer access required' }
+ * );
+ *
+ * procedure()
+ *   .guardNarrow(reviewerNarrow)
+ *   .expose(ArticleSchema)
+ *   .query(handler);
+ * ```
+ */
+export function createNarrowingGuard(level, check, options) {
+    return {
+        name: options?.name ?? level,
+        check,
+        message: options?.message,
+        statusCode: options?.statusCode,
+        _narrows: undefined,
+        accessLevel: level,
+    };
+}

package/dist/index.d.ts

@@ -16,7 +16,7 @@ export { createInMemoryTokenStore, generateTokenId, isValidTimespan, JwtManager,
 export type { EnhancedTokenStore, EnhancedTokenStoreOptions } from './token-store.js';
 export { createEnhancedTokenStore, DEFAULT_ALLOWED_ROLES, parseUserRoles, } from './token-store.js';
 export type { ADMIN, AdminContext, AUTHENTICATED, AuthenticatedContext, InferNarrowedContext, NarrowingGuard, RoleNarrowedContext, TaggedContext, } from './guards-narrowing.js';
-export { adminNarrow, authenticatedNarrow, hasRoleNarrow, } from './guards-narrowing.js';
+export { adminNarrow, authenticatedNarrow, createNarrowingGuard, hasRoleNarrow, } from './guards-narrowing.js';
 export { DEFAULT_HASH_CONFIG, hashPassword, PasswordHasher, passwordHasher, verifyPassword, } from './hash.js';
 export type { GuardBuilder } from './guards.js';
 export { allOf, anyOf, authenticated, defineGuard, emailVerified, executeGuard, executeGuards, guard, hasAnyPermission, hasPermission, hasRole, not, userCan, } from './guards.js';

package/dist/index.js

@@ -18,7 +18,7 @@ export { AuthError } from './types.js';
 export { AUTH_REGISTERED, checkDoubleRegistration, decorateAuth, getRequestAuth, getRequestUser, setRequestAuth, } from './decoration.js';
 export { createInMemoryTokenStore, generateTokenId, isValidTimespan, JwtManager, jwtManager, parseTimeToSeconds, validateTokenExpiration, } from './jwt.js';
 export { createEnhancedTokenStore, DEFAULT_ALLOWED_ROLES, parseUserRoles, } from './token-store.js';
-export { adminNarrow, authenticatedNarrow, hasRoleNarrow, } from './guards-narrowing.js';
+export { adminNarrow, authenticatedNarrow, createNarrowingGuard, hasRoleNarrow, } from './guards-narrowing.js';
 // ============================================================================
 // Password Hashing
 // ============================================================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veloxts/auth",
-  "version": "0.7.5",
+  "version": "0.7.6",
   "description": "Authentication and authorization system for VeloxTS framework",
   "type": "module",
   "main": "dist/index.js",
@@ -61,8 +61,8 @@
   "dependencies": {
     "@fastify/cookie": "11.0.2",
     "fastify": "5.7.4",
-    "@veloxts/core": "0.7.5",
-    "@veloxts/router": "0.7.5"
+    "@veloxts/router": "0.7.6",
+    "@veloxts/core": "0.7.6"
   },
   "peerDependencies": {
     "argon2": ">=0.30.0",
@@ -85,8 +85,8 @@
     "@vitest/coverage-v8": "4.0.18",
     "typescript": "5.9.3",
     "vitest": "4.0.18",
-    "@veloxts/validation": "0.7.5",
-    "@veloxts/testing": "0.7.5"
+    "@veloxts/validation": "0.7.6",
+    "@veloxts/testing": "0.7.6"
   },
   "keywords": [
     "velox",