Signed rule-pack updates

In short

SpeculaPro publishes rule-pack updates (new rules, revised defaults, packs for new jurisdictions) as signed bundle files, separately from program releases. You can install one without upgrading SpeculaPro, which matters on a network where upgrades are slow to approve or where there is no internet connection at all.

A bundle is the pack exactly as SpeculaPro wrote it, plus an Ed25519 signature by SpeculaPro. SpeculaPro checks the signature before it reads anything inside the file. A bundle that was altered, or that wasn’t signed by SpeculaPro, is refused.

Packs built into the program are trusted because the program itself is signed (see Verifying releases). Bundles use different signing keys from licences, so a licence key could never be used to ship rules, or the other way round.

Two ways to install a bundle

Where	Who	How
The web app: Rules, Rule packs panel, Signed pack update	People who can approve rules (`rules.approve`)	See Installing a pack
The command line, below	The operator, recording the install against a named person in a workspace	`speculapro packs install`

How to check a bundle before installing it

speculapro packs verify gh-bank-1.1.0.sppack

OK: pack gh-bank 1.1.0 (Ghana banks), 11 rules, signed with pack-2026-1

verify checks the signature against the keys built into your release and reads the pack, but changes nothing. It doesn’t need a database. If the signature doesn’t verify, it stops with rule-pack bundle is not valid: … and the reason.

How to install a bundle from the command line

# Docker Compose
docker compose run --rm -v "$PWD/gh-bank-1.1.0.sppack:/tmp/gh-bank.sppack:ro" cli \
  packs install /tmp/gh-bank.sppack --workspace acme --as [email protected]

pack gh-bank 1.1.0: upgraded, signed with pack-2026-1
  1 rule added (disabled until enabled)
  3 rules updated: new versions await approval
  6 rules unchanged

Rules your workspace changed, or whose tuning no longer fits, are listed by name with the reason.

The file must be readable by the container’s user (UID 65532), for example chmod 644.

Option	Meaning
`--workspace`	The workspace (its slug) to install or upgrade the pack in
`--as`	An active person in that workspace, by email, who holds `rules.approve` (and `rules.packs_downgrade` with `--force`). The install is recorded in the audit log under their name. Someone without the permission is refused: … doesn’t hold rules.approve in workspace acme: installing a pack needs it
`--force`	Allow an older version than the one installed. Use it only when SpeculaPro asks you to roll a pack back. The `--as` person needs `rules.packs_downgrade` (the MLRO role has it); it is recorded as a downgrade

The result says what happened:

Result	Meaning
`installed`	The workspace didn’t have the pack. Every rule was added, switched off, for your compliance team to review and enable
`upgraded`	The workspace had an older version. Rules new in this version were added, switched off, and rules whose definition changed got a new version awaiting approval
`unchanged`	The workspace already has this exact version. Nothing changed
`downgraded`	`--force` moved to an older version, the same way: changed rules got versions awaiting approval

What a bundle changes

New rules arrive switched off. Nothing new runs until someone with rules.approve reviews and enables it, as with a built-in pack.
Rules you already have are updated the same way as a built-in upgrade. A rule whose definition changed gets a new version, with the workspace’s tuning carried over, waiting for someone else to approve it; the version running today keeps running until then. Rules the workspace changed itself are left alone and listed. Installing a bundle never changes a running rule by itself.
The bundle becomes available to every workspace on the installation. Workspaces other than the one you installed it in see the newer version on their Rules page and upgrade in the usual way. See Installing a pack.

What is refused

Situation	Message
The signature doesn’t verify, or the file isn’t a pack bundle	`rule-pack bundle is not valid: …`
The bundle claims the same version as the pack built into your release, but its contents differ	`pack <key> <version> differs from the built-in pack of the same version`
A bundle with the same version but different contents was installed before	`pack <key> <version> is already present with different content`
The bundle is older than the installed version, without `--force`	`… someone allowed to downgrade packs can force it`
The licence has lapsed	Installing and upgrading rule packs is paused until a valid license is installed … See Licensing

So a version number always means one exact set of rules: nobody can slip different rules in under a version you have already reviewed.

How bundles are kept

Every bundle installed is stored in the database byte for byte, with its signature, and is verified again every time SpeculaPro loads it. Editing a stored bundle makes SpeculaPro ignore it. A bundle signed with a key that a later release no longer trusts is also ignored.

Each install is in the audit log: rule_pack.install, rule_pack.upgrade or rule_pack.downgrade, with the pack, the versions, the rules added, source: bundle, the signing key and, for a downgrade, forced: true.

On an air-gapped network

Download the bundle on a connected machine.
Carry it across with your approved media.
Run speculapro packs verify inside the network, then install it from the web app or the command line.

No connection to SpeculaPro is needed at any step: the keys that check the signature are in your release.