Deployment Guide

docker run -p 3000:3000 \
  -e GUARDAI_SESSION_SECRET=$(openssl rand -base64 32) \
  ghcr.io/oronts/oronts-guardai/oguardai-server:latest

IMAGE=ghcr.io/oronts/oronts-guardai/oguardai-server:latest
IDENTITY='https://github.com/oronts/.*/.github/workflows/docker.yml@.*'
ISSUER=https://token.actions.githubusercontent.com

# Verify the keyless signature (identity = the release workflow's OIDC subject).
cosign verify "$IMAGE" --certificate-identity-regexp "$IDENTITY" --certificate-oidc-issuer "$ISSUER"

# Verify and extract the SPDX SBOM attestation.
cosign verify-attestation "$IMAGE" --type spdxjson \
  --certificate-identity-regexp "$IDENTITY" --certificate-oidc-issuer "$ISSUER" \
  | jq -r '.payload | @base64d | fromjson | .predicate' > sbom.spdx.json

curl http://localhost:3000/v1/health
# {"status":"healthy","version":"0.1.0","uptime_seconds":1.2}

curl -X POST http://localhost:3000/v1/transform \
  -H "Content-Type: application/json" \
  -d '{"input": "Contact julia@example.com for help"}'

{
  "safe_text": "Contact {{email:e_001:7b1068662ab5}} for help",
  "session_id": "...",
  "session_state": "...",
  "entities": [{"token": "{{email:e_001:7b1068662ab5}}", "type": "email"}]
}

# Clone the repository
git clone https://github.com/oronts/oguardai.git
cd oguardai

# Build all Rust crates
cargo build --workspace

# Run all tests
cargo test --workspace

# Start the server with defaults
cargo run -p oguardai-server -- --config oguardai.yaml

server:
  host: "127.0.0.1"
  port: 3000

auth:
  mode: dev

session:
  backend: sealed
  secret: "dev-only-secret-change-in-prod!!"
  ttl_seconds: 3600

detector:
  mode: builtin

policy:
  default: default
  directory: policies

transform:
  context_strategy: full
  max_context_tokens: 4096

# Terminal 1: Start Python NER detector
cd apps/detector-py
uv sync
uv run uvicorn guardai_detector_service.main:app --host 0.0.0.0 --port 9090

# Terminal 2: Start Rust server with detector URL
GUARDAI_DETECTOR_URL=http://localhost:9090 \
  cargo run -p oguardai-server -- --config oguardai.yaml

# Required: 32-byte session encryption secret
GUARDAI_SESSION_SECRET=$(openssl rand -base64 32)

# Optional: log level
GUARDAI_LOG_LEVEL=guardai_server=info,tower_http=info

# Required environment variables:
export GUARDAI_SESSION_SECRET="$(openssl rand -base64 32)"
export GUARDAI_API_KEY_1="$(openssl rand -hex 32)"

docker compose -f deploy/docker/docker-compose.yml up --build

# Test with authenticated request:
# curl -H "X-API-Key: $GUARDAI_API_KEY_1" http://localhost:3000/v1/health

docker compose -f deploy/docker/docker-compose.minimal.yml up --build

# Add the OGuardAI Helm repository (when published)
helm repo add oguardai https://oronts.github.io/oguardai/charts
helm repo update

# Install with default values
helm install oguardai oguardai/oguardai \
  --namespace oguardai \
  --create-namespace \
  --set session.secret="$(openssl rand -base64 32)" \
  --set auth.apiKeys[0].name=default \
  --set auth.apiKeys[0].key="$(openssl rand -hex 32)" \
  --set audit.backend=file \
  --set audit.strict=true

# Or install from local chart
helm install oguardai deploy/helm/oguardai \
  --namespace oguardai \
  --create-namespace \
  --set session.secret="$(openssl rand -base64 32)" \
  --set auth.apiKeys[0].name=default \
  --set auth.apiKeys[0].key="$(openssl rand -hex 32)" \
  --set audit.backend=file \
  --set audit.strict=true

server:
  replicaCount: 3
  resources:
    requests:
      cpu: 500m
      memory: 512Mi
    limits:
      cpu: "2"
      memory: 1Gi

# replicaCount > 1 requires the shared redis backends (revocation + idempotency),
# or the chart refuses to render.
revocation:
  backend: redis
idempotency:
  backend: redis
redis:
  external:
    url: redis://redis:6379

session:
  backend: sealed
  ttlSeconds: 3600
  # Reference an existing Kubernetes secret
  existingSecret: oguardai-session-secret
  existingSecretKey: session-secret

auth:
  mode: api_key
  # API keys must use the name/key format matching the Helm chart template.
  # The template generates env vars GUARDAI_API_KEY_{NAME} from each entry.
  apiKeys:
    - name: my-service
      key: "GENERATE_WITH_openssl_rand_hex_32"  # Replace before deploying

policy:
  default: default
  directory: /app/policies

# Durable, fail-closed audit trail. REQUIRED for a non-dev (api_key/jwt/oidc) start:
# the server refuses to boot with the ephemeral log backend unless
# GUARDAI_ALLOW_EPHEMERAL_AUDIT=1 is set. Back the audit volume with a
# PersistentVolume; the default emptyDir does not survive pod restarts.
audit:
  backend: file
  strict: true
  file:
    path: /audit/audit.log

transform:
  contextStrategy: full
  maxContextTokens: 4096

# Enable Python NER detector
detector:
  enabled: true
  # The detector handles raw PII and fails closed (503) without the shared
  # X-Detector-API-Key secret. When detector.enabled, the chart requires
  # auth.apiKey or auth.existingSecret (or the explicit dev-only opt-out
  # auth.allowInsecure=true).
  auth:
    existingSecret: oguardai-detector-auth
    existingSecretKey: detector-api-key
  resources:
    requests:
      cpu: 500m
      memory: 1Gi
    limits:
      cpu: "2"
      memory: 2Gi

# Enable horizontal pod autoscaler
autoscaling:
  enabled: true
  minReplicas: 3
  maxReplicas: 10
  targetCPUUtilizationPercentage: 70

# Shared revocation is REQUIRED for more than one replica. The chart refuses to
# install when replicaCount > 1 or autoscaling.enabled unless revocation.backend
# is redis with an external URL: the default memory backend is pod-local, so a
# value revoked on one pod would not be refused by the others. Redis stores only
# HMAC-SHA-256 digests of revoked (type, value) pairs, never raw PII.
revocation:
  backend: redis

redis:
  external:
    url: "redis://redis-master.oguardai.svc.cluster.local:6379"

# Pod security
podSecurityContext:
  runAsNonRoot: true
  runAsUser: 1000
  fsGroup: 1000

securityContext:
  readOnlyRootFilesystem: true
  allowPrivilegeEscalation: false
  capabilities:
    drop:
      - ALL

helm install oguardai deploy/helm/oguardai \
  --namespace oguardai \
  --create-namespace \
  -f values-production.yaml

# Create the Kubernetes secret first
kubectl create secret generic oguardai-session-secret \
  --namespace oguardai \
  --from-literal=session-secret="$(openssl rand -base64 32)"

# Reference it in Helm values
helm install oguardai deploy/helm/oguardai \
  --set session.existingSecret=oguardai-session-secret \
  --set session.existingSecretKey=session-secret \
  --set auth.apiKeys[0].name=default \
  --set auth.apiKeys[0].key="$(openssl rand -hex 32)"

server:
  host: "0.0.0.0"      # Bind address (default: 0.0.0.0)
  port: 3000            # Bind port (default: 3000)
  allowed_origins:      # CORS allowlist enforced in non-dev auth modes; env GUARDAI_CORS_ORIGINS (comma-separated)
    - "https://app.example.com"
  tls:                  # Optional in-process TLS; TLS is usually terminated at the ingress instead
    enabled: false
    cert_path: "/etc/oguardai/tls.crt"   # env GUARDAI_TLS_CERT
    key_path: "/etc/oguardai/tls.key"    # env GUARDAI_TLS_KEY

auth:
  mode: api_key         # dev | api_key | jwt | oidc (default: dev)
  api_keys:             # Only used when mode=api_key
    - key: sk-...
      identity: my-service
      tenant_id: tenant-1  # Optional: multi-tenancy scope
      scopes:           # Optional: restrict to specific scopes
        - transform
        - rehydrate
  # JWT config (only used when mode=jwt)
  jwt:
    secret: "your-hmac-secret"
    issuer: "https://auth.example.com"
    audience: "guardai-api"   # Expected `aud` claim; a token whose audience differs is rejected
  # OIDC config (only used when mode=oidc)
  oidc:
    issuer: "https://issuer.example.com"
    jwks_url: "https://issuer.example.com/.well-known/jwks.json"
    audience: "guardai-api"
    tenant_claim: "tenant_id"   # Claim that carries the tenant identifier (required)
    algorithms: [RS256]         # Asymmetric allowlist: RS256/384/512, ES256/384, PS256/384/512

session:
  backend: sealed       # sealed (default: sealed)
  secret: "..."         # 32-byte encryption secret (REQUIRED for production)
  ttl_seconds: 3600     # Session TTL in seconds (default: 3600)

revocation_backend: memory   # memory (file-backed, per-instance) | redis (shared)
replay_backend: memory       # memory (per-instance) | redis (shared); rejects replayed continuations
session:
  redis_url: "redis://redis:6379"   # required when revocation_backend or replay_backend is redis

detector:
  mode: builtin         # builtin | advanced | both (default: builtin)
  advanced_url: "http://detector:9090"  # URL of Python NER sidecar
  default_language: null  # ISO 639-1 fallback when a request omits its own language; null falls back to "en" (no auto-detect)
  timeout_secs: 5  # NER request timeout (max 120); env GUARDAI_DETECTOR_TIMEOUT_SECS

policy:
  default: default      # Default policy name (default: "default")
  directory: policies   # Directory containing policy YAML files (default: "policies")

transform:
  context_strategy: full   # full | type_summary | referenced_only | none (default: full)
  max_context_tokens: 4096 # Max tokens for entity_context (default: 4096)

output_protection:
  enabled: true         # Output guard is enabled by default
  mode: strict          # strict | permissive (default: strict)
  default_action: mask  # allow | warn | mask | block (default: mask)
  exempt_types:         # Entity types exempt from output protection
    - greeting

prompt_security:
  enabled: true         # Enable prompt injection scanning (default: true)
  action: strip         # warn | strip | block (default: strip)

file_upload:
  max_size_bytes: 52428800  # 50MB default

rate_limit:
  enabled: false        # Enable rate limiting (default: false)
  requests_per_second: 100  # Global rate limit (default: 100)
  burst_size: 200       # Burst allowance (default: 200)

audit:
  backend: file         # log (ephemeral, fail-open; the default) | file (durable, hash-chained)
  strict: true          # fail a request closed (503) when its audit event cannot be recorded (default: false)
  file:
    path: /var/lib/guardai/audit/audit.log   # required when backend=file
  allow_ephemeral: false  # explicit waiver of the non-dev durable, strict requirement

idempotency:
  backend: memory              # memory (per-replica) | redis (shared; uses session.redis_url)
  ttl_seconds: 86400           # how long a completed Idempotency-Key result is replayed (default: 86400)
  in_progress_ttl_seconds: 60  # how long an in-flight claim blocks a duplicate before it is reclaimable (default: 60)

tenants:
  acme-corp:
    default_policy: gdpr-strict
    rate_limit:
      requests_per_second: 50
      burst_size: 100
  startup-inc:
    default_policy: default
    rate_limit:
      requests_per_second: 200
      burst_size: 400

# Generate a cryptographically random 32-byte secret
openssl rand -base64 32

session:
  secret: "new-production-secret-32-bytes!!"

session:
  keyring:
    current_kid: 0
    keys:
      - kid: 0
        secret: "${OLD_SECRET}"
      - kid: 1
        secret: "${NEW_SECRET}"

Single-key change:
  Old key active   |  Deploy new secret  |  New key only
  (all sessions)   |  (old blobs become  |  (clients re-transform
                   |   undecryptable)    |   to get new blobs)

Zero-downtime keyring:
  Seal under kid 0 | Add kid 1, seal kid 0 | Switch current_kid 1 | Remove kid 0
                   |                       | (kid 0 decrypts      | (kid 0 blobs
                   |                       |  until TTL)          |  now invalid)

curl http://localhost:3000/livez                    # Unauthenticated liveness probe
curl -H "X-API-Key: $GUARDAI_API_KEY" http://localhost:3000/v1/health  # Full health check

{
  "status": "healthy",
  "version": "0.1.0",
  "uptime_seconds": 3600.5,
  "components": {
    "detector": {"status": "healthy", "message": "builtin_and_ner (full entity detection)"},
    "session": {"status": "healthy", "message": "sealed"},
    "policies": {"status": "healthy", "message": "3 policies loaded"}
  }
}

# Example Prometheus alerting rules
groups:
  - name: guardai
    rules:
      - alert: OGuardAIUnhealthy
        expr: probe_success{job="guardai-health"} == 0
        for: 2m
        labels:
          severity: critical
        annotations:
          summary: "OGuardAI health check failing"

      - alert: OGuardAIHighLatency
        expr: histogram_quantile(0.95, rate(guardai_transform_duration_seconds_bucket{job="guardai"}[5m])) > 0.5
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "OGuardAI p95 latency above 500ms"

      - alert: OGuardAIHighErrorRate
        expr: rate(guardai_errors_total{job="guardai"}[5m]) / (rate(guardai_transforms_total{job="guardai"}[5m]) + rate(guardai_rehydrates_total{job="guardai"}[5m]) + 1) > 0.01
        for: 5m
        labels:
          severity: critical
        annotations:
          summary: "OGuardAI 5xx error rate above 1%"

{
  "timestamp": "2026-04-15T10:30:00Z",
  "level": "INFO",
  "target": "guardai_server::pipeline",
  "message": "transform completed",
  "request_id": "req-abc-123",
  "session_id": "sess-def-456",
  "tenant_id": "acme-corp",
  "entity_count": 3,
  "latency_ms": 12.5,
  "policy": "gdpr-strict"
}

# 3 instances, want 300 req/s global -> 100/s per instance
rate_limit:
  enabled: true
  requests_per_second: 100
  burst_size: 200

# prometheus.yml
scrape_configs:
  - job_name: 'guardai'
    # /metrics requires the `admin` scope whenever auth is enabled. Present an admin
    # credential: an Authorization: Bearer token in jwt/oidc mode, or route the scrape
    # through a proxy that injects the X-API-Key header in api_key mode.
    authorization:
      type: Bearer
      credentials: '<admin-scoped-jwt>'
    kubernetes_sd_configs:
      - role: pod
        selectors:
          - role: pod
            label: app=oguardai-server
    relabel_configs:
      - source_labels: [__meta_kubernetes_pod_ip]
        target_label: __address__
        replacement: '$1:3000'

# Total transforms across all instances
sum(guardai_transforms_total)

# Per-instance error rate
rate(guardai_errors_total[5m])

# p95 latency across all instances
histogram_quantile(0.95, sum(rate(guardai_transform_duration_seconds_bucket[5m])) by (le))

# Health endpoint shows detector status (requires auth when enabled)
curl -H "X-API-Key: $GUARDAI_API_KEY" http://localhost:3000/v1/health | jq '.components.detector'

# Capabilities shows what entity types are available
curl -H "X-API-Key: $GUARDAI_API_KEY" http://localhost:3000/v1/capabilities | jq '.entity_types[].name'

# Diagnostics shows full config (requires admin scope)
curl -H "X-API-Key: $GUARDAI_API_KEY" http://localhost:3000/v1/diagnostics | jq '.detector_mode'