• Simple, centralized identity storage and password checking. Passwords are securely stored using PBKDF2.
• Email-based password reset functionality with a minimalist web interface.
• Full API access for all operations: Separate user-facing and administrator-facing APIs are exposed on different ports and are accessed using an efficient binary protocol over HTTP.
• Full Java API for performing user and administrative operations.
• Strong separation between administrators and users.
• Fine-grained capability based security model for administrative operations; Safely write external services that can perform administrative operations while maintaining the principle of least privilege.
• Command-line administrative shell.
• Complete audit log; every operation that changes the state of the system is logged in an append-only log.
• Fully instrumented with OpenTelemetry.
• A small, easily auditable codebase with a heavy use of modularity for correctness.
• An extensive automated test suite with high coverage.
• Platform independence. No platform-dependent code is included in any form, and installations can largely be carried between platforms without changes.
• OSGi-ready
• JPMS-ready
• ISC license.

• Maven Central
• Quay.io

$ gpg --verify com.io7m.idstore.main-1.0.0-beta0018-distribution.zip.asc
gpg: assuming signed data in 'com.io7m.idstore.main-1.0.0-beta0018-distribution.zip.asc'
gpg: Signature made Tue 28 Jun 2022 15:01:56 GMT
gpg:                using RSA key 3CCE59428B30462D10459909C5607DA146E128B8
gpg:                issuer "contact@io7m.com"
gpg: using pgp trust model
gpg: Good signature from "io7m.com (2022 maven-rsa-key) <contact@io7m.com>" [unknown]

$ unzip com.io7m.idstore.main-1.0.0-beta0018-distribution.zip
$ export IDSTORE_HOME=$(realpath idstore)
$ ./idstore/bin/idstore
idstore: usage: idstore [command] [arguments ...]
...

$ podman pull quay.io/io7mcom/idstore:1.0.0-beta0018
$ podman run quay.io/io7mcom/idstore:1.0.0-beta0018
idstore: usage: idstore [command] [arguments ...]
...

$ curl http://localhost:51000/health
OK

$ idstore initial-admin \
  --admin-id '92f83bce-3973-4db8-8aaf-d401443a9772' \
  --admin-email 'someone@example.com' \
  --admin-realname 'Someone Else' \
  --admin-username 'someone' \
  --admin-password 12345678 \
  --configuration server.conf

$ idstore server --configuration server.conf
info: [localhost/<unresolved>:50000] User API server started
info: [localhost/<unresolved>:50001] User view server started
info: [localhost/<unresolved>:51000] Admin API server started

$ idstore shell
[idstore]# version
com.io7m.idstore 0.0.15-SNAPSHOT 20af71248a7784b0e5247eab4b1ebd28de284739

$ podman run \
  --name some-postgres \
  -e POSTGRES_USER=idstore_install \
  -e POSTGRES_PASSWORD=mysecretpassword \
  -d postgres

<?xml version="1.0" encoding="UTF-8" ?>

<Configuration xmlns="urn:com.io7m.idstore:configuration:1">
  <Branding ProductTitle="idstore"/>

  <Database Name="idstore"
            Kind="POSTGRESQL"
            OwnerRoleName="idstore_install"
            OwnerRolePassword="mydatabasewill"
            WorkerRolePassword="probablybecompromised"
            Address="db.example.com"
            Port="5432"
            Create="true"
            Upgrade="true"/>

  <HTTPServices>
    <HTTPServiceAdminAPI ListenAddress="[::]"
                         ListenPort="51000"
                         ExternalURI="http://[::]:51000/"/>
    <HTTPServiceUserAPI ListenAddress="[::]"
                        ListenPort="50000"
                        ExternalURI="http://[::]:50000/"/>
    <HTTPServiceUserView ListenAddress="[::]"
                         ListenPort="50001"
                         ExternalURI="http://[::]:50001/"/>
  </HTTPServices>

  <History UserLoginHistoryLimit="10" AdminLoginHistoryLimit="100"/>

  <Mail SenderAddress="no-reply@example.com" VerificationExpiration="PT24H">
    <SMTP Host="mail.example.com"
          Port="25"/>
  </Mail>

  <RateLimiting EmailVerificationRateLimit="PT10M" PasswordResetRateLimit="PT10M" />

  <Sessions UserSessionExpiration="PT30M" AdminSessionExpiration="PT30M"/>
</Configuration>

<Mail SenderAddress="no-reply@example.com"
      VerificationExpiration="PT24H">
  <SMTP Host="mail.example.com"
        Port="25"/>
</Mail>

<HTTPServices>
  <HTTPServiceAdminAPI ListenAddress="localhost"
                       ListenPort="51000"
                       ExternalURI="http://localhost:51000/"/>
  <HTTPServiceUserAPI ListenAddress="localhost"
                      ListenPort="50000"
                      ExternalURI="http://localhost:50000/"/>
  <HTTPServiceUserView ListenAddress="localhost"
                       ListenPort="50001"
                       ExternalURI="http://localhost:50001/"/>
</HTTPServices>

<Sessions UserSessionExpiration="PT30M"
          AdminSessionExpiration="PT30M"/>

<History UserLoginHistoryLimit="100"
         AdminLoginHistoryLimit="10000"/>

<Database Kind="POSTGRESQL"
          OwnerRoleName="idstore_install"
          OwnerRolePassword="mydatabasewill"
          WorkerRolePassword="probablybecompromised"
          ReaderRolePassword="lookbutdonottouch"
          Address="localhost"
          Port="54322"
          Create="true"
          Upgrade="true"/>

<RateLimiting
  EmailVerificationRateLimit="PT10M"
  PasswordResetRateLimit="PT10M"
  UserLoginRateLimit="PT5S"
  UserLoginDelay="PT1S"
  AdminLoginRateLimit="PT5S"
  AdminLoginDelay="PT1S" />

<PasswordExpiration
  UserPasswordValidityDuration="PT720H"
  AdminPasswordValidityDuration="PT2160H" />

<OpenTelemetry LogicalServiceName="idstore">
  <Logs Endpoint="http://logs.example.com:4317"
        Protocol="GRPC"/>
  <Metrics Endpoint="http://metrics.example.com:4317"
           Protocol="GRPC"/>
  <Traces Endpoint="http://traces.example.com:4317"
          Protocol="GRPC"/>
</OpenTelemetry>

<Branding ProductTitle="idstore">
  <ColorScheme>
    <ButtonColors>
      <Disabled>
        <BodyColor Red="0.101"
                   Green="0.309"
                   Blue="0.45"/>
        <BorderColor Red="0"
                     Green="0"
                     Blue="0"/>
        <EmbossEColor Red="0.175"
                      Green="0.527"
                      Blue="0.765"/>
        <EmbossNColor Red="0.175"
                      Green="0.527"
                      Blue="0.765"/>
        <EmbossSColor Red="0.07"
                      Green="0.214"
                      Blue="0.316"/>
        <EmbossWColor Red="0.07"
                      Green="0.214"
                      Blue="0.316"/>
        <TextColor Red="0"
                   Green="0"
                   Blue="0"/>
      </Disabled>
      <Enabled>
        <BodyColor Red="0.101"
                   Green="0.309"
                   Blue="0.45"/>
        <BorderColor Red="0"
                     Green="0"
                     Blue="0"/>
        <EmbossEColor Red="0.175"
                      Green="0.527"
                      Blue="0.765"/>
        <EmbossNColor Red="0.175"
                      Green="0.527"
                      Blue="0.765"/>
        <EmbossSColor Red="0.07"
                      Green="0.214"
                      Blue="0.316"/>
        <EmbossWColor Red="0.07"
                      Green="0.214"
                      Blue="0.316"/>
        <TextColor Red="0"
                   Green="0"
                   Blue="0"/>
      </Enabled>
      <Hover>
        <BodyColor Red="0.125"
                   Green="0.371"
                   Blue="0.539"/>
        <BorderColor Red="0"
                     Green="0"
                     Blue="0"/>
        <EmbossEColor Red="0.175"
                      Green="0.527"
                      Blue="0.765"/>
        <EmbossNColor Red="0.175"
                      Green="0.527"
                      Blue="0.765"/>
        <EmbossSColor Red="0.07"
                      Green="0.214"
                      Blue="0.316"/>
        <EmbossWColor Red="0.07"
                      Green="0.214"
                      Blue="0.316"/>
        <TextColor Red="0"
                   Green="0"
                   Blue="0"/>
      </Hover>
      <Pressed>
        <BodyColor Red="0.093"
                   Green="0.277"
                   Blue="0.406"/>
        <BorderColor Red="0"
                     Green="0"
                     Blue="0"/>
        <EmbossEColor Red="0.07"
                      Green="0.214"
                      Blue="0.316"/>
        <EmbossNColor Red="0.07"
                      Green="0.214"
                      Blue="0.316"/>
        <EmbossSColor Red="0.125"
                      Green="0.371"
                      Blue="0.539"/>
        <EmbossWColor Red="0.125"
                      Green="0.371"
                      Blue="0.539"/>
        <TextColor Red="0"
                   Green="0"
                   Blue="0"/>
      </Pressed>
    </ButtonColors>

    <ErrorBorderColor Red="1"
                      Green="0"
                      Blue="0"/>

    <HeaderBackgroundColor Red="0.184"
                           Green="0.184"
                           Blue="0.184"/>

    <HeaderLinkColor Red="1"
                     Green="1"
                     Blue="1"/>

    <HeaderTextColor Red="1"
                     Green="1"
                     Blue="1"/>

    <MainBackgroundColor Red="0.101"
                         Green="0.309"
                         Blue="0.45"/>

    <MainLinkColor Red="1"
                   Green="1"
                   Blue="1"/>

    <MainMessageBorderColor Red="0.1875"
                            Green="0.558"
                            Blue="0.8125"/>

    <MainTableBorderColor Red="0.1875"
                          Green="0.558"
                          Blue="0.8125"/>

    <MainTextColor Red="1"
                   Green="1"
                   Blue="1"/>
  </ColorScheme>
</Branding>

<?xml version="1.0" encoding="UTF-8" ?>

<schema xmlns="http://www.w3.org/2001/XMLSchema"
        xmlns:c="urn:com.io7m.idstore:configuration:1"
        targetNamespace="urn:com.io7m.idstore:configuration:1">

  <simpleType name="ColorComponent">
    <annotation>
      <documentation>
        The type of a component within a color.
      </documentation>
    </annotation>
    <restriction base="double">
      <minInclusive value="0.0"/>
      <maxInclusive value="1.0"/>
    </restriction>
  </simpleType>

  <complexType name="ColorType">
    <annotation>
      <documentation>
        An RGB color.
      </documentation>
    </annotation>

    <attribute name="Red"
               type="c:ColorComponent"
               use="required"/>
    <attribute name="Green"
               type="c:ColorComponent"
               use="required"/>
    <attribute name="Blue"
               type="c:ColorComponent"
               use="required"/>
  </complexType>

  <element name="ErrorBorderColor"
           type="c:ColorType">
    <annotation>
      <documentation>
        The color used for the border around error messages on web pages.
      </documentation>
    </annotation>
  </element>

  <element name="HeaderBackgroundColor"
           type="c:ColorType">
    <annotation>
      <documentation>
        The color used for the web page header background.
      </documentation>
    </annotation>
  </element>

  <element name="HeaderLinkColor"
           type="c:ColorType">
    <annotation>
      <documentation>
        The color used for the web page header links.
      </documentation>
    </annotation>
  </element>

  <element name="HeaderTextColor"
           type="c:ColorType">
    <annotation>
      <documentation>
        The color used for the web page header text.
      </documentation>
    </annotation>
  </element>

  <element name="MainBackgroundColor"
           type="c:ColorType">
    <annotation>
      <documentation>
        The color used for the web page main background.
      </documentation>
    </annotation>
  </element>

  <element name="MainLinkColor"
           type="c:ColorType">
    <annotation>
      <documentation>
        The color used for the web page main links on web pages.
      </documentation>
    </annotation>
  </element>

  <element name="MainMessageBorderColor"
           type="c:ColorType">
    <annotation>
      <documentation>
        The color used for the border around non-error messages on web pages.
      </documentation>
    </annotation>
  </element>

  <element name="MainTableBorderColor"
           type="c:ColorType">
    <annotation>
      <documentation>
        The color used for table borders on web pages.
      </documentation>
    </annotation>
  </element>

  <element name="MainTextColor"
           type="c:ColorType">
    <annotation>
      <documentation>
        The color used for the main text on web pages.
      </documentation>
    </annotation>
  </element>

  <element name="TextColor"
           type="c:ColorType">
    <annotation>
      <documentation>
        The color used for the button text.
      </documentation>
    </annotation>
  </element>

  <element name="BodyColor"
           type="c:ColorType">
    <annotation>
      <documentation>
        The color used for the button body.
      </documentation>
    </annotation>
  </element>

  <element name="BorderColor"
           type="c:ColorType">
    <annotation>
      <documentation>
        The color used for the button border.
      </documentation>
    </annotation>
  </element>

  <element name="EmbossEColor"
           type="c:ColorType">
    <annotation>
      <documentation>
        The color used for the east-facing emboss.
      </documentation>
    </annotation>
  </element>

  <element name="EmbossSColor"
           type="c:ColorType">
    <annotation>
      <documentation>
        The color used for the south-facing emboss.
      </documentation>
    </annotation>
  </element>

  <element name="EmbossWColor"
           type="c:ColorType">
    <annotation>
      <documentation>
        The color used for the west-facing emboss.
      </documentation>
    </annotation>
  </element>

  <element name="EmbossNColor"
           type="c:ColorType">
    <annotation>
      <documentation>
        The color used for the north-facing emboss.
      </documentation>
    </annotation>
  </element>

  <complexType name="ButtonStateColors">
    <annotation>
      <documentation>
        The colors used for a particular button state.
      </documentation>
    </annotation>
    <sequence>
      <element ref="c:BodyColor"/>
      <element ref="c:BorderColor"/>
      <element ref="c:EmbossEColor"/>
      <element ref="c:EmbossNColor"/>
      <element ref="c:EmbossSColor"/>
      <element ref="c:EmbossWColor"/>
      <element ref="c:TextColor"/>
    </sequence>
  </complexType>

  <element name="Enabled"
           type="c:ButtonStateColors">
    <annotation>
      <documentation>
        The colors used when the button is in the unpressed, enabled state.
      </documentation>
    </annotation>
  </element>

  <element name="Disabled"
           type="c:ButtonStateColors">
    <annotation>
      <documentation>
        The colors used when the button is in the disabled state.
      </documentation>
    </annotation>
  </element>

  <element name="Pressed"
           type="c:ButtonStateColors">
    <annotation>
      <documentation>
        The colors used when the button is in the pressed state.
      </documentation>
    </annotation>
  </element>

  <element name="Hover"
           type="c:ButtonStateColors">
    <annotation>
      <documentation>
        The colors used when the button is in the hover state.
      </documentation>
    </annotation>
  </element>

  <element name="ButtonColors">
    <annotation>
      <documentation>
        The colors used for all button states.
      </documentation>
    </annotation>
    <complexType>
      <sequence>
        <element ref="c:Disabled"/>
        <element ref="c:Enabled"/>
        <element ref="c:Hover"/>
        <element ref="c:Pressed"/>
      </sequence>
    </complexType>
  </element>

  <element name="ColorScheme">
    <complexType>
      <sequence>
        <element ref="c:ButtonColors"/>
        <element ref="c:ErrorBorderColor"/>
        <element ref="c:HeaderBackgroundColor"/>
        <element ref="c:HeaderLinkColor"/>
        <element ref="c:HeaderTextColor"/>
        <element ref="c:MainBackgroundColor"/>
        <element ref="c:MainLinkColor"/>
        <element ref="c:MainMessageBorderColor"/>
        <element ref="c:MainTableBorderColor"/>
        <element ref="c:MainTextColor"/>
      </sequence>
    </complexType>
  </element>

  <element name="Branding">
    <complexType>
      <sequence>
        <element ref="c:ColorScheme"
                 minOccurs="0"
                 maxOccurs="1"/>
      </sequence>

      <attribute name="ProductTitle"
                 use="required"
                 type="string">
        <annotation>
          <documentation>
            The product title that will be used in web pages and emails.
          </documentation>
        </annotation>
      </attribute>

      <attribute name="Logo"
                 use="optional"
                 type="anyURI">
        <annotation>
          <documentation>
            A file that contains a logo image used in web pages.
          </documentation>
        </annotation>
      </attribute>

      <attribute name="LoginExtra"
                 use="optional"
                 type="anyURI">
        <annotation>
          <documentation>
            A file that contains XHTML text that will be inserted into login web pages.
          </documentation>
        </annotation>
      </attribute>
    </complexType>
  </element>

  <complexType name="MailTransportType">
    <annotation>
      <documentation>
        The base type of mail transport configurations.
      </documentation>
    </annotation>
  </complexType>

  <complexType name="SMTPType">
    <annotation>
      <documentation>
        Settings for communicating over SMTP without encryption.
      </documentation>
    </annotation>
    <complexContent>
      <extension base="c:MailTransportType">
        <attribute name="Host"
                   type="anyURI"
                   use="required"/>
        <attribute name="Port"
                   type="unsignedInt"
                   use="required"/>
      </extension>
    </complexContent>
  </complexType>

  <complexType name="SMTPTLSType">
    <annotation>
      <documentation>
        Settings for communicating over SMTP_TLS.
      </documentation>
    </annotation>
    <complexContent>
      <extension base="c:MailTransportType">
        <attribute name="Host"
                   type="anyURI"
                   use="required"/>
        <attribute name="Port"
                   type="unsignedInt"
                   use="required"/>
      </extension>
    </complexContent>
  </complexType>

  <complexType name="SMTPSType">
    <annotation>
      <documentation>
        Settings for communicating over SMTPS.
      </documentation>
    </annotation>
    <complexContent>
      <extension base="c:MailTransportType">
        <attribute name="Host"
                   type="anyURI"
                   use="required"/>
        <attribute name="Port"
                   type="unsignedInt"
                   use="required"/>
      </extension>
    </complexContent>
  </complexType>

  <element name="SMTP"
           type="c:SMTPType"/>
  <element name="SMTPTLS"
           type="c:SMTPTLSType"/>
  <element name="SMTPS"
           type="c:SMTPSType"/>

  <element name="MailAuthentication">
    <annotation>
      <documentation>
        The mail server authentication configuration.
      </documentation>
    </annotation>

    <complexType>
      <attribute name="Username"
                 type="string"
                 use="required">
        <annotation>
          <documentation>
            The username that will be used to authenticate to the mail server.
          </documentation>
        </annotation>
      </attribute>
      <attribute name="Password"
                 type="string"
                 use="required">
        <annotation>
          <documentation>
            The password that will be used to authenticate to the mail server.
          </documentation>
        </annotation>
      </attribute>
    </complexType>
  </element>

  <element name="Mail">
    <annotation>
      <documentation>
        The mail server configuration.
      </documentation>
    </annotation>

    <complexType>
      <sequence>
        <choice minOccurs="1"
                maxOccurs="1">
          <element ref="c:SMTP"/>
          <element ref="c:SMTPS"/>
          <element ref="c:SMTPTLS"/>
        </choice>
        <element ref="c:MailAuthentication"
                 minOccurs="0"
                 maxOccurs="1"/>
      </sequence>

      <attribute name="SenderAddress"
                 type="string"
                 use="required"/>
      <attribute name="VerificationExpiration"
                 type="duration"
                 use="required"/>
    </complexType>
  </element>

  <element name="History">
    <annotation>
      <documentation>
        Retention settings for logins.
      </documentation>
    </annotation>

    <complexType>
      <attribute name="UserLoginHistoryLimit"
                 type="unsignedInt"
                 use="required">
        <annotation>
          <documentation>
            The number of login records to store for users.
          </documentation>
        </annotation>
      </attribute>
      <attribute name="AdminLoginHistoryLimit"
                 type="unsignedInt"
                 use="required">
        <annotation>
          <documentation>
            The number of login records to store for admins.
          </documentation>
        </annotation>
      </attribute>
    </complexType>
  </element>

  <complexType name="HTTPServiceType">
    <attribute name="ListenAddress"
               use="required"
               type="string">
      <annotation>
        <documentation>
          The address upon which this HTTP service will listen.
        </documentation>
      </annotation>
    </attribute>
    <attribute name="ListenPort"
               use="required"
               type="unsignedInt">
      <annotation>
        <documentation>
          The port upon which this HTTP service will listen.
        </documentation>
      </annotation>
    </attribute>
    <attribute name="ExternalURI"
               use="required"
               type="anyURI">
      <annotation>
        <documentation>
          The external URI by which this HTTP service will be accessible. This is used in emails and web pages and is
          primarily useful when the HTTP service will be used behind a reverse proxy.
        </documentation>
      </annotation>
    </attribute>
  </complexType>

  <element name="HTTPServiceAdminAPI"
           type="c:HTTPServiceType">
    <annotation>
      <documentation>
        Configuration for the Admin API service.
      </documentation>
    </annotation>
  </element>

  <element name="HTTPServiceUserAPI"
           type="c:HTTPServiceType">
    <annotation>
      <documentation>
        Configuration for the User API service.
      </documentation>
    </annotation>
  </element>

  <element name="HTTPServiceUserView"
           type="c:HTTPServiceType">
    <annotation>
      <documentation>
        Configuration for the User view service.
      </documentation>
    </annotation>
  </element>

  <element name="HTTPServices">
    <annotation>
      <documentation>
        Configuration for HTTP services.
      </documentation>
    </annotation>

    <complexType>
      <sequence>
        <element ref="c:HTTPServiceAdminAPI"/>
        <element ref="c:HTTPServiceUserAPI"/>
        <element ref="c:HTTPServiceUserView"/>
      </sequence>
    </complexType>
  </element>

  <element name="Sessions">
    <complexType>
      <attribute name="UserSessionExpiration"
                 type="duration"
                 use="required">
        <annotation>
          <documentation>
            The maximum age of idle user sessions before they are considered expired and deleted.
          </documentation>
        </annotation>
      </attribute>
      <attribute name="AdminSessionExpiration"
                 type="duration"
                 use="required">
        <annotation>
          <documentation>
            The maximum age of idle admin sessions before they are considered expired and deleted.
          </documentation>
        </annotation>
      </attribute>
    </complexType>
  </element>

  <element name="Database">
    <annotation>
      <documentation>
        Configuration for the database service.
      </documentation>
    </annotation>

    <complexType>
      <attribute name="OwnerRoleName" use="required" type="string">
        <annotation>
          <documentation>
            The name of the role that owns the database. This is used for the initial database setup, and for
            upgrades.
          </documentation>
        </annotation>
      </attribute>

      <attribute name="OwnerRolePassword" use="required" type="string">
        <annotation>
          <documentation>
            The password of the role that owns the database.
          </documentation>
        </annotation>
      </attribute>

      <attribute name="WorkerRolePassword" use="required" type="string">
        <annotation>
          <documentation>
            The password of the role used for normal database operation. This is an unprivileged role that
            does not have the ability to perform DDL or other database-changing operations.
          </documentation>
        </annotation>
      </attribute>

      <attribute name="ReaderRolePassword" use="optional" type="string">
        <annotation>
          <documentation>
            The password of the role used for read-only database operation. If this attribute is not specified,
            the read-only role is not allowed to log in.
          </documentation>
        </annotation>
      </attribute>

      <attribute name="Kind"
                 use="required"
                 type="string">
        <annotation>
          <documentation>
            The kind of the remote database, such as POSTGRESQL.
          </documentation>
        </annotation>
      </attribute>

      <attribute name="Name"
                 use="required"
                 type="string">
        <annotation>
          <documentation>
            The name of the database.
          </documentation>
        </annotation>
      </attribute>

      <attribute name="Address"
                 use="required"
                 type="string">
        <annotation>
          <documentation>
            The address of the database.
          </documentation>
        </annotation>
      </attribute>

      <attribute name="Port"
                 use="required"
                 type="unsignedInt">
        <annotation>
          <documentation>
            The port used to connect to the database.
          </documentation>
        </annotation>
      </attribute>

      <attribute name="Create"
                 use="required"
                 type="boolean">
        <annotation>
          <documentation>
            Should the database be created if it does not already exist?
          </documentation>
        </annotation>
      </attribute>

      <attribute name="Upgrade"
                 use="required"
                 type="boolean">
        <annotation>
          <documentation>
            Should the database schema be upgraded if the schema version is older than the current application?
          </documentation>
        </annotation>
      </attribute>
    </complexType>
  </element>

  <element name="PasswordExpiration">
    <annotation>
      <documentation>
        Configuration information for password expiration.
      </documentation>
    </annotation>

    <complexType>
      <attribute name="UserPasswordValidityDuration"
                 type="duration"
                 use="optional">
        <annotation>
          <documentation>
            The duration for which user passwords are valid. If unspecified, user passwords do not expire.
          </documentation>
        </annotation>
      </attribute>

      <attribute name="AdminPasswordValidityDuration"
                 type="duration"
                 use="optional">
        <annotation>
          <documentation>
            The duration for which admin passwords are valid. If unspecified, user passwords do not expire.
          </documentation>
        </annotation>
      </attribute>
    </complexType>
  </element>

  <element name="RateLimiting">
    <annotation>
      <documentation>
        Configuration information for request rate limiting.
      </documentation>
    </annotation>

    <complexType>
      <attribute name="UserLoginDelay"
                 type="duration"
                 default="PT1S"
                 use="optional">
        <annotation>
          <documentation>
            A fixed delay added to user login operations in order to reduce the feasibility of online password
            brute-forcing.
          </documentation>
        </annotation>
      </attribute>

      <attribute name="UserLoginRateLimit"
                 type="duration"
                 default="PT5S"
                 use="optional">
        <annotation>
          <documentation>
            User login attempts cannot be made more frequently than this duration, for a given IP address.
          </documentation>
        </annotation>
      </attribute>

      <attribute name="AdminLoginDelay"
                 type="duration"
                 default="PT1S"
                 use="optional">
        <annotation>
          <documentation>
            A fixed delay added to admin login operations in order to reduce the feasibility of online password
            brute-forcing.
          </documentation>
        </annotation>
      </attribute>

      <attribute name="AdminLoginRateLimit"
                 type="duration"
                 default="PT5S"
                 use="optional">
        <annotation>
          <documentation>
            Admin login attempts cannot be made more frequently than this duration, for a given IP address.
          </documentation>
        </annotation>
      </attribute>

      <attribute name="EmailVerificationRateLimit"
                 type="duration"
                 use="required">
        <annotation>
          <documentation>
            Email verifications for various operations cannot be prompted more frequently than this duration,
            for a given user account.
          </documentation>
        </annotation>
      </attribute>

      <attribute name="PasswordResetRateLimit"
                 type="duration"
                 use="required">
        <annotation>
          <documentation>
            Passwords cannot be reset more frequently than this duration, for a given IP address.
          </documentation>
        </annotation>
      </attribute>
    </complexType>
  </element>

  <simpleType name="OpenTelemetryProtocol">
    <annotation>
      <documentation>
        The protocol used to deliver OpenTelemetry data.
      </documentation>
    </annotation>

    <restriction base="string">
      <enumeration value="GRPC">
        <annotation>
          <documentation>
            The data will be sent using gRPC.
          </documentation>
        </annotation>
      </enumeration>
      <enumeration value="HTTP">
        <annotation>
          <documentation>
            The data will be sent using HTTP(s).
          </documentation>
        </annotation>
      </enumeration>
    </restriction>
  </simpleType>

  <element name="Metrics">
    <annotation>
      <documentation>
        Configuration information for OpenTelemetry metrics.
      </documentation>
    </annotation>

    <complexType>
      <attribute name="Endpoint"
                 use="required"
                 type="anyURI">
        <annotation>
          <documentation>
            The endpoint to which OTLP metrics data will be sent.
          </documentation>
        </annotation>
      </attribute>

      <attribute name="Protocol"
                 use="required"
                 type="c:OpenTelemetryProtocol">
        <annotation>
          <documentation>
            The protocol used to send metrics data.
          </documentation>
        </annotation>
      </attribute>
    </complexType>
  </element>

  <element name="Traces">
    <annotation>
      <documentation>
        Configuration information for OpenTelemetry traces.
      </documentation>
    </annotation>

    <complexType>
      <attribute name="Endpoint"
                 use="required"
                 type="anyURI">
        <annotation>
          <documentation>
            The endpoint to which OTLP trace data will be sent.
          </documentation>
        </annotation>
      </attribute>

      <attribute name="Protocol"
                 use="required"
                 type="c:OpenTelemetryProtocol">
        <annotation>
          <documentation>
            The protocol used to send trace data.
          </documentation>
        </annotation>
      </attribute>
    </complexType>
  </element>

  <element name="Logs">
    <annotation>
      <documentation>
        Configuration information for OpenTelemetry logs/events.
      </documentation>
    </annotation>

    <complexType>
      <attribute name="Endpoint"
                 use="required"
                 type="anyURI">
        <annotation>
          <documentation>
            The endpoint to which OTLP log data will be sent.
          </documentation>
        </annotation>
      </attribute>

      <attribute name="Protocol"
                 use="required"
                 type="c:OpenTelemetryProtocol">
        <annotation>
          <documentation>
            The protocol used to send log data.
          </documentation>
        </annotation>
      </attribute>
    </complexType>
  </element>

  <element name="OpenTelemetry">
    <annotation>
      <documentation>
        Configuration information for OpenTelemetry.
      </documentation>
    </annotation>

    <complexType>
      <sequence>
        <element ref="c:Logs"
                 minOccurs="0"
                 maxOccurs="1"/>
        <element ref="c:Metrics"
                 minOccurs="0"
                 maxOccurs="1"/>
        <element ref="c:Traces"
                 minOccurs="0"
                 maxOccurs="1"/>
      </sequence>

      <attribute name="LogicalServiceName"
                 use="required"
                 type="string">
        <annotation>
          <documentation>
            The logical name of the service as it will appear in OpenTelemetry.
          </documentation>
        </annotation>
      </attribute>
    </complexType>
  </element>

  <element name="Configuration">
    <annotation>
      <documentation>
        The main server configuration element.
      </documentation>
    </annotation>

    <complexType>
      <sequence>
        <element ref="c:Branding"/>
        <element ref="c:Database"/>
        <element ref="c:HTTPServices"/>
        <element ref="c:History"/>
        <element ref="c:Mail"/>
        <element ref="c:OpenTelemetry"
                 minOccurs="0"
                 maxOccurs="1"/>
        <element ref="c:PasswordExpiration"
                 minOccurs="0"
                 maxOccurs="1"/>
        <element ref="c:RateLimiting"/>
        <element ref="c:Sessions"/>
      </sequence>
    </complexType>
  </element>

</schema>

idstore: usage: idstore [command] [arguments ...]

  The idstore server and command-line application.

  Use the "help" command to examine specific commands:

    $ idstore help help.

  Command-line arguments can be placed one per line into a file, and
  the file can be referenced using the @ symbol:

    $ echo help > file.txt
    $ echo help >> file.txt
    $ idstore @file.txt

  Commands:
    help          Show usage information for a command.
    initialize    Initialize the server and database.
    server        Start the server.
    shell         Run the admin command shell.
    version       Show the application version.

  Documentation:
    https://www.io7m.com/software/idstore/

$ idstore server --configuration server.conf

$ (cat <<EOF
--configuration
server.conf
EOF
) > args.txt

$ idstore @args.txt

[idstore]# admin-ban-create
> --admin 3a193a61-9427-4c24-8bd4-667d19914970
> --expires-on 2100-01-01T00:00:00+00:00
> --reason "You did something objectionable"

[idstore]# mail-test --email user@example.com
Mail sent successfully.
Token: 220384

[idstore]# maintenance-mode --set 'We are performing maintenance. Normal service will resume shortly.'
Server is in maintenance mode with message "We are performing maintenance. Normal service will resume shortly."

[idstore]# maintenance-mode --unset Ignored
Server is now actively serving requests.

[idstore]# user-ban-create
> --user 3a193a61-9427-4c24-8bd4-667d19914970
> --expires-on 2100-01-01T00:00:00+00:00
> --reason "You did something objectionable"

$ curl https://idstore.example.com:51000/ | hexdump
0000:0000 | 00 00 00 01  00 00 00 01  DE 1E F9 F2  5E A7 38 8A | ........Þ.ùò^§8.
0000:0010 | 9B 79 78 8C  13 2A BF D1  00 00 00 01  00 00 00 00 | .yx..*¿Ñ........
0000:0020 | 00 00 00 0B  2F 61 64 6D  69 6E 2F 31  2F 30 2F    | ..../admin/1/0/

• com.io7m.cedarbridge
• com.io7m.idstore.protocol.admin.cb

;
; Copyright © 2023 Mark Raynsford <code@io7m.com> https://www.io7m.com
;
; Permission to use, copy, modify, and/or distribute this software for any
; purpose with or without fee is hereby granted, provided that the above
; copyright notice and this permission notice appear in all copies.
;
; THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
; WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
; MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
; SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
; WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
; ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
; IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
;

[language cedarbridge 1 0]

[package com.io7m.idstore.protocol.admin.cb]

[import com.io7m.cedarbridge cb]
[import com.io7m.cedarbridge.time ct]

[documentation IdA1Password "Information for a hashed password."]
[record IdA1Password
  [documentation algorithm "The password algorithm."]
  [field algorithm cb:String]
  [documentation hash "The password hash."]
  [field hash cb:String]
  [documentation salt "The password salt."]
  [field salt cb:String]
  [documentation expires "The password expiration date."]
  [field expires [cb:Option ct:OffsetDateTime]]
]

[documentation IdA1TimestampUTC "A UTC timestamp value."]
[record IdA1TimestampUTC
  [documentation year "The year."]
  [field year cb:IntegerUnsigned32]
  [documentation month "The month in the range [1, 12]."]
  [field month cb:IntegerUnsigned8]
  [documentation day "The day of the month in the range [1, 31]."]
  [field day cb:IntegerUnsigned8]
  [documentation hour "The hour in the range [0, 23]."]
  [field hour cb:IntegerUnsigned8]
  [documentation minute "The minute in the range [0, 59]."]
  [field minute cb:IntegerUnsigned8]
  [documentation second "The second in the range [0, 59]."]
  [field second cb:IntegerUnsigned8]
  [documentation millisecond "The millisecond in the range [0, 999]."]
  [field millisecond cb:IntegerUnsigned32]
]

[documentation IdA1Ban "An account ban."]
[record IdA1Ban
  [documentation user "The user (or admin) ID."]
  [field user cb:UUID]
  [documentation reason "The ban reason."]
  [field reason cb:String]
  [documentation expires "The expiration date, if any."]
  [field expires [cb:Option IdA1TimestampUTC]]
]

[documentation IdA1TimeRange "A UTC time range."]
[record IdA1TimeRange
  [documentation lower "The lower bound."]
  [field lower IdA1TimestampUTC]
  [documentation upper "The upper bound."]
  [field upper IdA1TimestampUTC]
]

[documentation IdA1Login "A login record."]
[record IdA1Login
  [documentation user "The user ID."]
  [field user cb:UUID]
  [documentation time "The login time."]
  [field time IdA1TimestampUTC]
  [documentation host "The user's host."]
  [field host cb:String]
  [documentation agent "The user's agent."]
  [field agent cb:String]
]

[documentation IdA1AdminPermission "An admin permission."]
[variant IdA1AdminPermission
  [documentation AdminBan "A permission that allows for banning admins."]
  [case AdminBan]
  [documentation AdminCreate "A permission that allows for creating admins."]
  [case AdminCreate]
  [documentation AdminDelete "A permission that allows for deleting admins."]
  [case AdminDelete]
  [documentation AdminWriteCredentials "A permission that allows updating admin credentials."]
  [case AdminWriteCredentials]
  [documentation AdminWriteCredentialsSelf "A permission that allows an admin to update its own credentials."]
  [case AdminWriteCredentialsSelf]
  [documentation AdminWriteEmail "A permission that allows updating admin emails."]
  [case AdminWriteEmail]
  [documentation AdminWriteEmailSelf "A permission that allows an admin to update its own emails."]
  [case AdminWriteEmailSelf]
  [documentation AdminWritePermissions "A permission that allows updating admin permissions."]
  [case AdminWritePermissions]
  [documentation AdminWritePermissionsSelf "A permission that allows an admin to update its own permissions."]
  [case AdminWritePermissionsSelf]
  [documentation AdminRead "A permission that allows reading admins."]
  [case AdminRead]
  [documentation AuditRead "A permission that allows reading the audit log."]
  [case AuditRead]
  [documentation UserDelete "A permission that allows deleting users."]
  [case UserDelete]
  [documentation UserCreate "A permission that allows creating users."]
  [case UserCreate]
  [documentation UserWriteCredentials "A permission that allows updating user credentials."]
  [case UserWriteCredentials]
  [documentation UserWriteEmail "A permission that allows updating user emails."]
  [case UserWriteEmail]
  [documentation UserRead "A permission that allows reading users."]
  [case UserRead]
  [documentation UserBan "A permission that allows for banning users."]
  [case UserBan]
  [documentation MailTest "A permission that allows for sending test mail."]
  [case MailTest]
  [documentation MaintenanceMode "A permission that allows for changing the server's maintenance mode."]
  [case MaintenanceMode]
]

[documentation IdA1AdminColumn "A column to use for sorting admins."]
[variant IdA1AdminColumn
  [documentation ByID "Order by admin ID."]
  [case ByID]
  [documentation ByIDName "Order by admin id name."]
  [case ByIDName]
  [documentation ByRealName "Order by admin realname."]
  [case ByRealName]
  [documentation ByTimeCreated "Order by admin creation time."]
  [case ByTimeCreated]
  [documentation ByTimeUpdated "Order by admin update time."]
  [case ByTimeUpdated]
]

[documentation IdA1AdminColumnOrdering "A column ordering spec."]
[record IdA1AdminColumnOrdering
  [documentation column "The admin column."]
  [field column IdA1AdminColumn]
  [documentation ascending "True if the results should be ascending."]
  [field ascending cb:Boolean]
]

[documentation IdA1AdminSearchParameters "Search parameters for admins."]
[record IdA1AdminSearchParameters
  [documentation timeCreatedRange "The range of creation times for returned admins."]
  [field timeCreatedRange IdA1TimeRange]
  [documentation timeUpdatedRange "The range of update times for returned admins."]
  [field timeUpdatedRange IdA1TimeRange]
  [documentation search "The search query text."]
  [field search [cb:Option cb:String]]
  [documentation ordering "The result ordering."]
  [field ordering IdA1AdminColumnOrdering]
  [documentation limit "The limit on the number of results."]
  [field limit cb:IntegerUnsigned16]
]

[documentation IdA1AdminSearchByEmailParameters "Search parameters for admins (by email)."]
[record IdA1AdminSearchByEmailParameters
  [documentation timeCreatedRange "The range of creation times for returned admins."]
  [field timeCreatedRange IdA1TimeRange]
  [documentation timeUpdatedRange "The range of update times for returned admins."]
  [field timeUpdatedRange IdA1TimeRange]
  [documentation search "The search query text."]
  [field search cb:String]
  [documentation ordering "The result ordering."]
  [field ordering IdA1AdminColumnOrdering]
  [documentation limit "The limit on the number of results."]
  [field limit cb:IntegerUnsigned16]
]

[documentation IdA1AuditSearchParameters "Search parameters for audit records."]
[record IdA1AuditSearchParameters
  [documentation timeRange "The range of time to include."]
  [field timeRange IdA1TimeRange]
  [documentation owner "All records contain this owner, if specified."]
  [field owner [cb:Option cb:String]]
  [documentation message "All records contain this message, if specified."]
  [field message [cb:Option cb:String]]
  [documentation type "All records contain this type, if specified."]
  [field type [cb:Option cb:String]]
  [documentation limit "The limit on the number of results."]
  [field limit cb:IntegerUnsigned16]
]

[documentation IdA1UserColumn "A column to use for sorting users."]
[variant IdA1UserColumn
  [documentation ByID "Order by user ID."]
  [case ByID]
  [documentation ByIDName "Order by user id name."]
  [case ByIDName]
  [documentation ByRealName "Order by user realname."]
  [case ByRealName]
  [documentation ByTimeCreated "Order by user creation time."]
  [case ByTimeCreated]
  [documentation ByTimeUpdated "Order by user update time."]
  [case ByTimeUpdated]
]

[documentation IdA1UserColumnOrdering "A column ordering spec."]
[record IdA1UserColumnOrdering
  [documentation column "The user column."]
  [field column IdA1UserColumn]
  [documentation ascending "True if the results should be ascending."]
  [field ascending cb:Boolean]
]

[documentation IdA1UserSearchParameters "Search parameters for users."]
[record IdA1UserSearchParameters
  [documentation timeCreatedRange "The range of creation times for returned users."]
  [field timeCreatedRange IdA1TimeRange]
  [documentation timeUpdatedRange "The range of update times for returned users."]
  [field timeUpdatedRange IdA1TimeRange]
  [documentation search "The search query text."]
  [field search [cb:Option cb:String]]
  [documentation ordering "The result ordering."]
  [field ordering IdA1UserColumnOrdering]
  [documentation limit "The limit on the number of results."]
  [field limit cb:IntegerUnsigned16]
]

[documentation IdA1UserSearchByEmailParameters "Search parameters for users (by email)."]
[record IdA1UserSearchByEmailParameters
  [documentation timeCreatedRange "The range of creation times for returned users."]
  [field timeCreatedRange IdA1TimeRange]
  [documentation timeUpdatedRange "The range of update times for returned users."]
  [field timeUpdatedRange IdA1TimeRange]
  [documentation search "The search query text."]
  [field search cb:String]
  [documentation ordering "The result ordering."]
  [field ordering IdA1UserColumnOrdering]
  [documentation limit "The limit on the number of results."]
  [field limit cb:IntegerUnsigned16]
]

[documentation IdA1Admin "An administrator."]
[record IdA1Admin
  [documentation id "The admin ID."]
  [field id cb:UUID]
  [documentation idName "The admin ID name."]
  [field idName cb:String]
  [documentation realName "The admin real name."]
  [field realName cb:String]
  [documentation emails "The admin emails."]
  [field emails [cb:List cb:String]]
  [documentation timeCreated "The time the admin was created."]
  [field timeCreated IdA1TimestampUTC]
  [documentation timeUpdated "The time the admin was last updated."]
  [field timeUpdated IdA1TimestampUTC]
  [documentation password "The hashed admin password."]
  [field password IdA1Password]
  [documentation permissions "The admin permissions."]
  [field permissions [cb:List IdA1AdminPermission]]
]

[documentation IdA1Page "A page of results."]
[record IdA1Page
  [documentation T "The type of result values."]
  [parameter T]
  [documentation items "The list of results."]
  [field items [cb:List T]]
  [documentation pageIndex "The page index."]
  [field pageIndex cb:IntegerUnsigned32]
  [documentation pageCount "The page count."]
  [field pageCount cb:IntegerUnsigned32]
  [documentation pageFirstOffset "The offset of the first item in the page."]
  [field pageFirstOffset cb:IntegerUnsigned64]]

[documentation IdA1AdminSummary "An admin summary."]
[record IdA1AdminSummary
  [documentation id "The admin ID."]
  [field id cb:UUID]
  [documentation idName "The admin ID name."]
  [field idName cb:String]
  [documentation realName "The admin real name."]
  [field realName cb:String]
  [documentation timeCreated "The time the admin was created."]
  [field timeCreated IdA1TimestampUTC]
  [documentation timeUpdated "The time the admin was last updated."]
  [field timeUpdated IdA1TimestampUTC]
]

[documentation IdA1AuditEvent "An audit event."]
[record IdA1AuditEvent
  [documentation id "The audit event ID."]
  [field id cb:IntegerUnsigned64]
  [documentation owner "The audit event owner."]
  [field owner cb:UUID]
  [documentation time "The audit event time."]
  [field time IdA1TimestampUTC]
  [documentation type "The audit event type."]
  [field type cb:String]
  [documentation message "The audit event message."]
  [field message cb:String]
]

[documentation IdA1User "A user."]
[record IdA1User
  [documentation id "The user ID."]
  [field id cb:UUID]
  [documentation idName "The user ID name."]
  [field idName cb:String]
  [documentation realName "The user real name."]
  [field realName cb:String]
  [documentation emails "The user emails."]
  [field emails [cb:List cb:String]]
  [documentation timeCreated "The time the user was created."]
  [field timeCreated IdA1TimestampUTC]
  [documentation timeUpdated "The time the user was last updated."]
  [field timeUpdated IdA1TimestampUTC]
  [documentation password "The hashed user password."]
  [field password IdA1Password]
]

[documentation IdA1UserSummary "A user summary."]
[record IdA1UserSummary
  [documentation id "The user ID."]
  [field id cb:UUID]
  [documentation idName "The user ID name."]
  [field idName cb:String]
  [documentation realName "The user real name."]
  [field realName cb:String]
  [documentation timeCreated "The time the user was created."]
  [field timeCreated IdA1TimestampUTC]
  [documentation timeUpdated "The time the user was last updated."]
  [field timeUpdated IdA1TimestampUTC]
]

[documentation IdA1PasswordExpirationSet "The possible behaviours for setting password expirations."]
[variant IdA1PasswordExpirationSet
  [documentation Never "Never expire, regardless of the server setting."]
  [case Never]
  [documentation Refresh "Refresh the password to the server setting."]
  [case Refresh]
  [documentation Specific "Expire at the given time, regardless of the server setting."]
  [case Specific [field time ct:OffsetDateTime]]
]

;
; Admin commands.
;

[documentation IdA1CommandAdminBanCreate "Ban an admin."]
[record IdA1CommandAdminBanCreate
  [documentation ban "The ban."]
  [field ban IdA1Ban]
]

[documentation IdA1CommandAdminBanDelete "Remove a ban on an admin."]
[record IdA1CommandAdminBanDelete
  [documentation adminId "The admin."]
  [field adminId cb:UUID]
]

[documentation IdA1CommandAdminBanGet "Get a ban on an admin."]
[record IdA1CommandAdminBanGet
  [documentation adminId "The admin."]
  [field adminId cb:UUID]
]

[documentation IdA1CommandAdminCreate "Create an admin."]
[record IdA1CommandAdminCreate
  [documentation adminId "The admin."]
  [field adminId [cb:Option cb:UUID]]
  [documentation idName "The admin ID name."]
  [field idName cb:String]
  [documentation realName "The admin real name."]
  [field realName cb:String]
  [documentation email "The admin email."]
  [field email cb:String]
  [documentation password "The admin password."]
  [field password IdA1Password]
  [documentation permissions "The set of permissions."]
  [field permissions [cb:List IdA1AdminPermission]]
]

[documentation IdA1CommandAdminDelete "Delete an admin."]
[record IdA1CommandAdminDelete
  [documentation adminId "The admin."]
  [field adminId cb:UUID]
]

[documentation IdA1CommandAdminEmailAdd "Add an email address to the given admin."]
[record IdA1CommandAdminEmailAdd
  [documentation adminId "The admin."]
  [field adminId cb:UUID]
  [documentation email "The email address."]
  [field email cb:String]
]

[documentation IdA1CommandAdminEmailRemove "Remove an email address from the given admin."]
[record IdA1CommandAdminEmailRemove
  [documentation adminId "The admin."]
  [field adminId cb:UUID]
  [documentation email "The email address."]
  [field email cb:String]
]

[documentation IdA1CommandAdminGet "Get the given admin."]
[record IdA1CommandAdminGet
  [documentation adminId "The admin."]
  [field adminId cb:UUID]
]

[documentation IdA1CommandAdminGetByEmail "Get the admin with the given email address."]
[record IdA1CommandAdminGetByEmail
  [documentation email "The email address."]
  [field email cb:String]
]

[documentation IdA1CommandAdminPermissionGrant "Grant a permission to the given admin."]
[record IdA1CommandAdminPermissionGrant
  [documentation adminId "The admin."]
  [field adminId cb:UUID]
  [documentation permission "The permission."]
  [field permission IdA1AdminPermission]
]

[documentation IdA1CommandAdminPermissionRevoke "Revoke a permission from the given admin."]
[record IdA1CommandAdminPermissionRevoke
  [documentation adminId "The admin."]
  [field adminId cb:UUID]
  [documentation permission "The permission."]
  [field permission IdA1AdminPermission]
]

[documentation IdA1CommandAdminSearchBegin "Start searching for admins."]
[record IdA1CommandAdminSearchBegin
  [documentation parameters "The search parameters."]
  [field parameters IdA1AdminSearchParameters]
]

[documentation IdA1CommandAdminSearchByEmailBegin "Start searching for admins (by email)."]
[record IdA1CommandAdminSearchByEmailBegin
  [documentation parameters "The search parameters."]
  [field parameters IdA1AdminSearchByEmailParameters]
]

[documentation IdA1CommandAdminSearchByEmailNext "Get the next page of admin search results."]
[record IdA1CommandAdminSearchByEmailNext]

[documentation IdA1CommandAdminSearchByEmailPrevious "Get the previous page of admin search results."]
[record IdA1CommandAdminSearchByEmailPrevious]

[documentation IdA1CommandAdminSearchNext "Get the next page of admin search results."]
[record IdA1CommandAdminSearchNext]

[documentation IdA1CommandAdminSearchPrevious "Get the previous page of admin search results."]
[record IdA1CommandAdminSearchPrevious]

[documentation IdA1CommandAdminSelf "A request to fetch the admin's own profile."]
[record IdA1CommandAdminSelf]

[documentation IdA1CommandAdminUpdateCredentials "A request to edit an admin's credentials."]
[record IdA1CommandAdminUpdateCredentials
  [documentation adminId "The admin."]
  [field adminId cb:UUID]
  [documentation idName "The admin's new ID name."]
  [field idName [cb:Option cb:String]]
  [documentation realName "The admin's new real name."]
  [field realName [cb:Option cb:String]]
  [documentation password "The admin's new password"]
  [field password [cb:Option IdA1Password]]
]

[documentation IdA1CommandAdminUpdatePasswordExpiration "A request to update the admin's password expiration."]
[record IdA1CommandAdminUpdatePasswordExpiration
  [documentation userId "The admin."]
  [field userId cb:UUID]
  [documentation set "The set behaviour."]
  [field set IdA1PasswordExpirationSet]
]

[documentation IdA1CommandAuditSearchBegin "Start searching/listing audit records."]
[record IdA1CommandAuditSearchBegin
  [documentation parameters "The search parameters."]
  [field parameters IdA1AuditSearchParameters]
]

[documentation IdA1CommandAuditSearchNext "Get the next page of audit search results."]
[record IdA1CommandAuditSearchNext]

[documentation IdA1CommandAuditSearchPrevious "Get the previous page of audit search results."]
[record IdA1CommandAuditSearchPrevious]

[documentation IdA1CommandMailTest "Send a test email to a given address."]
[record IdA1CommandMailTest
  [documentation address "The target email address."]
  [field address cb:String]
  [documentation token "The email token."]
  [field token cb:String]
]

[documentation IdA1CommandMaintenanceModeSet "Move the server to/from maintenance mode."]
[record IdA1CommandMaintenanceModeSet
  [documentation message "The message (if maintenance mode is to be turned on)."]
  [field message [cb:Option cb:String]]
]

[documentation IdA1CommandLogin "A request to log in."]
[record IdA1CommandLogin
  [documentation userName "The username."]
  [field userName cb:String]
  [documentation password "The password."]
  [field password cb:String]
  [documentation metadata "The extra metadata"]
  [field metadata [cb:Map cb:String cb:String]]
]

;
; User commands.
;

[documentation IdA1CommandUserBanCreate "Ban a user."]
[record IdA1CommandUserBanCreate
  [documentation ban "The ban."]
  [field ban IdA1Ban]
]

[documentation IdA1CommandUserBanDelete "Remove a ban on a user."]
[record IdA1CommandUserBanDelete
  [documentation userId "The user."]
  [field userId cb:UUID]
]

[documentation IdA1CommandUserBanGet "Get a ban on a user."]
[record IdA1CommandUserBanGet
  [documentation userId "The user."]
  [field userId cb:UUID]
]

[documentation IdA1CommandUserCreate "Create a user."]
[record IdA1CommandUserCreate
  [documentation userId "The user."]
  [field userId [cb:Option cb:UUID]]
  [documentation idName "The user ID name."]
  [field idName cb:String]
  [documentation realName "The user real name."]
  [field realName cb:String]
  [documentation email "The user email."]
  [field email cb:String]
  [documentation password "The user password."]
  [field password IdA1Password]
]

[documentation IdA1CommandUserDelete "Delete a user."]
[record IdA1CommandUserDelete
  [documentation userId "The user."]
  [field userId cb:UUID]
]

[documentation IdA1CommandUserEmailAdd "Add an email address to the given user."]
[record IdA1CommandUserEmailAdd
  [documentation userId "The user."]
  [field userId cb:UUID]
  [documentation email "The email address."]
  [field email cb:String]
]

[documentation IdA1CommandUserEmailRemove "Remove an email address from the given user."]
[record IdA1CommandUserEmailRemove
  [documentation userId "The user."]
  [field userId cb:UUID]
  [documentation email "The email address."]
  [field email cb:String]
]

[documentation IdA1CommandUserGet "Get the given user."]
[record IdA1CommandUserGet
  [documentation userId "The user."]
  [field userId cb:UUID]
]

[documentation IdA1CommandUserGetByEmail "Get the user with the given email address."]
[record IdA1CommandUserGetByEmail
  [documentation email "The email address."]
  [field email cb:String]
]

[documentation IdA1CommandUserLoginHistory "Get the given user's login history."]
[record IdA1CommandUserLoginHistory
  [documentation userId "The user."]
  [field userId cb:UUID]
]

[documentation IdA1CommandUserSearchBegin "Start searching for users."]
[record IdA1CommandUserSearchBegin
  [documentation parameters "The search parameters."]
  [field parameters IdA1UserSearchParameters]
]

[documentation IdA1CommandUserSearchByEmailBegin "Start searching for users (by email)."]
[record IdA1CommandUserSearchByEmailBegin
  [documentation parameters "The search parameters."]
  [field parameters IdA1UserSearchByEmailParameters]
]

[documentation IdA1CommandUserSearchByEmailNext "Get the next page of user search results."]
[record IdA1CommandUserSearchByEmailNext]

[documentation IdA1CommandUserSearchByEmailPrevious "Get the previous page of user search results."]
[record IdA1CommandUserSearchByEmailPrevious]

[documentation IdA1CommandUserSearchNext "Get the next page of user search results."]
[record IdA1CommandUserSearchNext]

[documentation IdA1CommandUserSearchPrevious "Get the previous page of user search results."]
[record IdA1CommandUserSearchPrevious]

[documentation IdA1CommandUserUpdateCredentials "A request to fetch the user's own profile."]
[record IdA1CommandUserUpdateCredentials
  [documentation userId "The user."]
  [field userId cb:UUID]
  [documentation idName "The user's new ID name."]
  [field idName [cb:Option cb:String]]
  [documentation realName "The user's new real name."]
  [field realName [cb:Option cb:String]]
  [documentation password "The user's new password"]
  [field password [cb:Option IdA1Password]]
]

[documentation IdA1CommandUserUpdatePasswordExpiration "A request to update the user's password expiration."]
[record IdA1CommandUserUpdatePasswordExpiration
  [documentation userId "The user."]
  [field userId cb:UUID]
  [documentation set "The set behaviour."]
  [field set IdA1PasswordExpirationSet]
]

;
; Admin responses.
;

[documentation IdA1ResponseBlame "A blame assignment."]
[variant IdA1ResponseBlame
  [documentation BlameClient "The client sent a bad response."]
  [case BlameClient]
  [documentation BlameServer "Something went wrong on the server."]
  [case BlameServer]
]

[documentation IdA1ResponseAdminBanCreate "A response to IdA1CommandAdminBanCreate."]
[record IdA1ResponseAdminBanCreate
  [documentation requestId "The ID of the request that yielded this response."]
  [field requestId cb:UUID]
  [documentation ban "The ban."]
  [field ban IdA1Ban]
]

[documentation IdA1ResponseAdminBanDelete "A response to IdA1CommandAdminBanDelete."]
[record IdA1ResponseAdminBanDelete
  [documentation requestId "The ID of the request that yielded this response."]
  [field requestId cb:UUID]
]

[documentation IdA1ResponseAdminBanGet "A response to IdA1CommandAdminBanGet."]
[record IdA1ResponseAdminBanGet
  [documentation requestId "The ID of the request that yielded this response."]
  [field requestId cb:UUID]
  [documentation ban "The ban."]
  [field ban [cb:Option IdA1Ban]]
]

[documentation IdA1ResponseAdminCreate "A response to IdA1CommandAdminCreate."]
[record IdA1ResponseAdminCreate
  [documentation requestId "The ID of the request that yielded this response."]
  [field requestId cb:UUID]
  [documentation admin "The admin."]
  [field admin IdA1Admin]
]

[documentation IdA1ResponseAdminDelete "A response to IdA1CommandAdminDelete."]
[record IdA1ResponseAdminDelete
  [documentation requestId "The ID of the request that yielded this response."]
  [field requestId cb:UUID]
]

[documentation IdA1ResponseAdminGet "A response to IdA1CommandAdminGet."]
[record IdA1ResponseAdminGet
  [documentation requestId "The ID of the request that yielded this response."]
  [field requestId cb:UUID]
  [documentation admin "The admin."]
  [field admin [cb:Option IdA1Admin]]
]

[documentation IdA1ResponseAdminSearchBegin "A response to IdA1CommandAdminSearchBegin."]
[record IdA1ResponseAdminSearchBegin
  [documentation requestId "The ID of the request that yielded this response."]
  [field requestId cb:UUID]
  [documentation page "The first page of results."]
  [field page [IdA1Page IdA1AdminSummary]]
]

[documentation IdA1ResponseAdminSearchNext "A response to IdA1CommandAdminSearchNext."]
[record IdA1ResponseAdminSearchNext
  [documentation requestId "The ID of the request that yielded this response."]
  [field requestId cb:UUID]
  [documentation page "The next page of results."]
  [field page [IdA1Page IdA1AdminSummary]]
]

[documentation IdA1ResponseAdminSearchPrevious "A response to IdA1CommandAdminSearchPrevious."]
[record IdA1ResponseAdminSearchPrevious
  [documentation requestId "The ID of the request that yielded this response."]
  [field requestId cb:UUID]
  [documentation page "The previous page of results."]
  [field page [IdA1Page IdA1AdminSummary]]
]

[documentation IdA1ResponseAdminSearchByEmailBegin "A response to IdA1CommandAdminSearchByEmailBegin."]
[record IdA1ResponseAdminSearchByEmailBegin
  [documentation requestId "The ID of the request that yielded this response."]
  [field requestId cb:UUID]
  [documentation page "The first page of results."]
  [field page [IdA1Page IdA1AdminSummary]]
]

[documentation IdA1ResponseAdminSearchByEmailNext "A response to IdA1CommandAdminSearchByEmailNext."]
[record IdA1ResponseAdminSearchByEmailNext
  [documentation requestId "The ID of the request that yielded this response."]
  [field requestId cb:UUID]
  [documentation page "The next page of results."]
  [field page [IdA1Page IdA1AdminSummary]]
]

[documentation IdA1ResponseAdminSearchByEmailPrevious "A response to IdA1CommandAdminSearchByEmailPrevious."]
[record IdA1ResponseAdminSearchByEmailPrevious
  [documentation requestId "The ID of the request that yielded this response."]
  [field requestId cb:UUID]
  [documentation page "The previous page of results."]
  [field page [IdA1Page IdA1AdminSummary]]
]

[documentation IdA1ResponseAdminSelf "A response to IdA1CommandAdminSelf."]
[record IdA1ResponseAdminSelf
  [documentation requestId "The ID of the request that yielded this response."]
  [field requestId cb:UUID]
  [documentation admin "The admin."]
  [field admin IdA1Admin]
]

[documentation IdA1ResponseAdminUpdate "A response to IdA1CommandAdminUpdateCredentials."]
[record IdA1ResponseAdminUpdate
  [documentation requestId "The ID of the request that yielded this response."]
  [field requestId cb:UUID]
  [documentation admin "The admin."]
  [field admin IdA1Admin]
]

[documentation IdA1ResponseAuditSearchBegin "A response to IdA1CommandAuditSearchBegin."]
[record IdA1ResponseAuditSearchBegin
  [documentation requestId "The ID of the request that yielded this response."]
  [field requestId cb:UUID]
  [documentation page "The first page of results."]
  [field page [IdA1Page IdA1AuditEvent]]
]

[documentation IdA1ResponseAuditSearchNext "A response to IdA1CommandAuditSearchNext."]
[record IdA1ResponseAuditSearchNext
  [documentation requestId "The ID of the request that yielded this response."]
  [field requestId cb:UUID]
  [documentation page "The next page of results."]
  [field page [IdA1Page IdA1AuditEvent]]
]

[documentation IdA1ResponseAuditSearchPrevious "A response to IdA1CommandAuditSearchPrevious."]
[record IdA1ResponseAuditSearchPrevious
  [documentation requestId "The ID of the request that yielded this response."]
  [field requestId cb:UUID]
  [documentation page "The previous page of results."]
  [field page [IdA1Page IdA1AuditEvent]]
]

[documentation IdA1ResponseMaintenanceModeSet "A response to IdA1CommandMaintenanceModeSet."]
[record IdA1ResponseMaintenanceModeSet
  [documentation requestId "The ID of the request that yielded this response."]
  [field requestId cb:UUID]
  [documentation message "The response message."]
  [field message cb:String]
]

[documentation IdA1ResponseMailTest "A response to IdA1CommandMailTest."]
[record IdA1ResponseMailTest
  [documentation requestId "The ID of the request that yielded this response."]
  [field requestId cb:UUID]
  [documentation token "The unique token that was placed into the test email."]
  [field token cb:String]
]

;
; User responses.
;

[documentation IdA1ResponseUserBanCreate "A response to IdA1CommandUserBanCreate."]
[record IdA1ResponseUserBanCreate
  [documentation requestId "The ID of the request that yielded this response."]
  [field requestId cb:UUID]
  [documentation ban "The ban."]
  [field ban IdA1Ban]
]

[documentation IdA1ResponseUserBanDelete "A response to IdA1CommandUserBanDelete."]
[record IdA1ResponseUserBanDelete
  [documentation requestId "The ID of the request that yielded this response."]
  [field requestId cb:UUID]
]

[documentation IdA1ResponseUserBanGet "A response to IdA1CommandUserBanGet."]
[record IdA1ResponseUserBanGet
  [documentation requestId "The ID of the request that yielded this response."]
  [field requestId cb:UUID]
  [documentation ban "The ban."]
  [field ban [cb:Option IdA1Ban]]
]

[documentation IdA1ResponseUserCreate "A response to IdA1CommandUserCreate."]
[record IdA1ResponseUserCreate
  [documentation requestId "The ID of the request that yielded this response."]
  [field requestId cb:UUID]
  [documentation user "The user."]
  [field user IdA1User]
]

[documentation IdA1ResponseUserDelete "A response to IdA1CommandUserDelete."]
[record IdA1ResponseUserDelete
  [documentation requestId "The ID of the request that yielded this response."]
  [field requestId cb:UUID]
]

[documentation IdA1ResponseUserGet "A response to IdA1CommandUserGet."]
[record IdA1ResponseUserGet
  [documentation requestId "The ID of the request that yielded this response."]
  [field requestId cb:UUID]
  [documentation user "The user."]
  [field user [cb:Option IdA1User]]
]

[documentation IdA1ResponseUserSearchBegin "A response to IdA1CommandUserSearchBegin."]
[record IdA1ResponseUserSearchBegin
  [documentation requestId "The ID of the request that yielded this response."]
  [field requestId cb:UUID]
  [documentation page "The first page of results."]
  [field page [IdA1Page IdA1UserSummary]]
]

[documentation IdA1ResponseUserSearchNext "A response to IdA1CommandUserSearchNext."]
[record IdA1ResponseUserSearchNext
  [documentation requestId "The ID of the request that yielded this response."]
  [field requestId cb:UUID]
  [documentation page "The next page of results."]
  [field page [IdA1Page IdA1UserSummary]]
]

[documentation IdA1ResponseUserSearchPrevious "A response to IdA1CommandUserSearchPrevious."]
[record IdA1ResponseUserSearchPrevious
  [documentation requestId "The ID of the request that yielded this response."]
  [field requestId cb:UUID]
  [documentation page "The previous page of results."]
  [field page [IdA1Page IdA1UserSummary]]
]

[documentation IdA1ResponseUserSearchByEmailBegin "A response to IdA1CommandUserSearchByEmailBegin."]
[record IdA1ResponseUserSearchByEmailBegin
  [documentation requestId "The ID of the request that yielded this response."]
  [field requestId cb:UUID]
  [documentation page "The first page of results."]
  [field page [IdA1Page IdA1UserSummary]]
]

[documentation IdA1ResponseUserSearchByEmailNext "A response to IdA1CommandUserSearchByEmailNext."]
[record IdA1ResponseUserSearchByEmailNext
  [documentation requestId "The ID of the request that yielded this response."]
  [field requestId cb:UUID]
  [documentation page "The next page of results."]
  [field page [IdA1Page IdA1UserSummary]]
]

[documentation IdA1ResponseUserSearchByEmailPrevious "A response to IdA1CommandUserSearchByEmailPrevious."]
[record IdA1ResponseUserSearchByEmailPrevious
  [documentation requestId "The ID of the request that yielded this response."]
  [field requestId cb:UUID]
  [documentation page "The previous page of results."]
  [field page [IdA1Page IdA1UserSummary]]
]

[documentation IdA1ResponseUserUpdate "A response to IdA1CommandUserUpdateCredentials."]
[record IdA1ResponseUserUpdate
  [documentation requestId "The ID of the request that yielded this response."]
  [field requestId cb:UUID]
  [documentation user "The user."]
  [field user IdA1User]
]

[documentation IdA1ResponseUserLoginHistory "A response to IdA1CommandUserLoginHistory."]
[record IdA1ResponseUserLoginHistory
  [documentation requestId "The ID of the request that yielded this response."]
  [field requestId cb:UUID]
  [documentation requestId "The user's login history."]
  [field history [cb:List IdA1Login]]
]

;
; General responses.
;

[documentation IdA1ResponseError "An error response."]
[record IdA1ResponseError
  [documentation requestId "The ID of the request that yielded this response."]
  [field requestId cb:UUID]
  [documentation errorCode "The error code."]
  [field errorCode cb:String]
  [documentation message "The error message."]
  [field message cb:String]
  [documentation attributes "The error attributes."]
  [field attributes [cb:Map cb:String cb:String]]
  [documentation remediatingAction "The remediating action, if any."]
  [field remediatingAction [cb:Option cb:String]]
  [documentation blame "The blame assignment."]
  [field blame IdA1ResponseBlame]
]

[documentation IdA1ResponseLogin "A response to IdA1CommandLogin."]
[record IdA1ResponseLogin
  [documentation requestId "The ID of the request that yielded this response."]
  [field requestId cb:UUID]
  [documentation admin "The admin."]
  [field admin IdA1Admin]
]

[documentation IdA "The Admin protocol."]
[protocol IdA
  [version 1
    [types-added
      IdA1CommandAdminBanCreate
      IdA1CommandAdminBanDelete
      IdA1CommandAdminBanGet
      IdA1CommandAdminCreate
      IdA1CommandAdminDelete
      IdA1CommandAdminEmailAdd
      IdA1CommandAdminEmailRemove
      IdA1CommandAdminGet
      IdA1CommandAdminGetByEmail
      IdA1CommandAdminPermissionGrant
      IdA1CommandAdminPermissionRevoke
      IdA1CommandAdminSearchBegin
      IdA1CommandAdminSearchByEmailBegin
      IdA1CommandAdminSearchByEmailNext
      IdA1CommandAdminSearchByEmailPrevious
      IdA1CommandAdminSearchNext
      IdA1CommandAdminSearchPrevious
      IdA1CommandAdminSelf
      IdA1CommandAdminUpdateCredentials
      IdA1CommandAdminUpdatePasswordExpiration
      IdA1CommandAuditSearchBegin
      IdA1CommandAuditSearchNext
      IdA1CommandAuditSearchPrevious
      IdA1CommandLogin
      IdA1CommandMailTest
      IdA1CommandMaintenanceModeSet
      IdA1CommandUserBanCreate
      IdA1CommandUserBanDelete
      IdA1CommandUserBanGet
      IdA1CommandUserCreate
      IdA1CommandUserDelete
      IdA1CommandUserEmailAdd
      IdA1CommandUserEmailRemove
      IdA1CommandUserGet
      IdA1CommandUserGetByEmail
      IdA1CommandUserLoginHistory
      IdA1CommandUserSearchBegin
      IdA1CommandUserSearchByEmailBegin
      IdA1CommandUserSearchByEmailNext
      IdA1CommandUserSearchByEmailPrevious
      IdA1CommandUserSearchNext
      IdA1CommandUserSearchPrevious
      IdA1CommandUserUpdateCredentials
      IdA1CommandUserUpdatePasswordExpiration
      IdA1ResponseAdminBanCreate
      IdA1ResponseAdminBanDelete
      IdA1ResponseAdminBanGet
      IdA1ResponseAdminCreate
      IdA1ResponseAdminDelete
      IdA1ResponseAdminGet
      IdA1ResponseAdminSearchBegin
      IdA1ResponseAdminSearchByEmailBegin
      IdA1ResponseAdminSearchByEmailNext
      IdA1ResponseAdminSearchByEmailPrevious
      IdA1ResponseAdminSearchNext
      IdA1ResponseAdminSearchPrevious
      IdA1ResponseAdminSelf
      IdA1ResponseAdminUpdate
      IdA1ResponseAuditSearchBegin
      IdA1ResponseAuditSearchNext
      IdA1ResponseAuditSearchPrevious
      IdA1ResponseError
      IdA1ResponseLogin
      IdA1ResponseMailTest
      IdA1ResponseMaintenanceModeSet
      IdA1ResponseUserBanCreate
      IdA1ResponseUserBanDelete
      IdA1ResponseUserBanGet
      IdA1ResponseUserCreate
      IdA1ResponseUserDelete
      IdA1ResponseUserGet
      IdA1ResponseUserLoginHistory
      IdA1ResponseUserSearchBegin
      IdA1ResponseUserSearchByEmailBegin
      IdA1ResponseUserSearchByEmailNext
      IdA1ResponseUserSearchByEmailPrevious
      IdA1ResponseUserSearchNext
      IdA1ResponseUserSearchPrevious
      IdA1ResponseUserUpdate
    ]
  ]
]

$ curl https://idstore.example.com:50000/ | hexdump
0000:0000 | 00 00 00 01  00 00 00 01  ED 62 8C 5A  01 82 36 AB | ........íb.Z..6«
0000:0010 | BE E3 5F E6  F6 A2 18 94  00 00 00 01  00 00 00 00 | ¾ã_æö¢..........
0000:0020 | 00 00 00 0A  2F 75 73 65  72 2F 31 2F  30 2F       | ..../user/1/0/

• com.io7m.cedarbridge
• com.io7m.idstore.protocol.user.cb

;
; Copyright © 2023 Mark Raynsford <code@io7m.com> https://www.io7m.com
;
; Permission to use, copy, modify, and/or distribute this software for any
; purpose with or without fee is hereby granted, provided that the above
; copyright notice and this permission notice appear in all copies.
;
; THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
; WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
; MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
; SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
; WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
; ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR
; IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
;

[language cedarbridge 1 0]

[package com.io7m.idstore.protocol.user.cb]

[import com.io7m.cedarbridge cb]
[import com.io7m.cedarbridge.time ct]

[documentation IdU1Password "Information for a hashed password."]
[record IdU1Password
  [documentation algorithm "The password algorithm."]
  [field algorithm cb:String]
  [documentation hash "The password hash."]
  [field hash cb:String]
  [documentation salt "The password salt."]
  [field salt cb:String]
  [documentation expires "The password expiration date."]
  [field expires [cb:Option ct:OffsetDateTime]]
]

[documentation IdU1TimestampUTC "A UTC timestamp value."]
[record IdU1TimestampUTC
  [documentation year "The year."]
  [field year cb:IntegerUnsigned32]
  [documentation month "The month in the range [1, 12]."]
  [field month cb:IntegerUnsigned8]
  [documentation day "The day of the month in the range [1, 31]."]
  [field day cb:IntegerUnsigned8]
  [documentation hour "The hour in the range [0, 23]."]
  [field hour cb:IntegerUnsigned8]
  [documentation minute "The minute in the range [0, 59]."]
  [field minute cb:IntegerUnsigned8]
  [documentation second "The second in the range [0, 59]."]
  [field second cb:IntegerUnsigned8]
  [documentation millisecond "The millisecond in the range [0, 999]."]
  [field millisecond cb:IntegerUnsigned32]
]

[documentation IdU1User "A user."]
[record IdU1User
  [documentation id "The user ID."]
  [field id cb:UUID]
  [documentation idName "The user ID name."]
  [field idName cb:String]
  [documentation realName "The user real name."]
  [field realName cb:String]
  [documentation emails "The user emails."]
  [field emails [cb:List cb:String]]
  [documentation timeCreated "The time the account was created."]
  [field timeCreated IdU1TimestampUTC]
  [documentation timeUpdated "The time the account was updated."]
  [field timeUpdated IdU1TimestampUTC]
  [documentation password "The user password."]
  [field password IdU1Password]
]

;
; Commands.
;

[documentation IdU1CommandLogin "A request to log in."]
[record IdU1CommandLogin
  [documentation userName "The username."]
  [field userName cb:String]
  [documentation password "The password."]
  [field password cb:String]
  [documentation metadata "Extra metadata included with the login request."]
  [field metadata [cb:Map cb:String cb:String]]
]

[documentation IdU1CommandUserSelf "A request to fetch the user's own profile."]
[record IdU1CommandUserSelf]

[documentation IdU1CommandEmailAddBegin "A request to add an email address."]
[record IdU1CommandEmailAddBegin
  [documentation email "The email address."]
  [field email cb:String]
]

[documentation IdU1CommandEmailRemoveBegin "A request to remove an email address."]
[record IdU1CommandEmailRemoveBegin
  [documentation email "The email address."]
  [field email cb:String]
]

[documentation IdU1CommandEmailAddPermit "A request to complete an email address challenge."]
[record IdU1CommandEmailAddPermit
  [documentation token "The challenge token."]
  [field token cb:String]
]

[documentation IdU1CommandEmailRemovePermit "A request to complete an email address challenge."]
[record IdU1CommandEmailRemovePermit
  [documentation token "The challenge token."]
  [field token cb:String]
]

[documentation IdU1CommandEmailAddDeny "A request to complete an email address challenge."]
[record IdU1CommandEmailAddDeny
  [documentation token "The challenge token."]
  [field token cb:String]
]

[documentation IdU1CommandEmailRemoveDeny "A request to complete an email address challenge."]
[record IdU1CommandEmailRemoveDeny
  [documentation token "The challenge token."]
  [field token cb:String]
]

[documentation IdU1CommandRealnameUpdate "A request to update the user's real name."]
[record IdU1CommandRealnameUpdate
  [documentation name "The new name."]
  [field name cb:String]
]

[documentation IdU1CommandPasswordUpdate "A request to update the user's password."]
[record IdU1CommandPasswordUpdate
  [documentation password "The new password."]
  [field password cb:String]
  [documentation passwordConfirm "The password confirmation."]
  [field passwordConfirm cb:String]
]

;
; Responses.
;

[documentation IdU1ResponseBlame "A blame assignment."]
[variant IdU1ResponseBlame
  [documentation BlameClient "The client sent a bad response."]
  [case BlameClient]
  [documentation BlameServer "Something went wrong on the server."]
  [case BlameServer]
]

[documentation IdU1ResponseError "An error response."]
[record IdU1ResponseError
  [documentation requestId "The ID of the request that yielded this response."]
  [field requestId cb:UUID]
  [documentation errorCode "The error code."]
  [field errorCode cb:String]
  [documentation message "The error message."]
  [field message cb:String]
  [documentation attributes "The error attributes."]
  [field attributes [cb:Map cb:String cb:String]]
  [documentation remediatingAction "The remediating action, if any."]
  [field remediatingAction [cb:Option cb:String]]
  [documentation blame "The blame assignment."]
  [field blame IdU1ResponseBlame]
]

[documentation IdU1ResponseLogin "A response to IdU1CommandLogin."]
[record IdU1ResponseLogin
  [documentation requestId "The ID of the request that yielded this response."]
  [field requestId cb:UUID]
  [documentation user "The user."]
  [field user IdU1User]
]

[documentation IdU1ResponseUserSelf "A response to IdU1CommandUserSelf."]
[record IdU1ResponseUserSelf
  [documentation requestId "The ID of the request that yielded this response."]
  [field requestId cb:UUID]
  [documentation user "The user."]
  [field user IdU1User]
]

[documentation IdU1ResponseUserUpdate "A response to various update commands."]
[record IdU1ResponseUserUpdate
  [documentation requestId "The ID of the request that yielded this response."]
  [field requestId cb:UUID]
  [documentation user "The user."]
  [field user IdU1User]
]

[documentation IdU1ResponseEmailAddBegin "A response to IdU1CommandEmailAddBegin."]
[record IdU1ResponseEmailAddBegin
  [documentation requestId "The ID of the request that yielded this response."]
  [field requestId cb:UUID]
]

[documentation IdU1ResponseEmailRemoveBegin "A response to IdU1CommandEmailRemoveBegin."]
[record IdU1ResponseEmailRemoveBegin
  [documentation requestId "The ID of the request that yielded this response."]
  [field requestId cb:UUID]
]

[documentation IdU1ResponseEmailAddPermit "A response to IdU1CommandEmailAddPermit."]
[record IdU1ResponseEmailAddPermit
  [documentation requestId "The ID of the request that yielded this response."]
  [field requestId cb:UUID]
]

[documentation IdU1ResponseEmailRemovePermit "A response to IdU1CommandEmailRemovePermit."]
[record IdU1ResponseEmailRemovePermit
  [documentation requestId "The ID of the request that yielded this response."]
  [field requestId cb:UUID]
]

[documentation IdU1ResponseEmailAddDeny "A response to IdU1CommandEmailAddDeny."]
[record IdU1ResponseEmailAddDeny
  [documentation requestId "The ID of the request that yielded this response."]
  [field requestId cb:UUID]
]

[documentation IdU1ResponseEmailRemoveDeny "A response to IdU1CommandEmailRemoveDeny."]
[record IdU1ResponseEmailRemoveDeny
  [documentation requestId "The ID of the request that yielded this response."]
  [field requestId cb:UUID]
]

;
; Protocol.
;

[documentation IdU "The User protocol."]
[protocol IdU
  [version 1
    [types-added
      IdU1CommandEmailAddBegin
      IdU1CommandEmailAddDeny
      IdU1CommandEmailAddPermit
      IdU1CommandEmailRemoveBegin
      IdU1CommandEmailRemoveDeny
      IdU1CommandEmailRemovePermit
      IdU1CommandLogin
      IdU1CommandPasswordUpdate
      IdU1CommandRealnameUpdate
      IdU1CommandUserSelf
      IdU1ResponseEmailAddBegin
      IdU1ResponseEmailAddDeny
      IdU1ResponseEmailAddPermit
      IdU1ResponseEmailRemoveBegin
      IdU1ResponseEmailRemoveDeny
      IdU1ResponseEmailRemovePermit
      IdU1ResponseError
      IdU1ResponseLogin
      IdU1ResponseUserSelf
      IdU1ResponseUserUpdate
    ]
  ]
]

• Parsing and validation complexity is linear in the size of the parsed message. It is not possible to specify a message that will result in an exponentially complex parse. Additionally, the server currently places hard limits on message sizes from clients; 1048576 octets for commands, and 1024 octets for login requests.
• Cedarbridge protocols are very strongly-typed, operate under a closed-world assumption, and are immune to any kind of reflection-based deserialization vulnerabilities. Deserialization of messages cannot under any circumstances result in the deserialization of arbitrary objects.
• Cedarbridge protocols have a structure that is known ahead of time by both peers. Neither side gets to decide the structure of messages during communication. This is a common source of vulnerabilities in other protocols, where message types are self-describing on the wire and therefore a hostile client is able to transmit the description of a message that will cause the server to do an unbounded amount of work to parse and/or validate the message.
• Parsing code generated by the Cedarbridge compiler does not preallocate any structures. It is not possible, therefore, for a specially-crafted message to result in the server performing a huge allocation based on an attacker-provided size value. If a message claims to provide a string that is 4294967295 octets long, the parser will attempt to consume 4294967295 octets one at a time. This requires an attacker to actually provide 4294967295 octets over the network, and the attacker will run into a hard request size limit before this completes.