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 user_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.
+// 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 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 instance.
+  // This key pair is generated and persisted by this service on the first Login
+  // invocation by the application instance.
+  //
+  // Returns the user identifier 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.
+  // GetUsers returns all authenticated user identities and the current user
+  // identity of the calling application instance. The user identities are a
+  // result of previous Login calls by the instance.
+  //
+  // The current user identity may be null if the instance is in logged out
+  // state (see 'Logout').
+  GetUsers() => (array<User> ids, User? current);
+
+  // SetCurrentUser sets the provided identity as the current user identity of
+  // the calling application instance. The provided identity must be present in
+  // the set of authenticated user identities for the application instance,
+  // otherwise an error is returned.
+  SetCurrentUser(User user) => (string? error);
+
+  // 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 identifier
+  // of the calling application instance is returned.
+  //
+  // Returns null if the application instance has not invoked Login.
+  GetUser(AppInstanceName? app) => (User? user);
 };
-