// 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 agent defines an interface to keep a private key in memory, and for
// clients to have access to the private key.
//
// Protocol
//
// The agent starts processes with the VEYRON_AGENT_FD set to one end of a
// unix domain socket. To connect to the agent, a client should create
// a unix domain socket pair. Then send one end of the socket to the agent
// with 1 byte of data. The agent will then serve the Agent service on
// the received socket, using SecurityNone.
//
// The agent also supports an optional mode where it can manage multiple principals.
// Typically this is only used by Device Manager. In this mode, VEYRON_AGENT_FD
// will be 3, and there will be another socket at fd 4.
// Creating a new principal is similar to connecting to to agent: create a socket
// pair and send one end on fd 4 with 1 byte of data.
// Set the data to 1 to request the principal only be stored in memory.
// The agent will create a new principal and respond with a principal handle on fd 4.
// To connect using a previously created principal, create a socket pair and send
// one end with the principal handle as data on fd 4. The agent will not send a
// response on fd 4.
// In either, you can use the normal process to connect to an agent over the
// other end of the pair. Typically you would pass the other end to a child
// process and set VEYRON_AGENT_FD so it knows to connect.
//
// The protocol also has limited support for caching: A client can
// request notification when any other client modifies the principal so it
// can flush the cache. See NotifyWhenChanged for details.
package agent

import (
	"v.io/v23/security"
)

type Agent interface {
	Bless(key []byte, wit security.WireBlessings, extension string, caveat security.Caveat, additionalCaveats []security.Caveat) (security.WireBlessings | error)
	BlessSelf(name string, caveats []security.Caveat) (security.WireBlessings | error)
	Sign(message []byte) (security.Signature | error)
	MintDischarge(forCaveat, caveatOnDischarge security.Caveat, additionalCaveatsOnDischarge []security.Caveat) (security.WireDischarge | error)
	PublicKey() ([]byte | error)
	BlessingsByName(name security.BlessingPattern) ([]security.WireBlessings | error)
	BlessingsInfo(blessings security.WireBlessings) (map[string][]security.Caveat | error)
	AddToRoots(blessing security.WireBlessings) error

	BlessingStoreSet(blessings security.WireBlessings, forPeers security.BlessingPattern) (security.WireBlessings | error)
	BlessingStoreForPeer(peerBlessings []string) (security.WireBlessings | error)
	BlessingStoreSetDefault(blessings security.WireBlessings) error
	BlessingStoreDefault() (security.WireBlessings | error)
	BlessingStorePeerBlessings() (map[security.BlessingPattern]security.WireBlessings | error)
	BlessingStoreDebugString() (string | error)

	BlessingRootsAdd(root []byte, pattern security.BlessingPattern) error
	BlessingRootsRecognized(root []byte, blessing string) error
	BlessingRootsDump() (map[security.BlessingPattern][][]byte | error)
	BlessingRootsDebugString() (string | error)

	// Clients using caching should call NotifyWhenChanged upon connecting to
	// the server. The server will stream back values whenever the client should
	// flush the cache. The streamed value is arbitrary, simply flush whenever
	// recieving a new item.
	NotifyWhenChanged() stream<_, bool> error
}