fair-tools

FAIR Tools

A library of Node.js tools for FAIR that can be used by authors and consumers of plugins for WordPress.

This library focuses on providing FAIR tools for the WordPress ecosystem, but its tools are also applicable to FAIR and DID PLC in general.

[!CAUTION]
This package is not production ready and is under heavy development. Do not use this unless you are comfortable testing the FAIR protocol and handling breaking changes, including breaking changes to storage of private keys.

Installation

For the best user experience, install FAIR Tools globally:

npm install -g fair-tools

Usage:

fair-tools <command> [options]

Alternatively, install and use FAIR Tools as a dev dependency of a package

npm install --save-dev fair-tools

Then add fair-tools to your package.json scripts:

{
	"scripts": {
		"fair-tools": "fair-tools"
	}
}

Usage:

npm run fair-tools -- <command> [options]

CLI reference

Commands:

fair-tools did create                   Create a new DID
fair-tools did verify                   Fully verify a DID, its document, and FAIR metadata
fair-tools did service add              Add a service URL to a DID
fair-tools did service replace          Replace a service URL in a DID
fair-tools did service remove           Remove a service URL from a DID
fair-tools did service verify           Verify a FAIR service endpoint URL
fair-tools did verification-key add     Add a verification key
fair-tools did verification-key check   Check if a verification key is valid for a DID
fair-tools did verification-key revoke  Revoke a verification key
fair-tools did rotation-key add         Add a rotation key
fair-tools did rotation-key check       Check if a rotation key is valid for a DID
fair-tools did rotation-key revoke      Revoke a rotation key
fair-tools did log verify               Validate a DID operation log from genesis
fair-tools did aka add                  Add a URL to the alsoKnownAs field
fair-tools did aka replace              Replace a URL in the alsoKnownAs field
fair-tools did aka remove               Remove a URL from the alsoKnownAs field
fair-tools did domain verify            Verify the DID DNS record of a domain
fair-tools did domain verify-alias      Verify alsoKnownAs domain aliases for a DID
fair-tools metadata release             Build a FAIR metadata document containing a new release
fair-tools metadata verify              Verify a FAIR metadata document
fair-tools metadata verify-release      Verify a specific release from a metadata document

To see all available commands:

fair-tools

For more information on a command:

fair-tools <command> --help

Basic usage

The basic steps to set up a plugin for distribution via FAIR are:

• Generate a DID and save its signing keys somewhere safe.
• Add the DID to your plugin header and publish it.
• Build the FAIR metadata for the package and publish it.
• Point your DID to the URL of the metadata document.

The initial setup of the DID only happens once. Subsequent updates to your plugin just require you to build the FAIR metadata for the package and publish it.

Create a DID

Creates a new DID and publishes it.

fair-tools did create --directory ./dids

This generates rotation and verification keypairs, creates a DID, publishes it to plc.directory, and writes the keys to <directory>/<did>.json with secure permissions (0600).

[!WARNING] Back up this file immediately! This file contains the private keys needed to manage your DID. If you lose this file, you will lose control of your DID permanently.

Add the DID to your plugin header

Manually add the new DID to the header of your plugin. The did:plc: prefix must be included.

  * Plugin Name: My Plugin
+ * Plugin ID: did:plc:abcdefghijklmnopqrstuvwx
  * Version: 1.0.0

Signing keys

Most subsequent commands after creating a DID require a signing key. There are two ways to provide one:

• Key file: Use --signing-file to specify a key file. The file can be either:

  • A JSON file created by fair-tools containing your keys (use --signing-key to select a specific key; defaults to first key)
  • A standalone PEM file (starts with -----BEGIN EC PRIVATE KEY----- for rotation keys or -----BEGIN PRIVATE KEY----- for verification keys)
  • A standalone multibase base58btc file (starts with z3vL for rotation keys or zru/zrv for verification keys from FAIR Beacon)
  • A standalone hex file (64-character lowercase hex string representing the 32-byte private key)

• Environment variable: If --signing-file is not provided, the command falls back to an environment variable:

  • FAIR_VERIFICATION_KEY for metadata signing
  • FAIR_ROTATION_KEY for DID operations

Build metadata

Builds signed FAIR metadata for a release of a plugin for WordPress.

fair-tools metadata release \
  --did did:plc:xxx \
  --plugin-file ./my-plugin/my-plugin.php \
  --zip-file ./my-plugin.zip \
  --url https://example.com/releases/my-plugin-1.0.0.zip \
  --metadata-file ./metadata.json \
  --output-file ./metadata.json

Add DID service URL

Adds your FAIR service URL to a DID.

fair-tools did service add \
  --did did:plc:xxx \
  --url https://example.com/did:plc:xxx/metadata.json

Replace DID service URL

Replaces the FAIR service URL for a DID. Requires specifying the old URL to prevent accidental overwrites.

fair-tools did service replace \
  --did did:plc:xxx \
  --old-url https://old.example.com/metadata.json \
  --new-url https://new.example.com/metadata.json

Remove DID service URL

Removes the FAIR service URL from a DID. Requires specifying the URL to prevent accidental removals.

fair-tools did service remove \
  --did did:plc:xxx \
  --url https://example.com/metadata.json

DID management

Over time you may need to manage the keys for your DID.

Add alsoKnownAs URL

Adds a URL to the alsoKnownAs field of a DID. For FAIR domain aliases, use a fair:// URL.

fair-tools did aka add \
  --did did:plc:xxx \
  --url fair://example.com

Before adding a fair:// alias, ensure your domain has a TXT record at _fairpm.<domain> with the value did=<your-did>. Use did domain verify to check this. After adding the alias, use did domain verify-alias to verify the complete setup.

Replace alsoKnownAs URL

Replaces a URL in the alsoKnownAs field of a DID. Requires specifying the old URL to prevent accidental overwrites.

fair-tools did aka replace \
  --did did:plc:xxx \
  --old-url fair://old.example.com \
  --new-url fair://new.example.com

Remove alsoKnownAs URL

Removes a URL from the alsoKnownAs field of a DID.

fair-tools did aka remove \
  --did did:plc:xxx \
  --url fair://example.com

Verify domain

Verifies that a domain's DNS TXT record is correctly configured for a DID. Use this to check DNS propagation before adding a domain alias to your DID.

fair-tools did domain verify \
  --domain example.com \
  --did did:plc:xxx

The domain requires a TXT record at _fairpm.<domain> with the value did=<your-did>.

Verify domain alias

Verifies the fair:// domain alias in a DID's alsoKnownAs field by fetching the DID document, extracting the alias, and checking the corresponding DNS TXT record.

fair-tools did domain verify-alias \
  --did did:plc:xxx

Add verification key

Generates a new verification key, adds it to a DID, and saves it to the key file.

fair-tools did verification-key add \
  --did did:plc:xxx

Use --output-file to save the new key to a different file instead of the signing file.

Check verification key

Checks if a verification key is valid by checking that it's present in the DID document's verification methods.

fair-tools did verification-key check \
  --did did:plc:xxx \
  --key did:key:z6Mk...

You can also provide the key via file or environment variable:

# From a file (accepts public key or private keypair)
fair-tools did verification-key check \
  --did did:plc:xxx \
  --key-file ./key.pem

# From environment variable
FAIR_VERIFICATION_KEY=z6Mk... fair-tools did verification-key check \
  --did did:plc:xxx

If neither --key nor --key-file is provided, uses FAIR_VERIFICATION_KEY environment variable.

Add rotation key

Generates a new rotation key, adds it to a DID, and saves it to the key file.

fair-tools did rotation-key add \
  --did did:plc:xxx

Use --output-file to save the new key to a different file instead of the signing file.

Check rotation key

Checks if a rotation key is valid by checking that it's present in the latest operation of the DID log.

fair-tools did rotation-key check \
  --did did:plc:xxx \
  --key did:key:zQ3sh...

You can also provide the key via file or environment variable:

# From a file (accepts public key or private keypair)
fair-tools did rotation-key check \
  --did did:plc:xxx \
  --key-file ./key.pem

# From environment variable
FAIR_ROTATION_KEY=zQ3sh... fair-tools did rotation-key check \
  --did did:plc:xxx

If neither --key nor --key-file is provided, uses FAIR_ROTATION_KEY environment variable.

Revoke verification key

Revokes a verification key from a DID.

fair-tools did verification-key revoke \
  --did did:plc:xxx \
  --revoke did:key:z6Mk...

Use --cleanup to delete the revoked key from the key file after success.

Revoke rotation key

Revokes a rotation key from a DID.

fair-tools did rotation-key revoke \
  --did did:plc:xxx \
  --revoke did:key:zQ3sh...

You cannot revoke the key used to sign the operation, and at least one rotation key must remain.

When using --signing-file without --signing-key, defaults to signing with the first available rotation key that isn't being revoked.

Use --cleanup to delete the revoked key from the key file after success.

Verification

Verification commands allow consumers to validate DIDs, metadata, and releases. These commands do not require signing keys.

Full DID verification

Performs comprehensive verification of a DID including its operation log, service endpoints, and domain aliases.

fair-tools did verify --did did:plc:xxx

This validates:

• DID log - Verifies the complete operation history from genesis, including all signatures and CID chain integrity
• Service endpoints - Fetches and validates FAIR metadata from each service URL
• Domain aliases - Checks that fair:// aliases in alsoKnownAs resolve correctly via DNS

Use --all-releases to verify all releases instead of just the latest.

Exit codes:

• 0 - All verifications passed
• 1 - Verification failed (invalid signature, broken chain, etc.)
• 2 - Could not verify (network error, DID not found, etc.)

Verify DID operation log

Validates a PLC DID's complete operation history from genesis to current state.

fair-tools did log verify --did did:plc:xxx

This validates:

• Genesis operation structure and DID computation
• Each operation's signature against the previous operation's rotation keys
• CID chain integrity (prev field matches previous operation CID)

Each operation is listed with its CID and signing key.

Verify service endpoint

Verifies a FAIR package management service endpoint URL.

fair-tools did service verify \
  --did did:plc:xxx \
  --url https://example.com/metadata.json

This validates:

• URL is accessible (HTTPS required)
• Response is valid FAIR metadata JSON
• Metadata DID matches the expected DID
• Release signatures are valid
• Release checksums are valid (if present)

Use --all-releases to verify all releases instead of just the latest.

Verify metadata

Verifies a FAIR metadata document including signature and checksum validation.

fair-tools metadata verify \
  --did did:plc:xxx \
  --url https://example.com/metadata.json

Or verify from a local file:

fair-tools metadata verify \
  --did did:plc:xxx \
  --file ./metadata.json

Use --all-releases to verify all releases instead of just the latest.

Verify specific release

Verifies a specific release version from a FAIR metadata document.

fair-tools metadata verify-release \
  --did did:plc:xxx \
  --url https://example.com/metadata.json \
  --version 1.2.3

Or from a local file:

fair-tools metadata verify-release \
  --did did:plc:xxx \
  --file ./metadata.json \
  --version 1.2.3

FAQs

I installed fair-tools globally but it's not always available, why not?

If you're using nvm or fnm to manage Node.js versions you'll need to install it globally for each version. This is how those tools and Node.js versions work, it's not specific to fair-tools.

Is this an official FAIR tool?

No. Its license facilitates it being transferred to The FAIR Web Foundation at a later date should they wish.

Alternatives

• FAIR Beacon - Plugin for WordPress for a self-hostable FAIR repo
• FAIR DID Manager - A PHP library for DID management and WordPress plugin/theme metadata generation
• FAIR Forge - Build system and artifact management for WordPress plugins/themes

License

MIT

 ███████████   █████████   █████ ███████████
░░███░░░░░░█  ███░░░░░███ ░░███ ░░███░░░░░███
 ░███   █ ░  ░███    ░███  ░███  ░███    ░███
 ░███████    ░███████████  ░███  ░██████████
 ░███░░░█    ░███░░░░░███  ░███  ░███░░░░░███
 ░███  ░     ░███    ░███  ░███  ░███    ░███
 █████       █████   █████ █████ █████   █████
░░░░░       ░░░░░   ░░░░░ ░░░░░ ░░░░░   ░░░░░

 ███████████                   ████
░█░░░███░░░█                  ░░███
░   ░███  ░   ██████   ██████  ░███   █████
    ░███     ███░░███ ███░░███ ░███  ███░░
    ░███    ░███ ░███░███ ░███ ░███ ░░█████
    ░███    ░███ ░███░███ ░███ ░███  ░░░░███
    █████   ░░██████ ░░██████  █████ ██████
   ░░░░░     ░░░░░░   ░░░░░░  ░░░░░ ░░░░░░