@bajustone/fortress 1.0.0-rc.1

package/dist/protect-D1v_0upK.d.cts

@@ -0,0 +1,123 @@
+import { E as EndpointDefinition, I as InferEndpointParams, a as InferEndpointQuery, b as InferEndpointBody, c as InferEndpointCallInput, d as InferEndpointResponses } from './config-GtlVt6ZD.cjs';
+import { R as RouteManifestEntry, F as Fortress } from './fortress-BmSvFfqK.cjs';
+import { S as Subject, T as TokenClaims } from './types-et0R8tsC.cjs';
+
+/**
+ * Host-owned route protection.
+ *
+ * Lets adapters and framework-less hosts run the same Fortress security
+ * pipeline used by `fortress.handleRequest()` around handlers they register
+ * themselves: plugin middleware, CSRF, principal resolution, RBAC,
+ * validation, and auth-cookie attachment.
+ */
+
+/**
+ * What you point `protect()` at: an `EndpointDefinition` (preferred — its
+ * phantom `<TBody, TQuery, TParams, TResponses>` types flow into the
+ * `ProtectedRouteContext`) or a handler name from `fortress.endpoints`
+ * (looser typing, falls back to `Record<string, unknown>` / `unknown`).
+ */
+type ProtectedRouteTarget<E extends EndpointDefinition<any, any, any, any> = EndpointDefinition> = string | E;
+/**
+ * Widen `{}` (the `EndpointDefinition` default for an unspecified input slot)
+ * back to `Record<string, unknown>` so adapter callers that pass a string
+ * target — or an untyped `EndpointDefinition` — keep the loose ergonomics
+ * they had before generics existed. A real declared schema produces a
+ * narrow object type, which passes through unchanged.
+ */
+type WidenObj<T> = [keyof T] extends [never] ? Record<string, unknown> : T;
+interface ProtectOptions {
+    /**
+     * Canonical path to use for plugin middleware / CSRF matching when the
+     * host-owned route is mounted at a path different from the endpoint path.
+     * Defaults to the incoming request pathname.
+     */
+    path?: string;
+    /** Override HTTP method for manifest lookup. Defaults to request.method. */
+    method?: string;
+    /** Explicit params for host paths that do not match the endpoint path. */
+    params?: Record<string, string>;
+    /** Attach auth cookies when the handler returns `{ accessToken, refreshToken? }`. Default `true`. */
+    attachAuthCookies?: boolean;
+}
+/**
+ * Per-request context handed to the host callback. When `target` is a
+ * typed `EndpointDefinition`, `body` / `query` / `params` / `input` are
+ * inferred from its phantom generics; when `target` is a handler name
+ * string, they fall back to `Record<string, unknown>` / `unknown`.
+ */
+interface ProtectedRouteContext<E extends EndpointDefinition<any, any, any, any> = EndpointDefinition> {
+    request: Request;
+    /** The resolved endpoint definition (typed when the target was typed). */
+    endpoint: E;
+    manifest: RouteManifestEntry;
+    subject?: Subject;
+    userId?: string;
+    claims?: TokenClaims;
+    scopes?: string[] | null;
+    params: WidenObj<InferEndpointParams<E>>;
+    query: WidenObj<InferEndpointQuery<E>>;
+    /**
+     * Parsed request body.
+     *
+     * When the endpoint declares a body schema, the handler only runs after
+     * that body passes Standard Schema validation, so `body` is narrowed to a
+     * non-optional `T` — use it directly without `!` or reaching for
+     * `ctx.input`. Endpoints with no declared body schema fall back to the
+     * loose `unknown` (which still admits `undefined`), matching the
+     * pre-generics ergonomics for string / untyped targets.
+     */
+    body: [keyof InferEndpointBody<E>] extends [never] ? unknown : InferEndpointBody<E>;
+    /**
+     * Merged `{ ...body, ...query, ...params }` input after URL coercion.
+     * Typed as the same intersection the `fortress.call.*` proxy uses.
+     */
+    input: [keyof InferEndpointCallInput<E>] extends [never] ? Record<string, unknown> : InferEndpointCallInput<E>;
+    /**
+     * Build a typed JSON response for a status declared on the endpoint.
+     *
+     * When `target` was a typed `EndpointDefinition`, `status` is narrowed
+     * to the response codes that endpoint actually declares and `body` is
+     * narrowed to that response's schema output. Use this instead of
+     * hand-rolling `new Response(JSON.stringify(...), { status })` for
+     * non-2xx returns:
+     *
+     * ```ts
+     * protectedRoute(fortress, getSchool, async (ctx) => {
+     *   const school = await loadSchool(ctx.params.id);
+     *   if (!school)
+     *     return ctx.respond(404, { code: 'NOT_FOUND', message: 'School not found', statusCode: 404 });
+     *   return { data: school };  // 2xx success returned as a plain object
+     * });
+     * ```
+     *
+     * For string-target / untyped endpoints, both arguments fall back to
+     * `number` / `unknown`, matching the loose ergonomics elsewhere in the
+     * context.
+     */
+    respond: [keyof InferEndpointResponses<E>] extends [never] ? (status: number, body: unknown) => Response : <S extends keyof InferEndpointResponses<E> & number>(status: S, body: InferEndpointResponses<E>[S]) => Response;
+}
+type ProtectedRouteHandler<E extends EndpointDefinition<any, any, any, any> = EndpointDefinition, TResult = unknown> = (ctx: ProtectedRouteContext<E>) => TResult | Response | Promise<TResult | Response>;
+/**
+ * Build a web-standard protected route handler for a host-owned route.
+ * Adapter-specific helpers wrap this function for Hono, Express, and
+ * SvelteKit ergonomics.
+ *
+ * Two overloads:
+ *
+ * - **Typed target** — pass an `EndpointDefinition` (e.g. the value produced
+ *   by `endpoint(...).build()`). Its `<TBody, TQuery, TParams, TResponses>`
+ *   phantoms flow into `ctx.body` / `ctx.query` / `ctx.params` / `ctx.input`.
+ * - **String target** — pass a unique `handler` name. Inputs fall back to
+ *   `Record<string, unknown>` / `unknown`, matching pre-0.2.x behaviour.
+ *
+ * The runtime is identical in both forms; this is purely typing.
+ */
+declare function protect<E extends EndpointDefinition<any, any, any, any>, TResult = unknown>(fortress: Fortress, target: E, handler: ProtectedRouteHandler<E, TResult>, options?: ProtectOptions): (request: Request) => Promise<Response>;
+declare function protect<TResult = unknown>(fortress: Fortress, target: string, handler: ProtectedRouteHandler<EndpointDefinition, TResult>, options?: ProtectOptions): (request: Request) => Promise<Response>;
+/** Resolve an endpoint eagerly; useful for adapter wrappers and diagnostics. */
+declare function resolveProtectedEndpoint(fortress: Fortress, target: ProtectedRouteTarget, method?: string): EndpointDefinition;
+/** Human-readable name for errors/logs. */
+declare function describeProtectedTarget(target: ProtectedRouteTarget): string;
+
+export { type ProtectedRouteContext as P, type ProtectOptions as a, type ProtectedRouteTarget as b, type ProtectedRouteHandler as c, describeProtectedTarget as d, protect as p, resolveProtectedEndpoint as r };

package/dist/protect-DsxV_-dJ.d.ts

@@ -0,0 +1,123 @@
+import { E as EndpointDefinition, I as InferEndpointParams, a as InferEndpointQuery, b as InferEndpointBody, c as InferEndpointCallInput, d as InferEndpointResponses } from './config-B2366s_G.js';
+import { R as RouteManifestEntry, F as Fortress } from './fortress-uA-_cheR.js';
+import { S as Subject, T as TokenClaims } from './types-et0R8tsC.js';
+
+/**
+ * Host-owned route protection.
+ *
+ * Lets adapters and framework-less hosts run the same Fortress security
+ * pipeline used by `fortress.handleRequest()` around handlers they register
+ * themselves: plugin middleware, CSRF, principal resolution, RBAC,
+ * validation, and auth-cookie attachment.
+ */
+
+/**
+ * What you point `protect()` at: an `EndpointDefinition` (preferred — its
+ * phantom `<TBody, TQuery, TParams, TResponses>` types flow into the
+ * `ProtectedRouteContext`) or a handler name from `fortress.endpoints`
+ * (looser typing, falls back to `Record<string, unknown>` / `unknown`).
+ */
+type ProtectedRouteTarget<E extends EndpointDefinition<any, any, any, any> = EndpointDefinition> = string | E;
+/**
+ * Widen `{}` (the `EndpointDefinition` default for an unspecified input slot)
+ * back to `Record<string, unknown>` so adapter callers that pass a string
+ * target — or an untyped `EndpointDefinition` — keep the loose ergonomics
+ * they had before generics existed. A real declared schema produces a
+ * narrow object type, which passes through unchanged.
+ */
+type WidenObj<T> = [keyof T] extends [never] ? Record<string, unknown> : T;
+interface ProtectOptions {
+    /**
+     * Canonical path to use for plugin middleware / CSRF matching when the
+     * host-owned route is mounted at a path different from the endpoint path.
+     * Defaults to the incoming request pathname.
+     */
+    path?: string;
+    /** Override HTTP method for manifest lookup. Defaults to request.method. */
+    method?: string;
+    /** Explicit params for host paths that do not match the endpoint path. */
+    params?: Record<string, string>;
+    /** Attach auth cookies when the handler returns `{ accessToken, refreshToken? }`. Default `true`. */
+    attachAuthCookies?: boolean;
+}
+/**
+ * Per-request context handed to the host callback. When `target` is a
+ * typed `EndpointDefinition`, `body` / `query` / `params` / `input` are
+ * inferred from its phantom generics; when `target` is a handler name
+ * string, they fall back to `Record<string, unknown>` / `unknown`.
+ */
+interface ProtectedRouteContext<E extends EndpointDefinition<any, any, any, any> = EndpointDefinition> {
+    request: Request;
+    /** The resolved endpoint definition (typed when the target was typed). */
+    endpoint: E;
+    manifest: RouteManifestEntry;
+    subject?: Subject;
+    userId?: string;
+    claims?: TokenClaims;
+    scopes?: string[] | null;
+    params: WidenObj<InferEndpointParams<E>>;
+    query: WidenObj<InferEndpointQuery<E>>;
+    /**
+     * Parsed request body.
+     *
+     * When the endpoint declares a body schema, the handler only runs after
+     * that body passes Standard Schema validation, so `body` is narrowed to a
+     * non-optional `T` — use it directly without `!` or reaching for
+     * `ctx.input`. Endpoints with no declared body schema fall back to the
+     * loose `unknown` (which still admits `undefined`), matching the
+     * pre-generics ergonomics for string / untyped targets.
+     */
+    body: [keyof InferEndpointBody<E>] extends [never] ? unknown : InferEndpointBody<E>;
+    /**
+     * Merged `{ ...body, ...query, ...params }` input after URL coercion.
+     * Typed as the same intersection the `fortress.call.*` proxy uses.
+     */
+    input: [keyof InferEndpointCallInput<E>] extends [never] ? Record<string, unknown> : InferEndpointCallInput<E>;
+    /**
+     * Build a typed JSON response for a status declared on the endpoint.
+     *
+     * When `target` was a typed `EndpointDefinition`, `status` is narrowed
+     * to the response codes that endpoint actually declares and `body` is
+     * narrowed to that response's schema output. Use this instead of
+     * hand-rolling `new Response(JSON.stringify(...), { status })` for
+     * non-2xx returns:
+     *
+     * ```ts
+     * protectedRoute(fortress, getSchool, async (ctx) => {
+     *   const school = await loadSchool(ctx.params.id);
+     *   if (!school)
+     *     return ctx.respond(404, { code: 'NOT_FOUND', message: 'School not found', statusCode: 404 });
+     *   return { data: school };  // 2xx success returned as a plain object
+     * });
+     * ```
+     *
+     * For string-target / untyped endpoints, both arguments fall back to
+     * `number` / `unknown`, matching the loose ergonomics elsewhere in the
+     * context.
+     */
+    respond: [keyof InferEndpointResponses<E>] extends [never] ? (status: number, body: unknown) => Response : <S extends keyof InferEndpointResponses<E> & number>(status: S, body: InferEndpointResponses<E>[S]) => Response;
+}
+type ProtectedRouteHandler<E extends EndpointDefinition<any, any, any, any> = EndpointDefinition, TResult = unknown> = (ctx: ProtectedRouteContext<E>) => TResult | Response | Promise<TResult | Response>;
+/**
+ * Build a web-standard protected route handler for a host-owned route.
+ * Adapter-specific helpers wrap this function for Hono, Express, and
+ * SvelteKit ergonomics.
+ *
+ * Two overloads:
+ *
+ * - **Typed target** — pass an `EndpointDefinition` (e.g. the value produced
+ *   by `endpoint(...).build()`). Its `<TBody, TQuery, TParams, TResponses>`
+ *   phantoms flow into `ctx.body` / `ctx.query` / `ctx.params` / `ctx.input`.
+ * - **String target** — pass a unique `handler` name. Inputs fall back to
+ *   `Record<string, unknown>` / `unknown`, matching pre-0.2.x behaviour.
+ *
+ * The runtime is identical in both forms; this is purely typing.
+ */
+declare function protect<E extends EndpointDefinition<any, any, any, any>, TResult = unknown>(fortress: Fortress, target: E, handler: ProtectedRouteHandler<E, TResult>, options?: ProtectOptions): (request: Request) => Promise<Response>;
+declare function protect<TResult = unknown>(fortress: Fortress, target: string, handler: ProtectedRouteHandler<EndpointDefinition, TResult>, options?: ProtectOptions): (request: Request) => Promise<Response>;
+/** Resolve an endpoint eagerly; useful for adapter wrappers and diagnostics. */
+declare function resolveProtectedEndpoint(fortress: Fortress, target: ProtectedRouteTarget, method?: string): EndpointDefinition;
+/** Human-readable name for errors/logs. */
+declare function describeProtectedTarget(target: ProtectedRouteTarget): string;
+
+export { type ProtectedRouteContext as P, type ProtectOptions as a, type ProtectedRouteTarget as b, type ProtectedRouteHandler as c, describeProtectedTarget as d, protect as p, resolveProtectedEndpoint as r };