@nilejs/nile 0.0.6 → 0.0.7

package/dist/index.d.cts

@@ -1,8 +1,55 @@
-import { Context, Hono } from 'hono';
 import { Result, ErrType, ResultMethods } from 'slang-ts';
+import { Context, Hono } from 'hono';
 import { Store } from 'hono-rate-limiter';
 import z, { ZodTypeAny } from 'zod';
 
+/** Where to extract the JWT token from incoming requests */
+type TokenSource = "header" | "cookie";
+/**
+ * Server-level auth configuration.
+ * Kept intentionally lean — only JWT verification via hono/jwt.
+ * For custom auth logic (RBAC, API keys, sessions), use onBeforeActionHandler.
+ */
+interface AuthConfig {
+    /** JWT secret used for token verification */
+    secret: string;
+    /** Where to look for the token (default: "header") */
+    method?: TokenSource;
+    /** Cookie name when method is "cookie" (default: "auth_token") */
+    cookieName?: string;
+    /** Header name when method is "header" (default: "authorization") */
+    headerName?: string;
+}
+/** Successful auth result populated on NileContext after verification */
+interface AuthResult {
+    userId: string;
+    organizationId: string;
+    /** Raw decoded JWT claims for custom logic in hooks */
+    claims: Record<string, unknown>;
+}
+/**
+ * Auth context passed to the JWT handler — carries the raw
+ * request data needed for token extraction.
+ */
+interface AuthContext {
+    headers?: Headers;
+    cookies?: Record<string, string>;
+}
+/**
+ * Auth handler function signature.
+ * Returns Ok(AuthResult) on success, Err(message) on failure.
+ */
+type AuthHandler = (context: AuthContext, config: AuthConfig) => Promise<Result<AuthResult, string>>;
+
+/**
+ * Lean JWT authentication handler.
+ * Extracts token from header or cookie, verifies via hono/jwt,
+ * and returns AuthResult with userId, organizationId, and raw claims.
+ *
+ * For anything beyond JWT (RBAC, API keys, sessions), use onBeforeActionHandler.
+ */
+declare function verifyJWT(context: AuthContext, config: AuthConfig): Promise<Result<AuthResult, string>>;
+
 /**
  * CORS options compatible with Hono's cors middleware
  */
@@ -173,6 +220,16 @@ interface NileContext<TDB = unknown> {
     getSession: (name: keyof Sessions) => Record<string, unknown> | undefined;
     /** Store session data for a specific interface */
     setSession: (name: keyof Sessions, data: Record<string, unknown>) => void;
+    /** Auth result populated after successful JWT verification */
+    authResult?: AuthResult;
+    /** Get the raw auth result after JWT verification */
+    getAuth: () => AuthResult | undefined;
+    /** Get authenticated user identity (userId + organizationId) */
+    getUser: () => {
+        userId: string;
+        organizationId: string;
+        [key: string]: unknown;
+    } | undefined;
     hookContext: HookContext;
     updateHookState: (key: string, value: unknown) => void;
     addHookLog: (phase: "before" | "after", logEntry: {
@@ -205,6 +262,8 @@ interface ServerConfig {
     /** Print registered services table to console on boot (default: true) */
     logServices?: boolean;
     resources?: Resources<unknown>;
+    /** JWT auth configuration — enables built-in token verification for protected actions */
+    auth?: AuthConfig;
     rest?: RestConfig;
     websocket?: Record<string, unknown>;
     rpc?: Record<string, unknown>;
@@ -312,6 +371,8 @@ interface EngineOptions {
         info: (msg: string, data?: unknown) => void;
     } | NileLogger;
     services: Services;
+    /** JWT auth configuration — when provided, protected actions require valid tokens */
+    auth?: AuthConfig;
     onBeforeActionHandler?: BeforeActionHandler<unknown, unknown>;
     onAfterActionHandler?: AfterActionHandler<unknown, unknown>;
 }
@@ -320,7 +381,7 @@ interface Engine {
     getServices: () => Result<ServiceSummary[], string>;
     getServiceActions: (serviceName: string) => Result<ActionSummary[], string>;
     getAction: (serviceName: string, actionName: string) => Result<Action, string>;
-    executeAction: (serviceName: string, actionName: string, payload: unknown, nileContext: NileContext<unknown>) => Promise<Result<unknown, string>>;
+    executeAction: (serviceName: string, actionName: string, payload: unknown, nileContext: NileContext<unknown>, authContext?: AuthContext) => Promise<Result<unknown, string>>;
 }
 
 /**
@@ -422,6 +483,95 @@ declare function getContext<TDB = unknown>(): NileContext<TDB>;
  */
 declare function createNileServer(config: ServerConfig): NileServer;
 
+/** Structured payload separating string fields from File objects */
+interface StructuredPayload {
+    fields: Record<string, string | string[]>;
+    files: Record<string, File | File[]>;
+}
+/**
+ * Internal validation result for the upload validation chain.
+ * Carries structured error data for rich client-facing error responses,
+ * unlike slang-ts Result which only carries a string error.
+ */
+interface UploadValidationResult {
+    status: boolean;
+    message?: string;
+    data?: Record<string, unknown>;
+    /** HTTP status code override (e.g., 415 for content-type mismatch) */
+    statusCode?: number;
+}
+/**
+ * Result from form-data parsing functions.
+ * On success: carries a StructuredPayload with separated fields/files.
+ * On failure: carries error metadata in errorData (not data) to avoid type conflicts.
+ */
+interface FormDataResult {
+    status: boolean;
+    message?: string;
+    /** Parsed structured payload — only present on success */
+    data?: StructuredPayload;
+    /** Error details — only present on failure */
+    errorData?: Record<string, unknown>;
+    /** HTTP status code override */
+    statusCode?: number;
+}
+/** Upload limits configuration — mirrors RestConfig.uploads.limits */
+interface UploadLimits {
+    maxFiles?: number;
+    maxFileSize?: number;
+    minFileSize?: number;
+    maxTotalSize?: number;
+    maxFilenameLength?: number;
+}
+/** Allowlist for MIME types and file extensions */
+interface UploadAllowlist {
+    mimeTypes?: string[];
+    extensions?: string[];
+}
+/** Full upload configuration — mirrors RestConfig.uploads */
+interface UploadsConfig {
+    enforceContentType?: boolean;
+    limits?: UploadLimits;
+    allow?: UploadAllowlist;
+    diagnostics?: boolean;
+}
+
+/**
+ * Multipart form-data parsing and content-type enforcement.
+ * Two parsing modes:
+ * - "flat" (default): conflict detection — rejects same key used for both files and fields
+ * - "structured": simple separation of fields and files with array aggregation
+ *
+ * Uses Hono's parseBody({ all: true }) for robust multipart parsing across HTTP clients.
+ */
+
+/**
+ * High-level upload handler: parses multipart form data, validates files,
+ * and returns the structured payload ready for the action handler.
+ *
+ * This is the single entry point called from the REST layer for form-data requests.
+ */
+declare function handleFormDataRequest(c: {
+    req: {
+        parseBody: (opts: {
+            all: true;
+        }) => Promise<Record<string, unknown>>;
+    };
+}, config: UploadsConfig, _uploadMode?: "flat" | "structured"): Promise<FormDataResult>;
+
+/**
+ * File validation chain for multipart uploads.
+ * 7-step sequential validation: filename length -> zero-byte -> min size ->
+ * file count -> max file size -> total size -> MIME + extension allowlist.
+ * Fails fast on first validation error.
+ */
+
+/**
+ * Run the full 7-step validation chain on an array of files.
+ * Fails fast on the first validation error. Returns { status: true } if all pass.
+ */
+declare function validateFiles(files: File[], config: UploadsConfig): UploadValidationResult;
+
 /**
  * Database instance or transaction pointer type.
  * Accepts a root DB instance (with .transaction method) or a transaction pointer.
@@ -643,4 +793,4 @@ interface HandleErrorParams {
  */
 declare function handleError(params: HandleErrorParams): ErrType<string> & ResultMethods<never>;
 
-export { type Action, type ActionHandler, type ActionResultConfig, type ActionSummary, type Actions, type AfterActionHandler, type BaseContext, type BeforeActionHandler, type CorsConfig, type CorsOptions, type CorsResolver, type CorsRouteRule, type CursorPage, type CursorPaginationOptions, type DBParams, type DBX, type Engine, type EngineOptions, type ExternalRequest, type ExternalResponse, type HookContext, type HookDefinition, type HookLogEntry, type Log, type LogFilter, type LoggerConfig, type ModelOperations, type ModelOptions, type NileContext, type NileLogger, type NileServer, type OffsetPage, type OffsetPaginationOptions, type RPCContext, type RateLimitConfig, type Resources, type RestConfig, type ServerConfig, type ServerRuntime, type Service, type ServiceSummary, type Services, type Sessions, type WebSocketContext, createAction, createActions, createLog, createLogger, createModel, createNileServer, createService, createServices, createTransactionVariant, getContext, getLogs, getZodSchema, handleError };
+export { type Action, type ActionHandler, type ActionResultConfig, type ActionSummary, type Actions, type AfterActionHandler, type AuthConfig, type AuthContext, type AuthHandler, type AuthResult, type BaseContext, type BeforeActionHandler, type CorsConfig, type CorsOptions, type CorsResolver, type CorsRouteRule, type CursorPage, type CursorPaginationOptions, type DBParams, type DBX, type Engine, type EngineOptions, type ExternalRequest, type ExternalResponse, type FormDataResult, type HookContext, type HookDefinition, type HookLogEntry, type Log, type LogFilter, type LoggerConfig, type ModelOperations, type ModelOptions, type NileContext, type NileLogger, type NileServer, type OffsetPage, type OffsetPaginationOptions, type RPCContext, type RateLimitConfig, type Resources, type RestConfig, type ServerConfig, type ServerRuntime, type Service, type ServiceSummary, type Services, type Sessions, type StructuredPayload, type TokenSource, type UploadAllowlist, type UploadLimits, type UploadValidationResult, type UploadsConfig, type WebSocketContext, createAction, createActions, createLog, createLogger, createModel, createNileServer, createService, createServices, createTransactionVariant, getContext, getLogs, getZodSchema, handleError, handleFormDataRequest, validateFiles, verifyJWT };

package/dist/index.d.ts

@@ -1,8 +1,55 @@
-import { Context, Hono } from 'hono';
 import { Result, ErrType, ResultMethods } from 'slang-ts';
+import { Context, Hono } from 'hono';
 import { Store } from 'hono-rate-limiter';
 import z, { ZodTypeAny } from 'zod';
 
+/** Where to extract the JWT token from incoming requests */
+type TokenSource = "header" | "cookie";
+/**
+ * Server-level auth configuration.
+ * Kept intentionally lean — only JWT verification via hono/jwt.
+ * For custom auth logic (RBAC, API keys, sessions), use onBeforeActionHandler.
+ */
+interface AuthConfig {
+    /** JWT secret used for token verification */
+    secret: string;
+    /** Where to look for the token (default: "header") */
+    method?: TokenSource;
+    /** Cookie name when method is "cookie" (default: "auth_token") */
+    cookieName?: string;
+    /** Header name when method is "header" (default: "authorization") */
+    headerName?: string;
+}
+/** Successful auth result populated on NileContext after verification */
+interface AuthResult {
+    userId: string;
+    organizationId: string;
+    /** Raw decoded JWT claims for custom logic in hooks */
+    claims: Record<string, unknown>;
+}
+/**
+ * Auth context passed to the JWT handler — carries the raw
+ * request data needed for token extraction.
+ */
+interface AuthContext {
+    headers?: Headers;
+    cookies?: Record<string, string>;
+}
+/**
+ * Auth handler function signature.
+ * Returns Ok(AuthResult) on success, Err(message) on failure.
+ */
+type AuthHandler = (context: AuthContext, config: AuthConfig) => Promise<Result<AuthResult, string>>;
+
+/**
+ * Lean JWT authentication handler.
+ * Extracts token from header or cookie, verifies via hono/jwt,
+ * and returns AuthResult with userId, organizationId, and raw claims.
+ *
+ * For anything beyond JWT (RBAC, API keys, sessions), use onBeforeActionHandler.
+ */
+declare function verifyJWT(context: AuthContext, config: AuthConfig): Promise<Result<AuthResult, string>>;
+
 /**
  * CORS options compatible with Hono's cors middleware
  */
@@ -173,6 +220,16 @@ interface NileContext<TDB = unknown> {
     getSession: (name: keyof Sessions) => Record<string, unknown> | undefined;
     /** Store session data for a specific interface */
     setSession: (name: keyof Sessions, data: Record<string, unknown>) => void;
+    /** Auth result populated after successful JWT verification */
+    authResult?: AuthResult;
+    /** Get the raw auth result after JWT verification */
+    getAuth: () => AuthResult | undefined;
+    /** Get authenticated user identity (userId + organizationId) */
+    getUser: () => {
+        userId: string;
+        organizationId: string;
+        [key: string]: unknown;
+    } | undefined;
     hookContext: HookContext;
     updateHookState: (key: string, value: unknown) => void;
     addHookLog: (phase: "before" | "after", logEntry: {
@@ -205,6 +262,8 @@ interface ServerConfig {
     /** Print registered services table to console on boot (default: true) */
     logServices?: boolean;
     resources?: Resources<unknown>;
+    /** JWT auth configuration — enables built-in token verification for protected actions */
+    auth?: AuthConfig;
     rest?: RestConfig;
     websocket?: Record<string, unknown>;
     rpc?: Record<string, unknown>;
@@ -312,6 +371,8 @@ interface EngineOptions {
         info: (msg: string, data?: unknown) => void;
     } | NileLogger;
     services: Services;
+    /** JWT auth configuration — when provided, protected actions require valid tokens */
+    auth?: AuthConfig;
     onBeforeActionHandler?: BeforeActionHandler<unknown, unknown>;
     onAfterActionHandler?: AfterActionHandler<unknown, unknown>;
 }
@@ -320,7 +381,7 @@ interface Engine {
     getServices: () => Result<ServiceSummary[], string>;
     getServiceActions: (serviceName: string) => Result<ActionSummary[], string>;
     getAction: (serviceName: string, actionName: string) => Result<Action, string>;
-    executeAction: (serviceName: string, actionName: string, payload: unknown, nileContext: NileContext<unknown>) => Promise<Result<unknown, string>>;
+    executeAction: (serviceName: string, actionName: string, payload: unknown, nileContext: NileContext<unknown>, authContext?: AuthContext) => Promise<Result<unknown, string>>;
 }
 
 /**
@@ -422,6 +483,95 @@ declare function getContext<TDB = unknown>(): NileContext<TDB>;
  */
 declare function createNileServer(config: ServerConfig): NileServer;
 
+/** Structured payload separating string fields from File objects */
+interface StructuredPayload {
+    fields: Record<string, string | string[]>;
+    files: Record<string, File | File[]>;
+}
+/**
+ * Internal validation result for the upload validation chain.
+ * Carries structured error data for rich client-facing error responses,
+ * unlike slang-ts Result which only carries a string error.
+ */
+interface UploadValidationResult {
+    status: boolean;
+    message?: string;
+    data?: Record<string, unknown>;
+    /** HTTP status code override (e.g., 415 for content-type mismatch) */
+    statusCode?: number;
+}
+/**
+ * Result from form-data parsing functions.
+ * On success: carries a StructuredPayload with separated fields/files.
+ * On failure: carries error metadata in errorData (not data) to avoid type conflicts.
+ */
+interface FormDataResult {
+    status: boolean;
+    message?: string;
+    /** Parsed structured payload — only present on success */
+    data?: StructuredPayload;
+    /** Error details — only present on failure */
+    errorData?: Record<string, unknown>;
+    /** HTTP status code override */
+    statusCode?: number;
+}
+/** Upload limits configuration — mirrors RestConfig.uploads.limits */
+interface UploadLimits {
+    maxFiles?: number;
+    maxFileSize?: number;
+    minFileSize?: number;
+    maxTotalSize?: number;
+    maxFilenameLength?: number;
+}
+/** Allowlist for MIME types and file extensions */
+interface UploadAllowlist {
+    mimeTypes?: string[];
+    extensions?: string[];
+}
+/** Full upload configuration — mirrors RestConfig.uploads */
+interface UploadsConfig {
+    enforceContentType?: boolean;
+    limits?: UploadLimits;
+    allow?: UploadAllowlist;
+    diagnostics?: boolean;
+}
+
+/**
+ * Multipart form-data parsing and content-type enforcement.
+ * Two parsing modes:
+ * - "flat" (default): conflict detection — rejects same key used for both files and fields
+ * - "structured": simple separation of fields and files with array aggregation
+ *
+ * Uses Hono's parseBody({ all: true }) for robust multipart parsing across HTTP clients.
+ */
+
+/**
+ * High-level upload handler: parses multipart form data, validates files,
+ * and returns the structured payload ready for the action handler.
+ *
+ * This is the single entry point called from the REST layer for form-data requests.
+ */
+declare function handleFormDataRequest(c: {
+    req: {
+        parseBody: (opts: {
+            all: true;
+        }) => Promise<Record<string, unknown>>;
+    };
+}, config: UploadsConfig, _uploadMode?: "flat" | "structured"): Promise<FormDataResult>;
+
+/**
+ * File validation chain for multipart uploads.
+ * 7-step sequential validation: filename length -> zero-byte -> min size ->
+ * file count -> max file size -> total size -> MIME + extension allowlist.
+ * Fails fast on first validation error.
+ */
+
+/**
+ * Run the full 7-step validation chain on an array of files.
+ * Fails fast on the first validation error. Returns { status: true } if all pass.
+ */
+declare function validateFiles(files: File[], config: UploadsConfig): UploadValidationResult;
+
 /**
  * Database instance or transaction pointer type.
  * Accepts a root DB instance (with .transaction method) or a transaction pointer.
@@ -643,4 +793,4 @@ interface HandleErrorParams {
  */
 declare function handleError(params: HandleErrorParams): ErrType<string> & ResultMethods<never>;
 
-export { type Action, type ActionHandler, type ActionResultConfig, type ActionSummary, type Actions, type AfterActionHandler, type BaseContext, type BeforeActionHandler, type CorsConfig, type CorsOptions, type CorsResolver, type CorsRouteRule, type CursorPage, type CursorPaginationOptions, type DBParams, type DBX, type Engine, type EngineOptions, type ExternalRequest, type ExternalResponse, type HookContext, type HookDefinition, type HookLogEntry, type Log, type LogFilter, type LoggerConfig, type ModelOperations, type ModelOptions, type NileContext, type NileLogger, type NileServer, type OffsetPage, type OffsetPaginationOptions, type RPCContext, type RateLimitConfig, type Resources, type RestConfig, type ServerConfig, type ServerRuntime, type Service, type ServiceSummary, type Services, type Sessions, type WebSocketContext, createAction, createActions, createLog, createLogger, createModel, createNileServer, createService, createServices, createTransactionVariant, getContext, getLogs, getZodSchema, handleError };
+export { type Action, type ActionHandler, type ActionResultConfig, type ActionSummary, type Actions, type AfterActionHandler, type AuthConfig, type AuthContext, type AuthHandler, type AuthResult, type BaseContext, type BeforeActionHandler, type CorsConfig, type CorsOptions, type CorsResolver, type CorsRouteRule, type CursorPage, type CursorPaginationOptions, type DBParams, type DBX, type Engine, type EngineOptions, type ExternalRequest, type ExternalResponse, type FormDataResult, type HookContext, type HookDefinition, type HookLogEntry, type Log, type LogFilter, type LoggerConfig, type ModelOperations, type ModelOptions, type NileContext, type NileLogger, type NileServer, type OffsetPage, type OffsetPaginationOptions, type RPCContext, type RateLimitConfig, type Resources, type RestConfig, type ServerConfig, type ServerRuntime, type Service, type ServiceSummary, type Services, type Sessions, type StructuredPayload, type TokenSource, type UploadAllowlist, type UploadLimits, type UploadValidationResult, type UploadsConfig, type WebSocketContext, createAction, createActions, createLog, createLogger, createModel, createNileServer, createService, createServices, createTransactionVariant, getContext, getLogs, getZodSchema, handleError, handleFormDataRequest, validateFiles, verifyJWT };