Skip to content

Commit 2ab2b94

Browse files
committed
docs(cli,migrate): warn that a forced decrypt pass clears undecryptable rows
A forced pass sets the plaintext of every row it cannot decrypt to NULL, including a value the application wrote after decrypting the row as its user. The --force warning, the skipped-rows report, the decrypt docstring and the stash-cli skill now say to do per-user remediation only after the last forced pass has completed, then re-run without --force. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018TacM4u97tr5yPAFynxYXW
1 parent b56561f commit 2ab2b94

3 files changed

Lines changed: 7 additions & 4 deletions

File tree

‎languages/typescript/packages/cli/src/commands/decrypt/backfill.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -190,7 +190,7 @@ export async function decryptBackfillCommand(
190190

191191
if (options.force) {
192192
p.log.warn(
193-
`--force will re-decrypt every row of ${options.table}.${pair.encryptedColumn} and overwrite the ${pair.plaintextColumn} values that already exist. Safe only while dual-writes are live: any row your application wrote to ${pair.plaintextColumn} alone (a newer value, or one cleared on purpose) gets the older ciphertext's value back.`,
193+
`--force will re-decrypt every row of ${options.table}.${pair.encryptedColumn} and overwrite the ${pair.plaintextColumn} values that already exist. Safe only while dual-writes are live: any row your application wrote to ${pair.plaintextColumn} alone (a newer value, or one cleared on purpose) gets the older ciphertext's value back. Every row it cannot decrypt (a lock context, say) has ${pair.plaintextColumn} set to NULL, including any your application has already decrypted, so decrypt those in your application only after the forced pass completes.`,
194194
)
195195
const proceed = await p.confirm({
196196
message: 'Continue with --force?',
@@ -427,7 +427,7 @@ export function skippedReport(
427427
if (failed > 0) {
428428
const codes = ` This run: ${formatCodes(failedCodes)}.`
429429
paragraphs.push(
430-
`${failed.toLocaleString()} row(s) of ${table}.${pair.encryptedColumn} could not be decrypted with these credentials and were left with ${pair.plaintextColumn} NULL.${codes} The usual cause is a value bound to an end-user lock context: only that user's identity can decrypt it, and the CLI has no way to act as them. Decrypt those rows in your application on behalf of each user (writing ${pair.plaintextColumn}), then re-run this backfill. \`stash decrypt drop\` refuses while any of them remain, because dropping ${pair.encryptedColumn} would destroy their only copy.`,
430+
`${failed.toLocaleString()} row(s) of ${table}.${pair.encryptedColumn} could not be decrypted with these credentials and were left with ${pair.plaintextColumn} NULL.${codes} The usual cause is a value bound to an end-user lock context: only that user's identity can decrypt it, and the CLI has no way to act as them. Decrypt those rows in your application on behalf of each user (writing ${pair.plaintextColumn}), then re-run this backfill without --force. Do that only after the last forced pass has completed: a forced pass, including a plain re-run that finishes an interrupted one, sets ${pair.plaintextColumn} back to NULL on every row it cannot decrypt. \`stash decrypt drop\` refuses while any of them remain, because dropping ${pair.encryptedColumn} would destroy their only copy.`,
431431
)
432432
}
433433

‎languages/typescript/packages/migrate/src/decrypt.ts‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -290,7 +290,10 @@ const REVERSE_EVENTS = {
290290
* a NULL plaintext, {@link countUndecrypted} still counts them, so the
291291
* coverage gate in `stash decrypt drop` refuses to drop the only copy of
292292
* their data. Under `force` the plaintext column may hold a stale value, so a
293-
* forced pass sets a skipped row's plaintext to NULL rather than leave it.
293+
* forced pass sets a skipped row's plaintext to NULL rather than leave it,
294+
* including a value the application wrote after decrypting the row as its
295+
* user: it cannot tell that from a stale one, so per-user remediation
296+
* belongs after the last forced pass.
294297
* A later run (after the cursor-based pass has completed) starts
295298
* from the beginning and retries them.
296299
*

‎skills/stash-cli/SKILL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -686,7 +686,7 @@ Same engine as `encrypt backfill`: keyset pagination, one transaction per chunk
686686

687687
The choice is recorded in `cs_migrations`. Later runs of the same reverse migration do not ask again: the twin's values are then its own. Choosing `--force` makes a forced pass owed from that moment, and so does starting any `--force` run: every later run is forced, with or without `--force`, until one completes, so an interrupted `--force` run is always finished as one, even if it failed before writing anything. A `--force` run after an interrupted plain one starts again from the first row.
688688

689-
**Lock contexts — known limitation, no bypass.** A value encrypted with an end-user lock context can only be decrypted as that user (see `stash-auth`). With workspace credentials it fails *on its own row* (`bulkDecrypt` reports per row), so the backfill **skips it, counts it, leaves the twin NULL** (a `--force` pass sets a skipped row's twin to NULL, so a stale value is never left behind), and reports the count and error codes; the count is also recorded in `cs_migrations` and shown by `decrypt status`. Decrypt those rows in your application on each user's behalf (writing the plaintext column), then re-run. `decrypt drop` refuses while any remain.
689+
**Lock contexts — known limitation, no bypass.** A value encrypted with an end-user lock context can only be decrypted as that user (see `stash-auth`). With workspace credentials it fails *on its own row* (`bulkDecrypt` reports per row), so the backfill **skips it, counts it, leaves the twin NULL** (a `--force` pass sets a skipped row's twin to NULL, so a stale value is never left behind), and reports the count and error codes; the count is also recorded in `cs_migrations` and shown by `decrypt status`. Decrypt those rows in your application on each user's behalf (writing the plaintext column), then re-run without `--force`. Do this only after the last forced pass has completed: a forced pass (including a plain run that finishes an interrupted one) sets the twin back to NULL on every row it cannot decrypt, an application-written value included. `decrypt drop` refuses while any remain.
690690

691691
**Ciphertext that decrypts to null.** A non-JSON twin can only store an empty value as NULL, which is also what "not decrypted yet" looks like, so these rows are skipped as `NULL_PLAINTEXT` and reported separately, with their primary keys. They are not a credentials or lock-context problem and a re-run will not change them. `decrypt drop` refuses while they hold ciphertext: once you have confirmed the values really are empty, set their encrypted column to NULL, then generate the drop.
692692

0 commit comments

Comments
 (0)