diff options
| -rw-r--r-- | README.md | 2 | ||||
| -rw-r--r-- | docs/TESTING.md | 2 | ||||
| -rw-r--r-- | docs/YOUR_STEPS.md | 300 |
3 files changed, 303 insertions, 1 deletions
@@ -13,6 +13,7 @@ A Garmin Connect IQ watch app that shows one-time passwords (TOTP, HOTP, and opt > - **Memory and speed:** a 100-entry import peaks at 45 % of the Forerunner 255S's memory instead of 56 %; QR mask scoring on packed rows; two job steps per tick on the 768 KB watches. > - **Watchdog safety:** every 2D encoder now handles the largest inputs the app accepts without being stopped by the watchdog, proven by `make watchdog` at twice the normal work per event. > - **Docs:** the [user guide](docs/USER_GUIDE.md) with the [known limitations](docs/USER_GUIDE.md#known-limitations). +> - **Your next steps:** [docs/YOUR_STEPS.md](docs/YOUR_STEPS.md), everything left for you before 1.0.0, in order. > > Waiting for you: the settings spike (`make spike`, [docs/SETTINGS_SPIKE.md](docs/SETTINGS_SPIKE.md)) and the [real-watch checklist](docs/TESTING.md#real-watch-checklist) with the 0.8.0 beta. The Phase 0 research, with sources, is in [docs/FEASIBILITY.md](docs/FEASIBILITY.md); the daily workflow is in [docs/DEVELOPER_GUIDE.md](docs/DEVELOPER_GUIDE.md). @@ -1025,6 +1026,7 @@ The simulator runs on your PC's CPU, so its timings don't represent a watch. In | --- | --- | | `README.md` | This plan, kept up to date as the project's overview | | [`docs/FEASIBILITY.md`](docs/FEASIBILITY.md) | Phase 0 findings with sources | +| `docs/YOUR_STEPS.md` | Your steps before 1.0.0: the settings spike, the on-watch tests and the results to send back | | `docs/USER_GUIDE.md` | Install the beta, import from Aegis, add codes, PIN and locking, daily use, moving to a new watch, troubleshooting | | `docs/DEVELOPER_GUIDE.md` | Repository layout, build, test and debug in Docker, adding a symbology or a device, coding conventions | | `docs/SECURITY.md` | Threat model, crypto choices and parameters, record formats, known limitations, how to report issues | diff --git a/docs/TESTING.md b/docs/TESTING.md index 73f89d5..c2c3e62 100644 --- a/docs/TESTING.md +++ b/docs/TESTING.md @@ -224,7 +224,7 @@ Tests never use real secrets or personal data. Fixtures are generated or hand-wr ## Real-watch checklist -Things the simulator can't verify, done by you on the Forerunner 70, with fake or test accounts only. 1.0.0 is tagged once every box is ticked (or a remaining item is recorded as a known limitation). The items were added milestone by milestone; M8 adds the release checks at the end. +Things the simulator can't verify, done by you on the Forerunner 70, with fake or test accounts only. 1.0.0 is tagged once every box is ticked (or a remaining item is recorded as a known limitation). The items were added milestone by milestone; M8 adds the release checks at the end. The same items in one step-by-step order, with fake test data and a results template: [YOUR_STEPS.md](YOUR_STEPS.md). - [ ] M1: install the settings spike from the Store beta and run tests A to H in [SETTINGS_SPIKE.md](SETTINGS_SPIKE.md); record the results there. - [ ] M4: sideload a debug build (`make build DEVICE=fr70`, then copy `build/debug/fr70.prg` to `GARMIN/APPS` over USB). Open the menu, choose "Debug: benchmark", and send me the numbers. They set the real PBKDF2 iteration count and the SHA-512 cost on your watch. diff --git a/docs/YOUR_STEPS.md b/docs/YOUR_STEPS.md new file mode 100644 index 0000000..c6b5d07 --- /dev/null +++ b/docs/YOUR_STEPS.md @@ -0,0 +1,300 @@ +<!-- + Author: cirakg & claude ai + Summary: Your step-by-step guide to everything left before 1.0.0: the settings spike, the on-watch tests with a debug build and the Store beta, and what to send back. +--> +# Your steps to 1.0.0 + +Everything that can be checked in Docker is done (0.8.0, `make ci` green). What's left needs your phone, your Forerunner 70 and your Garmin account. This page puts all of it in one order. It replaces reading the [real-watch checklist](TESTING.md#real-watch-checklist) item by item; every checklist item is covered here. + +**Rules for every step:** use only fake or test accounts and the fake secrets on this page. Never type a real secret into the app, the forms or the test pages. + +Total time: about 2.5 to 3 hours, which can be split across days at any part boundary. + +| Part | What | Time | +| --- | --- | --- | +| 1 | Preparation on the computer | 10 min | +| 2 | Garmin developer account | 10 min | +| 3 | Settings spike (M1) | 30 min | +| 4 | Debug build over USB: benchmark, demo entries, scanning | 40 min | +| 5 | Store beta 0.7.0, then the update to 0.8.0 | 20 min | +| 6 | Phone forms, glance, brightness on 0.8.0 | 45 min | +| 7 | Uninstall check and clean-up | 10 min | +| 8 | Send me the results | 5 min | + +## What you need + +- The computer, with Docker running: `sudo systemctl start docker` (it is off after a reboot). +- Your Android phone with **Garmin Connect** and the **Connect IQ Store** app, signed in to your Garmin account, paired with the Forerunner 70. +- The Forerunner 70's USB cable. +- An authenticator app on the phone (Aegis, or the one you use) to compare codes. You'll add a fake test entry to it and delete it at the end. +- A barcode scanner app on the phone that reads QR, Data Matrix, PDF417 and Aztec, for example the zxing-based "Barcode Scanner" or "Binary Eye". +- A stopwatch (the phone's clock app). +- Something to write the results in: a text file is fine. Part 8 has the template. + +### The fake test data + +| Name | Value | +| --- | --- | +| Test secret A | `JBSWY3DPEHPK3PXP` | +| Test secret B | `GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ` | +| Test PIN | `135790` (any 6 digits you don't use elsewhere) | +| Test EAN-13 | `5901234123457` | + +Two `otpauth://` links for the import test (fake accounts, secret A and B): + +```text +otpauth://totp/TestOne:alice@example.com?secret=JBSWY3DPEHPK3PXP&issuer=TestOne +otpauth://totp/TestTwo:bob@example.com?secret=GEZDGNBVGY3TQOJQGEZDGNBVGY3TQOJQ&issuer=TestTwo&digits=8 +``` + +A text of 300 characters for the large-QR timing (one line): + +```text +Fake QR test text 0123456789. Fake QR test text 0123456789. Fake QR test text 0123456789. Fake QR test text 0123456789. Fake QR test text 0123456789. Fake QR test text 0123456789. Fake QR test text 0123456789. Fake QR test text 0123456789. Fake QR test text 0123456789. Fake QR test text 0123456789. +``` + +Get these onto the phone the same way as the spike strings in part 3 (email them to yourself, for example). + +## Part 1: preparation on the computer + +In the project folder: + +1. Back up the developer key **before the first upload**. Copy the folder `.cache/keys/` to an encrypted place (a password-manager attachment or an encrypted USB drive). Once an app is uploaded with this key, every update must be signed with it; without it you'd have to start over with a new app and lose the data on the watch. +2. Build what you'll upload and sideload: + + ```sh + make spike + make build DEVICE=fr70 + make package + ``` + +3. Check that these files exist: + - `build/spike/settings-spike.iq`: the spike, for part 3. + - `build/debug/fr70.prg`: the debug build, for part 4. + - `build/package/otp-wallet-0.7.0.iq` and `build/package/otp-wallet-0.8.0.iq`: the Store betas, for part 5. The 0.7.0 file is the old one from M7; `make package` only rebuilds 0.8.0. If 0.7.0 is missing, tell me and we'll test the update differently. + +## Part 2: Garmin developer account + +1. Open <https://developer.garmin.com/connect-iq/> and sign in with your normal Garmin account. +2. Accept the Connect IQ developer agreement if asked. +3. Find the developer dashboard ("Upload an app" / "My apps"). You'll upload two apps there: Settings Spike in part 3 and OTP Wallet in part 5. Both are **beta apps**: only your account can see them. + +Garmin renames these pages sometimes; if a label differs, look for "beta" in the upload form. + +## Part 3: the settings spike (M1) + +This measures what Garmin Connect allows in the settings forms (field lengths, characters, write-back). The full instructions are in [SETTINGS_SPIKE.md](SETTINGS_SPIKE.md); this is the short order. + +1. **Upload:** in the dashboard, upload `build/spike/settings-spike.iq` as a **new app**, tick **Beta App**, name it "Settings Spike", fill in any short description and category. Wait until it shows as available (usually minutes). +2. **Install:** on the phone, open the Connect IQ Store app, find Settings Spike under your apps, install it on the Forerunner 70. +3. **Start it** on the watch from the apps list. It shows "Settings spike", "Changes seen: 0" and eight empty fields. +4. **Test strings:** send `spike/settings/test-strings/index.html` to the phone (email it to yourself) and open it in Chrome. Each string has a Copy button. +5. **Run tests A to H** from the table in [SETTINGS_SPIKE.md](SETTINGS_SPIKE.md#step-5-the-tests), with the spike open on the watch. The settings are in Garmin Connect: Forerunner 70, Connect IQ apps (or Activities & Apps), Settings Spike, Settings. Save after each change and read the watch. +6. **Write down** each result in the Results table of that page, or in your notes. Include the date, phone model, Garmin Connect version (Settings, About) and watch firmware. +7. Leave the spike installed until part 7; it doesn't interfere with OTP Wallet. + +## Part 4: debug build over USB + +The debug build has fake demo entries and the on-watch benchmark. It gets no phone settings, so it's only for these tests. Do this part **before** installing OTP Wallet from the Store, and remove it at the end of the part, so the two never sit on the watch at the same time. + +### 4.1 Copy it to the watch + +1. Connect the watch to the computer with the USB cable. +2. Open it in your file manager. Newer Garmin watches appear as an MTP device ("Forerunner 70", then "Internal Storage"). +3. Copy `build/debug/fr70.prg` into the folder `GARMIN/APPS` (on some watches `GARMIN/Apps`). +4. Eject the watch and unplug it. The app "OTP Wallet" appears in the watch's apps list. + +If the watch doesn't show up in the file manager, stop and tell me. Don't install anything on the computer for this without us talking first. + +### 4.2 Benchmark + +1. Open OTP Wallet, open the menu (hold MENU, or long-press the screen), choose **Debug: benchmark**. +2. Wait until it finishes ("Takes a few seconds"). +3. Take a photo of the screen, or write down every line (scroll if needed). + +### 4.3 Demo entries, codes and PIN + +1. Menu, **Set PIN**: enter the test PIN. Then menu, **Debug: demo entries**. The list fills with fake entries (GitHub, Google, Bank, VPN, Steam, Library and five cards). Bank is the locked one: if it isn't in the list, it is waiting for the PIN; choose menu, **Phone changes**, **Confirm all** and enter the PIN. +2. Check the list, open GitHub: the code in large digits and the countdown ring. In the last 5 seconds the next code shows too. +3. Open VPN (HOTP) and tap the code (or START): the next code appears. +4. Open Bank: the PIN keypad. Type with your finger: is it easy to hit the keys? +5. Enter a wrong PIN: the watch vibrates. Enter wrong PINs until five are wrong: the watch makes you wait 30 s. +6. Unlock with the right PIN, press BACK until you leave the app, start it again, open the locked entry: it must ask for the PIN again. +7. In the glance loop (scroll up or down from the watch face), the OTP Wallet glance shows the number of entries. +8. Menu, **Clock status**: the clock should say it is synced. Note what it shows. + +### 4.4 Scanning the demo cards + +Open each card and scan it with the phone's scanner app, indoors and outdoors (in daylight). If you can, try a shop scanner too. For each, note: reads / reads with effort / doesn't read. + +| Card | Type | Note also | +| --- | --- | --- | +| Gym card | EAN-13 | | +| Member QR | QR | Roughly how long the first opening takes ("Encoding…"); the second opening should be instant | +| Parcel | Data Matrix | | +| Ticket | PDF417 | | +| Rail pass | Aztec | | + +While a card is open: the backlight should be on (the Forerunner 70 has a MIP screen) and stay on for about a minute; a tap renews it. Check this in a dim room. + +### 4.5 Remove the debug build + +1. Connect the watch over USB again, delete `fr70.prg` from `GARMIN/APPS`, eject, unplug. +2. Check that OTP Wallet is gone from the apps list. + +## Part 5: Store beta, and the update from 0.7.0 to 0.8.0 + +To check that an update keeps your data, you install 0.7.0 first, put test data in, then update to 0.8.0. + +### 5.1 Install 0.7.0 + +1. In the dashboard, upload `build/package/otp-wallet-0.7.0.iq` as a **new app**, tick **Beta App**, name it "OTP Wallet". +2. On the phone, in the Connect IQ Store app, install OTP Wallet on the Forerunner 70. +3. Start it: it is empty and asks nothing yet. + +### 5.2 Put test data in + +1. Watch: menu, **Set PIN**, the test PIN. +2. Phone: Garmin Connect, Forerunner 70, Connect IQ apps, OTP Wallet, **Settings**. +3. **Add OTP** form: Issuer `TestOne`, Account `alice@example.com`, Secret: test secret A. Turn on **Add this entry**, save. Keep OTP Wallet open on the watch while saving. +4. Add a second one the same way: Issuer `TestLocked`, Secret: test secret B, **Require PIN to display** on. +5. **Add code** form: Card name `Test QR`, type QR, contents `Fake QR test text`. Save. +6. On the watch, open `Test QR` once (it gets encoded and cached). +7. Note the order of the entries in the list. + +### 5.3 Update to 0.8.0 + +1. In the dashboard, open the OTP Wallet app and upload `build/package/otp-wallet-0.8.0.iq` **as a new version of it** (not as a new app). +2. Update it on the watch from the Connect IQ Store app (or wait for the automatic update). +3. Open OTP Wallet. Menu, **About** must say 0.8.0. Check: + - The three entries are there, in the same order. + - `TestLocked` asks for the PIN and the test PIN opens it. + - `Test QR` shows "Encoding…" once (the cache format changed in 0.8.0), and opens instantly the next time. + +## Part 6: phone forms, glance and brightness on 0.8.0 + +Keep OTP Wallet open on the watch while you save forms, unless a step says otherwise. For each form, note the **Result** field on the phone (close and reopen the settings to see it) and the **Settings results** screen on the watch. + +### 6.1 Codes match the authenticator + +1. In your phone authenticator app, add a test entry manually with test secret A (TOTP, SHA1, 6 digits, 30 s). +2. Compare it with `TestOne` on the watch over two or three periods: the codes must be the same. + +### 6.2 Add OTP form + +1. You did this in 5.2. Now send the same form again unchanged: turn **Add this entry** on again and save. The result must be "Already added". +2. Note whether the form's fields were emptied on the phone after the first save. + +### 6.3 Import form + +1. Paste the two `otpauth://` links from the top of this page into **Text, part 1** (one per line). +2. Turn on **Import now**, save. +3. Check on the watch: `TestOne` is reported as a duplicate, `TestTwo` is imported with 8 digits. +4. Note whether the text field was emptied on the phone. + +### 6.4 Add code form + +1. Add an EAN-13 with the test EAN-13 (`5901234123457`), card name `Test EAN`. Scan it from the watch with the phone. +2. **Large code timing:** add a QR named `Big QR` with the 300-character text from the top of this page. On the watch, open it and time the "Encoding…" with the stopwatch. Open it again: instant. Scan it: the scanner must show the whole text. + +### 6.5 Manage entry form + +The entry IDs are in the About group on the phone, or in **Entry IDs** on the watch menu. + +1. Rename `TestTwo` to `Renamed`. +2. Move `Renamed` to position 1. +3. Delete `Renamed`. +4. Check after each: the watch list changes. + +### 6.6 Locked entry changes need the PIN + +1. With Manage entry, set **Require PIN** on `TestOne`. Save. +2. Then send **Don't require PIN** for `TestOne`. The watch must **not** apply it by itself. +3. On the watch: menu, **Phone changes**, **Confirm all**, enter the PIN. Now it applies. + +### 6.7 Options + +1. Change **Theme** to Light and **Code size** to another size, save: the watch changes as soon as the phone saves. +2. Set them back. +3. Does the **About** catalog (up to 800 characters) show completely on the phone? + +### 6.8 Glance code + +1. Make sure `TestOne` doesn't require the PIN (after 6.6 it doesn't). +2. Manage entry: `TestOne`, action **Mark as favourite (glance)**. Save. +3. Options: turn on **Show the favourite code in the glance**. Save. Open OTP Wallet once, then leave it. +4. In the glance loop: OTP Wallet shows `TESTONE`, the code and a bar counting down. The code matches the app and your authenticator. +5. Turn the option off on the phone and save, **without** opening the app: the glance must go back to "N entries". +6. Turn it on again, open the app once. Then set **Require PIN** on `TestOne` and open the app: `TestOne` must leave the glance. + +### 6.9 Brightness + +1. In a dim room, open `Test EAN`: the backlight comes on and stays on for about a minute. Tap: it renews. +2. Options: turn **Full brightness while showing a barcode** off, save, open the barcode again: no backlight now. +3. Turn it back on. + +### 6.10 Auto-lock and passcode + +1. Unlock `TestLocked`, then wait without touching the watch longer than **Lock after** (1 min by default): it must lock again. +2. If you use a watch passcode (system lock), note whether OTP Wallet behaves normally with it. + +## Part 7: uninstall check and clean-up + +1. In the Connect IQ Store app, uninstall OTP Wallet from the watch. +2. Install it again (0.8.0). Start it: it must be empty, with no entries and no PIN. +3. Uninstall Settings Spike from the watch. You can delete its beta from the dashboard. +4. Delete the test entry from your phone authenticator app, and the test strings and links you emailed yourself. +5. Keep OTP Wallet installed if you want to start using it; it's 0.8.0 until I tag 1.0.0 (then you'll upload that as a new version). + +## Part 8: send me the results + +Copy this, fill it in and paste it in the chat. "OK" is enough where everything worked; describe anything else. Photos of the screen help where something looks wrong. + +```text +Phone, Garmin Connect version, watch firmware: + +PART 3 SPIKE +A longest field complete / above that: +B largest total: +C characters missing or blocking: +D status visible on phone / password cleared: +E changes while open / while closed: +F password: arrives / masked: +G time short / longest: +H number field validation: +Other: + +PART 4 DEBUG BUILD +Benchmark lines (or photo): +Demo list, codes, ring, HOTP next: +PIN keypad feel / wrong PIN vibrate / 30 s wait: +Locked again after leaving: +Glance shows entry count: +Clock status: +Scans (indoors / outdoors / shop): Gym card, Member QR, Parcel, Ticket, Rail pass: +Member QR first opening time: +Backlight on barcode: + +PART 5 UPDATE +Entries, order and PIN kept after 0.7.0 -> 0.8.0: +Test QR re-encoded once, then instant: + +PART 6 ON 0.8.0 +Codes match authenticator: +Add OTP: result / fields emptied / repeat says Already added: +Import: result / text emptied: +Test EAN scans: +Big QR encoding time / scans complete: +Manage: rename, move, delete: +Locked change waits for Confirm all + PIN: +Theme / code size change at once: +About catalog complete on phone: +Glance: code + countdown / option off hides it / locked leaves it: +Brightness on / off option: +Auto-lock / passcode: + +PART 7 +Reinstall starts empty: +``` + +When I have this, I'll put the numbers into PERFORMANCE.md and the spike results into the design, fix anything that failed, and tag 1.0.0. Anything that can't be fixed goes into the known limitations in the [user guide](USER_GUIDE.md#known-limitations). |