yt_cli 2.3.0+1: security hardening, CLI example, doc improvements

- Add SecurityUtil for path validation, JSON schema validation, OAuth callback validation, and token file permissions
- Replace example/yt_cli_example.dart with example/README.md showing CLI usage
- Update CHANGELOG.md with current version
- Add Activities API command
- Update .pubignore to exclude doc/ and *.iml

Author: cdavis-code

packages/yt_cli/.pubignore

@@ -1,3 +1,5 @@
 client_secret.json
 youtube_server_tokens.json
 .dart_tool/
+doc/
+*.iml

packages/yt_cli/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 2.3.0+1
+
+### Changed
+- Security hardening: path validation, token file permissions, credential JSON schema validation, OAuth callback validation
+- example/ replaced with README.md showing CLI usage examples
+
+## 2.3.0
+
+### Added
+- Activities API command (`yt activities list`)
+
+### Changed
+- Depends on yt ^2.3.0
+
 ## 2.2.6+5
 
 * publication readiness: LICENSE, .pubignore, topics, funding, version sync

packages/yt_cli/README.md

@@ -61,6 +61,7 @@ yt videos --help
 ## Features
 
 - OAuth 2.0 web flow authorization with automatic token refresh
+- Query channel activity events (uploads, likes, subscriptions, etc.)
 - Query YouTube Analytics reports (views, watch time, demographics, and more)
 - Manage analytics groups and group items for organizing channels, videos, or playlists
 - Full CRUD for channels, playlists, videos, comments, and subscriptions
@@ -76,6 +77,7 @@ Run `yt --help` for the full list. Key commands:
 
 | Command | Description |
 |---------|-------------|
+| `activities` | List channel activity events |
 | `analytics` | YouTube Analytics reports, groups, and group items |
 | `authorize` | OAuth 2.0 web flow to authorize the CLI |
 | `broadcast` | Manage live broadcasts |
@@ -137,4 +139,4 @@ Any help from the open-source community is always welcome:
 
 ## License
 
-MIT License - see [LICENSE] for details.
+MIT License - see [LICENSE](LICENSE) for details.

packages/yt_cli/bin/yt.dart

@@ -12,6 +12,7 @@ void main(List<String> arguments) async {
       allowed: ['all', 'debug', 'info', 'warning', 'error', 'off'],
       defaultsTo: 'off',
     )
+    ..addCommand(YoutubeActivitiesCommand())
     ..addCommand(YoutubeAnalyticsCommand())
     ..addCommand(YoutubeAuthorizeCommand())
     ..addCommand(YoutubeBroadcastCommand())

packages/yt_cli/example/README.md

@@ -0,0 +1,41 @@
+# yt_cli Examples
+
+## Authorize the CLI
+
+```sh
+# Download client_secret.json from Google Cloud Console
+yt authorize
+```
+
+This opens a browser for OAuth 2.0 authorization. After approving, a refresh
+token is saved locally so subsequent runs are unattended.
+
+## Common commands
+
+```sh
+# Upload a video
+yt videos insert \
+  --video-file my_video.mp4 \
+  --part snippet \
+  --notify-subscribers true \
+  --body '{"snippet":{"title":"My Video","description":"Hello world!"}}'
+
+# Set a custom thumbnail
+yt thumbnails set \
+  --video-id YOUR_VIDEO_ID \
+  --file thumbnail.jpg
+
+# Search for videos
+yt search \
+  --q "Dart programming" \
+  --part snippet \
+  --max-results 5
+
+# List your channels
+yt channels list \
+  --mine true \
+  --part snippet
+```
+
+Run `yt --help` or `yt <command> --help` for the full list of available
+commands and their options.

packages/yt_cli/lib/meta.dart

@@ -6,5 +6,5 @@ library;
 import 'dart:convert' show json;
 
 final pubSpec = json.decode(
-  '{"name":"yt_cli","version":"2.2.6+6","description":"A CLI tool for the YouTube Data, Live Streaming, and Analytics APIs.","homepage":"https://github.com/cdavis-code/yt_workspace","repository":"https://github.com/cdavis-code/yt_workspace/tree/main/packages/yt_cli","issue_tracker":"https://github.com/cdavis-code/yt_workspace/issues"}',
+  '{"name":"yt_cli","version":"2.3.0+1","description":"A CLI tool for the YouTube Data, Live Streaming, and Analytics APIs.","homepage":"https://github.com/cdavis-code/yt_workspace","repository":"https://github.com/cdavis-code/yt_workspace/tree/main/packages/yt_cli","issue_tracker":"https://github.com/cdavis-code/yt_workspace/issues"}',
 );

packages/yt_cli/lib/src/cmd/youtube_activities_command.dart

@@ -0,0 +1,108 @@
+import 'package:args/command_runner.dart';
+import 'package:dio/dio.dart';
+import 'package:yt/yt.dart';
+
+import 'youtube_helper_command.dart';
+
+/// An activity resource contains information about an action that a particular
+/// channel, or user, has taken on YouTube.
+class YoutubeActivitiesCommand extends Command<void> {
+  @override
+  String get description =>
+      'An activity resource contains information about an action that a particular channel, or user, has taken on YouTube.';
+
+  @override
+  String get name => 'activities';
+
+  YoutubeActivitiesCommand() {
+    addSubcommand(YoutubeListActivitiesCommand());
+  }
+}
+
+/// Returns a list of channel activity events that match the request criteria.
+class YoutubeListActivitiesCommand extends YtHelperCommand {
+  @override
+  String get description =>
+      'Returns a list of channel activity events that match the request criteria.';
+
+  @override
+  String get name => 'list';
+
+  YoutubeListActivitiesCommand() {
+    argParser
+      ..addOption(
+        'part',
+        defaultsTo: 'snippet,contentDetails',
+        help:
+            'The part parameter specifies the activity resource parts that the API response will include.',
+      )
+      ..addOption(
+        'channel-id',
+        valueHelp: 'YouTube channel id',
+        help:
+            'The channelId parameter specifies a unique YouTube channel ID. The API will then return a list of that channel\'s activities.',
+      )
+      ..addFlag(
+        'mine',
+        defaultsTo: false,
+        negatable: false,
+        help:
+            'This parameter can only be used in a properly authorized request. Set this parameter\'s value to true to retrieve a feed of the authenticated user\'s activities.',
+      )
+      ..addOption(
+        'max-results',
+        defaultsTo: '5',
+        valueHelp: 'number',
+        help:
+            'The maxResults parameter specifies the maximum number of items that should be returned in the result set. Acceptable values are 1 to 50, inclusive. The default value is 5.',
+      )
+      ..addOption(
+        'page-token',
+        valueHelp: 'token',
+        help:
+            'The pageToken parameter identifies a specific page in the result set that should be returned.',
+      )
+      ..addOption(
+        'published-after',
+        valueHelp: 'date',
+        help:
+            'The publishedAfter parameter specifies the earliest date and time that an activity could have occurred for that activity to be included in the API response. The value is an RFC 3339 formatted date-time value (1970-01-01T00:00:00Z).',
+      )
+      ..addOption(
+        'published-before',
+        valueHelp: 'date',
+        help:
+            'The publishedBefore parameter specifies the date and time before which an activity must have occurred for that activity to be included in the API response. The value is an RFC 3339 formatted date-time value (1970-01-01T00:00:00Z).',
+      )
+      ..addOption(
+        'region-code',
+        valueHelp: 'code',
+        help:
+            'The regionCode parameter instructs the API to return results for the specified country. The parameter value is an ISO 3166-1 alpha-2 country code.',
+      );
+  }
+
+  @override
+  void run() async {
+    await initializeYt();
+
+    try {
+      final response = await activities.list(
+        part: argResults!['part'],
+        channelId: argResults?['channel-id'],
+        mine: argResults?.flag('mine') == true ? true : null,
+        maxResults: int.tryParse(argResults?['max-results'] ?? ''),
+        pageToken: argResults?['page-token'],
+        publishedAfter: argResults?['published-after'],
+        publishedBefore: argResults?['published-before'],
+        regionCode: argResults?['region-code'],
+      );
+
+      print(response);
+
+      close();
+    } on DioException catch (err) {
+      throw UsageException('API usage error:', err.usage);
+    }
+  }
+}

packages/yt_cli/lib/src/cmd/youtube_analytics_command.dart

@@ -6,6 +6,10 @@ import 'package:yt/yt.dart';
 
 import 'youtube_helper_command.dart';
 
+/// Root command for YouTube Analytics operations.
+///
+/// Provides access to analytics reports, groups, and group items
+/// for measuring channel performance and audience engagement.
 class YoutubeAnalyticsCommand extends Command<void> {
   @override
   String get description =>
@@ -23,6 +27,10 @@ class YoutubeAnalyticsCommand extends Command<void> {
 
 // -- Reports --
 
+/// Command group for querying YouTube Analytics reports.
+///
+/// Subcommands allow retrieving metrics like views, watch time,
+/// and audience demographics for channels or content owners.
 class YoutubeAnalyticsReportsCommand extends Command<void> {
   @override
   String get description => 'Query YouTube Analytics reports for a channel.';
@@ -35,6 +43,11 @@ class YoutubeAnalyticsReportsCommand extends Command<void> {
   }
 }
 
+/// Query YouTube Analytics reports with custom metrics and dimensions.
+///
+/// Retrieves analytics data such as views, estimated minutes watched,
+/// subscribers gained, and other performance metrics for a specified
+/// time period and channel.
 class AnalyticsReportsQueryCommand extends YtHelperCommand {
   @override
   String get description =>
@@ -142,6 +155,10 @@ class AnalyticsReportsQueryCommand extends YtHelperCommand {
 
 // -- Groups --
 
+/// Command group for managing YouTube Analytics groups.
+///
+/// Analytics groups allow organizing channels, videos, playlists,
+/// or assets for consolidated reporting and analysis.
 class YoutubeAnalyticsGroupsCommand extends Command<void> {
   @override
   String get description =>
@@ -158,6 +175,10 @@ class YoutubeAnalyticsGroupsCommand extends Command<void> {
   }
 }
 
+/// Retrieve a list of analytics groups for the authenticated user.
+///
+/// Lists all groups created by the authorized channel or content owner,
+/// with optional filtering by group type and pagination support.
 class GroupsListCommand extends YtHelperCommand {
   @override
   String get description =>

packages/yt_cli/lib/src/cmd/youtube_authorize_command.dart

@@ -1,15 +1,15 @@
-import 'dart:convert';
-
 import 'package:args/command_runner.dart';
 import 'package:oauth2/oauth2.dart' as oauth2;
 import 'package:universal_io/io.dart';
 
+import '../util/security_util.dart';
+
 /// Generate a refresh token used to authenticate the command line API
 /// requests.
 ///
 /// Uses an OAuth 2.0 web flow that captures a permanent Refresh Token for
 /// unattended server-side operation. See the setup guide for details on
-/// obtaining a [client_secret.json] file from the Google Cloud Console.
+/// obtaining a `client_secret.json` file from the Google Cloud Console.
 class YoutubeAuthorizeCommand extends Command<void> {
   static const _guideUrl =
       'https://github.com/faithoflifedev/yt/blob/main/packages/yt_cli/authentication.md';
@@ -49,11 +49,16 @@ class YoutubeAuthorizeCommand extends Command<void> {
     final overwrite = argResults!['overwrite-credentials'] as bool;
     final credentialsFilePath = argResults!['credentials-file'] as String;
 
-    final secretFile = File(credentialsFilePath);
-    if (!await secretFile.exists()) {
+    final File secretFile;
+    try {
+      secretFile = await SecurityUtil.validateInputFile(
+        credentialsFilePath,
+        argName: 'credentials-file',
+      );
+    } on FormatException catch (e) {
       print(
-        'Error: Could not find "$credentialsFilePath".\n'
-        'Download it from the Google Cloud Console Credentials page.\n'
+        'Error: ${e.message}\n'
+        'Download client_secret.json from the Google Cloud Console Credentials page.\n'
         'See the setup guide above for step-by-step instructions.',
       );
       exit(1);
@@ -67,13 +72,16 @@ class YoutubeAuthorizeCommand extends Command<void> {
       return;
     }
 
-    // Parse the Google Cloud Console credentials JSON.
-    final jsonString = await secretFile.readAsString();
-    final Map<String, dynamic> parsedJson = jsonDecode(jsonString);
-
-    // The JSON wraps credentials under "web" or "installed".
-    final String rootKey = parsedJson.containsKey('web') ? 'web' : 'installed';
-    final Map<String, dynamic> config = parsedJson[rootKey];
+    // Parse and validate the Google Cloud Console credentials JSON.
+    final Map<String, dynamic> config;
+    try {
+      config = SecurityUtil.parseAndValidateClientSecret(
+        await secretFile.readAsString(),
+      );
+    } on FormatException catch (e) {
+      print('Error: ${e.message}');
+      exit(1);
+    }
 
     final clientId = config['client_id'] as String;
     final clientSecret = config['client_secret'] as String;
@@ -124,6 +132,24 @@ class YoutubeAuthorizeCommand extends Command<void> {
     final request = await server.first;
     final callbackUri = request.uri;
 
+    // Validate the callback path matches the registered redirect URI and
+    // that an authorization code was returned without an error.
+    try {
+      SecurityUtil.validateOAuthCallback(
+        callback: callbackUri,
+        expectedRedirect: redirectUrl,
+      );
+    } on FormatException catch (e) {
+      request.response
+        ..statusCode = HttpStatus.badRequest
+        ..headers.contentType = ContentType.html
+        ..write('<h1>Authorization failed</h1><p>${e.message}</p>');
+      await request.response.close();
+      await server.close();
+      print('Error: ${e.message}');
+      exit(1);
+    }
+
     // Send a friendly success page back to the browser.
     request.response
       ..statusCode = HttpStatus.ok
@@ -140,8 +166,10 @@ class YoutubeAuthorizeCommand extends Command<void> {
       callbackUri.queryParameters,
     );
 
-    // Persist credentials so subsequent runs are fully automatic.
+    // Persist credentials so subsequent runs are fully automatic, then
+    // restrict the token file to owner read/write only on POSIX.
     await tokenStorageFile.writeAsString(client.credentials.toJson());
+    await SecurityUtil.restrictFilePermissions(tokenStorageFile);
 
     print('');
     print('Authorization completed.');