Key Management Refactoring

[Laurin-W]

Controlled Container Dereference Mixin

This is a mixin for controlled containers. You can add it and specify a dereferencePlan. Properties specified in the dereference plan are resolved and attached to the object requested by a get action. We use this, to dereference keys in the webId resource which are now just stored as triples in the form <webId> <sec:publicKey> <public key URI>. This is largely based on https://github.com/assemblee-virtuelle/archipelago/pull/159 by @simonLouvet, thank you :)

Key Services

The old keypair service remains for now but after migration (which needs to be done manually), the service actions redirect to the new key service. Before migration, the new key service is not usable. The new service stores keys in a /key container and public keys in a /public-key container. This makes pod export easier, allows authorized clients to manage keys, and to do client-side signing.

The new service supports both RSA and ed25519 keys.

Migration Instructions

When updating to a new version of semapps, you will need to use the new crypto package, as described in Breaking Changes.

The old service actions are still available so you will not have to change them immediately, neither run the key migration from file sytem to db.

To use the new key service actions, you will need to migrate the key store to the database. For that, call keys.migration.migrateKeysToDb from the repl. From there on, all actions from the legacy keypair service are redirected to the new service. A copy of all keys is kept in the file system in the <actorsKeyPairsDir>/old directory. If something should fail, you can just copy the keys back to the <actorsKeyPairsDir>. The key services check if the keys have been migrated by looking for key files in the <actorsKeyPairDir>, so this will cause the legacy keypair service to be used again.

For the keys service, some call signatures have changed. The most important actions you will probably need are getOrCreateWebIdKeys and getRemotePublicKeys which will return an array of keys. You can find details in the documentation (website or here)

Breaking Changes

WebIdService:

• If you are using the PodService, you will need to remove the webId service since it will be started automatically.
• Otherwise, you will need to change the service's settings:
  • The usersContainer is removed.
  • Instead, add thebaseUrl setting and the relative path setting (without a base url)
  • There is a new acceptedTypes setting (default foaf:Person) which you might need to adjust (e.g. to Object.values(FULL_ACTOR_TYPES) from package @semapps/activitypub)
• The service now uses a controlled container and will handle dynamic resolution of public keys (both ed25519 and RSA) for the fields publicKey and assertionMethod using the ControlledContainerDereference mixin. (Before, RSA keys were stored as blank nodes).

CryptoService and SignatureService:

• The @semapps/signature package is removed in favor of the @semapps/crypto package from which you can import the SignatureService now.
• If you don't use the CoreService, you will need to set up the KeyService for keys management, e.g. like

  this.broker.createService(KeysService, {
    settings: {
      actorsKeyPairsDir: path.resolve(baseDir, './actors'),
    }
  });
  

---

• [x] Semapps unit tests are running through,
• [ ] though for some reasons, I can't run unit tests on APods right now (branch independent), so I couldn't check yet.
• [ ] We need to update the versions at the right time, I set the crypto service to 0.7.0 (same as the others are at right now) but I suppose that's not correct?

---

Since there are quite a lot of code changes and dev capacity issues, unit test coverage is good and I did a self-review already, I think focusing review on the new keys and key-container services, as well as the dereference mixing, would be okay.

With regard to versioning

I created documentation for the services (see the .md files).

If someone could independently review the documentation, that would be awesome :)