@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.
- package/dist/authz/index.cjs +539 -0
- package/dist/authz/index.cjs.map +1 -0
- package/dist/authz/index.d.cts +210 -0
- package/dist/authz/index.d.ts +210 -0
- package/dist/authz/index.js +507 -0
- package/dist/authz/index.js.map +1 -0
- package/dist/constants/index.d.cts +2 -1
- package/dist/constants/index.d.ts +2 -1
- package/dist/cvcs/index.cjs +647 -353
- package/dist/cvcs/index.cjs.map +1 -1
- package/dist/cvcs/index.d.cts +658 -362
- package/dist/cvcs/index.d.ts +658 -362
- package/dist/cvcs/index.js +647 -353
- package/dist/cvcs/index.js.map +1 -1
- package/dist/enums/index.cjs +1 -9
- package/dist/enums/index.cjs.map +1 -1
- package/dist/enums/index.d.cts +7 -15
- package/dist/enums/index.d.ts +7 -15
- package/dist/enums/index.js +1 -9
- package/dist/enums/index.js.map +1 -1
- package/dist/{platform-auth-CvAYFVhK.d.cts → ic-DpKrdgQP.d.cts} +1 -78
- package/dist/{platform-auth-CvAYFVhK.d.ts → ic-DpKrdgQP.d.ts} +1 -78
- package/dist/index.cjs +899 -362
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +3 -1
- package/dist/index.d.ts +3 -1
- package/dist/index.js +893 -362
- package/dist/index.js.map +1 -1
- package/dist/platform-auth-B49Ly57B.d.cts +78 -0
- package/dist/platform-auth-B49Ly57B.d.ts +78 -0
- package/dist/types/index.d.cts +2 -2
- package/dist/types/index.d.ts +2 -2
- package/package.json +6 -1
- package/src/__sot__/README.md +3 -1
- package/src/__sot__/adminRoles.pin.json +122 -0
- package/src/__sot__/adminRoles.published.json +77 -0
- package/src/__sot__/coreFunctionFields.ts +16 -0
- package/src/__sot__/coreFunctions.pin.json +114 -1
- package/src/__sot__/roleFields.ts +137 -0
- package/src/__sot__/userRoles.pin.json +174 -0
- package/src/__sot__/userRoles.published.json +103 -0
- package/src/__tests__/__snapshots__/cvc-sot.snap +5 -5
- package/src/__tests__/admin-roles-canon.test.ts +80 -0
- package/src/__tests__/authz-resolve.test.ts +712 -0
- package/src/__tests__/core-functions-canon.test.ts +62 -12
- package/src/__tests__/cvc-sot-snapshot.test.ts +12 -4
- package/src/__tests__/cvc-status-parser.test.ts +1 -1
- package/src/__tests__/cvc-structural.test.ts +3 -3
- package/src/__tests__/role-vocab-gate.ts +279 -0
- package/src/__tests__/user-roles-canon.test.ts +104 -0
- package/src/authz/index.ts +9 -0
- package/src/authz/resolveEffectiveFunctions.ts +454 -0
- package/src/cvcs/adminRoles.v2.0.0.json +197 -0
- package/src/cvcs/{coreFunctions.v1.2.0.json → coreFunctions.v1.3.0.json} +357 -200
- package/src/cvcs/index.ts +3 -3
- package/src/cvcs/userRoles.v2.0.0.json +296 -0
- package/src/generated/coreFunctionsEvaluable.ts +101 -0
- package/src/generated/cvc-enums.ts +7 -15
- package/src/index.ts +4 -0
- package/src/cvcs/adminRoles.v1.0.0.json +0 -153
- 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 };
|