@amtp/protocol 1.0.1

package/dist/server/amtp-server.d.ts

@@ -0,0 +1,183 @@
+/**
+ * AMTP Express Middleware & Server Core
+ * HTTP server integration for AMTP protocol
+ */
+import express, { Express, Request, Response, NextFunction } from "express";
+import { AMTPDocument, AMTPResponseHeaders, AMTPPageRequest, Session, MIMEType, AMTPQLQueryRequest, AMTPQLQueryResponse } from "../types/amtp.types";
+/**
+ * AMTP Server Configuration
+ */
+export interface AMTPServerConfig {
+    port: number;
+    host: string;
+    sessionTimeout: number;
+    enableCORS: boolean;
+    enableCompression: boolean;
+    enableSecurityHeaders?: boolean;
+    enableRateLimit?: boolean;
+    rateLimit?: {
+        windowMs: number;
+        maxRequests: number;
+    };
+    maxRequestBodySize?: number;
+    trustedOrigins?: string[];
+    csrfProtection?: boolean;
+    sessionAbsoluteMaxLifetime?: number;
+    cache?: {
+        enabled: boolean;
+        defaultTTL: number;
+    };
+}
+/**
+ * AMTP Request Parser
+ * Converts Express request to AMTP request
+ */
+export declare class AMTPRequestParser {
+    parse(req: express.Request): AMTPPageRequest;
+    private parseCapabilities;
+}
+/**
+ * AMTP Response Builder
+ * Constructs HTTP response from AMTP document
+ */
+export declare class AMTPResponseBuilder {
+    build(doc: AMTPDocument | string, options?: {
+        sessionId?: string;
+        cacheControl?: string;
+        etag?: string;
+    }): {
+        headers: AMTPResponseHeaders;
+        body: string;
+    };
+    private documentToMarkdown;
+    private nodeToMarkdown;
+}
+/**
+ * Session Manager
+ * Handles user sessions and state
+ */
+export declare class SessionManager {
+    private sessions;
+    private csrfTokens;
+    private _absoluteMaxLifetimeMs;
+    constructor(absoluteMaxLifetimeMs?: number);
+    createSession(userId: string, username: string, ttlMs?: number): Session;
+    getSession(sessionId: string): Session | null;
+    deleteSession(sessionId: string): void;
+    /**
+     * Generate and store a CSRF token for the given session.
+     */
+    generateCsrfToken(sessionId: string): string;
+    /**
+     * Validate a CSRF token against the stored token for a session.
+     */
+    validateCsrfToken(sessionId: string, token: string): boolean;
+    /**
+     * Scan for and evict expired sessions. Call periodically.
+     */
+    pruneExpired(): void;
+}
+/**
+ * Content Negotiation
+ * Determines response format based on Accept header with proper q-value parsing
+ */
+export declare class ContentNegotiator {
+    negotiate(acceptHeader: string, _userAgent?: string): MIMEType;
+}
+/**
+ * AMTP Middleware Factory
+ * Creates express middleware for AMTP protocol
+ */
+export declare class AMTPMiddlewareFactory {
+    private parser;
+    private builder;
+    private _sessions;
+    private negotiator;
+    /**
+     * Access the session manager for admin / pruning operations
+     */
+    get sessions(): SessionManager;
+    constructor();
+    /**
+     * Main AMTP middleware
+     */
+    middleware(): (req: Request, res: Response, next: NextFunction) => void;
+    /**
+     * Response sender middleware
+     */
+    responseSender(): (req: Request, res: Response, next: NextFunction) => void;
+    /**
+     * Error handler middleware
+     */
+    errorHandler(): (err: Error, req: Request, res: Response, _next: NextFunction) => express.Response<any, Record<string, any>> | undefined;
+    /**
+     * Security headers middleware — adds standard HTTP security headers to all responses
+     */
+    securityHeaders(): (_req: Request, res: Response, next: NextFunction) => void;
+    /**
+     * Rate limiting middleware — rejects requests that exceed the configured window/count
+     */
+    rateLimit(windowMs: number, maxRequests: number): (req: Request, res: Response, next: NextFunction) => express.Response<any, Record<string, any>> | undefined;
+    /**
+     * CSRF guard — rejects state-changing requests that do not carry a valid CSRF token
+     * bound to the active session.
+     */
+    csrfGuard(): (req: Request, res: Response, next: NextFunction) => void | express.Response<any, Record<string, any>>;
+    /**
+     * Content negotiation middleware — resolves the AMTP mime type the client prefers
+     */
+    contentNegotiation(): (req: Request, res: Response, next: NextFunction) => void;
+    /**
+     * CORS middleware for AMTP
+     * `trustedOrigins` is set on the AMTPServer instance and passed here.
+     */
+    cors(trustedOrigins?: string[]): (req: Request, res: Response, next: NextFunction) => express.Response<any, Record<string, any>> | undefined;
+}
+/**
+ * AMTP Server
+ * Main server class wrapping Express
+ */
+export declare class AMTPServer {
+    private app;
+    private config;
+    private middlewareFactory;
+    private router;
+    constructor(config?: Partial<AMTPServerConfig>);
+    private setupMiddleware;
+    /**
+     * Register a route handler
+     */
+    register(method: string, path: string, handler: (req: Request, res: Response) => void): void;
+    /**
+     * Handle an AMTP-QL query (v2.0).
+     * The caller provides a function that returns the AMTPDocument to query.
+     * Returns { data } or { errors } per AMTPQLQueryResponse.
+     */
+    handleAMTPQL(body: AMTPQLQueryRequest, getDocument: () => AMTPDocument | Promise<AMTPDocument>): Promise<AMTPQLQueryResponse>;
+    /**
+     * Return the fully configured Express app with routes and middleware mounted.
+     * Does NOT start the HTTP listener — useful for testing with supertest.
+     */
+    getConfiguredApp(): Express;
+    /**
+     * Start server
+     */
+    start(): Promise<void>;
+    /**
+     * Get Express app instance
+     */
+    getApp(): Express;
+    /**
+     * Get the internal session manager (useful for tests).
+     */
+    getSessionManager(): SessionManager;
+}
+declare const _default: {
+    AMTPServer: typeof AMTPServer;
+    AMTPMiddlewareFactory: typeof AMTPMiddlewareFactory;
+    SessionManager: typeof SessionManager;
+    ContentNegotiator: typeof ContentNegotiator;
+    AMTPRequestParser: typeof AMTPRequestParser;
+    AMTPResponseBuilder: typeof AMTPResponseBuilder;
+};
+export default _default;