docs(readme): add README.md (#1)

Signed-off-by: Black-Hole1 <[email protected]>

README.md

@@ -0,0 +1,28 @@
+# OVM SSH Agent
+
+[![license]](https://github.com/oomol-lab/ovm-ssh-agent/blob/main/LICENSE) [![repo size]](https://github.com/oomol-lab/ovm-ssh-agent) [![release]](https://github.com/oomol-lab/ovm-ssh-agent/releases/latest)
+
+Compatible with any third-party SSH Agent. (e.g. 1Password)
+
+###### Supported Platforms
+
+- Mac OS
+- Linux
+
+
+###### Install
+
+```shell
+go get github.com/oomol-lab/ovm-ssh-agent
+```
+
+###### Documentation
+
+[![Go Reference](https://pkg.go.dev/badge/github.com/oomol-lab/ovm-ssh-agent.svg)](https://pkg.go.dev/github.com/oomol-lab/ovm-ssh-agent)
+
+Full go doc style documentation for the package can be viewed online without installing this package by using the GoDoc site here: http://pkg.go.dev/github.com/oomol-lab/ovm-ssh-agent
+
+
+[license]: https://img.shields.io/github/license/oomol-lab/ovm-ssh-agent?style=flat-square&color=9cf
+[repo size]: https://img.shields.io/github/repo-size/oomol-lab/ovm-ssh-agent?style=flat-square&color=9cf
+[release]: https://img.shields.io/github/v/release/oomol-lab/ovm-ssh-agent?style=flat-square&color=9cf

pkg/sshagent/agent.go

@@ -19,17 +19,21 @@ type ProxyAgent struct {
 	log                types.Logger
 }
 
+// NewProxyAgent creates a new ProxyAgent.
 func NewProxyAgent(log types.Logger) *ProxyAgent {
 	return &ProxyAgent{
 		local: agent.NewKeyring(),
 		log:   log,
 	}
 }
 
+// SetExtendedAgent sets the extended agent path.
 func (a *ProxyAgent) SetExtendedAgent(socketPath string) {
 	a.upstreamSocketPath = socketPath
 }
 
+// AddIdentities adds identities to the agent(local).
+// It not adds identities to the extended agent.
 func (a *ProxyAgent) AddIdentities(key ...agent.AddedKey) error {
 	for _, k := range key {
 		if err := a.Add(k); err != nil {
@@ -55,6 +59,7 @@ func (a *ProxyAgent) refreshExtendedAgent() agent.ExtendedAgent {
 	return agent.NewClient(conn)
 }
 
+// List returns the identities known to the agent(local + extended).
 func (a *ProxyAgent) List() ([]*agent.Key, error) {
 	l, err := a.local.List()
 
@@ -72,18 +77,25 @@ func (a *ProxyAgent) List() ([]*agent.Key, error) {
 	return l, err
 }
 
+// Add adds a private key to the agent(local).
+// It will not add from extended agent.
 func (a *ProxyAgent) Add(key agent.AddedKey) error {
 	return a.local.Add(key)
 }
 
+// Remove removes identities with the given public key (local).
+// It will not remove from extended agent.
 func (a *ProxyAgent) Remove(key ssh.PublicKey) error {
 	return a.local.Remove(key)
 }
 
+// RemoveAll removes all identities (local).
+// It will not remove all from extended agent.
 func (a *ProxyAgent) RemoveAll() error {
 	return a.local.RemoveAll()
 }
 
+// Lock locks the agent (local + extended).
 func (a *ProxyAgent) Lock(passphrase []byte) error {
 	err := a.local.Lock(passphrase)
 	if err != nil {
@@ -97,6 +109,7 @@ func (a *ProxyAgent) Lock(passphrase []byte) error {
 	return err
 }
 
+// Unlock undoes the effect of Lock (local + extended).
 func (a *ProxyAgent) Unlock(passphrase []byte) error {
 	err := a.local.Unlock(passphrase)
 	if err != nil {
@@ -110,6 +123,8 @@ func (a *ProxyAgent) Unlock(passphrase []byte) error {
 	return err
 }
 
+// Sign returns a signature by signing data with the given public key (local + extended).
+// Prioritize signing from the local. If signing from the local source fails, then try extended.
 func (a *ProxyAgent) Sign(key ssh.PublicKey, data []byte) (*ssh.Signature, error) {
 	sig, err := a.local.Sign(key, data)
 	if err == nil {
@@ -123,6 +138,7 @@ func (a *ProxyAgent) Sign(key ssh.PublicKey, data []byte) (*ssh.Signature, error
 	return sig, err
 }
 
+// Signers returns signers for all signers (local + extended).
 func (a *ProxyAgent) Signers() ([]ssh.Signer, error) {
 	signers, err := a.local.Signers()
 	if err != nil {
@@ -143,6 +159,8 @@ func (a *ProxyAgent) Signers() ([]ssh.Signer, error) {
 	return signers, err
 }
 
+// SignWithFlags returns a signature by signing data with the given public key (local + extended).
+// Prioritize signing from the local. If signing from the local source fails, then try extended.
 func (a *ProxyAgent) SignWithFlags(key ssh.PublicKey, data []byte, flags agent.SignatureFlags) (*ssh.Signature, error) {
 	sig, err := a.local.(agent.ExtendedAgent).SignWithFlags(key, data, flags)
 	if err == nil {
@@ -156,6 +174,7 @@ func (a *ProxyAgent) SignWithFlags(key ssh.PublicKey, data []byte, flags agent.S
 	return sig, err
 }
 
+// Extension not supported.
 func (a *ProxyAgent) Extension(extensionType string, contents []byte) ([]byte, error) {
 	return nil, agent.ErrExtensionUnsupported
 }

pkg/sshagent/sshagent.go

@@ -22,6 +22,7 @@ type SSHAgent struct {
 	poxyAgent  *ProxyAgent
 }
 
+// New creates a new SSHAgent.
 func New(socketPath string, log types.Logger) (*SSHAgent, error) {
 	s := &SSHAgent{
 		socketPath: socketPath,
@@ -40,14 +41,18 @@ func New(socketPath string, log types.Logger) (*SSHAgent, error) {
 	return s, nil
 }
 
+// SetExtendedAgent sets the extended agent path.
 func (s *SSHAgent) SetExtendedAgent(p string) {
 	s.poxyAgent.SetExtendedAgent(p)
 }
 
+// AddIdentities adds identities to the agent(local).
+// It not adds identities to the extended agent.
 func (s *SSHAgent) AddIdentities(key ...agent.AddedKey) error {
 	return s.poxyAgent.AddIdentities(key...)
 }
 
+// Listen starts listening on the ssh auth socket.
 func (s *SSHAgent) Listen() {
 	for {
 		conn, err := s.l.Accept()
@@ -71,6 +76,7 @@ func (s *SSHAgent) Listen() {
 	}
 }
 
+// Close closes the ssh auth socket.
 func (s *SSHAgent) Close() {
 	close(s.done)
 	_ = s.l.Close()

pkg/types/logger.go

@@ -5,6 +5,7 @@
 
 package types
 
+// Logger is the interface for logging.
 type Logger interface {
 	Infof(format string, args ...any)
 	Warnf(format string, args ...any)