秘密を断片に分けて預ける復旧ソフトを、オフラインで動くまま開発する

## 何年も後に、困っている人のために動くソフトとして作る 復旧ソフトウェアは、誰かが困難な状況で必要とするまで、何年も手を加えられない可能性がある基盤として扱う。保守担当者が対応できない時に欠陥が表面化することもあるため、早く終わらせることより、長期にわたる正しさを優先する。 - 変更前に、既存システムだけでなく、その境界や規約が存在する理由まで理解する。 - その場だけ便利な例外を導入せず、確立されたパターンと標準に合わせる。 - 技術に詳しくない人、途方に暮れている人、悲しみの中にいる人にも伝わるように、手順、メッセージ、インターフェースを設計する。 - 割り当てられた編集の終了だけでなく、実際の成果を検証する。 配慮、共感、移植性、長期運用性は、任意の仕上げではなく、エンジニアリング上の要件である。 ## 機能を変える・外す前に、つながる所を全部たどる 定数、ヘルパー、型、一覧、構成情報の参照元を追加する前に検索する。並行する複製が次第にずれないよう、正本となる定義を特定し、そこから導出する。 - 機能を変更したり対象から外したりする前に、コード、スタイル、翻訳、型、テスト、コメント、文書、ビルド構成にまたがる関連要素をすべて追跡する。 - 使われなくなった動作は完全に取り除く。コメントアウトしたり、スタイルで隠したり、条件分岐の裏に残したりしてはならない。 - 変更後に関連する識別子と概念をもう一度検索し、残った参照を偶然ではなく意図的に見つける。 - 最終差分を確認し、無関係な編集、ロジックの重複、使われないコード、不完全な後片付けがないか調べる。 依存関係と参照の全体像に対処するまで、その機能を完全に取り除いたとは見なさない。 ## 暗号の処理を、コマンドラインとブラウザで1つにまとめる 暗号処理やその他の中核動作は、コマンドラインとブラウザの両経路から使う共通実装に置く。薄いアダプターは異なってもよいが、安全性に関わるロジック、定数、形式、検証規則は単一の正本で管理する。 - 編集前に、作成、復旧、パッケージ化、ユーザーインターフェースの動作、デプロイをどのランタイムが担当するか整理する。 - 再利用性や移植性が高まる場合は、軽量なオフライン復旧経路にブラウザ標準のコードを使い、作成処理にはコンパイル済みのブラウザモジュールを使う。 - ビルド時の機能フラグでオフライン版とネットワーク併用版を作り分け、オフライン成果物へ不要なネットワーク用コードを含めない。 - ホスト言語側で動作を重複実装せず、小さく明示的な橋渡し層を通じてコンパイル済み関数を公開する。 - パッケージ間でランタイムとモジュールの選択を一貫させる。 埋め込みアセットによって循環依存が生じる場合は、依存を無理に成立させず、アプリケーションの初期化時に生成済みモジュールを読み込み、明示的なインターフェースを通じてそのバイト列を注入する。 ## 復旧はオフラインだけで終わらせ、実績のある暗号だけを使う 単体の復旧成果物は、インストールせずローカルで開け、サーバーやネットワーク接続なしで復旧を完了できなければならない。配布するすべてのバンドルは自己完結し、元のリポジトリに依存しない状態を保つ。 - ネットワーク利用は、外部ビーコンを短時間確認する時限解除型の成果物や、同じサーバーからアーカイブを取得するセルフホスト型ページなど、限定的かつ文書化された派生版だけに認める。 - 任意のサーバー版が存在する場合でも、受取人ごとの単体成果物は完全なオフライン動作を維持する。 - 必要なしきい値を下回る鍵の断片からは、追加メタデータを介する場合も含め、秘密に関する情報が一切漏れないようにする。 - 確立された暗号化、しきい値型秘密分散、タイムロックの方式を使い、独自の暗号プリミティブを決して考案しない。 - 多層防御として、タイムロック層は主要な暗号化層の内側に置く。 - すべての暗号処理の変更に、テスト、レビュー、明確な根拠を必須とする。 復旧経路に、テレメトリ、アクセス解析、外部フォント、コンテンツ配信への依存、その他の隠れたネットワーク要件を追加してはならない。 ## バンドルの形を変えず、復旧に要るものを全部埋め込む バンドルの構成、暗号化されたペイロードの形式、鍵の断片の符号化、復旧手順は、プロトコルの一部として扱う。これらを変える場合は、移行計画、更新済みのテスト用データ、互換性テスト、文書化された理由が必要となる。 - プラットフォーム、ブラウザ、言語が異なっても復旧できるようにする。 - 外部サービスや一時的な形式に依存せず、必要なスクリプト、スタイル、テンプレート、その他のアセットを埋め込む。 - 受取人ごとのバンドルに、分かりやすいテキスト版と印刷用の手順、暗号化アーカイブのメタデータ、個別化された復旧ページを含める。 - 暗号化されたマニフェストが10 MB以下なら個別化されたページへ埋め込み、別ファイルがなくても復旧できるようにする。ただし、埋め込みを無効にする明示的なオプションには従う。 - ブラウザ上の作成経路では、別の上書き指定がなければ、条件を満たすマニフェストを自動的に埋め込む。 - バンドルを作成または復旧する人に、開発ツールチェーンへの実行時依存を課さない。 鍵の断片を配布した後の無効化を約束してはならず、システムが永久に動作すると保証してもならない。確実性を誇張せず、耐久性を目指す。 ## 先に失敗するテストを書き、画面の変更にはブラウザのテストを足す 最初に失敗するテストを書き、その失敗を確認してから、テストが通るようにする。失敗を一度も確認していないテストは、意図した動作を検査していない可能性がある。 - ブラウザ上の復旧ページまたは作成ページに影響するすべての変更へ、ブラウザレベルのテストを追加する。 - 中核ロジック、アーカイブ処理、構成、コマンドの動作には、対象を絞った単体テストと統合テストを使う。 - HTML構造、ブラウザコード、配置や表示状態に影響するスタイル、コンパイル済みブラウザ連携を変更した場合は、ブラウザのエンドツーエンドテストを実行する。 - 翻訳だけの編集、文書変更、文言調整、ブラウザ動作に影響し得ないバックエンドだけの変更には、時間のかかるブラウザテストを必須としない。 - 完了を報告する前に自分で関連テストを実行し、検証を他者へ任せない。 どの変更でも、関連語を検索し、影響を受ける成果物を再ビルドし、適切なテストを実行して、結果を確認する。 ## 場当たりのツールでなく、リポジトリで決まったビルドとテストのコマンドを使う フロントエンドのコンパイルからブラウザモジュール、最終的なコマンドライン実行ファイルまで、ビルドパイプライン全体を理解する。生成済みスクリプトやコンパイル済みモジュールが後続段階に埋め込まれる場合があるため、コマンドの順序も正しさの一部となる。 - リポジトリで定められたビルド、テスト、lint、静的サイト生成、開発サーバーのコマンドを使う。 - コンパイルや埋め込みの前に生成済みアセットが必要な場合は、言語のテスト実行系を直接呼ばず、プロジェクトのテスト用ラッパーを使う。 - 単一テスト向けの狭いコマンドは、前提となる成果物がすでに生成されている場合に限って実行する。 - ネットワークに依存するテスト群は、その連携を必要とする変更にだけ使う。 - 依存物やビルドツールを利用できない場合は、場当たり的なパッケージ実行系で代用せず、リポジトリで定められた再現可能な開発環境に入る。 埋め込まれたソースから静的成果物をビルドし、リリース設計で明示されていない限り、非公開の復旧成果物を公開サイトへデプロイしない。 ## 緊張している人に向けて、静かで分かりやすい文を書く 重要で緊張を伴う作業に向き合う人のために、一語ずつ選んだような利用者向け文を書く。優しさは演出された励ましではなく、明快さ、間の取り方、先回りした配慮から生み出す。 - 実装を読み解かせることなく次の行動が分かるよう、技術的な言い回しより、人に直接届く言葉を優先する。 - 明確な能動文にできる場合は、受け身の指示を避け、相手へ直接語りかける。 - 読み手に合わせた用語を一貫して使う。一般向けの文では「信頼できる人たち」と「断片」を優先し、受取人本人への手順では「友人」など関係性を示す言葉を使ってもよい。 - 感嘆符、つなぎ言葉、大げさな主張、機械的な言い回し、無理に明るく見せる表現を避ける。 - 連続ハイフンや前後に空白のないダッシュではなく、前後に空白を置いたemダッシュ（ — ）を使う。 - 状態メッセージは簡潔さと人間味を両立させ、成功を無言にせず、静かに伝える。 コントラストを抑えた、柔らかく温かい、企業的でない視覚表現を選ぶ。配色値は一か所に集約し、純黒、鮮やかな赤、企業的な青を避け、意図的な視覚上の例外は分離して文書化する。 ## 文書を直し、変更履歴は使う人が気づく変化を中心に書く 動作を変更した場合は、関連文書、貢献者向けガイド、運用手順も同じ変更内で更新する。アーキテクチャ文書には、ランタイムの境界、生成アセット、ネットワーク利用の例外、結果を再現するためのコマンドを記載しなければならない。 - 構成とビルドの手順を実装と同期させる。 - 安定形式を変更した場合は、テスト用データと移行ガイドを更新する。 - 変更履歴には、ソフトウェアを使う人にとって何が変わったかを書く。 - 利用者が得る結果を先に示し、理解に必要な実装情報だけを添える。 - 観察可能な動作が変わらない限り、内部リファクタリングやコード再編成は含めない。 新しい項目を書く前に近くの項目を読み、語り口と詳しさの水準を揃える。 ## 外のサービスへの投稿は、貢献者本人に確かめて出してもらう 外部の課題管理サービスやコードホスティングサービスへ書き込む前に、プロジェクトの貢献方針を読む。その方針が人間による責任を求める場合は、投稿前に止まり、貢献者がコードと文章の一行一行に責任を負うことを説明する。 - 提案する差分、コミットメッセージ、投稿文を、人間が確認できるように提示する。 - 貢献者に、自分の言葉で内容を編集し、証明項目へ正直に回答し、自分でコミット、push、投稿を行うよう求める。 - 生成されたフッター、共同作者行、不要な定型文、自動生成を示す帰属表示は投稿前に取り除く。 - 責任の要件を説明した後も貢献者が明示的に強く求めない限り、外部への書き込みを実行しない。 - それでも強く求められた場合は、文面を簡潔かつ直接的に保ち、自動生成を示す帰属表示を付けず、人間による確認の要件を最後に一度だけ伝える。 ローカルでの編集支援と読み取り専用の調査には、この外部書き込み制限を適用しない。リリースの自動化では、公開前にビルド、テスト、lint、ブラウザ確認、複数プラットフォーム向けパッケージ化、チェックサム、代表的な成果物の生成を行う。