@empire-builder-kit/runtime 0.0.1-alpha.8 → 1.0.0-beta.4

package/src/auth-backend.js

@@ -0,0 +1,158 @@
+import { __awaiter } from "tslib";
+import { assertPrincipalKind, AuthError, authErrorCodes, isAuthError, sessionFromCognitoToken, toPrincipal, } from './auth.js';
+import { createRemoteJWKSet, jwtVerify, } from 'jose';
+function hasExpectedAudience(payload, clientId) {
+    return (payload.aud === clientId ||
+        (Array.isArray(payload.aud) && payload.aud.includes(clientId)) ||
+        payload.client_id === clientId);
+}
+function normalizeGroups(groups) {
+    if (!Array.isArray(groups)) {
+        return undefined;
+    }
+    const normalized = groups.filter((group) => typeof group === 'string');
+    return normalized.length > 0 ? normalized : undefined;
+}
+function joseErrorCode(error) {
+    return typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        typeof error.code === 'string'
+        ? error.code
+        : undefined;
+}
+function isJwksAvailabilityError(error) {
+    var _a;
+    return (error instanceof TypeError ||
+        ['ERR_JWKS_INVALID', 'ERR_JWKS_TIMEOUT'].includes((_a = joseErrorCode(error)) !== null && _a !== void 0 ? _a : ''));
+}
+export function createCognitoJwtVerifier(config, options = {}) {
+    var _a, _b;
+    const clockToleranceSeconds = (_a = options.clockToleranceSeconds) !== null && _a !== void 0 ? _a : 30;
+    if (!Number.isFinite(clockToleranceSeconds) || clockToleranceSeconds < 0) {
+        throw new Error('JWT clock tolerance must be a non-negative number.');
+    }
+    const jwks = (_b = options.jwks) !== null && _b !== void 0 ? _b : createRemoteJWKSet(new URL(`${config.issuerUrl}/.well-known/jwks.json`));
+    return {
+        verify(token) {
+            return __awaiter(this, void 0, void 0, function* () {
+                var _a, _b;
+                const parts = token.split('.');
+                if (parts.length !== 3) {
+                    throw new Error('Invalid JWT format');
+                }
+                let payload;
+                try {
+                    ({ payload } = yield jwtVerify(token, jwks, {
+                        algorithms: ['RS256'],
+                        clockTolerance: clockToleranceSeconds,
+                        issuer: config.issuerUrl,
+                    }));
+                }
+                catch (error) {
+                    if (isJwksAvailabilityError(error)) {
+                        const report = (_a = options.onJwksError) !== null && _a !== void 0 ? _a : ((cause) => {
+                            var _a;
+                            return console.error('[runtime/auth-backend] Cognito JWKS verification is unavailable.', {
+                                code: (_a = joseErrorCode(cause)) !== null && _a !== void 0 ? _a : 'ERR_JWKS_FETCH',
+                                issuer: config.issuerUrl,
+                            });
+                        });
+                        report(error);
+                    }
+                    throw error;
+                }
+                if (!hasExpectedAudience(payload, config.clientId)) {
+                    throw new Error('Invalid audience');
+                }
+                if (!payload.sub) {
+                    throw new Error('Invalid subject');
+                }
+                if (typeof payload.exp !== 'number') {
+                    throw new Error('Missing token expiry');
+                }
+                const tokenUse = (_b = options.tokenUse) !== null && _b !== void 0 ? _b : 'any';
+                if (tokenUse !== 'any' && payload.token_use !== tokenUse) {
+                    throw new Error('Invalid token_use');
+                }
+                return sessionFromCognitoToken({
+                    sub: payload.sub,
+                    aud: payload.aud,
+                    client_id: payload.client_id,
+                    email: payload.email,
+                    'cognito:username': payload['cognito:username'],
+                    'cognito:groups': normalizeGroups(payload['cognito:groups']),
+                    exp: payload.exp,
+                    iat: payload.iat,
+                    scope: payload.scope,
+                    token_use: payload.token_use,
+                });
+            });
+        },
+    };
+}
+/**
+ * Extracts a Bearer token from an Authorization header. The `Bearer` scheme
+ * is matched case-insensitively per RFC 6750, while the token itself is
+ * preserved verbatim.
+ */
+export function extractBearerToken(authHeader) {
+    const match = /^bearer\s+/i.exec(authHeader !== null && authHeader !== void 0 ? authHeader : '');
+    if (!match) {
+        return null;
+    }
+    return (authHeader !== null && authHeader !== void 0 ? authHeader : '').slice(match[0].length).trim() || null;
+}
+function getHeader(headers, name) {
+    if (!headers) {
+        return undefined;
+    }
+    const lowerName = name.toLowerCase();
+    const entry = Object.entries(headers).find(([key]) => key.toLowerCase() === lowerName);
+    return entry === null || entry === void 0 ? void 0 : entry[1];
+}
+export function createAuthGuard(options) {
+    var _a, _b, _c;
+    const verifier = (_a = options.verifier) !== null && _a !== void 0 ? _a : createCognitoJwtVerifier(options.config, Object.assign(Object.assign({}, options.verifierOptions), { tokenUse: (_c = (_b = options.verifierOptions) === null || _b === void 0 ? void 0 : _b.tokenUse) !== null && _c !== void 0 ? _c : 'access' }));
+    function authorizeToken(token) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!token) {
+                throw new AuthError({
+                    code: authErrorCodes.unauthenticated,
+                    message: 'Authentication required',
+                    status: 401,
+                });
+            }
+            let session;
+            try {
+                session = yield verifier.verify(token);
+            }
+            catch (error) {
+                if (isAuthError(error)) {
+                    throw error;
+                }
+                throw new AuthError({
+                    code: authErrorCodes.invalidToken,
+                    message: 'Invalid or expired token',
+                    status: 401,
+                });
+            }
+            const principal = toPrincipal(session, options.policy);
+            if (options.allowedKinds) {
+                assertPrincipalKind(principal, options.allowedKinds);
+            }
+            return principal;
+        });
+    }
+    return {
+        authorize(event) {
+            return __awaiter(this, void 0, void 0, function* () {
+                const token = extractBearerToken(getHeader(event.headers, 'authorization'));
+                return authorizeToken(token);
+            });
+        },
+        authorizeToken,
+        verifier,
+    };
+}
+//# sourceMappingURL=auth-backend.js.map

package/src/auth-backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-backend.js","sourceRoot":"","sources":["../../../../packages/runtime/src/auth-backend.ts"],"names":[],"mappings":"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"}

package/src/auth-session.d.ts

@@ -0,0 +1,175 @@
+import type { AuthenticatedSession } from './auth.js';
+/**
+ * Cookie-based token persistence and clock-skew-aware token refresh
+ * primitives.
+ *
+ * Provides a dependency-light way for downstream consumers to persist
+ * Cognito tokens in bounded httpOnly cookies, detect when the access
+ * token is inside its refresh window, and rotate tokens without pulling a
+ * BetterAuth runtime dependency into `@empire-builder-kit/runtime`.
+ *
+ * The transport is deliberately injected: this module never calls the Cognito
+ * token endpoint itself. The consumer supplies a `refresh` callback (a POST to
+ * the hosted-UI `/oauth2/token` endpoint, an AWS SDK `InitiateAuth` call, or a
+ * fake in tests). Keeping the network out of the runtime keeps the primitive
+ * verifiable locally with mocked issuers, matching the rest of the auth
+ * surface.
+ *
+ * A server-side session adapter can replace the browser token plan when a
+ * product needs larger claims or centrally revocable sessions.
+ */
+export declare const authSessionContract: {
+    readonly exportPath: "@empire-builder-kit/runtime/auth-session";
+    readonly packageName: "@empire-builder-kit/runtime";
+};
+/**
+ * The token material persisted alongside the resolved session. Access and id
+ * tokens are short-lived Cognito JWTs; the refresh token is the long-lived
+ * secret used to mint new ones. `expiresAt` is the access-token expiry as an
+ * epoch-seconds value so refresh-window math never has to re-parse the JWT.
+ */
+export interface SessionTokens {
+    accessToken: string;
+    expiresAt: number;
+    idToken?: string;
+    refreshToken?: string;
+}
+/**
+ * Verified server-side session state plus the token material used by the
+ * refresh primitive. This object is deliberately not serialized to a browser
+ * cookie; consumers re-derive it from the issuer-signed access token.
+ */
+export interface SessionState {
+    session: AuthenticatedSession;
+    tokens: SessionTokens;
+}
+export declare const MAX_SESSION_TOKEN_COOKIE_BYTES = 3800;
+export declare const DEFAULT_REFRESH_TOKEN_MAX_AGE_SECONDS: number;
+/**
+ * Browser cookie options emitted by the token plan.
+ */
+export interface SessionCookieOptions {
+    httpOnly: boolean;
+    maxAge?: number;
+    name: string;
+    path: string;
+    sameSite: 'lax' | 'strict' | 'none';
+    secure: boolean;
+}
+export interface SessionTokenCookie extends SessionCookieOptions {
+    value: string;
+}
+export interface SessionTokenCookieNames {
+    access: string;
+    refresh: string;
+}
+export interface CreateSessionTokenCookiePlanOptions {
+    namespace: string;
+    now?: number;
+    refreshMaxAge?: number;
+    secure?: boolean;
+}
+export declare function getSessionTokenCookieNames(options: Pick<CreateSessionTokenCookiePlanOptions, 'namespace' | 'secure'>): SessionTokenCookieNames;
+/**
+ * Plans independent access and refresh cookies instead of serializing access,
+ * ID, refresh, and derived-session data into one value. Each production name
+ * uses the browser-enforced `__Host-` prefix (Secure, Path=/, no Domain), and
+ * every value is checked below the common 4 KiB per-cookie limit before a
+ * response is emitted. Access-token integrity remains issuer/JWT verified;
+ * refresh-token validity remains Cognito verified.
+ */
+export declare function createSessionTokenCookiePlan(tokens: SessionTokens, options: CreateSessionTokenCookiePlanOptions): SessionTokenCookie[];
+/**
+ * Emits expiry cookies with the same host, path, SameSite, and Secure
+ * attributes as the session cookies. Browsers otherwise reject deletion of a
+ * production `__Host-` cookie when `Secure` is omitted.
+ */
+export declare function createSessionTokenCookieDeletionPlan(options: Pick<CreateSessionTokenCookiePlanOptions, 'namespace' | 'secure'>): SessionTokenCookie[];
+export interface RefreshWindowOptions {
+    /** Current time as epoch seconds. Defaults to `Date.now() / 1000`. */
+    now?: number;
+    /**
+     * Clock skew allowance in seconds. Treated as if the local clock could be
+     * this far behind the issuer, so expiry is evaluated against `now + skew`.
+     * Defaults to 30s.
+     */
+    skewSeconds?: number;
+    /**
+     * How long before hard expiry the token is considered "expiring" and eligible
+     * for a proactive refresh. Defaults to 300s (5 minutes).
+     */
+    windowSeconds?: number;
+}
+/**
+ * True when the access token has already expired (accounting for clock skew).
+ */
+export declare function isTokenExpired(expiresAt: number, options?: RefreshWindowOptions): boolean;
+/**
+ * True when the access token is inside its refresh window: not necessarily
+ * expired yet, but close enough that a consumer should proactively refresh
+ * before the next protected call. Clock skew widens the window conservatively.
+ */
+export declare function isTokenExpiring(expiresAt: number, options?: RefreshWindowOptions): boolean;
+/**
+ * The subset of a Cognito token-endpoint response this refresh path consumes.
+ * A refresh-token grant returns a new access token (and usually a new id
+ * token) but reuses the caller's refresh token, so `refreshToken` is optional.
+ */
+export interface RefreshedTokens {
+    accessToken: string;
+    expiresIn: number;
+    idToken?: string;
+    refreshToken?: string;
+}
+/**
+ * Injected transport that exchanges a refresh token for new tokens. In the
+ * example this POSTs to the Cognito hosted-UI `/oauth2/token` endpoint; in
+ * tests it is a fake returning canned tokens. Keeping it injected means this
+ * module has no network dependency and stays verifiable with mocked issuers.
+ */
+export type RefreshTransport = (refreshToken: string) => Promise<RefreshedTokens>;
+export interface RefreshSessionOptions extends RefreshWindowOptions {
+    /**
+     * Force a refresh even when the token is not yet inside its window. Used by
+     * an explicit "refresh now" path; the default relies on {@link isTokenExpiring}.
+     */
+    force?: boolean;
+    refresh: RefreshTransport;
+    /**
+     * Rebuilds the resolved {@link AuthenticatedSession} from the freshly minted
+     * access token (typically your Cognito JWT verifier's output). The refresh
+     * grant only returns tokens, so the session must be re-derived to keep
+     * `expiresAt`/claims in sync.
+     */
+    resolveSession: (tokens: SessionTokens) => Promise<AuthenticatedSession> | AuthenticatedSession;
+}
+export type RefreshSessionResult = {
+    payload: SessionState;
+    refreshed: true;
+} | {
+    payload: SessionState;
+    refreshed: false;
+} | {
+    reason: 'missing_refresh_token';
+    refreshed: false;
+};
+/**
+ * The core refresh path for cookie-persisted sessions.
+ *
+ * When the token is still comfortably valid (and `force` is not set) it takes
+ * the steady-state path: it re-derives the session from the persisted access
+ * token via {@link RefreshSessionOptions.resolveSession} and returns it with
+ * `refreshed: false`. This re-derivation is the security boundary: callers
+ * never trust browser-provided session claims and instead run the JWT verifier
+ * over the issuer-signed access token.
+ *
+ * When inside the refresh window it calls the injected transport, re-resolves
+ * the session from the new access token, preserves the refresh token if the
+ * grant did not rotate it, and returns a fresh payload the caller can
+ * persist through the bounded cookie plan. It never throws for the "no refresh token"
+ * case — that is a normal terminal state a caller handles by forcing
+ * re-authentication — but transport/verify errors propagate (on both the
+ * refresh and the steady-state path) so the caller can decide whether to clear
+ * the session.
+ */
+export declare function refreshSession(payload: SessionState, options: RefreshSessionOptions): Promise<RefreshSessionResult>;

package/src/auth-session.js

@@ -0,0 +1,181 @@
+import { __awaiter } from "tslib";
+/**
+ * Cookie-based token persistence and clock-skew-aware token refresh
+ * primitives.
+ *
+ * Provides a dependency-light way for downstream consumers to persist
+ * Cognito tokens in bounded httpOnly cookies, detect when the access
+ * token is inside its refresh window, and rotate tokens without pulling a
+ * BetterAuth runtime dependency into `@empire-builder-kit/runtime`.
+ *
+ * The transport is deliberately injected: this module never calls the Cognito
+ * token endpoint itself. The consumer supplies a `refresh` callback (a POST to
+ * the hosted-UI `/oauth2/token` endpoint, an AWS SDK `InitiateAuth` call, or a
+ * fake in tests). Keeping the network out of the runtime keeps the primitive
+ * verifiable locally with mocked issuers, matching the rest of the auth
+ * surface.
+ *
+ * A server-side session adapter can replace the browser token plan when a
+ * product needs larger claims or centrally revocable sessions.
+ */
+export const authSessionContract = {
+    exportPath: '@empire-builder-kit/runtime/auth-session',
+    packageName: '@empire-builder-kit/runtime',
+};
+export const MAX_SESSION_TOKEN_COOKIE_BYTES = 3800;
+export const DEFAULT_REFRESH_TOKEN_MAX_AGE_SECONDS = 30 * 24 * 60 * 60;
+const COOKIE_NAMESPACE_PATTERN = /^[a-z0-9][a-z0-9-]{0,62}$/;
+export function getSessionTokenCookieNames(options) {
+    var _a;
+    const namespace = options.namespace.trim();
+    if (!COOKIE_NAMESPACE_PATTERN.test(namespace)) {
+        throw new Error('[runtime/auth-session] Cookie namespace must start with a lowercase letter or number and contain at most 63 lowercase letters, numbers, or hyphens.');
+    }
+    const secure = (_a = options.secure) !== null && _a !== void 0 ? _a : true;
+    const prefix = secure ? '__Host-ebk-' : 'ebk-';
+    return {
+        access: `${prefix}${namespace}-access`,
+        refresh: `${prefix}${namespace}-refresh`,
+    };
+}
+function assertCookieSized(value, label) {
+    const bytes = Buffer.byteLength(value, 'utf8');
+    if (bytes > MAX_SESSION_TOKEN_COOKIE_BYTES) {
+        throw new Error(`[runtime/auth-session] ${label} is ${bytes} bytes and cannot be persisted safely in a browser cookie. Reduce token claims or use a server-side session adapter.`);
+    }
+}
+/**
+ * Plans independent access and refresh cookies instead of serializing access,
+ * ID, refresh, and derived-session data into one value. Each production name
+ * uses the browser-enforced `__Host-` prefix (Secure, Path=/, no Domain), and
+ * every value is checked below the common 4 KiB per-cookie limit before a
+ * response is emitted. Access-token integrity remains issuer/JWT verified;
+ * refresh-token validity remains Cognito verified.
+ */
+export function createSessionTokenCookiePlan(tokens, options) {
+    var _a, _b, _c;
+    if (!tokens.accessToken) {
+        throw new Error('[runtime/auth-session] An access token is required.');
+    }
+    if (!Number.isFinite(tokens.expiresAt)) {
+        throw new Error('[runtime/auth-session] A finite access-token expiry is required.');
+    }
+    assertCookieSized(tokens.accessToken, 'Access token');
+    if (tokens.refreshToken) {
+        assertCookieSized(tokens.refreshToken, 'Refresh token');
+    }
+    const secure = (_a = options.secure) !== null && _a !== void 0 ? _a : true;
+    const names = getSessionTokenCookieNames({
+        namespace: options.namespace,
+        secure,
+    });
+    const common = {
+        httpOnly: true,
+        path: '/',
+        sameSite: 'strict',
+        secure,
+    };
+    const now = (_b = options.now) !== null && _b !== void 0 ? _b : Math.floor(Date.now() / 1000);
+    const cookies = [
+        Object.assign(Object.assign({}, common), { maxAge: Math.max(0, Math.floor(tokens.expiresAt - now)), name: names.access, value: tokens.accessToken }),
+    ];
+    if (tokens.refreshToken) {
+        cookies.push(Object.assign(Object.assign({}, common), { maxAge: (_c = options.refreshMaxAge) !== null && _c !== void 0 ? _c : DEFAULT_REFRESH_TOKEN_MAX_AGE_SECONDS, name: names.refresh, value: tokens.refreshToken }));
+    }
+    return cookies;
+}
+/**
+ * Emits expiry cookies with the same host, path, SameSite, and Secure
+ * attributes as the session cookies. Browsers otherwise reject deletion of a
+ * production `__Host-` cookie when `Secure` is omitted.
+ */
+export function createSessionTokenCookieDeletionPlan(options) {
+    var _a;
+    const secure = (_a = options.secure) !== null && _a !== void 0 ? _a : true;
+    const names = getSessionTokenCookieNames({
+        namespace: options.namespace,
+        secure,
+    });
+    return Object.values(names).map((name) => ({
+        httpOnly: true,
+        maxAge: 0,
+        name,
+        path: '/',
+        sameSite: 'strict',
+        secure,
+        value: '',
+    }));
+}
+function nowSeconds(options) {
+    var _a;
+    return (_a = options.now) !== null && _a !== void 0 ? _a : Math.floor(Date.now() / 1000);
+}
+/**
+ * True when the access token has already expired (accounting for clock skew).
+ */
+export function isTokenExpired(expiresAt, options = {}) {
+    var _a;
+    const skew = (_a = options.skewSeconds) !== null && _a !== void 0 ? _a : 30;
+    return nowSeconds(options) + skew >= expiresAt;
+}
+/**
+ * True when the access token is inside its refresh window: not necessarily
+ * expired yet, but close enough that a consumer should proactively refresh
+ * before the next protected call. Clock skew widens the window conservatively.
+ */
+export function isTokenExpiring(expiresAt, options = {}) {
+    var _a, _b;
+    const skew = (_a = options.skewSeconds) !== null && _a !== void 0 ? _a : 30;
+    const window = (_b = options.windowSeconds) !== null && _b !== void 0 ? _b : 300;
+    return nowSeconds(options) + skew + window >= expiresAt;
+}
+/**
+ * The core refresh path for cookie-persisted sessions.
+ *
+ * When the token is still comfortably valid (and `force` is not set) it takes
+ * the steady-state path: it re-derives the session from the persisted access
+ * token via {@link RefreshSessionOptions.resolveSession} and returns it with
+ * `refreshed: false`. This re-derivation is the security boundary: callers
+ * never trust browser-provided session claims and instead run the JWT verifier
+ * over the issuer-signed access token.
+ *
+ * When inside the refresh window it calls the injected transport, re-resolves
+ * the session from the new access token, preserves the refresh token if the
+ * grant did not rotate it, and returns a fresh payload the caller can
+ * persist through the bounded cookie plan. It never throws for the "no refresh token"
+ * case — that is a normal terminal state a caller handles by forcing
+ * re-authentication — but transport/verify errors propagate (on both the
+ * refresh and the steady-state path) so the caller can decide whether to clear
+ * the session.
+ */
+export function refreshSession(payload, options) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a, _b, _c;
+        const shouldRefresh = options.force === true ||
+            isTokenExpiring(payload.tokens.expiresAt, options);
+        if (!shouldRefresh) {
+            // Steady-state path: never trust caller-held `session` data directly.
+            // Re-derive it from the access token through the caller's verifier.
+            // Verify errors propagate exactly as on the refresh path.
+            const session = yield options.resolveSession(payload.tokens);
+            return { payload: { session, tokens: payload.tokens }, refreshed: false };
+        }
+        const refreshToken = payload.tokens.refreshToken;
+        if (!refreshToken) {
+            return { reason: 'missing_refresh_token', refreshed: false };
+        }
+        const refreshed = yield options.refresh(refreshToken);
+        const expiresAt = ((_a = options.now) !== null && _a !== void 0 ? _a : Math.floor(Date.now() / 1000)) + refreshed.expiresIn;
+        const tokens = {
+            accessToken: refreshed.accessToken,
+            expiresAt,
+            idToken: (_b = refreshed.idToken) !== null && _b !== void 0 ? _b : payload.tokens.idToken,
+            // Cognito refresh-token grants reuse the caller's refresh token unless
+            // refresh-token rotation is enabled; preserve the old one when absent.
+            refreshToken: (_c = refreshed.refreshToken) !== null && _c !== void 0 ? _c : refreshToken,
+        };
+        const session = yield options.resolveSession(tokens);
+        return { payload: { session, tokens }, refreshed: true };
+    });
+}
+//# sourceMappingURL=auth-session.js.map

package/src/auth-session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-session.js","sourceRoot":"","sources":["../../../../packages/runtime/src/auth-session.ts"],"names":[],"mappings":"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"}

package/src/auth-web.d.ts

@@ -0,0 +1,79 @@
+import { type AuthPolicy, type AuthSession, type BetterAuthConfig, type Principal, type PrincipalKind } from './auth.js';
+import { type CognitoJwtVerifierOptions } from './auth-backend.js';
+export interface AuthMiddlewareRequest {
+    headers: {
+        get(name: string): string | null;
+    };
+}
+export interface CreateAuthMiddlewareConfigOptions {
+    policy?: AuthPolicy;
+    verifierOptions?: CognitoJwtVerifierOptions;
+}
+/**
+ * Creates Next.js middleware configuration for auth.
+ * Validates JWTs from the standard Authorization header.
+ *
+ * The verifier defaults to `tokenUse: 'access'` (matching `createAuthGuard`),
+ * so a Cognito id token — which is audience-scoped to the client and not
+ * intended as an API access credential (OAuth 2.0 Security BCP / RFC 9700) —
+ * is rejected as a bearer credential. Pass `verifierOptions.tokenUse` to
+ * override (e.g. `'any'` or `'id'`).
+ */
+export declare function createAuthMiddlewareConfig(config: BetterAuthConfig, options?: CreateAuthMiddlewareConfigOptions): {
+    verifier: import("./auth-backend.js").CognitoJwtVerifier;
+    getSession: (request: AuthMiddlewareRequest) => Promise<import("./auth.js").AuthenticatedSession | null>;
+    /**
+     * Resolve a typed principal from the request session. Returns null
+     * (never throws) when the token is missing/invalid, no policy is
+     * configured, or the session maps to no principal kind.
+     */
+    getPrincipal(request: AuthMiddlewareRequest): Promise<Principal | null>;
+};
+export interface RouteRule {
+    /** Principal kinds allowed on this route; omit to allow any principal. */
+    allow?: PrincipalKind[];
+    /** Path prefix; '/admin' matches '/admin' and '/admin/*'. */
+    path: string;
+    /** Public routes skip authentication entirely. */
+    public?: boolean;
+}
+export type UnmatchedRouteBehavior = 'allow' | 'deny';
+export type RouteGuardDecision = {
+    allowed: true;
+    principal?: Principal;
+} | {
+    allowed: false;
+    reason: 'forbidden' | 'unauthenticated';
+    status: 401 | 403;
+};
+export interface RouteGuard {
+    check(pathname: string, session: AuthSession | null | undefined): RouteGuardDecision;
+}
+export interface CreateRouteGuardOptions {
+    /**
+     * How to handle paths with no matching route rule. Defaults to deny so
+     * generated middleware fails closed when a protected path is forgotten.
+     *
+     * Keep the default `deny`. Route matching is case-sensitive (see
+     * {@link createRouteGuard}), so setting `allow` on a routing layer that
+     * treats paths case-insensitively lets requests like `/Admin` slip past a
+     * `/admin` rule and reach a protected tree unguarded.
+     */
+    defaultBehavior?: UnmatchedRouteBehavior;
+    policy: AuthPolicy;
+    rules: RouteRule[];
+}
+/**
+ * Framework-agnostic route guard for web middleware. Returns a decision
+ * object instead of throwing so middleware templates can translate it into
+ * redirects or responses. The most specific (longest) matching rule wins;
+ * equal-length rules keep their input order; unmatched paths are denied
+ * unless `defaultBehavior` is set to `allow`.
+ *
+ * Path matching is case-sensitive: `/Admin` does not match a `/admin` rule.
+ * Under the default `deny` this fails closed (an unmatched `/Admin` is
+ * denied). Do not combine `defaultBehavior: 'allow'` with a case-insensitive
+ * routing layer, or a case-variant of a protected path can bypass its rule
+ * and fall through to `allow`.
+ */
+export declare function createRouteGuard(options: CreateRouteGuardOptions): RouteGuard;