Skip to main content
Record a file’s SHA-256 fingerprint and verify it later with Truthlocks. Files are hashed locally: the CLI sends the fingerprint and record metadata, not the file contents. Runtime: Node.js 18+ · Package: @truthlocks/protect · Command: truthlock-protect Console · Consumer app · API documentation

​
Install

The truthlocks command is also installed as an alias. This package records online fingerprints; use @truthlocks/cli for offline proof-bundle verification.

​
Choose your account type

An API key is not a consumer token. The CLI uses different endpoints for these two workflows. Test API keys select the sandbox host. Set TRUTHLOCK_API_URL only when you intentionally need a different API origin.

​
Workspace quickstart

Set TRUTHLOCKS_API_KEY, TRUTHLOCKS_ISSUER_ID and TRUTHLOCKS_KEY_ID in your environment, then protect an existing file:
Replace the example retry key with a unique value for this operation. Retain it with the request details and reuse it only for the identical request. The output contains attestation_id and payload_b64url; retain both. The --output option saves a receipt without overwriting an existing file. This operation writes a record. You can select the issuer and key explicitly instead:
Replace the uppercase placeholders. The algorithm must match the selected key. If exactly one active issuer and one eligible signing key are available, the CLI can select them automatically; otherwise it asks you to choose using flags. Workspace records use structured claims with a document.sha256 fingerprint and an explicit document hash. They follow workspace/API access rules; consumer visibility flags do not apply to this workflow.

​
Consumer quickstart

Set TRUTHLOCK_TOKEN to an authorized consumer bearer token, with workspace API-key environment variables unset, then run:
Consumer records are private by default. Use --public only when you want a public consumer record. The service selects the consumer signing key; --algorithm, --issuer-id and --key-id are workspace options and are rejected in consumer mode.

​
Verify a record and file

Use the saved receipt and the original file. The receipt supplies the exact bytes that were signed; the file supplies the fingerprint to compare:
For a current consumer record, you can reconstruct its defined personal-record-v2 payload from the original file:
This reconstruction is automatic when using only a consumer token with --file. It does not reconstruct arbitrary workspace claims or historical payload formats. For a workspace record without a saved receipt, supply the original signed payload bytes using --payload-file ./signed-payload.json. Do not reformat that JSON. Exit code 0 requires both verdict: VALID and signature_verified: true. Altered files and incomplete proofs exit nonzero. An ID-only lookup cannot verify a signature; it reports INCOMPLETE unless a stronger status such as revocation applies:
A valid fingerprint record is evidence that bytes match the recorded hash. It does not independently prove authorship, copyright ownership, or the truth of its title.

​
Commands

Developer registration is a separate account-creation operation. It does not create a consumer session or guarantee an issuer/signing key is already provisioned.

​
Options and local storage

protect accepts --title, --description, --category, --content-type, --json, --api-key, --issuer-id, --key-id, --algorithm, --idempotency-key and --output. --public and --private apply only to consumers. File category is auto-detected unless supplied. Directories are not supported. The historical TRUTHLOCK_API_KEY variable is still accepted. Explicit API-key flags and environment variables take priority over a saved developer key. An explicit consumer-token environment variable takes priority over a saved developer key when no API-key environment variable is supplied. A saved consumer token lives in ~/.truthlock/config.json; developer credentials live in ~/.truthlocks/credentials.json. These are local credential files. Keep them out of repositories and backups intended for publication.

​
Troubleshooting

Requests use a 30-second timeout and are sent once. Redirects are rejected. Rate-limit remaining values are not presented as a monthly quota.

​
Upgrading from 1.0

Version 1.1.1 adds retained signed payloads and cryptographic verification with original files. Version 1.1 fixes API-key headers, consumer content_hash, workspace signing, private consumer defaults, JSON output, command aliases and real verification. Previous examples that claimed a protection lookup was cryptographic verification should be replaced. MIT license.