recflare/apps/auth/src/platform-db.ts

/**
 * Platform identity links on the shared `recflare` D1 database (owned by the `auth`
 * worker, migration 0007). One row per (platform, platform id, account): the Steam
 * user 76561…211 is linked to account 42, the Meta user 27061… is linked to account
 * 42 as well, and both let that player into that account without a password.
 *
 * This table replaced the single `platformId`/`platform` pair on the account blob as
 * the thing logins are decided from, because that pair could only hold ONE identity —
 * a player with a PC and a headset had to pick which device got a cached login. The
 * blob fields are kept as the account's *primary* identity (the first one linked) for
 * the account DTO and the refresh grant's claims; nothing authorizes off them.
 *
 * It is deliberately the ONE source of truth for both halves of a cached login: the
 * picker (`/cachedlogin/forplatformid`) lists the accounts this table links to an
 * identity, and the `cached_login` grant asks this table whether the account it was
 * handed is linked to the identity that was proven. When those two disagreed the
 * client was offered an account it could never log into — see the regression test.
 *
 * A link is only ever written from a VERIFIED identity (a Steam-signed ticket or a
 * Meta-validated nonce). It is what turns "this platform user" into "may enter this
 * account with no password", so an unproven `platform_id` must never reach it.
 *
 * Not every link is a LOGIN, though. The table is the account's set of external
 * identities, and some are stored for what they entitle the player to rather than for
 * entry: `PlatformType.Discord` (101) is written by the website's benefits claim, from an
 * OAuth2 code exchange Discord itself vouched for. Nobody signs in with it —
 * `verifyPlatformProof` answers `unsupported` for anything but Steam and Meta, so a
 * `cached_login` naming platform 101 is refused — and the picker must not offer it
 * either. See {@link CACHED_LOGIN_PLATFORMS}, which is what keeps those two in step.
 *
 * That entitlement is also the one thing a link carries beyond the identity itself: the
 * `role` column (migration 0010) records the Discord roles the claim read, so what a
 * player was granted Plus FOR survives the claim instead of collapsing into a bare
 * `hasPlus`. See {@link PlatformLink.roles}.
 */

import { PlatformType } from '@repo/domain/src/enums'

/**
 * Schema DDL (mirror of migrations/0007_platform_accounts.sql, sans the backfill, plus
 * 0010's `role` column — which is an ALTER on prod and a plain column here, since this
 * builds the table from nothing).
 */
export const PLATFORM_SCHEMA_DDL: string[] = [
	`CREATE TABLE IF NOT EXISTS platform_account (
		account_id INTEGER NOT NULL,
		platform INTEGER NOT NULL,
		platform_id TEXT NOT NULL,
		linked_at TEXT NOT NULL,
		role TEXT,
		PRIMARY KEY (platform, platform_id, account_id)
	)`,
	// The picker's lookup: "which accounts does this identity open?". Covered by the
	// primary key's leading columns, so no separate index is needed for it.
	`CREATE INDEX IF NOT EXISTS idx_platform_account_account ON platform_account (account_id)`,
	// Lookup by bare platform id, across platforms — the bulk (friends) route, which
	// resolves ids it has no platform for.
	`CREATE INDEX IF NOT EXISTS idx_platform_account_platform_id ON platform_account (platform_id)`,
]

/**
 * The one-time backfill 0007 ran after creating the table: every identity already bound
 * to an account became a link, so nobody lost their cached login at deploy. It has run;
 * this exists so a test can still exercise it, which is the only coverage that legacy
 * blob-bound accounts get a link at all.
 *
 * `platform` is COALESCEd to 0 because nothing ever defaulted that field — an account
 * can carry a platformId with no platform recorded, and back when Steam was the only
 * verifiable platform an unset one *was* Steam.
 *
 * NOT byte-identical to the migration any more, deliberately. 0007 selected the
 * `account.platform_id` generated column; 0008 drops it, so that text is unrunnable
 * against the head schema the tests build. This selects the blob directly instead —
 * the same values, since the dropped column was DEFINED as
 * `json_extract(data, '$.platformId')`. 0007 is left exactly as it ran on prod.
 */
export const PLATFORM_BACKFILL_SQL = `INSERT OR IGNORE INTO platform_account (account_id, platform, platform_id, linked_at)
	SELECT
		account_id,
		COALESCE(json_extract(data, '$.platform'), 0),
		json_extract(data, '$.platformId'),
		COALESCE(json_extract(data, '$.createdAt'), '1970-01-01T00:00:00Z')
	FROM account
	WHERE json_extract(data, '$.platformId') IS NOT NULL
		AND json_extract(data, '$.platformId') <> ''`

/**
 * The platforms a cached login can actually be redeemed for — the ones
 * `verifyPlatformProof` can prove, which is Steam (a Steam-signed ticket) and Meta/Oculus
 * (a Meta-validated nonce).
 *
 * This is the picker's filter, and it exists to keep a promise the picker's own API
 * documentation makes: "an entry here is always redeemable by a `cached_login` grant
 * (both read the same table)". Once the table began holding identities that are NOT
 * credentials — Discord, from the website's benefits claim — listing every row would have
 * broken that promise in two ways at once. The client would be offered an account it can
 * never log into (the grant refuses platform 101 outright), and, worse, the picker is
 * PUBLIC and unauthenticated: `GET /cachedlogin/forplatformid/101/<snowflake>` would have
 * told anyone which RecFlare account a given Discord user owns, and the bulk route would
 * have done it for a list of them at once. A Discord id is trivially readable by anyone in
 * a shared server, so that is a deanonymisation of every player who claimed benefits.
 *
 * Adding a platform here means asserting `verifyPlatformProof` can prove it. Filtering
 * happens in the two picker reads only — {@link isPlatformIdentityLinked},
 * {@link countAccountsForPlatformIdentity} and {@link getLinksForAccount} deliberately see
 * every link, because they answer "is this identity taken / whose is it", which is exactly
 * the question the benefits claim's once-only guard asks about a Discord id.
 */
export const CACHED_LOGIN_PLATFORMS: readonly number[] = [PlatformType.Steam, PlatformType.Oculus]

/**
 * `IN (…)` fragment for the allowlist, so the filter is applied by the query rather than
 * in JS. Placeholders are numbered from ?2 because the one caller binds the platform id
 * as ?1 — explicit indices rather than bare `?`, which SQLite would number by position
 * and quietly renumber the moment another parameter is added ahead of it.
 */
const CACHED_LOGIN_FILTER = `platform IN (${CACHED_LOGIN_PLATFORMS.map((_, i) => `?${i + 2}`).join(', ')})`

/** One account ↔ platform identity link. */
export interface PlatformLink {
	accountId: number
	platform: number
	platformId: string
	/** ISO-8601 time the link was made. */
	linkedAt: string
	/**
	 * The roles this identity held in its platform's community when the link was last
	 * written — Discord role id snowflakes, kept as strings (one exceeds 2^53). Empty for
	 * every platform that has no such thing, which is all of them but Discord.
	 *
	 * A SNAPSHOT from the claim, not a live read: nothing here can re-read a member's roles
	 * without their own OAuth token (see apps/www/src/discord.ts, which deliberately holds
	 * no bot token), so this says what they held when they claimed. Stored as a JSON array
	 * in the `role` column (migration 0010).
	 */
	roles: string[]
}

interface LinkRow {
	accountId: number
	platform: number
	platformId: string
	linkedAt: string
	/** The `role` column: a JSON array of role ids, or NULL for a link that has none. */
	role: string | null
}

const SELECT_LINK = `SELECT account_id AS accountId, platform, platform_id AS platformId,
	linked_at AS linkedAt, role FROM platform_account`

/**
 * A stored `role` array back into role ids. Tolerant by design — every failure mode is
 * "this link has no roles recorded", which is the truth for every Steam and Meta link and
 * the honest answer for a row written before 0010. A NULL, a value that isn't JSON, or a
 * JSON value that isn't an array of strings all land there rather than throwing: the roles
 * are a record, and no caller's correctness depends on them, so a bad one must not take
 * down the login picker that reads the same rows.
 */
const parseRoles = (raw: string | null): string[] => {
	if (raw === null || raw === '') return []
	try {
		const parsed: unknown = JSON.parse(raw)
		return Array.isArray(parsed) ? parsed.filter((r): r is string => typeof r === 'string') : []
	} catch {
		return []
	}
}

/** One row as the rest of the codebase sees it. */
const toLink = (row: LinkRow): PlatformLink => ({
	accountId: row.accountId,
	platform: row.platform,
	platformId: row.platformId,
	linkedAt: row.linkedAt,
	roles: parseRoles(row.role),
})

/**
 * Link a verified platform identity to an account. Idempotent — re-logging in on the
 * same platform doesn't churn the row, and `linkedAt` keeps the time of the FIRST
 * link. Returns true when this created a new link.
 *
 * Callers must pass an identity the platform itself proved. Nothing in here can tell
 * a verified id from a spoofed one.
 *
 * `roles` records what that identity held in its platform's community — Discord role ids,
 * from the benefits claim's member read. Omitting it (every login path: Steam and Meta
 * have no such thing) leaves the column NULL rather than writing an empty array, so
 * "never had roles" stays distinguishable in the table from "claimed holding none". An
 * EMPTY array is a real value and is stored as one.
 *
 * Unlike the rest of the row, roles are REFRESHED on a repeat link: they're a snapshot of
 * a membership that moves, and the later claim is the fresher reading. That is also why
 * the update is separate from the insert rather than an upsert — the insert's
 * `meta.changes` is what tells a new link from an existing one, and an
 * `ON CONFLICT DO UPDATE` reports a change either way, which would make every re-login
 * look like a first link to {@link linkLoginIdentity}'s primary-identity write. The second
 * statement only runs on the Discord path, and only when the row was already there.
 */
export async function linkPlatformIdentity(
	db: D1Database,
	accountId: number,
	platform: number,
	platformId: string,
	roles?: readonly string[]
): Promise<boolean> {
	if (platformId === '') return false
	const role = roles === undefined ? null : JSON.stringify([...roles])
	const res = await db
		.prepare(
			`INSERT OR IGNORE INTO platform_account (account_id, platform, platform_id, linked_at, role)
			 VALUES (?1, ?2, ?3, ?4, ?5)`
		)
		.bind(accountId, platform, platformId, new Date().toISOString(), role)
		.run()
	if (res.meta.changes > 0) return true

	if (role !== null) {
		await db
			.prepare(
				`UPDATE platform_account SET role = ?4
				 WHERE account_id = ?1 AND platform = ?2 AND platform_id = ?3`
			)
			.bind(accountId, platform, platformId, role)
			.run()
	}
	return false
}

/**
 * The accounts a platform identity opens — what the login-screen picker lists.
 * Ordered oldest link first so the list is stable between launches (D1 row order
 * isn't). Empty id yields nothing rather than matching every link.
 */
export async function getLinksForPlatformIdentity(
	db: D1Database,
	platform: number,
	platformId: string
): Promise<PlatformLink[]> {
	if (platformId === '') return []
	// Asking about a platform nobody can log in from yields nothing at all, rather than a
	// list the grant would refuse — see CACHED_LOGIN_PLATFORMS.
	if (!CACHED_LOGIN_PLATFORMS.includes(platform)) return []
	const { results } = await db
		.prepare(
			`${SELECT_LINK} WHERE platform = ?1 AND platform_id = ?2 ORDER BY linked_at, account_id`
		)
		.bind(platform, platformId)
		.all<LinkRow>()
	return results.map(toLink)
}

/**
 * Links for a bare platform id, whatever platform it belongs to. For the bulk
 * (friends-resolution) lookup, which posts ids with no platform alongside them, and
 * for the single-id route when the client sends a non-numeric platform.
 */
export async function getLinksForPlatformId(
	db: D1Database,
	platformId: string
): Promise<PlatformLink[]> {
	if (platformId === '') return []
	// Matches on any platform a cached login can be redeemed for — but only those. This is
	// the route a bare id takes, so without the filter a Discord snowflake posted here
	// would resolve its account even though naming platform 101 explicitly would not.
	const { results } = await db
		.prepare(
			`${SELECT_LINK} WHERE platform_id = ?1 AND ${CACHED_LOGIN_FILTER}
			 ORDER BY linked_at, account_id`
		)
		.bind(platformId, ...CACHED_LOGIN_PLATFORMS)
		.all<LinkRow>()
	return results.map(toLink)
}

/** Every platform identity linked to an account (a player's PC and headset, say). */
export async function getLinksForAccount(
	db: D1Database,
	accountId: number
): Promise<PlatformLink[]> {
	const { results } = await db
		.prepare(`${SELECT_LINK} WHERE account_id = ?1 ORDER BY linked_at, platform`)
		.bind(accountId)
		.all<LinkRow>()
	return results.map(toLink)
}

/**
 * Whether this account is linked to this platform identity — the single check the
 * `cached_login` grant authorizes on. An account with no link for the presented
 * identity cannot be cached-logged-into and must use a password.
 */
export async function isPlatformIdentityLinked(
	db: D1Database,
	accountId: number,
	platform: number,
	platformId: string
): Promise<boolean> {
	if (platformId === '') return false
	const row = await db
		.prepare(
			`SELECT 1 AS ok FROM platform_account
			 WHERE account_id = ?1 AND platform = ?2 AND platform_id = ?3`
		)
		.bind(accountId, platform, platformId)
		.first<{ ok: number }>()
	return row !== null
}

/**
 * How many accounts one platform identity already opens — the count both signup caps
 * and link caps are enforced against, so an identity can't accumulate accounts by
 * creating them under the cap and then linking more in.
 */
export async function countAccountsForPlatformIdentity(
	db: D1Database,
	platform: number,
	platformId: string
): Promise<number> {
	if (platformId === '') return 0
	const row = await db
		.prepare(`SELECT COUNT(*) AS n FROM platform_account WHERE platform = ?1 AND platform_id = ?2`)
		.bind(platform, platformId)
		.first<{ n: number }>()
	return row?.n ?? 0
}