basalt / drives/src / DriveNotificationResult

Interface: DriveNotificationResult

The outcome of verifying an inbound notification.

challenge covers the handshake every one of the three vendors performs before it will deliver anything: Microsoft Graph POSTs a validationToken that must be echoed as text/plain, Dropbox GETs a challenge parameter, Google sends a sync state message. Returning it lets one neutral route answer all three.

Properties

accountIds?

> optional accountIds?: readonly string[]

Defined in: drives/src/provider.ts:375

Provider account ids the notification is about — Dropbox's list_folder.accounts (dbid:…).

Matched against DriveConnectionAccount.id. One notification can name several accounts, and one account can be connected more than once (two labels, or two tenants), so this resolves to a set of connections rather than one.

It is only ever consulted once the adapter has authenticated the notification — for Dropbox, an HMAC-SHA256 over the raw body under the app secret. An account id a caller merely asserts must never select a connection.

challenge?

> optional challenge?: string

Defined in: drives/src/provider.ts:325

Respond 200 with exactly this body (and content-type: text/plain), and do nothing else.

changed

> changed: boolean

Defined in: drives/src/provider.ts:358

Whether this notification means "there is new work" (most are content-free pings).

externalIds?

> optional externalIds?: readonly string[]

Defined in: drives/src/provider.ts:360

Vendor id the notification is about, when it names one. Most vendors do not.

replayKey?

> optional replayKey?: string

Defined in: drives/src/provider.ts:394

What makes this delivery distinct from another one, for the engine's replay guard — when the vendor has something better than the body.

Absent, the engine keys a delivery by a digest of its raw body, which is right for Dropbox (the body is exactly what the signature covers) and for Graph (a replay repeats the body byte for byte). Google is the exception: its notifications have an empty body and the only thing telling two apart is X-Goog-Message-Number, so the Google adapter reports that here.

The key is only ever read from a result the adapter returned, never from a header the engine picks up on its own. Phase 2 read x-goog-message-number for every provider, which let anyone replaying a signed Dropbox body (or a Graph one) add a fresh number and walk past the guard. A key is worth only what authenticates it: on Google, whoever holds the channel token can mint any number anyway, so nothing is lost there.

secret?

> optional secret?: string

Defined in: drives/src/provider.ts:338

Secret the provider echoed back, for the engine to match against a connection — present only for vendors that let us choose one (Graph clientState, Google channel token).

Dropbox has none. Its webhook URI is registered once per app in the App Console, not per connection: there is no subscription to attach a secret to, the payload is signed with the app secret instead, and the connection is identified by accountIds. Phase 1 assumed every vendor authenticates with a secret we generated; the first real adapter proved otherwise, so a result may now carry accountIds instead.

secrets?

> optional secrets?: readonly string[]

Defined in: drives/src/provider.ts:354

Several secrets, when one delivery batches notifications for more than one subscription.

Microsoft Graph posts a {"value":[…]} envelope, and every subscription that shares a notification URL can contribute an entry to it — two connections of one tenant, or two tenants behind one route. Reporting only the first clientState would sync one connection and leave the rest stale, which is the same failure accountIds and DriveNotificationOutcome.connections were introduced for in phase 2a, arriving from the other direction.

An adapter sets secret for the ordinary one-subscription delivery and this for a batch; the engine matches a connection against either.

watchId?

> optional watchId?: string

Defined in: drives/src/provider.ts:356

Provider subscription/channel id, when the notification carries one.