sveltekit-firebase-helpers 0.0.1

package/README.md

@@ -0,0 +1,158 @@
+# sveltekit-firebase-helpers
+
+Helpers for using Firebase with SvelteKit. Because I always end up with the same code on every SvelteKit + Firebase project I have ...
+
+## Firebase Auth Gotchas
+
+When using Firebase Auth, the protocol of the auth service needs to match that of your app. What are the implications of this?
+
+Well, if you're using the _live_ Firebase Auth service you need to use `https` even when running in local dev mode which can be achieved via the `vite-plugin-mkcert` package. You will also need to make sure that your app follows the [Best practices for using signInWithRedirect on browsers that block third-party storage access](https://firebase.google.com/docs/auth/web/redirect-best-practices) which, spoiler, you should do via Option 3 of that article (and what this package helps with). You _could_ use `signInWithPopup` but you really shouldn't as it comes with its own problems.
+
+If you're using the Auth Emulator you have two options. It runs on `http` only so will work fine if you _don't_ include the `vite-plugin-mkcert` package in your vite config (but silently fail if you do). If you _do_ need `https` locally for other reasons you can use [Caddy](https://caddyserver.com/) as a reverse proxy to provide the secure access to it. Personally, I prefer to toggle the vite config so I don't have to install and start another service which keeps the project neat and self-contained.
+
+Finally, how do you sync the client-side auth state to your server? If you only use firebase-hosted services you don't need to, but if you have code on your server that needs to know the identity of the user, such as a shopping cart checkout, it will be important. How do you do this?
+
+You _could_ check for the ID Token changing on the client, and send a fetch request to your own server to mirror the state using a cookie, but there are subtle issues with this - the ID Token is automatically refreshed when calling firebase services but the one in the cookie may end up out-of-date if you're calling your own server. You also then have state in two different places, potentially out-of-sync, which is not ideal.
+
+A better option is to implement [Session management with service workers](https://firebase.google.com/docs/auth/web/service-worker-sessions) where the existing client-side auth state is used to automatically add an Authorization bearer token to each server request - it will even handle an initial page load if you need the auth state for SSR. Adding this auth token is something else this package can help with.
+
+It also handles some edge cases you may otherwise struggle with. Picture this - in response to a form POST action you want to update the custom claims for a user, maybe to indicate which service plan they are now on or that they have some new permission. You might _expect_ to do the form post, have the `invalidateAll()` method called (which Svelte's `use:enhance` form action does for you by default) and see your freshly loaded data based on the claim you set during the server action. Except it won't. The Firebase client-side lib syncs the auth state of the main thread with the service-worker but it does it via polling so there can be a half-second or so where it doesn't have the latest auth token, or any auth token at all if you have just loaded a page from a sign-in redirect. Again, this is something this package can help with by providing it's own temporary auth-token-syncing for those situations just to ensure the state seen by the service-worker is completely up-to-date.
+
+Oh, and one other issue - SvelteKit is often very opinionated but sometimes those opinions are a little blinkered. You can't, for instance, use _dynamic_ .env variables in your service-worker code, only _static_ ones which just doesn't cut-it for serious work - you should be able to deploy the same compiled code / docker image to different environments and have it work, having to compile a specific version for each one is tedious and error prone. Anyway, we built something in to handle this as well to save you the work of figuring it out.
+
+## Usage
+
+How to use the features of the package. Of course, you need to install it using the package manager of your choice (which should be `pnpm`):
+
+    pnpm i svelte-firebase-helpers
+
+### Server Hooks
+
+The server-side helpers are added as handlers in your app [server hooks](https://svelte.dev/docs/kit/hooks#Server-hooks). You can add them separately (using `sequence` if you have multiple handlers) or use a single call to add them all. Let's go through each one individually first:
+
+#### Auth Handle
+
+To decode any http `Authorization` header added by the service-worker use `createAuthHandle` passing in the `firebase-admin/auth` instance it needs to decode the firebase ID token:
+
+```ts
+import { createAuthHandle } from "svelte-firebase-helpers";
+import { auth } from './firebase.server'
+
+export const handle = createAuthHandle(auth)
+```
+
+Any requests with an `Authorication Bearer [token]` header will now be decoded and added as a `locals.user` property.
+
+#### Options Handle
+
+The service-worker needs access to the firebase config, but SveleKit conspires to make that difficult to import. To get around this we provide our own server-endpoint that the service-worker can request it from.
+
+```ts
+import { createOptionsHandle } from "svelte-firebase-helpers";
+import { options } from './firebase'
+
+export const handle = createOptionsHandle(options)
+```
+
+Example `options.ts`:
+
+```ts
+import { dev } from '$app/environment'
+import {
+  PUBLIC_FIREBASE_API_KEY,
+  PUBLIC_FIREBASE_AUTH_DOMAIN,
+  PUBLIC_FIREBASE_DATABASE_URL,
+  PUBLIC_FIREBASE_PROJECT_ID,
+  PUBLIC_FIREBASE_STORAGE_BUCKET,
+  PUBLIC_FIREBASE_MESSAGING_SENDER_ID,
+  PUBLIC_FIREBASE_APP_ID,
+  PUBLIC_FIREBASE_MEASUREMENT_ID
+} from '$env/static/public'
+
+export const options = {
+  apiKey: PUBLIC_FIREBASE_API_KEY,
+  authDomain: dev ? 'localhost:5173' : PUBLIC_FIREBASE_AUTH_DOMAIN,
+  databaseURL: PUBLIC_FIREBASE_DATABASE_URL,
+  projectId: PUBLIC_FIREBASE_PROJECT_ID,
+  storageBucket: PUBLIC_FIREBASE_STORAGE_BUCKET,
+  messagingSenderId: PUBLIC_FIREBASE_MESSAGING_SENDER_ID,
+  appId: PUBLIC_FIREBASE_APP_ID,
+  measurementId: PUBLIC_FIREBASE_MEASUREMENT_ID
+}
+```
+
+You can test the handle is working correctly by requesting the `/__/firebase/init.json` endpoint in your app. You should see the client-side Firebase Options config returned (which is perfectly safe and normal to send to the client for the client-side Firebase libraries to work).
+
+#### Proxy Handle
+
+To proxy auth requests so you can use `signInWithRedirect` on browsers that block 3rd party cookies (now all of them) use `createAuthHandle` passing in the `application-id.firebaseapp.com` domain name from you Firebase app config, e.g. `captaincodeman-experiment.firebaseapp.com`.
+
+```ts
+import { createOptionsHandle } from "svelte-firebase-helpers";
+import { env } from '$env/dynamic/public'
+
+const auth_domain = env.PUBLIC_FIREBASE_AUTH_DOMAIN
+
+export const handle = createProxyHandle(auth_domain)
+```
+
+Any requests to `/__/auth/...` will be proxied to the `auth_domain` configured, effectively making your app serve the firebase auth endpoints itself to get around the 3rd party cookie restrictions.
+
+#### Combined Handle
+
+An alternative is to use a single combined `createHandle` function that will add each individual handle if the property it needs is included.
+
+So pass the `auth` instance (`firebase-admin/auth`) and it will add the Auth Handle. Pass the `options` object and it will add the Options Handle. Pass the `auth_domain` and the Proxy Handle will be added.
+
+```ts
+import { env } from '$env/dynamic/public'
+import { createHandle } from 'svelte-firebase-helpers'
+import { options } from './routes/firebase'
+import { auth } from './routes/firebase-server'
+
+const auth_domain = env.PUBLIC_FIREBASE_AUTH_DOMAIN
+
+export const handle = createHandle({ auth, options, auth_domain })
+```
+
+### Service Worker
+
+To automatically add the `Authentication Bearer [idToken]` http header to each server request, use the `addFirebaseAuth` method in your service worker. If running against the Firebase Auth Emulator pass that as a separate `auth_emulator` parameter. The service-worker code will automatically request and use the `/__/firebase/init.json` endpoint provided by the Options Handle above so it needs to be added to the Server Hooks.
+
+```ts
+/// <reference types="@sveltejs/kit" />
+/// <reference no-default-lib="true"/>
+/// <reference lib="esnext" />
+/// <reference lib="webworker" />
+
+import { addFirebaseAuth } from 'svelte-firebase-helpers'
+
+addFirebaseAuth({
+  auth_emulator: 'http://localhost:9099'  // if using the Firebase Auth Emulator
+})
+```
+
+NOTE: when using a service-worker for firebase state, you _must_ implement [custom auth initialization](https://firebase.google.com/docs/auth/web/custom-dependencies#when_to_use_custom_initialization) specifically using `indexedDBLocalPersistence` for persistence. This is handled in the `addFirebaseAuth` implementation but for your own firebase client you can initialize it using:
+
+```ts
+import {
+  browserPopupRedirectResolver,
+  getAuth,
+  indexedDBLocalPersistence,
+  initializeAuth,
+ } from 'firebase/auth'
+import { app } from './app'
+import { browser } from '$app/environment'
+
+// SSR friendly auth initialization
+export const auth = browser
+  ? initializeAuth(app, {
+      persistence: [indexedDBLocalPersistence],
+      popupRedirectResolver: browserPopupRedirectResolver,
+    })
+  : getAuth(app)
+```
+
+The `browser` check is to avoid an error if using SSR.
+
+One additional advantage of this is that your client-side auth dependencies are reduced so your app should start faster (you can also avoid loading the `popupRedirectResolver` for initialization and pass it to methods like `signInWithRedirect` when called for even greater savings).

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+import { Auth } from 'firebase/auth';
+import { Handle } from '@sveltejs/kit';
+import { Auth as Auth$1, DecodedIdToken } from 'firebase-admin/auth';
+import { FirebaseOptions } from 'firebase/app';
+
+declare function syncAuthToken(auth: Auth): Promise<void>;
+
+declare function createAuthHandle(auth: Auth$1): Handle;
+
+declare function createOptionsHandle(options: FirebaseOptions): Handle;
+
+declare function createProxyHandle(auth_domain: string, init?: HeadersInit): Handle;
+
+declare function createHandle(config: {
+    auth?: Auth$1;
+    options?: FirebaseOptions;
+    auth_domain?: string;
+    init?: HeadersInit;
+}): Handle;
+
+declare global {
+    namespace App {
+        interface Locals {
+            user: DecodedIdToken | null;
+        }
+    }
+}
+
+/// <reference no-default-lib="true"/>
+declare function addFirebaseAuth(config: {
+    auth_emulator?: string;
+}): void;
+
+export { addFirebaseAuth, createAuthHandle, createHandle, createOptionsHandle, createProxyHandle, syncAuthToken };

package/dist/index.js

@@ -0,0 +1 @@
+import{getIdToken as k}from"firebase/auth";async function C(t){if(t.currentUser){let o=await k(t.currentUser,!0),{serviceWorker:n}=navigator,{controller:r}=n;r&&await new Promise(c=>{n.addEventListener("message",()=>c(),{once:!0}),r.postMessage({type:"useToken",useToken:o})})}}function y(t){return async({event:n,resolve:r})=>{let{locals:c,request:e}=n,s=e.headers.get("Authorization")?.split("Bearer ")[1];if(s)try{c.user=await t.verifyIdToken(s)}catch(a){console.error(a)}return r(n)}}var g=globalThis.process?.env?.NODE_ENV,_=g&&!g.toLowerCase().startsWith("prod");function w(t,o){let n=JSON.stringify(t),r=new Headers(o?.headers);return r.has("content-length")||r.set("content-length",b.encode(n).byteLength.toString()),r.has("content-type")||r.set("content-type","application/json"),new Response(n,{...o,headers:r})}var b=new TextEncoder;function H(t){return async({event:n,resolve:r})=>{let{request:c,url:e}=n;return c.method==="GET"&&e.pathname.startsWith("/__/firebase/init.json")?(console.log("handle options"),w(t)):r(n)}}function T(t,o){return async({event:r,resolve:c})=>{let{request:e,url:i}=r;if(e.method==="GET"&&i.pathname.startsWith("/__/auth/")){console.log("handle proxy",t),i.host=t,i.port="443";let s=await fetch(i,{headers:{"Accept-Encoding":"identity"}}),a=await s.text(),u=new Headers({...o,"Cache-Control":s.headers.get("Cache-Control"),"Content-Type":s.headers.get("Content-Type"),Vary:"accept-encoding"});return new Response(a,{headers:u})}return c(r)}}function l(...t){let o=t.length;return o?({event:n,resolve:r})=>{return c(0,n,{});function c(e,i,s){let a=t[e];return a({event:i,resolve:(u,f)=>{let p=async({html:d,done:x})=>(f?.transformPageChunk&&(d=await f.transformPageChunk({html:d,done:x})??""),s?.transformPageChunk&&(d=await s.transformPageChunk({html:d,done:x})??""),d),h=s?.filterSerializedResponseHeaders??f?.filterSerializedResponseHeaders,m=s?.preload??f?.preload;return e<o-1?c(e+1,u,{transformPageChunk:p,filterSerializedResponseHeaders:h,preload:m}):r(u,{transformPageChunk:p,filterSerializedResponseHeaders:h,preload:m})}})}}:({event:n,resolve:r})=>r(n)}function ye(t){let o=[];return t.auth&&o.push(y(t.auth)),t.options&&o.push(H(t.options)),t.auth_domain&&o.push(T(t.auth_domain,t.init)),l(...o)}import{initializeApp as E}from"firebase/app";import{getIdToken as R,initializeAuth as S,connectAuthEmulator as j,indexedDBLocalPersistence as O}from"firebase/auth";function He(t){let o=new Promise(async(e,i)=>{let a=await(await fetch("/__/firebase/init.json")).json(),u=E(a),f=S(u,{persistence:[O]});t.auth_emulator&&j(f,t.auth_emulator),await f.authStateReady(),e(f)}),n;self.addEventListener("message",e=>{function i(){self.clients.matchAll({}).then(function(s){s&&s.length&&s[0].postMessage({ack:!0})})}if(e.data)switch(e.data.type){case"useToken":n=e.data.useToken,i(),setTimeout(()=>n=void 0,5e3);break}});async function r(){let e=await o;if(e.currentUser)try{return await R(e.currentUser)}catch{return null}else return null}async function c(e){try{if(e.method!=="GET")if(e.headers.get("Content-Type")?.indexOf("json")!==-1){let i=await e.json();return JSON.stringify(i)}else return e.text()}catch{}}self.addEventListener("fetch",e=>{if(new URL(e.request.url).origin!==location.origin)return;async function s(){let a=e.request,u=n??await r();if(u){let f=new Headers(a.headers);f.append("Authorization","Bearer "+u);let p=await c(a);try{a=new Request(a.url,{method:a.method,headers:f,mode:"same-origin",credentials:a.credentials,cache:a.cache,redirect:a.redirect,referrer:a.referrer,body:p})}catch{}}return fetch(a)}e.respondWith(s())})}export{He as addFirebaseAuth,y as createAuthHandle,ye as createHandle,H as createOptionsHandle,T as createProxyHandle,C as syncAuthToken};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "sveltekit-firebase-helpers",
+  "description": "Helpers for using Firebase with SvelteKit",
+  "version": "0.0.1",
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "!dist/**/*.spec.*"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "svelte": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "svelte": "./dist/index.js"
+    }
+  },
+  "peerDependencies": {
+    "firebase": "^11.0.0",
+    "firebase-admin": "^13.0.0",
+    "svelte": "^5.0.0"
+  },
+  "devDependencies": {
+    "@sveltejs/adapter-auto": "^6.0.0",
+    "@sveltejs/kit": "^2.16.0",
+    "@sveltejs/vite-plugin-svelte": "^5.0.0",
+    "esm-env": "^1.2.2",
+    "firebase": "^11.9.1",
+    "firebase-admin": "^13.4.0",
+    "prettier": "^3.4.2",
+    "prettier-plugin-svelte": "^3.3.3",
+    "publint": "^0.3.2",
+    "svelte": "^5.0.0",
+    "svelte-check": "^4.0.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.0.0",
+    "vite": "^6.2.6",
+    "vite-plugin-devtools-json": "^0.2.0",
+    "vite-plugin-mkcert": "^1.17.8"
+  },
+  "keywords": [
+    "svelte"
+  ],
+  "scripts": {
+    "dev": "vite dev",
+    "build": "vite build && npm run prepack",
+    "preview": "vite preview",
+    "check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
+    "check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
+    "format": "prettier --write .",
+    "lint": "prettier --check .",
+    "emulators:start": "firebase emulators:start --only auth"
+  }
+}