auth.ts · Source

auth.tsapps/realtime/src/auth.tsraw ← src3,790 B← Back to the app
1/**
2 * WS handshake auth (TASK-0091 R1).
3 *
4 * Verifies the access JWT (HS256, shared API secret) with
5 * `@factory/auth`'s `verifyAccessToken` — the same crypto the API guard
6 * uses (never a copy). Resolutions recorded in the task file:
7 *
8 *  - **note 13** — the shipping API signs `{sub, workspaces: string[]}`
9 *    (no single `workspaceId` claim, no `iss`). The handshake therefore:
10 *    requires `sub`; when `iss` IS present it must be `factory`; the
11 *    room's workspace (resolved server-side, note 14) must be a member
12 *    of `workspaces[]`.
13 *  - **doc §2.1 grace** — a token expired by < 5 min is accepted (a tab
14 *    left open across the 15 min boundary survives until the client's
15 *    BFF refresh). `verifyAccessToken` throws on `exp <= now`, so the
16 *    grace is applied here with the injectable clock.
17 *
18 * The token is read from the upgrade (query `?token=` or the
19 * `Authorization: Bearer` header) and is NEVER logged.
20 */
21 
22import { verifyAccessToken, type DecodedAccessToken } from "@factory/auth/tokens";
23 
24/** The accepted JWT issuer (note 13 — checked only when present). */
25export const EXPECTED_ISSUER = "factory";
26 
27/** doc §2.1: expired-by-< 5 min is accepted (grace for open tabs). */
28export const EXPIRY_GRACE_MS = 5 * 60 * 1000;
29 
30/** A verified handshake identity. */
31export interface SessionIdentity {
32  readonly userId: string;
33  readonly workspaces: readonly string[];
34  /** `jti` (audit correlation). */
35  readonly jti: string;
36  /** Unix seconds. */
37  readonly exp: number;
38}
39 
40export type VerifyOutcome =
41  | { readonly ok: true; readonly session: SessionIdentity }
42  | { readonly ok: false; readonly reason: "missing_token" | "invalid_token" | "wrong_issuer" | "no_workspaces" };
43 
44/**
45 * Verify an access token for the WS handshake.
46 *
47 * @param token   the raw JWT (from the upgrade query/header)
48 * @param secret  the shared JWT secret (env)
49 * @param nowMs   injectable clock (deterministic tests)
50 */
51export function verifyHandshakeToken(
52  token: string | null | undefined,
53  secret: string,
54  nowMs: number = Date.now(),
55): VerifyOutcome {
56  if (token === undefined || token === null || token.length === 0) {
57    return { ok: false, reason: "missing_token" };
58  }
59  let claims: DecodedAccessToken;
60  try {
61    claims = verifyAccessToken(token, secret, nowMs);
62  } catch (err) {
63    // Expired-by-< grace → re-verify against (now - grace) so ONLY exp
64    // can pass; every other failure (signature, alg, shape) stays fatal.
65    const msg = err instanceof Error ? err.message : String(err);
66    if (/expired/i.test(msg)) {
67      try {
68        claims = verifyAccessToken(token, secret, nowMs - EXPIRY_GRACE_MS);
69      } catch {
70        return { ok: false, reason: "invalid_token" };
71      }
72    } else {
73      return { ok: false, reason: "invalid_token" };
74    }
75  }
76  // note 13: `iss` when present must be `factory`.
77  const iss = (claims as { iss?: unknown }).iss;
78  if (iss !== undefined && iss !== EXPECTED_ISSUER) {
79    return { ok: false, reason: "wrong_issuer" };
80  }
81  // The shipping API mints `workspaces: string[]` (auth.service.ts) but
82  // `DecodedAccessToken` does not declare it — read it defensively, same
83  // as `iss` above.
84  const workspacesRaw = (claims as { workspaces?: unknown }).workspaces;
85  const workspaces = Array.isArray(workspacesRaw)
86    ? (workspacesRaw as unknown[]).filter((w): w is string => typeof w === "string")
87    : [];
88  if (workspaces.length === 0) {
89    // A token without any workspace claim cannot be bound to a room —
90    // fail closed (4001): the API always mints `workspaces`.
91    return { ok: false, reason: "no_workspaces" };
92  }
93  return {
94    ok: true,
95    session: {
96      userId: claims.sub,
97      workspaces,
98      jti: claims.jti,
99      exp: claims.exp,
100    },
101  };
102}
103