Docs / Specification

contract connector · 40-connector.md · 41-secrets.md · 42-drive-extensions.md · guide · card

Drive extensions

Connector implementers use these extensions to capture Picker-selected files and structured Sheets rows, track Drive changes and enforce domain-approved access.

drive-picks

Files a principal selects through Picker, the selection position, and the rows a tenant connection stores.

• picker-sourceThe gdrive-picks source serves files and pages with drive-oauthconnector.source.drive-oauthThe drive source mints its access token from a refresh token and client credentials bound as secret:// references, once per fire and again on a 401, holding it in memory and writing it to no store, journal or record. and drive-page-grainconnector.source.drive-page-grainIn bytes-and-pages mode, each PDF page lands one pages row under document-grain, decoded behind parse-boundary; bytes land in no column. In metadata-only mode, no page content row lands. for files selected through Picker.
• file-selectionOn gdrive-picks and gdrive-sheet, file_ids selects distinct individual files without a folder root; folder_id and folder_ids are absent.
  Why

  A-connector#picker-files-bind
• file-selection-limitfile_ids holds at most 128 entries.
• file-selection-invalidtestAn empty, repeated or mixed file_ids selection, or one exceeding file-selection-limitconnector.drive-picks.file-selection-limitfile_ids holds at most 128 entries., raises ConnectorDriveFilesInvalid before a Drive request.
  Why

  because an ambiguous selection cannot establish which files a later tombstone withdraws
• file-accesstestThe source validates each selected file with the bound credential. An uncaptured inaccessible or trashed id, non-file id, or file outside configured drive_id raises ConnectorDriveFileRejected without landing rows or advancing position.
  Why

  because an inaccessible picker id cannot count as a complete selection
• file-revokedtestWhen a captured file becomes inaccessible or trashed under a valid credential, the source tombstones its file and pages once. The position adds its id to the withdrawn set. Authentication and transient failures advance no position.
• file-withdrawntestA withdrawn id stays selected without refusing later fires. A fire finding the file inaccessible stores nothing for that file. When access returns, the source captures the file as new and removes its id from the withdrawn set.
  Why

  A-connector#picker-files-bind
• export-limittestIf Drive answers a picked file’s export with 403 exportSizeLimitExceeded, the source applies drive-export-limitconnector.source.drive-export-limitA Doc, Sheet or Slides deck whose export Drive answers 403 exportSizeLimitExceeded lands its file row with a skipped reason naming Drive's export limit and no pages, and the read continues.. The file id stays outside the withdrawn set, and its files row receives no tombstone.
  Why

  because Drive refuses that export on every fire while the principal still reads the file, and a tombstone withdraws a file nobody revoked
• file-positionThe position binds sorted file_ids and mode; changing either rereads retained files, and a complete read tombstones deselected files and their pages.
  Why

  A-connector#picker-files-bind
• row-scopeA connection-bound run stamps its Drive files and pages rows and tombstones with the admitted tenant and principal. The source supplies neither value.
• row-identityA connection-bound Drive row and position key include connection identity beside file_id. Connections selecting the same file keep separate rows and positions.

unsettled: Does Picker selection of a folder under drive.file grant the app access to its descendant files? owner: connector affects: connector.drive-picks

Scenarios

• connector.drive-picks.file-selection-invalidconnector.drive-picks.file-selection-invalidAn empty, repeated or mixed file_ids selection, or one exceeding file-selection-limit, raises ConnectorDriveFilesInvalid before a Drive request.: WHEN file_ids repeats one id or appears beside folder_id, THEN validation raises ConnectorDriveFilesInvalidconnector.drive-picks.file-selection-invalidAn empty, repeated or mixed file_ids selection, or one exceeding file-selection-limit, raises ConnectorDriveFilesInvalid before a Drive request. before any request.
• connector.drive-picks.file-accessconnector.drive-picks.file-accessThe source validates each selected file with the bound credential. An uncaptured inaccessible or trashed id, non-file id, or file outside configured drive_id raises ConnectorDriveFileRejected without landing rows or advancing position.: WHEN a picked id is inaccessible to the bound credential, THEN ConnectorDriveFileRejectedconnector.drive-picks.file-accessThe source validates each selected file with the bound credential. An uncaptured inaccessible or trashed id, non-file id, or file outside configured drive_id raises ConnectorDriveFileRejected without landing rows or advancing position. commits neither rows nor position.
• connector.drive-picks.file-accessconnector.drive-picks.file-accessThe source validates each selected file with the bound credential. An uncaptured inaccessible or trashed id, non-file id, or file outside configured drive_id raises ConnectorDriveFileRejected without landing rows or advancing position.: WHEN a picked file lies in another Shared Drive than the configured drive_id, THEN ConnectorDriveFileRejectedconnector.drive-picks.file-accessThe source validates each selected file with the bound credential. An uncaptured inaccessible or trashed id, non-file id, or file outside configured drive_id raises ConnectorDriveFileRejected without landing rows or advancing position. commits neither rows nor position.
• connector.drive-picks.file-revokedconnector.drive-picks.file-revokedWhen a captured file becomes inaccessible or trashed under a valid credential, the source tombstones its file and pages once. The position adds its id to the withdrawn set. Authentication and transient failures advance no position.: WHEN a captured file loses access under a valid credential, THEN its file and pages receive tombstones before the selection position advances.
• connector.drive-picks.file-revokedconnector.drive-picks.file-revokedWhen a captured file becomes inaccessible or trashed under a valid credential, the source tombstones its file and pages once. The position adds its id to the withdrawn set. Authentication and transient failures advance no position.: WHEN two fires follow a captured file’s revocation, THEN the first lands its tombstone, the second lands none, and both keep the other picked files in the position.
• connector.drive-picks.file-withdrawnconnector.drive-picks.file-withdrawnA withdrawn id stays selected without refusing later fires. A fire finding the file inaccessible stores nothing for that file. When access returns, the source captures the file as new and removes its id from the withdrawn set.: WHEN a withdrawn file becomes readable again, THEN the next fire lands its captured row and the position holds it outside the withdrawn set.
• connector.drive-picks.export-limitconnector.drive-picks.export-limitIf Drive answers a picked file's export with 403 exportSizeLimitExceeded, the source applies drive-export-limit. The file id stays outside the withdrawn set, and its files row receives no tombstone.: WHEN a captured Sheet’s new version exceeds Drive’s export limit, THEN its files row lands skipped rather than removed, and the position keeps it.
• connector.drive-picks.file-positionconnector.drive-picks.file-positionThe position binds sorted file_ids and mode; changing either rereads retained files, and a complete read tombstones deselected files and their pages.: WHEN a file id leaves a complete selection, THEN its file row and prior pages land tombstones.
• connector.drive-picks.row-scopeconnector.drive-picks.row-scopeA connection-bound run stamps its Drive files and pages rows and tombstones with the admitted tenant and principal. The source supplies neither value.: WHEN two tenants select the same file id, THEN each landed row carries only its admitted tenant and principal.

drive-sheet

Google Sheets capture as structured rows, separate from PDF page capture.

• source-nameThe gdrive-sheet source serves rows and shares drive-oauthconnector.source.drive-oauthThe drive source mints its access token from a refresh token and client credentials bound as secret:// references, once per fire and again on a 401, holding it in memory and writing it to no store, journal or record. and file-selectionconnector.drive-picks.file-selectionOn gdrive-picks and gdrive-sheet, file_ids selects distinct individual files without a folder root; folder_id and folder_ids are absent. without changing the gdrive source’s files and pages tables.
• export-formatA Google Sheet selected for structured capture exports as XLSX; CSV contains only the first sheet.
• sheet-identityEach landed spreadsheet row carries file_id, sheet id, sheet name, source row number, connection identity, tenant and principal.
• row-keyA spreadsheet row key combines connection identity, file id, sheet id and source row number. A complete recapture tombstones keys absent from the captured workbook.
• cell-valuesThe row preserves each cell’s typed value and its column position; an empty cell is distinct from a missing row.
• formula-valueThe source stores a formula cell’s exported result and records that the cell contains a formula. Contextful does not evaluate the formula.
• export-refusalA workbook whose export exceeds drive-file-capconnector.source.drive-file-capFor a file over max_file_bytes, 64 MiB by default, the source stores a file row with a skipped reason naming the cap, without pages. The source reads no bytes past the cap and continues. lands a named skipped file row and no partial spreadsheet rows.
  Why

  because a truncated workbook cannot establish row identity or removal
• export-limitWhen export-limitconnector.drive-picks.export-limitIf Drive answers a picked file's export with 403 exportSizeLimitExceeded, the source applies drive-export-limit. The file id stays outside the withdrawn set, and its files row receives no tombstone. rejects a workbook export, the source stores a named skipped file row and retains prior spreadsheet rows and keys. Only file-revokedconnector.drive-picks.file-revokedWhen a captured file becomes inaccessible or trashed under a valid credential, the source tombstones its file and pages once. The position adds its id to the withdrawn set. Authentication and transient failures advance no position. tombstones a selected workbook.
  Why

  because an export over Drive’s size limit leaves the workbook readable, so its rows still describe the principal’s file

Scenarios

• connector.drive-sheet.sheet-identityconnector.drive-sheet.sheet-identityEach landed spreadsheet row carries file_id, sheet id, sheet name, source row number, connection identity, tenant and principal.: WHEN a workbook has two sheets with row 3 on each, THEN their landed keys differ by sheet id.
• connector.drive-sheet.row-keyconnector.drive-sheet.row-keyA spreadsheet row key combines connection identity, file id, sheet id and source row number. A complete recapture tombstones keys absent from the captured workbook.: WHEN a complete recapture removes a row, THEN the old row key receives a tombstone.
• connector.drive-sheet.export-limitconnector.drive-sheet.export-limitWhen export-limit rejects a workbook export, the source stores a named skipped file row and retains prior spreadsheet rows and keys. Only file-revoked tombstones a selected workbook.: WHEN a captured workbook’s next export answers 403 exportSizeLimitExceeded, THEN no spreadsheet row of it receives a tombstone.

drive-changes

Change cursors and complete listings of a selected Drive corpus.

• initial-tokenBefore the initial full listing, the source obtains a start page token. The source commits the token with the complete listing, preserving replay of changes during listing.
• cursor-scopeThe cursor binds the connection, credential principal, declared drive, selected roots or file ids, and capture mode. A changed binding starts a complete listing.
• page-commitA change read follows every nextPageToken and advances to newStartPageToken only after the resulting rows and removals commit.
• selection-filterThe source admits a changed file only when its current ancestry or id satisfies the bound selection. Moving outside the selection produces tombstones.
• removed-fileFor a removal change, the source withdraws the file and pages only after establishing that the selected file is absent or inaccessible.
• invalid-tokenIf Drive rejects or expires a change token, the source starts a complete selected listing. The incomplete change response advances no removals.
  Why

  because a missing change interval cannot prove the retained files still satisfy the selection

Scenarios

• connector.drive-changes.page-commitconnector.drive-changes.page-commitA change read follows every nextPageToken and advances to newStartPageToken only after the resulting rows and removals commit.: WHEN a change response has another page, THEN the committed cursor does not skip that page.
• connector.drive-changes.invalid-tokenconnector.drive-changes.invalid-tokenIf Drive rejects or expires a change token, the source starts a complete selected listing. The incomplete change response advances no removals.: WHEN Drive rejects the cursor, THEN a complete walk reconciles removals before a new token commits.

drive-domain-auth

Organization-approved Drive access and the principal whose authority each request carries.

• delegation-grantDomain-wide delegation requires an operator-declared Workspace domain, authorized service account and approved scope set bound to the connection.
• impersonated-principalEvery delegated Drive request names one admitted Workspace user as its subject; the row and permission sweep retain that subject’s identity.
• domain-boundaryA delegated request for a subject outside its declared domain raises ConnectorDriveDomainRejected before token minting.
  Why

  because administrator approval for one domain conveys no authority over another
• organization-exportA sanctioned organization-wide export declares its scope and disclosure posture explicitly; delegated user reads do not imply that export.

Scenarios

• connector.drive-domain-auth.domain-boundaryconnector.drive-domain-auth.domain-boundaryA delegated request for a subject outside its declared domain raises ConnectorDriveDomainRejected before token minting.: WHEN a connection names a user outside its approved domain, THEN ConnectorDriveDomainRejectedconnector.drive-domain-auth.domain-boundaryA delegated request for a subject outside its declared domain raises ConnectorDriveDomainRejected before token minting. precedes any Google request.