@hogsend/plugin-discord 0.22.0

package/src/connect/member-link.ts

@@ -0,0 +1,79 @@
+import type { DiscordCurrentUser } from "./oauth.js";
+
+/**
+ * The shape a per-member link reduces to: the args for a single
+ * `resolveOrCreateContact({ email?, discordId })` call (the consumer's
+ * `resolveContact` callback forwards it). No bespoke merge path — the engine's
+ * existing identity machinery folds the Discord-only contact onto the
+ * email/identified one (or fills `discord_id` in when only the email resolves).
+ */
+export interface DiscordMemberLink {
+  /** The Discord user the member linked. */
+  user: DiscordCurrentUser;
+}
+
+export interface MemberLinkContactPatch {
+  /**
+   * The RAW Discord snowflake — routed through the engine's `discord` identity
+   * Kind via `resolveOrCreateContact({ discordId })`, which makes the
+   * `discord_id` column load-bearing. NOT a `discord:`-prefixed `userId`: that
+   * stuffed the snowflake into `external_id`, leaving `discord_id` always NULL.
+   */
+  discordId: string;
+  contactProperties: Record<string, unknown>;
+}
+
+/**
+ * Map a member-link OAuth result → a contact patch.
+ *
+ * SECURITY — the Discord-reported email is NEVER a resolution/merge KEY here:
+ * the authoritative email is the one the link was ISSUED for (carried in the
+ * engine-verified `state.email`), so the connector passes THAT to
+ * `resolveContact`, not whatever Discord returns. The Discord-reported email is
+ * stored ONLY as a non-key `contactProperty` (`discordEmail`), and ONLY when
+ * Discord reports it present AND `verified === true` — an unverified email is
+ * dropped entirely. This closes the grafting/account-takeover vector where an
+ * attacker sets a Discord email matching a victim's contact to merge into it.
+ *
+ * `isDiscordLinked` is stamped `true` here — a successful per-member link is the
+ * ONLY thing that sets it (an unlinked Discord-only contact never gets it).
+ *
+ * The NON-KEY `properties.discord` metadata object (id/username/global_name/
+ * avatar) is populated from the `/users/@me` pull and deep-merges into whatever
+ * inbound events already accumulated (see `DEEP_MERGE_KEYS` in the engine's
+ * `lib/contacts.ts`); `last_seen` is NOT stamped here (a link is an identity
+ * attach, not activity). `isDiscordLinked` + `discordEmail` stay TOP-LEVEL flags
+ * (they are not part of the Discord-platform metadata object).
+ */
+export function memberLinkToContactPatch(
+  link: DiscordMemberLink,
+): MemberLinkContactPatch {
+  const { user } = link;
+  const verifiedEmail =
+    user.verified === true &&
+    typeof user.email === "string" &&
+    user.email.length > 0
+      ? user.email
+      : undefined;
+
+  const discord: Record<string, unknown> = { id: user.id };
+  if (typeof user.username === "string") discord.username = user.username;
+  if (typeof user.global_name === "string") {
+    discord.global_name = user.global_name;
+  }
+  if (typeof user.avatar === "string") discord.avatar = user.avatar;
+
+  const contactProperties: Record<string, unknown> = {
+    discord,
+    isDiscordLinked: true,
+  };
+  // Non-key property only — NEVER a resolution key (anti-graft, see above).
+  if (verifiedEmail) {
+    contactProperties.discordEmail = verifiedEmail;
+  }
+
+  return {
+    discordId: user.id,
+    contactProperties,
+  };
+}

package/src/connect/oauth.ts

@@ -0,0 +1,159 @@
+import {
+  DISCORD_API_BASE,
+  DISCORD_BOT_INSTALL_SCOPES,
+  DISCORD_MEMBER_LINK_SCOPES,
+  DISCORD_OAUTH_AUTHORIZE_URL,
+  DISCORD_OAUTH_TOKEN_URL,
+} from "../constants.js";
+
+/**
+ * Discord OAuth2 URL builders + the authorization-code exchange. `fetch`-only;
+ * zero `discord.js`. These run inside the engine API process (the connect flow
+ * + the connector's `oauthCallback` handler).
+ *
+ * SECURITY — both authorize-URL builders REQUIRE a `state`: the redirect lands
+ * UNAUTHENTICATED on `/v1/connectors/discord/oauth/callback`, so without a
+ * caller-minted, server-verified `state` an attacker could forge the callback
+ * (login-CSRF / grafting a Discord id onto an arbitrary contact). For the
+ * member-link flow the `state` MUST also bind the intended contact/email; the
+ * `oauthCallback` handler verifies `state` BEFORE exchanging the code.
+ */
+
+export interface BuildBotInstallUrlArgs {
+  applicationId: string;
+  /** Redirect URI registered on the app (…/v1/connectors/discord/oauth/callback). */
+  redirectUri: string;
+  /** Permissions bitfield the bot is requested with (stringified integer). */
+  permissions: string;
+  /** Opaque CSRF state the callback verifies. */
+  state: string;
+  /** Optional guild to pre-select in the install dialog. */
+  guildId?: string;
+}
+
+/**
+ * The one-click bot-install authorize URL. The single `redirectUri` is used
+ * verbatim (NO `flow` query) — the signed-state `purpose` (`install` |
+ * `member_link`) is what the `oauthCallback` branches on, and the exchange
+ * `redirect_uri` must byte-match this authorize value.
+ */
+export function buildBotInstallUrl(args: BuildBotInstallUrlArgs): string {
+  const url = new URL(DISCORD_OAUTH_AUTHORIZE_URL);
+  url.searchParams.set("client_id", args.applicationId);
+  url.searchParams.set("scope", DISCORD_BOT_INSTALL_SCOPES.join(" "));
+  url.searchParams.set("permissions", args.permissions);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("redirect_uri", args.redirectUri);
+  url.searchParams.set("state", args.state);
+  if (args.guildId) {
+    url.searchParams.set("guild_id", args.guildId);
+    url.searchParams.set("disable_guild_select", "true");
+  }
+  return url.toString();
+}
+
+export interface BuildMemberLinkUrlArgs {
+  applicationId: string;
+  redirectUri: string;
+  /** Opaque CSRF state — MUST bind the intended contact/email (see header). */
+  state: string;
+}
+
+/**
+ * The per-member link authorize URL. The single `redirectUri` is used verbatim
+ * (NO `flow` query) — the signed-state `purpose` disambiguates install vs.
+ * member at the callback, and the exchange `redirect_uri` must byte-match this
+ * authorize value.
+ */
+export function buildMemberLinkUrl(args: BuildMemberLinkUrlArgs): string {
+  const url = new URL(DISCORD_OAUTH_AUTHORIZE_URL);
+  url.searchParams.set("client_id", args.applicationId);
+  url.searchParams.set("scope", DISCORD_MEMBER_LINK_SCOPES.join(" "));
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("redirect_uri", args.redirectUri);
+  url.searchParams.set("state", args.state);
+  url.searchParams.set("prompt", "consent");
+  return url.toString();
+}
+
+/** Discord's token-endpoint response (subset; bot-install adds `guild`). */
+export interface DiscordTokenResponse {
+  access_token: string;
+  token_type: string;
+  expires_in: number;
+  refresh_token?: string;
+  scope: string;
+  /** Present on a bot-install grant — the guild the bot was added to. */
+  guild?: { id: string; name?: string };
+}
+
+export interface ExchangeDiscordCodeArgs {
+  applicationId: string;
+  clientSecret: string;
+  code: string;
+  /** MUST byte-match the `redirect_uri` sent on the authorize URL (no flow). */
+  redirectUri: string;
+}
+
+/**
+ * Exchange an authorization `code` for tokens at Discord's token endpoint.
+ * `application/x-www-form-urlencoded`, HTTP-Basic-free (client id + secret in
+ * the body, per Discord's docs). Throws on a non-2xx.
+ *
+ * SECRET HYGIENE — the thrown message carries ONLY the HTTP status + a short
+ * static reason. Discord's error body can echo the request (which contains the
+ * `client_secret`) or partial token material, so it is NEVER interpolated into
+ * the thrown message or logged.
+ */
+export async function exchangeDiscordCode(
+  args: ExchangeDiscordCodeArgs,
+): Promise<DiscordTokenResponse> {
+  const body = new URLSearchParams({
+    client_id: args.applicationId,
+    client_secret: args.clientSecret,
+    grant_type: "authorization_code",
+    code: args.code,
+    redirect_uri: args.redirectUri,
+  });
+
+  const res = await fetch(DISCORD_OAUTH_TOKEN_URL, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: body.toString(),
+  });
+
+  if (!res.ok) {
+    throw new Error(`Discord token exchange failed (${res.status})`);
+  }
+  return (await res.json()) as DiscordTokenResponse;
+}
+
+/** Discord `/users/@me` response subset — the member-link identity pull. */
+export interface DiscordCurrentUser {
+  id: string;
+  username?: string;
+  /** Discord's display name (the post-2023 unique-name system). */
+  global_name?: string | null;
+  /** Avatar hash (NOT a URL). */
+  avatar?: string | null;
+  email?: string | null;
+  /** TRUE iff Discord has verified the email — gate the link on this. */
+  verified?: boolean;
+}
+
+/**
+ * Fetch the authenticated user (member-link flow). Throws on a non-2xx with
+ * ONLY the HTTP status — the response/error body (and the Bearer token it
+ * pertains to) is never echoed into the thrown message or logged.
+ */
+export async function getCurrentUser(
+  accessToken: string,
+): Promise<DiscordCurrentUser> {
+  const res = await fetch(`${DISCORD_API_BASE}/users/@me`, {
+    headers: { Authorization: `Bearer ${accessToken}` },
+  });
+  if (!res.ok) {
+    throw new Error(`Discord /users/@me failed (${res.status})`);
+  }
+  return (await res.json()) as DiscordCurrentUser;
+}

package/src/connect/patch-application.ts

@@ -0,0 +1,67 @@
+import { DISCORD_API_BASE } from "../constants.js";
+
+/**
+ * Wire the Discord application server-side via `PATCH /applications/@me` (Bot
+ * auth). Sets the `interactions_endpoint_url` (and optional install params) so
+ * a fresh app is fully provisioned without portal clicking.
+ *
+ * IMPORTANT: Discord validates `interactions_endpoint_url` by synchronously
+ * PINGing it during the PATCH — the interactions route MUST be live and
+ * publicly reachable first, or the PATCH 400s. The caller (the `wire` admin
+ * route) refuses when `API_PUBLIC_URL` is loopback for exactly this reason.
+ *
+ * Idempotent: PATCHing the same values again is a no-op on Discord's side.
+ */
+
+export interface PatchApplicationArgs {
+  /** Bot token (used as `Bot <token>` — application-level config edits). */
+  botToken: string;
+  /** Public interactions URL (…/v1/connectors/discord/interactions). */
+  interactionsEndpointUrl: string;
+  /** Optional in-app install params (scopes + permissions bitfield). */
+  installParams?: { scopes: string[]; permissions: string };
+}
+
+export interface PatchApplicationResult {
+  applicationId: string;
+  interactionsEndpointUrl: string | null;
+}
+
+export async function patchApplication(
+  args: PatchApplicationArgs,
+): Promise<PatchApplicationResult> {
+  const payload: Record<string, unknown> = {
+    interactions_endpoint_url: args.interactionsEndpointUrl,
+  };
+  if (args.installParams) {
+    payload.install_params = {
+      scopes: args.installParams.scopes,
+      permissions: args.installParams.permissions,
+    };
+  }
+
+  const res = await fetch(`${DISCORD_API_BASE}/applications/@me`, {
+    method: "PATCH",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bot ${args.botToken}`,
+    },
+    body: JSON.stringify(payload),
+  });
+
+  if (!res.ok) {
+    // SECRET HYGIENE — status + a short static reason ONLY. The error body can
+    // echo back the request (carrying the `Bot` token) or app config; it is
+    // NEVER interpolated into the thrown message or logged.
+    throw new Error(`Discord PATCH /applications/@me failed (${res.status})`);
+  }
+
+  const app = (await res.json()) as {
+    id: string;
+    interactions_endpoint_url?: string | null;
+  };
+  return {
+    applicationId: app.id,
+    interactionsEndpointUrl: app.interactions_endpoint_url ?? null,
+  };
+}