@zero-server/cli 0.9.1 → 0.9.3

package/types/auth.d.ts

@@ -0,0 +1,520 @@
+import { Request } from './request';
+import { Response } from './response';
+import { MiddlewareFunction } from './middleware';
+
+// --- JWT ---------------------------------------------------------
+
+export interface JwtHeader {
+    alg: string;
+    typ: string;
+    kid?: string;
+    [key: string]: any;
+}
+
+export interface JwtPayload {
+    iss?: string;
+    sub?: string;
+    aud?: string | string[];
+    exp?: number;
+    nbf?: number;
+    iat?: number;
+    jti?: string;
+    [key: string]: any;
+}
+
+export interface JwtDecoded {
+    header: JwtHeader;
+    payload: JwtPayload;
+    signature: string;
+}
+
+export interface JwtSignOptions {
+    algorithm?: string;
+    expiresIn?: number;
+    issuer?: string;
+    audience?: string;
+    subject?: string;
+    jwtId?: string;
+    notBefore?: number;
+    header?: Record<string, any>;
+}
+
+export interface JwtVerifyOptions {
+    algorithms?: string | string[];
+    audience?: string | string[];
+    issuer?: string | string[];
+    subject?: string;
+    clockTolerance?: number;
+    maxAge?: number;
+    ignoreExpiration?: boolean;
+}
+
+export interface JwtVerifyResult {
+    header: JwtHeader;
+    payload: JwtPayload;
+}
+
+export interface JwtMiddlewareOptions {
+    secret?: string | Buffer;
+    publicKey?: string | Buffer;
+    getKey?: (header: JwtHeader, payload: JwtPayload) => string | Buffer | Promise<string | Buffer>;
+    jwksUri?: string;
+    algorithms?: string | string[];
+    getToken?: (req: Request) => string | null;
+    tokenLocation?: 'header' | 'cookie' | 'query';
+    cookieName?: string;
+    queryParam?: string;
+    audience?: string | string[];
+    issuer?: string | string[];
+    subject?: string;
+    clockTolerance?: number;
+    maxAge?: number;
+    credentialsRequired?: boolean;
+    isRevoked?: (payload: JwtPayload) => boolean | Promise<boolean>;
+    onError?: (err: { message: string; code: string; statusCode: number }, req: Request, res: Response) => void;
+    fetcher?: Function;
+    cacheTtl?: number;
+}
+
+export function jwt(opts: JwtMiddlewareOptions): MiddlewareFunction;
+export function jwtSign(payload: Record<string, any>, secret: string | Buffer, opts?: JwtSignOptions): string;
+export function jwtVerify(token: string, secretOrKey: string | Buffer, opts?: JwtVerifyOptions): JwtVerifyResult;
+export function jwtDecode(token: string): JwtDecoded | null;
+
+export interface JwksGetKey {
+    (header: JwtHeader, payload?: JwtPayload): Promise<string>;
+    _clearCache(): void;
+}
+
+export interface JwksOptions {
+    fetcher?: Function;
+    cacheTtl?: number;
+    requestTimeout?: number;
+}
+
+export function jwks(jwksUri: string, opts?: JwksOptions): JwksGetKey;
+
+export interface TokenPairConfig {
+    accessSecret: string | Buffer;
+    refreshSecret?: string | Buffer;
+    accessExpiresIn?: number;
+    refreshExpiresIn?: number;
+    algorithm?: string;
+}
+
+export interface TokenPairInstance {
+    generateTokens(payload: Record<string, any>): { accessToken: string; refreshToken: string };
+    verifyRefreshToken(token: string): JwtVerifyResult;
+    verifyAccessToken(token: string): JwtVerifyResult;
+}
+
+export function tokenPair(config: TokenPairConfig): TokenPairInstance;
+export function createRefreshToken(payload: Record<string, any>, secret: string | Buffer, opts?: { expiresIn?: number; algorithm?: string }): string;
+export const SUPPORTED_ALGORITHMS: string[];
+
+// --- Session -----------------------------------------------------
+
+export interface SessionData {
+    [key: string]: any;
+}
+
+export declare class Session {
+    id: string;
+    constructor(id: string, data?: SessionData);
+    get(key: string): any;
+    set(key: string, value: any): Session;
+    has(key: string): boolean;
+    delete(key: string): boolean;
+    all(): SessionData;
+    readonly size: number;
+    clear(): Session;
+    destroy(): void;
+    regenerate(): void;
+    flash(key: string, value: any): Session;
+    flashes(key?: string): any[] | Record<string, any[]>;
+}
+
+export interface SessionCookieOptions {
+    maxAge?: number;
+    path?: string;
+    domain?: string;
+    secure?: boolean;
+    httpOnly?: boolean;
+    sameSite?: 'Strict' | 'Lax' | 'None' | string;
+}
+
+export interface SessionStore {
+    get(sid: string): Promise<string | null>;
+    set(sid: string, data: string, maxAge?: number): Promise<void>;
+    destroy(sid: string): Promise<void>;
+}
+
+export interface MemoryStoreOptions {
+    ttl?: number;
+    pruneInterval?: number;
+    maxSessions?: number;
+}
+
+export declare class MemoryStore implements SessionStore {
+    constructor(opts?: MemoryStoreOptions);
+    get(sid: string): Promise<string | null>;
+    set(sid: string, data: string, maxAge?: number): Promise<void>;
+    destroy(sid: string): Promise<void>;
+    readonly length: number;
+    clear(): void;
+    close(): void;
+}
+
+export interface SessionOptions {
+    secret: string | string[];
+    store?: SessionStore;
+    name?: string;
+    cookie?: SessionCookieOptions;
+    rolling?: boolean;
+    genid?: () => string;
+}
+
+export function session(opts: SessionOptions): MiddlewareFunction;
+
+// --- OAuth2 ------------------------------------------------------
+
+export interface OAuthProviderPreset {
+    authorizeUrl: string;
+    tokenUrl: string;
+    userInfoUrl: string | null;
+    scope: string;
+    pkce: boolean;
+    responseMode?: string;
+}
+
+export interface OAuthOptions {
+    provider?: 'google' | 'github' | 'microsoft' | 'apple';
+    clientId: string;
+    clientSecret: string;
+    callbackUrl: string;
+    authorizeUrl?: string;
+    tokenUrl?: string;
+    userInfoUrl?: string;
+    scope?: string;
+    pkce?: boolean;
+    responseMode?: string;
+    fetcher?: Function;
+    timeout?: number;
+}
+
+export interface OAuthAuthorizeResult {
+    url: string;
+    state: string;
+    codeVerifier?: string;
+}
+
+export interface OAuthTokens {
+    access_token: string;
+    token_type: string;
+    expires_in?: number;
+    refresh_token?: string;
+    id_token?: string;
+    scope?: string;
+    [key: string]: any;
+}
+
+export interface OAuthClient {
+    authorize(params?: { scope?: string; state?: string; extra?: Record<string, string> }): OAuthAuthorizeResult;
+    callback(query: { code?: string; state?: string; error?: string; error_description?: string }, verify?: { state?: string; codeVerifier?: string }): Promise<OAuthTokens>;
+    refresh(refreshToken: string): Promise<OAuthTokens>;
+    userInfo(accessToken: string): Promise<Record<string, any>>;
+    readonly config: Readonly<OAuthOptions>;
+}
+
+export function oauth(opts: OAuthOptions): OAuthClient;
+export function generatePKCE(length?: number): { codeVerifier: string; codeChallenge: string };
+export function generateState(bytes?: number): string;
+export const OAUTH_PROVIDERS: Record<string, OAuthProviderPreset>;
+
+// --- Authorization -----------------------------------------------
+
+export function authorize(...roles: (string | string[])[]): MiddlewareFunction;
+export function can(...permissions: (string | string[])[]): MiddlewareFunction;
+export function canAny(...permissions: (string | string[])[]): MiddlewareFunction;
+
+export declare class Policy {
+    before?(user: any, action: string, resource?: any): boolean | undefined;
+    check(action: string, user: any, resource?: any): boolean | Promise<boolean>;
+    [action: string]: any;
+}
+
+export function gate(
+    policy: Policy,
+    action: string,
+    getResource?: (req: Request) => any | Promise<any>,
+): MiddlewareFunction;
+
+export function attachUserHelpers(): MiddlewareFunction;
+
+// --- Two-Factor Authentication -----------------------------------
+
+export interface TwoFactorSecret {
+    raw: Buffer;
+    base32: string;
+    hex: string;
+}
+
+export interface TOTPOptions {
+    period?: number;
+    digits?: number;
+    algorithm?: 'sha1' | 'sha256' | 'sha512';
+    time?: number;
+}
+
+export interface TOTPVerifyOptions extends TOTPOptions {
+    window?: number;
+}
+
+export interface TOTPVerifyResult {
+    valid: boolean;
+    delta: number | null;
+}
+
+export interface OtpauthURIOptions {
+    secret: string | Buffer;
+    issuer: string;
+    account: string;
+    period?: number;
+    digits?: number;
+    algorithm?: 'sha1' | 'sha256' | 'sha512';
+}
+
+export interface BackupCodesResult {
+    codes: string[];
+    hashes: string[];
+}
+
+export interface BackupCodeVerifyResult {
+    valid: boolean;
+    index: number | null;
+}
+
+export interface Require2FAOptions {
+    sessionKey?: string;
+    errorMessage?: string;
+    statusCode?: number;
+    isEnabled?: (req: Request) => boolean | Promise<boolean>;
+}
+
+export interface VerifyTOTPMiddlewareOptions {
+    getSecret: (req: Request) => string | Buffer | Promise<string | Buffer>;
+    codeField?: string;
+    sessionKey?: string;
+    maxAttempts?: number;
+    lockoutMs?: number;
+    window?: number;
+    period?: number;
+    algorithm?: 'sha1' | 'sha256' | 'sha512';
+    digits?: number;
+    replayStore?: ReplayStore;
+    getUserId?: (req: Request) => string | Promise<string>;
+    onSuccess?: (req: Request, res: Response) => void;
+    onFailure?: (req: Request, res: Response, attemptsLeft: number) => void;
+}
+
+export interface ReplayStore {
+    get(userId: string): Promise<number | null>;
+    set(userId: string, counter: number, ttlMs: number): Promise<void>;
+}
+
+export declare class InMemoryReplayStore implements ReplayStore {
+    constructor();
+    get(userId: string): Promise<number | null>;
+    set(userId: string, counter: number, ttlMs: number): Promise<void>;
+    clear(): void;
+    destroy(): void;
+}
+
+export interface Verify2FAOptions {
+    getSecret: (req: Request) => string | Buffer | Promise<string | Buffer>;
+    getBackupHashes?: (req: Request) => string[] | Promise<string[]>;
+    onBackupUsed?: (req: Request, index: number) => void | Promise<void>;
+    getCredential?: (req: Request, credId: string) => any | Promise<any>;
+    updateCredentialCounter?: (req: Request, credId: string, newCounter: number) => void | Promise<void>;
+    expectedOrigin?: string;
+    expectedRPID?: string;
+    codeField?: string;
+    backupField?: string;
+    sessionKey?: string;
+    maxAttempts?: number;
+    lockoutMs?: number;
+    window?: number;
+    period?: number;
+    algorithm?: 'sha1' | 'sha256' | 'sha512';
+    digits?: number;
+    replayStore?: ReplayStore;
+    getUserId?: (req: Request) => string | Promise<string>;
+    onSuccess?: (req: Request, res: Response, method: 'totp' | 'backup' | 'webauthn') => void;
+    onFailure?: (req: Request, res: Response, attemptsLeft: number) => void;
+}
+
+export interface TwoFactor {
+    generateSecret(bytes?: number): TwoFactorSecret;
+    generateTOTP(secret: string | Buffer, opts?: TOTPOptions): string;
+    verifyTOTP(token: string, secret: string | Buffer, opts?: TOTPVerifyOptions): TOTPVerifyResult;
+    otpauthURI(opts: OtpauthURIOptions): string;
+    generateBackupCodes(count?: number, bytes?: number): BackupCodesResult;
+    verifyBackupCode(code: string, hashes: string[]): BackupCodeVerifyResult;
+    require2FA(opts?: Require2FAOptions): MiddlewareFunction;
+    verifyTOTPMiddleware(opts: VerifyTOTPMiddlewareOptions): MiddlewareFunction;
+    verify2FA(opts: Verify2FAOptions): MiddlewareFunction;
+    InMemoryReplayStore: typeof InMemoryReplayStore;
+    DEFAULT_PERIOD: number;
+    DEFAULT_DIGITS: number;
+    DEFAULT_ALGORITHM: string;
+    DEFAULT_WINDOW: number;
+    SUPPORTED_TOTP_ALGORITHMS: string[];
+}
+
+export const twoFactor: TwoFactor;
+
+// --- WebAuthn / Passkeys -----------------------------------------
+
+export interface WebAuthnRegistrationOptions {
+    rpName: string;
+    rpId: string;
+    userId: string;
+    userName: string;
+    userDisplayName?: string;
+    challenge?: Buffer;
+    challengeSize?: number;
+    attestation?: 'none' | 'direct' | 'indirect';
+    authenticatorSelection?: {
+        authenticatorAttachment?: 'platform' | 'cross-platform';
+        residentKey?: 'discouraged' | 'preferred' | 'required';
+        requireResidentKey?: boolean;
+        userVerification?: 'discouraged' | 'preferred' | 'required';
+    };
+    excludeCredentials?: Array<{ id: string | Buffer; type?: string; transports?: string[] }>;
+    timeout?: number;
+}
+
+export interface WebAuthnRegistrationResult {
+    verified: boolean;
+    credential: {
+        id: string;
+        publicKey: Buffer;
+        counter: number;
+        type: string;
+        transports?: string[];
+    };
+    authData: {
+        rpIdHash: Buffer;
+        flags: number;
+        signCount: number;
+        aaguid: Buffer;
+        credentialId: Buffer;
+    };
+}
+
+export interface WebAuthnVerifyRegistrationOptions {
+    response: any;
+    expectedChallenge: string;
+    expectedOrigin: string;
+    expectedRPID: string;
+}
+
+export interface WebAuthnAuthenticationOptions {
+    rpId: string;
+    challenge?: Buffer;
+    challengeSize?: number;
+    allowCredentials?: Array<{ id: string | Buffer; type?: string; transports?: string[] }>;
+    userVerification?: 'discouraged' | 'preferred' | 'required';
+    timeout?: number;
+}
+
+export interface WebAuthnAuthenticationResult {
+    verified: boolean;
+    authData: {
+        rpIdHash: Buffer;
+        flags: number;
+        signCount: number;
+    };
+}
+
+export interface WebAuthnVerifyAuthenticationOptions {
+    response: any;
+    expectedChallenge: string;
+    expectedOrigin: string;
+    expectedRPID: string;
+    credential: { publicKey: Buffer; counter: number; id?: string };
+}
+
+export interface WebAuthn {
+    generateRegistrationOptions(opts: WebAuthnRegistrationOptions): any;
+    verifyRegistration(opts: WebAuthnVerifyRegistrationOptions): Promise<WebAuthnRegistrationResult>;
+    generateAuthenticationOptions(opts: WebAuthnAuthenticationOptions): any;
+    verifyAuthentication(opts: WebAuthnVerifyAuthenticationOptions): Promise<WebAuthnAuthenticationResult>;
+}
+
+export const webauthn: WebAuthn;
+
+// --- Trusted Device / Remember Me --------------------------------
+
+export interface TrustedDeviceIssueOptions {
+    secret: string;
+    maxAge?: number;
+    cookieName?: string;
+    fingerprint?: (req: Request) => string | Promise<string>;
+    getUserId?: (req: Request) => string | Promise<string>;
+}
+
+export interface TrustedDeviceVerifyOptions {
+    secret: string;
+    previousSecrets?: string | string[];
+    cookieName?: string;
+    fingerprint?: (req: Request) => string | Promise<string>;
+    getUserId?: (req: Request) => string | Promise<string>;
+    checkIP?: boolean;
+}
+
+export interface TrustedDeviceRevokeOptions {
+    cookieName?: string;
+}
+
+export interface TrustedDevice {
+    issue(opts: TrustedDeviceIssueOptions): MiddlewareFunction;
+    verify(opts: TrustedDeviceVerifyOptions): (req: Request) => Promise<boolean>;
+    revoke(opts?: TrustedDeviceRevokeOptions): MiddlewareFunction;
+}
+
+export const trustedDevice: TrustedDevice;
+
+// --- 2FA Enrollment Flow -----------------------------------------
+
+export interface EnrollmentOptions {
+    saveSecret: (req: Request, secret: string, backupHashes: string[]) => Promise<void>;
+    removeSecret: (req: Request) => Promise<void>;
+    issuer?: string;
+    getAccount?: (req: Request) => string | Promise<string>;
+    sessionKey?: string;
+    ttl?: number;
+    backupCount?: number;
+    window?: number;
+    period?: number;
+    algorithm?: 'sha1' | 'sha256' | 'sha512';
+    digits?: number;
+    isEnabled?: (req: Request) => boolean | Promise<boolean>;
+}
+
+export interface EnrollmentDisableOptions {
+    confirm?: (req: Request) => boolean | Promise<boolean>;
+}
+
+export interface EnrollmentVerifyOptions {
+    codeField?: string;
+}
+
+export interface EnrollmentFlow {
+    start(): MiddlewareFunction;
+    verify(opts?: EnrollmentVerifyOptions): MiddlewareFunction;
+    complete(): MiddlewareFunction;
+    disable(opts?: EnrollmentDisableOptions): MiddlewareFunction;
+}
+
+export function enrollment(opts: EnrollmentOptions): EnrollmentFlow;

package/types/body.d.ts

@@ -0,0 +1,14 @@
+// Re-exports for @zero-server/body — body parser types
+export {
+    BodyParserOptions,
+    JsonParserOptions,
+    UrlencodedParserOptions,
+    TextParserOptions,
+    MultipartOptions,
+    MultipartFile,
+    json,
+    urlencoded,
+    text,
+    raw,
+    multipart,
+} from './middleware';

package/types/cli.d.ts

@@ -0,0 +1,2 @@
+// Re-exports for @zero-server/cli — CLI runner types
+export { CLI, runCLI } from './orm';

package/types/cluster.d.ts

@@ -0,0 +1,75 @@
+/// <reference types="node" />
+
+import { Worker } from 'cluster';
+
+export interface ClusterOptions {
+    /** Number of worker processes (default: CPU count). */
+    workers?: number;
+    /** Automatically respawn crashed workers (default: true). */
+    respawn?: boolean;
+    /** Initial delay (ms) before respawning (default: 1000). */
+    respawnDelay?: number;
+    /** Maximum respawn delay after backoff (default: 30000). */
+    maxRespawnDelay?: number;
+    /** Multiplier for exponential backoff (default: 2). */
+    backoffFactor?: number;
+}
+
+export declare class ClusterManager {
+    constructor(opts?: ClusterOptions);
+
+    /** Whether this is the primary (master) process. */
+    readonly isPrimary: boolean;
+
+    /** Whether this is a worker process. */
+    readonly isWorker: boolean;
+
+    /** Configured number of workers. */
+    readonly workerCount: number;
+
+    /** IDs of currently active workers. */
+    readonly workerIds: number[];
+
+    /** Number of currently alive workers. */
+    readonly activeWorkers: number;
+
+    /** Fork all worker processes. */
+    fork(): ClusterManager;
+
+    /** Broadcast a typed message to all workers. */
+    broadcast(type: string, data: any): void;
+
+    /** Send a typed message to a specific worker. */
+    sendTo(workerId: number, type: string, data: any): void;
+
+    /** Send a typed message from a worker to the primary. */
+    sendToPrimary(type: string, data: any): void;
+
+    /** Register a handler for a typed IPC message. */
+    onMessage(type: string, fn: (data: any, worker?: Worker) => void): ClusterManager;
+
+    /** Perform a rolling restart of all workers. */
+    reload(): Promise<void>;
+
+    /** Shut down the entire cluster gracefully. */
+    shutdown(opts?: { timeout?: number }): Promise<void>;
+
+    /** Enable automatic per-worker metrics aggregation. */
+    enableMetrics(registry: import('./observe').MetricsRegistry, opts?: { interval?: number }): ClusterManager;
+
+    /** Stop the per-worker metrics reporting timer. */
+    disableMetrics(): void;
+
+    /** Enable sticky sessions by hashing client IPs to workers. */
+    enableSticky(server: import('http').Server | import('https').Server, opts?: {
+        hash?: (ip: string, workerCount: number) => number;
+    }): ClusterManager;
+}
+
+/**
+ * High-level clustering helper.
+ */
+export declare function cluster(
+    workerFn: (mgr: ClusterManager) => void,
+    opts?: ClusterOptions
+): ClusterManager;

package/types/env.d.ts

@@ -0,0 +1,80 @@
+// --- Env Field Definition ----------------------------------------
+
+export interface EnvFieldDef {
+    /** Value type for coercion. */
+    type?: 'string' | 'number' | 'integer' | 'boolean' | 'port' | 'array' | 'json' | 'url' | 'enum';
+    /** Field is required. */
+    required?: boolean;
+    /** Default value (or function returning a value). */
+    default?: any | (() => any);
+    /** Min value (number/integer) or min length (string). */
+    min?: number;
+    /** Max value (number/integer) or max length (string). */
+    max?: number;
+    /** Pattern match (string type). */
+    match?: RegExp;
+    /** Delimiter for array type. Default: ','. */
+    separator?: string;
+    /** Allowed values for enum type. */
+    values?: string[];
+}
+
+export type EnvSchema = Record<string, EnvFieldDef>;
+
+export interface EnvLoadOptions {
+    /** Directory to load .env files from. Default: `process.cwd()`. */
+    path?: string;
+    /** Write file values into `process.env`. Default: false. */
+    override?: boolean;
+}
+
+// --- Env Proxy ---------------------------------------------------
+
+export interface Env {
+    /**
+     * Get a variable by key.
+     */
+    (key: string): any;
+
+    /**
+     * Load environment variables, optionally with a typed schema.
+     */
+    load(schema?: EnvSchema, options?: EnvLoadOptions): Record<string, any>;
+
+    /**
+     * Get a variable by key.
+     */
+    get(key: string): any;
+
+    /**
+     * Get a variable by key, throwing if missing.
+     */
+    require(key: string): any;
+
+    /**
+     * Check if a variable exists (in store or `process.env`).
+     */
+    has(key: string): boolean;
+
+    /**
+     * Return all loaded variables.
+     */
+    all(): Record<string, any>;
+
+    /**
+     * Clear all loaded variables from the internal store.
+     */
+    reset(): void;
+
+    /**
+     * Parse a raw `.env` string into key-value pairs.
+     */
+    parse(src: string): Record<string, string>;
+
+    /**
+     * Property access for variables (e.g., `env.PORT`).
+     */
+    [key: string]: any;
+}
+
+export const env: Env;