Authentication and Security

Relevant source files

• .github/workflows/arch_smoke.yml
• .github/workflows/pr_agent.yml
• CONTRIBUTING.md
• RECOVERY.md
• SECURITY.md
• assets/banner.svg
• cli/src/__tests__/templates.test.ts
• cli/src/bin.ts
• eslint.config.ts
• scripts/dev.ts
• scripts/generate-dockerhub-readme.ts
• src/__tests__/jwt.test.ts
• src/__tests__/logger.test.ts
• src/auth.ts
• src/functions/authorizer.ts
• src/jwt.ts
• src/logger.ts
• src/vault-mcp/oauth/__tests__/consent-page.test.ts
• src/vault-mcp/oauth/__tests__/oauth-provider.test.ts
• src/vault-mcp/oauth/__tests__/oauth-routes.test.ts
• src/vault-mcp/oauth/consent-page.ts
• src/vault-mcp/oauth/oauth-provider.ts
• src/vault-mcp/oauth/oauth-routes.ts
• sst.config.ts

Vault Cortex implements a robust, two-layer security model designed to protect personal notes while enabling remote access. Unlike most MCP servers that operate without authentication, Vault Cortex treats read/write access to a vault as a sensitive capability, providing defense-in-depth through an AWS Lambda authorizer and a full OAuth 2.1 provider.

The Two-Layer Auth Model

Security is enforced at two distinct boundaries in the reference deployment:

1. Infrastructure Layer (Lambda Authorizer): A path-aware AWS Lambda function attached to the API Gateway. It validates the Authorization header before requests reach the server src/functions/authorizer.ts4-9
2. Application Layer (OAuth 2.1): An internal provider that supports dynamic client registration, PKCE-secured authorization flows, and JWT-based session management src/vault-mcp/oauth/oauth-provider.ts1-10

Data Flow: Request Authorization

The following diagram illustrates how a request from an MCP client is validated through both security layers.

Request Validation Sequence

Sources: src/functions/authorizer.ts47-83 src/vault-mcp/oauth/oauth-provider.ts150-160

---

AWS Lambda Authorizer

The handler in src/functions/authorizer.ts serves as the first line of defense in AWS deployments. It is "path-aware," meaning it applies different logic based on the requested endpoint src/functions/authorizer.ts44-57

• Open Paths: Endpoints like /.well-known/, /authorize, /token, /register, /revoke, and /healthz are permitted to bypass authorization to allow the OAuth discovery and handshake process to function src/functions/authorizer.ts34-42
• Protected Paths: The /mcp endpoint requires a valid bearer token. The authorizer accepts two types of credentials:
  1. Static Token: Matches the McpAuthToken secret exactly using safeEqual src/functions/authorizer.ts71-74
  2. JWT Access Token: A token signed by the server's secret using the HS256 algorithm, validated via verifyJwt src/functions/authorizer.ts76-79

The authorizer relies on Resource.McpAuthToken.value provisioned via SST src/functions/authorizer.ts67

Sources: src/functions/authorizer.ts1-26 src/auth.ts1-15 sst.config.ts97

---

OAuth 2.1 Provider

The OAuth implementation allows agents to request specific scopes (currently vault) and provides users with a consent interface.

Key Components

Entity	Role	Code Location
createOAuthProvider	Factory that initializes the provider with SQLite persistence.	src/vault-mcp/oauth/oauth-provider.ts150-154
SqliteClientsStore	Persists dynamic client registrations to clients table in oauth.db.	src/vault-mcp/oauth/oauth-provider.ts99-103
mcpAuthRouter	SDK-managed routes for .well-known/mcp-configuration, /token, etc.	src/vault-mcp/oauth/oauth-routes.ts49-61
renderConsentPage	Generates the HTML form where users enter their MCP_AUTH_TOKEN to approve a client.	src/vault-mcp/oauth/consent-page.ts1-15

Token Management and Security

• HS256 JWTs: Access tokens are minimal JWTs signed with the server's secret. The implementation is custom-built in src/jwt.ts using only node:crypto to minimize the Lambda bundle size src/jwt.ts1-9
• Sliding Expiry: Refresh tokens have a 60-day lifetime (REFRESH_TOKEN_TTL_S). Every use rotates the token and resets the window src/vault-mcp/oauth/oauth-provider.ts35-39
• Single-Use Rotation: When a refresh token is used in consumeRefreshToken, it is deleted and a new one is issued to prevent replay src/vault-mcp/oauth/oauth-provider.ts195-210
• Safe Comparison: All token comparisons use safeEqual (wrapping crypto.timingSafeEqual) to prevent timing attacks src/auth.ts17-25

Sources: src/jwt.ts30-59 src/vault-mcp/oauth/oauth-provider.ts187-192 src/vault-mcp/oauth/oauth-provider.ts62-97

---

Runtime Hardening

Beyond authentication, Vault Cortex implements extensive runtime protections to ensure data integrity and prevent common attack vectors SECURITY.md25-30

Path Traversal and Injection Prevention

• Path Traversal: resolveSafePath() resolves then prefix-checks every path — ../../etc/passwd throws before filesystem access SECURITY.md32-35 toVaultRelativePath() normalizes backslashes and collapses ../ before checks SECURITY.md36-38
• SQL Injection: All queries use parameterized statements. sanitizeFtsQuery() strips FTS5 metacharacters and reserved words SECURITY.md57-60
• Prompt Injection: escapeVaultContentClosingTag() prevents vault content from breaking out of the <vault-content> data boundary in assembled prompts SECURITY.md61-64
• XSS Prevention: escapeHtml() is used on the OAuth consent page to escape client-supplied values SECURITY.md66-68

Data Integrity and Atomic Writes

• Atomic Writes: Uses a temp-then-rename strategy (atomicWriteFile) so readers never see partial content SECURITY.md71
• TOCTOU Guards: atomicWriteFileExclusive() uses link() on POSIX or O_EXCL on Windows to atomically create files without a check-then-write window SECURITY.md46-49
• Memory Layer Guards: Includes a shrink guard (refuses writes removing >50% of a file) and an idempotency guard (exact-bullet dedup) SECURITY.md74-78

Container and Information Leak Hardening

• Information Leaks: safeHandler() catches exceptions and returns only the message, masking internal stack traces and container paths SECURITY.md86-92
• Docker Hardening: Runs as a non-root user (node), uses tini as PID 1, and strips package managers (npm/npx/yarn) from the runtime image SECURITY.md93-100

Security Logic Entity Map

Sources: SECURITY.md25-106 src/jwt.ts50-75 src/functions/authorizer.ts47-83

---

Automated Scanning

Vault Cortex maintains a high security posture through a comprehensive toolchain integrated into the CI/CD pipeline SECURITY.md114-130:

• Gitleaks: Scans for accidental secret commits in full git history SECURITY.md119
• Trivy: Performs vulnerability scanning of Docker images (:latest and :remote) for OS-layer and dependency CVEs SECURITY.md120-124
• CodeQL: Static analysis for security vulnerabilities on every PR and push SECURITY.md118
• OpenSSF Scorecard: Grades the repo's security practices (dependency pinning, branch protection, SAST) SECURITY.md125-127
• Dependabot: Automates dependency updates for npm, GitHub Actions, and Docker base images SECURITY.md128-130

Sources: SECURITY.md114-130 CONTRIBUTING.md121-130