@al-hamoud/authx-server

Server-only Firebase Admin auth utilities with:

• Safe Admin singleton init (env or explicit config)
• Simple, typed API (verifyIdToken, getUser, setCustomClaims)
• Functional Result monad (Ok/Err) for error handling
• SSOT validation via arktype (JWT idToken, E.164 phone, uid, config)
• Drop-in adapters for Next.js App Router and Express
• Full CORS helpers (allowlist, credentials, methods/headers, preflight)

Node runtime only. Designed for Next.js API routes (nodejs runtime), Express/Fastify, and serverless.

Install

npm i @al-hamoud/authx-server

Requires Node >= 18.

Environment variables

Use the same names as in your app (e.g., authx-ex1):

• FIREBASE_PROJECT_ID
• FIREBASE_CLIENT_EMAIL
• FIREBASE_PRIVATE_KEY (supports \\n restoration)
• Optional: FIREBASE_SERVICE_ACCOUNT_JSON (stringified service account)

Quick start (framework-agnostic)

import { initAdmin, verifyIdToken, getUser, setCustomClaims } from "@al-hamoud/authx-server";

// Optionally call once at boot; otherwise functions will lazy-init from env
initAdmin();

const result = await verifyIdToken(idToken, { checkRevoked: false });
if (result.ok) {
  const user = result.data; // { id, phone?, email?, claims? }
} else {
  // result.error: { code: 'INVALID_TOKEN' | 'EXPIRED_TOKEN' | ... , message }
}

Quick start (Next.js App Router)

// app/api/auth/verify-id-token/route.ts
import { createNextVerifyHandler, createNextHealthHandler } from "@al-hamoud/authx-server/adapters/next";

export const runtime = "nodejs"; // REQUIRED: Firebase Admin runs on Node, not Edge

export const POST = createNextVerifyHandler({
  checkRevoked: false,
  cors: {
    allowOrigins: ["https://your.app"],
    credentials: false,
  },
});

export const GET = createNextHealthHandler();

Result monad in a nutshell

All public APIs return Promise<Result<T, E>>:

• Ok<T>(data) => { ok: true, data }
• Err<E>(error) => { ok: false, error }
• Helpers: map, mapError, andThen

Error codes are stable and typed:

• INVALID_INPUT (validation via arktype failed)
• INVALID_TOKEN, EXPIRED_TOKEN, REVOKED_TOKEN
• CONFIG_MISSING, ADMIN_INIT_FAILED
• USER_NOT_FOUND, INTERNAL

Validation (SSOT)

• idToken: base64url JWT triplet
• phone: E.164 strict (+ plus up to 15 digits)
• uid: non-empty string, up to 128 chars (permissive)
• config: required env variables present and non-empty

CORS (full job)

• Allowlist origins: string | string[] | RegExp | ((origin) => boolean)
• Options: credentials, methods, headers, maxAge
• Robust OPTIONS preflight responder
• Secure defaults: methods: ["GET","POST","OPTIONS"], credentials: false

CSP/connect-src guidance

Allow Firebase Auth endpoints in your app’s CSP connect-src (the library does not modify CSP):

• https://apis.google.com
• https://*.googleapis.com
• https://identitytoolkit.googleapis.com
• https://securetoken.googleapis.com
• https://firebaseinstallations.googleapis.com

API reference (summary)

• initAdmin(config?) => Result<true, Error>
• health() => Result<{ adminInitialized: boolean; projectId?: string }, Error>
• verifyIdToken(idToken, { checkRevoked? }) => Result<{ id: string; phone?: string; email?: string; claims?: Record<string, unknown> }, Error>
• getUser(uid) => Result<{ id: string; phone?: string; email?: string; disabled?: boolean; providerIds?: string[] }, Error>
• setCustomClaims(uid, claims) => Result<true, Error>

See detailed docs and examples in the sections above once implementation is complete.

License

MIT © AL-Hamoud LTD