Continue Bee

Continue Bee (50 points to anyone who gets the reference) is a lightweight implementation of the Sessionless authentication protocol, which allows implementers to save a hash of client state, and then check that state when a client returns.

Overview

Continue Bee is composed of a CRUD server and database pair, and companion client-side libraries. This repo defines the contract between client and server via REST API, provides database implementation(s) for storing the models used in that contract, and the methods necessary in a client implementation.

The typical usage will look something like:

sequenceDiagram
    Client->>+Server: Register User
    Server->>+DB: Save userUUID
    Server->>+Client: Sends userUUID
    Client->>+Server: Sends State Hash
    Server->>+DB: Saves State Hash
    Client->>+Server: Returns and re-sends state hash
    Server->>+DB: Checks State Hash
    Server->>+Client: Returns OK/not OK

Loading

And here's what the architecture looks like:

flowchart TD
    A[(DB)] <-->|CRUD| B{Server}
    B <--> |REST API| C[SDK in Language 1]
    B <-->|REST API| D[SDK in Language 2]
    B <-->|REST API| E[SDK in Language 3]

Loading

API

It doesn't get much CRUDier than this API:

POST /user/create Creates a new user if pubKey does not exist, and returns existing uuid if it does. signature message is: timestamp + pubKey + hash

Parameters

name	required	data type	description
pubKey	true	string (hex)	the publicKey of the user's keypair
timestamp	true	string	in a production system timestamps prevent replay attacks
hash	true	string	the state hash to save for the user
signature	true	string (signature)	the signature from sessionless for the message

Responses

http code	content-type	response
200	application/json	{"userUUID": <uuid>}
400	application/json	{"code":"400","message":"Bad Request"}

Example cURL

 curl -X PUT -H "Content-Type: application/json" -d '{"pubKey": "key", "timestamp": "now", "signature": "sig"}' https://www.continuebee.com/user/create

GET /user/:uuid?timestamp=&hash=&signature= Returns whether last saved hash matches sent hash

Parameters

name	required	data type	description
timestamp	true	string	in a production system timestamps prevent replay attacks
hash	true	string	the state hash saved client side
signature	true	string (signature)	the signature from sessionless for the message

Responses

http code	content-type	response
200	application/json	{"userUUID": <uuid>}
406	application/json	{"code":"406","message":"Not acceptable"}

Example cURL

 curl -X GET -H "Content-Type: application/json" https://www.continuebee.com/<uuid>?timestamp=123&hash=hash&signature=signature 

PUT /user/:uuid/save-hash Returns whether last saved hash matches sent hash. signature message is: timestamp + pubkey + hash + newHash

Parameters

name	required	data type	description
timestamp	true	string	in a production system timestamps prevent replay attacks
userUUID	true	string	the user's uuid
hash	true	string	the old hash to replace
newHash	true	string	the state hash saved client side
signature	true	string (signature)	the signature from sessionless for the message

Responses

http code	content-type	response
200	application/json	{"userUUID": <uuid>}
400	application/json	{"code":"400","message":"Bad Request"}

Example cURL

 curl -X POST -H "Content-Type: application/json" -d '{"timestamp": "right now", "userUUID": "uuid", "hash": "hash", "newHash": "newHash", "signature": "signature"}' https://www.continuebee.com/user/update-hash

DELETE /user/delete Deletes a uuid and pubKey. signature message is: timestamp + userUUID + hash

Parameters

name	required	data type	description
timestamp	true	string	in a production system timestamps prevent replay attacks
userUUID	true	string	the user's uuid
hash	true	string	the old hash to replace
signature	true	string (signature)	the signature from sessionless for the message

Responses

http code	content-type	response
202	application/json	empty
400	application/json	{"code":"400","message":"Bad Request"}

Example cURL

 curl -X DELETE https://www.continuebee.com/user/delete

Databases

One of the biggest benefits of Sessionless is that it doesn't need to store any sensitive data. This means all of the data Continue Bee cares about can all be saved in a single table/collection/whatever-other-construct-some-database-may-have. And that table looks like:

uuid	pubKey	hash
string	string	string

uuid, and pubKey should have unique constraints (Sessionless generated keys and uuids should not collide, but since this is a public API people may just reuse keys and uuids).

Client SDKs

Client SDKs need to generate keys via Sessionless, and implement the networking to interface with the server. To do so they should implement the following methods:

createUser(hash, saveKeys, getKeys) - Should generate keys, save them appropriately client side, and PUT to /user/create.

updateHash(uuid, hash, newHash) - Should POST the passed in hash to /user/:uuid/update-hash.

checkHash(uuid, hash) - Should GET to check the saved hash on the client against the saved hash on the server via /user/:uuid?timestamp=timestamp&hash=hash&signature=signature.

deleteUser(uuid, hash) - Should DELETE a user by calling /user/:uuid.

Use cases

NOTE Continue bee is experimental, and the instance at continuebee.com is ephemeral, and may go away or reset at any time. If you're making the next Palworld and want to use continuebee, you're advised to self-host it, or contact zach@planetnine.app to help him upgrade the micro instance it runs on :).

• If you have a game with some state stored locally, say gems a user has acquired, and you don't want them to mess with the number of gems, you can use continuebee to save their gem number periodically, and then check that number when they return to the game.

• You can use continuebee as straight auth for your backend instead of other auth providers.

• You can use continuebee for account continuity before using more intrusive auth layers. I.e. instead of having potential players bounce off because of needing to enter their email/password before playing, you can auth with continuebee, and then ask for email/password when they hit level five after they've been hooked.

• Just use it as a practice backend before figuring out all the auth needs of your game/app.

Self-hosting

This is a bit dependent on what the server implementations are, so we'll fill the details in later, but the idea is that continuebee is hostable by others either for public use like the main instance, or private use.

Contributing

To add to this repo, feel free to make a pull request.