@htilabs/platform-common-models 0.47.0 → 0.48.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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@htilabs/platform-common-models",
3
- "version": "0.47.0",
3
+ "version": "0.48.0",
4
4
  "description": "Shared constants, types, and models for HTI Labs applications",
5
5
  "type": "module",
6
6
  "main": "./dist/index.cjs",
@@ -125,6 +125,8 @@
125
125
  "clean": "rm -rf dist",
126
126
  "codegen:cvc": "tsx scripts/codegen-cvc-enums.ts",
127
127
  "codegen:cvc:check": "tsx scripts/codegen-cvc-enums.ts --check",
128
+ "gen:authz-tables": "tsx scripts/gen-authz-tables.ts",
129
+ "gen:authz-tables:check": "tsx scripts/gen-authz-tables.ts --check",
128
130
  "gen:capture-conflict-semantics": "tsx scripts/gen-capture-conflict-semantics.ts",
129
131
  "gen:capture-conflict-semantics:check": "tsx scripts/gen-capture-conflict-semantics.ts --check",
130
132
  "test:capture-conflict-semantics": "node --import tsx --test scripts/lib/captureConflictSemantics.test.ts",
@@ -0,0 +1,461 @@
1
+ /**
2
+ * The function door (Kickoff 08b § 11) and the shared role-code translation
3
+ * (2026-10-22 audit). Fixtures read the codebook default bounds as generated
4
+ * (`CORE_FUNCTION_DEFAULT_BOUNDS`, CVC-133 1.4.0); each case first asserts the
5
+ * bound it relies on, so a codebook change fails loudly here rather than
6
+ * silently testing a different bound.
7
+ */
8
+ import { describe, expect, it } from "vitest";
9
+ import * as authzSubpath from "../authz/index.js";
10
+ import { readFileSync, readdirSync } from "node:fs";
11
+ import path from "node:path";
12
+ import { fileURLToPath } from "node:url";
13
+ import {
14
+ canonicalRoleCode,
15
+ codebookDefaultBound,
16
+ functionDoor,
17
+ isCanonEvaluableFunction,
18
+ type AuthzRoleRow,
19
+ type FunctionDoorState,
20
+ } from "../index.js";
21
+
22
+ const NOT_OFFERED: FunctionDoorState = {
23
+ offered: false,
24
+ allowed: false,
25
+ reason: null,
26
+ };
27
+ const ALLOWED: FunctionDoorState = {
28
+ offered: true,
29
+ allowed: true,
30
+ reason: null,
31
+ };
32
+
33
+ describe("functionDoor — one case per codebook bound", () => {
34
+ const cases = [
35
+ // [function, role, bound]
36
+ ["api_key_manage", "MEM-ADM", "ALWAYS"],
37
+ ["case_claim", "crisis_response", "PREF_YES"], // Default On
38
+ ["announcement_publish", "MEM-ADM", "PREF_NO"], // Default Off
39
+ ] as const;
40
+
41
+ for (const [fn, role, bound] of cases) {
42
+ it(`${bound}: offered; allowed only when the effective set holds it`, () => {
43
+ expect(codebookDefaultBound(fn, role)).toBe(bound);
44
+ const roleCodes = [role];
45
+ const granted = functionDoor({
46
+ effectiveFunctions: [fn],
47
+ roleCodes,
48
+ functionKey: fn,
49
+ });
50
+ expect(granted).toEqual(ALLOWED);
51
+ const refused = functionDoor({
52
+ effectiveFunctions: [],
53
+ roleCodes: [role],
54
+ functionKey: fn,
55
+ });
56
+ expect(refused.offered).toBe(true);
57
+ expect(refused.allowed).toBe(false);
58
+ expect(refused.reason).toMatch(/ is not part of your roles$/);
59
+ });
60
+ }
61
+
62
+ it("NEVER: not offered, no reason", () => {
63
+ expect(codebookDefaultBound("api_key_manage", "SUP")).toBe("NEVER");
64
+ expect(
65
+ functionDoor({
66
+ effectiveFunctions: [],
67
+ roleCodes: ["SUP"],
68
+ functionKey: "api_key_manage",
69
+ }),
70
+ ).toEqual(NOT_OFFERED);
71
+ });
72
+
73
+ it("NA (Not relevant): read as NEVER — not offered", () => {
74
+ expect(codebookDefaultBound("api_key_manage", "case_nav")).toBe("NA");
75
+ expect(
76
+ functionDoor({
77
+ effectiveFunctions: [],
78
+ roleCodes: ["case_nav"],
79
+ functionKey: "api_key_manage",
80
+ }),
81
+ ).toEqual(NOT_OFFERED);
82
+ });
83
+
84
+ it("unbound: a role the codebook does not name is not offered", () => {
85
+ expect(codebookDefaultBound("api_key_manage", "screener")).toBeNull();
86
+ expect(
87
+ functionDoor({
88
+ effectiveFunctions: [],
89
+ roleCodes: ["screener"],
90
+ functionKey: "api_key_manage",
91
+ }),
92
+ ).toEqual(NOT_OFFERED);
93
+ });
94
+
95
+ it("no roles at all: not offered", () => {
96
+ expect(
97
+ functionDoor({
98
+ effectiveFunctions: [],
99
+ roleCodes: [],
100
+ functionKey: "api_key_manage",
101
+ }),
102
+ ).toEqual(NOT_OFFERED);
103
+ });
104
+
105
+ it("the effective set wins for allowed: a granted function is offered and allowed even if no role is codebook-bound (live policy moved off the default)", () => {
106
+ expect(
107
+ functionDoor({
108
+ effectiveFunctions: ["api_key_manage"],
109
+ roleCodes: ["screener"],
110
+ functionKey: "api_key_manage",
111
+ }),
112
+ ).toEqual(ALLOWED);
113
+ });
114
+ });
115
+
116
+ describe("functionDoor — stacking (NEVER stays local to its role)", () => {
117
+ it("one role NEVER, another ALWAYS → offered per the non-NEVER role; allowed follows the effective set", () => {
118
+ expect(codebookDefaultBound("api_key_manage", "SUP")).toBe("NEVER");
119
+ expect(codebookDefaultBound("api_key_manage", "MEM-ADM")).toBe("ALWAYS");
120
+ const roleCodes = ["SUP", "MEM-ADM"];
121
+ expect(
122
+ functionDoor({
123
+ effectiveFunctions: ["api_key_manage"],
124
+ roleCodes,
125
+ functionKey: "api_key_manage",
126
+ }),
127
+ ).toEqual(ALLOWED);
128
+ expect(
129
+ functionDoor({
130
+ effectiveFunctions: ["case_view"],
131
+ roleCodes,
132
+ functionKey: "api_key_manage",
133
+ }),
134
+ ).toEqual({
135
+ offered: true,
136
+ allowed: false,
137
+ reason: "Manage API keys is not part of your roles",
138
+ });
139
+ // order does not matter
140
+ expect(
141
+ functionDoor({
142
+ effectiveFunctions: [],
143
+ roleCodes: ["MEM-ADM", "SUP"],
144
+ functionKey: "api_key_manage",
145
+ }).offered,
146
+ ).toBe(true);
147
+ });
148
+
149
+ it("every role NEVER / NA → not offered", () => {
150
+ expect(
151
+ functionDoor({
152
+ effectiveFunctions: [],
153
+ roleCodes: ["SUP", "case_nav"],
154
+ functionKey: "api_key_manage",
155
+ }),
156
+ ).toEqual(NOT_OFFERED);
157
+ });
158
+
159
+ it("a stored re-keyed role code reads as its live role (hotline_op → crisis_response)", () => {
160
+ expect(
161
+ functionDoor({
162
+ effectiveFunctions: [],
163
+ roleCodes: ["hotline_op"],
164
+ functionKey: "case_claim",
165
+ }).offered,
166
+ ).toBe(true);
167
+ expect(
168
+ functionDoor({
169
+ effectiveFunctions: [],
170
+ roleCodes: ["acct_adm"],
171
+ functionKey: "api_key_manage",
172
+ }).offered,
173
+ ).toBe(true);
174
+ });
175
+ });
176
+
177
+ describe("functionDoor — live Tier-1 rows take precedence over the codebook default", () => {
178
+ it("live NEVER overrides codebook PREF_NO → not offered", () => {
179
+ expect(codebookDefaultBound("announcement_publish", "MEM-ADM")).toBe("PREF_NO");
180
+ const roles: AuthzRoleRow[] = [
181
+ { code: "MEM-ADM", functions: { announcement_publish: "NEVER" } },
182
+ ];
183
+ expect(
184
+ functionDoor({
185
+ effectiveFunctions: [],
186
+ roleCodes: ["MEM-ADM"],
187
+ functionKey: "announcement_publish",
188
+ }).offered,
189
+ ).toBe(true); // codebook path
190
+ expect(
191
+ functionDoor({
192
+ effectiveFunctions: [],
193
+ roleCodes: ["MEM-ADM"],
194
+ functionKey: "announcement_publish",
195
+ roles,
196
+ }),
197
+ ).toEqual(NOT_OFFERED);
198
+ });
199
+
200
+ it("live PREF_NO overrides codebook NEVER → offered and refused", () => {
201
+ expect(codebookDefaultBound("api_key_manage", "SUP")).toBe("NEVER");
202
+ const roles: AuthzRoleRow[] = [{ code: "SUP", functions: { api_key_manage: "PREF_NO" } }];
203
+ expect(
204
+ functionDoor({
205
+ effectiveFunctions: [],
206
+ roleCodes: ["SUP"],
207
+ functionKey: "api_key_manage",
208
+ roles,
209
+ }),
210
+ ).toEqual({
211
+ offered: true,
212
+ allowed: false,
213
+ reason: "Manage API keys is not part of your roles",
214
+ });
215
+ });
216
+
217
+ it("live rows decide alone: a role with no row, or no stored state, is unbound even if the codebook binds it", () => {
218
+ const base = {
219
+ effectiveFunctions: [],
220
+ roleCodes: ["MEM-ADM"],
221
+ functionKey: "api_key_manage",
222
+ };
223
+ expect(functionDoor({ ...base, roles: [] })).toEqual(NOT_OFFERED);
224
+ expect(functionDoor({ ...base, roles: [{ code: "MEM-ADM", functions: {} }] })).toEqual(
225
+ NOT_OFFERED,
226
+ );
227
+ });
228
+
229
+ it("live NA and a malformed stored state read NEVER; a malformed functions container binds nothing", () => {
230
+ const base = {
231
+ effectiveFunctions: [],
232
+ roleCodes: ["MEM-ADM"],
233
+ functionKey: "api_key_manage",
234
+ };
235
+ for (const functions of [
236
+ { api_key_manage: "NA" },
237
+ { api_key_manage: "yes" },
238
+ ["api_key_manage"],
239
+ ]) {
240
+ expect(
241
+ functionDoor({
242
+ ...base,
243
+ roles: [{ code: "MEM-ADM", functions } as unknown as AuthzRoleRow],
244
+ }),
245
+ JSON.stringify(functions),
246
+ ).toEqual(NOT_OFFERED);
247
+ }
248
+ });
249
+
250
+ it("live rows stack: one role's live NEVER stays local", () => {
251
+ const roles: AuthzRoleRow[] = [
252
+ { code: "SUP", functions: { api_key_manage: "NEVER" } },
253
+ { code: "MEM-ADM", functions: { api_key_manage: "ALWAYS" } },
254
+ ];
255
+ expect(
256
+ functionDoor({
257
+ effectiveFunctions: [],
258
+ roleCodes: ["SUP", "MEM-ADM"],
259
+ functionKey: "api_key_manage",
260
+ roles,
261
+ }).offered,
262
+ ).toBe(true);
263
+ });
264
+
265
+ it("a re-keyed stored role code finds its live row under the canon code", () => {
266
+ const roles: AuthzRoleRow[] = [
267
+ { code: "crisis_response", functions: { case_claim: "PREF_YES" } },
268
+ ];
269
+ expect(
270
+ functionDoor({
271
+ effectiveFunctions: [],
272
+ roleCodes: ["hotline_op"],
273
+ functionKey: "case_claim",
274
+ roles,
275
+ }).offered,
276
+ ).toBe(true);
277
+ });
278
+
279
+ it("live retired (or missing) catalog row → not offered", () => {
280
+ const base = {
281
+ effectiveFunctions: [],
282
+ roleCodes: ["MEM-ADM"],
283
+ functionKey: "api_key_manage",
284
+ };
285
+ expect(
286
+ functionDoor({
287
+ ...base,
288
+ functions: [{ code: "api_key_manage", retired: true }],
289
+ }),
290
+ ).toEqual(NOT_OFFERED);
291
+ expect(functionDoor({ ...base, functions: [{ code: "case_view" }] })).toEqual(NOT_OFFERED);
292
+ expect(
293
+ functionDoor({
294
+ ...base,
295
+ functions: [{ code: "api_key_manage", retired: false }],
296
+ }).offered,
297
+ ).toBe(true);
298
+ });
299
+
300
+ it("never refuses what the server grants: granted wins over a live NEVER or a retired row", () => {
301
+ const base = {
302
+ effectiveFunctions: ["api_key_manage"],
303
+ roleCodes: ["MEM-ADM"],
304
+ functionKey: "api_key_manage",
305
+ };
306
+ expect(
307
+ functionDoor({
308
+ ...base,
309
+ roles: [{ code: "MEM-ADM", functions: { api_key_manage: "NEVER" } }],
310
+ }),
311
+ ).toEqual(ALLOWED);
312
+ expect(
313
+ functionDoor({
314
+ ...base,
315
+ functions: [{ code: "api_key_manage", retired: true }],
316
+ }),
317
+ ).toEqual(ALLOWED);
318
+ });
319
+
320
+ it("absent rows (undefined / null) → the codebook path, unchanged", () => {
321
+ const base = {
322
+ effectiveFunctions: [],
323
+ roleCodes: ["MEM-ADM"],
324
+ functionKey: "api_key_manage",
325
+ };
326
+ const codebook = functionDoor(base);
327
+ expect(codebook.offered).toBe(true);
328
+ expect(functionDoor({ ...base, roles: null, functions: null })).toEqual(codebook);
329
+ expect(functionDoor({ ...base, roles: undefined, functions: undefined })).toEqual(codebook);
330
+ });
331
+ });
332
+
333
+ describe("./authz carries no SOT JSON (bundle)", () => {
334
+ it("no module in src/authz imports a src/cvcs file", () => {
335
+ const dir = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "authz");
336
+ const specifiers = readdirSync(dir)
337
+ .filter((f) => f.endsWith(".ts"))
338
+ .flatMap((f) =>
339
+ [...readFileSync(path.join(dir, f), "utf8").matchAll(/from\s+"([^"]+)"/g)].map(
340
+ (m) => m[1]!,
341
+ ),
342
+ );
343
+ expect(specifiers.filter((s) => s.includes("/cvcs/") || s.endsWith(".json"))).toEqual([]);
344
+ });
345
+ });
346
+
347
+ describe("functionDoor — unknown / retired / not-v1 keys are never offered", () => {
348
+ it("an unknown key, even if a caller's effective set lists it", () => {
349
+ expect(isCanonEvaluableFunction("account_suspend")).toBe(false); // in CVC-133, v1: false
350
+ const keys = [
351
+ "not_a_function",
352
+ "ida_conduct",
353
+ "constructor",
354
+ "missingness_root",
355
+ "unknown",
356
+ "account_suspend",
357
+ ];
358
+ for (const key of keys) {
359
+ expect(
360
+ functionDoor({
361
+ effectiveFunctions: [key],
362
+ roleCodes: ["MEM-ADM", "PLT-ADM"],
363
+ functionKey: key,
364
+ }),
365
+ key,
366
+ ).toEqual(NOT_OFFERED);
367
+ }
368
+ });
369
+ });
370
+
371
+ describe("functionDoor — the refusal's words", () => {
372
+ const base = {
373
+ effectiveFunctions: [],
374
+ roleCodes: ["MEM-ADM"],
375
+ functionKey: "api_key_manage",
376
+ };
377
+
378
+ it("defaults to the codebook title", () => {
379
+ expect(functionDoor(base).reason).toBe("Manage API keys is not part of your roles");
380
+ });
381
+
382
+ it("takes a lookup function or a map; blank or missing falls back to the codebook title", () => {
383
+ expect(functionDoor({ ...base, label: () => "API keys" }).reason).toBe(
384
+ "API keys is not part of your roles",
385
+ );
386
+ expect(functionDoor({ ...base, label: { api_key_manage: "Keys" } }).reason).toBe(
387
+ "Keys is not part of your roles",
388
+ );
389
+ expect(functionDoor({ ...base, label: () => " " }).reason).toBe(
390
+ "Manage API keys is not part of your roles",
391
+ );
392
+ expect(functionDoor({ ...base, label: {} }).reason).toBe(
393
+ "Manage API keys is not part of your roles",
394
+ );
395
+ });
396
+
397
+ it("returns a fresh object each call (callers may mutate)", () => {
398
+ const a = functionDoor({
399
+ effectiveFunctions: [],
400
+ roleCodes: [],
401
+ functionKey: "api_key_manage",
402
+ });
403
+ const b = functionDoor({
404
+ effectiveFunctions: [],
405
+ roleCodes: [],
406
+ functionKey: "api_key_manage",
407
+ });
408
+ expect(a).not.toBe(b);
409
+ a.reason = "x";
410
+ expect(b.reason).toBeNull();
411
+ });
412
+ });
413
+
414
+ describe("canonicalRoleCode — matches Thread seatRoleCodes.ts and platform lib/authz/roleCodes.ts", () => {
415
+ it.each([
416
+ ["hotline_op", "crisis_response"],
417
+ ["case_advocate", "case_nav"],
418
+ ["leads_investigator", "investigator"],
419
+ ["acct_adm", "MEM-ADM"],
420
+ ["ACCT-ADM", "MEM-ADM"],
421
+ ])("re-key source %s → %s", (stored, canon) => {
422
+ expect(canonicalRoleCode(stored)).toBe(canon);
423
+ });
424
+
425
+ it.each(["crisis_response", "case_nav", "MEM-ADM", "PLT-ADM", "TEAM-ADM", "volunteer"])(
426
+ "a current code %s → itself",
427
+ (code) => {
428
+ expect(canonicalRoleCode(code)).toBe(code);
429
+ },
430
+ );
431
+
432
+ it.each(["unknown", "anonymous", "data_not_collected", "missingness_root"])(
433
+ "a withdrawn code with no successor (%s) → null",
434
+ (code) => {
435
+ expect(canonicalRoleCode(code)).toBeNull();
436
+ },
437
+ );
438
+
439
+ it("exact spellings only: no case- or separator-folding; identity keyMap lines are not sources", () => {
440
+ for (const code of [
441
+ "plt_adm",
442
+ "PLT_ADM",
443
+ "Plt-Adm",
444
+ "mem_adm",
445
+ "Crisis_Response",
446
+ "",
447
+ "constructor",
448
+ ]) {
449
+ expect(canonicalRoleCode(code), code).toBeNull();
450
+ }
451
+ });
452
+
453
+ it("a non-string is no role", () => {
454
+ for (const v of [null, undefined, 7, {}, ["MEM-ADM"]]) expect(canonicalRoleCode(v)).toBeNull();
455
+ });
456
+
457
+ it("is on the browser-safe ./authz subpath", () => {
458
+ expect(authzSubpath.canonicalRoleCode).toBe(canonicalRoleCode);
459
+ expect(authzSubpath.functionDoor).toBe(functionDoor);
460
+ });
461
+ });
@@ -256,6 +256,48 @@ describe("§ 4.1 extras", () => {
256
256
  expect(selectActingTeamId([], "team-verified-elsewhere")).toBe("team-verified-elsewhere");
257
257
  });
258
258
 
259
+ it("rule 5 (Kickoff 08b § 6 step 2): the verified team is returned as is when given; the primary team is the fallback when not", () => {
260
+ const seat = ["team-primary", "team-second"];
261
+ expect(selectActingTeamId(seat, "team-second")).toBe("team-second");
262
+ expect(selectActingTeamId(seat, undefined)).toBe("team-primary");
263
+ expect(selectActingTeamId(seat, null)).toBe("team-primary");
264
+ expect(selectActingTeamId(seat, "")).toBe("team-primary");
265
+ expect(selectActingTeamId([], null)).toBeNull();
266
+ });
267
+
268
+ it("rule 5 contract Thread relies on: a caller that derives its own acting team passes it as verifiedActingTeamId and the shared selector never second-guesses it", () => {
269
+ // Thread's `resolveActingTeamId` (@thread/shared, apps/api/src/helpers/acting-team.ts)
270
+ // picks the FIRST seat team whose apps include THREAD — not the seat's primary team.
271
+ const seatTeams = [
272
+ { id: "team-pave-only", apps: ["PAVE"] },
273
+ { id: "team-thread", apps: ["PAVE", "THREAD"] },
274
+ ];
275
+ const threadActing = seatTeams.find((t) => t.apps.includes("THREAD"))!.id;
276
+ const seatTeamIds = seatTeams.map((t) => t.id);
277
+ const policies: Record<string, AuthzTeamPolicy> = {
278
+ "team-pave-only": {},
279
+ "team-thread": { functions: { session_create: "PREF_NO" } },
280
+ };
281
+ // Left to itself the selector would choose the primary (PAVE-only) team,
282
+ // whose policy WOULD grant session_create…
283
+ expect(selectActingTeamId(seatTeamIds)).toBe("team-pave-only");
284
+ expect(
285
+ resolve({
286
+ assignedRoleCodes: ["CIRO"],
287
+ teamPolicy: policies[selectActingTeamId(seatTeamIds) ?? ""] ?? null,
288
+ }),
289
+ ).toContain("session_create");
290
+ // …so Thread must hand its own answer in, and it comes back untouched.
291
+ expect(selectActingTeamId(seatTeamIds, threadActing)).toBe("team-thread");
292
+ // …and with the caller's team the answer changes: the choice of team decides it.
293
+ expect(
294
+ resolve({
295
+ assignedRoleCodes: ["CIRO"],
296
+ teamPolicy: policies[selectActingTeamId(seatTeamIds, threadActing) ?? ""] ?? null,
297
+ }),
298
+ ).not.toContain("session_create");
299
+ });
300
+
259
301
  it("rule 8: a canon-unknown code is denied even when the caller's catalog lists it with a v1-looking row", () => {
260
302
  // ida_conduct is in the platform seed (cvcRoles.js) but not in CVC-133.
261
303
  const fns = resolve({
@@ -498,6 +540,10 @@ describe("§ 4.1 extras", () => {
498
540
  "../generated/coreFunctionsEvaluable.js",
499
541
  "./defaultBounds.js",
500
542
  "../generated/coreFunctionDefaultBounds.js",
543
+ "./functionDoor.js",
544
+ "./roleCodes.js",
545
+ "./storedReads.js",
546
+ "../generated/authzBrowserTables.js",
501
547
  ]),
502
548
  );
503
549
  });