Entitlements & Security

The Security Layer protects every aspect of the Layerr system, from API keys to workspace isolation to regulatory compliance. It ensures that secrets never leak, tenants never cross boundaries, and guardrails prevent misuse.

Security Subsystems

Subsystem	Purpose	Key Files
Secrets Manager	Encrypted storage for API keys and credentials	src/backend/crypto.ts, security/secrets/
Credential Rotation	Automatic rotation of provider API keys	security/rotation/
Access Control	Permission engine for workspace resources	security/access/
Tenant Isolation	Multi-tenant workspace boundary enforcement	security/tenancy/
Gateway Security	Token validation, audit logging, rate limiting	security/gateway/
Guardrails	Content policy enforcement and PII detection	guardrails/evaluator.ts
Entitlements Engine	License and feature-gating	entitlements/engine.ts

Secrets Management

API keys and credentials are stored encrypted (src/backend/crypto.ts):

Feature	Implementation
Encryption at rest	AES-256-GCM via src/backend/crypto.ts
Key derivation	scrypt (crypto.scryptSync) with a random per-record salt
Per-field encryption	localKey, cloudKey, router.key, and each localProviders[*].key are encrypted individually
Encryption secret	Derived from ENCRYPTION_SECRET (falls back to ADMIN_API_KEY with a warning)
Redaction	Automatic redaction in logs (security/secrets/redact.ts)
Access audit	Every key access is logged

Caution

Encrypted values are tagged with a gcm1: prefix. Changing the key without first setting a stable ENCRYPTION_SECRET (for example, rotating ADMIN_API_KEY while relying on the fallback) breaks decryption of existing data.

Credential Rotation

The rotation engine (security/rotation/engine.ts) handles:

Function	Purpose
CredentialRotationEngine	Orchestrates scheduled key rotation
rotateKey()	Rotates a single provider key
detectStaleKeys()	Identifies keys approaching expiry

Rotation Schedule

Provider Type	Rotation Interval
Cloud providers (OpenAI, Anthropic)	90 days
Self-hosted (Ollama, local)	Disabled
Enterprise contracts	Configurable

Gateway Authentication

API and gateway requests authenticate with the ADMIN_API_KEY, supplied either as a bearer token or a dedicated header:

Authorization: Bearer <ADMIN_API_KEY>

x-admin-key: <ADMIN_API_KEY>

If ADMIN_API_KEY is not configured, all API access is disabled. The gateway and orchestration routes (for example POST /v1/chat/completions) layer additional entitlement checks on top of the key:

Requirement	Enforced By
Valid ADMIN_API_KEY (Bearer or x-admin-key)	gatewayAuthMiddleware
Capability gateway_access	requireCapability('gateway_access')
Scope orchestration.execute	requireGatewayScope('orchestration.execute')

There is no separate per-workspace API key; access is governed by the single admin key plus the capability and scope entitlements above.

Outbound URL Validation (SSRF)

Client-supplied provider URLs are validated by security/url-validation.ts before any outbound fetch. The policy blocks cloud metadata endpoints (169.254.169.254, metadata.google.internal), the Kubernetes API, IPv6 loopback, and loopback to Layerr’s own port. It deliberately allows private-LAN addresses (192.168.x, 10.x, 172.16-31.x) so that self-hosted local Ollama instances remain reachable.

Access Control

The permission engine (security/access/engine.ts) enforces:

Permission	Description
workspaces:read	View workspace configuration
workspaces:write	Modify workspace settings
providers:create	Add new provider connections
providers:delete	Remove provider connections
traces:read	View execution traces
traces:delete	Delete execution traces
billing:read	View billing and cost data
billing:write	Modify budget settings
admin:all	Super admin access

Tenant Isolation

Workspace isolation is enforced at multiple levels (security/tenancy/):

Level	Enforcement
Database	Row-level security per workspaceId
Runtime	Context injection prevents cross-tenant lookups
Cache	Tenant-scoped cache keys
Logs	WorkspaceId tagged on every log entry

Guardrails

The guardrails evaluator (guardrails/evaluator.ts) checks requests for:

Check	Action
PII detection	Block or redact if PII detected
Sensitive data	Sanitize sensitive data in traces (sanitizeSensitiveData())
Content policy	Enforce workspace content policies
Rate limiting	Per-workspace and per-provider rate limits

Entitlements

The entitlements engine (entitlements/engine.ts) manages:

Feature	Control
License activation	Validates license keys
Feature gating	Enables/disables features based on tier
Snapshot management	License snapshot and validation

File Reference

File	What It Does
src/backend/crypto.ts	AES-256-GCM encryption, scrypt key derivation, password hashing
security/secrets/redact.ts	Log redaction
security/url-validation.ts	Outbound URL (SSRF) validation for provider targets
security/rotation/engine.ts	Key rotation orchestration
security/rotation/detector.ts	Stale key detection
security/access/engine.ts	Permission evaluation
security/tenancy/context.ts	Tenant context injection
security/gateway/middleware.ts	Gateway token validation
security/gateway/audit.ts	Access audit logging
guardrails/evaluator.ts	Content policy and PII checks
entitlements/engine.ts	License and feature entitlements

Integration

1. Execution Engine → reads API keys from Secrets Manager
2. Provider Registry → triggers rotation on credential expiry
3. Workspace Profiles → reads tenant context for isolation
4. Economics → respects feature entitlements (e.g., simulation access)
5. All API routes → pass through gateway middleware for auth and audit