// Copyright 2017 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

module webauth.mojom;

import "mojo/common/time.mojom";
import "url/mojo/url.mojom";

// This file describes the communication between the WebAuthentication renderer
// implementation and browser-side implementations to create public key
// credentials and use already-created credentials to get assertions.
// See https://w3c.github.io/webauthn/.

enum AuthenticatorStatus {
  SUCCESS,
  PENDING_REQUEST,
  NOT_ALLOWED_ERROR,
  NOT_SUPPORTED_ERROR,
  INVALID_DOMAIN,
  TIMED_OUT,
  NOT_IMPLEMENTED,
  UNKNOWN_ERROR,
};

// Credential information returned by both Authenticator::MakeCredential 
// and Authenticator::GetAssertion.
 struct CommonCredentialInfo {
  // The base64url encoding of |raw_id|.
  string id;

  // An identifier for the credential.
  array<uint8> raw_id;

  // A blob of data containing the JSON serialization of client data passed
  // to the authenticator.
  array<uint8> client_data_json;
};

// The public key and attestation returned by Authenticator::MakeCredential.
struct MakeCredentialAuthenticatorResponse {
  CommonCredentialInfo info;

  // A blob of data returned by the authenticator after creating a credential.
  array<uint8> attestation_object;
};

struct GetAssertionAuthenticatorResponse {
  CommonCredentialInfo info;

  // A blob of data returned by the authenticator after generating an assertion.
  array<uint8> authenticator_data;

  // Cryptographic signature proving possession of the credential private key.
  array<uint8> signature;

   // Only supported by CTAP devices, not by U2F devices.
   // Equivalent of the `user.id` passed into create().
   // Maximum 64 bytes.
   array<uint8>? user_handle;
};

// Information about the relying party. These fields take arbitrary input.
struct PublicKeyCredentialRpEntity {
  // An ASCII serialization of an origin.
  string id;

  // Friendly name associated with the relying party intended for display.
  // e.g. "Acme Corporation".
  string name;

  // Image associated with the entity. e.g. a relying party's logo.
  url.mojom.Url? icon;
};

// Informatiom about the account held by the user. These fields take
// arbitrary input.
struct PublicKeyCredentialUserEntity {
  // Unique identifier for a user account An opaque byte sequence with a
  // maximum size of 64 bytes.
  array<uint8> id;

  // Friendly name associated with the entity intended for display.
  // e.g."john.p.smith@example.com" or "+14255551234" for a user.
  string name;

  // Image associated with the entity. For example, a user’s avatar.
  url.mojom.Url? icon;

  // Contains a friendly name for the user account (e.g., "John P. Smith").
  string display_name;
};

// Parameters that are used to generate an appropriate public key credential.
struct PublicKeyCredentialParameters {
  PublicKeyCredentialType type;
  int32 algorithm_identifier;
};

// Parameters passed into calls to GetAssertion.
struct PublicKeyCredentialRequestOptions {
  // An indefinite-length blob passed from the the relying party server,
  // to be sent to an authenticator for signing.
  array<uint8> challenge;

  // Time to wait for an authenticator to complete an operation.
  // Adjusted to fall within a client-defined range.
  mojo.common.mojom.TimeDelta adjusted_timeout;

  // An ASCII serialization of the origin claimed by the relying party.
  string relying_party_id;

  // A list of credentials the relying party knows about and would
  // accept as the signing credential.
  array<PublicKeyCredentialDescriptor> allow_credentials;
};

// Parameters passed into calls to MakeCredential.
struct MakePublicKeyCredentialOptions {
  // Information about the relying party and user entities, respectively.
  // Used by the authenticator to create or retrieve an appropriate public key
  // credential for the requested account.
  PublicKeyCredentialRpEntity relying_party;
  PublicKeyCredentialUserEntity user;

  // An indefinite-length blob passed from the the relying party server,
  // to be sent to an authenticator to make a credential.
  array<uint8> challenge;

  // Parameters defining the type of created credential that the relying
  // party would accept.
  array<PublicKeyCredentialParameters> public_key_parameters;

  // Time to wait for an authenticator to complete an operation.
  // Adjusted to fall within a client-defined range.
  mojo.common.mojom.TimeDelta adjusted_timeout;

  // A list of credentials the relying party knows about. If an
  // authenticator has one of these credentials, it should not
  // create a new one.
  array<PublicKeyCredentialDescriptor> exclude_credentials;

  // TODO(kpaulhamus): add AuthenticatorSelectionCriteria
};

enum PublicKeyCredentialType {
  PUBLIC_KEY,
};

// Describes the credentials that the relying party already knows about for
// the given account. If any of these are known to the authenticator,
// it should not create a new credential.
struct PublicKeyCredentialDescriptor {
  PublicKeyCredentialType type;

  // Blob representing a credential key handle. Up to 255 bytes for
  // U2F authenticators.
  array<uint8> id;

  array<AuthenticatorTransport> transports;
};

enum AuthenticatorTransport {
  USB,
  NFC,
  BLE,
};

// Interface to direct authenticators to create or use a public key credential.
interface Authenticator {
  // Gets the credential info for a new public key credential created by an
  // authenticator for the given |MakePublicKeyCredentialOptions|
  // [MakeCredentialAuthenticatorResponse] will be set if and only if status == SUCCESS.
  MakeCredential(MakePublicKeyCredentialOptions options)
      => (AuthenticatorStatus status, MakeCredentialAuthenticatorResponse? credential);

  // Uses an existing credential to produce an assertion for the given
  // |PublicKeyCredentialRequestOptions|.
  // |GetAssertionResponse| will be set if and only if status == SUCCESS.
  GetAssertion(PublicKeyCredentialRequestOptions options)
      => (AuthenticatorStatus status, GetAssertionAuthenticatorResponse? credential);
};