Account Linking

# Steam. This one variable is enough.
ACCOUNT_LINK_ALLOWED_ORIGINS=https://yourgame.com

# Twitch. BOTH are required, or it does not register.
ACCOUNT_LINK_TWITCH_CLIENT_ID=...
ACCOUNT_LINK_TWITCH_CLIENT_SECRET=...

# Optional. Widens Steam with persona name and avatar.
STEAM_WEB_API_KEY=...

curl -X POST $API/v1/accounts/mint-link \
  -H "Authorization: Bearer $SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider":"steam","email":"player@example.com"}'

{ "url": "https://api.yourgame.com/v1/accounts/steam/start?t=...", "expiresAt": "..." }

// version is a decimal STRING, because the column is a Postgres bigint.
if (BigInt(incoming.version) > BigInt(stored.version)) {
  await upsert(incoming);
}

import { contacts, type Database } from "@hogsend/db";
import { createHogsendClient, type AccountLinkHooks } from "@hogsend/engine";
import { eq, sql } from "drizzle-orm";

// The hooks are passed INTO createHogsendClient, which is what builds `db`, so
// they read a deferred handle wired after the client exists.
let dbHandle: Database | undefined;
export function setAccountLinkDb(db: Database): void {
  dbHandle = db;
}

export const accountLinkHooks: AccountLinkHooks = {
  // Post-commit, at-least-once, fail-open, bounded at 5s. Idempotent by
  // construction: one UPDATE setting the same keys to the same values.
  async afterLink(ctx) {
    if (!dbHandle) return;
    const patch = {
      [`${ctx.provider}_user_id`]: ctx.identity.providerUserId,
      [`${ctx.provider}_username`]: ctx.identity.username ?? null,
      // The bigint version as a STRING. Never parseInt it.
      [`${ctx.provider}_link_version`]: ctx.version,
    };
    await dbHandle
      .update(contacts)
      .set({
        properties: sql`jsonb_strip_nulls(COALESCE(${contacts.properties}, '{}'::jsonb) || ${JSON.stringify(patch)}::jsonb)`,
      })
      .where(eq(contacts.id, ctx.contactId));
  },
};

const client = createHogsendClient({
  accountLinks: {
    hooks: accountLinkHooks,
    allowedOrigins: ["https://play.yourgame.com"],
  },
});
setAccountLinkDb(client.db);

import { AccountLinkCallbackError, oauth2Link } from "@hogsend/engine";

export const battlenet = oauth2Link({
  meta: { id: "battlenet", name: "Battle.net" },
  authorizeEndpoint: "https://oauth.battle.net/authorize",
  tokenEndpoint: "https://oauth.battle.net/token",
  clientId: process.env.BATTLENET_CLIENT_ID ?? "",
  clientSecret: process.env.BATTLENET_CLIENT_SECRET ?? "",
  scopes: ["openid"],
  usePkce: true,
  userInfo: {
    url: "https://oauth.battle.net/oauth/userinfo",
    // MUST pick the platform's immutable id. `sub` is the account id;
    // `battletag` is a renameable handle, so it is display data only.
    map: (json) => {
      const profile = json as { sub?: string; battletag?: string };
      if (!profile.sub) {
        throw new AccountLinkCallbackError(
          "exchange_failed",
          "userinfo carried no sub",
        );
      }
      return {
        providerUserId: profile.sub,
        ...(profile.battletag ? { username: profile.battletag } : {}),
      };
    },
  },
});

// The verified account.linked / account.unlinked payload, narrowed to the
// fields a mirror needs.
interface AccountEvent {
  state: "linked" | "unlinked";
  provider: string;
  providerUserId: string;
  contactId: string;
  // A decimal string, because the column is a Postgres bigint.
  version: string;
}

export async function handleAccountEvent(event: AccountEvent) {
  const stored = await db.playerAccount.findUnique({
    where: {
      provider_providerUserId: {
        provider: event.provider,
        providerUserId: event.providerUserId,
      },
    },
  });

  // DISCARD. A duplicate, a reordered pair and a late delivery all land here.
  if (stored && BigInt(event.version) <= BigInt(stored.version)) {
    return "discarded";
  }

  // APPLY. Keyed on the pair, never on contactId: a relink moves the pair
  // between contacts and both mutations share one version sequence.
  await db.playerAccount.upsert({
    where: {
      provider_providerUserId: {
        provider: event.provider,
        providerUserId: event.providerUserId,
      },
    },
    create: {
      provider: event.provider,
      providerUserId: event.providerUserId,
      state: event.state,
      contactId: event.contactId,
      version: event.version,
    },
    update: {
      state: event.state,
      contactId: event.contactId,
      version: event.version,
    },
  });
  return "applied";
}

import { contacts } from "@hogsend/db";
import { defineWebhookSource, getLiveLink } from "@hogsend/engine";
import { eq } from "drizzle-orm";
import { z } from "zod";

export const gameServerSource = defineWebhookSource({
  meta: { id: "game-server", name: "Game server" },
  auth: {
    type: "match",
    header: "x-game-server-secret",
    envKey: "GAME_SERVER_WEBHOOK_SECRET",
  },
  schema: z.object({
    steamId: z.string().regex(/^\d{17}$/),
    event: z.string(),
  }),
  async transform(payload, ctx) {
    const link = await getLiveLink({
      db: ctx.db,
      provider: "steam",
      providerUserId: payload.steamId,
    });
    // No link means we do not know who this is. A SteamID is not a contact.
    if (!link) return null;

    const [contact] = await ctx.db
      .select()
      .from(contacts)
      .where(eq(contacts.id, link.contactId))
      .limit(1);
    if (!contact) return null;

    return {
      event: payload.event,
      // The canonical contact key: external_id ?? anonymous_id ?? id.
      userId: contact.externalId ?? contact.anonymousId ?? contact.id,
      ...(contact.email ? { userEmail: contact.email } : {}),
      eventProperties: { steam_id: payload.steamId },
    };
  },
});

# Who owns this platform account right now?
curl $API/v1/accounts/steam/76561197960287930 -H "Authorization: Bearer $SECRET_KEY"

# Every live link for a contact.
curl "$API/v1/accounts?email=player@example.com" -H "Authorization: Bearer $SECRET_KEY"