Sign and publish a producer manifest

For

Vendors that publish HOS facts: developers, and whoever runs the website

Time

30 minutes

You need

hos, see Install · Your producer's manifest · A website you can publish files on, over HTTPS

Status

Draft

Why this matters#

A manifest decides what consumers trust: the facts you publish, and the values you are the authority on. If anyone could change it, anyone could claim to be the authority on a hotel's rooms. So HOS Events 0.1 has producers sign their manifest, and consumers verify it before trusting it. A manifest that fails verification counts as no manifest: nothing it declares is processed.

What you publish#

A public producer serves three files, on one HTTPS origin, the address of its website:

The private key is never published.

1. Verify an example producer

   HOS publishes the three files of a fictional producer, Example Housekeeping. Download them into a new folder:

   PowerShellCommand PromptmacOS / Linux

   curl -O https://hos-ai.vercel.app/spec/0.1/conformance/signing/well-known/manifest.json
   curl -O https://hos-ai.vercel.app/spec/0.1/conformance/signing/well-known/manifest.jws
   curl -O https://hos-ai.vercel.app/spec/0.1/conformance/signing/well-known/jwks.json

   Verify the manifest with its key set. hos finds the signature next to the manifest, in manifest.jws:

   Terminal

   npx @hos-ai/cli manifest verify manifest.json --jwks jwks.json

   Output

   ✓ manifest.jws: signed with key Rmvn6iiK5EPEKShAwybtwHfST8XHnptFp5kdveGjsfk (Ed25519) on 2026-09-26T00:00:00Z, valid until 2027-09-26T00:00:00Z
   ✓ manifest.json: valid manifest of https://housekeeping.example
   
   ✓ The manifest of https://housekeeping.example is signed and valid.

   What just happened. hos read the signature, found the key it names in the key set, and checked that the signature matches the manifest, byte for byte in its canonical form. It checked the dates, and that the manifest itself is valid.

2. Change the manifest without signing it

   Open manifest.json. In the occupancy declaration, this producer says it is not the authority. Replace "authoritative": false with "authoritative": true, as someone claiming authority on occupancy would, save, and verify again:

   Output

   ✗ manifest.jws: bad signature
     error   The signature does not match this manifest and key Rmvn6iiK5EPEKShAwybtwHfST8XHnptFp5kdveGjsfk: the manifest changed after it was signed, or another key signed it.
             rule events/signed-manifests
   ✓ manifest.json: valid manifest of https://housekeeping.example
   
   ✗ The manifest of https://housekeeping.example fails verification. A consumer treats it as no manifest: nothing it declares is processed.

   The manifest is still valid, but the signature no longer matches it: a consumer ignores the whole manifest, and every fact of this producer. Put false back.

3. Verify as of a later date

   A signature expires. --at verifies as of another time, to see what a consumer will see then:

   Terminal

   npx @hos-ai/cli manifest verify manifest.json --jwks jwks.json --at 2027-10-01T00:00:00Z

   Output

   ✗ manifest.jws: expired
     error   The signature expired on 2027-09-26T00:00:00.000Z. The producer signs its manifest again before it expires.
             rule events/signed-manifests
   ✓ manifest.json: valid manifest of https://housekeeping.example
   
   ✗ The manifest of https://housekeeping.example fails verification. A consumer treats it as no manifest: nothing it declares is processed.

4. Create your key

   Now for your own manifest. In the folder where you keep it, create a key. No manifest yet? Download the example PMS's, from Check what a producer publishes, to try:

   PowerShellCommand PromptmacOS / Linux

   curl -O https://hos-ai.vercel.app/docs/tools/examples/producer/manifest.json

   Then:

   Terminal

   npx @hos-ai/cli manifest keygen --key private-key.json --jwks jwks.json

   $ npx @hos-ai/cli manifest keygen --key private-key.json --jwks jwks.json
   Wrote the private key JX2SZbhtnWjL3S56tqzpZ-uCF0aAYhGO7RMRmQoI9hY (Ed25519) to private-key.json. Keep it secret: whoever holds it can sign as this producer.
   Added its public key to jwks.json, which now holds 1 key. Publish it at /.well-known/hos/jwks.json.

   Your key has another id, its kid: the fingerprint of the public key, which names it in the key set. hos writes two files: private-key.json, the private key, and jwks.json, the key set with the public key. The key is Ed25519; --alg ES256 creates an ES256 key instead, for systems that only support that one.

   Keep the private key secret

   Whoever holds private-key.json can sign as your producer.

   • Never commit it. Add it to your .gitignore:

   Text

   private-key.json

   • Store it in your secrets manager, or wherever your organisation keeps signing keys, and give it only to the system that signs.
   • On macOS and Linux, hos makes the file readable by you alone. Windows does not enforce that: store it in a folder only you can read.

5. Sign the manifest

   Terminal

   npx @hos-ai/cli manifest sign manifest.json --key private-key.json

   Output

   Signed manifest.json with key JX2SZbhtnWjL3S56tqzpZ-uCF0aAYhGO7RMRmQoI9hY (Ed25519), until 2026-12-25T22:21:29Z: manifest.jws.
   Publish it beside the manifest, at /.well-known/hos/manifest.jws, and sign again before it expires.

   hos checks that the manifest is valid, then writes its signature to manifest.jws. The signature lasts 90 days; --days sets another length. Verify it, as for the example:

   Terminal

   npx @hos-ai/cli manifest verify manifest.json --jwks jwks.json

   Output

   ✓ manifest.jws: signed with key JX2SZbhtnWjL3S56tqzpZ-uCF0aAYhGO7RMRmQoI9hY (Ed25519) on 2026-09-26T22:21:29Z, valid until 2026-12-25T22:21:29Z
   ✓ manifest.json: valid manifest of urn:hos:pms:demo
   
   ✓ The manifest of urn:hos:pms:demo is signed and valid.

   The manifest itself does not change: its signature is a separate file. Change the manifest, and you sign it again.

6. Publish the three files

   Put manifest.json, manifest.jws and jwks.json in the folder .well-known/hos/ at the root of your website, and serve them over HTTPS as they are. How depends on your host:

   • A static site or a folder served by your web server: create .well-known/hos/ in the site's root folder. Some tools skip folders whose name starts with a dot: check that the files are deployed.
   • Vercel, Netlify and most front-end hosts: put the folder in the folder your host publishes as is, often public/, so that it becomes public/.well-known/hos/.
   • Nginx: serve the folder with a location, for example:

   Text

   location /.well-known/hos/ {
       root /var/www/hos;
   }

   The files are small, static and public. application/json is the usual content type for the two JSON files; hos reads them whatever their type.

7. Verify what you published

   Give hos the address of your manifest. It fetches the signature and the key set from the same folder:

   Terminal

   npx @hos-ai/cli manifest verify https://your-domain.example/.well-known/hos/manifest.json

   Here is what it prints for the example producer, whose files HOS publishes in another folder, given with --jws and --jwks-url:

   Terminal

   npx @hos-ai/cli manifest verify https://hos-ai.vercel.app/spec/0.1/conformance/signing/well-known/manifest.json --jws https://hos-ai.vercel.app/spec/0.1/conformance/signing/well-known/manifest.jws --jwks-url https://hos-ai.vercel.app/spec/0.1/conformance/signing/well-known/jwks.json

   Output

   ✓ https://hos-ai.vercel.app/spec/0.1/conformance/signing/well-known/manifest.jws: signed with key Rmvn6iiK5EPEKShAwybtwHfST8XHnptFp5kdveGjsfk (Ed25519) on 2026-09-26T00:00:00Z, valid until 2027-09-26T00:00:00Z
   ✓ https://hos-ai.vercel.app/spec/0.1/conformance/signing/well-known/manifest.json: valid manifest of https://housekeeping.example
   
   ✓ The manifest of https://housekeeping.example is signed and valid.

Sign again before it expires#

A signature lasts 90 days by default. Sign again well before, for example every 60 days, and publish the new manifest.jws. The same key can sign again: nothing else changes.

To be warned in time, verify your published manifest as of a date a few weeks ahead, for example in a scheduled CI job. It fails while there is still time to sign:

npx @hos-ai/cli manifest verify https://your-domain.example/.well-known/hos/manifest.json --at 2027-01-15T00:00:00Z

Run the checks in CI will give a complete workflow.

Change keys#

Change keys from time to time, and whenever a key may have been seen by someone it should not. Add the new key to the same key set:

npx @hos-ai/cli manifest keygen --key private-key-2.json --jwks jwks.json

Wrote the private key sqWWEPDBWPptMJ4bVa9WOEcSImfGPBGGoxFosvSI9rc (Ed25519) to private-key-2.json. Keep it secret: whoever holds it can sign as this producer.
Added its public key to jwks.json, which now holds 2 keys. Publish it at /.well-known/hos/jwks.json.

Then:

1. publish the new jwks.json, with both keys;
2. sign with the new key, --key private-key-2.json, and publish the new manifest.jws;
3. keep the old key in the key set until every signature made with it has expired, then remove it from jwks.json, publish, and delete the old private key.

If a private key leaks#

Whatever the key signed can be forged until the key is gone. At once:

1. remove its public key from jwks.json, and publish the key set;
2. create a new key, sign the manifest with it, and publish manifest.jws and jwks.json;
3. delete the old private key everywhere it was stored.

Once the old key is gone from the key set, anything signed with it fails verification, including forgeries.

A private key published by mistake in the key set is a leak too. hos refuses it:

✗ manifest.jws: unusable key
  error   Key _qrqVc4ppJqRlSjHYaHTqNznScDUivyY67dYQl78kiw is a private key. A key set publishes public keys only: this private key is exposed and must be replaced.
          rule events/signed-manifests

A producer that is not public#

A producer that does not publish on the web gives its consumers the three files through configured, authenticated URLs, or as files. Consumers verify them from files:

npx @hos-ai/cli manifest verify manifest.json --jws manifest.jws --jwks jwks.json

Why a signature fails#

Clocks may differ by up to 60 seconds: hos and consumers allow it.

Next steps#

• Check what a producer publishes: the facts that your manifest declares.
• Run the checks in CI: verify your manifest every day, and be warned before it expires.
• HOS Events 0.1, signed manifests: the rules themselves.