Skip to content
Calvery Vault

Access Tokens

Access Token adalah identitas programmatic di Calvery. Dipakai untuk:

  • SDK di aplikasi production
  • GitHub Actions / GitLab CI / Vercel
  • Script deploy manual
  • Script monitoring / backup

Format

cvsm_<64-char-hex>

Contoh: cvsm_a3f5b1c8d9e2f7a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5

  • Prefix cvsm_ memudahkan secret scanner (GitHub, GitLeaks) deteksi kalau bocor
  • 64 char hex = 256-bit entropy → tidak bisa di-brute force
  • Stored sebagai SHA-256 hash di DB — tidak bisa dilihat ulang setelah create

Lifecycle

Create

Dashboard → Access Tokens → + Buat token:

  • Name: label deskriptif (github-actions, local-dev-john)
  • Expiry: opsional (30 / 90 / 365 hari, atau tanpa expiry)

Token muncul sekali. Copy ke password manager / secret vault kamu sendiri.

Inherit permissions

Token mewarisi permission user pembuatnya:

  • Kalau kamu owner team acme → token bisa akses semua secret acme
  • Kalau kamu cuma viewer → token read-only juga
  • Kalau kamu di-suspend → semua token kamu otomatis invalid

Usage tracking

  • last_used_at di-update tiap token dipakai (throttled 1 menit)
  • Visible di dashboard → Access Tokens
  • Handy untuk audit: token yang last_used_at > 90 hari lalu bisa di-revoke tanpa risiko

Revoke

Dashboard → Access Tokens → tombol 🗑️ → confirm.
Effect: instant. Tidak ada caching — next request pakai token itu langsung 401.

Anti-bypass protection

Token validation jalan lewat multi-layer defense:

  1. Format validation — request dengan token yang tidak match pattern cvsm_<64-hex> ditolak tanpa DB lookup. Brute force dengan format salah tidak waste DB resource.
  2. Prefix rate limit — 10+ failed lookup dengan prefix yang sama dalam 5 menit → prefix itu di-lock 5 menit. Attacker yang brute-force body token akan kena cooldown cepat.
  3. Constant-time hash compare — walau DB unique index sudah exact-match, kita tambah subtle.ConstantTimeCompare untuk defense-in-depth terhadap timing leak.
  4. Failed auth counter per token — tersimpan di kolom failed_auth_count. Kalau IP allowlist miss 5x, token auto-lock 1 jam (locked_until).
  5. IP allowlist (opsional) — set allowed_ips per token via DB/admin API (array of CIDR atau single IP). Kalau set, request dari IP di luar whitelist ditolak dan fail counter naik.
  6. Admin lock — admin bisa manual lock token via locked_until column (future UI button).

Efek keseluruhan: credential stuffing + brute force secara praktis infeasible. Kalau ada yang curiga (misal notif “IP baru di token CI”), tinggal revoke.

IP allowlist untuk CI token (opsional)

Kalau kamu tahu persis IP range runner CI (mis. GitHub Actions self-hosted, VPS internal), bisa pin token:

-- Contoh: restrict token cuma boleh dari 10.0.0.0/8 atau single IP 203.0.113.42
UPDATE api_tokens
SET allowed_ips = ARRAY['10.0.0.0/8', '203.0.113.42']
WHERE id = '<token-uuid>' AND user_id = '<your-user-id>';

UI untuk edit allowlist coming di v0.4. Sementara lewat SQL direct.

Best practices

1. One token per use case

❌ Jangan pakai 1 token untuk semua (dev + CI + prod)
✅ Buat terpisah: dev-laptop-john, github-ci, vercel-prod, monitoring-backup

Alasan: kalau satu bocor, revoke cuma yang bermasalah — tidak ganggu sistem lain.

2. Set expiry

Token tanpa expiry = liability. Set max 1 tahun, rotate sebelum expire.

3. Store di secret manager lain untuk bootstrap

Token Calvery sendiri butuh disimpan di tempat aman:

  • GitHub Actions → secrets.CVSM_TOKEN
  • Vercel → Environment Variables
  • AWS → Secrets Manager atau Parameter Store
  • Local dev → ~/.zshrc atau 1Password CLI

4. Rotate setelah incident

Kalau ada karyawan resign, laptop hilang, atau suspect leak:

  1. Revoke token affected di dashboard
  2. Generate baru dengan name baru
  3. Update downstream (CI env, production)

5. Monitor audit log

Role Admin+ bisa lihat audit log → filter by user_email: "machine-token-...".
Pattern anomali (tiba-tiba spike request, IP baru) → investigasi + revoke.

Programmatic token creation

Belum ada API untuk create token via REST (cuma via dashboard). Ini intentional — token create butuh manual action untuk audit trail.

Kalau kamu butuh flow automation (dynamically generated tokens), buat user khusus [email protected], login sekali di dashboard, generate token, simpan di secret manager infra kamu.

Security notes

  • Token TIDAK bisa di-decrypt — stored SHA-256 hash only. Kalau user lupa token, harus create baru.
  • Token lebih aman daripada password karena tidak bisa di-reuse untuk login ke dashboard (terpisah auth mechanism).
  • Prefix cvsm_ sengaja bikin GitHub secret scanner detect kalau tertulis accidentally di public repo → GitHub akan notify Calvery + kamu, token auto-revoke (planned).

FAQ

Kenapa tidak ada “Token + scope” seperti GitHub PAT?
v0.1 pakai model “inherit user permission”. Scope granular (read-only specific env) coming v0.4.

Bisa share token ke tim?
Secara teknis bisa, tapi jangan. Setiap orang buat token sendiri → audit log lebih jelas.

Token expired, secret masih bisa diakses pakai SDK lama?
Tidak. Cache SDK lokal cuma punya value 30 detik. Setelah cache expire, fetch baru → 401 → SDK throw CalveryAuthError.