Xodian ドキュメント

#概要

Xodian を使うと、アプリはユーザーが正規の端末を使う実在の人物ひとりであることを確認できます。その人が誰なのかは知らないまま。自撮りも、本人確認書類のアップロードも、個人情報も不要です。

確認はユーザーが omni アプリで行います。あなたのバックエンドは署名付きの id_token（ES256 JWT）を受け取り、そこには次の情報が入っています：

• human：改造されていない正規の端末を使う実在の人物である
• sub：あなたのアプリだけが見られる、この人の非公開ID。何度訪れても同じ
• level：証拠の強さ（1 = デバイス、2 = 定着）
• uniqueness：この人があなたにとって初めて（new）か、再訪（returning）か、競合（contested）か

向いている用途

エアドロップや報酬キャンペーン（1人1回）、ゲームアカウントや体験版、コミュニティ投票、そして本格的なKYCの前段に置く安価なボット対策。

向いていない用途

Xodian は本人確認ではありません。名前・年齢・国籍は分からず、それだけで KYC/AML の義務を満たすこともありません。

#クイックスタート（10分）

秘密鍵を保管できるサーバーと、ボタンを表示するWebページまたはアプリが必要です。サンドボックスは無料で、登録も不要です。

1. テストキーを取得

   トップページのサンドボックス、またはAPIから取得します。シークレットは一度しか表示されないので、サーバーに保管してください。

   COPY

   curl -X POST https://xodian.xode.net/v1/test/clients \
     -H "Content-Type: application/json" \
     -d '{"name":"Acme Airdrop","domain":"acme.example"}'
   
   # → {"clientId":"rpt_3f9a…","clientSecret":"osk_rpt_3f9a…_…",
   #    "test":true,"baseUrl":"https://xodian.xode.net","dailyQuota":500}

2. サーバーからセッションを開く

   reference はこの試行に対するあなた自身のIDです（例：受け取りID）。トークンの nonce としてそのまま戻ってきます。

   COPY

   curl -X POST https://xodian.xode.net/v1/sessions \
     -H "Authorization: Bearer $XODIAN_SECRET" \
     -H "Content-Type: application/json" \
     -d '{"scope":["human"],"minLevel":1,"reference":"signup-42"}'

   COPY

   {
     "sessionId": "BQuIzVWtfYrpFA4_N4ZgzpLW",
     "pollToken": "CI_8JleZxedaAoDLo7Wg46vB",
     "expiresAt": 1791251375,
     "url": "https://xodian.xode.net/s/BQuIzVWtfYrpFA4_N4ZgzpLW",
     "deeplink": "xode://id?s=BQuIzVWtfYrpFA4_N4ZgzpLW",
     "scope": ["human"],
     "minLevel": 1,
     "test": true
   }

   このオブジェクトをそのままブラウザに渡してください。シークレットは含まれていません。

3. ボタンを表示

   ウィジェットはデスクトップではQRを、スマホでは「omniで続ける」ボタンを表示し、状態を確認して結果を知らせます。

   COPY

   <script src="https://xodian.xode.net/sdk.js"></script>
   <div id="verify"></div>
   <script>
     Xodian.button("#verify",
       () => fetch("/api/xodian/start", { method: "POST" }).then(r => r.json()),
       { onApproved: (s) => fetch("/api/xodian/finish?session=" + s.sessionId) });
   </script>

4. サンドボックスで応答

   テストセッションではウィジェット内にシミュレーションパネル（承認・拒否・不合格・期限切れ）が出ます。シミュレーターAPIも使えます。

5. サーバーでトークンを取得・検証

   シークレットでセッションを読み、idToken を JWKS で検証します。トークンの検証を参照してください。

#基本概念

セッション

1回の確認の試みです。あなたのサーバーが作成し、ユーザーは5分以内（expiresAt）に omni で応答します。すべてのセッションは必ずひとつの最終状態で終わります：

保証レベル

minLevel はセッションごとに指定します。それを下回ると rejected だけが返り、レベルなどの情報は返りません。

アプリ別ID（sub）

同じ人でもアプリごとに異なる sub になるため、パートナー同士がデータを突き合わせて人を追跡することはできません。あなたのアプリ内では固定で、同じ人には毎回同じ sub が返り、ウォレットを新しい端末に移しても変わりません。1台の端末の複数ウォレットは同じ sub になります。「1人1回」の判定キーには sub を使ってください。

一意性（uniqueness）

スコープ

human は常に含まれます。ユーザーの XODE ウォレットアドレスが必要なら wallet を追加します。ユーザーが omni で共有をオンにした場合のみ渡され、あなたのキーでこの権限が有効になっている必要があります。

reference と nonce

reference に渡した値（最大200文字）はトークンの nonce として返ります。必ず照合し、ある試行用のトークンが別の試行に使い回されないようにしてください。

#APIリファレンス

ベースURLは https://xodian.xode.net、リクエストもレスポンスもJSONです。サーバーからの呼び出しはクライアントシークレットで認証します：

Authorization: Bearer osk_<clientId>_<random>

POST /v1/sessions

{
  "sessionId": "BQuIzVWtfYrpFA4_N4ZgzpLW",
  "pollToken": "CI_8JleZxedaAoDLo7Wg46vB",
  "expiresAt": 1791251375,
  "url": "https://xodian.xode.net/s/BQuIzVWtfYrpFA4_N4ZgzpLW",
  "deeplink": "xode://id?s=BQuIzVWtfYrpFA4_N4ZgzpLW",
  "scope": ["human"],
  "minLevel": 1,
  "test": true
}

url はQRに入るアドレス、deeplink は同じ端末で omni を直接開きます。ブラウザには sessionId、pollToken、url、deeplink、expiresAt を渡してください。

GET /v1/sessions/{id}

サーバー専用です。状態を返し、approved のときは idToken、sub、level も返します。セッションを作ったクライアントだけが読めます。

curl https://xodian.xode.net/v1/sessions/BQuIzVWtfYrpFA4_N4ZgzpLW \
  -H "Authorization: Bearer $XODIAN_SECRET"

# approved →
{
  "sessionId": "BQuIzVWtfYrpFA4_N4ZgzpLW",
  "status": "approved",
  "expiresAt": 1791251375,
  "idToken": "eyJhbGciOiJFUzI1NiIs…",
  "sub": "oid_9f3c1a8be41d…",
  "level": 1
}

# rejected →
{ "sessionId": "…", "status": "rejected", "reason": "insufficient_level", "expiresAt": … }

GET /v1/sessions/{id}/status

ブラウザ向けです。セッション専用の pollToken で分かるのは状態と（最終状態なら）理由だけです。ウィジェットが1〜3秒ごとに代わりに呼び出します。

GET https://xodian.xode.net/v1/sessions/{sessionId}/status?t={pollToken}

{ "sessionId": "…", "status": "pending", "expiresAt": 1791251375 }

ディスカバリーと鍵

GET https://xodian.xode.net/v1/.well-known/configuration

{
  "service": "Xodian",
  "issuer": "https://xodian.xode.net",
  "jwks_uri": "https://xodian.xode.net/v1/.well-known/jwks.json",
  "sessions_endpoint": "https://xodian.xode.net/v1/sessions",
  "scopes_supported": ["human", "wallet"],
  "levels": { "1": "device", "2": "established" },
  "id_token_signing_alg_values_supported": ["ES256"],
  "session_ttl_seconds": 300
}

鍵は ES256（P-256）です。鍵を更新しても以前の鍵はしばらく JWKS に残るため、更新直前に署名されたトークンも検証できます。JWKS はキャッシュし、未知の kid が来たら取り直してください。

エラー

エラーは JSON {"detail": "…"} で、detail はメッセージ、または code と message を持つオブジェクトです。

#Webウィジェット（sdk.js）

依存関係のない小さなスクリプトひとつです。どのページ・どのフレームワークでも動きます。

<script src="https://xodian.xode.net/sdk.js"></script>

Xodian.button(target, getSession, options)

target（セレクターまたは要素）に「Verify with Xodian」ボタンを描画します。クリックすると getSession() を待ちます。この関数はあなたのバックエンドから取得したセッションオブジェクトを返す必要があります。その後モーダルを開きます。

<script src="https://xodian.xode.net/sdk.js"></script>
<div id="verify"></div>
<script>
  Xodian.button("#verify",
    () => fetch("/api/xodian/start", { method: "POST" }).then(r => r.json()),
    { onApproved: (s) => fetch("/api/xodian/finish?session=" + s.sessionId) });
</script>

Xodian.open(session, options)

手元にあるセッションでモーダルを開きます。{ close() } を返します。

// Your own button, your own flow:
const session = await fetch("/api/xodian/start", { method: "POST" }).then(r => r.json());

const modal = Xodian.open(session, {
  onApproved: (s) => finish(s.sessionId),     // fetch the token on YOUR server
  onRejected: (s) => explain(s.reason),
  onDenied:   () => {},
  onExpired:  () => {},
  onClose:    () => {},                       // closed by the user
});
// modal.close() closes it from code.

オプション

文言と言語

モーダルの既定は英語です。text を渡すと翻訳したり、サービスの口調に合わせたりできます。キー：title、subtitle、step1、step1m（モバイル）、step2、step3、openApp、noApp、secured、okTitle、okBody、deniedTitle、deniedBody、rejTitle、rejBody、expTitle、expBody、close。指定のないキーは英語になります。

Xodian.open(session, {
  text: {
    title: "사람 인증",
    subtitle: "실제 사람인지 확인해요. 이름·번호·지갑은 공유되지 않아요.",
    step1: "omni 앱으로 스캔", step2: "공유 내용을 확인하고 승인", step3: "완료",
    close: "닫기",
  },
});

ネイティブアプリ

// iOS / Android / Flutter: no QR needed on the same phone.
// Open the deeplink from the session your backend created:
openURL(session.deeplink)          // xode://id?s=…

// omni asks the person, then returns them. Your app polls your backend,
// which reads GET /v1/sessions/{id} with the secret.

#Xodian Connect（ウォレット）

Connect は web3 ゲートウェイとしての Xodian です。ブラウザ拡張なしで、あなたのサイトが利用者の XODE ウォレットに接続して署名を求めます。リカバリーフレーズは omni アプリから出ず、すべてのリクエストは署名前にそのアプリで利用者に表示されます。

流れはこうです。あなたのバックエンドがセッションを開き、利用者が omni で承認し（デスクトップは QR、スマートフォンはディープリンク）、あなたのページが connect トークンを一度だけ受け取り、以降はそのトークンで署名を求めます。

セッションを開く

ライブクライアントはバックエンドからクライアントシークレットと共にセッションを開き、ブラウザには sessionId と pollToken だけを渡します。

POST https://xodian.xode.net/v1/connect/sessions
Authorization: Bearer osk_<clientId>_<secret>
Origin: https://your-domain.example
Content-Type: application/json

{"clientId":"rp_…","scope":["human","wallet"],"minLevel":1}

サンドボックスキーはブラウザのみの経路を保ちます。セルフサービスの rpt_ キーは、登録ドメインまたは http://localhost からページで直接セッションを開けます。そこでは対価がないからです — 実機はサンドボックスセッションを拒否するため、実際のウォレットには届きません。そのようなセッションは同意画面で未検証と表示され、ライブクライアントがシークレットなしで開いたセッションも同じです。

SDK

<script src="https://xodian.xode.net/connect.js"></script>

XodianConnect.init({ clientId: 'rp_…', chainId: 3417 });
const { address, evmAddress, sub, level } = await XodianConnect.connect();
XodianConnect.disconnect();

接続情報（トークン・アドレス・ペアワイズ sub・レベル）はページ自身の localStorage に保存され、30 日間有効です。署名呼び出しで 401 が返るのは失効または期限切れで、SDK が消去して再接続します。

発見経路は 2 つあります。EVM ライブラリには EIP-6963 で XODE omni（rdns: net.xode.omni）として自らを通知します。そのため wagmi・RainbowKit・viem の一覧に、window.ethereum の枠を奪い合わずに現れます — その枠を埋めたく、かつ空いている場合のみ init({ injectEthereum: true }) を使ってください。polkadot-js アプリには window.injectedWeb3.xodian として公開され、enable()・accounts.get()・signer を提供します。

プロバイダのメソッド

扱うべきエラー

omni が拒否するもの、その理由

署名画面がセキュリティ境界です。だから利用者に説明できないものは拒否します。以下は想定される動作であり、正しい挙動として扱ってください。

• XODE 自身の予約文字列であるメッセージ — xode- で始まるすべて。これらはウォレットを XODE 自身に認証させる文字列であり、サイトが要求できてはなりません。
• omni が生のバイト列から確認できないパレット・コール番号のコール。デコーダに尋ねる前に判定します。
• バッチのラッパー。中に何が入っているかを読むにはチェーンのメタデータ全体が必要で、端末はそれを持たないため、信頼で承認せず拒否します。
• omni がバイト列から自ら再構成する 2 つの送金以外の残高送金すべて。「全額送金」の類を排除する方法です。
• bidi オーバーライドやゼロ幅文字を含むテキスト — 警告付きで hex 表示されます。そうした行は書かれている内容と違って読めるためです。
• 長いメッセージは利用者が開くまで。おおよそ 400 文字または 8 行を超えると折りたたまれ承認ボタンが無効になるため、画面の下に隠した要求をタップ一回で署名させられません。ログインメッセージは短く保ってください。

レシート

すべての署名の判断は Sentinel 台帳に記録され XODE にアンカーされます（検証と同じです）。拒否にはウォレットの署名が載るため、利用者が拒否したというレシートは実際に利用者を意味します。署名なしに閉じられたリクエストはキャンセルとして記録されます。

上限

#トークンの検証

検証は必ずサーバーで行ってください。ブラウザが伝える状態は信用しないでください。

クレーム

{
  "iss": "https://xodian.xode.net",
  "aud": "rp_acme",
  "sub": "oid_9f3c1a8be41d02c7aa50e07b",
  "iat": 1791251090, "exp": 1791251690,
  "jti": "BQuIzVWtfYrpFA4_N4ZgzpLW",
  "nonce": "signup-42",
  "human": true,
  "level": 2, "level_name": "established",
  "uniqueness": "new",
  "verified_at": 1791251090,
  "receipt": "1791251090-a1b2c3d4",
  "wallet": "XqF4…"          // only with the wallet scope AND the person's consent
}

チェックリスト

1. 署名が ES256 で、JWKS で検証できる
2. iss が https://xodian.xode.net、aud があなたのクライアントID
3. exp を過ぎていない
4. nonce がセッション作成時の reference と一致
5. jti が未使用
6. 本番では test が付いていない
7. level がその操作に必要な水準以上

import { createRemoteJWKSet, jwtVerify } from "jose";

const JWKS = createRemoteJWKSet(
  new URL("https://xodian.xode.net/v1/.well-known/jwks.json"));

export async function finish(sessionId, expectedReference) {
  const s = await fetch(`https://xodian.xode.net/v1/sessions/${sessionId}`, {
    headers: { Authorization: `Bearer ${process.env.XODIAN_SECRET}` },
  }).then(r => r.json());
  if (s.status !== "approved") return { ok: false, reason: s.reason || s.status };

  const { payload } = await jwtVerify(s.idToken, JWKS, {
    issuer: "https://xodian.xode.net",
    audience: process.env.XODIAN_CLIENT_ID,
    algorithms: ["ES256"],
  });
  if (payload.nonce !== expectedReference) throw new Error("token is for another session");
  if (payload.test && process.env.NODE_ENV === "production") throw new Error("sandbox token");
  await db.usedTokens.insertUnique(payload.jti);          // one use per token
  return { ok: true, person: payload.sub, level: payload.level,
           contested: payload.uniqueness === "contested" };
}

import os, requests, jwt   # pip install "pyjwt[crypto]" requests

JWKS = jwt.PyJWKClient("https://xodian.xode.net/v1/.well-known/jwks.json")

def finish(session_id, expected_reference):
    s = requests.get(f"https://xodian.xode.net/v1/sessions/{session_id}",
                     headers={"Authorization": f"Bearer {os.environ['XODIAN_SECRET']}"},
                     timeout=10).json()
    if s["status"] != "approved":
        return None
    key = JWKS.get_signing_key_from_jwt(s["idToken"]).key
    claims = jwt.decode(s["idToken"], key, algorithms=["ES256"],
                        audience=os.environ["XODIAN_CLIENT_ID"],
                        issuer="https://xodian.xode.net")
    assert claims["nonce"] == expected_reference
    assert not claims.get("test"), "sandbox token"
    return claims          # claims["sub"] is your key for this person

#Webhook

ポーリングの代わりに、本番キーではセッションが最終状態になったときに POST で通知を受け取れます。Webhook は本番キーの発行時に設定します（セルフサービスのテストキーにはありません）。

POST https://your-app.example/xodian/webhook
Content-Type: application/json
User-Agent: xodian-webhook/1
X-Omni-Signature: t=1791251090,v1=5f1c…e9

{"event":"session.approved","sessionId":"…","status":"approved",
 "expiresAt":1791251375,"idToken":"eyJhbGciOiJFUzI1NiIs…"}

# when the person removes your app in omni:
{"event":"grant.revoked","sub":"oid_9f3c1a8be41d02c7aa50e07b"}

署名の検証

ヘッダーは t=<UNIX秒>,v1=<hex> で、v1 = HMAC-SHA256(Webhookシークレット, t + "." + 生の本文) です。リプレイを防ぐため、古いタイムスタンプは拒否してください。

import crypto from "node:crypto";

// Use the RAW request body, exactly as received.
function verifyXodian(rawBody, header, secret /* whsec_… */) {
  const parts = Object.fromEntries(header.split(",").map(p => p.split("=")));
  const expected = crypto.createHmac("sha256", secret)
    .update(`${parts.t}.${rawBody}`).digest("hex");
  const ok = parts.v1 && crypto.timingSafeEqual(
    Buffer.from(expected), Buffer.from(parts.v1.padEnd(expected.length)));
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  return ok && fresh;
}

配信

8秒以内に 2xx を返してください。そうでなければ間隔を広げながら合計4回まで試行します。同じ通知が重複することがあるので sessionId で冪等に処理し、idToken は通常どおり検証してください。

#サンドボックス

テストキー（rpt_…）は無料で、自分で作成できます。本番と同じですが、次の点が異なります：

• セッションへの応答はウィジェットのシミュレーションパネルか、APIのシミュレーターで行う
• トークンに "test": true が付き、sub は oid_test_ で始まる
• Webhook とオンチェーンレシートはない
• キーごとに1日500セッション、ネットワークごとに1日5個まで新規キー

シミュレーター

curl -X POST https://xodian.xode.net/v1/test/sessions/$SESSION_ID/simulate \
  -H "Content-Type: application/json" \
  -d '{"outcome":"approve","level":2,"persona":"alice","shareWallet":true}'

# outcome:    approve | deny | reject | expire
# level:      1 | 2                      (approve)
# persona:    any name; same persona → same sub
# uniqueness: new | returning | contested (optional, forces the value)
# reason:     insufficient_level | device_unverified | no_device | integrity_stale (reject)

同じ persona は常に同じ sub になるので、「1人1回」や再訪ユーザーをテストできます。セッションの minLevel より低いレベルで承認すると、本番と同じく不合格になります。

#不合格の理由

不合格のセッションには reason が付きます。ユーザーには中立的なメッセージを表示してください。詳細は omni が本人にだけ説明します。

未知の理由は一般的な不合格として扱ってください。新しいコードが追加されることがあります。

#オンチェーンレシート

本番のすべての判定（承認・拒否）は Sentinel 台帳に記録され、1時間ごとに XODE チェーンにアンカーされます。トークンの receipt がその記録のハンドルです。あなたや監査人は後から、Xodian がその時点で実際にその判定をし、その後誰も変更していないことを証明できます。

GET https://xodian.xode.net/sentinel/receipt/1791251090-a1b2c3d4
GET https://xodian.xode.net/sentinel/anchors
GET https://xodian.xode.net/sentinel/verify.py     # independent verifier, standard library only

台帳は公開されているため、個人情報は含みません。対象はハッシュ値で、sub やウォレットではありません。

#セキュリティチェックリスト

• クライアントシークレットはサーバーだけに置く。Webページ、アプリのバンドル、リポジトリに入れない
• すべてのトークンを自分で検証する：署名、iss、aud、exp、nonce、1回限りの jti
• 1人1回の特典はウォレットやメールではなく sub で判定する
• リリース前に contested の扱いを決める（受け入れ・確認・拒否）
• お金や投票が関わる場面ではレベル2を使う
• 本番では test トークンを拒否する
• 必要なものだけを保存する。多くの場合 sub と日付で十分

#上限とキー

セッションの有効期間は5分、トークンは10分です。本番キーは依頼に応じて更新できます。新しいキーが発行された瞬間に古いキーは無効になるので、すぐに反映してください。

#利用者の方へ

ユーザーにこのセクションへのリンクを送っても構いません。ユーザーが見る流れ：

1. omni をインストール

   Google Play と App Store で無料です。omni はスマホでライトノードを動かす XODE のアプリです。

2. 読み取るかタップ

   パソコンでは omni アプリでQRを読み取ります。スマホでは「omniで続ける」をタップします。

3. 共有内容を確認して承認

   omni はどのアプリが求めているか、何を受け取るかを正確に表示します。承認するとウォレットキーと端末のハードウェアキーで署名します。

4. 完了

   アプリに伝わるのは、実在の人物であることと、そのアプリだけが見られる非公開IDだけ。名前・番号・残高・利用履歴は決して共有されません。

連携アプリの管理

omni の設定 → Xodianで、確認したアプリの一覧と現在のレベルを見たり、アプリを解除したりできます。解除するとアプリに通知されますが、アプリが既に持っているデータの削除はそのアプリ次第です。必要なら直接依頼してください。

「不合格になりました」

omni が理由と解決方法を表示します。多くの場合、改造していない端末でストア版の omni を使う、omni を開いて端末を再確認する、レベル2を求めるアプリなら同じ端末で2週間ほど omni を使い続ける、で解決します。

#よくある質問

変更履歴

• 2026-10-06 xodian.xode.net に移転し、短いパス（/v1/…、/sdk.js、/s/<id>）を導入。発行者は https://xodian.xode.net に。QR案内ページを4言語に対応。
• 2026-10-05 v1：セッション、レベル1–2、アプリ別ID、一意性、ウィジェット、サンドボックスとシミュレーター、Webhook、オンチェーンレシート。