[C10] NFC protocol and session management

[grantfox-oss]

C10 — NFC protocol and session management

Field	Value
ID	C10
ETA	ETA 3
Priority	P0
Complexity	H
Depends on	C03, C05, C08, C09
Atomic tasks	CLI-046, CLI-047, CLI-048, CLI-049, CLI-050, CLI-051, CLI-052
Est. effort	3 engineer-weeks
Blocker	⚠️ Hard blocker — see Hard blockers section

Executive summary

This deliverable builds the NFC core stack from native setup through payload validation, encoding, reader/writer sessions, and centralized state management.
It defines the canonical payment-request schema and codec constraints that protect against malformed or oversized NDEF payloads.
It implements session lifecycle controls and single-session guarantees required for reliable mobile NFC behavior.
As a hard blocker, C10 enables higher-level receive/send NFC flows by providing stable transport and state primitives.

Product context

C10 executes CLI-046 through CLI-052 after ADR validation. It installs/configures react-native-nfc-manager, introduces NfcService abstraction, defines Zod PaymentRequest schema (type, recipient, asset, amount, timestamps/expiry), implements codec encode/decode with size checks, and builds writer/reader session modules with timeouts and cleanup behavior. Finally, it adds NfcSessionStore (idle, scanning, writing, success, error) with nfcActive to coordinate auth lock policy.

User stories

• As a receiver, I want to broadcast a payment request over NFC so that a payer can read it instantly.
• As a payer, I want to read and validate NFC payment payloads so that I can trust what I am approving.
• As a developer, I want an abstracted NFC service so that native library details are isolated from product logic.
• As an app, I want a centralized NFC session store so that only one session runs at a time without lock conflicts.

Prerequisites

• C03 native plugin baseline and dev-client rebuild workflow complete
• C05 NFC ADR approved with platform constraints documented
• C08 assets constants available for payload schema alignment
• C06 session policy hooks available for nfcActive integration

Atomic sub-task checklist

CLI-ID	Title	Key deliverable
CLI-046	Install and configure react-native-nfc-manager	Enable NFC native runtime
CLI-047	NfcService abstraction (isSupported, session)	Wrap native NFC APIs in stable interface
CLI-048	PaymentRequest schema Zod	Validate canonical NFC payload
CLI-049	Serialize/deserialize NFC JSON payload	Encode/decode request safely
CLI-050	NFC writer session (receiver emits request)	Publish request via NDEF
CLI-051	NFC reader session (sender receives request)	Read and validate request via NDEF
CLI-052	NfcSessionStore state machine	Coordinate one active NFC session and lock policy

Scope — In

• Install NFC manager library and configure native plugins/entitlements.
• Implement service abstraction for support checks and session lifecycle methods.
• Define Zod payment request schema with expiry validation helpers.
• Implement codec for compact JSON payload encode/decode and max-size guard.
• Implement writer session flow with timeout, cancel, and cleanup semantics.
• Implement reader session flow with single-read policy and expiry rejection.
• Implement centralized NFC session store and nfcActive coordination signal.
• Provide mocks and test harness points for unit-level NFC logic validation.

Scope — Out

• Higher-level receive/send screen orchestration beyond core services
• Server-side request persistence and replay protection API
• QR fallback implementation
• Always-on background scanning or multi-tap batch handling

Architecture & conventions

C10 aligns with FOLDER_LAYOUT by concentrating transport logic in src/features/nfc/services, schemas in src/features/nfc/schemas, hooks in src/features/nfc/hooks, and session state in src/features/nfc/state. On the Expo/React Native stack, it uses abstraction and state-machine patterns to isolate native NFC complexity from payment UI layers. It also coordinates cross-feature policy through nfcActive so auth/session patterns remain coherent.

Files to create/modify

• package.json
• app.config.ts
• README.md
• src/features/nfc/services/NfcService.ts
• src/features/nfc/services/NfcService.native.ts
• src/features/nfc/schemas/paymentRequest.ts
• src/features/nfc/services/NfcPayloadCodec.ts
• src/features/nfc/services/NfcWriter.ts
• src/features/nfc/hooks/useNfcWriter.ts
• src/features/nfc/services/NfcReader.ts
• src/features/nfc/hooks/useNfcReader.ts
• src/features/nfc/state/nfcSessionStore.ts
• src/features/auth/hooks/useSessionPolicy.ts
• src/features/wallet/constants/assets.ts
• src/features/nfc/services/nfc-spike.ts

Implementation guide

1. Install and pin react-native-nfc-manager according to ADR decision.
2. Configure app plugin and platform entitlements/permissions for NFC runtime.
3. Rebuild dev client and verify isSupported() smoke behavior.
4. Define NfcService interface and native implementation wrapper.
5. Create PaymentRequest schema with recipient, asset, amount, timestamp, expiresAt fields.
6. Add expiry validation helper and strict parse path for request decoding.
7. Implement codec encode/decode with compact JSON and max payload-size check.
8. Implement writer session service with timeout auto-cancel and cleanup hooks.
9. Implement reader session service with single-read policy and callback contract.
10. Create useNfcWriter and useNfcReader hooks to expose session APIs.
11. Implement NfcSessionStore transitions and enforce one-active-session semantics.
12. Connect nfcActive to session policy integration point in auth hooks.
13. Add mock/test scaffolding for codec, schema parse, and session transition logic.

Acceptance criteria

• NFC manager is installed, configured, and functional in dev build runtime.
• NfcService exposes stable API for support checks and session operations.
• PaymentRequest schema rejects invalid recipient, asset, amount, or expiry fields.
• Codec roundtrip preserves payload equivalence for valid request objects.
• Codec rejects malformed JSON and over-limit payload sizes with typed errors.
• Writer session starts, writes payload, times out at configured boundary, and cleans up.
• Reader session reads once, validates payload, and ignores duplicate reads in same session.
• Expired payment requests are rejected before callback propagation.
• Session cancel path reliably releases NFC resources after interruption.
• NfcSessionStore enforces one active session and deterministic transitions.
• nfcActive is available to prevent auth lock conflicts during active sessions.
• Core NFC modules remain free of payment business decision logic.
• README includes rebuild and runtime verification guidance for NFC changes.
• Unit-level tests cover schema, codec, and store transition edge cases.

Test plan

• Unit: Unit tests for schema parsing, codec roundtrip/oversize errors, and nfcSessionStore transitions with mocked service calls.
• Manual: Run writer/reader PoC between two devices, validate timeout/cancel behavior, and test expired payload rejection.
• Device: Mandatory two-device NFC validation on physical hardware for both writer and reader session paths.

Server coordination

C10 must stay aligned with S08/S09 payment-request.v1 contract semantics because schema and codec choices are shared integration boundaries. Replay/expiry policies should be coordinated with S18 hardening work, while future end-to-end payment orchestration with authorization/relay will intersect S10 and S14-S16 flows. Contract review checkpoints should be scheduled before promoting payload changes.

Security notes

• Validate and reject expired or malformed payloads before any payment action.
• Enforce strict payload size limits to reduce parser and transport abuse.
• Avoid logging full NFC payload content when errors occur.
• Ensure session cancellation always releases native NFC handles.

Risks & pitfalls

• Platform differences in NFC behavior can break parity across iOS and Android.
• Payload schema drift from server contract can cause silent interoperability failures.
• Session cleanup bugs may leave NFC hardware locked or stale between attempts.
• Oversized payload handling may regress without strict tests and limits.
• Insufficient reader timeout handling can degrade UX and battery use.
• Auth lock coordination gaps can interrupt active NFC interactions unexpectedly.

Definition of done

• NFC runtime and service abstraction are production-ready for MVP scope.
• Schema and codec contracts are validated, typed, and tested.
• Reader and writer sessions function on physical devices with cleanup guarantees.
• Session store coordinates active-state policy and auth lock integration.
• C10 blocker is cleared for higher-level NFC receive/send feature work.

---

---

Source: build plan

[mordabdul1]

I'd like to take ownership of this issue. It covers the core NFC foundation for the project, and I'm confident I can deliver a clean, secure, and well-tested implementation that aligns with the specified architecture and acceptance criteria. I'll pay close attention to session lifecycle management, payload validation, cross-platform behavior, and documentation to ensure it's production-ready.

If possible, I'd be grateful if you could assign this issue to me. I'm committed to seeing it through to completion and responding promptly to any review feedback.

[mordabdul1]

I'd like to take ownership of this issue. It covers the core NFC foundation for the project, and I'm confident I can deliver a clean, secure, and well-tested implementation that aligns with the specified architecture and acceptance criteria. I'll pay close attention to session lifecycle management, payload validation, cross-platform behavior, and documentation to ensure it's production-ready.

If possible, I'd be grateful if you could assign this issue to me. I'm committed to seeing it through to completion and responding promptly to any review feedback.

[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 #32)
2. Your PR will be reviewed by the Ding-Payments maintainers

Good luck! Track your progress on GrantFox.