ドキュメント

ネットワークを切ったまま検証できる資格情報

QR コードが証明そのものを持ち歩きます。qredential は署名、有効期限、失効状態、クレームを、端末から一度もリクエストを出さずに確認します。

はじめる

npm i qredential

Node 20 以降、現行のあらゆるブラウザ、そして React Native。WebCrypto だけを使い、Node 固有のものは使いません。検証する側の端末はたいてい携帯電話だからです。実行時の依存関係はありません。

テストスイート全体が、コミットのたびに Linux、macOS、Windows 上の Node 20、22、24 で、そして Chromium、Firefox、WebKit で実行されます。Ed25519 は四つすべてで動かしています。

何かを検証する

import { verify } from 2

const result = await verify(scannedText, { trust })

if (result.ok) {
  console.log(result.claims.given_name)   0
} else {
  console.log(result.reason)              1
}

一巡の流れ

三者、三つの呼び出し。発行者が一度署名し、保持者が渡るものを絞り、検証者が判断します。

import { issue, present, verify } from 9

0
const { credential, qr } = await issue({
  issuer: 'https:1
  kid: 10,
  key: issuerPrivateJwk,
  claims: {
    given_name: 11,
    family_name: 12,
    birth_date: 13,
    over_18: true,
  },
  disclose: [14, 15],
  holderKey: holderPublicJwk,
  expiresIn: 16,
})

2
3
const presentation = await present(credential, {
  disclose: [17],
  keyBinding: { key: holderPrivateJwk, audience: 'https:4
})

5
const result = await verify(presentation, {
  trust,
  nonce: challenge,
  audience: 'https:6
})
result.claims       7
result.claims.birth_date  8

選択的開示

別々の二者が別々の二つの判断を下します。これを混同するのが典型的な設計ミスです。発行者は署名時に disclose で、どのクレームを伏せてよいかを決めます。保持者はその中からどれを実際に見せるかを、読み取り時に、同じく disclose で決めます。発行者が指定しなかったクレームは、誰にも伏せられません。

仕組みはごく普通のハッシュです。開示可能な各クレームは 128 ビットのランダムなソルトとともに直列化され、その文字列のダイジェストだけが資格情報に署名されます。クレームを見せるとは、元の文字列を送って検証者にハッシュさせ、ダイジェストを突き合わせてもらうことです。伏せるとは、検証者の手元に決して開けないダイジェストが残るということです。

入れ子、配列、再帰的な開示

RFC 9901 は三つすべてを許し、欧州のウォレット圏は三つすべてを使います。ここでの検証は、7.1 節の処理モデルに従って、どの深さでもそれらを解決します。

• 入れ子オブジェクト内の _sd 配列は、そのオブジェクトのプロパティを隠します。
• {"...": digest} の形をした配列要素は、その要素自体を隠します。伏せられた要素はプレースホルダとして残らず配列から取り除かれるので、受け取るのはそのまま表示できるきれいな値です。
• 開示された値がさらにどちらの形も含みうるため、一つ解くとさらに現れます。

そのどれも claims には漏れません。_sd キーも "..." 要素も呼び出し側には届きません。開示された名前は address.locality のようなパスで返り、全体が同じ RFC の独立実装と双方向で突き合わせられています。

発行者が開示可能にしなかったクレームを要求すると、黙って要求より少なく返すのではなく、例外を投げます。

保持者を証明する

選択的開示が証明するのは、発行者がそれらのクレームに署名したことです。それだけでは、提示している人物が本人であることは証明されません。しかもこの隙間は理屈の上の話ではありません。他人のコードを撮った写真は同じ署名を持ち、まったく同じように検証を通ります。

鍵バインディングがこれを塞ぎます。発行者が保持者の公開鍵を資格情報に書き込み、読み取りの場で保持者のウォレットが対応する秘密鍵で新しいチャレンジに署名します。写真にはそれができません。

三つの手順

0
const { credential } = await issue({
  ...,
  holderKey: holderPublicJwk,
})

1
const presentation = await present(credential, {
  disclose: [6],
  keyBinding: {
    key: holderPrivateJwk,
    audience: 'https:2
    nonce: challengeFromTheVerifier,
  },
})

3
const result = await verify(scanned, {
  trust,
  nonce: challengeIIssued,
  audience: 'https:4
})
result.holderVerified   5

証明は四つのものに結び付き、それぞれが特定の攻撃を塞ぎます。nonce は記録された提示の再生を防ぎ、audience はある検証者向けの証明を別の検証者で使うことを防ぎ、署名は発行者が結び付けた鍵に紐づけ、sd_hash は提示された開示の集合そのものを覆うので、保持者の署名後に中継者が開示を足したり削ったりできません。証明には有効期限もあり、既定で五分、maxKeyBindingAge で調整できます。

静的な資格情報と、その選択を声に出して行うべき理由

カードに印刷されたコードには、以上のどれもできません。読み取りの場で署名する装置が存在しないので、静的な資格情報は本質的に複製可能です。これは誤りではなく、現実によくある状況です。ただし検証者が、それと知った上で下すべき判断です。

const result = await verify(scanned, { trust, acceptWithoutHolderProof: true })
result.holderVerified   0

この指定がなければ、証明のない提示は holder_proof_missing で拒否されます。既定を厳しい側にしてあるのは意図的です。危ないのは、入口の読み取り機を作る人が鍵バインディングの存在を知らないまま、スクリーンショットで破られるものを出荷する場合です。問題を名指しして大きな音を立てて失敗するほうが、それを覆い隠す静かな既定値よりも価値があります。

何を代償にするか

バインディングは QR の観点では無料ではありません。保持者の公開鍵は資格情報の中に居座り、証明は提示に付いて回ります。

証明そのものは約 285 文字です。見た目ほど問題にはなりません。鍵バインディングができる資格情報は、定義からして画面に表示されているのであり、そこではコードを大きく明るくできるからです。密度の限界が問題になるのは擦り切れた印刷カードであり、印刷カードはそもそも鍵バインディングをするはずがありません。

サイズの予算

QR コードは最大でも英数字およそ 4300 文字しか収まりませんが、その大きさのコードは傷んだカードやひび割れた画面では読めません。実用上の上限はバージョン 20 前後です。

現実的な運転免許証が費やす量は次のとおりです。クレーム八つ、有効期間五年、ステータスリストへのポインタ付き。リポジトリの examples/sizes.mjs で測定しています。

居心地が悪いのは真ん中の行で、カードを刷った後より、ここで知るほうがましです。選択的開示は資格情報をほぼ倍にします。開示可能なクレームごとにソルトと署名済みダイジェストがかかり、しかもダイジェストは、保持者がそのクレームを見せるかどうかに関わらずペイロードに残るからです。これは意図的です。見せた内容に応じてダイジェストの個数が減れば、何を伏せたかが漏れてしまいます。実際の帰結として、提示時の節約は直感が約束するより小さくなります。ここでは三割であって、八割ではありません。

ですから、検証者が単独で見る必要が本当にありうるクレームだけを開示可能にしてください。全部ではなく、二つか三つ。fits() が、決める前に現在地を教えてくれます。

オフラインでの失効確認

失効確認は実装が飛ばしがちな部分で、飛ばすと盗まれた資格情報が永遠に通ってしまいます。

ステータスリストは、資格情報一件につき一ビットの圧縮ビット列です。百万件を覆うリストはほとんどがゼロの 125 KB で、圧縮すれば数キロバイトになります。電波があるときに取得し、ないときに照合してください。

0
const statusList = await createStatusList({
  issuer: 'https:1
  kid: 4,
  key: issuerPrivateJwk,
  uri: 'https:2
  size: 1_000_000,
  revoked: [48219],
  expiresIn: 5,
})

3
const result = await verify(scanned, {
  trust,
  status: cachedStatusList,
  maxStatusAge: 6,
})

拒否の理由は読む価値があります。どれもが、もっと無口なライブラリなら偽の「はい」を返していたはずの場所だからです。

• リストを渡していないので、失効は一度も確認されていない: status_unavailable
• キャッシュしたリストが maxStatusAge より古いので、失効を否定できない: status_list_stale
• リストが信頼リストにない鍵で署名されている。攻撃者が失効済み資格情報を洗浄するならまさにこの手口: bad_signature
• リストの発行者が資格情報の発行者と異なる、あるいは uri が異なる。同じ添字でもリストごとに指すものが違うので、結び付いていないリストは答えにならない: status_unavailable
• 資格情報の添字が、キャッシュしたリストの外側にある。つまり実際には何も読めていない: status_unavailable

確信が持てないときにどうするかは、あなたの運用の方針の問題であってライブラリの問題ではないので、qredential はそれを黙って代わりに決めることを拒みます。失効が確認できたときは、成功した結果が revocationChecked: true でそう告げます。

信頼リスト

経路外で端末に届ける必要がある唯一のものが、あなたが信じてよいと考える発行者公開鍵の集合です。これはめったに変わらないので、アプリに同梱して週に一度更新する、というのはまったく妥当な配布方法です。

const trust = {
  issuers: {
    'https:0
      name: 1,
      keys: [{ kid: 2, alg: 3, jwk: publicJwk }],
    },
  },
}

どのアルゴリズムを使うかを決めるのは信頼された鍵であって、資格情報自身のヘッダに書かれたアルゴリズムでは決してありません。これがアルゴリズム置換に対する防御のすべてであり、alg が推測されるのではなく信頼リストの鍵側に置かれている理由です。

リストが端末にどう届くか、鍵をどう更新するか、秘密鍵をどこに置くかは対象外です。ライブラリはそれらを入力として受け取ります。

API リファレンス

四つの関数が資格情報の一生を覆い、加えて失効を公開する発行者向けに一つあります。

issue(options)

返り値は credential（SD-JWT の結合形式。ウォレットに保存するのはこれです）、qr（読み取り可能なエンベロープ）、bytes（qr の文字数）、disclosable（保持者が伏せられるクレーム名）です。

present(credential, options)

資格情報を列挙されたクレームに絞り、読み取り可能なエンベロープを返します。署名済み JWT には一切手を触れないので、残った内容に対して発行者の署名は依然として有効です。結合形式でもエンベロープでも受け付けます。発行者が開示可能にしなかったクレームを求めると例外を投げます。

disclose はパスを受け取ります。verify() が disclosed で返すものと同じです。

await present(credential, {
  disclose: [0, 1, 2],
})

名前だけを書けば一区間のパスなので、'over_18' はこれまでどおりの意味です。配列の添字は発行時の資格情報における位置であって提示側の位置ではないため、保持者がほかに何を伏せても、選択子は書いたとおりの意味を保ちます。また入れ子の開示は、それを含む開示なしには正当に渡れないので、address.locality を求めると address も一緒に送られます。呼び出し側に押しつけず、こちらで解決します。

verify(input, options)

敵対的な入力に対して例外を投げることはありません。判別可能な合併型を返します。成功時は { ok: true, claims, issuer, subject, issuedAt, expiresAt, disclosed, withheld, revocationChecked }、失敗時は { ok: false, reason, message } で、reason は下の表から取られます。

withheld は、渡らなかった開示可能クレームの個数です。方針判断には役立ちますが、構造上それがどれだったかを教えることはできません。

claims にあるものはすべて主体を記述します。 iss、iat、exp、status のようにトークン自体を記述する登録済みクレームは、代わりに型付きのフィールドとして現れます。そしてそれらを設定しようとする開示や、ペイロードが既に決めたクレームを上書きしようとする開示は、資格情報全体を失敗させます。したがって claims を素直に走査しても安全です。

fits(payload, errorCorrection)

同期関数。{ chars, version, capacity, comfortable, errorCorrection, advice } を返します。誤り訂正の既定が M なのは、L が紙の上では気前よく見えて、擦り切れた印刷カードでは失敗するからです。version はどのバージョンにも収まらないとき null になり、advice はビルドログにそのまま出せる一文です。

createStatusList(options)

発行者向け。issuer、key、kid、alg、uri、size、revoked、suspended、expiresIn、issuedAt を受け取り、署名済みのステータスリストトークンを返します。リストの外側の添字は、隣の資格情報のビットを壊すのではなく例外を投げます。

そのほかのエクスポート

QR エンベロープ用の pack、unpack、isEnvelope、およびコーデック単体の encodeBase45 と decodeBase45。ツール作りには便利ですが、通常の利用には不要です。

エラーの扱い

約束はちょうど二つあり、その分け方は偶然ではなく意図的です。この二文を覚えれば、catch ブロックを一つ書いて、そこに何が来うるかを把握できます。

分かれている理由は、verify() が敵対的な入力に向けられるために存在するからです。例外を投げる検証器は、誰かが try/catch で包んで人を素通しさせる検証器です。だから、あなたが必ず見る結果を返します。それ以外は、呼び出し側がコードで直せる条件で失敗するので、そこでは投げるのが正しい形です。

どちらの規則も、ランダムな文字列、壊れた鍵、破損したエンベロープ、敵対的なオプションを生成して、それ以外は何も外へ出ないことを主張する性質ベースのテストで支えられています。JSON パースからの SyntaxError も、WebCrypto からの DOMException も、確保時の RangeError も出ません。

検証結果を扱う

結果は判別可能な合併型なので、TypeScript が型を絞ってくれます。

const result = await verify(scanned, { trust })

if (result.ok) {
  result.claims          0
  result.withheld        1
} else {
  switch (result.reason) {
    case 2:            return askForARenewal()
    case 3:            return refuseAndLog()
    case 4:  return retryWhenOnline()
    default:                   return refuse(result.reason)
  }
}

コードベースが try/catch を中心に組まれているなら、同じ結果を assertVerified() に通してください。失われるものはありません。投げられるエラーが元の理由を持ち回ります。

import { verify, assertVerified, isQredentialError } from 1

try {
  const credential = assertVerified(await verify(scanned, { trust }))
  admit(credential.claims)
} catch (error) {
  if (isQredentialError(error) && error.code === 2) {
    refuse(error.reason)   0
  } else {
    throw error
  }
}

拒否理由

verify() が result.reason として返します。プレイグラウンドはこれらを一つずつ検証器に投げつけるので、届くところを見られます。

投げられるエラー

verify() 以外はすべて QredentialError を投げ、そこには code が入っています。instanceof ではなく isQredentialError() を使ってください。形を見るので、同じ依存ツリーにパッケージの写しが二つ入り込んでも動き続けます。それが instanceof が静かに一致しなくなる典型的な原因です。

下にあるものを読む

このライブラリが他所の失敗を包むところでは、元のものを標準の cause プロパティに保ちます。具体的なコードを得るために詳細を失うことはありません。

try {
  await unpack(scanned)
} catch (error) {
  if (isQredentialError(error)) {
    error.code           0
    error.cause          1
  }
}

これでないもの

• ウォレットではありません。 画面も保存機能もありません。
• 鍵管理ではありません。 鍵も、信頼リストの配布も、あなたが用意します。
• まだ ISO 18013-5 mDL ではありません。 あちらは JWT ではなく CBOR と COSE です。予定には入っていますが、適合規格を半分だけ満たしたと称するのは、何も称さないより悪いことです。
• 監査は受けていません。 公開された規格を実装し、プレイグラウンドの攻撃に対して試験していますが、テストが示せるのは防御の存在であって、その網羅性ではありません。

ソースは実行時依存ゼロでおよそ 1,300 行です。信頼する前に読むことが現実的であるように、あえてそうしてあります。脆弱性は GitHub の Security タブを通してください。範囲と応答期限は SECURITY.md にあります。