avp-go

Go implementation of Agent Vault Protocol
Standard conformance · Single binary · Cloud native

---

Overview

avp-go is the official Go implementation of the Agent Vault Protocol (AVP). It's designed for cloud-native applications, Kubernetes operators, and high-performance backend services.

Features

• Standard AVP Conformance — All 7 core operations
• Multiple Backends — File, Keychain, Remote (HashiCorp Vault, AWS, GCP, Azure)
• Cloud Native — Kubernetes secrets, service mesh ready
• Zero Dependencies — Pure Go, no CGO required
• Context Support — Full context.Context integration

Installation

go get github.com/avp-protocol/avp-go

Quick Start

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/avp-protocol/avp-go"
)

func main() {
    ctx := context.Background()

    // Create vault instance
    vault, err := avp.NewVault("avp.toml")
    if err != nil {
        log.Fatal(err)
    }
    defer vault.Close()

    // Authenticate
    if err := vault.Authenticate(ctx); err != nil {
        log.Fatal(err)
    }

    // Store a secret
    if err := vault.Store(ctx, "anthropic_api_key", []byte("sk-ant-...")); err != nil {
        log.Fatal(err)
    }

    // Retrieve a secret
    apiKey, err := vault.Retrieve(ctx, "anthropic_api_key")
    if err != nil {
        log.Fatal(err)
    }

    fmt.Printf("Retrieved key: %s...\n", apiKey[:10])
}

Backend Selection

import "github.com/avp-protocol/avp-go"

// File backend (encrypted)
vault, _ := avp.NewVault(avp.WithBackend(&avp.FileBackend{
    Path:   "~/.avp/secrets.enc",
    Cipher: avp.CipherAES256GCM,
}))

// OS Keychain
vault, _ := avp.NewVault(avp.WithBackend(&avp.KeychainBackend{}))

// HashiCorp Vault
vault, _ := avp.NewVault(avp.WithBackend(&avp.RemoteBackend{
    URL:   "https://vault.company.com",
    Token: "hvs.xxx",
}))

// AWS Secrets Manager
vault, _ := avp.NewVault(avp.WithBackend(&avp.AWSBackend{
    Region: "us-east-1",
}))

// GCP Secret Manager
vault, _ := avp.NewVault(avp.WithBackend(&avp.GCPBackend{
    Project: "my-project",
}))

Kubernetes Integration

import "github.com/avp-protocol/avp-go/k8s"

// Use Kubernetes secrets as backend
vault, _ := avp.NewVault(avp.WithBackend(&k8s.SecretBackend{
    Namespace: "default",
}))

// Or create a Kubernetes operator
operator := k8s.NewOperator(vault)
operator.Run(ctx)

Migration

import "github.com/avp-protocol/avp-go/migration"

// Migrate from file to remote vault
err := migration.Migrate(ctx,
    &avp.FileBackend{Path: "~/.avp/secrets.enc"},
    &avp.RemoteBackend{URL: "https://vault.company.com"},
)

API Reference

Vault Interface

type Vault interface {
    Discover(ctx context.Context) (*DiscoverResponse, error)
    Authenticate(ctx context.Context, opts ...AuthOption) error
    Store(ctx context.Context, name string, value []byte, opts ...StoreOption) error
    Retrieve(ctx context.Context, name string) ([]byte, error)
    Delete(ctx context.Context, name string) error
    List(ctx context.Context, opts ...ListOption) ([]SecretEntry, error)
    Rotate(ctx context.Context, name string, strategy RotationStrategy) error
    Close() error
}

Conformance

Level	Status
AVP Core	✅ Complete
AVP Full	✅ Complete
AVP Hardware	⚠️ Via USB bridge

Contributing

See CONTRIBUTING.md for development setup.

We're looking for maintainers! If you're interested, open an issue.

License

Apache 2.0 — see LICENSE.

---

Specification · Documentation · Issues