Cover released vault checkout and credential preconditions

Author: rgarcia

README.md

@@ -128,7 +128,7 @@ Commands with JSON output support:
 - **Proxies**: `create`, `list`, `get`, `update`, `check`
 - **API Keys**: `create`, `list`, `get`, `update`, `rotate`
 - **Auth Connections**: `timeline`
-- **Vaults**: `create`, `list`, `get`, `credentials create/update`, `items list/get/events/invoke` (including `collect` and `fill`), `wallets create/payment-methods`, `cards create/update` (display-safe public fields only)
+- **Vaults**: `create`, `list`, `get`, `credentials create/update`, `items list/get/events/invoke` (including `collect`, `fill`, and `prepare_checkout`), `wallets create/payment-methods`, `cards create/update` (display-safe public fields only)
 - **Projects**: `update`
 - **Org**: `limits get/set`
 - **Apps**: `list`, `history`
@@ -300,7 +300,9 @@ with a spec such as `{"fields":{"password":{"value":"replacement"}}}`. Keep actu
 secrets in protected files or stdin, never shell arguments. Omission preserves values;
 null or an empty string clears supported fields, including required text/email/password fields (returning them to pending collection). The form still requires nonempty required inputs. Field definitions cannot change. Stale versions fail,
 without retries. `items invoke <vault> <key> collect` reopens the full form without
-clearing values; compare versions to observe edits to already-ready items.
+clearing values; compare versions to observe edits to already-ready items. When an update
+is bound to an earlier read, also pass `--expected-item-id <id>` to reject a replacement
+item at the same key. Neither precondition is refreshed automatically.
 
 Do not use credential items to store, collect, or fill credit card data, including card numbers (PANs), security codes (CVV/CVC), or expiration dates. Use wallet and card item types for credit cards and payment checkout instead.
 
@@ -515,7 +517,7 @@ card spec. Otherwise, the cardholder selects a card at approval. A reusable card
 #### Invoking item operations
 
 `items get` displays every `available_operations` entry's type and description, plus
-an `items invoke` command retaining the selected project (replace `<json>` for fill).
+an `items invoke` command retaining the selected project (replace `<json>` for fill or prepare_checkout).
 Read the description and follow its approval requirements before invoking. Required user actions
 (OAuth, enrollment, MFA, spend approval) appear separately; they are not operations to invoke
 through this endpoint.
@@ -527,14 +529,37 @@ actions in `recovery_required`, even if a stale action or operation was returned
 
 `authorize` sends `{"type":"authorize"}` without `--params` and returns the updated item,
 possibly with a required user action. `collect` is also parameterless and returns a credential
-collection URL. `--open` is supported for authorize and collect.
-The [API spec](https://api.onkernel.com/spec.yaml) also accepts `fill`, with its inputs in
+collection URL. `--open` is supported for authorize, collect, and prepare_checkout.
+The [API spec](https://api.onkernel.com/spec.yaml) also accepts `fill` and `prepare_checkout`, with their inputs in
 `--params` or `--spec-file <path|->` (mutually exclusive, maximum 128 KiB). The positional
 operation supplies `type`; including `type` in either input is rejected.
 Parameters must be a JSON object without unknown or duplicate properties. There is no
 operation `--spec` flag; wallet/card `--spec` flags remain unchanged. New parameterless
 operations can still be invoked by name when advertised.
 
+##### Prepare an AgentCard checkout
+
+For an unused AgentCard card, invoke `prepare_checkout` only when advertised:
+
+```bash
+kernel vaults items invoke user-123 order-1 prepare_checkout --params '{"checkout":{"browser_id":"browser-session-id","merchant_origin":"https://shop.example","environment":"production"}}' --open
+kernel vaults items get user-123 order-1 --wait 60 -o json
+```
+
+`--spec-file <path|->` accepts the same JSON. `browser_id` is the active session with
+this vault attached. `merchant_origin` is the canonical HTTPS origin of the top-level
+merchant document, not the Square iframe; HTTP localhost is allowed for tests.
+`environment` is `production` or `sandbox` and refers to Square, not the credential mode.
+
+Keep the approval page open. Poll until the item's status is `ready_to_submit`, then
+submit native Pay before `state.preparation.expires_at`. Readiness lasts at most 30
+seconds, and polling does not extend it. The CLI displays the preparation ID, status,
+browser, origin, environment, approval URL, and submission deadline.
+
+Each preparation is single-use, including after failure or expiry. A preparation
+marked `consumed` has been claimed; it does not prove the payment settled or succeeded.
+Do not automatically retry or switch checkout paths after an uncertain result.
+
 ##### Fill browser fields
 
 Fill supports credential items and ready Link cards when advertised by the API, not AgentCard.

cmd/vaults.go

@@ -202,13 +202,16 @@ func (c VaultsCmd) SaveCard(ctx context.Context, vault, key string, spec kernel.
 	return c.showItem(item, output, false)
 }
 
-func (c VaultsCmd) Invoke(ctx context.Context, vault, key, operation string, params *vaultFillParams, output string, open bool) error {
+func (c VaultsCmd) Invoke(ctx context.Context, vault, key, operation string, params *vaultOperationParams, output string, open bool) error {
 	if strings.TrimSpace(operation) == "" {
 		return fmt.Errorf("operation must not be empty")
 	}
-	if operation == "fill" && (params == nil || open) {
+	if operation == "fill" && (params == nil || params.Fill == nil || open) {
 		return fmt.Errorf("fill requires --params and does not support --open")
 	}
+	if operation == "prepare_checkout" && (params == nil || params.Checkout == nil) {
+		return fmt.Errorf("prepare_checkout requires checkout parameters")
+	}
 	item, err := c.vaults.Items.Get(ctx, key, kernel.VaultItemGetParams{IDOrName: vault}, option.WithMaxRetries(0))
 	if err != nil {
 		if operation == "fill" {
@@ -240,13 +243,18 @@ func (c VaultsCmd) Invoke(ctx context.Context, vault, key, operation string, par
 		return fmt.Errorf("operation %q is not advertised in available_operations; inspect the item", operation)
 	}
 	if operation == "fill" {
-		if err := validateVaultFillItem(params, item); err != nil {
+		if err := validateVaultFillItem(params.Fill, item); err != nil {
 			return err
 		}
-		return c.fill(ctx, vault, key, params, output)
+		return c.fill(ctx, vault, key, params.Fill, output)
 	}
 	request := kernel.VaultItemPerformOperationParams{IDOrName: vault}
-	if operation == "collect" {
+	if operation == "prepare_checkout" {
+		if item.Type != "card" || item.Spec.Provider != "agentcard" {
+			return fmt.Errorf("prepare_checkout requires an AgentCard card")
+		}
+		request.OfPrepareCheckout = &kernel.PrepareCheckoutVaultItemOperationRequestParam{Type: "prepare_checkout", Checkout: *params.Checkout}
+	} else if operation == "collect" {
 		request.OfCollect = &kernel.CollectVaultItemOperationRequestParam{Type: "collect"}
 	} else {
 		// Preserve support for other advertised parameterless operations.

cmd/vaults_commands.go

@@ -167,7 +167,12 @@ Fill is available for credential items and ready Link cards when advertised, not
 Fill never submits forms. completed means fields were filled, not website acceptance.
 failed may leave partial writes; unknown quarantines the browser. Never automatically
 retry or fall back to aliases. Requests are not automatically retried.
-Only collect/authorize may use --open. Fill returns value-free per-field outcomes;
+prepare_checkout requires checkout.browser_id, checkout.merchant_origin (canonical HTTPS
+origin of the top-level merchant page), and checkout.environment (production or sandbox).
+Use only when advertised for an AgentCard card. Keep the returned approval page open,
+poll until ready_to_submit, then submit native Pay before preparation.expires_at.
+Preparations are single-use, including after failure or expiry; never retry automatically.
+collect/authorize/prepare_checkout may use --open. Fill returns value-free per-field outcomes;
 completed exits 0, failed/unknown exit nonzero with valid JSON retained on stdout in -o json.`,
 		Example: `  kernel vaults items invoke user-vault login collect
   kernel vaults items invoke user-vault login fill --spec-file - <<'JSON'
@@ -179,8 +184,8 @@ JSON
 			raw, _ := cmd.Flags().GetString("params")
 			paramsSet := cmd.Flags().Changed("params")
 			if cmd.Flags().Changed("spec-file") {
-				if args[2] != "fill" {
-					return fmt.Errorf("--spec-file is only supported for fill")
+				if args[2] != "fill" && args[2] != "prepare_checkout" {
+					return fmt.Errorf("--spec-file is only supported for fill and prepare_checkout")
 				}
 				data, err := readVaultSpecFile(cmd)
 				if err != nil {
@@ -194,8 +199,8 @@ JSON
 			}
 			return getVaultsHandler(cmd).Invoke(cmd.Context(), args[0], args[1], args[2], params, vaultOutput(cmd), open)
 		}}
-	invoke.Flags().String("params", "", "Fill parameters JSON (maximum 128 KiB); omit type and credential values")
-	invoke.Flags().String("spec-file", "", "Fill parameters JSON file (use '-' for stdin; maximum 128 KiB)")
+	invoke.Flags().String("params", "", "Fill or prepare_checkout parameters JSON (maximum 128 KiB); omit type and credential values")
+	invoke.Flags().String("spec-file", "", "Fill or prepare_checkout parameters JSON file (use '-' for stdin; maximum 128 KiB)")
 	invoke.MarkFlagsMutuallyExclusive("params", "spec-file")
 	invoke.Flags().Bool("open", false, "Open a returned HTTPS action URL in your browser")
 	addVaultJSONOutputFlag(invoke)

cmd/vaults_credentials.go

@@ -6,6 +6,7 @@ import (
 	"fmt"
 	"io"
 	"os"
+	"strings"
 
 	kernel "github.com/kernel/kernel-go-sdk"
 	"github.com/kernel/kernel-go-sdk/option"
@@ -49,13 +50,18 @@ func newVaultCredentialsCommand() *cobra.Command {
 				}
 				version, _ := cmd.Flags().GetInt64("version")
 				open, _ := cmd.Flags().GetBool("open")
-				return getVaultsHandler(cmd).saveCredential(cmd.Context(), args[0], args[1], data, update, version, vaultOutput(cmd), open)
+				expectedID, _ := cmd.Flags().GetString("expected-item-id")
+				if cmd.Flags().Changed("expected-item-id") && strings.TrimSpace(expectedID) == "" {
+					return fmt.Errorf("--expected-item-id must not be empty")
+				}
+				return getVaultsHandler(cmd).saveCredential(cmd.Context(), args[0], args[1], data, update, version, expectedID, vaultOutput(cmd), open)
 			},
 		}
 		if update {
 			cmd.Long += "\nUpdate preserves omitted fields, replaces nonempty string values, and clears supported values with null or an empty string. Clearing a required text/email/password field returns pending_collection; form submissions still require a nonempty value.\nField definitions are immutable. Do not automatically retry version conflicts."
 			cmd.Flags().Int64("version", 0, "Expected version from items get (required; never auto-refreshed)")
 			_ = cmd.MarkFlagRequired("version")
+			cmd.Flags().String("expected-item-id", "", "Immutable item ID from the original read; reject an update if the key now refers to a replacement item")
 			cmd.Example = "  kernel vaults credentials update user-vault login --version 2 --spec-file changes.json"
 		} else {
 			cmd.Example = `  kernel vaults credentials create user-vault login --spec-file - <<'JSON'
@@ -97,7 +103,7 @@ func readVaultSpecFile(cmd *cobra.Command) ([]byte, error) {
 	return data, nil
 }
 
-func (c VaultsCmd) saveCredential(ctx context.Context, vault, key string, data []byte, update bool, version int64, output string, open bool) error {
+func (c VaultsCmd) saveCredential(ctx context.Context, vault, key string, data []byte, update bool, version int64, expectedID, output string, open bool) error {
 	var item *kernel.VaultItemUnion
 	var err error
 	if update {
@@ -108,7 +114,11 @@ func (c VaultsCmd) saveCredential(ctx context.Context, vault, key string, data [
 		if json.Unmarshal(data, &spec) != nil {
 			return fmt.Errorf("invalid credential update spec")
 		}
-		item, err = c.vaults.Items.Update(ctx, key, kernel.VaultItemUpdateParams{IDOrName: vault, OfCredentialVaultItemUpdateRequest: &kernel.CredentialVaultItemUpdateRequestParam{Type: "credential", Version: version, Spec: spec}}, option.WithMaxRetries(0))
+		request := kernel.CredentialVaultItemUpdateRequestParam{Type: "credential", Version: version, Spec: spec}
+		if expectedID != "" {
+			request.ExpectedItemID = kernel.String(expectedID)
+		}
+		item, err = c.vaults.Items.Update(ctx, key, kernel.VaultItemUpdateParams{IDOrName: vault, OfCredentialVaultItemUpdateRequest: &request}, option.WithMaxRetries(0))
 	} else {
 		var spec kernel.CredentialVaultItemSpecInputParam
 		if json.Unmarshal(data, &spec) != nil || len(spec.Fields) == 0 {

cmd/vaults_credentials_test.go

@@ -38,6 +38,7 @@ func TestCredentialCreateAndUpdate(t *testing.T) {
 				if update {
 					assert.Equal(t, "PATCH", r.Method)
 					assert.JSONEq(t, `2`, string(body["version"]))
+					assert.JSONEq(t, `"credential-1"`, string(body["expected_item_id"]))
 					assert.JSONEq(t, `{"fields":{"password":{"value":null}}}`, string(body["spec"]))
 				} else {
 					assert.Equal(t, "PUT", r.Method)
@@ -50,7 +51,7 @@ func TestCredentialCreateAndUpdate(t *testing.T) {
 			if update {
 				args[2] = "update"
 				args[6] = credentialSpecFile(t, `{"fields":{"password":{"value":null}}}`)
-				args = append(args, "--version", "2")
+				args = append(args, "--version", "2", "--expected-item-id", "credential-1")
 			}
 			out, _, err := executeVaultCommand(t, client, args...)
 			require.NoError(t, err)
@@ -74,7 +75,7 @@ func TestCredentialWriteErrorsAreRedactedAndNotRetried(t *testing.T) {
 				io.WriteString(w, `{"message":"secret-echo"}`)
 			})
 			c := VaultsCmd{vaults: &client.Vaults}
-			err := c.saveCredential(context.Background(), "user", "login", []byte(`{"fields":{"password":{"type":"password","value":"secret-echo"}}}`), false, 0, "json", false)
+			err := c.saveCredential(context.Background(), "user", "login", []byte(`{"fields":{"password":{"type":"password","value":"secret-echo"}}}`), false, 0, "", "json", false)
 			require.Error(t, err)
 			assert.NotContains(t, err.Error(), "secret-echo")
 			assert.Equal(t, 1, calls)

cmd/vaults_operation_params.go

@@ -12,6 +12,11 @@ import (
 	kernel "github.com/kernel/kernel-go-sdk"
 )
 
+type vaultOperationParams struct {
+	Fill     *vaultFillParams
+	Checkout *kernel.VaultCheckoutContextParam
+}
+
 type vaultFillParams struct {
 	BrowserID string           `json:"browser_id"`
 	PageURL   string           `json:"page_url,omitempty"`
@@ -67,25 +72,43 @@ func vaultParamsObject(raw, allowed string) (map[string]json.RawMessage, error)
 	return object, nil
 }
 
-func parseVaultOperationParams(operation, raw string, paramsSet, openSet bool) (*vaultFillParams, error) {
+func parseVaultOperationParams(operation, raw string, paramsSet, openSet bool) (*vaultOperationParams, error) {
 	if strings.TrimSpace(operation) == "" {
 		return nil, fmt.Errorf("operation must not be empty")
 	}
-	if openSet && operation != "authorize" && operation != "collect" {
-		return nil, fmt.Errorf("--open is only supported for authorize and collect")
+	if openSet && operation != "authorize" && operation != "collect" && operation != "prepare_checkout" {
+		return nil, fmt.Errorf("--open is only supported for authorize, collect, and prepare_checkout")
+	}
+	if len(raw) > 128*1024 {
+		return nil, fmt.Errorf("operation parameters exceed 128 KiB")
+	}
+	if operation == "prepare_checkout" {
+		if !paramsSet {
+			return nil, fmt.Errorf("prepare_checkout requires --params or --spec-file with checkout")
+		}
+		checkout, err := parseVaultCheckoutParams(raw)
+		if err != nil {
+			return nil, err
+		}
+		return &vaultOperationParams{Checkout: checkout}, nil
 	}
 	if operation != "fill" {
 		if paramsSet {
-			return nil, fmt.Errorf("--params is only supported for fill; authorize takes no parameters")
+			return nil, fmt.Errorf("--params is only supported for fill and prepare_checkout; authorize takes no parameters")
 		}
 		return nil, nil
 	}
 	if !paramsSet {
 		return nil, fmt.Errorf("fill requires --params or --spec-file with browser_id and fields")
 	}
-	if len(raw) > 128*1024 {
-		return nil, fmt.Errorf("fill parameters exceed 128 KiB")
+	fill, err := parseVaultFillParams(raw)
+	if err != nil {
+		return nil, err
 	}
+	return &vaultOperationParams{Fill: fill}, nil
+}
+
+func parseVaultFillParams(raw string) (*vaultFillParams, error) {
 	object, err := vaultParamsObject(raw, "browser_id page_url fields timeout_ms")
 	if err != nil {
 		return nil, err