オブジェクトキー設計：ストレージおよびセキュリティ設計
不透明でテナントスコープのオブジェクトキーとデータベースの所有権レコードを定義し、ファイル名、ユーザー、および可変の認可情報がストレージの識別子になったり、URLやログを通じて漏洩したりしないようにします。
パッケージステータス: 人間によるレビューのためのリファレンスコンテキストが準備完了。契約とテストシナリオは完成していますが、採用実装がそれらを通過したという保証はありません。
決定事項
環境およびテナントの名前空間の下でサーバー側に不透明なキーを生成し、元の名前と認可情報はアプリケーションデータベースに保持します。バケットはプライベートとして扱い、すべてのアップロードやダウンロードは所有権レコードを通じて解決します。
範囲
- キー文法、所有権マッピング、バージョン識別、マルチパートアップロード、一時オブジェクト、ログ、ライフサイクルプレフィックス、マイグレーション。
- S3互換ストレージ内のプライベートアプリケーションオブジェクト。
- 衝突、列挙、およびクロステナント制御。
範囲外
- プロジェクト間のコンテンツアドレス重複排除。
- オブジェクトキーを認可メカニズムにしたり、生のバケットリストを公開したりすること。
契約
- キーは制御されたスラッグとランダムまたはサーバー発行の識別子のみを含み、元のファイル名、メール、アカウント名、信頼できないパス文字列は含みません。
- テナントIDと環境は所有権レコードに対して検証される別個のキーセグメントです。
- 1つの論理ファイルバージョンは1つの不変オブジェクトキーにマップされ、置き換えは新しいバージョンキーを作成します。
- データベースレコードが状態、メディアタイプ、サイズ、ダイジェスト、アップローダー、テナント、バージョン、ライフサイクルを所有し、オブジェクトメタデータだけが真実の唯一の情報源ではありません。
- クライアント提供の名前は表示用メタデータであり、ダウンロードヘッダー用に別途サニタイズされます。
- 一時および検疫プレフィックスには明示的なライフサイクルルールがあり、アクティブファイルとして提供できません。
実装ガイダンス
env/tenant-id/files/file-id/version-id/blobのような文法を使用し、すべてのIDはサーバー側で生成および検証します。- 期待されるキー、バイト制限、コンテンツタイプポリシー、有効期限に紐づくスコープ付きアップロード意図を発行します。
- 運用上十分な場合は元のファイル名ではなくオブジェクトIDやハッシュをログに記録します。
- マイグレーションはマッピングを書き込み、新しい不変キーにコピーしてから読み取りを切り替え、古いオブジェクトのクリーンアップ前にダイジェストを検証します。
障害処理と安全策
- トラバーサルセグメント、制御文字、曖昧な正規化、所有権レコードと不整合なテナントを含むキーは拒否します。
- アップロードが完了してもコミットされたデータベースレコードがない場合は、孤立したものとして検疫状態に残します。
- データベースとオブジェクトのダイジェストが異なる場合は、所有権を黙って更新せずに提供をブロックし調査します。
検証と運用
- キー検証拒否、クロステナント拒否、オブジェクト欠落および所有権なしオブジェクトの調整、ダイジェスト不一致、一時オブジェクトの経過時間を測定します。
- ログ、署名付きURL、エラー応答が元のプライベート名を露出しないことをテストします。
- バケットポリシーを監査し、直接のパブリック読み取りおよびリストが無効のままであることを確認します。
このパッケージ内の実行可能に見える例はフィクスチャおよび受け入れ契約です。
コレクションルートから python tools/validate.py を実行してパッケージ構造とメタデータをチェックし、対象リポジトリでシナリオを実装および実行してください。
採用の前提条件
example.yamlの名前や数値は採用プロファイルであり、普遍的なデフォルトではありません。- 採用チームはアクター、データクラス、エラー語彙、所有権を自システムにマッピングする必要があります。