The Veritas Kanban server includes a flexible authentication and authorization system to protect API endpoints and WebSocket connections from unauthorized access.
For local development, enable localhost bypass:
# .env
VERITAS_AUTH_ENABLED=true
VERITAS_AUTH_LOCALHOST_BYPASS=trueThis allows unauthenticated requests from localhost/127.0.0.1 while still requiring auth for remote connections during development.
In NODE_ENV=production, localhost bypass is not honored for HTTP or WebSocket
auth, even if an old .env file still enables it.
For production, configure API keys:
# .env
VERITAS_AUTH_ENABLED=true
VERITAS_AUTH_LOCALHOST_BYPASS=false
VERITAS_ADMIN_KEY=your-secure-admin-key
VERITAS_API_KEYS=agent1:key1:agent,dashboard:key2:read-onlyRemote access must follow the v5 remote security posture in
ADR 0002. In
short: prefer one trusted origin for the web client, /api, and /ws; keep
auth enabled; disable localhost bypass outside loopback; use HTTPS, VPN, or a
trusted tunnel for browser/mobile sessions; and use exact origins instead of
wildcard CORS.
Clients can authenticate using any of these methods:
curl -H "Authorization: Bearer your-api-key" \
http://localhost:3001/api/taskscurl -H "X-API-Key: your-api-key" \
http://localhost:3001/api/tasksconst ws = new WebSocket('ws://localhost:3001/ws?api_key=your-api-key');HTTP requests do not accept API keys in query strings. Use headers for HTTP and
reserve the WebSocket api_key query fallback for clients that cannot send auth
headers during the upgrade.
v5 planning note: the current role model is intentionally small. The planned multi-user model expands this into workspace-scoped
owner,admin,member,reviewer,read-only, andagentroles with scoped agent tokens. See v5 Identity, Workspace, and RBAC Model.
| Role | Read | Write | Admin Actions |
|---|---|---|---|
admin |
✅ | ✅ | ✅ |
agent |
✅ | ✅ | ❌ |
read-only |
✅ | ❌ | ❌ |
- admin: Full access to all endpoints including sensitive operations
- agent: Can read/write tasks, run agents, manage worktrees. Intended for AI agents like OpenClaw
- read-only: Can perform read endpoints, including documented read-like POST checks. Suitable for dashboards and monitoring
Agent self-service routes are still permission-scoped. Read-like checks such as
agent routing and permission checks require agent:read; approval requests
require task:write; approval review, routing configuration, and permission
elevation require admin:manage.
Worktree mutations are fail-closed around repository ownership. Creation
records a credential-redacted repository fingerprint, exact base commit,
unique path/branch, and ownership lease before running git worktree add.
Active attempts lock rebase, integration, and cleanup. Cleanup inspects tracked
changes, untracked files, commits not reachable from the remote base, merge
reachability, and external process holds. An unavailable hold probe is treated
as incomplete evidence, not a clean result. Overrideable findings require
admin:manage plus an explicit actor-attributed reason in the durable manifest;
active runs, unexpired attempt leases, branch mismatches, and manifest
mismatches cannot be overridden. Integration resume revalidates path
containment, registered-worktree identity, common Git directory, and
credential-redacted remote identity before any push. Integration uses a
detached temporary worktree and a non-force push, so the configured primary
checkout is not mutated.
Repository-controlled execution is a separate trust boundary from worktree ownership. Before an executable provider launch, Veritas inventories recognized agent instructions, provider configuration, MCP servers, hooks, language-server settings, workflows, extensions, skills, and agent definitions. Executable configuration requires an explicit, actor-attributed decision for the exact workspace identity and inventory digest. Model-only instructions can run provisionally only under the enforced restricted profile. The inventory and decision are bound into the immutable launch manifest and rescanned before provider creation; drift fails closed. A repository-owned policy can only narrow trust. See Workspace Execution Trust.
Authenticated REST requests and WebSocket connections now carry a shared auth context for the v5 RBAC migration:
| Field | Description |
|---|---|
role |
Current compatibility role: admin, agent, read-only |
userId |
Local fallback user ID until persisted users are enforced |
workspaceId |
Local fallback workspace ID until workspace scoping lands |
actorType |
user, agent, service, or localhost-bypass |
authMethod |
disabled, session, api-key, device-session, or localhost-bypass |
tokenName |
API key name when authenticated with a configured key |
permissions |
Role-derived permission list used by new route guards |
New v5 endpoints should prefer explicit permission guards over broad role checks. Legacy role guards remain supported while route coverage is migrated.
Browser password sessions are local-owner only in v5 GA. The server accepts the
session cookie only on loopback requests with loopback Host/Origin/Referer
metadata. A verified loopback owner session receives the narrow
local-agent:run capability so the packaged desktop can start and control local
agents; this does not enable unauthenticated localhost bypass, which remains
disabled in production. Remote, server, PWA, and multi-user clients must
authenticate with a trusted device session or scoped API token so active
workspace membership, role, revocation, and downgraded scopes are revalidated.
The v5 authority surface is tracked in
docs/security/permission-coverage.json.
Run node scripts/check-permission-coverage.mjs to fail when a REST route
prefix, WebSocket event, CLI command, MCP tool, workflow step/action type,
command palette action, or tracked background job is added without a permission
classification.
The v5.0 hardening review is recorded in
docs/security/v5-security-review.md,
including fixed high/critical findings, accepted hardening risks, and the
password-session local-owner boundary.
Release compatibility, stale-client behavior, update channels, and rollback
limits are tracked in
docs/V6-COMPATIBILITY-AND-RELEASE-POLICY.md.
Compatibility errors and debug bundles must redact tokens, cookies, private
keys, local private paths, raw chat content, and task body text.
Buzz communication diagnostics and delivery store environment-variable
references and public/redacted metadata only. The Nostr private key and
optional NIP-OA auth tag are resolved only for an active probe or signing
operation and are never returned.
The built-in signer accepts hexadecimal or nsec private-key material,
constructs the Buzz-required nonce and exact request-body hash, and clears its
decoded key bytes after signing on a best-effort basis.
Relay URLs reject userinfo, query strings, and fragments. Outbound requests use
scheme validation, explicit plaintext/local/RFC1918/ULA opt-ins, DNS pinning,
manual redirects, fixed timeouts, and bounded response reads. Link-local,
cloud-metadata, and CGNAT ranges remain blocked under the private-network
opt-in. The compatibility probe reads NIP-11 metadata and authenticated query
filters only. The communication worker uses a DNS-pinned, channel-allowlisted
NIP-42 WebSocket subscription and verifies event signatures, kinds, channel
IDs, timestamps, and bounded sizes before projection. Outbound signed events
are persisted before submission. Ambiguous writes are queried by event ID and
the persisted signature, configured identity, and mapped channel are
re-verified before any resubmission. Echoed adapter event IDs are suppressed.
Optional command discovery runs without a shell and receives a minimal
environment that excludes provider and Buzz credentials. See
Buzz Communication Adapter.
Buzz persona/team import accepts only reconstructed, signature-verified kinds
30175 and 30176 from the configured signed query path. Event, content,
JSON depth, key count, array count, string, URL, and batch limits apply before
preview. Secret-like values and fields for credentials, environment, commands,
paths, processes, managed agents, MCP, hooks, skills, or engrams reject the
record. Public avatar URLs are validated but never fetched.
Definition import is an explicit one-way data operation. Newly materialized profiles, rosters, and roster members are disabled. Declared Buzz runtime, model, and provider values remain source metadata and are not provider-runtime evidence. The source event ID and optimistic local revision are checked again inside the authoritative JSON-file lock or SQLite transaction before mutation. Source removal never deletes local materializations.
Tool-server definitions are administrator-controlled and schema validated. Transport arguments are arrays executed without a shell, HTTP URLs cannot contain userinfo, query strings, or fragments, and environment/header fields store key names only. Raw environment and credential values are excluded from definitions, discovery records, run catalogs, launch manifests, logs, and events. Credential-like environment keys, explicit broker references, and HTTP header references fail closed until brokered provider launch handles are available.
Discovery schemas and all tool inputs and results have bounded byte and item limits. Discovery is bound to the exact definition digest so identity or version drift invalidates cached evidence. Required failures block launch; optional failures remain visible as degraded catalog entries. An immutable catalog binds task, attempt, provider-runtime digest, task-envelope digest, definition digest, discovery digest, and each per-tool policy decision.
Native provider configuration exposes only allow decisions. Denied and
approval-required tools remain disabled. The mediated call route requires
agent:write, the exact active running attempt, and a catalog digest matching
the persisted launch manifest. Approval-required calls bind the server, tool,
arguments, catalog digest, and operation ID to run-approval/v1; a changed,
expired, rejected, or stale decision fails closed.
Each invocation validates arguments against the discovered JSON Schema,
dispatches once per stable operation ID, and records bounded redacted
tool.started, tool.completed, or causal run.error events. Run completion
closes supervised bridge sessions. Credential-bound definitions remain
unavailable until the provider launch credential broker can resolve run-scoped
handles without persisting values.
Provider runtime manifests are authorization evidence, not display metadata.
The server validates their complete capability inventory, canonical SHA-256
digest, probe state, and secret redaction before use. Launch requirements and
run controls qualify only with supported or advisory evidence;
unsupported, unknown, missing, failed-probe, malformed, or invalid-digest
evidence fails closed.
The selected manifest is persisted on the attempt before provider execution. Status, logs, completion, stop, message/steer, token reporting, tool events, and artifact ingestion compare the active snapshot with the persisted digest before acting. A mismatch stops provider event ingestion and requires the operator to terminate the detached provider through its host supervisor, reconcile attempt state, and launch a fresh run. Veritas does not offer a UI force-stop that bypasses runtime evidence.
The durable run supervisor also binds the provider snapshot to the exact task envelope, launch manifest, worktree fingerprint and ownership lease, host identity, and operating-system process start identity. Recovery uses an expiring compare-and-set lease. Process-group stop is refused when the PID has exited, been reused, moved hosts, or cannot be identified safely; remote sessions are contacted only through adapter-declared recovery controls.
Public sandbox dry-runs accept a live registered manifest digest, not a
caller-supplied manifest body. The server resolves the digest from current host
registrations and rejects unknown, expired, or provider-mismatched evidence.
Human Veritas approval gates remain separate from provider-native
run.approvals; one does not imply the other. Shared co-drive links are pinned
to their source attempt. Message and approval actions require that exact attempt
to remain active and require current run.steer or run.approvals evidence, so
an old link cannot control a replacement run on the same task.
Agent sandbox policy presets live in the shared app config and are managed from
Settings -> Agents -> Sandbox Policies or /api/sandbox-policies.
Use them to constrain:
- Filesystem read/write paths, denied paths, dotfile masking, and local-only handles.
- Network egress defaults, allowlisted hosts and path prefixes, and private network or metadata endpoint blocks.
- Environment variable passthrough.
- Credential access mode: none, brokered references, or explicit environment passthrough.
Launch-time validation resolves every preset rule from the persisted provider
runtime manifest. Required unsupported controls block the agent or workflow
step before execution. Advisory unsupported controls continue with warnings.
Every dry-run and launch-time decision writes a governance trace with raw
detail redacted; credential references and environment-style name=value
strings are shown as [redacted].
For local ACP, Claude Code, Codex app-server, Codex CLI, and Hermes runs,
Veritas can compile those filesystem rules into a version-bound codex sandbox process wrapper. The credential-free backend probe covers read,
write, deny, symlink and hard-link escape, dotfile, protected metadata,
descendant, PATH-tool, and backend re-execution behavior. A failed or missing
backend blocks a required policy before provider process creation. Codex SDK
and remote OpenClaw runs require exact provider-native conformance evidence,
including descendant inheritance, run-scoped temporary storage, and cleanup;
coarse provider sandbox modes remain advisory.
Workspace and home aliases are canonical-base constrained. Nested mounts below allowed roots are denied unless explicitly granted or denied, and the relevant mount topology is rechecked before provider spawn. A changed or uninspectable topology fails closed. The bounded workspace tree is scanned before compilation and immediately before activation for pre-existing hard links that alias inaccessible external inodes.
CLI package and virtual-environment roots are read-only. Linked-worktree Git
metadata is resolved to exact protected read-only roots so status and diff can
work without exposing the primary checkout for writes. Ambient system/global
Git configuration is disabled; only effective author identity values may be
carried in memory for the run, and they are excluded from manifests and logs.
The .git, .agents, .codex, and .veritas-kanban names receive explicit
read-only entries directly beneath writable roots and cannot themselves be
selected as writable policy roots. A protected path that is or becomes a
symlink blocks launch.
Launch evidence stores only canonical path hashes and binds the filesystem decision to the exact provider runtime manifest digest and conformed backend executable-content digest. The executable is rehashed after policy evaluation and immediately before activation, so same-size replacement with restored timestamps still blocks launch. Local run-specific temporary and cache directories are registered with the durable run supervisor and cleaned on terminal completion or recovery; cleanup rejects symlinked ancestors. Remote provider-native backends must prove their equivalent lifecycle. See Run-scoped filesystem sandbox backends.
Required filesystem boundaries have no per-run bypass. Task-readiness
overrideReason values do not affect sandbox enforcement. Relaxation requires
an authorized advisory policy preset, and the evaluated policy plus launch
decision are retained as governance evidence.
Credential definitions are stored separately from secret values. An admin can
register a source reference and bounded host/tool/destination/action policy at
/api/credential-broker; the stored credential-definition/v1 record contains
only metadata and a canonical digest.
Internal consumers can issue an opaque credential-lease/v1 handle only when
the referenced definition appears in the active attempt's immutable launch
manifest. The lease is bound to that task, attempt, manifest digest, definition
digest, scope digest, and exact action fingerprint. Handles are persisted only
as SHA-256 hashes. Uses are claimed atomically before source resolution and
enforce TTL, maximum uses, approval posture, and current run binding.
The resolved value is passed only to a controlled in-process callback. The broker rejects callbacks that return the value and replaces callback/source errors with credential-free failures. Definitions, leases, audit events, logs, manifests, completion packets, and API responses never contain the resolved value. Terminal run paths revoke matching leases, and startup reconciliation expires stale leases or blocks leases whose source is unavailable.
This is a foundation, not a claim that provider traffic is controlled.
Required brokered presets fail closed when runtime evidence is advisory,
external, missing, or bypassable. Provider handle migration requires the
controlled network or tool boundaries documented in
Credential Broker. Raw env-passthrough remains an
explicit compatibility mode and is not brokered.
Agent budget policies are enforced through the same governance path. Workspace,
agent, workflow, workflow-agent, and per-run budgets can cap tokens,
provider-reported cost, tool-call counts, runtime, retry count, and workflow
fan-out. Soft thresholds write budget-policy warning traces. Hard thresholds
pause or block for approval, downgrade to a configured model route, or cancel
the run with recorded trace and completion-packet evidence.
For untrusted or externally sourced work, prefer a required preset with repository-scoped writes, default-deny network egress, metadata endpoint blocking, and brokered credentials. Keep the legacy permissive preset only for existing local Codex CLI workflows that still need broad compatibility.
| Variable | Default | Description |
|---|---|---|
VERITAS_AUTH_ENABLED |
true |
Enable/disable authentication |
VERITAS_AUTH_LOCALHOST_BYPASS |
false |
Allow unauthenticated localhost requests in development |
VERITAS_ADMIN_KEY |
(none) | Admin API key with full access |
VERITAS_API_KEYS |
(none) | Comma-separated API keys (format: name:key:role) |
name:key:role,name2:key2:role2
Example:
veritas:vk_abc123xyz:agent,dashboard:vk_def456uvw:read-only
# Generate a random 32-character key
openssl rand -base64 32import { generateApiKey } from './middleware/auth.js';
const key = generateApiKey('vk'); // e.g., vk_AbCdEf123...Check the current authentication configuration:
curl http://localhost:3001/api/auth/statusResponse:
{
"enabled": true,
"localhostBypass": false,
"configuredKeys": 2,
"hasAdminKey": true
}curl http://localhost:3001/healthWebSocket connections are authenticated on connect:
// With API key
const ws = new WebSocket('ws://localhost:3001/ws?api_key=your-key');
ws.onclose = (event) => {
if (event.code === 4001) {
console.error('Authentication failed:', event.reason);
}
};| Code | Meaning |
|---|---|
1000 |
Normal close |
4001 |
Authentication required/failed |
{
"error": "Authentication required",
"code": "AUTH_REQUIRED",
"hint": "Provide API key via Authorization header (Bearer <key>), X-API-Key header, or api_key query parameter"
}{
"error": "Write access denied",
"code": "WRITE_FORBIDDEN",
"hint": "Your API key has read-only access"
}-
Never commit API keys - Use environment variables or
.envfiles (add to.gitignore) -
Rotate keys regularly - Update API keys periodically, especially if compromised
-
Use HTTPS in production - API keys are transmitted in headers/URLs
-
Principle of least privilege - Use
read-onlyfor dashboards,agentfor automation -
Monitor access - The server logs connection attempts with role information
-
Constrain agent launches - Assign sandbox policy presets and run budgets before running untrusted or expensive work. Default-deny network egress, broker credentials, and cap token, spend, tool-call, runtime, retry, and fan-out exposure when a workflow does not need broad access.
-
Keep remote mode explicit - Binding outside loopback, reverse proxying, tunneling, or serving mobile/PWA clients requires auth enabled, localhost bypass disabled, exact CORS/WebSocket origins, and redacted diagnostics. See ADR 0002.
If you're upgrading from an earlier version without authentication:
-
Before upgrading: Document all clients that access the API
-
During upgrade:
- Start with
VERITAS_AUTH_LOCALHOST_BYPASS=truefor smooth transition - Generate API keys for each client
- Update clients to include authentication headers
- Start with
-
After testing: Disable localhost bypass for production
Check that VERITAS_AUTH_LOCALHOST_BYPASS=true is set, or provide an API key.
- Verify the key matches exactly (no extra spaces)
- Check that the key is in the
VERITAS_API_KEYSorVERITAS_ADMIN_KEYvariable - Ensure the format is correct:
name:key:role
- Check browser console for the close reason
- Ensure the API key is passed as a query parameter:
?api_key=...
┌─────────────────────────────────────────────────────────────┐
│ Request Flow │
├─────────────────────────────────────────────────────────────┤
│ │
│ Client Request │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ CORS/JSON │ (express middleware) │
│ └──────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ ┌───────────────────────┐ │
│ │ /health │──▶│ Bypass auth │ │
│ │ /api/auth/* │ │ (unauthenticated) │ │
│ └──────────────┘ └───────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ authenticate │ (middleware/auth.ts) │
│ │ │ │
│ │ - Check auth │ │
│ │ enabled │ │
│ │ - Localhost │ │
│ │ bypass? │ │
│ │ - Validate │ │
│ │ API key │ │
│ └──────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────┐ │
│ │ Route Handler│ (req.auth available) │
│ └──────────────┘ │
│ │
└─────────────────────────────────────────────────────────────┘
- v3.3.0 (2026-02-15): Task intelligence security hardening
- Crash-recovery checkpointing with auto-sanitization of 20+ secret patterns plus regex value detection
- XSS prevention in observational memory via
sanitizeCommentText() - DFS cycle detection in task dependencies prevents infinite loop attacks
- Input sanitization on agent filter (trim + 100 char cap)
- Zod validation on all dependency and checkpoint routes
- v3.0.0 (2026-02-09): Workflow engine security
- ReDoS protection on regex acceptance criteria
- Expression injection prevention in template evaluator
- Parallel DoS limits (max 50 concurrent sub-steps)
- Gate approval authentication and permission checks
- RBAC with ACL files for workflow access control
- Audit logging of all workflow changes
- v2.0.0 (2026-02-06): Multi-agent security
- Agent permission levels (Intern/Specialist/Lead) with enforcement
- Agent registry with heartbeat-based liveness tracking
- MCP SDK patched to ^1.26.0 (GHSA-345p-7cg4-v4c7)
- Rate limiting documentation (reverse proxy recommended for public deployments)
- v1.0.0 (2026-01-29): Initial authentication implementation
- API key authentication for HTTP and WebSocket
- Role-based authorization (admin, agent, read-only)
- Localhost bypass for development
- Configuration via environment variables