// Copyright 2015 The Vanadium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

package io.v.v23.security;

import io.v.v23.verror.VException;

import java.security.interfaces.ECPublicKey;

/**
 * An entity capable of making or receiving RPCs.  {@link VPrincipal}s have a unique
 * (public, private) key pair, have blessings bound to them, and can bless other principals.
 * <p>
 * Multiple goroutines may invoke methods on a {@link VPrincipal} simultaneously.
 * <p>
 * See also: <a href="https://github.com/vanadium/docs/blob/master/glossary.md#principal">https://github.com/vanadium/docs/blob/master/glossary.md#principal</a>.
 */
public interface VPrincipal {
    /**
     * Binds extensions of blessings held by this principal to another principal (represented by
     * its public key).
     * <p>
     * For example, a principal with the blessings {@code "google:alice"} and
     * {@code "vanadium:alice"} can bind the blessings {@code "google:alice:friend"} and
     * {@code "vanadium:alice:friend"} to another principal using:
     * <p><blockquote><pre>
     *   {@literal bless(<other principal>, <google:alice, vanadium:alice>, "friend", ...)}
     * </pre></blockquote><p>
     * To discourage unconstrained delegation of authority, the interface requires at least one
     * caveat to be provided. If unconstrained delegation is desired, the
     * {@link VSecurity#newUnconstrainedUseCaveat} method can be used to produce this argument.
     * <p>
     * {@code with.publicKey()} must be the same as the principal's public key.
     *
     * @param  key               public key representing the principal being blessed
     * @param  with              blessings of the current principal (i.e., the one doing the
     *                           blessing) that should be used for the blessing
     * @param  extension         extension that the blessee should be blessed with
     * @param  caveat            caveat on the blessing
     * @param  additionalCaveats addional caveats on the blessing
     * @return                   the resulting blessings
     * @throws VException        if the blessee couldn't be blessed
     */
    Blessings bless(ECPublicKey key, Blessings with, String extension, Caveat caveat,
        Caveat... additionalCaveats) throws VException;

    /**
     * Creates a blessing with the provided name for this principal.
     *
     * @param  name            the name to bless self with
     * @param  caveats         caveats on the blessings
     * @return                 the resulting blessings
     * @throws VException      if there was an error blessing self
     */
    Blessings blessSelf(String name, Caveat... caveats) throws VException;

    /**
     * Uses the private key of the principal to sign a message.
     *
     * @param  message         the message to be signed
     * @return                 signature of the message
     * @throws VException      if the message couldn't be signed
     */
    VSignature sign(byte[] message) throws VException;

    /**
     * Returns the public key counterpart of the private key held by the principal.
     */
    ECPublicKey publicKey();

    /**
     * Provides access to the {@link BlessingStore} containing blessings that have been granted to
     * this principal.  The returned {@link BlessingStore} is never {@code null}.
     *
     * @return a {@link BlessingStore} containing blessings that have been granted to this principal
     */
    BlessingStore blessingStore();

    /**
     * Returns the set of recognized authorities (identified by their public keys) on blessings that
     * match specific patterns.  Never returns {@code null}.
     */
    BlessingRoots roots();
}