Signing keys

Every version of an app is signed (see Trust and security). You sign with a key of your own: an Ed25519 key in a file on your computer. Your workspace keeps its public half, and the key stands for you: every version signed with it is yours, whoever deploys it, and members trust you, not the key.

Making a key

matter keys create

It asks for a passphrase (leave it empty for none), makes the key, and registers it in your workspaces as yours. Your first key is your default. The key’s name says which of your keys it is, the computer it was made on unless you give --name "CI"; your own name shows beside it.

The key is a file in ~/.matter/keys, readable by you alone. Matter asks for its passphrase each time you deploy, and never keeps the key unlocked. In scripts, set MATTER_SIGNING_KEY_PASSPHRASE instead.

Agents in Matter run matter as you, so they can deploy with a key that has no passphrase. Give your key a passphrase if only you should deploy with it.

matter keys list          # your keys, * marks the default, and where each is registered
matter keys default <key> # deploy with this key unless told otherwise

Name a key by its name, or its fingerprint as matter keys list shows it.

Which key a deploy uses

matter app deploy signs with, in order:

1. the key --key <key> names;
2. the key in MATTER_SIGNING_KEY;
3. the key "signingKey" names in matter.json, for a project the team always signs with one key;
4. your default key.

The first deploy with a key registers it in the app’s workspace, if it isn’t yet.

Sharing a key with your team

A team that publishes an app together can sign with one person’s key: its versions are then that person’s, whoever deployed them, and open for every member who trusts them. Versions shows both: “Sam (deployed by Ana)”.

matter keys export --private > sales-team-key.json  # its file, passphrase and all

Send the file however your team shares secrets, and have each person keep it on their computer:

matter keys import sales-team-key.json

Or each of you can sign with your own key: each version is then its deployer’s, and members trust each of you.

In CI

Give CI the key’s file as a secret, and set it as MATTER_SIGNING_KEY (with MATTER_SIGNING_KEY_PASSPHRASE if it has one). matter app deploy signs with it, without keeping it.

Revoking a key

matter keys revoke <key>

It revokes the key in your workspaces and sets its file aside (~/.matter/keys/revoked). Every version the key signed stops on every computer, so deploy your apps again with another key: one of yours keeps them yours, so members who trusted you don’t need to again.

The key needn’t be on this computer: name a key you registered elsewhere (a lost laptop’s) by its name or fingerprint, as matter keys list shows them. Whoever registered a key can revoke it, as can anyone holding it, and workspace admins, who can revoke anyone’s.

When someone leaves

A key publishes as its member while they’re in the workspace. When they leave, their keys stop counting: the server refuses deploys with them, and the versions they signed stop, so a copy of a key they shared can’t go on publishing as them. Deploy their apps again with your own key.

What Matter checks

A signature covers the app, the SHA-256 of the version’s zip, and its manifest. The server checks it against the registered key before it takes the version. Each member’s Matter checks it again before it runs any of the version: it checks the key’s fingerprint, the signature, and that the files it downloaded match the zip that was signed. So a version runs only as its key’s holder made it.

Who a key belongs to is what the workspace registered: Matter takes the server’s word for it, as it does for who’s a member.