@twelvehart/supermemory-runtime 1.0.0-next.0

package/src/services/csrf.service.ts

@@ -0,0 +1,252 @@
+import * as crypto from 'node:crypto'
+import { getLogger } from '../utils/logger.js'
+
+const logger = getLogger('csrf-service')
+
+/**
+ * CSRF Token Service
+ *
+ * Provides cryptographically secure CSRF token generation, signing, and validation
+ * using HMAC-SHA256 for token integrity.
+ *
+ * Security features:
+ * - Crypto.randomBytes(32) for token generation
+ * - HMAC-SHA256 for token signing
+ * - Constant-time comparison to prevent timing attacks
+ * - Token rotation support
+ * - Session association
+ */
+
+export interface CsrfToken {
+  token: string
+  signature: string
+  expiresAt: number
+  sessionId?: string
+}
+
+export interface CsrfConfig {
+  secret: string
+  tokenLength: number
+  expirationMs: number
+}
+
+/** Maximum number of tokens to store before evicting oldest */
+const MAX_TOKENS = 10000
+
+export class CsrfService {
+  private readonly secret: Buffer
+  private readonly tokenLength: number
+  private readonly expirationMs: number
+  private readonly tokenStore: Map<string, CsrfToken>
+  private cleanupTimer: ReturnType<typeof setInterval> | null = null
+
+  constructor(config: CsrfConfig) {
+    // Ensure secret is at least 32 bytes for security
+    if (config.secret.length < 32) {
+      throw new Error('CSRF secret must be at least 32 characters')
+    }
+
+    this.secret = Buffer.from(config.secret, 'utf8')
+    this.tokenLength = config.tokenLength
+    this.expirationMs = config.expirationMs
+    this.tokenStore = new Map()
+
+    // Cleanup expired tokens periodically
+    this.cleanupTimer = setInterval(() => this.cleanupExpiredTokens(), 60000) // Every minute
+  }
+
+  /**
+   * Generate a cryptographically secure CSRF token.
+   *
+   * @param sessionId - Optional session identifier for token association
+   * @returns CSRF token with signature and expiration
+   */
+  generateToken(sessionId?: string): CsrfToken {
+    // Generate random token using crypto.randomBytes
+    const tokenBytes = crypto.randomBytes(this.tokenLength)
+    const token = tokenBytes.toString('base64url')
+
+    // Create expiration timestamp
+    const expiresAt = Date.now() + this.expirationMs
+
+    // Sign the token using HMAC-SHA256
+    const signature = this.signToken(token, expiresAt, sessionId)
+
+    const csrfToken: CsrfToken = {
+      token,
+      signature,
+      expiresAt,
+      sessionId,
+    }
+
+    // Enforce token store limit to prevent DoS
+    if (this.tokenStore.size >= MAX_TOKENS) {
+      // LRU eviction: remove oldest token (first entry in Map)
+      const firstKey = this.tokenStore.keys().next().value
+      if (firstKey) {
+        this.tokenStore.delete(firstKey)
+      }
+    }
+
+    // Store token for validation
+    this.tokenStore.set(token, csrfToken)
+
+    return csrfToken
+  }
+
+  /**
+   * Validate a CSRF token using constant-time comparison.
+   *
+   * @param token - Token to validate
+   * @param signature - Expected signature
+   * @param sessionId - Optional session identifier for validation
+   * @returns True if token is valid and not expired
+   */
+  validateToken(token: string, signature: string, sessionId?: string): boolean {
+    // Retrieve stored token
+    const storedToken = this.tokenStore.get(token)
+
+    if (!storedToken) {
+      return false
+    }
+
+    // Check expiration
+    if (Date.now() > storedToken.expiresAt) {
+      this.tokenStore.delete(token)
+      return false
+    }
+
+    // Verify session association if provided
+    if (sessionId && storedToken.sessionId !== sessionId) {
+      return false
+    }
+
+    // Verify signature using constant-time comparison
+    const expectedSignature = this.signToken(token, storedToken.expiresAt, storedToken.sessionId)
+
+    return this.constantTimeCompare(signature, expectedSignature)
+  }
+
+  /**
+   * Rotate a token (invalidate old, generate new).
+   *
+   * @param oldToken - Token to invalidate
+   * @param sessionId - Optional session identifier
+   * @returns New CSRF token
+   */
+  rotateToken(oldToken: string, sessionId?: string): CsrfToken {
+    // Invalidate old token
+    this.tokenStore.delete(oldToken)
+
+    // Generate new token
+    return this.generateToken(sessionId)
+  }
+
+  /**
+   * Sign a token using HMAC-SHA256.
+   *
+   * @param token - Token to sign
+   * @param expiresAt - Expiration timestamp
+   * @param sessionId - Optional session identifier
+   * @returns HMAC signature
+   */
+  private signToken(token: string, expiresAt: number, sessionId?: string): string {
+    const hmac = crypto.createHmac('sha256', this.secret)
+
+    // Include token, expiration, and optional session in signature
+    hmac.update(token)
+    hmac.update(String(expiresAt))
+
+    if (sessionId) {
+      hmac.update(sessionId)
+    }
+
+    return hmac.digest('base64url')
+  }
+
+  /**
+   * Constant-time string comparison to prevent timing attacks.
+   *
+   * @param a - First string
+   * @param b - Second string
+   * @returns True if strings are equal
+   */
+  private constantTimeCompare(a: string, b: string): boolean {
+    if (a.length !== b.length) return false
+
+    try {
+      return crypto.timingSafeEqual(Buffer.from(a, 'utf8'), Buffer.from(b, 'utf8'))
+    } catch {
+      return false
+    }
+  }
+
+  private cleanupExpiredTokens(): void {
+    const now = Date.now()
+    let cleanedCount = 0
+
+    for (const [token, csrfToken] of this.tokenStore) {
+      if (now > csrfToken.expiresAt) {
+        this.tokenStore.delete(token)
+        cleanedCount++
+      }
+    }
+
+    if (cleanedCount > 0) {
+      logger.debug('Cleaned up expired tokens', { cleanedCount })
+    }
+  }
+
+  /** Get token count (for monitoring) */
+  getTokenCount(): number {
+    return this.tokenStore.size
+  }
+
+  /** Clear all tokens (for testing) */
+  clearTokens(): void {
+    this.tokenStore.clear()
+  }
+
+  /** Release resources */
+  destroy(): void {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer)
+      this.cleanupTimer = null
+    }
+    this.tokenStore.clear()
+  }
+}
+
+/** Create a CSRF service instance with default or custom configuration */
+export function createCsrfService(config?: Partial<CsrfConfig>): CsrfService {
+  const secret = config?.secret || process.env.CSRF_SECRET || generateDefaultSecret()
+
+  const defaultConfig: CsrfConfig = {
+    secret,
+    tokenLength: 32, // 32 bytes = 256 bits
+    expirationMs: 60 * 60 * 1000, // 1 hour
+  }
+
+  return new CsrfService({ ...defaultConfig, ...config })
+}
+
+/** Generate a default secret for development. WARNING: Never use in production. */
+function generateDefaultSecret(): string {
+  const allowGeneratedLocalSecrets = process.env.SUPERMEMORY_ALLOW_GENERATED_LOCAL_SECRETS === 'true'
+
+  if (process.env.NODE_ENV === 'production' && !allowGeneratedLocalSecrets) {
+    throw new Error(
+      'CSRF_SECRET environment variable must be set in production. Generate a secure secret using: openssl rand -base64 48'
+    )
+  }
+
+  if (process.env.NODE_ENV === 'production') {
+    logger.warn(
+      'CSRF_SECRET not set; generating an ephemeral local secret because SUPERMEMORY_ALLOW_GENERATED_LOCAL_SECRETS=true'
+    )
+  } else {
+    logger.warn('Using generated CSRF secret for development - set CSRF_SECRET in production')
+  }
+
+  return crypto.randomBytes(48).toString('base64')
+}

package/src/services/documents.repository.ts

@@ -0,0 +1,219 @@
+/**
+ * Document Repository - Database operations for documents (PostgreSQL)
+ */
+
+import { desc, eq, inArray, or, sql } from 'drizzle-orm'
+import { getPostgresDatabase } from '../db/postgres.js'
+import { getDatabaseUrl, isPostgresUrl } from '../db/client.js'
+import { documents, type Document, type NewDocument } from '../db/schema/documents.schema.js'
+import { DatabaseError } from '../utils/errors.js'
+import { getLogger } from '../utils/logger.js'
+
+const logger = getLogger('DocumentRepository')
+
+let _db: ReturnType<typeof getPostgresDatabase> | null = null
+
+function getDb(): ReturnType<typeof getPostgresDatabase> {
+  if (_db) return _db
+  const databaseUrl = getDatabaseUrl()
+  if (!isPostgresUrl(databaseUrl)) {
+    throw new Error(
+      'DocumentRepository requires a PostgreSQL DATABASE_URL. SQLite is only supported in tests and is not compatible with document persistence.'
+    )
+  }
+  _db = getPostgresDatabase(databaseUrl)
+  return _db
+}
+
+const db = new Proxy({} as ReturnType<typeof getPostgresDatabase>, {
+  get(_target, prop) {
+    return getDb()[prop as keyof ReturnType<typeof getPostgresDatabase>]
+  },
+})
+
+export interface DocumentListOptions {
+  containerTag?: string
+  limit?: number
+  offset?: number
+}
+
+export class DocumentRepository {
+  private readonly database: typeof db
+
+  constructor(database: typeof db = db) {
+    this.database = database
+  }
+
+  async create(input: {
+    id?: string
+    content: string
+    containerTag: string
+    metadata?: Record<string, unknown> | null
+    customId?: string | null
+    contentType?: string | null
+    status?: string | null
+  }): Promise<Document> {
+    try {
+      const [record] = await this.database
+        .insert(documents)
+        .values({
+          id: input.id,
+          content: input.content,
+          containerTag: input.containerTag,
+          metadata: input.metadata ?? null,
+          customId: input.customId ?? null,
+          contentType: input.contentType ?? 'text/plain',
+          status: input.status ?? 'pending',
+        } as NewDocument)
+        .returning()
+
+      if (!record) {
+        throw new DatabaseError('Failed to create document', 'insert', {
+          containerTag: input.containerTag,
+        })
+      }
+
+      return record
+    } catch (error) {
+      logger.errorWithException('Failed to create document', error, {
+        containerTag: input.containerTag,
+      })
+      if (error instanceof DatabaseError) {
+        throw error
+      }
+      throw new DatabaseError('Failed to create document', 'insert', { originalError: error })
+    }
+  }
+
+  async findById(id: string): Promise<Document | null> {
+    const [record] = await this.database.select().from(documents).where(eq(documents.id, id)).limit(1)
+    return record ?? null
+  }
+
+  async findByCustomId(customId: string): Promise<Document | null> {
+    const [record] = await this.database.select().from(documents).where(eq(documents.customId, customId)).limit(1)
+    return record ?? null
+  }
+
+  async findByIdOrCustomId(idOrCustomId: string): Promise<Document | null> {
+    const byId = await this.findById(idOrCustomId)
+    if (byId) return byId
+    return this.findByCustomId(idOrCustomId)
+  }
+
+  async list(options: DocumentListOptions = {}): Promise<{ documents: Document[]; total: number }> {
+    const limit = options.limit ?? 20
+    const offset = options.offset ?? 0
+    const whereClause = options.containerTag ? eq(documents.containerTag, options.containerTag) : undefined
+
+    const countResult = await this.database
+      .select({ count: sql<number>`count(*)` })
+      .from(documents)
+      .where(whereClause)
+
+    const records = await this.database
+      .select()
+      .from(documents)
+      .where(whereClause)
+      .orderBy(desc(documents.createdAt))
+      .limit(limit)
+      .offset(offset)
+
+    return {
+      documents: records,
+      total: Number(countResult[0]?.count ?? 0),
+    }
+  }
+
+  async update(
+    id: string,
+    updates: {
+      content?: string
+      containerTag?: string
+      metadata?: Record<string, unknown> | null
+    }
+  ): Promise<Document | null> {
+    try {
+      const updatePayload: Partial<NewDocument> = {
+        updatedAt: new Date(),
+      }
+
+      if (updates.content !== undefined) {
+        updatePayload.content = updates.content
+      }
+
+      if (updates.containerTag !== undefined) {
+        updatePayload.containerTag = updates.containerTag
+      }
+
+      if (updates.metadata !== undefined) {
+        updatePayload.metadata = updates.metadata ?? null
+      }
+
+      const [record] = await this.database.update(documents).set(updatePayload).where(eq(documents.id, id)).returning()
+
+      return record ?? null
+    } catch (error) {
+      logger.errorWithException('Failed to update document', error, { id })
+      throw new DatabaseError('Failed to update document', 'update', { originalError: error, id })
+    }
+  }
+
+  async deleteById(id: string): Promise<boolean> {
+    const [deleted] = await this.database.delete(documents).where(eq(documents.id, id)).returning({ id: documents.id })
+    return Boolean(deleted)
+  }
+
+  async findByIdsOrCustomIds(ids: string[]): Promise<Document[]> {
+    if (ids.length === 0) return []
+    return this.database
+      .select()
+      .from(documents)
+      .where(or(inArray(documents.id, ids), inArray(documents.customId, ids)))
+  }
+
+  async deleteByIds(ids: string[]): Promise<string[]> {
+    if (ids.length === 0) return []
+    const deleted = await this.database
+      .delete(documents)
+      .where(inArray(documents.id, ids))
+      .returning({ id: documents.id })
+    return deleted.map((row) => row.id)
+  }
+
+  async deleteByContainerTags(containerTags: string[]): Promise<string[]> {
+    if (containerTags.length === 0) return []
+    const deleted = await this.database
+      .delete(documents)
+      .where(inArray(documents.containerTag, containerTags))
+      .returning({ id: documents.id })
+    return deleted.map((row) => row.id)
+  }
+}
+
+// ==========================================================================
+// Singleton Factory (lazy)
+// ==========================================================================
+
+let _repositoryInstance: DocumentRepository | null = null
+
+export function getDocumentRepository(): DocumentRepository {
+  if (!_repositoryInstance) {
+    _repositoryInstance = new DocumentRepository()
+  }
+  return _repositoryInstance
+}
+
+export function resetDocumentRepository(): void {
+  _repositoryInstance = null
+}
+
+export function createDocumentRepository(database?: typeof db): DocumentRepository {
+  return new DocumentRepository(database ?? db)
+}
+
+export const documentRepository = new Proxy({} as DocumentRepository, {
+  get(_, prop) {
+    return getDocumentRepository()[prop as keyof DocumentRepository]
+  },
+})

package/src/services/documents.service.ts

@@ -0,0 +1,191 @@
+/**
+ * Document Service - API-facing document operations
+ */
+
+import { ApiDocument } from '../types/api.types.js'
+import type { Document } from '../db/schema/documents.schema.js'
+import { DocumentRepository, getDocumentRepository, type DocumentListOptions } from './documents.repository.js'
+
+const DEFAULT_CONTAINER_TAG = 'default'
+
+export interface CreateDocumentInput {
+  id: string
+  content: string
+  containerTag?: string
+  metadata?: Record<string, unknown>
+  customId?: string
+  contentType?: string
+}
+
+export interface UpdateDocumentInput {
+  content?: string
+  containerTag?: string
+  metadata?: Record<string, unknown>
+}
+
+export class DocumentService {
+  private repository: DocumentRepository
+
+  constructor(repository?: DocumentRepository) {
+    this.repository = repository ?? getDocumentRepository()
+  }
+
+  async createDocument(input: CreateDocumentInput): Promise<ApiDocument> {
+    const record = await this.repository.create({
+      id: input.id,
+      content: input.content,
+      containerTag: this.normalizeContainerTag(input.containerTag),
+      metadata: input.metadata ?? null,
+      customId: input.customId ?? null,
+      contentType: input.contentType ?? 'text/plain',
+      status: 'pending',
+    })
+
+    return this.toApiDocument(record)
+  }
+
+  async getDocument(idOrCustomId: string): Promise<ApiDocument | null> {
+    const record = await this.repository.findByIdOrCustomId(idOrCustomId)
+    return record ? this.toApiDocument(record) : null
+  }
+
+  async getDocumentByCustomId(customId: string): Promise<ApiDocument | null> {
+    const record = await this.repository.findByCustomId(customId)
+    return record ? this.toApiDocument(record) : null
+  }
+
+  async updateDocument(idOrCustomId: string, updates: UpdateDocumentInput): Promise<ApiDocument | null> {
+    const existing = await this.repository.findByIdOrCustomId(idOrCustomId)
+    if (!existing) return null
+
+    const record = await this.repository.update(existing.id, {
+      content: updates.content,
+      containerTag: updates.containerTag,
+      metadata: updates.metadata,
+    })
+
+    return record ? this.toApiDocument(record) : null
+  }
+
+  async deleteDocument(idOrCustomId: string): Promise<string | null> {
+    const existing = await this.repository.findByIdOrCustomId(idOrCustomId)
+    if (!existing) return null
+
+    const deleted = await this.repository.deleteById(existing.id)
+    return deleted ? existing.id : null
+  }
+
+  async listDocuments(options: DocumentListOptions = {}): Promise<{
+    documents: ApiDocument[]
+    total: number
+    limit: number
+    offset: number
+  }> {
+    const limit = options.limit ?? 20
+    const offset = options.offset ?? 0
+
+    const { documents, total } = await this.repository.list({
+      containerTag: options.containerTag,
+      limit,
+      offset,
+    })
+
+    return {
+      documents: documents.map((doc) => this.toApiDocument(doc)),
+      total,
+      limit,
+      offset,
+    }
+  }
+
+  async bulkDelete(input: {
+    ids?: string[]
+    containerTags?: string[]
+  }): Promise<{ deletedIds: string[]; notFoundIds: string[] }> {
+    const deleted = new Set<string>()
+    const notFound = new Set<string>()
+
+    if (input.ids?.length) {
+      const matches = await this.repository.findByIdsOrCustomIds(input.ids)
+      const byId = new Map(matches.map((doc) => [doc.id, doc] as const))
+      const byCustomId = new Map(
+        matches.filter((doc) => doc.customId).map((doc) => [doc.customId as string, doc] as const)
+      )
+
+      const idsToDelete = new Set<string>()
+      for (const id of input.ids) {
+        const match = byId.get(id) ?? byCustomId.get(id)
+        if (match) {
+          idsToDelete.add(match.id)
+        } else {
+          notFound.add(id)
+        }
+      }
+
+      if (idsToDelete.size > 0) {
+        const deletedIds = await this.repository.deleteByIds([...idsToDelete])
+        for (const id of deletedIds) {
+          deleted.add(id)
+        }
+      }
+    }
+
+    if (input.containerTags?.length) {
+      const deletedIds = await this.repository.deleteByContainerTags(input.containerTags)
+      for (const id of deletedIds) {
+        deleted.add(id)
+      }
+    }
+
+    return {
+      deletedIds: [...deleted],
+      notFoundIds: [...notFound],
+    }
+  }
+
+  private normalizeContainerTag(containerTag?: string): string {
+    if (!containerTag || !containerTag.trim()) {
+      return DEFAULT_CONTAINER_TAG
+    }
+    return containerTag
+  }
+
+  private toApiDocument(document: Document): ApiDocument {
+    return {
+      id: document.id,
+      content: document.content,
+      containerTag: document.containerTag || undefined,
+      metadata: (document.metadata as Record<string, unknown> | null) ?? undefined,
+      customId: document.customId ?? undefined,
+      createdAt: document.createdAt.toISOString(),
+      updatedAt: document.updatedAt.toISOString(),
+    }
+  }
+}
+
+// ==========================================================================
+// Singleton Factory (lazy)
+// ==========================================================================
+
+let _serviceInstance: DocumentService | null = null
+
+export function getDocumentService(): DocumentService {
+  if (!_serviceInstance) {
+    _serviceInstance = new DocumentService()
+  }
+  return _serviceInstance
+}
+
+export function resetDocumentService(): void {
+  _serviceInstance = null
+}
+
+export function createDocumentService(repository?: DocumentRepository): DocumentService {
+  return new DocumentService(repository ?? getDocumentRepository())
+}
+
+export const documentService = new Proxy({} as DocumentService, {
+  get(_, prop) {
+    return getDocumentService()[prop as keyof DocumentService]
+  },
+})