@hraness/ghostget 0.17.2

package/src/providers/twitch-web-runtime.ts

@@ -0,0 +1,226 @@
+import type { GhostgetAuth } from "../auth";
+import { canonicalJson } from "../canonical-json";
+import type { OperationInput, WebSessionRecipe } from "../model";
+import {
+  createWebSessionClient,
+  webSessionAuthSubject,
+  webSessionCookie,
+  type WebSessionClient,
+  type WebSessionNetworkDependencies,
+} from "../web-session-client";
+import type {
+  WebSessionDispatchEvent,
+  WebSessionExecution,
+  WebSessionOperationDeadline,
+} from "../web-session-execution";
+import { failedProviderRead, type ProviderReadFailureStage } from "./read-failure";
+import {
+  TWITCH_GQL_ORIGIN,
+  TWITCH_GQL_PATH,
+  TWITCH_WEB_CLIENT_ID,
+  TWITCH_WEB_OPERATIONS,
+  parseTwitchCurrentViewerResponse,
+  parseTwitchProfileResponse,
+  projectTwitchProfileStats,
+  twitchCurrentViewerRequest,
+  twitchLogin,
+  twitchProfileRequest,
+  TwitchProfileTargetUnavailableError,
+  TwitchViewerAuthRepairRequiredError,
+  type TwitchPersistedQueryRequest,
+  type TwitchViewer,
+} from "./twitch-web";
+
+const MAX_TWITCH_RESPONSE_BYTES = 256 * 1024;
+
+export type TwitchWebRuntimeDependencies =
+  Partial<WebSessionNetworkDependencies> & {
+    readonly now?: () => number;
+  };
+
+function exactProfileInput(input: OperationInput): string {
+  const keys = Object.keys(input);
+  if (keys.length !== 1 || keys[0] !== "profile") {
+    throw new Error("Twitch profiles.read accepts only input.profile");
+  }
+  return twitchLogin(input.profile, "input.profile");
+}
+
+function twitchAuthToken(client: WebSessionClient): string {
+  const token = webSessionCookie(client.cookies, "auth-token");
+  if (!/^[A-Za-z0-9._~-]{16,512}$/u.test(token)) {
+    throw new Error("Twitch auth-token cookie did not match the reviewed credential shape");
+  }
+  return token;
+}
+
+function twitchHeaders(
+  client: WebSessionClient,
+  referer: string,
+): Readonly<Record<string, string>> {
+  if (!/^[a-z0-9]{20,64}$/u.test(TWITCH_WEB_CLIENT_ID)) {
+    throw new Error("Twitch web client ID is not reviewed");
+  }
+  const token = twitchAuthToken(client);
+  return Object.freeze({
+    accept: "*/*",
+    authorization: `OAuth ${token}`,
+    "client-id": TWITCH_WEB_CLIENT_ID,
+    "content-type": "text/plain",
+    referer,
+  });
+}
+
+async function requestTwitchBatch(
+  client: WebSessionClient,
+  request: readonly TwitchPersistedQueryRequest[],
+  referer: string,
+  maximumBytes: number,
+): Promise<unknown> {
+  return client.requestJson({
+    url: new URL(TWITCH_GQL_PATH, TWITCH_GQL_ORIGIN),
+    method: "POST",
+    headers: twitchHeaders(client, referer),
+    body: canonicalJson(request),
+    expectedStatuses: [200],
+    expectedContentTypes: ["application/json"],
+    maxBytes: Math.min(maximumBytes, MAX_TWITCH_RESPONSE_BYTES),
+  });
+}
+
+async function currentViewer(
+  client: WebSessionClient,
+): Promise<TwitchViewer> {
+  return parseTwitchCurrentViewerResponse(await requestTwitchBatch(
+    client,
+    twitchCurrentViewerRequest(),
+    "https://www.twitch.tv/",
+    MAX_TWITCH_RESPONSE_BYTES,
+  ));
+}
+
+function viewerSubject(viewer: TwitchViewer): string {
+  return `twitch:${viewer.id}`;
+}
+
+function requireBoundViewer(auth: GhostgetAuth, viewer: TwitchViewer): void {
+  const expected = webSessionAuthSubject(auth);
+  if (expected === null || !/^twitch:[1-9][0-9]{0,31}$/u.test(expected)) {
+    throw new Error(
+      "Twitch profile statistics require an auth locator bound to the exact viewer subject",
+    );
+  }
+  if (viewerSubject(viewer) !== expected) {
+    throw new Error(
+      "Twitch browser session viewer no longer matches the confirmed auth subject",
+    );
+  }
+}
+
+function observedAt(
+  dependencies: TwitchWebRuntimeDependencies | undefined,
+): string {
+  const now = dependencies?.now?.() ?? Date.now();
+  if (
+    !Number.isSafeInteger(now)
+    || now < 0
+    || now > 8_640_000_000_000_000
+  ) {
+    throw new Error("Twitch profile observation time is invalid");
+  }
+  return new Date(now).toISOString();
+}
+
+export async function probeTwitchWebSubject(
+  auth: GhostgetAuth,
+  options: {
+    readonly timeoutMs?: number;
+    readonly dependencies?: TwitchWebRuntimeDependencies;
+    readonly signal?: AbortSignal;
+  } = {},
+): Promise<string> {
+  const client = await createWebSessionClient(TWITCH_GQL_ORIGIN, auth, {
+    timeoutMs: options.timeoutMs ?? 60_000,
+    ...(options.signal === undefined ? {} : { signal: options.signal }),
+    ...(options.dependencies === undefined
+      ? {}
+      : { dependencies: options.dependencies }),
+  });
+  return viewerSubject(await currentViewer(client));
+}
+
+export async function executeTwitchWebOperation(
+  recipe: WebSessionRecipe,
+  input: OperationInput,
+  auth: GhostgetAuth,
+  options: {
+    readonly signal?: AbortSignal;
+    readonly operationDeadline?: WebSessionOperationDeadline;
+    readonly beforeDispatch?: (
+      event: WebSessionDispatchEvent,
+    ) => Promise<void>;
+    readonly afterDispatchVerified?: (
+      event: WebSessionDispatchEvent,
+    ) => Promise<void>;
+    readonly dependencies?: TwitchWebRuntimeDependencies;
+  } = {},
+): Promise<WebSessionExecution> {
+  if (
+    recipe.site !== "twitch"
+    || recipe.action !== "profiles.read"
+    || recipe.contractVersion !== 1
+    || TWITCH_WEB_OPERATIONS["profiles.read"].state !== "observed"
+  ) {
+    throw new Error("Twitch authenticated profiles.read contract is not installed");
+  }
+  const profile = exactProfileInput(input);
+  // R1 performs no dispatch and never invokes mutation lifecycle callbacks.
+  void options.beforeDispatch;
+  void options.afterDispatchVerified;
+  const finalUrl = `https://www.twitch.tv/${profile}`;
+  let stage: ProviderReadFailureStage = "bootstrap";
+  try {
+    const client = await createWebSessionClient(TWITCH_GQL_ORIGIN, auth, {
+      timeoutMs: recipe.timeoutMs,
+      ...(options.signal === undefined ? {} : { signal: options.signal }),
+      ...(options.operationDeadline === undefined
+        ? {}
+        : { operationDeadline: options.operationDeadline }),
+      ...(options.dependencies === undefined
+        ? {}
+        : { dependencies: options.dependencies }),
+    });
+    stage = "identity";
+    const viewer = await currentViewer(client);
+    requireBoundViewer(auth, viewer);
+    stage = "target";
+    const response = await requestTwitchBatch(
+      client,
+      twitchProfileRequest(profile),
+      `${finalUrl}/about`,
+      recipe.maxOutputBytes,
+    );
+    const output = projectTwitchProfileStats(
+      parseTwitchProfileResponse(response, profile, viewer),
+      observedAt(options.dependencies),
+    );
+    return {
+      status: "succeeded",
+      output,
+      finalUrl: output.target.url,
+      dispatchStarted: false,
+      dispatch: { planned: 0, started: 0, verified: 0 },
+    };
+  } catch (error) {
+    return failedProviderRead("Twitch profile", error, finalUrl, {
+      stage,
+      authenticated: true,
+      accountMismatch: (candidate) => candidate.message.includes("no longer matches")
+        || candidate.message.includes("did not bind the current viewer ID"),
+      authRepairRequired: (candidate) => candidate.message.includes("auth-token cookie")
+        || candidate.message.includes("auth locator bound")
+        || candidate instanceof TwitchViewerAuthRepairRequiredError,
+      targetUnavailable: (candidate) => candidate instanceof TwitchProfileTargetUnavailableError,
+    });
+  }
+}

package/src/providers/twitch-web.ts

@@ -0,0 +1,274 @@
+/**
+ * Twitch authenticated-web profile statistics contract.
+ *
+ * This module owns the two fixed registered GraphQL operations and their
+ * bounded projections. It has no network access and never accepts an origin,
+ * path, header, raw GraphQL document, revision, or response selector from a
+ * caller.
+ */
+
+export const TWITCH_APP_ORIGIN = "https://www.twitch.tv";
+export const TWITCH_GQL_ORIGIN = "https://gql.twitch.tv";
+export const TWITCH_GQL_PATH = "/gql";
+
+export const TWITCH_WEB_OPERATION_NAMES = Object.freeze([
+  "profiles.read",
+] as const);
+
+export type TwitchWebOperationName =
+  (typeof TWITCH_WEB_OPERATION_NAMES)[number];
+
+export const TWITCH_WEB_OPERATIONS = Object.freeze({
+  "profiles.read": Object.freeze({
+    effect: "read" as const,
+    risk: "R1" as const,
+    state: "observed" as const,
+    reason:
+      "fixed authenticated current-viewer and target-bound About-panel registered queries project one exact follower count without acknowledgement side effects",
+  }),
+});
+
+// These fixed public web-client contract values come from the reviewed
+// first-party operations, never from caller input or runtime discovery.
+export const TWITCH_WEB_CLIENT_ID = "kimne78kx3ncx6brgo4mv6wki5h1ko";
+export const TWITCH_CURRENT_VIEWER_REVISION =
+  "6c870de60372d53089341c8af304c35c541754b72550eb2672224b017a39512e";
+export const TWITCH_ABOUT_PANEL_REVISION =
+  "3b9cd4edd28e8e6f7ba6152a56157bc2b1c1a8f6e81d70808ad1b85250e5288f";
+
+type JsonRecord = Record<string, unknown>;
+
+export type TwitchViewer = Readonly<{
+  id: string;
+}>;
+
+export type TwitchProfile = Readonly<{
+  id: string;
+  login: string;
+  followers: number;
+}>;
+
+type ExactCountMetric = Readonly<{
+  status: "available";
+  value: number;
+  precision: "exact";
+  unit: "count";
+}>;
+
+export type TwitchProfileStats = Readonly<{
+  schemaVersion: 1;
+  provider: "twitch";
+  target: Readonly<{
+    kind: "profile";
+    id: string;
+    url: string;
+  }>;
+  observedAt: string;
+  completeness: "complete";
+  metrics: Readonly<{
+    followers: ExactCountMetric;
+  }>;
+  metadata: Readonly<{
+    login: string;
+  }>;
+}>;
+
+export type TwitchPersistedQueryRequest = Readonly<{
+  operationName: "TopNav_CurrentUser" | "ChannelRoot_AboutPanel";
+  variables: Readonly<Record<string, string | boolean>>;
+  extensions: Readonly<{
+    persistedQuery: Readonly<{
+      version: 1;
+      sha256Hash: string;
+    }>;
+  }>;
+}>;
+
+function record(value: unknown, label: string): JsonRecord {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+  return value as JsonRecord;
+}
+
+function exactGraphQlResult(value: unknown, label: string): JsonRecord {
+  if (!Array.isArray(value) || value.length !== 1) {
+    throw new Error(`${label} must be one exact GraphQL batch result`);
+  }
+  const result = record(value[0], `${label}[0]`);
+  if (Object.hasOwn(result, "errors")) {
+    throw new Error(`${label} returned GraphQL errors`);
+  }
+  return record(result.data, `${label}[0].data`);
+}
+
+function twitchUserId(value: unknown, label: string): string {
+  if (
+    typeof value !== "string"
+    || !/^[1-9][0-9]{0,31}$/u.test(value)
+  ) {
+    throw new Error(`${label} must be one exact Twitch user ID`);
+  }
+  return value;
+}
+
+export function twitchLogin(
+  value: unknown,
+  label = "Twitch login",
+): string {
+  if (
+    typeof value !== "string"
+    || !/^[a-z0-9_]{4,25}$/u.test(value)
+  ) {
+    throw new Error(`${label} must be one exact lowercase Twitch login`);
+  }
+  return value;
+}
+
+function exactFollowerCount(value: unknown): number {
+  if (!Number.isSafeInteger(value) || (value as number) < 0) {
+    throw new Error("Twitch follower count must be an exact nonnegative safe integer");
+  }
+  return value as number;
+}
+
+function persistedQuery(
+  operationName: TwitchPersistedQueryRequest["operationName"],
+  variables: Readonly<Record<string, string | boolean>>,
+  revision: string,
+): TwitchPersistedQueryRequest {
+  if (!/^[a-f0-9]{64}$/u.test(revision)) {
+    throw new Error(`Twitch ${operationName} revision is not reviewed`);
+  }
+  return Object.freeze({
+    operationName,
+    variables,
+    extensions: Object.freeze({
+      persistedQuery: Object.freeze({ version: 1 as const, sha256Hash: revision }),
+    }),
+  });
+}
+
+/** Build the fixed one-entry current-viewer GraphQL batch. */
+export function twitchCurrentViewerRequest(): readonly TwitchPersistedQueryRequest[] {
+  return Object.freeze([
+    persistedQuery(
+      "TopNav_CurrentUser",
+      Object.freeze({}),
+      TWITCH_CURRENT_VIEWER_REVISION,
+    ),
+  ]);
+}
+
+/** Build the fixed one-entry About-panel GraphQL batch for one exact login. */
+export function twitchProfileRequest(
+  requestedLogin: unknown,
+): readonly TwitchPersistedQueryRequest[] {
+  const channelLogin = twitchLogin(requestedLogin, "requested Twitch login");
+  return Object.freeze([
+    persistedQuery(
+      "ChannelRoot_AboutPanel",
+      Object.freeze({ channelLogin, skipSchedule: true }),
+      TWITCH_ABOUT_PANEL_REVISION,
+    ),
+  ]);
+}
+
+/** Parse exactly one authenticated current-viewer result. */
+export class TwitchViewerAuthRepairRequiredError extends Error {
+  constructor() {
+    super("Twitch selected session is not signed in");
+    this.name = "TwitchViewerAuthRepairRequiredError";
+  }
+}
+
+export function parseTwitchCurrentViewerResponse(value: unknown): TwitchViewer {
+  const data = exactGraphQlResult(value, "Twitch current-viewer response");
+  if (data.currentUser === null) {
+    throw new TwitchViewerAuthRepairRequiredError();
+  }
+  const currentUser = record(
+    data.currentUser,
+    "Twitch current-viewer response[0].data.currentUser",
+  );
+  return Object.freeze({
+    id: twitchUserId(
+      currentUser.id,
+      "Twitch current-viewer response[0].data.currentUser.id",
+    ),
+  });
+}
+
+export class TwitchProfileTargetUnavailableError extends Error {
+  constructor() {
+    super("Twitch profile target is unavailable");
+    this.name = "TwitchProfileTargetUnavailableError";
+  }
+}
+
+/**
+ * Parse the fixed login-parameterized target response only after binding its
+ * immutable account ID to the already-probed viewer.
+ */
+export function parseTwitchProfileResponse(
+  value: unknown,
+  requestedLogin: unknown,
+  viewer: TwitchViewer,
+): TwitchProfile {
+  const login = twitchLogin(requestedLogin, "requested Twitch login");
+  const data = exactGraphQlResult(value, "Twitch profile response");
+  if (data.user === null) throw new TwitchProfileTargetUnavailableError();
+  const user = record(data.user, "Twitch profile response[0].data.user");
+  const responseId = twitchUserId(user.id, "Twitch profile response[0].data.user.id");
+  if (responseId !== viewer.id) {
+    throw new Error("Twitch profile response did not bind the current viewer ID");
+  }
+  const followers = record(
+    user.followers,
+    "Twitch profile response[0].data.user.followers",
+  );
+  return Object.freeze({
+    id: responseId,
+    login,
+    followers: exactFollowerCount(followers.totalCount),
+  });
+}
+
+function exactObservedAt(value: string): string {
+  if (
+    !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/u.test(value)
+    || !Number.isFinite(Date.parse(value))
+  ) {
+    throw new Error("Twitch statistics observedAt must be an exact UTC observation time");
+  }
+  return value;
+}
+
+/** Project only public target metadata and the exact target-bound count. */
+export function projectTwitchProfileStats(
+  profile: TwitchProfile,
+  observedAt: string,
+): TwitchProfileStats {
+  const login = twitchLogin(profile.login);
+  const followers = exactFollowerCount(profile.followers);
+  return Object.freeze({
+    schemaVersion: 1,
+    provider: "twitch",
+    target: Object.freeze({
+      kind: "profile",
+      id: twitchUserId(profile.id, "Twitch profile ID"),
+      url: `${TWITCH_APP_ORIGIN}/${login}`,
+    }),
+    observedAt: exactObservedAt(observedAt),
+    completeness: "complete",
+    metrics: Object.freeze({
+      followers: Object.freeze({
+        status: "available",
+        value: followers,
+        precision: "exact",
+        unit: "count",
+      }),
+    }),
+    metadata: Object.freeze({ login }),
+  });
+}

package/src/providers/whatsapp-account-identity.ts

@@ -0,0 +1,55 @@
+export type CanonicalWhatsAppAccountKind = "pn" | "lid";
+
+const CANONICAL_PN_ACCOUNT_PATTERN = /^[1-9][0-9]{4,14}$/u;
+const CANONICAL_LID_ACCOUNT_PATTERN = /^[1-9][0-9]{4,19}$/u;
+const CANONICAL_PARTICIPANT_JID_PATTERN =
+  /^([1-9][0-9]{4,14})(?::[0-9]{1,5})?@s\.whatsapp\.net$|^([1-9][0-9]{4,19})(?::[0-9]{1,5})?@lid$/u;
+
+export function isCanonicalWhatsAppAccountId(
+  kind: CanonicalWhatsAppAccountKind,
+  value: unknown,
+): value is string {
+  return typeof value === "string" && (
+    kind === "pn"
+      ? CANONICAL_PN_ACCOUNT_PATTERN.test(value)
+      : CANONICAL_LID_ACCOUNT_PATTERN.test(value)
+  );
+}
+
+export function isCanonicalWhatsAppAccountSubject(value: unknown): value is string {
+  if (typeof value !== "string") return false;
+  const match = /^whatsapp:(pn|lid):([0-9]+)$/u.exec(value);
+  const kind = match?.[1];
+  const account = match?.[2];
+  return (kind === "pn" || kind === "lid")
+    && account !== undefined
+    && isCanonicalWhatsAppAccountId(kind, account);
+}
+
+export function canonicalWhatsAppAccountSubjectJid(subject: unknown): string {
+  if (!isCanonicalWhatsAppAccountSubject(subject)) {
+    throw new Error("WhatsApp account subject is not canonical");
+  }
+  const match = /^whatsapp:(pn|lid):([0-9]+)$/u.exec(subject);
+  if (match?.[1] === undefined || match[2] === undefined) {
+    throw new Error("WhatsApp account subject is not canonical");
+  }
+  const [, kind, account] = match;
+  return kind === "pn"
+    ? `${account}@s.whatsapp.net`
+    : `${account}@lid`;
+}
+
+export function canonicalWhatsAppParticipantJid(value: unknown): string {
+  if (typeof value !== "string") {
+    throw new Error("WhatsApp participant JID is not canonical");
+  }
+  const match = CANONICAL_PARTICIPANT_JID_PATTERN.exec(value);
+  const account = match?.[1] ?? match?.[2];
+  if (account === undefined) {
+    throw new Error("WhatsApp participant JID is not canonical");
+  }
+  return match?.[1] === undefined
+    ? `${account}@lid`
+    : `${account}@s.whatsapp.net`;
+}