[C11] NFC platform config, security and documentation

[grantfox-oss]

C11 — NFC platform config, security and documentation

Field	Value
ID	C11
ETA	ETA 3
Priority	P0
Complexity	H
Depends on	C10
Atomic tasks	CLI-053, CLI-054, CLI-055, CLI-056, CLI-057, CLI-058, CLI-059, CLI-060
Est. effort	6-8 days

Executive summary

Consolidate platform-level NFC readiness for iOS and Android, then lock down payload safety and replay protections so receive/send flows can trust inbound requests.
Centralize NFC session composition, user-facing error mapping, and analytics instrumentation in one implementation surface (useNfc + error services) to reduce duplicated failure handling.
Publish docs/nfc-flow.md as the implementation and onboarding source of truth, including handshake sequence, security constraints, and device requirements for beta testers.

Product context

This deliverable completes the hardening layer between C10 protocol primitives and end-user payment flows. It addresses platform capability detection, expiration/replay validation, strict payload privacy rules, iOS/Android native configuration checks, and operational documentation. Without C11, C12/C13 can technically run but remain fragile, non-portable, and unsafe for production-like testing.

User stories

• As a user on a misconfigured device, I see immediately why NFC is unavailable and how to fix it.
• As a security reviewer, I can verify that NFC payloads never include secrets and that replay windows are constrained.
• As a mobile engineer, I can use one useNfc() hook API across receive/send without re-implementing session lifecycle.
• As QA, I have deterministic error messages and analytics events for timeout, interruption, invalid payload, and disabled NFC paths.
• As a new contributor, I can implement and debug NFC flows from docs/nfc-flow.md without reverse engineering app internals.

Prerequisites

• C10 completed with stable reader/writer primitives and payload codec.
• Dev builds available on physical iOS and Android devices (Expo Go unsupported).
• Analytics stub from CLI-012 available for event constants and tracking.
• Agreement on NFC security policy (no secret/seed/private key fields in payload schema).

Atomic sub-task checklist

CLI-ID	Title	Key deliverable
CLI-053	NfcAvailabilityBanner and redirect to settings	Detect unsupported/disabled NFC and guide user to OS settings
CLI-054	Expiry validation and replay protection	Reject expired/duplicate requests with skew and TTL constraints
CLI-055	NFC security: prohibit secrets in payload	Enforce static checks and documentation for forbidden payload fields
CLI-056	Config iOS Core NFC sessions	Validate iOS entitlements, usage strings, and foreground behavior
CLI-057	Config Android foreground dispatch NFC	Validate Android permission, dispatch behavior, and OEM caveats
CLI-058	Hook useNfc() composer	Expose unified hook API for read/write/cancel/status
CLI-059	NFC error handling and analytics	Map native/flow errors to user copy and analytics events
CLI-060	Document nfc-flow.md	Publish end-to-end NFC implementation and troubleshooting guide

Scope — In

• NFC availability UX in send/receive entry points.
• Validation pipeline for expiry, replay dedupe, and clock skew tolerance.
• Schema guardrails and tests that fail on secret-like payload fields.
• iOS + Android native configuration verification and checklists.
• Reusable useNfc() orchestration hook and cleanup semantics.
• Unified NFC error taxonomy and analytics coverage.
• NFC documentation including diagrams, errors, security rules, and device checklist links.

Scope — Out

• QR fallback or hybrid transport.
• Payload cryptographic signatures or server nonce protocol.
• Background NFC scanning/HCE card emulation.
• Automated E2E framework implementation (covered by later deliverables).

Architecture & conventions

Keep NFC concerns inside src/features/nfc/ as a layered stack: schema/validation -> service adapters -> hook orchestration -> UI components. Enforce non-sensitive payload contract at schema boundary, and keep analytics/logging redacted by design. Platform capability and session lifecycle state should remain feature-local and exposed to screens only through hooks/selectors.

Files to create/modify

• src/features/nfc/components/NfcAvailabilityBanner.tsx
• src/features/nfc/services/paymentRequestValidation.ts
• src/features/nfc/schemas/__tests__/paymentRequest.security.test.ts
• src/features/nfc/hooks/useNfc.ts
• src/features/nfc/services/nfcErrors.ts
• src/features/nfc/schemas/paymentRequest.ts
• src/features/nfc/services/NfcReader.ts
• src/features/nfc/state/nfcSessionStore.ts
• src/app/(tabs)/receive.tsx
• src/app/(tabs)/send.tsx
• app.config.ts
• docs/nfc-flow.md
• docs/nfc-device-checklist.md
• README.md
• src/constants/analytics-events.ts

Implementation guide

1. Implement capability banner rendering paths for unsupported/disabled NFC and add settings deep-link helper.
2. Build validatePaymentRequest() with expiry, clock skew tolerance, and short-lived dedupe key cache.
3. Add schema security tests that assert forbidden key patterns are absent from request payload model.
4. Audit and update app.config.ts for iOS Core NFC and Android NFC permission/foreground requirements.
5. Create useNfc() hook that wraps reader/writer services, exposes status primitives, and guarantees unmount cleanup.
6. Introduce centralized NfcErrorCode and mapping utility with Spanish-first user copy and no sensitive logging.
7. Wire analytics events for success/failure/timeout paths from hook-level transitions.
8. Document flow sequence, security checklist, payload contract references, and test-device caveats in docs/nfc-flow.md.
9. Update README and checklist links so onboarding references a single authoritative NFC runbook.

Acceptance criteria

• Availability banner appears in send/receive when NFC is unsupported or disabled.
• Tapping banner action opens OS settings on supported platforms.
• Expired payment requests are rejected before business flow callback execution.
• Duplicate payload replays within 5-minute TTL window are rejected deterministically.
• Validation tolerates configured clock skew and accepts valid fresh payloads.
• Payload schema tests fail CI if secret/private/seed-like fields are introduced.
• No analytics event includes payload body, pubkey raw value, or any secret material.
• iOS NFC usage description and entitlement configuration are documented and validated on physical device.
• Android NFC permission and foreground dispatch flow work on at least one Pixel-class and one OEM variant device.
• useNfc() exposes stable API (startWriting, startReading, cancel, status) used by send/receive flows.
• NFC sessions are canceled and cleaned up on route change/unmount with no dangling readers.
• Error mapping differentiates unavailable/disabled/timeout/interrupted/payload-invalid cases with actionable Spanish copy.
• NFC error and success analytics events emit with expected event names and sanitized props.
• docs/nfc-flow.md contains handshake diagram, role split (writer/reader), security rules, and troubleshooting table.
• README links to NFC documentation and checklist pages are valid.

Test plan

• Unit: Validation tests for expiry/skew/replay; schema security tests; mapNfcError tests; useNfc hook behavior tests with mocked services.
• Manual: Disable NFC and verify banner; run 2-device happy path; replay same payload within TTL; force timeout/interruption; verify analytics payload redaction.
• Device: Physical iPhone (Core NFC), physical Android (Pixel/Samsung class), and at least one cross-platform pair for tap exchange.

Server coordination

No direct server dependency. Keep payload versioning aligned with server-side expectations (payment-request.v1) documented in shared contracts and ADR references.

Security notes

• Explicitly forbid private keys, seeds, credential secrets, and auth tokens in NFC payload schema.
• Replay mitigation uses expiry + dedupe cache; document residual risk when attacker captures payload inside valid window.
• Analytics and logs must only include error codes/categories, never raw payload or credential identifiers.
• Document platform-specific behavior differences that can affect reliability/security assumptions (foreground requirement, session interruption).

Risks & pitfalls

• Device/OEM NFC variance can create false negatives in readiness checks.
• Clock drift between devices may reject otherwise valid requests if skew window is too strict.
• Overly broad security test regex may produce developer friction; define clear allowed/forbidden patterns.
• Missing cleanup in hook layer can leak session state and cause flaky downstream flows.

Definition of done

• NFC platform support and security checks merged with green CI.
• Receive/send tabs consume useNfc APIs without duplicating low-level service orchestration.
• iOS and Android NFC config validated in dev builds and recorded in checklist docs.
• NFC docs published with working diagrams and linked from README.
• Analytics redaction and error mapping behavior validated in manual runbook.

---

---

Source: build plan

[zeemscript]

I'd be happy to take this on. The requirements are clear, and I can deliver a robust, maintainable implementation with proper testing and a well-documented PR. Looking forward to contributing!

[Heazzy500]

Hello, I’ve gone through the requirements and I’m confident I can implement a proper solution that matches the acceptance criteria. Kindly assign this issue to me.

[davieslennox0]

Fintech is my thing, imagine where passion meets skill, let me help resolve this

[Primex-hub]

I will love to fix this issue

[YAustinXYZ]

I wanna do this

[gloskull]

Hi, I’d love to work on this issue. I have 4 years of experience across backend, frontend, full-stack, and smart contract development. I understand the task clearly and can deliver a clean, efficient, well-tested solution on time, with strong focus on code quality and maintainability. My PR will be submitted in 12hours

[grantfox-oss]

🦊 GrantFox — @YAustinXYZ has been assigned to this issue as part of the Official Campaign | FWC26 campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #33)
2. Your PR will be reviewed by the Ding-Payments maintainers

Good luck! Track your progress on GrantFox.