Skip to content

feat(nfc): C11 NFC platform config, validation, useNfc hook, docs #38

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
JoelVR17 merged 4 commits into from
Jul 20, 2026
Merged

feat(nfc): C11 NFC platform config, validation, useNfc hook, docs #38

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
f46d8c3
feat(nfc): C11 NFC platform config, validation, useNfc hook, docs
YAustinXYZ Jul 20, 2026
17d2742
fix(nfc): remove duplicate hook and duplicate PaymentRequest type — u…
YAustinXYZ Jul 20, 2026
becf1ae
chore: update package-lock.json to include @emnapi deps (CI npm ci fix)
YAustinXYZ Jul 20, 2026
87f82b0
style: format files to satisfy prettier/eslint
YAustinXYZ Jul 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -116,6 +116,8 @@ See [docs/adr-nfc-library.md](docs/adr-nfc-library.md) for platform constraints
- [Product flows & system definition](docs/ding-payments.md)
- [Client MVP build plan](docs/build-plan-client-mvp.md)
- [NFC library ADR](docs/adr-nfc-library.md)
- [NFC runtime flow and troubleshooting](docs/nfc-flow.md)
- [NFC device checklist](docs/nfc-device-checklist.md)

## License

Expand Down
11 changes: 11 additions & 0 deletions docs/nfc-device-checklist.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# NFC device checklist

Devices to test
- iPhone with Core NFC support (physical device)
- Pixel-class Android device
- Samsung/other OEM device to capture vendor variance

Checklist
- Ensure NFC is enabled in system settings.
- For iOS: confirm entitlement and Info.plist usage string present in `app.config.ts`.
- For Android: confirm `android.permission.NFC` is declared and app handles foreground dispatch.
27 changes: 27 additions & 0 deletions docs/nfc-flow.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,27 @@
# NFC flow and troubleshooting

This document describes the NFC handshake, security constraints, and common troubleshooting steps for developers and beta testers.

Overview
- Roles: Writer (sender) and Reader (receiver).
- Format: `payment-request.v1` JSON payload with non-sensitive fields only.

Handshake
1. Writer prepares `payment-request.v1` payload with `id` and optional `expiresAt` (epoch seconds).
2. Reader calls `useNfc().startReading()` and waits for inbound payload.
3. On read, the app validates payload using `validatePaymentRequest()` which enforces expiry and replay dedupe.
4. If valid, proceed to presentation/confirm UI. If invalid, surface mapped Spanish error copy.

Security rules
- Forbidden fields: secret, private, seed, token, passphrase, password, privKey, keyPair.
- Replay protection: 5-minute TTL dedupe window; duplicate requests rejected deterministically.
- Clock skew tolerance: 30s default; configurable in validator.

Platform notes
- iOS: Core NFC requires entitlement `com.apple.developer.nfc.readersession.formats` and `NFCReaderUsageDescription` in Info.plist. Only physical devices supported.
- Android: Add `android.permission.NFC` and handle foreground dispatch. Test on Pixel and Samsung-class devices.

Troubleshooting
- NFC Unavailable: ensure device supports NFC and app has permissions.
- NFC Disabled: ask user to enable in OS settings.
- Timeout: ask users to bring devices closer and retry.
Loading
Loading