Database and auth

Supabase integration

Ahena works with a Supabase project you own: it checks the project, configures the auth site URL and redirect allow list, and generates database and auth code. Your app talks to Supabase directly. Ahena is never in the request path.

BetaFull Supabase docs

What Ahena inspects

Read-only: inspecting and Doctor never change anything at Supabase.

Project, region and Postgres version, and whether the project is active.
Service health for the database, auth, REST and storage.
Auth settings: site URL, redirect URLs and enabled sign-in methods. That response also holds secrets; Ahena keeps an allowlist of fields and drops the rest at the boundary.
Row level security on public tables (reading pg_class and pg_policy only) and applied migrations, compared with supabase/migrations/*.sql in your repository.

What Ahena configures

You declare what you want in ahena.config.ts; ahena plan shows each change with its classification before anything is applied.

Change	Classification	Notes
Set a missing site URL	CONFIRMATION_REQUIRED	—
Add a redirect URL	CONFIRMATION_REQUIRED	—
Replace the site URL	DESTRUCTIVE	Sign-in links that use the old value stop working.
Remove a redirect URL	DESTRUCTIVE	Sign-in links that use it stop working.

Refused outright:

Localhost, plain-HTTP and wildcard-domain URLs in production.

Generated code: src/ahena/providers/supabase.ts, src/ahena/database and src/ahena/auth (each with a raw escape hatch) and .env.example.supabase. On the server every call gets a fresh client, so one user's session never reaches another request.

How Ahena verifies

After every write, Ahena reads Supabase back. Each change ends in one of these states, and the plan's outcome says why:

VERIFIED: Ahena read the provider back and saw the desired state. The CLI shows ✓ only for VERIFIED.
APPLIED_UNVERIFIED: The provider accepted the change, but the re-read doesn't show it yet (after bounded polling), or the re-read failed.

Before the PATCH to the auth config, Ahena plans again and re-reads the current settings. Afterwards it reads them back to confirm the site URL and redirect allow list.

If a request may have reached Supabase but the answer was lost, Ahena re-reads before deciding: done, safe to retry, or “check before retrying”.

What Doctor diagnoses

Key checks from ahena doctor. Each finding says why it matters, where, the impact and whether Ahena can fix it. The full list is in the Supabase docs.

Check	What it means
`supabase.project.status`	Project active, transitioning, or paused or failed.
`supabase.health.{db,auth,rest,storage}`	Service health as Supabase reports it.
`supabase.db.rls`	Public tables without row level security (readable with the anon key).
`supabase.db.migrations`	Applied migrations against the repository's. Pending is a FAIL in production.
`supabase.auth.site_url`	Missing, a development URL in production, or different from your config.
`supabase.auth.redirects_broad`	Wildcards like `https://.com/*` that match domains you don't control.
`supabase.auth.autoconfirm`	Production sign-ups skip email confirmation.

More on findings, health and continuous checks: Doctor.

Approvals

Supabase changes here are classified CONFIRMATION_REQUIRED and DESTRUCTIVE. Every change is planned and shown as a diff first. Ahena itself enforces who can approve it:

SAFE changes are applied without asking.
In production, every other change needs approval in the Ahena dashboard, signed in, by an admin.
In other environments, CONFIRMATION_REQUIRED changes are approved in the CLI; BILLABLE and DESTRUCTIVE changes always need the dashboard.
MANUAL steps are never applied by Ahena.

--yes and --allow-billable don't replace a dashboard approval. See approvals for how it works and why the browser.

Manual steps

These are MANUAL: Ahena never does them. It lists them with the exact steps when they apply.

Project paused: restore it in the Supabase dashboard, then run ahena doctor.
Tables without RLS: add alter table … enable row level security; plus policies in a migration. Doctor prints the statements.
Pending migrations: supabase link --project-ref <ref>, then supabase db push. Ahena doesn't apply migrations or change RLS.
Copy the anon key into your app's environment yourself. Ahena doesn't fetch the anon or service-role keys.

Credentials and permissions

Name	Secret	Notes
`SUPABASE_ACCESS_TOKEN`	Yes	A personal access token (`sbp_…`), stored envelope-encrypted and bound to the environment.
`SUPABASE_PROJECT_REF`	No	The 20-letter project id. If you don't pass it, Ahena lists your projects and you pick one.

Least privilege

A Supabase personal access token can manage every project in the account and can't be scoped. Ahena reports it as personal-access-token:full-account and warns when you connect.
Ahena only calls endpoints covered by four OAuth scopes: projects:read, auth:read, auth:write and database:read.
Use a dedicated Supabase account or organization for production to limit what the token can reach.

Each credential Ahena stores gets its own key and is envelope-encrypted, bound to the environment. See security.

Workflow example

Connect, check, plan, then apply. Placeholders (…) stand for your own values.

```
SUPABASE_ACCESS_TOKEN=sbp_… ahena connect supabase -e production
```
Connect, then pick the project from the list (or pass --set SUPABASE_PROJECT_REF=…). You can also pipe the token or type it at a hidden prompt; never pass it as an argument.
```
ahena doctor -e production
```
Check project health, RLS, migrations and auth URLs.
```
ahena plan -e production
```
See every change needed to match ahena.config.ts, with its classification.
```
ahena apply -e production
```
Approve and apply. In production that approval happens in the dashboard, signed in.

ahena generate supabase -e production --framework nextjs

Write the database and auth layer into src/ahena/.

Verification status

Beta

Available in beta. Every capability is validated by Ahena's automated provider contract and conformance tests; verification against the real service is next.

How Supabase is tested

Supabase is tested against a simulated version of its Management API and contract fixtures, including the auth PATCH, the read-back after it and unknown-outcome recovery.
It hasn't been run against a real Supabase project yet. The real-provider harness is ready and needs a disposable ahena-test-* project.
The generated database and auth code is typechecked against supabase-js and also run in Ahena's tests with Ahena stopped.

The providers overview explains Ahena's testing methodology and what has been verified for every provider.

Limitations

No OAuth connection yet: personal access token only.
Ahena doesn't apply migrations or change RLS. It tells you exactly what to run.
Storage and edge functions aren't modelled.
Ahena never creates or deletes Supabase projects.

Disconnecting

ahena disconnect supabase deletes the token Ahena stored and links you to Supabase's token page to delete it there; projects, data, users and settings are untouched.