fix(secrets): apply the rebinding rule to shell, and say when a run's log is gone

Review round 3, plus the docs that were left claiming the old behavior.

- shell.ts: a script that writes a configured name (API_KEY=local, export/local/
  readonly, read, for, unset) expands its own value from that point on, not the
  mounted secret, so recording it claimed a use that never happened. Every mention
  of the name must now be a `$NAME` / `${NAME}` expansion, matching the allowlist
  shape the Python detector already uses. Applied per name rather than per file:
  JavaScript and Python shadow one object holding every secret, whereas rebinding
  one shell variable says nothing about the rest.

- The usage trail deliberately outlives execution logs, so a row routinely names a
  run whose log has been pruned. The read now left-joins workflow_execution_logs on
  its unique execution_id and reports availability, and the panel renders the chip
  disabled with the platform tooltip instead of linking into an empty Logs view.
  Three states: no run to link, a run whose log is gone, and a live link.

- Docs said a direct environmentVariables/$KEY read does not activate masking,
  which this branch changes. Corrected in credentials.mdx, function.mdx and the
  logging FAQ, and the recognition limits are now written down: runtime-built
  names, reassigned bindings, and reads that cannot be told apart from text.
  Added a "See usage" section covering who can see it and why an empty trail
  means "nothing recognized" rather than "never used".

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: icecrasher321

apps/docs/content/docs/en/logs-debugging/logging.mdx

@@ -94,7 +94,7 @@ import { FAQ } from '@/components/ui/faq'
 <FAQ items={[
   { question: "How long are run logs retained?", answer: "Free plans retain logs for 7 days — after that, logs are archived to cloud storage and deleted from the database. Pro, Team, and Enterprise plans retain logs indefinitely with no automatic cleanup." },
   { question: "What data is captured in each run log?", answer: "Each log entry includes the run ID, workflow ID, trigger type, start and end timestamps, total duration in milliseconds, cost breakdown (total cost, token counts, and per-model breakdowns), run data with trace spans, final output, and any associated files. The log details sidebar lets you inspect block-level inputs and outputs." },
-  { question: "Are saved secrets visible in logs?", answer: "When a value saved under Secrets is successfully substituted through {{KEY}}, exact, case-sensitive occurrences are masked throughout the log-facing copy, including the live block-log display, Logs Overview input and output, Trace, log-read APIs, and the Logs block's Get Run Details output. This is not a general redactor: hardcoded or directly read values do not activate masking by themselves, and encoded, hashed, or transformed values are not matched. Functional execution responses, streams, and callbacks remain unchanged. See Execution log protection under Secrets for details." },
+  { question: "Are saved secrets visible in logs?", answer: "When a value saved under Secrets is successfully substituted through {{KEY}}, exact, case-sensitive occurrences are masked throughout the log-facing copy, including the live block-log display, Logs Overview input and output, Trace, log-read APIs, and the Logs block's Get Run Details output. Direct reads such as environmentVariables['KEY'] or shell $KEY also activate masking when Sim can recognize the read in the code beforehand; a name built at runtime, a reassigned binding, or a hardcoded literal is not recognized. This is not a general redactor: encoded, hashed, or transformed values are not matched. Functional execution responses, streams, and callbacks remain unchanged. See Execution log protection under Secrets for details." },
   { question: "What is a workflow snapshot?", answer: "A frozen copy of the workflow's structure (blocks, connections, and configuration) captured at run time, so you can see the exact state behind a particular run — useful for debugging workflows that have been modified since." },
   { question: "Can I access logs programmatically?", answer: "Yes. The External API provides endpoints to query logs with filtering by workflow, time range, trigger type, duration, cost, and model. You can also set up webhook, email, or Slack notifications for real-time alerts when runs complete." },
   { question: "What does Live mode do on the Logs page?", answer: "It refreshes the Logs page in real time so new entries appear as they are recorded — useful during deployments or when monitoring active workflows." },

apps/docs/content/docs/en/platform/credentials.mdx

@@ -71,8 +71,18 @@ When a saved secret is successfully substituted through a `{{KEY}}` reference, S
 
 Secret resolution and functional workflow behavior are unchanged: blocks, tools, and downstream steps receive the real runtime value. Stored functional execution data, workflow execution responses, streams, callbacks, block state, and snapshots are not rewritten. Log-facing views and read APIs receive a separate protected copy, so the Logs Overview **Workflow Input** and **Workflow Output** are masked without changing the underlying workflow result. Model requests receive another protected projection: exact secret values known to the run are replaced with `{{KEY}}` before model-visible messages, prompts, tool arguments, or tool continuations leave Sim.
 
+Code that reads a secret straight off the runtime environment — `environmentVariables['KEY']` or `environmentVariables.KEY` in JavaScript, `environmentVariables['KEY']` or `environmentVariables.get('KEY')` in Python, `$KEY` or `${KEY}` in shell — also activates masking, provided Sim can see the read in the code before it runs. A hardcoded literal never does: Sim has no way to know it came from a secret.
+
 <Callout type="warn">
-Execution-log masking is activated only when Sim successfully resolves a value from **Settings → Secrets** through `{{KEY}}`. A hardcoded literal, direct `environmentVariables['KEY']` read, or shell `$KEY` read does not activate log masking by itself. Model-bound projection also checks the run's authorized secret catalog, including direct reads, but both protections match only exact values. Encoded, hashed, fragmented, or otherwise transformed versions are not matched. Do not deliberately return or print secrets.
+Direct reads are found by reading the code, not by running it, so recognition stops where the code stops being readable ahead of time. Sim reports a direct read only when it can attribute one with certainty, and skips it otherwise — an unrecognized read is not masked, and does not appear under **See usage**.
+
+A read is **not** recognized when:
+
+- **The name is built at runtime.** `environmentVariables[keyName]`, `$@`, `${!indirect}`, `eval`, `printenv`, or a sourced file hide which secret is being read.
+- **The binding is reassigned.** If JavaScript or Python code declares its own `environmentVariables` — a variable, parameter, destructured binding, loop target, or assignment — reads off it are no longer the mounted environment, so Sim stops reporting direct reads in that file. In shell the same applies per variable: after `KEY=something`, `$KEY` is the script's own value, so that name is skipped while others are unaffected.
+- **The read cannot be told apart from text.** A `$KEY` inside single quotes or a quoted heredoc (`<<'EOF'`) never expands, and Sim treats anything its scanner cannot place as not running.
+
+Both masking and model-bound projection match only exact values in either case. Encoded, hashed, fragmented, or otherwise transformed versions are not matched, and a value assembled or emitted piece by piece cannot be matched at all — determining whether arbitrary code will eventually reveal a value is not decidable in general. Treat these as a safety net, not a boundary: do not deliberately return, print, or transmit secrets.
 </Callout>
 
 ### Copilot code execution
@@ -105,9 +115,22 @@ From here you can:
 - View the **Key** and edit the **Value**
 - Edit the **Description** — an optional note telling teammates what the secret is for. Workspace secrets only; a personal secret is not shared, so it has none
 - Manage **Members** — invite teammates by email and assign them an **Admin** or **Member** role
+- Open **See usage** — where this secret has actually been used
 
 Click **Save** to apply changes, or **Back** to return to the list.
 
+### See usage
+
+**See usage** lists the runs that resolved this secret: when it was last used, what used it (a workflow, the Sim agent, or an MCP server), how it was triggered, who it resolved under, and a link to the most recent run in Logs. Rows are grouped by day, so a workflow on a schedule reads as one row per day rather than thousands.
+
+This answers the question worth asking before rotating a key: who has been using it, inside what, and how recently.
+
+Only people who can read the value can see it — a Credential Admin on a workspace secret, or the owner of a personal one. For everyone else the action is visible but disabled, because the trail names workflows, people, and run IDs, which is the same information masking withholds. Two people who each hold a personal secret under the same name see only their own runs.
+
+<Callout>
+Usage is recorded independently of execution logs, so it outlives them: logs expire under your workspace's retention setting, while the record of who touched a credential does not. It records what a run resolved, subject to the recognition limits under [Execution log protection](#execution-log-protection) — a read Sim cannot attribute is left out rather than guessed at, so treat an empty trail as "nothing recognized," not proof a secret was never used.
+</Callout>
+
 ## Workspace vs. Personal
 
 | | Workspace | Personal |

apps/docs/content/docs/en/workflows/blocks/function.mdx

@@ -279,10 +279,13 @@ packages, and 10 managed CLI tools.
 
 When a Function block is used as an Agent tool, its code can read every workspace
 secret by default — both `{{MY_SECRET}}` and `environmentVariables['MY_SECRET']`.
-Use `{{MY_SECRET}}` when the value may appear in execution logs: a successful
-double-brace substitution activates [execution-trace masking](/platform/credentials#execution-log-protection),
-while direct `environmentVariables['MY_SECRET']` access alone does not activate
-it by itself.
+Prefer `{{MY_SECRET}}` when the value may appear in execution logs. A successful
+double-brace substitution always activates
+[execution-trace masking](/platform/credentials#execution-log-protection). A direct
+`environmentVariables['MY_SECRET']` read activates it too, but only when Sim can
+recognize the read in the code beforehand — a name built at runtime, or a file that
+reassigns `environmentVariables` itself, is not recognized. See
+[the recognition limits](/platform/credentials#execution-log-protection).
 
 To narrow that, set **Secret access** to *Selected secrets* in the block's
 tool configuration and pick the names the code may read. Two things change:

apps/sim/app/api/secrets/usage/route.test.ts

@@ -49,6 +49,7 @@ describe('GET /api/secrets/usage', () => {
           actorName: 'Ada',
           actorEmail: 'ada@example.com',
           lastExecutionId: 'execution-1',
+          lastExecutionAvailable: true,
           lastTrigger: 'schedule',
         },
       ],

apps/sim/app/workspace/[workspaceId]/settings/secrets/[credentialId]/components/secret-usage-panel/secret-usage-panel.tsx

@@ -3,6 +3,7 @@
 import { useMemo } from 'react'
 import { ChipLink } from '@sim/emcn'
 import { formatDateTime } from '@sim/utils/formatting'
+import { SettingsActionChip } from '@/components/settings/settings-header'
 import type { SecretUsageEntryPayload, SecretUsageScope } from '@/lib/api/contracts'
 import { FloatingOverflowText } from '@/app/workspace/[workspaceId]/components'
 import { DELETED_WORKFLOW_LABEL, TriggerBadge } from '@/app/workspace/[workspaceId]/logs/utils'
@@ -13,6 +14,19 @@ import {
 import { SettingsEmptyState } from '@/app/workspace/[workspaceId]/settings/components/settings-empty-state'
 import { useSecretUsage } from '@/hooks/queries/credentials'
 
+/**
+ * The disabled twin of the View log chip, for a run whose log has been pruned. Routed through
+ * the shared settings chip so it carries the platform's disabled tooltip treatment — including
+ * the pointer-events handling a disabled button needs for the tooltip to fire at all.
+ */
+const EXPIRED_LOG_ACTION = {
+  id: 'view-log',
+  text: 'View log',
+  disabled: true,
+  tooltip: 'This run\u2019s log is past your workspace\u2019s retention window',
+  onSelect: () => {},
+} as const
+
 interface SecretUsagePanelProps {
   workspaceId: string
   secretName: string
@@ -56,7 +70,10 @@ export function SecretUsagePanel({ workspaceId, secretName, scope }: SecretUsage
         ),
         actor: entry.actorName ?? 'Unknown',
         /**
-         * A run only exists for an execution; MCP config resolution has none.
+         * Three states, not two. A row with no execution id never had a run to link (Sim agent
+         * and MCP resolutions have none). A row whose run has since been pruned — usage
+         * outlives logs on purpose — keeps the chip but disables it, so the reader learns the
+         * log expired instead of clicking into an empty Logs view.
          *
          * `border` is the outline-only variant: a bare chip renders as unadorned
          * `--text-body` text at `text-sm`, which next to the Actor cell's `--text-secondary`
@@ -66,13 +83,19 @@ export function SecretUsagePanel({ workspaceId, secretName, scope }: SecretUsage
          * growing it, so a row with a link is the same height as one without.
          */
         trailing: entry.lastExecutionId ? (
-          <ChipLink
-            href={`/workspace/${workspaceId}/logs?executionId=${entry.lastExecutionId}`}
-            variant='border'
-            className='-my-1'
-          >
-            View log
-          </ChipLink>
+          entry.lastExecutionAvailable ? (
+            <ChipLink
+              href={`/workspace/${workspaceId}/logs?executionId=${entry.lastExecutionId}`}
+              variant='border'
+              className='-my-1'
+            >
+              View log
+            </ChipLink>
+          ) : (
+            <span className='-my-1 inline-flex'>
+              <SettingsActionChip action={EXPIRED_LOG_ACTION} />
+            </span>
+          )
         ) : undefined,
       })),
     [data?.entries, workspaceId]

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

@@ -32,6 +32,8 @@ export const secretUsageEntrySchema = z.object({
   actorName: z.string().nullable(),
   actorEmail: z.string().nullable(),
   lastExecutionId: z.string().nullable(),
+  /** False once that run's log has aged out of the workspace's retention window. */
+  lastExecutionAvailable: z.boolean(),
   lastTrigger: z.string().nullable(),
 })
 

apps/sim/lib/execution/code-placeholders/compiler.test.ts

@@ -1421,6 +1421,40 @@ describe('a shadowed environment binding disables direct-read detection', () =>
   })
 })
 
+describe('a rebound shell variable is not the mounted secret', () => {
+  /**
+   * Each shell secret is its own variable, so a script that writes the name is expanding its
+   * own value from that point on. Recording it would claim a use of the injected secret that
+   * never happened.
+   */
+  it.each([
+    ['plain assignment', 'API_KEY=local\necho "$API_KEY"'],
+    ['export assignment', 'export API_KEY=local\necho "$API_KEY"'],
+    ['local assignment', 'f() { local API_KEY=x; echo "$API_KEY"; }\nf'],
+    ['readonly assignment', 'readonly API_KEY=x\necho "$API_KEY"'],
+    ['append assignment', 'API_KEY+=suffix\necho "$API_KEY"'],
+    ['read into the name', 'read API_KEY\necho "$API_KEY"'],
+    ['for loop target', 'for API_KEY in a b; do echo "$API_KEY"; done'],
+    ['unset', 'unset API_KEY\necho "$API_KEY"'],
+  ])('%s', async (_label, code) => {
+    expect(await directReadNames(code, CodeLanguage.Shell)).toEqual([])
+  })
+
+  /** Rebinding one variable says nothing about the others, unlike the single object JS and Python share. */
+  it('drops only the rebound name', async () => {
+    const compiled = await compileCodePlaceholders({
+      code: 'API_KEY=local\necho "$API_KEY $OTHER_KEY"',
+      language: CodeLanguage.Shell,
+      environmentVariables: { API_KEY: 'a-value', OTHER_KEY: 'b-value' },
+    })
+    expect(compiled.resolvedSecretNames).toEqual(['OTHER_KEY'])
+  })
+
+  it('still reports a name the script only expands', async () => {
+    expect(await directReadNames('echo "$API_KEY"', CodeLanguage.Shell)).toEqual(['API_KEY'])
+  })
+})
+
 describe('shell true positives survive the fail-closed rule', () => {
   it.each([
     ['bare unquoted', 'echo $API_KEY'],

apps/sim/lib/execution/code-placeholders/shell.ts

@@ -597,6 +597,31 @@ function collectShellOccurrenceContexts(
 /** `$NAME` and `${NAME}` — including `${NAME:-default}`, whose name still ends at `:`. */
 const SHELL_PARAMETER_EXPANSION = /\$(?:\{\s*([A-Za-z_][A-Za-z0-9_]*)|([A-Za-z_][A-Za-z0-9_]*))/g
 
+/**
+ * Whether every mention of `name` in the script is a parameter expansion of it.
+ *
+ * Shell has no injected environment object to shadow — each secret is its own variable — so a
+ * script that writes the name (`API_KEY=local`, `export`/`local`/`readonly`, `read API_KEY`,
+ * `for API_KEY in …`, `unset`) is expanding its own value from that point on, not the mounted
+ * secret. There is no shell parser here to resolve that with, so this takes the same allowlist
+ * shape as the Python detector: a mention that is not preceded by `$` or `${` is something
+ * this scanner cannot attribute, and the name is dropped.
+ *
+ * Per name rather than per file, unlike JavaScript and Python: those shadow one object holding
+ * every secret, so losing it loses them all, whereas rebinding one shell variable says nothing
+ * about the rest.
+ */
+function isOnlyExpanded(code: string, name: string): boolean {
+  const mention = new RegExp(`(?<![A-Za-z0-9_])${name}(?![A-Za-z0-9_])`, 'g')
+  let found: RegExpExecArray | null
+  while ((found = mention.exec(code)) !== null) {
+    const before = code[found.index - 1]
+    const expanded = before === '$' || (before === '{' && code[found.index - 2] === '$')
+    if (!expanded) return false
+  }
+  return true
+}
+
 /**
  * Reports secrets a shell script expands straight out of the process environment.
  *
@@ -652,6 +677,9 @@ function recordShellDirectEnvironmentReads(
   }
   if (candidates.length === 0) return
 
+  /** Computed once per name — a script may expand the same secret many times. */
+  const attributable = new Map<string, boolean>()
+
   const contexts = collectShellOccurrenceContexts(code, candidates, 0, code.length, false)
   for (const candidate of candidates) {
     const shellContext = contexts.get(candidate)
@@ -662,6 +690,12 @@ function recordShellDirectEnvironmentReads(
      * expansion outright.
      */
     if (!shellContext || shellContext.quote === 'single') continue
+    let onlyExpanded = attributable.get(candidate.name)
+    if (onlyExpanded === undefined) {
+      onlyExpanded = isOnlyExpanded(code, candidate.name)
+      attributable.set(candidate.name, onlyExpanded)
+    }
+    if (!onlyExpanded) continue
     context.recordDirectEnvironmentRead(candidate.name, candidate.start)
   }
 }

apps/sim/lib/secrets/usage/queries.ts

@@ -1,5 +1,5 @@
 import { db } from '@sim/db'
-import { secretUsage, user, workflow } from '@sim/db/schema'
+import { secretUsage, user, workflow, workflowExecutionLogs } from '@sim/db/schema'
 import { and, desc, eq } from 'drizzle-orm'
 import type { ResolvedSecretScope } from '@/executor/utils/resolved-secret-trace-registry'
 
@@ -16,6 +16,12 @@ export interface SecretUsageEntry {
   actorName: string | null
   actorEmail: string | null
   lastExecutionId: string | null
+  /**
+   * Whether that run's log still exists. Usage outlives logs by design — the trail is not
+   * bound by `logRetentionHours` — so a row routinely names a run whose log has since been
+   * pruned, and the UI has to say so rather than link into an empty view.
+   */
+  lastExecutionAvailable: boolean
   lastTrigger: string | null
 }
 
@@ -55,11 +61,17 @@ export async function getSecretUsage(query: SecretUsageQuery): Promise<SecretUsa
       actorName: user.name,
       actorEmail: user.email,
       lastExecutionId: secretUsage.lastExecutionId,
+      /** At most one row: `execution_id` carries a unique index, so this cannot fan out. */
+      lastExecutionLogId: workflowExecutionLogs.id,
       lastTrigger: secretUsage.lastTrigger,
     })
     .from(secretUsage)
     .leftJoin(workflow, eq(workflow.id, secretUsage.workflowId))
     .leftJoin(user, eq(user.id, secretUsage.actorUserId))
+    .leftJoin(
+      workflowExecutionLogs,
+      eq(workflowExecutionLogs.executionId, secretUsage.lastExecutionId)
+    )
     .where(
       and(
         eq(secretUsage.workspaceId, query.workspaceId),
@@ -73,10 +85,11 @@ export async function getSecretUsage(query: SecretUsageQuery): Promise<SecretUsa
 
   return {
     /** The storage sentinel is an implementation detail of the unique key, not a value. */
-    entries: rows.map((row) => ({
+    entries: rows.map(({ lastExecutionLogId, ...row }) => ({
       ...row,
       workflowId: row.workflowId || null,
       actorUserId: row.actorUserId || null,
+      lastExecutionAvailable: lastExecutionLogId !== null,
     })),
   }
 }