// Copyright 2015 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 vanadium;

// Represents the name of an application. |url| is the url of the application.
// |qualifier| is a string that allows to tie a specific instance of an
// application to another.
struct AppInstanceName {
  string url;
  string? qualifier;
};

// Represents a user identity obtained for an application instance.
//
// |email| is the email address of the user, which may be obtained through a
// third-party authentication flow (e.g., oauth2).
//
// |blessing| is a JSON-encoded Vanadium blessing binding a human-readable
// name (that includes |email|) to the public key of the application instance.
// More specifically, it represents a JSON-encoded WireBlessings object defined
// here: https://github.com/vanadium/go.v23/blob/master/security/types.vdl#L136
// A detailed decription of blessings can be found here:
// https://github.com/vanadium/docs/blob/master/concepts/security.md
struct User {
  string email;
  array<uint8> blessing;
  // TODO(ataly, ukode): Include the name of the identity provider?
  // TODO(ataly, ukode): Include the first and last name of the user?
  // TODO(ataly, ukode): Include any unique ids assigned to the user by the
  // identity provider?
};

// A service that binds user identities to an application instance running in
// Mojo. An application instance may have multiple user identities with one of
// them set as the current identity.
[ServiceName="vanadium::PrincipalService"]
interface PrincipalService {
  // Login is called by an application instance (requestor_url/qualifier) that
  // wants to get a new user identity. The service may obtain the user identity
  // through a third-party authentication flow (e.g., oauth2) which may involve
  // user intervention. The obtained identity is added to the set of
  // authenticated user identities of the application instance, and is also set
  // as the current user identity for the application instance.
  //
  // Additionally, the service creates a user blessing that binds the obtained
  // email address of the user to the unique public/private key-pair of the
  // application instance.
  //
  // Returns the user identity or null if an error is encountered at any stage.
  Login() => (User? user);

  // Logout sets the current user identity of the calling application instance
  // to null.
  Logout();

  // GetUser returns the current user identity for a given application
  // instance.  If a null application instance is provided then the current
  // user identity of the calling application instance is returned.
  //
  // Returns null if the application instance has not invoked Login or if the
  // instance is in logged out state (see 'Logout').
  GetUser(AppInstanceName? app) => (User? user);

  // SetUser sets the current user identity of the calling application
  // instance. The provided identity must be present in the set of logged-in
  // user identities for the application instance, otherwise an error is
  // returned.
  SetUser(User user) => (string? error);

  // GetLoggedInUsers returns all authenticated user identities of the calling
  // application instance. The user identities are a result of previous Login
  // calls by the application instance.
  GetLoggedInUsers() => (array<User> ids);
};