@veloxts/router 0.8.3 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,80 @@
 # @veloxts/router
 
+## 0.9.0
+
+### Minor Changes
+
+- e1c32a2: Add `.check()` post-middleware authorization primitive on the procedure builder.
+
+  `.check()` runs **after** input validation, `.through()` pipeline transforms, and all `.use()` middleware have populated the context — immediately before the handler. Use it for authorization that depends on input fields and/or context values populated by middleware:
+
+  ```typescript
+  procedure()
+    .input(z.object({ sessionId: z.string() }))
+    .guard(authenticated) // pre-input, ctx-only (unchanged)
+    .use(loadParticipant) // middleware extends ctx
+    .check(
+      (
+        { input, ctx }, // sees input + middleware-extended ctx
+      ) => ctx.participant.sessionId === input.sessionId,
+    )
+    .query(handler);
+  ```
+
+  **When to use which:**
+  - `.guard(authenticated)` — pre-input, ctx-only authentication (fast-fail).
+  - `.policy(PostPolicy.update)` — declarative resource-policy authorization.
+  - `.check(({ input, ctx }) => ...)` — ad-hoc authorization that needs both `input` and middleware-extended `ctx`.
+
+  Returning `false` throws `ForbiddenError` (403). Throwing inside the function propagates as-is, so callers can throw custom domain errors with finer-grained status codes. Multiple `.check()` calls AND-compose with short-circuit on first failure.
+
+  Closes the gap exposed by the `ara/apps/api` audit where `requireParticipant((i) => i.id)` had to be implemented as `.use()` middleware because `.guard()` couldn't see middleware-extended ctx.
+
+- feat(router): add raw() response primitive for redirects, cookies, custom headers and .check() post-middleware authorization primitive
+- 83c5da1: Add `raw()` response primitive for procedures.
+
+  Procedure handlers can now return non-JSON HTTP responses — redirects, cookies, custom headers, raw bodies, streams — without bypassing the procedure system. This closes the gap exposed by the `ara/apps/api` audit, where the OAuth callback at `src/auth/atlassian.routes.ts` had to be a raw `fastify.get(...)` route because procedures couldn't model `reply.redirect()` or cookies.
+
+  ```typescript
+  import { procedure, raw } from "@veloxts/router";
+
+  export const oauthProcedures = procedures("oauth", {
+    authorize: procedure()
+      .rest({ method: "GET", path: "/auth/atlassian" })
+      .query(async ({ ctx }) => {
+        const { url, state, codeVerifier } = provider.buildAuthorizeUrl();
+        return raw({
+          cookies: [
+            {
+              name: "oauth_state",
+              value: pack(state, codeVerifier, secret),
+              options: { httpOnly: true, sameSite: "lax" },
+            },
+          ],
+          redirect: { url, status: 302 },
+        });
+      }),
+  });
+  ```
+
+  `raw()` accepts:
+  - `status` — HTTP status (default 200, ignored when `redirect` is set)
+  - `headers` — response headers
+  - `cookies` — array of `{ name, value, options }` (requires `@fastify/cookie` to be registered)
+  - `redirect` — `{ url, status? }` for 301/302/303/307/308 redirects
+  - `body` — string, Buffer, or Node `Readable` stream
+
+  The REST adapter detects `RawResponse` via a brand and short-circuits before applying the auto 201/204 status logic. OpenAPI generation already handles missing response schemas gracefully — `.raw()` procedures without `.output()` document as a response without a body schema (valid OpenAPI).
+
+  Also exports `RawResponse`, `RawResponseOptions`, `RawResponseCookie`, `RawResponseCookieOptions`, `RawResponseRedirect`, and `isRawResponse` from `@veloxts/router`.
+
+### Patch Changes
+
+- Updated dependencies
+- Updated dependencies [ca6ede3]
+  - @veloxts/core@0.9.0
+  - @veloxts/validation@0.9.0
+
 ## 0.8.3
 
 ### Patch Changes
@@ -471,7 +546,6 @@
 - ### feat(auth): Unified Adapter-Only Architecture
 
   **New Features:**
-
   - Add `JwtAdapter` implementing the `AuthAdapter` interface for unified JWT authentication
   - Add `jwtAuth()` convenience function for direct adapter usage with optional built-in routes (`/api/auth/refresh`, `/api/auth/logout`)
   - Add `AuthContext` discriminated union (`NativeAuthContext | AdapterAuthContext`) for type-safe auth mode handling
@@ -479,24 +553,20 @@
   - Add shared decoration utilities (`decorateAuth`, `setRequestAuth`, `checkDoubleRegistration`)
 
   **Architecture Changes:**
-
   - `authPlugin` now uses `JwtAdapter` internally - all authentication flows through the adapter pattern
   - Single code path for authentication (no more dual native/adapter modes)
   - `authContext.authMode` is now always `'adapter'` with `providerId='jwt'` when using `authPlugin`
 
   **Breaking Changes:**
-
   - Remove deprecated `LegacySessionConfig` interface (use `sessionMiddleware` instead)
   - Remove deprecated `session` field from `AuthConfig`
   - `User` interface no longer has index signature (extend via declaration merging)
 
   **Type Safety Improvements:**
-
   - `AuthContext` discriminated union enables exhaustive type narrowing based on `authMode`
   - Export `NativeAuthContext` and `AdapterAuthContext` types for explicit typing
 
   **Migration:**
-
   - Existing `authPlugin` usage remains backward-compatible
   - If checking `authContext.token`, use `authContext.session` instead (token stored in session for adapter mode)
 
@@ -515,12 +585,10 @@
   Addresses 9 user feedback items to improve DX, reduce boilerplate, and eliminate template duplications.
 
   ### Phase 1: Validation Helpers (`@veloxts/validation`)
-
   - Add `prismaDecimal()`, `prismaDecimalNullable()`, `prismaDecimalOptional()` for Prisma Decimal → number conversion
   - Add `dateToIso`, `dateToIsoNullable`, `dateToIsoOptional` aliases for consistency
 
   ### Phase 2: Template Deduplication (`@veloxts/auth`)
-
   - Export `createEnhancedTokenStore()` with token revocation and refresh token reuse detection
   - Export `parseUserRoles()` and `DEFAULT_ALLOWED_ROLES`
   - Fix memory leak: track pending timeouts for proper cleanup on `destroy()`
@@ -528,20 +596,17 @@
   - Fix jwtManager singleton pattern in templates
 
   ### Phase 3: Router Helpers (`@veloxts/router`)
-
   - Add `createRouter()` returning `{ collections, router }` for DRY setup
   - Add `toRouter()` for router-only use cases
   - Update all router templates to use `createRouter()`
 
   ### Phase 4: Guard Type Narrowing - Experimental (`@veloxts/auth`, `@veloxts/router`)
-
   - Add `NarrowingGuard` interface with phantom `_narrows` type
   - Add `authenticatedNarrow` and `hasRoleNarrow()` guards
   - Add `guardNarrow()` method to `ProcedureBuilder` for context narrowing
   - Enables `ctx.user` to be non-null after guard passes
 
   ### Phase 5: Documentation (`@veloxts/router`)
-
   - Document `.rest()` override patterns
   - Document `createRouter()` helper usage
   - Document `guardNarrow()` experimental API
@@ -1466,7 +1531,6 @@
 ### Patch Changes
 
 - Fix Prisma client generation in scaffolder
-
   - Added automatic Prisma client generation after dependency installation in create-velox-app
   - Fixed database template to validate DATABASE_URL environment variable
   - Added alpha release warning to all package READMEs

package/dist/index.d.ts

@@ -39,7 +39,7 @@
  */
 /** Router package version */
 export declare const ROUTER_VERSION: string;
-export type { AfterHandler, CompiledProcedure, ContextExtensions, ContextFactory, ExtendedContext, GuardLike, HttpMethod, InferProcedureContext, InferProcedureErrors, InferProcedureInput, InferProcedureOutput, Middleware, MiddlewareArgs, MiddlewareFunction, MiddlewareNext, MiddlewareResult, ParentResourceChain, ParentResourceConfig, PolicyActionLike, ProcedureCollection, ProcedureHandler, ProcedureHandlerArgs, ProcedureRecord, ProcedureType, RestRouteOverride, TransactionalOptions, } from './types.js';
+export type { AfterHandler, CheckFn, CompiledProcedure, ContextExtensions, ContextFactory, ExtendedContext, GuardLike, HttpMethod, InferProcedureContext, InferProcedureErrors, InferProcedureInput, InferProcedureOutput, Middleware, MiddlewareArgs, MiddlewareFunction, MiddlewareNext, MiddlewareResult, ParentResourceChain, ParentResourceConfig, PolicyActionLike, ProcedureCollection, ProcedureHandler, ProcedureHandlerArgs, ProcedureRecord, ProcedureType, RestRouteOverride, TransactionalOptions, } from './types.js';
 export { PROCEDURE_METHOD_MAP, } from './types.js';
 export type { GuardErrorResponse, RouterErrorCode } from './errors.js';
 export { GuardError, isGuardError } from './errors.js';
@@ -47,6 +47,8 @@ export type { DefineProceduresOptions, } from './procedure/builder.js';
 export { defineProcedures, executeProcedure, isCompiledProcedure, isProcedureCollection, procedure, procedures, } from './procedure/builder.js';
 export type { PipelineStep, RevertAction, StepOptions } from './procedure/pipeline.js';
 export { defineRevert, defineStep } from './procedure/pipeline.js';
+export type { RawResponse, RawResponseCookie, RawResponseCookieOptions, RawResponseOptions, RawResponseRedirect, } from './raw.js';
+export { isRawResponse, raw } from './raw.js';
 export { createProcedure, typedProcedure } from './procedure/factory.js';
 export type { BuilderRuntimeState, InferOutputSchema, InferProcedures, InferSchemaOutput, PostHandlerBuilder, ProcedureBuilder, ProcedureBuilderState, ProcedureDefinitions, ValidOutputSchema, ValidSchema, } from './procedure/types.js';
 export type { RouterResult } from './router-utils.js';

package/dist/index.js

@@ -52,6 +52,7 @@ export {
 defineProcedures, executeProcedure, isCompiledProcedure, isProcedureCollection, procedure, procedures, // Short alias for defineProcedures
  } from './procedure/builder.js';
 export { defineRevert, defineStep } from './procedure/pipeline.js';
+export { isRawResponse, raw } from './raw.js';
 // ============================================================================
 // Router Utilities
 // ============================================================================

package/dist/procedure/builder.js

@@ -169,6 +169,19 @@ function createBuilder(state) {
                 policyAction: action,
             });
         },
+        /**
+         * Adds a post-middleware authorization check.
+         *
+         * Runs after input validation, pipeline transforms, and middleware —
+         * immediately before the handler. Returning `false` throws ForbiddenError;
+         * throwing propagates as-is.
+         */
+        check(check) {
+            return createBuilder({
+                ...state,
+                checks: [...(state.checks ?? []), check],
+            });
+        },
         /**
          * Declares domain error classes this procedure may throw
          */
@@ -326,17 +339,26 @@ function compileProcedureOrBranching(type, handlerOrMap, state) {
  */
 function compileProcedure(type, handler, state) {
     const typedMiddlewares = state.middlewares;
+    // Wrap the handler with .check() invocations so checks run AFTER middleware.
+    // Wrapping at the handler level (rather than inserting a phase in
+    // executeProcedure) keeps the precompiled middleware executor intact and
+    // ensures checks see middleware-extended ctx + post-pipeline input.
+    const checks = state.checks;
+    const handlerWithChecks = checks && checks.length > 0 ? wrapHandlerWithChecks(handler, checks) : handler;
     // Pre-compile the middleware chain executor if middlewares exist
     // This avoids rebuilding the chain on every request
-    const precompiledExecutor = typedMiddlewares.length > 0 ? createMiddlewareExecutor(typedMiddlewares, handler) : undefined;
+    const precompiledExecutor = typedMiddlewares.length > 0
+        ? createMiddlewareExecutor(typedMiddlewares, handlerWithChecks)
+        : undefined;
     // Create the final procedure object with .useAfter() support
     return createPostHandlerBuilder({
         type,
-        handler,
+        handler: handlerWithChecks,
         inputSchema: state.inputSchema,
         outputSchema: state.outputSchema,
         middlewares: typedMiddlewares,
         guards: state.guards,
+        checks,
         restOverride: state.restOverride,
         deprecated: state.deprecated,
         deprecationMessage: state.deprecationMessage,
@@ -362,6 +384,25 @@ function compileProcedure(type, handler, state) {
         policyAction: state.policyAction,
     });
 }
+/**
+ * Wraps a handler with `.check()` predicates that run before the handler.
+ *
+ * Checks AND-compose with short-circuit. Returning `false` throws
+ * ForbiddenError; throwing inside a check propagates as-is.
+ *
+ * @internal
+ */
+function wrapHandlerWithChecks(handler, checks) {
+    return async ({ input, ctx }) => {
+        for (const check of checks) {
+            const passed = await check({ input, ctx });
+            if (!passed) {
+                throw new ForbiddenError('Authorization check failed');
+            }
+        }
+        return handler({ input, ctx });
+    };
+}
 /**
  * Compiles a Level 3 branched procedure with a handler map
  *
@@ -372,6 +413,16 @@ function compileProcedure(type, handler, state) {
  */
 function compileProcedureWithHandlerMap(type, dispatchHandler, handlerMap, state) {
     const typedMiddlewares = state.middlewares;
+    // Wrap each branched handler with .check() invocations (parallel to
+    // compileProcedure). The dispatch handler stays unwrapped because checks
+    // run inside the per-branch handlers.
+    const checks = state.checks;
+    const handlerMapWithChecks = checks && checks.length > 0
+        ? Object.fromEntries(Object.entries(handlerMap).map(([key, branchHandler]) => [
+            key,
+            wrapHandlerWithChecks(branchHandler, checks),
+        ]))
+        : handlerMap;
     return createPostHandlerBuilder({
         type,
         handler: dispatchHandler,
@@ -379,6 +430,7 @@ function compileProcedureWithHandlerMap(type, dispatchHandler, handlerMap, state
         outputSchema: undefined, // Level 3 uses resource schema projection, not Zod output validation
         middlewares: typedMiddlewares,
         guards: [], // Guards come from access level config
+        checks,
         restOverride: state.restOverride,
         deprecated: state.deprecated,
         deprecationMessage: state.deprecationMessage,
@@ -388,7 +440,7 @@ function compileProcedureWithHandlerMap(type, dispatchHandler, handlerMap, state
         _precompiledExecutor: undefined, // Branched procedures don't use precompiled chains
         _resourceSchema: state.resourceSchema,
         _resourceLevel: undefined, // No fixed level — determined at runtime by branch selection
-        _handlerMap: handlerMap,
+        _handlerMap: handlerMapWithChecks,
         // Store error classes declared via .throws()
         errorClasses: state.errorClasses,
         // Store transactional configuration

package/dist/procedure/types.d.ts

@@ -12,7 +12,7 @@
 import type { BaseContext, DomainError } from '@veloxts/core';
 import type { ZodType } from 'zod';
 import type { OutputForLevel, ResourceSchema, TaggedResourceSchema } from '../resource/index.js';
-import type { AfterHandler, CompiledProcedure, GuardLike, MiddlewareFunction, ParentResourceConfig, PolicyActionLike, ProcedureHandler, RestRouteOverride, TransactionalOptions } from '../types.js';
+import type { AfterHandler, CheckFn, CompiledProcedure, GuardLike, MiddlewareFunction, ParentResourceConfig, PolicyActionLike, ProcedureHandler, RestRouteOverride, TransactionalOptions } from '../types.js';
 import type { PipelineStep } from './pipeline.js';
 /**
  * Internal state type that accumulates type information through the builder chain
@@ -257,6 +257,41 @@ export interface ProcedureBuilder<TInput = unknown, TOutput = unknown, TContext
     policy<TResourceName extends string>(action: string extends TResourceName ? PolicyActionLike<unknown, unknown, TResourceName> : Uncapitalize<TResourceName> extends keyof TContext ? PolicyActionLike<unknown, unknown, TResourceName> : PolicyActionLike<unknown, unknown, TResourceName> & {
         _contextMissing: `Add .use() middleware to provide '${Uncapitalize<TResourceName>}' in context before .policy()`;
     }): ProcedureBuilder<TInput, TOutput, TContext, TErrors>;
+    /**
+     * Adds a post-middleware authorization check.
+     *
+     * `.check()` runs AFTER input validation, AFTER `.through()` pipeline
+     * transforms, and AFTER all `.use()` middleware have populated the context
+     * — immediately before the handler. Use it for authorization that depends
+     * on input fields and/or context values populated by middleware (e.g.
+     * resource ownership where the resource was loaded by a preceding `.use()`).
+     *
+     * Returning `false` throws a `ForbiddenError` (403). Throwing inside the
+     * function propagates the original error so callers can throw custom
+     * errors with finer-grained status codes.
+     *
+     * Multiple `.check()` calls AND-compose with short-circuit on first failure.
+     *
+     * **When to use which:**
+     * - `.guard(authenticated)` — pre-input, ctx-only authentication (fast-fail).
+     * - `.policy(PostPolicy.update)` — declarative resource-policy authorization.
+     * - `.check(({ input, ctx }) => ...)` — ad-hoc authorization that needs
+     *   both `input` and middleware-extended `ctx`.
+     *
+     * @param check - Post-middleware authorization predicate
+     * @returns Same builder (no type changes)
+     *
+     * @example
+     * ```typescript
+     * procedure()
+     *   .input(z.object({ sessionId: z.string() }))
+     *   .guard(authenticated)
+     *   .use(loadParticipant) // adds ctx.participant
+     *   .check(({ input, ctx }) => ctx.participant.sessionId === input.sessionId)
+     *   .query(handler);
+     * ```
+     */
+    check(check: CheckFn<TInput, TContext>): ProcedureBuilder<TInput, TOutput, TContext, TErrors>;
     /**
      * Declares domain error classes that this procedure may throw
      *
@@ -627,6 +662,8 @@ export interface BuilderRuntimeState {
     pipelineSteps?: PipelineStep[];
     /** Policy action reference for declarative authorization */
     policyAction?: PolicyActionLike;
+    /** Post-middleware checks declared via .check() */
+    checks?: CheckFn[];
 }
 /**
  * Type for the procedures object passed to defineProcedures

package/dist/raw.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Raw response primitive for procedures
+ *
+ * Lets procedure handlers return non-JSON HTTP responses (redirects, cookies,
+ * custom headers, raw bodies, streams) without bypassing the procedure system.
+ *
+ * Returning a `RawResponse` from a procedure handler tells the REST adapter
+ * to apply the response settings to Fastify's `reply` and skip the default
+ * JSON serialization path.
+ *
+ * Procedures using `raw()` typically omit `.output()` since the response
+ * body isn't a JSON-serialized DTO. Their OpenAPI documentation is generated
+ * without a response schema (valid OpenAPI for raw responses).
+ *
+ * @example OAuth callback (replaces a raw `fastify.get(...)` route)
+ * ```typescript
+ * import { procedure, raw } from '@veloxts/router';
+ *
+ * export const oauthProcedures = procedures('oauth', {
+ *   authorize: procedure()
+ *     .rest({ method: 'GET', path: '/auth/atlassian' })
+ *     .query(async ({ ctx }) => {
+ *       const { url, state, codeVerifier } = provider.buildAuthorizeUrl();
+ *       return raw({
+ *         cookies: [
+ *           { name: 'oauth_state', value: pack(state, codeVerifier), options: { httpOnly: true } },
+ *         ],
+ *         redirect: { url, status: 302 },
+ *       });
+ *     }),
+ * });
+ * ```
+ *
+ * @example File download
+ * ```typescript
+ * import { createReadStream } from 'node:fs';
+ *
+ * download: procedure()
+ *   .input(z.object({ id: z.string() }))
+ *   .query(async ({ input }) => raw({
+ *     status: 200,
+ *     headers: {
+ *       'Content-Type': 'application/octet-stream',
+ *       'Content-Disposition': `attachment; filename="${input.id}.bin"`,
+ *     },
+ *     body: createReadStream(`/storage/${input.id}.bin`),
+ *   }));
+ * ```
+ *
+ * @module raw
+ */
+import type { Readable } from 'node:stream';
+/** Brand identifying a `RawResponse` returned from `raw()`. */
+declare const RAW_RESPONSE_BRAND = "__velox_raw_response__";
+/**
+ * Cookie options accepted by `RawResponse.cookies`.
+ *
+ * Mirrors `@fastify/cookie`'s `CookieSerializeOptions` shape but kept as a
+ * plain interface so this module has no hard dependency on `@fastify/cookie`.
+ * Procedures using `cookies` require that plugin to be registered (see
+ * `@veloxts/auth` template for the standard wiring).
+ */
+export interface RawResponseCookieOptions {
+    domain?: string;
+    expires?: Date;
+    httpOnly?: boolean;
+    maxAge?: number;
+    path?: string;
+    priority?: 'low' | 'medium' | 'high';
+    sameSite?: 'lax' | 'none' | 'strict' | boolean;
+    secure?: boolean | 'auto';
+    signed?: boolean;
+}
+/** Cookie to set on the response. */
+export interface RawResponseCookie {
+    /** Cookie name. */
+    readonly name: string;
+    /** Cookie value (string only — caller is responsible for encoding). */
+    readonly value: string;
+    /** Optional cookie attributes (max-age, httpOnly, secure, etc.). */
+    readonly options?: RawResponseCookieOptions;
+}
+/** Redirect descriptor. */
+export interface RawResponseRedirect {
+    /** Absolute or relative URL to redirect to. */
+    readonly url: string;
+    /**
+     * HTTP redirect status. Defaults to `302` (Found).
+     * Use `303` for POST → GET redirects, `307`/`308` to preserve method+body.
+     */
+    readonly status?: 301 | 302 | 303 | 307 | 308;
+}
+/**
+ * Options accepted by `raw()`. All fields optional — a bare `raw({})`
+ * sends an empty 200 response.
+ */
+export interface RawResponseOptions {
+    /**
+     * HTTP status code. Defaults to `200`. Ignored when `redirect` is set
+     * (the redirect's `status` wins).
+     */
+    status?: number;
+    /** Headers to set on the response. */
+    headers?: Record<string, string>;
+    /**
+     * Cookies to set via `reply.setCookie`. Requires `@fastify/cookie` to be
+     * registered on the Fastify instance.
+     */
+    cookies?: ReadonlyArray<RawResponseCookie>;
+    /** Redirect to a URL. When set, `body` is ignored. */
+    redirect?: RawResponseRedirect;
+    /**
+     * Response body. Strings, Buffers, and Node streams are sent as-is via
+     * `reply.send()` so the caller controls Content-Type via `headers`.
+     * Plain objects are NOT serialized — use a regular `.output()` schema for
+     * JSON responses.
+     */
+    body?: string | Buffer | Readable;
+}
+/**
+ * Branded raw-response object returned by `raw()`. The REST adapter detects
+ * this brand and applies the contained settings to Fastify's `reply`.
+ */
+export interface RawResponse extends RawResponseOptions {
+    readonly [RAW_RESPONSE_BRAND]: true;
+}
+/**
+ * Create a raw HTTP response from a procedure handler.
+ *
+ * The returned object is a branded marker — its presence tells the REST
+ * adapter to bypass JSON serialization and apply headers/cookies/redirect/body
+ * directly to the Fastify reply.
+ *
+ * @param options - Response settings. All fields optional.
+ * @returns A `RawResponse` to return from a `.query()` or `.mutation()` handler.
+ *
+ * @example
+ * ```typescript
+ * .query(async ({ ctx }) => raw({
+ *   cookies: [{ name: 'session', value: token, options: { httpOnly: true } }],
+ *   redirect: { url: '/dashboard', status: 302 },
+ * }))
+ * ```
+ */
+export declare function raw(options?: RawResponseOptions): RawResponse;
+/**
+ * Type guard: returns true when `value` is a `RawResponse` produced by `raw()`.
+ *
+ * Verifies via a private WeakSet — checking the brand key alone would let
+ * user-controlled JSON forge raw responses if echoed by a handler. Values
+ * constructed in another realm (Worker, vm) won't be in this realm's
+ * registry; that's intentional — if you need cross-realm raw responses,
+ * call `raw()` on the realm that owns the REST adapter.
+ *
+ * Used by the REST adapter to short-circuit JSON serialization. Exported for
+ * advanced cases (custom adapters, testing) — most users don't need it.
+ */
+export declare function isRawResponse(value: unknown): value is RawResponse;
+export {};

package/dist/raw.js

@@ -0,0 +1,52 @@
+/** Brand identifying a `RawResponse` returned from `raw()`. */
+const RAW_RESPONSE_BRAND = '__velox_raw_response__';
+/**
+ * WeakSet of objects produced by `raw()`. Used by `isRawResponse` to verify
+ * that a value originated from this module rather than just carrying the
+ * brand key. Defeats forgery attempts where a procedure handler echoes
+ * user-controlled JSON containing `__velox_raw_response__: true` (e.g. a
+ * generic echo handler returning `request.body` verbatim) — without this
+ * registry, such a payload could trigger an unintended redirect or cookie
+ * set via the REST adapter's short-circuit.
+ *
+ * @internal
+ */
+const rawInstances = new WeakSet();
+/**
+ * Create a raw HTTP response from a procedure handler.
+ *
+ * The returned object is a branded marker — its presence tells the REST
+ * adapter to bypass JSON serialization and apply headers/cookies/redirect/body
+ * directly to the Fastify reply.
+ *
+ * @param options - Response settings. All fields optional.
+ * @returns A `RawResponse` to return from a `.query()` or `.mutation()` handler.
+ *
+ * @example
+ * ```typescript
+ * .query(async ({ ctx }) => raw({
+ *   cookies: [{ name: 'session', value: token, options: { httpOnly: true } }],
+ *   redirect: { url: '/dashboard', status: 302 },
+ * }))
+ * ```
+ */
+export function raw(options = {}) {
+    const response = { ...options, [RAW_RESPONSE_BRAND]: true };
+    rawInstances.add(response);
+    return response;
+}
+/**
+ * Type guard: returns true when `value` is a `RawResponse` produced by `raw()`.
+ *
+ * Verifies via a private WeakSet — checking the brand key alone would let
+ * user-controlled JSON forge raw responses if echoed by a handler. Values
+ * constructed in another realm (Worker, vm) won't be in this realm's
+ * registry; that's intentional — if you need cross-realm raw responses,
+ * call `raw()` on the realm that owns the REST adapter.
+ *
+ * Used by the REST adapter to short-circuit JSON serialization. Exported for
+ * advanced cases (custom adapters, testing) — most users don't need it.
+ */
+export function isRawResponse(value) {
+    return typeof value === 'object' && value !== null && rawInstances.has(value);
+}

package/dist/rest/adapter.js

@@ -10,6 +10,7 @@
 import { ConfigurationError, createLogger } from '@veloxts/core';
 const log = createLogger('router');
 import { executeProcedure } from '../procedure/builder.js';
+import { isRawResponse } from '../raw.js';
 import { buildMultiLevelNestedPath, buildNestedRestPath, buildRestPath, calculateNestingDepth, parseNamingConvention, } from './naming.js';
 import { registerCollections } from './registry.js';
 /** Default nesting depth threshold for warnings */
@@ -176,6 +177,10 @@ function createRouteHandler(route) {
         const ctx = getContextFromRequest(request);
         // Execute the procedure
         const result = await executeProcedure(route.procedure, input, ctx);
+        // Short-circuit on raw responses (redirects, cookies, custom headers/body)
+        if (isRawResponse(result)) {
+            return applyRawResponse(reply, result);
+        }
         // Set appropriate HTTP status codes based on method and result
         switch (route.method) {
             case 'POST':
@@ -196,6 +201,44 @@ function createRouteHandler(route) {
         return result;
     };
 }
+/**
+ * Apply a `RawResponse` to a Fastify reply.
+ *
+ * Sets headers, cookies, status, and either redirects or sends the body.
+ * Returns the reply so Fastify treats the request as handled (no implicit
+ * JSON serialization of the return value).
+ *
+ * Cookies require `@fastify/cookie` to be registered on the Fastify instance —
+ * we cast through `unknown` to avoid a hard dependency on that plugin's types.
+ *
+ * @internal
+ */
+function applyRawResponse(reply, response) {
+    if (response.headers) {
+        for (const [name, value] of Object.entries(response.headers)) {
+            reply.header(name, value);
+        }
+    }
+    if (response.cookies && response.cookies.length > 0) {
+        const replyWithCookie = reply;
+        if (typeof replyWithCookie.setCookie !== 'function') {
+            throw new ConfigurationError('raw().cookies requires @fastify/cookie to be registered on the Fastify instance.');
+        }
+        for (const cookie of response.cookies) {
+            replyWithCookie.setCookie(cookie.name, cookie.value, cookie.options);
+        }
+    }
+    if (response.redirect) {
+        return reply.redirect(response.redirect.url, response.redirect.status ?? 302);
+    }
+    if (response.status !== undefined) {
+        reply.status(response.status);
+    }
+    if (response.body !== undefined) {
+        return reply.send(response.body);
+    }
+    return reply.send();
+}
 /**
  * Type guard to check if a value is a plain object
  */

package/dist/types.d.ts

@@ -221,6 +221,32 @@ export type MiddlewareFunction<TInput, TContext extends BaseContext = BaseContex
  * ```
  */
 export type Middleware<TContext extends BaseContext = BaseContext> = MiddlewareFunction<unknown, TContext, TContext>;
+/**
+ * Post-middleware authorization check.
+ *
+ * Runs AFTER input validation, AFTER pipeline transforms, and AFTER all
+ * `.use()` middleware has populated the context — but BEFORE the handler.
+ * Use `.check()` for authorization that depends on input fields and/or
+ * context values populated by middleware (e.g. resource ownership checks
+ * where ctx.participant was loaded by `.use(loadParticipant)`).
+ *
+ * Returning `false` throws a `ForbiddenError` (403). Throwing inside the
+ * function propagates the original error so callers can throw custom
+ * domain errors with finer-grained status codes.
+ *
+ * Multiple `.check()` calls AND-compose with short-circuit on first failure.
+ *
+ * Distinguished from `.guard()`: guards are pre-input, ctx-only, fast-fail
+ * authentication checks. Checks are post-middleware authorization that can
+ * read input.
+ *
+ * @template TInput - The validated input type
+ * @template TContext - The context type (post-middleware extensions)
+ */
+export type CheckFn<TInput = unknown, TContext extends BaseContext = BaseContext> = (args: {
+    input: TInput;
+    ctx: TContext;
+}) => boolean | Promise<boolean>;
 /**
  * REST route override configuration
  *
@@ -325,6 +351,14 @@ export interface CompiledProcedure<TInput = unknown, TOutput = unknown, TContext
     readonly middlewares: ReadonlyArray<MiddlewareFunction<TInput, TContext, TContext, TOutput>>;
     /** Guards to execute before handler (checked before middleware) */
     readonly guards: ReadonlyArray<GuardLike<TContext>>;
+    /**
+     * Post-middleware authorization checks (registered via `.check()`).
+     *
+     * Run after input validation, pipeline transforms, and all middleware
+     * have populated the context — immediately before the handler. Returning
+     * `false` throws ForbiddenError (403); throwing propagates as-is.
+     */
+    readonly checks?: ReadonlyArray<CheckFn<TInput, TContext>>;
     /** REST route override (if specified) */
     readonly restOverride?: RestRouteOverride;
     /** Whether this procedure is deprecated */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@veloxts/router",
-  "version": "0.8.3",
+  "version": "0.9.0",
   "description": "Procedure definitions with tRPC and REST routing for VeloxTS framework",
   "type": "module",
   "main": "dist/index.js",
@@ -39,10 +39,11 @@
   "dependencies": {
     "@trpc/server": "11.16.0",
     "fastify": "5.8.5",
-    "@veloxts/core": "0.8.3",
-    "@veloxts/validation": "0.8.3"
+    "@veloxts/core": "0.9.0",
+    "@veloxts/validation": "0.9.0"
   },
   "devDependencies": {
+    "@fastify/cookie": "11.0.2",
     "@vitest/coverage-v8": "4.1.5",
     "esbuild": "0.28.0",
     "typescript": "5.9.3",