@aiquants/daily-report 0.14.1 → 0.16.0

package/README.md

@@ -144,8 +144,10 @@ createDailyReportServer({
 | Return value | Meaning |
 | --- | --- |
 | `undefined` / `null` | Unrestricted — every source type (the default when the port is not injected). |
-| `["legacy", "Internal"]` | Only those source types are visible. |
+| `["legacy", "Internal"]` | Only those source types are visible (bodies **and** comments). |
 | `[]` | Nothing is visible (zero rows) — **not** the same as `null`. |
+| `{ read: [...] }` | Same as returning the bare array — the comment dimension follows `read`. |
+| `{ read: [...], comment: [...] }` | Bodies and comments restricted independently. See [Comment visibility](#comment-visibility). |
 | throws | Treated as `[]` (deny all). The failure is logged; an authorization-store outage never falls open. |
 
 - **Vocabulary**: the strings are `DailyReportHub.source_type` **values** — the `sourceType` of each entry you registered in `externalSources`, plus `"Internal"` which the package writes for reports it creates. They are *not* your authorization resource keys; mapping a resource key (e.g. `report_legacy`) onto a source type (e.g. `legacy`) is the consuming app's job. Read the canonical set at boot from `dailyReportServer.knownSourceTypes` and assert your mapping against it — an unknown token silently matches zero rows.
@@ -157,6 +159,33 @@ createDailyReportServer({
 - **Performance**: the port is called once per request on the critical path (cache keys incorporate the resolved set), so keep it fast — cache grants per session/user with a short TTL (≤ 60s). A live SSE connection re-resolves on its existing keep-alive tick (~60s) to bound how long a revoked grant keeps streaming; that call passes `reason: "refresh"` and reuses the connection's original `Request`, so a cache keyed on request identity **must** be bypassed when `reason === "refresh"` or the re-check silently returns the stale set.
 - **SSE latency**: because a live connection re-resolves periodically, a grant change (in either direction) takes effect for the stream within ~60s. Events dropped before a widening are not replayed; the next read (which re-resolves per request) restores them.
 
+### Comment visibility
+
+Return `{ read, comment }` from the same port to restrict **reading and writing comments** independently of the report bodies — this is what connects a per-category comment permission (e.g. `daily_report_legacy_comment`) to actual access control.
+
+```ts
+resolveVisibleSourceTypes: async (request, { reason }) => {
+  const grants = await yourAuthz.grantsFor(request, { skipCache: reason === "refresh" })
+  return {
+    read: grants.readableSourceTypes,        // e.g. ["legacy", "Internal"]
+    comment: grants.commentableSourceTypes,  // e.g. ["Internal"] — omit the key to follow `read`
+  }
+},
+```
+
+| `comment` | Meaning |
+| --- | --- |
+| omitted | Follows `read` — identical to returning a bare array. This is the default and the only spelling for "same as bodies". |
+| `[]` | Comments are invisible and cannot be written, while the bodies stay readable. |
+| `["Internal"]` | Only those source types' comments are visible/writable. Narrowed to `read ∩ comment` at construction, since comments only ever ship inside an already-read-filtered report. |
+
+- **`null` is rejected by the type system** — a second spelling for "follow `read`" would make the dimension four-state and reintroduce exactly the unrestricted-vs-deny-all confusion the tri-state contract exists to prevent. A `null` that slips through at runtime fails **closed**.
+- **What it covers**: `DailyReportDetail` carries comments in **two** structurally different fields — `commentItems` (the package's own comment table) and `comments` (legacy JSON supplied by an `externalSources` adapter). Both are gated. They are emptied, never omitted: the keys are required by the SSE schema, and dropping them would make a receiver discard the whole message.
+- **Live events**: `comment-add` / `comment-delete` are judged on the comment dimension, and the report payload embedded in `report-create` / `report-update` / `report-publish` has its two comment arrays emptied per viewer at delivery time.
+- **Your own comments are always visible and always deletable** (`commentItems` only — the legacy `comments` array carries no user identity, so it is all-or-nothing per source type). Hiding them would strand existing comments as undeletable the moment a grant is revoked, with no security gain.
+- **Writing to external sources remains impossible regardless** — `addComment` rejects any non-`Internal` source type outright, so for external categories the comment dimension effectively controls *reading*.
+- **Cache**: the dimension is folded into the cache-key digest, so revoking only the comment grant invalidates immediately. When `comment` follows `read` (the default) the digest is byte-identical to before, so existing deployments see no cache churn.
+
 ## Client wiring
 
 ```tsx