memory-journal-mcp 8.0.1 → 9.1.0

package/dist/audit/audit-logger.d.ts

@@ -0,0 +1,89 @@
+/**
+ * memory-journal-mcp — Operational Telemetry Logger
+ *
+ * Async-buffered JSONL writer for operational telemetry. Appends one
+ * JSON object per line to a configurable file path, or writes to
+ * stderr for containerised deployments (`--audit-log stderr`).
+ *
+ * Architecture aligned with postgres-mcp's production-proven logger:
+ *   - JSONL format: one JSON object per line
+ *   - Async buffered: 50-entry high-water mark + 100ms auto-flush
+ *   - Rotation: configurable max size, keep 5 historical archives (.1–.5)
+ *   - Graceful close: flushes remaining entries and stops the timer
+ *   - Streaming tail-read: recent() reads only last 64KB for O(1) memory
+ *   - stderr mode: `--audit-log stderr` routes to process.stderr
+ *
+ * Non-throwing by design: telemetry failures log to stderr but never
+ * propagate to tool callers.
+ */
+import type { AuditConfig, AuditEntry, AuditSearchFilters } from './types.js';
+export declare class AuditLogger {
+    readonly config: AuditConfig;
+    private buffer;
+    private flushTimer;
+    private flushQueue;
+    private closed;
+    private dirEnsured;
+    private readonly stderrMode;
+    private _droppedCount;
+    constructor(config: AuditConfig);
+    /**
+     * Total number of events dropped due to memory limits or persistent I/O failure.
+     */
+    get droppedCount(): number;
+    /**
+     * Append an audit entry to the buffer.
+     * Non-blocking — the entry is serialised and queued; the
+     * actual file write happens on the next flush cycle.
+     *
+     * NOTE: This is a lossy operational telemetry mechanism, not a guaranteed immutable ledger.
+     * Under extreme backpressure or persistent I/O failure, oldest entries will be dropped
+     * to preserve memory and system stability.
+     */
+    log(entry: AuditEntry): void;
+    /**
+     * Log a denied access attempt.
+     */
+    logDenial(toolName: string, reason: string, context?: {
+        user?: string | null;
+        scopes?: string[];
+        category?: AuditEntry['category'];
+        scope?: string;
+        requestId?: string;
+        sessionId?: string;
+    }): void;
+    /**
+     * Flush the buffer to disk.
+     * Safe to call concurrently — serialises via `this.flushQueue` Promise chain.
+     */
+    flush(): Promise<void>;
+    /**
+     * Gracefully close the logger — flush remaining entries and stop the timer.
+     */
+    close(): Promise<void>;
+    /**
+     * Read the most recent audit entries from the log file.
+     * Uses a streaming tail-read: only the last TAIL_READ_BYTES (64 KB) are
+     * read from disk, preventing O(n) memory spikes for large audit logs.
+     * Used by the `memory://audit` resource.
+     *
+     * @param count Maximum number of entries to return (default 50)
+     */
+    recent(count?: number): Promise<AuditEntry[]>;
+    /**
+     * Search across the active log and all rotated archives.
+     * Reads files backward from newest to oldest up to the configured limit.
+     */
+    search(filters: AuditSearchFilters): Promise<AuditEntry[]>;
+    /**
+     * Ensure the parent directory of the log file exists.
+     */
+    private ensureDirectory;
+    /**
+     * Rotate the log file if it exceeds the configured size limit.
+     * Keeps up to 5 rotated files (`.1` through `.5`); older data is discarded.
+     * Rotation failure is non-fatal — audit must not block tool execution.
+     */
+    private rotateIfNeeded;
+}
+//# sourceMappingURL=audit-logger.d.ts.map

package/dist/audit/audit-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-logger.d.ts","sourceRoot":"","sources":["../../src/audit/audit-logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAA;AAiC7E,qBAAa,WAAW;IACpB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;IAE5B,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,UAAU,CAA8C;IAChE,OAAO,CAAC,UAAU,CAAmC;IACrD,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,UAAU,CAAQ;IAC1B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC,OAAO,CAAC,aAAa,CAAI;gBAEb,MAAM,EAAE,WAAW;IAa/B;;OAEG;IACH,IAAI,YAAY,IAAI,MAAM,CAEzB;IAED;;;;;;;;OAQG;IACH,GAAG,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAuB5B;;OAEG;IACH,SAAS,CACL,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE;QACN,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;QACpB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;QACjB,QAAQ,CAAC,EAAE,UAAU,CAAC,UAAU,CAAC,CAAA;QACjC,KAAK,CAAC,EAAE,MAAM,CAAA;QACd,SAAS,CAAC,EAAE,MAAM,CAAA;QAClB,SAAS,CAAC,EAAE,MAAM,CAAA;KACrB,GACF,IAAI;IAgBP;;;OAGG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAgD5B;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAW5B;;;;;;;OAOG;IACG,MAAM,CAAC,KAAK,GAAE,MAA6B,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAyDzE;;;OAGG;IACG,MAAM,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IAyDhE;;OAEG;YACW,eAAe;IAW7B;;;;OAIG;YACW,cAAc;CAsB/B"}

package/dist/audit/audit-resource.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Audit Resource Handler
+ *
+ * Serves the memory://audit resource — the last 50 telemetry entries
+ * as a structured, YAML-style text payload with a session summary
+ * including token totals and error counts.
+ *
+ * Per mcp-builder §2.3: annotated as ASSISTANT_FOCUSED (agent-only).
+ *
+ * When telemetry logging is not configured, returns a brief informational
+ * message with a setup hint.
+ *
+ * Uses the AuditLogger.recent() streaming tail-read (64KB window)
+ * instead of loading the entire file — O(1) memory regardless of
+ * telemetry log size.
+ */
+import type { InternalResourceDef } from '../handlers/resources/shared.js';
+import type { AuditLogger } from './audit-logger.js';
+/**
+ * Returns the InternalResourceDef for memory://audit.
+ * The AuditLogger instance is bound at creation time.
+ *
+ * @param getLogger - A function that returns the current AuditLogger instance (or null).
+ *                    Using a getter function avoids capturing a null reference at registration
+ *                    time — the logger may not exist yet when resources are registered.
+ */
+export declare function getAuditResourceDef(getLogger: () => AuditLogger | null): InternalResourceDef;
+//# sourceMappingURL=audit-resource.d.ts.map

package/dist/audit/audit-resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-resource.d.ts","sourceRoot":"","sources":["../../src/audit/audit-resource.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EACR,mBAAmB,EAGtB,MAAM,iCAAiC,CAAA;AAExC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAMpD;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,WAAW,GAAG,IAAI,GAAG,mBAAmB,CA6F5F"}

package/dist/audit/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Audit Module Barrel
+ *
+ * Re-exports the audit logger, interceptor, resource handler, and types.
+ */
+export { AuditLogger } from './audit-logger.js';
+export { createAuditInterceptor } from './interceptor.js';
+export type { AuditInterceptor, AuditToolHandlerFn } from './interceptor.js';
+export type { AuditEntry, AuditConfig, AuditCategory } from './types.js';
+export { DEFAULT_AUDIT_LOG_MAX_SIZE_BYTES } from './types.js';
+export { getAuditResourceDef } from './audit-resource.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/audit/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/audit/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAE/C,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAA;AACzD,YAAY,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAE5E,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAExE,OAAO,EAAE,gCAAgC,EAAE,MAAM,YAAY,CAAA;AAE7D,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA"}

package/dist/audit/interceptor.d.ts

@@ -0,0 +1,44 @@
+/**
+ * memory-journal-mcp — Audit Interceptor
+ *
+ * Wraps tool execution to produce audit entries for all tool
+ * invocations. Write/admin tools are always logged; read-scoped
+ * tools are logged only when `--audit-reads` is enabled.
+ *
+ * Each entry includes a `tokenEstimate` (~4 bytes per token)
+ * computed from the serialized result size.
+ *
+ * The interceptor is injected into the tool handler cache
+ * (ensureToolCache in handlers/tools/index.ts) so that all
+ * tool handlers are audited without per-handler changes.
+ */
+import type { AuditLogger } from './audit-logger.js';
+/** Tool handler function signature that the interceptor wraps */
+export type AuditToolHandlerFn = (args: Record<string, unknown>) => Promise<unknown>;
+/**
+ * Audit interceptor interface — provides an `around` method
+ * to wrap tool execution with audit logging.
+ */
+export interface AuditInterceptor {
+    /**
+     * Wrap a tool invocation with audit logging.
+     * Returns the tool result unchanged; re-throws any errors.
+     *
+     * @param toolName  MCP tool name
+     * @param args      Tool input arguments
+     * @param fn        The actual tool handler to execute
+     */
+    around<T>(toolName: string, args: unknown, fn: () => Promise<T>): Promise<T>;
+}
+/**
+ * Create an audit interceptor bound to the given logger.
+ *
+ * @param auditLogger  The JSONL audit logger
+ */
+export declare function createAuditInterceptor(auditLogger: AuditLogger): AuditInterceptor;
+/**
+ * Execute an operation with audit logging.
+ * Intended for resources and prompts which operate outside the standard tool interceptor.
+ */
+export declare function auditOperation<T>(auditLogger: AuditLogger | null, operationType: 'resource' | 'prompt', name: string, fn: () => Promise<T> | T): Promise<T>;
+//# sourceMappingURL=interceptor.d.ts.map

package/dist/audit/interceptor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interceptor.d.ts","sourceRoot":"","sources":["../../src/audit/interceptor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAYpD,iEAAiE;AACjE,MAAM,MAAM,kBAAkB,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAA;AAEpF;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC7B;;;;;;;OAOG;IACH,MAAM,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;CAC/E;AAyCD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,WAAW,GAAG,gBAAgB,CAiGjF;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAAC,CAAC,EAClC,WAAW,EAAE,WAAW,GAAG,IAAI,EAC/B,aAAa,EAAE,UAAU,GAAG,QAAQ,EACpC,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GACzB,OAAO,CAAC,CAAC,CAAC,CAmDZ"}

package/dist/audit/types.d.ts

@@ -0,0 +1,68 @@
+/**
+ * memory-journal-mcp — Audit Log Types
+ *
+ * Types and configuration for the JSONL audit trail.
+ * Records write/admin tool invocations with optional OAuth identity,
+ * timing, and outcome for forensic-grade visibility.
+ */
+/** Category of the audited operation */
+export type AuditCategory = 'read' | 'write' | 'admin' | 'team' | 'audit';
+/**
+ * Single audit log entry — serialised as one line of JSONL.
+ */
+export interface AuditEntry {
+    /** ISO 8601 timestamp */
+    timestamp: string;
+    /** Correlates with RequestContext.requestId (or generated UUID) */
+    requestId: string;
+    /** The transport session ID */
+    sessionId?: string | undefined;
+    /** MCP tool name (e.g. "create_entry") */
+    tool: string;
+    /** Operation category */
+    category: AuditCategory;
+    /** OAuth scope required for this tool */
+    scope: string;
+    /** OAuth subject claim — null when OAuth is not configured */
+    user: string | null;
+    /** All scopes present on the calling token */
+    scopes: string[];
+    /** Execution duration in milliseconds */
+    durationMs: number;
+    /** Whether the tool executed successfully */
+    success: boolean;
+    /** Error message when success is false */
+    error?: string | undefined;
+    /** Tool input arguments (omitted in redact mode) */
+    args?: Record<string, unknown> | undefined;
+    /** Estimated token count of the tool response (~4 bytes per token) */
+    tokenEstimate?: number | undefined;
+}
+/** Filters for searching the audit log */
+export interface AuditSearchFilters {
+    tool_name?: string;
+    user?: string;
+    date_range?: {
+        start?: string;
+        end?: string;
+    };
+    status?: boolean;
+    category?: AuditCategory;
+    limit?: number;
+}
+/** Audit log configuration */
+export interface AuditConfig {
+    /** Master switch — false means no interceptor is created */
+    enabled: boolean;
+    /** Absolute path to the JSONL output file, or "stderr" for container mode */
+    logPath: string;
+    /** When true, tool arguments are omitted from entries */
+    redact: boolean;
+    /** When true, read-scoped tools are also logged (default: false) */
+    auditReads: boolean;
+    /** Maximum log file size in bytes before rotation (default: 10MB). 0 = no rotation. */
+    maxSizeBytes: number;
+}
+/** Default maximum JSONL audit log size before rotation (10 MB). */
+export declare const DEFAULT_AUDIT_LOG_MAX_SIZE_BYTES: number;
+//# sourceMappingURL=types.d.ts.map

package/dist/audit/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/audit/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,wCAAwC;AACxC,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,CAAA;AAEzE;;GAEG;AACH,MAAM,WAAW,UAAU;IACvB,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAA;IAEjB,mEAAmE;IACnE,SAAS,EAAE,MAAM,CAAA;IAEjB,+BAA+B;IAC/B,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAE9B,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAA;IAEZ,yBAAyB;IACzB,QAAQ,EAAE,aAAa,CAAA;IAEvB,yCAAyC;IACzC,KAAK,EAAE,MAAM,CAAA;IAEb,8DAA8D;IAC9D,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IAEnB,8CAA8C;IAC9C,MAAM,EAAE,MAAM,EAAE,CAAA;IAEhB,yCAAyC;IACzC,UAAU,EAAE,MAAM,CAAA;IAElB,6CAA6C;IAC7C,OAAO,EAAE,OAAO,CAAA;IAEhB,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAE1B,oDAAoD;IACpD,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;IAE1C,sEAAsE;IACtE,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACrC;AAED,0CAA0C;AAC1C,MAAM,WAAW,kBAAkB;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,UAAU,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IAC7C,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,QAAQ,CAAC,EAAE,aAAa,CAAA;IACxB,KAAK,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,8BAA8B;AAC9B,MAAM,WAAW,WAAW;IACxB,4DAA4D;IAC5D,OAAO,EAAE,OAAO,CAAA;IAEhB,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAA;IAEf,yDAAyD;IACzD,MAAM,EAAE,OAAO,CAAA;IAEf,oEAAoE;IACpE,UAAU,EAAE,OAAO,CAAA;IAEnB,uFAAuF;IACvF,YAAY,EAAE,MAAM,CAAA;CACvB;AAMD,oEAAoE;AACpE,eAAO,MAAM,gCAAgC,QAAmB,CAAA"}

package/dist/auth/auth-context.d.ts

@@ -0,0 +1,42 @@
+/**
+ * memory-journal-mcp — Auth Context (AsyncLocalStorage)
+ *
+ * Provides per-request authentication context threading using Node.js
+ * AsyncLocalStorage. Allows the HTTP transport to store the validated
+ * auth context so that tool handlers can enforce per-tool scopes
+ * without direct parameter coupling through the MCP SDK layer.
+ */
+import type { AuthenticatedContext } from './middleware.js';
+/**
+ * Run a function within an authenticated context.
+ * Called by the HTTP transport after token validation.
+ *
+ * @param context - The validated auth context from middleware
+ * @param fn - The async function to run (MCP SDK request handling)
+ * @returns The result of the wrapped function
+ */
+export declare function runWithAuthContext<T>(context: AuthenticatedContext, fn: () => T): T;
+/**
+ * Get the current request's auth context.
+ * Returns undefined when:
+ * - OAuth is not configured (stdio transport, no auth)
+ * - Called outside of an HTTP request context
+ *
+ * Tool handlers use this to enforce per-tool scope checks.
+ */
+export declare function getAuthContext(): AuthenticatedContext | undefined;
+/**
+ * Run a callback within a specific auth context.
+ * Alias for runWithAuthContext with synchronous return type.
+ */
+export declare function withAuthContext<T>(context: AuthenticatedContext, fn: () => T): T;
+/**
+ * Check if the current request has an authenticated context.
+ */
+export declare function isAuthenticated(): boolean;
+/**
+ * Get the scopes from the current authenticated context.
+ * Returns empty array if not authenticated.
+ */
+export declare function getAuthenticatedScopes(): string[];
+//# sourceMappingURL=auth-context.d.ts.map

package/dist/auth/auth-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-context.d.ts","sourceRoot":"","sources":["../../src/auth/auth-context.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AAQ3D;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,OAAO,EAAE,oBAAoB,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAEnF;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,IAAI,oBAAoB,GAAG,SAAS,CAEjE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,OAAO,EAAE,oBAAoB,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC,CAEhF;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,OAAO,CAGzC;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,EAAE,CAMjD"}

package/dist/auth/authorization-server-discovery.d.ts

@@ -0,0 +1,90 @@
+/**
+ * memory-journal-mcp — Authorization Server Discovery (RFC 8414)
+ *
+ * Discovers and caches OAuth 2.0 Authorization Server Metadata
+ * as specified in RFC 8414.
+ *
+ * @see https://datatracker.ietf.org/doc/html/rfc8414
+ */
+import type { AuthorizationServerMetadata, AuthServerDiscoveryConfig } from './types.js';
+/**
+ * Authorization Server Metadata Discovery
+ *
+ * Fetches and caches OAuth 2.0 authorization server metadata
+ * from the /.well-known/oauth-authorization-server endpoint.
+ */
+export declare class AuthorizationServerDiscovery {
+    private readonly authServerUrl;
+    private readonly cacheTtl;
+    private readonly timeout;
+    private cachedMetadata;
+    private cacheExpiry;
+    constructor(config: AuthServerDiscoveryConfig);
+    /**
+     * Discover authorization server metadata
+     *
+     * Fetches from /.well-known/oauth-authorization-server
+     * Results are cached for cacheTtl seconds.
+     *
+     * @returns Authorization server metadata
+     * @throws AuthServerDiscoveryError if discovery fails
+     */
+    discover(): Promise<AuthorizationServerMetadata>;
+    /**
+     * Validate required metadata fields per RFC 8414
+     */
+    private validateMetadata;
+    /**
+     * Get cached metadata (throws if not discovered)
+     */
+    getMetadata(): AuthorizationServerMetadata;
+    /**
+     * Get JWKS URI from metadata
+     *
+     * @throws Error if metadata not discovered or jwks_uri not present
+     */
+    getJwksUri(): string;
+    /**
+     * Get token endpoint from metadata
+     */
+    getTokenEndpoint(): string;
+    /**
+     * Get issuer from metadata
+     */
+    getIssuer(): string;
+    /**
+     * Get registration endpoint from metadata (RFC 7591)
+     *
+     * @returns Registration endpoint or null if not supported
+     */
+    getRegistrationEndpoint(): string | null;
+    /**
+     * Check if dynamic client registration is supported
+     */
+    supportsClientRegistration(): boolean;
+    /**
+     * Get supported scopes from metadata
+     */
+    getSupportedScopes(): string[];
+    /**
+     * Check if a specific scope is supported
+     */
+    isScopeSupported(scope: string): boolean;
+    /**
+     * Clear cached metadata
+     */
+    clearCache(): void;
+    /**
+     * Check if cache is valid
+     */
+    isCacheValid(): boolean;
+    /**
+     * Get the authorization server URL
+     */
+    getAuthServerUrl(): string;
+}
+/**
+ * Create an Authorization Server Discovery instance
+ */
+export declare function createAuthServerDiscovery(authServerUrl: string, options?: Partial<Omit<AuthServerDiscoveryConfig, 'authServerUrl'>>): AuthorizationServerDiscovery;
+//# sourceMappingURL=authorization-server-discovery.d.ts.map

package/dist/auth/authorization-server-discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authorization-server-discovery.d.ts","sourceRoot":"","sources":["../../src/auth/authorization-server-discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,2BAA2B,EAAE,yBAAyB,EAAE,MAAM,YAAY,CAAA;AAUxF;;;;;GAKG;AACH,qBAAa,4BAA4B;IACrC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAQ;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAQ;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAQ;IAEhC,OAAO,CAAC,cAAc,CAA2C;IACjE,OAAO,CAAC,WAAW,CAAI;gBAEX,MAAM,EAAE,yBAAyB;IAY7C;;;;;;;;OAQG;IACG,QAAQ,IAAI,OAAO,CAAC,2BAA2B,CAAC;IAkKtD;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAqBxB;;OAEG;IACH,WAAW,IAAI,2BAA2B;IAS1C;;;;OAIG;IACH,UAAU,IAAI,MAAM;IAUpB;;OAEG;IACH,gBAAgB,IAAI,MAAM;IAI1B;;OAEG;IACH,SAAS,IAAI,MAAM;IAInB;;;;OAIG;IACH,uBAAuB,IAAI,MAAM,GAAG,IAAI;IAIxC;;OAEG;IACH,0BAA0B,IAAI,OAAO;IAIrC;;OAEG;IACH,kBAAkB,IAAI,MAAM,EAAE;IAI9B;;OAEG;IACH,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO;IAMxC;;OAEG;IACH,UAAU,IAAI,IAAI;IASlB;;OAEG;IACH,YAAY,IAAI,OAAO;IAIvB;;OAEG;IACH,gBAAgB,IAAI,MAAM;CAG7B;AAMD;;GAEG;AACH,wBAAgB,yBAAyB,CACrC,aAAa,EAAE,MAAM,EACrB,OAAO,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,yBAAyB,EAAE,eAAe,CAAC,CAAC,GACpE,4BAA4B,CAM9B"}

package/dist/auth/errors.d.ts

@@ -0,0 +1,90 @@
+/**
+ * memory-journal-mcp — OAuth Error Classes
+ *
+ * Module-prefixed error classes for OAuth 2.0 authentication
+ * and authorization failures. Extends MemoryJournalMcpError
+ * for harmonized error handling across the MCP ecosystem.
+ */
+import { MemoryJournalMcpError } from '../types/errors.js';
+/**
+ * OAuth error code constants
+ */
+export declare const AUTH_ERROR_CODES: {
+    readonly TOKEN_MISSING: "AUTH_TOKEN_MISSING";
+    readonly TOKEN_INVALID: "AUTH_TOKEN_INVALID";
+    readonly TOKEN_EXPIRED: "AUTH_TOKEN_EXPIRED";
+    readonly SIGNATURE_INVALID: "AUTH_SIGNATURE_INVALID";
+    readonly SCOPE_DENIED: "AUTH_SCOPE_DENIED";
+    readonly DISCOVERY_FAILED: "AUTH_DISCOVERY_FAILED";
+    readonly JWKS_FETCH_FAILED: "AUTH_JWKS_FETCH_FAILED";
+    readonly REGISTRATION_FAILED: "AUTH_REGISTRATION_FAILED";
+};
+/**
+ * Base class for OAuth-related errors.
+ * Extends MemoryJournalMcpError with OAuth-specific properties.
+ */
+export declare class OAuthError extends MemoryJournalMcpError {
+    /** HTTP status code for this error */
+    readonly httpStatus: number;
+    /** WWW-Authenticate header value */
+    readonly wwwAuthenticate?: string | undefined;
+    constructor(message: string, code: string, httpStatus: number, details?: Record<string, unknown>, wwwAuthenticate?: string);
+}
+/**
+ * Token is missing from the request
+ */
+export declare class TokenMissingError extends OAuthError {
+    constructor(realm?: string);
+}
+/**
+ * Token is invalid (malformed, wrong format, etc.)
+ */
+export declare class InvalidTokenError extends OAuthError {
+    constructor(message?: string, details?: Record<string, unknown>);
+}
+/**
+ * Token has expired
+ */
+export declare class TokenExpiredError extends OAuthError {
+    constructor(expiredAt?: Date);
+}
+/**
+ * Token signature is invalid
+ */
+export declare class InvalidSignatureError extends OAuthError {
+    constructor(message?: string);
+}
+/**
+ * Token does not have required scope
+ */
+export declare class InsufficientScopeError extends OAuthError {
+    constructor(requiredScope: string | string[], providedScopes?: string[]);
+}
+/**
+ * Failed to discover authorization server metadata
+ */
+export declare class AuthServerDiscoveryError extends OAuthError {
+    constructor(serverUrl: string, cause?: Error);
+}
+/**
+ * Failed to fetch JWKS
+ */
+export declare class JwksFetchError extends OAuthError {
+    constructor(jwksUri: string, cause?: Error);
+}
+/**
+ * Failed to register client
+ */
+export declare class ClientRegistrationError extends OAuthError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+/**
+ * Check if an error is an OAuth error
+ */
+export declare function isOAuthError(error: unknown): error is OAuthError;
+/**
+ * Get WWW-Authenticate header for an OAuth error.
+ * @deprecated Use error.wwwAuthenticate property directly instead
+ */
+export declare function getWWWAuthenticateHeader(error: OAuthError, realm?: string): string;
+//# sourceMappingURL=errors.d.ts.map

package/dist/auth/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/auth/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAA;AAM1D;;GAEG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;CASnB,CAAA;AAMV;;;GAGG;AACH,qBAAa,UAAW,SAAQ,qBAAqB;IACjD,sCAAsC;IACtC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAE3B,oCAAoC;IACpC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;gBAGzC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,MAAM,EAClB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjC,eAAe,CAAC,EAAE,MAAM;CAgB/B;AAMD;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,UAAU;gBACjC,KAAK,SAAuB;CAU3C;AAED;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,UAAU;gBACjC,OAAO,SAAyB,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAIlF;AAED;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,UAAU;gBACjC,SAAS,CAAC,EAAE,IAAI;CAU/B;AAED;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,UAAU;gBACrC,OAAO,SAAwC;CAU9D;AAMD;;GAEG;AACH,qBAAa,sBAAuB,SAAQ,UAAU;gBACtC,aAAa,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,cAAc,CAAC,EAAE,MAAM,EAAE;CAa1E;AAMD;;GAEG;AACH,qBAAa,wBAAyB,SAAQ,UAAU;gBACxC,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK;CAY/C;AAED;;GAEG;AACH,qBAAa,cAAe,SAAQ,UAAU;gBAC9B,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK;CAO7C;AAED;;GAEG;AACH,qBAAa,uBAAwB,SAAQ,UAAU;gBACvC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAIjE;AAMD;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,UAAU,CAEhE;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,SAAuB,GAAG,MAAM,CAEhG"}

package/dist/auth/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * memory-journal-mcp — Auth Module Public Exports
+ *
+ * OAuth 2.0 authentication and authorization components.
+ */
+export type * from './types.js';
+export { AUTH_ERROR_CODES, OAuthError, TokenMissingError, InvalidTokenError, TokenExpiredError, InvalidSignatureError, InsufficientScopeError, AuthServerDiscoveryError, JwksFetchError, ClientRegistrationError, isOAuthError, } from './errors.js';
+export * from './scopes.js';
+export { getRequiredScope, getToolScopeMap } from './scope-map.js';
+export { runWithAuthContext, getAuthContext } from './auth-context.js';
+export { OAuthResourceServer, createOAuthResourceServer } from './oauth-resource-server.js';
+export { AuthorizationServerDiscovery, createAuthServerDiscovery, } from './authorization-server-discovery.js';
+export { TokenValidator, createTokenValidator } from './token-validator.js';
+export { createAuthMiddleware, extractBearerToken, requireScope, requireAnyScope, requireToolScope, oauthErrorHandler, type AuthMiddlewareConfig, } from './middleware.js';
+export { createAuthenticatedContext, validateAuth, formatOAuthError, type AuthenticatedContext, } from './middleware.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/auth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/auth/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,mBAAmB,YAAY,CAAA;AAE/B,OAAO,EACH,gBAAgB,EAChB,UAAU,EACV,iBAAiB,EACjB,iBAAiB,EACjB,iBAAiB,EACjB,qBAAqB,EACrB,sBAAsB,EACtB,wBAAwB,EACxB,cAAc,EACd,uBAAuB,EACvB,YAAY,GACf,MAAM,aAAa,CAAA;AAGpB,cAAc,aAAa,CAAA;AAG3B,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AAGlE,OAAO,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAA;AAGtE,OAAO,EAAE,mBAAmB,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAA;AAC3F,OAAO,EACH,4BAA4B,EAC5B,yBAAyB,GAC5B,MAAM,qCAAqC,CAAA;AAC5C,OAAO,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAA;AAG3E,OAAO,EACH,oBAAoB,EACpB,kBAAkB,EAClB,YAAY,EACZ,eAAe,EACf,gBAAgB,EAChB,iBAAiB,EACjB,KAAK,oBAAoB,GAC5B,MAAM,iBAAiB,CAAA;AAGxB,OAAO,EACH,0BAA0B,EAC1B,YAAY,EACZ,gBAAgB,EAChB,KAAK,oBAAoB,GAC5B,MAAM,iBAAiB,CAAA"}

package/dist/auth/middleware.d.ts

@@ -0,0 +1,77 @@
+/**
+ * memory-journal-mcp — OAuth Middleware
+ *
+ * Express middleware for OAuth 2.0 authentication and authorization.
+ * Extracts Bearer tokens, validates them, and enforces scope requirements.
+ */
+import type { Request, Response, NextFunction, RequestHandler } from 'express';
+import type { TokenClaims } from './types.js';
+import type { AuthInfo } from '@modelcontextprotocol/server';
+import type { TokenValidator } from './token-validator.js';
+import type { OAuthResourceServer } from './oauth-resource-server.js';
+import { extractBearerToken } from './transport-agnostic.js';
+export { extractBearerToken };
+/**
+ * Extended Express Request with auth context
+ */
+export interface AuthRequest extends Request {
+    /** MCP standard auth info */
+    auth?: AuthInfo;
+    /** Original Token claims */
+    tokenClaims?: TokenClaims;
+    /** Raw access token */
+    accessToken?: string;
+    /** Request ID for tracing */
+    requestId?: string;
+}
+/**
+ * Auth middleware configuration
+ */
+export interface AuthMiddlewareConfig {
+    /** Token validator instance */
+    tokenValidator: TokenValidator;
+    /** Resource server instance (for WWW-Authenticate header) */
+    resourceServer: OAuthResourceServer;
+    /** Paths that bypass authentication (e.g., '/.well-known/*', '/health') */
+    publicPaths?: string[];
+}
+/**
+ * Create the main authentication middleware
+ *
+ * This middleware:
+ * 1. Skips authentication for public paths (e.g., /.well-known/*)
+ * 2. Extracts Bearer token from Authorization header
+ * 3. Validates the token using the TokenValidator
+ * 4. Attaches validated claims to req.auth
+ * 5. Returns 401 with WWW-Authenticate header on failure
+ */
+export declare function createAuthMiddleware(config: AuthMiddlewareConfig): RequestHandler;
+/**
+ * Middleware factory that requires a specific scope
+ *
+ * @param scope - Required scope
+ * @returns Express middleware
+ */
+export declare function requireScope(scope: string): RequestHandler;
+/**
+ * Middleware factory that requires any of the specified scopes
+ *
+ * @param scopes - Array of acceptable scopes (user must have at least one)
+ * @returns Express middleware
+ */
+export declare function requireAnyScope(scopes: string[]): RequestHandler;
+/**
+ * Middleware factory that requires scope for a specific tool
+ *
+ * @param toolName - Name of the tool being accessed
+ * @returns Express middleware
+ */
+export declare function requireToolScope(toolName: string): RequestHandler;
+/**
+ * Error handler middleware for OAuth errors
+ *
+ * Should be added after all routes to catch OAuth-related errors
+ */
+export declare function oauthErrorHandler(error: Error, _req: Request, res: Response, next: NextFunction): void;
+export { createAuthenticatedContext, validateAuth, formatOAuthError, type AuthenticatedContext, } from './transport-agnostic.js';
+//# sourceMappingURL=middleware.d.ts.map

package/dist/auth/middleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.d.ts","sourceRoot":"","sources":["../../src/auth/middleware.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAC9E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAC7C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAA;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AAC1D,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA;AAKrE,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAE5D,OAAO,EAAE,kBAAkB,EAAE,CAAA;AAM7B;;GAEG;AACH,MAAM,WAAW,WAAY,SAAQ,OAAO;IACxC,6BAA6B;IAC7B,IAAI,CAAC,EAAE,QAAQ,CAAA;IACf,4BAA4B;IAC5B,WAAW,CAAC,EAAE,WAAW,CAAA;IACzB,uBAAuB;IACvB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,6BAA6B;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAA;CACrB;AAMD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACjC,+BAA+B;IAC/B,cAAc,EAAE,cAAc,CAAA;IAE9B,6DAA6D;IAC7D,cAAc,EAAE,mBAAmB,CAAA;IAEnC,2EAA2E;IAC3E,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;CACzB;AA0CD;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,oBAAoB,GAAG,cAAc,CAsFjF;AAMD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,cAAc,CAsC1D;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,cAAc,CAwChE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc,CAoCjE;AAMD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC7B,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,OAAO,EACb,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,YAAY,GACnB,IAAI,CAiBN;AAMD,OAAO,EACH,0BAA0B,EAC1B,YAAY,EACZ,gBAAgB,EAChB,KAAK,oBAAoB,GAC5B,MAAM,yBAAyB,CAAA"}