KOKON PAY · GUIDE

使い方と安全性

焼肉古今専用の前払い残高システム。お客様が先にチャージ → ご来店で消込します。

① お店（オーナー）の使い方

専用URLを開くだけでログインできます。パスワードは不要です。

お渡ししたオーナーURL（/pay/manage/…）を一度開く。以降は /pay/manage だけで入れます（ブラウザに記憶されます）。

発行：お客様のメールと金額を入れて「発行」→ QR会員証が出ます。その場で見せる／リンクを送る。今すぐ使える

会計で引き落とす：お客様のQRを読む → 会計金額を入力 → 残高から引く。今すぐ使える

監視：画面上部に「発行未使用残高」「会員数」「台帳の改竄検知（✓健全）」が常時表示。発行・消込はその都度Telegramに自動通知されます。

できることの一覧

操作	内容	状態
残高の発行	金額ボタン→QR手渡し	利用可
会計で消込	QR読取→金額入力	利用可
監査人の登録/停止	第三者に台帳の裏書きを依頼	利用可
オンラインチャージ	お客様がカードで自分でチャージ	準備中

※ オンライン決済（カード）と料率の本公開は、料率・積立条件・有効期限が確定してから有効化します。それまでは現金でお預かりした分を上の「発行」で記録する運用です。

② 店員の使い方

店員さん用には別の専用URL（/pay/staff/…）があります。

店員モードは消込（会計の引き落とし）だけができます。
残高の発行はできません（権限を分けてあるため、店員のミスや不正で残高が増えることはありません）。

店員URLはオーナー画面下部の「店員モードを開く →」からも確認できます。

③ お客様側

発行するとQR付きの会員証ページ（/pay/wallet/…）が作られます。
お客様はそのURL（QR）を保存。ご来店時に見せていただき、お店が読み取って消込します。
チャージ・利用のたびに、お客様のメールへ証明コード（hash）付きのレシートが届きます（後から第三者でも改竄がないことを確認できます）。

④ 安全性 ―「オーナーでも改竄できない」設計

このシステムの核心は、お金の記録を後からこっそり書き換えられないことです（＝書き換えたら必ず検知できる / tamper-evident）。

追記専用ハッシュチェーン台帳：すべての発行・消込が鎖状に記録され、各行が前の行の指紋（hash）を含みます。過去の1行でも書き換えると鎖が切れ、改竄が即わかります。
公開監査ページ：誰でも整合性を確認できます。透明性レポート／ /pay/audit
第三者の裏書き：会計士などが公開鍵で署名でき、改竄があると「署名は有効なのに台帳と不一致」になり露見します。
外部アンカー：台帳の最新状態を定期的にTelegram と GitHub の記録に外部保存し、後からの辻褄合わせを防ぎます。
即時通知：発行・消込のたびにTelegramへ自動通知。常に監視でき、不正発行にすぐ気づけます。
発行上限キャップ：発行未使用残高が ¥8,000,000 に達すると自動でチャージ停止（資金決済法の届出ライン手前で安全側に）。
二重加算の防止：オンライン決済では同じ入金が二度数えられない仕組み（UNIQUE制約）で物理的に弾きます。
鍵リンク方式：パスワードを廃止し、役割ごとの推測不能な鍵URL→Cookieセッション化（鍵をURL・ログから除去）。HMACの定数時間比較で照合します。

⚠ 鍵URLの取り扱い
オーナー／店員のURLはパスワードと同等です。ご本人だけが受け取り、公開チャネル（SNS・共有メモ等）には貼らないでください。万一漏れても、発行/消込はTelegram通知＋¥800万キャップで被害を抑えられますが、漏れたらすぐご連絡を。数分で鍵を作り直して旧URLを無効化できます。

⑤ 監査人の方へ（独立検証の手順）

この台帳は、店側の協力なしに第三者だけで整合性を検証できます。検証ツールはオープンソース（MIT）で公開しています。

A. 公開検証だけ（鍵不要・誰でも）

/pay/transparency … 整合性・登録監査人・裏書き一覧（人が読む用）
/pay/audit … 台帳ヘッドと件数（機械可読）
/pay/attestations … 各裏書きの pubkey・message・signature。Ed25519 で各自照合可能

B. 監査人として裏書きする（公開鍵を店に登録）

Ed25519 鍵ペアを生成し、公開鍵だけをお店に渡して登録してもらう。

お店から監査用エクスポート（PIIを含まない確定フィールドのみの台帳）を受け取る。

ローカルでハッシュチェーンを独立再計算し、現在のヘッドに署名して提出。

python kokon_audit.py keygen                       # 鍵を作る → 公開鍵を店へ
python kokon_audit.py verify --export ledger.json  # 台帳を独立再計算
python kokon_audit.py attest --base https://kokon.tokyo \
       --priv priv.key --witness "会計士〇〇" --export ledger.json

C. 改竄が起きるとどう見えるか

過去の行を書き換えると、再計算したヘッドが各監査人の署名済みヘッドと一致しなくなります。署名自体は有効なまま「台帳と不一致」と表示され、改竄が第三者に露見します（検証済み）。

📖 仕様・CLI・会計士向けガイド（MIT）：
github.com/yukihamada/kokon-pay-audit ・ SPEC.md（プロトコル仕様）・会計士向けガイド(PDF)

⑥ 困ったとき

URLを誤って他人に送った → すぐご連絡を。鍵を作り直して旧URLを無効化します（数分）。
画面が開けない → 別端末・シークレットウィンドウでは、最初にお渡しした鍵付きURLから開き直してください。
残高や取引の数字が合わない → 透明性レポートで台帳が「✓健全」かをまず確認してください。

古今ペイ · KOKON PAY ／透明性レポート・オーナー画面