vesper-memory 0.5.4 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (80) hide show
  1. package/CHANGELOG.md +22 -0
  2. package/README.md +6 -6
  3. package/config/sqlite-schema.sql +31 -0
  4. package/dist/cli.js +6 -49
  5. package/dist/cli.js.map +1 -1
  6. package/dist/consolidation/pipeline.d.ts +25 -6
  7. package/dist/consolidation/pipeline.d.ts.map +1 -1
  8. package/dist/consolidation/pipeline.js +310 -67
  9. package/dist/consolidation/pipeline.js.map +1 -1
  10. package/dist/memory-layers/semantic-memory.d.ts +8 -3
  11. package/dist/memory-layers/semantic-memory.d.ts.map +1 -1
  12. package/dist/memory-layers/semantic-memory.js +110 -50
  13. package/dist/memory-layers/semantic-memory.js.map +1 -1
  14. package/dist/memory-layers/skill-library.d.ts +9 -9
  15. package/dist/memory-layers/skill-library.d.ts.map +1 -1
  16. package/dist/memory-layers/skill-library.js +85 -56
  17. package/dist/memory-layers/skill-library.js.map +1 -1
  18. package/dist/memory-layers/working-memory.d.ts +2 -2
  19. package/dist/memory-layers/working-memory.d.ts.map +1 -1
  20. package/dist/memory-layers/working-memory.js +57 -47
  21. package/dist/memory-layers/working-memory.js.map +1 -1
  22. package/dist/retrieval/hybrid-search.d.ts.map +1 -1
  23. package/dist/retrieval/hybrid-search.js +10 -5
  24. package/dist/retrieval/hybrid-search.js.map +1 -1
  25. package/dist/retrieval/index-outbox.d.ts +50 -0
  26. package/dist/retrieval/index-outbox.d.ts.map +1 -0
  27. package/dist/retrieval/index-outbox.js +225 -0
  28. package/dist/retrieval/index-outbox.js.map +1 -0
  29. package/dist/retrieval/memory-retriever.d.ts +123 -0
  30. package/dist/retrieval/memory-retriever.d.ts.map +1 -0
  31. package/dist/retrieval/memory-retriever.js +723 -0
  32. package/dist/retrieval/memory-retriever.js.map +1 -0
  33. package/dist/router/smart-router.js +18 -18
  34. package/dist/server-wrapper.js +0 -0
  35. package/dist/server.d.ts +9 -1
  36. package/dist/server.d.ts.map +1 -1
  37. package/dist/server.js +859 -355
  38. package/dist/server.js.map +1 -1
  39. package/dist/utils/claude-mcp-config.d.ts +3 -0
  40. package/dist/utils/claude-mcp-config.d.ts.map +1 -0
  41. package/dist/utils/claude-mcp-config.js +42 -0
  42. package/dist/utils/claude-mcp-config.js.map +1 -0
  43. package/dist/utils/monitoring.d.ts +1 -0
  44. package/dist/utils/monitoring.d.ts.map +1 -1
  45. package/dist/utils/monitoring.js +1 -0
  46. package/dist/utils/monitoring.js.map +1 -1
  47. package/dist/utils/paths.d.ts +13 -1
  48. package/dist/utils/paths.d.ts.map +1 -1
  49. package/dist/utils/paths.js +24 -0
  50. package/dist/utils/paths.js.map +1 -1
  51. package/dist/utils/validation.d.ts +14 -2
  52. package/dist/utils/validation.d.ts.map +1 -1
  53. package/dist/utils/validation.js +64 -48
  54. package/dist/utils/validation.js.map +1 -1
  55. package/docker-compose.yml +3 -3
  56. package/package.json +7 -4
  57. package/scripts/README.md +1 -1
  58. package/scripts/health-check.sh +8 -4
  59. package/scripts/init-qdrant.ts +42 -60
  60. package/scripts/test-mcp-server.sh +2 -2
  61. package/dist/config/rate-limits.d.ts +0 -76
  62. package/dist/config/rate-limits.d.ts.map +0 -1
  63. package/dist/config/rate-limits.js +0 -161
  64. package/dist/config/rate-limits.js.map +0 -1
  65. package/dist/middleware/auth.d.ts +0 -287
  66. package/dist/middleware/auth.d.ts.map +0 -1
  67. package/dist/middleware/auth.js +0 -610
  68. package/dist/middleware/auth.js.map +0 -1
  69. package/dist/monitoring/health.d.ts +0 -241
  70. package/dist/monitoring/health.d.ts.map +0 -1
  71. package/dist/monitoring/health.js +0 -649
  72. package/dist/monitoring/health.js.map +0 -1
  73. package/dist/monitoring/metrics.d.ts +0 -153
  74. package/dist/monitoring/metrics.d.ts.map +0 -1
  75. package/dist/monitoring/metrics.js +0 -349
  76. package/dist/monitoring/metrics.js.map +0 -1
  77. package/dist/security/rate-limit-middleware.d.ts +0 -119
  78. package/dist/security/rate-limit-middleware.d.ts.map +0 -1
  79. package/dist/security/rate-limit-middleware.js +0 -193
  80. package/dist/security/rate-limit-middleware.js.map +0 -1
@@ -1,76 +0,0 @@
1
- /**
2
- * Rate Limiting Configuration
3
- *
4
- * Defines tier-based rate limits for MCP tools.
5
- * Configurable via environment variables.
6
- *
7
- * Security: Implements SEC-HIGH-001 from security audit
8
- */
9
- import { RateLimitConfig } from "../utils/rate-limiter.js";
10
- /**
11
- * Available rate limit tiers
12
- *
13
- * Note: "unlimited" is the highest tier (not "enterprise")
14
- * This matches the tier naming in auth.ts and postgres-auth-schema.sql
15
- */
16
- export type TierName = "standard" | "premium" | "unlimited";
17
- /**
18
- * Tier-based rate limits for all MCP operations
19
- *
20
- * Limits are per-minute unless otherwise specified.
21
- *
22
- * | Tier | store_memory | retrieve_memory | list_recent | get_stats |
23
- * |------|-------------|-----------------|-------------|-----------|
24
- * | standard | 100/min | 300/min | 60/min | 30/min |
25
- * | premium | 500/min | 1000/min | 200/min | 100/min |
26
- * | unlimited | no limit | no limit | no limit | no limit |
27
- */
28
- export declare const TIER_LIMITS: Record<TierName, Record<string, RateLimitConfig>>;
29
- /**
30
- * Legacy export for backwards compatibility
31
- */
32
- export declare const RATE_LIMIT_TIERS: Record<TierName, Record<string, RateLimitConfig>>;
33
- /**
34
- * Get rate limits for a specific tier
35
- *
36
- * @param tier - The tier name
37
- * @returns Rate limit configuration for all operations
38
- */
39
- export declare function getTierLimits(tier: TierName): Record<string, RateLimitConfig>;
40
- /**
41
- * Configuration from environment variables
42
- */
43
- export interface RateLimitEnvConfig {
44
- /** Default tier for users without explicit tier assignment */
45
- defaultTier: TierName;
46
- /** Whether to allow requests when Redis is unavailable (default: false - fail closed) */
47
- failOpen: boolean;
48
- /** Custom limits that override tier defaults */
49
- customLimits?: Record<string, number>;
50
- /** Emergency fallback limit when Redis is down (only used with failOpen: false) */
51
- emergencyLimit: number;
52
- }
53
- /**
54
- * Read rate limit configuration from environment variables
55
- *
56
- * Environment variables:
57
- * - RATE_LIMIT_DEFAULT_TIER: Default tier (standard|premium|unlimited)
58
- * - RATE_LIMIT_FAIL_OPEN: Whether to allow requests when Redis is down (true|false)
59
- * - RATE_LIMIT_STORE_MEMORY: Override store_memory limit
60
- * - RATE_LIMIT_RETRIEVE_MEMORY: Override retrieve_memory limit
61
- * - RATE_LIMIT_LIST_RECENT: Override list_recent limit
62
- * - RATE_LIMIT_GET_STATS: Override get_stats limit
63
- * - RATE_LIMIT_EMERGENCY: Emergency in-memory limit when Redis is down
64
- *
65
- * @returns Rate limit configuration
66
- */
67
- export declare function getRateLimitConfigFromEnv(): RateLimitEnvConfig;
68
- /**
69
- * Build rate limit configuration by merging tier defaults with custom limits
70
- *
71
- * @param tier - Base tier
72
- * @param customLimits - Custom limit overrides
73
- * @returns Merged rate limit configuration
74
- */
75
- export declare function buildRateLimitConfig(tier: TierName, customLimits?: Record<string, number>): Record<string, RateLimitConfig>;
76
- //# sourceMappingURL=rate-limits.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"rate-limits.d.ts","sourceRoot":"","sources":["../../src/config/rate-limits.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAE3D;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG,UAAU,GAAG,SAAS,GAAG,WAAW,CAAC;AAE5D;;;;;;;;;;GAUG;AACH,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAyDzE,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,gBAAgB,mDAAc,CAAC;AAE5C;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAE7E;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,8DAA8D;IAC9D,WAAW,EAAE,QAAQ,CAAC;IAEtB,yFAAyF;IACzF,QAAQ,EAAE,OAAO,CAAC;IAElB,gDAAgD;IAChD,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEtC,mFAAmF;IACnF,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,yBAAyB,IAAI,kBAAkB,CA0C9D;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,QAAQ,EACd,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACpC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAoBjC"}
@@ -1,161 +0,0 @@
1
- /**
2
- * Rate Limiting Configuration
3
- *
4
- * Defines tier-based rate limits for MCP tools.
5
- * Configurable via environment variables.
6
- *
7
- * Security: Implements SEC-HIGH-001 from security audit
8
- */
9
- /**
10
- * Tier-based rate limits for all MCP operations
11
- *
12
- * Limits are per-minute unless otherwise specified.
13
- *
14
- * | Tier | store_memory | retrieve_memory | list_recent | get_stats |
15
- * |------|-------------|-----------------|-------------|-----------|
16
- * | standard | 100/min | 300/min | 60/min | 30/min |
17
- * | premium | 500/min | 1000/min | 200/min | 100/min |
18
- * | unlimited | no limit | no limit | no limit | no limit |
19
- */
20
- export const TIER_LIMITS = {
21
- standard: {
22
- store_memory: {
23
- maxRequests: 100,
24
- windowSeconds: 60,
25
- },
26
- retrieve_memory: {
27
- maxRequests: 300,
28
- windowSeconds: 60,
29
- },
30
- list_recent: {
31
- maxRequests: 60,
32
- windowSeconds: 60,
33
- },
34
- get_stats: {
35
- maxRequests: 30,
36
- windowSeconds: 60,
37
- },
38
- },
39
- premium: {
40
- store_memory: {
41
- maxRequests: 500,
42
- windowSeconds: 60,
43
- },
44
- retrieve_memory: {
45
- maxRequests: 1000,
46
- windowSeconds: 60,
47
- },
48
- list_recent: {
49
- maxRequests: 200,
50
- windowSeconds: 60,
51
- },
52
- get_stats: {
53
- maxRequests: 100,
54
- windowSeconds: 60,
55
- },
56
- },
57
- unlimited: {
58
- // Use very high values (effectively no limit) for unlimited tier
59
- // We avoid actual infinity to prevent edge cases in Redis
60
- store_memory: {
61
- maxRequests: 1000000,
62
- windowSeconds: 60,
63
- },
64
- retrieve_memory: {
65
- maxRequests: 1000000,
66
- windowSeconds: 60,
67
- },
68
- list_recent: {
69
- maxRequests: 1000000,
70
- windowSeconds: 60,
71
- },
72
- get_stats: {
73
- maxRequests: 1000000,
74
- windowSeconds: 60,
75
- },
76
- },
77
- };
78
- /**
79
- * Legacy export for backwards compatibility
80
- */
81
- export const RATE_LIMIT_TIERS = TIER_LIMITS;
82
- /**
83
- * Get rate limits for a specific tier
84
- *
85
- * @param tier - The tier name
86
- * @returns Rate limit configuration for all operations
87
- */
88
- export function getTierLimits(tier) {
89
- return TIER_LIMITS[tier] || TIER_LIMITS.standard;
90
- }
91
- /**
92
- * Read rate limit configuration from environment variables
93
- *
94
- * Environment variables:
95
- * - RATE_LIMIT_DEFAULT_TIER: Default tier (standard|premium|unlimited)
96
- * - RATE_LIMIT_FAIL_OPEN: Whether to allow requests when Redis is down (true|false)
97
- * - RATE_LIMIT_STORE_MEMORY: Override store_memory limit
98
- * - RATE_LIMIT_RETRIEVE_MEMORY: Override retrieve_memory limit
99
- * - RATE_LIMIT_LIST_RECENT: Override list_recent limit
100
- * - RATE_LIMIT_GET_STATS: Override get_stats limit
101
- * - RATE_LIMIT_EMERGENCY: Emergency in-memory limit when Redis is down
102
- *
103
- * @returns Rate limit configuration
104
- */
105
- export function getRateLimitConfigFromEnv() {
106
- const defaultTier = (process.env.RATE_LIMIT_DEFAULT_TIER || "standard");
107
- // Security: Default to fail closed (deny requests when Redis is unavailable)
108
- const failOpenEnv = process.env.RATE_LIMIT_FAIL_OPEN;
109
- const failOpen = failOpenEnv === "true";
110
- // Parse custom limits from environment
111
- const customLimits = {};
112
- const storeMemoryLimit = process.env.RATE_LIMIT_STORE_MEMORY;
113
- if (storeMemoryLimit) {
114
- customLimits.store_memory = parseInt(storeMemoryLimit, 10);
115
- }
116
- const retrieveMemoryLimit = process.env.RATE_LIMIT_RETRIEVE_MEMORY;
117
- if (retrieveMemoryLimit) {
118
- customLimits.retrieve_memory = parseInt(retrieveMemoryLimit, 10);
119
- }
120
- const listRecentLimit = process.env.RATE_LIMIT_LIST_RECENT;
121
- if (listRecentLimit) {
122
- customLimits.list_recent = parseInt(listRecentLimit, 10);
123
- }
124
- const getStatsLimit = process.env.RATE_LIMIT_GET_STATS;
125
- if (getStatsLimit) {
126
- customLimits.get_stats = parseInt(getStatsLimit, 10);
127
- }
128
- // Emergency limit for in-memory fallback (very conservative)
129
- const emergencyLimit = parseInt(process.env.RATE_LIMIT_EMERGENCY || "10", 10);
130
- return {
131
- defaultTier,
132
- failOpen,
133
- customLimits: Object.keys(customLimits).length > 0 ? customLimits : undefined,
134
- emergencyLimit,
135
- };
136
- }
137
- /**
138
- * Build rate limit configuration by merging tier defaults with custom limits
139
- *
140
- * @param tier - Base tier
141
- * @param customLimits - Custom limit overrides
142
- * @returns Merged rate limit configuration
143
- */
144
- export function buildRateLimitConfig(tier, customLimits) {
145
- const tierLimits = getTierLimits(tier);
146
- if (!customLimits) {
147
- return tierLimits;
148
- }
149
- // Merge custom limits with tier defaults
150
- const merged = { ...tierLimits };
151
- for (const [operation, maxRequests] of Object.entries(customLimits)) {
152
- if (merged[operation]) {
153
- merged[operation] = {
154
- ...merged[operation],
155
- maxRequests,
156
- };
157
- }
158
- }
159
- return merged;
160
- }
161
- //# sourceMappingURL=rate-limits.js.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"rate-limits.js","sourceRoot":"","sources":["../../src/config/rate-limits.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAYH;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,WAAW,GAAsD;IAC5E,QAAQ,EAAE;QACR,YAAY,EAAE;YACZ,WAAW,EAAE,GAAG;YAChB,aAAa,EAAE,EAAE;SAClB;QACD,eAAe,EAAE;YACf,WAAW,EAAE,GAAG;YAChB,aAAa,EAAE,EAAE;SAClB;QACD,WAAW,EAAE;YACX,WAAW,EAAE,EAAE;YACf,aAAa,EAAE,EAAE;SAClB;QACD,SAAS,EAAE;YACT,WAAW,EAAE,EAAE;YACf,aAAa,EAAE,EAAE;SAClB;KACF;IACD,OAAO,EAAE;QACP,YAAY,EAAE;YACZ,WAAW,EAAE,GAAG;YAChB,aAAa,EAAE,EAAE;SAClB;QACD,eAAe,EAAE;YACf,WAAW,EAAE,IAAI;YACjB,aAAa,EAAE,EAAE;SAClB;QACD,WAAW,EAAE;YACX,WAAW,EAAE,GAAG;YAChB,aAAa,EAAE,EAAE;SAClB;QACD,SAAS,EAAE;YACT,WAAW,EAAE,GAAG;YAChB,aAAa,EAAE,EAAE;SAClB;KACF;IACD,SAAS,EAAE;QACT,iEAAiE;QACjE,0DAA0D;QAC1D,YAAY,EAAE;YACZ,WAAW,EAAE,OAAO;YACpB,aAAa,EAAE,EAAE;SAClB;QACD,eAAe,EAAE;YACf,WAAW,EAAE,OAAO;YACpB,aAAa,EAAE,EAAE;SAClB;QACD,WAAW,EAAE;YACX,WAAW,EAAE,OAAO;YACpB,aAAa,EAAE,EAAE;SAClB;QACD,SAAS,EAAE;YACT,WAAW,EAAE,OAAO;YACpB,aAAa,EAAE,EAAE;SAClB;KACF;CACF,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,WAAW,CAAC;AAE5C;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,IAAc;IAC1C,OAAO,WAAW,CAAC,IAAI,CAAC,IAAI,WAAW,CAAC,QAAQ,CAAC;AACnD,CAAC;AAmBD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,yBAAyB;IACvC,MAAM,WAAW,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,uBAAuB,IAAI,UAAU,CAAa,CAAC;IAEpF,6EAA6E;IAC7E,MAAM,WAAW,GAAG,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC;IACrD,MAAM,QAAQ,GAAG,WAAW,KAAK,MAAM,CAAC;IAExC,uCAAuC;IACvC,MAAM,YAAY,GAA2B,EAAE,CAAC;IAEhD,MAAM,gBAAgB,GAAG,OAAO,CAAC,GAAG,CAAC,uBAAuB,CAAC;IAC7D,IAAI,gBAAgB,EAAE,CAAC;QACrB,YAAY,CAAC,YAAY,GAAG,QAAQ,CAAC,gBAAgB,EAAE,EAAE,CAAC,CAAC;IAC7D,CAAC;IAED,MAAM,mBAAmB,GAAG,OAAO,CAAC,GAAG,CAAC,0BAA0B,CAAC;IACnE,IAAI,mBAAmB,EAAE,CAAC;QACxB,YAAY,CAAC,eAAe,GAAG,QAAQ,CAAC,mBAAmB,EAAE,EAAE,CAAC,CAAC;IACnE,CAAC;IAED,MAAM,eAAe,GAAG,OAAO,CAAC,GAAG,CAAC,sBAAsB,CAAC;IAC3D,IAAI,eAAe,EAAE,CAAC;QACpB,YAAY,CAAC,WAAW,GAAG,QAAQ,CAAC,eAAe,EAAE,EAAE,CAAC,CAAC;IAC3D,CAAC;IAED,MAAM,aAAa,GAAG,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC;IACvD,IAAI,aAAa,EAAE,CAAC;QAClB,YAAY,CAAC,SAAS,GAAG,QAAQ,CAAC,aAAa,EAAE,EAAE,CAAC,CAAC;IACvD,CAAC;IAED,6DAA6D;IAC7D,MAAM,cAAc,GAAG,QAAQ,CAC7B,OAAO,CAAC,GAAG,CAAC,oBAAoB,IAAI,IAAI,EACxC,EAAE,CACH,CAAC;IAEF,OAAO;QACL,WAAW;QACX,QAAQ;QACR,YAAY,EAAE,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,SAAS;QAC7E,cAAc;KACf,CAAC;AACJ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,oBAAoB,CAClC,IAAc,EACd,YAAqC;IAErC,MAAM,UAAU,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IAEvC,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,yCAAyC;IACzC,MAAM,MAAM,GAAoC,EAAE,GAAG,UAAU,EAAE,CAAC;IAElE,KAAK,MAAM,CAAC,SAAS,EAAE,WAAW,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC;QACpE,IAAI,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC;YACtB,MAAM,CAAC,SAAS,CAAC,GAAG;gBAClB,GAAG,MAAM,CAAC,SAAS,CAAC;gBACpB,WAAW;aACZ,CAAC;QACJ,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}
@@ -1,287 +0,0 @@
1
- /**
2
- * MCP Authentication Middleware
3
- *
4
- * Implements API key authentication for MCP tools with:
5
- * - Bearer token authentication
6
- * - bcrypt password hashing
7
- * - Key expiration
8
- * - IP allowlisting
9
- * - Scope-based authorization
10
- * - Audit logging
11
- *
12
- * Security Features:
13
- * - Constant-time comparison via bcrypt
14
- * - No plaintext key storage
15
- * - Gradual rollout support (AUTH_ENABLED env var)
16
- * - Rate limit tier enforcement
17
- */
18
- /** API key format prefix */
19
- export declare const API_KEY_PREFIX = "mem_v1_";
20
- /** Number of random bytes for key generation (30 bytes = 40 chars base64url) */
21
- export declare const API_KEY_BYTES = 30;
22
- /** bcrypt work factor (12 = ~250ms on modern hardware) */
23
- export declare const BCRYPT_ROUNDS = 12;
24
- /** Default key expiration in days */
25
- export declare const DEFAULT_KEY_EXPIRATION_DAYS = 90;
26
- /** Maximum allowed key expiration in days */
27
- export declare const MAX_KEY_EXPIRATION_DAYS = 365;
28
- /** Maximum grace period for key rotation in hours */
29
- export declare const MAX_GRACE_PERIOD_HOURS = 168;
30
- /** Valid scopes for API keys */
31
- export declare const VALID_SCOPES: readonly ["store_memory", "retrieve_memory", "list_recent", "get_stats", "*"];
32
- export type ValidScope = (typeof VALID_SCOPES)[number];
33
- /** Result of API key generation */
34
- export interface GeneratedApiKey {
35
- fullKey: string;
36
- keyPrefix: string;
37
- keyHash: string;
38
- }
39
- /** API key record from database */
40
- export interface ApiKeyRecord {
41
- id: string;
42
- userId: string;
43
- keyHash: string;
44
- scopes: string[];
45
- tier: string;
46
- expiresAt: Date | null;
47
- ipAllowlist: string[] | null;
48
- revokedAt: Date | null;
49
- lastUsedAt: Date | null;
50
- }
51
- /** Authentication result */
52
- export interface AuthResult {
53
- authenticated: boolean;
54
- userId: string;
55
- keyId: string;
56
- tier: string;
57
- scopes: string[];
58
- }
59
- /** Audit log actions */
60
- export declare enum AuditAction {
61
- AUTHENTICATE = "authenticate",
62
- RATE_LIMITED = "rate_limited",
63
- REVOKED = "revoked",
64
- ROTATED = "rotated",
65
- CREATED = "created",
66
- SCOPE_DENIED = "scope_denied",
67
- IP_DENIED = "ip_denied",
68
- EXPIRED = "expired"
69
- }
70
- /** Audit log entry */
71
- export interface AuditEntry {
72
- apiKeyId: string | null;
73
- action: AuditAction;
74
- success: boolean;
75
- ipAddress: string | null;
76
- userAgent?: string;
77
- requestPath?: string;
78
- failureReason?: string;
79
- metadata?: Record<string, unknown>;
80
- createdAt: Date;
81
- }
82
- /** Key rotation result */
83
- export interface RotationResult {
84
- newKey: GeneratedApiKey;
85
- gracePeriodHours: number;
86
- oldKeyValidUntil: Date;
87
- }
88
- /** Request context for authentication */
89
- export interface AuthRequest {
90
- apiKey: string | undefined;
91
- ip: string;
92
- toolName: string;
93
- userAgent?: string;
94
- }
95
- /** Database interface for auth operations */
96
- export interface AuthDatabase {
97
- getApiKey(prefix: string): Promise<ApiKeyRecord | null>;
98
- updateLastUsed(keyId: string): Promise<void>;
99
- createAuditEntry(entry: AuditEntry): Promise<void>;
100
- }
101
- /** Rate limits per tier */
102
- export interface TierRateLimits {
103
- store_memory: number;
104
- retrieve_memory: number;
105
- list_recent: number;
106
- get_stats: number;
107
- }
108
- /**
109
- * Generate a new API key with cryptographically secure random bytes
110
- *
111
- * @returns Generated key with full key, prefix, and hash
112
- */
113
- export declare function generateApiKey(): Promise<GeneratedApiKey>;
114
- /**
115
- * Verify an API key against its stored hash
116
- *
117
- * Uses bcrypt.compare for constant-time comparison
118
- *
119
- * @param providedKey - The API key provided by the client
120
- * @param storedHash - The bcrypt hash stored in the database
121
- * @returns true if key is valid
122
- */
123
- export declare function verifyApiKey(providedKey: string, storedHash: string): Promise<boolean>;
124
- /**
125
- * Validate API key format without database lookup
126
- *
127
- * @param key - API key to validate
128
- * @returns true if format is valid
129
- */
130
- export declare function validateApiKeyFormat(key: string): boolean;
131
- /**
132
- * Extract the prefix from an API key for database lookup
133
- *
134
- * @param key - Full API key
135
- * @returns 8-character prefix or null if invalid
136
- */
137
- export declare function extractKeyPrefix(key: string): string | null;
138
- /**
139
- * Check if an API key is expired
140
- *
141
- * @param expiresAt - Expiration date (null means never expires)
142
- * @returns true if key is expired
143
- */
144
- export declare function isKeyExpired(expiresAt: Date | null): boolean;
145
- /**
146
- * Calculate default expiration date (90 days from now)
147
- *
148
- * @returns Expiration date
149
- */
150
- export declare function calculateDefaultExpiration(): Date;
151
- /**
152
- * Calculate expiration date with custom days (capped at max)
153
- *
154
- * @param days - Number of days until expiration
155
- * @returns Expiration date
156
- */
157
- export declare function calculateExpiration(days: number): Date;
158
- /**
159
- * Get expiration days from environment or default
160
- *
161
- * @returns Number of days for key expiration
162
- */
163
- export declare function getExpirationDays(): number;
164
- /**
165
- * Check if an IP address is in the allowlist
166
- *
167
- * Supports both individual IPs and CIDR notation
168
- *
169
- * @param ip - Client IP address
170
- * @param allowlist - Array of allowed IPs/CIDRs (empty or null allows all)
171
- * @returns true if IP is allowed
172
- */
173
- export declare function isIpAllowed(ip: string, allowlist: string[] | null | undefined): boolean;
174
- /**
175
- * Check if user has required scope
176
- *
177
- * @param userScopes - Scopes granted to user
178
- * @param requiredScope - Scope required for operation
179
- * @returns true if user has scope
180
- */
181
- export declare function hasScope(userScopes: string[] | null | undefined, requiredScope: string): boolean;
182
- /**
183
- * Rotate an API key with optional grace period
184
- *
185
- * @param oldKeyHash - Hash of the old key (unused, for signature compatibility)
186
- * @param gracePeriodHours - Hours to allow old key (0 = immediate revocation)
187
- * @returns New key and grace period info
188
- */
189
- export declare function rotateApiKey(_oldKeyHash: string, gracePeriodHours: number): Promise<RotationResult>;
190
- /**
191
- * Create an audit log entry
192
- *
193
- * @param params - Audit entry parameters
194
- * @returns Audit entry object
195
- */
196
- export declare function createAuditEntry(params: {
197
- apiKeyId: string | null;
198
- action: AuditAction;
199
- success: boolean;
200
- ipAddress: string | null;
201
- userAgent?: string;
202
- requestPath?: string;
203
- failureReason?: string;
204
- metadata?: Record<string, unknown>;
205
- }): AuditEntry;
206
- /**
207
- * Hash an API key for audit logging (never log full key)
208
- *
209
- * @param key - Full API key
210
- * @returns Truncated SHA-256 hash for identification
211
- */
212
- export declare function hashForAudit(key: string): string;
213
- /**
214
- * Authenticate an MCP request
215
- *
216
- * @param request - Request context
217
- * @param db - Database interface
218
- * @returns Authentication result
219
- * @throws Error if authentication fails
220
- */
221
- export declare function authenticateRequest(request: AuthRequest, db: AuthDatabase): Promise<AuthResult>;
222
- /**
223
- * Check if authentication is enabled
224
- *
225
- * @returns true if AUTH_ENABLED=true
226
- */
227
- export declare function isAuthEnabled(): boolean;
228
- /**
229
- * Get rate limits for a tier
230
- *
231
- * @param tier - Rate limit tier
232
- * @returns Rate limits for the tier
233
- */
234
- export declare function getRateLimitsForTier(tier: string): TierRateLimits;
235
- /**
236
- * Create an in-memory cache for auth results
237
- *
238
- * @param options - Cache configuration
239
- * @returns Cache object with get/set methods
240
- */
241
- export declare function createAuthCache(options: {
242
- maxSize: number;
243
- ttlSeconds: number;
244
- }): {
245
- get(keyId: string): {
246
- userId: string;
247
- tier: string;
248
- } | null;
249
- set(keyId: string, value: {
250
- userId: string;
251
- tier: string;
252
- }): void;
253
- /**
254
- * Invalidate a specific key from the cache
255
- * HIGH-002: Used to immediately invalidate revoked/rotated keys
256
- *
257
- * @param keyId - The key ID (prefix) to invalidate
258
- * @returns true if key was in cache, false otherwise
259
- */
260
- invalidate(keyId: string): boolean;
261
- clear(): void;
262
- size(): number;
263
- };
264
- /**
265
- * Type for cache invalidation callback
266
- */
267
- export type AuthCache = ReturnType<typeof createAuthCache>;
268
- /**
269
- * Revoke an API key and invalidate it from cache
270
- * HIGH-002: Ensures revoked keys cannot be used even if cached
271
- *
272
- * @param keyPrefix - The key prefix to revoke
273
- * @param cache - The auth cache instance
274
- * @param reason - Reason for revocation (for audit logging)
275
- * @returns true if key was invalidated from cache
276
- */
277
- export declare function revokeApiKey(keyPrefix: string, cache: AuthCache, reason?: string): boolean;
278
- /**
279
- * Invalidate a rotated API key from cache
280
- * HIGH-002: Ensures old keys cannot be used during rotation
281
- *
282
- * @param oldKeyPrefix - The old key prefix being rotated
283
- * @param cache - The auth cache instance
284
- * @returns true if old key was invalidated from cache
285
- */
286
- export declare function invalidateRotatedKey(oldKeyPrefix: string, cache: AuthCache): boolean;
287
- //# sourceMappingURL=auth.d.ts.map
@@ -1 +0,0 @@
1
- {"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/middleware/auth.ts"],"names":[],"mappings":"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"}