@veloxts/auth 0.6.72 → 0.6.74

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @veloxts/auth
 
+## 0.6.74
+
+### Patch Changes
+
+- docs: fix erroneous file paths and improve auth context documentation
+- Updated dependencies
+  - @veloxts/core@0.6.74
+  - @veloxts/router@0.6.74
+
+## 0.6.73
+
+### Patch Changes
+
+- fix(create): add @veloxts/auth as explicit dependency in auth template
+- Updated dependencies
+  - @veloxts/core@0.6.73
+  - @veloxts/router@0.6.73
+
 ## 0.6.72
 
 ### Patch Changes

package/dist/types.d.ts

@@ -22,26 +22,70 @@ export declare class AuthError extends Error {
     constructor(message: string, statusCode: number, code?: string);
 }
 /**
- * Base user interface for authenticated requests
+ * Base user interface available on `ctx.user` after authentication.
  *
- * Applications should extend this via declaration merging to add
- * custom properties without using index signatures:
+ * **IMPORTANT:** `ctx.user` is NOT the raw database user. It only contains
+ * fields explicitly returned by your `userLoader` function passed to `authPlugin()`.
  *
- * @example
+ * ## How ctx.user Gets Populated
+ *
+ * 1. JWT token is validated from cookie/header
+ * 2. User ID is extracted from token payload
+ * 3. Your `userLoader(userId)` function is called
+ * 4. Only fields returned by `userLoader` are available on `ctx.user`
+ *
+ * ## Default Fields
+ *
+ * The scaffolded templates return:
+ * - `id`: User's unique identifier
+ * - `email`: User's email address
+ * - `name`: User's display name
+ * - `roles`: Array of role names
+ *
+ * ## Adding Custom Fields
+ *
+ * To add fields like `organizationId` to `ctx.user`:
+ *
+ * 1. Update your `userLoader` to return the field:
+ * ```typescript
+ * async function userLoader(userId: string) {
+ *   const user = await db.user.findUnique({ where: { id: userId } });
+ *   return {
+ *     id: user.id,
+ *     email: user.email,
+ *     organizationId: user.organizationId, // Add field here
+ *   };
+ * }
+ * ```
+ *
+ * 2. Extend this interface via declaration merging:
  * ```typescript
  * declare module '@veloxts/auth' {
  *   interface User {
- *     name?: string;
- *     avatarUrl?: string;
- *     tenantId?: string;
+ *     organizationId: string;
  *   }
  * }
  * ```
  *
+ * ## Common Mistake
+ *
+ * ```typescript
+ * // ❌ WRONG - undefined if not returned by userLoader
+ * const orgId = ctx.user.organizationId;
+ *
+ * // ✅ CORRECT - After adding to userLoader
+ * const orgId = ctx.user.organizationId;
+ *
+ * // ✅ ALTERNATIVE - Fetch full user when needed
+ * const fullUser = await db.user.findUnique({ where: { id: ctx.user.id } });
+ * ```
+ *
  * This approach provides:
  * - Full type safety (no implicit `unknown` properties)
  * - Better IDE autocomplete
  * - Compile-time errors for typos
+ *
+ * @see userLoader option in authPlugin configuration
  */
 export interface User {
     /** Unique user identifier */
@@ -157,8 +201,32 @@ export interface AuthConfig {
     /** Rate limiting configuration */
     rateLimit?: RateLimitConfig;
     /**
-     * User loader function - fetches user from database by ID
-     * Called on every authenticated request to populate ctx.user
+     * User loader function - fetches user from database by ID.
+     *
+     * Called on every authenticated request to populate `ctx.user`.
+     *
+     * **IMPORTANT:** Only fields you return here will be available on `ctx.user`.
+     * The returned object is NOT the raw database user - you control exactly
+     * which fields are exposed.
+     *
+     * @example
+     * ```typescript
+     * userLoader: async (userId) => {
+     *   const user = await db.user.findUnique({ where: { id: userId } });
+     *   if (!user) return null;
+     *
+     *   return {
+     *     id: user.id,
+     *     email: user.email,
+     *     name: user.name,
+     *     roles: parseUserRoles(user.roles),
+     *     // Add custom fields here to make them available on ctx.user
+     *     organizationId: user.organizationId,
+     *   };
+     * }
+     * ```
+     *
+     * @see User interface for extending the type via declaration merging
      */
     userLoader?: (userId: string) => Promise<User | null>;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veloxts/auth",
-  "version": "0.6.72",
+  "version": "0.6.74",
   "description": "Authentication and authorization system for VeloxTS framework",
   "type": "module",
   "main": "dist/index.js",
@@ -57,8 +57,8 @@
   "dependencies": {
     "@fastify/cookie": "11.0.2",
     "fastify": "5.6.2",
-    "@veloxts/core": "0.6.72",
-    "@veloxts/router": "0.6.72"
+    "@veloxts/router": "0.6.74",
+    "@veloxts/core": "0.6.74"
   },
   "peerDependencies": {
     "argon2": ">=0.30.0",
@@ -82,8 +82,8 @@
     "fastify-plugin": "5.1.0",
     "typescript": "5.9.3",
     "vitest": "4.0.16",
-    "@veloxts/testing": "0.6.72",
-    "@veloxts/validation": "0.6.72"
+    "@veloxts/testing": "0.6.74",
+    "@veloxts/validation": "0.6.74"
   },
   "keywords": [
     "velox",