fcw

README

fcw - Firefox Controller Wrapper

A Go library for managing Firefox instances with custom profiles and settings. Useful for creating site-specific browsers, kiosk applications, or configuring Firefox for overlay networks like Tor or I2P.

Features

• Launch Firefox with custom profiles and settings
• Create WebApp-style Firefox instances
• Manage Firefox processes and profiles
• Certificate management support
• Private browsing mode
• Support for portable Firefox installations
• Cross-platform (Windows, macOS, Linux)

Installation

go get github.com/eyedeekay/go-fpw

Core Functions

Basic Usage

// Create and launch Firefox with basic profile
ui, err := fcw.BasicFirefox("profile-dir", false, "https://example.com")

// Create a WebApp-style Firefox instance
ui, err := fcw.WebAppFirefox("webapp-profile", false, false, "https://example.com")

// Manage certificates
cm, err := ui.CertManager()
err = cm.AddCertificate("cert.pem", "nickname")

WebApp Mode Features

When using WebAppFirefox(), the following customizations are applied:

• Minimal UI with hidden URL bar
• Custom userChrome.css for app-like appearance
• Disabled telemetry and first-run procedures
• Optional offline mode support
• Copy URL to clipboard extension
• User profile customizations enabled

Site-Specific Browser Application

The package includes ssbapp, a command-line utility for creating isolated Firefox instances for specific websites. See ssbapp documentation for details.

Example usage:

ssbapp -url "https://example.com" -private -profiles "./my-profiles"

License

MIT License - See LICENSE file

Contributing

Contributions welcome! Please feel free to submit issues and pull requests.

Documentation

Overview

Package fcw wraps a Firefox process from start-to-finish, and allows the user to pass a profile directory to that process where it will find pre-configured settings. It's useful for using Firefox as an interface to applications, and for applying specific settings for use when browsing overlay networks like Tor or I2P.

Index

• Variables
• func DeAppifyUserJS(profile string) error
• func LoadCertificate(certPath string) (*x509.Certificate, error)
• func LocateFirefox() string
• func MessageBox(title, text string) bool
• func PortablePath() string
• func PromptDownload()
• func Run() error
• func UnpackApp(profileDir string, offline bool) (string, error)
• type CertManager
  • func NewCertManager(profileDir string) (*CertManager, error)
  • func (cm *CertManager) AddCertificate(certPath, nickname string) error
  • func (cm *CertManager) ListCertificates() ([]cert9util.CertificateInfo, error)
  • func (cm *CertManager) RemoveCertificate(nickname string) error
• type UI
  • func BasicFirefox(userdir string, private bool, args ...string) (UI, error)
  • func NewFirefox(url, dir string, width, height int, customArgs ...string) (UI, error)
  • func WebAppFirefox(userdir string, private, offline bool, args ...string) (UI, error)

Variables

var FirefoxExecutable = LocateFirefox

FirefoxExecutable returns a string which points to the preferred Firefox executable file as calculated by the LocateFirefox variable

var UserChrome []byte

var UserOverrides []byte

Functions

func DeAppifyUserJS

func DeAppifyUserJS(profile string) error

func LoadCertificate

func LoadCertificate(certPath string) (*x509.Certificate, error)

LoadCertificate loads a certificate from a PEM file

func LocateFirefox

func LocateFirefox() string

LocateFirefox returns a path to the Firefox binary, or an empty string if Firefox installation is not found.

func MessageBox

func MessageBox(title, text string) bool

MessageBox creates a dialog box which prompts the user to download and install Firefox if they have not already.

func PortablePath

func PortablePath() string

PortablePath determines if there is a "Portable" Firefox in a sub-directory of the runtime directory

func PromptDownload

func PromptDownload()

PromptDownload asks user if they want to download and install Firefox, and opens a download web page if the user agrees.

func Run

func Run() error

Run creates a basic instance of the Firefox manager with a default profile directory and launches duckduckgo.com

func UnpackApp

func UnpackApp(profileDir string, offline bool) (string, error)

UnpackApp unpacks a "App" mode profile into the "profileDir" and returns the path to the profile and possibly, an error if something goes wrong. If everything works, the error will be nil

Types

type CertManager

type CertManager struct {
	// contains filtered or unexported fields
}

CertManager handles Firefox certificate operations

func NewCertManager

func NewCertManager(profileDir string) (*CertManager, error)

NewCertManager creates a certificate manager for the given Firefox profile

func (*CertManager) AddCertificate

func (cm *CertManager) AddCertificate(certPath, nickname string) error

AddCertificate imports a certificate from a PEM file

func (*CertManager) ListCertificates

func (cm *CertManager) ListCertificates() ([]cert9util.CertificateInfo, error)

ListCertificates returns all certificates in the database

func (*CertManager) RemoveCertificate

func (cm *CertManager) RemoveCertificate(nickname string) error

RemoveCertificate removes a certificate by its nickname

type UI

type UI interface {
	Done() <-chan struct{}
	Close() error
	Log() string
	CertManager() (*CertManager, error)
}

UI is a wrapper/manager for a Firefox external process.

func BasicFirefox

func BasicFirefox(userdir string, private bool, args ...string) (UI, error)

BasicFirefox sets up a new Firefox instance, and creates the profile directory if it does not already exist.

func NewFirefox

func NewFirefox(url, dir string, width, height int, customArgs ...string) (UI, error)

NewFirefox creates a new instance of the Firefox manager.

func WebAppFirefox

func WebAppFirefox(userdir string, private, offline bool, args ...string) (UI, error)

WebAppFirefox sets up a new Firefox instance, and creates the profile directory if it does not already exist. It turns Firefox into a WebApp-Viewer with the provided profile