feat(Innertube/HTTPClient): Add BotGuardManager and improve one-time context in HTTPClient

src/Innertube.ts

@@ -1,7 +1,7 @@
-import Session from './core/Session.js';
+import Session, { type ClientType } from './core/Session.js';
 
 import { Kids, Music, Studio } from './core/clients/index.js';
-import { AccountManager, InteractionManager, PlaylistManager } from './core/managers/index.js';
+import { AccountManager, BotGuardManager, InteractionManager, PlaylistManager } from './core/managers/index.js';
 import { Feed, TabbedFeed } from './core/mixins/index.js';
 
 import {
@@ -24,7 +24,7 @@ import NavigationEndpoint from './parser/classes/NavigationEndpoint.js';
 import type Format from './parser/classes/misc/Format.js';
 
 import * as Constants from './utils/Constants.js';
-import { generateRandomString, InnertubeError, throwIfMissing, u8ToBase64 } from './utils/Utils.js';
+import { generateRandomString, InnertubeError, parseLooseJSON, throwIfMissing, u8ToBase64 } from './utils/Utils.js';
 
 import type { ApiResponse } from './core/Actions.js';
 import type {
@@ -36,7 +36,7 @@ import type {
   InnerTubeConfig,
   SearchFilters
 } from './types/index.js';
-import type { IBrowseResponse, IParsedResponse } from './parser/index.js';
+import type { IBrowseResponse, IGetChallengeResponse, IParsedResponse, RawNode } from './parser/index.js';
 
 import {
   CommunityPostCommentsParam,
@@ -51,6 +51,7 @@ import {
   SearchFilter_Filters_UploadDate,
   SearchFilter_Prioritize
 } from '../protos/generated/misc/params.js';
+import { parseResponse } from './parser/parser.js';
 
 /**
  * Provides access to various services and modules in the YouTube API.
@@ -556,17 +557,46 @@ export default class Innertube {
   /**
    * Fetches an attestation challenge.
    */
-  async getAttestationChallenge(engagement_type: EngagementType, ids?: Record<string, any>[]) {
+  async getAttestationChallenge(engagement_type: EngagementType, ids?: Record<string, any>[], args?: {eacr_token?: string, client?: ClientType, eats?: string} ) {
     const payload: Record<string, any> = {
       engagementType: engagement_type
     };
 
     if (ids)
       payload.ids = ids;
+    if (args?.eacr_token)
+      payload.eacrToken = args.eacr_token;
+    if (args?.client)
+      payload.client = args.client;
+    if (args?.eats)
+      payload.one_time_context = { request: { eats: args.eats } };
 
     return this.actions.execute('/att/get', { parse: true, ...payload });
   }
 
+  async initialData(page_url: string) {
+    const url = new URL(page_url);
+    const inital_data = await this.session.http.fetch(url.pathname, {
+      method: 'GET',
+      baseURL: url.origin
+    });
+    const html = await inital_data.text();
+
+    const ytcfg_regex = /ytcfg\.set\(({.+?})\);/s;
+    const attestation_data_regex = /window\.ytAtN\(\s*({[\s\S]*?})\s*\)/;
+
+    const ytcfg_string = ytcfg_regex.exec(html)?.[1];
+    const attestation_data_string = attestation_data_regex.exec(html)?.[1];
+
+    const yt_atn: {R: RawNode, T: string}|null = attestation_data_string ? parseLooseJSON(attestation_data_string) : null;
+
+    return {
+      ytcfg: ytcfg_string ? JSON.parse(ytcfg_string) as RawNode : null,
+      atn: yt_atn?.R ? parseResponse<IGetChallengeResponse>(yt_atn.R) : null,
+      eacr_token: yt_atn ? yt_atn.T : null
+    };
+  }
+
   /**
    * Utility method to call an endpoint without having to use {@link Actions}.
    */
@@ -618,6 +648,13 @@ export default class Innertube {
     return new InteractionManager(this.#session.actions);
   }
 
+  /**
+   * An interface for interacting with BotGuard
+   */
+  get botguard() {
+    return new BotGuardManager(this);
+  }
+
   /**
    * An internal class used to dispatch requests.
    */

src/core/Actions.ts

@@ -13,7 +13,7 @@ import type {
 import { NavigateAction, Parser } from '../parser/index.js';
 import { InnertubeError } from '../utils/Utils.js';
 
-import type { Session } from './index.js';
+import type { PartialContext, Session } from './index.js';
 
 export interface ApiResponse {
   success: boolean;
@@ -83,21 +83,24 @@ export default class Actions {
     parse: true;
     protobuf?: false;
     serialized_data?: any;
-    skip_auth_check?: boolean
+    skip_auth_check?: boolean;
+    one_time_context?: PartialContext;
   }): Promise<ParsedResponse<T>>;
   async execute<T extends InnertubeEndpoint>(endpoint: T, args?: {
     [key: string]: any;
     parse?: false;
     protobuf?: true;
     serialized_data?: any;
-    skip_auth_check?: boolean
+    skip_auth_check?: boolean;
+    one_time_context?: PartialContext;
   }): Promise<ApiResponse>;
   async execute<T extends InnertubeEndpoint>(endpoint: T, args?: {
     [key: string]: any;
     parse?: boolean;
     protobuf?: boolean;
     serialized_data?: any;
-    skip_auth_check?: boolean
+    skip_auth_check?: boolean;
+    one_time_context?: PartialContext;
   }): Promise<ParsedResponse<T> | ApiResponse> {
     let data;
 

src/core/Session.ts

@@ -93,16 +93,43 @@ export type Context = {
     enableSafetyMode: boolean;
     lockedSafetyMode: boolean;
     onBehalfOfUser?: string;
+    delegationContext?: {
+      externalChannelId: string,
+      roleType: {
+        channelRoleType:
+        'CREATOR_CHANNEL_ROLE_TYPE_OWNER' | 'CREATOR_CHANNEL_ROLE_TYPE_MANAGER' | 'CREATOR_CHANNEL_ROLE_TYPE_EDITOR' | 'CREATOR_CHANNEL_ROLE_TYPE_EDITOR_LIMITED' |
+        'CREATOR_CHANNEL_ROLE_TYPE_SUBTITLE_EDITOR' | 'CREATOR_CHANNEL_ROLE_TYPE_VIEWER' | 'CREATOR_CHANNEL_ROLE_TYPE_VIEWER_LIMITED' | 'CREATOR_CHANNEL_ROLE_TYPE_UNSPECIFIED' |
+        'CREATOR_CHANNEL_ROLE_TYPE_MODERATOR' | 'CREATOR_CHANNEL_ROLE_TYPE_CUSTOM'
+      }
+    }
+    serializedDelegationContext?: string;
   };
   thirdParty?: {
     embedUrl: string;
   };
   request?: {
     useSsl: boolean;
     internalExperimentFlags: any[];
+    eats?: string;
+    returnLogEntry?: boolean;
+    sessionInfo?: { token: string };
+    attestationResponseData?: {
+      challenge: string;
+      webResponse: string;
+    };
+    reauthRequestInfo?: {
+      encodedReauthProofToken: string;
+    };
   };
 }
 
+export type PartialContext = {
+  client?: Partial<Context['client']>;
+  user?: Partial<Context['user']>;
+  thirdParty?: Partial<Context['thirdParty']>;
+  request?: Partial<Context['request']>;
+};
+
 type ContextData = {
   hl: string;
   gl: string;

src/core/managers/BotGuardManager.ts

@@ -0,0 +1,158 @@
+import type Innertube from '../../Innertube.js';
+import type RunAttestationCommand from '../../parser/classes/commands/RunAttestationCommand.js';
+import type { AttIdsRaw } from '../../parser/classes/commands/RunAttestationCommand.js';
+import type { IGetChallengeResponse, RawNode } from '../../parser/index.js';
+import type { BotGuardChallengeInfo, BotGuardSolver, BotGuardSolverChallenge } from '../../types/BotGuard.js';
+import type { EngagementType } from '../../types/Misc.js';
+import { InnertubeError } from '../../utils/Utils.js';
+import type { ClientType } from '../index.js';
+
+export interface ChallengeSolverArgsBase<T> {
+  content_binding?: T;
+  atn_page_url?: string;
+  eacr_token?: string;
+  eats?: string;
+  client?: ClientType;
+  ytcfg?: RawNode;
+}
+
+export interface ChallengeSolverArgsRunAttestationCommand<T> extends ChallengeSolverArgsBase<T> {
+  run_attestation_command: RunAttestationCommand;
+}
+
+export interface ChallengeSolverArgsEngagement<T> extends ChallengeSolverArgsBase<T> {
+  engagement_type: EngagementType;
+  ids: AttIdsRaw[];
+}
+
+export type ChallengeSolverArgs<T> = ChallengeSolverArgsEngagement<T> | ChallengeSolverArgsRunAttestationCommand<T>;
+
+export default class BotGuardManager {
+  readonly #innertube: Innertube;
+  #botguard_challenge_info_cache: Record<string, BotGuardChallengeInfo>;
+
+  constructor(innertube: Innertube) {
+    this.#innertube = innertube;
+    this.#botguard_challenge_info_cache = {};
+  }
+
+  #challengeExpired(challenge?: string) {
+    if (!challenge) return true;
+    const params = new URLSearchParams(challenge);
+    const issued_seconds = Number(params.get('c'));
+    const ttl_seconds = Number(params.get('t'));
+    if ((issued_seconds + ttl_seconds) * 1000 > Date.now()) return false;
+    return true;
+  }
+
+  #innerCacheKey(engagement_type: EngagementType, ids: AttIdsRaw[], atn_page_url?: string) {
+    return engagement_type + JSON.stringify(ids) + (atn_page_url ? atn_page_url : '');
+  }
+
+  #cleanCache() {
+    for (const key of Object.keys(this.#botguard_challenge_info_cache)) {
+      if (this.#challengeExpired(this.#botguard_challenge_info_cache[key].challenge)) {
+        delete this.#botguard_challenge_info_cache[key];
+      }
+    }
+  }
+
+  #insertCache<T>(challenge_info: BotGuardChallengeInfo, args: ChallengeSolverArgsEngagement<T>) {
+    this.#cleanCache();
+
+    const inner_cache_key = this.#innerCacheKey(args.engagement_type, args.ids, args.atn_page_url);
+    this.#botguard_challenge_info_cache[inner_cache_key] = challenge_info;
+  }
+
+  #checkCache<T>(args: ChallengeSolverArgsEngagement<T>): BotGuardChallengeInfo|null {
+    this.#cleanCache();
+
+    const inner_cache_key = this.#innerCacheKey(args.engagement_type, args.ids, args.atn_page_url);
+    if (!this.#challengeExpired(this.#botguard_challenge_info_cache[inner_cache_key]?.challenge))
+      return this.#botguard_challenge_info_cache[inner_cache_key];
+    return null;
+  }
+
+  #challengeResponseToBotGuardChallengeInfo(challenge_response: IGetChallengeResponse, ytcfg?: RawNode): BotGuardChallengeInfo {
+    if (!challenge_response.challenge) throw new InnertubeError('Failed to get API attestation challenge info');
+    if (challenge_response.bg_challenge) {
+      if (ytcfg) (challenge_response.bg_challenge as BotGuardSolverChallenge).ytcfg = ytcfg;
+      return challenge_response as BotGuardChallengeInfo;
+    }
+    if (challenge_response.botguard_data) return {
+      bg_challenge: {
+        global_name: 'trayride',
+        client_experiments_state_blob: '',
+        interpreter_hash: '',
+        interpreter_url: challenge_response.botguard_data.interpreter_url,
+        program: challenge_response.botguard_data.program,
+        ytcfg: ytcfg
+      },
+      challenge: challenge_response.challenge
+    };
+    throw new InnertubeError('Unable to parse challenge_response to botguard_challenge_info');
+  }
+
+  async #getApiChallenge<T>(args: ChallengeSolverArgsEngagement<T>): Promise<BotGuardChallengeInfo> {
+    const cache_check = this.#checkCache(args);
+    if (cache_check) return cache_check;
+
+    const challenge_response = await this.#innertube.getAttestationChallenge(args.engagement_type, args.ids, {
+      eacr_token: args.eacr_token,
+      client: args.client,
+      eats: args.eats
+    });
+    const botguard_challenge_info = this.#challengeResponseToBotGuardChallengeInfo(challenge_response, args.ytcfg);
+
+    this.#insertCache(botguard_challenge_info, args);
+    return botguard_challenge_info;
+  }
+  async #getPageChallenge<T>(args: ChallengeSolverArgsEngagement<T>): Promise<BotGuardChallengeInfo> {
+    if (!args.atn_page_url) throw new InnertubeError('Assertion failed; \'atn_page_url\' was supposed to not be empty');
+    const cache_check = this.#checkCache(args);
+    if (cache_check) return cache_check;
+
+    const initial_data = await this.#innertube.initialData(args.atn_page_url);
+    if (!initial_data.atn && !initial_data.eacr_token) throw new InnertubeError(`Was unable to find a challenge in atn_page_url: ${args.atn_page_url}`);
+    const challenge_response = initial_data.atn ?? await this.#getApiChallenge({ ...args, engagement_type: 'ENGAGEMENT_TYPE_UNBOUND', eacr_token: initial_data.eacr_token! });
+    const botguard_challenge_info = this.#challengeResponseToBotGuardChallengeInfo(challenge_response, initial_data.ytcfg ?? args.ytcfg);
+
+    this.#insertCache(botguard_challenge_info, args);
+    return botguard_challenge_info;
+  }
+
+  async getChallenge<T>(args: ChallengeSolverArgsEngagement<T>): Promise<BotGuardChallengeInfo> {
+    if (!args.atn_page_url) return await this.#getApiChallenge(args);
+    return await this.#getPageChallenge(args);
+  };
+
+  #normalizeChallengeSolverOpts<T>(args: ChallengeSolverArgs<T>): ChallengeSolverArgsEngagement<T> {
+    if (!('run_attestation_command' in args)) return args;
+    return {
+      engagement_type: args.run_attestation_command.engagement_type,
+      ids: args.run_attestation_command.raw_ids ?? [],
+      ...args
+    };
+  }
+
+  async run<T>(botguard_solver: BotGuardSolver<T>, args: ChallengeSolverArgs<T>) {
+    const challenge = await this.getChallenge(this.#normalizeChallengeSolverOpts(args));
+    return {
+      web_response: await botguard_solver.solve(challenge.bg_challenge, args.content_binding ?? challenge.challenge as T),
+      challenge
+    };
+  }
+
+  async log<T>(botguard_solver: BotGuardSolver<T>, args: ChallengeSolverArgs<T>) {
+    const normalized_opts = this.#normalizeChallengeSolverOpts(args);
+    const result = await this.run(botguard_solver, normalized_opts);
+    return await this.#innertube.actions.execute('/att/log', {
+      ...(args.client ? { client: args.client } : {}),
+      ...(args.eats ? { one_time_context: { request: { eats: args.eats } } } : {}),
+      challenge: result.challenge.challenge,
+      engagementType: normalized_opts.engagement_type,
+      ids: normalized_opts.ids,
+      webResponse: result.web_response
+    });
+  }
+}

src/core/managers/index.ts

@@ -1,3 +1,4 @@
 export { default as AccountManager } from './AccountManager.js';
 export { default as PlaylistManager } from './PlaylistManager.js';
-export { default as InteractionManager } from './InteractionManager.js';
+export { default as InteractionManager } from './InteractionManager.js';
+export { default as BotGuardManager } from './BotGuardManager.js';

src/parser/classes/commands/RunAttestationCommand.ts

@@ -1,3 +1,4 @@
+import type { EngagementType } from '../../../types/Misc.js';
 import { YTNode } from '../../helpers.js';
 import type { RawNode } from '../../types/index.js';
 
@@ -12,16 +13,29 @@ export type AttIds = {
   share_id?: string;
 }
 
+export type AttIdsRaw = {
+  encryptedVideoId?: string;
+  externalChannelId?: string;
+  commentId?: string;
+  externalOwnerId?: string;
+  artistId?: string;
+  playlistId?: string;
+  externalPostId?: string;
+  shareId?: string;
+}
+
 export default class RunAttestationCommand extends YTNode {
   static type = 'RunAttestationCommand';
-  
-  public engagement_type: string;
+
+  public engagement_type: EngagementType;
   public ids?: AttIds[];
+  public raw_ids?: AttIdsRaw[];
 
   constructor(data: RawNode) {
     super();
     this.engagement_type = data.engagementType;
     if (Reflect.has(data, 'ids')) {
+      this.raw_ids = data.ids;
       this.ids = data.ids.map((id: RawNode) => ({
         encrypted_video_id: id.encryptedVideoId,
         external_channel_id: id.externalChannelId,