Obnam → blog → 2026 → Obnam server API, part 2

Goal

The goal for today is the same as last time:

The goal for today is to start implementation of the Obnam server HTTP API. If all goes well, after this development session I can run the server, and use authenticated requests to upload chunks, download chunks, delete chunks, and search for chunks based on label.

Plan

  • Implement obnam-server token command, with mutually exclusive options --append-only and --delete-also. There is no default. The options choose which claims the token will have.

  • Implement obnam-server validate TOKEN that validates a token and shows its contents as JSON.

  • If there's time, start implementing the HTTP API.

Notes

  • I'll continue with the branch I made last time. The test suite still passes.

  • I changed my mind, since writing the plan above. Instead of mutually exclusive options I'll add a --allow=X, where X is one of append or delete. I think this is clearer as a user that only one is allowed.

  • In the TokenFactory I made last time, based on my prototyping, I'm separating server ID and URL. Why?

  • Ah, a PASETO token separates issuer and audience. For now I don't think that is needed for Obnam API tokens. They're all issued by a specific instance of the server, and the only allowed audience is the same server. So I'll make the command line only have an option for the server URL.

  • I don't have user management yet. I'll stick with a fixed obnam user. Doing user management well is a big task, and I'm doing to skip it for now and only rely on API tokens.

  • Oops, I ran into a roadblock. I've made a configuration file that requires the token signing key to be specified. I don't have a way to generate that key. I'm going to have to make the configuration make the signing key (key pair) to be optional.

  • Made the obnam-server token command generate and output a token.

  • I'll need a way to store the token signing key persistently. My first step was to generate the key pair on every run, but that obviously won't work for validation. So I'll need something like obnam-server init. In hindsight, I should have done this first, but no real harm done. Making the key pair configuration optional is obviously going to be needed anyway.

  • I think I don't want to store the key pair in the configuration. One reason is that configuration files should avoid including sensitive information, and the secret part of the key pair is certainly that. When there's sensitive information you always have to be careful about using or exporting the configuration.

    Another reason is that I don't want init to modify the configuration file. What I'm going to do is have the configuration file specify the location of a file that has the key pair. Modifying files is always tricky.

  • What I'm going to do is have the configuration file specify the name of the file where the key pair is stored. The init command will write that file (and fail if it exists), and when the run time configuration is loaded, the file is read, if it's there.

  • For simplicity, the key pair file will always be JSON. I should probably make the filename be relative to the configuration file where it's specified, but that can wait.

  • I need to put the server URL in the configuration as well. Again, I could've thought about this earlier to make the change easier to make.

  • Added validation of tokens.

  • Added verification scenario for tokens.

  • Merged.

Comments?

If you have feedback on this, please use the following fediverse thread: https://toot.liw.fi/@liw/116034114744774750.