test(stack): stage USER_JWT live-coverage guard (skipped pending secret)

The identity/lock-context live suites soft-skip on a missing USER_JWT, which the
CI coverage guard never asserted. Add a LIVE_LOCK_CONTEXT_ENABLED flag and a
guard assertion, kept as it.skip until the USER_JWT CI secret is provisioned
(flip to it.runIf(IN_CI) then) so CI does not fail on the not-yet-present secret.

Author: tobyhede

packages/stack/__tests__/helpers/live-gate.ts

@@ -23,6 +23,17 @@ export const LIVE_EQL_V3_PG_ENABLED = Boolean(
   process.env.DATABASE_URL && LIVE_CIPHERSTASH_ENABLED,
 )
 
+/**
+ * True when live credentials AND a `USER_JWT` are configured. The identity /
+ * lock-context live suites additionally require a `USER_JWT` to bind keys to an
+ * end-user identity, and SOFT-SKIP (inline `if (!userJwt) return`) when it is
+ * absent — so a missing/rotated `USER_JWT` lets them skip green in CI. This
+ * flag lets the live-coverage guard assert that path is actually exercised.
+ */
+export const LIVE_LOCK_CONTEXT_ENABLED = Boolean(
+  process.env.USER_JWT && LIVE_CIPHERSTASH_ENABLED,
+)
+
 export const describeLive = LIVE_CIPHERSTASH_ENABLED ? describe : describe.skip
 
 export const describeLivePg = LIVE_EQL_V3_PG_ENABLED ? describe : describe.skip

packages/stack/__tests__/live-coverage-guard.test.ts

@@ -55,6 +55,7 @@ import { describe, expect, it } from 'vitest'
 import {
   LIVE_CIPHERSTASH_ENABLED,
   LIVE_EQL_V3_PG_ENABLED,
+  LIVE_LOCK_CONTEXT_ENABLED,
 } from './helpers/live-gate'
 
 // GitHub Actions always sets CI=true; treat any truthy CI as "must run live".
@@ -87,6 +88,28 @@ describe('live-coverage guard', () => {
     },
   )
 
+  // DEFERRED (follow-up): the CI `USER_JWT` secret is not yet provisioned, so
+  // enforcing this now would fail CI. Skipped until the secret exists — flip
+  // back to `it.runIf(IN_CI)` at that point. It still documents the real gap:
+  // the identity / lock-context live suites soft-skip on a missing USER_JWT, so
+  // once the secret lands this guard turns a silent whole-suite skip into a
+  // loud failure (as the CS_*/DATABASE_URL guards already do).
+  it.skip(
+    'CI must have USER_JWT so the lock-context live suites do not silently skip',
+    () => {
+      expect(
+        LIVE_LOCK_CONTEXT_ENABLED,
+        'CI must run the live lock-context / identity suites — ' +
+          '`LIVE_LOCK_CONTEXT_ENABLED` is false. This needs the CS_* creds AND ' +
+          'a `USER_JWT`; the identity/lock-context suites (e.g. ' +
+          'lock-context.test.ts, protect-ops.test.ts, ' +
+          'operators-lock-context-live-pg.test.ts) SOFT-SKIP when USER_JWT is ' +
+          'absent, so a missing/rotated USER_JWT lets them skip green with no ' +
+          'signal — the exact failure mode this guard exists to prevent.',
+      ).toBe(true)
+    },
+  )
+
   // Local dev with no creds: nothing to assert. Keep at least one always-run
   // assertion so the file is never reported as fully empty/pending.
   it('is always collected (guard file runs outside every live gate)', () => {