Security Guide

# PLANNED — these TLS environment variables do not exist yet.
# A standalone topgun-server production binary with env-var TLS config is planned.
# For TLS today, configure it programmatically via TlsConfig when embedding the server.
#
# PORT=443 \
# DATABASE_URL=postgres://user:pass@localhost/topgun \
# TOPGUN_TLS_ENABLED=true \
# TOPGUN_TLS_CERT_PATH=/etc/topgun/tls/server.crt \
# TOPGUN_TLS_KEY_PATH=/etc/topgun/tls/server.key \
# TOPGUN_TLS_MIN_VERSION=TLSv1.3 \
# TOPGUN_CLUSTER_TLS_ENABLED=true \       # Planned — v3.0
# TOPGUN_CLUSTER_TLS_CERT_PATH=/etc/topgun/tls/cluster.crt \
# TOPGUN_CLUSTER_TLS_KEY_PATH=/etc/topgun/tls/cluster.key \
# TOPGUN_CLUSTER_TLS_CA_PATH=/etc/topgun/tls/ca.crt \
# TOPGUN_CLUSTER_MTLS=true \
# topgun-server    # <-- planned binary, not yet available

import { TopGunClient } from '@topgunbuild/client';
import { IDBAdapter } from '@topgunbuild/adapters';

// Production: Use wss:// (WebSocket Secure)
const client = new TopGunClient({
  serverUrl: 'wss://topgun.example.com',
  storage: new IDBAdapter()
});
// Set the JWT after construction — the constructor has no token field
client.setAuthToken('your-jwt-token');

// Development only: ws:// (unencrypted)
const devClient = new TopGunClient({
  serverUrl: 'ws://localhost:8080',
  storage: new IDBAdapter()
});

# Working today:
PORT=8090
DATABASE_URL=postgres://user:pass@localhost/topgun
JWT_SECRET=your-secret-key
TOPGUN_ADMIN_PASSWORD=your-admin-password

# Planned (not yet implemented — use TlsConfig struct for programmatic TLS):
# TOPGUN_PORT=443
# TOPGUN_TLS_ENABLED=true
# TOPGUN_TLS_CERT_PATH=/etc/topgun/tls/server.crt
# TOPGUN_TLS_KEY_PATH=/etc/topgun/tls/server.key
# TOPGUN_TLS_MIN_VERSION=TLSv1.3

# Planned — cluster mTLS (v3.0):
# TOPGUN_CLUSTER_PORT=9443
# TOPGUN_CLUSTER_TLS_ENABLED=true
# TOPGUN_CLUSTER_TLS_CERT_PATH=/etc/topgun/tls/cluster.crt
# TOPGUN_CLUSTER_TLS_KEY_PATH=/etc/topgun/tls/cluster.key
# TOPGUN_CLUSTER_TLS_CA_PATH=/etc/topgun/tls/ca.crt
# TOPGUN_CLUSTER_MTLS=true

#!/bin/bash
# Generate self-signed certificates for testing
# For production, use Let's Encrypt or your organization's CA

# Create output directory
mkdir -p certs && cd certs

# 1. Generate CA (Certificate Authority)
openssl genrsa -out ca.key 4096
openssl req -new -x509 -days 365 -key ca.key \
  -out ca.crt -subj "/CN=TopGun CA"

# 2. Generate Server Certificate
openssl genrsa -out server.key 2048
openssl req -new -key server.key \
  -out server.csr -subj "/CN=topgun.example.com"

# Create SAN (Subject Alternative Name) config
cat > san.cnf << EOF
[req]
distinguished_name = req_distinguished_name
req_extensions = v3_req
[req_distinguished_name]
[v3_req]
subjectAltName = @alt_names
[alt_names]
DNS.1 = topgun.example.com
DNS.2 = *.topgun.example.com
DNS.3 = localhost
IP.1 = 127.0.0.1
EOF

# Sign with CA
openssl x509 -req -days 365 -in server.csr \
  -CA ca.crt -CAkey ca.key -CAcreateserial \
  -out server.crt -extfile san.cnf -extensions v3_req

# 3. Generate Cluster Node Certificates (for mTLS)
for i in 1 2 3; do
  openssl genrsa -out node${i}.key 2048
  openssl req -new -key node${i}.key \
    -out node${i}.csr -subj "/CN=topgun-node-${i}"
  openssl x509 -req -days 365 -in node${i}.csr \
    -CA ca.crt -CAkey ca.key -CAcreateserial \
    -out node${i}.crt
done

echo "Certificates generated in ./certs/"

chmod +x scripts/generate-certs.sh
./scripts/generate-certs.sh

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: [email protected]
    privateKeySecretRef:
      name: letsencrypt-prod-account-key
    solvers:
    - http01:
        ingress:
          class: nginx
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: topgun-tls
  namespace: topgun
spec:
  secretName: topgun-tls
  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer
  dnsNames:
  - topgun.example.com
  - "*.topgun-cluster.svc.cluster.local"

# Install cert-manager
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.13.0/cert-manager.yaml

# Apply configuration
kubectl apply -f k8s/cert-manager.yaml

# Verify certificate
openssl x509 -in server.crt -text -noout

# Check expiry date
openssl x509 -enddate -noout -in server.crt

# Verify key matches certificate
openssl x509 -noout -modulus -in server.crt | openssl md5
openssl rsa -noout -modulus -in server.key | openssl md5
# Both should output the same hash

# Test TLS connection
openssl s_client -connect localhost:443 -tls1_3

# View full certificate chain
openssl s_client -showcerts -connect topgun.example.com:443

TLS_AES_256_GCM_SHA384
TLS_CHACHA20_POLY1305_SHA256
TLS_AES_128_GCM_SHA256

ECDHE-ECDSA-AES256-GCM-SHA384
ECDHE-RSA-AES256-GCM-SHA384
ECDHE-ECDSA-CHACHA20-POLY1305
ECDHE-RSA-CHACHA20-POLY1305

import { TopGunClient, EncryptedStorageAdapter } from '@topgunbuild/client';
import { IDBAdapter } from '@topgunbuild/adapters';

// Get encryption key (see key management strategies below)
const encryptionKey = await getEncryptionKey(); // or getDeviceKey()

// Create base adapter and wrap with encryption
const baseAdapter = new IDBAdapter();
const encryptedAdapter = new EncryptedStorageAdapter(baseAdapter, encryptionKey);

const client = new TopGunClient({
  serverUrl: 'wss://topgun.example.com',
  storage: encryptedAdapter
});

async function getEncryptionKey(password: string): Promise<CryptoKey> {
  const encoder = new TextEncoder();

  // Get or create salt
  let saltString = localStorage.getItem('encryption_salt');
  let salt: Uint8Array;

  if (saltString) {
    salt = Uint8Array.from(atob(saltString), c => c.charCodeAt(0));
  } else {
    salt = crypto.getRandomValues(new Uint8Array(16));
    localStorage.setItem('encryption_salt', btoa(String.fromCharCode(...salt)));
  }

  // Derive key from password
  const keyMaterial = await crypto.subtle.importKey(
    'raw',
    encoder.encode(password),
    'PBKDF2',
    false,
    ['deriveKey']
  );

  return crypto.subtle.deriveKey(
    {
      name: 'PBKDF2',
      salt: salt,
      iterations: 100000,
      hash: 'SHA-256'
    },
    keyMaterial,
    { name: 'AES-GCM', length: 256 },
    false,
    ['encrypt', 'decrypt']
  );
}

async function getDeviceKey(): Promise<CryptoKey> {
  const storedKey = localStorage.getItem('topgun_device_key');

  if (storedKey) {
    // Import existing key
    const keyData = Uint8Array.from(atob(storedKey), c => c.charCodeAt(0));
    return crypto.subtle.importKey(
      'raw',
      keyData,
      { name: 'AES-GCM', length: 256 },
      false,
      ['encrypt', 'decrypt']
    );
  }

  // Generate new key
  const key = await crypto.subtle.generateKey(
    { name: 'AES-GCM', length: 256 },
    true, // extractable
    ['encrypt', 'decrypt']
  );

  // Store for future use
  const exported = await crypto.subtle.exportKey('raw', key);
  localStorage.setItem(
    'topgun_device_key',
    btoa(String.fromCharCode(...new Uint8Array(exported)))
  );

  return key;
}