Clarify the interactions among secret versions

cmd/setec/setec.go

@@ -441,6 +441,9 @@ func runPut(env *command.Env, name string) error {
 		return fmt.Errorf("failed to write secret: %w", err)
 	}
 	fmt.Printf("Secret saved as %q, version %d\n", name, ver)
+	if ver != 1 {
+		fmt.Printf("  To activate this version, run 'setec activate %q %d'\n", name, ver)
+	}
 	return nil
 }
 

docs/README.md

@@ -3,7 +3,11 @@
 ## Table of Contents
 
 - [Background](#background)
-- [Basic usage](#basic-usage)
+- [API Overview](#api-overview)
+   - [Basic Operations](#basic-operations)
+   - [Current Active Versions](#current-active-versions)
+   - [Deleting Values](#deleting-values)
+- [Basic Usage](#basic-usage)
 - [Migrating to Setec](#migrating-to-setec)
 - [Operations and Maintenance](#operations-and-maintenance)
    - [Secret Rotation](#secret-rotation)
@@ -40,6 +44,47 @@ surface for managing secrets in third-party deployment environments: All the
 secrets are stored in one place, with access controls and audit logs to allow
 forensics in the event of a compromise.
 
+
+## API Overview
+
+A **secret** in `setec` is a named collection of values. Each value is an
+arbitrary byte string identified by an integer **version number**.
+
+### Basic Operations
+
+The [setec API](api.md) defines the following basic operations:
+
+- The `get` method retrieves the value of a single version of a secret.
+  Clients use this method to obtain the secrets they need in production.
+
+- The `info` and `list` methods report the names and available versions (but
+  not the values) of secrets accessible to the caller.
+
+- The `put` method creates or adds a new value to a secret. The server assigns
+  and reports a version number for the value.
+
+### Current Active Versions
+
+- At any time, one version of the secret is designated as its **current active
+  version**. The active version is reported by default from the `get` method if
+  the caller does not specify a specific version.
+
+- When a secret is first created, its initial value (version 1) becomes its
+  current active version.
+
+- Thereafter, the `activate` method must be used to update the current active
+  version. This ensures the operator of the service has precise control over
+  which version of a secret should be used at a time.
+
+### Deleting Values
+
+- The `delete-version` method deletes a single version of a secret.  This
+  method will not delete the current active version.
+
+- The `delete` method deletes all the versions of a secret, removing it
+  entirely from the service.
+
+
 ## Basic usage
 
 All of the methods of the setec API are HTTPS POST requests. Calls to the API
@@ -101,6 +146,7 @@ setec_get() {
 }
 ```
 
+
 ## Migrating to Setec
 
 When migrating existing programs to use setec, there are two main patterns of
@@ -194,6 +240,7 @@ call_api() {
 # ...
 ```
 
+
 ## Operations and Maintenance
 
 This section discusses some common service operation and maintenance tasks that
@@ -438,6 +485,7 @@ the program's secret values to local storage, which means they can be read by
 program can start up immediately using cached data, even if the secrets server
 is not reachable when it launches.
 
+
 ## Self-Contained Operation
 
 In some cases, you may need to run a program entirely without access to a
@@ -532,6 +580,7 @@ The opposite is also true: By design, the format of the cache files can also be
 used directly as the input to a `FileClient` if you need to spin up a new
 instance of an existing server somewhere else.
 
+
 ## Unit Testing
 
 For programs written in Go, the [`setectest`][setectest] package provides

docs/api.md

@@ -1,7 +1,7 @@
 # setec API
 
 > WARNING: This API is still under active development, and subject to change.
-> This document is up-to-date as of 13-Oct-2023.
+> This document is up-to-date as of 11-May-2024.
 
 The setec service exports an API over HTTPS. All methods of the API are called
 via HTTPS POST, with request and response payloads transmitted as JSON.