support create-version operation

The `create-version` operation Creates a specific version of a secret, sets its value and
immediately activates that version. It fails with HTTP status 412 (precondition failed)
if this version of the secret already has a value.

Updates tailscale/corp#34020

Signed-off-by: Percy Wegmann <[email protected]>

Author: oxtoacart

acl/acl.go

@@ -27,6 +27,11 @@ const (
 	// secret.
 	ActionPut = Action("put")
 
+	// ActionCreateVersion ("create-version" in the API) denotes permission to
+	// create a specific version of a secret if and only if that version has no
+	// current value.
+	ActionCreateVersion = Action("create-version")
+
 	// ActionActivate ("activate" in the API) denotes permission to set one one
 	// of of the available versions of a secret as the active one.
 	ActionActivate = Action("activate")

acl/acl_test.go

@@ -16,7 +16,7 @@ func TestACL(t *testing.T) {
 			Secret: []acl.Secret{"control/foo", "control/bar"},
 		},
 		acl.Rule{
-			Action: []acl.Action{acl.ActionInfo, acl.ActionPut, acl.ActionActivate},
+			Action: []acl.Action{acl.ActionInfo, acl.ActionPut, acl.ActionCreateVersion, acl.ActionActivate},
 			Secret: []acl.Secret{"*"},
 		},
 		acl.Rule{
@@ -55,6 +55,12 @@ func TestACL(t *testing.T) {
 		allow("put", "something/else"),
 		allow("put", "dev/foo"),
 
+		allow("create-version", "control/foo"),
+		allow("create-version", "control/bar"),
+		allow("create-version", "control/quux"),
+		allow("create-version", "something/else"),
+		allow("create-version", "dev/foo"),
+
 		allow("activate", "control/foo"),
 		allow("activate", "control/bar"),
 		allow("activate", "control/quux"),

client/setec/client.go

@@ -199,6 +199,19 @@ func (c Client) Put(ctx context.Context, name string, value []byte) (version api
 	})
 }
 
+// CreateVersion 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.
+//
+// Access requirement: "create-version"
+func (c Client) CreateVersion(ctx context.Context, name string, version api.SecretVersion, value []byte) error {
+	_, err := do[struct{}](ctx, c, "/api/create-version", api.CreateVersionRequest{
+		Name:    name,
+		Version: version,
+		Value:   value,
+	})
+	return err
+}
+
 // Activate changes the active version of the secret called name to version.
 //
 // Access requirement: "activate"

db/db.go

@@ -50,6 +50,9 @@ var (
 	// ErrNotFound is the error returned by DB methods when the
 	// database lacks a necessary secret or secret version.
 	ErrNotFound = errors.New("not found")
+	// ErrVersionExists indicates that an attempt was made to create a
+	// version of a secret that already exists.
+	ErrVersionExists = errors.New("version already exists")
 )
 
 // Open loads the secrets database at path, decrypting it using key.
@@ -237,7 +240,7 @@ func (db *DB) Put(caller Caller, name string, value []byte) (api.SecretVersion,
 	if strings.HasPrefix(name, configPrefix) {
 		return db.putConfigLocked(name, value)
 	}
-	return db.kv.put(name, value)
+	return db.kv.put(name, value, 0)
 }
 
 func (db *DB) putConfigLocked(name string, value []byte) (api.SecretVersion, error) {
@@ -247,6 +250,38 @@ func (db *DB) putConfigLocked(name string, value []byte) (api.SecretVersion, err
 	}
 }
 
+// CreateVersion creates the specified version of the secret called name with
+// the specified value. For a secret that does not yet exist, CreateVersion creates
+// the secret, sets the specified version to the given value and makes this the
+// secret's initial version. For a secret that  already exists, CreateVersion
+// returns an error if the specified version already has a value; otherwise, CreateVersion
+// sets the specified version to the given value and immediately activates this version.
+//
+// Access requirement: "create-version"
+func (db *DB) CreateVersion(caller Caller, name string, version api.SecretVersion, value []byte) error {
+	if name == "" {
+		return errors.New("empty secret name")
+	}
+	if err := db.checkAndLog(caller, acl.ActionCreateVersion, name, version); err != nil {
+		return err
+	}
+
+	db.mu.Lock()
+	defer db.mu.Unlock()
+	_, err := db.kv.getVersion(name, version)
+	if err == nil {
+		return ErrVersionExists
+	}
+	if !errors.Is(err, ErrNotFound) {
+		return err
+	}
+	_, err = db.kv.put(name, value, version)
+	if err != nil {
+		return err
+	}
+	return db.kv.setActive(name, version)
+}
+
 // Activate changes the active version of the secret called name to version.
 func (db *DB) Activate(caller Caller, name string, version api.SecretVersion) error {
 	if name == "" {

db/db_test.go

@@ -7,6 +7,7 @@ import (
 	"bytes"
 	"errors"
 	"io"
+	"math"
 	"os"
 	"strconv"
 	"testing"
@@ -227,6 +228,45 @@ func TestPut(t *testing.T) {
 	mustGetVersion(ver3, "test value 2")
 }
 
+func TestCreateVersion(t *testing.T) {
+	d := setectest.NewDB(t, nil)
+	id := d.Superuser
+
+	const testName = "test-secret-name"
+	mustGetVersion := func(version api.SecretVersion, want string) *api.SecretValue {
+		t.Helper()
+		got := d.MustGetVersion(id, testName, version)
+		if !bytes.Equal(got.Value, []byte(want)) {
+			t.Fatalf("Get %q version %v: got %q, want %q", testName, id, got.Value, want)
+		}
+		return got
+	}
+
+	testValue1 := []byte("test value 1")
+	testValue2 := []byte("test value 2")
+
+	// Setting first version should be allowed.
+	err := d.Actual.CreateVersion(id, testName, 1, testValue1)
+	if err != nil {
+		t.Fatalf("failed to Set first version: %s", err)
+	}
+	mustGetVersion(1, "test value 1")
+
+	// Setting a disjoint version for the first time should be allowed.
+	err = d.Actual.CreateVersion(id, testName, math.MaxInt64, testValue2)
+	if err != nil {
+		t.Fatalf("failed to Set disjoint version: %s", err)
+	}
+	mustGetVersion(math.MaxInt64, "test value 2")
+
+	// Setting a disjoint version for the second time should not be allowed.
+	err = d.Actual.CreateVersion(id, testName, math.MaxInt64, testValue2)
+	if !errors.Is(err, db.ErrVersionExists) {
+		t.Fatalf("Setting existing version should have failed with %s but returned %s", db.ErrVersionExists, err)
+	}
+	mustGetVersion(math.MaxInt64, "test value 2")
+}
+
 func TestDelete(t *testing.T) {
 	d := setectest.NewDB(t, nil)
 	id := d.Superuser

db/kv.go

@@ -320,7 +320,8 @@ func (kv *kv) getVersion(name string, version api.SecretVersion) (*api.SecretVal
 // exists, value is saved as a new inactive version. Otherwise, value
 // is saved as the initial version of the secret and immediately set
 // active. On success, returns the secret version for the new value.
-func (kv *kv) put(name string, value []byte) (api.SecretVersion, error) {
+// If an explicit version is specified, the value is saved at that version.
+func (kv *kv) put(name string, value []byte, version api.SecretVersion) (api.SecretVersion, error) {
 	s := kv.secrets[name]
 	if s == nil {
 		kv.secrets[name] = &secret{
@@ -344,7 +345,11 @@ func (kv *kv) put(name string, value []byte) (api.SecretVersion, error) {
 		return s.LatestVersion, nil
 	}
 
-	s.LatestVersion++
+	if version > s.LatestVersion {
+		s.LatestVersion = version
+	} else {
+		s.LatestVersion++
+	}
 	s.Versions[s.LatestVersion] = bsValue
 	if err := kv.save(); err != nil {
 		delete(s.Versions, s.LatestVersion)

docs/README.md

@@ -80,6 +80,10 @@ The [setec API](api.md) defines the following basic operations:
 - The `put` method creates or adds a new value to a secret. The server assigns
   and reports a version number for the value.
 
+- The `create-version` method creates a specific version of a secret, sets its
+  value and immediately activates that version. It fails if a value already exists for
+  that version.
+
 ### Current Active Versions
 
 - At any time, one version of the secret is designated as its **current active
@@ -92,6 +96,8 @@ The [setec API](api.md) defines the following basic operations:
 - 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
 

docs/api.md

@@ -33,6 +33,9 @@ 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 value.
+
 - `activate`: Denotes permission to set one one of of the available versions of
   a secret as the active one.
 
@@ -105,7 +108,7 @@ The service defines named _actions_ that are subject to access control:
   {"Name":"example","Versions":[1,2,3],"ActiveVersion":2}
   ```
 
-- `/api/put`: Add a a new value for a secret.
+- `/api/put`: Add a new value for a secret.
 
   **Requires:** `put` permission for the specified name.
 
@@ -127,6 +130,19 @@ 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.
+
+  **Requires:** `create-version` permission for the specified name.
+
+  **Request:** `api.CreateVersionRequest`
+
+  **Example request:**
+  ```json
+  {"Name":"example","Version": 2025, "Value":"YSBuZXcgYmVnaW5uaW5n"}
+  ```
+
+  **Response:** `null`
+
 - `/api/activate`: Set the active version of an existing secret.
 
   **Requires:** `activate` permission for the specified name.

server/server.go

@@ -95,6 +95,7 @@ type Server struct {
 	countCallForbidden     *metrics.LabelMap // :: method name → count
 	countCallNotFound      *metrics.LabelMap // :: method name → count
 	countCallInternalError *metrics.LabelMap // :: method name → count
+	countCallAlreadySet    *metrics.LabelMap // :: method name → count
 }
 
 //go:embed templates
@@ -133,6 +134,7 @@ func New(ctx context.Context, cfg Config) (*Server, error) {
 		countCallForbidden:     &metrics.LabelMap{Label: "method"},
 		countCallNotFound:      &metrics.LabelMap{Label: "method"},
 		countCallInternalError: &metrics.LabelMap{Label: "method"},
+		countCallAlreadySet:    &metrics.LabelMap{Label: "method"},
 	}
 
 	if cfg.BackupBucket != "" {
@@ -151,6 +153,7 @@ func New(ctx context.Context, cfg Config) (*Server, error) {
 	cfg.Mux.HandleFunc("/api/get", ret.get)
 	cfg.Mux.HandleFunc("/api/info", ret.info)
 	cfg.Mux.HandleFunc("/api/put", ret.put)
+	cfg.Mux.HandleFunc("/api/create-version", ret.createVersion)
 	cfg.Mux.HandleFunc("/api/activate", ret.activate)
 	cfg.Mux.HandleFunc("/api/delete", ret.deleteSecret)
 	cfg.Mux.HandleFunc("/api/delete-version", ret.deleteVersion)
@@ -251,6 +254,15 @@ func (s *Server) put(w http.ResponseWriter, r *http.Request) {
 	})
 }
 
+func (s *Server) createVersion(w http.ResponseWriter, r *http.Request) {
+	serveJSON(s, w, r, func(req api.CreateVersionRequest, id db.Caller) (struct{}, error) {
+		if err := s.db.CreateVersion(id, req.Name, req.Version, req.Value); err != nil {
+			return struct{}{}, err
+		}
+		return struct{}{}, nil
+	})
+}
+
 func (s *Server) activate(w http.ResponseWriter, r *http.Request) {
 	serveJSON(s, w, r, func(req api.ActivateRequest, id db.Caller) (struct{}, error) {
 		if err := s.db.Activate(id, req.Name, req.Version); err != nil {
@@ -376,6 +388,9 @@ func serveJSON[REQ any, RESP any](s *Server, w http.ResponseWriter, r *http.Requ
 		w.Header().Set("Content-Type", "application/json")
 		w.WriteHeader(http.StatusNotModified)
 		return
+	} else if errors.Is(err, db.ErrVersionExists) {
+		s.countCallAlreadySet.Add(apiMethod, 1)
+		http.Error(w, "version already set", http.StatusPreconditionFailed)
 	} else if err != nil {
 		s.countCallInternalError.Add(apiMethod, 1)
 		http.Error(w, "internal error", http.StatusInternalServerError)

setectest/dbtest.go

@@ -30,7 +30,7 @@ func superuser() db.Caller {
 		Permissions: acl.Rules{
 			acl.Rule{
 				Action: []acl.Action{
-					acl.ActionGet, acl.ActionInfo, acl.ActionPut, acl.ActionActivate, acl.ActionDelete,
+					acl.ActionGet, acl.ActionInfo, acl.ActionPut, acl.ActionCreateVersion, acl.ActionActivate, acl.ActionDelete,
 				},
 				Secret: []acl.Secret{"*"},
 			},