@cosmstack/blackshield/dist/server/index.d.cts

A developer-first security toolkit for React/Next.js applications

import { z } from 'zod';
import { NextRequest, NextResponse } from 'next/server';

interface SecureUser {
    id: string;
    email?: string;
    roles?: string[];
    permissions?: string[];
    metadata?: Record<string, unknown>;
}
interface ServerInputValidation<T = unknown> {
    data: T;
    errors: Record<string, string[]>;
    isValid: boolean;
}
interface CsrfToken {
    token: string;
    expiresAt: number;
}
interface CsrfConfig {
    tokenHeader?: string;
    tokenCookie?: string;
    tokenExpiry?: number;
}

declare function validateServerInput<T>(schema: z.ZodSchema<T>, input: unknown): ServerInputValidation<T>;
declare function createServerValidator<T>(schema: z.ZodSchema<T>): (input: unknown) => ServerInputValidation<T>;
declare const commonSchemas: {
    email: z.ZodString;
    password: z.ZodString;
    id: z.ZodString;
    slug: z.ZodString;
    url: z.ZodString;
    safeString: z.ZodString;
};

interface SecureCookieOptions {
    maxAge?: number;
    httpOnly?: boolean;
    secure?: boolean;
    sameSite?: 'strict' | 'lax' | 'none';
    path?: string;
}
declare function createSignedCookie(name: string, value: unknown, options?: SecureCookieOptions): Promise<void>;
declare function readSecureCookie<T = unknown>(name: string): Promise<T | null>;
declare function deleteSecureCookie(name: string): Promise<void>;

/**
 * Generate a new CSRF token
 */
declare function generateCsrfToken(config?: Partial<CsrfConfig>): Promise<CsrfToken>;
/**
 * Verify a CSRF token
 */
declare function verifyCsrfToken(token: string): Promise<boolean>;
/**
 * Set CSRF token in cookie
 */
declare function setCsrfTokenCookie(config?: Partial<CsrfConfig>): Promise<string>;
/**
 * Validate CSRF token from request
 */
declare function validateCsrfToken(req: NextRequest, config?: Partial<CsrfConfig>): Promise<boolean>;
/**
 * CSRF middleware for API routes
 */
declare function csrfMiddleware(config?: Partial<CsrfConfig>): (req: NextRequest) => Promise<Response | null>;

interface ProtectOptions {
    /** Require authentication */
    requireAuth?: boolean;
    /** Required user roles */
    roles?: string[];
    /** Required permissions */
    permissions?: string[];
    /** CSRF protection configuration */
    csrf?: boolean | Partial<CsrfConfig>;
    /** Rate limiting configuration */
    rateLimit?: {
        /** Maximum requests per window */
        max: number;
        /** Time window in seconds */
        windowSeconds: number;
        /** Custom key generator */
        keyGenerator?: (req: NextRequest) => string;
    };
    /** Input validation schema */
    schemaValidation?: z.ZodSchema;
    /** Custom authorization function */
    customAuth?: (user: SecureUser | null, req: NextRequest) => boolean | Promise<boolean>;
}
interface ProtectedContext {
    user: SecureUser | null;
    validatedInput?: unknown;
}
type ProtectedHandler<T = unknown> = (req: NextRequest, context: ProtectedContext, params?: T) => Promise<NextResponse> | NextResponse;
declare function protect<T = unknown>(handler: ProtectedHandler<T>, options?: ProtectOptions): (req: NextRequest, params?: T) => Promise<NextResponse>;
declare function protectServerAction<T extends unknown[], R>(action: (...args: T) => Promise<R>, options?: Omit<ProtectOptions, 'rateLimit'>): (...args: T) => Promise<R | {
    error: string;
    status: number;
}>;

export { type ProtectOptions, type SecureCookieOptions, type ServerInputValidation, commonSchemas, createServerValidator, createSignedCookie, csrfMiddleware, deleteSecureCookie, generateCsrfToken, protect, protectServerAction, readSecureCookie, setCsrfTokenCookie, validateCsrfToken, validateServerInput, verifyCsrfToken };