decryptre 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
decryptre/__init__.py ADDED
@@ -0,0 +1,11 @@
1
+ """DecryptRE: offline text decryption and encryption toolkit.
2
+
3
+ Everything in this package runs locally. There are no network calls, no
4
+ telemetry and no remote wordlists.
5
+ """
6
+
7
+ __version__ = "0.1.0"
8
+
9
+ from .models import Candidate # noqa: F401
10
+
11
+ __all__ = ["Candidate", "__version__"]
decryptre/__main__.py ADDED
@@ -0,0 +1,6 @@
1
+ """Enable ``python -m decryptre``."""
2
+
3
+ from .cli import main
4
+
5
+ if __name__ == "__main__":
6
+ raise SystemExit(main())
@@ -0,0 +1,231 @@
1
+ """Layered auto-detection ("no passphrase" mode).
2
+
3
+ Strategy: peel one layer at a time. At each depth every plausible decoder is
4
+ tried (encodings, classical ciphers, XOR, and -- for DecryptRE containers --
5
+ a passphrase dictionary). Results are scored with :mod:`decryptre.scorer`,
6
+ the best few are kept as the next frontier, and a visited set stops cycles.
7
+
8
+ Budgets (``max_depth``, ``max_candidates``) keep the search bounded. This is
9
+ a heuristic search, not an exhaustive keyspace scan.
10
+ """
11
+
12
+ import base64
13
+ from typing import Dict, Iterable, List, Optional
14
+
15
+ from . import classical, encodings, modern_crypto, xor
16
+ from .containers import is_container
17
+ from .models import Candidate
18
+ from .scorer import printable_ratio, score_text
19
+
20
+ XOR_PREFIX = "decryptre:xor:"
21
+
22
+
23
+ def _unique_best(candidates: Iterable[Candidate]) -> List[Candidate]:
24
+ best: Dict[str, Candidate] = {}
25
+ for candidate in candidates:
26
+ current = best.get(candidate.text)
27
+ if current is None or candidate.score > current.score:
28
+ best[candidate.text] = candidate
29
+ return list(best.values())
30
+
31
+
32
+ def _decode_xor_wrapper(text: str) -> Optional[Candidate]:
33
+ if not text.strip().startswith(XOR_PREFIX):
34
+ return None
35
+ token = text.strip()[len(XOR_PREFIX):]
36
+ token += "=" * ((-len(token)) % 4)
37
+ try:
38
+ raw = base64.urlsafe_b64decode(token.encode("ascii"))
39
+ except (ValueError, UnicodeDecodeError):
40
+ return None
41
+ # Keep the raw bytes as latin-1 text so the XOR breaker can attack them.
42
+ ciphertext = raw.decode("latin-1")
43
+ return Candidate(
44
+ ciphertext, "xor", {"op": "base64-unwrap"}, score_text(ciphertext)
45
+ )
46
+
47
+
48
+ def _expand(
49
+ parent: Candidate,
50
+ wordlist: Iterable[str],
51
+ include_substitution: bool,
52
+ ) -> List[Candidate]:
53
+ """Produce every one-layer child of ``parent``."""
54
+ text = parent.text
55
+ depth = parent.depth + 1
56
+ sample = text[:4000]
57
+ children: List[Candidate] = []
58
+
59
+ def add(child: Candidate) -> None:
60
+ child.depth = depth
61
+ child.parent = f"{parent.method} {parent.describe_params()}".strip()
62
+ if child.text and child.text != text:
63
+ children.append(child)
64
+
65
+ # 1. XOR wrapper produced by `decryptre encrypt --method xor`.
66
+ wrapped = _decode_xor_wrapper(text)
67
+ if wrapped is not None:
68
+ add(wrapped)
69
+
70
+ # 2. Encodings (one level).
71
+ for name in encodings.ENCODINGS:
72
+ if not encodings.looks_like(text, name):
73
+ continue
74
+ try:
75
+ decoded = encodings.decode(text, name)
76
+ except encodings.DecodeError:
77
+ continue
78
+ add(Candidate(decoded, name, {"op": "decode"}, score_text(decoded)))
79
+
80
+ # 3. Classical ciphers.
81
+ if any(ch.isalpha() for ch in sample):
82
+ add_many = children.extend
83
+ add_many(
84
+ _with_depth(classical.break_caesar(sample, top=3), depth, parent)
85
+ )
86
+ add_many(_with_depth(classical.break_atbash(sample), depth, parent))
87
+ # Vigenere and substitution are comparatively slow; they are most
88
+ # useful on the first text layer, so only run them there.
89
+ if depth == 1 and 20 <= len(sample) <= 1000:
90
+ add_many(
91
+ _with_depth(classical.break_vigenere(sample, top=2), depth, parent)
92
+ )
93
+ if 10 <= len(sample) <= 4000:
94
+ add_many(
95
+ _with_depth(classical.break_railfence(sample, top=2), depth, parent)
96
+ )
97
+ # Substitution is the slowest solver, so only attempt it when the
98
+ # cheaper ciphers failed to produce readable English.
99
+ best_so_far = max((c.score for c in children), default=float("-inf"))
100
+ if (
101
+ include_substitution
102
+ and depth == 1
103
+ and 40 <= len(sample) <= 800
104
+ and best_so_far < -7.0
105
+ ):
106
+ add_many(
107
+ _with_depth(
108
+ classical.break_substitution(
109
+ sample, restarts=3, iterations=8000, top=1
110
+ ),
111
+ depth,
112
+ parent,
113
+ )
114
+ )
115
+
116
+ # 4. XOR. Always try it on a freshly decoded encoding layer: XOR after
117
+ # Base64/hex is a classic combination. On the original input only try it
118
+ # when the text does not already look like English.
119
+ data = xor.to_bytes(sample)
120
+ decoded_layer = parent.method in encodings.ENCODINGS
121
+ worth_trying = (
122
+ printable_ratio(sample) < 0.75
123
+ or decoded_layer
124
+ or (depth == 1 and score_text(sample) < -8.0)
125
+ )
126
+ if data and worth_trying:
127
+ add_many = children.extend
128
+ add_many(_with_depth(xor.break_single_byte(data, top=2), depth, parent))
129
+ if 8 <= len(data) <= 4000:
130
+ add_many(
131
+ _with_depth(
132
+ xor.break_repeating_key(data, top=2), depth, parent
133
+ )
134
+ )
135
+
136
+ # 5. Modern crypto: dictionary attack on DecryptRE containers only.
137
+ if wordlist and is_container(text):
138
+ add_many = children.extend
139
+ add_many(
140
+ _with_depth(
141
+ modern_crypto.dictionary_attack(text, wordlist, top=2),
142
+ depth,
143
+ parent,
144
+ )
145
+ )
146
+
147
+ return _unique_best(children)
148
+
149
+
150
+ def _with_depth(
151
+ candidates: Iterable[Candidate], depth: int, parent: Candidate
152
+ ) -> List[Candidate]:
153
+ out = []
154
+ for candidate in candidates:
155
+ if candidate.text == parent.text:
156
+ continue
157
+ candidate.depth = depth
158
+ candidate.parent = f"{parent.method} {parent.describe_params()}".strip()
159
+ out.append(candidate)
160
+ return out
161
+
162
+
163
+ def _select_frontier(children: List[Candidate], beam: int) -> List[Candidate]:
164
+ """Keep the best children, plus decodes that deserve another layer.
165
+
166
+ Encoding decodes are deterministic and cheap, so they are always carried
167
+ forward even when the decoded text does not look like English yet (it may
168
+ be the ciphertext of the next layer).
169
+ """
170
+ unique = _unique_best(children)
171
+ unique.sort(key=lambda c: c.score, reverse=True)
172
+ selected = unique[:beam]
173
+ carriers = [
174
+ c for c in unique
175
+ if c.method in encodings.ENCODINGS or c.params.get("op") == "base64-unwrap"
176
+ ]
177
+ for carrier in carriers[:3]:
178
+ if carrier not in selected:
179
+ selected.append(carrier)
180
+ return selected
181
+
182
+
183
+ def detect(
184
+ text: str,
185
+ max_depth: int = 3,
186
+ max_candidates: int = 2000,
187
+ top: int = 5,
188
+ wordlist: Optional[Iterable[str]] = None,
189
+ beam: int = 6,
190
+ include_substitution: bool = True,
191
+ ) -> List[Candidate]:
192
+ """Return the most English-looking decryptions found, best first."""
193
+ if max_depth < 1:
194
+ return [Candidate(text, "input", {}, score_text(text), 0)]
195
+
196
+ wordlist = list(wordlist or [])
197
+ best: Dict[str, Candidate] = {}
198
+
199
+ def remember(candidate: Candidate) -> None:
200
+ current = best.get(candidate.text)
201
+ if current is None or candidate.score > current.score:
202
+ best[candidate.text] = candidate
203
+
204
+ start = Candidate(text, "input", {}, score_text(text), 0)
205
+ remember(start)
206
+
207
+ frontier = [start]
208
+ visited = set()
209
+ produced = 0
210
+
211
+ for _depth in range(max_depth):
212
+ children: List[Candidate] = []
213
+ for parent in frontier:
214
+ if produced >= max_candidates:
215
+ break
216
+ for child in _expand(parent, wordlist, include_substitution):
217
+ signature = child.signature()
218
+ if signature in visited:
219
+ continue
220
+ visited.add(signature)
221
+ produced += 1
222
+ remember(child)
223
+ children.append(child)
224
+ if produced >= max_candidates:
225
+ break
226
+ if not children:
227
+ break
228
+ frontier = _select_frontier(children, beam)
229
+
230
+ ranked = sorted(best.values(), key=lambda c: c.score, reverse=True)
231
+ return ranked[:max(1, top)]
decryptre/classical.py ADDED
@@ -0,0 +1,426 @@
1
+ """Classical ciphers: Caesar/ROT-N, Atbash, Vigenere, Rail Fence, substitution.
2
+
3
+ Every "break_*" function is offline parameter search guided by
4
+ :func:`decryptre.scorer.score_text`; nothing here needs a network connection.
5
+ Substitution solving is a best-effort hill climb and can fail on short or
6
+ unusual text -- the README says so too.
7
+ """
8
+
9
+ import math
10
+ import random
11
+ from collections import Counter
12
+ from typing import List
13
+
14
+ from .models import Candidate
15
+ from .ngrams import log_table
16
+ from .scorer import ENGLISH_FREQ, chi_square, score_text
17
+
18
+ ALPHABET = "abcdefghijklmnopqrstuvwxyz"
19
+ _ALPHA_INDEX = {c: i for i, c in enumerate(ALPHABET)}
20
+
21
+
22
+ # ---------------------------------------------------------------------------
23
+ # Caesar / ROT-N
24
+ # ---------------------------------------------------------------------------
25
+
26
+ def caesar_encrypt(text: str, shift: int) -> str:
27
+ shift %= 26
28
+ out = []
29
+ for ch in text:
30
+ if "a" <= ch <= "z":
31
+ out.append(chr((ord(ch) - 97 + shift) % 26 + 97))
32
+ elif "A" <= ch <= "Z":
33
+ out.append(chr((ord(ch) - 65 + shift) % 26 + 65))
34
+ else:
35
+ out.append(ch)
36
+ return "".join(out)
37
+
38
+
39
+ def caesar_decrypt(text: str, shift: int) -> str:
40
+ return caesar_encrypt(text, -shift)
41
+
42
+
43
+ def rot13(text: str) -> str:
44
+ return caesar_encrypt(text, 13)
45
+
46
+
47
+ def break_caesar(text: str, top: int = 5) -> List[Candidate]:
48
+ results = []
49
+ for shift in range(26):
50
+ plain = caesar_decrypt(text, shift)
51
+ results.append(
52
+ Candidate(plain, "caesar", {"shift": shift}, score_text(plain))
53
+ )
54
+ results.sort(key=lambda c: c.score, reverse=True)
55
+ return results[:top]
56
+
57
+
58
+ # ---------------------------------------------------------------------------
59
+ # Atbash
60
+ # ---------------------------------------------------------------------------
61
+
62
+ def atbash(text: str) -> str:
63
+ out = []
64
+ for ch in text:
65
+ if "a" <= ch <= "z":
66
+ out.append(chr(122 - (ord(ch) - 97)))
67
+ elif "A" <= ch <= "Z":
68
+ out.append(chr(90 - (ord(ch) - 65)))
69
+ else:
70
+ out.append(ch)
71
+ return "".join(out)
72
+
73
+
74
+ def break_atbash(text: str) -> List[Candidate]:
75
+ plain = atbash(text)
76
+ return [Candidate(plain, "atbash", {}, score_text(plain))]
77
+
78
+
79
+ # ---------------------------------------------------------------------------
80
+ # Vigenere
81
+ # ---------------------------------------------------------------------------
82
+
83
+ def _vigenere_shift(text: str, key: str, direction: int) -> str:
84
+ key_letters = [c for c in key.lower() if c in _ALPHA_INDEX]
85
+ if not key_letters:
86
+ raise ValueError("Vigenere key must contain at least one letter")
87
+ out = []
88
+ key_pos = 0
89
+ for ch in text:
90
+ if "a" <= ch <= "z" or "A" <= ch <= "Z":
91
+ base = 97 if ch.islower() else 65
92
+ shift = _ALPHA_INDEX[key_letters[key_pos % len(key_letters)]]
93
+ out.append(chr((ord(ch) - base + direction * shift) % 26 + base))
94
+ key_pos += 1
95
+ else:
96
+ out.append(ch)
97
+ return "".join(out)
98
+
99
+
100
+ def vigenere_encrypt(text: str, key: str) -> str:
101
+ return _vigenere_shift(text, key, 1)
102
+
103
+
104
+ def vigenere_decrypt(text: str, key: str) -> str:
105
+ return _vigenere_shift(text, key, -1)
106
+
107
+
108
+ def _best_shift_for_column(letters: str) -> int:
109
+ """Pick the Caesar shift whose output best matches English frequencies."""
110
+ best_shift, best_score = 0, float("inf")
111
+ for shift in range(26):
112
+ shifted = "".join(
113
+ chr((ord(c) - 97 - shift) % 26 + 97) for c in letters
114
+ )
115
+ value = chi_square(shifted)
116
+ if value < best_score:
117
+ best_shift, best_score = shift, value
118
+ return best_shift
119
+
120
+
121
+ def _average_ic(letters: str, key_length: int) -> float:
122
+ total = 0.0
123
+ for column in range(key_length):
124
+ counts = Counter(letters[column::key_length])
125
+ n = sum(counts.values())
126
+ if n < 2:
127
+ continue
128
+ total += sum(c * (c - 1) for c in counts.values()) / (n * (n - 1))
129
+ return total / key_length
130
+
131
+
132
+ def _refine_key(key: str, sample: str, passes: int = 2) -> str:
133
+ """Hill-climb the key one letter at a time against the English score."""
134
+ best = list(key)
135
+ best_score = score_text(vigenere_decrypt(sample, key))
136
+ for _ in range(passes):
137
+ improved = False
138
+ for index in range(len(best)):
139
+ original = best[index]
140
+ best_letter, best_value = original, best_score
141
+ for letter in ALPHABET:
142
+ if letter == original:
143
+ continue
144
+ trial = list(best)
145
+ trial[index] = letter
146
+ value = score_text(vigenere_decrypt(sample, "".join(trial)))
147
+ if value > best_value:
148
+ best_letter, best_value = letter, value
149
+ if best_letter != original:
150
+ best[index] = best_letter
151
+ best_score = best_value
152
+ improved = True
153
+ if not improved:
154
+ break
155
+ return "".join(best)
156
+
157
+
158
+ def break_vigenere(text: str, max_key_length: int = 12, top: int = 5) -> List[Candidate]:
159
+ letters_only = "".join(c for c in text.lower() if c in _ALPHA_INDEX)
160
+ if len(letters_only) < 8:
161
+ return []
162
+ max_key_length = min(max_key_length, max(1, len(letters_only) // 4))
163
+
164
+ # Prefer lengths whose columns look like English (index of coincidence).
165
+ lengths = sorted(
166
+ range(1, max_key_length + 1),
167
+ key=lambda length: abs(_average_ic(letters_only, length) - 0.066),
168
+ )[:4]
169
+ if 1 not in lengths:
170
+ lengths.append(1)
171
+
172
+ sample = text[:500]
173
+ results: List[Candidate] = []
174
+ for length in lengths:
175
+ key_chars = []
176
+ for column in range(length):
177
+ column_letters = letters_only[column::length]
178
+ if not column_letters:
179
+ key_chars.append("a")
180
+ continue
181
+ key_chars.append(ALPHABET[_best_shift_for_column(column_letters)])
182
+ key = _refine_key("".join(key_chars), sample)
183
+ plain = vigenere_decrypt(text, key)
184
+ results.append(
185
+ Candidate(plain, "vigenere", {"key": key}, score_text(plain))
186
+ )
187
+ results.sort(key=lambda c: c.score, reverse=True)
188
+ return results[:top]
189
+
190
+
191
+ # ---------------------------------------------------------------------------
192
+ # Rail fence
193
+ # ---------------------------------------------------------------------------
194
+
195
+ def _rail_pattern(length: int, rails: int) -> List[int]:
196
+ if rails <= 1:
197
+ return [0] * length
198
+ pattern = []
199
+ rail = 0
200
+ direction = 1
201
+ for _ in range(length):
202
+ pattern.append(rail)
203
+ if rail == 0:
204
+ direction = 1
205
+ elif rail == rails - 1:
206
+ direction = -1
207
+ rail += direction
208
+ return pattern
209
+
210
+
211
+ def railfence_encrypt(text: str, rails: int) -> str:
212
+ if rails <= 1:
213
+ return text
214
+ rows = [[] for _ in range(rails)]
215
+ for ch, rail in zip(text, _rail_pattern(len(text), rails)):
216
+ rows[rail].append(ch)
217
+ return "".join("".join(row) for row in rows)
218
+
219
+
220
+ def railfence_decrypt(text: str, rails: int) -> str:
221
+ if rails <= 1:
222
+ return text
223
+ pattern = _rail_pattern(len(text), rails)
224
+ counts = Counter(pattern)
225
+ rows: List[List[str]] = []
226
+ index = 0
227
+ for rail in range(rails):
228
+ size = counts[rail]
229
+ rows.append(list(text[index:index + size]))
230
+ index += size
231
+ pointers = [0] * rails
232
+ out = []
233
+ for rail in pattern:
234
+ out.append(rows[rail][pointers[rail]])
235
+ pointers[rail] += 1
236
+ return "".join(out)
237
+
238
+
239
+ def break_railfence(text: str, max_rails: int = 12, top: int = 5) -> List[Candidate]:
240
+ results = []
241
+ for rails in range(2, max_rails + 1):
242
+ if rails >= len(text):
243
+ break
244
+ plain = railfence_decrypt(text, rails)
245
+ results.append(
246
+ Candidate(plain, "railfence", {"rails": rails}, score_text(plain))
247
+ )
248
+ results.sort(key=lambda c: c.score, reverse=True)
249
+ return results[:top]
250
+
251
+
252
+ # ---------------------------------------------------------------------------
253
+ # Simple substitution (best-effort hill climb)
254
+ # ---------------------------------------------------------------------------
255
+
256
+ def substitution_decrypt(text: str, mapping) -> str:
257
+ """Decrypt with a cipher-letter -> plain-letter mapping.
258
+
259
+ ``mapping`` may be a 26-character string where position *i* is the plain
260
+ letter for ciphertext letter ``ALPHABET[i]``, or a dict.
261
+ """
262
+ if isinstance(mapping, str):
263
+ if len(mapping) != 26:
264
+ raise ValueError("substitution key must be 26 letters")
265
+ table: Dict[str, str] = {ALPHABET[i]: mapping[i].lower() for i in range(26)}
266
+ else:
267
+ table = {str(k).lower(): str(v).lower() for k, v in mapping.items()}
268
+ out = []
269
+ for ch in text:
270
+ low = ch.lower()
271
+ if low in table:
272
+ plain = table[low]
273
+ out.append(plain.upper() if ch.isupper() else plain)
274
+ else:
275
+ out.append(ch)
276
+ return "".join(out)
277
+
278
+
279
+ def substitution_encrypt(text: str, mapping) -> str:
280
+ """Encrypt with a cipher-letter -> plain-letter mapping (inverse of decrypt)."""
281
+ if isinstance(mapping, str):
282
+ if len(mapping) != 26:
283
+ raise ValueError("substitution key must be 26 letters")
284
+ table = {ALPHABET[i]: mapping[i].lower() for i in range(26)}
285
+ else:
286
+ table = {str(k).lower(): str(v).lower() for k, v in mapping.items()}
287
+ inverse = {plain: cipher for cipher, plain in table.items()}
288
+ out = []
289
+ for ch in text:
290
+ low = ch.lower()
291
+ if low in inverse:
292
+ cipher = inverse[low]
293
+ out.append(cipher.upper() if ch.isupper() else cipher)
294
+ else:
295
+ out.append(ch)
296
+ return "".join(out)
297
+
298
+
299
+ def _key_score(key, trigrams, table, floor) -> float:
300
+ index = _ALPHA_INDEX
301
+ total = 0.0
302
+ for (a, b, c), count in trigrams:
303
+ total += count * table.get(
304
+ key[index[a]] + key[index[b]] + key[index[c]], floor
305
+ )
306
+ return total
307
+
308
+
309
+ def _anneal(key, trigrams, rng, iterations: int, table, floor):
310
+ """Simulated-annealing swap search over the 26-letter key."""
311
+ index = _ALPHA_INDEX
312
+ current = _key_score(key, trigrams, table, floor)
313
+ best_score, best_key = current, list(key)
314
+
315
+ for step in range(iterations):
316
+ i, j = rng.randrange(26), rng.randrange(26)
317
+ if i == j:
318
+ continue
319
+ affected = [
320
+ (a, b, c, count)
321
+ for (a, b, c), count in trigrams
322
+ if i in (index[a], index[b], index[c])
323
+ or j in (index[a], index[b], index[c])
324
+ ]
325
+
326
+ def local_score():
327
+ return sum(
328
+ count * table.get(
329
+ key[index[a]] + key[index[b]] + key[index[c]], floor
330
+ )
331
+ for a, b, c, count in affected
332
+ )
333
+
334
+ before = local_score()
335
+ key[i], key[j] = key[j], key[i]
336
+ after = local_score()
337
+
338
+ accept = after >= before
339
+ if not accept:
340
+ temperature = max(0.02, 0.5 * (1.0 - step / max(1, iterations)))
341
+ accept = rng.random() < math.exp((after - before) / max(1e-9, temperature * 4))
342
+ if accept:
343
+ current += after - before
344
+ if current > best_score:
345
+ best_score, best_key = current, list(key)
346
+ else:
347
+ key[i], key[j] = key[j], key[i]
348
+
349
+ return best_key
350
+
351
+
352
+ def break_substitution(
353
+ text: str,
354
+ restarts: int = 5,
355
+ iterations: int = 10000,
356
+ seed: int = 0,
357
+ top: int = 3,
358
+ ) -> List[Candidate]:
359
+ """Best-effort substitution solver using an English trigram model.
360
+
361
+ Substitution needs a fair amount of text to solve reliably (a couple of
362
+ hundred letters is comfortable; a short greeting is not). When it is not
363
+ confident the candidate list shows the alternatives, so treat the result
364
+ as a suggestion and verify it by reading.
365
+ """
366
+ sample = text[:2000]
367
+ letters = [c for c in sample.lower() if c in _ALPHA_INDEX]
368
+ if len(letters) < 30:
369
+ return []
370
+
371
+ trigrams = list(Counter(zip(letters, letters[1:], letters[2:])).items())
372
+ index = _ALPHA_INDEX
373
+ table, floor = log_table()
374
+
375
+ frequencies = Counter(letters)
376
+ by_cipher_frequency = sorted(ALPHABET, key=lambda c: (-frequencies[c], c))
377
+ by_english_frequency = sorted(ALPHABET, key=lambda c: -ENGLISH_FREQ[c])
378
+ seed_key = ["a"] * 26
379
+ for cipher_letter, plain_letter in zip(by_cipher_frequency, by_english_frequency):
380
+ seed_key[index[cipher_letter]] = plain_letter
381
+
382
+ rng = random.Random(seed)
383
+ solved = []
384
+ for restart in range(max(1, restarts)):
385
+ key = list(seed_key)
386
+ # Later restarts start a few swaps away from the frequency guess.
387
+ for _ in range(min(restart, 6)):
388
+ a, b = rng.randrange(26), rng.randrange(26)
389
+ key[a], key[b] = key[b], key[a]
390
+ best_key = _anneal(key, trigrams, rng, iterations, table, floor)
391
+ solved.append(
392
+ (_key_score(best_key, trigrams, table, floor), "".join(best_key))
393
+ )
394
+
395
+ results = []
396
+ seen = set()
397
+ for _, key in sorted(solved, reverse=True):
398
+ if key in seen:
399
+ continue
400
+ seen.add(key)
401
+ plain = substitution_decrypt(sample, key)
402
+ results.append(
403
+ Candidate(plain, "substitution", {"key": key}, score_text(plain))
404
+ )
405
+ return results[:top]
406
+
407
+
408
+ # ---------------------------------------------------------------------------
409
+ # No-passphrase entry point used by auto-detect
410
+ # ---------------------------------------------------------------------------
411
+
412
+ def break_classical(text: str, top: int = 5) -> List[Candidate]:
413
+ """Run every classical breaker on ``text`` and return the best results."""
414
+ results: List[Candidate] = []
415
+ results.extend(break_caesar(text, top=top))
416
+ results.extend(break_atbash(text))
417
+ results.extend(break_vigenere(text, top=top))
418
+ results.extend(break_railfence(text, top=top))
419
+ # Substitution is the slowest, so only attempt it on text that could
420
+ # plausibly contain enough English signal.
421
+ if 40 <= len(text) <= 2000:
422
+ results.extend(
423
+ break_substitution(text, restarts=4, iterations=800, top=2)
424
+ )
425
+ results.sort(key=lambda c: c.score, reverse=True)
426
+ return results[:top]