From 1a90d3d3a24030797dc15817d7a577f25ff2669c Mon Sep 17 00:00:00 2001 From: "M. J. Fromberger" Date: Wed, 7 Jan 2026 09:52:10 -0800 Subject: [PATCH 1/3] docs: add more details about explicit version management As a follow-up to #151, add a bit more prose to the docs about the existence of explicitly-managed version numbers, and some recommendations about when to use them. --- docs/README.md | 45 ++++++++++++++++++++++++++++++++++++++------- docs/api.md | 9 ++++++--- 2 files changed, 44 insertions(+), 10 deletions(-) diff --git a/docs/README.md b/docs/README.md index f973e9e..65d41ff 100644 --- a/docs/README.md +++ b/docs/README.md @@ -21,6 +21,7 @@ Setec is a lightweight secrets management service that uses Tailscale for access - [Operations and Maintenance](#operations-and-maintenance) - [Secret Rotation](#secret-rotation) - [Automatic Updates](#automatic-updates) + - [Explicit Version Management](#explicit-version-management) - [Bootstrapping and Availability](#bootstrapping-and-availability) - [Testing](#testing) @@ -93,14 +94,24 @@ secret. 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. +- When a secret is first created, its initial value becomes its current active + version. + + The `put` API method assigns sequential versions starting from the largest + previously used (initially 1, for a new secret). + The `create-version` API method uses the version number specified by the caller. + +- Thereater, the active version changes in the following ways: + + The `activate` method updates the current active version to a specific + existing value. + + A successful `create-version` method call automatically activates the new + version of the secret that it created. + + Note that `put` does _not_ automatically update the active version, except + when creating the initial value of a new secret. -- 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. - - The special `create-version` method automatically activates the set - version and does not require a call to `activate`. ### Deleting Values @@ -422,6 +433,26 @@ effects a poll of all known secrets synchronously. It is safe for the client to do this concurrently with a background poll; the store will coalesce the operations. +### Explicit Version Management + +For some use cases, the caller may wish to explicitly control the version +numbers of a secret. For example, a caller may wish to associate multiple +secret values with one or more timestamps or other identifying values. + +To support this, the [API](api.md) supports a `create-version` method, allowing +the caller to explicitly choose the version number assigned to a secret value. +The `create-version` method automatically activates a newly-created version, +but such values are otherwise normal, and can be fetched and deleted in the +usual way. Note, however, that a particular version number cannot be reused +once created, even if it is later deleted. + +Although it is safe to mix `put`, `activate` and `create-version` calls on the +same secret, for clarity of use we recommend using _either_ `create-version` +alone, _or_ `put` and `activate` together, but not both. Regardless which +version management style you use, secret values can be [updated +automatically](#automatic-updates) in the usual way. + + ### Bootstrapping and Availability A reasonable concern when fetching secrets from a network service is what diff --git a/docs/api.md b/docs/api.md index 7079532..c8b85f1 100644 --- a/docs/api.md +++ b/docs/api.md @@ -33,8 +33,8 @@ The service defines named _actions_ that are subject to access control: - `put`: Denotes permission to put a new value of a secret. -- `create-version`: Denotes permission to create a specific version of a secret, but not - override an existing version. +- `create-version`: Denotes permission to create a specific version of a + secret, but not overwrite an existing version. - `activate`: Denotes permission to set one one of of the available versions of a secret as the active one. @@ -130,7 +130,10 @@ The service defines named _actions_ that are subject to access control: secret, the server reports the existing active version without modifying the store. -- `/api/create-version`: Creates a specific version of a secret, sets its value and immediately activates that version. It fails if this version of the secret already has a value. The specified version must be > 0. +- `/api/create-version`: Creates a new version of a secret, sets its value and + immediately activates that version. It fails if the specified version number + has already been used for this secret (even if deleted). The specified + version number must be > 0. **Requires:** `create-version` permission for the specified name. From eb88c0ca71b6d4a9d692f96c43e5ba5e341258bd Mon Sep 17 00:00:00 2001 From: "M. J. Fromberger" Date: Thu, 15 Jan 2026 09:37:17 -0800 Subject: [PATCH 2/3] up-to-date --- docs/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/api.md b/docs/api.md index c8b85f1..c404eb0 100644 --- a/docs/api.md +++ b/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 11-May-2024. +> This document is up-to-date as of 15-Jan-2026. 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. From 6edf19657d7d2934fc9485039419c0a594d00e91 Mon Sep 17 00:00:00 2001 From: "M. J. Fromberger" Date: Thu, 15 Jan 2026 09:37:51 -0800 Subject: [PATCH 3/3] fix typo --- docs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index 65d41ff..94ed79f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -101,7 +101,7 @@ secret. previously used (initially 1, for a new secret). The `create-version` API method uses the version number specified by the caller. -- Thereater, the active version changes in the following ways: +- Thereafter, the active version changes in the following ways: The `activate` method updates the current active version to a specific existing value.