{"_id":"@al-hamoud/authx-server","name":"@al-hamoud/authx-server","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@al-hamoud/authx-server","version":"0.1.0","description":"Server-only Firebase Admin auth utilities with Result monad, SSOT validation, Next.js/Express adapters.","license":"MIT","repository":{"type":"git","url":"git+https://github.com/AL-Hamoud-LTD/authx-server.git"},"type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"},"./adapters/next":{"types":"./dist/adapters/next/index.d.ts","import":"./dist/adapters/next/index.js","require":"./dist/adapters/next/index.cjs"},"./adapters/express":{"types":"./dist/adapters/express/index.d.ts","import":"./dist/adapters/express/index.js","require":"./dist/adapters/express/index.cjs"},"./package.json":"./package.json"},"engines":{"node":">=18"},"sideEffects":false,"scripts":{"build":"tsup","dev":"tsup --watch","typecheck":"tsc --noEmit","prepare":"npm run build"},"dependencies":{"arktype":"^2.1.22","firebase-admin":"^12.0.0"},"devDependencies":{"@types/node":"^20.11.0","tsup":"^8.0.1","typescript":"^5.6.3"},"keywords":["firebase-admin","nextjs","express","auth","result","monad","arktype"],"_id":"@al-hamoud/authx-server@0.1.0","gitHead":"66a6cdebd9b8298e113fb3c548a2662ae58fc345","bugs":{"url":"https://github.com/AL-Hamoud-LTD/authx-server/issues"},"homepage":"https://github.com/AL-Hamoud-LTD/authx-server#readme","_nodeVersion":"22.19.0","_npmVersion":"11.5.2","dist":{"integrity":"sha512-t1aiTMw5OeXJGuMK+gl2tojqbEz7dSYlFvupfPdHEs2RR2u8eVlgzhOk8MRUZWWDio3JBeYNvIbOXkgZc5Cnxg==","shasum":"17db93617c6e4bdb0780a30ab66bb9ffc4eb7320","tarball":"https://registry.npmjs.org/@al-hamoud/authx-server/-/authx-server-0.1.0.tgz","fileCount":23,"unpackedSize":177318,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIAl02vhahbJRSpzUa9RV5ZUiMhJthHRHw48yOy7aTAa8AiBO4S4fBSc/sct5WUqs00j15KTPlqB5F8yfjNrA0qtb7w=="}]},"_npmUser":{"name":"al-hamoud","email":"ihsan.alhamoud@gmail.com"},"directories":{},"maintainers":[{"name":"al-hamoud","email":"ihsan.alhamoud@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/authx-server_0.1.0_1760121342353_0.6625791007249844"},"_hasShrinkwrap":false}},"time":{"created":"2025-10-10T18:35:42.180Z","0.1.0":"2025-10-10T18:35:42.543Z","modified":"2025-10-10T18:35:42.830Z"},"maintainers":[{"name":"al-hamoud","email":"ihsan.alhamoud@gmail.com"}],"description":"Server-only Firebase Admin auth utilities with Result monad, SSOT validation, Next.js/Express adapters.","homepage":"https://github.com/AL-Hamoud-LTD/authx-server#readme","keywords":["firebase-admin","nextjs","express","auth","result","monad","arktype"],"repository":{"type":"git","url":"git+https://github.com/AL-Hamoud-LTD/authx-server.git"},"bugs":{"url":"https://github.com/AL-Hamoud-LTD/authx-server/issues"},"license":"MIT","readme":"# @al-hamoud/authx-server\r\n\r\nServer-only Firebase Admin auth utilities with:\r\n\r\n- Safe Admin singleton init (env or explicit config)\r\n- Simple, typed API (verifyIdToken, getUser, setCustomClaims)\r\n- Functional Result monad (Ok/Err) for error handling\r\n- SSOT validation via arktype (JWT idToken, E.164 phone, uid, config)\r\n- Drop-in adapters for Next.js App Router and Express\r\n- Full CORS helpers (allowlist, credentials, methods/headers, preflight)\r\n\r\n> Node runtime only. Designed for Next.js API routes (nodejs runtime), Express/Fastify, and serverless.\r\n\r\n## Install\r\n\r\n```bash\r\nnpm i @al-hamoud/authx-server\r\n```\r\n\r\nRequires Node >= 18.\r\n\r\n## Environment variables\r\n\r\nUse the same names as in your app (e.g., authx-ex1):\r\n\r\n- `FIREBASE_PROJECT_ID`\r\n- `FIREBASE_CLIENT_EMAIL`\r\n- `FIREBASE_PRIVATE_KEY` (supports `\\\\n` restoration)\r\n- Optional: `FIREBASE_SERVICE_ACCOUNT_JSON` (stringified service account)\r\n\r\n## Quick start (framework-agnostic)\r\n\r\n```ts\r\nimport { initAdmin, verifyIdToken, getUser, setCustomClaims } from \"@al-hamoud/authx-server\";\r\n\r\n// Optionally call once at boot; otherwise functions will lazy-init from env\r\ninitAdmin();\r\n\r\nconst result = await verifyIdToken(idToken, { checkRevoked: false });\r\nif (result.ok) {\r\n  const user = result.data; // { id, phone?, email?, claims? }\r\n} else {\r\n  // result.error: { code: 'INVALID_TOKEN' | 'EXPIRED_TOKEN' | ... , message }\r\n}\r\n```\r\n\r\n## Quick start (Next.js App Router)\r\n\r\n```ts\r\n// app/api/auth/verify-id-token/route.ts\r\nimport { createNextVerifyHandler, createNextHealthHandler } from \"@al-hamoud/authx-server/adapters/next\";\r\n\r\nexport const runtime = \"nodejs\"; // REQUIRED: Firebase Admin runs on Node, not Edge\r\n\r\nexport const POST = createNextVerifyHandler({\r\n  checkRevoked: false,\r\n  cors: {\r\n    allowOrigins: [\"https://your.app\"],\r\n    credentials: false,\r\n  },\r\n});\r\n\r\nexport const GET = createNextHealthHandler();\r\n```\r\n\r\n## Result monad in a nutshell\r\n\r\nAll public APIs return `Promise<Result<T, E>>`:\r\n\r\n- `Ok<T>(data)` => `{ ok: true, data }`\r\n- `Err<E>(error)` => `{ ok: false, error }`\r\n- Helpers: `map`, `mapError`, `andThen`\r\n\r\nError codes are stable and typed:\r\n\r\n- `INVALID_INPUT` (validation via arktype failed)\r\n- `INVALID_TOKEN`, `EXPIRED_TOKEN`, `REVOKED_TOKEN`\r\n- `CONFIG_MISSING`, `ADMIN_INIT_FAILED`\r\n- `USER_NOT_FOUND`, `INTERNAL`\r\n\r\n## Validation (SSOT)\r\n\r\n- idToken: base64url JWT triplet\r\n- phone: E.164 strict (`+` plus up to 15 digits)\r\n- uid: non-empty string, up to 128 chars (permissive)\r\n- config: required env variables present and non-empty\r\n\r\n## CORS (full job)\r\n\r\n- Allowlist origins: string | string[] | RegExp | ((origin) => boolean)\r\n- Options: `credentials`, `methods`, `headers`, `maxAge`\r\n- Robust OPTIONS preflight responder\r\n- Secure defaults: `methods: [\"GET\",\"POST\",\"OPTIONS\"]`, `credentials: false`\r\n\r\n## CSP/connect-src guidance\r\n\r\nAllow Firebase Auth endpoints in your app’s CSP `connect-src` (the library does not modify CSP):\r\n\r\n- `https://apis.google.com`\r\n- `https://*.googleapis.com`\r\n- `https://identitytoolkit.googleapis.com`\r\n- `https://securetoken.googleapis.com`\r\n- `https://firebaseinstallations.googleapis.com`\r\n\r\n## API reference (summary)\r\n\r\n- `initAdmin(config?) => Result<true, Error>`\r\n- `health() => Result<{ adminInitialized: boolean; projectId?: string }, Error>`\r\n- `verifyIdToken(idToken, { checkRevoked? }) => Result<{ id: string; phone?: string; email?: string; claims?: Record<string, unknown> }, Error>`\r\n- `getUser(uid) => Result<{ id: string; phone?: string; email?: string; disabled?: boolean; providerIds?: string[] }, Error>`\r\n- `setCustomClaims(uid, claims) => Result<true, Error>`\r\n\r\nSee detailed docs and examples in the sections above once implementation is complete.\r\n\r\n## License\r\n\r\nMIT © AL-Hamoud LTD\r\n","readmeFilename":"README.md","_rev":"1-e03caa717627b49d3cbf56394e8682fb"}