|
| 1 | +import { generateShortId } from '@sim/utils/id' |
| 2 | + |
| 3 | +/** |
| 4 | + * Header naming the browser tab that sent a request. |
| 5 | + * |
| 6 | + * Shared by the client that sets it and the route handlers that read it. An opaque correlation |
| 7 | + * token, never an authorization input. |
| 8 | + */ |
| 9 | +export const CLIENT_ID_HEADER = 'x-sim-client-id' |
| 10 | + |
| 11 | +/** |
| 12 | + * Generated ids are {@link generateShortId} length; the ceiling is slack for that, not a format. |
| 13 | + * Bounded because the value is caller-controlled and gets fanned out to every subscriber of a |
| 14 | + * table — uncapped, one request could inflate every broadcast payload it triggers. |
| 15 | + */ |
| 16 | +const MAX_CLIENT_ID_LENGTH = 64 |
| 17 | + |
| 18 | +let cachedClientId: string | undefined |
| 19 | + |
| 20 | +/** |
| 21 | + * An id for this browser tab, generated once per page load and not stable across reloads. |
| 22 | + * |
| 23 | + * Deliberately per-TAB rather than per-user or per-session: its only consumer compares it against |
| 24 | + * the originator stamped on a broadcast, so two tabs belonging to the same user must not share one. |
| 25 | + * A shared id would make the second tab ignore the first tab's edits and silently go stale. |
| 26 | + * |
| 27 | + * Returns `undefined` on the server, where there is no tab to identify. |
| 28 | + */ |
| 29 | +export function getClientId(): string | undefined { |
| 30 | + if (typeof window === 'undefined') return undefined |
| 31 | + cachedClientId ??= generateShortId() |
| 32 | + return cachedClientId |
| 33 | +} |
| 34 | + |
| 35 | +/** |
| 36 | + * The sending tab's id, as seen by a route handler. Absent for server-to-server callers, for any |
| 37 | + * client that did not send one, and for an over-long value — all read as "unattributed", never as |
| 38 | + * "not the actor". |
| 39 | + * |
| 40 | + * Untrusted, and never safe to broadcast as-is: see {@link fingerprintClientId}. |
| 41 | + */ |
| 42 | +export function readClientId(request: Request): string | undefined { |
| 43 | + const raw = request.headers.get(CLIENT_ID_HEADER) |
| 44 | + return raw && raw.length <= MAX_CLIENT_ID_LENGTH ? raw : undefined |
| 45 | +} |
| 46 | + |
| 47 | +/** |
| 48 | + * One-way digest of a tab id, for naming the originator of a broadcast. |
| 49 | + * |
| 50 | + * The raw id must never travel on a broadcast. Every subscriber of a table sees every event, so a |
| 51 | + * raw id would be observable by any collaborator, who could then replay it as their own |
| 52 | + * `x-sim-client-id` — their write would be attributed to your tab, your tab would suppress its |
| 53 | + * refetch, and it would sit on stale rows. Publishing the digest instead means matching it |
| 54 | + * requires already knowing the id, which only the tab that generated it does. |
| 55 | + * |
| 56 | + * Web Crypto rather than `node:crypto` so one implementation serves both sides — the server |
| 57 | + * stamping the event and the browser recognising its own — with no chance of the two disagreeing. |
| 58 | + */ |
| 59 | +export async function fingerprintClientId(clientId: string): Promise<string> { |
| 60 | + const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(clientId)) |
| 61 | + return Array.from(new Uint8Array(digest)) |
| 62 | + .map((byte) => byte.toString(16).padStart(2, '0')) |
| 63 | + .join('') |
| 64 | +} |
| 65 | + |
| 66 | +let cachedFingerprint: string | undefined |
| 67 | + |
| 68 | +/** |
| 69 | + * This tab's fingerprint, as it appears on a broadcast it caused. `undefined` on the server, and |
| 70 | + * until the first digest resolves — callers must treat that as "not me" and take the normal path. |
| 71 | + */ |
| 72 | +export async function getClientFingerprint(): Promise<string | undefined> { |
| 73 | + const clientId = getClientId() |
| 74 | + if (!clientId) return undefined |
| 75 | + cachedFingerprint ??= await fingerprintClientId(clientId) |
| 76 | + return cachedFingerprint |
| 77 | +} |
0 commit comments