How to Secure Your SupaForge Credentials

What Credentials Does SupaForge Need?

SupaForge connects to two Supabase projects (source and target) to compare their environments. This requires:

• Database connection strings — PostgreSQL URIs with username, password, host, and database name.
• Supabase service role key (optional) — for auth, storage, and Edge Function checks that use the Management API.

These are the most sensitive values in your workflow. A leaked connection string gives full read/write access to your database.

Rule 1 — Never Commit Credentials

Never put connection strings in your config file if it's committed to Git. Use environment variables instead:

{
  "environments": {
    "staging": {
      "dbUrl": "$SUPAFORGE_STAGING_URL",
      "projectRef": "$SUPAFORGE_STAGING_REF",
      "apiKey": "$SUPAFORGE_STAGING_KEY"
    },
    "production": {
      "dbUrl": "$SUPAFORGE_PROD_URL",
      "projectRef": "$SUPAFORGE_PROD_REF",
      "apiKey": "$SUPAFORGE_PROD_KEY"
    }
  },
  "source": "staging",
  "target": "production"
}

SUPAFORGE_STAGING_URL=postgresql://user:pass@db.STAGING_REF.supabase.co:5432/postgres
SUPAFORGE_STAGING_REF=your-staging-project-ref
SUPAFORGE_STAGING_KEY=your-staging-service-role-key
SUPAFORGE_PROD_URL=postgresql://user:pass@db.PROD_REF.supabase.co:5432/postgres
SUPAFORGE_PROD_REF=your-production-project-ref
SUPAFORGE_PROD_KEY=your-production-service-role-key

Add .env to your .gitignore. Use .env.example with placeholder values to document the required variables.

Rule 2 — Use CI Secrets

In CI/CD pipelines, store credentials as encrypted secrets — not in workflow files:

• GitHub Actions — Repository secrets or environment secrets.
• GitLab CI — CI/CD variables with "masked" and "protected" enabled.
• Vercel / Netlify — Environment variables in the project settings.

- name: Run scan
  env:
    SUPAFORGE_STAGING_URL: ${{ secrets.SUPAFORGE_STAGING_URL }}
    SUPAFORGE_PROD_URL: ${{ secrets.SUPAFORGE_PROD_URL }}
  run: npx supaforge scan

Rule 3 — Encrypt at Rest

If you're building a hosted service on top of SupaForge (like a team dashboard), encrypt credentials before storing them in your database. Use AES-256-GCM with a unique initialisation vector (IV) per row:

import { createCipheriv, createDecipheriv, randomBytes } from 'crypto';

const ALGORITHM = 'aes-256-gcm';

function encrypt(plaintext: string, key: Buffer): string {
  const iv = randomBytes(12);
  const cipher = createCipheriv(ALGORITHM, key, iv);
  const encrypted = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()]);
  const tag = cipher.getAuthTag();
  return Buffer.concat([iv, tag, encrypted]).toString('base64');
}

function decrypt(ciphertext: string, key: Buffer): string {
  const data = Buffer.from(ciphertext, 'base64');
  const iv = data.subarray(0, 12);
  const tag = data.subarray(12, 28);
  const encrypted = data.subarray(28);
  const decipher = createDecipheriv(ALGORITHM, key, iv);
  decipher.setAuthTag(tag);
  return decipher.update(encrypted) + decipher.final('utf8');
}

Store the encryption key in an environment variable (ENCRYPTION_KEY), not in your codebase. The key should be a 64-character hex string (32 bytes).

Rule 4 — Principle of Least Privilege

• Use read-only database roles for scans. SupaForge only needs read access to detect drift. Create a dedicated role with SELECT permissions.
• Use separate roles for promote. Only the promote step needs write access. Use a different connection string with elevated permissions.
• Rotate credentials regularly. Supabase lets you reset the database password from the Dashboard — do this on a schedule.

Rule 5 — Enable MFA on Supabase

A compromised Supabase account can expose all connection strings. Enable MFA on every team member's Supabase account:

1. Go to Account → Security in the Supabase Dashboard.
2. Enable TOTP (authenticator app) — this is the most reliable factor.
3. Consider enforcing MFA at the organisation level if available.

Checklist

• ✅ Connection strings in environment variables, not committed files.
• ✅ CI/CD uses encrypted secrets.
• ✅ Credentials encrypted at rest if stored in a database.
• ✅ Read-only roles for scans, write roles only for promote.
• ✅ MFA enabled on all Supabase accounts.
• ✅ Database passwords rotated on a schedule.

Summary

Credential security is non-negotiable. Use environment variables, CI secrets, AES-256-GCM encryption for storage, least-privilege roles, and MFA to protect your Supabase environments.