api.fabaccess-api/main.capnp

@0xbf017710be5a54ff;

using CSharp = import "programming_language/csharp.capnp";
$CSharp.namespace("FabAccessAPI.Schema");

using import "auth.capnp".Authentication;
using import "auth.capnp".AuthSupported;
using import "auth.capnp".Mechanism;
using import "resources.capnp".Resources;
using import "users.capnp".Users;
using import "user.capnp".User;
using import "permissions.capnp".Permissions;

const currentVersion :Version = (major = 1, minor = 0);

struct Version
{
    major @0 :Int32;
    minor @1 :Int32;
}

interface Bootstrap
{
    getAPIVersion @0 () -> Version;
    # Returns the API version implemented by the server. As a client, you can compare this version with the local currentVersion.

    getServerRelease @1 () -> ( name :Text, release :Text );
    # Returns the server implementation name and version/build number Designed only for human-facing
    # debugging output so should be informative over machine-readable.
    # Example: ("bffhd", "0.3.1-f397e1e [rustc 1.57.0 (f1edd0429 2021-11-29)]")

    getServerInfo @2 () -> ( spacename :Text, instanceurl :Text );
    # Returns information about the server, which can be used to resolve MDNS to DNS and display the server name to the user.

    mechanisms @3 () -> AuthSupported;
    # Get a list of Mechanisms this server allows in this context.

    createSession @4 ( mechanism :Text, upgrade :Text ) -> ( authentication :Authentication(Session) );
    # Create a new session with the server that you wish to authenticate using `mechanism`.  If the
    # mechanism is a client-first mechanism you can then immediately call Authentication::step with
    # initial data in a pipelined fashion.  If the mechanism is server-first you must call
    # Authentication::step with a NULL `data` parameter.

    # register @5 () -> ();
    # Placeholder for a future capability for users to register themselves.

}

struct Session {
    # An API session with the server.  The below capabilities are set to NULL if the authenticated
    # user doesn't have permission to access the system in question, or if the server does not
    # implement it.

    whoami @0 :User;
    # Returns the currently authenticated user.

    resources @1 :Resources;
    # Access to the resources configured.

    users @2 :Users;
    # User administration.

    permissions @3 :Permissions;
}