actor-gate 0.1.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "actor-gate",
-  "version": "0.1.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/index.d.ts

@@ -1 +1,2 @@
 export { withExpressProtectedRoute, type ExpressProtectedAuth, type ExpressProtectedRouteContext, type ExpressRequestLike, type ExpressResponseLike, type WithExpressProtectedRouteOptions, } from './protected-route';
+export { buildProtectedRouteSession, buildProtectedRouteSessionWithMeta, type ProtectedRouteSession, type ProtectedRouteSessionWithMeta, } from '../shared/protected-route-session';

package/src/express/index.js

@@ -1 +1,2 @@
 export { withExpressProtectedRoute, } from './protected-route';
+export { buildProtectedRouteSession, buildProtectedRouteSessionWithMeta, } from '../shared/protected-route-session';

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/index.d.ts

@@ -1,5 +1,6 @@
 export declare const SUPPORTED_NEXT_ROUTERS: readonly ["pages", "app"];
 export type SupportedNextRouter = (typeof SUPPORTED_NEXT_ROUTERS)[number];
+export { buildProtectedRouteSession, buildProtectedRouteSessionWithMeta, type ProtectedRouteSession, type ProtectedRouteSessionWithMeta, } from '../shared/protected-route-session';
 export * from './pages/index';
 export * from './app/index';
 export * from './shared/auth-routes';

package/src/next/index.js

@@ -1,4 +1,5 @@
 export const SUPPORTED_NEXT_ROUTERS = ['pages', 'app'];
+export { buildProtectedRouteSession, buildProtectedRouteSessionWithMeta, } from '../shared/protected-route-session';
 export * from './pages/index';
 export * from './app/index';
 export * from './shared/auth-routes';

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({

package/src/shared/protected-route-session.d.ts

@@ -0,0 +1,34 @@
+import { type AuthServiceErrorCode } from '../core/services/auth-error';
+import type { ValidatedAccessTokenResult } from '../core/services/contracts';
+import type { AuthActor } from '../core/types/auth-contract';
+type SessionMetaValue<TServerSessionData extends {
+    meta?: unknown;
+}> = Exclude<TServerSessionData['meta'], undefined | null>;
+export type ProtectedRouteSession<TSessionId, TUserId, TActor extends AuthActor = AuthActor, TServerSessionData extends Record<string, unknown> = Record<string, never>> = {
+    sessionId: TSessionId;
+    userId: TUserId;
+    actor: TActor;
+    issuedAt: number;
+    expiresAt: number;
+    serverSessionData?: TServerSessionData;
+};
+export type ProtectedRouteSessionWithMeta<TSessionId, TUserId, TActor extends AuthActor = AuthActor, TServerSessionData extends Record<string, unknown> & {
+    meta?: unknown;
+} = {
+    meta?: unknown;
+}> = ProtectedRouteSession<TSessionId, TUserId, TActor, TServerSessionData> & {
+    serverSessionData: TServerSessionData & {
+        meta: SessionMetaValue<TServerSessionData>;
+    };
+    meta: SessionMetaValue<TServerSessionData>;
+};
+export declare function buildProtectedRouteSession<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>>(auth: ValidatedAccessTokenResult<TSessionId, TUserId, TActor, TServerSessionData, TClientSessionData, TExtClaims>): ProtectedRouteSession<TSessionId, TUserId, TActor, TServerSessionData>;
+export declare function buildProtectedRouteSessionWithMeta<TSessionId, TUserId, TActor extends AuthActor = AuthActor, TServerSessionData extends Record<string, unknown> & {
+    meta?: unknown;
+} = {
+    meta?: unknown;
+}, TClientSessionData extends Record<string, unknown> = Record<string, never>, TExtClaims extends Record<string, unknown> = Record<string, never>>(auth: ValidatedAccessTokenResult<TSessionId, TUserId, TActor, TServerSessionData, TClientSessionData, TExtClaims>, options?: {
+    errorCode?: AuthServiceErrorCode;
+    errorMessage?: string;
+}): ProtectedRouteSessionWithMeta<TSessionId, TUserId, TActor, TServerSessionData>;
+export {};

package/src/shared/protected-route-session.js

@@ -0,0 +1,33 @@
+import { AuthServiceError, } from '../core/services/auth-error';
+function buildMissingMetaError(options) {
+    return new AuthServiceError({
+        code: options?.errorCode ?? 'unauthorized',
+        message: options?.errorMessage ?? 'Authenticated session metadata is missing.',
+    });
+}
+export function buildProtectedRouteSession(auth) {
+    const session = auth.session;
+    return {
+        sessionId: auth.authContext.sessionId,
+        userId: auth.authContext.userId,
+        actor: auth.claims.actor,
+        issuedAt: session?.issuedAt ?? auth.claims.iat,
+        expiresAt: session?.expiresAt ?? auth.claims.exp,
+        ...(session?.serverSessionData === undefined
+            ? {}
+            : { serverSessionData: session.serverSessionData }),
+    };
+}
+export function buildProtectedRouteSessionWithMeta(auth, options) {
+    const session = buildProtectedRouteSession(auth);
+    const serverSessionData = session.serverSessionData;
+    const meta = serverSessionData?.meta;
+    if (meta === undefined || meta === null) {
+        throw buildMissingMetaError(options);
+    }
+    return {
+        ...session,
+        serverSessionData: serverSessionData,
+        meta: meta,
+    };
+}