ui: verify the ADM PIN from the matched card preset (v2.7.8)

The preset ADM key was stored but never used: the header badge showed
whether a key exists and whether the card was verified, yet the only way
to verify was the pySim command line.

- POST /api/verify-adm builds the TS 102 221 VERIFY itself (CHV number
  from the card model, short keys padded to 8 bytes with 'f') so the raw
  SW is reported: 63Cx -> attempts_left, 6983/9804 -> blocked, 6982 ->
  security error.  The key is never stored and is redacted from request
  logs.
- PWA: the header ADM badge is clickable when the matched preset has a
  key; a failed file-manager read/write (6982/9804) shows a Verify ADM
  button next to the error.  Every retry after a failure asks for
  confirmation and shows the remaining attempts (stronger text on the
  last attempt); a blocked ADM disables both entry points until the card
  session changes.  No automatic retries.
- tests: tests/test_adm_verify.py (fake scc, APDU/SW mapping, redaction)
  and frontend/tests/adm_verify.test.js (retry prompt, SW classifier,
  wiring) + card_state indicator expectations
- docs/api.md, help EN/RU, AGENTS; version trio 2.7.8; sw cache v211

frontend/help-ru.html

@@ -356,6 +356,7 @@
 		<li><strong>Редактировать</strong> — изменение hex-данных, <strong>Сохранить</strong> для записи (или <strong>Отмена</strong>)</li>
 		<li><strong>Данные как на карте / Декодированные данные</strong> — переключение между hex-дампом и таблицей декодированных полей (клиентские декодеры EF: IMSI, ICCID, SPN, списки PLMN, LOCI/PSLOCI/EPSLOCI, ADN/MSISDN, таблицы сервисов, SUME, …); серверный pySim JSON того же чтения остаётся доступен в свёрнутом блоке <em>pySim JSON (сервер)</em></li>
 		<li><strong>Проверить все файлы</strong> — обход всего дерева (включая пользовательские файлы) с пометкой каждого элемента: есть (обычный вид) или нет (красный ✗, без стрелки разворачивания); существующие пустые DF показывают <code class="font-mono text-sm">(пусто)</code>. Отображается прогресс <em>N / всего</em>, обход можно остановить; в конце — сводка «есть/нет». Файлы проверяются только при разворачивании или проверке — просмотр остаётся ленивым.</li>
+		<li><strong>ADM</strong> — файлы, требующие администраторский PIN, возвращают <code class="font-mono text-sm">6982</code>/<code class="font-mono text-sm">9804</code>; если в подходящей предустановке карты (тот же ICCID) есть ключ ADM, рядом с ошибкой появляется кнопка <strong>«Проверить ADM»</strong>, а значок в заголовке (<code class="font-mono text-sm">ADM ✓/✗ ⚿</code>) становится кликабельным. Каждый неверный ключ расходует попытку: остаток показывается, а повторная попытка требует подтверждения. Заблокированный ADM здесь не восстановить — нужен ключ разблокировки карты.</li>
 	</ul>
 
 	<h3 id="pysim-cmdline" class="text-lg font-medium mb-2">6.2 Командная строка pySim</h3>

frontend/help.html

@@ -356,6 +356,7 @@
 		<li><strong>Edit</strong> — modify hex data, <strong>Save</strong> to write back (or <strong>Cancel</strong>)</li>
 		<li><strong>Raw / Decoded</strong> — toggle between the hex dump and a decoded field table (client-side EF decoders: IMSI, ICCID, SPN, PLMN lists, LOCI/PSLOCI/EPSLOCI, ADN/MSISDN, service tables, SUME, …); the server-side pySim JSON of the same read stays available in the collapsed <em>pySim JSON (server)</em> disclosure</li>
 		<li><strong>Probe all files</strong> — walks the whole tree (including custom files) and marks every entry present (normal) or absent (red ✗, no expand arrow); empty-but-present DFs show <code class="font-mono text-sm">(empty)</code>. Shows progress <em>N / total</em>, can be stopped, and finishes with a present/absent summary. Files are only verified when expanded or probed — browsing stays lazy.</li>
+		<li><strong>ADM</strong> — files that need the administrator PIN fail with <code class="font-mono text-sm">6982</code>/<code class="font-mono text-sm">9804</code>; if the matching card preset (same ICCID) carries an ADM key, a <strong>Verify ADM</strong> button appears next to the error and the header badge (<code class="font-mono text-sm">ADM ✓/✗ ⚿</code>) becomes clickable. Every wrong key consumes an attempt: the remaining attempts are shown and a retry asks for confirmation. A blocked ADM cannot be recovered here — it needs the card&rsquo;s unblock key.</li>
 	</ul>
 
 	<h3 id="pysim-cmdline" class="text-lg font-medium mb-2">6.2 pySim command line</h3>

frontend/index.html

@@ -1413,7 +1413,7 @@
 // ===== Version =====
 // Single source of truth for the PWA version: shown in the header and used
 // by the server version check in pysimConnect().
-const SIMPLE_VERSION = '2.7.7';
+const SIMPLE_VERSION = '2.7.8';
 document.getElementById('app-version').textContent = 'v' + SIMPLE_VERSION;
 
 // ===== Tab switching =====
@@ -4858,6 +4858,12 @@ let _pysimCardEquipped = false;
 let _pysimEquipping = false;
 let _pysimAdmVerified = null;      // null = no card session
 let _pysimAdmKey = null;           // ADM key present in the matching preset
+let _pysimAdmCanVerify = false;    // indicator clickable (card + preset key, not blocked)
+let _pysimAdmAttemptsLeft = null;  // last 63Cx result for this card session
+let _pysimAdmBlocked = false;      // 6983/9804 — no further tries until the session changes
+let _pysimAdmVerifying = false;    // verify request in flight (double-click guard)
+let _pysimAdmStateKey = null;      // last rendered indicator state
+let _pysimLastStatus = null;       // last /api/status payload (for local repaints)
 let _pysimCardIccid = null;        // EF.ICCID digits of the equipped card (null = unknown)
 let _pysimHeaderIccid = undefined; // last value rendered in the header indicator
 let _pysimHeaderScp80 = undefined; // last SCP80/SCP81 marker state
@@ -4934,17 +4940,24 @@ function pysimApplyAvailability() {
 // Compact ADM state next to the header's card indicator: "ADM ✓" when the
 // administrator PIN was verified (pySim rs.adm_verified), "ADM ✗" otherwise;
 // a trailing key glyph (⚿) marks that the matching card preset carries an ADM
-// key. Hidden without a card session; only rewrites the DOM when the state
-// changes (the 2s /api/status poll calls this on every update).
+// key.  With a key present the badge is clickable and verifies it on demand;
+// hidden without a card session.  Only rewrites the DOM when the state changes
+// (the 2s /api/status poll calls this on every update).
 function pysimUpdateAdmIndicator(status) {
 	const el = document.getElementById('state-indicator-adm');
 	if (!el) return;
 	const verified = (status && status.connected) ? !!status.adm_verified : null;
 	const key = verified === null ? null : cardsAdmPresent(cardsMatchedPreset());
-	if (verified === _pysimAdmVerified && key === _pysimAdmKey) return;
+	const canVerify = key === true && !_pysimAdmBlocked && !_pysimAdmVerifying;
+	const stateKey = [verified, key, canVerify, _pysimAdmAttemptsLeft, _pysimAdmBlocked].join('|');
+	if (stateKey === _pysimAdmStateKey) return;
+	_pysimAdmStateKey = stateKey;
 	_pysimAdmVerified = verified;
 	_pysimAdmKey = key;
-	el.classList.remove('text-emerald-600', 'dark:text-emerald-400', 'text-red-500');
+	_pysimAdmCanVerify = canVerify;
+	el.classList.remove('text-emerald-600', 'dark:text-emerald-400', 'text-red-500', 'cursor-pointer');
+	el.removeAttribute('onclick');
+	el.removeAttribute('role');
 	if (verified === null) {
 		el.classList.add('hidden');
 		el.removeAttribute('title');
@@ -4954,9 +4967,101 @@ function pysimUpdateAdmIndicator(status) {
 	el.classList.remove('hidden');
 	el.classList.add(verified ? 'text-emerald-600' : 'text-red-500');
 	if (verified) el.classList.add('dark:text-emerald-400');
-	el.setAttribute('title', t(key
-		? (verified ? 'ADM key in the card preset — verified' : 'ADM key in the card preset — not verified')
-		: (verified ? 'Verified — no ADM key in the card preset' : 'No ADM key in the card preset — not verified')));
+	let tip;
+	if (key && _pysimAdmBlocked) {
+		tip = t('ADM is blocked — unblock the card to try again');
+	} else if (key) {
+		tip = t('ADM key in the card preset — click to verify');
+		if (_pysimAdmAttemptsLeft !== null) tip += ' — ' + _pysimAdmAttemptsLeft + ' ' + t('attempt(s) left');
+	} else {
+		tip = t(verified ? 'Verified — no ADM key in the card preset' : 'No ADM key in the card preset — not verified');
+	}
+	el.setAttribute('title', tip);
+	if (canVerify) {
+		el.classList.add('cursor-pointer');
+		el.setAttribute('role', 'button');
+		el.setAttribute('onclick', 'pysimVerifyAdm()');
+	}
+}
+
+// Confirmation text before a repeated ADM attempt (null on the first try).
+// Every wrong key consumes an attempt; a blocked ADM is unrecoverable here.
+function pysimAdmRetryPrompt(attemptsLeft) {
+	if (attemptsLeft === null || attemptsLeft === undefined) return null;
+	if (attemptsLeft <= 1) return t('This is the last attempt before the ADM is blocked. Try again?');
+	return t('ADM verification already failed') + ' — ' + attemptsLeft + ' ' + t('attempt(s) left')
+		+ '. ' + t('A wrong key can block the ADM permanently. Try again?');
+}
+
+// Verify the ADM PIN from the matched card preset (top-bar indicator or the
+// file manager's security-error hint).  `statusEl` receives the result inline
+// when given; otherwise the card status line is used.  Never retries by
+// itself: every attempt after a failure is confirmed first.
+async function pysimVerifyAdm(statusEl) {
+	if (_pysimAdmVerifying) return;
+	const preset = cardsMatchedPreset();
+	if (!cardsAdmPresent(preset)) return;
+	const el = statusEl || document.getElementById('pysim-status');
+	if (_pysimAdmBlocked) {
+		if (el) el.textContent = t('ADM is blocked — unblock the card to try again');
+		return;
+	}
+	const prompt = pysimAdmRetryPrompt(_pysimAdmAttemptsLeft);
+	if (prompt && !confirm(prompt)) return;
+	_pysimAdmVerifying = true;
+	if (el) el.textContent = t('Verifying ADM...');
+	let verifiedOverride;
+	try {
+		const data = await pysimFetch('/api/verify-adm', { adm: preset.adm });
+		if (data.ok) {
+			_pysimAdmAttemptsLeft = null;
+			_pysimAdmBlocked = false;
+			verifiedOverride = true;
+			if (el) el.textContent = t('ADM verified');
+		} else if (data.blocked) {
+			_pysimAdmBlocked = true;
+			if (el) el.textContent = t('ADM is blocked');
+		} else if (typeof data.attempts_left === 'number') {
+			_pysimAdmAttemptsLeft = data.attempts_left;
+			if (el) el.textContent = t('ADM verification failed') + ' — ' + data.attempts_left + ' ' + t('attempt(s) left');
+		} else if (el) {
+			el.textContent = 'SW: ' + (data.sw || '?') + ' — ' + (data.error || 'Error');
+		}
+	} catch (e) {
+		if (el) el.textContent = t('Error') + ': ' + e.message;
+	} finally {
+		_pysimAdmVerifying = false;
+		const base = _pysimLastStatus || { connected: true };
+		pysimUpdateAdmIndicator(Object.assign({}, base,
+			verifiedOverride === undefined ? {} : { adm_verified: verifiedOverride }));
+	}
+}
+
+// SW codes that mean "verify the ADM PIN first" (access condition / security).
+function pysimAdmSecuritySw(sw) {
+	return sw === '6982' || sw === '9804';
+}
+
+// A new card session (equip/removal) forgets the attempt/blocked state: the
+// counter belongs to the physical card that was just replaced or reset.
+function pysimAdmResetAttempts() {
+	_pysimAdmAttemptsLeft = null;
+	_pysimAdmBlocked = false;
+	_pysimAdmStateKey = null;
+}
+
+// Render a failed file-manager operation; when the SW is a security error and
+// the matched preset carries an ADM, offer verification inline (the key is
+// only ever sent on an explicit click).
+function pysimFsShowError(statusEl, sw, error) {
+	statusEl.textContent = 'SW: ' + (sw || '?') + ' — ' + (error || 'Error');
+	if (!pysimAdmSecuritySw(sw) || !cardsAdmPresent(cardsMatchedPreset()) || _pysimAdmBlocked) return;
+	const btn = document.createElement('button');
+	btn.textContent = t('Verify ADM');
+	btn.className = 'ml-2 px-2 py-0.5 text-xs rounded bg-amber-600 text-white hover:bg-amber-700';
+	btn.onclick = () => pysimVerifyAdm(statusEl);
+	statusEl.appendChild(document.createTextNode(' '));
+	statusEl.appendChild(btn);
 }
 
 // EF.ICCID digits of the equipped card, printed next to the card image
@@ -7082,7 +7187,7 @@ async function pysimFsRead() {
 		body.mode = 'raw';   // decoding is client-side (works offline in snapshots too)
 		const data = await pysimFetch('/api/read', body);
 		if (!data.success) {
-			statusEl.textContent = 'SW: ' + (data.sw || '?') + ' — ' + (data.error || 'Error');
+			pysimFsShowError(statusEl, data.sw, data.error);
 			return;
 		}
 		statusEl.textContent = 'SW: ' + data.sw + ' OK';
@@ -7209,7 +7314,7 @@ async function pysimFsSave() {
 				pysimFsCancel();
 				pysimFsRead();
 			} else {
-				statusEl.textContent = 'SW: ' + (data.sw || '?') + ' — ' + (data.error || 'Error');
+				pysimFsShowError(statusEl, data.sw, data.error);
 			}
 		} else {
 			// Record file
@@ -7227,7 +7332,7 @@ async function pysimFsSave() {
 					body.record_nr = parseInt(num);
 					const data = await pysimFetch('/api/write', body);
 					if (!data.success) {
-						statusEl.textContent = 'SW: ' + (data.sw || '?') + ' — ' + (data.error || 'Error') + ' (record ' + num + ')';
+						pysimFsShowError(statusEl, data.sw, (data.error || 'Error') + ' (record ' + num + ')');
 						return;
 					}
 				}
@@ -8054,6 +8159,7 @@ async function pysimResetCardData(refreshStatus) {
 function pysimCardStateUpdate(status) {
 	if (!status || typeof status.connected !== 'boolean') return;
 	_pysimServerAvailable = true;
+	_pysimLastStatus = status;
 	_pysimCardEquipped = !!status.connected;
 	_pysimEquipping = !!status.equipping;
 	_pysimCardIccid = status.connected ? (status.iccid || null) : null;
@@ -8071,6 +8177,7 @@ function pysimCardStateUpdate(status) {
 	const sessionChanged = _pysimCardSession !== null
 		&& status.card_session !== undefined && status.card_session !== _pysimCardSession;
 	if (status.card_session !== undefined) _pysimCardSession = status.card_session;
+	if (sessionChanged) pysimAdmResetAttempts();
 	if (status.connected) {
 		pysimSetConnected(true);
 		pysimResetCardData(true);
@@ -13313,6 +13420,16 @@ const LANG_RU = {
 	'ADM not verified': 'ADM не подтверждён',
 	'ADM key in the card preset — verified': 'Ключ ADM в предустановке — подтверждён',
 	'ADM key in the card preset — not verified': 'Ключ ADM в предустановке — не подтверждён',
+	'ADM key in the card preset — click to verify': 'Ключ ADM в предустановке — нажмите для проверки',
+	'Verify ADM': 'Проверить ADM',
+	'Verifying ADM...': 'Проверка ADM...',
+	'ADM verification failed': 'Проверка ADM не удалась',
+	'ADM verification already failed': 'Проверка ADM уже завершилась неудачей',
+	'attempt(s) left': 'попыток осталось',
+	'A wrong key can block the ADM permanently. Try again?': 'Неверный ключ может навсегда заблокировать ADM. Попробовать снова?',
+	'This is the last attempt before the ADM is blocked. Try again?': 'Это последняя попытка — неверный ключ заблокирует ADM. Попробовать снова?',
+	'ADM is blocked': 'ADM заблокирован',
+	'ADM is blocked — unblock the card to try again': 'ADM заблокирован — разблокируйте карту, чтобы повторить',
 	'Verified — no ADM key in the card preset': 'Подтверждён — ключа ADM в предустановке нет',
 	'No ADM key in the card preset — not verified': 'Ключа ADM в предустановке нет — не подтверждён',
 	'SCP80 preset complete': 'Предустановка SCP80 заполнена',

frontend/sw.js

@@ -1,4 +1,4 @@
-const CACHE = 'simple-v210';
+const CACHE = 'simple-v211';
 const URLS = [
   'index.html',
   'help.html',

frontend/tests/adm_verify.test.js

@@ -0,0 +1,65 @@
+const { test } = require('node:test');
+const assert = require('node:assert');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const html = fs.readFileSync(path.join(__dirname, '..', 'index.html'), 'utf8');
+
+function extractFunc(src, name) {
+	const re = new RegExp('function\\s+' + name + '\\s*\\([^)]*\\)\\s*\\{');
+	const m = re.exec(src);
+	if (!m) throw new Error('function ' + name + ' not found');
+	let i = m.index + m[0].length - 1;
+	let depth = 0;
+	for (; i < src.length; i++) {
+		if (src[i] === '{') depth++;
+		else if (src[i] === '}') {
+			depth--;
+			if (depth === 0) break;
+		}
+	}
+	return src.slice(m.index, i + 1);
+}
+
+let code = '';
+for (const fn of ['pysimAdmRetryPrompt', 'pysimAdmSecuritySw']) {
+	code += extractFunc(html, fn) + '\n';
+}
+code += 'globalThis.t = s => s;\n';
+eval(code);
+
+test('pysimAdmRetryPrompt is silent on the first try', () => {
+	assert.strictEqual(pysimAdmRetryPrompt(null), null);
+	assert.strictEqual(pysimAdmRetryPrompt(undefined), null);
+});
+
+test('pysimAdmRetryPrompt warns with the remaining attempts', () => {
+	const msg = pysimAdmRetryPrompt(3);
+	assert.ok(msg.includes('3'), msg);
+	assert.ok(msg.includes('attempt(s) left'), msg);
+	assert.ok(msg.includes('block'), msg);
+	assert.ok(msg.includes('Try again?'), msg);
+});
+
+test('pysimAdmRetryPrompt uses the stronger last-attempt text', () => {
+	for (const left of [1, 0]) {
+		const msg = pysimAdmRetryPrompt(left);
+		assert.ok(msg.includes('last attempt'), left + ': ' + msg);
+		assert.ok(msg.includes('Try again?'), msg);
+	}
+});
+
+test('pysimAdmSecuritySw flags only the access-condition SWs', () => {
+	for (const sw of ['6982', '9804']) assert.ok(pysimAdmSecuritySw(sw), sw);
+	for (const sw of ['9000', '6985', '63C2', '', null, undefined]) {
+		assert.ok(!pysimAdmSecuritySw(sw), String(sw));
+	}
+});
+
+test('file-manager security failures route through the ADM hint', () => {
+	// no raw SW error rendering is left (all three sites use the hint helper)
+	assert.ok(!/statusEl\.textContent = 'SW: ' \+ \(data\.sw/.test(html), 'raw SW error rendering is gone');
+	assert.strictEqual((html.match(/pysimFsShowError\(statusEl, data\.sw/g) || []).length, 3);
+	assert.ok(html.includes("btn.textContent = t('Verify ADM')"));
+	assert.ok(html.includes("el.setAttribute('onclick', 'pysimVerifyAdm()')"));
+});

frontend/tests/card_state.test.js

@@ -25,6 +25,9 @@ let code = 'var _pysimCardStateKey = null;\nvar _pysimCardSession = null;\n'
 	+ 'var _pysimServerAvailable = null;\nvar _pysimCardEquipped = false;\n'
 	+ 'var _pysimProactiveSeq = null;\nvar _pysimStkSig = null;\nvar _pysimAdmVerified = null;\n'
 	+ 'var _pysimAdmKey = null;\n'
+	+ 'var _pysimAdmCanVerify = false;\nvar _pysimAdmAttemptsLeft = null;\n'
+	+ 'var _pysimAdmBlocked = false;\nvar _pysimAdmVerifying = false;\n'
+	+ 'var _pysimAdmStateKey = null;\nvar _pysimLastStatus = null;\n'
 	+ 'var _pysimHeaderIccid = undefined;\nvar _pysimHeaderScp80 = undefined;\nvar _pysimHeaderScp81 = undefined;\n'
 	+ 'var _cardsAutoIccid = null;\nvar _pysimCardIccid = null;\n';
 code += extractFunc(html, 'pysimCardStateUpdate') + '\n';
@@ -33,6 +36,7 @@ code += extractFunc(html, 'pysimControlDisabled') + '\n';
 code += extractFunc(html, 'pysimProactiveSeqChanged') + '\n';
 code += extractFunc(html, 'pysimStkStatusChanged') + '\n';
 code += extractFunc(html, 'pysimUpdateAdmIndicator') + '\n';
+code += extractFunc(html, 'pysimAdmResetAttempts') + '\n';
 code += extractFunc(html, 'pysimUpdateIccidIndicator') + '\n';
 code += extractFunc(html, 'pysimUpdatePresetIndicator') + '\n';
 code += extractFunc(html, 'pysimUpdatePresetIndicators') + '\n';
@@ -72,6 +76,12 @@ function setup() {
 	_pysimProactiveSeq = null;
 	_pysimAdmVerified = null;
 	_pysimAdmKey = null;
+	_pysimAdmCanVerify = false;
+	_pysimAdmAttemptsLeft = null;
+	_pysimAdmBlocked = false;
+	_pysimAdmVerifying = false;
+	_pysimAdmStateKey = null;
+	_pysimLastStatus = null;
 	_pysimHeaderIccid = undefined;
 	_pysimHeaderScp80 = undefined;
 	_pysimHeaderScp81 = undefined;
@@ -272,11 +282,12 @@ test('the ADM badge marks an ADM key in the matching preset', () => {
 	globalThis.cardsFindByIccid = () => 0;
 	pysimCardStateUpdate(st({ adm_verified: true }));
 	assert.strictEqual(adm.textContent, 'ADM ✓ ⚿');
-	assert.strictEqual(adm.title, 'ADM key in the card preset — verified');
+	assert.strictEqual(adm.title, 'ADM key in the card preset — click to verify');
+	assert.ok(adm.classes.has('cursor-pointer'), 'the badge is clickable with a preset key');
 	// key present, verification lost (e.g. card reset)
 	pysimCardStateUpdate(st({ adm_verified: false }));
 	assert.strictEqual(adm.textContent, 'ADM ✗ ⚿');
-	assert.strictEqual(adm.title, 'ADM key in the card preset — not verified');
+	assert.strictEqual(adm.title, 'ADM key in the card preset — click to verify');
 	// verified manually, preset has no ADM -> no key glyph
 	globalThis.cards = [];
 	pysimCardStateUpdate(st({ adm_verified: true }));