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

// TODO(fxbug.dev/42836): Supply UI for system authentication.
/// A stateless interface serving an authentication mechanism capable of
/// supplying pre-key material for use with storage unlock. Clients are
/// responsible for managing and persisting enrollments. Enrollment
/// data created during registration must be provided back during
/// authentication.
///
/// NOTE: This protocol may not be discoverable in the future.
@discoverable
protocol StorageUnlockMechanism {
    /// Interactively requests the user to authenticate against any of the
    /// provided enrollments.
    ///
    /// `enrollments`      A list of enrollments that will be accepted.
    ///
    /// Returns: `attempt` An `AttemptedEvent` where the `enrollment_id` refers
    ///                    to one of the provided enrollments, and the optional
    ///                    `updated_enrollment_data` indicates that the
    ///                    enrollment with said id must also be updated if the
    ///                    attempt is successful.
    Authenticate(struct {
        enrollments vector<Enrollment>:MAX_ENROLLMENTS;
    }) -> (struct {
        attempt AttemptedEvent;
    }) error Error;

    /// Interactively run the enrollment flow for a single enrollment.
    ///
    /// Returns: `enrollment_data` Data associated with this enrollment,
    ///                            to be provided during authentication in
    ///                            the future.
    ///          `prekey_material` The the pre-key material that will be
    ///                            produced by successfully authenticating
    ///                            against this enrollment.
    Enroll() -> (struct {
        enrollment_data EnrollmentData;
        prekey_material PrekeyMaterial;
    }) error Error;

    // TODO(dnordstrom): Add method for initilizing authentication event,
    // in order to support user initiated authentication mode.
};

// TODO(dnordstrom): Add a layer of indirection such that multiple
// authentication mechansims can be served by a single discoverable interface.