# Create a new project
npx create-vril-app@latest my-app
cd my-app
npm run dev

# Or add to existing project
npm install vril-js

# Verify installation
npx vril doctor

import { defineVrilConfig } from './src/lib/vril/config/define';

export default defineVrilConfig({
  security: {
    trustedTypes: true,
    apiMembrane: true,
    csp: {
      defaultSrc: ["'self'"],
      scriptSrc: ["'self'", "'unsafe-inline'"],
      objectSrc: ["'none'"],
    },
    csrf: {
      enabled: true,
      tokenHeader: 'x-vril-csrf',
      sameSite: 'Strict',
    },
  },
  crypto: {
    defaultAlgorithm: 'aes-256-gcm',
    kdfIterations: 600000,    // OWASP: 600K+
    pqcEnabled: true,
    hybridMode: true,
    keyRotationDays: 90,
  },
  build: {
    cspNonce: true,
    sriHashes: true,
    sbom: true,
  },
  auth: {
    sessionTTL: 86400000,
    passwordMinLength: 12,
  },
});

import { createVrilApp, VrilVault, PQCHandler, signal } from '@/lib/vril';

// 1. Create your secure app
const app = createVrilApp({
  security: { trustedTypes: true, apiMembrane: true },
  crypto: { pqcEnabled: true, hybridMode: true },
});

// 2. Encrypt sensitive data with ΩVault
const vault = new VrilVault(600000);
const encrypted = await vault.encrypt('passphrase', 'sensitive data');
const decrypted = await vault.decrypt('passphrase', encrypted);

// 3. Post-quantum key exchange
const pqc = new PQCHandler();
const hybridKey = await pqc.generateHybridKeyPair();

// 4. Reactive state with ΩSignal
const count = signal(0);
const doubled = computed(() => count() * 2);
effect(() => console.log(`Count: ${count()}, Doubled: ${doubled()}`));
count.set(1);

import { createVrilApp, env, FeatureFlags } from '@/lib/vril/core';

const app = createVrilApp({
  security: { trustedTypes: true, apiMembrane: true },
  crypto: { pqcEnabled: true, hybridMode: true },
});

// Environment detection
console.log(env.isServer, env.isClient, env.isEdge);

// Feature flags with gradual rollout
const flags = new FeatureFlags();
flags.register('pqc-v2', { enabled: true, rollout: 25 }); // 25% rollout
if (flags.isEnabled('pqc-v2')) { /* use new PQC API */ }

import { createConfig, EnvironmentConfig } from '@/lib/vril/config';

const envConfig = EnvironmentConfig.createWithPresets();
const { config, validate } = createConfig({
  base: { crypto: { kdfIterations: 600000 } },
  environment: envConfig,
});

const result = validate();
if (!result.valid) {
  console.error('Config errors:', result.errors);
}

import { createPlugin, PluginRegistry } from '@/lib/vril/plugin';

const auditPlugin = createPlugin('security-audit')
  .onInit((ctx) => { ctx.log('Audit plugin initialized'); })
  .onRequest((ctx) => { ctx.log('Request intercepted'); })
  .build();

const registry = new PluginRegistry();
registry.register(auditPlugin);
registry.initializeAll();

import type { SecureString, Encrypted, SecurityLevel } from '@/lib/vril/types';

// Branded types prevent accidental misuse at compile time
function processSecure(input: SecureString) { /* ... */ }
// processSecure('plain'); // TypeScript error!
// processSecure(validate('plain') as SecureString); // OK

// Encrypted<T> cannot be accidentally treated as plaintext
function decrypt<T>(data: Encrypted<T>): T { /* ... */ }

import { installTrustedTypes, installAPIMembrane, DOMPSanitizer } from '@/lib/vril/security';

// Install zero-trust membrane
installTrustedTypes();
installAPIMembrane(['WebTransport', 'RTCPeerConnection']);

// Sanitize untrusted HTML
const sanitizer = new DOMPSanitizer();
const safe = sanitizer.sanitize(untrustedHTML);

// Validate URLs
const validator = new URLValidator();
const result = validator.validate(userUrl, { allowedProtocols: ['https:'] });

import { VrilVault } from '@/lib/vril/security/crypto/vault';

const vault = new VrilVault(600000);

// Encrypt sensitive data
const encrypted = await vault.encrypt('my-passphrase', 'sensitive data');
// encrypted = { v: 2, salt, iv, ciphertext, algorithm: 'AES-256-GCM', kdf: 'PBKDF2-SHA-512', kdfIterations: 600000 }

// Decrypt
const decrypted = await vault.decrypt('my-passphrase', encrypted);
// decrypted = { plaintext: 'sensitive data', algorithm: 'AES-256-GCM', verified: true }

// Check passphrase strength
const strength = vault.assessStrength('my-passphrase');
// strength = { score: 4, max: 6, label: 'moderate' }

import { PQCHandler } from '@/lib/vril/security/crypto/pqc';

const pqc = new PQCHandler();

// Check algorithm support
pqc.isSupported('ML-KEM-768'); // true
pqc.isSupported('ML-DSA-65');  // true

// Generate hybrid key pair
const keyPair = await pqc.generateKeyPair('X25519-ML-KEM-768');

// Key encapsulation
const result = await pqc.hybridKeyExchange(peerPublicKey);

// Get algorithm info
const info = pqc.getAlgorithmInfo('ML-KEM-768');
// info = { name: 'ML-KEM-768', standard: 'FIPS 203', securityLevel: 3, ... }

import { HybridKEM, HybridSigner } from '@/lib/vril/security/crypto/hybrid';

// Hybrid key exchange
const kem = new HybridKEM();
const result = await kem.encapsulate();
// result.classicalAlgorithm = 'X25519'
// result.pqcAlgorithm = 'ML-KEM-768'
// result.combinedSecret = SHA-256(X25519_secret || ML-KEM_secret || ctx)

// Hybrid signing
const signer = new HybridSigner();
const signature = await signer.sign(message, keyPair);
const valid = await signer.verify(message, signature, publicKey);
// Both ECDSA-P256 AND ML-DSA-65 must verify

import { CryptoAgility } from '@/lib/vril/security/crypto/agility';

const agility = new CryptoAgility();

// Check system status
const status = agility.getStatus();
// { totalAlgorithms: 12, activeAlgorithms: 8, migrationsPending: 2 }

// Select best algorithm by type
const bestKEM = agility.selectAlgorithm('kem'); // X25519+ML-KEM-768

// Plan migration
const registry = agility.getRegistry();
const plan = registry.migrate('x25519', 'ml-kem-768');
// plan = { success: true, message: 'Migrated from X25519 to ML-KEM-768' }

import { XSSShield, CookieFortress, CrossOriginIsolation } from '@/lib/vril/security/hardening';

// XSS protection
const shield = new XSSShield();
const safe = shield.sanitize(untrustedHTML);

// Secure cookies
const cookies = new CookieFortress();
cookies.set('session', token, { sameSite: 'Strict', httpOnly: true, secure: true });

// Cross-origin isolation for SharedArrayBuffer
const isolation = new CrossOriginIsolation();
isolation.enable();

import { SecurityAuditor, generateSecurityReport } from '@/lib/vril/security/audit';

const auditor = new SecurityAuditor();
const headerResults = auditor.scanHeaders();
const domResults = auditor.scanDOM();
const cryptoResults = auditor.scanCrypto();

// Full audit report
const report = await generateSecurityReport();
console.log(report.score); // 0-100
console.log(report.findings); // VulnerabilityFinding[]
console.log(report.compliance); // ComplianceStatus

import { signal, computed, effect, batch, encryptedSignal } from '@/lib/vril/signals';

const name = signal('World');
const greeting = computed(() => `Hello, ${name()}!`);

effect(() => console.log(greeting())); // "Hello, World!"
name.set('Vril');                      // "Hello, Vril!"

// Batch updates
batch(() => {
  name.set('Alice');
  // ... other updates
  // Only one notification after batch completes
});

// Encrypted signal (AES-256-GCM in memory)
const secret = encryptedSignal('sensitive-value', 'encryption-key');

import { createStore, loggerMiddleware, encryptionMiddleware } from '@/lib/vril/state';

const store = createStore(
  { count: 0, user: null },
  { middleware: [loggerMiddleware, encryptionMiddleware(['user'])] }
);

store.setState({ count: 1 });
const count = store.select((s) => s.count);

// Subscribe to changes
store.subscribe((state, prev) => {
  console.log('State changed:', state);
});

import { useSignal, useEncryptedState, useCSRFToken } from '@/lib/vril/hooks';

function SecureForm() {
  const count = useSignal(signal(0));
  const [secret, setSecret] = useEncryptedState('field-key', 'initial');
  const csrfToken = useCSRFToken();

  return (
    <form>
      <input type="hidden" name="csrf" value={csrfToken} />
      <input value={secret} onChange={(e) => setSecret(e.target.value)} />
      <button type="button" onClick={() => count.set(c => c + 1)}>{count}</button>
    </form>
  );
}

import { MemoryCache, EncryptedCache } from '@/lib/vril/cache';

const cache = new MemoryCache<string>({ maxSize: 1000, ttl: 60000 });
await cache.set('user:1', JSON.stringify(user));
const user = await cache.get('user:1');

// Encrypted cache for sensitive data
const encCache = new EncryptedCache({ passphrase: 'vault-key' });
await encCache.set('api-key', 'sk_live_abc123');
const key = await encCache.get('api-key');

import { CSRFGuard, RequestSigner, validateDeserializedPayload } from '@/lib/vril/server';

// CSRF protection
const token = CSRFGuard.generateToken();
const isValid = CSRFGuard.validateToken(request, expectedToken);

// Request signing (edge → origin)
const signer = new RequestSigner(process.env.SIGNING_SECRET);
const signature = await signer.sign(payload, Date.now());

// Validate deserialized RSC data
const result = validateDeserializedPayload(data, { maxDepth: 16 });
if (!result.valid) throw new Error(result.reason);

import { BuildSecurityChecker, SRIHasher } from '@/lib/vril/build';

// Run 20-point security audit
const checker = new BuildSecurityChecker();
checker.pass('csp-nonce');
checker.pass('sri-hashes');
checker.pass('hsts-preload');
const status = checker.getStatus();
// { total: 20, passed: 3, failed: [...17 items] }

// Generate SRI attribute
const sri = await SRIHasher.compute(scriptContent, 'sha384');
// "sha384-..."

import { RouteSecurityRegistry, createSecureHandler, RouteMiddleware } from '@/lib/vril/router';

const registry = new RouteSecurityRegistry();
registry.register({ path: '/api/*', security: { csrf: true, rateLimit: 60 } });

// Composable middleware
const handler = RouteMiddleware.compose(
  RouteMiddleware.withAuth,
  RouteMiddleware.withCSRF,
  RouteMiddleware.withRateLimit({ max: 100 }),
)(async (req) => Response.json({ ok: true }));

import { SessionManager, RBAC, PasswordHandler } from '@/lib/vril/auth';

// Sessions
const sessions = new SessionManager({ ttl: 86400000 });
const session = sessions.create({ userId: '123' });

// RBAC
const rbac = new RBAC();
rbac.defineRole('admin', ['read', 'write', 'delete']);
rbac.defineRole('user', ['read']);
const canDelete = rbac.checkPermission('admin', 'delete'); // true

// Passwords
const passwords = new PasswordHandler();
const hash = await passwords.hash('user-password');
const valid = await passwords.verify('user-password', hash);

import { createAPIRoute, APISchema } from '@/lib/vril/api';

const schema = APISchema.object({
  name: APISchema.string().min(1).max(100),
  email: APISchema.string().pattern(/^[^@]+@[^@]+$/),
});

const handler = createAPIRoute({
  validate: schema,
  rateLimit: { max: 100, window: 60000 },
  csrf: true,
}, async (req) => {
  return Response.json({ user: req.body });
});

import { createSSRStream, SSRSecurityGuard, SelectiveHydration } from '@/lib/vril/ssr';

const guard = new SSRSecurityGuard();
const clean = guard.sanitize(ssrOutput);

const hydration = new SelectiveHydration();
hydration.mark('hero', 'immediate');
hydration.mark('comments', 'visible');
hydration.mark('analytics', 'idle');

import { StreamIntegrityValidator, RateLimitedStream } from '@/lib/vril/streaming';

const validator = new StreamIntegrityValidator('hmac-secret');
validator.addChunk(chunk);
const isValid = validator.verify(finalChunk, expectedHash);

const limited = new RateLimitedStream({ bytesPerSecond: 1024 * 1024 });

import { EdgeRuntime, EdgeKV, EdgeSecurity } from '@/lib/vril/edge';

const runtime = new EdgeRuntime();
if (runtime.isEdge()) { /* edge-specific code */ }

const kv = new EdgeKV<string>({ namespace: 'sessions', ttl: 3600 });
await kv.set('user:1', JSON.stringify(session));

const edgeSec = new EdgeSecurity({ preset: 'strict' });
const isBot = edgeSec.detectBot(userAgent);

import { HeadManager, generateOGTags, CSPNonceInjector } from '@/lib/vril/head';

const head = new HeadManager();
head.addTitle('My App');
head.addMeta({ name: 'description', content: 'Secure app' });

const ogTags = generateOGTags({ title: 'My App', url: 'https://app.com' });
const nonce = CSPNonceInjector.generate();

import { PerformanceMonitor, SecurityDiagnostics } from '@/lib/vril/diagnostics';

const perf = new PerformanceMonitor();
perf.start('encryption');
await vault.encrypt(key, data);
perf.end('encryption');
// encryption: 42ms

const diag = new SecurityDiagnostics();
const health = diag.checkAll();

import { constantTimeEqual, secureRandomString, hashData } from '@/lib/vril/utils';

// Constant-time comparison (prevents timing attacks)
const match = constantTimeEqual(userToken, expectedToken);

// Secure random string
const apiKey = secureRandomString(32, 'alphanumeric');

// SHA-256 hashing
const hash = await hashData('input-data', 'SHA-256');