Google Drive Port

Purpose

This is the Harbor reference integration for the Google Drive API.

Use it when:

• building Google Drive actions in Harbor
• extending the Dock / Hub Google Drive entry
• teaching Codex or OpenClaw how to map a storage API into Harbor Ports and Harbor Actions without turning Harbor into a generic file proxy

Harbor Port worksheet

Product

• Product: Google Drive API
• Publisher slug: google
• Publisher name: Google
• Category: Storage
• Tags: google, drive, storage, files, productivity

Safe Harbor Port metadata

• Kind: http_api
• Label: Google Drive API
• Description: Google Drive API connection managed locally through Harbor.
• Base URL: https://www.googleapis.com/
• Auth mode: header_token
• Auth header name: Authorization
• Auth token prefix: Bearer

Hidden local config

• authToken

Harbor stores the token locally only. Dock / Hub manifests must never contain it.

Harbor action design notes

Google Drive is a good Harbor fit today when we combine fixed routes with Harbor's Action Model for typed query parameters.

Good Harbor Google Drive actions:

• stable GET routes for file listing, file metadata, Drive search, shared drive reads, permissions, and change tokens
• explicit POST routes for folder creation or file copy flows
• Action Model input.path, input.query, and input.body envelopes instead of raw query-string editing
• requestBodyMode: "none" for reads
• requestBodyMode: "json" for bounded writes
• resultMode: "json_summary" for all starter actions
• bounded path templates like /drive/v3/files/{fileId} when a concrete Drive item must be targeted

Avoid for now:

• upload flows that depend on uploadType query parameters or media uploads
• computed provider query builders like structured Drive-search-to-q translation, which are planned after basic typed query support
• giant sharing-management surfaces with broad mutation options
• automatic publish of write actions

Starter Google Drive actions

Automatic read actions

• list-files -> GET /drive/v3/files
• get-file-metadata -> GET /drive/v3/files/{fileId}
• search-files -> GET /drive/v3/files
• list-shared-drives -> GET /drive/v3/drives
• get-shared-drive -> GET /drive/v3/drives/{driveId}
• get-start-page-token -> GET /drive/v3/changes/startPageToken
• list-file-permissions -> GET /drive/v3/files/{fileId}/permissions

Approval-friendly write actions

• create-folder -> POST /drive/v3/files
• copy-file -> POST /drive/v3/files/{fileId}/copy

Why these actions

These routes fit Harbor's current safe model well because they:

• stay under one fixed Google API origin
• use fixed paths or small explicit path templates relative to the Harbor Port
• keep query parameters typed and reviewable through Harbor's Action Model
• keep hidden auth entirely local to Harbor Node
• avoid arbitrary full URL editing and raw query-string injection
• can be reviewed as named capabilities before publish

Action Model notes

For Google Drive actions, Harbor stores explicit path templates and typed parameter metadata such as:

• /drive/v3/files/{fileId}
• /drive/v3/drives/{driveId}
• /drive/v3/files/{fileId}/permissions
• /drive/v3/files/{fileId}/copy

At execution time, callers supply values by location:

• input.path for path placeholders
• input.query for typed query parameters
• input.body for JSON write payloads

Example file metadata request:

{
  "path": {
    "fileId": "1abcExampleDriveFileId"
  }
}

Example Drive search request:

{
  "query": {
    "q": "name contains 'invoice' and trashed = false",
    "pageSize": 25,
    "orderBy": "modifiedTime desc"
  }
}

Harbor fills path placeholders safely, validates query values against the stored action schema, applies static query defaults such as supportsAllDrives, and then sends the assembled request to Google Drive.

Suggested operator workflow

1. Import the Google Drive Dock entry from Dock / Hub.
2. Configure the local Google bearer token in Harbor Node.
3. Use low-risk file and shared drive read actions first.
4. Keep create-folder and copy-file on require_approval unless there is a very deliberate local policy reason not to.
5. Add more drafts when the query parameters can be typed and reviewed safely.

Suggested agent workflow

1. Inspect the existing Google Drive Harbor Port.
2. Inspect live actions and drafts.
3. Propose additional fixed-path or bounded path-template actions, plus typed query params where Harbor can model them safely.
4. Validate and test drafts.
5. Request publish instead of self-publishing unless Harbor explicitly allows it.

Agents should never:

• ask Harbor for the stored token
• edit hidden Google Drive auth
• widen Google Drive into a generic arbitrary proxy
• add raw query-string escape hatches instead of typed Action Model query parameters

Current update strategy

For now, Google Drive updates are manual:

• update the Dock / Hub Google Drive integration document in apps/hub/catalog/integrations/google/drive.json
• bump the manifest version when the action set changes materially
• re-import into Harbor or create new drafts from the updated Dock entry

Future options such as computed Drive query builders or upload-specific action support are intentionally deferred until Harbor has clearer provider-adapter and upload semantics.

Official reference starting points

• Google Drive API reference root: https://developers.google.com/workspace/drive/api/reference/rest
• Files list: https://developers.google.com/workspace/drive/api/reference/rest/v3/files/list
• Files get: https://developers.google.com/workspace/drive/api/reference/rest/v3/files/get
• Files create: https://developers.google.com/workspace/drive/api/reference/rest/v3/files/create
• Files copy: https://developers.google.com/workspace/drive/api/reference/rest/v3/files/copy
• Drives list: https://developers.google.com/workspace/drive/api/reference/rest/v3/drives/list
• Drives get: https://developers.google.com/workspace/drive/api/reference/rest/v3/drives/get
• Changes get start page token: https://developers.google.com/workspace/drive/api/reference/rest/v3/changes/getStartPageToken
• Permissions list: https://developers.google.com/workspace/drive/api/reference/rest/v3/permissions/list