@libai168/dsh-tool-google-drive 0.2.0 → 0.4.0

package/README.md

@@ -34,6 +34,8 @@ Recommended read-only OAuth scopes:
 - Docs read: `https://www.googleapis.com/auth/documents.readonly`
 - Sheets read: `https://www.googleapis.com/auth/spreadsheets.readonly`
 
+Both `baseUrl` and `tokenUrl` overrides must be absolute `http://` or `https://` root URLs. Only publicly reachable hosts are allowed: localhost, loopback, private, link-local, CGNAT, multicast, reserved/documentation/benchmark ranges, and every IANA special-purpose block are rejected, and a hostname whose DNS results contain any such address fails closed before the request is sent. Credentials, query strings, fragments, and non-root paths are not allowed.
+
 ## OAuth helper
 
 This package includes a small no-dependency helper that generates a Google OAuth consent URL, captures the loopback callback, exchanges the authorization code, and prints a ready-to-copy Cordis config snippet with a refresh token.
@@ -71,7 +73,7 @@ The helper requests offline access with consent prompting so Google can return a
 
 | Tool | Description | Write |
 |---|---|---|
-| `gdrive_auth_test` | Verify Google Drive credentials and return token metadata | no |
+| `gdrive_auth_test` | Verify Google Drive credentials without returning token material | no |
 | `gdrive_list_files` | List or search Drive files by query and pagination | no |
 | `gdrive_get_file` | Get one Drive file's metadata by file ID | no |
 | `gdrive_list_permissions` | List file/folder/shared-drive sharing permissions with pagination | no |
@@ -115,6 +117,8 @@ gsheets_get_values({ spreadsheetId: 'spreadsheet_id', range: 'Sheet1!A1:D20' })
 
 Permission and revision listings return an opaque `nextPageToken`; pass it back as `pageToken` to continue. `gdrive_list_permissions` can include shared-drive and domain-admin flags when the OAuth principal has those permissions. Permission email addresses, revision download URLs, and exported content are returned only by explicitly requested read tools; treat them as sensitive workspace data.
 
+Export, Docs, and Sheets content is bounded in the client result layer. Export output accepts maxBytes (default 1 MiB, capped at 10 MiB); Docs accepts maxBytes/maxTabs; Sheets accepts maxRows/maxColumns/maxCells. Results include truncated and contentLength so callers can detect an imposed limit.
+
 ## Development
 
 ```sh

package/README.zh.md

@@ -34,6 +34,8 @@ npm install @libai168/dsh-tool-google-drive
 - Docs 读取：`https://www.googleapis.com/auth/documents.readonly`
 - Sheets 读取：`https://www.googleapis.com/auth/spreadsheets.readonly`
 
+`baseUrl` 与 `tokenUrl` 两个覆盖都必须是绝对的 `http://` 或 `https://` 根地址。只允许公网可达主机：localhost、环回、私有、链路本地、CGNAT、组播、保留/文档/基准测试网段以及全部 IANA 特殊用途地址段都会被拒绝；DNS 结果包含任一此类地址时会在发出请求前 fail closed。不允许 credentials、query、fragment 或非根路径。
+
 ## OAuth 授权辅助脚本
 
 本包内置一个无额外依赖的辅助脚本：生成 Google OAuth 授权 URL、监听本机回调、用授权码换取 token，并输出可直接复制到 Cordis 配置里的 `refreshToken` 片段。
@@ -71,7 +73,7 @@ npm install @libai168/dsh-tool-google-drive
 
 | 工具 | 说明 | 写操作 |
 |---|---|---|
-| `gdrive_auth_test` | 验证 Google Drive 凭证并返回 token 元信息 | 否 |
+| `gdrive_auth_test` | 验证 Google Drive 凭证但不返回 token 内容 | 否 |
 | `gdrive_list_files` | 按查询与分页列出或搜索 Drive 文件 | 否 |
 | `gdrive_get_file` | 按文件 ID 获取 Drive 文件元数据 | 否 |
 | `gdrive_list_permissions` | 分页列出文件、文件夹或共享云端硬盘的共享权限 | 否 |
@@ -115,6 +117,8 @@ gsheets_get_values({ spreadsheetId: 'spreadsheet_id', range: 'Sheet1!A1:D20' })
 
 权限和修订列表会返回不透明的 `nextPageToken`；把它作为 `pageToken` 传回即可继续分页。`gdrive_list_permissions` 支持在 OAuth 主体具备权限时传入共享云端硬盘和域管理员参数。权限邮箱、修订下载 URL 以及导出内容只会由明确调用的只读工具返回，请将它们视为敏感工作区数据。
 
+导出、Docs 和 Sheets 内容会在客户端结果层限额。导出支持 maxBytes（默认 1 MiB，最多 10 MiB），Docs 支持 maxBytes/maxTabs，Sheets 支持 maxRows/maxColumns/maxCells。结果包含 truncated 和 contentLength，调用方可识别是否触发限额。
+
 ## 开发
 
 ```sh

package/lib/client.js

@@ -1,4 +1,5 @@
 /** Google Drive API client with injected fetch for testability. */
+import { assertSafeUrl, EndpointSecurityError, normalizeBaseUrl } from './url-security.js';
 export class GoogleDriveError extends Error {
     code;
     constructor(message, code) {
@@ -33,6 +34,23 @@ function toJson(value) {
         return '{}';
     }
 }
+function clampBytes(value, fallback = 1024 * 1024, maximum = 10 * 1024 * 1024) {
+    if (!Number.isFinite(value))
+        return fallback;
+    return Math.max(1, Math.min(maximum, Math.trunc(value)));
+}
+function clampCount(value, fallback, maximum) {
+    if (!Number.isFinite(value))
+        return fallback;
+    return Math.max(1, Math.min(maximum, Math.trunc(value)));
+}
+function limitUtf8(value, maxBytes) {
+    const source = Buffer.from(value, 'utf8');
+    if (source.byteLength <= maxBytes)
+        return { value, contentLength: source.byteLength, truncated: false };
+    const limited = source.subarray(0, maxBytes).toString('utf8');
+    return { value: limited, contentLength: Buffer.byteLength(limited, 'utf8'), truncated: true };
+}
 function mapOwners(value) {
     return asArray(value).map(item => {
         const record = asRecord(item);
@@ -186,9 +204,27 @@ function mapSpreadsheet(data) {
         sheets: asArray(r.sheets).map(item => mapSheetProperties(asRecord(item).properties ?? item)),
     };
 }
-function mapSheetValues(data, spreadsheetId, fallbackRange = '') {
+function mapSheetValues(data, spreadsheetId, fallbackRange = '', options = {}) {
     const r = asRecord(data);
-    const values = asArray(r.values).map(row => asArray(row).map(cell => cell == null ? '' : String(cell)));
+    const maxRows = clampCount(options.maxRows, 1000, 10000);
+    const maxColumns = clampCount(options.maxColumns, 100, 1000);
+    const maxCells = clampCount(options.maxCells, 100000, 1000000);
+    const rawValues = asArray(r.values);
+    let truncated = rawValues.length > maxRows;
+    let remaining = maxCells;
+    const values = [];
+    for (const row of rawValues.slice(0, maxRows)) {
+        const rawRow = asArray(row);
+        if (rawRow.length > maxColumns || rawRow.length > remaining)
+            truncated = true;
+        const limitedRow = rawRow.slice(0, Math.min(maxColumns, remaining)).map(cell => cell == null ? '' : String(cell));
+        values.push(limitedRow);
+        remaining -= limitedRow.length;
+        if (remaining <= 0 && values.length < rawValues.length) {
+            truncated = true;
+            break;
+        }
+    }
     return {
         spreadsheetId,
         range: asString(r, 'range') || fallbackRange,
@@ -196,6 +232,8 @@ function mapSheetValues(data, spreadsheetId, fallbackRange = '') {
         rowCount: values.length,
         columnCount: values.reduce((max, row) => Math.max(max, row.length), 0),
         values,
+        contentLength: values.reduce((total, row) => total + row.length, 0),
+        truncated,
     };
 }
 export class GoogleDriveClient {
@@ -207,16 +245,32 @@ export class GoogleDriveClient {
     tokenUrl;
     timeoutMs;
     fetchImpl;
+    lookupImpl;
     tokenCache = null;
     constructor(options = {}) {
         this.staticToken = options.accessToken ?? '';
         this.clientId = options.clientId ?? '';
         this.clientSecret = options.clientSecret ?? '';
         this.refreshToken = options.refreshToken ?? '';
-        this.baseUrl = (options.baseUrl ?? 'https://www.googleapis.com/drive/v3').replace(/\/+$/, '');
-        this.tokenUrl = options.tokenUrl ?? 'https://oauth2.googleapis.com/token';
+        try {
+            this.baseUrl = normalizeBaseUrl(options.baseUrl, 'https://www.googleapis.com/drive/v3');
+        }
+        catch (error) {
+            if (error instanceof EndpointSecurityError)
+                throw new GoogleDriveError(error.message, 400);
+            throw error;
+        }
+        try {
+            this.tokenUrl = normalizeBaseUrl(options.tokenUrl, 'https://oauth2.googleapis.com/token');
+        }
+        catch (error) {
+            if (error instanceof EndpointSecurityError)
+                throw new GoogleDriveError(error.message, 400);
+            throw error;
+        }
         this.timeoutMs = options.timeoutMs ?? 15000;
         this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
+        this.lookupImpl = options.lookupImpl;
     }
     hasCredentials() {
         return Boolean(this.staticToken || (this.clientId && this.clientSecret && this.refreshToken));
@@ -260,6 +314,14 @@ export class GoogleDriveClient {
         const combined = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
         const timer = this.timeoutMs > 0 ? setTimeout(() => controller.abort(), this.timeoutMs) : undefined;
         try {
+            try {
+                await assertSafeUrl(new URL(this.tokenUrl), this.lookupImpl);
+            }
+            catch (error) {
+                if (error instanceof EndpointSecurityError)
+                    throw new GoogleDriveError(error.message, 400);
+                throw error;
+            }
             const response = await this.fetchImpl(this.tokenUrl, {
                 method: 'POST',
                 headers: { 'content-type': 'application/x-www-form-urlencoded' },
@@ -296,6 +358,14 @@ export class GoogleDriveClient {
         const combined = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
         const timer = this.timeoutMs > 0 ? setTimeout(() => controller.abort(), this.timeoutMs) : undefined;
         try {
+            try {
+                await assertSafeUrl(new URL(url), this.lookupImpl);
+            }
+            catch (error) {
+                if (error instanceof EndpointSecurityError)
+                    throw new GoogleDriveError(error.message, 400);
+                throw error;
+            }
             const response = await this.fetchImpl(url, {
                 method,
                 headers,
@@ -318,8 +388,8 @@ export class GoogleDriveClient {
         }
     }
     async authTest(signal) {
-        const token = await this.getAccessToken(signal);
-        return { ok: true, authMethod: this.staticToken ? 'access_token' : 'refresh_token', tokenPreview: `${token.slice(0, 8)}...` };
+        await this.getAccessToken(signal);
+        return { ok: true, authMethod: this.staticToken ? 'access_token' : 'refresh_token' };
     }
     async listFiles(options = {}) {
         const data = asRecord(await this.request('GET', '/files', {
@@ -389,10 +459,20 @@ export class GoogleDriveClient {
             responseType: responseEncoding === 'base64' ? 'arrayBuffer' : 'text',
             signal: options.signal,
         });
-        const content = responseEncoding === 'base64'
-            ? Buffer.from(raw).toString('base64')
-            : String(raw);
-        return { fileId, exportMimeType, encoding: responseEncoding, content, contentLength: content.length };
+        const maxBytes = clampBytes(options.maxBytes);
+        let content;
+        let truncated = false;
+        if (responseEncoding === 'base64') {
+            const bytes = Buffer.from(raw);
+            truncated = bytes.byteLength > maxBytes;
+            content = bytes.subarray(0, maxBytes).toString('base64');
+        }
+        else {
+            const limited = limitUtf8(String(raw), maxBytes);
+            content = limited.value;
+            truncated = limited.truncated;
+        }
+        return { fileId, exportMimeType, encoding: responseEncoding, content, contentLength: content.length, truncated };
     }
     async listSharedDrives(options = {}) {
         const data = asRecord(await this.request('GET', '/drives', {
@@ -432,14 +512,19 @@ export class GoogleDriveClient {
             signal: options.signal,
         });
         const extracted = extractDocumentContent(data);
+        const limitedText = limitUtf8(extracted.text, clampBytes(options.maxBytes));
+        const maxTabs = clampCount(options.maxTabs, 100, 1000);
+        const tabs = extracted.tabs.slice(0, maxTabs);
         const r = asRecord(data);
         return {
             documentId: asString(r, 'documentId') || documentId,
             title: asString(r, 'title'),
             revisionId: asString(r, 'revisionId'),
-            text: extracted.text,
+            text: limitedText.value,
             tabCount: extracted.tabs.length,
-            tabs: extracted.tabs,
+            tabs,
+            contentLength: limitedText.contentLength,
+            truncated: limitedText.truncated || extracted.tabs.length > tabs.length,
         };
     }
     async getSpreadsheet(spreadsheetId, options = {}) {
@@ -462,6 +547,6 @@ export class GoogleDriveClient {
             },
             signal: options.signal,
         });
-        return mapSheetValues(data, spreadsheetId, range);
+        return mapSheetValues(data, spreadsheetId, range, options);
     }
 }

package/lib/index.js

@@ -90,14 +90,14 @@ export function createTools(client) {
     return [
         defineTool({
             name: 'gdrive_auth_test',
-            description: 'Verify Google Drive credentials and return token metadata.',
+            description: 'Verify Google Drive credentials without returning token material.',
             parameters: {},
             output: {
                 schema: {
                     type: 'object', additionalProperties: false,
-                    properties: { ok: { type: 'boolean' }, reason: { type: 'string' }, authMethod: { type: 'string' }, tokenPreview: { type: 'string' } },
+                    properties: { ok: { type: 'boolean' }, reason: { type: 'string' }, authMethod: { type: 'string' } },
                 },
-                render: (_args, value) => value.ok ? text(`authMethod: ${value.authMethod}\ntoken: ${value.tokenPreview}`) : text(`Google Drive auth failed: ${value.reason}`),
+                render: (_args, value) => value.ok ? text('authMethod: ' + value.authMethod) : text('Google Drive auth failed: ' + value.reason),
             },
             presentCall() { return { card: 'generic', title: 'Verify Google Drive credentials', kind: 'read' }; },
             async execute(_args, exec) {
@@ -224,14 +224,14 @@ export function createTools(client) {
         defineTool({
             name: 'gdrive_export_file',
             description: 'Export a Google Workspace file to text or another MIME type. Read-only operation.',
-            parameters: { fileId: { type: 'string', required: true, description: 'Google Drive file ID' }, exportMimeType: { type: 'string', description: 'Export MIME type, default text/plain' }, responseEncoding: { type: 'string', description: 'Output encoding: text or base64 (default text)' }, supportsAllDrives: { type: 'boolean', description: 'Enable shared drive support' } },
-            output: { schema: { type: 'object', additionalProperties: false, properties: { found: { type: 'boolean' }, reason: { type: 'string' }, fileId: { type: 'string' }, exportMimeType: { type: 'string' }, encoding: { type: 'string' }, content: { type: 'string' }, contentLength: { type: 'number' } } }, render: (_args, value) => value.found ? text((value.content ?? '').slice(0, 4000)) : text(value.reason ?? 'Google Drive is not configured.') },
+            parameters: { fileId: { type: 'string', required: true, description: 'Google Drive file ID' }, exportMimeType: { type: 'string', description: 'Export MIME type, default text/plain' }, responseEncoding: { type: 'string', description: 'Output encoding: text or base64 (default text)' }, maxBytes: { type: 'integer', description: 'Maximum source bytes to return, default 1 MiB, capped at 10 MiB' }, supportsAllDrives: { type: 'boolean', description: 'Enable shared drive support' } },
+            output: { schema: { type: 'object', additionalProperties: false, properties: { found: { type: 'boolean' }, reason: { type: 'string' }, fileId: { type: 'string' }, exportMimeType: { type: 'string' }, encoding: { type: 'string' }, content: { type: 'string' }, contentLength: { type: 'number' }, truncated: { type: 'boolean' } } }, render: (_args, value) => value.found ? text((value.content ?? '').slice(0, 4000) + (value.truncated ? '\n[content truncated by maxBytes]' : '')) : text(value.reason ?? 'Google Drive is not configured.') },
             presentCall(args) { return { card: 'generic', title: `Export Google Drive file ${args.fileId ?? ''}`, kind: 'read' }; },
             async execute(args, exec) {
                 if (!client.hasCredentials())
                     return unavailable('Google Drive accessToken or refresh token credentials are not configured.');
                 try {
-                    return { found: true, ...await client.exportFile(args.fileId, { exportMimeType: args.exportMimeType, responseEncoding: args.responseEncoding, supportsAllDrives: args.supportsAllDrives, signal: exec.signal }) };
+                    return { found: true, ...await client.exportFile(args.fileId, { exportMimeType: args.exportMimeType, responseEncoding: args.responseEncoding, maxBytes: args.maxBytes, supportsAllDrives: args.supportsAllDrives, signal: exec.signal }) };
                 }
                 catch (error) {
                     if (error instanceof GoogleDriveError)
@@ -281,14 +281,14 @@ export function createTools(client) {
         defineTool({
             name: 'gdocs_get_document',
             description: 'Read a Google Docs document structure and extracted text by document ID.',
-            parameters: { documentId: { type: 'string', required: true, description: 'Google Docs document ID' }, includeTabsContent: { type: 'boolean', description: 'Include tab content, default true' }, suggestionsViewMode: { type: 'string', description: 'Optional suggestions view mode' }, commentsViewMode: { type: 'string', description: 'Optional comments view mode' }, fields: { type: 'string', description: 'Optional field mask' } },
-            output: { schema: { type: 'object', additionalProperties: false, properties: { found: { type: 'boolean' }, reason: { type: 'string' }, documentId: { type: 'string' }, title: { type: 'string' }, revisionId: { type: 'string' }, text: { type: 'string' }, tabCount: { type: 'number' }, tabs: { type: 'array', items: { type: 'object', additionalProperties: false, properties: { tabId: { type: 'string' }, title: { type: 'string' }, index: { type: 'number' }, textLength: { type: 'number' } } } } } }, render: (_args, value) => value.found ? renderDocument(value) : text(value.reason ?? 'Google Docs is not configured.') },
+            parameters: { documentId: { type: 'string', required: true, description: 'Google Docs document ID' }, includeTabsContent: { type: 'boolean', description: 'Include tab content, default true' }, maxBytes: { type: 'integer', description: 'Maximum UTF-8 document bytes, default 1 MiB, capped at 10 MiB' }, maxTabs: { type: 'integer', description: 'Maximum tab metadata records, default 100' }, suggestionsViewMode: { type: 'string', description: 'Optional suggestions view mode' }, commentsViewMode: { type: 'string', description: 'Optional comments view mode' }, fields: { type: 'string', description: 'Optional field mask' } },
+            output: { schema: { type: 'object', additionalProperties: false, properties: { found: { type: 'boolean' }, reason: { type: 'string' }, documentId: { type: 'string' }, title: { type: 'string' }, revisionId: { type: 'string' }, text: { type: 'string' }, contentLength: { type: 'number' }, truncated: { type: 'boolean' }, tabCount: { type: 'number' }, tabs: { type: 'array', items: { type: 'object', additionalProperties: false, properties: { tabId: { type: 'string' }, title: { type: 'string' }, index: { type: 'number' }, textLength: { type: 'number' } } } } } }, render: (_args, value) => value.found ? renderDocument(value) : text(value.reason ?? 'Google Docs is not configured.') },
             presentCall(args) { return { card: 'generic', title: `Google Doc ${args.documentId ?? ''}`, kind: 'read' }; },
             async execute(args, exec) {
                 if (!client.hasCredentials())
                     return unavailable('Google Drive accessToken or refresh token credentials are not configured.');
                 try {
-                    return { found: true, ...await client.getDocument(args.documentId, { includeTabsContent: args.includeTabsContent, suggestionsViewMode: args.suggestionsViewMode, commentsViewMode: args.commentsViewMode, fields: args.fields, signal: exec.signal }) };
+                    return { found: true, ...await client.getDocument(args.documentId, { includeTabsContent: args.includeTabsContent, maxBytes: args.maxBytes, maxTabs: args.maxTabs, suggestionsViewMode: args.suggestionsViewMode, commentsViewMode: args.commentsViewMode, fields: args.fields, signal: exec.signal }) };
                 }
                 catch (error) {
                     if (error instanceof GoogleDriveError)
@@ -319,14 +319,14 @@ export function createTools(client) {
         defineTool({
             name: 'gsheets_get_values',
             description: 'Read values from one Google Sheets A1 range.',
-            parameters: { spreadsheetId: { type: 'string', required: true, description: 'Google Sheets spreadsheet ID' }, range: { type: 'string', required: true, description: 'A1 notation range, e.g. Sheet1!A1:D20' }, valueRenderOption: { type: 'string', description: 'FORMATTED_VALUE, UNFORMATTED_VALUE, or FORMULA' }, dateTimeRenderOption: { type: 'string', description: 'SERIAL_NUMBER or FORMATTED_STRING' }, majorDimension: { type: 'string', description: 'ROWS or COLUMNS' } },
-            output: { schema: { type: 'object', additionalProperties: false, properties: { found: { type: 'boolean' }, reason: { type: 'string' }, spreadsheetId: { type: 'string' }, range: { type: 'string' }, majorDimension: { type: 'string' }, rowCount: { type: 'number' }, columnCount: { type: 'number' }, values: { type: 'array', items: { type: 'array', items: { type: 'string' } } } } }, render: (_args, value) => value.found ? renderValues(value) : text(value.reason ?? 'Google Sheets is not configured.') },
+            parameters: { spreadsheetId: { type: 'string', required: true, description: 'Google Sheets spreadsheet ID' }, range: { type: 'string', required: true, description: 'A1 notation range, e.g. Sheet1!A1:D20' }, valueRenderOption: { type: 'string', description: 'FORMATTED_VALUE, UNFORMATTED_VALUE, or FORMULA' }, dateTimeRenderOption: { type: 'string', description: 'SERIAL_NUMBER or FORMATTED_STRING' }, majorDimension: { type: 'string', description: 'ROWS or COLUMNS' }, maxRows: { type: 'integer', description: 'Maximum rows, default 1000' }, maxColumns: { type: 'integer', description: 'Maximum columns, default 100' }, maxCells: { type: 'integer', description: 'Maximum cells, default 100000' } },
+            output: { schema: { type: 'object', additionalProperties: false, properties: { found: { type: 'boolean' }, reason: { type: 'string' }, spreadsheetId: { type: 'string' }, range: { type: 'string' }, majorDimension: { type: 'string' }, rowCount: { type: 'number' }, columnCount: { type: 'number' }, contentLength: { type: 'number' }, truncated: { type: 'boolean' }, values: { type: 'array', items: { type: 'array', items: { type: 'string' } } } } }, render: (_args, value) => value.found ? renderValues(value) : text(value.reason ?? 'Google Sheets is not configured.') },
             presentCall(args) { return { card: 'generic', title: `Google Sheet values ${args.range ?? ''}`, kind: 'read' }; },
             async execute(args, exec) {
                 if (!client.hasCredentials())
                     return unavailable('Google Drive accessToken or refresh token credentials are not configured.');
                 try {
-                    return { found: true, ...await client.getSheetValues(args.spreadsheetId, args.range, { valueRenderOption: args.valueRenderOption, dateTimeRenderOption: args.dateTimeRenderOption, majorDimension: args.majorDimension, signal: exec.signal }) };
+                    return { found: true, ...await client.getSheetValues(args.spreadsheetId, args.range, { valueRenderOption: args.valueRenderOption, dateTimeRenderOption: args.dateTimeRenderOption, majorDimension: args.majorDimension, maxRows: args.maxRows, maxColumns: args.maxColumns, maxCells: args.maxCells, signal: exec.signal }) };
                 }
                 catch (error) {
                     if (error instanceof GoogleDriveError)

package/lib/types/client.d.ts

@@ -1,4 +1,5 @@
 /** Google Drive API client with injected fetch for testability. */
+import { type LookupImpl } from './url-security.js';
 export interface GoogleDriveClientOptions {
     accessToken?: string;
     clientId?: string;
@@ -8,6 +9,8 @@ export interface GoogleDriveClientOptions {
     tokenUrl?: string;
     timeoutMs?: number;
     fetchImpl?: typeof fetch;
+    /** Test-only DNS lookup override; production uses node:dns/promises. */
+    lookupImpl?: LookupImpl;
 }
 export declare class GoogleDriveError extends Error {
     readonly code: number;
@@ -85,6 +88,8 @@ export interface GoogleDocumentInfo {
     text: string;
     tabCount: number;
     tabs: GoogleDocTabInfo[];
+    contentLength: number;
+    truncated: boolean;
 }
 export interface GoogleSheetPropertiesInfo {
     sheetId: number;
@@ -111,6 +116,8 @@ export interface GoogleSheetValuesInfo {
     rowCount: number;
     columnCount: number;
     values: string[][];
+    contentLength: number;
+    truncated: boolean;
 }
 export declare class GoogleDriveClient {
     private readonly staticToken;
@@ -121,6 +128,7 @@ export declare class GoogleDriveClient {
     private readonly tokenUrl;
     private readonly timeoutMs;
     private readonly fetchImpl;
+    private readonly lookupImpl;
     private tokenCache;
     constructor(options?: GoogleDriveClientOptions);
     hasCredentials(): boolean;
@@ -130,7 +138,6 @@ export declare class GoogleDriveClient {
     authTest(signal?: AbortSignal): Promise<{
         ok: boolean;
         authMethod: string;
-        tokenPreview: string;
     }>;
     listFiles(options?: {
         query?: string;
@@ -180,6 +187,7 @@ export declare class GoogleDriveClient {
         exportMimeType?: string;
         responseEncoding?: 'text' | 'base64';
         supportsAllDrives?: boolean;
+        maxBytes?: number;
         signal?: AbortSignal;
     }): Promise<{
         fileId: string;
@@ -187,6 +195,7 @@ export declare class GoogleDriveClient {
         encoding: string;
         content: string;
         contentLength: number;
+        truncated: boolean;
     }>;
     listSharedDrives(options?: {
         pageSize?: number;
@@ -208,6 +217,8 @@ export declare class GoogleDriveClient {
         suggestionsViewMode?: string;
         commentsViewMode?: string;
         fields?: string;
+        maxBytes?: number;
+        maxTabs?: number;
         signal?: AbortSignal;
     }): Promise<GoogleDocumentInfo>;
     getSpreadsheet(spreadsheetId: string, options?: {
@@ -220,6 +231,9 @@ export declare class GoogleDriveClient {
         valueRenderOption?: string;
         dateTimeRenderOption?: string;
         majorDimension?: string;
+        maxRows?: number;
+        maxColumns?: number;
+        maxCells?: number;
         signal?: AbortSignal;
     }): Promise<GoogleSheetValuesInfo>;
 }

package/lib/types/url-security.d.ts

@@ -0,0 +1,12 @@
+import type { LookupAddress } from 'node:dns';
+export type LookupImpl = (hostname: string, options: {
+    all: true;
+}) => Promise<LookupAddress[]>;
+export declare class EndpointSecurityError extends Error {
+    constructor(message: string);
+}
+export declare function isBlockedAddress(address: string): boolean;
+/** Normalize a configured endpoint to origin + optional path prefix. */
+export declare function normalizeBaseUrl(value: string | undefined, fallback?: string): string;
+/** Validate the final request destination, resolving ordinary hostnames fail-closed. */
+export declare function assertSafeUrl(url: URL, lookupImpl?: LookupImpl): Promise<void>;

package/lib/url-security.js

@@ -0,0 +1,217 @@
+/**
+ * Fail-closed destination validation for an operator-configured API endpoint.
+ *
+ * GENERATED FILE — instantiated from .verify/url-security.template.ts.
+ * Every copy of url-security.ts must stay byte-identical apart from LABEL, so
+ * the implementations cannot drift the way they did before. Behaviour that must
+ * hold across all copies is pinned by security-vectors.json in each repository.
+ */
+import { lookup as dnsLookup } from 'node:dns/promises';
+import { isIP } from 'node:net';
+const LABEL = 'Google Drive';
+export class EndpointSecurityError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'EndpointSecurityError';
+    }
+}
+const defaultLookup = async (hostname, options) => dnsLookup(hostname, options);
+/** Aligned with the IANA IPv4 Special-Purpose Address Registry. */
+const IPV4_BLOCKED_RANGES = [
+    ['0.0.0.0', 8], // this network / unspecified
+    ['10.0.0.0', 8], // private
+    ['100.64.0.0', 10], // carrier-grade NAT
+    ['127.0.0.0', 8], // loopback
+    ['169.254.0.0', 16], // link-local
+    ['172.16.0.0', 12], // private
+    ['192.0.0.0', 24], // IETF protocol assignments
+    ['192.0.2.0', 24], // TEST-NET-1
+    ['192.31.196.0', 24], // AS112-v4
+    ['192.52.193.0', 24], // AMT
+    ['192.88.99.0', 24], // deprecated 6to4 relay anycast
+    ['192.168.0.0', 16], // private
+    ['192.175.48.0', 24], // AS112-v4 direct delegation
+    ['198.18.0.0', 15], // benchmarking
+    ['198.51.100.0', 24], // TEST-NET-2
+    ['203.0.113.0', 24], // TEST-NET-3
+    ['224.0.0.0', 4], // multicast
+    ['240.0.0.0', 4], // reserved / future use
+];
+/** Aligned with the IANA IPv6 Special-Purpose Address Registry. */
+const IPV6_BLOCKED_RANGES = [
+    ['::', 96], // unspecified and IPv4-compatible
+    ['::ffff:0:0', 96], // IPv4-mapped
+    ['64:ff9b::', 96], // well-known NAT64
+    ['64:ff9b:1::', 48], // local-use NAT64
+    ['100::', 64], // discard-only
+    ['100:0:0:1::', 64], // dummy IPv6 prefix (RFC 9780)
+    ['2001::', 23], // IETF protocol assignments: Teredo, AMT, AS112-v6, benchmarking, ORCHID/ORCHIDv2, DRiP
+    ['2001:db8::', 32], // documentation
+    ['2002::', 16], // 6to4
+    ['2620:4f:8000::', 48], // direct delegation AS112 service
+    ['3fff::', 20], // documentation (RFC 9637)
+    ['5f00::', 16], // segment routing (SRv6) SIDs
+    ['fc00::', 7], // unique local
+    ['fe80::', 10], // link-local
+    ['fec0::', 10], // deprecated site-local
+    ['ff00::', 8], // multicast
+];
+function parseIpv4(address) {
+    const parts = address.split('.');
+    if (parts.length !== 4 || parts.some(part => !/^\d{1,3}$/.test(part)))
+        return null;
+    let value = 0n;
+    for (const part of parts) {
+        const octet = Number(part);
+        if (octet > 255)
+            return null;
+        value = (value << 8n) | BigInt(octet);
+    }
+    return value;
+}
+function parseIpv6(address) {
+    const normalized = address.toLowerCase();
+    if (normalized.includes('%'))
+        return null;
+    const sections = normalized.split('::');
+    if (sections.length > 2)
+        return null;
+    const parseSection = (section) => {
+        if (!section)
+            return [];
+        const parts = section.split(':');
+        const result = [];
+        for (const [index, part] of parts.entries()) {
+            if (part.includes('.')) {
+                if (index !== parts.length - 1)
+                    return null;
+                const ipv4 = parseIpv4(part);
+                if (ipv4 === null)
+                    return null;
+                result.push((ipv4 >> 16n).toString(16), (ipv4 & 0xffffn).toString(16));
+            }
+            else if (/^[0-9a-f]{1,4}$/.test(part)) {
+                result.push(part);
+            }
+            else {
+                return null;
+            }
+        }
+        return result;
+    };
+    const head = parseSection(sections[0]);
+    const tail = sections.length === 2 ? parseSection(sections[1]) : [];
+    if (!head || !tail)
+        return null;
+    const parts = [...head, ...tail];
+    if (sections.length === 1) {
+        if (parts.length !== 8)
+            return null;
+    }
+    else {
+        const zeroCount = 8 - parts.length;
+        if (zeroCount < 1)
+            return null;
+        parts.splice(head.length, 0, ...Array.from({ length: zeroCount }, () => '0'));
+    }
+    if (parts.length !== 8)
+        return null;
+    let value = 0n;
+    for (const part of parts)
+        value = (value << 16n) | BigInt(Number.parseInt(part, 16));
+    return value;
+}
+function inRange(address, network, bits, width) {
+    const hostBits = width - bits;
+    const mask = hostBits === width ? 0n : ((1n << BigInt(width)) - 1n) ^ ((1n << BigInt(hostBits)) - 1n);
+    return (address & mask) === (network & mask);
+}
+function isBlockedIpv4(address) {
+    const value = parseIpv4(address);
+    if (value === null)
+        return true;
+    return IPV4_BLOCKED_RANGES.some(([network, bits]) => {
+        const parsed = parseIpv4(network);
+        return parsed !== null && inRange(value, parsed, bits, 32);
+    });
+}
+function isBlockedIpv6(address) {
+    const value = parseIpv6(address);
+    if (value === null)
+        return true;
+    return IPV6_BLOCKED_RANGES.some(([network, bits]) => {
+        const parsed = parseIpv6(network);
+        return parsed !== null && inRange(value, parsed, bits, 128);
+    });
+}
+export function isBlockedAddress(address) {
+    const family = isIP(address);
+    if (family === 4)
+        return isBlockedIpv4(address);
+    if (family === 6)
+        return isBlockedIpv6(address);
+    return true;
+}
+function hostnameIsLocal(hostname) {
+    const normalized = hostname.toLowerCase().replace(/\.+$/, '');
+    return normalized === 'localhost'
+        || normalized.endsWith('.localhost')
+        || normalized === 'localhost.localdomain'
+        || normalized.endsWith('.localhost.localdomain')
+        || normalized === 'local'
+        || normalized.endsWith('.local');
+}
+/** Normalize a configured endpoint to origin + optional path prefix. */
+export function normalizeBaseUrl(value, fallback = '') {
+    const input = value ?? fallback;
+    // An empty endpoint means "not configured"; each client keeps its own behaviour.
+    if (!input)
+        return '';
+    if (typeof input !== 'string' || input.trim() !== input || /[\u0000-\u001f\u007f]/.test(input)) {
+        throw new EndpointSecurityError(LABEL + ' base URL is invalid.');
+    }
+    let url;
+    try {
+        url = new URL(input);
+    }
+    catch {
+        throw new EndpointSecurityError(LABEL + ' base URL is invalid.');
+    }
+    if ((url.protocol !== 'http:' && url.protocol !== 'https:') || !url.hostname || url.username || url.password || url.search || url.hash) {
+        throw new EndpointSecurityError(LABEL + ' base URL is invalid.');
+    }
+    const pathPrefix = url.pathname.replace(/\/+$/, '');
+    return `${url.origin}${pathPrefix}`;
+}
+/** Validate the final request destination, resolving ordinary hostnames fail-closed. */
+export async function assertSafeUrl(url, lookupImpl = defaultLookup) {
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new EndpointSecurityError(LABEL + ' request URL was rejected by host safety policy.');
+    }
+    const hostname = url.hostname.replace(/^\[|\]$/g, '').replace(/\.+$/, '').toLowerCase();
+    if (!hostname || hostnameIsLocal(hostname)) {
+        throw new EndpointSecurityError(LABEL + ' request URL was rejected by host safety policy.');
+    }
+    const literalFamily = isIP(hostname);
+    if (literalFamily) {
+        if (isBlockedAddress(hostname)) {
+            throw new EndpointSecurityError(LABEL + ' request URL was rejected by host safety policy.');
+        }
+        return;
+    }
+    let addresses;
+    try {
+        addresses = await lookupImpl(hostname, { all: true });
+    }
+    catch {
+        throw new EndpointSecurityError(LABEL + ' request URL was rejected by host safety policy.');
+    }
+    if (!Array.isArray(addresses) || addresses.length === 0) {
+        throw new EndpointSecurityError(LABEL + ' request URL was rejected by host safety policy.');
+    }
+    for (const result of addresses) {
+        if (!result || (result.family !== 4 && result.family !== 6) || isIP(result.address) !== result.family || isBlockedAddress(result.address)) {
+            throw new EndpointSecurityError(LABEL + ' request URL was rejected by host safety policy.');
+        }
+    }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@libai168/dsh-tool-google-drive",
   "description": "Google Workspace read-only tools for DeepSeek Harness: Drive files, permissions, revisions, Docs, Sheets, and Shared Drives",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",
@@ -32,7 +32,8 @@
     "build": "tsc -p tsconfig.json",
     "typecheck": "tsc --noEmit -p tsconfig.test.json && tsc --noEmit -p tsconfig.json",
     "test": "vitest run",
-    "auth:google": "node scripts/auth-google.mjs"
+    "auth:google": "node scripts/auth-google.mjs",
+    "prepare": "npm run build"
   },
   "publishConfig": {
     "access": "public"