@htilabs/platform-common-models 0.54.0 → 0.56.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/README.md +90 -0
  2. package/dist/authz/index.cjs +353 -2
  3. package/dist/authz/index.cjs.map +1 -1
  4. package/dist/authz/index.d.cts +330 -9
  5. package/dist/authz/index.d.ts +330 -9
  6. package/dist/authz/index.js +339 -1
  7. package/dist/authz/index.js.map +1 -1
  8. package/dist/{index-XWSYon40.d.cts → index-Bj-s0nZy.d.cts} +1 -1
  9. package/dist/{index-Bh1zO_Vu.d.ts → index-DvAypMJV.d.ts} +1 -1
  10. package/dist/index.cjs +503 -2
  11. package/dist/index.cjs.map +1 -1
  12. package/dist/index.d.cts +4 -4
  13. package/dist/index.d.ts +4 -4
  14. package/dist/index.js +483 -2
  15. package/dist/index.js.map +1 -1
  16. package/dist/models/index.d.cts +2 -2
  17. package/dist/models/index.d.ts +2 -2
  18. package/dist/schemas/index.d.cts +25 -25
  19. package/dist/schemas/index.d.ts +25 -25
  20. package/dist/sharing-ceiling/index.cjs +152 -2
  21. package/dist/sharing-ceiling/index.cjs.map +1 -1
  22. package/dist/sharing-ceiling/index.d.cts +214 -2
  23. package/dist/sharing-ceiling/index.d.ts +214 -2
  24. package/dist/sharing-ceiling/index.js +145 -2
  25. package/dist/sharing-ceiling/index.js.map +1 -1
  26. package/package.json +1 -1
  27. package/src/__tests__/authz-resolve.test.ts +5 -0
  28. package/src/__tests__/authz-viewing-policy.test.ts +685 -0
  29. package/src/__tests__/authz-viewing-scope.test.ts +1037 -0
  30. package/src/__tests__/core-function-default-bounds.test.ts +2 -2
  31. package/src/authz/functionDoor.ts +4 -4
  32. package/src/authz/index.ts +2 -0
  33. package/src/authz/resolveEffectiveFunctions.ts +6 -4
  34. package/src/authz/viewingPolicy.ts +525 -0
  35. package/src/authz/viewingScope.ts +359 -0
  36. package/src/sharingCeiling/__tests__/fireShareEvent.test.ts +437 -0
  37. package/src/sharingCeiling/fireShareEvent.ts +352 -0
  38. package/src/sharingCeiling/index.ts +4 -0
  39. package/src/sharingCeiling/resolve.ts +31 -5
  40. package/dist/{cvcEntry-D787utvP.d.cts → cvcEntry-BLeRivoF.d.cts} +8 -8
  41. package/dist/{cvcEntry-D787utvP.d.ts → cvcEntry-BLeRivoF.d.ts} +8 -8
@@ -0,0 +1,359 @@
1
+ /**
2
+ * @htilabs/platform-common-models/authz — the Level 3 category filter of internal
3
+ * viewing: what of a case a viewer who does not own it may see, given the
4
+ * effective level and the governing policy's `visibleGroups` / `scopeVocab`.
5
+ *
6
+ * Lifted from PAVE `@pave/domain` `viewingScope.ts` (pave-2.0 develop 41f5f916:
7
+ * `caseViewingAccess`, `recordViewing`, `caseSurfacesOn`, `caseSurfacesAsStub`)
8
+ * and `viewingProjection.ts` (`viewingComponentOpen`), unchanged in behaviour.
9
+ * The only difference: PAVE reads its module-level resolver binding; here the
10
+ * app passes its own binding of the CVC-236 v4 resolver (`scope`), so the
11
+ * browser-safe `./authz` entry never inlines the SOT JSON. PAVE's wire
12
+ * projections (`viewingProjection` field lists, route homes) and the stub
13
+ * projection stay in the app.
14
+ *
15
+ * Pure and I/O-free: the caller resolves every fact about the viewer (effective
16
+ * level, whether the case passes its agency / team row filter, ownership, the
17
+ * governing policy) and this module only decides.
18
+ *
19
+ * Rules (contract § 2; Crysta 2026-11-03; prototype `recordOpenAccess`,
20
+ * `carVisibleUnderAccess`, `applyViewingPolicy`):
21
+ * - a case the viewer cannot see: nothing; an owned case: the full record;
22
+ * - level 1: the stub in search; level 2: the stub in search and pickers;
23
+ * neither opens the record; level 0: nothing;
24
+ * - level 3 with NO policy on file (`whitelist: null`): the full record;
25
+ * - level 3 with a policy: the client's stub rows and system information
26
+ * always, plus whatever the whitelist COVERS on the record's kind-tree home
27
+ * row (a category covers that category under every person on the record).
28
+ * Unmapped or uncovered is hidden; an empty list hides everything else;
29
+ * - the author always sees their own record on a case they can see.
30
+ */
31
+
32
+ import type {
33
+ InformationScopeResolver,
34
+ ScopeReading,
35
+ ScopeSubjectKind,
36
+ } from "../services/informationScopeResolver.js";
37
+ import type { ViewingLevel } from "./resolveEffectiveFunctions.js";
38
+ import { type GoverningViewingPolicy, viewingPolicyVocabulary } from "./viewingPolicy.js";
39
+
40
+ /**
41
+ * The bound CVC-236 resolver the Level 3 filter reads (the app's binding of
42
+ * `createInformationScopeResolver` to `coreInformationScopeSot`).
43
+ */
44
+ export type ViewingScopeResolver = Pick<
45
+ InformationScopeResolver,
46
+ "row" | "readSelection" | "isCovered"
47
+ >;
48
+
49
+ /** Where a non-owned case can surface (prototype `applyViewingPolicy` context + record open). */
50
+ export type ViewingSurface = "search" | "autocomplete" | "open";
51
+
52
+ /** A stored viewing whitelist (the admin-set by-category selection). */
53
+ export interface StoredViewingWhitelist {
54
+ /** Flat list of scope codes (the policy's `visibleGroups`). */
55
+ informationScope: readonly string[] | null | undefined;
56
+ /**
57
+ * The policy's vocabulary stamp as the hub wrote it (`scopeVocab`: 3, 4 or 5) —
58
+ * never the CVC-236 tree version. Any other value reads nothing.
59
+ */
60
+ scopeVocab: number | null | undefined;
61
+ }
62
+
63
+ /** Everything the caller resolved about the viewer and the case. */
64
+ export interface ViewingContext {
65
+ /** The case passes the caller's agency / team row filter. `false` ⇒ nothing on it. */
66
+ canSeeCase: boolean;
67
+ /** The case is owned / claimed by the viewer or their team: always fully visible. */
68
+ ownedByViewer: boolean;
69
+ /** The effective viewing level (`viewingLevelFromFunctions`). */
70
+ level: ViewingLevel;
71
+ /**
72
+ * The governing policy's whitelist ({@link viewingWhitelistFromPolicy}). `null`
73
+ * means exactly one thing: NO viewing policy is on file, so Level 3 renders every
74
+ * component. A row with no list is an empty list, not `null`.
75
+ */
76
+ whitelist: StoredViewingWhitelist | null;
77
+ }
78
+
79
+ /** The decision for one case. */
80
+ export type CaseViewingAccess =
81
+ | { readonly mode: "full"; readonly reason: "owned" | "no_viewing_policy" }
82
+ | { readonly mode: "none"; readonly reason: "cannot_see_case" | "level_0" }
83
+ | { readonly mode: "stub"; readonly level: 1 | 2 }
84
+ | {
85
+ readonly mode: "whitelist";
86
+ /** The whitelist's v4 reading (`readSelection`, subject `policy`), untouched. */
87
+ readonly reading: ScopeReading;
88
+ /**
89
+ * The list coverage is read on: the reading, plus `relationships_household`
90
+ * when the prototype's v4 alias on `identifying` applies (a stamp below 5).
91
+ */
92
+ readonly visibleScope: readonly string[];
93
+ /** The prototype's ONE-HOME domain carry applies (stamp 3). */
94
+ readonly oneHomeCarry: boolean;
95
+ /** The v4 alias carries `relationship_dynamics` at domain grain (stamp < 5 naming `identifying`). */
96
+ readonly relationshipDynamicsCarry: boolean;
97
+ };
98
+
99
+ /** The vocabulary stamp a whitelist with no stored stamp of its own is read at. */
100
+ const CURRENT_VIEWING_POLICY_VOCAB = 5;
101
+
102
+ /** The v4 category the prototype's alias opens for a pre-v4 `identifying`. */
103
+ const RELATIONSHIPS_HOUSEHOLD = "relationships_household";
104
+
105
+ /** The assertion domain the prototype's v4 alias carries at domain grain. */
106
+ const RELATIONSHIP_DYNAMICS = "relationship_dynamics";
107
+
108
+ /**
109
+ * The whitelist {@link caseViewingAccess} reads for a governing-policy result:
110
+ * `null` when nothing governs (the full record at Level 3); the row's list and
111
+ * stamp when a row governs; an unreadable empty list when the policy is
112
+ * unavailable (whose level 0 already shows nothing — never widens).
113
+ */
114
+ export function viewingWhitelistFromPolicy(
115
+ policy: GoverningViewingPolicy,
116
+ ): StoredViewingWhitelist | null {
117
+ switch (policy.source) {
118
+ case "none":
119
+ return null;
120
+ case "team":
121
+ case "account":
122
+ return { informationScope: [...policy.visibleGroups], scopeVocab: policy.scopeVocab };
123
+ default:
124
+ return { informationScope: [], scopeVocab: null };
125
+ }
126
+ }
127
+
128
+ /** Resolve a viewer's access to one case. */
129
+ export function caseViewingAccess(
130
+ ctx: ViewingContext,
131
+ scope: ViewingScopeResolver,
132
+ ): CaseViewingAccess {
133
+ // An exhaustive, strict ladder: every out-of-type input lands on the NARROWEST
134
+ // branch, never falls through to a wider one.
135
+ if (ctx.canSeeCase !== true) {
136
+ return { mode: "none", reason: "cannot_see_case" };
137
+ }
138
+ if (ctx.ownedByViewer === true) return { mode: "full", reason: "owned" };
139
+ if (ctx.level === 1 || ctx.level === 2) {
140
+ return { mode: "stub", level: ctx.level };
141
+ }
142
+ if (ctx.level !== 3) return { mode: "none", reason: "level_0" };
143
+ // Exactly `null`: no viewing policy on file. An ABSENT whitelist is out-of-type
144
+ // input, not that fact, so it reads as an empty list and never widens.
145
+ if (ctx.whitelist === null) {
146
+ return { mode: "full", reason: "no_viewing_policy" };
147
+ }
148
+ const stored: StoredViewingWhitelist = ctx.whitelist ?? {
149
+ informationScope: [],
150
+ scopeVocab: CURRENT_VIEWING_POLICY_VOCAB,
151
+ };
152
+ const stamp = typeof stored.scopeVocab === "number" ? stored.scopeVocab : null;
153
+ const vocab = viewingPolicyVocabulary(stamp);
154
+ // A stamp this reader cannot read is handed to the resolver as stored (never 3
155
+ // or 4, which are readable), so the resolver reads it unsupported and includes
156
+ // nothing; an unstamped list is unsupported (fail closed).
157
+ const reading = scope.readSelection(
158
+ stored.informationScope,
159
+ vocab !== null ? vocab.scopeVersion : stamp,
160
+ { subject: "policy" },
161
+ );
162
+ // The alias reads the stored category itself, so a list naming only `names`
163
+ // does not carry it.
164
+ const identifyingAlias =
165
+ vocab !== null && vocab.identifyingAlias && reading.informationScope.includes("identifying");
166
+ return {
167
+ mode: "whitelist",
168
+ reading,
169
+ visibleScope: identifyingAlias
170
+ ? [...reading.informationScope, RELATIONSHIPS_HOUSEHOLD]
171
+ : reading.informationScope,
172
+ oneHomeCarry: vocab !== null && vocab.oneHomeCarry,
173
+ relationshipDynamicsCarry: identifyingAlias,
174
+ };
175
+ }
176
+
177
+ /**
178
+ * Does the case surface on `surface`? Level 1 — search only; level 2 — search and
179
+ * autocomplete; neither opens the record. Level 3 and full open it.
180
+ */
181
+ export function caseSurfacesOn(access: CaseViewingAccess, surface: ViewingSurface): boolean {
182
+ switch (access.mode) {
183
+ case "none":
184
+ return false;
185
+ case "full":
186
+ case "whitelist":
187
+ return true;
188
+ case "stub":
189
+ if (surface === "search") return true;
190
+ if (surface === "autocomplete") return access.level === 2;
191
+ return false;
192
+ }
193
+ }
194
+
195
+ /** Does the case surface as the stub projection (levels 1 and 2 only)? */
196
+ export function caseSurfacesAsStub(access: CaseViewingAccess): boolean {
197
+ return access.mode === "stub";
198
+ }
199
+
200
+ /** One record on a case, as the viewing decision reads it. */
201
+ export interface ViewingRecord {
202
+ /** The v4 kind-tree row the record's field is homed on (never a per-kind code). */
203
+ homeRow: string;
204
+ /** Whose record it is: the client, or another named person's kind. */
205
+ subjectKind: ScopeSubjectKind;
206
+ /** The author's user id. The author always sees their own record. */
207
+ authorUserId?: string | null | undefined;
208
+ /** The record's assertion domain, read ONLY by the pre-v4 carries. */
209
+ domain?: string | null | undefined;
210
+ }
211
+
212
+ /** Why a record is (not) visible. */
213
+ export type RecordViewingReason =
214
+ | "author"
215
+ | "full"
216
+ | "stub_row"
217
+ | "covered"
218
+ | "one_home_carry"
219
+ | "identifying_alias_carry"
220
+ | "cannot_see_case"
221
+ | "level_0"
222
+ | "not_opened"
223
+ | "not_covered"
224
+ | "unknown_row";
225
+
226
+ export interface RecordViewingDecision {
227
+ readonly visible: boolean;
228
+ readonly reason: RecordViewingReason;
229
+ }
230
+
231
+ /**
232
+ * The pre-v4 ONE-HOME carry: a stamp-3 whitelist that does NOT cover Screens &
233
+ * assessments keeps showing the three domains it showed before the re-point.
234
+ * Domain grain; the CATEGORY must be named.
235
+ */
236
+ const ONE_HOME_CARRY: ReadonlyArray<{
237
+ readonly homeRow: string;
238
+ readonly domains: ReadonlySet<string>;
239
+ readonly unlockedBy: string;
240
+ }> = [
241
+ { homeRow: "summary_ida", domains: new Set(["ida_determination"]), unlockedBy: "risk" },
242
+ {
243
+ homeRow: "summary_needs_assessment",
244
+ domains: new Set(["needs_assessment", "recommended_followup"]),
245
+ unlockedBy: "services",
246
+ },
247
+ ];
248
+
249
+ function isClientStubRow(scope: ViewingScopeResolver, code: string): boolean {
250
+ const row = scope.row(code);
251
+ return (
252
+ row !== undefined &&
253
+ row.levelFloor === 1 &&
254
+ row.rowType !== "branch" &&
255
+ (row.kindBranch === "client" || row.kindBranch === null)
256
+ );
257
+ }
258
+
259
+ /**
260
+ * May the viewer see this record on the case? A case the viewer cannot see:
261
+ * nothing (checked first, even for the author); the author: their own record;
262
+ * level 0: nothing; an owned case or no policy: all; level 1 / 2: the record never
263
+ * opens; level 3: the client's stub rows always, otherwise the whitelist must
264
+ * COVER the record's kind-tree home row.
265
+ */
266
+ export function recordViewing(
267
+ access: CaseViewingAccess,
268
+ record: ViewingRecord,
269
+ viewerUserId: string | null | undefined,
270
+ scope: ViewingScopeResolver,
271
+ ): RecordViewingDecision {
272
+ if (access.mode === "none" && access.reason === "cannot_see_case") {
273
+ return { visible: false, reason: "cannot_see_case" };
274
+ }
275
+ const author = record.authorUserId;
276
+ if (typeof author === "string" && author.trim().length > 0 && author === viewerUserId) {
277
+ return { visible: true, reason: "author" };
278
+ }
279
+ switch (access.mode) {
280
+ case "none":
281
+ return { visible: false, reason: access.reason };
282
+ case "full":
283
+ return { visible: true, reason: "full" };
284
+ case "stub":
285
+ return { visible: false, reason: "not_opened" };
286
+ case "whitelist":
287
+ return whitelistDecision(access, record, scope);
288
+ }
289
+ }
290
+
291
+ function whitelistDecision(
292
+ access: Extract<CaseViewingAccess, { mode: "whitelist" }>,
293
+ record: ViewingRecord,
294
+ scope: ViewingScopeResolver,
295
+ ): RecordViewingDecision {
296
+ const home = scope.row(record.homeRow);
297
+ // Deny-by-default for a home the tree does not know, and for a per-kind code
298
+ // passed as a home (a home is a kind-tree row).
299
+ if (home === undefined || home.kindRow !== undefined) {
300
+ return { visible: false, reason: "unknown_row" };
301
+ }
302
+ if (
303
+ (record.subjectKind === "client" || home.kindBranch !== "client") &&
304
+ isClientStubRow(scope, record.homeRow)
305
+ ) {
306
+ return { visible: true, reason: "stub_row" };
307
+ }
308
+ const list = access.visibleScope;
309
+ if (scope.isCovered(list, record.homeRow)) {
310
+ return { visible: true, reason: "covered" };
311
+ }
312
+ if (access.relationshipDynamicsCarry && record.domain === RELATIONSHIP_DYNAMICS) {
313
+ return { visible: true, reason: "identifying_alias_carry" };
314
+ }
315
+ if (
316
+ access.oneHomeCarry &&
317
+ !scope.isCovered(list, "instruments") &&
318
+ typeof record.domain === "string"
319
+ ) {
320
+ for (const carry of ONE_HOME_CARRY) {
321
+ if (
322
+ record.homeRow === carry.homeRow &&
323
+ carry.domains.has(record.domain) &&
324
+ scope.isCovered(list, carry.unlockedBy)
325
+ ) {
326
+ return { visible: true, reason: "one_home_carry" };
327
+ }
328
+ }
329
+ }
330
+ return { visible: false, reason: "not_covered" };
331
+ }
332
+
333
+ /** Is this kind-tree row visible under `access` (for the client)? */
334
+ export function viewingRowVisible(
335
+ access: CaseViewingAccess,
336
+ homeRow: string,
337
+ scope: ViewingScopeResolver,
338
+ ): boolean {
339
+ return recordViewing(access, { homeRow, subjectKind: "client" }, null, scope).visible;
340
+ }
341
+
342
+ /**
343
+ * Is this home row OPEN as a whole component under `access`: does the whitelist
344
+ * itself cover it? Stricter than {@link viewingRowVisible}: the stub (a name and a
345
+ * date of birth) does not open a whole component such as the name history behind
346
+ * it. System information is on every list, so it opens.
347
+ */
348
+ export function viewingComponentOpen(
349
+ access: CaseViewingAccess,
350
+ homeRow: string,
351
+ scope: ViewingScopeResolver,
352
+ ): boolean {
353
+ if (access.mode === "full") return true;
354
+ if (access.mode !== "whitelist") return false;
355
+ const row = scope.row(homeRow);
356
+ if (row === undefined || row.kindRow !== undefined) return false;
357
+ if (row.status === "retired") return false;
358
+ return scope.isCovered(access.visibleScope, homeRow);
359
+ }