File size: 19,564 Bytes
bf8519f
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2bdff0c
 
 
 
 
 
 
 
 
 
 
81a8217
 
bf8519f
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
2bdff0c
 
 
 
 
 
 
 
81a8217
 
 
 
 
bf8519f
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
f5696cb
bf8519f
f5696cb
bf8519f
f5696cb
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
bf8519f
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
f5696cb
bf8519f
 
 
 
 
 
f5696cb
bf8519f
 
f5696cb
bf8519f
 
f5696cb
bf8519f
 
 
f5696cb
bf8519f
 
 
f5696cb
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
bf8519f
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
// ---------------------------------------------------------------------------
// shell/session.ts β€” the CLIENT half of X2's auth contract (EXIT wave 1, X5).
//
// WHAT THIS REPLACES. The shell's door was HTTP Basic on a shared APP_PASSWORD
// (`api/main.py`'s BasicAuth middleware): no per-user identity, no BU isolation,
// no `may_open` gate β€” which is why SHELL.md says this frame must not be
// reachable by a real user until EXIT-3 lands. This module is the per-user door:
// the SAME `core/users` accounts the Streamlit `gate()` verifies, reached over
// `POST /api/v1/auth/login` and carried by the X3 signed cookie.
//
// ⚠ THE COOKIE IS HttpOnly (X3), SO THIS CODE CANNOT SEE IT β€” and that is the
// point. There is no client-side "am I logged in?" bit to cache, mirror into
// localStorage, or trust: the only way to know is to ASK the server, which is
// also the only party that can tell whether the user's `epoch` was bumped out
// from under an outstanding cookie. So `me()` runs on every boot, and its
// answer is never persisted. A cached session flag would keep painting the
// frame for a revoked user, which is the whole reason X3 has an epoch.
//
// WHY THIS FILE HOLDS NO import.meta. It is compiled to CommonJS and run under
// node by `verify_login.py`; `import.meta` is a hard error there. Anything
// environment-shaped (the current app's base URL) is a PARAMETER, never a
// module-level read β€” see nav.ts for the same rule.
// ---------------------------------------------------------------------------

// The prefix and the credentials word live in `apiContract.ts` β€” ONE copy, read
// by this module, by nav.ts and by the grid's apiBridge. `verify_login.py`
// mutates them there to prove the gate can see them.
import { API_V1, CREDENTIALS as CREDS, checkTenant } from "../apiContract";

export { API_V1 };

/**
 * The session's user, per X2's login/me payload. Deliberately narrow: the shell
 * needs identity for the account row and nothing else. **Scope is NOT decided
 * here** β€” the row pool is BU-scoped server-side (EXIT-3b) and the nav is
 * `may_open`-filtered server-side (X6), so `bus`/`modules` are for DISPLAY, and
 * a client that re-derived permission from them would be the permission system
 * trusting its own subject (the `Field.createdBy` precedent in types.ts).
 */
export interface SessionUser {
  username: string;
  name: string;
  role: string;
  /** BU labels this user may view β€” `core.users.allowed_bus_labels` semantics. */
  bus: string[];
  /** Granted registry keys, or the literal `'all'` β€” `core/users`' own encoding. */
  modules: string[] | "all";
  /**
   * ⭐ WAVE 35 Β· T06 β€” the company this session is bound to. The SERVER has always sent it
   * (`routes_auth::_public_user`, wave 18 C1-TENANT) and nothing on the client had ever declared
   * it, so it arrived and was thrown away by the type. Owner item 13 needs it: the Subscription
   * page is hidden for Royal Imports.
   * β›” NOT optional and NOT defaulted here. `_public_user` already defaults it to `royal-imports`
   * server-side, and a SECOND default on the client would silently hide the Subscription row for
   * any tenant whose payload was malformed β€” failing toward "you have no subscription", which is
   * the wrong direction to fail in for a billing surface.
   */
  tenant: string;
  /** The server's display name for this workspace, never a permission input. */
  workspaceName: string;
  /** Wave 14 C-AVATAR β€” the user's OWN profile photo as a data URL, or absent. Everyone
   *  else's photos ride `workspace.userAvatars`, keyed by display name. */
  avatar?: string | null;
}

export function isAdmin(user: SessionUser | null): boolean {
  return user?.role === "admin";
}

/**
 * Normalise the server's user object.
 *
 * DEFENSIVE ON THE DISPLAY FIELDS, STRICT ON IDENTITY. A missing `name` falls
 * back to the username (a person with no display name still gets a door); a
 * missing `username` returns null, because an authenticated session with no
 * subject is not a session. The distinction matters: hard-failing on a cosmetic
 * field would turn a harmless server change into every user locked out, while
 * inventing a subject would be worse than the 401 it papers over.
 */
export function parseUser(raw: unknown): SessionUser | null {
  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
  const r = raw as Record<string, unknown>;
  const username = typeof r.username === "string" ? r.username.trim() : "";
  if (!username) return null;
  const name = typeof r.name === "string" && r.name.trim() !== "" ? r.name.trim() : username;
  const role = typeof r.role === "string" ? r.role : "";
  const bus = Array.isArray(r.bus) ? r.bus.filter((b): b is string => typeof b === "string") : [];
  const modules =
    r.modules === "all"
      ? "all"
      : Array.isArray(r.modules)
        ? r.modules.filter((m): m is string => typeof m === "string")
        : [];
  // Defensive like the display fields: only a data: image URL is carried; anything
  // else renders the initials disc rather than a broken <img>.
  const avatar =
    typeof r.avatar === "string" && r.avatar.startsWith("data:image/") ? r.avatar : null;
  /* ⭐ WAVE 35 Β· T06 β€” the tenant slug the session is bound to. Parsed defensively like every
     other field here, and normalised the same way the SERVER normalises it in
     `routes_auth::_public_user` (`strip().lower()`), so a comparison against
     `NO_SUBSCRIPTION_TENANT` cannot fail on whitespace or case.
     ⚠ A malformed payload yields `""`, never `"royal-imports"`. An empty slug matches no tenant
     rule, so the Subscription page is SHOWN β€” the safe direction: a customer seeing a page they
     could have been spared beats a paying customer being told they have no subscription. */
  const tenant = typeof r.tenant === "string" ? r.tenant.trim().toLowerCase() : "";
  const workspaceName =
    typeof r.workspaceName === "string" && r.workspaceName.trim() !== ""
      ? r.workspaceName.trim()
      : "Workspace";
  return { username, name, role, bus, modules, avatar, tenant, workspaceName };
}

/** The `{user: {...}}` envelope both `/auth/login` and `/auth/me` return. */
export function parseUserEnvelope(body: unknown): SessionUser | null {
  if (!body || typeof body !== "object") return null;
  return parseUser((body as { user?: unknown }).user);
}

// --- error copy ------------------------------------------------------------

/** Shown when the server gives us nothing better on a rejected credential. Same
 *  words as the Streamlit `gate()` β€” one product, one wrong-password sentence. */
export const BAD_CREDENTIALS = "Incorrect username or password.";
export const SERVER_UNAVAILABLE = "Sign-in is unavailable right now. Try again in a moment.";
export const NETWORK_UNAVAILABLE = "Cannot reach the server. Check your connection and try again.";

/**
 * X2's error envelope is `{"error": {"code", "message"}}`. Which message the
 * user sees is a policy question, so the rule is explicit rather than "show
 * whatever came back":
 *
 *   - **4xx β†’ prefer the SERVER's message.** A 4xx message is policy the client
 *     cannot know β€” "too many attempts, try again in 30 seconds" is the server's
 *     backoff talking (X5: *the server owns backoff*), and replacing it with our
 *     generic line would hide the only actionable thing on the screen.
 *   - **5xx β†’ OUR generic line.** A 500's message describes the server's
 *     internals to someone who is, by definition, not authenticated yet.
 *   - **status 0 β†’ a transport failure**, which never reached a server at all.
 *
 * `status` 0 is our own encoding for "fetch threw" β€” there is no HTTP 0.
 */
export function errorMessage(status: number, body: unknown): string {
  if (status === 0) return NETWORK_UNAVAILABLE;
  if (status >= 500) return SERVER_UNAVAILABLE;
  const err = (body as { error?: { message?: unknown } } | null)?.error;
  const msg = typeof err?.message === "string" ? err.message.trim() : "";
  if (msg) return msg;
  return status === 401 ? BAD_CREDENTIALS : SERVER_UNAVAILABLE;
}

// --- auth transport --------------------------------------------------------

export type LoginOutcome =
  | { ok: true; user: SessionUser }
  | { ok: false; reason: "credentials" | "throttled" | "password_expired"
      | "mfa_required" | "mfa_invalid" | "mfa_enrolment_required" | "server" | "network";
      message: string };

// W57-T36: keep the old export for callers compiled against the original door.
export type LoginResult = LoginOutcome;
export type LoginReason = Extract<LoginOutcome, { ok: false }>["reason"];

/** A 401 now names three different steps. The SERVER'S code decides which one;
 *  status only separates transport/server failures from an unknown client refusal.
 *  Named so verify_login can negative-control the mapping without rendering a form. */
export function loginReason(status: number, body: unknown): LoginReason {
  if (status === 0) return "network";
  if (status >= 500) return "server";
  const code = (body as { error?: { code?: unknown } } | null)?.error?.code;
  switch (code) {
    case "invalid_credentials": return "credentials";
    case "too_many_attempts": return "throttled";
    case "password_expired":
    case "mfa_required":
    case "mfa_invalid":
    case "mfa_enrolment_required": return code;
    default: return "credentials";
  }
}

async function readJson(res: Response): Promise<unknown> {
  try {
    return await res.json();
  } catch {
    return null;
  }
}

/**
 * X2 `POST /api/v1/auth/login`. NO client-side backoff, deliberately: X5 gives
 * the delay to the server, because a delay a browser imposes on itself is a
 * delay an attacker's script simply does not import.
 *
 * `tenant` is omitted rather than defaulted β€” X2 types it optional with the
 * server's own default, and a client that pins `'royal-imports'` into every
 * login is a client that has to be re-shipped for tenant #2.
 */
export async function login(username: string, password: string, mfaCode?: string): Promise<LoginOutcome> {
  let res: Response;
  try {
    res = await fetch(`${API_V1}/auth/login`, {
      method: "POST",
      credentials: CREDS,
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ username, password, ...(mfaCode !== undefined ? { mfaCode } : {}) }),
    });
  } catch {
    return { ok: false, reason: loginReason(0, null), message: errorMessage(0, null) };
  }
  const body = await readJson(res);
  if (!res.ok) return { ok: false, reason: loginReason(res.status, body), message: errorMessage(res.status, body) };
  const user = parseUserEnvelope(body);
  // A 200 whose body we cannot read as a user is NOT a session. Treating it as
  // one would paint the frame for a subject nobody can name.
  if (!user) return { ok: false, reason: "server", message: SERVER_UNAVAILABLE };
  return { ok: true, user };
}

// W57-T35/T36: these are wire shapes, never cached account state. In particular,
// the candidate secret and clear recovery codes belong only to the mounted form.
export interface PasswordPolicy {
  rules: { rule: string; message: string }[];
  minLength: number;
  maxAgeDays: number;
  historyCount: number;
}

export interface MFASetup {
  secret: string;
  otpauthUri: string;
  issuer: string;
}

export interface MFAStatus {
  enrolled: boolean;
  enrolledAt: string | null;
  recoveryCodesRemaining: number;
}

type AuthFailure = { ok: false; message: string };
type AuthReply = { ok: true; body: unknown; status: number } | AuthFailure;

/** One transport policy for the additional POST doors. Session-scoped replies
 *  also pass the existing tenant guard; a repointed tab must not display codes
 *  as though they belonged to the account still painted in its chrome.
 *
 *  β›” IT TAKES THE WHOLE URL, NOT A SUFFIX, AND THAT IS NOT A STYLE CHOICE.
 *  `verify_api.py`'s D-48 leg reads every client fetch path out of the source and asserts the
 *  app actually MOUNTED a route for it, by READING THE SOURCE TEXT. A first draft of this helper
 *  took a suffix and joined it to the prefix itself, which made all four of these doors
 *  undecidable at once: the gate could see only a wildcard segment, matched it to nothing, and
 *  went red - the correct answer to "I cannot tell what this client calls". Writing the whole url
 *  at each call site is what keeps that proof possible.
 *  ⚠ AND BECAUSE THE SCAN READS TEXT, A COMMENT COUNTS. The sentence above originally quoted the
 *  offending template literal, and the gate dutifully found it in this comment and stayed red on
 *  a file that had already been fixed. Do not spell one out in here. */
async function authPost(url: string, payload: Record<string, string>, sessionScoped = false): Promise<AuthReply> {
  let res: Response;
  try {
    res = await fetch(url, {
      method: "POST",
      credentials: CREDS,
      cache: "no-store",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(payload),
    });
  } catch {
    return { ok: false, message: errorMessage(0, null) };
  }
  if (sessionScoped && checkTenant(res)) return { ok: false, message: SERVER_UNAVAILABLE };
  const body = await readJson(res);
  if (!res.ok) return { ok: false, message: errorMessage(res.status, body) };
  return { ok: true, body, status: res.status };
}

function asRecord(raw: unknown): Record<string, unknown> | null {
  return raw && typeof raw === "object" && !Array.isArray(raw) ? raw as Record<string, unknown> : null;
}

function nonemptyString(raw: unknown): raw is string {
  return typeof raw === "string" && raw.trim().length > 0;
}

function nonnegativeInteger(raw: unknown): raw is number {
  return typeof raw === "number" && Number.isSafeInteger(raw) && raw >= 0;
}

/** Take the entire issued set or refuse it. Filtering a damaged payload would
 *  tell a person they saved all their recovery codes when some never reached them. */
function recoveryCodes(body: unknown): string[] | null {
  const codes = asRecord(body)?.recoveryCodes;
  return Array.isArray(codes) && codes.length > 0 && codes.every(nonemptyString)
    && new Set(codes).size === codes.length ? codes : null;
}

export async function passwordPolicy(): Promise<PasswordPolicy | null> {
  try {
    const res = await fetch(`${API_V1}/auth/password-policy`, { credentials: CREDS });
    if (res.ok === false) return null;
    const b = asRecord(await readJson(res));
    if (!b || !Array.isArray(b.rules) || b.rules.length === 0
        || !nonnegativeInteger(b.minLength) || b.minLength === 0
        || !nonnegativeInteger(b.maxAgeDays) || !nonnegativeInteger(b.historyCount)) return null;
    const rules: PasswordPolicy["rules"] = [];
    for (const raw of b.rules) {
      const rule = asRecord(raw);
      if (!rule || !nonemptyString(rule.rule) || !nonemptyString(rule.message)) return null;
      rules.push({ rule: rule.rule, message: rule.message });
    }
    return { rules, minLength: b.minLength, maxAgeDays: b.maxAgeDays, historyCount: b.historyCount };
  } catch {
    return null;
  }
}

export async function changePassword(username: string, currentPassword: string, newPassword: string): Promise<{ ok: true } | AuthFailure> {
  const r = await authPost(`${API_V1}/auth/password`, { username, currentPassword, newPassword });
  if (r.ok === false) return r;
  return r.status === 204 ? { ok: true } : { ok: false, message: SERVER_UNAVAILABLE };
}

export async function mfaEnrollStart(username: string, password: string): Promise<({ ok: true } & MFASetup) | AuthFailure> {
  const r = await authPost(`${API_V1}/auth/mfa/enroll`, { username, password });
  if (r.ok === false) return r;
  const b = asRecord(r.body);
  if (!b || !nonemptyString(b.secret) || !nonemptyString(b.otpauthUri) || !nonemptyString(b.issuer))
    return { ok: false, message: SERVER_UNAVAILABLE };
  // digits/period are carried by the server's URI. No second authenticator configuration here.
  return { ok: true, secret: b.secret, otpauthUri: b.otpauthUri, issuer: b.issuer };
}

export async function mfaEnrollConfirm(username: string, password: string, secret: string, code: string): Promise<{ ok: true; user: SessionUser; recoveryCodes: string[] } | AuthFailure> {
  const r = await authPost(`${API_V1}/auth/mfa/enroll/confirm`, { username, password, secret, code });
  if (r.ok === false) return r;
  const user = parseUserEnvelope(r.body);
  const codes = recoveryCodes(r.body);
  // A 200 without a readable subject is NOT a session, exactly like login.
  // Missing codes also refuse success: acknowledgement cannot stand for an unseen set.
  if (!user || !codes) return { ok: false, message: SERVER_UNAVAILABLE };
  return { ok: true, user, recoveryCodes: codes };
}

export async function mfaStatus(): Promise<MFAStatus | null> {
  try {
    const res = await fetch(`${API_V1}/auth/mfa`, { credentials: CREDS, cache: "no-store" });
    if (checkTenant(res) || !res.ok) return null;
    const b = asRecord(await readJson(res));
    if (!b || typeof b.enrolled !== "boolean" || !nonnegativeInteger(b.recoveryCodesRemaining)
        || !(b.enrolledAt === null || (nonemptyString(b.enrolledAt) && Number.isFinite(Date.parse(b.enrolledAt))))) return null;
    const enrolledAt: string | null = typeof b.enrolledAt === "string" ? b.enrolledAt : null;
    return { enrolled: b.enrolled, enrolledAt, recoveryCodesRemaining: b.recoveryCodesRemaining };
  } catch {
    return null;
  }
}

export async function regenerateRecoveryCodes(password: string): Promise<{ ok: true; recoveryCodes: string[] } | AuthFailure> {
  const r = await authPost(`${API_V1}/auth/mfa/recovery-codes`, { password }, true);
  if (r.ok === false) return r;
  const codes = recoveryCodes(r.body);
  return codes ? { ok: true, recoveryCodes: codes } : { ok: false, message: SERVER_UNAVAILABLE };
}

/**
 * X2 `GET /api/v1/auth/me`. FAIL-CLOSED: anything that is not a 200 carrying a
 * readable user β€” 401, 404 (the route not built yet), a proxy's HTML error
 * page, a dropped connection β€” reads as NO SESSION. There is no state in which
 * a failure to confirm the session is treated as having one.
 */
export async function me(): Promise<SessionUser | null> {
  try {
    const res = await fetch(`${API_V1}/auth/me`, { credentials: CREDS });
    // ⭐ THE BOOT SIDE OF THE TENANT GUARD. `me()` runs on every boot, so this is what ARMS
    // the comparator with the tenant this frame belongs to β€” every later call then only has to
    // notice a change. It also catches the swap directly on a re-check.
    // ⚠ Deliberately BEFORE the `!res.ok` return: a repointed tab still gets a 200 here, and
    // the guard must see the header on exactly the request that establishes identity.
    if (checkTenant(res)) return null;
    if (!res.ok) return null;
    return parseUserEnvelope(await readJson(res));
  } catch {
    return null;
  }
}

/**
 * X2 `POST /api/v1/auth/logout` β†’ 204, cookie cleared.
 *
 * Returns nothing and swallows failures ON PURPOSE: the caller drops to the
 * login screen either way. A logout button that reports failure and leaves the
 * user sitting in the app is worse than one that always closes the door on this
 * browser β€” and the cookie is the server's to invalidate, so the honest local
 * action is "stop showing the frame".
 */
export async function logout(): Promise<void> {
  try {
    await fetch(`${API_V1}/auth/logout`, { method: "POST", credentials: CREDS });
  } catch {
    // deliberate: see above
  }
}