leganuxservices/llavero-keychain repository overview

Application
    │  Authorization: Bearer llv_dev_xxx
    ▼
Llavero ── validate token ── policy (deny by default) ── resolve service/environment
    │── decrypt credential (AES-256-GCM) ── auth driver (bearer/oauth2/aws-sigv4...)
    ▼
External API          (the real secret only travels to the registered hostname)

npm install

# 1. Master key (required in production; ephemeral one is generated in dev)
export LLAVERO_MASTER_KEY=$(openssl rand -hex 32)

npm run dev    # http://localhost:3000

ADMIN=localhost:3000/admin

# Service (upstream)
curl -s -X POST $ADMIN/services -H 'content-type: application/json' -d '{
  "name": "OpenAI", "slug": "openai",
  "baseUrl": "https://api.openai.com", "authDriver": "bearer"
}'
# → keep the returned "id"

# Environment
curl -s -X POST $ADMIN/environments -H 'content-type: application/json' \
  -d '{"serviceId":"<service-id>","name":"staging"}'
# → keep the environment "id"

# Credential (auto-encrypted; never shown again)
curl -s -X POST $ADMIN/credentials -H 'content-type: application/json' \
  -d '{"serviceId":"<service-id>","name":"primary","secret":{"token":"sk-real-openai-key"}}'
# → keep the credential "id"

# Client (your consumer application)
curl -s -X POST $ADMIN/clients -H 'content-type: application/json' -d '{"name":"my-backend"}'

# Internal token — SHOWN ONLY ONCE
curl -s -X POST $ADMIN/clients/<client-id>/tokens -H 'content-type: application/json' \
  -d '{"environment":"stg"}'
# → {"token":"llv_stg_...", ...}  save it

# Policy (without an explicit policy EVERYTHING is rejected: deny by default)
curl -s -X POST $ADMIN/policies -H 'content-type: application/json' -d '{
  "clientId":"<client-id>", "serviceId":"<service-id>",
  "environments":["staging"], "methods":["POST"], "paths":["/v1/*"]
}'

curl -X POST localhost:3000/gateway/openai/v1/responses \
  -H 'Authorization: Bearer llv_stg_...' \
  -H 'x-llavero-env: staging' \
  -H 'content-type: application/json' \
  -d '{"model":"gpt-5","input":"hello"}'

export LLAVERO_MASTER_KEY=$(openssl rand -hex 32)
export LLAVERO_ADMIN_KEY=$(openssl rand -hex 24)   # enables /admin and /dashboard in prod
docker compose up -d

cd cli && npm install
node cli.mjs config
node cli.mjs call openai /v1/models --env dev --token llv_dev_...

cd examples/client-demo
npm run provision        # creates services/clients/policies/token via Admin API
npm run demo:openai      # OpenAI (bearer)
npm run demo:mercadopago # MercadoPago (bearer)
npm run demo:google      # Firebase/Identity Toolkit + userinfo (oauth2)
npm run demo:stripe      # Stripe (bearer)
npm run demo:aws-s3      # PUT/GET object signed (aws-sigv4)
npm run demo:api-key     # httpbin reflects the injected header (api-key)

npm run seed   # creates openai, stripe, mercadopago, google (oauth2) and aws-s3
               # with dev/staging/production environments and PLACEHOLDER credentials
               # (idempotent; replace placeholders with real secrets)

src/
  config/ConfigService.ts        # Centralized config (env + Zod)
  core/
    logger.ts                    # Pino with secret redaction
    errors/index.ts              # Domain errors (AppError, NotFound, 401/403/429/5xx)
  auth-drivers/                  # Interface + Registry + 6 swappable drivers
  gateway/
    HttpGateway.ts               # auth → policy → route → credential → driver → upstream → audit
    WebSocketGateway.ts          # Driver handshake + transparent tunnel
    RouteResolver.ts             # Alias or slug + x-llavero-env
    UpstreamUrlBuilder.ts        # SSRF guard (origin = registered baseUrl)
    HeaderSanitizer.ts           # Drop hop-by-hop, auth, cookie, host
    UpstreamClient.ts            # Interface (+ UndiciUpstreamClient, no redirects)
  services/                      # ServiceManager, EnvironmentManager, AliasManager
  credentials/                   # CredentialManager + EncryptionProvider (AES-GCM)
  clients/                       # ClientManager, TokenManager (llv_*)
  policies/PolicyEngine.ts       # deny-by-default, '*' and prefixes
  plugins/                       # PluginManager + RateLimitPlugin
  audit/AuditService.ts          # Per-request metadata; never secrets
  admin/                         # Admin REST API + SSR Dashboard (same manager layer)
  database/                      # DatabaseProvider, schema, repositories, migrations
  bootstrap.ts                   # AppContainer (manual DI)
  app.ts / server.ts
scripts/seed-examples.ts         # Example seeds (npm run seed)
sdk/                             # Client SDK (LlaveroClient)
cli/                             # CLI (Commander + SDK)
examples/client-demo/            # Gateway consumption demo
tests/                           # Vitest (79 tests)

curl localhost:3000/health   # {"status":"ok"} — process alive
curl localhost:3000/ready    # checks: database, masterKey, core → 200 or 503