@flow-industries/id 0.24.0 → 0.24.2

package/dist/sdk/oauth/encryption.d.ts

@@ -0,0 +1,4 @@
+export declare function createCredentialCipher(encodedKey: string): {
+    seal<T>(value: T, context: string): string;
+    open<T>(value: string, context: string): T;
+};

package/dist/sdk/oauth/encryption.js

@@ -0,0 +1,29 @@
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+export function createCredentialCipher(encodedKey) {
+    const key = Buffer.from(encodedKey, "base64");
+    if (key.length !== 32)
+        throw new Error("OAuth storage key must encode 32 bytes");
+    return {
+        seal(value, context) {
+            const nonce = randomBytes(12);
+            const cipher = createCipheriv("aes-256-gcm", key, nonce);
+            cipher.setAAD(Buffer.from(context));
+            const body = Buffer.concat([
+                cipher.update(JSON.stringify(value), "utf8"),
+                cipher.final(),
+            ]);
+            return Buffer.concat([nonce, cipher.getAuthTag(), body]).toString("base64");
+        },
+        open(value, context) {
+            const data = Buffer.from(value, "base64");
+            const cipher = createDecipheriv("aes-256-gcm", key, data.subarray(0, 12));
+            cipher.setAAD(Buffer.from(context));
+            cipher.setAuthTag(data.subarray(12, 28));
+            // SAFETY: authenticated ciphertext is written only by seal with the same domain context.
+            return JSON.parse(Buffer.concat([
+                cipher.update(data.subarray(28)),
+                cipher.final(),
+            ]).toString("utf8"));
+        },
+    };
+}

package/dist/sdk/oauth/stores.d.ts

@@ -0,0 +1,16 @@
+import type { AppDb } from "../db/handle";
+export interface OAuthCredentialStore<T> {
+    set(id: string, value: T): Promise<void>;
+    get(id: string): Promise<T | undefined>;
+    del(id: string): Promise<void>;
+}
+export declare function withOAuthTransaction<T>(database: AppDb, fn: () => Promise<T>, sessionGuard?: (providerId: string, accountId: string) => Promise<void>): Promise<T>;
+export declare function withOAuthSessionLock<T>(database: AppDb, providerId: string, accountId: string, fn: () => Promise<T>): Promise<T>;
+export declare function createOAuthStores<State, Session>(database: AppDb, storageKey: string, providerId: string): {
+    stateStore: OAuthCredentialStore<State>;
+    sessionStore: OAuthCredentialStore<Session>;
+    requestLock: <T>(name: string, fn: () => T | PromiseLike<T>) => Promise<T>;
+};
+export declare function cleanupOAuthCredentials(database: AppDb): Promise<void>;
+export declare function peekOAuthState<State>(database: AppDb, storageKey: string, providerId: string, id: string): Promise<State | undefined>;
+export declare function lockOAuthSession(database: AppDb, providerId: string, accountId: string): Promise<void>;

package/dist/sdk/oauth/stores.js

@@ -0,0 +1,159 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { and, eq, lt, notExists, sql } from "drizzle-orm";
+import { account, oauthSession, oauthState } from "../db/schema";
+import { createCredentialCipher } from "./encryption";
+const transactionContext = new AsyncLocalStorage();
+const sessionGuardContext = new AsyncLocalStorage();
+export function withOAuthTransaction(database, fn, sessionGuard) {
+    const guard = sessionGuard ?? sessionGuardContext.getStore();
+    return transactionContext.run(database, () => guard ? sessionGuardContext.run(guard, fn) : fn());
+}
+export async function withOAuthSessionLock(database, providerId, accountId, fn) {
+    const current = transactionContext.getStore();
+    if (current) {
+        await lockOAuthSession(current, providerId, accountId);
+        await sessionGuardContext.getStore()?.(providerId, accountId);
+        return fn();
+    }
+    const outcome = await database.transaction(async (tx) => {
+        await lockOAuthSession(tx, providerId, accountId);
+        try {
+            return { ok: true, value: await withOAuthTransaction(tx, fn) };
+        }
+        catch (error) {
+            return { ok: false, error };
+        }
+    });
+    if (!outcome.ok)
+        throw outcome.error;
+    return outcome.value;
+}
+export function createOAuthStores(database, storageKey, providerId) {
+    const cipher = createCredentialCipher(storageKey);
+    const currentDatabase = () => transactionContext.getStore() ?? database;
+    const stateStore = {
+        async set(id, value) {
+            const data = cipher.seal(value, JSON.stringify(["oauth-state", providerId, id]));
+            const expiresAt = new Date(Date.now() + 10 * 60_000);
+            await currentDatabase()
+                .insert(oauthState)
+                .values({ providerId, id, data, expiresAt })
+                .onConflictDoUpdate({
+                target: [oauthState.providerId, oauthState.id],
+                set: { data, expiresAt },
+            });
+        },
+        async get(id) {
+            // Consuming before token exchange makes callback replay fail across replicas.
+            const [row] = await currentDatabase()
+                .delete(oauthState)
+                .where(and(eq(oauthState.providerId, providerId), eq(oauthState.id, id)))
+                .returning();
+            if (!row || row.expiresAt.getTime() <= Date.now())
+                return undefined;
+            return cipher.open(row.data, JSON.stringify(["oauth-state", providerId, id]));
+        },
+        async del(id) {
+            await currentDatabase()
+                .delete(oauthState)
+                .where(and(eq(oauthState.providerId, providerId), eq(oauthState.id, id)));
+        },
+    };
+    const sessionStore = {
+        async set(accountId, value) {
+            const data = cipher.seal(value, JSON.stringify(["oauth-session", providerId, accountId]));
+            const updatedAt = new Date();
+            await withOAuthSessionLock(database, providerId, accountId, async () => currentDatabase()
+                .insert(oauthSession)
+                .values({ providerId, accountId, data, updatedAt, formatVersion: 2 })
+                .onConflictDoUpdate({
+                target: [oauthSession.providerId, oauthSession.accountId],
+                set: { data, updatedAt, formatVersion: 2 },
+            }));
+        },
+        async get(accountId) {
+            const [row] = await currentDatabase()
+                .select()
+                .from(oauthSession)
+                .where(and(eq(oauthSession.providerId, providerId), eq(oauthSession.accountId, accountId)));
+            return row
+                ? cipher.open(row.data, sessionContext(providerId, accountId, row.formatVersion))
+                : undefined;
+        },
+        async del(accountId) {
+            await withOAuthSessionLock(database, providerId, accountId, async () => currentDatabase()
+                .delete(oauthSession)
+                .where(and(eq(oauthSession.providerId, providerId), eq(oauthSession.accountId, accountId))));
+        },
+    };
+    const requestLock = async (name, fn) => {
+        const current = transactionContext.getStore();
+        if (current) {
+            await current.execute(sql `select pg_advisory_xact_lock(hashtext(${lockName(providerId, name)}))`);
+            return await fn();
+        }
+        const outcome = await database.transaction(async (tx) => {
+            await tx.execute(sql `select pg_advisory_xact_lock(hashtext(${lockName(providerId, name)}))`);
+            try {
+                return {
+                    ok: true,
+                    value: await transactionContext.run(tx, fn),
+                };
+            }
+            catch (error) {
+                // SDK invalidation must commit even when token refresh fails.
+                return { ok: false, error };
+            }
+        });
+        if (!outcome.ok)
+            throw outcome.error;
+        return outcome.value;
+    };
+    return { stateStore, sessionStore, requestLock };
+}
+export async function cleanupOAuthCredentials(database) {
+    await database.execute(sql `delete from oauth_state where (provider_id, id) in (select provider_id, id from oauth_state where expires_at < (now() at time zone 'UTC') limit 100)`);
+    const cutoff = new Date(Date.now() - 60 * 60_000);
+    const candidates = await database
+        .select({
+        providerId: oauthSession.providerId,
+        accountId: oauthSession.accountId,
+    })
+        .from(oauthSession)
+        .where(and(lt(oauthSession.updatedAt, cutoff), notExists(database
+        .select()
+        .from(account)
+        .where(and(eq(account.providerId, oauthSession.providerId), eq(account.accountId, oauthSession.accountId))))))
+        .limit(100);
+    for (const { providerId, accountId } of candidates) {
+        await database.transaction(async (tx) => {
+            await lockOAuthSession(tx, providerId, accountId);
+            await tx.delete(oauthSession).where(and(eq(oauthSession.providerId, providerId), eq(oauthSession.accountId, accountId), lt(oauthSession.updatedAt, cutoff), notExists(tx
+                .select()
+                .from(account)
+                .where(and(eq(account.providerId, providerId), eq(account.accountId, accountId))))));
+        });
+    }
+}
+export async function peekOAuthState(database, storageKey, providerId, id) {
+    const [row] = await database
+        .select()
+        .from(oauthState)
+        .where(and(eq(oauthState.providerId, providerId), eq(oauthState.id, id)));
+    if (!row || row.expiresAt.getTime() <= Date.now())
+        return undefined;
+    return createCredentialCipher(storageKey).open(row.data, JSON.stringify(["oauth-state", providerId, id]));
+}
+function sessionContext(providerId, accountId, formatVersion) {
+    if (formatVersion === 2)
+        return JSON.stringify(["oauth-session", providerId, accountId]);
+    if (formatVersion === 1 && providerId === "atproto")
+        return `session:${accountId}`;
+    throw new Error("Unsupported OAuth credential format");
+}
+function lockName(providerId, name) {
+    return JSON.stringify(["oauth-lock", providerId, name]);
+}
+export async function lockOAuthSession(database, providerId, accountId) {
+    await database.execute(sql `select pg_advisory_xact_lock(hashtext(${lockName(providerId, accountId)}))`);
+}

package/dist/sdk/settings/appearance.d.ts

@@ -0,0 +1,3 @@
+import type { SurfaceRegistry } from "../types";
+import { type Catalog } from "./cosmetics";
+export declare function appearanceSurface(catalog?: Catalog): SurfaceRegistry;

package/dist/sdk/settings/appearance.js

@@ -0,0 +1,167 @@
+import { isString } from "../json";
+import { appearanceConflict, CATALOG, COSMETIC_SLOTS, conflictingRegions, cosmeticsForSlot, paintKey, paintSlots, STARTING_OUTFIT, slotLabel, slotRequired, } from "./cosmetics";
+const HAIR_COLORS = [
+    { value: "#26201d", label: "Black" },
+    { value: "#6b4226", label: "Brown" },
+    { value: "#8b5a2b", label: "Chestnut" },
+    { value: "#b5532a", label: "Copper" },
+    { value: "#d9b380", label: "Blonde" },
+    { value: "#9b9b9b", label: "Grey" },
+    { value: "#ececec", label: "White" },
+];
+const SKIN_COLORS = [
+    { value: "#f5d0b5", label: "Porcelain" },
+    { value: "#eab98f", label: "Fair" },
+    { value: "#d9a066", label: "Tan" },
+    { value: "#b97a4e", label: "Bronze" },
+    { value: "#96613a", label: "Amber" },
+    { value: "#7a4b2a", label: "Sienna" },
+    { value: "#5c3823", label: "Umber" },
+    { value: "#3d2419", label: "Ebony" },
+];
+function cosmeticSlotSettings(catalog) {
+    return COSMETIC_SLOTS.filter((slot) => cosmeticsForSlot(slot, catalog).length > 0).map((slot) => ({
+        key: slot,
+        group: "cosmetics",
+        label: slotLabel(slot),
+        type: "cosmetic",
+        default: STARTING_OUTFIT[slot],
+        slot,
+        required: slotRequired(slot),
+        items: cosmeticsForSlot(slot, catalog).map((item) => cosmeticOffer(item)),
+    }));
+}
+const PAINT_COLORS = [
+    { value: "#f2f2f2", label: "White" },
+    { value: "#9b9b9b", label: "Grey" },
+    { value: "#2a2a2e", label: "Charcoal" },
+    { value: "#26262b", label: "Black" },
+    { value: "#d63c3c", label: "Red" },
+    { value: "#e8863a", label: "Orange" },
+    { value: "#e6c545", label: "Yellow" },
+    { value: "#47a35e", label: "Green" },
+    { value: "#4c6b45", label: "Olive" },
+    { value: "#3d6ef0", label: "Blue" },
+    { value: "#3a5bbf", label: "Navy" },
+    { value: "#8a5bd6", label: "Purple" },
+    { value: "#eab98f", label: "Tan" },
+    { value: "#6b4226", label: "Brown" },
+    { value: "#4a3527", label: "Leather" },
+];
+const RETIRED_GARMENT_COLORS = [
+    { key: "tshirt_color", paint: paintKey("hoodie", "tshirt") },
+    { key: "shorts_color", paint: paintKey("cargo_shorts", "shorts") },
+];
+function rgb(hex) {
+    if (!/^#[0-9a-f]{6}$/i.test(hex))
+        return null;
+    return [
+        Number.parseInt(hex.slice(1, 3), 16),
+        Number.parseInt(hex.slice(3, 5), 16),
+        Number.parseInt(hex.slice(5, 7), 16),
+    ];
+}
+function nearestSwatch(color, options) {
+    const target = rgb(color);
+    if (!target)
+        return null;
+    const [red, green, blue] = target;
+    let best = null;
+    for (const option of options) {
+        const candidate = rgb(option.value);
+        if (!candidate)
+            continue;
+        const distance = (candidate[0] - red) ** 2 +
+            (candidate[1] - green) ** 2 +
+            (candidate[2] - blue) ** 2;
+        if (!best || distance < best.distance) {
+            best = { value: option.value, distance };
+        }
+    }
+    return best?.value ?? null;
+}
+function retireGarmentPalette(stored) {
+    const next = { ...stored };
+    for (const { key, paint } of RETIRED_GARMENT_COLORS) {
+        const color = next[key];
+        delete next[key];
+        if (paint in next || !isString(color))
+            continue;
+        const nearest = nearestSwatch(color, PAINT_COLORS);
+        if (nearest)
+            next[paint] = nearest;
+    }
+    return next;
+}
+function dressMandatorySlots(stored) {
+    const next = { ...stored };
+    for (const slot of COSMETIC_SLOTS) {
+        if (slotRequired(slot) && next[slot] === "")
+            delete next[slot];
+    }
+    return next;
+}
+function appearanceV2(stored) {
+    return dressMandatorySlots(retireGarmentPalette(stored));
+}
+const UNPAINTED = {
+    skin: "#eab98f",
+    brownhair: "#6b4226",
+    tshirt: "#3d6ef0",
+    shorts: "#2a2a2e",
+    Shoes: "#4a3527",
+    outline: "#26262b",
+};
+function paintDescriptor(item, material) {
+    return {
+        key: paintKey(item.id, material),
+        group: "paint",
+        label: item.name,
+        type: "paint",
+        default: UNPAINTED[material],
+        options: PAINT_COLORS,
+        cosmetic: item.id,
+        material,
+    };
+}
+function cosmeticOffer(item) {
+    return {
+        ...item,
+        conflicts: conflictingRegions(item.regions),
+        paint: item.paintable.map((material) => paintDescriptor(item, material)),
+    };
+}
+function paintSettings(settings, catalog) {
+    return paintSlots(settings, catalog).map((paint) => paintDescriptor(paint.item, paint.material));
+}
+function appearanceSettings(catalog) {
+    return [
+        {
+            key: "hair_color",
+            group: "colors",
+            label: "Hair",
+            type: "enum",
+            default: "#6b4226",
+            options: HAIR_COLORS,
+        },
+        {
+            key: "skin_color",
+            group: "colors",
+            label: "Skin",
+            type: "enum",
+            default: "#eab98f",
+            options: SKIN_COLORS,
+        },
+        ...cosmeticSlotSettings(catalog),
+    ];
+}
+export function appearanceSurface(catalog = CATALOG) {
+    return {
+        version: 2,
+        settings: appearanceSettings(catalog),
+        migrations: [{ to: 2, up: appearanceV2 }],
+        randomDefaults: true,
+        validate: (settings) => appearanceConflict(settings, catalog),
+        derived: (settings) => paintSettings(settings, catalog),
+    };
+}

package/dist/sdk/settings/cosmetics.d.ts

@@ -0,0 +1,150 @@
+/**
+ * The cosmetic catalog, the space each item occupies, the surfaces it exposes
+ * for paint, and the single rule that decides whether two items may be worn at
+ * once.
+ *
+ * Pure — no DB, no I/O — and deliberately the ONLY implementation of that rule.
+ * TF2 evaluated it per equip path and its quickswitch path skipped the check
+ * entirely, so players equipped conflicting cosmetics that silently unequipped
+ * on restart (Source-1-Games#4055). Here the rule hangs off the surface
+ * registry and runs inside the one settings write path, which is why no route
+ * can forget it: a client may grey out conflicting picks for UX, but the save
+ * is the enforcer.
+ *
+ * The catalog is a code constant rather than a table, matching the appearance
+ * palette beside it — adding an item is a one-line edit and no migration. It
+ * promotes to a `cosmetic` table when non-engineers must edit it live.
+ */
+import type { CosmeticItem, CosmeticMaterial, CosmeticSlot, EquipConflict, EquippedCosmetics, EquipRegion, PaintSlot, SettingsConflict } from "../types/cosmetics";
+import type { Settings } from "./registry";
+/** Every slot, in the order the customizer and the resolver walk them. */
+export declare const COSMETIC_SLOTS: readonly CosmeticSlot[];
+/** What a player reads this slot's row as. */
+export declare function slotLabel(slot: CosmeticSlot): string;
+/** Whether an avatar must wear something in this slot. */
+export declare function slotRequired(slot: CosmeticSlot): boolean;
+/**
+ * A catalog: the items on sale, resolved by id.
+ *
+ * A parameter rather than a module constant everywhere below, because the
+ * region rules have to stay testable against items that are not products.
+ * AUTH-223 is what the alternative costs: four cosmetics with no mesh anywhere
+ * — a beanie, earmuffs, a diving helmet, a bandana — were added to the shipped
+ * catalog purely so the composite and second-region collisions had something to
+ * collide, and a customizer duly offered all four for sale. The fixtures now
+ * live in `cosmetics.test.ts` and build a catalog of their own.
+ */
+export type Catalog = ReadonlyMap<string, CosmeticItem>;
+/** A catalog over `items`, refusing a duplicate id. */
+export declare function catalogOf(items: readonly CosmeticItem[]): Catalog;
+/**
+ * Every item a player may equip. EACH ONE MUST HAVE GEOMETRY: an id here with
+ * no mesh behind it renders as an item that vanishes when worn, and the model's
+ * side of the pairing is `cosmetic_items` in
+ * `game/games/arena/player/luna_bodygroups.tres` — a catalog id absent from
+ * there names nothing the renderer can draw.
+ */
+export declare const COSMETICS: readonly CosmeticItem[];
+/** Every item the shipped model can wear. */
+export declare const CATALOG: Catalog;
+/**
+ * What a player is wearing before they have dressed themselves — the outfit the
+ * model ships in, named in catalog terms.
+ *
+ * It is a DEFAULT of the appearance surface, resolved server-side exactly the
+ * way `randomDefaults` resolves a palette colour, and that is the whole point:
+ * a stored loadout is then the entire truth about what an avatar wears, and no
+ * renderer has to guess whether an empty slot means "new player" or "wants
+ * nothing there". AUTH-223 is what guessing cost — the client synthesised the
+ * starting outfit whenever the loadout named nothing at all, so equipping a
+ * single item anywhere silently stripped the other two.
+ *
+ * Every slot is listed, `""` for the ones a player starts bare in, so
+ * `satisfies` makes a new slot a typecheck error here until someone has said
+ * what a new player wears in it. A slot {@link SLOTS} marks required must name
+ * an item: it is the value an unnamed slot falls back to, so a mandatory slot
+ * starting at `""` would be a refusal every new player is born holding.
+ */
+export declare const STARTING_OUTFIT: {
+    hair: string;
+    ears: string;
+    hat: string;
+    face: string;
+    top: string;
+    bottom: string;
+    feet: string;
+};
+export declare function cosmeticById(id: string, catalog?: Catalog): CosmeticItem | undefined;
+export declare function cosmeticsForSlot(slot: CosmeticSlot, catalog?: Catalog): readonly CosmeticItem[];
+/**
+ * Every region an item occupying `regions` cannot share a body with: those
+ * regions themselves, plus everything each of them overlaps.
+ *
+ * Closing the set here is what lets a client grey out an impossible pick
+ * without a copy of {@link REGION_OVERLAPS}. The schema projects this per
+ * catalog item, so a collision becomes a set intersection: nothing to
+ * symmetrise, and no room to assume overlap is transitive (it is not). A
+ * mirrored vocabulary is what AUTH-210 cost.
+ */
+export declare function conflictingRegions(regions: readonly EquipRegion[]): readonly EquipRegion[];
+/**
+ * The first region two items both occupy, or null. A region trivially occupies
+ * itself, so "sharing a region" and "occupying overlapping regions" are the
+ * same check rather than two rules that can drift apart.
+ *
+ * Resolved through {@link conflictingRegions}, so the rule the save path
+ * enforces and the projection a client greys out from are ONE function rather
+ * than two that happen to agree today.
+ */
+export declare function sharedRegion(a: readonly EquipRegion[], b: readonly EquipRegion[]): EquipRegion | null;
+/** The first pair of equipped items whose regions collide, or null. THE rule. */
+export declare function equipConflict(settings: Settings, catalog?: Catalog): EquipConflict | null;
+/**
+ * The first mandatory slot the loadout explicitly empties, or null.
+ *
+ * Explicitly is the whole subtlety: `""` is the unequip verb, while a slot the
+ * blob never names falls back to its default — the starting outfit, which fills
+ * every mandatory slot. So this refuses the request that undresses an avatar
+ * and never a partial patch that simply did not mention the slot.
+ *
+ * A slot the catalog sells nothing for is exempt for the same reason it is not
+ * a setting: there is nothing to put in it, so demanding one would lock every
+ * save out until content lands.
+ */
+export declare function bareSlot(settings: Settings, catalog?: Catalog): CosmeticSlot | null;
+/**
+ * The appearance surface's cross-field rule as the registry consumes it. Wired
+ * onto the surface rather than called from a route, so every write path gets
+ * it by construction.
+ *
+ * Two rules, one hook: a pair of items that cannot share a body, and a slot an
+ * avatar may not go without. Both are relations over the whole loadout rather
+ * than properties of one key, which is why neither can live in `sanitize`.
+ */
+export declare function appearanceConflict(settings: Settings, catalog?: Catalog): SettingsConflict | null;
+/**
+ * The `appearance` key holding one item's colour for one of its materials.
+ *
+ * Segmented rather than opaque so it can GROW without a second key space:
+ * GAME-178 paints a masked region of an item instead of its whole surface,
+ * which is one more segment here. The separator is legal in a JSON key and
+ * illegal in an id and a material name, which `cosmetics.test.ts` enforces —
+ * without that a key would be ambiguous the day someone names an item
+ * `round.glasses`.
+ */
+export declare function paintKey(itemId: string, material: CosmeticMaterial): string;
+/**
+ * Every recolourable surface the equipped set exposes, in slot order: one
+ * entry per paintable material on each worn item.
+ *
+ * This is what makes the appearance surface dynamic — the colour pickers a
+ * player sees are a function of what they are wearing, so a colour cannot
+ * outlive the item it painted.
+ */
+export declare function paintSlots(settings: Settings, catalog?: Catalog): PaintSlot[];
+/**
+ * The equipped set as `/api/session/verify` hands it to a game server: the
+ * items that render, each carrying the regions it occupies, the body it
+ * suppresses, and the paint to apply to it.
+ */
+export declare function equippedFor(settings: Settings, catalog?: Catalog): EquippedCosmetics;