AHENA
Documentation menu

Providers

Firebase

Uses the Ahena CLI (beta). Install it with npm install -g @ahena/cli, or prefix commands with npx @ahena/cli. See Installation. The dashboard covers projects, connections, Doctor, the Stack Graph, plans and approvals without it.

Overview

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

Package: @ahena/provider-firebase · Category: push Capabilities: fcm, mobile-config, apns-readiness

Connection

Field Secret Notes
FIREBASE_SERVICE_ACCOUNT yes The service account JSON key (Project settings → Service accounts → Generate new private key). Pipe it: ahena connect firebase < key.json.
FIREBASE_PROJECT_ID no Discovered from the key/account if not given.

Ahena signs a short-lived OAuth assertion itself (RS256 via WebCrypto, so it works on Workers). It always uses Google's token endpoint and ignores token_uri in the key file, so a tampered key can't redirect the signed assertion.

Permissions

Grant the service account only:

  • Firebase Viewer (roles/firebase.viewer): project and app inspection, config download
  • Firebase Cloud Messaging API Admin (roles/firebasecloudmessaging.admin): FCM validation
  • Firebase Admin: only if you want Ahena to register apps

OAuth scopes requested per call: firebase.readonly (reads), firebase.messaging (FCM validation), and firebase only when registering an app you approved.

Capabilities

Capability What Ahena does
fcm Validates sending with a dry-run message (validateOnly, nothing delivered); generates server push code.
mobile-config Registers iOS/Android apps (after approval) and downloads GoogleService-Info.plist / google-services.json.
apns-readiness Checks iOS apps are set up for APNs delivery.

Network: oauth2.googleapis.com, firebase.googleapis.com, fcm.googleapis.com (enforced). ahena lock tracks registered apps for drift. ahena add notifications adds device registration and an inbox on top.

Configure

push: {
  provider: "firebase",
  ios: { bundleId: "com.example.leo" },
  android: { packageName: "com.example.leo" },
  iosDir: "ios/Leo",            // where GoogleService-Info.plist goes
  androidDir: "android/app",    // where google-services.json goes
},

Registering a missing app is CONFIRMATION_REQUIRED. Ahena never deletes apps or projects.

Generate

ahena generate firebase writes src/ahena/notifications (toDevice, toTopic, send, raw), src/ahena/providers/firebase.ts, and downloads GoogleService-Info.plist and google-services.json for the registered apps. These contain public identifiers, not secrets.

Doctor checks

Id Severity Meaning
firebase.credentials FAIL Key isn't a valid service account JSON.
firebase.project PASS / FAIL Project accessible (else: grant Firebase Viewer).
firebase.fcm PASS / FAIL validate_only send succeeds; distinguishes a disabled API from a missing role. Nothing is delivered.
firebase.ios_app / firebase.android_app PASS / FAIL App registered for the configured bundle id / package.
firebase.ios_team WARNING iOS app has no Apple Team ID.
firebase.apns INFO Firebase's public API doesn't expose whether an APNs key is uploaded, so Ahena shows the console steps instead of a ✓.

Manual steps

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

Limitations

  • APNs key status can't be read through the API (see above).
  • 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.

Disconnect behavior

Removes the connection and the key Ahena stored. Delete the key in Google Cloud console → IAM → Service accounts → Keys. Apps, tokens and messages are untouched.