See also: ADR-005 · ADR-008 · ADR-012 · Drive tools · Back to the index
ADR-013 — The drive tool family, a third motivated exception to the scope freeze
Status: Accepted · Date: 2026-10-17
· Scope: src/tools/Orkeon.Tools.Drive, Orkeon.Tools.Abstractions/Auth (the OAuth client the e-mail and drive families share), Orkeon.Hosting (the drive subdirectory of /credentials), orkeon drive (Orkeon.Scripting.Cli), the Orkeon.Tools umbrella
Context
The owner asked for Google Drive and OneDrive support. Nothing in the repository spoke to either;
a note of the VFS design only envisaged "a network IFileSystemService" for remote storage. Two
shapes were possible, and the owner chose the first on 2026-10-17:
- A tool family, on the model of the e-mail one: explicit tools an agent calls, each guarded by a right.
- A VFS mount: a drive mounted under
/drive/..., every file tool working on it. Deeper, but the VFS is synchronous in places, has no notion of a provider's ids, sharing or Google's own documents, and latency, quotas and caching would leak into every file tool.
The scope freeze holds for the same reason as for e-mail (ADR-012): a script runs on Jint and cannot speak OAuth or HTTP to a provider with a stored token; a plugin would not be "directly in Orkeon" and would rebuild the token storage, the rights and the screening.
The e-mail family already had a hand-written OAuth2 client (device code, loopback PKCE with a
paste fallback, refresh with rotation), a token store behind the internal /credentials root,
the secret reading of the user's environment scope, and Microsoft Graph in plain HTTP — all
internal to Orkeon.Tools.Email.
Decision
- A ninth family,
Orkeon.Tools.Drive, with the layering of ADR-005 (Domain, Tools.Abstractions, Orkeon.Rag for the injection detector, Constants.Configuration), held by an allowlist test. No new package: the Drive API v3 and Microsoft Graph are spoken in plain HTTP withSystem.Text.Json. - The OAuth layer moves to
Orkeon.Tools.Abstractions/Auth, internal and shared by the two families throughInternalsVisibleTo: the client, the loopback listener, the secret reader and the sign-in flows. It throws anOAuthException; each family translates it into its own exception, same message, matching code.IEmailLoginInteractionkeeps its name and now inherits the publicIOAuthLoginInteraction, with no member of its own. - Two engines behind one internal port (
IDrive), one shape of item. Google Drive is found by name under each parent (it has no paths) and its own documents are read and downloaded by export; OneDrive is addressed by path. - The operator decides, the agent names an account.
Rights(Read, Write, Organize, Share, Delete, Purge) is mandatory;Rootconfines an account to a folder, an item outside it being reported as not found; sharing is closed untilShare:AllowedRecipientsnames someone, and public links stay off untilShare:AllowPublicLinks. An account that only reads asks for a read-only scope. - The token never leaves the API host. OneDrive downloads go through the pre-authenticated
downloadUrl, upload sessions get noAuthorizationheader, paging links are checked — never a redirect followed with the token. - One credentials directory per run. The drive tokens live in a
drivesubdirectory of the e-mail family's/credentialsroot, owner-only on Unix; when the two sections name different directories, the e-mail one wins and the runner says so at start. - The forge denies the drive tools: there is no trial drive, and a forged crew must not touch
the operator's actual one.
drive_readscreens and marks its text itself, and bypasses the result sanitizer like the e-mail tools; the other drive tools stay sanitized.
Consequences
- 102 built-in tool classes, 49 src and 37 test projects; the umbrella package carries nine families.
orkeon drive accounts | login | logout | check; the typings of.ork.tsscripts; a "Drive" family in an external client's tool list, driven overloginandcheck --events jsonl.- Google shared drives, SharePoint libraries, revisions, comments, copies and a VFS mount are out of scope, documented in the guide.
- The real-account campaign is the owner's (DRIVE-07): the offline tests script both APIs, and the guide says the family is not yet campaigned.
Amendment (2026-10-29)
- The counts in Consequences (102 built-in tool classes, 49 src and 37 test projects) are those of the day the ADR was written. At this date the repository holds 120 built-in tool classes, 50 src projects and 38 test projects (
scripts/check-doc-claims.py). - The last Consequences bullet says the guide shows the family as not yet campaigned. A campaign pass (DRIVE-07) ran on 2026-10-24; the guide (Drive) states what is recorded, and the DRIVE-07 card is not closed.