basalt / drives-microsoft/src / MicrosoftDrive
Class: MicrosoftDrive
Defined in: drives-microsoft/src/index.ts:284
The adapter. Construct it with microsoftDrive.
Implements
Constructors
Constructor
> new MicrosoftDrive(options): MicrosoftDrive
Defined in: drives-microsoft/src/index.ts:317
Parameters
options
Returns
MicrosoftDrive
Properties
allowedHosts
> readonly allowedHosts: readonly string[]
Defined in: drives-microsoft/src/index.ts:295
The SSRF allowlist.
login.microsoftonline.com is here because the token endpoint is fetched (the consent URL is handed to a browser and never opened by the framework — there is no separate host for it to add). graph.microsoft.com is the API. Everything after that is a content host, and every entry is a .suffix: see MICROSOFT_DOWNLOAD_HOSTS.
Implementation of
authorization
> readonly authorization: DriveAuthorization
Defined in: drives-microsoft/src/index.ts:304
Implementation of
deltaIncludesExisting
> readonly deltaIncludesExisting: true = true
Defined in: drives-microsoft/src/index.ts:303
/delta with no token enumerates the drive first and only then hands over a deltaLink, so the change feed is the backfill. Declaring this honestly is what stops the engine from running a redundant full listing pass before the first delta run — and, on Google, declaring it wrongly is what would make a first sync import nothing at all.
Implementation of
DriveProvider.deltaIncludesExisting
name
> readonly name: "microsoft" = 'microsoft'
Defined in: drives-microsoft/src/index.ts:285
Stable identifier, stored on every connection: google, microsoft, dropbox.
Implementation of
Methods
delta()
> delta(session, cursor): Promise<DriveDelta>
Defined in: drives-microsoft/src/index.ts:653
Reads one page of changes since cursor.
Parameters
session
cursor
string
Returns
Promise<DriveDelta>
Implementation of
download()
> download(session, item): Promise<DriveContent>
Defined in: drives-microsoft/src/index.ts:541
Opens an item's bytes.
The interesting part is what is not done. Graph offers two ways in:
GET {item}/content, which answers302to a CDN host, and@microsoft.graph.downloadUrl, a short-lived pre-signed URL.
This adapter asks for the pre-signed URL and fetches it with no Authorization header, so the Graph bearer token is never presented to a host that does not need it. The /content redirect is only a fallback, for the rare item Graph declines to pre-sign.
The URL itself is treated as a credential throughout: it is fetched immediately, never stored in DriveItem.raw, never logged, and never placed in an error's details — which is why a failure from the content host is reported with a fixed summary and the body is destroyed unread.
Parameters
session
item
Returns
Promise<DriveContent>
Implementation of
get()
> get(session, externalId): Promise<DriveItem | null>
Defined in: drives-microsoft/src/index.ts:500
Fetches one item's metadata. null when it no longer exists.
Parameters
session
externalId
string
Returns
Promise<DriveItem | null>
Implementation of
list()
> list(session, options): Promise<DrivePage<DriveItem>>
Defined in: drives-microsoft/src/index.ts:482
Lists one page of a folder.
Parameters
session
options
Returns
Promise<DrivePage<DriveItem>>
Implementation of
startDelta()
> startDelta(session, options): Promise<string>
Defined in: drives-microsoft/src/index.ts:649
Establishes the delta cursor.
Graph has no way to hand back a cursor positioned at the beginning of a drive without also delivering the first page: GET {resource}/delta with no token returns the enumeration and the link to continue it. So this returns a synthetic marker, and the first delta call turns it into the real request. The cursor is opaque to the engine by contract, which is what makes that legal rather than a hack — and it is why this adapter can declare deltaIncludesExisting true honestly.
Parameters
session
options
folderId?
string
Returns
Promise<string>
Implementation of
unwatch()
> unwatch(session, watch): Promise<void>
Defined in: drives-microsoft/src/index.ts:719
Cancels a subscription.
Parameters
session
watch
Returns
Promise<void>
Implementation of
upload()
> upload(session, input): Promise<DriveItem>
Defined in: drives-microsoft/src/index.ts:607
Simple upload.
The body is streamed onto the socket, never buffered. The 4 MB ceiling is Graph's own for PUT …/content and the lowest of the three vendors; anything larger needs createUploadSession, which is deliberately out of scope for now, so larger files are refused up front rather than after the bytes have been sent. A source that lies about its size is caught mid-stream by the cap instead of being trusted.
Parameters
session
input
Returns
Promise<DriveItem>
Implementation of
verifyNotification()
> verifyNotification(input): DriveNotificationResult
Defined in: drives-microsoft/src/index.ts:754
Verifies an inbound notification. Pure and synchronous — no session, no network, so hammering the webhook route cannot be amplified into Graph traffic.
Two shapes arrive here:
- The validation handshake. Graph POSTs
?validationToken=…and expects it echoed verbatim astext/plainwithin seconds — duringPOST /subscriptions, so before any subscription exists to look up. Returning it as DriveNotificationResult.challenge lets the shared neutral route answer it; this adapter adds no route of its own. - A change notification, a JSON envelope of one or more entries, each carrying the
clientStatewe chose. There is no signature anywhere in Graph's webhook design:clientStateis the authentication, so an entry without one is rejected rather than treated as anonymous.
One delivery may batch entries for several subscriptions that share a notification URL — two connections of the same tenant, or two tenants behind one route. Reporting only the first would sync one and leave the rest stale, so a batch is reported as DriveNotificationResult.secrets.
Parameters
input
Returns
Implementation of
DriveProvider.verifyNotification
watch()
> watch(session, input): Promise<DriveWatch>
Defined in: drives-microsoft/src/index.ts:690
Registers a Graph change subscription.
clientState is the secret the engine generated, and it is the whole of the authentication: Graph does not sign notifications. It comes back on every delivery and verifyNotification compares it in constant time.
Two things worth knowing, both surfaced rather than hidden:
- Graph calls the notification URL synchronously while creating the subscription, with a
validationTokenit expects echoed astext/plainwithin seconds. Awatch()that fails with400 subscriptionValidationFailedmeans the route is not reachable from the internet, not that the code is wrong. - The subscription expires — under 30 days for a drive, less for other resources — and Graph never renews it. DriveWatch.expiresAt is surfaced so the app can renew it from a reconciler; see the README.
Parameters
session
input
Returns
Promise<DriveWatch>