@veloxts/auth 0.6.92 → 0.6.93

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @veloxts/auth
 
+## 0.6.93
+
+### Patch Changes
+
+- feat(router): add Resource API with phantom types for context-dependent outputs
+- Updated dependencies
+  - @veloxts/core@0.6.93
+  - @veloxts/router@0.6.93
+
 ## 0.6.92
 
 ### Patch Changes

package/GUIDE.md

@@ -86,6 +86,45 @@ const adminWithPermission = procedure()
   .mutation(handler);
 ```
 
+## Resource API Integration
+
+Guards work seamlessly with the Resource API for context-dependent outputs:
+
+```typescript
+import { resource, resourceSchema } from '@veloxts/router';
+import { authenticatedNarrow, adminNarrow } from '@veloxts/auth';
+
+const UserSchema = resourceSchema()
+  .public('id', z.string())
+  .public('name', z.string())
+  .authenticated('email', z.string())
+  .admin('internalNotes', z.string().nullable())
+  .build();
+
+// Anonymous - returns { id, name }
+const getPublicUser = procedure()
+  .query(async ({ input, ctx }) => {
+    const user = await ctx.db.user.findUnique({ where: { id: input.id } });
+    return resource(user, UserSchema).forAnonymous();
+  });
+
+// Authenticated - returns { id, name, email }
+const getUser = procedure()
+  .guardNarrow(authenticatedNarrow)
+  .query(async ({ input, ctx }) => {
+    const user = await ctx.db.user.findUnique({ where: { id: input.id } });
+    return resource(user, UserSchema).for(ctx); // Auto-detects level
+  });
+
+// Admin - returns all fields
+const getFullUser = procedure()
+  .guardNarrow(adminNarrow)
+  .query(async ({ input, ctx }) => {
+    const user = await ctx.db.user.findUnique({ where: { id: input.id } });
+    return resource(user, UserSchema).forAdmin();
+  });
+```
+
 ## Password Hashing
 
 ```typescript

package/dist/guards-narrowing.d.ts

@@ -5,18 +5,26 @@
  * When using `guardNarrow(authenticatedNarrow)`, the context type
  * is narrowed to guarantee `ctx.user` is non-null.
  *
+ * Additionally, these guards add phantom type tags for use with the
+ * Resource API, enabling context-dependent output types.
+ *
  * EXPERIMENTAL: This API may change. The current recommended approach
  * is to use middleware for context type extension.
  *
  * @module auth/guards-narrowing
  */
+import type { AccessLevel, ADMIN, AUTHENTICATED, TaggedContext } from '@veloxts/router';
 import type { AuthContext, GuardFunction, User } from './types.js';
+export type { AccessLevel, ADMIN, AUTHENTICATED, TaggedContext };
 /**
  * A guard that narrows the context type after passing.
  *
  * The `_narrows` phantom type indicates what the guard guarantees
  * about the context after it passes.
  *
+ * The `accessLevel` property is used by the procedure builder to
+ * automatically set `ctx.__accessLevel` for resource auto-projection.
+ *
  * @template TRequired - Context properties required to run the guard
  * @template TGuaranteed - Context properties guaranteed after guard passes
  */
@@ -35,18 +43,41 @@ export interface NarrowingGuard<TRequired, TGuaranteed> {
      * @internal
      */
     readonly _narrows: TGuaranteed;
+    /**
+     * Runtime access level for automatic resource projection.
+     *
+     * When set, the procedure builder will automatically assign this
+     * value to `ctx.__accessLevel` after the guard passes, enabling
+     * auto-projection with `.resource()`.
+     */
+    accessLevel?: AccessLevel;
 }
 /**
  * Context type with a guaranteed authenticated user.
  *
  * After `authenticatedNarrow` passes, the context is narrowed to this type.
+ * Includes a phantom tag for the Resource API.
  */
-export interface AuthenticatedContext {
+export interface AuthenticatedContext extends TaggedContext<typeof AUTHENTICATED> {
     auth: AuthContext & {
         isAuthenticated: true;
     };
     user: User;
 }
+/**
+ * Context type with a guaranteed user having admin role.
+ *
+ * After `adminNarrow` passes, the context is narrowed to this type.
+ * Includes a phantom tag for the Resource API.
+ */
+export interface AdminContext extends TaggedContext<typeof ADMIN> {
+    auth: AuthContext & {
+        isAuthenticated: true;
+    };
+    user: User & {
+        roles: string[];
+    };
+}
 /**
  * Context type with a guaranteed user having specific roles.
  */
@@ -88,6 +119,30 @@ export interface RoleNarrowedContext {
 export declare const authenticatedNarrow: NarrowingGuard<{
     auth?: AuthContext;
 }, AuthenticatedContext>;
+/**
+ * Admin guard with type narrowing and phantom tag.
+ *
+ * When used with `guardNarrow()`, narrows `ctx.user` to a User with admin role
+ * and tags the context with ADMIN for use with the Resource API.
+ *
+ * @example
+ * ```typescript
+ * import { adminNarrow } from '@veloxts/auth';
+ * import { resource, UserSchema } from '@veloxts/router';
+ *
+ * procedure()
+ *   .guardNarrow(adminNarrow)
+ *   .query(({ ctx }) => {
+ *     // ctx.user is typed as User with roles: string[]
+ *     // When used with resource(), returns all fields including admin-only
+ *     const user = await ctx.db.user.findUnique({ where: { id } });
+ *     return resource(user, UserSchema).forAdmin();
+ *   });
+ * ```
+ */
+export declare const adminNarrow: NarrowingGuard<{
+    user?: User;
+}, AdminContext>;
 /**
  * Creates a role-checking guard with type narrowing.
  *

package/dist/guards-narrowing.js

@@ -5,6 +5,9 @@
  * When using `guardNarrow(authenticatedNarrow)`, the context type
  * is narrowed to guarantee `ctx.user` is non-null.
  *
+ * Additionally, these guards add phantom type tags for use with the
+ * Resource API, enabling context-dependent output types.
+ *
  * EXPERIMENTAL: This API may change. The current recommended approach
  * is to use middleware for context type extension.
  *
@@ -49,6 +52,36 @@ 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()
+    accessLevel: 'authenticated',
+};
+/**
+ * Admin guard with type narrowing and phantom tag.
+ *
+ * When used with `guardNarrow()`, narrows `ctx.user` to a User with admin role
+ * and tags the context with ADMIN for use with the Resource API.
+ *
+ * @example
+ * ```typescript
+ * import { adminNarrow } from '@veloxts/auth';
+ * import { resource, UserSchema } from '@veloxts/router';
+ *
+ * procedure()
+ *   .guardNarrow(adminNarrow)
+ *   .query(({ ctx }) => {
+ *     // ctx.user is typed as User with roles: string[]
+ *     // When used with resource(), returns all fields including admin-only
+ *     const user = await ctx.db.user.findUnique({ where: { id } });
+ *     return resource(user, UserSchema).forAdmin();
+ *   });
+ * ```
+ */
+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()
+    accessLevel: 'admin',
 };
 /**
  * Creates a role-checking guard with type narrowing.

package/dist/index.d.ts

@@ -15,8 +15,8 @@ export type { TokenStore } from './jwt.js';
 export { createInMemoryTokenStore, generateTokenId, isValidTimespan, JwtManager, jwtManager, parseTimeToSeconds, validateTokenExpiration, } from './jwt.js';
 export type { EnhancedTokenStore, EnhancedTokenStoreOptions } from './token-store.js';
 export { createEnhancedTokenStore, DEFAULT_ALLOWED_ROLES, parseUserRoles, } from './token-store.js';
-export type { AuthenticatedContext, InferNarrowedContext, NarrowingGuard, RoleNarrowedContext, } from './guards-narrowing.js';
-export { authenticatedNarrow, hasRoleNarrow } from './guards-narrowing.js';
+export type { ADMIN, AdminContext, AUTHENTICATED, AuthenticatedContext, InferNarrowedContext, NarrowingGuard, RoleNarrowedContext, TaggedContext, } from './guards-narrowing.js';
+export { adminNarrow, authenticatedNarrow, 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 { authenticatedNarrow, hasRoleNarrow } from './guards-narrowing.js';
+export { adminNarrow, authenticatedNarrow, hasRoleNarrow, } from './guards-narrowing.js';
 // ============================================================================
 // Password Hashing
 // ============================================================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veloxts/auth",
-  "version": "0.6.92",
+  "version": "0.6.93",
   "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.2",
-    "@veloxts/core": "0.6.92",
-    "@veloxts/router": "0.6.92"
+    "@veloxts/core": "0.6.93",
+    "@veloxts/router": "0.6.93"
   },
   "peerDependencies": {
     "argon2": ">=0.30.0",
@@ -86,8 +86,8 @@
     "fastify-plugin": "5.1.0",
     "typescript": "5.9.3",
     "vitest": "4.0.18",
-    "@veloxts/testing": "0.6.92",
-    "@veloxts/validation": "0.6.92"
+    "@veloxts/testing": "0.6.93",
+    "@veloxts/validation": "0.6.93"
   },
   "keywords": [
     "velox",