// Copyright 2019 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library fuchsia.identity.authentication;

using zx;

/// The maxium size of the prekey material in bytes.
const PREKEY_MATERIAL_MAX_SIZE uint32 = 32;

/// The maxium size of enrollment data in bytes.
const ENROLLMENT_DATA_MAX_SIZE uint32 = 256;

/// An empty struct for union variants without data.
/// TODO(https://fxbug.dev/42159332): Replace with a built-in type when one exists.
type Empty = struct {};

/// Specifies the reason that a fuchsia.identity.authentication method failed.
type Error = flexible enum {
    /// Some other problem occurred that cannot be classified using one of the
    /// more specific statuses. Retry is optional.
    UNKNOWN = 1;

    /// An internal error occurred. This usually indicates a bug within the
    /// component implementing the authentication mechanism. Retry is optional.
    INTERNAL = 2;

    /// The requested operation is not supported. This generally indicates that
    /// implementation of a new feature is not yet complete. The request should
    /// not be retried.
    UNSUPPORTED_OPERATION = 3;

    /// An invalid or non-functional `AuthenticationContextProvider` was
    /// provided. Retrying is unlikely to correct this error.
    INVALID_AUTH_CONTEXT = 4;

    /// The request was malformed in some way, such as supplying duplicate
    /// enrollment entries. The request should not be retried.
    INVALID_REQUEST = 5;

    /// Data supplied with the request was malformed in some way, such as
    /// supplying corrupted enrollment data. The request should not be retried.
    INVALID_DATA_FORMAT = 6;

    /// A local resource error occurred such as I/O, FIDL, or memory allocation
    /// failure. Retry, after a delay, is recommended.
    RESOURCE = 7;

    /// The client cancelled an authentication operation, usually by closing
    /// a channel.
    ABORTED = 8;
};

/// The maximum number of active enrollments per authentication mechanism and
/// account.
const MAX_ENROLLMENTS uint32 = 16;

/// An Enrollment is an instantiation of an authentication mechanism for a
/// particular account. An enrollment is typically tied to a user-controlled
/// authentication factor, such as a fingerprint, a password or a security key.
type Enrollment = struct {
    /// An identifier for the enrollment within the scope of the account.
    id EnrollmentId;

    /// Data associated with the enrollment.
    data EnrollmentData;
};

/// A unique identifier for an `Enrollment` within an account and an
/// authentication mechanism.
alias EnrollmentId = uint64;

/// Arbitrary opaque data associated with an authentication enrollment, created
/// and subsequently read by the authentication mechanism that produced the
/// enrollment. It is meaningful only to the authenticator, and opaque to its
/// clients.
alias EnrollmentData = vector<uint8>:ENROLLMENT_DATA_MAX_SIZE;

/// Pseudo-random data associated with an enrollment of an authentication
/// mechanism capable of storage unlock. It is reproduced only upon
/// successful authentication against that enrollment.
alias PrekeyMaterial = vector<uint8>:PREKEY_MATERIAL_MAX_SIZE;

/// An authentication event is a statement which an authentication mechanism
/// makes about the presence and/or engagement of an account owner, and thus
/// affecting the entity's authentication state. The effect of an event depends
/// on the properties of the authentication mechanism which created it.
/// A positive authentication event may contribute to an increase in
/// authentication state.
type PositiveEvent = table {
    /// The UTC time when the event completed.
    1: timestamp zx.Time;
};

/// A negative authentication event may contribute to a decrease in
/// authentication state.
type NegativeEvent = table {
    /// The UTC time when the event completed.
    1: timestamp zx.Time;
};

/// A attempted authentication event may contribute to an increase in
/// authentication state if and only if the pre-key material is correct.
/// Otherwise, it does not affect the authentication state.
type AttemptedEvent = table {
    /// The UTC time when the event completed.
    1: timestamp zx.Time;

    /// The id of the enrollment used to produce this attempt.
    2: enrollment_id EnrollmentId;

    /// Enrollment data which should should replace the old enrollment data upon
    /// successful authentication. This field is only populated if a change in
    /// enrollment data is required.
    3: updated_enrollment_data EnrollmentData;

    /// Pre-key material produced during the authentication attempt.
    4: prekey_material PrekeyMaterial;
};