Issue, Share and Verify a Passport
How to get a signed passport, hand it to someone outside your studio, and check one yourself with nothing but the file and the published public keys.
Issue one
You usually do not have to. Approving a release issues a signed passport in the same step. To issue one at another time:
- Open the release on the Release plan, or the work package’s Passport tab.
- Choose Issue a signed passport. The studio’s owner or an admin can; a lone owner does it alone.
- The new version appears in the list of signed passports, with who issued it.
What you can download
| File | What it is | Give it to |
|---|---|---|
.dsse | The signed envelope: the passport and its signature together | Anyone who will verify it. This is the file that matters |
.json | The exact body that was signed, byte for byte | Someone who wants to read or process the content |
.html | The same record as a page to read, with the verifier’s answer as it stood when the page was made | Someone who wants to read it without tools. A saved page cannot check itself again |
Share one by link
- On the list of signed passports, choose Share… on the version you want. Only the studio’s owner can.
- Choose how long the link lasts: 1 to 30 days.
- Copy the link. It is shown once; the Studio keeps only a fingerprint of it and cannot show it again.
Whoever holds the link sees that one version, rendered, with the verifier’s answer at the moment they look — so an exception that has run out during the link’s life is shown as expired — and can download the .dsse to check for themselves. Revoke a link at any time from the same place. A studio can have up to 25 live links. Creating and revoking a link is audited; who opened one is not recorded.
Verify one, offline
On the list of signed passports, Verify one outside the Studio gives the command and the script. The script needs only Node.js 18 or later — no packages, nothing to install.
- Download the published public keys once and keep them:
curl -fsS https://api.productivityworkbench.com/.well-known/artefact-passport-keys.json -o keys.json - Check the file:
node verify-passport.mjs passport.dsse --keys keys.json - To ask “may this be deployed to production at this commit?”, name the environment and the commit:
node verify-passport.mjs passport.dsse --keys keys.json --environment production --digest COMMIT_SHA
| Exit status | Meaning |
|---|---|
| 0 | The signature is valid. With an environment named: nothing is unmet, no exception has run out, and the commit is one the passport covers |
| 1 | It is not |
| 2 | The command could not be run |
After the keys are downloaded, verification needs no network. Add --json for the full answer. The same check is a public endpoint, POST /verify/passport, which needs no sign-in: the signature is the authentication. And because the file is a standard signed in-toto statement in a DSSE envelope, general-purpose signing tools read it too.
Reading the answer
If you want more than “trust the download”
Each signed passport shows the id of the key that signed it, beside Signed by. Give that id to your verifier out of band and have it accept only that key, rather than whatever the keys address serves on the day. When Productivity Workbench replaces its signing key, the earlier key stays in the published list as retired, so every passport it signed still verifies.
What there is not
There is no public page where a visitor pastes a passport to verify it, and no public log of issued passports. Verification is the script, the endpoint, or your own tools.