Oslonøkkelen - Keychain push

syntax = "proto3";

package com.github.oslokommune.oslonokkelen.keychainpush.proto;

option java_outer_classname = "KeychainPushApi";
option java_multiple_files = false;

// Used by third party system to push permissions to Oslonøkkelen.
//
// POST https://.../api/keychainfactory/{keychain-factory-id}/push/{permission-id}
//
// If the permission is successfully stored it will reply with http 201 and no response body.
// On error the response should contain `PermissionPushErrorResponse`
message PushKeychainRequest {

  // How Oslonøkkelen can find the recipients of the permission.
  //
  // Important
  // ---------
  // Right now Oslonøkkelen only supports a single recipient.
  // Sending requests with 0 or > 1 recipient will return an invalid request.
  repeated Recipient recipients = 1;

  // Determines when Oslonøkkelen is allowed to grant access.
  // Must contain at least one entry.
  repeated Period periods = 2;

  // "Nice to know" information to be presented to the user.
  InformationForUser informationForUser = 3;

  // At least one of these options must be provided. The recipient of the permission must have confirmed
  // this in Oslonøkkelen before any permissions can be pushed from third party systems.
  message Recipient {
    oneof lookupKey {

      // Recipient phone number including country code.
      PhoneNumber phoneNumber = 1;

      // We might add support for looking up users based on email later
      // string emailAddress = 2;

    }
  }

  // Determines when the recipient can use the keychain to open doors.
  // Note that each "keychain factory" is configured with a timezone (Europe/Oslo in 99.999999% of the cases)
  // and `from` and `until` fields are local time for that timezone.
  message Period {

    // ISO-8601 - Example: 2020-12-15T15:00:00
    // Don't include utc offset!
    string from = 1;

    // ISO-8601 - Example: 2020-12-15T15:00:00
    // Don't include utc offset!
    string until = 2;

  }

  // This information does not affect the permission itself, but is presented
  // to use user in the app. Think of this as "nice to have" information.
  message InformationForUser {

    // Mandatory title.
    // Max length: 100
    //
    // Example: "Testveien 2A - 19th of May - #booking-123"
    string title = 1;

    // Useful information related to the permission. Could be a reminder
    // to do (or not do) something after entering a building.
    //
    // Max length: 2000
    string message = 2;

    // Markdown will look a lot nicer in the app.
    // The default type is text.
    TextContentType messageContentType = 3;

    // If this is a booking it might be nice to include a link to a page where the recipient
    // can see and modify the booking.
    string moreInfoLink = 4;

  }


  enum TextContentType {

    PLAIN_TEXT = 0;

    MARKDOWN = 1;

  }

  // Used to look up user profiles.
  message PhoneNumber {

    // Example: 47
    string countryCode = 1;

    string phoneNumber = 2;

  }

  // Empty for now, but we might want to add fields later..
  //
  // Content-Type: application/protobuf;type=push-ok
  message OkResponse {

  }

}
// Content-Type: application/protobuf;type=delete
message KeychainDeleteRequest {

  // Optional reason. Will show up in the app.
  string humanReadableReason = 1;


  // Empty for now, but we might want to add fields later..
  //
  // Content-Type: application/protobuf;type=delete-ok
  message OkResponse {

  }

}

// Content-Type: application/protobuf;type=factories-ls
message ListKeychainFactoriesRequest {

  // Content-Type: application/protobuf;type=factory-list
  message ListResponse {
    repeated FactorySummary summary = 1;
  }

  message FactorySummary {
    string id = 1;
    string title = 2;
  }
}

// Content-Type: application/protobuf;type=error
message ErrorResponse {

  // Says something about what went wrong and what can be done about it.
  ErrorCode errorCode = 1;

  // Optional debug message. This is _not_ intended for the end user, but it can
  // contain useful technical information for debugging problems.
  string technicalDebugMessage = 2;

  enum ErrorCode {

    // Unexpected error.
    UNKNOWN = 0;

    // Unable to find a user profile.
    // Recipient of permissions must verify phone or email address
    // before he or she can receive permissions from third party systems.
    MISSING_PROFILE = 1;

    // Id or key is wrong. Please don't try again without
    // fixing the credentials.
    INVALID_CREDENTIALS = 2;

  }

}

// Third party systems can use this to fetch information about a keychain factories
// owned by that system. This can be a convenient way to validate the configuration.
//
// GET: https://.../api/keychainfactory/{keychain-factory-id}
// Response content-type: application/protobuf;type=keychain-factory-info
message KeychainFactoryPushInfo {

  // Example: Europe/Oslo
  string timezoneId = 1;

}

// EXPERIMENTAL!
// -------------
// The general idea is that Oslonøkkelen can push events to third party systems as
// things happen to keychains created by keychains factories owned by the system.
//
// These events will be signed allowing third party systems to download the public key
// and verify that the event was actually sent by Oslonøkkelen and not someone pretending to be.
//
// Content-type: application/protobuf;type=event
message KeychainEvent {

  // Timestamp indicating when the event happened.
  // ISO-8601 - UTC
  //
  // Example:
  // 2021-04-27T13:07:07.769606557Z
  string timestamp = 1;

  // One of these will be set.
  oneof event {
    KeychainCreated keychainCreated = 5;
    KeychainUpdated keychainUpdated = 6;
    KeychainDeleted keychainDeleted = 7;
  }

  // A new keychain was created by a guard configuration
  // owned by your system. Receiving this event for an unknown
  // permission is a good way to detect api key abuse.
  message KeychainCreated {
    string keychainFactoryId = 1;
    string permissionId = 2;
  }

  // A keychain owned by your system has been updated.
  message KeychainUpdated {
    string keychainFactoryId = 1;
    string permissionId = 2;
  }

  // A keychain owned by your system has been deleted.
  message KeychainDeleted {
    string keychainFactoryId = 1;
    string permissionId = 2;
  }

}