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:

``bash npm install -g fair-tools`

Usage:

`fair-tools [options]`


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

`bash npm install --save-dev fair-tools`

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

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

Usage:

`npm run fair-tools -- [options]`

`CLI reference`

Commands:

`shell 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:

`shell fair-tools`

For more information on a command:

`fair-tools --help`

`Basic usage`

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

1. Generate a DID and save its signing keys somewhere safe. 2. Add the DID to your plugin header and publish it. 3. Build the FAIR metadata for the package and publish it. 4. 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.

`$3`

Creates a new DID and publishes it.

`bash 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 /.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.

`$3`

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

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

`$3`

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

1. Key file: Use --signing-fileto specify a key file. The file can be either: - A JSON file created by fair-tools containing your keys (use--signing-keyto 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 withz3vL for rotation keys or zru/zrvfor verification keys from FAIR Beacon) - A standalone hex file (64-character lowercase hex string representing the 32-byte private key)

2. Environment variable: If --signing-fileis not provided, the command falls back to an environment variable: -FAIR_VERIFICATION_KEYfor metadata signing -FAIR_ROTATION_KEY for DID operations

`$3`

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

`bash 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`

`$3`

Adds your FAIR service URL to a DID.

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

`$3`

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

`bash 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`

`$3`

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

`bash 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.

`$3`

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

`bash 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. with the value did=. Use did domain verify to check this. After adding the alias, use did domain verify-alias to verify the complete setup.

`$3`

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

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

`$3`

Removes a URL from the alsoKnownAs field of a DID.

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

`$3`

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.

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

The domain requires a TXT record at _fairpm. with the value did=.

`$3`

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.

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

`$3`

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

`bash 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.

`$3`

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

`bash 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:

`bash

`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.

`$3`

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

`bash 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.

`$3`

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

`bash 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:

`bash

`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.

`$3`

Revokes a verification key from a DID.

`bash 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.

`$3`

Revokes a rotation key from a DID.

`bash 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.

`$3`

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

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

This validates:

1. DID log - Verifies the complete operation history from genesis, including all signatures and CID chain integrity 2. Service endpoints - Fetches and validates FAIR metadata from each service URL 3. Domain aliases - Checks thatfair:// 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.)

`$3`

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

`bash 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.

`$3`

Verifies a FAIR package management service endpoint URL.

`bash 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.

`$3`

Verifies a FAIR metadata document including signature and checksum validation.

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

Or verify from a local file:

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

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

`$3`

Verifies a specific release version from a FAIR metadata document.

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

Or from a local file:

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

`FAQs`

`$3`

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.

`$3`

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

`███████████ █████████ █████ ███████████ ░░███░░░░░░█ ███░░░░░███ ░░███ ░░███░░░░░███ ░███ █ ░ ░███ ░███ ░███ ░███ ░███ ░███████ ░███████████ ░███ ░██████████ ░███░░░█ ░███░░░░░███ ░███ ░███░░░░░███ ░███ ░ ░███ ░███ ░███ ░███ ░███ █████ █████ █████ █████ █████ █████ ░░░░░ ░░░░░ ░░░░░ ░░░░░ ░░░░░ ░░░░░

███████████ ████ ░█░░░███░░░█ ░░███ ░ ░███ ░ ██████ ██████ ░███ █████ ░███ ███░░███ ███░░███ ░███ ███░░ ░███ ░███ ░███░███ ░███ ░███ ░░█████ ░███ ░███ ░███░███ ░███ ░███ ░░░░███ █████ ░░██████ ░░██████ █████ ██████ ░░░░░ ░░░░░░ ░░░░░░ ░░░░░ ░░░░░░``

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.

Installation

For the best user experience, install FAIR Tools globally:

``bash npm install -g fair-tools`

Usage:

`fair-tools [options]`


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

`bash npm install --save-dev fair-tools`

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

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

Usage:

`npm run fair-tools -- [options]`

`CLI reference`

Commands:

To see all available commands:

`shell fair-tools`

For more information on a command:

`fair-tools --help`

`Basic usage`

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

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.

`$3`

Creates a new DID and publishes it.

`bash 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 /.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.

`$3`

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

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

`$3`

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

2. Environment variable: If --signing-fileis not provided, the command falls back to an environment variable: -FAIR_VERIFICATION_KEYfor metadata signing -FAIR_ROTATION_KEY for DID operations

`$3`

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

`$3`

Adds your FAIR service URL to a DID.

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

`$3`

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

`bash 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`

`$3`

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

`bash 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.

`$3`

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

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

`$3`

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

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

`$3`

Removes a URL from the alsoKnownAs field of a DID.

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

`$3`

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.

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

The domain requires a TXT record at _fairpm. with the value did=.

`$3`

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.

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

`$3`

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

`bash 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.

`$3`

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

`bash 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:

`bash

`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.

`$3`

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

`bash 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.

`$3`

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

`bash 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:

`bash

`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.

`$3`

Revokes a verification key from a DID.

`bash 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.

`$3`

Revokes a rotation key from a DID.

`bash 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.

`$3`

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

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

This validates:

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.)

`$3`

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

`bash 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.

`$3`

Verifies a FAIR package management service endpoint URL.

`bash 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.

`$3`

Verifies a FAIR metadata document including signature and checksum validation.

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

Or verify from a local file:

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

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

`$3`

Verifies a specific release version from a FAIR metadata document.

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

Or from a local file:

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

`FAQs`

`$3`

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.

`$3`

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

`Alternatives`

`License`

MIT