fix(secrets): let a workspace secret change its metadata without resending the value

Restoring redaction cost more than removing it. The only way to flip a secret
back to redacted was to re-send the plaintext, because the write required a
value and omitting it fell into an interactive prompt that cannot run in CI.
A workspace secret can now change its description or visibility on its own; the
stored value is never re-encrypted or rewritten, a write that names no existing
secret answers not-found rather than creating one, and a personal secret still
requires a value because it has no other writable field.

The path parameter was also one shared schema across the write and the delete,
so a single description had to cover both and the delete documented an argument
that could create and replace. Split, mirroring the credentials pair.

The metadata write is a new update against the credentials table, so its scope
is asserted by composition and by condition count: an unscoped update would let
one workspace flip another workspace's identically-named secret out of
redaction, and the cache invalidation would then carry that flag into the other
workspace's runtime catalog.

Author: waleedlatif1

apps/sim/app/api/v2/secrets/[name]/route.test.ts

@@ -206,6 +206,59 @@ describe('/api/v2/secrets/[name]', () => {
     expect(response.status).toBe(200)
   })
 
+  it('sends a value-less workspace write through as a metadata-only update at 200', async () => {
+    mocks.set.mockResolvedValueOnce({ secret, userId: 'user-1', created: false })
+
+    const response = await PUT(
+      request('PUT', { workspaceId: WORKSPACE_ID, scope: 'workspace', unredacted: false }),
+      context
+    )
+
+    expect(response.status).toBe(200)
+    expect(mocks.set).toHaveBeenCalledWith({
+      principal: PRINCIPAL,
+      input: {
+        workspaceId: WORKSPACE_ID,
+        name: SECRET_NAME,
+        scope: 'workspace',
+        unredacted: false,
+      },
+      request: expect.anything(),
+    })
+    expect(mocks.set.mock.calls[0][0].input).not.toHaveProperty('value')
+  })
+
+  it('answers 404 rather than creating when a metadata-only write names no secret', async () => {
+    mocks.set.mockRejectedValueOnce(new OrchestrationError('not_found', 'Secret not found'))
+
+    const response = await PUT(
+      request('PUT', { workspaceId: WORKSPACE_ID, scope: 'workspace', unredacted: true }),
+      context
+    )
+
+    expect(response.status).toBe(404)
+  })
+
+  it('rejects a value-less personal write, which has no metadata field to update', async () => {
+    const response = await PUT(
+      request('PUT', { workspaceId: WORKSPACE_ID, scope: 'personal' }),
+      context
+    )
+
+    expect(response.status).toBe(400)
+    expect(mocks.set).not.toHaveBeenCalled()
+  })
+
+  it('rejects a workspace write carrying nothing to write', async () => {
+    const response = await PUT(
+      request('PUT', { workspaceId: WORKSPACE_ID, scope: 'workspace' }),
+      context
+    )
+
+    expect(response.status).toBe(400)
+    expect(mocks.set).not.toHaveBeenCalled()
+  })
+
   it('deletes a secret through the semantic delete operation', async () => {
     const response = await DELETE(request('DELETE'), context)
 

apps/sim/app/api/v2/secrets/[name]/route.ts

@@ -12,7 +12,10 @@ import { toV2Secret } from '@/app/api/v2/secrets/utils'
 export const dynamic = 'force-dynamic'
 export const revalidate = 0
 
-/** PUT /api/v2/secrets/[name] — Create or replace a write-only secret value. */
+/**
+ * PUT /api/v2/secrets/[name] — Create or replace a write-only secret value, or
+ * update a workspace secret's metadata alone when the body carries no value.
+ */
 export const PUT = defineV2JsonRoute({
   contract: v2SetSecretContract,
   operation: secretOperations.set,

apps/sim/lib/api/contracts/v2/openapi/resources.ts

@@ -1368,11 +1368,14 @@ const declaredRoutes = [
     resourceOperation('Secrets', {
       operationId: 'setSecret',
       summary: 'Set Secret',
-      description: `Create or replace a workspace or caller-owned personal secret. The value is encrypted at rest, is write-only, and is never included in the response. ${WORKSPACE_API_KEY_DENIED}`,
+      description: `Create or replace a workspace or caller-owned personal secret. The value is encrypted at rest, is write-only, and is never included in the response. Omit \`value\` on a workspace secret to update \`description\` and \`unredacted\` alone: the stored value is left untouched and is never re-encrypted, and because a metadata-only write cannot create a secret it answers \`404\` when the named secret does not exist. A personal secret always requires \`value\`, having no other writable field. ${WORKSPACE_API_KEY_DENIED}`,
       errors: RESOURCE_ERRORS,
       success: {
         byStatus: {
-          200: { description: 'The existing secret value was replaced.' },
+          200: {
+            description:
+              'The existing secret value was replaced, or its metadata was updated in place.',
+          },
           201: { description: 'The secret was created.' },
         },
       },
@@ -1389,13 +1392,18 @@ const declaredRoutes = [
         v2SetSecretContract.body,
         'SetSecretRequest',
         'Set secret request',
-        'Ownership scope and write-only value for the secret.',
+        'Ownership scope and write-only value for the secret. A workspace secret may instead send description or unredacted alone, without a value.',
         [
           {
             workspaceId: WORKSPACE_ID,
             scope: SECRET_EXAMPLE.scope,
             value: 'YOUR_SECRET_VALUE',
           },
+          {
+            workspaceId: WORKSPACE_ID,
+            scope: 'workspace',
+            unredacted: false,
+          },
         ]
       ),
       response: documentedSchema(

apps/sim/lib/api/contracts/v2/secrets.test.ts

@@ -3,9 +3,11 @@
  */
 import { describe, expect, it } from 'vitest'
 import {
+  v2DeleteSecretContract,
   v2SecretSchema,
   v2SecretWithValueSchema,
   v2SetSecretBodySchema,
+  v2SetSecretContract,
 } from '@/lib/api/contracts/v2/secrets'
 
 const secret = {
@@ -70,3 +72,95 @@ describe('v2SecretWithValueSchema value', () => {
     ).toBe(true)
   })
 })
+
+/** Reads the `name` field description off a contract's path-parameter schema. */
+function nameDescription(params: unknown): string | undefined {
+  const shape = (params as { shape: Record<string, { description?: string }> }).shape
+  return shape.name.description
+}
+
+describe('secret path-parameter descriptions', () => {
+  it('does not offer writes on the delete path parameter', () => {
+    const description = nameDescription(v2DeleteSecretContract.params)
+
+    expect(description).toBe('Secret to delete.')
+    expect(description).not.toMatch(/create|replace/i)
+  })
+
+  it('does not offer deletion on the set path parameter', () => {
+    expect(nameDescription(v2SetSecretContract.params)).not.toMatch(/delete/i)
+  })
+
+  it('gives the two operations distinct path-parameter prose', () => {
+    expect(nameDescription(v2SetSecretContract.params)).not.toBe(
+      nameDescription(v2DeleteSecretContract.params)
+    )
+  })
+})
+
+describe('v2SetSecretBodySchema metadata-only write', () => {
+  it('accepts a workspace body carrying only unredacted, so restoring redaction costs no value', () => {
+    const parsed = v2SetSecretBodySchema.safeParse({
+      workspaceId: 'workspace-1',
+      scope: 'workspace',
+      unredacted: false,
+    })
+
+    expect(parsed.success).toBe(true)
+    if (parsed.success) expect(parsed.data.value).toBeUndefined()
+  })
+
+  it('accepts a workspace body carrying only a description', () => {
+    expect(
+      v2SetSecretBodySchema.safeParse({
+        workspaceId: 'workspace-1',
+        scope: 'workspace',
+        description: 'Prod billing key',
+      }).success
+    ).toBe(true)
+  })
+
+  it('rejects a workspace body with nothing to write rather than resolving to an empty update', () => {
+    const parsed = v2SetSecretBodySchema.safeParse({
+      workspaceId: 'workspace-1',
+      scope: 'workspace',
+    })
+
+    expect(parsed.success).toBe(false)
+    if (!parsed.success) {
+      expect(parsed.error.issues).toEqual([
+        expect.objectContaining({
+          path: ['value'],
+          message: 'value, description, or unredacted is required',
+        }),
+      ])
+    }
+  })
+
+  it('still requires a value for a personal secret, which has no metadata field to write', () => {
+    const parsed = v2SetSecretBodySchema.safeParse({
+      workspaceId: 'workspace-1',
+      scope: 'personal',
+    })
+
+    expect(parsed.success).toBe(false)
+    if (!parsed.success) {
+      expect(parsed.error.issues).toEqual([
+        expect.objectContaining({
+          path: ['value'],
+          message: 'value is required for a personal secret',
+        }),
+      ])
+    }
+  })
+
+  it('keeps rejecting an empty value, which is a write and not an omission', () => {
+    expect(
+      v2SetSecretBodySchema.safeParse({
+        workspaceId: 'workspace-1',
+        scope: 'workspace',
+        value: '',
+      }).success
+    ).toBe(false)
+  })
+})

apps/sim/lib/api/contracts/v2/secrets.ts

@@ -104,10 +104,22 @@ export const v2ListSecretsQuerySchema = z
   .strict()
 export type V2ListSecretsQuery = z.output<typeof v2ListSecretsQuerySchema>
 
-export const v2SecretParamsSchema = z.object({
-  name: v2SecretNameSchema.describe('Secret to create, replace, or delete.'),
+/**
+ * The secret a path addresses, named for what the route does to it.
+ *
+ * `PUT` and `DELETE` sit on the same path but are not the same operation, and the
+ * OpenAPI document already publishes them as two components (`SetSecretParams`,
+ * `DeleteSecretParams`). One shared `describe()` forced both to read "create,
+ * replace, or delete", so `sim secrets delete` documented writes the route cannot
+ * perform.
+ */
+export const v2SetSecretParamsSchema = z.object({
+  name: v2SecretNameSchema.describe('Secret to create or replace.'),
+})
+
+export const v2DeleteSecretParamsSchema = z.object({
+  name: v2SecretNameSchema.describe('Secret to delete.'),
 })
-export type V2SecretParams = z.output<typeof v2SecretParamsSchema>
 
 export const v2SetSecretBodySchema = z
   .object({
@@ -119,7 +131,10 @@ export const v2SetSecretBodySchema = z
       .string()
       .min(1, 'value is required')
       .max(65_536, 'value is too long')
-      .describe('Write-only secret value. It is never returned.')
+      .optional()
+      .describe(
+        'Write-only secret value. It is never returned. Omit it on a workspace secret to change description or unredacted alone, leaving the stored value untouched; the secret must already exist. Always required for a personal secret, which carries no other writable field.'
+      )
       .meta({ writeOnly: true }),
     description: z
       .string()
@@ -137,19 +152,49 @@ export const v2SetSecretBodySchema = z
       ),
   })
   .strict()
+  /**
+   * `value` is optional on the schema so a workspace secret's redaction policy can
+   * be flipped back without re-transmitting the plaintext — restoring redaction is
+   * the safe direction and must not cost more than leaving it off. Two refinements
+   * keep that from over-relaxing the request: a personal secret has no metadata
+   * field at all, so a value-less personal write would be a silent no-op rather
+   * than an update; and a body carrying none of the three writable fields is
+   * rejected outright instead of resolving to an empty write.
+   */
   .superRefine((data, ctx) => {
-    if (data.scope === 'personal' && data.description !== undefined) {
-      ctx.addIssue({
-        code: 'custom',
-        path: ['description'],
-        message: 'description is only supported for a workspace secret',
-      })
+    if (data.scope === 'personal') {
+      if (data.value === undefined) {
+        ctx.addIssue({
+          code: 'custom',
+          path: ['value'],
+          message: 'value is required for a personal secret',
+        })
+      }
+      if (data.description !== undefined) {
+        ctx.addIssue({
+          code: 'custom',
+          path: ['description'],
+          message: 'description is only supported for a workspace secret',
+        })
+      }
+      if (data.unredacted !== undefined) {
+        ctx.addIssue({
+          code: 'custom',
+          path: ['unredacted'],
+          message: 'unredacted is only supported for a workspace secret',
+        })
+      }
+      return
     }
-    if (data.scope === 'personal' && data.unredacted !== undefined) {
+    if (
+      data.value === undefined &&
+      data.description === undefined &&
+      data.unredacted === undefined
+    ) {
       ctx.addIssue({
         code: 'custom',
-        path: ['unredacted'],
-        message: 'unredacted is only supported for a workspace secret',
+        path: ['value'],
+        message: 'value, description, or unredacted is required',
       })
     }
   })
@@ -180,12 +225,17 @@ export const v2ListSecretsContract = defineRouteContract({
   },
 })
 
-/** Creates or replaces a secret value without returning it. */
+/**
+ * Creates or replaces a secret value without returning it, or — for a workspace
+ * secret sent without a value — updates its description and redaction policy
+ * alone. A value-less write never creates: it answers 404 when the secret is
+ * absent.
+ */
 export const v2SetSecretContract = defineRouteContract({
   method: 'PUT',
   path: '/api/v2/secrets/[name]',
   query: noInputSchema,
-  params: v2SecretParamsSchema,
+  params: v2SetSecretParamsSchema,
   body: v2SetSecretBodySchema,
   response: {
     mode: 'json',
@@ -197,7 +247,7 @@ export const v2SetSecretContract = defineRouteContract({
 export const v2DeleteSecretContract = defineRouteContract({
   method: 'DELETE',
   path: '/api/v2/secrets/[name]',
-  params: v2SecretParamsSchema,
+  params: v2DeleteSecretParamsSchema,
   query: v2DeleteSecretQuerySchema,
   response: {
     mode: 'json',