actor-gate 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "actor-gate",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Schema-agnostic Next.js auth library for direct and MCP authentication flows.",
   "type": "module",
   "private": false,

package/src/express/protected-route.d.ts

@@ -40,5 +40,15 @@ export type WithExpressProtectedRouteOptions<TSessionId, TUserId, TActor extends
         resourceMetadataUrl?: string;
     };
 };
+/**
+ * Wraps an Express route with access-token authentication and standardized
+ * auth/system error responses.
+ *
+ * Handler output behavior:
+ * - Return a non-`undefined` value to send `200` with `res.json(output)`.
+ * - Return `undefined` to send `204`.
+ * - If your handler already committed the response (for example via
+ *   `res.status(...).json(...)`), this wrapper does not overwrite it.
+ */
 export declare function withExpressProtectedRoute<TSessionId, TUserId, TActor extends AuthActor = AuthActor, TServerSessionData extends Record<string, unknown> = Record<string, never>, TClientSessionData extends Record<string, unknown> = Record<string, never>, TExtClaims extends Record<string, unknown> = Record<string, never>, TReq extends ExpressRequestLike = ExpressRequestLike, TRes extends ExpressResponseLike = ExpressResponseLike, TOutput = unknown>(options: WithExpressProtectedRouteOptions<TSessionId, TUserId, TActor, TServerSessionData, TClientSessionData, TExtClaims, TReq, TRes, TOutput>): (req: TReq, res: TRes) => Promise<void>;
 export {};

package/src/express/protected-route.js

@@ -37,6 +37,16 @@ function sendExpressAuthError(res, error, input) {
     }
     res.status(built.statusCode).json(built.body);
 }
+/**
+ * Wraps an Express route with access-token authentication and standardized
+ * auth/system error responses.
+ *
+ * Handler output behavior:
+ * - Return a non-`undefined` value to send `200` with `res.json(output)`.
+ * - Return `undefined` to send `204`.
+ * - If your handler already committed the response (for example via
+ *   `res.status(...).json(...)`), this wrapper does not overwrite it.
+ */
 export function withExpressProtectedRoute(options) {
     const authorizationHeaderName = options.authorizationHeaderName ?? 'authorization';
     const requestIdHeaderName = options.requestIdHeaderName ?? 'x-request-id';

package/src/next/app/protected-route.d.ts

@@ -24,4 +24,13 @@ export type WithAppProtectedRouteOptions<TSessionId, TUserId, TActor extends Aut
     authorizationHeaderName?: string;
     challenge?: WithAppAuthRouteOptions<TOutput>['challenge'];
 };
+/**
+ * Wraps a Next.js App Router handler with access-token authentication and
+ * standardized auth/system error handling.
+ *
+ * Handler output behavior:
+ * - Return a `Response` to fully control the HTTP response.
+ * - Return a non-`undefined` non-`Response` value to send `200` JSON.
+ * - Return `undefined` to send `204`.
+ */
 export declare function withAppProtectedRoute<TSessionId, TUserId, TActor extends AuthActor = AuthActor, TServerSessionData extends Record<string, unknown> = Record<string, never>, TClientSessionData extends Record<string, unknown> = Record<string, never>, TExtClaims extends Record<string, unknown> = Record<string, never>, TOutput = unknown>(options: WithAppProtectedRouteOptions<TSessionId, TUserId, TActor, TServerSessionData, TClientSessionData, TExtClaims, TOutput>): (req: Request) => Promise<Response>;

package/src/next/app/protected-route.js

@@ -1,6 +1,15 @@
 import { AuthServiceError } from '../../core/services/auth-error';
 import { assertBearerOnlyActorPolicy, resolveAccessTokenTransportAdapter, } from '../shared/direct-auth-utils';
 import { withAppAuthRoute } from './wrapper';
+/**
+ * Wraps a Next.js App Router handler with access-token authentication and
+ * standardized auth/system error handling.
+ *
+ * Handler output behavior:
+ * - Return a `Response` to fully control the HTTP response.
+ * - Return a non-`undefined` non-`Response` value to send `200` JSON.
+ * - Return `undefined` to send `204`.
+ */
 export function withAppProtectedRoute(options) {
     const accessTokenTransportAdapter = resolveAccessTokenTransportAdapter(options.accessTokenTransport);
     return withAppAuthRoute({

package/src/next/pages/protected-route.d.ts

@@ -25,4 +25,14 @@ export type WithPagesProtectedRouteOptions<TSessionId, TUserId, TActor extends A
     authorizationHeaderName?: string;
     challenge?: WithPagesAuthRouteOptions<TOutput>['challenge'];
 };
+/**
+ * Wraps a Next.js Pages API route with access-token authentication and
+ * standardized auth/system error handling.
+ *
+ * Handler output behavior:
+ * - Return a non-`undefined` value to send `200` with `res.json(output)`.
+ * - Return `undefined` to send `204`.
+ * - If your handler already finished the response (for example by calling
+ *   `res.status(...).json(...)` directly), the wrapper does not overwrite it.
+ */
 export declare function withPagesProtectedRoute<TSessionId, TUserId, TActor extends AuthActor = AuthActor, TServerSessionData extends Record<string, unknown> = Record<string, never>, TClientSessionData extends Record<string, unknown> = Record<string, never>, TExtClaims extends Record<string, unknown> = Record<string, never>, TOutput = unknown>(options: WithPagesProtectedRouteOptions<TSessionId, TUserId, TActor, TServerSessionData, TClientSessionData, TExtClaims, TOutput>): NextApiHandler;

package/src/next/pages/protected-route.js

@@ -1,6 +1,16 @@
 import { AuthServiceError } from '../../core/services/auth-error';
 import { assertBearerOnlyActorPolicy, resolveAccessTokenTransportAdapter, } from '../shared/direct-auth-utils';
 import { withPagesAuthRoute } from './wrapper';
+/**
+ * Wraps a Next.js Pages API route with access-token authentication and
+ * standardized auth/system error handling.
+ *
+ * Handler output behavior:
+ * - Return a non-`undefined` value to send `200` with `res.json(output)`.
+ * - Return `undefined` to send `204`.
+ * - If your handler already finished the response (for example by calling
+ *   `res.status(...).json(...)` directly), the wrapper does not overwrite it.
+ */
 export function withPagesProtectedRoute(options) {
     const accessTokenTransportAdapter = resolveAccessTokenTransportAdapter(options.accessTokenTransport);
     return withPagesAuthRoute({