@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/README.md CHANGED
@@ -16,6 +16,44 @@ Package exports are organized into a public root API and a small number of
16
16
  dedicated subpaths (`/validation`, `/cvcs`) — consult `package.json` for the
17
17
  authoritative `exports` map.
18
18
 
19
+ ## authz — the function door + canonicalRoleCode / 0.48.0 (additive — DRAFT exports; nothing existing changes)
20
+
21
+ **What it makes possible.** The resolver (`resolveEffectiveFunctions`) decides
22
+ what a seat may do; nothing carried that answer to the screen. Kickoff 08b
23
+ § 11 adds the carrier, on the browser-safe `./authz` subpath (and the root):
24
+
25
+ - `functionDoor({ effectiveFunctions, roleCodes, functionKey, label?, roles?, functions? })` →
26
+ `{ allowed, reason, offered }` — the door shape the shared components take
27
+ (`SharePurposeAccess` / `ShareRow.revokeAccess` read `{ allowed, reason }`;
28
+ the host reads `offered` to decide whether to draw the control). Encoding:
29
+ the function's Tier-1 bound across the seat's roles, stacked with NEVER
30
+ local to its role. NEVER / NA for every role, or no role bound → not
31
+ offered. Bound (Always / Default On / Default Off) but not in the effective
32
+ set → offered, refused with `"<label> is not part of your roles"` (label:
33
+ the caller's lookup, else the CVC-133 title, else the key). In the effective
34
+ set → allowed, always (the door never refuses what the server grants).
35
+ **Which bound:** the LIVE `platformRoles` rows when the host passes `roles`
36
+ (the same rows it hands `resolveEffectiveFunctions`, read through the
37
+ resolver's own Tier-1 reader), else the codebook default
38
+ (`CORE_FUNCTION_DEFAULT_BOUNDS`). A passed `functions` catalog drops a
39
+ missing or retired function. Unknown / not-v1 keys are never offered.
40
+ **The door is the early answer only — each app's server-side
41
+ `requireFunction` stays the authority.**
42
+ - Bundle: `./authz` reads a generated `src/generated/authzBrowserTables.ts`
43
+ (CVC-133 titles + the role re-key table, ~7 KB source) instead of the SOT
44
+ JSON — `npm run gen:authz-tables`, drift gate `gen:authz-tables:check` in
45
+ CI. The resolver's stored-row reads moved verbatim into an internal
46
+ `storedReads.ts` shared with the door (no behaviour change).
47
+ - `canonicalRoleCode(code)` — stored role code → live CVC-134 / CVC-135 canon
48
+ code through the SOTs' `_supersedes.keyMap` (`hotline_op` →
49
+ `crisis_response`, `acct_adm` / `ACCT-ADM` → `MEM-ADM`; withdrawn with no
50
+ successor → `null`; exact spellings only). Ported from Thread
51
+ `seatRoleCodes.ts` / platform `lib/authz/roleCodes.ts` (same results) so
52
+ PAVE gets it; the apps keep their copies until they switch over.
53
+ - `selectActingTeamId` — no behaviour change; documented and tested: a caller
54
+ that derives its own acting team (Thread's first-THREAD-team rule) passes it
55
+ as `verifiedActingTeamId`, and the selector never second-guesses it.
56
+
19
57
  ## serviceDeliveryChangeType 1.0.0 / 0.47.0 (additive — a new DRAFT list; nothing existing changes)
20
58
 
21
59
  **What it makes possible.** Every change to a service record can be recorded as
@@ -27,7 +27,9 @@ __export(authz_exports, {
27
27
  DEFAULT_BOUND_STATE_LABELS: () => DEFAULT_BOUND_STATE_LABELS,
28
28
  DEFAULT_BOUND_STATE_VALUES: () => DEFAULT_BOUND_STATE_VALUES,
29
29
  VIEWING_LEVEL_FUNCTIONS: () => VIEWING_LEVEL_FUNCTIONS,
30
+ canonicalRoleCode: () => canonicalRoleCode,
30
31
  codebookDefaultBound: () => codebookDefaultBound,
32
+ functionDoor: () => functionDoor,
31
33
  isCanonEvaluableFunction: () => isCanonEvaluableFunction,
32
34
  resolveEffectiveFunctions: () => resolveEffectiveFunctions,
33
35
  resolveEffectiveViewingLevel: () => resolveEffectiveViewingLevel,
@@ -409,13 +411,7 @@ var CORE_FUNCTIONS_EVALUABLE_KEYS = [
409
411
  "viewing_level_3_components"
410
412
  ];
411
413
 
412
- // src/authz/resolveEffectiveFunctions.ts
413
- var CANON_EVALUABLE = new Set(
414
- CORE_FUNCTIONS_EVALUABLE_KEYS.filter((k) => Object.hasOwn(CoreFunctionsKeys, k))
415
- );
416
- function isCanonEvaluableFunction(code) {
417
- return CANON_EVALUABLE.has(code);
418
- }
414
+ // src/authz/storedReads.ts
419
415
  var ABSENT = { kind: "absent" };
420
416
  var MALFORMED = { kind: "malformed" };
421
417
  function isPlainObject(v) {
@@ -437,6 +433,27 @@ function readState(map, code) {
437
433
  if (v === DEFAULT_BOUND_STATE.NA) return PERMISSION_STATE.NEVER;
438
434
  return typeof v === "string" && STATES.has(v) ? v : "malformed";
439
435
  }
436
+ function tier1State(roleFunctions, code) {
437
+ const listed = roleFunctions.kind === "map" ? readState(roleFunctions.map, code) : void 0;
438
+ if (listed === void 0) return void 0;
439
+ return listed === "malformed" ? PERMISSION_STATE.NEVER : listed;
440
+ }
441
+ function catalogRowCode(row) {
442
+ if (!isPlainObject(row)) return null;
443
+ const code = own(row, "code");
444
+ const retired = own(row, "retired");
445
+ if (typeof code !== "string") return null;
446
+ if (retired !== void 0 && retired !== false) return null;
447
+ return code;
448
+ }
449
+
450
+ // src/authz/resolveEffectiveFunctions.ts
451
+ var CANON_EVALUABLE = new Set(
452
+ CORE_FUNCTIONS_EVALUABLE_KEYS.filter((k) => Object.hasOwn(CoreFunctionsKeys, k))
453
+ );
454
+ function isCanonEvaluableFunction(code) {
455
+ return CANON_EVALUABLE.has(code);
456
+ }
440
457
  function teamValueRestricts(map, code) {
441
458
  const gate = readState(map, code);
442
459
  return gate !== void 0 && gate !== PERMISSION_STATE.PREF_YES && gate !== PERMISSION_STATE.ALWAYS;
@@ -504,12 +521,8 @@ function resolveEffectiveFunctions(input) {
504
521
  if (heldCodes.length === 0) return [];
505
522
  const vocabulary = [];
506
523
  for (const fn of catalog) {
507
- if (!isPlainObject(fn)) continue;
508
- const code = own(fn, "code");
509
- const retired = own(fn, "retired");
510
- if (typeof code !== "string" || !isCanonEvaluableFunction(code)) continue;
511
- if (retired !== void 0 && retired !== false) continue;
512
- vocabulary.push(code);
524
+ const code = catalogRowCode(fn);
525
+ if (code !== null && isCanonEvaluableFunction(code)) vocabulary.push(code);
513
526
  }
514
527
  const agencyAll = readContainer(input.agencyOverrides);
515
528
  const team = compileTeamGate(input.teamPolicy);
@@ -521,9 +534,8 @@ function resolveEffectiveFunctions(input) {
521
534
  const agency = agencyAll.kind === "map" ? readContainer(own(agencyAll.map, roleCode)) : agencyAll;
522
535
  for (const fn of vocabulary) {
523
536
  if (granted.has(fn)) continue;
524
- const listed = roleFunctions.kind === "map" ? readState(roleFunctions.map, fn) : void 0;
525
- if (listed === void 0) continue;
526
- const tier1 = listed === "malformed" ? PERMISSION_STATE.NEVER : listed;
537
+ const tier1 = tier1State(roleFunctions, fn);
538
+ if (tier1 === void 0) continue;
527
539
  let state = tier1;
528
540
  if (tier1 !== PERMISSION_STATE.ALWAYS && tier1 !== PERMISSION_STATE.NEVER) {
529
541
  const override = agency.kind === "malformed" ? "malformed" : agency.kind === "map" ? readState(agency.map, fn) : void 0;
@@ -653,6 +665,219 @@ function codebookDefaultBound(functionCode, roleCode) {
653
665
  const roles = CORE_FUNCTION_DEFAULT_BOUNDS[functionCode];
654
666
  return Object.hasOwn(roles, roleCode) ? roles[roleCode] : null;
655
667
  }
668
+
669
+ // src/generated/authzBrowserTables.ts
670
+ var CORE_FUNCTION_TITLES = {
671
+ "agency_info_manage": "Edit own agency's profile",
672
+ "announcement_publish": "Publish announcements",
673
+ "api_key_manage": "Manage API keys",
674
+ "assessments_conduct": "Conduct Assessments",
675
+ "auth_model_manage_platform": "Manage platform authorization model",
676
+ "case_assign_reassign": "Assign / reassign case ownership",
677
+ "case_claim": "Claim inbound share (PAVE)",
678
+ "case_close": "Close case",
679
+ "case_collaborator_add": "Share / Add Users to a case",
680
+ "case_edit": "Edit Cases (add intake, case notes, goals, services)",
681
+ "case_needs_action_flag_manage": "Manage case escalation / needs-action flags",
682
+ "case_reopen": "Case Re-open",
683
+ "case_side_panel_use": "Utilize side panel for comments/notes and uploads",
684
+ "case_status_manage": "Change case status",
685
+ "case_transfer_bulk": "Bulk transfer cases (turnover)",
686
+ "case_view": "View (agency) Cases",
687
+ "case_visibility_manage": "Go dark / restore case visibility",
688
+ "ci_periodic_review": "Review criminal intelligence record (periodic)",
689
+ "ci_record_purge_or_retire": "Retire or purge criminal intelligence record",
690
+ "ci_record_validate": "Validate criminal intelligence record",
691
+ "ci_to_evidence_export_authorize": "Authorize criminal intelligence \u2192 evidence export",
692
+ "deconfliction_alert_acknowledge": "Accept a deconfliction alert",
693
+ "deconfliction_unmask": "Unmask a deconfliction",
694
+ "determination_perform": "Perform Determinations",
695
+ "disclose_external_request": "Request External Disclosure",
696
+ "enrollment_manage": "Manage program enrollments",
697
+ "exit_discharge_conduct": "Conduct program exit / discharge",
698
+ "export_deidentified": "Export de-identified reports/datasets",
699
+ "goals_plan_manage": "Create and manage plans, goals, action steps",
700
+ "idb_record_create": "Create IDB record",
701
+ "indicator_manual_add": "Add a manual indicator",
702
+ "investigation_create_claim": "Create Investigation + Claim a Tip / Lead",
703
+ "investigation_session_run": "Run an investigation session",
704
+ "investigative_database_search": "Search account IDB",
705
+ "investigative_request_send": "Submit an investigative request (Ask HTI)",
706
+ "lead_create": "Create a Tip / Lead",
707
+ "lead_publish": "Publish a Tip / Lead",
708
+ "lead_route_assign": "Route / assign a lead to an agency",
709
+ "lead_triage_manage": "Triage leads",
710
+ "magic_link_share_send": "Send Magic Link Shares",
711
+ "mandatory_report_send": "Send mandatory report",
712
+ "member_account_report_generate": "Member Account Report generation",
713
+ "member_onboarding_support": "Assist member onboarding (support)",
714
+ "message_moderate": "Moderate messages",
715
+ "message_send": "Send platform messages",
716
+ "milestone_log": "Log investigative milestones",
717
+ "needs_priorities_conduct": "Conduct needs assessment and immediate priorities",
718
+ "network_corpus_access": "Access raw/worked machine-network corpus",
719
+ "note_open_departed_author": "Open a deactivated author's private notes",
720
+ "onboarding_config_sign_off": "Approve the configuration summary (Phase III sign-off)",
721
+ "open_source_search": "Search across all open source information",
722
+ "person_association_update": "Assign or update person\u2019s role, relationships, phone numbers or social media associations",
723
+ "person_merge_manage": "Manage person identity merges",
724
+ "platform_perm_modify": "Modify Platform Permissions",
725
+ "profile_domain_edit": "Edit subject profile domains",
726
+ "record_activity_view": "View a record's activity log",
727
+ "record_print": "Export/Print",
728
+ "referral_receive_external": "Receive External Referrals",
729
+ "referral_receive_internal": "Receive Internal Referrals",
730
+ "referral_send_external": "Refer External (Excluding VSP to LE)",
731
+ "referral_send_internal": "Refer Internal",
732
+ "roi_submit_manage": "Upload/Edit/Submit ROI",
733
+ "role_assign": "Role Assignment",
734
+ "roles_accounts_toggle": "Toggle Roles / Accounts",
735
+ "sandbox_environment_manage": "Manage sandbox and testing environments",
736
+ "screening_conduct": "Conduct Screenings",
737
+ "screening_view": "View Victim/Abuse Screening Responses",
738
+ "service_log_manage": "Log and manage service instances",
739
+ "session_create": "Record creation (sessions, cases, etc.)",
740
+ "share_config": "Sharing Configuration",
741
+ "share_revoke": "Revoke an active share / ROI",
742
+ "share_rule_approve_cross_agency": "Approve cross-agency sharing rules",
743
+ "share_vsp_to_le": "VSP to LE Share",
744
+ "srl_manage": "Manage the agency's Service Registry (SRL)",
745
+ "supervisee_thread_view": "View supervisee threads",
746
+ "support_ticket_triage": "Triage support tickets / bug reports",
747
+ "system_diagnostics_view": "View system diagnostics and logs (support)",
748
+ "team_config_manage": "Team structure & admin scoping (account-level)",
749
+ "team_membership_manage": "Manage team membership",
750
+ "team_share_narrowing": "Narrow a team's sharing",
751
+ "team_workflow_config_manage": "Manage team workflow configuration",
752
+ "training_gate_manage": "Manage training/certification gates (i.e. required modules for roles + teams)",
753
+ "usr_manage": "User Management",
754
+ "viewing_config_manage": "Configure internal viewing (Type A)",
755
+ "viewing_level_1_search": "Non-owned case identity on search",
756
+ "viewing_level_2_autocomplete": "Non-owned case identity in autocomplete",
757
+ "viewing_level_3_components": "Non-owned case component access"
758
+ };
759
+ var CANON_ROLE_CODE_LIST = [
760
+ "case_nav",
761
+ "healthcare_provider_medical",
762
+ "behavioral_health_provider",
763
+ "crisis_response",
764
+ "intel_analyst",
765
+ "investigator",
766
+ "le_liaison_vsp",
767
+ "legal_advocate",
768
+ "mandatory_reporter",
769
+ "mdt_participant",
770
+ "prosecutor_review",
771
+ "public_reporter",
772
+ "research_analytics",
773
+ "screener",
774
+ "volunteer",
775
+ "PLT-ADM",
776
+ "PLT-SUP",
777
+ "MEM-ADM",
778
+ "TEAM-ADM",
779
+ "AUD",
780
+ "DATA-ADM",
781
+ "GOV-AUD",
782
+ "CIRO",
783
+ "SUP",
784
+ "TRAIN-ADM"
785
+ ];
786
+ var ROLE_CODE_RE_KEYS = {
787
+ "missingness_root": null,
788
+ "unknown": null,
789
+ "anonymous": null,
790
+ "data_not_collected": null,
791
+ "hotline_op": "crisis_response",
792
+ "case_advocate": "case_nav",
793
+ "leads_investigator": "investigator",
794
+ "MISSINGNESS-ROOT": null,
795
+ "UNKNOWN": null,
796
+ "ANONYMOUS": null,
797
+ "DATA-NOT-COLLECTED": null,
798
+ "acct_adm": "MEM-ADM",
799
+ "ACCT-ADM": "MEM-ADM"
800
+ };
801
+
802
+ // src/authz/roleCodes.ts
803
+ var CANON_ROLE_CODES = new Set(CANON_ROLE_CODE_LIST);
804
+ var SOURCES = new Map(Object.entries(ROLE_CODE_RE_KEYS));
805
+ function canonicalRoleCode(code) {
806
+ if (typeof code !== "string") return null;
807
+ if (CANON_ROLE_CODES.has(code)) return code;
808
+ return SOURCES.has(code) ? SOURCES.get(code) ?? null : null;
809
+ }
810
+
811
+ // src/authz/functionDoor.ts
812
+ var NOT_OFFERED = Object.freeze({
813
+ offered: false,
814
+ allowed: false,
815
+ reason: null
816
+ });
817
+ function labelFor(functionKey, lookup) {
818
+ let label;
819
+ if (typeof lookup === "function") label = lookup(functionKey);
820
+ else if (lookup && Object.hasOwn(lookup, functionKey)) label = lookup[functionKey];
821
+ if (typeof label === "string" && label.trim()) return label;
822
+ return Object.hasOwn(CORE_FUNCTION_TITLES, functionKey) ? CORE_FUNCTION_TITLES[functionKey] : functionKey;
823
+ }
824
+ function drawsControl(state) {
825
+ return state === PERMISSION_STATE.ALWAYS || state === PERMISSION_STATE.PREF_YES || state === PERMISSION_STATE.PREF_NO;
826
+ }
827
+ function indexRoleRows(rows) {
828
+ const byCode = /* @__PURE__ */ new Map();
829
+ if (!Array.isArray(rows)) return byCode;
830
+ for (const r of rows) {
831
+ const code = isPlainObject(r) ? own(r, "code") : void 0;
832
+ if (isPlainObject(r) && typeof code === "string") byCode.set(code, r);
833
+ }
834
+ return byCode;
835
+ }
836
+ function liveRoleBound(rows, roleCode, functionKey) {
837
+ const row = rows.get(roleCode);
838
+ if (row === void 0) return false;
839
+ const container = readContainer(own(row, "functions"));
840
+ if (container.kind === "malformed") return false;
841
+ return drawsControl(tier1State(container, functionKey));
842
+ }
843
+ function codebookRoleBound(roleCode, functionKey) {
844
+ const bound = codebookDefaultBound(functionKey, roleCode);
845
+ return bound !== DEFAULT_BOUND_STATE.NA && drawsControl(bound);
846
+ }
847
+ function functionDoor(input) {
848
+ const { functionKey } = input;
849
+ if (typeof functionKey !== "string" || !isCanonEvaluableFunction(functionKey)) {
850
+ return { ...NOT_OFFERED };
851
+ }
852
+ let granted = false;
853
+ for (const fn of input.effectiveFunctions) {
854
+ if (fn === functionKey) {
855
+ granted = true;
856
+ break;
857
+ }
858
+ }
859
+ if (granted) return { offered: true, allowed: true, reason: null };
860
+ const functions = input.functions;
861
+ if (functions !== void 0 && functions !== null) {
862
+ const kept = Array.isArray(functions) && functions.some((row) => catalogRowCode(row) === functionKey);
863
+ if (!kept) return { ...NOT_OFFERED };
864
+ }
865
+ const liveRows = input.roles;
866
+ const live = liveRows !== void 0 && liveRows !== null ? indexRoleRows(liveRows) : null;
867
+ const roleCodes = input.roleCodes;
868
+ const bound = (Array.isArray(roleCodes) ? roleCodes : []).some((code) => {
869
+ const canon = canonicalRoleCode(code);
870
+ if (canon === null) return false;
871
+ if (live === null) return codebookRoleBound(canon, functionKey);
872
+ return liveRoleBound(live, canon, functionKey) || typeof code === "string" && code !== canon && liveRoleBound(live, code, functionKey);
873
+ });
874
+ if (!bound) return { ...NOT_OFFERED };
875
+ return {
876
+ offered: true,
877
+ allowed: false,
878
+ reason: `${labelFor(functionKey, input.label)} is not part of your roles`
879
+ };
880
+ }
656
881
  // Annotate the CommonJS export names for ESM import in node:
657
882
  0 && (module.exports = {
658
883
  CORE_FUNCTION_DEFAULT_BOUNDS,
@@ -662,7 +887,9 @@ function codebookDefaultBound(functionCode, roleCode) {
662
887
  DEFAULT_BOUND_STATE_LABELS,
663
888
  DEFAULT_BOUND_STATE_VALUES,
664
889
  VIEWING_LEVEL_FUNCTIONS,
890
+ canonicalRoleCode,
665
891
  codebookDefaultBound,
892
+ functionDoor,
666
893
  isCanonEvaluableFunction,
667
894
  resolveEffectiveFunctions,
668
895
  resolveEffectiveViewingLevel,