Bun.passwordで、パスワードをハッシュ化して照合する方法

​​Bun​Argon2,bcrypt,TypeScript

Bun には、パスワードをハッシュ化する Bun.password.hash() と、入力されたパスワードがハッシュと合うかを確かめる Bun.password.verify() が組み込まれています。argon2id と bcrypt に対応していて、npm でパッケージを入れる必要はありません。

会員登録やログインの機能を作り、ユーザーのパスワードをデータベースに保存するときに使います。基本の書き方、アルゴリズムとコストの指定、エラーになる場合、bcrypt の72バイトの扱い、設定ごとにかかる時間を、検証環境で実際に動かして確かめました。

補足

検証環境は Ubuntu 24.04(x86_64、4 CPU)、Bun 1.4.4 です。コードは TypeScript で書き、bun ファイル名.ts で実行しました。ほかの言語との互換は、Python 3.11 の bcrypt 5.0.0 と argon2-cffi 25.1.0 でだけ確かめています。Windows と macOS、データベースへの保存、Node.js の bcrypt パッケージなどとの比較は試していません。公式ドキュメントは、検証に使った版(タグ bun-v1.4.4)の元ファイルを GitHub で確認し、リンクもそこに張っています。

ハッシュ化して、照合する

次の basic.ts で、同じパスワードを2回ハッシュ化し、正しいパスワードと違うパスワードで照合しました。

ts
const password = "neko-no-te-2026";

// ハッシュにする(既定は argon2id)
const hash = await Bun.password.hash(password);
console.log(hash);
console.log(`長さ: ${hash.length}`);

// 確かめる
console.log("正しいパスワード:", await Bun.password.verify(password, hash));
console.log("違うパスワード:", await Bun.password.verify("neko-no-te-2025", hash));

// 同じパスワードでも、ハッシュにするたびに結果が変わる
const again = await Bun.password.hash(password);
console.log(again);
console.log("1回目と同じ文字列か:", hash === again);
console.log("2回目のハッシュでも確かめられるか:", await Bun.password.verify(password, again));
text
$argon2id$v=19$m=65536,t=2,p=1$u91IIDCd+ANrJT5iqNeXrOAHKqMpcmlbd+kJFi9Foho$06f78OE3VMQLI/zjCbsro+T0k0yH/4kM+weP2/Mm5Ko
長さ: 118
正しいパスワード: true
違うパスワード: false
$argon2id$v=19$m=65536,t=2,p=1$iUC7nLqUtLAYJKztXJoAAwL4FZ0Bg02uowvbCov5vV8$+L0uHCse7mjwsyhVzuwv7zavxsKVKe0aQJBbWQfiZ3U
1回目と同じ文字列か: false
2回目のハッシュでも確かめられるか: true

hash() も verify() も Promise を返すので、await で受け取ります。verify() は、合えば true、合わなければ false を返しました。

同じパスワードでも、2回目のハッシュは1回目と違う文字列になりました。hash() はソルト(ハッシュごとに変えるランダムな値)を自動で作り、ハッシュの文字列の中に入れるためです(公式ドキュメントのソルトの説明)。ソルトを別の場所に保存する必要はありません。hash() が返した文字列だけで照合できました。

ハッシュの文字列は $ で区切られていて、先頭から、アルゴリズム(argon2id)、バージョン(v=19)、使うメモリの量(m=65536、単位は KiB)、繰り返しの回数(t=2)、並列度(p=1)、ソルト、ハッシュの本体が並びます(公式ドキュメントの argon2 の形式の説明)。

アルゴリズムとコストを指定する

hash() の2つ目の引数で、アルゴリズムとコストを指定できます。アルゴリズムの名前だけを文字列で渡すこともできます。argon2 では memoryCost(メモリの量、KiB)と timeCost(繰り返しの回数)を、bcrypt では cost(4〜31、既定は10)を指定します(公式ドキュメントにある、2つ目の引数の説明、型定義の bcrypt の cost の説明)。

ts
const password = "neko-no-te-2026";

const hashes = {
  "argon2id(既定)": await Bun.password.hash(password),
  "argon2id、memoryCost 19456・timeCost 2": await Bun.password.hash(password, {
    algorithm: "argon2id",
    memoryCost: 19456,
    timeCost: 2,
  }),
  "argon2i": await Bun.password.hash(password, "argon2i"),
  "bcrypt(既定)": await Bun.password.hash(password, "bcrypt"),
  "bcrypt、cost 12": await Bun.password.hash(password, { algorithm: "bcrypt", cost: 12 }),
};

for (const [label, hash] of Object.entries(hashes)) {
  // verify は、ハッシュの文字列からアルゴリズムを読み取る
  console.log(`${label}\n  ${hash}\n  verify: ${await Bun.password.verify(password, hash)}`);
}

// アルゴリズムを指定して、ハッシュと合わないとき
try {
  await Bun.password.verify(password, hashes["bcrypt(既定)"], "argon2id");
} catch (e) {
  console.log(`${(e as Error).name}: ${(e as Error).message}`);
}
text
argon2id(既定)
  $argon2id$v=19$m=65536,t=2,p=1$W7QNZOBZvxaWj/SSd5xvmXg9gaign+YOdSBZkSe4qOM$eqrwDrNMdN1ZC0iUSqgn13Dof3jJ7Yvny621Sa3CxVI
  verify: true
argon2id、memoryCost 19456・timeCost 2
  $argon2id$v=19$m=19456,t=2,p=1$LePcEVODtL5O5niRKKslMOsrqlrsHcDiszRW3RC3dqE$+DPOPlP15LYcmNjcF/jdapccxC4asxjH6FY/0ndFHCs
  verify: true
argon2i
  $argon2i$v=19$m=65536,t=2,p=1$1kmzx9qgkADxUKkdbVuDTLu6mbt7zO0wJjfIjJlH85U$kPaoXzv1k7xqqFz9YlqLtOKMrssBYbyMtxn7DO2B3Bg
  verify: true
bcrypt(既定)
  $2b$10$iyriz6z4WNgBEMn1UOLqbOn7VhOOKlyEJy0LFSAVzR.uy7ceXcPdS
  verify: true
bcrypt、cost 12
  $2b$12$62eUiGJRsBWWh1GAgju6j.6DAbrezinikmsxWDxN6fwET5IOCmHaO
  verify: true
Error: Password verification failed with error "InvalidEncoding"

指定したコストは、ハッシュの文字列にそのまま入りました(m=19456、$2b$12$)。bcrypt のハッシュは $2b$ で始まる60文字の形式です。

verify() には、どのアルゴリズムのハッシュでも、アルゴリズムを指定せずに渡せました。ハッシュの文字列からアルゴリズムを読み取るためです(公式ドキュメントの verify の説明)。そのため、あとでコストやアルゴリズムを変えても、前の設定で作ったハッシュはそのまま照合できます。3つ目の引数でアルゴリズムを指定し、それがハッシュと合わないときは、false ではなくエラーになりました。

設定ごとにかかる時間

パスワードのハッシュは、総当たりで破られにくいよう、わざと時間がかかるように作られています。設定ごとに hash() と verify() を10回ずつ実行して、1回あたりの時間を測りました。3回測った結果です。

設定 hash(3回) verify(3回)
argon2id(既定、m=65536 t=2) 140.4 / 148.4 / 140.7 ms 126.0 / 116.8 / 111.1 ms
argon2id m=19456 t=2 44.3 / 32.9 / 33.9 ms 36.0 / 33.3 / 35.1 ms
bcrypt cost 10(既定) 77.6 / 79.3 / 77.4 ms 77.0 / 78.0 / 78.3 ms
bcrypt cost 12 306.0 / 313.6 / 307.8 ms 313.0 / 310.9 / 308.3 ms
bcrypt cost 14 1,237.7 / 1,244.9 / 1,219.7 ms 1,226.6 / 1,224.4 / 1,218.6 ms
Bun.password.hash 1回にかかった時間の横棒グラフ。argon2id(既定)140.7 ms、argon2id m=19456 t=2 33.9 ms、bcrypt cost 10(既定)77.6 ms、bcrypt cost 12 307.8 ms、bcrypt cost 14 1237.7 ms
設定ごとの hash 1回の時間。10回の平均を3回測った中央値

bcrypt は、cost を2つ上げるごとに時間が約4倍になり、cost 12 で約0.3秒、cost 14 で約1.2秒かかりました。verify() も hash() とほぼ同じ時間がかかるので、この時間はログインのたびにかかります。数字は検証用VMでの値です。

表の m=19456 t=2 は、OWASP の Password Storage Cheat Sheet が argon2id の最低限の設定の1つとして挙げている値(19 MiB、2回、並列度1)です。Bun の既定(64 MiB、2回)は、これより多くのメモリを使います。同じ文書は、bcrypt を Argon2 や scrypt が使えない古いシステム向けとしたうえで、cost は10以上にするよう書いています(bcrypt の節)。

エラーになる場合と、false が返る場合

まちがった値を渡したときの動きを、次の edge.ts で確かめました(コードと出力の抜粋)。

ts
await tryIt("空のパスワードをハッシュにする", () => Bun.password.hash(""));
await tryIt("空のパスワードを確かめる", () => Bun.password.verify("", hash));
await tryIt("空のハッシュで確かめる", () => Bun.password.verify("neko-no-te-2026", ""));
await tryIt("ハッシュでない文字列で確かめる", () => Bun.password.verify("neko-no-te-2026", "abc"));
await tryIt("bcrypt の cost に 3", () => Bun.password.hash("x", { algorithm: "bcrypt", cost: 3 }));
await tryIt("argon2id の memoryCost に 4", () => Bun.password.hash("x", { algorithm: "argon2id", memoryCost: 4 }));
text
空のパスワードをハッシュにする: TypeError: password must not be empty
空のパスワードを確かめる: false
空のハッシュで確かめる: false
ハッシュでない文字列で確かめる: Error: Password verification failed with error "UnsupportedAlgorithm"
bcrypt の cost に 3: TypeError: Rounds must be an integer between 4 and 31
argon2id の memoryCost に 4: TypeError: Memory cost must be at least 8

空のパスワードは、hash() ではエラーになり、verify() では false が返りました。型定義のコメントにも、同じ動きが書かれています(型定義の verify と hash の説明)。

注意したいのは、verify() にハッシュの形式でない文字列を渡したときです。空の文字列では false でしたが、"abc" では false ではなく例外になりました。型定義にも、ハッシュが不正なら例外を投げると書かれています。

bcrypt の72バイトを超えるパスワード

公式ドキュメントによると、bcrypt のライブラリは、ふつうは72バイトを超えた部分を切り捨てます。Bun は切り捨てずに、72バイトを超えるパスワードを SHA-512 にかけてから bcrypt に渡します(72バイトについての公式ドキュメントの説明)。先頭の72バイトが同じで、73バイト目だけが違うパスワードで確かめました(edge.ts の続き)。

ts
const base = "a".repeat(72);
const long = await Bun.password.hash(base + "x", "bcrypt");
await tryIt("73バイト目だけ違うパスワード", () => Bun.password.verify(base + "y", long));
await tryIt("同じ73バイトのパスワード", () => Bun.password.verify(base + "x", long));

// 日本語は1文字3バイト(UTF-8)なので、24文字で72バイトになる
const jp = "ね".repeat(24);
console.log(`「ね」24文字のバイト数: ${new TextEncoder().encode(jp).length}`);
text
73バイト目だけ違うパスワード: false
同じ73バイトのパスワード: true
「ね」24文字のバイト数: 72

73バイト目だけ違うパスワードは、false になりました。ひらがなは UTF-8 で1文字3バイトなので、72バイトは24文字です。

ただし、Bun の外では事情が変わります。Python の bcrypt 5.0.0 で、73バイトのパスワードをハッシュ化してみたうえで、Bun が73バイトのパスワードから作ったハッシュ(bun_long)も照合しました(compat.py の抜粋)。

python
bcrypt.hashpw(b"a" * 73, bcrypt.gensalt())
bcrypt.checkpw(b"a" * 73, bun_long.encode())
bcrypt.checkpw(b"a" * 72, bun_long.encode())

3行それぞれの結果です。

text
Python の bcrypt で73バイトをハッシュにする: ValueError: password cannot be longer than 72 bytes, truncate manually if necessary (e.g. my_password[:72])
Bun の73バイトの bcrypt を、Python で73バイトのまま確かめる: ValueError: password cannot be longer than 72 bytes, truncate manually if necessary (e.g. my_password[:72])
Bun の73バイトの bcrypt を、Python で先頭72バイトで確かめる: False

Python の bcrypt 5.0.0 は、切り捨てずに、72バイトを超えるパスワードをエラーにしました。先頭の72バイトに切って渡しても、Bun の前処理とは違うので False です。

注意

Bun の bcrypt で72バイトを超えるパスワードから作ったハッシュは、Python の bcrypt 5.0.0 では照合できませんでした。Bun と同じ前処理(SHA-512)をしない bcrypt では照合できないので、あとで別の言語のサーバーに移す見込みがあるなら、argon2id を使うか、登録のときにパスワードを72バイトまでに制限してください。OWASP の文書も、bcrypt ではパスワードを72バイトまでに制限するよう書いています。

72バイト以下のパスワードと argon2id では、Bun と Python のあいだでハッシュをやり取りできました。Python 側は bcrypt.checkpw() と argon2-cffi の PasswordHasher().verify() で照合しています(Python と Bun、2つのスクリプトの出力をまとめたもの)。

text
Python で Bun の bcrypt を確かめる: True
Python で Bun の argon2id を確かめる: True
Bun で Python の bcrypt を確かめる: true
Bun で Python の argon2id を確かめる: true

Python の argon2-cffi が作ったハッシュは m=65536,t=3,p=4 で、Bun の既定とは設定が違いますが、Bun の verify() はそのまま照合しました。

hashSync は、計算が終わるまでほかの処理を止める

hashSync() と verifySync() という同期版もあります。公式ドキュメントは、計算が重いので、同期版はアプリの性能を落とすことがあると書いています(同期版についての公式ドキュメントの説明)。非同期の hash() と verify() は、別のスレッド(ワーカースレッド)で計算します(型定義のコメント)。

違いを見るため、10ミリ秒ごとのタイマーを動かしながら、既定の argon2id で5回ハッシュ化する block.ts を作りました(抜粋)。

ts
async function count(label: string, work: () => unknown) {
  let ticks = 0;
  const timer = setInterval(() => ticks++, 10);
  const start = performance.now();
  await work();
  const ms = performance.now() - start;
  clearInterval(timer);
  console.log(`${label}: ${ms.toFixed(1)} ms、その間のタイマー ${ticks} 回`);
}

await count("hashSync を5回", () => {
  for (let j = 0; j < 5; j++) Bun.password.hashSync(password);
});
await count("hash を5回(await で1つずつ)", async () => {
  for (let j = 0; j < 5; j++) await Bun.password.hash(password);
});

3回くり返した結果です。

text
hashSync を5回: 637.9 ms、その間のタイマー 0 回
hash を5回(await で1つずつ): 620.1 ms、その間のタイマー 61 回
hashSync を5回: 560.6 ms、その間のタイマー 0 回
hash を5回(await で1つずつ): 544.2 ms、その間のタイマー 53 回
hashSync を5回: 603.3 ms、その間のタイマー 0 回
hash を5回(await で1つずつ): 592.7 ms、その間のタイマー 58 回

かかった時間はほぼ同じですが、hashSync() の間は、タイマーが1回も動きませんでした。この間はイベントループが止まり、タイマーのようなほかの処理が動きません。サーバーの処理では、await で使う hash() と verify() を選びます。

登録とログインに組み込む

最後に、Bun.serve の routes で、登録とログインだけのサーバーを作りました。ユーザーは、データベースの代わりにメモリ上の Map に持たせています。

ts
// 登録とログインだけの小さなサーバー。ユーザーはメモリ上の Map に持つ
const users = new Map<string, string>(); // ユーザー名 → パスワードのハッシュ

Bun.serve({
  port: 3000,
  routes: {
    "/signup": {
      POST: async (req) => {
        const { name, password } = await req.json();
        if (users.has(name)) return new Response("使われている名前です", { status: 409 });
        users.set(name, await Bun.password.hash(password));
        return new Response("登録しました", { status: 201 });
      },
    },
    "/login": {
      POST: async (req) => {
        const { name, password } = await req.json();
        const hash = users.get(name);
        const ok = hash !== undefined && (await Bun.password.verify(password, hash));
        if (!ok) return new Response("名前かパスワードが違います", { status: 401 });
        return new Response(`ようこそ、${name}さん`);
      },
    },
    "/debug/users": () => Response.json(Object.fromEntries(users)),
  },
});
console.log("http://localhost:3000 で待ち受け中");

/debug/users は、保存された中身を見るために付けたものです。実際のサーバーには入れません。curl で送った結果は次のとおりです(一部。末尾の [201] などは HTTP のステータスコードです)。

text
$ curl -s -w ' [%{http_code}]\n' -X POST localhost:3000/signup -d '{"name":"tama","password":"neko-no-te-2026"}'
登録しました [201]
$ curl -s -w ' [%{http_code}]\n' -X POST localhost:3000/login -d '{"name":"tama","password":"neko-no-te-2026"}'
ようこそ、tamaさん [200]
$ curl -s -w ' [%{http_code}]\n' -X POST localhost:3000/login -d '{"name":"tama","password":"neko-no-te-2025"}'
名前かパスワードが違います [401]
$ curl -s -w ' [%{http_code}]\n' -X POST localhost:3000/login -d '{"name":"mike","password":"neko-no-te-2026"}'
名前かパスワードが違います [401]
$ curl -s localhost:3000/debug/users
{"tama":"$argon2id$v=19$m=65536,t=2,p=1$hNZ+uyAlNdGB/VijUbcK1Zdm/STTi8RBhTvrSiA4wc0$O5yVV5jPH5Vhk058/6YWTJZH6L26z+IiIWkkRLod+NQ"}

保存されているのはハッシュだけで、パスワードそのものは残っていません。パスワードが違うときも、登録されていない名前のときも、同じ「名前かパスワードが違います」を返すようにしています。

​Posted by 86