Flutter / Dart Shield SDK

dependencies:
  akedly_shield:
    git:
      url: https://github.com/Akedly-Org/akedly-shield-dart.git
      ref: main

dependencies:
  akedly_shield:
    git:
      url: https://github.com/Akedly-Org/akedly-shield-dart.git
      ref: 1.1.0

flutter pub get

import 'package:flutter/material.dart';
import 'package:akedly_shield/akedly_shield.dart';
import 'dart:convert';
import 'package:http/http.dart' as http;

// Your backend base URL — keeps APIKey and pipelineID server-side.
const backendUrl = 'https://yourapp.com';

class OTPScreen extends StatefulWidget {
  final String phoneNumber;
  // Supply the same 4, 5, or 6 value configured by your backend.
  final int otpLength;

  const OTPScreen({
    super.key,
    required this.phoneNumber,
    required this.otpLength,
  });

  @override
  State<OTPScreen> createState() => _OTPScreenState();
}

class _OTPScreenState extends State<OTPScreen> {
  String? _transactionReqID;
  String _otp = '';
  bool _loading = false;
  String? _error;
  String? _turnstileSiteKey;
  Map<String, dynamic>? _challengeData;

  Future<void> _sendOTP({String? turnstileToken}) async {
    setState(() { _loading = true; _error = null; });
    try {
      // 1. Get challenge from YOUR backend
      final challengeRes = await http.get(
        Uri.parse('$backendUrl/auth/akedly/challenge'),
      );
      final data = jsonDecode(challengeRes.body)['data'];

      // Check if Turnstile is needed and we don't have a token yet
      if (data['turnstile']?['required'] == true && turnstileToken == null) {
        setState(() {
          _challengeData = data;
          _turnstileSiteKey = data['turnstile']['siteKey'];
          _loading = false;
        });
        return; // Wait for Turnstile token via widget callback
      }

      // 2. Solve PoW in background isolate only when the pipeline requires it
      Map<String, dynamic>? powSolution;
      if (data['challengeRequired'] == true) {
        final nonce = await solvePowInIsolate(
          data['challenge'] as String,
          data['difficulty'] as int,
        );
        powSolution = {
          'challengeToken': data['challengeToken'],
          'nonce': nonce,
        };
      }

      // 3. Send proof via YOUR backend
      final sendRes = await http.post(
        Uri.parse('$backendUrl/auth/akedly/send'),
        headers: {'Content-Type': 'application/json'},
        body: jsonEncode({
          'phoneNumber': widget.phoneNumber,
          if (powSolution != null) 'powSolution': powSolution,
          if (turnstileToken != null) 'turnstileToken': turnstileToken,
        }),
      );
      final result = jsonDecode(sendRes.body);
      setState(() { _transactionReqID = result['data']['transactionReqID']; });
    } catch (e) {
      setState(() { _error = e.toString(); });
    } finally {
      setState(() { _loading = false; });
    }
  }

  Future<void> _verifyOTP() async {
    setState(() { _loading = true; _error = null; });
    try {
      final res = await http.post(
        Uri.parse('$backendUrl/auth/akedly/verify'),
        headers: {'Content-Type': 'application/json'},
        body: jsonEncode({'transactionReqID': _transactionReqID, 'otp': _otp}),
      );
      final result = jsonDecode(res.body);
      if (result['status'] == 'success') {
        if (mounted) Navigator.of(context).pop(true);
      } else {
        setState(() { _error = 'Invalid OTP'; });
      }
    } catch (e) {
      setState(() { _error = e.toString(); });
    } finally {
      setState(() { _loading = false; });
    }
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Verify Phone')),
      body: Padding(
        padding: const EdgeInsets.all(16),
        child: Column(
          crossAxisAlignment: CrossAxisAlignment.stretch,
          children: [
            if (_turnstileSiteKey != null && _transactionReqID == null)
              SizedBox(
                height: 1,
                child: AkedlyTurnstile(
                  siteKey: _turnstileSiteKey!,
                  onToken: (token) => _sendOTP(turnstileToken: token),
                  onError: (err) => setState(() { _error = err; }),
                ),
              ),
            if (_transactionReqID == null) ...[
              Text('Send OTP to ${widget.phoneNumber}'),
              const SizedBox(height: 16),
              ElevatedButton(
                onPressed: _loading ? null : () => _sendOTP(),
                child: Text(_loading ? 'Sending...' : 'Send OTP'),
              ),
            ] else ...[
              TextField(
                onChanged: (v) => setState(() { _otp = v; }),
                decoration: const InputDecoration(labelText: 'Enter OTP'),
                keyboardType: TextInputType.number,
                maxLength: otpLength,
              ),
              const SizedBox(height: 16),
              ElevatedButton(
                onPressed: _loading || _otp.length < otpLength ? null : _verifyOTP,
                child: Text(_loading ? 'Verifying...' : 'Verify'),
              ),
            ],
            if (_error != null)
              Padding(
                padding: const EdgeInsets.only(top: 16),
                child: Text(_error!, style: const TextStyle(color: Colors.red)),
              ),
          ],
        ),
      ),
    );
  }
}

import 'package:akedly_shield/akedly_shield.dart';

// After an OTP /verify that returned data.enrollmentToken:
// For result.verified to be true here, the OTP /verify that minted enrollmentToken must
// also have passed returnTarget: { "url": "myapp://akedly-passkey" }. Without it enrollment
// still succeeds, but this resolves verified:false / no_proof — treat it as advisory.
final result = await AkedlyPasskey.openCeremony(
  token: enrollmentToken,
  callbackScheme: 'myapp',
);
// result.verified == true => the passkey now exists (proven on the next sign-in).

import 'package:akedly_shield/akedly_shield.dart';

// 1. Your backend clears the gate + starts the ceremony:
//    POST /api/v1.2/transactions/passkey/auth-options
//      { APIKey, pipelineID, verificationAddress: { phoneNumber }, powSolution?, turnstileToken?,
//        returnTarget: { url: "myapp://akedly-passkey" } }  // <-- REQUIRED for the resultToken
//    -> { data: { ceremonyToken, requestID } }
final auth = await myBackend.startPasskeyAuth(phone);
if (auth == null) return runOtpFallback(); // 404 NO_PASSKEY -> use OTP

// 2. Run the hosted ceremony in a system auth session.
final AkedlyPasskeyResult result = await AkedlyPasskey.openCeremony(
  token: auth.ceremonyToken,
  callbackScheme: 'myapp',
  // ceremonyOrigin: 'https://localhost:5174', // shared-cert local QA
);

if (result.verified) {
  // 3. Confirm offline on YOUR backend without waiting for polling/callback. See below.
  await myBackend.completeSignIn(
    result.resultToken!,
    expectedRequestID: auth.requestID,
  );
} else if (result.reason == 'no_proof') {
  // The authentication may have SUCCEEDED and been billed — the relay just carried no proof.
  // Reconcile /result or the backend callback BEFORE starting OTP, or you charge twice.
  await reconcileThenMaybeOtp(auth.requestID);
} else {
  await runOtpFallback();
}

https://auth.akedly.io/pk?token=&returnUrl=myapp://akedly-passkey
   -> redirects to: myapp://akedly-passkey?verified=true&transactionId=…
      (resultToken ONLY if your backend signed returnTarget into the ceremony token)