All resources (tables, views, etc.) on the Space and Time network must be created with a public/private keypair. The public key is added to the CREATE TABLE statement and saved on the network. The private key is used to sign self-describing authorization keys (aka biscuits) which authorize any request to that table.

This allows authorization to be decentralized, while allowing the owner of the table (aka the person holding the private key) to define and share signed biscuits that the table can verify as authentic. The self-describing nature of biscuits also allow that authorization to be limited to a particular table, person, time period, or subscription.

To get started quickly, you can use the SXTCLI to generate a new table keypair AND an admin-level biscuit, all with one command: Open up a terminal window and enter the command:

sxtcli biscuit generate wildcard

The above command will return:

1. An ED25519 keypair (hex encoded) that can be used for creating tables, views, etc.
2. A description of the biscuit capabilities, in this case:
   1. for ANY resource ("*") with a matching public key,
   2. allow ANY command ("*") - hence the name "wildcard" or admin biscuit
3. The actual biscuit key itself

This output will be displayed as:

Biscuit KeyPair (hex)
Private key: D4EAC895937773E3047FE2E9AFA7004B80601BA0F687511BC23658D366FFB51B
Public key:  51297647296389ADABBB6E62230203C620DF47BF8DCAEEF1B1EC35507FBA48E0
Biscuit content:
 Facts:
  sxt:capability("*","*");
Biscuit:
EpABCiYKDnN4dDpjYXBhYmlsaXR5CgEqGAMiDwoNCIAIEgMYgQgSAxiBCBIkCAASIJK...

Note, the below key was modified to be invalid -- please generate your own fresh key!

📘

Both Users and Tables / Views use the ED25519 keypair for security. However, there is a difference in encoding between the two:

• User authentication will expect Base64 encoding
• Tables and Views, which need it embedded in SQL, will expect Hex encoding

The CLI will return the correct encoding when generating new keys.

🚧

Store the private key somewhere safe! If you lose the private key, you lose control of the table, view, or resource!

Multiple tables or views can share a single keypair - for example, a User table and a User_Settings table may share the same keypair (and so wildcard biscuit), since they are related and often operated on together.

That said, it is NOT recommended to reuse keys too widely, as it broadens the exposure of any stolen or lost keys.

👍

Congrats! You have created a new resource public/private keypair!

Access type defines the global default access type for the table or view. For example, you can make the table globally public or private. To set the default table permission, you add the property access_type= to the WITH statement during table creation. If omitted, SxT will default to "Permissioned" (aka Private) which is the most restrictive default permission.

• PERMISSIONED (default setting) - No access is provided by default, and every request must include a biscuit authorization. If not set, your table will default to a Permissioned table.

  • Syntax: modify your WITH statement to:
    WITH "public_key=$RESOURCE_PUBLIC_KEY, access_type=PERMISSIONED" (or omit access_type)
  • Use-Cases: private or internal organizational data, such as CRM data, private application logs, organizational master data, user analytics, etc.

• PUBLIC_READ - Everyone on the network will have SELECT access by default, allowing anyone on the network to run queries on the data. For example, all SxT Blockchain tables are PUBLIC_READ.

  • Syntax: modify your WITH statement to:
    WITH "public_key=$RESOURCE_PUBLIC_KEY, access_type=PUBLIC_READ"
  • Use-Cases: publicly accessible data like weather data, stock or blockchain data, social feeds, test data, or anonymized data for educational or hackathon purposes.

• PUBLIC_APPEND - Everyone on the network will have SELECT,INSERT permissions by default, allowing anyone on the network to query OR insert new data. Only users with the appropriate biscuit authorization can update or delete data, or modify the table's structure. This is sometimes used as a public (append-only) logging mechanism, although it's important to note that anyone on the network can add any number of new records.

  • Syntax: modify your WITH statement to:
    WITH "public_key=$RESOURCE_PUBLIC_KEY, access_type=PUBLIC_APPEND"
  • Use-Cases: Rare, but some publicly accessible logs or anonymized data collection points.

• PUBLIC_WRITE - Everyone on the network will have SELECT,INSERT,UPDATE,DELETE permissions by default, allowing anyone on the network to query, add, delete, or alter any data in the table. Only users with the appropriate biscuit authorization can modify the table or view's structure. This is often used by Space and Time in demo projects, as it allows easy and open access to try SxT features, without needing to worry about biscuits. Because literally anyone can do anything to the data, this is not typically used outside of demos.

  • Syntax: modify your WITH statement to:
    WITH "public_key=$RESOURCE_PUBLIC_KEY, access_type=PUBLIC_WRITE"
  • Use-Cases: Publically accessible temporary data caches (insert / process / delete), or test-dev tables , or for simplified demos of data processes (where data quality doesn't matter)

When you're complete with the activity, simply commit your changes to your branch of work, then push to the SXT-Community/SXTAccreditation repo. Many IDEs have automated processes to manage this for you, but to do this manually by opening a temrinal / WSL window, and typing:

cd ./your/path/SXTAccreditation/<your_folder>
git checkout <your_branch>
git add .  
git commit -m "added my new working file"
git push

If you get an error on line 5 saying, The current branch stephens_work has no upstream branch, this is because Github doesn't know about your branch yet. Simply run the command the git tool recommends - it will look something like:
git push --set-upstream origin <your_branch>

When you're done for the day, head over to SXT-Community/SXTAccreditation/Pulls page on Github, and (if you're logged in) you'll see a message like:

Click on the button above to create a Pull Request, give us some feedback in the description, and click "Create Pull Request". Done!