vwarden
Unified OIDC 1.0, OAuth 2.1, SAML 2.0, SCIM 2.0 & Access Policy Engine

vwarden — Unified Identity, Federation & Access Policy Engine

vwarden — Unified Identity, Federation & Access Policy Engine

Overview

vwarden is a self-contained, zero-external-dependency OpenID Connect (OIDC) 1.0, OAuth 2.1, SAML 2.0, SCIM 2.0, Access Policy Decision Point (PDP), and LDAPv3 Directory Bridge. Distributed as a single native executable for Windows, Linux, and macOS, vwarden serves as the central identity and authorization authority for both End Users and System Administrators.

IDENTITY TOPOLOGY

vwarden End-to-End OpenID Connect 1.0, OAuth 2.1, SAML 2.0 & SCIM 2.0 Architecture

Click any component node to inspect how vwarden authenticates principals, mints signed tokens, and governs policies.

Interactive SVG • Click any node (6 components)
1. RELYING PARTIES & PRINCIPALS Browser / CLI / Ecosystem Services 2. IDENTITY & POLICY CORE OIDC + SAML + SCIM + ZERO-TRUST PDP 3. PERSISTENCE & CRYPTO VAULT Sharded MVCC / SQLite / Postgres OIDC + PKCE MFA / SCIM Verify Enforce Sealed I/O Federation Clients Relying Parties (RP) vgate, vft, vsite, vstore, vsight Principals Operators & End Users Self-Service Portal & Admin Studio Protocol Core OIDC & OAuth 2.1 Engine Discovery, PKCE, Token & JWKS Identity Engine MFA, SAML 2.0 & SCIM 2.0 Argon2id, Two-Step TOTP & SCIM Security Boundary Zero-Trust Policy Guard ZERO-TRUST PDP + Rate Limiter Persistence SecretVault & Sharded MVCC AES-256-GCM + 64-Shard WAL
Components:
Federation Clients
Relying Parties (RP)
Relying Party Federation Boundary
Component 1 of 6
Architectural Role & Purpose

Applications, gateways, and CLI services that delegate authentication and policy evaluation to vwarden.

Contextual Description & System Interaction

Forms the Relying Party boundary across vgate IAP, vft file transfer, vsite, vstore, varc, vca, and vsight.

Core Functionality & Security Mechanics
  • Initiates OAuth 2.1 Authorization Code + PKCE (S256) flows
  • Verifies signed EdDSA ID Tokens and Access Tokens via JWKS endpoint
  • Consumes SCIM 2.0 user and group lifecycle provisioning events
Principals
Operators & End Users
Role-Separated Web Studio
Component 2 of 6
Architectural Role & Purpose

Human end users managing credentials/MFA and operators governing tenants, OrgUnits, and policies.

Contextual Description & System Interaction

Supports both reflexive self-service SSO (/ui/portal) and scoped or global governance (/ui/delegated, /ui/admin).

Core Functionality & Security Mechanics
  • Enrolls RFC 6238 TOTP MFA via offline ISO 18004 SVG QR codes
  • Governs tenants, OAuth clients, signing key rotation, and Zero-Trust PDP policies
  • Inspects real-time Ed25519-signed RFC 5424 security audit trails
Protocol Core
OIDC & OAuth 2.1 Engine
OIDC 1.0 OAuth 2.1 PKCE Engine
Component 3 of 6
Architectural Role & Purpose

Implements RFC 8414 Discovery, OAuth 2.1 PKCE authorization, token exchange, JTI revocation, and JWKS publication.

Contextual Description & System Interaction

Eliminates implicit flow vulnerabilities and token replay by enforcing OAuth 2.1 and OpenID Connect 1.0 Core invariants.

Core Functionality & Security Mechanics
  • Serves /.well-known/openid-configuration and /.well-known/jwks.json
  • Enforces mandatory S256 PKCE code_challenge verification and state/nonce binding
  • Mints short-lived EdDSA (Ed25519) JWTs with multi-key rotation and JTI tombstones
Identity Engine
MFA, SAML 2.0 & SCIM 2.0
Credential KDF SAML 2.0 SCIM 2.0
Component 4 of 6
Architectural Role & Purpose

Provides Argon2id credential hashing, two-step TOTP MFA, SAML 2.0 federation, and RFC 7643/7644 SCIM 2.0 provisioning.

Contextual Description & System Interaction

Bridges modern OIDC microservices and enterprise SAML/SCIM/LDAPv3 directories inside a single executable.

Core Functionality & Security Mechanics
  • Enforces two-step mfa_challenge_token login and 30-second TOTP step replay protection
  • Hashes passwords with Argon2id (19 MiB, t=2, p=1) and transparent legacy upgrade
  • Synchronizes users and groups with atomic session and JIT grant revocation on deprovisioning
Security Boundary
Zero-Trust Policy Guard
Zero-Trust Policy Engine Transport Guard
Component 5 of 6
Architectural Role & Purpose

Enforces Zero-Trust PDP RBAC/ABAC/Org-Graph policies, constant-time checks, CSRF headers, and sliding-window rate limits.

Contextual Description & System Interaction

Protects every endpoint against timing side-channels, path traversal, CSRF, XSS, and credential stuffing.

Core Functionality & Security Mechanics
  • Compares all tokens and hashes via SHA-256 length-hiding constant-time equality
  • Enforces HttpOnly; SameSite=Lax cookies, X-Vwarden-CSRF: 1, and bounded socket framing
  • Emits Ed25519-signed hash-chained RFC 5424 SIEM audit entries for every security event
Persistence
SecretVault & Sharded MVCC
AES-256-GCM Vault Sharded MVCC Store
Component 6 of 6
Architectural Role & Purpose

Seals sensitive keys with AES-256-GCM and persists state in 64-shard Copy-on-Write MVCC + binary WAL.

Contextual Description & System Interaction

Ensures that even a raw snapshot never exposes plaintext passwords, MFA seeds, or signing private keys.

Core Functionality & Security Mechanics
  • Seals TOTP secrets, Ed25519 keys, and vnet_tok_ grants via AES-256-GCM + AAD (ENC[vw1:...])
  • Persists CRC32 binary WAL segments, sparse offset indexes, and LZ4 snapshots
  • Supports sharded MVCC, SQLite WAL, and PostgreSQL persistence backends

Core Capabilities

Audience Capability Operational Value
End Users Single Sign-On (SSO) & Two-Step TOTP MFA Sign in once using Argon2id password verification and a two-step RFC 6238 6-digit TOTP verification ceremony with 30-second replay protection across connected applications (vgate, vft, vsite, vstore, vsight, varc, vca).
End Users Self-Service Identity Portal (/ui/portal) Manage personal profile attributes, rotate passwords with current-password verification, enroll authenticator apps via offline ISO/IEC 18004 vector SVG QR codes, and request or revoke Just-in-Time (JIT) access leases.
Delegated Operators Organizational Unit Workspace (/ui/delegated) Approve or reject staged onboarding requests and temporary JIT access workflows strictly within assigned Organizational Unit subtrees under separation-of-duties guardrails.
System Administrators Unified Governance & Federation (/ui/admin) Govern multi-tenant realms, RBAC/ABAC/Org-Graph policies, OAuth 2.1 PKCE clients, SAML 2.0 Service Providers, SCIM 2.0 lifecycle provisioning, Corporate Active Directory / LDAPv3 synchronization, clustered WAL replication, and Ed25519-signed SIEM audit trails.
Platform Engineers Flexible Persistence & Standalone TLS Run out of the box on the built-in 64-shard Copy-on-Write MVCC engine with CRC32-verified binary WAL and LZ4 snapshots, or connect to SQLite WAL / PostgreSQL; deploy behind vgate over loopback HTTP/1.1 or directly with built-in TLS 1.2+ (--tls-cert / --tls-key).

Live Workspace Preview

Authentication & Onboarding Gate (/ui/auth)

vwarden Sign-In & Multi-Factor Authentication Gate

End-User Self-Service Portal (/ui/portal)

vwarden End-User Self-Service Profile & Offline ISO 18004 QR MFA Enrollment


End-User Documentation Suite

  1. Overview & Readme — Product overview, core capabilities, and quickstart commands.
  2. How-To Guide — Step-by-step operational recipes for TLS deployment, MFA enrollment, OIDC client registration, and JIT access workflows.
  3. End-User Guide — Complete guide for signing in, enrolling TOTP authenticators, managing personal profiles, and requesting temporary infrastructure leases.
  4. Administrator Guide — Production installation, master key vault management, tenant/OrgUnit governance, SCIM 2.0 deprovisioning, and SIEM audit verification.
  5. Operations, Use Cases & Examples — End-to-end integration playbooks and runnable HTTP/CLI examples for OAuth 2.1 PKCE, Policy Decision Point evaluation, SCIM 2.0, SAML 2.0, and VGate PAM/JIT.
  6. Configuration & CLI Reference — Complete reference for CLI subcommands, flags, environment variables, bootstrap configuration JSON, and REST API endpoints.
  7. Performance & Capacity Guide — Throughput, latency characteristics, Argon2id sizing, sharded MVCC scaling, and hardware sizing recommendations.
  8. Consolidated User Handbook — Single-file master compendium combining all End-User, How-To, Administrator, Operations, Configuration, and Performance guides.

Quickstart

Launch vwarden locally using the prebuilt binary for your operating system (dist/bin/windows/vwarden.exe, dist/bin/linux/vwarden, or dist/bin/macos/vwarden):

BASH
# Check installed semantic version
./vwarden version

# Inspect generated OpenID Connect 1.0 discovery metadata
./vwarden discovery https://id.acme.example.com

# Start the identity server and Web Studio on 127.0.0.1:8443 using the built-in MVCC store
./vwarden serve 8443 vprevail

# Start with standalone HTTPS termination
./vwarden serve 8443 vprevail --tls-cert certs/fullchain.pem --tls-key certs/privkey.pem

Once running, open http://127.0.0.1:8443/ui/auth (or https://127.0.0.1:8443/ui/auth when TLS is enabled) in your browser.

vwarden — How-To Guide

1. How to Deploy Behind vgate vs. Standalone HTTPS

System administrators can deploy vwarden in two production network topologies without changing client configurations:

When vgate terminates public ACME/TLS 1.3 traffic on port 443, bind vwarden strictly to loopback (127.0.0.1) and configure a shared Policy Enforcement Point (PEP) secret:

BASH
export VWARDEN_MASTER_KEY_HEX="0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
export VGATE_MESH_SECRET="replace-with-256-bit-random-mesh-hmac-secret"
export VWARDEN_PEP_TOKEN="replace-with-256-bit-random-pep-bearer-secret"

./vwarden serve 8443 vprevail --host 127.0.0.1 --pep-token "$VWARDEN_PEP_TOKEN"

Recipe B — Standalone Direct HTTPS Termination

When deploying vwarden directly on an internal network without an upstream proxy, supply a PEM certificate chain and private key. vwarden automatically activates Strict-Transport-Security and marks vwarden_session cookies as Secure:

BASH
./vwarden serve 8443 vprevail \
  --host 0.0.0.0 \
  --tls-cert ./certs/fullchain.pem \
  --tls-key ./certs/privkey.pem

2. How to Enroll and Confirm Two-Step TOTP Multi-Factor Authentication

vwarden uses a two-phase MFA enrollment ceremony so users never lock themselves out if a browser tab closes mid-scan.

Offline ISO 18004 QR Code MFA Enrollment in /ui/portal

  1. Sign in at /ui/auth and navigate to Self-Service (/ui/portal) -> 1. My Profile, Password & MFA QR.
  2. Click 1. Stage New TOTP QR Secret (POST /api/v1/self/mfa/enroll). vwarden seals a fresh RFC 4648 Base32 secret in the AES-256-GCM vault under a pending key and renders an ISO/IEC 18004 SVG QR code locally in your browser.
  3. Scan the QR code using any RFC 6238 authenticator app (1Password, Bitwarden, Proton Pass, Google Authenticator, or Microsoft Authenticator).
  4. Enter the live 6-digit code in the confirmation input and click 2. Confirm & Activate MFA (POST /api/v1/self/mfa/confirm).
  5. Your active session immediately upgrades to mfa_verified: true, and future sign-ins enforce the two-step challenge.

3. How to Submit and Approve a Staged User Onboarding Request

Self-service registration never writes unvetted accounts into the active directory. Instead, it launches a durable approval workflow.

Self-Service Registration & Durable Onboarding Workflow

  1. Applicant Action (/ui/auth):
    • Select the Register / Request Onboarding Workflow tab.
    • Enter desired username, full name, corporate email, password, target Organizational Unit, department, and business justification.
    • Click Submit Registration & Start Onboarding Workflow. vwarden returns a workflow ID (for example, wf_onb_...) in pending_approval state.
  2. Administrator / Delegated Admin Action (/ui/admin or /ui/delegated):
    • Sign in as an authorized administrator and open 1. Onboarding & JIT Approvals.
    • Review the applicant's requested Organizational Unit and justification.
    • Click Approve & Activate User to atomically provision the directory record and group bindings, or Reject to discard the staged request with a signed SIEM audit record.

4. How to Register an OpenID Connect 1.0 Relying Party Client

  1. Sign in to /ui/admin and open 5. Federation & OAuth Clients.
  2. Click + Register OAuth 2.1 Client and populate:
    • Client ID: Safe slug matching [a-zA-Z0-9_-]{1,64} (for example, vft-enterprise-portal).
    • Display Name: Human-readable service title.
    • Allowed Redirect URIs: Exact HTTPS callback URLs (comma-separated).
    • Allowed Scopes: openid,profile,email,groups,offline_access.
    • Require PKCE (S256): Enabled (mandatory for OAuth 2.1 security).
  3. Configure your Relying Party with the discovery URL:
TEXT
   https://id.acme.example.com/.well-known/openid-configuration

5. How to Request and Revoke Just-In-Time (JIT) Infrastructure Access

Requesting VGate JIT PAM Access in /ui/portal

  1. Open Self-Service (/ui/portal) -> 2. Request JIT Access & Active VGate Leases.
  2. Choose a service catalog template (such as VGate Prod Bastion SSH or VGate Prod PostgreSQL), select the required lease duration (15m, 30m, 1h, or 4h), and enter the incident ticket ID.
  3. Click Request VGate JIT Lease & Launch Approval Workflow.
  4. Once your Organizational Unit manager approves the request in /ui/delegated, your active vnet_tok_... subject token appears in the Active VGate PAM TagGrants table with a live expiration countdown.
  5. When maintenance concludes early, click Revoke Lease (POST /api/v1/self/vgate/revoke) to terminate the network grant immediately.

vwarden — End-User Guide

vwarden — Unified Identity, Federation & Access Policy Engine

1. Welcome to vwarden Single Sign-On

vwarden is your organization's central sign-in, Multi-Factor Authentication (MFA), and access request portal. Instead of maintaining separate passwords for internal web applications, file transfer portals, observability consoles, and developer repositories, you authenticate once through vwarden to access authorized services seamlessly.


2. Signing In & Two-Step Verification (/ui/auth)

vwarden Sign-In Gate

2.1 Step 1 — Directory Password Sign-In

  1. When opening a protected application (or visiting /ui/auth directly), verify your Tenant Realm (for example, acme) and enter your Username and Password.
  2. Your password is protected using memory-hard Argon2id hashing and is never transmitted to downstream applications.
  3. If TOTP MFA is not yet enabled on your account, vwarden establishes your browser session inside an HttpOnly; SameSite=Lax cookie and routes you to /ui/portal.

2.2 Step 2 — 6-Digit Authenticator Challenge

  1. When TOTP MFA is active on your account, Step 1 displays Step 2 — RFC 6238 6-Digit TOTP Verification Code instead of creating a session immediately.
  2. Open your mobile or desktop authenticator application and enter the current 6-digit code within 5 minutes.
  3. Every 6-digit TOTP code is single-use within its 30-second window—even if an onlooker sees your code, it cannot be replayed to open a second session.
  4. Upon verification, your session carries the mfa_verified assurance claim so MFA-protected resources permit access automatically.

3. Requesting a New Account (Self-Service Onboarding)

Staged Onboarding Registration Form

If you are a new employee or contractor without an active directory account:

  1. At /ui/auth, click Register / Request Onboarding Workflow.
  2. Complete your desired username, display name, work email, password, Organizational Unit, department, and ticket or manager reference.
  3. Click Submit Registration & Start Onboarding Workflow.
  4. Your request enters a staged approval queue (pending_approval). As soon as an authorized administrator approves your onboarding workflow, your account becomes active for Single Sign-On.

4. Managing Your Identity in the Self-Service Portal (/ui/portal)

All operations in /ui/portal act strictly on your own identity (is_self reflexive scope), ensuring you can update personal preferences safely without administrative intervention.

4.1 Profile Attributes & Password Rotation

  • Edit My Profile: Click Edit My Profile in the top action bar to update your display name, email address, given/family name, department, POSIX home directory, or login shell.
  • Inspect My SCIM 2.0 JSON: View the exact standardized RFC 7643 identity payload shared with connected enterprise applications.
  • Change My Password: Click Change My Password, enter your current password and a new password, and submit. Your account immediately upgrades to a fresh Argon2id digest.

4.2 Offline QR Code MFA Enrollment

Self-Service Portal Profile & QR Code MFA Enrollment

  • Click 1. Stage New TOTP QR Secret to render a crisp vector QR code generated locally by vwarden (zero data is sent to third-party QR websites).
  • Scan the QR code in your authenticator app, type the current 6-digit code, and click 2. Confirm & Activate MFA.
  • If you refresh or close the tab before confirming, your previous MFA configuration remains intact.

4.3 Requesting Temporary JIT Infrastructure Leases

Self-Service JIT Access Request & Active Leases

Production servers and databases enforce Zero Standing Privilege—access is granted only for explicit maintenance windows:

  1. Open 2. Request JIT Access & Active VGate Leases.
  2. Select the target workflow template, lease TTL, protected resource URN, and protocol (pam:ssh, db:postgres, or k8s:exec), then provide your incident or change ticket justification.
  3. Track live approval status in My Submitted Access & Onboarding Workflow Requests.
  4. Once approved, copy your time-bounded vnet_tok_... lease from Active VGate PAM TagGrants, or click Revoke to end the session early.

4.4 Testing SSO Applications & Signing Out

  • Open 3. My SSO Applications & OAuth 2.1 PKCE to inspect OIDC Discovery metadata, JWKS public keys, and SAML 2.0 metadata, or test OAuth 2.1 PKCE token exchange and revocation.
  • Passkeys (FIDO2 / WebAuthn): Under 1. My Profile & MFA, register a hardware security key or platform passkey (ES256 or EdDSA) and use Sign In with Passkey (FIDO2) on /ui/auth for passwordless MFA sign-in.
  • Device Authorization (/ui/device): When signing in from a CLI or headless device, open /ui/device (or follow the verification link), enter the XXXX-XXXX user code, and click Approve Device.
  • Click Sign Out in the top-right header at any time to destroy your server-side session and clear your browser cookie immediately.

vwarden — Administrator Guide

vwarden — Unified Identity, Federation & Access Policy Engine

1. Deployment Architecture & Storage Modes

vwarden ships as a standalone native binary (dist/bin/windows/vwarden.exe, dist/bin/linux/vwarden, dist/bin/macos/vwarden) requiring zero external runtime VMs or C shared libraries beyond standard OS networking.

Storage Backend Command Invocation Recommended Operational Use Case
Built-In Sharded MVCC (vprevail) vwarden serve 8443 vprevail Default recommended appliance mode. Persists all directory objects, policies, SCIM schemas, workflows, JIT grants, signing keys, and SIEM state across 64 Copy-on-Write MVCC shards backed by CRC32-verified binary WAL segments and LZ4 snapshots, with native peer-to-peer WAL delta replication.
Embedded SQLite WAL (sqlite) vwarden serve 8443 sqlite Single-node relational persistence using SQLite in Write-Ahead Logging mode (busy_timeout=5000) paired with in-memory MVCC for high-frequency ephemeral tokens and rate-limit buckets.
PostgreSQL Cluster (postgres) vwarden serve 8443 postgres Shared external PostgreSQL cluster configured via VWARDEN_PG_HOST, VWARDEN_PG_PORT, VWARDEN_PG_USER, VWARDEN_PG_PASSWORD, and VWARDEN_PG_DBNAME.

2. Cryptographic Vault & Production Secrets Management

Sensitive secrets—including user TOTP seeds, Ed25519 OIDC signing private keys, VGate vnet_tok_ mesh leases, and SIEM signing keys—are encrypted at rest inside ENC[vw1:<hex>] envelopes using NIST SP 800-38D AES-256-GCM with per-record Associated Authenticated Data (AAD).

BASH
# Generate and export production cryptographic secrets
export VWARDEN_MASTER_KEY_HEX="$(openssl rand -hex 32)"
export VGATE_MESH_SECRET="$(openssl rand -hex 32)"
export VWARDEN_PEP_TOKEN="$(openssl rand -hex 32)"

Bootstrap Realm Configuration (config/vwarden_bootstrap.json)

On initial startup against an empty data directory, vwarden reads config/vwarden_bootstrap.json to seed the initial tenant realm and global administrator account. Rotate the bootstrap administrator password immediately upon first sign-in and enroll TOTP MFA.


3. Delegated Org-Unit Administration (/ui/delegated)

Delegated Org-Admin Workspace

Large enterprises can delegate day-to-day user management and JIT approvals to regional or divisional leads (delegated_admin role) without granting global administrative privileges:

  • Subtree Confinement: Delegated administrators manage users, groups, and workflows strictly within Organizational Units where their user_id is listed in delegated_admins (plus child OrgUnits).
  • Mandatory Separation-of-Duties Guardrails: Built-in high-priority deny rules (pol-00-deny-delegated-self-approve and pol-00-deny-delegated-admin-escalation) are immutable:
  • A delegated administrator cannot approve their own workflow request (is_self).
  • A delegated administrator cannot assign the admin role or modify global admin accounts.

4. Global Policy Governance & Live PDP Simulation (/ui/admin)

Access Policy Topology & Live PDP Simulator

Open 4. Access Policies & Topology in /ui/admin to author and test Zero-Trust PDP access policies combining RBAC, ABAC, Organizational Graph relations, and JIT lease checks:

  1. Interactive Topology Map: Click any role, policy rule, or protected resource node on the vector canvas to inspect or edit bindings.
  2. Conjunctive Policy Rules: Combine priority ordering (1 highest), permit / deny effects, URN wildcard patterns (urn:vwarden:infra:prod-*), action sets (pam:ssh,k8s:exec), graph relations (is_self, is_manager_of_target, is_delegated_admin_of_org, has_active_jit_grant), MFA/VNet step-up flags, and X-Vwarden-* obligation headers.
  3. Live PDP Simulator: Select any subject, action, resource URN, and session assurance state to run POST /access/v1/evaluate and inspect the exact matched rule, obligations, and denial advice (request_workflow_approval) before rolling rules out to production gateways.

5. SCIM 2.0 Lifecycle, Federation & Immediate Kill-Switch

  • SCIM 2.0 Provisioning (/scim/v2/Users, /scim/v2/Groups, /scim/v2/Schemas):
  • Register custom enterprise schema extensions in 2. Users & SCIM 2.0.
  • Execute SCIM Deprovision / Kill-Switch (POST /api/v1/scim/deprovision) when an employee separates or a credential compromise is suspected: vwarden atomically sets is_active = false, purges active sessions, revokes refresh tokens, and terminates all active VGateTagGrant infrastructure leases.
  • Corporate Active Directory / LDAPv3 & SAML 2.0 (5. Federation & OAuth Clients):
  • Test RFC 4511 ASN.1 BER bind credentials and RFC 4515 filter escaping via Test LDAPv3 BER Bind, and synchronize AD entries into scoped OrgUnits.
  • Issue and verify signed SAML 2.0 assertions hardened against XXE, XML comment injection, XML Signature Wrapping (XSW-1..8), and assertion replay.

6. Cluster Replication, Backups & Non-Repudiable SIEM (/ui/admin)

Clustered vprevail Topology & Ed25519 SIEM Audit Ledger

Open 6. Clustered vprevail & SIEM Audit to operate multi-node high availability and cryptographic audit verification:

  • WAL Offset Replication & Subgraph Migration:
  • Register voter replica peers, monitor per-peer WAL byte lag and shard ranges (0..31, 32..63), trigger Sync WAL Delta Across All Peers (POST /api/v1/cluster/sync), or migrate tenant subgraphs (POST /api/v1/cluster/transfer).
  • Backup & Restore Procedure:
  1. Trigger a cluster sync/checkpoint to flush an LZ4 .snap snapshot alongside active .wal segments under data/prevail/.
  2. Copy data/prevail/ and logs/ to encrypted backup storage (secrets inside remain sealed under ENC[vw1:...]).
  3. To restore, place data/prevail/ on the replacement host, supply VWARDEN_MASTER_KEY_HEX, and start vwarden serve.
    • Non-Repudiable SIEM Ledger Verification & Optional vsight Streaming:
    • Every authentication, MFA challenge, policy change, workflow resolution, and SCIM event is chained with rolling SHA-256 (prev_hash -> chain_hash) and signed with Ed25519, formatted as RFC 5424 [vward@5424 ...] structured data.
    • Decoupled SIEM Integration: Stream events over UDP/TCP syslog (127.0.0.1:5514) or optionally configure an async HTTP collector URL (http_ingest_url / VWARDEN_SIEM_HTTP_URL, e.g. vsight's /api/v1/telemetry/ingest-raw) with a Bearer token (http_auth_token / VWARDEN_SIEM_HTTP_TOKEN). If the target SIEM is offline or unconfigured, vwarden continues operating without blocking.
    • Click Verify SHA-256 Chain & Ed25519 Signatures (GET /api/v1/siem/verify) to validate tamper-evidence, or Rotate & Seal Audit Log (.seal) (POST /api/v1/siem/rotate) for archival compliance.

vwarden — Operations, Use Cases & Examples

vwarden — Unified Identity, Federation & Access Policy Engine

1. Operational Use Cases Overview

vwarden unifies five enterprise identity workloads that traditionally require separate identity servers, privileged access brokers, and policy engines:

  1. Zero-Trust Edge Identity-Aware Proxy (IAP) with vgate: Authenticate external engineers via OAuth 2.1 Authorization Code + PKCE (S256) + Two-Step TOTP MFA before forwarding requests to internal web portals.
  2. Just-In-Time (JIT) Privileged Infrastructure Access: Enforce Zero Standing Privilege on production SSH bastions and PostgreSQL clusters using manager-approved, auto-expiring VGateTagGrant mesh leases.
  3. Externalized Policy Decision Point (PDP) for Microservices: Offload real-time RBAC + ABAC + Organizational Graph authorization checks to POST /access/v1/evaluate.
  4. Automated HR-to-Cloud Provisioning & Instant Kill-Switch (SCIM 2.0): Provision multi-profile users from corporate HR/AD systems and atomically revoke sessions, tokens, and infrastructure leases upon separation.
  5. High-Assurance Multi-Region Identity Clustering & SIEM Compliance: Replicate sharded WAL deltas across regional replicas while streaming Ed25519-signed RFC 5424 audit trails to vsight or enterprise SIEM platforms.

2. Example 1 — OAuth 2.1 Authorization Code + PKCE (S256) Token Exchange

Relying Parties (vgate, vft, vsite, or custom web/CLI apps) authenticate principals without exposing raw credentials using RFC 7636 PKCE S256:

BASH
# 1. Generate a cryptographic PKCE code_verifier and S256 code_challenge
CODE_VERIFIER="dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
CODE_CHALLENGE="E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"

# 2. Request a single-use authorization code bound to the S256 challenge and OIDC nonce
curl -sS -X POST "http://127.0.0.1:8443/oauth2/authorize" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_slug": "acme",
    "client_id": "vgate-edge-iap",
    "redirect_uri": "https://portal.acme.example.com/oauth2/callback",
    "scope": "openid profile email groups offline_access",
    "state": "csrf-state-9812",
    "nonce": "oidc-nonce-4410",
    "code_challenge": "'"$CODE_CHALLENGE"'",
    "code_challenge_method": "S256",
    "username": "marcus.lind",
    "password": "ChangeMeInProd#2026"
  }'

# 3. Exchange the single-use authorization code + code_verifier for EdDSA JWTs
curl -sS -X POST "http://127.0.0.1:8443/oauth2/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "<AUTH_CODE_FROM_STEP_2>",
    "redirect_uri": "https://portal.acme.example.com/oauth2/callback",
    "client_id": "vgate-edge-iap",
    "client_secret": "<CLIENT_SECRET>",
    "code_verifier": "'"$CODE_VERIFIER"'"
  }'

# 4. Introspect or revoke an issued EdDSA access token
curl -sS -X POST "http://127.0.0.1:8443/oauth2/introspect" \
  -H "Content-Type: application/json" \
  -d '{"token": "<ACCESS_TOKEN>"}'

3. Example 2 — Real-Time Policy Decision Point (POST /access/v1/evaluate)

Edge gateways (vgate, vsite) and internal microservices query vwarden to evaluate conjunctive RBAC, ABAC, Org-Graph, MFA, and JIT lease policies in sub-millisecond latency:

Access Policy Evaluation & Live Simulator

BASH
curl -sS -X POST "http://127.0.0.1:8443/access/v1/evaluate" \
  -H "Content-Type: application/json" \
  -H "X-Vwarden-PEP-Token: $VWARDEN_PEP_TOKEN" \
  -d '{
    "tenant_slug": "acme",
    "subject_user_id": "usr_marcus_dev",
    "action": "pam:ssh",
    "resource": "urn:vwarden:infra:prod-eu-k8s-01",
    "target_org_id": "org_emea_eng",
    "mfa_verified": true,
    "vnet_verified": true
  }'

Example Response (When No Active JIT Lease Exists):

JSON
{
  "permitted": false,
  "effect": "deny",
  "matched_rule_id": "pol-02-prod-bastion-jit",
  "matched_rule_name": "Production Bastion & Kubernetes JIT Access",
  "advice": "request_workflow_approval",
  "workflow_template_id": "wf-jit-manager-approval",
  "explanation": "Denied: rule requires active JIT workflow grant (has_active_jit_grant) on urn:vwarden:infra:prod-eu-k8s-01"
}

4. Example 3 — End-to-End Just-In-Time (JIT) Bastion Approval & Early Revocation

JIT Access Request & Active VGate Leases

BASH
# 1. Engineer submits a 30-minute SSH JIT request via reflexive self-service API
curl -sS -X POST "http://127.0.0.1:8443/api/v1/self/workflows" \
  -H "Authorization: Bearer $ENGINEER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "wf-jit-manager-approval",
    "target_resource": "urn:vwarden:infra:prod-eu-k8s-01",
    "target_action": "pam:ssh",
    "grant_duration_sec": 1800,
    "reason": "INC-5104: Inspect EU payment worker socket saturation"
  }'

# 2. EMEA Delegated Admin approves the workflow, minting a signed vnet_tok_ lease
curl -sS -X POST "http://127.0.0.1:8443/api/v1/workflows/resolve" \
  -H "Authorization: Bearer $DELEGATED_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "<WORKFLOW_ID>",
    "approved": true,
    "comment": "Approved for 30m incident window INC-5104"
  }'

# 3. Engineer revokes their own lease early once remediation finishes
curl -sS -X POST "http://127.0.0.1:8443/api/v1/self/vgate/revoke" \
  -H "Authorization: Bearer $ENGINEER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"grant_id": "<VGATE_GRANT_ID>"}'

5. Example 4 — SCIM 2.0 Provisioning & Instant Employee Offboarding

BASH
# List provisioned SCIM 2.0 enterprise users
curl -sS -H "Authorization: Bearer $ADMIN_TOKEN" \
  "http://127.0.0.1:8443/scim/v2/Users"

# Trigger atomic offboarding kill-switch (disables user, purges sessions, revokes JIT grants)
curl -sS -X POST "http://127.0.0.1:8443/api/v1/scim/deprovision" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_marcus_dev",
    "reason": "HR-OFFBOARD-2026-091: Contract completion"
  }'

6. Example 5 — Programmable Zero-Trust Policies via vvm WebAssembly 3.0 (vwarden-wasm)

When running the vwarden-wasm build (-d vvm), administrators and platform teams can evaluate custom WebAssembly 3.0 (.wat or .wasm) policy predicates and claim mappers inside a zero-I/O, fuel-metered sandbox (POST /api/v1/policies/wasm/eval).

6.1 Real-Life Example A: Geo-Velocity & Risk-Score MFA Gate

Allow low-risk logins (risk <= 40) directly, require MFA for medium-risk logins (41..75), and deny high-risk logins (> 75):

BASH
curl -sS -X POST "http://127.0.0.1:8443/api/v1/policies/wasm/eval" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "export_fn": "evaluate",
    "args_csv": "65,1",
    "max_fuel": 50000,
    "wat_source": "(module (func (export \"evaluate\") (param $risk i64) (param $mfa i64) (result i64) (if (result i64) (i64.le_s (local.get $risk) (i64.const 40)) (then (i64.const 1)) (else (if (result i64) (i32.and (i64.le_s (local.get $risk) (i64.const 75)) (i64.eq (local.get $mfa) (i64.const 1))) (then (i64.const 1)) (else (i64.const 0)))))))"
  }'

6.2 Real-Life Example B: Production Maintenance-Window Gate

Restrict production deployments to 08:00–18:00 UTC unless an approved break-glass flag (1) is active:

BASH
curl -sS -X POST "http://127.0.0.1:8443/api/v1/policies/wasm/eval" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "export_fn": "check_window",
    "args_csv": "22,0",
    "max_fuel": 50000,
    "wat_source": "(module (func (export \"check_window\") (param $hour i64) (param $bg i64) (result i64) (if (result i64) (i64.eq (local.get $bg) (i64.const 1)) (then (i64.const 1)) (else (if (result i64) (i32.and (i64.ge_s (local.get $hour) (i64.const 8)) (i64.le_s (local.get $hour) (i64.const 18))) (then (i64.const 1)) (else (i64.const 0)))))))"
  }'

6.3 Real-Life Example C: Custom OIDC / SAML Clearance-Tier Mapper

Compute a dynamic clearance_tier (3 = Top Secret, 2 = Confidential, 1 = Standard) from department code (9 = Security) and tenure years:

BASH
curl -sS -X POST "http://127.0.0.1:8443/api/v1/policies/wasm/eval" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "export_fn": "map_clearance",
    "args_csv": "9,5",
    "max_fuel": 50000,
    "wat_source": "(module (func (export \"map_clearance\") (param $dept i64) (param $tenure i64) (result i64) (if (result i64) (i32.and (i64.eq (local.get $dept) (i64.const 9)) (i64.ge_s (local.get $tenure) (i64.const 3))) (then (i64.const 3)) (else (if (result i64) (i64.ge_s (local.get $tenure) (i64.const 1)) (then (i64.const 2)) (else (i64.const 1)))))))"
  }'

6.4 Fuel-Metered Infinite-Loop Protection

Every Wasm plugin runs with an explicit instruction budget (max_fuel, default 50,000). If a buggy or malicious module enters an infinite loop, vwarden-wasm traps immediately once max_fuel is exhausted and returns HTTP 400 without impacting other tenants or worker threads.


7. Day-2 Operations Runbook Checklist

Operational Task Cadence Verification Endpoint / CLI
Verify SIEM Hash Chain & Ed25519 Signatures Hourly / Automated GET /api/v1/siem/verify
Rotate & Seal SIEM Audit Segment (.seal) Daily POST /api/v1/siem/rotate
Sweep Expired JIT Workflows & Ephemeral Leases Every 60 seconds POST /api/v1/workflows/tick (plus automatic runtime sweep)
Verify Replica WAL Lag Across Cluster Peers Continuous GET /api/v1/overview -> cluster.peers[].lag_entries == 0
Rotate Tenant Ed25519 OIDC Signing Key Every 90 days Publish new kid with overlap in GET /.well-known/jwks.json

vwarden — Configuration & CLI Reference

vwarden — Unified Identity, Federation & Access Policy Engine

1. Command-Line Interface (vwarden) Reference

TEXT
Usage: vwarden <command> [options]
Subcommand Arguments & Flags Audience Description
serve (start) [port] [backend] [--host <ip>] [--issuer <url>] [--tls-cert <pem>] [--tls-key <pem>] [--pep-token <tok>] [--demo] Administrators & Operators Starts the HTTP/1.1 or standalone TLS 1.2+ identity server and role-separated Web Studio (127.0.0.1:8443 and vprevail by default; production-safe unless --demo is set).
version (-v, --version) None All Users Prints the semantic version of the vwarden binary.
discovery [issuer_url] Developers & Integrators Emits the complete RFC 8414 / OpenID Connect 1.0 /.well-known/openid-configuration JSON document for issuer_url (defaults to https://127.0.0.1:8443).
openapi [issuer_url] Developers & Integrators Emits the complete OpenAPI 3.1.0 JSON specification for all authentication, self-service, federation, policy, and governance endpoints.
verify-id <identifier> Operators Validates a tenant slug, client ID, or resource identifier against the strict [a-zA-Z0-9_-]{1,64} whitelist.
help (-h, --help) None All Users Prints the CLI command and flag summary.

vwarden serve Flag Details

Flag Default Environment Variable Fallback Description
[port] / --port <n> 8443 — TCP port for the API and Web Studio listener.
[backend] / --backend <name> vprevail — Directory persistence backend: vprevail (64-shard MVCC + WAL), sqlite (SQLite WAL), or postgres (PostgreSQL).
--host <ip> 127.0.0.1 — Network interface bind address (127.0.0.1 for loopback behind vgate, 0.0.0.0 for direct ingress).
--issuer <url> http(s)://<host>:<port> VWARDEN_ISSUER_URL Public OIDC/SAML/WebAuthn issuer URL (required when running behind a reverse proxy such as vgate or nginx).
--tls-cert <path> Empty (HTTP) VWARDEN_TLS_CERT PEM certificate chain path enabling standalone TLS 1.2+ HTTPS termination, HSTS, and Secure cookies.
--tls-key <path> Empty (HTTP) VWARDEN_TLS_KEY PEM private key path paired with --tls-cert.
--pep-token <secret> Empty VWARDEN_PEP_TOKEN Shared bearer token verified via X-Vwarden-PEP-Token for remote Policy Enforcement Point callers of POST /access/v1/evaluate.
--demo false VWARDEN_DEMO_MODE Opt-in local demo mode seeding sample users/clients and enabling /api/v1/auth/pkce-demo (disabled by default in production).

2. Environment Variables Reference

Environment Variable Required in Production Purpose
VWARDEN_MASTER_KEY_HEX Yes 64-character hex (32-byte) master key for the AES-256-GCM cryptographic vault sealing TOTP seeds, Ed25519 keys, JIT vnet_tok_ grants, and SIEM keys.
VWARDEN_ISSUER_URL Yes (behind proxy) Public HTTPS origin advertised in OIDC Discovery, JWT iss, SAML EntityID, and WebAuthn rpId.
VWARDEN_BOOTSTRAP_ADMIN_PASSWORD Recommended (first boot) Initial global admin password on first boot; if omitted in production mode, a one-time CSPRNG password is generated and logged to stderr.
VWARDEN_DEMO_MODE No (false default) Set to 1 / true only in local evaluation environments to seed sample users and enable /api/v1/auth/pkce-demo.
VGATE_MESH_SECRET Yes (when using VGate JIT) Shared HMAC-SHA256 secret used to sign time-bounded vnet_tok_ mesh leases consumed by vgate.
VWARDEN_PEP_TOKEN Recommended Shared secret authenticating remote gateways invoking POST /access/v1/evaluate.
VWARDEN_TLS_CERT Optional PEM certificate chain path for standalone HTTPS termination.
VWARDEN_TLS_KEY Optional PEM private key path for standalone HTTPS termination.
VWARDEN_PG_HOST Only when --backend postgres PostgreSQL server hostname or IP address (127.0.0.1 default).
VWARDEN_PG_PORT Only when --backend postgres PostgreSQL TCP port (5432 default).
VWARDEN_PG_USER Only when --backend postgres PostgreSQL authentication role.
VWARDEN_PG_PASSWORD Only when --backend postgres PostgreSQL role password.
VWARDEN_PG_DBNAME Only when --backend postgres PostgreSQL target database name (vwarden default).

3. Bootstrap Configuration File (config/vwarden_bootstrap.json)

When starting with an empty data directory, vwarden loads config/vwarden_bootstrap.json to initialize the default tenant realm and global administrator account:

JSON
{
  "tenant_slug": "acme",
  "tenant_display_name": "Acme Global Cloud Corp",
  "bootstrap_admin_user_id": "usr_admin",
  "bootstrap_admin_username": "admin",
  "bootstrap_admin_password": "ReplaceWithStrongInitialPassword#2026!",
  "bootstrap_admin_email": "admin@acme.example.com",
  "bootstrap_admin_display_name": "System Administrator",
  "bootstrap_admin_org_id": "org_root",
  "bootstrap_admin_role": "admin",
  "bootstrap_admin_groups": "platform-admins,secops,sre-prod",
  "bootstrap_admin_entitlements": "iam:admin,pdp:write,pam:bastion,scim:admin,cluster:admin,workflow:approve"
}

4. HTTP Protocol, Self-Service & Governance Endpoints

4.1 OpenID Connect 1.0, OAuth 2.1, SAML 2.0, SCIM 2.0 & PDP Endpoints

Method & Path Access Control Specification
GET /.well-known/openid-configuration Public RFC 8414 / OIDC 1.0 Discovery metadata.
GET /.well-known/jwks.json Public RFC 7517 / RFC 8037 Ed25519 JSON Web Key Set (EdDSA).
POST /oauth2/authorize Rate-Limited Public OAuth 2.1 Authorization Code + mandatory S256 PKCE challenge endpoint.
POST /oauth2/token Client Auth / PKCE Single-use authorization code exchange and rotating refresh token grant.
GET|POST /oauth2/userinfo Bearer JWT OIDC 1.0 UserInfo claims (sub, email, name, groups_csv, primary_role, tenant_slug).
POST /oauth2/introspect Authenticated RFC 7662 token introspection verifying signature, exp, JTI revocation, and active user status.
POST /oauth2/revoke Authenticated RFC 7009 token revocation writing immediate JTI tombstones or deleting opaque refresh tokens.
GET /saml/v2/metadata Public SAML 2.0 Identity Provider XML metadata.
POST /api/v1/saml/issue & /verify Admin SAML 2.0 signed XML assertion issuance and XSW-1..8 / XXE / replay-guarded verification.
GET|POST /scim/v2/Users Admin / Delegated RFC 7643 / 7644 multi-profile SCIM 2.0 user provisioning and directory query.
GET /scim/v2/Groups Admin / Delegated RFC 7643 / 7644 SCIM 2.0 IdentityGroup listing.
GET|POST /scim/v2/Schemas Public GET / Admin POST Built-in and custom tenant SCIM 2.0 schema extension registry.
POST /access/v1/evaluate Bearer / PEP Token / Loopback Zero-Trust Policy Decision Point evaluation returning permit/deny, obligations, and workflow advice.

4.2 Auth Gate, Reflexive Self-Service (/api/v1/self/*) & Admin Studio Endpoints

Method & Path Access Control Specification
POST /api/v1/auth/login Rate-Limited Public Primary Argon2id credential check; returns session or mfa_required + mfa_challenge_token.
POST /api/v1/auth/mfa/verify Rate-Limited Public Verifies single-use mfa_challenge_token + 6-digit RFC 6238 TOTP code with 30s replay guard.
POST /api/v1/auth/register-onboarding Rate-Limited Public Stages a non-privileged OnboardingRequest and launches wf-user-onboarding.
GET /api/v1/auth/session & POST /api/v1/auth/logout Authenticated Session introspection and immediate server-side + cookie logout.
GET /api/v1/self Self-Service (is_self) Caller's own profile, SCIM 2.0 JSON, submitted workflows, and active VGateTagGrant leases.
POST /api/v1/self/profile Self-Service (is_self) Updates personal non-privileged profile attributes.
POST /api/v1/self/password Self-Service (is_self) Verifies current_password and rotates the caller's Argon2id password hash.
POST /api/v1/self/mfa/enroll & /confirm Self-Service (is_self) Stages AES-256-GCM sealed TOTP secret + local SVG QR, and activates MFA upon 6-digit confirmation.
POST /api/v1/self/workflows Self-Service (is_self) Submits a JIT access workflow bound reflexively to the authenticated caller.
POST /api/v1/self/vgate/revoke Self-Service (is_self) Early-revokes an active VGateTagGrant owned by the caller.
GET /api/v1/openapi.json Public OpenAPI 3.1.0 machine-readable schema document.
GET /ui/auth, /ui/portal, /ui/delegated, /ui/admin, /ui/device Role-Separated UI Web Studio workspaces for Sign-In/Onboarding, End Users, Delegated Org-Admins, Global Admins, and RFC 8628 Device Verification.
POST /oauth2/device_authorization OIDC & OAuth 2.1 Initiate RFC 8628 Device Authorization Grant (device_code + user_code).
POST /api/v1/oauth/device/verify OIDC & OAuth 2.1 Approve or deny a pending RFC 8628 user_code as an authenticated user.
POST /api/v1/auth/webauthn/register/{begin,finish} WebAuthn / FIDO2 Register a FIDO2 Passkey (ES256 P-256 or EdDSA Ed25519) for the signed-in user.
POST /api/v1/auth/webauthn/login/{begin,finish} WebAuthn / FIDO2 Passwordless / MFA Passkey assertion ceremony returning an HttpOnly session cookie.
POST /api/v1/auth/webauthn/delete WebAuthn / FIDO2 Remove a registered Passkey owned by the current user.
GET / POST /api/v1/policies/wasm Global Admin (pdp:write) List or persist named WebAssembly 3.0 Zero-Trust PDP plugins referenced via condition_expr: "wasm:<plugin_id>".
POST /api/v1/policies/wasm/delete Global Admin (pdp:write) Remove a persisted WebAssembly 3.0 policy plugin by plugin_id.
POST /api/v1/policies/wasm/eval Bearer / PEP Token / Loopback Evaluate a .wat or .wasm policy/claim plugin inside the fuel-metered vvm sandbox (vwarden-wasm build).

Optional SIEM Environment Variables

  • VWARDEN_SIEM_HTTP_URL: Optional HTTP/HTTPS SIEM ingest URL (e.g. http://127.0.0.1:8080/api/v1/telemetry/ingest-raw for vsight). Leave unset to disable HTTP streaming.
  • VWARDEN_SIEM_HTTP_TOKEN: Optional Bearer token sent in Authorization: Bearer <token> when VWARDEN_SIEM_HTTP_URL is configured.

vwarden — Performance & Capacity Guide

vwarden — Unified Identity, Federation & Access Policy Engine

1. Performance Design Principles

Identity and policy engines sit directly on the critical path of user sign-ins, microservice token verifications, and zero-trust proxy evaluations. vwarden achieves predictable low tail latency and minimal memory footprint through four architectural choices:

  1. Zero-GC-Pause Native Execution: Compiled directly to native x86_64/ARM64 machine code with deterministic value layouts and bounded socket buffers (16 KiB header cap, 1 MiB body cap).
  2. 64-Shard Copy-on-Write MVCC State Engine: Hot reads (GET /.well-known/jwks.json, POST /oauth2/introspect, POST /access/v1/evaluate, GET /api/v1/auth/session) execute against lock-free Copy-on-Write snapshots partitioned across 64 shards with {tenant} hash-tag co-location.
  3. Intentionally Asymmetric Cryptography:
    • Primary Password Login (Argon2id, 19 MiB, t=2, p=1) is intentionally memory-hard (~25–45 ms per login) to defeat GPU/ASIC offline cracking while bounded by per-IP rate limiting and connection semaphores.
    • Downstream Token & Policy Verification (Ed25519 / SHA-256 / MVCC) runs in microseconds to sub-millisecond latency so authenticated traffic scales to tens of thousands of requests per second.
  4. Sequential CRC32 Binary WAL + LZ4 Checkpoints: Mutations append compact 32-byte framed records sequentially to segmented .wal files (64 MiB segment threshold) with 24-byte sparse .idx indexes and LZ4-compressed .snap checkpoints for rapid cold-start recovery.

2. Measured Operation Latency & Throughput Profile

Representative single-node production (-prod) measurements on an 8-vCPU / 16 GiB x86_64 host (vprevail sharded MVCC backend over loopback HTTP/1.1):

Operation / Endpoint Dominant Work Median Latency (p50) Tail Latency (p99) Single-Node Sustained Throughput
OIDC Discovery & JWKS (GET /.well-known/*) In-memory read + socket frame 0.14 ms 0.48 ms > 28,000 req/s
ZERO-TRUST PDP Evaluation (POST /access/v1/evaluate) 64-shard MVCC lookup + RBAC/ABAC/Org-Graph eval 0.26 ms 0.85 ms > 16,500 evals/s
JWT Introspection (POST /oauth2/introspect) Ed25519 verify + JTI tombstone MVCC check 0.31 ms 0.95 ms > 13,000 req/s
OAuth 2.1 PKCE Token Exchange (POST /oauth2/token) Atomic WAL consume + SHA-256 PKCE + Ed25519 sign 0.78 ms 2.10 ms ~ 4,800 exchanges/s
Primary Password Login (POST /api/v1/auth/login) Memory-hard Argon2id (19 MiB, t=2, p=1) + WAL 31.0 ms 54.0 ms ~ 210 logins/s (CPU/RAM-bound by design)
Two-Step TOTP Verify (POST /api/v1/auth/mfa/verify) AES-256-GCM unseal + RFC 6238 HMAC + replay WAL 0.62 ms 1.75 ms ~ 5,400 verifications/s
Local ISO 18004 QR Enrollment (POST /api/v1/self/mfa/enroll) AES-256-GCM seal + GF(256) Reed-Solomon SVG render 0.85 ms 2.20 ms ~ 4,200 enrollments/s
Signed SIEM Audit Append + Chain Link SHA-256 chain + Ed25519 sign + append 0.29 ms 0.90 ms > 11,000 events/s

3. Capacity Planning & Hardware Sizing Guide

Deployment Tier Directory Scale Peak Login Concurrency Recommended Compute & Memory Storage & Topology
Small / Team Appliance Up to 2,500 users, 25 OAuth/SAML apps <= 25 logins/sec, 1,500 PDP evals/sec 2 vCPU, 2 GiB RAM Single node (vprevail or sqlite) on NVMe SSD (10 GiB) behind vgate.
Mid-Market Enterprise 2,500 – 50,000 users, 150 apps, multi-OrgUnit <= 100 logins/sec, 10,000 PDP evals/sec 4–8 vCPU, 8 GiB RAM Primary + 1 Voter Replica (vprevail WAL sync) on NVMe SSD (50 GiB).
Global High-Availability 50,000 – 500,000+ users, multi-region tenants 200+ logins/sec, 30,000+ PDP evals/sec 16+ vCPU, 32 GiB RAM per node 3-node regional cluster (0..31 / 32..63 shard affinity) + dedicated SIEM shipping.

4. Production Tuning Recommendations

  1. Right-Size Concurrent Argon2id Headroom:
    • Each concurrent Argon2id verification allocates a 19 MiB memory arena for ~30 ms. With the default 256 socket concurrency cap and per-IP login rate limiting, worst-case simultaneous password hashing stays comfortably bounded; ensure at least 2 GiB free RAM on nodes handling heavy Monday-morning sign-in bursts.
  2. Prefer Offline JWKS Verification at the Edge:
    • Configure vgate, vft, and vsite to cache GET /.well-known/jwks.json and verify EdDSA access tokens locally on every request, reserving POST /oauth2/introspect and POST /access/v1/evaluate for step-up privileged actions and instant JTI revocation checks.
  3. Keep data/prevail/ on Local NVMe Storage:
    • Binary WAL segment appends and .snap LZ4 checkpoints benefit from low-latency NVMe fsync; avoid network-mounted NFS/SMB shares for active WAL directories.
  4. Periodic SIEM Log Rotation (.seal):
    • Schedule daily POST /api/v1/siem/rotate calls so active SIEM ledger verification (GET /api/v1/siem/verify) scans bounded daily segments while archiving cryptographically sealed .seal files to cold storage.

vwarden — Consolidated End-User, Administrator & Operations Handbook

vwarden — Unified Identity, Federation & Access Policy Engine


Part I: vwarden — Unified Identity, Federation & Access Policy Engine

Overview

vwarden is a self-contained, zero-external-dependency OpenID Connect (OIDC) 1.0, OAuth 2.1, SAML 2.0, SCIM 2.0, Access Policy Decision Point (PDP), and LDAPv3 Directory Bridge. Distributed as a single native executable for Windows, Linux, and macOS, vwarden serves as the central identity and authorization authority for both End Users and System Administrators.

IDENTITY TOPOLOGY

vwarden End-to-End OpenID Connect 1.0, OAuth 2.1, SAML 2.0 & SCIM 2.0 Architecture

Click any component node to inspect how vwarden authenticates principals, mints signed tokens, and governs policies.

Interactive SVG • Click any node (6 components)
1. RELYING PARTIES & PRINCIPALS Browser / CLI / Ecosystem Services 2. IDENTITY & POLICY CORE OIDC + SAML + SCIM + ZERO-TRUST PDP 3. PERSISTENCE & CRYPTO VAULT Sharded MVCC / SQLite / Postgres OIDC + PKCE MFA / SCIM Verify Enforce Sealed I/O Federation Clients Relying Parties (RP) vgate, vft, vsite, vstore, vsight Principals Operators & End Users Self-Service Portal & Admin Studio Protocol Core OIDC & OAuth 2.1 Engine Discovery, PKCE, Token & JWKS Identity Engine MFA, SAML 2.0 & SCIM 2.0 Argon2id, Two-Step TOTP & SCIM Security Boundary Zero-Trust Policy Guard ZERO-TRUST PDP + Rate Limiter Persistence SecretVault & Sharded MVCC AES-256-GCM + 64-Shard WAL
Components:
Federation Clients
Relying Parties (RP)
Relying Party Federation Boundary
Component 1 of 6
Architectural Role & Purpose

Applications, gateways, and CLI services that delegate authentication and policy evaluation to vwarden.

Contextual Description & System Interaction

Forms the Relying Party boundary across vgate IAP, vft file transfer, vsite, vstore, varc, vca, and vsight.

Core Functionality & Security Mechanics
  • Initiates OAuth 2.1 Authorization Code + PKCE (S256) flows
  • Verifies signed EdDSA ID Tokens and Access Tokens via JWKS endpoint
  • Consumes SCIM 2.0 user and group lifecycle provisioning events
Principals
Operators & End Users
Role-Separated Web Studio
Component 2 of 6
Architectural Role & Purpose

Human end users managing credentials/MFA and operators governing tenants, OrgUnits, and policies.

Contextual Description & System Interaction

Supports both reflexive self-service SSO (/ui/portal) and scoped or global governance (/ui/delegated, /ui/admin).

Core Functionality & Security Mechanics
  • Enrolls RFC 6238 TOTP MFA via offline ISO 18004 SVG QR codes
  • Governs tenants, OAuth clients, signing key rotation, and Zero-Trust PDP policies
  • Inspects real-time Ed25519-signed RFC 5424 security audit trails
Protocol Core
OIDC & OAuth 2.1 Engine
OIDC 1.0 OAuth 2.1 PKCE Engine
Component 3 of 6
Architectural Role & Purpose

Implements RFC 8414 Discovery, OAuth 2.1 PKCE authorization, token exchange, JTI revocation, and JWKS publication.

Contextual Description & System Interaction

Eliminates implicit flow vulnerabilities and token replay by enforcing OAuth 2.1 and OpenID Connect 1.0 Core invariants.

Core Functionality & Security Mechanics
  • Serves /.well-known/openid-configuration and /.well-known/jwks.json
  • Enforces mandatory S256 PKCE code_challenge verification and state/nonce binding
  • Mints short-lived EdDSA (Ed25519) JWTs with multi-key rotation and JTI tombstones
Identity Engine
MFA, SAML 2.0 & SCIM 2.0
Credential KDF SAML 2.0 SCIM 2.0
Component 4 of 6
Architectural Role & Purpose

Provides Argon2id credential hashing, two-step TOTP MFA, SAML 2.0 federation, and RFC 7643/7644 SCIM 2.0 provisioning.

Contextual Description & System Interaction

Bridges modern OIDC microservices and enterprise SAML/SCIM/LDAPv3 directories inside a single executable.

Core Functionality & Security Mechanics
  • Enforces two-step mfa_challenge_token login and 30-second TOTP step replay protection
  • Hashes passwords with Argon2id (19 MiB, t=2, p=1) and transparent legacy upgrade
  • Synchronizes users and groups with atomic session and JIT grant revocation on deprovisioning
Security Boundary
Zero-Trust Policy Guard
Zero-Trust Policy Engine Transport Guard
Component 5 of 6
Architectural Role & Purpose

Enforces Zero-Trust PDP RBAC/ABAC/Org-Graph policies, constant-time checks, CSRF headers, and sliding-window rate limits.

Contextual Description & System Interaction

Protects every endpoint against timing side-channels, path traversal, CSRF, XSS, and credential stuffing.

Core Functionality & Security Mechanics
  • Compares all tokens and hashes via SHA-256 length-hiding constant-time equality
  • Enforces HttpOnly; SameSite=Lax cookies, X-Vwarden-CSRF: 1, and bounded socket framing
  • Emits Ed25519-signed hash-chained RFC 5424 SIEM audit entries for every security event
Persistence
SecretVault & Sharded MVCC
AES-256-GCM Vault Sharded MVCC Store
Component 6 of 6
Architectural Role & Purpose

Seals sensitive keys with AES-256-GCM and persists state in 64-shard Copy-on-Write MVCC + binary WAL.

Contextual Description & System Interaction

Ensures that even a raw snapshot never exposes plaintext passwords, MFA seeds, or signing private keys.

Core Functionality & Security Mechanics
  • Seals TOTP secrets, Ed25519 keys, and vnet_tok_ grants via AES-256-GCM + AAD (ENC[vw1:...])
  • Persists CRC32 binary WAL segments, sparse offset indexes, and LZ4 snapshots
  • Supports sharded MVCC, SQLite WAL, and PostgreSQL persistence backends

Core Capabilities

Audience Capability Operational Value
End Users Single Sign-On (SSO) & Two-Step TOTP MFA Sign in once using Argon2id password verification and a two-step RFC 6238 6-digit TOTP verification ceremony with 30-second replay protection across connected applications (vgate, vft, vsite, vstore, vsight, varc, vca).
End Users Self-Service Identity Portal (/ui/portal) Manage personal profile attributes, rotate passwords with current-password verification, enroll authenticator apps via offline ISO/IEC 18004 vector SVG QR codes, and request or revoke Just-in-Time (JIT) access leases.
Delegated Operators Organizational Unit Workspace (/ui/delegated) Approve or reject staged onboarding requests and temporary JIT access workflows strictly within assigned Organizational Unit subtrees under separation-of-duties guardrails.
System Administrators Unified Governance & Federation (/ui/admin) Govern multi-tenant realms, RBAC/ABAC/Org-Graph policies, OAuth 2.1 PKCE clients, SAML 2.0 Service Providers, SCIM 2.0 lifecycle provisioning, Corporate Active Directory / LDAPv3 synchronization, clustered WAL replication, and Ed25519-signed SIEM audit trails.
Platform Engineers Flexible Persistence & Standalone TLS Run out of the box on the built-in 64-shard Copy-on-Write MVCC engine with CRC32-verified binary WAL and LZ4 snapshots, or connect to SQLite WAL / PostgreSQL; deploy behind vgate over loopback HTTP/1.1 or directly with built-in TLS 1.2+ (--tls-cert / --tls-key).

Live Workspace Preview

Authentication & Onboarding Gate (/ui/auth)

vwarden Sign-In & Multi-Factor Authentication Gate

End-User Self-Service Portal (/ui/portal)

vwarden End-User Self-Service Profile & Offline ISO 18004 QR MFA Enrollment


End-User Documentation Suite

  1. Overview & Readme — Product overview, core capabilities, and quickstart commands.
  2. How-To Guide — Step-by-step operational recipes for TLS deployment, MFA enrollment, OIDC client registration, and JIT access workflows.
  3. End-User Guide — Complete guide for signing in, enrolling TOTP authenticators, managing personal profiles, and requesting temporary infrastructure leases.
  4. Administrator Guide — Production installation, master key vault management, tenant/OrgUnit governance, SCIM 2.0 deprovisioning, and SIEM audit verification.
  5. Operations, Use Cases & Examples — End-to-end integration playbooks and runnable HTTP/CLI examples for OAuth 2.1 PKCE, Policy Decision Point evaluation, SCIM 2.0, SAML 2.0, and VGate PAM/JIT.
  6. Configuration & CLI Reference — Complete reference for CLI subcommands, flags, environment variables, bootstrap configuration JSON, and REST API endpoints.
  7. Performance & Capacity Guide — Throughput, latency characteristics, Argon2id sizing, sharded MVCC scaling, and hardware sizing recommendations.
  8. Consolidated User Handbook — Single-file master compendium combining all End-User, How-To, Administrator, Operations, Configuration, and Performance guides.

Quickstart

Launch vwarden locally using the prebuilt binary for your operating system (dist/bin/windows/vwarden.exe, dist/bin/linux/vwarden, or dist/bin/macos/vwarden):

BASH
# Check installed semantic version
./vwarden version

# Inspect generated OpenID Connect 1.0 discovery metadata
./vwarden discovery https://id.acme.example.com

# Start the identity server and Web Studio on 127.0.0.1:8443 using the built-in MVCC store
./vwarden serve 8443 vprevail

# Start with standalone HTTPS termination
./vwarden serve 8443 vprevail --tls-cert certs/fullchain.pem --tls-key certs/privkey.pem

Once running, open http://127.0.0.1:8443/ui/auth (or https://127.0.0.1:8443/ui/auth when TLS is enabled) in your browser.


Part II: vwarden — How-To Guide

1. How to Deploy Behind vgate vs. Standalone HTTPS

System administrators can deploy vwarden in two production network topologies without changing client configurations:

When vgate terminates public ACME/TLS 1.3 traffic on port 443, bind vwarden strictly to loopback (127.0.0.1) and configure a shared Policy Enforcement Point (PEP) secret:

BASH
export VWARDEN_MASTER_KEY_HEX="0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
export VGATE_MESH_SECRET="replace-with-256-bit-random-mesh-hmac-secret"
export VWARDEN_PEP_TOKEN="replace-with-256-bit-random-pep-bearer-secret"

./vwarden serve 8443 vprevail --host 127.0.0.1 --pep-token "$VWARDEN_PEP_TOKEN"

Recipe B — Standalone Direct HTTPS Termination

When deploying vwarden directly on an internal network without an upstream proxy, supply a PEM certificate chain and private key. vwarden automatically activates Strict-Transport-Security and marks vwarden_session cookies as Secure:

BASH
./vwarden serve 8443 vprevail \
  --host 0.0.0.0 \
  --tls-cert ./certs/fullchain.pem \
  --tls-key ./certs/privkey.pem

2. How to Enroll and Confirm Two-Step TOTP Multi-Factor Authentication

vwarden uses a two-phase MFA enrollment ceremony so users never lock themselves out if a browser tab closes mid-scan.

Offline ISO 18004 QR Code MFA Enrollment in /ui/portal

  1. Sign in at /ui/auth and navigate to Self-Service (/ui/portal) -> 1. My Profile, Password & MFA QR.
  2. Click 1. Stage New TOTP QR Secret (POST /api/v1/self/mfa/enroll). vwarden seals a fresh RFC 4648 Base32 secret in the AES-256-GCM vault under a pending key and renders an ISO/IEC 18004 SVG QR code locally in your browser.
  3. Scan the QR code using any RFC 6238 authenticator app (1Password, Bitwarden, Proton Pass, Google Authenticator, or Microsoft Authenticator).
  4. Enter the live 6-digit code in the confirmation input and click 2. Confirm & Activate MFA (POST /api/v1/self/mfa/confirm).
  5. Your active session immediately upgrades to mfa_verified: true, and future sign-ins enforce the two-step challenge.

3. How to Submit and Approve a Staged User Onboarding Request

Self-service registration never writes unvetted accounts into the active directory. Instead, it launches a durable approval workflow.

Self-Service Registration & Durable Onboarding Workflow

  1. Applicant Action (/ui/auth):
    • Select the Register / Request Onboarding Workflow tab.
    • Enter desired username, full name, corporate email, password, target Organizational Unit, department, and business justification.
    • Click Submit Registration & Start Onboarding Workflow. vwarden returns a workflow ID (for example, wf_onb_...) in pending_approval state.
  2. Administrator / Delegated Admin Action (/ui/admin or /ui/delegated):
    • Sign in as an authorized administrator and open 1. Onboarding & JIT Approvals.
    • Review the applicant's requested Organizational Unit and justification.
    • Click Approve & Activate User to atomically provision the directory record and group bindings, or Reject to discard the staged request with a signed SIEM audit record.

4. How to Register an OpenID Connect 1.0 Relying Party Client

  1. Sign in to /ui/admin and open 5. Federation & OAuth Clients.
  2. Click + Register OAuth 2.1 Client and populate:
    • Client ID: Safe slug matching [a-zA-Z0-9_-]{1,64} (for example, vft-enterprise-portal).
    • Display Name: Human-readable service title.
    • Allowed Redirect URIs: Exact HTTPS callback URLs (comma-separated).
    • Allowed Scopes: openid,profile,email,groups,offline_access.
    • Require PKCE (S256): Enabled (mandatory for OAuth 2.1 security).
  3. Configure your Relying Party with the discovery URL:
TEXT
   https://id.acme.example.com/.well-known/openid-configuration

5. How to Request and Revoke Just-In-Time (JIT) Infrastructure Access

Requesting VGate JIT PAM Access in /ui/portal

  1. Open Self-Service (/ui/portal) -> 2. Request JIT Access & Active VGate Leases.
  2. Choose a service catalog template (such as VGate Prod Bastion SSH or VGate Prod PostgreSQL), select the required lease duration (15m, 30m, 1h, or 4h), and enter the incident ticket ID.
  3. Click Request VGate JIT Lease & Launch Approval Workflow.
  4. Once your Organizational Unit manager approves the request in /ui/delegated, your active vnet_tok_... subject token appears in the Active VGate PAM TagGrants table with a live expiration countdown.
  5. When maintenance concludes early, click Revoke Lease (POST /api/v1/self/vgate/revoke) to terminate the network grant immediately.

Part III: vwarden — End-User Guide

1. Welcome to vwarden Single Sign-On

vwarden is your organization's central sign-in, Multi-Factor Authentication (MFA), and access request portal. Instead of maintaining separate passwords for internal web applications, file transfer portals, observability consoles, and developer repositories, you authenticate once through vwarden to access authorized services seamlessly.


2. Signing In & Two-Step Verification (/ui/auth)

vwarden Sign-In Gate

2.1 Step 1 — Directory Password Sign-In

  1. When opening a protected application (or visiting /ui/auth directly), verify your Tenant Realm (for example, acme) and enter your Username and Password.
  2. Your password is protected using memory-hard Argon2id hashing and is never transmitted to downstream applications.
  3. If TOTP MFA is not yet enabled on your account, vwarden establishes your browser session inside an HttpOnly; SameSite=Lax cookie and routes you to /ui/portal.

2.2 Step 2 — 6-Digit Authenticator Challenge

  1. When TOTP MFA is active on your account, Step 1 displays Step 2 — RFC 6238 6-Digit TOTP Verification Code instead of creating a session immediately.
  2. Open your mobile or desktop authenticator application and enter the current 6-digit code within 5 minutes.
  3. Every 6-digit TOTP code is single-use within its 30-second window—even if an onlooker sees your code, it cannot be replayed to open a second session.
  4. Upon verification, your session carries the mfa_verified assurance claim so MFA-protected resources permit access automatically.

3. Requesting a New Account (Self-Service Onboarding)

Staged Onboarding Registration Form

If you are a new employee or contractor without an active directory account:

  1. At /ui/auth, click Register / Request Onboarding Workflow.
  2. Complete your desired username, display name, work email, password, Organizational Unit, department, and ticket or manager reference.
  3. Click Submit Registration & Start Onboarding Workflow.
  4. Your request enters a staged approval queue (pending_approval). As soon as an authorized administrator approves your onboarding workflow, your account becomes active for Single Sign-On.

4. Managing Your Identity in the Self-Service Portal (/ui/portal)

All operations in /ui/portal act strictly on your own identity (is_self reflexive scope), ensuring you can update personal preferences safely without administrative intervention.

4.1 Profile Attributes & Password Rotation

  • Edit My Profile: Click Edit My Profile in the top action bar to update your display name, email address, given/family name, department, POSIX home directory, or login shell.
  • Inspect My SCIM 2.0 JSON: View the exact standardized RFC 7643 identity payload shared with connected enterprise applications.
  • Change My Password: Click Change My Password, enter your current password and a new password, and submit. Your account immediately upgrades to a fresh Argon2id digest.

4.2 Offline QR Code MFA Enrollment

Self-Service Portal Profile & QR Code MFA Enrollment

  • Click 1. Stage New TOTP QR Secret to render a crisp vector QR code generated locally by vwarden (zero data is sent to third-party QR websites).
  • Scan the QR code in your authenticator app, type the current 6-digit code, and click 2. Confirm & Activate MFA.
  • If you refresh or close the tab before confirming, your previous MFA configuration remains intact.

4.3 Requesting Temporary JIT Infrastructure Leases

Self-Service JIT Access Request & Active Leases

Production servers and databases enforce Zero Standing Privilege—access is granted only for explicit maintenance windows:

  1. Open 2. Request JIT Access & Active VGate Leases.
  2. Select the target workflow template, lease TTL, protected resource URN, and protocol (pam:ssh, db:postgres, or k8s:exec), then provide your incident or change ticket justification.
  3. Track live approval status in My Submitted Access & Onboarding Workflow Requests.
  4. Once approved, copy your time-bounded vnet_tok_... lease from Active VGate PAM TagGrants, or click Revoke to end the session early.

4.4 Testing SSO Applications & Signing Out

  • Open 3. My SSO Applications & OAuth 2.1 PKCE to inspect OIDC Discovery metadata, JWKS public keys, and SAML 2.0 metadata, or test OAuth 2.1 PKCE token exchange and revocation.
  • Passkeys (FIDO2 / WebAuthn): Under 1. My Profile & MFA, register a hardware security key or platform passkey (ES256 or EdDSA) and use Sign In with Passkey (FIDO2) on /ui/auth for passwordless MFA sign-in.
  • Device Authorization (/ui/device): When signing in from a CLI or headless device, open /ui/device (or follow the verification link), enter the XXXX-XXXX user code, and click Approve Device.
  • Click Sign Out in the top-right header at any time to destroy your server-side session and clear your browser cookie immediately.

Part IV: vwarden — Administrator Guide

1. Deployment Architecture & Storage Modes

vwarden ships as a standalone native binary (dist/bin/windows/vwarden.exe, dist/bin/linux/vwarden, dist/bin/macos/vwarden) requiring zero external runtime VMs or C shared libraries beyond standard OS networking.

Storage Backend Command Invocation Recommended Operational Use Case
Built-In Sharded MVCC (vprevail) vwarden serve 8443 vprevail Default recommended appliance mode. Persists all directory objects, policies, SCIM schemas, workflows, JIT grants, signing keys, and SIEM state across 64 Copy-on-Write MVCC shards backed by CRC32-verified binary WAL segments and LZ4 snapshots, with native peer-to-peer WAL delta replication.
Embedded SQLite WAL (sqlite) vwarden serve 8443 sqlite Single-node relational persistence using SQLite in Write-Ahead Logging mode (busy_timeout=5000) paired with in-memory MVCC for high-frequency ephemeral tokens and rate-limit buckets.
PostgreSQL Cluster (postgres) vwarden serve 8443 postgres Shared external PostgreSQL cluster configured via VWARDEN_PG_HOST, VWARDEN_PG_PORT, VWARDEN_PG_USER, VWARDEN_PG_PASSWORD, and VWARDEN_PG_DBNAME.

2. Cryptographic Vault & Production Secrets Management

Sensitive secrets—including user TOTP seeds, Ed25519 OIDC signing private keys, VGate vnet_tok_ mesh leases, and SIEM signing keys—are encrypted at rest inside ENC[vw1:<hex>] envelopes using NIST SP 800-38D AES-256-GCM with per-record Associated Authenticated Data (AAD).

BASH
# Generate and export production cryptographic secrets
export VWARDEN_MASTER_KEY_HEX="$(openssl rand -hex 32)"
export VGATE_MESH_SECRET="$(openssl rand -hex 32)"
export VWARDEN_PEP_TOKEN="$(openssl rand -hex 32)"

Bootstrap Realm Configuration (config/vwarden_bootstrap.json)

On initial startup against an empty data directory, vwarden reads config/vwarden_bootstrap.json to seed the initial tenant realm and global administrator account. Rotate the bootstrap administrator password immediately upon first sign-in and enroll TOTP MFA.


3. Delegated Org-Unit Administration (/ui/delegated)

Delegated Org-Admin Workspace

Large enterprises can delegate day-to-day user management and JIT approvals to regional or divisional leads (delegated_admin role) without granting global administrative privileges:

  • Subtree Confinement: Delegated administrators manage users, groups, and workflows strictly within Organizational Units where their user_id is listed in delegated_admins (plus child OrgUnits).
  • Mandatory Separation-of-Duties Guardrails: Built-in high-priority deny rules (pol-00-deny-delegated-self-approve and pol-00-deny-delegated-admin-escalation) are immutable:
  • A delegated administrator cannot approve their own workflow request (is_self).
  • A delegated administrator cannot assign the admin role or modify global admin accounts.

4. Global Policy Governance & Live PDP Simulation (/ui/admin)

Access Policy Topology & Live PDP Simulator

Open 4. Access Policies & Topology in /ui/admin to author and test Zero-Trust PDP access policies combining RBAC, ABAC, Organizational Graph relations, and JIT lease checks:

  1. Interactive Topology Map: Click any role, policy rule, or protected resource node on the vector canvas to inspect or edit bindings.
  2. Conjunctive Policy Rules: Combine priority ordering (1 highest), permit / deny effects, URN wildcard patterns (urn:vwarden:infra:prod-*), action sets (pam:ssh,k8s:exec), graph relations (is_self, is_manager_of_target, is_delegated_admin_of_org, has_active_jit_grant), MFA/VNet step-up flags, and X-Vwarden-* obligation headers.
  3. Live PDP Simulator: Select any subject, action, resource URN, and session assurance state to run POST /access/v1/evaluate and inspect the exact matched rule, obligations, and denial advice (request_workflow_approval) before rolling rules out to production gateways.

5. SCIM 2.0 Lifecycle, Federation & Immediate Kill-Switch

  • SCIM 2.0 Provisioning (/scim/v2/Users, /scim/v2/Groups, /scim/v2/Schemas):
  • Register custom enterprise schema extensions in 2. Users & SCIM 2.0.
  • Execute SCIM Deprovision / Kill-Switch (POST /api/v1/scim/deprovision) when an employee separates or a credential compromise is suspected: vwarden atomically sets is_active = false, purges active sessions, revokes refresh tokens, and terminates all active VGateTagGrant infrastructure leases.
  • Corporate Active Directory / LDAPv3 & SAML 2.0 (5. Federation & OAuth Clients):
  • Test RFC 4511 ASN.1 BER bind credentials and RFC 4515 filter escaping via Test LDAPv3 BER Bind, and synchronize AD entries into scoped OrgUnits.
  • Issue and verify signed SAML 2.0 assertions hardened against XXE, XML comment injection, XML Signature Wrapping (XSW-1..8), and assertion replay.

6. Cluster Replication, Backups & Non-Repudiable SIEM (/ui/admin)

Clustered vprevail Topology & Ed25519 SIEM Audit Ledger

Open 6. Clustered vprevail & SIEM Audit to operate multi-node high availability and cryptographic audit verification:

  • WAL Offset Replication & Subgraph Migration:
  • Register voter replica peers, monitor per-peer WAL byte lag and shard ranges (0..31, 32..63), trigger Sync WAL Delta Across All Peers (POST /api/v1/cluster/sync), or migrate tenant subgraphs (POST /api/v1/cluster/transfer).
  • Backup & Restore Procedure:
  1. Trigger a cluster sync/checkpoint to flush an LZ4 .snap snapshot alongside active .wal segments under data/prevail/.
  2. Copy data/prevail/ and logs/ to encrypted backup storage (secrets inside remain sealed under ENC[vw1:...]).
  3. To restore, place data/prevail/ on the replacement host, supply VWARDEN_MASTER_KEY_HEX, and start vwarden serve.
    • Non-Repudiable SIEM Ledger Verification & Optional vsight Streaming:
    • Every authentication, MFA challenge, policy change, workflow resolution, and SCIM event is chained with rolling SHA-256 (prev_hash -> chain_hash) and signed with Ed25519, formatted as RFC 5424 [vward@5424 ...] structured data.
    • Decoupled SIEM Integration: Stream events over UDP/TCP syslog (127.0.0.1:5514) or optionally configure an async HTTP collector URL (http_ingest_url / VWARDEN_SIEM_HTTP_URL, e.g. vsight's /api/v1/telemetry/ingest-raw) with a Bearer token (http_auth_token / VWARDEN_SIEM_HTTP_TOKEN). If the target SIEM is offline or unconfigured, vwarden continues operating without blocking.
    • Click Verify SHA-256 Chain & Ed25519 Signatures (GET /api/v1/siem/verify) to validate tamper-evidence, or Rotate & Seal Audit Log (.seal) (POST /api/v1/siem/rotate) for archival compliance.

Part V: vwarden — Operations, Use Cases & Examples

1. Operational Use Cases Overview

vwarden unifies five enterprise identity workloads that traditionally require separate identity servers, privileged access brokers, and policy engines:

  1. Zero-Trust Edge Identity-Aware Proxy (IAP) with vgate: Authenticate external engineers via OAuth 2.1 Authorization Code + PKCE (S256) + Two-Step TOTP MFA before forwarding requests to internal web portals.
  2. Just-In-Time (JIT) Privileged Infrastructure Access: Enforce Zero Standing Privilege on production SSH bastions and PostgreSQL clusters using manager-approved, auto-expiring VGateTagGrant mesh leases.
  3. Externalized Policy Decision Point (PDP) for Microservices: Offload real-time RBAC + ABAC + Organizational Graph authorization checks to POST /access/v1/evaluate.
  4. Automated HR-to-Cloud Provisioning & Instant Kill-Switch (SCIM 2.0): Provision multi-profile users from corporate HR/AD systems and atomically revoke sessions, tokens, and infrastructure leases upon separation.
  5. High-Assurance Multi-Region Identity Clustering & SIEM Compliance: Replicate sharded WAL deltas across regional replicas while streaming Ed25519-signed RFC 5424 audit trails to vsight or enterprise SIEM platforms.

2. Example 1 — OAuth 2.1 Authorization Code + PKCE (S256) Token Exchange

Relying Parties (vgate, vft, vsite, or custom web/CLI apps) authenticate principals without exposing raw credentials using RFC 7636 PKCE S256:

BASH
# 1. Generate a cryptographic PKCE code_verifier and S256 code_challenge
CODE_VERIFIER="dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"
CODE_CHALLENGE="E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM"

# 2. Request a single-use authorization code bound to the S256 challenge and OIDC nonce
curl -sS -X POST "http://127.0.0.1:8443/oauth2/authorize" \
  -H "Content-Type: application/json" \
  -d '{
    "tenant_slug": "acme",
    "client_id": "vgate-edge-iap",
    "redirect_uri": "https://portal.acme.example.com/oauth2/callback",
    "scope": "openid profile email groups offline_access",
    "state": "csrf-state-9812",
    "nonce": "oidc-nonce-4410",
    "code_challenge": "'"$CODE_CHALLENGE"'",
    "code_challenge_method": "S256",
    "username": "marcus.lind",
    "password": "ChangeMeInProd#2026"
  }'

# 3. Exchange the single-use authorization code + code_verifier for EdDSA JWTs
curl -sS -X POST "http://127.0.0.1:8443/oauth2/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "<AUTH_CODE_FROM_STEP_2>",
    "redirect_uri": "https://portal.acme.example.com/oauth2/callback",
    "client_id": "vgate-edge-iap",
    "client_secret": "<CLIENT_SECRET>",
    "code_verifier": "'"$CODE_VERIFIER"'"
  }'

# 4. Introspect or revoke an issued EdDSA access token
curl -sS -X POST "http://127.0.0.1:8443/oauth2/introspect" \
  -H "Content-Type: application/json" \
  -d '{"token": "<ACCESS_TOKEN>"}'

3. Example 2 — Real-Time Policy Decision Point (POST /access/v1/evaluate)

Edge gateways (vgate, vsite) and internal microservices query vwarden to evaluate conjunctive RBAC, ABAC, Org-Graph, MFA, and JIT lease policies in sub-millisecond latency:

Access Policy Evaluation & Live Simulator

BASH
curl -sS -X POST "http://127.0.0.1:8443/access/v1/evaluate" \
  -H "Content-Type: application/json" \
  -H "X-Vwarden-PEP-Token: $VWARDEN_PEP_TOKEN" \
  -d '{
    "tenant_slug": "acme",
    "subject_user_id": "usr_marcus_dev",
    "action": "pam:ssh",
    "resource": "urn:vwarden:infra:prod-eu-k8s-01",
    "target_org_id": "org_emea_eng",
    "mfa_verified": true,
    "vnet_verified": true
  }'

Example Response (When No Active JIT Lease Exists):

JSON
{
  "permitted": false,
  "effect": "deny",
  "matched_rule_id": "pol-02-prod-bastion-jit",
  "matched_rule_name": "Production Bastion & Kubernetes JIT Access",
  "advice": "request_workflow_approval",
  "workflow_template_id": "wf-jit-manager-approval",
  "explanation": "Denied: rule requires active JIT workflow grant (has_active_jit_grant) on urn:vwarden:infra:prod-eu-k8s-01"
}

4. Example 3 — End-to-End Just-In-Time (JIT) Bastion Approval & Early Revocation

JIT Access Request & Active VGate Leases

BASH
# 1. Engineer submits a 30-minute SSH JIT request via reflexive self-service API
curl -sS -X POST "http://127.0.0.1:8443/api/v1/self/workflows" \
  -H "Authorization: Bearer $ENGINEER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "wf-jit-manager-approval",
    "target_resource": "urn:vwarden:infra:prod-eu-k8s-01",
    "target_action": "pam:ssh",
    "grant_duration_sec": 1800,
    "reason": "INC-5104: Inspect EU payment worker socket saturation"
  }'

# 2. EMEA Delegated Admin approves the workflow, minting a signed vnet_tok_ lease
curl -sS -X POST "http://127.0.0.1:8443/api/v1/workflows/resolve" \
  -H "Authorization: Bearer $DELEGATED_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "<WORKFLOW_ID>",
    "approved": true,
    "comment": "Approved for 30m incident window INC-5104"
  }'

# 3. Engineer revokes their own lease early once remediation finishes
curl -sS -X POST "http://127.0.0.1:8443/api/v1/self/vgate/revoke" \
  -H "Authorization: Bearer $ENGINEER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"grant_id": "<VGATE_GRANT_ID>"}'

5. Example 4 — SCIM 2.0 Provisioning & Instant Employee Offboarding

BASH
# List provisioned SCIM 2.0 enterprise users
curl -sS -H "Authorization: Bearer $ADMIN_TOKEN" \
  "http://127.0.0.1:8443/scim/v2/Users"

# Trigger atomic offboarding kill-switch (disables user, purges sessions, revokes JIT grants)
curl -sS -X POST "http://127.0.0.1:8443/api/v1/scim/deprovision" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "usr_marcus_dev",
    "reason": "HR-OFFBOARD-2026-091: Contract completion"
  }'

6. Example 5 — Programmable Zero-Trust Policies via vvm WebAssembly 3.0 (vwarden-wasm)

When running the vwarden-wasm build (-d vvm), administrators and platform teams can evaluate custom WebAssembly 3.0 (.wat or .wasm) policy predicates and claim mappers inside a zero-I/O, fuel-metered sandbox (POST /api/v1/policies/wasm/eval).

6.1 Real-Life Example A: Geo-Velocity & Risk-Score MFA Gate

Allow low-risk logins (risk <= 40) directly, require MFA for medium-risk logins (41..75), and deny high-risk logins (> 75):

BASH
curl -sS -X POST "http://127.0.0.1:8443/api/v1/policies/wasm/eval" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "export_fn": "evaluate",
    "args_csv": "65,1",
    "max_fuel": 50000,
    "wat_source": "(module (func (export \"evaluate\") (param $risk i64) (param $mfa i64) (result i64) (if (result i64) (i64.le_s (local.get $risk) (i64.const 40)) (then (i64.const 1)) (else (if (result i64) (i32.and (i64.le_s (local.get $risk) (i64.const 75)) (i64.eq (local.get $mfa) (i64.const 1))) (then (i64.const 1)) (else (i64.const 0)))))))"
  }'

6.2 Real-Life Example B: Production Maintenance-Window Gate

Restrict production deployments to 08:00–18:00 UTC unless an approved break-glass flag (1) is active:

BASH
curl -sS -X POST "http://127.0.0.1:8443/api/v1/policies/wasm/eval" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "export_fn": "check_window",
    "args_csv": "22,0",
    "max_fuel": 50000,
    "wat_source": "(module (func (export \"check_window\") (param $hour i64) (param $bg i64) (result i64) (if (result i64) (i64.eq (local.get $bg) (i64.const 1)) (then (i64.const 1)) (else (if (result i64) (i32.and (i64.ge_s (local.get $hour) (i64.const 8)) (i64.le_s (local.get $hour) (i64.const 18))) (then (i64.const 1)) (else (i64.const 0)))))))"
  }'

6.3 Real-Life Example C: Custom OIDC / SAML Clearance-Tier Mapper

Compute a dynamic clearance_tier (3 = Top Secret, 2 = Confidential, 1 = Standard) from department code (9 = Security) and tenure years:

BASH
curl -sS -X POST "http://127.0.0.1:8443/api/v1/policies/wasm/eval" \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "export_fn": "map_clearance",
    "args_csv": "9,5",
    "max_fuel": 50000,
    "wat_source": "(module (func (export \"map_clearance\") (param $dept i64) (param $tenure i64) (result i64) (if (result i64) (i32.and (i64.eq (local.get $dept) (i64.const 9)) (i64.ge_s (local.get $tenure) (i64.const 3))) (then (i64.const 3)) (else (if (result i64) (i64.ge_s (local.get $tenure) (i64.const 1)) (then (i64.const 2)) (else (i64.const 1)))))))"
  }'

6.4 Fuel-Metered Infinite-Loop Protection

Every Wasm plugin runs with an explicit instruction budget (max_fuel, default 50,000). If a buggy or malicious module enters an infinite loop, vwarden-wasm traps immediately once max_fuel is exhausted and returns HTTP 400 without impacting other tenants or worker threads.


7. Day-2 Operations Runbook Checklist

Operational Task Cadence Verification Endpoint / CLI
Verify SIEM Hash Chain & Ed25519 Signatures Hourly / Automated GET /api/v1/siem/verify
Rotate & Seal SIEM Audit Segment (.seal) Daily POST /api/v1/siem/rotate
Sweep Expired JIT Workflows & Ephemeral Leases Every 60 seconds POST /api/v1/workflows/tick (plus automatic runtime sweep)
Verify Replica WAL Lag Across Cluster Peers Continuous GET /api/v1/overview -> cluster.peers[].lag_entries == 0
Rotate Tenant Ed25519 OIDC Signing Key Every 90 days Publish new kid with overlap in GET /.well-known/jwks.json

Part VI: vwarden — Configuration & CLI Reference

1. Command-Line Interface (vwarden) Reference

TEXT
Usage: vwarden <command> [options]
Subcommand Arguments & Flags Audience Description
serve (start) [port] [backend] [--host <ip>] [--issuer <url>] [--tls-cert <pem>] [--tls-key <pem>] [--pep-token <tok>] [--demo] Administrators & Operators Starts the HTTP/1.1 or standalone TLS 1.2+ identity server and role-separated Web Studio (127.0.0.1:8443 and vprevail by default; production-safe unless --demo is set).
version (-v, --version) None All Users Prints the semantic version of the vwarden binary.
discovery [issuer_url] Developers & Integrators Emits the complete RFC 8414 / OpenID Connect 1.0 /.well-known/openid-configuration JSON document for issuer_url (defaults to https://127.0.0.1:8443).
openapi [issuer_url] Developers & Integrators Emits the complete OpenAPI 3.1.0 JSON specification for all authentication, self-service, federation, policy, and governance endpoints.
verify-id <identifier> Operators Validates a tenant slug, client ID, or resource identifier against the strict [a-zA-Z0-9_-]{1,64} whitelist.
help (-h, --help) None All Users Prints the CLI command and flag summary.

vwarden serve Flag Details

Flag Default Environment Variable Fallback Description
[port] / --port <n> 8443 — TCP port for the API and Web Studio listener.
[backend] / --backend <name> vprevail — Directory persistence backend: vprevail (64-shard MVCC + WAL), sqlite (SQLite WAL), or postgres (PostgreSQL).
--host <ip> 127.0.0.1 — Network interface bind address (127.0.0.1 for loopback behind vgate, 0.0.0.0 for direct ingress).
--issuer <url> http(s)://<host>:<port> VWARDEN_ISSUER_URL Public OIDC/SAML/WebAuthn issuer URL (required when running behind a reverse proxy such as vgate or nginx).
--tls-cert <path> Empty (HTTP) VWARDEN_TLS_CERT PEM certificate chain path enabling standalone TLS 1.2+ HTTPS termination, HSTS, and Secure cookies.
--tls-key <path> Empty (HTTP) VWARDEN_TLS_KEY PEM private key path paired with --tls-cert.
--pep-token <secret> Empty VWARDEN_PEP_TOKEN Shared bearer token verified via X-Vwarden-PEP-Token for remote Policy Enforcement Point callers of POST /access/v1/evaluate.
--demo false VWARDEN_DEMO_MODE Opt-in local demo mode seeding sample users/clients and enabling /api/v1/auth/pkce-demo (disabled by default in production).

2. Environment Variables Reference

Environment Variable Required in Production Purpose
VWARDEN_MASTER_KEY_HEX Yes 64-character hex (32-byte) master key for the AES-256-GCM cryptographic vault sealing TOTP seeds, Ed25519 keys, JIT vnet_tok_ grants, and SIEM keys.
VWARDEN_ISSUER_URL Yes (behind proxy) Public HTTPS origin advertised in OIDC Discovery, JWT iss, SAML EntityID, and WebAuthn rpId.
VWARDEN_BOOTSTRAP_ADMIN_PASSWORD Recommended (first boot) Initial global admin password on first boot; if omitted in production mode, a one-time CSPRNG password is generated and logged to stderr.
VWARDEN_DEMO_MODE No (false default) Set to 1 / true only in local evaluation environments to seed sample users and enable /api/v1/auth/pkce-demo.
VGATE_MESH_SECRET Yes (when using VGate JIT) Shared HMAC-SHA256 secret used to sign time-bounded vnet_tok_ mesh leases consumed by vgate.
VWARDEN_PEP_TOKEN Recommended Shared secret authenticating remote gateways invoking POST /access/v1/evaluate.
VWARDEN_TLS_CERT Optional PEM certificate chain path for standalone HTTPS termination.
VWARDEN_TLS_KEY Optional PEM private key path for standalone HTTPS termination.
VWARDEN_PG_HOST Only when --backend postgres PostgreSQL server hostname or IP address (127.0.0.1 default).
VWARDEN_PG_PORT Only when --backend postgres PostgreSQL TCP port (5432 default).
VWARDEN_PG_USER Only when --backend postgres PostgreSQL authentication role.
VWARDEN_PG_PASSWORD Only when --backend postgres PostgreSQL role password.
VWARDEN_PG_DBNAME Only when --backend postgres PostgreSQL target database name (vwarden default).

3. Bootstrap Configuration File (config/vwarden_bootstrap.json)

When starting with an empty data directory, vwarden loads config/vwarden_bootstrap.json to initialize the default tenant realm and global administrator account:

JSON
{
  "tenant_slug": "acme",
  "tenant_display_name": "Acme Global Cloud Corp",
  "bootstrap_admin_user_id": "usr_admin",
  "bootstrap_admin_username": "admin",
  "bootstrap_admin_password": "ReplaceWithStrongInitialPassword#2026!",
  "bootstrap_admin_email": "admin@acme.example.com",
  "bootstrap_admin_display_name": "System Administrator",
  "bootstrap_admin_org_id": "org_root",
  "bootstrap_admin_role": "admin",
  "bootstrap_admin_groups": "platform-admins,secops,sre-prod",
  "bootstrap_admin_entitlements": "iam:admin,pdp:write,pam:bastion,scim:admin,cluster:admin,workflow:approve"
}

4. HTTP Protocol, Self-Service & Governance Endpoints

4.1 OpenID Connect 1.0, OAuth 2.1, SAML 2.0, SCIM 2.0 & PDP Endpoints

Method & Path Access Control Specification
GET /.well-known/openid-configuration Public RFC 8414 / OIDC 1.0 Discovery metadata.
GET /.well-known/jwks.json Public RFC 7517 / RFC 8037 Ed25519 JSON Web Key Set (EdDSA).
POST /oauth2/authorize Rate-Limited Public OAuth 2.1 Authorization Code + mandatory S256 PKCE challenge endpoint.
POST /oauth2/token Client Auth / PKCE Single-use authorization code exchange and rotating refresh token grant.
GET|POST /oauth2/userinfo Bearer JWT OIDC 1.0 UserInfo claims (sub, email, name, groups_csv, primary_role, tenant_slug).
POST /oauth2/introspect Authenticated RFC 7662 token introspection verifying signature, exp, JTI revocation, and active user status.
POST /oauth2/revoke Authenticated RFC 7009 token revocation writing immediate JTI tombstones or deleting opaque refresh tokens.
GET /saml/v2/metadata Public SAML 2.0 Identity Provider XML metadata.
POST /api/v1/saml/issue & /verify Admin SAML 2.0 signed XML assertion issuance and XSW-1..8 / XXE / replay-guarded verification.
GET|POST /scim/v2/Users Admin / Delegated RFC 7643 / 7644 multi-profile SCIM 2.0 user provisioning and directory query.
GET /scim/v2/Groups Admin / Delegated RFC 7643 / 7644 SCIM 2.0 IdentityGroup listing.
GET|POST /scim/v2/Schemas Public GET / Admin POST Built-in and custom tenant SCIM 2.0 schema extension registry.
POST /access/v1/evaluate Bearer / PEP Token / Loopback Zero-Trust Policy Decision Point evaluation returning permit/deny, obligations, and workflow advice.

4.2 Auth Gate, Reflexive Self-Service (/api/v1/self/*) & Admin Studio Endpoints

Method & Path Access Control Specification
POST /api/v1/auth/login Rate-Limited Public Primary Argon2id credential check; returns session or mfa_required + mfa_challenge_token.
POST /api/v1/auth/mfa/verify Rate-Limited Public Verifies single-use mfa_challenge_token + 6-digit RFC 6238 TOTP code with 30s replay guard.
POST /api/v1/auth/register-onboarding Rate-Limited Public Stages a non-privileged OnboardingRequest and launches wf-user-onboarding.
GET /api/v1/auth/session & POST /api/v1/auth/logout Authenticated Session introspection and immediate server-side + cookie logout.
GET /api/v1/self Self-Service (is_self) Caller's own profile, SCIM 2.0 JSON, submitted workflows, and active VGateTagGrant leases.
POST /api/v1/self/profile Self-Service (is_self) Updates personal non-privileged profile attributes.
POST /api/v1/self/password Self-Service (is_self) Verifies current_password and rotates the caller's Argon2id password hash.
POST /api/v1/self/mfa/enroll & /confirm Self-Service (is_self) Stages AES-256-GCM sealed TOTP secret + local SVG QR, and activates MFA upon 6-digit confirmation.
POST /api/v1/self/workflows Self-Service (is_self) Submits a JIT access workflow bound reflexively to the authenticated caller.
POST /api/v1/self/vgate/revoke Self-Service (is_self) Early-revokes an active VGateTagGrant owned by the caller.
GET /api/v1/openapi.json Public OpenAPI 3.1.0 machine-readable schema document.
GET /ui/auth, /ui/portal, /ui/delegated, /ui/admin, /ui/device Role-Separated UI Web Studio workspaces for Sign-In/Onboarding, End Users, Delegated Org-Admins, Global Admins, and RFC 8628 Device Verification.
POST /oauth2/device_authorization OIDC & OAuth 2.1 Initiate RFC 8628 Device Authorization Grant (device_code + user_code).
POST /api/v1/oauth/device/verify OIDC & OAuth 2.1 Approve or deny a pending RFC 8628 user_code as an authenticated user.
POST /api/v1/auth/webauthn/register/{begin,finish} WebAuthn / FIDO2 Register a FIDO2 Passkey (ES256 P-256 or EdDSA Ed25519) for the signed-in user.
POST /api/v1/auth/webauthn/login/{begin,finish} WebAuthn / FIDO2 Passwordless / MFA Passkey assertion ceremony returning an HttpOnly session cookie.
POST /api/v1/auth/webauthn/delete WebAuthn / FIDO2 Remove a registered Passkey owned by the current user.
GET / POST /api/v1/policies/wasm Global Admin (pdp:write) List or persist named WebAssembly 3.0 Zero-Trust PDP plugins referenced via condition_expr: "wasm:<plugin_id>".
POST /api/v1/policies/wasm/delete Global Admin (pdp:write) Remove a persisted WebAssembly 3.0 policy plugin by plugin_id.
POST /api/v1/policies/wasm/eval Bearer / PEP Token / Loopback Evaluate a .wat or .wasm policy/claim plugin inside the fuel-metered vvm sandbox (vwarden-wasm build).

Optional SIEM Environment Variables

  • VWARDEN_SIEM_HTTP_URL: Optional HTTP/HTTPS SIEM ingest URL (e.g. http://127.0.0.1:8080/api/v1/telemetry/ingest-raw for vsight). Leave unset to disable HTTP streaming.
  • VWARDEN_SIEM_HTTP_TOKEN: Optional Bearer token sent in Authorization: Bearer <token> when VWARDEN_SIEM_HTTP_URL is configured.

Part VII: vwarden — Performance & Capacity Guide

1. Performance Design Principles

Identity and policy engines sit directly on the critical path of user sign-ins, microservice token verifications, and zero-trust proxy evaluations. vwarden achieves predictable low tail latency and minimal memory footprint through four architectural choices:

  1. Zero-GC-Pause Native Execution: Compiled directly to native x86_64/ARM64 machine code with deterministic value layouts and bounded socket buffers (16 KiB header cap, 1 MiB body cap).
  2. 64-Shard Copy-on-Write MVCC State Engine: Hot reads (GET /.well-known/jwks.json, POST /oauth2/introspect, POST /access/v1/evaluate, GET /api/v1/auth/session) execute against lock-free Copy-on-Write snapshots partitioned across 64 shards with {tenant} hash-tag co-location.
  3. Intentionally Asymmetric Cryptography:
    • Primary Password Login (Argon2id, 19 MiB, t=2, p=1) is intentionally memory-hard (~25–45 ms per login) to defeat GPU/ASIC offline cracking while bounded by per-IP rate limiting and connection semaphores.
    • Downstream Token & Policy Verification (Ed25519 / SHA-256 / MVCC) runs in microseconds to sub-millisecond latency so authenticated traffic scales to tens of thousands of requests per second.
  4. Sequential CRC32 Binary WAL + LZ4 Checkpoints: Mutations append compact 32-byte framed records sequentially to segmented .wal files (64 MiB segment threshold) with 24-byte sparse .idx indexes and LZ4-compressed .snap checkpoints for rapid cold-start recovery.

2. Measured Operation Latency & Throughput Profile

Representative single-node production (-prod) measurements on an 8-vCPU / 16 GiB x86_64 host (vprevail sharded MVCC backend over loopback HTTP/1.1):

Operation / Endpoint Dominant Work Median Latency (p50) Tail Latency (p99) Single-Node Sustained Throughput
OIDC Discovery & JWKS (GET /.well-known/*) In-memory read + socket frame 0.14 ms 0.48 ms > 28,000 req/s
ZERO-TRUST PDP Evaluation (POST /access/v1/evaluate) 64-shard MVCC lookup + RBAC/ABAC/Org-Graph eval 0.26 ms 0.85 ms > 16,500 evals/s
JWT Introspection (POST /oauth2/introspect) Ed25519 verify + JTI tombstone MVCC check 0.31 ms 0.95 ms > 13,000 req/s
OAuth 2.1 PKCE Token Exchange (POST /oauth2/token) Atomic WAL consume + SHA-256 PKCE + Ed25519 sign 0.78 ms 2.10 ms ~ 4,800 exchanges/s
Primary Password Login (POST /api/v1/auth/login) Memory-hard Argon2id (19 MiB, t=2, p=1) + WAL 31.0 ms 54.0 ms ~ 210 logins/s (CPU/RAM-bound by design)
Two-Step TOTP Verify (POST /api/v1/auth/mfa/verify) AES-256-GCM unseal + RFC 6238 HMAC + replay WAL 0.62 ms 1.75 ms ~ 5,400 verifications/s
Local ISO 18004 QR Enrollment (POST /api/v1/self/mfa/enroll) AES-256-GCM seal + GF(256) Reed-Solomon SVG render 0.85 ms 2.20 ms ~ 4,200 enrollments/s
Signed SIEM Audit Append + Chain Link SHA-256 chain + Ed25519 sign + append 0.29 ms 0.90 ms > 11,000 events/s

3. Capacity Planning & Hardware Sizing Guide

Deployment Tier Directory Scale Peak Login Concurrency Recommended Compute & Memory Storage & Topology
Small / Team Appliance Up to 2,500 users, 25 OAuth/SAML apps <= 25 logins/sec, 1,500 PDP evals/sec 2 vCPU, 2 GiB RAM Single node (vprevail or sqlite) on NVMe SSD (10 GiB) behind vgate.
Mid-Market Enterprise 2,500 – 50,000 users, 150 apps, multi-OrgUnit <= 100 logins/sec, 10,000 PDP evals/sec 4–8 vCPU, 8 GiB RAM Primary + 1 Voter Replica (vprevail WAL sync) on NVMe SSD (50 GiB).
Global High-Availability 50,000 – 500,000+ users, multi-region tenants 200+ logins/sec, 30,000+ PDP evals/sec 16+ vCPU, 32 GiB RAM per node 3-node regional cluster (0..31 / 32..63 shard affinity) + dedicated SIEM shipping.

4. Production Tuning Recommendations

  1. Right-Size Concurrent Argon2id Headroom:
    • Each concurrent Argon2id verification allocates a 19 MiB memory arena for ~30 ms. With the default 256 socket concurrency cap and per-IP login rate limiting, worst-case simultaneous password hashing stays comfortably bounded; ensure at least 2 GiB free RAM on nodes handling heavy Monday-morning sign-in bursts.
  2. Prefer Offline JWKS Verification at the Edge:
    • Configure vgate, vft, and vsite to cache GET /.well-known/jwks.json and verify EdDSA access tokens locally on every request, reserving POST /oauth2/introspect and POST /access/v1/evaluate for step-up privileged actions and instant JTI revocation checks.
  3. Keep data/prevail/ on Local NVMe Storage:
    • Binary WAL segment appends and .snap LZ4 checkpoints benefit from low-latency NVMe fsync; avoid network-mounted NFS/SMB shares for active WAL directories.
  4. Periodic SIEM Log Rotation (.seal):
    • Schedule daily POST /api/v1/siem/rotate calls so active SIEM ledger verification (GET /api/v1/siem/verify) scans bounded daily segments while archiving cryptographically sealed .seal files to cold storage.