@forklaunch/core 1.3.6 → 1.3.8

package/lib/{apiDefinition.types-CN-qa49j.d.mts → apiDefinition.types-CtTiIWvC.d.mts}

@@ -189,25 +189,16 @@ type RoleSet = {
 } | {
     readonly forbiddenRoles: Set<string>;
 };
-/** Auth base for authenticated routes — JWT/Basic, no RBAC. */
-type AuthenticatedAuthBase = TokenOptions & {
-    readonly decodeResource?: DecodeResource;
+/** Constraints that forbid RBAC fields on authenticated routes. */
+type NoRbacConstraint = {
     readonly allowedPermissions?: never;
     readonly forbiddenPermissions?: never;
     readonly allowedRoles?: never;
     readonly forbiddenRoles?: never;
-} & (BasicAuthMethods | JwtAuthMethods);
-/** Auth base for protected routes — JWT/Basic with required RBAC. */
-type ProtectedAuthBase = TokenOptions & {
-    readonly decodeResource?: DecodeResource;
-} & (PermissionSet | RoleSet) & (BasicAuthMethods | JwtAuthMethods);
-/**
- * @deprecated Use AccessAuth discriminated union instead.
- * Kept for backwards compatibility with AuthMethods.
- */
+};
 type AuthMethodsBase = TokenOptions & (HmacMethods | ({
     readonly decodeResource?: DecodeResource;
-} & ((PermissionSet & (BasicAuthMethods | JwtAuthMethods)) | (RoleSet & (BasicAuthMethods | JwtAuthMethods)) | (BasicAuthMethods | JwtAuthMethods))));
+} & (BasicAuthMethods | JwtAuthMethods)));
 /**
  * Route access level — determines authentication and authorization requirements.
  *
@@ -222,6 +213,7 @@ type AccessLevel = 'public' | 'authenticated' | 'protected' | 'internal';
  * - `public`: auth not allowed
  * - `authenticated`: JWT/Basic auth required, RBAC fields disallowed
  * - `protected`: auth required, must include at least one RBAC declaration
+ *   (surfacing functions are optional here — they can be provided at router/app level)
  * - `internal`: auth required, must be HMAC
  */
 type AccessAuth<Auth> = {
@@ -229,10 +221,10 @@ type AccessAuth<Auth> = {
     readonly auth?: never;
 } | {
     readonly access: 'authenticated';
-    readonly auth?: Auth & AuthenticatedAuthBase;
+    readonly auth?: Auth & NoRbacConstraint;
 } | {
     readonly access: 'protected';
-    readonly auth: Auth & ProtectedAuthBase & ({
+    readonly auth: Auth & ({
         readonly allowedPermissions: Set<string>;
     } | {
         readonly forbiddenPermissions: Set<string>;
@@ -255,25 +247,25 @@ type SchemaAuthMethods<SV extends AnySchemaValidator, ParamsSchema extends Param
     readonly requiredScope?: string;
     readonly scopeHeirarchy?: string[];
     readonly surfaceScopes?: ExpressLikeSchemaAuthMapper<SV, ParamsSchema, ReqBody, QuerySchema, ReqHeaders, VersionedApi, SessionObject<SV>, BaseRequest>;
-    readonly requiredFeatures?: string[];
-    readonly requireActiveSubscription?: boolean;
-} & ({
     readonly surfacePermissions?: ExpressLikeSchemaAuthMapper<SV, ParamsSchema, ReqBody, QuerySchema, ReqHeaders, VersionedApi, SessionObject<SV>, BaseRequest>;
-} | {
     readonly surfaceRoles?: ExpressLikeSchemaAuthMapper<SV, ParamsSchema, ReqBody, QuerySchema, ReqHeaders, VersionedApi, SessionObject<SV>, BaseRequest>;
-});
+    readonly requiredFeatures?: string[];
+    readonly requireActiveSubscription?: boolean;
+};
 type AuthMethods<SV extends AnySchemaValidator, P extends ParamsDictionary, ReqBody extends Record<string, unknown>, ReqQuery extends Record<string, unknown>, ReqHeaders extends Record<string, string>, VersionedReqs extends VersionedRequests, BaseRequest> = AuthMethodsBase & {
     readonly sessionSchema?: SessionObject<SV>;
     readonly requiredScope?: string;
     readonly scopeHeirarchy?: string[];
     readonly surfaceScopes?: ExpressLikeAuthMapper<SV, P, ReqBody, ReqQuery, ReqHeaders, VersionedReqs, SessionObject<SV>, BaseRequest>;
-    readonly requiredFeatures?: string[];
-    readonly requireActiveSubscription?: boolean;
-} & (({
     readonly surfacePermissions?: ExpressLikeAuthMapper<SV, P, ReqBody, ReqQuery, ReqHeaders, VersionedReqs, SessionObject<SV>, BaseRequest>;
-} & PermissionSet) | ({
     readonly surfaceRoles?: ExpressLikeAuthMapper<SV, P, ReqBody, ReqQuery, ReqHeaders, VersionedReqs, SessionObject<SV>, BaseRequest>;
-} & RoleSet));
+    readonly allowedPermissions?: Set<string>;
+    readonly forbiddenPermissions?: Set<string>;
+    readonly allowedRoles?: Set<string>;
+    readonly forbiddenRoles?: Set<string>;
+    readonly requiredFeatures?: string[];
+    readonly requireActiveSubscription?: boolean;
+};
 /**
  * Type representing a mapped schema.
  *s ParamsDictionary,

package/lib/{apiDefinition.types-CAOGkjXe.d.ts → apiDefinition.types-fBjxhhaM.d.ts}

@@ -189,25 +189,16 @@ type RoleSet = {
 } | {
     readonly forbiddenRoles: Set<string>;
 };
-/** Auth base for authenticated routes — JWT/Basic, no RBAC. */
-type AuthenticatedAuthBase = TokenOptions & {
-    readonly decodeResource?: DecodeResource;
+/** Constraints that forbid RBAC fields on authenticated routes. */
+type NoRbacConstraint = {
     readonly allowedPermissions?: never;
     readonly forbiddenPermissions?: never;
     readonly allowedRoles?: never;
     readonly forbiddenRoles?: never;
-} & (BasicAuthMethods | JwtAuthMethods);
-/** Auth base for protected routes — JWT/Basic with required RBAC. */
-type ProtectedAuthBase = TokenOptions & {
-    readonly decodeResource?: DecodeResource;
-} & (PermissionSet | RoleSet) & (BasicAuthMethods | JwtAuthMethods);
-/**
- * @deprecated Use AccessAuth discriminated union instead.
- * Kept for backwards compatibility with AuthMethods.
- */
+};
 type AuthMethodsBase = TokenOptions & (HmacMethods | ({
     readonly decodeResource?: DecodeResource;
-} & ((PermissionSet & (BasicAuthMethods | JwtAuthMethods)) | (RoleSet & (BasicAuthMethods | JwtAuthMethods)) | (BasicAuthMethods | JwtAuthMethods))));
+} & (BasicAuthMethods | JwtAuthMethods)));
 /**
  * Route access level — determines authentication and authorization requirements.
  *
@@ -222,6 +213,7 @@ type AccessLevel = 'public' | 'authenticated' | 'protected' | 'internal';
  * - `public`: auth not allowed
  * - `authenticated`: JWT/Basic auth required, RBAC fields disallowed
  * - `protected`: auth required, must include at least one RBAC declaration
+ *   (surfacing functions are optional here — they can be provided at router/app level)
  * - `internal`: auth required, must be HMAC
  */
 type AccessAuth<Auth> = {
@@ -229,10 +221,10 @@ type AccessAuth<Auth> = {
     readonly auth?: never;
 } | {
     readonly access: 'authenticated';
-    readonly auth?: Auth & AuthenticatedAuthBase;
+    readonly auth?: Auth & NoRbacConstraint;
 } | {
     readonly access: 'protected';
-    readonly auth: Auth & ProtectedAuthBase & ({
+    readonly auth: Auth & ({
         readonly allowedPermissions: Set<string>;
     } | {
         readonly forbiddenPermissions: Set<string>;
@@ -255,25 +247,25 @@ type SchemaAuthMethods<SV extends AnySchemaValidator, ParamsSchema extends Param
     readonly requiredScope?: string;
     readonly scopeHeirarchy?: string[];
     readonly surfaceScopes?: ExpressLikeSchemaAuthMapper<SV, ParamsSchema, ReqBody, QuerySchema, ReqHeaders, VersionedApi, SessionObject<SV>, BaseRequest>;
-    readonly requiredFeatures?: string[];
-    readonly requireActiveSubscription?: boolean;
-} & ({
     readonly surfacePermissions?: ExpressLikeSchemaAuthMapper<SV, ParamsSchema, ReqBody, QuerySchema, ReqHeaders, VersionedApi, SessionObject<SV>, BaseRequest>;
-} | {
     readonly surfaceRoles?: ExpressLikeSchemaAuthMapper<SV, ParamsSchema, ReqBody, QuerySchema, ReqHeaders, VersionedApi, SessionObject<SV>, BaseRequest>;
-});
+    readonly requiredFeatures?: string[];
+    readonly requireActiveSubscription?: boolean;
+};
 type AuthMethods<SV extends AnySchemaValidator, P extends ParamsDictionary, ReqBody extends Record<string, unknown>, ReqQuery extends Record<string, unknown>, ReqHeaders extends Record<string, string>, VersionedReqs extends VersionedRequests, BaseRequest> = AuthMethodsBase & {
     readonly sessionSchema?: SessionObject<SV>;
     readonly requiredScope?: string;
     readonly scopeHeirarchy?: string[];
     readonly surfaceScopes?: ExpressLikeAuthMapper<SV, P, ReqBody, ReqQuery, ReqHeaders, VersionedReqs, SessionObject<SV>, BaseRequest>;
-    readonly requiredFeatures?: string[];
-    readonly requireActiveSubscription?: boolean;
-} & (({
     readonly surfacePermissions?: ExpressLikeAuthMapper<SV, P, ReqBody, ReqQuery, ReqHeaders, VersionedReqs, SessionObject<SV>, BaseRequest>;
-} & PermissionSet) | ({
     readonly surfaceRoles?: ExpressLikeAuthMapper<SV, P, ReqBody, ReqQuery, ReqHeaders, VersionedReqs, SessionObject<SV>, BaseRequest>;
-} & RoleSet));
+    readonly allowedPermissions?: Set<string>;
+    readonly forbiddenPermissions?: Set<string>;
+    readonly allowedRoles?: Set<string>;
+    readonly forbiddenRoles?: Set<string>;
+    readonly requiredFeatures?: string[];
+    readonly requireActiveSubscription?: boolean;
+};
 /**
  * Type representing a mapped schema.
  *s ParamsDictionary,

package/lib/http/index.d.mts

@@ -5,8 +5,8 @@ import { AnySchemaValidator } from '@forklaunch/validator';
 import { ServerOptions, IncomingMessage, ServerResponse } from 'node:http';
 import { O as OpenTelemetryCollector, M as MetricsDefinition, T as TelemetryOptions } from '../openTelemetryCollector-DorlR4pn.mjs';
 export { L as LogFn, a as LoggerMeta, b as MetricType, P as PinoLogger, h as httpRequestsTotalCounter, c as httpServerDurationHistogram, l as logger, m as meta } from '../openTelemetryCollector-DorlR4pn.mjs';
-import { M as Method, P as PathParamHttpContractDetails, H as HttpContractDetails, E as ExpressLikeRouterOptions, a as SessionObject, b as ParamsObject, R as ResponsesObject, B as Body, Q as QueryObject, c as HeadersObject, V as VersionSchema, d as SchemaAuthMethods, e as ExpressLikeSchemaHandler, f as ResolvedSessionObject, C as ContractDetails, g as PathMatch, L as LiveTypeFunction, h as LiveSdkFunction, A as AuthMethodsBase, i as ExpressLikeApplicationOptions, j as ParamsDictionary, k as VersionedRequests, l as AuthMethods, D as DecodeResource, m as BasicAuthMethods, F as ForklaunchRequest, n as MiddlewareContractDetails, o as ExpressLikeSchemaAuthMapper, p as ForklaunchNextFunction, q as ForklaunchResponse, r as ForklaunchResHeaders, s as ForklaunchStatusResponse, t as ForklaunchSendableData } from '../apiDefinition.types-CN-qa49j.mjs';
-export { u as AccessLevel, v as BodyObject, w as DefaultSubscriptionData, x as DocsConfiguration, y as ErrorContainer, z as ExpressLikeAuthMapper, G as ExpressLikeGlobalAuthOptions, I as ExpressLikeHandler, J as ExpressLikeSchemaGlobalAuthOptions, K as ExtractBody, N as ExtractContentType, O as ExtractResponseBody, T as ExtractedParamsObject, U as FileBody, W as ForklaunchBaseRequest, X as ForklaunchResErrors, Y as HmacMethods, Z as HttpMethod, _ as JsonBody, $ as JwtAuthMethods, a0 as LiveTypeFunctionRequestInit, a1 as MapParamsSchema, a2 as MapReqBodySchema, a3 as MapReqHeadersSchema, a4 as MapReqQuerySchema, a5 as MapResBodyMapSchema, a6 as MapResHeadersSchema, a7 as MapSchema, a8 as MapSessionSchema, a9 as MapVersionedReqsSchema, aa as MapVersionedRespsSchema, ab as MultipartForm, ac as NumberOnlyObject, ad as PathParamMethod, ae as PermissionSet, af as RawTypedResponseBody, ag as RequestContext, ah as ResolvedForklaunchAuthRequest, ai as ResolvedForklaunchRequest, aj as ResolvedForklaunchResponse, ak as ResponseBody, al as ResponseCompiledSchema, am as ResponseShape, an as RoleSet, ao as ServerSentEventBody, S as StringOnlyObject, ap as TextBody, aq as TypedBody, ar as TypedRequestBody, as as TypedResponseBody, at as UnknownBody, au as UnknownResponseBody, av as UrlEncodedForm, aw as VersionedResponses } from '../apiDefinition.types-CN-qa49j.mjs';
+import { M as Method, P as PathParamHttpContractDetails, H as HttpContractDetails, E as ExpressLikeRouterOptions, a as SessionObject, b as ParamsObject, R as ResponsesObject, B as Body, Q as QueryObject, c as HeadersObject, V as VersionSchema, d as SchemaAuthMethods, e as ExpressLikeSchemaHandler, f as ResolvedSessionObject, C as ContractDetails, g as PathMatch, L as LiveTypeFunction, h as LiveSdkFunction, A as AuthMethodsBase, i as ExpressLikeApplicationOptions, j as ParamsDictionary, k as VersionedRequests, l as AuthMethods, D as DecodeResource, m as BasicAuthMethods, F as ForklaunchRequest, n as MiddlewareContractDetails, o as ExpressLikeSchemaAuthMapper, p as ForklaunchNextFunction, q as ForklaunchResponse, r as ForklaunchResHeaders, s as ForklaunchStatusResponse, t as ForklaunchSendableData } from '../apiDefinition.types-CtTiIWvC.mjs';
+export { u as AccessLevel, v as BodyObject, w as DefaultSubscriptionData, x as DocsConfiguration, y as ErrorContainer, z as ExpressLikeAuthMapper, G as ExpressLikeGlobalAuthOptions, I as ExpressLikeHandler, J as ExpressLikeSchemaGlobalAuthOptions, K as ExtractBody, N as ExtractContentType, O as ExtractResponseBody, T as ExtractedParamsObject, U as FileBody, W as ForklaunchBaseRequest, X as ForklaunchResErrors, Y as HmacMethods, Z as HttpMethod, _ as JsonBody, $ as JwtAuthMethods, a0 as LiveTypeFunctionRequestInit, a1 as MapParamsSchema, a2 as MapReqBodySchema, a3 as MapReqHeadersSchema, a4 as MapReqQuerySchema, a5 as MapResBodyMapSchema, a6 as MapResHeadersSchema, a7 as MapSchema, a8 as MapSessionSchema, a9 as MapVersionedReqsSchema, aa as MapVersionedRespsSchema, ab as MultipartForm, ac as NumberOnlyObject, ad as PathParamMethod, ae as PermissionSet, af as RawTypedResponseBody, ag as RequestContext, ah as ResolvedForklaunchAuthRequest, ai as ResolvedForklaunchRequest, aj as ResolvedForklaunchResponse, ak as ResponseBody, al as ResponseCompiledSchema, am as ResponseShape, an as RoleSet, ao as ServerSentEventBody, S as StringOnlyObject, ap as TextBody, aq as TypedBody, ar as TypedRequestBody, as as TypedResponseBody, at as UnknownBody, au as UnknownResponseBody, av as UrlEncodedForm, aw as VersionedResponses } from '../apiDefinition.types-CtTiIWvC.mjs';
 import { JWTPayload, JWK } from 'jose';
 import { ZodSchemaValidator } from '@forklaunch/validator/zod';
 import { FastMCP } from 'fastmcp';
@@ -581,6 +581,12 @@ declare class ForklaunchExpressLikeRouter<SV extends AnySchemaValidator, BasePat
     private addRouterToSdk;
     registerNestableMiddlewareHandler<Name extends string, Path extends `/${string}`, P extends ParamsObject<SV>, ResBodyMap extends ResponsesObject<SV>, ReqBody extends Body<SV>, ReqQuery extends QueryObject<SV>, ReqHeaders extends HeadersObject<SV>, ResHeaders extends HeadersObject<SV>, LocalsObj extends Record<string, unknown>, VersionedApi extends VersionSchema<SV, 'middleware'>, const SessionSchema extends SessionObject<SV>, Auth extends SchemaAuthMethods<SV, P, ReqBody, ReqQuery, ReqHeaders, VersionedApi, BaseRequest>>(registrationMethod: NestableRouterBasedHandler<RouterHandler, Internal>, pathOrContractDetailsOrMiddlewareOrTypedHandler: Path | ContractDetailsOrMiddlewareOrTypedHandler<SV, Name, 'middleware', Path, P, ResBodyMap, ReqBody, ReqQuery, ReqHeaders, ResHeaders, LocalsObj, VersionedApi, BaseRequest, BaseResponse, NextFunction, RouterSession, Auth> | ConstrainedForklaunchRouter<SV, RouterHandler>, contractDetailsOrMiddlewareOrTypedHandler?: ContractDetailsOrMiddlewareOrTypedHandler<SV, Name, 'middleware', Path, P, ResBodyMap, ReqBody, ReqQuery, ReqHeaders, ResHeaders, LocalsObj, VersionedApi, BaseRequest, BaseResponse, NextFunction, RouterSession, Auth> | ConstrainedForklaunchRouter<SV, RouterHandler>, ...middlewareOrMiddlewareWithTypedHandler: (MiddlewareOrMiddlewareWithTypedHandler<SV, Name, 'middleware', Path, P, ResBodyMap, ReqBody, ReqQuery, ReqHeaders, ResHeaders, LocalsObj, VersionedApi, BaseRequest, BaseResponse, NextFunction, RouterSession, Auth> | ConstrainedForklaunchRouter<SV, RouterHandler>)[]): this;
     private addRouterOptions;
+    /**
+     * Validates that all protected routes have the required surfacing functions
+     * available (from the route, router, or application level).
+     * Call this at listen() time when the full option chain is assembled.
+     */
+    validateSurfacingFunctions(router?: ForklaunchRouter<SV>, parentAuth?: Record<string, unknown>): void;
     use: TypedNestableMiddlewareDefinition<this, RouterHandler, Internal, SV, RouterSession, BaseRequest, BaseResponse, NextFunction>;
     all: TypedMiddlewareDefinition<this, SV, RouterSession, BaseRequest, BaseResponse, NextFunction, RouterHandler>;
     connect: TypedMiddlewareDefinition<this, SV, RouterSession, BaseRequest, BaseResponse, NextFunction, RouterHandler>;
@@ -726,6 +732,11 @@ declare abstract class ForklaunchExpressLikeApplication<SV extends AnySchemaVali
      * @param {SV} schemaValidator - The schema validator.
      */
     constructor(schemaValidator: SV, internal: Server, postEnrichMiddleware: RouterHandler[], openTelemetryCollector: OpenTelemetryCollector<MetricsDefinition>, appOptions?: ExpressLikeApplicationOptions<SV, Session> | undefined);
+    /**
+     * Validates all registered routes across the app and all mounted routers.
+     * Call this at the start of listen() to fail fast at startup.
+     */
+    protected validateAllRoutes(): void;
     abstract listen(...args: unknown[]): void;
 }
 

package/lib/http/index.d.ts

@@ -5,8 +5,8 @@ import { AnySchemaValidator } from '@forklaunch/validator';
 import { ServerOptions, IncomingMessage, ServerResponse } from 'node:http';
 import { O as OpenTelemetryCollector, M as MetricsDefinition, T as TelemetryOptions } from '../openTelemetryCollector-DorlR4pn.js';
 export { L as LogFn, a as LoggerMeta, b as MetricType, P as PinoLogger, h as httpRequestsTotalCounter, c as httpServerDurationHistogram, l as logger, m as meta } from '../openTelemetryCollector-DorlR4pn.js';
-import { M as Method, P as PathParamHttpContractDetails, H as HttpContractDetails, E as ExpressLikeRouterOptions, a as SessionObject, b as ParamsObject, R as ResponsesObject, B as Body, Q as QueryObject, c as HeadersObject, V as VersionSchema, d as SchemaAuthMethods, e as ExpressLikeSchemaHandler, f as ResolvedSessionObject, C as ContractDetails, g as PathMatch, L as LiveTypeFunction, h as LiveSdkFunction, A as AuthMethodsBase, i as ExpressLikeApplicationOptions, j as ParamsDictionary, k as VersionedRequests, l as AuthMethods, D as DecodeResource, m as BasicAuthMethods, F as ForklaunchRequest, n as MiddlewareContractDetails, o as ExpressLikeSchemaAuthMapper, p as ForklaunchNextFunction, q as ForklaunchResponse, r as ForklaunchResHeaders, s as ForklaunchStatusResponse, t as ForklaunchSendableData } from '../apiDefinition.types-CAOGkjXe.js';
-export { u as AccessLevel, v as BodyObject, w as DefaultSubscriptionData, x as DocsConfiguration, y as ErrorContainer, z as ExpressLikeAuthMapper, G as ExpressLikeGlobalAuthOptions, I as ExpressLikeHandler, J as ExpressLikeSchemaGlobalAuthOptions, K as ExtractBody, N as ExtractContentType, O as ExtractResponseBody, T as ExtractedParamsObject, U as FileBody, W as ForklaunchBaseRequest, X as ForklaunchResErrors, Y as HmacMethods, Z as HttpMethod, _ as JsonBody, $ as JwtAuthMethods, a0 as LiveTypeFunctionRequestInit, a1 as MapParamsSchema, a2 as MapReqBodySchema, a3 as MapReqHeadersSchema, a4 as MapReqQuerySchema, a5 as MapResBodyMapSchema, a6 as MapResHeadersSchema, a7 as MapSchema, a8 as MapSessionSchema, a9 as MapVersionedReqsSchema, aa as MapVersionedRespsSchema, ab as MultipartForm, ac as NumberOnlyObject, ad as PathParamMethod, ae as PermissionSet, af as RawTypedResponseBody, ag as RequestContext, ah as ResolvedForklaunchAuthRequest, ai as ResolvedForklaunchRequest, aj as ResolvedForklaunchResponse, ak as ResponseBody, al as ResponseCompiledSchema, am as ResponseShape, an as RoleSet, ao as ServerSentEventBody, S as StringOnlyObject, ap as TextBody, aq as TypedBody, ar as TypedRequestBody, as as TypedResponseBody, at as UnknownBody, au as UnknownResponseBody, av as UrlEncodedForm, aw as VersionedResponses } from '../apiDefinition.types-CAOGkjXe.js';
+import { M as Method, P as PathParamHttpContractDetails, H as HttpContractDetails, E as ExpressLikeRouterOptions, a as SessionObject, b as ParamsObject, R as ResponsesObject, B as Body, Q as QueryObject, c as HeadersObject, V as VersionSchema, d as SchemaAuthMethods, e as ExpressLikeSchemaHandler, f as ResolvedSessionObject, C as ContractDetails, g as PathMatch, L as LiveTypeFunction, h as LiveSdkFunction, A as AuthMethodsBase, i as ExpressLikeApplicationOptions, j as ParamsDictionary, k as VersionedRequests, l as AuthMethods, D as DecodeResource, m as BasicAuthMethods, F as ForklaunchRequest, n as MiddlewareContractDetails, o as ExpressLikeSchemaAuthMapper, p as ForklaunchNextFunction, q as ForklaunchResponse, r as ForklaunchResHeaders, s as ForklaunchStatusResponse, t as ForklaunchSendableData } from '../apiDefinition.types-fBjxhhaM.js';
+export { u as AccessLevel, v as BodyObject, w as DefaultSubscriptionData, x as DocsConfiguration, y as ErrorContainer, z as ExpressLikeAuthMapper, G as ExpressLikeGlobalAuthOptions, I as ExpressLikeHandler, J as ExpressLikeSchemaGlobalAuthOptions, K as ExtractBody, N as ExtractContentType, O as ExtractResponseBody, T as ExtractedParamsObject, U as FileBody, W as ForklaunchBaseRequest, X as ForklaunchResErrors, Y as HmacMethods, Z as HttpMethod, _ as JsonBody, $ as JwtAuthMethods, a0 as LiveTypeFunctionRequestInit, a1 as MapParamsSchema, a2 as MapReqBodySchema, a3 as MapReqHeadersSchema, a4 as MapReqQuerySchema, a5 as MapResBodyMapSchema, a6 as MapResHeadersSchema, a7 as MapSchema, a8 as MapSessionSchema, a9 as MapVersionedReqsSchema, aa as MapVersionedRespsSchema, ab as MultipartForm, ac as NumberOnlyObject, ad as PathParamMethod, ae as PermissionSet, af as RawTypedResponseBody, ag as RequestContext, ah as ResolvedForklaunchAuthRequest, ai as ResolvedForklaunchRequest, aj as ResolvedForklaunchResponse, ak as ResponseBody, al as ResponseCompiledSchema, am as ResponseShape, an as RoleSet, ao as ServerSentEventBody, S as StringOnlyObject, ap as TextBody, aq as TypedBody, ar as TypedRequestBody, as as TypedResponseBody, at as UnknownBody, au as UnknownResponseBody, av as UrlEncodedForm, aw as VersionedResponses } from '../apiDefinition.types-fBjxhhaM.js';
 import { JWTPayload, JWK } from 'jose';
 import { ZodSchemaValidator } from '@forklaunch/validator/zod';
 import { FastMCP } from 'fastmcp';
@@ -581,6 +581,12 @@ declare class ForklaunchExpressLikeRouter<SV extends AnySchemaValidator, BasePat
     private addRouterToSdk;
     registerNestableMiddlewareHandler<Name extends string, Path extends `/${string}`, P extends ParamsObject<SV>, ResBodyMap extends ResponsesObject<SV>, ReqBody extends Body<SV>, ReqQuery extends QueryObject<SV>, ReqHeaders extends HeadersObject<SV>, ResHeaders extends HeadersObject<SV>, LocalsObj extends Record<string, unknown>, VersionedApi extends VersionSchema<SV, 'middleware'>, const SessionSchema extends SessionObject<SV>, Auth extends SchemaAuthMethods<SV, P, ReqBody, ReqQuery, ReqHeaders, VersionedApi, BaseRequest>>(registrationMethod: NestableRouterBasedHandler<RouterHandler, Internal>, pathOrContractDetailsOrMiddlewareOrTypedHandler: Path | ContractDetailsOrMiddlewareOrTypedHandler<SV, Name, 'middleware', Path, P, ResBodyMap, ReqBody, ReqQuery, ReqHeaders, ResHeaders, LocalsObj, VersionedApi, BaseRequest, BaseResponse, NextFunction, RouterSession, Auth> | ConstrainedForklaunchRouter<SV, RouterHandler>, contractDetailsOrMiddlewareOrTypedHandler?: ContractDetailsOrMiddlewareOrTypedHandler<SV, Name, 'middleware', Path, P, ResBodyMap, ReqBody, ReqQuery, ReqHeaders, ResHeaders, LocalsObj, VersionedApi, BaseRequest, BaseResponse, NextFunction, RouterSession, Auth> | ConstrainedForklaunchRouter<SV, RouterHandler>, ...middlewareOrMiddlewareWithTypedHandler: (MiddlewareOrMiddlewareWithTypedHandler<SV, Name, 'middleware', Path, P, ResBodyMap, ReqBody, ReqQuery, ReqHeaders, ResHeaders, LocalsObj, VersionedApi, BaseRequest, BaseResponse, NextFunction, RouterSession, Auth> | ConstrainedForklaunchRouter<SV, RouterHandler>)[]): this;
     private addRouterOptions;
+    /**
+     * Validates that all protected routes have the required surfacing functions
+     * available (from the route, router, or application level).
+     * Call this at listen() time when the full option chain is assembled.
+     */
+    validateSurfacingFunctions(router?: ForklaunchRouter<SV>, parentAuth?: Record<string, unknown>): void;
     use: TypedNestableMiddlewareDefinition<this, RouterHandler, Internal, SV, RouterSession, BaseRequest, BaseResponse, NextFunction>;
     all: TypedMiddlewareDefinition<this, SV, RouterSession, BaseRequest, BaseResponse, NextFunction, RouterHandler>;
     connect: TypedMiddlewareDefinition<this, SV, RouterSession, BaseRequest, BaseResponse, NextFunction, RouterHandler>;
@@ -726,6 +732,11 @@ declare abstract class ForklaunchExpressLikeApplication<SV extends AnySchemaVali
      * @param {SV} schemaValidator - The schema validator.
      */
     constructor(schemaValidator: SV, internal: Server, postEnrichMiddleware: RouterHandler[], openTelemetryCollector: OpenTelemetryCollector<MetricsDefinition>, appOptions?: ExpressLikeApplicationOptions<SV, Session> | undefined);
+    /**
+     * Validates all registered routes across the app and all mounted routers.
+     * Call this at the start of listen() to fail fast at startup.
+     */
+    protected validateAllRoutes(): void;
     abstract listen(...args: unknown[]): void;
 }
 

package/lib/http/index.js

@@ -111,6 +111,31 @@ function cors(corsOptions) {
 // src/http/router/expressLikeRouter.ts
 var import_common11 = require("@forklaunch/common");
 
+// src/http/guards/hasPermissionChecks.ts
+function hasPermissionChecks(maybePermissionedAuth) {
+  if (typeof maybePermissionedAuth !== "object" || maybePermissionedAuth === null) {
+    return false;
+  }
+  const hasAllowedPermissions = "allowedPermissions" in maybePermissionedAuth && maybePermissionedAuth.allowedPermissions instanceof Set && maybePermissionedAuth.allowedPermissions.size > 0;
+  const hasForbiddenPermissions = "forbiddenPermissions" in maybePermissionedAuth && maybePermissionedAuth.forbiddenPermissions instanceof Set && maybePermissionedAuth.forbiddenPermissions.size > 0;
+  return hasAllowedPermissions || hasForbiddenPermissions;
+}
+
+// src/http/guards/hasRoleChecks.ts
+function hasRoleChecks(maybeRoledAuth) {
+  if (typeof maybeRoledAuth !== "object" || maybeRoledAuth === null) {
+    return false;
+  }
+  const hasAllowedRoles = "allowedRoles" in maybeRoledAuth && maybeRoledAuth.allowedRoles instanceof Set && maybeRoledAuth.allowedRoles.size > 0;
+  const hasForbiddenRoles = "forbiddenRoles" in maybeRoledAuth && maybeRoledAuth.forbiddenRoles instanceof Set && maybeRoledAuth.forbiddenRoles.size > 0;
+  return hasAllowedRoles || hasForbiddenRoles;
+}
+
+// src/http/guards/hasScopeChecks.ts
+function hasScopeChecks(maybePermissionedAuth) {
+  return typeof maybePermissionedAuth === "object" && maybePermissionedAuth !== null && "requiredScope" in maybePermissionedAuth && maybePermissionedAuth.requiredScope != null;
+}
+
 // src/http/guards/isForklaunchRouter.ts
 function isForklaunchRouter(maybeForklaunchRouter) {
   return maybeForklaunchRouter != null && typeof maybeForklaunchRouter === "object" && "basePath" in maybeForklaunchRouter && "routes" in maybeForklaunchRouter && Array.isArray(maybeForklaunchRouter.routes);
@@ -320,31 +345,6 @@ function discriminateResponseBodies(schemaValidator, responses) {
 // src/http/router/routerSharedLogic.ts
 var import_common10 = require("@forklaunch/common");
 
-// src/http/guards/hasPermissionChecks.ts
-function hasPermissionChecks(maybePermissionedAuth) {
-  if (typeof maybePermissionedAuth !== "object" || maybePermissionedAuth === null) {
-    return false;
-  }
-  const hasAllowedPermissions = "allowedPermissions" in maybePermissionedAuth && maybePermissionedAuth.allowedPermissions instanceof Set && maybePermissionedAuth.allowedPermissions.size > 0;
-  const hasForbiddenPermissions = "forbiddenPermissions" in maybePermissionedAuth && maybePermissionedAuth.forbiddenPermissions instanceof Set && maybePermissionedAuth.forbiddenPermissions.size > 0;
-  return hasAllowedPermissions || hasForbiddenPermissions;
-}
-
-// src/http/guards/hasRoleChecks.ts
-function hasRoleChecks(maybeRoledAuth) {
-  if (typeof maybeRoledAuth !== "object" || maybeRoledAuth === null) {
-    return false;
-  }
-  const hasAllowedRoles = "allowedRoles" in maybeRoledAuth && maybeRoledAuth.allowedRoles instanceof Set && maybeRoledAuth.allowedRoles.size > 0;
-  const hasForbiddenRoles = "forbiddenRoles" in maybeRoledAuth && maybeRoledAuth.forbiddenRoles instanceof Set && maybeRoledAuth.forbiddenRoles.size > 0;
-  return hasAllowedRoles || hasForbiddenRoles;
-}
-
-// src/http/guards/hasScopeChecks.ts
-function hasScopeChecks(maybePermissionedAuth) {
-  return typeof maybePermissionedAuth === "object" && maybePermissionedAuth !== null && "requiredScope" in maybePermissionedAuth && maybePermissionedAuth.requiredScope != null;
-}
-
 // src/http/guards/hasVersionedSchema.ts
 function hasVersionedSchema(contractDetails) {
   return typeof contractDetails === "object" && contractDetails !== null && "versions" in contractDetails && contractDetails.versions !== null;
@@ -1960,6 +1960,46 @@ var ForklaunchExpressLikeRouter = class _ForklaunchExpressLikeRouter {
       );
     });
   }
+  /**
+   * Validates that all protected routes have the required surfacing functions
+   * available (from the route, router, or application level).
+   * Call this at listen() time when the full option chain is assembled.
+   */
+  validateSurfacingFunctions(router = this, parentAuth) {
+    const routerAuth = router.routerOptions?.auth && typeof router.routerOptions.auth === "object" ? router.routerOptions.auth : void 0;
+    const globalAuth = routerAuth ?? parentAuth;
+    for (const route of router.routes) {
+      const auth = route.contractDetails.auth;
+      const access = route.contractDetails.access;
+      if (!auth || access !== "protected") continue;
+      const routeAuth = auth;
+      const routeName = route.contractDetails.name;
+      if (hasPermissionChecks(auth)) {
+        if (!routeAuth["surfacePermissions"] && !globalAuth?.surfacePermissions) {
+          throw new Error(
+            `Route '${routeName}': declares allowedPermissions or forbiddenPermissions but no surfacePermissions function was provided on the route, router, or application`
+          );
+        }
+      }
+      if (hasRoleChecks(auth)) {
+        if (!routeAuth["surfaceRoles"] && !globalAuth?.surfaceRoles) {
+          throw new Error(
+            `Route '${routeName}': declares allowedRoles or forbiddenRoles but no surfaceRoles function was provided on the route, router, or application`
+          );
+        }
+      }
+      if (hasScopeChecks(auth)) {
+        if (!routeAuth["surfaceScopes"] && !globalAuth?.surfaceScopes) {
+          throw new Error(
+            `Route '${routeName}': declares requiredScope but no surfaceScopes function was provided on the route, router, or application`
+          );
+        }
+      }
+    }
+    for (const subRouter of router.routers) {
+      this.validateSurfacingFunctions(subRouter, globalAuth);
+    }
+  }
   use = (pathOrContractDetailsOrMiddlewareOrTypedHandler, contractDetailsOrMiddlewareOrTypedHandler, ...middlewareOrMiddlewareWithTypedHandler) => {
     [
       pathOrContractDetailsOrMiddlewareOrTypedHandler,
@@ -2267,6 +2307,13 @@ var ForklaunchExpressLikeApplication = class extends ForklaunchExpressLikeRouter
     this.appOptions = appOptions;
     this.internal.use(cors(this.appOptions?.cors ?? {}));
   }
+  /**
+   * Validates all registered routes across the app and all mounted routers.
+   * Call this at the start of listen() to fail fast at startup.
+   */
+  validateAllRoutes() {
+    this.validateSurfacingFunctions();
+  }
 };
 
 // src/http/cluster/isPortBound.ts
@@ -4111,7 +4158,7 @@ function generateOperationObject(schemaValidator, path, method, controllerName,
       operationObject.security = [
         {
           basic: Array.from(
-            "allowedPermissions" in auth ? auth.allowedPermissions?.values() || [] : []
+            "allowedPermissions" in auth && auth.allowedPermissions instanceof Set ? auth.allowedPermissions.values() : []
           )
         }
       ];
@@ -4123,7 +4170,7 @@ function generateOperationObject(schemaValidator, path, method, controllerName,
       operationObject.security = [
         {
           [auth.headerName !== "Authorization" ? "bearer" : "apiKey"]: Array.from(
-            "allowedPermissions" in auth ? auth.allowedPermissions?.values() || [] : []
+            "allowedPermissions" in auth && auth.allowedPermissions instanceof Set ? auth.allowedPermissions.values() : []
           )
         }
       ];