feat(cli,api,store): binding CRUD, multi-destination cred add, cred update (#24)

* feat(store): add UpdateBinding method with optional field updates

* feat(cli): add sluice binding CRUD subcommand

* feat(cli): support multiple --destination on cred add

* feat(cli): add sluice cred update for value replacement

* feat(api): add PATCH endpoints for binding and credential updates

* chore: verify acceptance criteria for binding-cli plan

* docs: document sluice binding and cred update, mark plan complete

* fix: address review findings from binding-cli plan

Squashed fixes from review phases 1 through 4 and codex iterations 1-10:
- preserve OAuth refresh_token when not supplied (CLI + API)
- sync paired allow rule when binding destination, ports, or protocols change
- add EnvVar field to BindingUpdateOpts; --env-var and --protocols on update
- reject duplicate binding add via case-insensitive UNIQUE index (migrations 000005, 000007)
- migration aborts on conflicting binding dedup so data loss is surfaced to operators
- classify API errors: 409 Conflict on duplicates, 400 only for ErrBindingValidation, 500 otherwise
- wrap validation errors (port range, destination glob, protocols, env_var) with ErrBindingValidation sentinel
- close TOCTOUs: AddBinding env_var check transactional; RemoveBindingWithRuleCleanup in one tx; UpdateBindingWithRuleSync transactional; PostApiCredentials/PatchApiCredentialsName acquire reloadMu
- CAS-protect credential rollback against concurrent writers (vault.RollbackAdd, store.RemoveCredentialMetaCAS)
- PatchApiCredentialsName and handleCredUpdate use credential_meta as authoritative type source
- updatePairedRuleTx walks both cred-add and binding-add source prefixes
- recompileEngine/rebuildResolver failures now return 500 to callers instead of WARN+success
- return 500 on rebuildResolver failures in PostApiCredentials/DeleteApiCredentialsName
- consolidated source-prefix constants into store package
- deleted dead UpdateBinding/UpdateRuleDestinationBySource/SyncPairedAllowRule code
- extracted parsePortsList helper into flagutil.go
- updated CLAUDE.md and openapi.yaml to match new behavior

* refactor(store): consolidate binding-cli migrations into 000005

The binding-cli branch added 000005, 000006, and 000007 across separate
review iterations. None have shipped to production, so they should be one
atomic schema change. The consolidated 000005 drops idx_bindings_env_var,
detects conflicting (credential, LOWER(destination)) bindings, dedups
exact duplicates with their paired allow rules, and creates the
case-insensitive unique index in a single migration.

* fix(store): use %w for wrapped error formatting (errorlint)

Author: nnemirovsky

CLAUDE.md

@@ -75,17 +75,27 @@ sluice mcp                          # start MCP gateway
 
 sluice cred add <name> [--type static|oauth] [--destination host] [--ports 443] [--header Authorization] [--template "Bearer {value}"] [--env-var OPENAI_API_KEY]
 sluice cred add <name> --type oauth --token-url <url> --destination <host> --ports 443 [--env-var OPENAI_API_KEY]
+sluice cred update <name>           # replace credential value (prompts via stdin, handles static and OAuth; OAuth refresh token is preserved if left blank)
 sluice cred list
 sluice cred remove <name>
 
+sluice binding add <credential> --destination <host> [--ports 443] [--header Authorization] [--template "Bearer {value}"] [--env-var OPENAI_API_KEY]
+sluice binding list [--credential <name>]
+sluice binding update <id> [--destination <host>] [--ports 443] [--header Authorization] [--template "Bearer {value}"] [--protocols http,grpc] [--env-var OPENAI_API_KEY]
+sluice binding remove <id>
+
 sluice cert generate                # generate CA certificate for HTTPS MITM
 sluice audit verify                 # verify audit log hash chain integrity
 ```
 
-When `--destination` is provided, `sluice cred add` also creates an allow rule and binding in the store. When `--env-var` is provided, the phantom token is injected into the agent container as that environment variable via `docker exec` (no shared volume needed). For HTTP/WebSocket upstreams, `--command` holds the URL. Env values prefixed with `vault:` are resolved from the credential vault at upstream spawn time.
+When `--destination` is provided, `sluice cred add` also creates an allow rule and binding in the store. The flag may be repeated to create multiple bindings that share the same `--ports`, `--header`, and `--template` values (use `sluice binding add` afterwards for per-destination customization). When `--env-var` is provided, the phantom token is injected into the agent container as that environment variable via `docker exec` (no shared volume needed). For HTTP/WebSocket upstreams, `--command` holds the URL. Env values prefixed with `vault:` are resolved from the credential vault at upstream spawn time.
 
 Two credential types: `static` (default) for API keys and `oauth` for OAuth access/refresh token pairs. OAuth credentials prompt for tokens via stdin (not CLI flags) to avoid shell history exposure.
 
+`sluice cred update` uses PATCH partial-update semantics for OAuth credentials. Pressing Enter at the refresh token prompt (or omitting the second line when piping via stdin) preserves the currently stored refresh token. To explicitly clear the refresh token, update the credential again with the desired empty value through the REST API (`PATCH /api/credentials/<name>` with `"refresh_token": ""`). This prevents an access-token rotation from silently destroying the stored refresh token.
+
+`sluice binding update --destination` also updates the paired auto-created allow rule (tagged `binding-add:<credential>` or `cred-add:<credential>`) so the new destination is not orphaned. If no paired rule exists (e.g. because it was manually removed), the binding destination is still updated and a warning is printed. No fallback rule is created so an operator's intentional removal is not silently reverted. `--env-var` on binding update can be used to change or clear the env var name after the initial binding was created.
+
 Runtime flags: `--mcp-base-url` sets the external URL the agent uses to reach sluice's MCP gateway (e.g. `http://sluice:3000`). This is added to `SelfBypass` so sluice does not policy-check its own MCP traffic. Defaults to deriving from `--health-addr`.
 
 ## MCP Gateway Setup

api/openapi.yaml

@@ -295,6 +295,37 @@ paths:
                 $ref: "#/components/schemas/ErrorResponse"
 
   /api/credentials/{name}:
+    patch:
+      operationId: patchApiCredentialsName
+      summary: Replace the value of an existing credential
+      tags: [credentials]
+      parameters:
+        - name: name
+          in: path
+          required: true
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CredentialUpdate"
+      responses:
+        "204":
+          description: Credential updated
+        "400":
+          description: Invalid request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "404":
+          description: Credential not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
     delete:
       operationId: deleteApiCredentialsName
       summary: Remove a credential
@@ -352,8 +383,56 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorResponse"
+        "409":
+          description: Binding already exists for this credential and destination
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
 
   /api/bindings/{id}:
+    patch:
+      operationId: patchApiBindingsId
+      summary: Update a credential binding
+      tags: [bindings]
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: integer
+            format: int64
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/BindingUpdate"
+      responses:
+        "200":
+          description: Binding updated
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Binding"
+        "400":
+          description: Invalid request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "404":
+          description: Binding not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
+        "409":
+          description: Destination collides with an existing binding for the same credential
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorResponse"
     delete:
       operationId: deleteApiBindingsId
       summary: Remove a credential binding
@@ -794,6 +873,10 @@ components:
 
     CreateBindingRequest:
       type: object
+      description: |
+        Creates a binding between a credential and a destination. The server
+        rejects duplicates: a binding on the same (credential, destination)
+        pair may only exist once. Repeated POSTs return 409 Conflict.
       required: [destination, credential]
       properties:
         destination:
@@ -816,6 +899,66 @@ components:
           type: string
           description: Environment variable name for phantom token injection
 
+    BindingUpdate:
+      type: object
+      description: |
+        Partial update for a binding. At least one field must be set in the
+        request body, otherwise the server returns 400 Bad Request (matching
+        the CLI). Only fields that are present are modified. Setting
+        `destination` to a non-empty value also updates the paired
+        auto-created allow rule (tagged with `binding-add:<credential>` or
+        `cred-add:<credential>`) so the new destination is not orphaned. If
+        the paired rule has been removed manually, the binding destination
+        is still updated and a warning is logged (no fallback rule is
+        created). Passing an empty array for `ports` or `protocols` clears
+        them. Passing an empty string for `header`, `template`, or `env_var`
+        clears the field. Updating `destination` to a value that collides
+        with another binding on the same credential returns 409 Conflict.
+      properties:
+        destination:
+          type: string
+        ports:
+          type: array
+          items:
+            type: integer
+        header:
+          type: string
+        template:
+          type: string
+        protocols:
+          type: array
+          items:
+            type: string
+        env_var:
+          type: string
+          description: Environment variable name for phantom token injection
+
+    CredentialUpdate:
+      type: object
+      description: |
+        New value for an existing credential. For static credentials, set
+        `value`. For OAuth credentials, set `access_token` and optionally
+        `refresh_token`. The existing `token_url` is preserved.
+
+        PATCH semantics: omitting `refresh_token` for an OAuth credential
+        preserves the currently stored refresh token. To explicitly clear
+        the refresh token, send an empty string (`"refresh_token": ""`).
+        This prevents clients that rotate only the access token from
+        silently destroying the stored refresh token.
+      properties:
+        value:
+          type: string
+          description: New secret value (for static credentials)
+        access_token:
+          type: string
+          description: New OAuth access token (for oauth credentials)
+        refresh_token:
+          type: string
+          description: |
+            New OAuth refresh token (for oauth credentials). Omit to
+            preserve the existing refresh token. Send an empty string to
+            clear it.
+
     MCPUpstream:
       type: object
       required: [id, name, command]