@aiquants/daily-report 0.13.0 → 0.14.0

package/src/server/visibility.ts

@@ -154,14 +154,102 @@ export function buildVisibleSourceTypeCondition(sourceTypeColumn: AnyMsSqlColumn
 }
 
 /**
- * Computes a stable, bounded, collision-free cache-key digest of the set.
- * 可視集合から安定・有界・衝突不能なキャッシュキー用ダイジェストを算出する処理。
+ * Request-scoped viewer scope carrying the normalized visible source-type set.
+ * 正規化済みの可視 sourceType 集合を運ぶ、リクエストスコープの閲覧範囲。
  *
- * 無制限は `"all"`、空集合は `"none"`、それ以外は**畳み込み済みトークンを昇順にそのまま連結**する。
- * 生連結のため、論理的に等価な集合は必ず同一の、論理的に異なる集合は必ず別のダイジェストになる
- * (ハッシュ衝突で別権限のキャッシュ行を配信する事故が原理的に起きない)。権限が安定している間は
- * キーが不変になるため、キャッシュは完全に再利用される (性能無退行)。
- * 区分数が異常に多い場合だけキー長を抑えるため FNV-1a 32bit へ退避し、`h:` 接頭辞で生連結と区別する。
+ * このクラスは private フィールドを持つことで**名目型**になっており、`{ visible: null }` のような
+ * 構造的偽造も、`{ ...scope, visible: null }` のようなスプレッドによる widening も型が拒否する
+ * (`unique symbol` ブランドでは後者を防げないことを実測で確認済み)。
+ *
+ * 生成経路は {@link DailyReportViewerScope.restrictTo} と {@link DailyReportViewerScope.unrestricted}
+ * の 2 つだけであり、`null` を「可視性」としてそのまま綴ることはできない。結果として、
+ * **絞り込まれない読み取りは必ず `unrestricted(理由)` として現れる**ため、
+ * `grep -rn "DailyReportViewerScope.unrestricted("` が fail-open の全数リストになる。
+ */
+export class DailyReportViewerScope {
+    /**
+     * 正規化済みの可視集合を保持する private スロット。
+     *
+     * ❗ public な読み取り専用プロパティにしてはならない。`readonly` は型のみの制約であり、
+     * `Object.assign(scope, { visible: null })` は型検査も実行時も素通りして実体を書き換える
+     * (実測済み)。private スロット + getter なら代入が実行時にも失敗する。
+     */
+    readonly #visible: VisibleSourceTypeSet
+
+    private constructor(visible: VisibleSourceTypeSet) {
+        this.#visible = visible
+    }
+
+    /** 正規化済みの可視集合。`null` は無制限、空集合は 0 件 (fail-close)。 */
+    get visible(): VisibleSourceTypeSet {
+        // ❗ 実体をそのまま返さない。`ReadonlySet` は型のみの制約で、実体の `Set` は
+        //    `(scope.visible as unknown as Set<string>).add(...)` で in-place に広げられる (実測済み)。
+        //    毎回コピーを返すことで、外部から可視集合を広げる経路を断つ
+        return this.#visible === null ? null : new Set(this.#visible)
+    }
+
+    /**
+     * Builds a scope restricted to the given source types (empty input = zero rows).
+     * 指定した sourceType へ限定した閲覧範囲を生成する処理 (空入力は 0 件)。
+     *
+     * 入力は {@link normalizeVisibleSourceTypes} を通るため、大小文字・前後空白・重複・非文字列は
+     * ここで吸収される。
+     *
+     * ❗ 引数は `readonly string[]` に**狭めてある**。`null` / `undefined` を受け付けると、
+     * 「restrict」という名前のまま無制限スコープを生む第 2 の入口になり、
+     * 「絞り込まれない読み取りは必ず {@link DailyReportViewerScope.unrestricted} に現れる」
+     * という監査不変条件が崩れる。無制限は必ず理由付きで明示すること。
+     *
+     * @param sourceTypes Visible source-type tokens. 可視 sourceType のトークン群。
+     * @returns The scope. 生成した閲覧範囲。
+     */
+    static restrictTo(sourceTypes: readonly string[]): DailyReportViewerScope {
+        return new DailyReportViewerScope(normalizeVisibleSourceTypes(sourceTypes))
+    }
+
+    /**
+     * Builds an unrestricted scope; every call site is an audited fail-open.
+     * 無制限の閲覧範囲を生成する処理。全呼び出し箇所が監査対象の fail-open となる。
+     *
+     * ❗ 理由文字列は必須。読み捨てるが、呼び出し箇所の全数列挙と「なぜここは絞らなくてよいか」の
+     * 記録を強制するために受け取る。
+     *
+     * @param auditReason Why unrestricted access is correct here. なぜここで無制限が正当かの理由。
+     * @returns The unrestricted scope. 無制限の閲覧範囲。
+     */
+    static unrestricted(auditReason: string): DailyReportViewerScope {
+        void auditReason
+        return new DailyReportViewerScope(null)
+    }
+}
+
+/**
+ * Computes the cache-key digest for a whole viewer scope.
+ * 閲覧範囲全体からキャッシュキー用ダイジェストを算出する処理。
+ *
+ * スコープに次元が増えてもキャッシュキーの生成点を 1 つに保つための入口。
+ *
+ * @param scope Viewer scope. 閲覧範囲。
+ * @returns Digest usable as a cache-key component. キャッシュキー構成要素として使えるダイジェスト。
+ */
+export function computeViewerScopeDigest(scope: DailyReportViewerScope): string {
+    return computeSourceTypeDigest(scope.visible)
+}
+
+/**
+ * Computes a stable and bounded cache-key digest of the set.
+ * 可視集合から安定・有界なキャッシュキー用ダイジェストを算出する処理。
+ *
+ * 無制限は `"all"`、空集合は `"none"`、それ以外は `s:` 名前空間の下へ**長さ接頭辞付きトークンを昇順連結**する。
+ * 連結は長さ接頭辞付きなので**単射**であり、通常経路 (`s:`) では論理的に等価な集合が必ず同一の、
+ * 異なる集合が必ず別のダイジェストになる。sentinel (`all` / `none`) とも名前空間が分かれるため、
+ * 限定集合が無制限 / 全拒否と同じバケットを共有することはない。権限が安定している間はキーが
+ * 不変になるため、キャッシュは完全に再利用される (性能無退行)。
+ *
+ * ❗ 区分数が異常に多い場合だけキー長を抑えるため FNV-1a 32bit へ退避し `sh:` 接頭辞を付ける。
+ * **この退避経路に限り理論上の衝突がありうる** (32bit)。衝突しても影響は同一ユーザーの
+ * キャッシュ再利用に留まり、認可判定そのものは SQL 述語が担うため漏洩には至らない。
+ * 通常の区分数 (数個) では到達しない。
  *
  * @param set Normalized visible set. 正規化済みの可視集合。
  * @returns Digest usable as a cache-key component. キャッシュキー構成要素として使えるダイジェスト。
@@ -173,10 +261,17 @@ export function computeSourceTypeDigest(set: VisibleSourceTypeSet): string {
     if (set.size === 0) {
         return "none"
     }
-    // 昇順ソートで要素順に依存しないキーにする (同じ集合は常に同じダイジェスト)
-    const joined = [...set].sort().join(DIGEST_SEPARATOR)
+    // 昇順ソートで要素順に依存しないキーにする (同じ集合は常に同じダイジェスト)。
+    // ❗ 各トークンは長さ接頭辞付きで連結する。素の区切り文字だけでは、区切り文字を含む
+    //    トークンが別の集合と同じ連結結果になりうる (単射でなくなる)
+    const joined = [...set]
+        .sort()
+        .map((token) => `${token.length}:${token}`)
+        .join(DIGEST_SEPARATOR)
+    // ❗ 限定集合の名前空間を `s:` で分ける。分けないと、`"all"` や `"none"` へ畳み込まれる
+    //    トークンだけを許された閲覧者が、無制限 / 全拒否と同じキャッシュバケットを共有してしまう
     if (joined.length <= DIGEST_RAW_MAX_LENGTH) {
-        return joined
+        return `s:${joined}`
     }
     // 長大キーの退避のみハッシュ化する。衝突しても影響は同一ユーザーのキャッシュ再利用に限られ、
     // かつ TTL で失効するが、生連結と混同しないよう接頭辞で区別する
@@ -185,5 +280,5 @@ export function computeSourceTypeDigest(set: VisibleSourceTypeSet): string {
         hash ^= joined.charCodeAt(i)
         hash = Math.imul(hash, 0x01000193)
     }
-    return `h:${(hash >>> 0).toString(16)}`
+    return `sh:${(hash >>> 0).toString(16)}`
 }