internet_identity.did

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 LayoutMigrationState = variant {
    not_started;
    started: record {
        // number of anchors that still need migration. Once it reaches 0, the migration is finished.
        anchors_left: nat64;
        batch_size: nat64;
    };
    finished;
};

type InternetIdentityStats = record {
    users_registered: nat64;
    storage_layout_version: nat8;
    assigned_user_number_range: record {
        nat64;
        nat64;
    };
    archive_info: ArchiveInfo;
    canister_creation_cycles_cost: nat64;
    // this is opt so that we can remove the migration state after the migration without breaking any clients
    layout_migration_state: opt LayoutMigrationState;
};

// Information about the archive.
type ArchiveInfo = record {
    // Canister id of the archive or empty if no archive has been deployed yet.
    archive_canister : opt principal;
    // Expected hash of the archive wasm module. II will accept wasm modules hashing to this hash in the canister call
    // deploy_archive. The actual installed archive wasm hash might be different if the archive has not yet been upgraded.
    // When empty, deployment of the archive is disabled and II will not accept any wasm module.
    expected_wasm_hash: opt blob;
};

// Init arguments of II which can be supplied on install and upgrade.
// Setting a value to null keeps the previous value.
type InternetIdentityInit = record {
    // Set lowest and highest anchor
    assigned_user_number_range : opt record {
        nat64;
        nat64;
    };
    // Set the module hash of the archive canister
    archive_module_hash : opt blob;
    // Set the amounts of cycles sent with the create canister message.
    // This is configurable because in the staging environment cycles are required.
    // The canister creation cost on mainnet is currently 100'000'000'000 cycles. If this value is higher thant the
    // canister creation cost, the newly created canister will keep extra cycles.
    canister_creation_cycles_cost : opt nat64;
    // Migration batch size for the anchor layout migration.
    // If set to 0, migration is disabled (if the migration was already started, it will be paused in the current state).
    layout_migration_batch_size: opt nat32;
};

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;
};

type DeployArchiveResult = variant {
    // The archive was deployed successfully and the supplied wasm module has been installed. The principal of the archive
    // canister is returned.
    success: principal;
    // Initial archive creation is already in progress.
    creation_in_progress;
    // Archive deployment failed. An error description is returned.
    failed: text;
};

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;

    deploy_archive: (wasm: blob) -> (DeployArchiveResult);
}