Improve documentation and in-app messaging when Specter-Javacard is bricked due to wrong PIN attempts (Plus review behavior)

[3rdIteration]

1. Improved documentation to mention what happens when Specter-Javacard PIN is incorrect and the applet bricked
2. Improved feedback messages on the Specter Device when Specter-Javacard is bricked due to wrong PIN.

[netlify]

✅ Deploy Preview for specter-diy-docs ready!

Name	Link
🔨 Latest commit	143eaf8
🔍 Latest deploy log	https://app.netlify.com/projects/specter-diy-docs/deploys/691660ff4a02bf0008053efa
😎 Deploy Preview	https://deploy-preview-317--specter-diy-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[3rdIteration]

This was something that I noticed when some first-time users were giving Specter DIY a go at the DIY retreat, some folk would mess around and end up locking the Smartcard, but the current workflow was quite confusing both in terms of how everything behaves if you boot with a locked card, the messaging in the app as well as the documentation.

One question to discuss here is whether the "wipe device" button should be offered if the user boots with a locked smartcard, or whether this should be reserved only for the specific "session" where the user enters the wrong pin and bricks everything. (I think some information should be offered when you insert a bricked card, before anything is entered)

A second question is whether, given a user can use multiple different smartcards with the device, it's overkill to offer to wipe the whole thing if you brick a smartcard. (Perhaps just show a warning only, reserving the wipe process for if the device PIN is entered incorrectly the max number of times) Wiping on smartcard lock seems like overkill...

The current behavior in this PR is that a new, more verbose message is displayed when booted with a bricked Smartcard, with a button offering to Wipe Specter Device

[3rdIteration]

Feedback from discussion, will remove the button to reset the device as this will confuse users, especially given that this factory resetting the specter device doesn't unlock the smartcard.

Will modify and update the PR

[k9ert]

@Schnuartz please test!

[Schnuartz]

I sacrificed a Smartcard and tested it.

This is the new text that is shown:


Now it also was not possible for me to press ok. I needed to restart. Not sure how it was before.

Don't have a SeedSigner with Smartcard
Applet yet. And I was not able unbrick the Smartcard:

[3rdIteration]

@Schnuartz it's just the same process that you use to flash the applet on existing smartcard. It looks like your PC has multiple readers, so you just need to specify the reader in the command you are using. (Even if you specify part of its name with the -r argument)

[Schnuartz]

Made a mistake here this is the actual error message. Not the one I posted previosly:

[Schnuartz]

So now I was finally able to unbrick it in windows.. Using Kimi 2.5. Not sure if that was the easierst way, but I plugged in the QR-Scanner and the Smarcard. And it did it for me. After that it explained how he did it:

NXP J3H145 Smartcard Refurbishment Guide

Recovering a "bricked" Specter-DIY MemoryCard applet on an NXP J3H145 Java Card.

---

1. Hardware Identification

Attribute	Value
Card Type	NXP J3H145
Platform	JCOP3 (Java Card Operating Platform v3)
Java Card Version	3.0.4
GlobalPlatform	2.2.1
EEPROM	145KB user memory
Security	Common Criteria EAL5+ certified
Interface	Dual (contact + contactless)
Default ISD Keys	404142434445464748494A4B4C4D4E4F

J3H145 vs JCOP3

Term	Meaning
JCOP3	Java Card Operating Platform version 3 (software platform)
J3H145	NXP's specific chip model (hardware) that runs JCOP3

---

2. Problem Diagnosis

Symptom: Card "bricked" after too many wrong PIN attempts.

Technical Root Cause

• Specter-DIY's MemoryCardApplet stores a PIN retry counter in applet instance memory
• After 3 consecutive wrong PIN entries → counter reaches 0
• Applet enters PERMANENTLY_LOCKED state
• ISD (Issuer Security Domain) remains fully operational

Why It's Recoverable

┌─────────────────────────────────────────┐
│  ISD (Card Operating System)            │  ← ALWAYS ACCESSIBLE
│  AID: A000000151000000                  │     (Factory keys)
│  Status: OP_READY                       │
├─────────────────────────────────────────┤
│  Package: B00B5111CB                    │
│  └─ Applet: B00B5111CB01               │  ← LOCKED (PIN=0)
│     State: PERMANENTLY_LOCKED           │     Delete & replace!
└─────────────────────────────────────────┘

The ISD sits above the applet layer — even when the applet is permanently locked, the card OS remains accessible with factory keys. This is true for any GlobalPlatform-compliant Java Card.

Compatible Cards

The same refurbishment process works on any GlobalPlatform-compliant Java Card:

• NXP: J2A080, J2D081, J3A041, J3H145, J3R180, J3R200
• G&D: Smartcafe
• Oberthur: Cosmo

All share: ISD architecture, SCP02/SCP03 secure channel protocols, same APDU command set.

---

3. Required Tools

Tool	Purpose	Source
gp.jar	GlobalPlatform management	GlobalPlatformPro
ant-javacard.jar	Build CAP files	ant-javacard
JavaCard SDK 3.0.4+	CAP conversion	Oracle / NXP
Apache Ant	Build automation	ant.apache.org
pyscard (optional)	Low-level PC/SC debugging	pypi.org/project/pyscard

---

4. Refurbishment Procedure

Step 1: Verify Card Connectivity

java -jar gp.jar -l

Expected Output (Bricked State):

ISD: A000000151000000 (OP_READY)
APP: B00B5111CB01 (SELECTABLE) [LOCKED]
PKG: B00B5111CB (LOADED)

Success Criteria: ISD responds with OP_READY status.

---

Step 2: Authenticate to ISD

gp.jar automatically uses default test keys:

ENC: 404142434445464748494A4B4C4D4E4F
MAC: 404142434445464748494A4B4C4D4E4F
DEK: 404142434445464748494A4B4C4D4E4F

Secure Channel: gp.jar negotiates SCP02 or SCP03 with the ISD.

---

Step 3: Delete Locked Applet

java -jar gp.jar --delete B00B5111CB --force

Parameter	Value	Explanation
Target	B00B5111CB	Package AID (deletes all instances)
--force	Required	Bypass "active application" protection
APDU Sequence	DELETE → SELECT	GP 2.2.1 compliant

What happens:

1. gp.jar opens secure channel to ISD
2. Sends DELETE [AID=B00B5111CB] APDU
3. ISD marks package + applet instance as deleted
4. Garbage collection frees EEPROM memory

Success Indicator:

Warning: no keys given, using default test key 404142434445464748494A4B4C4D4E4F

(No error message = success)

---

Step 4: Reinstall Fresh Applet

java -jar gp.jar --install MemoryCard.cap

This installs a fresh MemoryCardApplet instance with a new PIN retry counter (reset to default).

---

Step 5: Verify Installation

java -jar gp.jar -l

Expected Output (Refurbished):

ISD: A000000151000000 (OP_READY)
APP: B00B5111CB01 (SELECTABLE)
PKG: B00B5111CB (LOADED)

The [LOCKED] flag should be gone.

---

5. Important Notes

• PIN lockout threshold: Up to 10 wrong attempts before permanent lockout (card-dependent, Specter-DIY default is 3)
• Data loss: Deleting the applet destroys all stored data (seeds, keys). This is a full wipe.
• ISD key security: Default keys (4041...4F) are test keys. Production cards should have personalized ISD keys.
• No hardware damage: This process is purely software-level. The J3H145 hardware is unaffected.

---

6. Relevance

This procedure was used to refurbish a J3H145 card for Specter-DIY PR #317 testing. The card is now fully operational with a fresh applet instance.

[3rdIteration]

So now I was finally able to unbrick it in windows.. Using Kimi 2.5. Not sure if that was the easierst way, but I plugged in the QR-Scanner and the Smarcard. And it did it for me. After that it explained how he did it:

NXP J3H145 Smartcard Refurbishment Guide

Recovering a "bricked" Specter-DIY MemoryCard applet on an NXP J3H145 Java Card.

1. Hardware Identification

Attribute Value
Card Type NXP J3H145
Platform JCOP3 (Java Card Operating Platform v3)
Java Card Version 3.0.4
GlobalPlatform 2.2.1
EEPROM 145KB user memory
Security Common Criteria EAL5+ certified
Interface Dual (contact + contactless)
Default ISD Keys 404142434445464748494A4B4C4D4E4F

J3H145 vs JCOP3

Term Meaning
JCOP3 Java Card Operating Platform version 3 (software platform)
J3H145 NXP's specific chip model (hardware) that runs JCOP3

2. Problem Diagnosis

Symptom: Card "bricked" after too many wrong PIN attempts.

Technical Root Cause

• Specter-DIY's MemoryCardApplet stores a PIN retry counter in applet instance memory
• After 3 consecutive wrong PIN entries → counter reaches 0
• Applet enters PERMANENTLY_LOCKED state
• ISD (Issuer Security Domain) remains fully operational

Why It's Recoverable

┌─────────────────────────────────────────┐
│  ISD (Card Operating System)            │  ← ALWAYS ACCESSIBLE
│  AID: A000000151000000                  │     (Factory keys)
│  Status: OP_READY                       │
├─────────────────────────────────────────┤
│  Package: B00B5111CB                    │
│  └─ Applet: B00B5111CB01               │  ← LOCKED (PIN=0)
│     State: PERMANENTLY_LOCKED           │     Delete & replace!
└─────────────────────────────────────────┘

The ISD sits above the applet layer — even when the applet is permanently locked, the card OS remains accessible with factory keys. This is true for any GlobalPlatform-compliant Java Card.

Compatible Cards

The same refurbishment process works on any GlobalPlatform-compliant Java Card:

• NXP: J2A080, J2D081, J3A041, J3H145, J3R180, J3R200
• G&D: Smartcafe
• Oberthur: Cosmo

All share: ISD architecture, SCP02/SCP03 secure channel protocols, same APDU command set.

3. Required Tools

Tool Purpose Source
gp.jar GlobalPlatform management GlobalPlatformPro
ant-javacard.jar Build CAP files ant-javacard
JavaCard SDK 3.0.4+ CAP conversion Oracle / NXP
Apache Ant Build automation ant.apache.org
pyscard (optional) Low-level PC/SC debugging pypi.org/project/pyscard

4. Refurbishment Procedure

Step 1: Verify Card Connectivity

java -jar gp.jar -l

Expected Output (Bricked State):

ISD: A000000151000000 (OP_READY)
APP: B00B5111CB01 (SELECTABLE) [LOCKED]
PKG: B00B5111CB (LOADED)

Success Criteria: ISD responds with OP_READY status.

Step 2: Authenticate to ISD

gp.jar automatically uses default test keys:

ENC: 404142434445464748494A4B4C4D4E4F
MAC: 404142434445464748494A4B4C4D4E4F
DEK: 404142434445464748494A4B4C4D4E4F

Secure Channel: gp.jar negotiates SCP02 or SCP03 with the ISD.

Step 3: Delete Locked Applet

java -jar gp.jar --delete B00B5111CB --force

Parameter Value Explanation
Target B00B5111CB Package AID (deletes all instances)
--force Required Bypass "active application" protection
APDU Sequence DELETE → SELECT GP 2.2.1 compliant
What happens:

1. gp.jar opens secure channel to ISD
2. Sends DELETE [AID=B00B5111CB] APDU
3. ISD marks package + applet instance as deleted
4. Garbage collection frees EEPROM memory

Success Indicator:

Warning: no keys given, using default test key 404142434445464748494A4B4C4D4E4F

(No error message = success)

Step 4: Reinstall Fresh Applet

java -jar gp.jar --install MemoryCard.cap

This installs a fresh MemoryCardApplet instance with a new PIN retry counter (reset to default).

Step 5: Verify Installation

java -jar gp.jar -l

Expected Output (Refurbished):

ISD: A000000151000000 (OP_READY)
APP: B00B5111CB01 (SELECTABLE)
PKG: B00B5111CB (LOADED)

The [LOCKED] flag should be gone.

5. Important Notes

• PIN lockout threshold: Up to 10 wrong attempts before permanent lockout (card-dependent, Specter-DIY default is 3)
• Data loss: Deleting the applet destroys all stored data (seeds, keys). This is a full wipe.
• ISD key security: Default keys (4041...4F) are test keys. Production cards should have personalized ISD keys.
• No hardware damage: This process is purely software-level. The J3H145 hardware is unaffected.

6. Relevance

This procedure was used to refurbish a J3H145 card for Specter-DIY PR #317 testing. The card is now fully operational with a fresh applet instance.

This is way overcomplicated and also confusing. You don't need Apache ant or anything like that, you just need to uninstall and reinstall the applet.