Principal Service: Add support for multiple user accounts

mojo/services/vanadium/security/interfaces/principal.mojom

-// 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.
+// 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.
+// 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;
 };
 
-// Certificate represents a human-readable name and public-key (DER encoded) pair.
-// The private-key for a certificate is only available for signing operations
-// within the principal service application.
-struct Certificate {
-   string extension;
-   array<uint8>? publickey;
+// Represents a user identity. |email| is the email address of the user, which
+// may be obtained through a third-party authentication flow (e.g., oauth2).
+struct User {
+  string email;
+  Blessing 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?
 };
 
-// Blessing is a credential binding a user identity to a public key. The corresponding
-// private key is only available for signing within the PrincipalService application.
-struct Blessing {
-   array<Certificate> chain;
+// Certificate represents a human-readable name and public-key (DER encoded)
+// pair.  The private-key for a certificate is only available for signing
+// operations within the principal service application.
+struct Certificate {
+  string extension; array<uint8>? publickey;
 };
 
-// ChainSeparator is the separator used to join name extensions in a certificate chain.
+// Blessing is a credential binding a user identity to a public key. The
+// corresponding private key is only available for signing within the
+// PrincipalService application. A detailed decription of the blessings concept
+// can be found at:
+// https://github.com/vanadium/docs/blob/master/concepts/security.md
+// TODO(ataly, gauthamt): This Blessing type does not match the Vanadium
+// WireBlessing type. For the blessing to be usable by SyncBase we will have to
+// make it match the WireBlessing type.
+struct Blessing {
+  array<Certificate> chain;
+};
+
+// ChainSeparator is the separator used to join name extensions in a
+// certificate chain.
 const string ChainSeparator = "/";
 
-// A service that binds user identities to an application instance running in Mojo
+// 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.
 interface PrincipalService {
   // Login is called by an application instance (requestor_url/qualifier) that
-  // wants to get a user blessing. The service may obtain the user blessing
-  // through a third-party authentication flow (eg:oauth2). The user blessing
-  // is bound to a public/private key-pair that this service generates and
-  // persists for this application instance. Returns null if login fails.
-  Login() => (Blessing? user_blessing);
+  // 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);
 
-  // Removes the user blessing for the application instance that invokes the
-  // Logout method.
+  // Logout sets the current user identity of the calling application instance
+  // to null.
   Logout();
 
-  // GetUserBlessing returns the user blessing for a given application instance.
-  // It returns an error if the application instance has not invoked Login().
-  GetUserBlessing(AppInstanceName app) => (Blessing? user_blessing);
+  // 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);
 };
-