Firemitt

Fireguards are hot, but not enough to burn. As long as you got your mitts on.

Description

Firemitt is a client-side integration package for Fireguard, a Firebase authentication middleman app. It handles the full lifecycle of an auth flow: opening the Fireguard window (popup or iframe), passing configuration, and resolving or rejecting based on the authentication result.

It is particularly useful for browser extensions and web apps operating under Manifest V3 restrictions, where direct Firebase SDK usage is limited or blocked.

Features

• Popup authentication: FiremittHelper.auth opens a Fireguard popup window, manages the auth handshake, and returns a promise that resolves with the token on success or rejects on failure.
• Iframe authentication: Optionally embed Fireguard inside an iframe by setting mode: "iframe". Provide an existing iframe element or a container element and Firemitt manages the lifecycle.
• Flexible configuration: Control the popup position, dimensions, app name, logo, Firebase credentials, auth provider, and theme with a single options object.
• Custom theming: Pass primary, secondary, text, and background colors to style the Fireguard UI to match your app.
• Multiple auth providers: Choose from Google, GitHub, Facebook, Twitter, Microsoft, Apple, or Yahoo via the provider field.
• Event-driven internals: EventHelper provides a clean interface for sending and receiving cross-window events used by the auth flow.
• Config validation: ConfigHelper validates and normalizes Fireguard options before they are used, catching missing or malformed values early.

Installation

pnpm add @eoussama/firemitt
Copy

Usage

Popup authentication

FiremittHelper.auth is the main entry point. It opens a Fireguard popup window, passes your configuration to it, and returns a promise that resolves with the auth token on success.

import { FiremittHelper } from "@eoussama/firemitt";

const options = {

  // URL of the Fireguard instance (use the hosted one or a self-hosted deployment)
  url: "https://ouss.es/fireguard",

  // Optional: position of the popup window
  pos: {
    y: 50,
    x: (window.screen.width / 2) - 500
  },

  // Optional: dimensions of the popup window
  dim: {
    width: 450,
    height: 260
  },

  config: {
    name: "My App Name",

    // Optional: authentication provider (default: "google")
    provider: "google",

    // Optional: URL to your app's logo
    logo: "https://url/to/your/logo/image",

    // Optional: custom theme colors
    theme: {
      text: "#1a3544",
      primary: "#ffe536",
      secondary: "#1a3544",
      background: "#ffffff"
    },

    // Your web app's Firebase configuration
    firebase: {
      appId: "",
      apiKey: "",
      projectId: "",
      authDomain: "",
      measurementId: "",
      storageBucket: "",
      messagingSenderId: ""
    }
  }
};

FiremittHelper.auth(options)
  .then((token) => {
    console.warn("Authentication successful!", token);
  })
  .catch((error) => {
    console.error("Authentication failed:", error);
  });
Copy

Iframe authentication

Set mode: "iframe" and provide either a container (Firemitt creates and manages the iframe) or an existing element (Firemitt loads Fireguard into it without managing its lifecycle).

// Auto-created iframe inside a container element
FiremittHelper.auth({
  url: "https://ouss.es/fireguard",
  mode: "iframe",
  iframe: { container: document.getElementById("auth-container")! },
  config: { name: "My App", firebase: { /* ... */ } }
});

// Existing iframe element
FiremittHelper.auth({
  url: "https://ouss.es/fireguard",
  mode: "iframe",
  iframe: { element: document.getElementById("auth-frame") as HTMLIFrameElement },
  config: { name: "My App", firebase: { /* ... */ } }
});
Copy

You can point url at the hosted Fireguard instance (https://ouss.es/fireguard) or your own self-hosted deployment.

Note: Firebase only allows sign-in popups from authorized domains. If you are using a self-hosted Fireguard deployment, add its domain to the authorized domains list in the Firebase Console under Authentication → Settings → Authorized domains. Skipping this step will cause the authentication popup to be blocked.

Configuration

TFiremittOptions

Property	Type	Required	Description
url	string	✓	URL of the Fireguard instance to open.
mode	"popup" | "iframe"		Authentication mode. Defaults to "popup".
iframe	TIframeOptions		Required when mode is "iframe". Provide either an existing element or a container.
pos	Partial<TPos>		Position of the popup window on screen. Ignored in iframe mode.
dim	Partial<TDim>		Dimensions of the popup or auto-created iframe.
config	Partial<TFireguardOptions>		Fireguard configuration passed to the auth window.

TIframeOptions

Property	Type	Required	Description
element	HTMLIFrameElement	✓ (or container)	Existing iframe element to load Fireguard into.
container	HTMLElement	✓ (or element)	Container element where Firemitt creates and appends an iframe automatically.

TPos

Property	Type	Required	Description
x	number	✓	Horizontal position of the popup window in pixels.
y	number	✓	Vertical position of the popup window in pixels.

TDim

Property	Type	Required	Description
width	number	✓	Width of the popup or auto-created iframe in pixels.
height	number	✓	Height of the popup or auto-created iframe in pixels.

TFireguardOptions

Property	Type	Required	Description
name	string	✓	Display name of your application shown in the Fireguard UI.
firebase	TFirebaseConfig	✓	Firebase project configuration used to initialize authentication.
logo	string		URL to your app's logo image displayed in the Fireguard UI.
provider	string		Authentication provider to use. Defaults to "google". See EProvider for supported values.
theme	Partial<TTheme>		Custom colors applied to the Fireguard UI.

TTheme

Property	Type	Required	Description
text	string	✓	Color applied to text elements.
primary	string	✓	Primary accent color.
secondary	string	✓	Secondary accent color.
background	string	✓	Page background color.

EProvider

Value	Provider
"google"	Google
"github"	GitHub
"facebook"	Facebook
"twitter"	Twitter / X
"microsoft"	Microsoft
"apple"	Apple
"yahoo"	Yahoo

TFirebaseConfig

Property	Type	Required	Description
appId	string	✓	Unique identifier for the Firebase app.
apiKey	string	✓	API key for authenticating Firebase requests.
projectId	string	✓	Globally unique identifier for the Firebase project.
authDomain	string	✓	Domain used by Firebase Authentication.
measurementId	string	✓	Google Analytics measurement ID.
storageBucket	string	✓	Cloud Storage bucket name for Firebase Storage.
messagingSenderId	string	✓	Sender ID for Firebase Cloud Messaging.

Full API reference is available in the docs.

Playground

An interactive playground is available for testing Firemitt against a live Fireguard instance without writing any code. It lets you configure all options through a form — Firebase credentials, auth provider, theme colors, dimensions, and auth mode — and trigger an auth flow directly in the browser.

To run it locally:

pnpm playground
Copy

Contributing

Contributions are welcome. Please read the contributing guidelines and code of conduct before opening a pull request.