Keep-rules follow-ups: unforgeable placeholders, CVV floor in text, card numbers in token text (0.17.1, #160102)

[jab3z]

The library side of #160102: what the 0.17.0 keep-rules round left, closed after three review rounds. A patch release (0.17.1): every change is a fix or a tightening. Some wallet tokens that 0.17.0 kept are now masked (fails closed); none that 0.17.0 masked now ships.

Placeholders can't be forged or confused (M4, M3)

• A kept value's placeholder is named from a blake2b digest of the value itself ([KEPT-<14 letters>-MASKED]), not its position.
• A placeholder written into the text (an entity-encoded [KEPT-A-MASKED] in a KPay body) restores nothing.
• Two different wallets inside one hashed credential get two different tokens. The same credential with the same wallet keeps the same token on every line.

The CVV/SAD floor in text (M2)

• Text that names a CVV or SAD key, XML tag, or {name, value} pair label anywhere keeps no wallet in it. It uses the key walk's classification, with safe keys honoured.
• The text rules read objects only three levels deep, and a real Apple Pay token is three deep itself, so {"cvv": [token]} can only be floored this way. Fails closed.
• Ottu's real bodies still keep their tokens: KPay <udf9> beside <password>, Connect's SDK Apple Pay request beside cvv_required, and a Google Pay body.

The guard reads a card number inside a kept value's text (N3)

• A text leaf of a keep match is read in one linear pass, as the pci rules read a value (holds_pan_run). These now refuse the keep: "4111…+cvv+123" in base64, "4111…ab" in hex, "1234 4111…", "4111… 12/25", 20 bare digits.
• Three leaves are not read: epoch milliseconds (Google Pay's keyExpiration), a canonical UUID, and a whole hex id of 24+ characters holding a hex letter.
  • The hex-id case follows the rule Connect's own card scan already uses. Without it, 1.1% of Apple Pay tokens were refused, because a random 64-hex transactionId sometimes holds a Luhn run.
  • So a card number written into a whole hex id ships with a kept token. Accepted (Dacian, 2026-10-02): Apple writes these ids, and an Apple Pay token carries no PAN, so the token is logged in full.
• A crafted 400 KB token is decided in about 0.4 s, linear (round 2's version took 6.5 s).

Ottu's matchers (N3, contrib)

• Every slot must be text in its alphabet: base64 (never hex alone), hex, or digits.
• signedMessage and signedKey must hold exactly their fields.
• displayName is letters plus an optional last four, and never a CVV or SAD name ("CVV 1234").
• network and type are letters alone, or empty, and never a CVV or SAD name ("network": "cvv=123" and an email in type were kept before; from the bot review).
• Real-token keep rate: 59,999 of 60,000. The one miss is a 13-digit run occurring by chance in ciphertext; it fails closed.

Also

• A label rule wins at any depth strictly inside a keep match (M8).
• A label rule that raises inside a keep match refuses the keep, raising nothing.
• A rule with both field_type and keep = True is refused as ambiguous (M6).
• The README states measured costs: wallet lines cost 10-35% more than 0.17.0; lines without a wallet are unchanged. It also states what the text floor and the guard read and don't.

Verification

• 6877 tests pass on Python 3.12 and 3.10 (5765 at 0.17.0). Each fix's tests failed first.
• golden/masking_0156.json is unchanged.
• Reviews: task review (CHANGES_REQUESTED), re-review of rounds 1-2 (CHANGES_REQUESTED: a quadratic guard), and re-review of round 3 (APPROVED). The round-3 review ran ~2.5M never-raises fuzz calls with 0 exceptions, plus linear-cost probes up to 1.6 MB. Its minors are fixed here: base64 slots that are hex alone, a CVV-named displayName, and docs.

Left for a follow-up

• Generic keep rules only, not reachable through Ottu's WALLET_RULES:
  • a dict key that is a card number ships in text;
  • a JSON number inside JSON text is read by int_is_pan only;
  • a CVV key written with \uXXXX escapes is read by the key walk, not the text floor (documented).
• A localised, non-Latin displayName fails the matcher; the token is then masked, which fails closed.
• Samsung Pay still needs a real captured token.

Release

Patch, 0.17.1. Connect and Ottu PG then pin >=0.17.1.

Refs #160102

🤖 Generated with Claude Code

[jab3z]

@claude review

[claude]

Claude finished @jab3z's task in 1m 6s —— View job

---

Review of #72 (keep-rules follow-ups, 0.17.1)

I read the code statically. I couldn't run the tests or my probes: the sandbox denied pytest, writing a probe script, and git fetch. The checkout has no merge base with origin/main, so I read the final files instead of the diff. I read masking/value_rules.py, contrib/ottu/masking.py, and the placeholder, floor and holds_card_run parts of masking/patterns.py. I did not read contrib/net/__init__.py or the tests.

Overall: the design holds up. Naming placeholders from a digest of the value, applying the CVV/SAD floor to the whole text, and reading card runs inside kept text are all sound, and every failure path fails closed. I found two gaps, both in places where the PR text claims more than the code does. Neither blocks the PR, but I'd resolve both before release or add them to the "Left for a follow-up" list.

Findings

1. network and type in paymentMethod are not alphabet-checked (ecsctx/contrib/ottu/masking.py, _is_pk_payment_token)

• The PR says "Every slot must be text in its alphabet".
• network and type are only required to be a str of at most 64 characters (_PAYMENT_METHOD_TEXT_LIMIT).
• holds_card_data documents that it does not read a short CVV inside a longer string and leaves that to the matcher. This matcher doesn't check, so these values ship as sent:
  • {"network": "cvv=123"}
  • {"type": "john@example.com"}
• I could not run a probe, so this comes from reading the code: the guard only sees a key, a pair, a whole PAN, or a 12+ digit run.
• The README's "CVV written in a slot's own alphabet cannot be told from ciphertext" caveat doesn't cover this, because these slots have no alphabet.
• Fix: give network and type a letters-only pattern, such as [A-Za-z][A-Za-z .&_-]{0,31}, and run classify_key over them as _is_display_name does.

2. The hex-id exemption lets a card number ship inside a hex-alphabet slot (ecsctx/masking/patterns.py:826, _HEX_ID)

• A leaf of 24+ hex characters that holds at least one hex letter is never read for a card run.
• Ottu's hex slots (transactionId, applicationData, transactionIdentifier) accept any hex text. A value like 4111111111111111abcdefabcdefabcd is accepted by the matcher.
  • It is not pan_shaped as a whole.
  • holds_card_run returns False.
  • It ships with the PAN in it.
• A real Apple Pay transactionId is a random 64-hex digest. The cost is about 1.1% of real tokens refused, and the PR accepts it for the benefit of Connect's own scan.
• The PR notes this rule follows Connect's scan, but not that it opens a way to ship a PAN. A cheap tightening is to exempt only a leaf of exactly 64 hex characters (SHA-256) for these slots. Alternatively, document it as an accepted residual next to the "Left for a follow-up" list.

Minor

• _BASE64 rejects any string made only of hex characters. That is fail-closed and correct for real tokens, but a short tag could in principle be refused by chance. The probability is negligible at the real lengths, so no action is needed.
• Placeholders use an unkeyed 64-bit blake2b digest, so forging one needs the value itself. The collision path (stash_kept returns None, KeptStash.hold returns the value) fails closed. Fine.
• floored_text is only evaluated once a span is found, which keeps the cost off lines with no wallet. Good.

Not verified

• The claims of 6797 passing tests, the fuzz runs and the 0.4 s linear-time probe. I did not rerun any of them.
• contrib/net (redact_body changes) and the new tests.
  · branch fix/160102-keep-rules-followups