Trilium/docs/Developer Guide/Developer Guide/Architecture/Security.md

Security

Trilium implements a defense-in-depth security model with multiple layers of protection for user data. The security architecture covers authentication, authorization, encryption, input sanitization, and secure communication.

Security Principles

1. Data Privacy: User data is protected at rest and in transit
2. Encryption: Per-note encryption for sensitive content
3. Authentication: Multiple authentication methods supported
4. Authorization: Single-user model with granular protected sessions
5. Input Validation: All user input sanitized
6. Secure Defaults: Security features enabled by default
7. Transparency: Open source allows security audits

Threat Model

Threats Considered

1. Unauthorized Access
   • Physical access to device
   • Network eavesdropping
   • Stolen credentials
   • Session hijacking
2. Data Exfiltration
   • Malicious scripts
   • XSS attacks
   • SQL injection
   • CSRF attacks
3. Data Corruption
   • Malicious modifications
   • Database tampering
   • Sync conflicts
4. Privacy Leaks
   • Unencrypted backups
   • Search indexing
   • Temporary files
   • Memory dumps

Out of Scope

• Nation-state attackers
• Zero-day vulnerabilities in dependencies
• Hardware vulnerabilities (Spectre, Meltdown)
• Physical access with unlimited time
• Quantum computing attacks

Authentication

Password Authentication

Implementation: apps/server/src/services/password.ts

TOTP (Two-Factor Authentication)

Implementation: apps/server/src/routes/api/login.ts

OpenID Connect

Implementation: apps/server/src/routes/api/login.ts

Supported Providers:

• Any OpenID Connect compatible provider
• Google, GitHub, Auth0, etc.

Flow:

// 1. Redirect to provider
GET /api/login/openid

// 2. Provider redirects back with code
GET /api/login/openid/callback?code=...

// 3. Exchange code for tokens
const tokens = await openidClient.callback(redirectUri, req.query)

// 4. Verify ID token
const claims = tokens.claims()

// 5. Create session
req.session.loggedIn = true

Session Management

Session Storage: SQLite database (sessions table)

Session Configuration:

app.use(session({
    secret: sessionSecret,
    resave: false,
    saveUninitialized: false,
    rolling: true,
    cookie: {
        maxAge: 7 * 24 * 60 * 60 * 1000,  // 7 days
        httpOnly: true,
        secure: isHttps,
        sameSite: 'lax'
    },
    store: new SqliteStore({
        db: db,
        table: 'sessions'
    })
}))

Session Invalidation:

• Automatic timeout after inactivity
• Manual logout clears session
• Server restart invalidates all sessions (optional)

Authorization

Single-User Model

Desktop:

• Single user (owner of device)
• No multi-user support
• Full access to all notes

Server:

• Single user per installation
• Authentication required for all operations
• No user roles or permissions

Protected Sessions

Purpose: Temporary access to encrypted (protected) notes

Implementation: apps/server/src/services/protected_session.ts

Workflow:

// 1. User enters password for protected notes
POST /api/protected-session/enter
Body: { password: "protected-password" }

// 2. Derive encryption key
const protectedDataKey = deriveKey(password)

// 3. Verify password (decrypt known encrypted value)
const decrypted = decrypt(testValue, protectedDataKey)
if (decrypted === expectedValue) {
    // 4. Store in memory (not in session)
    protectedSessionHolder.setProtectedDataKey(protectedDataKey)
    
    // 5. Set timeout
    setTimeout(() => {
        protectedSessionHolder.clearProtectedDataKey()
    }, timeout)
}

Protected Session Timeout:

• Default: 10 minutes (configurable)
• Extends on activity
• Cleared on browser close
• Separate from main session

API Authorization

Internal API:

• Requires authenticated session
• CSRF token validation
• Same-origin policy

ETAPI (External API):

• Token-based authentication
• No session required
• Rate limiting

Encryption

Note Encryption

Encryption Algorithm: AES-256-CBC

Key Hierarchy:

User Password
    ↓ (scrypt)
Data Key (for protected notes)
    ↓ (AES-128)
Protected Note Content

Protected Note Metadata:

• Content IS encrypted
• Type and MIME are NOT encrypted
• Attributes are NOT encrypted

Data Key Management

Key Rotation:

• Not currently supported
• Requires re-encrypting all protected notes

Transport Encryption

HTTPS:

• Recommended for server installations
• TLS 1.2+ only
• Strong cipher suites preferred
• Certificate validation enabled

Desktop:

• Local communication (no network)
• No HTTPS required

Backup Encryption

Database Backups:

• Protected notes remain encrypted in backup
• Backup file should be protected separately
• Consider encrypting backup storage location

Input Sanitization

XSS Prevention

• HTML Sanitization

• CKEditor Configuration:

  // apps/client/src/widgets/type_widgets/text_type_widget.ts
  ClassicEditor.create(element, {
      // Restrict allowed content
      htmlSupport: {
          allow: [
              { name: /./, attributes: true, classes: true, styles: true }
          ],
          disallow: [
              { name: 'script' },
              { name: 'iframe', attributes: /^(?!src$).*/ }
          ]
      }
  })
  

• Content Security Policy

SQL Injection Prevention

Parameterized Queries:

const notes = sql.getRows(
    'SELECT * FROM notes WHERE title = ?',
    [userInput]
)

ORM Usage:

// Entity-based access prevents SQL injection
const note = becca.getNote(noteId)
note.title = userInput  // Sanitized by entity
note.save()  // Parameterized query

CSRF Prevention

CSRF Token Validation:

Location: apps/server/src/routes/csrf_protection.ts

Stateless CSRF using Double Submit Cookie Pattern via csrf-csrf.

File Upload Validation

Validation:

// Validate file size
const maxSize = 100 * 1024 * 1024  // 100 MB
if (file.size > maxSize) {
    throw new Error('File too large')
}

Network Security

HTTPS Configuration

Certificate Validation:

• Require valid certificates in production
• Self-signed certificates allowed for development
• Certificate pinning not implemented

Rate Limiting

Login Rate Limiting:

const loginLimiter = rateLimit({
    windowMs: 15 * 60 * 1000,
    max: 10,  // 10 failed attempts
    skipSuccessfulRequests: true
})

app.post('/api/login/password', loginLimiter, loginHandler)

Data Security

Secure Data Deletion

Soft Delete:

// Mark as deleted (sync first)
note.isDeleted = 1
note.deleteId = generateUUID()
note.save()

// Entity change tracked for sync
addEntityChange('notes', noteId, note)

Hard Delete (Erase):

// After sync completed
sql.execute('DELETE FROM notes WHERE noteId = ?', [noteId])
sql.execute('DELETE FROM branches WHERE noteId = ?', [noteId])
sql.execute('DELETE FROM attributes WHERE noteId = ?', [noteId])

// Mark entity change as erased
sql.execute('UPDATE entity_changes SET isErased = 1 WHERE entityId = ?', [noteId])

Blob Cleanup:

// Find orphaned blobs (not referenced by any note/revision/attachment)
const orphanedBlobs = sql.getRows(`
    SELECT blobId FROM blobs
    WHERE blobId NOT IN (SELECT blobId FROM notes WHERE blobId IS NOT NULL)
      AND blobId NOT IN (SELECT blobId FROM revisions WHERE blobId IS NOT NULL)
      AND blobId NOT IN (SELECT blobId FROM attachments WHERE blobId IS NOT NULL)
`)

// Delete orphaned blobs
for (const blob of orphanedBlobs) {
    sql.execute('DELETE FROM blobs WHERE blobId = ?', [blob.blobId])
}

Memory Security

Protected Data in Memory:

• Protected data keys stored in memory only
• Cleared on timeout
• Not written to disk
• Not in session storage

Dependency Security

Vulnerability Scanning

Tools:

• Renovate bot - Automatic dependency updates
• pnpm audit - Check for known vulnerabilities
• GitHub Dependabot alerts

Process:

# Check for vulnerabilities
npm audit

# Fix automatically
npm audit fix

# Manual review for breaking changes
npm audit fix --force

Dependency Pinning

package.json:

{
  "dependencies": {
    "express": "4.18.2",  // Exact version
    "better-sqlite3": "^9.2.2"  // Compatible versions
  }
}

pnpm Overrides:

{
  "pnpm": {
    "overrides": {
      "lodash@<4.17.21": ">=4.17.21",  // Force minimum version
      "axios@<0.21.2": ">=0.21.2"
    }
  }
}

Patch Management

pnpm Patches:

# Create patch
pnpm patch @ckeditor/ckeditor5

# Edit files in temporary directory
# ...

# Generate patch file
pnpm patch-commit /tmp/ckeditor5-patch

# Patch applied automatically on install

Security Auditing

Logs

Security Events Logged:

• Login attempts (success/failure)
• Protected session access
• Password changes
• ETAPI token usage
• Failed CSRF validations

Log Location:

• Desktop: Console output
• Server: Log files or stdout

Monitoring

Metrics to Monitor:

• Failed login attempts
• API error rates
• Unusual database changes
• Large exports/imports