Home

Awesome

DEPRECIATION NOTICE: Since this project was created, Safari changed the technology they use for extensions, and it no longer uses xar archives. See https://underpassapp.com/news/2023-4-24.html

xar-js

Build Status npm version

xar-js is a JavaScript library and command-line utility for reading and writing xar archives.

It was originally written to facilitate automated building of Safari Extensions.

Installation

npm install -g xar-js

Usage

Building a Safari Extension

To build a Safari extension without using Extension Builder, you will first need to get developer certificates for Safari from Apple, export the certificates and the intermediate and root certificates in the signing chain. You can then use xarjs create to generate .safariextz extensions.

  1. You will need a Developer Certificate as described in the Safari Extension Development Guide

  2. Once you have the Developer Certificate installed in your keychain, you will need to export it.

    1. Go to the 'Certificates' section of the 'Keychain Access' application, command-click on the 'Safari Developer: ...' certificate and select the 'Export' option.
    2. Save the certificate using the .p12 format.
    3. Extract the public and private keys from the resulting .p12 file using openssl:
    # export public certificate
openssl pkcs12 -in safari-certs.p12 -nokeys -out cert.pem

# export private key (note the 'nodes' option means that it will be unencrypted)
openssl pkcs12 -nodes -in safari-certs.p12 -nocerts -out privatekey.pem

  3. Export the intermediate certificate and root certificates used to sign your developer certificate from Keychain Access.

    These are the 'Apple Worldwide Developer Relations Certification Authority' (usually in your login keychain) and the 'Apple Root CA' certificate (usually in the 'System Roots' section). (These are named apple-intermediate.pem and apple-root.pem in the following instructions).

    In the export options dialog, select the Privacy Enhanced Mail (PEM) format.

  4. Use xarjs create to generate a .safariextz archive from your .safariextension directory containing the files for the extension:

    Note: The order of the --cert arguments is important. The leaf certificate must be specified first, followed by the intermediate and then the root.

    xarjs create extension.safariextz --cert cert.pem --cert apple-intermediate.pem --cert apple-root.pem --private-key privatekey.pem extension.safariextension

  5. Verify that Safari accepts the resulting extension:

    open extension.safariextz

    Should result in Safari showing a dialog prompting you to install the extension.