identity.did

type verification_code = text;
type maxTimeToLive = opt nat64;
type UserNumber = nat64;
type PublicKey = blob;
type CredentialId = blob;
type DeviceKey = PublicKey;
type UserKey = PublicKey;
type SessionKey = PublicKey;
type FrontendHostname = text;
type Timestamp = nat64;

type HeaderField = record { text; text; };

type HttpRequest = record {
  method: text;
  url: text;
  headers: vec HeaderField;
  body: blob;
};

type HttpResponse = record {
  status_code: nat16;
  headers: vec HeaderField;
  body: blob;
  streaming_strategy: opt StreamingStrategy;
};

type StreamingCallbackHttpResponse = record {
  body: blob;
  token: opt Token;
};

type Token = record {};

type StreamingStrategy = variant {
  Callback: record {
    callback: func (Token) -> (StreamingCallbackHttpResponse) query;
    token: Token;
  };
};

type Purpose = variant {
    recovery;
    authentication;
};

type KeyType = variant {
    unknown;
    platform;
    cross_platform;
    seed_phrase;
};

// This describes whether a device is "protected" or not.
// When protected, a device can only be updated or removed if the
// user is authenticated with that very device.
type DeviceProtection = variant {
    protected;
    unprotected;
};

type Challenge = record {
    png_base64: text;
    challenge_key: ChallengeKey;
};

type DeviceData = record {
  pubkey : DeviceKey;
  alias : text;
  credential_id : opt CredentialId;
  purpose: Purpose;
  key_type: KeyType;
  protection: DeviceProtection;
};

type RegisterResponse = variant {
  // A new user was successfully registered.
  registered: record { user_number: UserNumber; };
  // No more registrations are possible in this instance of the II service canister.
  canister_full;
  // The challenge was not successful.
  bad_challenge;
};

type AddTentativeDeviceResponse = variant {
  // The device was tentatively added.
  added_tentatively: record { verification_code: text; device_registration_timeout: Timestamp;};
  // Device registration mode is off, either due to timeout or because it was never enabled.
  device_registration_mode_off;
  // There is another device already added tentatively
  another_device_tentatively_added;
};

type VerifyTentativeDeviceResponse = variant {
  // The device was successfully verified.
  verified;
  // Wrong verification code entered. Retry with correct code.
  wrong_code: record { retries_left: nat8};
  // Device registration mode is off, either due to timeout or because it was never enabled.
  device_registration_mode_off;
  // There is no tentative device to be verified.
  no_device_to_verify;
};

type Delegation = record {
  pubkey: PublicKey;
  expiration: Timestamp;
  targets: opt vec principal;
};

type SignedDelegation = record {
  delegation: Delegation;
  signature: blob;
};

type GetDelegationResponse = variant {
  // The signed delegation was successfully retrieved.
  signed_delegation: SignedDelegation;

  // The signature is not ready. Maybe retry by calling `prepare_delegation`
  no_such_delegation
};

type InternetIdentityStats = record {
  users_registered: nat64;
  assigned_user_number_range: record { nat64; nat64; };
};

type InternetIdentityInit = record {
  assigned_user_number_range : record { nat64; nat64; };
};

type ChallengeKey = text;

type ChallengeResult = record {
    key : ChallengeKey;
    chars : text;
};

type DeviceRegistrationInfo = record {
    tentative_device : opt DeviceData;
    expiration: Timestamp;
};

type IdentityAnchorInfo = record {
    devices : vec DeviceData;
    device_registration: opt DeviceRegistrationInfo;
};

service : (opt InternetIdentityInit) -> {
  init_salt: () -> ();
  create_challenge : () -> (Challenge);
  register : (DeviceData, ChallengeResult) -> (RegisterResponse);
  add : (UserNumber, DeviceData) -> ();
  update : (UserNumber, DeviceKey, DeviceData) -> ();
  remove : (UserNumber, DeviceKey) -> ();
  // Returns all devices of the user (authentication and recovery) but no information about device registrations.
  // Note: Will be changed in the future to be more consistent with get_anchor_info.
  lookup : (UserNumber) -> (vec DeviceData) query;
  get_anchor_info : (UserNumber) -> (IdentityAnchorInfo);
  get_principal : (UserNumber, FrontendHostname) -> (principal) query;
  stats : () -> (InternetIdentityStats) query;

  enter_device_registration_mode : (UserNumber) -> (Timestamp);
  exit_device_registration_mode : (UserNumber) -> ();
  add_tentative_device : (UserNumber, DeviceData) -> (AddTentativeDeviceResponse);
  verify_tentative_device : (UserNumber, verification_code: text) -> (VerifyTentativeDeviceResponse);

  prepare_delegation : (UserNumber, FrontendHostname, SessionKey, maxTimeToLive : opt nat64) -> (UserKey, Timestamp);
  get_delegation: (UserNumber, FrontendHostname, SessionKey, Timestamp) -> (GetDelegationResponse) query;

  http_request: (request: HttpRequest) -> (HttpResponse) query;
}