{"id":34666710,"url":"https://github.com/johnbillion/fair-tools","last_synced_at":"2025-12-24T19:03:44.234Z","repository":{"id":327420287,"uuid":"1109179829","full_name":"johnbillion/fair-tools","owner":"johnbillion","description":"Node.js tools for the FAIR protocol. Create keys, create and manage DIDs, and build signed metadata for WordPress plugins.","archived":false,"fork":false,"pushed_at":"2025-12-21T18:56:22.000Z","size":1317,"stargazers_count":5,"open_issues_count":13,"forks_count":1,"subscribers_count":1,"default_branch":"trunk","last_synced_at":"2025-12-22T18:04:24.986Z","etag":null,"topics":["did-plc","fair","node","npm-package"],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/fair-tools","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/johnbillion.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"johnbillion"}},"created_at":"2025-12-03T12:57:40.000Z","updated_at":"2025-12-22T12:25:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/johnbillion/fair-tools","commit_stats":null,"previous_names":["johnbillion/fair-tools"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/johnbillion/fair-tools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnbillion%2Ffair-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnbillion%2Ffair-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnbillion%2Ffair-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnbillion%2Ffair-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/johnbillion","download_url":"https://codeload.github.com/johnbillion/fair-tools/tar.gz/refs/heads/trunk","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnbillion%2Ffair-tools/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28006375,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-24T02:00:07.193Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["did-plc","fair","node","npm-package"],"created_at":"2025-12-24T19:00:59.323Z","updated_at":"2025-12-24T19:03:44.228Z","avatar_url":"https://github.com/johnbillion.png","language":"JavaScript","funding_links":["https://github.com/sponsors/johnbillion"],"categories":[],"sub_categories":[],"readme":"# FAIR Tools\n\nA library of Node.js tools for [FAIR](https://fair.pm/) that can be used by authors of plugins and themes for WordPress. Create keys, create DIDs, manage DID documents, and build signed FAIR metadata.\n\nThis library focuses on providing FAIR tools for the WordPress ecosystem, but its tools are also applicable to FAIR and DID PLC in general.\n\n\u003e [!CAUTION]  \n\u003e 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.\n\n## Installation\n\nFor the best user experience, install FAIR Tools globally:\n\n```bash\nnpm install -g fair-tools\n```\n\nUsage:\n\n```\nfair-tools \u003ccommand\u003e [options]\n```\n\n\u003cdetails\u003e\n\u003csummary\u003eAlternatively, install and use FAIR Tools as a dev dependency of a package\u003c/summary\u003e\n\n```bash\nnpm install --save-dev fair-tools\n```\n\nThen add `fair-tools` to your `package.json` scripts:\n\n```json\n{\n\t\"scripts\": {\n\t\t\"fair-tools\": \"fair-tools\"\n\t}\n}\n```\n\nUsage:\n\n```\nnpm run fair-tools -- \u003ccommand\u003e [options]\n```\n\n\u003c/details\u003e\n\n## CLI reference\n\nCommands:\n\n```shell\nfair-tools did create                   Create a new DID\nfair-tools did service add              Add a service URL to a DID\nfair-tools did service replace          Replace a service URL in a DID\nfair-tools did service remove           Remove a service URL from a DID\nfair-tools did verification-key add     Add a verification key\nfair-tools did verification-key revoke  Revoke a verification key\nfair-tools did rotation-key add         Add a rotation key\nfair-tools did rotation-key revoke      Revoke a rotation key\nfair-tools did aka add                  Add a URL to the alsoKnownAs field\nfair-tools did aka replace              Replace a URL in the alsoKnownAs field\nfair-tools did aka remove               Remove a URL from the alsoKnownAs field\nfair-tools did domain verify            Verify the DID DNS record of a domain\nfair-tools did domain verify-alias      Verify alsoKnownAs domain aliases for a DID\nfair-tools metadata build               Build a FAIR metadata document\n```\n\nTo see all available commands:\n\n```shell\nfair-tools\n```\n\nFor more information on a command:\n\n```\nfair-tools \u003ccommand\u003e --help\n```\n\n## Basic usage\n\nThe basic steps to set up a plugin for distribution via FAIR are:\n\n1. Generate a DID and save its signing keys somewhere safe.\n2. Add the DID to your plugin header and publish it.\n3. Build the FAIR metadata for the package and publish it.\n4. Point your DID to the URL of the metadata document.\n\nThe 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.\n\n### Create a DID\n\nCreates a new DID and publishes it.\n\n```bash\nfair-tools did create --directory ./dids\n```\n\nThis generates rotation and verification keypairs, creates a DID, publishes it to plc.directory, and writes the keys to `\u003cdirectory\u003e/\u003cdid\u003e.json` with secure permissions (0600).\n\n\u003e [!WARNING]\n\u003e Back up this file immediately!\n\u003e This file contains the private keys needed to manage your DID.\n\u003e If you lose this file, you will lose control of your DID permanently.\n\n### Add the DID to your plugin header\n\nManually add the new DID to the header of your plugin. The `did:plc:` prefix must be included.\n\n```diff\n  * Plugin Name: My Plugin\n+ * Plugin ID: did:plc:abcdefghijklmnopqrstuvwx\n  * Version: 1.0.0\n```\n\n### Signing keys\n\nMost subsequent commands after creating a DID require a signing key. There are two ways to provide one:\n\n1. **Key file**: Use `--signing-file` to specify a key file. The file can be either:\n   - A JSON file created by fair-tools containing your keys (use `--signing-key` to select a specific key; defaults to first key)\n   - A standalone PEM file (starts with `-----BEGIN EC PRIVATE KEY-----` for rotation keys or `-----BEGIN PRIVATE KEY-----` for verification keys)\n   - A standalone multibase base58btc file (starts with `z3vL` for rotation keys or `zru`/`zrv` for verification keys from FAIR Beacon)\n   - A standalone hex file (64-character lowercase hex string representing the 32-byte private key)\n\n2. **Environment variable**: If `--signing-file` is not provided, the command falls back to an environment variable:\n   - `FAIR_VERIFICATION_KEY` for metadata signing\n   - `FAIR_ROTATION_KEY` for DID operations\n\n### Build metadata\n\nBuilds signed FAIR metadata for a release of a plugin for WordPress.\n\n```bash\nfair-tools metadata build \\\n  --did did:plc:xxx \\\n  --plugin-file ./my-plugin/my-plugin.php \\\n  --zip-file ./my-plugin.zip \\\n  --url https://example.com/releases/my-plugin-1.0.0.zip \\\n  --metadata-file ./metadata.json \\\n  --output-file ./metadata.json\n```\n\n### Add DID service URL\n\nAdds your FAIR service URL to a DID.\n\n```bash\nfair-tools did service add \\\n  --did did:plc:xxx \\\n  --url https://example.com/did:plc:xxx/metadata.json\n```\n\n### Replace DID service URL\n\nReplaces the FAIR service URL for a DID. Requires specifying the old URL to prevent accidental overwrites.\n\n```bash\nfair-tools did service replace \\\n  --did did:plc:xxx \\\n  --old-url https://old.example.com/metadata.json \\\n  --new-url https://new.example.com/metadata.json\n```\n\n### Remove DID service URL\n\nRemoves the FAIR service URL from a DID. Requires specifying the URL to prevent accidental removals.\n\n```bash\nfair-tools did service remove \\\n  --did did:plc:xxx \\\n  --url https://example.com/metadata.json\n```\n\n## DID management\n\nOver time you may need to manage the keys for your DID.\n\n### Add alsoKnownAs URL\n\nAdds a URL to the alsoKnownAs field of a DID. For FAIR domain aliases, use a `fair://` URL.\n\n```bash\nfair-tools did aka add \\\n  --did did:plc:xxx \\\n  --url fair://example.com\n```\n\nBefore adding a `fair://` alias, ensure your domain has a TXT record at `_fairpm.\u003cdomain\u003e` with the value `did=\u003cyour-did\u003e`. Use `did domain verify` to check this. After adding the alias, use `did domain verify-alias` to verify the complete setup.\n\n### Replace alsoKnownAs URL\n\nReplaces a URL in the alsoKnownAs field of a DID. Requires specifying the old URL to prevent accidental overwrites.\n\n```bash\nfair-tools did aka replace \\\n  --did did:plc:xxx \\\n  --old-url fair://old.example.com \\\n  --new-url fair://new.example.com\n```\n\n### Remove alsoKnownAs URL\n\nRemoves a URL from the alsoKnownAs field of a DID.\n\n```bash\nfair-tools did aka remove \\\n  --did did:plc:xxx \\\n  --url fair://example.com\n```\n\n### Verify domain\n\nVerifies 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.\n\n```bash\nfair-tools did domain verify \\\n  --domain example.com \\\n  --did did:plc:xxx\n```\n\nThe domain requires a TXT record at `_fairpm.\u003cdomain\u003e` with the value `did=\u003cyour-did\u003e`.\n\n### Verify domain alias\n\nVerifies 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.\n\n```bash\nfair-tools did domain verify-alias \\\n  --did did:plc:xxx\n```\n\n### Add verification key\n\nGenerates a new verification key, adds it to a DID, and saves it to the key file.\n\n```bash\nfair-tools did verification-key add \\\n  --did did:plc:xxx\n```\n\nUse `--output-file` to save the new key to a different file instead of the signing file.\n\n### Add rotation key\n\nGenerates a new rotation key, adds it to a DID, and saves it to the key file.\n\n```bash\nfair-tools did rotation-key add \\\n  --did did:plc:xxx\n```\n\nUse `--output-file` to save the new key to a different file instead of the signing file.\n\n### Revoke verification key\n\nRevokes a verification key from a DID.\n\n```bash\nfair-tools did verification-key revoke \\\n  --did did:plc:xxx \\\n  --revoke did:key:z6Mk...\n```\n\nUse `--cleanup` to delete the revoked key from the key file after success.\n\n### Revoke rotation key\n\nRevokes a rotation key from a DID.\n\n```bash\nfair-tools did rotation-key revoke \\\n  --did did:plc:xxx \\\n  --revoke did:key:zQ3sh...\n```\n\nYou cannot revoke the key used to sign the operation, and at least one rotation key must remain.\n\nWhen using `--signing-file` without `--signing-key`, defaults to signing with the first available rotation key that isn't being revoked.\n\nUse `--cleanup` to delete the revoked key from the key file after success.\n\n## FAQs\n\n### I installed fair-tools globally but it's not always available, why not?\n\nIf 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.\n\n### Is this an official FAIR tool?\n\nNo. Its license facilitates it being transferred to The FAIR Web Foundation at a later date should they wish.\n\n## Alternatives\n\n- [FAIR Beacon](https://github.com/fairpm/fair-beacon) - Plugin for WordPress for a self-hostable FAIR repo\n- [FAIR DID Manager](https://github.com/fairpm/did-manager/tree/initial-implementation) - A PHP library for DID management and WordPress plugin/theme metadata generation\n- [FAIR Forge](https://github.com/fairpm/fair-forge) - Build system and artifact management for WordPress plugins/themes\n\n## License\n\nMIT\n\n```\n ███████████   █████████   █████ ███████████\n░░███░░░░░░█  ███░░░░░███ ░░███ ░░███░░░░░███\n ░███   █ ░  ░███    ░███  ░███  ░███    ░███\n ░███████    ░███████████  ░███  ░██████████\n ░███░░░█    ░███░░░░░███  ░███  ░███░░░░░███\n ░███  ░     ░███    ░███  ░███  ░███    ░███\n █████       █████   █████ █████ █████   █████\n░░░░░       ░░░░░   ░░░░░ ░░░░░ ░░░░░   ░░░░░\n\n ███████████                   ████\n░█░░░███░░░█                  ░░███\n░   ░███  ░   ██████   ██████  ░███   █████\n    ░███     ███░░███ ███░░███ ░███  ███░░\n    ░███    ░███ ░███░███ ░███ ░███ ░░█████\n    ░███    ░███ ░███░███ ░███ ░███  ░░░░███\n    █████   ░░██████ ░░██████  █████ ██████\n   ░░░░░     ░░░░░░   ░░░░░░  ░░░░░ ░░░░░░\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnbillion%2Ffair-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjohnbillion%2Ffair-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnbillion%2Ffair-tools/lists"}