Skip to main content

Upgrading from Excalibur 0.5 to Excalibur 0.6

In this guide, you'll find steps to update your Excalibur app and server instances to version 0.6.

important

Please read this guide carefully and follow all steps.

This guide will assume that the 0.6.x version of the Excalibur server is installed. If you are using version 0.5.x, please upgrade to 0.6.x before proceeding.

Configuration File v5​

Excalibur 0.6 modifies the configuration file from version 4 to version 5, with the following changes:

  • A new table security.opaque was added, containing fields relating to the OPAQUE-3DH protocol, which are:
    • security.opaque.oprf_seed: the seed for Oblivious Pseudo-Random Function (OPRF) operations
    • security.opaque.public_key: the public key for OPAQUE-3DH protocol
    • security.opaque.private_key: the private key for OPAQUE-3DH protocol

Existing configuration files can be upgraded by running

excalibur config update

on the server. Verify that the updated configuration is valid by running the command

excalibur config validate

You should see Config is valid! appear in the terminal.

Database Changes​

The database schema has been updated, with the following changes:

  • Added fields needed for the OPAQUE-3DH protocol
  • Modified existing Secure Remote Password (SRP) fields to be nullable
  • Implemented new database-backed filesystem (explained below)

As such, existing databases need to be upgraded. This can be done by running

excalibur db upgrade

on the server.

New Filesystem​

In previous versions of Excalibur, the filesystem is based on the operating system's filesystem. That means that whatever quirks that the operating system has, will be reflected in Excalibur. For example, on Windows, the filesystem is case-insensitive, while on Linux, it is case-sensitive.

In Excalibur 0.6, we have migrated the filesystem to be based on the database. This makes the filesystem more consistent across platforms. This, however, means that a migration is needed to use the new filesystem.

First, it is recommended to create a backup of the server files by running:

excalibur backup

You can optionally specify the output file name by using the --output flag. By default, a backup file named excalibur-files-backup.zip should have been created.

Now, begin the migration to the new filesystem by running:

excalibur db migrate-files

Server CLI Changes​

excalibur start Command​

The --enable-cors and --disable-cors flags have been renamed to --enable-cors-validation and --no-cors-validation respectively, since "disabling CORS" resulting in all requests being allowed was misleading.

excalibur user add Command​

Along with the addition of the OPAQUE-3DH protocol for authentication, a new option --auth-protocol has been added to the excalibur user add command. It defaults to the new OPAQUE authentication mechanism; for SRP compatibility, specify --auth-protocol=SRP.

Server API Changes​

This update introduces some significant changes to the server API.

MIME Type Determination for Files​

Some endpoints return files or a directory containing a list of items (like files). In previous versions, these Files would include a MIME type in the mimetype field. However, we have removed it from the File type in favour of the client performing their own MIME type determination.

This affects the following endpoints:

  • /api/files/search (which returns a list of file-score pairs)
  • /api/files/list/{path} (which returns a list of files or directories)

If your custom client code interacts with any of these endpoints, you will need to update it to perform MIME type determination on the client side.

Response Content Removed for Some Endpoints​

Certain endpoints' response content have been removed as their response codes sufficiently indicate the success/failure of the operation.

In particular, these endpoints now no longer return any content for the 200 OK status code:

  • /api/files/move (previously returned Item Moved)
  • /api/files/mkdir/{path} (previously returned Directory created)
  • /api/files/rename/{path} (previously returned Item renamed)
  • /api/files/upload/{path} (previously returned File uploaded)

If your custom client code interacts with any of these endpoints, you will need to update it to rely solely on the response code.

App Upgrades​

There are also some upgrades that need to be applied from the app.

Switching from SRP to OPAQUE​

Excalibur 0.6 switches the default authentication protocol from the legacy SRP protocol to the state-of-the-art OPAQUE protocol introduced in RFC9807.

When existing users who use SRP authentication log into the server, a popup will appear asking them to switch to OPAQUE. Simply click on "OK" to complete the transition.

Deprecation

SRP will be deprecated in a future release, so it is recommended to switch to OPAQUE as soon as possible.

New users will automatically use the OPAQUE protocol, so no action is needed for them.

(Optional) Obfuscated Names​

To better improve the privacy of users while using the app, Excalibur 0.6 adds name obfuscation for the files and folders uploaded to the server.

By default, this feature is disabled for existing users, but it can be enabled by:

  1. Logging into the app
  2. Going to the "Settings" page
  3. Going to the "Server Settings" submenu
  4. Toggling "Obfuscated Names"

Conclusion​

These are the steps to upgrade your Excalibur app and server instances to version 0.6. After following these steps, your Excalibur instance should be running on version 0.6.