@htilabs/platform-common-models 0.79.0 → 0.80.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.
@@ -0,0 +1,304 @@
1
+ /**
2
+ * @htilabs/platform-common-models/authz — a seat's app access
3
+ *
4
+ * The ONE answer to "may this person open this app?", shared by Thread's and
5
+ * PAVE's sign-in doors and the platform's app tiles so the three never give
6
+ * different answers. Pure TypeScript: no mongoose, no I/O. The caller reads
7
+ * the seat's teams and the account from its own database and passes them in.
8
+ *
9
+ * ## Canon (Crysta's rulings)
10
+ *
11
+ * - 2026-10-02: "Contract grants apps to the Account, users gain access via
12
+ * teams" (UDD Team Data Object § 2 scenario 1; Account Data Object § 2).
13
+ * - 2026-08-20, Ruling 1: "a user's app access should always be derivable
14
+ * from the union of teams they belong to" (records repo
15
+ * `tools/build_platform_directory.py`, TEAM-APP-ACCESS).
16
+ * - 2026-08-20, Ruling 2: Echo + Trail are granted to "everyone with an
17
+ * account". They are not team-scoped, never appear in a team's apps, and
18
+ * are added at the USER grain only ("an active user of any account gets
19
+ * them"). Same generator; the prototype's user grain adds them to every
20
+ * user (`HTI_appsForUser`, platform-prototype `src/data.js`).
21
+ * - 2026-08-31 (Terry login), TRAIL-ONLY PRE-LAUNCH: a seat whose account is
22
+ * not launched yet reaches Trail only — no casework app and no Echo
23
+ * (`HTI_preLaunchAccountFor`, platform-prototype `src/data.js`).
24
+ * - 2026-10-18: "the team object is where app access is gained".
25
+ * - 2026-10-02 (ORG-ROW-IDENTITY-ONLY-2026-10-08): apps live at the account,
26
+ * the team and the user, never the organization. This function reads no
27
+ * organization or agency apps.
28
+ * - 2026-11-12: HTI loads the account's apps; HTI or account admins put app
29
+ * access on a team, inside that grant; users reach apps through the teams
30
+ * they are on.
31
+ *
32
+ * ## The rule
33
+ *
34
+ * platform side (`teamAllows`):
35
+ * - account not launched (`accountPreLaunch`): Trail only;
36
+ * - Echo, Trail: every seat (Ruling 2), whatever its teams or the grant;
37
+ * - Thread, PAVE, LEADS: some ACTIVE team of the seat carries the app,
38
+ * AND the account grants it when the account grant is known.
39
+ * allowed = auth0Allows OR platform side.
40
+ *
41
+ * ## Where this differs from the prototype's user grain (`HTI_appsForUser`)
42
+ *
43
+ * 1. The Auth0 OR — the TRANSITION. The prototype answers from the teams
44
+ * alone. Production teams are not yet trustworthy (on 2026-10-08 all 64
45
+ * platform-prod teams read `apps: ["PAVE"]`, platform
46
+ * `docs/TEAM_APPS_FIELD.md`), so on day one the answer is ADDITIVE: the
47
+ * app's existing Auth0 decision still lets a person in and the teams can
48
+ * only add access. `via` names which side answered, so the apps can
49
+ * report every seat where the two disagree. When Crysta says the Auth0
50
+ * role stops counting, callers pass `auth0Allows: false` (or this OR is
51
+ * removed). The OR also reaches the pre-launch rule: during the
52
+ * transition an Auth0 yes admits a seat of an account that is not
53
+ * launched yet, where the prototype allows Trail only.
54
+ * 2. An inactive team grants nothing (Crysta 2026-11-12). The prototype's
55
+ * user grain counts every team on the seat; it is being updated to match
56
+ * (platform-prototype `fix/k08c-inactive-team-no-apps`).
57
+ * 3. The account ceiling (Crysta 2026-11-12: teams are set inside the apps
58
+ * HTI granted the account). The prototype's user grain applies none; with
59
+ * the grant unknown this function applies none either.
60
+ *
61
+ * ## What stays with the caller
62
+ *
63
+ * - Which seats are asked about: active seats only. Ruling 2 gives Echo and
64
+ * Trail to "an active user of any account"; a deactivated seat is refused
65
+ * before this function is called.
66
+ * - The Auth0 decision, as a boolean. Which `allowed_apps` values count is
67
+ * per app and per tier (Thread `config/runtime/api.yaml` THREAD_APP_KEYS:
68
+ * `thread,thread_test` on dev, `thread,thread_train` on train; PAVE
69
+ * `apps/api/src/plugins/auth.ts` `appAccessKeys`), so it is not decided
70
+ * here.
71
+ * - Which teams are ACTIVE. Stored team status differs by app (Thread's
72
+ * numeric `status`, the registry's `active` boolean); the caller sets
73
+ * `active: false` on a retired team. `active` absent or `null` counts as
74
+ * active.
75
+ * - The account grant: the account's `apps_subscribed`, "Apps the contract
76
+ * grants" (UDD Account Data Object; hti-features Account.v1; records
77
+ * `HTI_ACCOUNT_DIRECTORY.csv`), the list HTI sets. Read it with
78
+ * {@link accountAppGrant}. Never pass a list derived from the teams, and
79
+ * never the legacy `accounts.apps` the PAVE sync writes; pass `null`
80
+ * ("not known") instead. (`apps_declared` was a 2026-10-18 records-
81
+ * generator artifact, now retired; it is not read.)
82
+ * - Whether the account is launched. The caller sets `accountPreLaunch` when
83
+ * the account's `member_status` is `prospective` or `onboarding`.
84
+ *
85
+ * ## Reading stored app lists
86
+ *
87
+ * A team's or account's apps are read as a list (a bare string counts as a
88
+ * one-item list), each value trimmed and matched case-insensitively against
89
+ * the five platform apps: production stores `"PAVE"` (PLATFORM_TOOL codes on
90
+ * `teams.apps`), canon stores `"pave"` (`apps_used`). Values that name no
91
+ * platform app (`"PLATFORM"`, `"thread_test"`, `""`), and a stored value that
92
+ * is neither a list nor a string, are dropped and listed in `unrecognized`; a
93
+ * tier-suffixed Auth0 role name is never an app here.
94
+ */
95
+
96
+ import {
97
+ CASEWORK_APP_IDS,
98
+ PLATFORM_APP_IDS,
99
+ UNIVERSAL_APP_IDS,
100
+ platformAppById,
101
+ type PlatformAppId,
102
+ } from "../constants/platform-apps.js";
103
+ import type { PlatformToolValue } from "../constants/platform-auth.js";
104
+
105
+ /** One of the seat's teams, as the caller read it. */
106
+ export interface SeatAppAccessTeam {
107
+ /**
108
+ * The apps the team carries: production `teams.apps` (`["PAVE"]`) or
109
+ * canon's `apps_used` (`["pave"]`). Any case; a bare string is one app.
110
+ */
111
+ readonly apps?: unknown;
112
+ /** `false` for a retired or inactive team, which grants nothing. Absent or `null` counts as active. */
113
+ readonly active?: boolean | null;
114
+ }
115
+
116
+ export interface SeatAppAccessInput {
117
+ /** The app being asked about: `"THREAD"`, `"thread"`, `"Thread"` all mean Thread. */
118
+ readonly app: unknown;
119
+ /** The app's own Auth0 decision (`allowed_apps` against its accepted keys for this tier). */
120
+ readonly auth0Allows: boolean;
121
+ /** The seat's teams. Absent, empty or not a list: the seat is on no team. */
122
+ readonly teams?: readonly (SeatAppAccessTeam | null | undefined)[] | null;
123
+ /**
124
+ * The apps HTI granted the account — its `apps_subscribed`, read with
125
+ * {@link accountAppGrant}. The ceiling a team cannot
126
+ * exceed. `null` / `undefined`: not known, so no ceiling applies. A list,
127
+ * even empty, is a known grant. A value that is neither a list nor a string
128
+ * is read as a known grant of nothing and reported in `unrecognized`. Echo
129
+ * and Trail are never limited by it (Ruling 2).
130
+ */
131
+ readonly accountGrant?: unknown;
132
+ /** True when the seat's account is not launched yet (`member_status` prospective / onboarding): Trail only. */
133
+ readonly accountPreLaunch?: boolean | null;
134
+ }
135
+
136
+ /** Which side let the person in: the app's Auth0 decision, the platform side (teams and account), both, or neither. */
137
+ export type SeatAppAccessVia = "auth0" | "teams" | "both" | "none";
138
+
139
+ export interface SeatAppAccessResult {
140
+ /** May the seat open the app. */
141
+ readonly allowed: boolean;
142
+ /** Which side answered yes. `teams` means the platform side: the seat's teams, its account, Ruling 2. */
143
+ readonly via: SeatAppAccessVia;
144
+ /** The app asked about as a PLATFORM_TOOL code (`"THREAD"`), or null when it names no platform app. */
145
+ readonly app: PlatformToolValue | null;
146
+ /** The platform side's answer for this app. */
147
+ readonly teamAllows: boolean;
148
+ /** Every app the platform side grants the seat (universal apps included), in canonical order. */
149
+ readonly teamApps: readonly PlatformToolValue[];
150
+ /** The union of the seat's active teams' apps before the account ceiling, in canonical order. */
151
+ readonly teamUnion: readonly PlatformToolValue[];
152
+ /** The account grant as read, in canonical order; null when not known. */
153
+ readonly accountGrant: readonly PlatformToolValue[] | null;
154
+ /** Stored app values on the teams or the account that name no platform app, as written. */
155
+ readonly unrecognized: readonly string[];
156
+ }
157
+
158
+ const UNIVERSAL = new Set<PlatformAppId>(UNIVERSAL_APP_IDS);
159
+ const TRAIL: PlatformAppId = "trail";
160
+
161
+ /** The PLATFORM_TOOL code (`"THREAD"`) for a platform app id (`"thread"`). */
162
+ function toolCode(id: PlatformAppId): PlatformToolValue {
163
+ return id.toUpperCase() as PlatformToolValue;
164
+ }
165
+
166
+ /** A value as written, for the `unrecognized` report. */
167
+ function asWritten(v: unknown): string {
168
+ if (typeof v === "string") return v;
169
+ try {
170
+ const json = JSON.stringify(v);
171
+ return json === undefined ? String(v) : json;
172
+ } catch {
173
+ return String(v);
174
+ }
175
+ }
176
+
177
+ /**
178
+ * A stored app list as a list: a bare string is one value; `null` /
179
+ * `undefined` is none; anything else is none and reported.
180
+ */
181
+ function listOf(value: unknown, unrecognized: string[]): readonly unknown[] {
182
+ if (value === null || value === undefined) return [];
183
+ if (typeof value === "string") return [value];
184
+ if (Array.isArray(value)) return value;
185
+ unrecognized.push(asWritten(value));
186
+ return [];
187
+ }
188
+
189
+ /** Read a stored app list into platform app ids, collecting what names no app. */
190
+ function readApps(value: unknown, unrecognized: string[]): Set<PlatformAppId> {
191
+ const out = new Set<PlatformAppId>();
192
+ for (const v of listOf(value, unrecognized)) {
193
+ const app = platformAppById(v);
194
+ if (app) out.add(app.id);
195
+ else unrecognized.push(asWritten(v));
196
+ }
197
+ return out;
198
+ }
199
+
200
+ /** Ids in the canonical order (Trail, Thread, PAVE, LEADS, Echo) as PLATFORM_TOOL codes. */
201
+ function ordered(ids: ReadonlySet<PlatformAppId>): PlatformToolValue[] {
202
+ return PLATFORM_APP_IDS.filter((id) => ids.has(id)).map(toolCode);
203
+ }
204
+
205
+ /** The account grant: null when not known, else the apps it grants. */
206
+ function readGrant(value: unknown, unrecognized: string[]): Set<PlatformAppId> | null {
207
+ if (value === null || value === undefined) return null;
208
+ return readApps(value, unrecognized);
209
+ }
210
+
211
+ /**
212
+ * The account grant to pass as `accountGrant`: the account's
213
+ * `apps_subscribed`, "Apps the contract grants" (UDD Account Data Object;
214
+ * hti-features Account.v1), the list HTI sets. Returns `null` when it is
215
+ * absent, or for no account. Reads nothing else: never `apps_declared` (a
216
+ * retired generator artifact) and never the legacy `apps` field.
217
+ */
218
+ export function accountAppGrant(
219
+ account: { readonly apps_subscribed?: unknown } | null | undefined,
220
+ ): unknown {
221
+ if (!account || typeof account !== "object") return null;
222
+ const grant = account.apps_subscribed;
223
+ return grant === null || grant === undefined ? null : grant;
224
+ }
225
+
226
+ interface TeamSide {
227
+ readonly granted: Set<PlatformAppId>;
228
+ readonly union: Set<PlatformAppId>;
229
+ readonly grant: Set<PlatformAppId> | null;
230
+ readonly unrecognized: string[];
231
+ }
232
+
233
+ function teamSide(
234
+ teams: unknown,
235
+ accountGrant: unknown,
236
+ accountPreLaunch: unknown,
237
+ ): TeamSide {
238
+ const unrecognized: string[] = [];
239
+ const grant = readGrant(accountGrant, unrecognized);
240
+ const union = new Set<PlatformAppId>();
241
+ for (const team of Array.isArray(teams) ? (teams as unknown[]) : []) {
242
+ if (!team || typeof team !== "object") continue;
243
+ const t = team as SeatAppAccessTeam;
244
+ if (t.active === false) continue;
245
+ for (const id of readApps(t.apps, unrecognized)) union.add(id);
246
+ }
247
+ const granted = new Set<PlatformAppId>();
248
+ if (accountPreLaunch === true) {
249
+ // TRAIL-ONLY PRE-LAUNCH: no casework app, no Echo, until launch.
250
+ granted.add(TRAIL);
251
+ return { granted, union, grant, unrecognized };
252
+ }
253
+ // Universal apps (Echo, Trail): every seat, whatever its teams or the grant (Ruling 2).
254
+ for (const id of UNIVERSAL) granted.add(id);
255
+ // Casework apps: carried by an active team, inside the account's grant when it is known.
256
+ for (const id of CASEWORK_APP_IDS) {
257
+ if (union.has(id) && (grant === null || grant.has(id))) granted.add(id);
258
+ }
259
+ return { granted, union, grant, unrecognized };
260
+ }
261
+
262
+ /**
263
+ * Every app the platform side grants the seat: Echo and Trail (Ruling 2),
264
+ * plus the casework apps its active teams carry inside the account grant when
265
+ * one is known; Trail only before launch. As PLATFORM_TOOL codes, in the
266
+ * canonical order. The Auth0 role is not part of this answer.
267
+ */
268
+ export function seatTeamApps(input: {
269
+ readonly teams?: SeatAppAccessInput["teams"];
270
+ readonly accountGrant?: unknown;
271
+ readonly accountPreLaunch?: boolean | null;
272
+ }): PlatformToolValue[] {
273
+ return ordered(teamSide(input.teams, input.accountGrant, input.accountPreLaunch).granted);
274
+ }
275
+
276
+ /**
277
+ * May this seat open this app, and why. See the module comment for the rule.
278
+ * An app value that names no platform app is never granted by the platform
279
+ * side; the Auth0 decision still stands for it.
280
+ */
281
+ export function seatAppAccess(input: SeatAppAccessInput): SeatAppAccessResult {
282
+ const side = teamSide(input.teams, input.accountGrant, input.accountPreLaunch);
283
+ const app = platformAppById(input.app);
284
+ const teamAllows = app !== null && side.granted.has(app.id);
285
+ const auth0Allows = input.auth0Allows === true;
286
+ const via: SeatAppAccessVia =
287
+ auth0Allows && teamAllows
288
+ ? "both"
289
+ : auth0Allows
290
+ ? "auth0"
291
+ : teamAllows
292
+ ? "teams"
293
+ : "none";
294
+ return {
295
+ allowed: auth0Allows || teamAllows,
296
+ via,
297
+ app: app ? toolCode(app.id) : null,
298
+ teamAllows,
299
+ teamApps: ordered(side.granted),
300
+ teamUnion: ordered(side.union),
301
+ accountGrant: side.grant ? ordered(side.grant) : null,
302
+ unrecognized: side.unrecognized,
303
+ };
304
+ }
@@ -233,18 +233,18 @@ type SectionQuestionRef = InferRawDocType<typeof sectionQuestionRefSchema>;
233
233
  declare const guidanceSchema: Schema<any, mongoose.Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
234
234
  _id: false;
235
235
  }, {
236
- type: "tip" | "warning" | "prompt";
237
236
  text: string;
238
- }, mongoose.Document<unknown, {}, {
239
237
  type: "tip" | "warning" | "prompt";
238
+ }, mongoose.Document<unknown, {}, {
240
239
  text: string;
240
+ type: "tip" | "warning" | "prompt";
241
241
  }, {
242
242
  id: string;
243
243
  }, mongoose.MergeType<mongoose.DefaultSchemaOptions, {
244
244
  _id: false;
245
245
  }>> & Omit<{
246
- type: "tip" | "warning" | "prompt";
247
246
  text: string;
247
+ type: "tip" | "warning" | "prompt";
248
248
  } & {
249
249
  _id: mongoose.Types.ObjectId;
250
250
  } & {
@@ -252,8 +252,8 @@ declare const guidanceSchema: Schema<any, mongoose.Model<any, any, any, any, any
252
252
  }, "id"> & {
253
253
  id: string;
254
254
  }, unknown, {
255
- type: "tip" | "warning" | "prompt";
256
255
  text: string;
256
+ type: "tip" | "warning" | "prompt";
257
257
  } & {
258
258
  _id: mongoose.Types.ObjectId;
259
259
  } & {
@@ -294,18 +294,18 @@ declare const sectionSchemaDefinition: {
294
294
  type: Schema<any, mongoose.Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
295
295
  _id: false;
296
296
  }, {
297
- type: "tip" | "warning" | "prompt";
298
297
  text: string;
299
- }, mongoose.Document<unknown, {}, {
300
298
  type: "tip" | "warning" | "prompt";
299
+ }, mongoose.Document<unknown, {}, {
301
300
  text: string;
301
+ type: "tip" | "warning" | "prompt";
302
302
  }, {
303
303
  id: string;
304
304
  }, mongoose.MergeType<mongoose.DefaultSchemaOptions, {
305
305
  _id: false;
306
306
  }>> & Omit<{
307
- type: "tip" | "warning" | "prompt";
308
307
  text: string;
308
+ type: "tip" | "warning" | "prompt";
309
309
  } & {
310
310
  _id: mongoose.Types.ObjectId;
311
311
  } & {
@@ -313,8 +313,8 @@ declare const sectionSchemaDefinition: {
313
313
  }, "id"> & {
314
314
  id: string;
315
315
  }, unknown, {
316
- type: "tip" | "warning" | "prompt";
317
316
  text: string;
317
+ type: "tip" | "warning" | "prompt";
318
318
  } & {
319
319
  _id: mongoose.Types.ObjectId;
320
320
  } & {
@@ -233,18 +233,18 @@ type SectionQuestionRef = InferRawDocType<typeof sectionQuestionRefSchema>;
233
233
  declare const guidanceSchema: Schema<any, mongoose.Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
234
234
  _id: false;
235
235
  }, {
236
- type: "tip" | "warning" | "prompt";
237
236
  text: string;
238
- }, mongoose.Document<unknown, {}, {
239
237
  type: "tip" | "warning" | "prompt";
238
+ }, mongoose.Document<unknown, {}, {
240
239
  text: string;
240
+ type: "tip" | "warning" | "prompt";
241
241
  }, {
242
242
  id: string;
243
243
  }, mongoose.MergeType<mongoose.DefaultSchemaOptions, {
244
244
  _id: false;
245
245
  }>> & Omit<{
246
- type: "tip" | "warning" | "prompt";
247
246
  text: string;
247
+ type: "tip" | "warning" | "prompt";
248
248
  } & {
249
249
  _id: mongoose.Types.ObjectId;
250
250
  } & {
@@ -252,8 +252,8 @@ declare const guidanceSchema: Schema<any, mongoose.Model<any, any, any, any, any
252
252
  }, "id"> & {
253
253
  id: string;
254
254
  }, unknown, {
255
- type: "tip" | "warning" | "prompt";
256
255
  text: string;
256
+ type: "tip" | "warning" | "prompt";
257
257
  } & {
258
258
  _id: mongoose.Types.ObjectId;
259
259
  } & {
@@ -294,18 +294,18 @@ declare const sectionSchemaDefinition: {
294
294
  type: Schema<any, mongoose.Model<any, any, any, any, any, any, any>, {}, {}, {}, {}, {
295
295
  _id: false;
296
296
  }, {
297
- type: "tip" | "warning" | "prompt";
298
297
  text: string;
299
- }, mongoose.Document<unknown, {}, {
300
298
  type: "tip" | "warning" | "prompt";
299
+ }, mongoose.Document<unknown, {}, {
301
300
  text: string;
301
+ type: "tip" | "warning" | "prompt";
302
302
  }, {
303
303
  id: string;
304
304
  }, mongoose.MergeType<mongoose.DefaultSchemaOptions, {
305
305
  _id: false;
306
306
  }>> & Omit<{
307
- type: "tip" | "warning" | "prompt";
308
307
  text: string;
308
+ type: "tip" | "warning" | "prompt";
309
309
  } & {
310
310
  _id: mongoose.Types.ObjectId;
311
311
  } & {
@@ -313,8 +313,8 @@ declare const sectionSchemaDefinition: {
313
313
  }, "id"> & {
314
314
  id: string;
315
315
  }, unknown, {
316
- type: "tip" | "warning" | "prompt";
317
316
  text: string;
317
+ type: "tip" | "warning" | "prompt";
318
318
  } & {
319
319
  _id: mongoose.Types.ObjectId;
320
320
  } & {