<aside> 💡

GeoAuthとは

GeoAuthは、位置情報を暗号学的に証明してIDトークンに反映する“場所起点”の認証レイヤーです。ユーザーの基準位置をSBT（Soulbound Token）としてブロックチェーンに結び付け、以後のアクセス時にGeohash＋HMAC-SHA256で生成した署名を検証し、その結果をJWT/Firebaseトークンに埋め込んで返却します。これにより「その人が、想定された場所から操作しているか」をアプリ側が即時に判定できます。

全体像（アーキテクチャと基本フロー）

• 構成要素：クライアントアプリ、GeoAuth API、データストア（Firestore等）、SBTスマートコントラクト、認証サービス（JWT/Firebase）、KMS/Secret Manager。各コンポーネントが連携し、位置データの保存・検証とトークン発行を行います。
• 初回登録（/register-sbt）：ユーザーの基準位置（緯度経度）をGeohash化しHMAC署名を行います。SBTをmintして保存し、salt（digital_secret）やgeoauth_secret等を払い出します。併せてクライアント向けIDトークンも発行します。
• 通常認証（/access-token）：基準位置のlocation_signatureを作成して送信。SBTトークンに保存済みの位置情報とHMAC署名を照合し、成功時にJWT/Firebaseトークンを返却します（nonce/timestampでリプレイ対策）。
• 初期位置検証（/verify-first-location）および継続検証（/verify-user-location）：JWTで保護されたAPIとして、署名の妥当性をverifiedフラグで返します。

主要機能

• 位置情報認証
  • Geohash精度は8文字（約19m×19m）。署名生成はHMAC-SHA256。保存位置はSBTおよびFirestoreに暗号化して保持します。
• トークン連携
  • Firebaseカスタムトークン＋JWTを併用。デフォルトでJWTは2時間、Firebaseトークンは1時間の有効期限。全APIは@jwt_requiredで保護され、トークン内user_idとリクエストのuser_idを突き合わせます。
• SBT管理
  • SBTokenコントラクトと連携してmint/get（getSBTData）を実行。SBTにはlocation_hashやpartner_id等のメタを保持できます。
• セキュリティ設計
  • KMS/Secret Managerで署名鍵を安全管理、nonceによる重複使用防止、HMAC比較の安全実装、保存データの暗号化などを明記。
• パフォーマンス要件
  • 1リクエスト平均50ms以下の処理目標。

効用（導入メリット）

• なりすまし・乗っ取りの抑止

  場所条件を暗号学的署名で強制するため、パスワードや端末トークン流出だけでは突破しにくい。nonce/timestampや短いトークンTTLもセッション悪用を抑えます。

• 高リスク操作のガードレール

  送金・設定変更などを「登録済み地点からのみ許可」といったポリシーで実装しやすい（検証結果はJWTに含まれるためアプリ側が即判定可能）。

• 監査性と連携容易性

  SBTへlocation_hashや更新履歴をもたせられ、ブロックチェーン連携の監査ログとして活用可能。API・サンプルコードが整備され、既存のFastAPI／Firebase／EVMスタックに馴染みます。

• ユーザー体験と運用性の両立

  通常は署名付きリクエストを送るだけで、アプリはverifiedフラグや新しいIDトークンを受け取るシンプルな運用です。

前提・注意点

• 位置精度のばらつき：屋内などで精度が低い場合は失敗しやすいため、運用では許容距離（例：100m）や再試行導線を設ける必要があります。
• 鍵・秘密情報管理：KMS/Secret ManagerでユーザーごとのHMAC秘密鍵を厳格管理の必要があります。クライアント保存値（salt等）は安全保管してください。
• トークン運用：Bearer付与やTTL切れ、user_id不一致で401となるため、リフレッシュや再ログインのUXを設計。
• チェーン連携：SBT mint時はガス設定・CHAIN_ID・管理者鍵の設定を確認。 </aside>

1. 認証システムコア機能

1.1 位置情報認証システム

• 基準位置登録:
  • ユーザー登録時(register-sbt API)に指定された位置情報をSBTトークンをmintして保存
  • 座標形式: 緯度経度をGeohashアルゴリズムで位置情報をハッシュ化、HMAC-SHA256で署名を生成
• 位置検証プロセス:
  1. 認証リクエスト(access-token API)で現在位置を送信
  2. Geohashアルゴリズムで位置情報をハッシュ化
  3. HMAC-SHA256で署名を生成
  4. 署名を検証して位置情報の正当性を確認
  5. 検証結果をJWTトークンに含めて返却
• 技術仕様:
  • ハッシュ化: Geohashアルゴリズムを使用 (精度:8文字)
  • 署名生成: HMAC-SHA256を使用
  • セキュリティ:
    • 保存位置データはSBTとFirestoreで暗号化
    • 署名用シークレットキーは環境変数で管理

1.2 トークンベース認証

• FirebaseカスタムトークンとJWTを併用（generate_jwt関数）
• アクセストークンは/access-tokenで取得
• JWT有効期限:2時間（generate_jwt_base関数）
• @jwt_requiredデコレータでAPI保護

2. GeoAuth API仕様 (最新版)

2.1 認証・位置情報API

• POST /access-token - アクセストークン発行
  • 基準位置認証フロー
  • 必須パラメータ:
    • user_id: SBT登録時に発行されたユーザーID
    • digital_id: デジタルID
    • timestamp: UNIXタイムスタンプ
    • nonce: ランダム文字列(リプレイ攻撃防止)
    • location_signature: 位置情報署名
  • 処理フロー:
    1. HMAC署名検証 (verify_hmac関数)
    2. SBTから保存位置情報取得 (get_saved_location_from_sbt)
    3. 署名検証 (hmac.compare_digest)
    4. JWTトークン生成 (generate_jwt)
  • レスポンス:
    • status: “success”|“error”
    • user_id: ユーザーID
    • access_token: Firebaseカスタムトークン変換後のIDトークン
  • エラーコード:
    • 400: 必須パラメータ不足/不正
    • 401: HMAC署名検証失敗
    • 500: 内部サーバーエラー
• POST /verify-first-location - 初期位置検証
  • ユーザー登録後の最初の位置認証用
  • @jwt_required必須
  • 必須パラメータ:
    • user_id: ユーザーID
    • digital_id: デジタルID
    • timestamp: UNIXタイムスタンプ
    • nonce: ランダム文字列
    • location_signature: 位置情報署名
  • レスポンス:
• エラーコード:
• GET /get-user-auth/{user_id} - ユーザー認証情報取得
• POST /verify-user-location - 位置検証(更新版)