@htilabs/platform-common-models 0.22.0 → 0.23.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 (61) hide show
  1. package/dist/authz/index.cjs +539 -0
  2. package/dist/authz/index.cjs.map +1 -0
  3. package/dist/authz/index.d.cts +210 -0
  4. package/dist/authz/index.d.ts +210 -0
  5. package/dist/authz/index.js +507 -0
  6. package/dist/authz/index.js.map +1 -0
  7. package/dist/constants/index.d.cts +2 -1
  8. package/dist/constants/index.d.ts +2 -1
  9. package/dist/cvcs/index.cjs +647 -353
  10. package/dist/cvcs/index.cjs.map +1 -1
  11. package/dist/cvcs/index.d.cts +658 -362
  12. package/dist/cvcs/index.d.ts +658 -362
  13. package/dist/cvcs/index.js +647 -353
  14. package/dist/cvcs/index.js.map +1 -1
  15. package/dist/enums/index.cjs +1 -9
  16. package/dist/enums/index.cjs.map +1 -1
  17. package/dist/enums/index.d.cts +7 -15
  18. package/dist/enums/index.d.ts +7 -15
  19. package/dist/enums/index.js +1 -9
  20. package/dist/enums/index.js.map +1 -1
  21. package/dist/{platform-auth-CvAYFVhK.d.cts → ic-DpKrdgQP.d.cts} +1 -78
  22. package/dist/{platform-auth-CvAYFVhK.d.ts → ic-DpKrdgQP.d.ts} +1 -78
  23. package/dist/index.cjs +899 -362
  24. package/dist/index.cjs.map +1 -1
  25. package/dist/index.d.cts +3 -1
  26. package/dist/index.d.ts +3 -1
  27. package/dist/index.js +893 -362
  28. package/dist/index.js.map +1 -1
  29. package/dist/platform-auth-B49Ly57B.d.cts +78 -0
  30. package/dist/platform-auth-B49Ly57B.d.ts +78 -0
  31. package/dist/types/index.d.cts +2 -2
  32. package/dist/types/index.d.ts +2 -2
  33. package/package.json +6 -1
  34. package/src/__sot__/README.md +3 -1
  35. package/src/__sot__/adminRoles.pin.json +122 -0
  36. package/src/__sot__/adminRoles.published.json +77 -0
  37. package/src/__sot__/coreFunctionFields.ts +16 -0
  38. package/src/__sot__/coreFunctions.pin.json +114 -1
  39. package/src/__sot__/roleFields.ts +137 -0
  40. package/src/__sot__/userRoles.pin.json +174 -0
  41. package/src/__sot__/userRoles.published.json +103 -0
  42. package/src/__tests__/__snapshots__/cvc-sot.snap +5 -5
  43. package/src/__tests__/admin-roles-canon.test.ts +80 -0
  44. package/src/__tests__/authz-resolve.test.ts +712 -0
  45. package/src/__tests__/core-functions-canon.test.ts +62 -12
  46. package/src/__tests__/cvc-sot-snapshot.test.ts +12 -4
  47. package/src/__tests__/cvc-status-parser.test.ts +1 -1
  48. package/src/__tests__/cvc-structural.test.ts +3 -3
  49. package/src/__tests__/role-vocab-gate.ts +279 -0
  50. package/src/__tests__/user-roles-canon.test.ts +104 -0
  51. package/src/authz/index.ts +9 -0
  52. package/src/authz/resolveEffectiveFunctions.ts +454 -0
  53. package/src/cvcs/adminRoles.v2.0.0.json +197 -0
  54. package/src/cvcs/{coreFunctions.v1.2.0.json → coreFunctions.v1.3.0.json} +357 -200
  55. package/src/cvcs/index.ts +3 -3
  56. package/src/cvcs/userRoles.v2.0.0.json +296 -0
  57. package/src/generated/coreFunctionsEvaluable.ts +101 -0
  58. package/src/generated/cvc-enums.ts +7 -15
  59. package/src/index.ts +4 -0
  60. package/src/cvcs/adminRoles.v1.0.0.json +0 -153
  61. package/src/cvcs/userRoles.v1.0.0.json +0 -203
@@ -0,0 +1,210 @@
1
+ import { j as PermissionStateValue } from '../platform-auth-B49Ly57B.cjs';
2
+
3
+ /**
4
+ * @htilabs/platform-common-models — the shared CVC-133 authorization resolver
5
+ *
6
+ * ONE pure function that every app (Thread · PAVE 2.0 · platform) calls to turn
7
+ * a seat's roles and the stored platform / agency / team policies into the set
8
+ * of CVC-133 function codes the seat may perform. No I/O and no mongoose: each
9
+ * app keeps only a loader that reads the platform-written collections and hands
10
+ * the rows in. Browser-safe entry: `@htilabs/platform-common-models/authz`.
11
+ *
12
+ * Spec: records repo (`htilabstech/prototype`) `KICKOFF_SHARED_AUTHZ_RESOLVER_2026-10-12.md`
13
+ * § 3 (the ruled model) and § 4.1 (this file). Line cites below are to the
14
+ * platform prototype (`htilabstech/platform-prototype` @ af10119)
15
+ * `src/agencyhub.jsx` `authzResolve` unless they name another file;
16
+ * `policyResolver.js` / `proxy/route.ts` cites are to `htilabstech/platform`
17
+ * develop @ ccf8da3.
18
+ *
19
+ * THE RULES (kickoff § 3 numbering)
20
+ *
21
+ * 1. Layers intersect and clamp downward: effective = platform ∩ agency ∩
22
+ * team (CAM, Notion 27f1ef14abcd8016accaca50780b2906; the devs' "3-Tier HTI
23
+ * Platform Permission Model", Notion 32c1ef14abcd80f0933ec66638bcc300:
24
+ * "The most restrictive applicable setting wins. Access is always clamped
25
+ * downward, never expanded upward"). Per role: the platform state (Tier 1)
26
+ * is the base; the agency may move an unlocked state (Tier 2,
27
+ * `agencyhub.jsx:601-624` — an account may switch a Default-Off function on
28
+ * or require it, or switch a Default-On one off); the team may only take a
29
+ * grant away (rule 4). The user-restriction, training, clearance, legal-basis
30
+ * and purpose layers (`:629-693`) are not inputs here (CAM layers the dev
31
+ * model has no data for yet, inventory resolvers.md D6).
32
+ * 2. Roles union at the user level; NEVER is local to its role. A function is
33
+ * granted when ANY assigned role's own cascade grants it; a role whose
34
+ * cascade ends at NEVER / Default-Off simply contributes nothing — it never
35
+ * vetoes another role's grant (`:566-589`, Crysta 2026-08-09 "grants are
36
+ * computed first"; restated 2026-10-12 "roles stack").
37
+ * 3. Required is immune to the team gate: a state that is ALWAYS after
38
+ * Tier 1 + Tier 2 (platform ALWAYS, or an agency that escalated the role to
39
+ * ALWAYS) is not team-gated (dev model: "locked" states skip Tier 3,
40
+ * `platform/lib/utils/policyResolver.js:58-72`; prototype `:625` "agency
41
+ * cannot disable"). NEVER at Tier 1 / Tier 2 is immune to a team lift —
42
+ * a Tier-1 ALWAYS / NEVER also ignores the agency layer
43
+ * (`policyResolver.js:46-48`). NOTE (kickoff § 5 trap): today's prototype
44
+ * still runs the team check for `required` (`:626-628`); "Required immune
45
+ * to the team gate" is the queued prototype ship. This resolver encodes the
46
+ * ruling, not the current prototype behaviour.
47
+ * 4. The team layer is RESTRICT-ONLY (`:626-628` "teams are workflow
48
+ * containers, never authority"; editor log lines `:1236` / `:4490` "it never
49
+ * grants"; UDD Team object, Notion 3ec1ef14abcd814385e4c4e84e071178: "If a
50
+ * team enables a function, but a user's role does not permit that function,
51
+ * the user does not gain access to it through team membership"). A team
52
+ * PREF_NO (or a NEVER, which the platform's own write path refuses from a
53
+ * team, `app/api/admin/proxy/route.ts:900`, but which is honoured
54
+ * fail-closed) takes the grant away; a team PREF_YES or ALWAYS is
55
+ * ignored — it never lifts a Default-Off or an agency switch-off. The
56
+ * policy's role-grain `roles[]` and flat `functions` maps are both team
57
+ * restrictions: either one switching a function off is enough.
58
+ * 5. One acting team per resolution: the seat's primary team (`team_id` =
59
+ * `team_ids[0]`, `setUserTeams` `:3228`; `authzForCurrentUser` passes the
60
+ * single `u.team_id`, `:734`), or a verified acting team the request
61
+ * carries (pave-2.0 team-scope precedence ADR, Notion
62
+ * 3921ef14abcd814ca839c1e7c3a57485). The caller resolves that ONE team's
63
+ * policy and passes it as `teamPolicy` — see `selectActingTeamId`. No team,
64
+ * or a team with no policy, is an explicit pass-through (ruling 3c, `:626`).
65
+ * 8. Unknown / retired / not-v1 functions are denied (`:556` "unknown function
66
+ * — deny by default", `:557` retired, `:558` not-v1) — decided by the canon
67
+ * this package ships, not by the caller's rows. The prototype checks its
68
+ * injected canon registry (`HTI_CORE_FUNCTIONS`, `:552-558`); here that is
69
+ * the CVC-133 SOT (`coreFunctions.v1.3.0.json`, whose `v1` / `retired`
70
+ * booleans are canon's own row flags), read through the slim generated key
71
+ * set `CORE_FUNCTIONS_EVALUABLE_KEYS` (v1 && !retired; GATE I asserts it
72
+ * equals the SOT) and intersected with `CoreFunctionsKeys`. No assigned
73
+ * roles, or none that resolve to a role row, yields the empty set.
74
+ *
75
+ * FAIL-CLOSED ON MALFORMED STORED DATA (ruled 2026-10-13, co-zo3 review and
76
+ * verification rounds). Every input is read defensively, so malformed data
77
+ * makes `resolveEffectiveFunctions` deny, never throw:
78
+ * - an `input` that is not an object, or a `roles` / `functions` /
79
+ * `assignedRoleCodes` that is not an array (null, a number, a string —
80
+ * never split into characters), resolves to `[]`;
81
+ * - a present state that is not one of the four PERMISSION_STATE values is
82
+ * NEVER at Tier 1, NEVER at Tier 2 (for that role), and a restriction at
83
+ * Tier 3; `undefined` and `null` mean "not set";
84
+ * - a state CONTAINER that is present but not a plain object (an array, a
85
+ * string, a Map, …) fails closed for everything it could govern: a role's
86
+ * `functions` → the role grants nothing; the agency's map, or one role's
87
+ * entry in it → NEVER for every unlocked state it covers; the team policy,
88
+ * its `functions`, or its `roles` list → every team-gated grant restricted;
89
+ * one role's `overrides` → that role's team-gated grants restricted;
90
+ * - a `teamPolicy.roles` entry that is not an object with a string `roleCode`
91
+ * cannot be attributed to a role, so it restricts every role's team-gated
92
+ * grants; duplicate entries for one role are unioned (any off wins);
93
+ * - a catalog row's `retired` keeps the function only when it is absent or
94
+ * exactly `false`;
95
+ * - Required (rule 3) stays immune to every team-side restriction.
96
+ *
97
+ * Rules 6 (app access is not a function) and 7 (vocabulary vs policy state)
98
+ * are about what the inputs are, not about this computation.
99
+ */
100
+
101
+ /** True when canon lets the resolver evaluate `code` at all (rule 8). */
102
+ declare function isCanonEvaluableFunction(code: string): boolean;
103
+ /** A map of function code → permission state, as the platform stores it. */
104
+ type AuthzStateMap = Readonly<Record<string, PermissionStateValue>>;
105
+ /**
106
+ * One `platformRoles` row (Tier 1): the role's platform state per function.
107
+ * A function the role does not list resolves to PREF_NO when it shares one of
108
+ * the role's tools, else NEVER (not applicable) — the rule all three dev
109
+ * resolvers use (`policyResolver.js:33-40`).
110
+ */
111
+ interface AuthzRoleRow {
112
+ readonly code: string;
113
+ readonly tools?: readonly string[];
114
+ readonly functions?: AuthzStateMap;
115
+ }
116
+ /**
117
+ * One `platformFunctions` row: the deployment's function catalog, which
118
+ * supplies each function's `tools` (the Tier-1 default above). It can only
119
+ * narrow canon, never widen it:
120
+ * - a code canon does not carry, or carries as not-v1 / retired, is denied
121
+ * even when it is listed here;
122
+ * - `retired` other than absent / exactly `false` denies a function canon
123
+ * still has (a deployment may stop offering one early);
124
+ * - a canon function missing from this list is denied (it has no catalog row).
125
+ * Any other stored field (e.g. `platformFunctions.status`) is not read: a stale
126
+ * "Future function (not v1)" status never denies a function canon says is v1.
127
+ */
128
+ interface AuthzFunctionRow {
129
+ readonly code: string;
130
+ readonly tools?: readonly string[];
131
+ readonly retired?: boolean;
132
+ }
133
+ /** One role-grain override entry, as stored in `teamAccessPolicies.roles[]`. */
134
+ interface AuthzRoleOverrides {
135
+ readonly roleCode: string;
136
+ readonly overrides?: AuthzStateMap;
137
+ }
138
+ /**
139
+ * The ONE acting team's `teamAccessPolicies` document (rule 5). `roles[]`
140
+ * narrows one role; `functions` narrows every role. Both only restrict, so a
141
+ * function is off for a role when any of them says so.
142
+ */
143
+ interface AuthzTeamPolicy {
144
+ readonly roles?: readonly AuthzRoleOverrides[];
145
+ readonly functions?: AuthzStateMap;
146
+ }
147
+ interface ResolveEffectiveFunctionsInput {
148
+ /** Every `platformRoles` row the seat might hold (extra rows are ignored). */
149
+ readonly roles: readonly AuthzRoleRow[];
150
+ /** The deployment's function catalog (`platformFunctions`), narrowed by canon. */
151
+ readonly functions: readonly AuthzFunctionRow[];
152
+ /** The seat's assigned role codes. */
153
+ readonly assignedRoleCodes: readonly string[];
154
+ /** Tier 2 — the agency's overrides, `{ roleCode → { functionCode → state } }`. */
155
+ readonly agencyOverrides?: Readonly<Record<string, AuthzStateMap>>;
156
+ /** Tier 3 — the acting team's policy; absent / null = pass-through. */
157
+ readonly teamPolicy?: AuthzTeamPolicy | null;
158
+ /** Declared, not configurable: an unknown function is always denied (rule 8). */
159
+ readonly unknownFunctionPolicy: "deny";
160
+ }
161
+ /**
162
+ * Resolve the CVC-133 function codes a seat may perform.
163
+ *
164
+ * @returns sorted, de-duplicated function codes; `[]` when nothing resolves,
165
+ * including when `input` is not an object or `roles`, `functions` or
166
+ * `assignedRoleCodes` is not an array (never a throw; a string is
167
+ * never iterated as characters).
168
+ */
169
+ declare function resolveEffectiveFunctions(input: ResolveEffectiveFunctionsInput): string[];
170
+ /**
171
+ * Pick the ONE team whose policy feeds `teamPolicy`.
172
+ *
173
+ * - `verifiedActingTeamId` given → that team, as is. VERIFYING it is the
174
+ * caller's job: each app has its own membership source (pave-2.0 checks
175
+ * `teams.members[]` through its membership checker; `users.teams` is not kept
176
+ * in step with it), so this helper does not second-guess the caller against
177
+ * `seatTeamIds`. Pass only a team the caller has confirmed the seat sits on.
178
+ * - otherwise → the primary team, `seatTeamIds[0]`;
179
+ * - no teams → `null` (pass-through).
180
+ */
181
+ declare function selectActingTeamId(seatTeamIds: readonly string[], verifiedActingTeamId?: string | null): string | null;
182
+ /** Level 0 is derived (no level function resolves), never a configurable rung. */
183
+ type ViewingLevel = 0 | 1 | 2 | 3;
184
+ /** The three Type-A viewing functions, highest first. */
185
+ declare const VIEWING_LEVEL_FUNCTIONS: readonly [readonly ["viewing_level_3_components", 3], readonly ["viewing_level_2_autocomplete", 2], readonly ["viewing_level_1_search", 1]];
186
+ /**
187
+ * The effective internal viewing level from an already-resolved function set.
188
+ *
189
+ * Canon (CVC-133 `viewing_level_3_components` logic_notes, records
190
+ * `data/cvcs/core_functions.yaml` @ f4356aa4): "Effective viewing level = the
191
+ * highest of the three level functions the user's roles resolve to … clamped by
192
+ * the team-set level — most restrictive wins; the team axis clamps down, never
193
+ * up. … Absence of all three functions = Level 0 (not a configurable setting)."
194
+ *
195
+ * `teamViewingLevel` is the level the account's viewing policy sets for the
196
+ * acting team — the team's own row, else the account-wide rule (prototype
197
+ * `src/screens.jsx:14671` `effLevel`, `:14819` "a member's own role can only
198
+ * narrow it further"). Absent / null = no team-set level, so no clamp.
199
+ *
200
+ * Own / claimed cases are always fully visible; that is the caller's
201
+ * record-level check, not this function's.
202
+ */
203
+ declare function viewingLevelFromFunctions(effectiveFunctions: Iterable<string>, teamViewingLevel?: ViewingLevel | null): ViewingLevel;
204
+ /**
205
+ * Resolve the seat's functions (same input, same rules as
206
+ * `resolveEffectiveFunctions`) and return its effective internal viewing level.
207
+ */
208
+ declare function resolveEffectiveViewingLevel(input: ResolveEffectiveFunctionsInput, teamViewingLevel?: ViewingLevel | null): ViewingLevel;
209
+
210
+ export { type AuthzFunctionRow, type AuthzRoleOverrides, type AuthzRoleRow, type AuthzStateMap, type AuthzTeamPolicy, type ResolveEffectiveFunctionsInput, VIEWING_LEVEL_FUNCTIONS, type ViewingLevel, isCanonEvaluableFunction, resolveEffectiveFunctions, resolveEffectiveViewingLevel, selectActingTeamId, viewingLevelFromFunctions };
@@ -0,0 +1,210 @@
1
+ import { j as PermissionStateValue } from '../platform-auth-B49Ly57B.js';
2
+
3
+ /**
4
+ * @htilabs/platform-common-models — the shared CVC-133 authorization resolver
5
+ *
6
+ * ONE pure function that every app (Thread · PAVE 2.0 · platform) calls to turn
7
+ * a seat's roles and the stored platform / agency / team policies into the set
8
+ * of CVC-133 function codes the seat may perform. No I/O and no mongoose: each
9
+ * app keeps only a loader that reads the platform-written collections and hands
10
+ * the rows in. Browser-safe entry: `@htilabs/platform-common-models/authz`.
11
+ *
12
+ * Spec: records repo (`htilabstech/prototype`) `KICKOFF_SHARED_AUTHZ_RESOLVER_2026-10-12.md`
13
+ * § 3 (the ruled model) and § 4.1 (this file). Line cites below are to the
14
+ * platform prototype (`htilabstech/platform-prototype` @ af10119)
15
+ * `src/agencyhub.jsx` `authzResolve` unless they name another file;
16
+ * `policyResolver.js` / `proxy/route.ts` cites are to `htilabstech/platform`
17
+ * develop @ ccf8da3.
18
+ *
19
+ * THE RULES (kickoff § 3 numbering)
20
+ *
21
+ * 1. Layers intersect and clamp downward: effective = platform ∩ agency ∩
22
+ * team (CAM, Notion 27f1ef14abcd8016accaca50780b2906; the devs' "3-Tier HTI
23
+ * Platform Permission Model", Notion 32c1ef14abcd80f0933ec66638bcc300:
24
+ * "The most restrictive applicable setting wins. Access is always clamped
25
+ * downward, never expanded upward"). Per role: the platform state (Tier 1)
26
+ * is the base; the agency may move an unlocked state (Tier 2,
27
+ * `agencyhub.jsx:601-624` — an account may switch a Default-Off function on
28
+ * or require it, or switch a Default-On one off); the team may only take a
29
+ * grant away (rule 4). The user-restriction, training, clearance, legal-basis
30
+ * and purpose layers (`:629-693`) are not inputs here (CAM layers the dev
31
+ * model has no data for yet, inventory resolvers.md D6).
32
+ * 2. Roles union at the user level; NEVER is local to its role. A function is
33
+ * granted when ANY assigned role's own cascade grants it; a role whose
34
+ * cascade ends at NEVER / Default-Off simply contributes nothing — it never
35
+ * vetoes another role's grant (`:566-589`, Crysta 2026-08-09 "grants are
36
+ * computed first"; restated 2026-10-12 "roles stack").
37
+ * 3. Required is immune to the team gate: a state that is ALWAYS after
38
+ * Tier 1 + Tier 2 (platform ALWAYS, or an agency that escalated the role to
39
+ * ALWAYS) is not team-gated (dev model: "locked" states skip Tier 3,
40
+ * `platform/lib/utils/policyResolver.js:58-72`; prototype `:625` "agency
41
+ * cannot disable"). NEVER at Tier 1 / Tier 2 is immune to a team lift —
42
+ * a Tier-1 ALWAYS / NEVER also ignores the agency layer
43
+ * (`policyResolver.js:46-48`). NOTE (kickoff § 5 trap): today's prototype
44
+ * still runs the team check for `required` (`:626-628`); "Required immune
45
+ * to the team gate" is the queued prototype ship. This resolver encodes the
46
+ * ruling, not the current prototype behaviour.
47
+ * 4. The team layer is RESTRICT-ONLY (`:626-628` "teams are workflow
48
+ * containers, never authority"; editor log lines `:1236` / `:4490` "it never
49
+ * grants"; UDD Team object, Notion 3ec1ef14abcd814385e4c4e84e071178: "If a
50
+ * team enables a function, but a user's role does not permit that function,
51
+ * the user does not gain access to it through team membership"). A team
52
+ * PREF_NO (or a NEVER, which the platform's own write path refuses from a
53
+ * team, `app/api/admin/proxy/route.ts:900`, but which is honoured
54
+ * fail-closed) takes the grant away; a team PREF_YES or ALWAYS is
55
+ * ignored — it never lifts a Default-Off or an agency switch-off. The
56
+ * policy's role-grain `roles[]` and flat `functions` maps are both team
57
+ * restrictions: either one switching a function off is enough.
58
+ * 5. One acting team per resolution: the seat's primary team (`team_id` =
59
+ * `team_ids[0]`, `setUserTeams` `:3228`; `authzForCurrentUser` passes the
60
+ * single `u.team_id`, `:734`), or a verified acting team the request
61
+ * carries (pave-2.0 team-scope precedence ADR, Notion
62
+ * 3921ef14abcd814ca839c1e7c3a57485). The caller resolves that ONE team's
63
+ * policy and passes it as `teamPolicy` — see `selectActingTeamId`. No team,
64
+ * or a team with no policy, is an explicit pass-through (ruling 3c, `:626`).
65
+ * 8. Unknown / retired / not-v1 functions are denied (`:556` "unknown function
66
+ * — deny by default", `:557` retired, `:558` not-v1) — decided by the canon
67
+ * this package ships, not by the caller's rows. The prototype checks its
68
+ * injected canon registry (`HTI_CORE_FUNCTIONS`, `:552-558`); here that is
69
+ * the CVC-133 SOT (`coreFunctions.v1.3.0.json`, whose `v1` / `retired`
70
+ * booleans are canon's own row flags), read through the slim generated key
71
+ * set `CORE_FUNCTIONS_EVALUABLE_KEYS` (v1 && !retired; GATE I asserts it
72
+ * equals the SOT) and intersected with `CoreFunctionsKeys`. No assigned
73
+ * roles, or none that resolve to a role row, yields the empty set.
74
+ *
75
+ * FAIL-CLOSED ON MALFORMED STORED DATA (ruled 2026-10-13, co-zo3 review and
76
+ * verification rounds). Every input is read defensively, so malformed data
77
+ * makes `resolveEffectiveFunctions` deny, never throw:
78
+ * - an `input` that is not an object, or a `roles` / `functions` /
79
+ * `assignedRoleCodes` that is not an array (null, a number, a string —
80
+ * never split into characters), resolves to `[]`;
81
+ * - a present state that is not one of the four PERMISSION_STATE values is
82
+ * NEVER at Tier 1, NEVER at Tier 2 (for that role), and a restriction at
83
+ * Tier 3; `undefined` and `null` mean "not set";
84
+ * - a state CONTAINER that is present but not a plain object (an array, a
85
+ * string, a Map, …) fails closed for everything it could govern: a role's
86
+ * `functions` → the role grants nothing; the agency's map, or one role's
87
+ * entry in it → NEVER for every unlocked state it covers; the team policy,
88
+ * its `functions`, or its `roles` list → every team-gated grant restricted;
89
+ * one role's `overrides` → that role's team-gated grants restricted;
90
+ * - a `teamPolicy.roles` entry that is not an object with a string `roleCode`
91
+ * cannot be attributed to a role, so it restricts every role's team-gated
92
+ * grants; duplicate entries for one role are unioned (any off wins);
93
+ * - a catalog row's `retired` keeps the function only when it is absent or
94
+ * exactly `false`;
95
+ * - Required (rule 3) stays immune to every team-side restriction.
96
+ *
97
+ * Rules 6 (app access is not a function) and 7 (vocabulary vs policy state)
98
+ * are about what the inputs are, not about this computation.
99
+ */
100
+
101
+ /** True when canon lets the resolver evaluate `code` at all (rule 8). */
102
+ declare function isCanonEvaluableFunction(code: string): boolean;
103
+ /** A map of function code → permission state, as the platform stores it. */
104
+ type AuthzStateMap = Readonly<Record<string, PermissionStateValue>>;
105
+ /**
106
+ * One `platformRoles` row (Tier 1): the role's platform state per function.
107
+ * A function the role does not list resolves to PREF_NO when it shares one of
108
+ * the role's tools, else NEVER (not applicable) — the rule all three dev
109
+ * resolvers use (`policyResolver.js:33-40`).
110
+ */
111
+ interface AuthzRoleRow {
112
+ readonly code: string;
113
+ readonly tools?: readonly string[];
114
+ readonly functions?: AuthzStateMap;
115
+ }
116
+ /**
117
+ * One `platformFunctions` row: the deployment's function catalog, which
118
+ * supplies each function's `tools` (the Tier-1 default above). It can only
119
+ * narrow canon, never widen it:
120
+ * - a code canon does not carry, or carries as not-v1 / retired, is denied
121
+ * even when it is listed here;
122
+ * - `retired` other than absent / exactly `false` denies a function canon
123
+ * still has (a deployment may stop offering one early);
124
+ * - a canon function missing from this list is denied (it has no catalog row).
125
+ * Any other stored field (e.g. `platformFunctions.status`) is not read: a stale
126
+ * "Future function (not v1)" status never denies a function canon says is v1.
127
+ */
128
+ interface AuthzFunctionRow {
129
+ readonly code: string;
130
+ readonly tools?: readonly string[];
131
+ readonly retired?: boolean;
132
+ }
133
+ /** One role-grain override entry, as stored in `teamAccessPolicies.roles[]`. */
134
+ interface AuthzRoleOverrides {
135
+ readonly roleCode: string;
136
+ readonly overrides?: AuthzStateMap;
137
+ }
138
+ /**
139
+ * The ONE acting team's `teamAccessPolicies` document (rule 5). `roles[]`
140
+ * narrows one role; `functions` narrows every role. Both only restrict, so a
141
+ * function is off for a role when any of them says so.
142
+ */
143
+ interface AuthzTeamPolicy {
144
+ readonly roles?: readonly AuthzRoleOverrides[];
145
+ readonly functions?: AuthzStateMap;
146
+ }
147
+ interface ResolveEffectiveFunctionsInput {
148
+ /** Every `platformRoles` row the seat might hold (extra rows are ignored). */
149
+ readonly roles: readonly AuthzRoleRow[];
150
+ /** The deployment's function catalog (`platformFunctions`), narrowed by canon. */
151
+ readonly functions: readonly AuthzFunctionRow[];
152
+ /** The seat's assigned role codes. */
153
+ readonly assignedRoleCodes: readonly string[];
154
+ /** Tier 2 — the agency's overrides, `{ roleCode → { functionCode → state } }`. */
155
+ readonly agencyOverrides?: Readonly<Record<string, AuthzStateMap>>;
156
+ /** Tier 3 — the acting team's policy; absent / null = pass-through. */
157
+ readonly teamPolicy?: AuthzTeamPolicy | null;
158
+ /** Declared, not configurable: an unknown function is always denied (rule 8). */
159
+ readonly unknownFunctionPolicy: "deny";
160
+ }
161
+ /**
162
+ * Resolve the CVC-133 function codes a seat may perform.
163
+ *
164
+ * @returns sorted, de-duplicated function codes; `[]` when nothing resolves,
165
+ * including when `input` is not an object or `roles`, `functions` or
166
+ * `assignedRoleCodes` is not an array (never a throw; a string is
167
+ * never iterated as characters).
168
+ */
169
+ declare function resolveEffectiveFunctions(input: ResolveEffectiveFunctionsInput): string[];
170
+ /**
171
+ * Pick the ONE team whose policy feeds `teamPolicy`.
172
+ *
173
+ * - `verifiedActingTeamId` given → that team, as is. VERIFYING it is the
174
+ * caller's job: each app has its own membership source (pave-2.0 checks
175
+ * `teams.members[]` through its membership checker; `users.teams` is not kept
176
+ * in step with it), so this helper does not second-guess the caller against
177
+ * `seatTeamIds`. Pass only a team the caller has confirmed the seat sits on.
178
+ * - otherwise → the primary team, `seatTeamIds[0]`;
179
+ * - no teams → `null` (pass-through).
180
+ */
181
+ declare function selectActingTeamId(seatTeamIds: readonly string[], verifiedActingTeamId?: string | null): string | null;
182
+ /** Level 0 is derived (no level function resolves), never a configurable rung. */
183
+ type ViewingLevel = 0 | 1 | 2 | 3;
184
+ /** The three Type-A viewing functions, highest first. */
185
+ declare const VIEWING_LEVEL_FUNCTIONS: readonly [readonly ["viewing_level_3_components", 3], readonly ["viewing_level_2_autocomplete", 2], readonly ["viewing_level_1_search", 1]];
186
+ /**
187
+ * The effective internal viewing level from an already-resolved function set.
188
+ *
189
+ * Canon (CVC-133 `viewing_level_3_components` logic_notes, records
190
+ * `data/cvcs/core_functions.yaml` @ f4356aa4): "Effective viewing level = the
191
+ * highest of the three level functions the user's roles resolve to … clamped by
192
+ * the team-set level — most restrictive wins; the team axis clamps down, never
193
+ * up. … Absence of all three functions = Level 0 (not a configurable setting)."
194
+ *
195
+ * `teamViewingLevel` is the level the account's viewing policy sets for the
196
+ * acting team — the team's own row, else the account-wide rule (prototype
197
+ * `src/screens.jsx:14671` `effLevel`, `:14819` "a member's own role can only
198
+ * narrow it further"). Absent / null = no team-set level, so no clamp.
199
+ *
200
+ * Own / claimed cases are always fully visible; that is the caller's
201
+ * record-level check, not this function's.
202
+ */
203
+ declare function viewingLevelFromFunctions(effectiveFunctions: Iterable<string>, teamViewingLevel?: ViewingLevel | null): ViewingLevel;
204
+ /**
205
+ * Resolve the seat's functions (same input, same rules as
206
+ * `resolveEffectiveFunctions`) and return its effective internal viewing level.
207
+ */
208
+ declare function resolveEffectiveViewingLevel(input: ResolveEffectiveFunctionsInput, teamViewingLevel?: ViewingLevel | null): ViewingLevel;
209
+
210
+ export { type AuthzFunctionRow, type AuthzRoleOverrides, type AuthzRoleRow, type AuthzStateMap, type AuthzTeamPolicy, type ResolveEffectiveFunctionsInput, VIEWING_LEVEL_FUNCTIONS, type ViewingLevel, isCanonEvaluableFunction, resolveEffectiveFunctions, resolveEffectiveViewingLevel, selectActingTeamId, viewingLevelFromFunctions };