Verify a Vault export locally on Linux

Before you begin

Use Linux x86-64 with Python 3.9 or newer and GnuPG. You also need enough disk space for the installed tools, encrypted export, temporary files, and any decrypted output.

Open a Bash terminal and check the prerequisites:

uname -m
python3 --version
gpg --version

Expected result: x86_64, Python 3.9 or newer, and GnuPG version information. If a command is missing, install that prerequisite using your Linux distribution's package manager before continuing.

You need a completed .pfv and its matching .key.json. If you do not have them, export one file from Desktop. If you received the pair, use those files directly.

Keep the key file private. Anyone with the package and its .key.json can decrypt that revision, even after their PhotonFile access is revoked. Treat a decrypted copy as sensitive too.

1. Download the setup files, but do not run setup yet

Release 0.1.5

Save all three files in one new folder with the filenames shown above. Do not save an HTML error page as a script or rename a duplicate download to disguise its identity. Open a terminal in that folder using your file manager.

Run every command block below from this same download folder. The blocks do not depend on shell variables set in earlier steps. When asked for export or output paths, enter full paths without surrounding quotes, even if they contain spaces.

The commands on this page use the configured website https://www.photonfile.com. This website selects the release channel and package origin. It is not necessarily the package-download hostname. Do not switch environments partway through installation.

2. Authenticate the setup script

Independently confirm the full release primary fingerprint before trusting the download:

65988DFA88F70DC1704F196E19283DA08E1FEDAD

Compare it with a previously trusted release certificate or a separately authenticated PhotonFile source. Copying a fingerprint only from this page shares the website's trust. If you cannot authenticate the fingerprint, stop. Setup cannot authenticate its own first execution.

This block uses a fresh isolated public keyring and verifies the setup script without executing it:

(
  set -eu
  release_keyring=$(mktemp -d)
  chmod 700 "$release_keyring"
  gpg --no-options --batch --homedir "$release_keyring" --import photonfile-linux-release-public.asc
  gpg --no-options --batch --homedir "$release_keyring" --fingerprint --list-keys 65988DFA88F70DC1704F196E19283DA08E1FEDAD
  gpg --no-options --batch --homedir "$release_keyring" --export 65988DFA88F70DC1704F196E19283DA08E1FEDAD > "$release_keyring/trusted.gpg"
  gpg --no-options --batch --homedir "$release_keyring" --no-default-keyring --keyring "$release_keyring/trusted.gpg" --no-auto-key-retrieve --verify photonfile-verifier-setup.py.asc photonfile-verifier-setup.py
  printf '\nSetup signature verified. Continue only if you independently authenticated the primary fingerprint above.\n'
)

Expected result: the expected primary fingerprint, a valid signature from its signing subkey, and the final confirmation line. A GnuPG owner-trust warning is not a substitute for checking the fingerprint. Missing, invalid, expired, or revoked signatures are a stop condition. Do not continue after an error.

The temporary directory contains only public verification material. Never accept a replacement primary key merely because a download asks you to.

3. Check and install the release

Only after step 2 succeeds, run this block as your normal user, not with sudo:

(
  set -eu
  python3 photonfile-verifier-setup.py --server 'https://www.photonfile.com' verify-release
  python3 photonfile-verifier-setup.py --server 'https://www.photonfile.com' install
  python3 photonfile-verifier-setup.py --server 'https://www.photonfile.com' doctor
)

Expected result: setup prints Authenticated Linux release: and a release identity, followed by Authenticated installed files:. These checks authenticate installed tool files, not your export. Setup downloads and checks release inventories and signatures. The first installation needs network access.

4. Verify your export

Enter the two full paths shown by Desktop, or the paths of the pair you received. This prompts for filenames, not key contents. The key must be a regular file you own, not a symbolic link. The block makes its permissions owner-only, as required by the native reader. It does not change the key's contents:

(
  set -eu
  read -r -p 'Full path to the .pfv package: ' export_package
  read -r -p 'Full path to its .key.json file: ' export_key
  test -f "$export_key" && test ! -L "$export_key"
  chmod 600 -- "$export_key"
  python3 photonfile-verifier-setup.py --server 'https://www.photonfile.com' cli -- verify-export "$export_package" --key-file "$export_key" --json
)

Expected result: a successful JSON report containing Content and layout verified. The report explicitly lists checks that remain unverified. No plaintext output is created by this command. If it fails, stop and check that the two files belong to the same completed export.

5. Optionally decrypt a readable copy

Choose a new output path in an existing private folder. Use an appropriate filename for the original content. The public content-key reader does not authenticate its original protected filename. This command re-verifies the pair before writing plaintext:

(
  set -eu
  read -r -p 'Full path to the .pfv package: ' export_package
  read -r -p 'Full path to its .key.json file: ' export_key
  read -r -p 'Full path for a NEW decrypted output file: ' decrypted_output
  test -f "$export_key" && test ! -L "$export_key"
  chmod 600 -- "$export_key"
  python3 photonfile-verifier-setup.py --server 'https://www.photonfile.com' cli -- decrypt-export "$export_package" --key-file "$export_key" --output "$decrypted_output" --json
)

Expected result: a successful report and a readable file at the output path you entered. An existing destination is refused rather than overwritten. The encrypted export remains unchanged.

Prefer a local browser window?

After installing, you can run the authenticated browser bundle on this computer instead of using command-line verification:

python3 photonfile-verifier-setup.py --server 'https://www.photonfile.com' launch

Open the printed http://127.0.0.1:PORT/ URL in your browser. Leave the terminal running and follow steps 2 through 5 of the browser guide, using this local window instead of the hosted app. The 256 MiB browser package limit still applies. Press Ctrl+C in the terminal when finished.

Do not open the bundle as a file:// page or use a generic web server. Setup supplies the required security headers.

What does a successful result mean?

Content and layout verified means the encrypted content and its structure passed the checks using the matching exported key. It does not prove who authored the file, when it existed, or that it is the latest revision.

Protected metadata, original key wrapping, and external freshness remain unverified by the public content-key reader. For example, the result does not independently authenticate the file's protected metadata or prove that the server still grants access. It is not the author's digital signature.

These are PhotonFile-published tools, not an unaffiliated audit. Read about the trust model and release evidence.

Troubleshooting

Signature or installed-file checks fail: Stop. Confirm the script and signature were downloaded as a matching pair. Do not bypass checks, modify signed files, or trust a different primary key to continue.
Downloads are blocked or unavailable: Check you are using the intended website. If access is restricted, contact its operator. Do not switch to a different environment or disable verification as a workaround.
Verification rejects my export: Use the exact completed package and key pair. If a fresh matching export fails, preserve the error for support without sharing the secret key.
The output already exists: Choose a new filename or folder. Do not delete an existing file merely to make the command succeed.

After your first verification

Offline use and installation location

After installation, native verification, decryption, doctor, and local-browser launch need no release discovery or network access. Offline use cannot learn newly published revocations.

To install from an offline release directory, it must contain the complete published channel/catalog and referenced objects with their URL path layout, not just one downloaded archive. Use --release-dir instead of --server, never both. Offline sources use a separate default installation prefix.

(
  set -eu
  read -r -p 'Full path to the complete offline release directory: ' offline_release
  python3 photonfile-verifier-setup.py --release-dir "$offline_release" verify-release
  python3 photonfile-verifier-setup.py --release-dir "$offline_release" install
  python3 photonfile-verifier-setup.py --release-dir "$offline_release" doctor
)

For subsequent offline commands, use that same --release-dir in place of the website option. To choose another installation location, supply --prefix before the command and keep using it. Each prefix retains its source. Use a separate prefix for another environment.

Updates, rollback, and removal

Update from the same website when online:

python3 photonfile-verifier-setup.py --server 'https://www.photonfile.com' update

Previous versions remain installed. For rollback, enter an exact previously installed identity printed by setup, including its version, full source commit, and generation. This explicitly permits selecting an older release:

(
  set -eu
  read -r -p 'Previously installed release identity: ' installed_release
  python3 photonfile-verifier-setup.py --server 'https://www.photonfile.com' use "$installed_release" --allow-downgrade
)

To remove an installed release, enter its exact identity:

(
  set -eu
  read -r -p 'Installed release identity to remove: ' installed_release
  python3 photonfile-verifier-setup.py --server 'https://www.photonfile.com' uninstall "$installed_release"
)

Uninstall preserves modified and unrelated files, learned revocations, and signed trust history. An editable receipt alone never authorizes execution or deletion. Your exported package, key, and decrypted copies are separate files you manage.

Return to the verification overview.