Add transactional account linking with arkavo-node #23

arkavo-com · 2025-12-06T02:28:00Z

Summary

Adds transactional blockchain account linking with arkavo-node and NTDF token support:

Transactional account linking: Registration fails if blockchain linking fails (no silent failures)
Secured backchannel RPC: Direct server-to-server call to arkavo-node (no JWT verification needed)
NTDF token generation: NanoTDF-based authentication tokens using opentdf-rs library
Reliability improvements: Retry with exponential backoff, address normalization
Security improvements: Authenticator flags validation (User Present check)

Key Design Decisions

Backchannel Architecture (No JWT Token Passing)

The link between authnz-rs and arkavo-node is a secured backchannel - a trusted server-to-server connection. This means:

No JWT token is sent to arkavo-node for verification
arkavo-node trusts authnz-rs as the authoritative identity provider
The RPC call passes user_id, did, and blockchain_address directly
This simplifies the architecture and avoids JWT parsing on the blockchain node

Transactional Semantics

If account linking fails after 3 retries, registration is blocked (returns 503 SERVICE_UNAVAILABLE). This ensures the user doesn't end up with a registered account that isn't linked to their blockchain address.

Flow

Client                    authnz-rs                   arkavo-node
  |                          |                            |
  |-- register(addr) ------->|                            |
  |                          |-- validate addr format     |
  |                          |-- WebAuthn ceremony        |
  |                          |-- store in DynamoDB        |
  |                          |                            |
  |                          |-- linkAccountWithProof --->|
  |                          |   (backchannel RPC:        |
  |                          |    user_id, did, addr)     |
  |                          |                            |
  |                          |<-- success/fail -----------|
  |                          |                            |
  |<-- JWT + NTDF token -----|  (only on success)         |

Changes by Commit

Add transactional account linking - Optional blockchain_address param, backchannel RPC
Fix PR review issues - HTTP client timeout (5s), client reuse, test fixes
Add NTDF token generation - NanoTDF-based tokens for authenticated requests
Add reliability improvements - Retry w/ exponential backoff, error propagation, address normalization
Refactor NTDF to use opentdf-rs - Correct HKDF salt (SHA256("L1L")), spec compliance
Fix warnings and add flags validation - User Present flag check (security improvement)

Configuration

ARKAVO_NODE_URL: arkavo-node RPC endpoint (default: http://127.0.0.1:9933)
KAS_PUBLIC_KEY_PATH: (optional) KAS public key for NTDF token generation
KAS_URL: (optional) KAS URL embedded in NTDF tokens

Test Plan

Build successfully with new dependencies
All 35 tests pass
No compiler warnings
Register without blockchain_address (existing flow unchanged)
Register with valid blockchain_address, arkavo-node not running (returns 503)
Register with invalid blockchain_address format (returns 400)
Register with valid blockchain_address, arkavo-node running (full flow)
Verify NTDF token is included in X-NTDF-Token header

Related Issues

Partial implementation for #21 and #22 (chain anchoring infrastructure)

🤖 Generated with Claude Code

Enables atomic DID-to-blockchain-address linking during registration via backchannel RPC call to arkavo-node. Changes: - Add optional `blockchain_address` parameter to RegisterParams - Include `did` and `blockchain_address` in AccountToken JWT claims - Add `link_account_on_chain()` to call arkavo-node RPC after registration - Add reqwest dependency for HTTP client - Improve error response status codes (BAD_REQUEST for validation errors) Flow: 1. Client provides blockchain_address during registration 2. authnz-rs validates address format (0x + 40 hex chars) 3. After successful passkey registration, authnz-rs calls arkavo_linkAccountWithProof RPC on arkavo-node 4. arkavo-node verifies JWT and links DID to address on-chain Environment: - ARKAVO_NODE_URL: arkavo-node RPC endpoint (default: http://127.0.0.1:9933) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Fix broken test_webauthn_error_responses test to verify correct status codes after HTTP status code improvements - Add test_blockchain_address_validation test for EVM address format - Add HTTP client to AppState with 5-second timeout for RPC calls - Reuse HTTP client instead of creating new one per request - Update link_account_on_chain to use shared client 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Add ntdf_token module for NanoTDF-based authentication tokens - Implement ECDH key exchange with KAS public key - Add AES-256-GCM encryption for payload - Add Z85 encoding for wire format - Update Cargo.toml with required dependencies (z85, aes-gcm, hkdf, rand_core) - Enable ecdh feature for p256 crate 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Add AccountLinkingFailed error variant with SERVICE_UNAVAILABLE status - Propagate account linking errors to block registration on failure - Add retry with exponential backoff (3 attempts, 100ms * 2^n delay) - Normalize blockchain address to lowercase for consistency - Add test for AccountLinkingFailed error response - Fix rustls version for aws-lc-rs dependency compatibility - Add opentdf-rs v0.8.0 dependencies for NanoTDF Collection support 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Replace custom NanoTDF implementation with opentdf-rs library: - Use NanoTdfBuilder from opentdf-crypto for encryption - Correct HKDF salt: SHA256("L1L") per NanoTDF spec - Remove custom ECDH, HKDF, and AES-GCM code - Remove aes-gcm and hkdf direct dependencies - Add roundtrip test verifying Z85 decode and magic number - Simplify error types (remove EcdhError, Z85EncodeError) The opentdf-rs library handles all cryptographic operations: - Ephemeral P-256 key generation - ECDH key agreement - HKDF-SHA256 key derivation with spec-compliant salt - AES-256-GCM encryption with 3-byte IV 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

- Remove unused `head` import from main.rs - Add User Present (UP) flag validation for attestation and assertion - Add Attested Credential (AT) flag warning for incomplete attestation - Document auth_flags module with WebAuthn/FIDO spec reference - Add #[allow(dead_code)] with documentation for: - receipt field (Apple fraud detection, future use) - rp_id_hash raw bytes (stored as hex string instead) - Add debug logging for authenticator flags Security improvement: Now validates that User Present flag is set, which is required per WebAuthn spec for genuine user interaction. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Add explicit ring crypto provider installation at startup to resolve ambiguity when both ring and aws-lc-rs are enabled via transitive dependencies (tokio-rustls, aws-smithy-http-client, hyper-rustls). 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Implements W3C WebAuthn Level 3 Related Origin Requests (ROR) specification to allow passkeys registered on identity.arkavo.net to be used on related origins. Configuration loaded from WEBAUTHN_CONFIG_PATH env var (defaults to webauthn.json). Uses newtype wrappers to distinguish Extension types and avoid conflicts with existing apple-app-site-association endpoint. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

sonarqubecloud · 2025-12-07T16:41:42Z

Quality Gate passed

Issues
2 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

arkavo-com mentioned this pull request Dec 6, 2025

Add user_registry contract and AuthApi RPC for DID-to-account linking arkavo-org/arkavo-node#24

Open

9 tasks

arkavo-com and others added 7 commits December 6, 2025 08:47

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add transactional account linking with arkavo-node #23

Add transactional account linking with arkavo-node #23

Uh oh!

arkavo-com commented Dec 6, 2025 •

edited

Loading

Uh oh!

sonarqubecloud bot commented Dec 7, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Add transactional account linking with arkavo-node #23

Are you sure you want to change the base?

Add transactional account linking with arkavo-node #23

Uh oh!

Conversation

arkavo-com commented Dec 6, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Key Design Decisions

Backchannel Architecture (No JWT Token Passing)

Transactional Semantics

Flow

Changes by Commit

Configuration

Test Plan

Related Issues

Uh oh!

sonarqubecloud bot commented Dec 7, 2025

Quality Gate passed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

arkavo-com commented Dec 6, 2025 •

edited

Loading