Push notifications

Firebase integration

Ahena works with your Firebase project: it checks Firebase Cloud Messaging can send, registers your iOS and Android apps, downloads their config files and generates server-side push code. Your server talks to FCM directly. Ahena is never in the push path.

BetaFull Firebase docs

What Ahena inspects

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

Whether the project is accessible to the service account.
Whether FCM can send, with a dry-run message (validateOnly): nothing is delivered.
Registered iOS and Android apps for your bundle id and package name, and whether the iOS app has an Apple Team ID.

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
Register a missing iOS or Android app	CONFIRMATION_REQUIRED	Ahena never deletes apps or projects.

Generated code: src/ahena/notifications (toDevice, toTopic, send, raw) and src/ahena/providers/firebase.ts, and downloads GoogleService-Info.plist and google-services.json for the registered apps.

How Ahena verifies

After every write, Ahena reads Firebase 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.

App registration is a long-running operation on Google's side. Ahena polls it with bounded backoff (about 20 seconds), then reads the apps back. An "already exists" answer after a retry counts as applied once the re-read confirms it.

If a request may have reached Firebase 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 Firebase docs.

Check	What it means
`firebase.credentials`	The key isn't a valid service account JSON.
`firebase.project`	Project accessible (otherwise: grant Firebase Viewer).
`firebase.fcm`	A `validate_only` send succeeds; tells a disabled API apart from a missing role.
`firebase.ios_app / firebase.android_app`	App registered for the configured bundle id or package.
`firebase.apns`	Firebase's public API doesn't expose whether an APNs key is uploaded, so Ahena shows the console steps instead of a ✓.

More on findings, health and continuous checks: Doctor.

Approvals

Firebase changes here are classified CONFIRMATION_REQUIRED. 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.

iOS: upload your APNs authentication key in the Firebase console (Project settings → Cloud Messaging). Ahena can't do this for you.
If Doctor reports the FCM API is disabled, enable it in Google Cloud for the project.
Android: add SHA certificate fingerprints if you use features that need them.
Add the Firebase client SDK to your apps to obtain device tokens.

Credentials and permissions

Name	Secret	Notes
`FIREBASE_SERVICE_ACCOUNT`	Yes	The service account JSON key, piped to `ahena connect firebase`. Ahena always uses Google's token endpoint and ignores `token_uri` in the file.
`FIREBASE_PROJECT_ID`	No	Discovered from the key if not given.

Least privilege

Grant the service account only Firebase Viewer (inspection and config download) and Firebase Cloud Messaging API Admin (FCM validation). Add Firebase Admin only if you want Ahena to register apps.
When you connect, Ahena asks Google which of the permissions it needs the service account holds (Cloud Resource Manager testIamPermissions, a read-only call) and reports each as granted or missing. If that API is disabled, they're reported as unknown and a missing role shows up as a 403 in Doctor.

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.

ahena connect firebase -e production < key.json

Pipe the service account key in.

```
ahena doctor -e production
```
Check project access, an FCM dry run and app registration.
```
ahena plan -e production
```
See which apps would be registered.
```
ahena apply -e production
```
Approve and apply; Ahena polls the registration and reads the apps back.
```
ahena generate firebase -e production
```
Write push code and download the apps' config files.

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 Firebase is tested

Firebase is tested against a simulated version of its APIs and contract fixtures, including operation polling, pagination and the read-back after each write.
It hasn't been run against a real Firebase project yet. The real-provider harness is ready and needs a disposable ahena-test-* project.
Permission detection is partial: the connection doesn't check the service account's roles (see Credentials and permissions).
The generated push code is typechecked against firebase-admin, not run.

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

Limitations

APNs key status can't be read through the API.
App registration is asynchronous on Google's side; Doctor shows it once it's live.
Ahena doesn't send real notifications. Use the Firebase console's test send to try a device.

Disconnecting

ahena disconnect firebase removes the stored key (delete it under Google Cloud's service account keys); apps, tokens and messages are untouched.