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

/// 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
closed protocol StorageUnlockMechanism {
    /// Interactively requests the user to authenticate against any of the
    /// provided enrollments.
    ///
    /// `interaction` The server end of a channel that will be used to
    ///               interact with the UI. The type of this channel must
    ///               match a mechanism supported by the authenticator.
    /// `enrollments` A list of enrollments that will be accepted. These
    ///               must all match the mechanism specified in `interaction`.
    ///
    /// 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.
    ///
    /// Fails with `ABORTED` if the client closes the `interaction` channel.
    strict Authenticate(resource struct {
        interaction InteractionProtocolServerEnd;
        enrollments vector<Enrollment>:MAX_ENROLLMENTS;
    }) -> (struct {
        attempt AttemptedEvent;
    }) error Error;

    /// Interactively run the enrollment flow for a single enrollment.
    ///
    /// `interaction` The server end of a channel that will be used to
    ///               interact with the UI. The type of this channel must
    ///               match a mechanism supported by the authenticator.
    ///
    /// Returns: `enrollment_data` Data associated with this enrollment,
    ///                            to be provided during authentication in
    ///                            the future.
    ///          `prekey_material` The pre-key material that will be produced
    ///                            by successfully authenticating against this
    ///                            enrollment.
    ///
    /// Fails with `ABORTED` if the client closes the `interaction` channel.
    strict Enroll(resource struct {
        interaction InteractionProtocolServerEnd;
    }) -> (struct {
        enrollment_data EnrollmentData;
        prekey_material PrekeyMaterial;
    }) error Error;
};