google-workspace-admin-mcp 0.0.0-stage → 0.1.0-beta.101

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (219) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +169 -2
  3. package/dist/auth/config.d.ts +14 -0
  4. package/dist/auth/config.d.ts.map +1 -0
  5. package/dist/auth/config.js +49 -0
  6. package/dist/auth/config.js.map +1 -0
  7. package/dist/auth/edition.d.ts +26 -0
  8. package/dist/auth/edition.d.ts.map +1 -0
  9. package/dist/auth/edition.js +64 -0
  10. package/dist/auth/edition.js.map +1 -0
  11. package/dist/auth/oauth.d.ts +10 -0
  12. package/dist/auth/oauth.d.ts.map +1 -0
  13. package/dist/auth/oauth.js +84 -0
  14. package/dist/auth/oauth.js.map +1 -0
  15. package/dist/auth/token-store.d.ts +14 -0
  16. package/dist/auth/token-store.d.ts.map +1 -0
  17. package/dist/auth/token-store.js +37 -0
  18. package/dist/auth/token-store.js.map +1 -0
  19. package/dist/catalog.d.ts +33 -0
  20. package/dist/catalog.d.ts.map +1 -0
  21. package/dist/catalog.js +7 -0
  22. package/dist/catalog.js.map +1 -0
  23. package/dist/docs/scopes.d.ts +8 -0
  24. package/dist/docs/scopes.d.ts.map +1 -0
  25. package/dist/docs/scopes.js +23 -0
  26. package/dist/docs/scopes.js.map +1 -0
  27. package/dist/docs/tools.d.ts +18 -0
  28. package/dist/docs/tools.d.ts.map +1 -0
  29. package/dist/docs/tools.js +68 -0
  30. package/dist/docs/tools.js.map +1 -0
  31. package/dist/main.d.ts +3 -0
  32. package/dist/main.d.ts.map +1 -0
  33. package/dist/main.js +75 -0
  34. package/dist/main.js.map +1 -0
  35. package/dist/passthrough/allowlist.d.ts +14 -0
  36. package/dist/passthrough/allowlist.d.ts.map +1 -0
  37. package/dist/passthrough/allowlist.js +28 -0
  38. package/dist/passthrough/allowlist.js.map +1 -0
  39. package/dist/passthrough/dispatch.d.ts +20 -0
  40. package/dist/passthrough/dispatch.d.ts.map +1 -0
  41. package/dist/passthrough/dispatch.js +116 -0
  42. package/dist/passthrough/dispatch.js.map +1 -0
  43. package/dist/safety/audit.d.ts +18 -0
  44. package/dist/safety/audit.d.ts.map +1 -0
  45. package/dist/safety/audit.js +26 -0
  46. package/dist/safety/audit.js.map +1 -0
  47. package/dist/safety/policy.d.ts +14 -0
  48. package/dist/safety/policy.d.ts.map +1 -0
  49. package/dist/safety/policy.js +29 -0
  50. package/dist/safety/policy.js.map +1 -0
  51. package/dist/server.d.ts +35 -0
  52. package/dist/server.d.ts.map +1 -0
  53. package/dist/server.js +79 -0
  54. package/dist/server.js.map +1 -0
  55. package/dist/services/cloud-search.d.ts +42 -0
  56. package/dist/services/cloud-search.d.ts.map +1 -0
  57. package/dist/services/cloud-search.js +113 -0
  58. package/dist/services/cloud-search.js.map +1 -0
  59. package/dist/services/devices.d.ts +50 -0
  60. package/dist/services/devices.d.ts.map +1 -0
  61. package/dist/services/devices.js +136 -0
  62. package/dist/services/devices.js.map +1 -0
  63. package/dist/services/directory-groups.d.ts +65 -0
  64. package/dist/services/directory-groups.d.ts.map +1 -0
  65. package/dist/services/directory-groups.js +150 -0
  66. package/dist/services/directory-groups.js.map +1 -0
  67. package/dist/services/directory.d.ts +67 -0
  68. package/dist/services/directory.d.ts.map +1 -0
  69. package/dist/services/directory.js +179 -0
  70. package/dist/services/directory.js.map +1 -0
  71. package/dist/services/domains.d.ts +27 -0
  72. package/dist/services/domains.d.ts.map +1 -0
  73. package/dist/services/domains.js +78 -0
  74. package/dist/services/domains.js.map +1 -0
  75. package/dist/services/group-settings-catalog.d.ts +27 -0
  76. package/dist/services/group-settings-catalog.d.ts.map +1 -0
  77. package/dist/services/group-settings-catalog.js +100 -0
  78. package/dist/services/group-settings-catalog.js.map +1 -0
  79. package/dist/services/group-settings.d.ts +26 -0
  80. package/dist/services/group-settings.d.ts.map +1 -0
  81. package/dist/services/group-settings.js +59 -0
  82. package/dist/services/group-settings.js.map +1 -0
  83. package/dist/services/licensing.d.ts +40 -0
  84. package/dist/services/licensing.d.ts.map +1 -0
  85. package/dist/services/licensing.js +96 -0
  86. package/dist/services/licensing.js.map +1 -0
  87. package/dist/services/orgunits.d.ts +40 -0
  88. package/dist/services/orgunits.d.ts.map +1 -0
  89. package/dist/services/orgunits.js +97 -0
  90. package/dist/services/orgunits.js.map +1 -0
  91. package/dist/services/reports.d.ts +98 -0
  92. package/dist/services/reports.d.ts.map +1 -0
  93. package/dist/services/reports.js +240 -0
  94. package/dist/services/reports.js.map +1 -0
  95. package/dist/services/resources.d.ts +96 -0
  96. package/dist/services/resources.d.ts.map +1 -0
  97. package/dist/services/resources.js +275 -0
  98. package/dist/services/resources.js.map +1 -0
  99. package/dist/services/roles.d.ts +62 -0
  100. package/dist/services/roles.d.ts.map +1 -0
  101. package/dist/services/roles.js +142 -0
  102. package/dist/services/roles.js.map +1 -0
  103. package/dist/services/transfer.d.ts +43 -0
  104. package/dist/services/transfer.d.ts.map +1 -0
  105. package/dist/services/transfer.js +98 -0
  106. package/dist/services/transfer.js.map +1 -0
  107. package/dist/services/user-security.d.ts +37 -0
  108. package/dist/services/user-security.d.ts.map +1 -0
  109. package/dist/services/user-security.js +90 -0
  110. package/dist/services/user-security.js.map +1 -0
  111. package/dist/services/vault-query.d.ts +60 -0
  112. package/dist/services/vault-query.d.ts.map +1 -0
  113. package/dist/services/vault-query.js +216 -0
  114. package/dist/services/vault-query.js.map +1 -0
  115. package/dist/services/vault.d.ts +219 -0
  116. package/dist/services/vault.d.ts.map +1 -0
  117. package/dist/services/vault.js +624 -0
  118. package/dist/services/vault.js.map +1 -0
  119. package/dist/smoke/checks.d.ts +26 -0
  120. package/dist/smoke/checks.d.ts.map +1 -0
  121. package/dist/smoke/checks.js +102 -0
  122. package/dist/smoke/checks.js.map +1 -0
  123. package/dist/smoke/guards.d.ts +36 -0
  124. package/dist/smoke/guards.d.ts.map +1 -0
  125. package/dist/smoke/guards.js +111 -0
  126. package/dist/smoke/guards.js.map +1 -0
  127. package/dist/smoke/redact.d.ts +17 -0
  128. package/dist/smoke/redact.d.ts.map +1 -0
  129. package/dist/smoke/redact.js +103 -0
  130. package/dist/smoke/redact.js.map +1 -0
  131. package/dist/smoke/report.d.ts +38 -0
  132. package/dist/smoke/report.d.ts.map +1 -0
  133. package/dist/smoke/report.js +93 -0
  134. package/dist/smoke/report.js.map +1 -0
  135. package/dist/smoke/shape.d.ts +26 -0
  136. package/dist/smoke/shape.d.ts.map +1 -0
  137. package/dist/smoke/shape.js +96 -0
  138. package/dist/smoke/shape.js.map +1 -0
  139. package/dist/tools/cloud-search.d.ts +4 -0
  140. package/dist/tools/cloud-search.d.ts.map +1 -0
  141. package/dist/tools/cloud-search.js +82 -0
  142. package/dist/tools/cloud-search.js.map +1 -0
  143. package/dist/tools/directory/devices.d.ts +4 -0
  144. package/dist/tools/directory/devices.d.ts.map +1 -0
  145. package/dist/tools/directory/devices.js +133 -0
  146. package/dist/tools/directory/devices.js.map +1 -0
  147. package/dist/tools/directory/domains.d.ts +4 -0
  148. package/dist/tools/directory/domains.d.ts.map +1 -0
  149. package/dist/tools/directory/domains.js +79 -0
  150. package/dist/tools/directory/domains.js.map +1 -0
  151. package/dist/tools/directory/groups.d.ts +4 -0
  152. package/dist/tools/directory/groups.d.ts.map +1 -0
  153. package/dist/tools/directory/groups.js +192 -0
  154. package/dist/tools/directory/groups.js.map +1 -0
  155. package/dist/tools/directory/orgunits.d.ts +4 -0
  156. package/dist/tools/directory/orgunits.d.ts.map +1 -0
  157. package/dist/tools/directory/orgunits.js +117 -0
  158. package/dist/tools/directory/orgunits.js.map +1 -0
  159. package/dist/tools/directory/roles.d.ts +4 -0
  160. package/dist/tools/directory/roles.d.ts.map +1 -0
  161. package/dist/tools/directory/roles.js +155 -0
  162. package/dist/tools/directory/roles.js.map +1 -0
  163. package/dist/tools/directory/user-security.d.ts +4 -0
  164. package/dist/tools/directory/user-security.d.ts.map +1 -0
  165. package/dist/tools/directory/user-security.js +115 -0
  166. package/dist/tools/directory/user-security.js.map +1 -0
  167. package/dist/tools/directory/users.d.ts +4 -0
  168. package/dist/tools/directory/users.d.ts.map +1 -0
  169. package/dist/tools/directory/users.js +261 -0
  170. package/dist/tools/directory/users.js.map +1 -0
  171. package/dist/tools/directory.d.ts +23 -0
  172. package/dist/tools/directory.d.ts.map +1 -0
  173. package/dist/tools/directory.js +23 -0
  174. package/dist/tools/directory.js.map +1 -0
  175. package/dist/tools/group-settings.d.ts +4 -0
  176. package/dist/tools/group-settings.d.ts.map +1 -0
  177. package/dist/tools/group-settings.js +47 -0
  178. package/dist/tools/group-settings.js.map +1 -0
  179. package/dist/tools/licensing.d.ts +4 -0
  180. package/dist/tools/licensing.d.ts.map +1 -0
  181. package/dist/tools/licensing.js +99 -0
  182. package/dist/tools/licensing.js.map +1 -0
  183. package/dist/tools/reports.d.ts +4 -0
  184. package/dist/tools/reports.d.ts.map +1 -0
  185. package/dist/tools/reports.js +120 -0
  186. package/dist/tools/reports.js.map +1 -0
  187. package/dist/tools/resources.d.ts +4 -0
  188. package/dist/tools/resources.d.ts.map +1 -0
  189. package/dist/tools/resources.js +309 -0
  190. package/dist/tools/resources.js.map +1 -0
  191. package/dist/tools/system.d.ts +16 -0
  192. package/dist/tools/system.d.ts.map +1 -0
  193. package/dist/tools/system.js +73 -0
  194. package/dist/tools/system.js.map +1 -0
  195. package/dist/tools/transfer.d.ts +4 -0
  196. package/dist/tools/transfer.d.ts.map +1 -0
  197. package/dist/tools/transfer.js +96 -0
  198. package/dist/tools/transfer.js.map +1 -0
  199. package/dist/tools/vault.d.ts +4 -0
  200. package/dist/tools/vault.d.ts.map +1 -0
  201. package/dist/tools/vault.js +656 -0
  202. package/dist/tools/vault.js.map +1 -0
  203. package/dist/util/errors.d.ts +18 -0
  204. package/dist/util/errors.d.ts.map +1 -0
  205. package/dist/util/errors.js +97 -0
  206. package/dist/util/errors.js.map +1 -0
  207. package/dist/util/redact.d.ts +12 -0
  208. package/dist/util/redact.d.ts.map +1 -0
  209. package/dist/util/redact.js +37 -0
  210. package/dist/util/redact.js.map +1 -0
  211. package/dist/version.d.ts +7 -0
  212. package/dist/version.d.ts.map +1 -0
  213. package/dist/version.js +8 -0
  214. package/dist/version.js.map +1 -0
  215. package/docs/SETUP.md +260 -0
  216. package/docs/SMOKE-TESTING.md +176 -0
  217. package/docs/TOOLS.md +131 -0
  218. package/docs/api/scopes.json +59 -0
  219. package/package.json +79 -4
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Single Barrel Labs
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,170 @@
1
- # Temporary Holding Version
1
+ # google-workspace-admin-mcp
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ An MCP server for the **Google Workspace admin plane**: the APIs that manage a
4
+ tenant, not the ones that read a user's mail.
5
+
6
+ > **Status: 0.1.1.** Eight admin surfaces, 107 tools, published to npm.
7
+ > [`docs/TOOLS.md`](docs/TOOLS.md) lists every tool; [`docs/SETUP.md`](docs/SETUP.md)
8
+ > takes you from a clean Cloud project to a working server.
9
+
10
+ ## Why
11
+
12
+ Google now ships hosted MCP servers for user surfaces — Gmail, Drive, Calendar.
13
+ Nothing covers the admin surfaces where an administrator actually spends their
14
+ day: who exists, what happened, what is licensed, what must be held or
15
+ transferred. The community servers that touch admin APIs are shallow, stale, or
16
+ built around key files.
17
+
18
+ Admin work is also **sequence** work. "User reports a phishing email" is not one
19
+ API call, it is: find the user, read their recent logins, list their OAuth
20
+ grants, list their app passwords and devices, revoke sessions, then decide
21
+ whether to suspend. Tools alone are not the product; the sequence is. MCP makes
22
+ sequences cheap, which is why this belongs here rather than in a dashboard.
23
+
24
+ ## What this is not
25
+
26
+ **This server cannot read your users' mail.** That is enforced in code, not just
27
+ stated in a README:
28
+
29
+ - No service accounts. No key files, no JWT signing, no key rotation.
30
+ - No domain-wide delegation.
31
+ - No impersonation: there is no `as` parameter anywhere, and no credential type
32
+ that could express one.
33
+ - No user-content APIs: Gmail, Drive, Docs, Sheets, Slides, the Calendar API,
34
+ Chat, Meet, Keep, Tasks, Forms, YouTube, Classroom, Sites and Apps Script are
35
+ out of scope, permanently. (Calendar *resources* — the rooms a company books —
36
+ are admin data and are in scope.)
37
+
38
+ The supported paths for the things people use impersonation for are the audited
39
+ ones: **Vault** for legal holds and eDiscovery, **Data Transfer** for offboarding,
40
+ **Reports** for investigation. That is the whole design.
41
+
42
+ It is also not a GAM replacement. GAM is a scripting language with a decade of
43
+ edge cases; this is a small set of typed tools built to be driven by a model
44
+ without guessing.
45
+
46
+ ## Scope
47
+
48
+ | Surface | What it covers |
49
+ | --- | --- |
50
+ | Directory | users, aliases, groups, members, org units, roles, devices, tokens, domains |
51
+ | Reports | audit activities, customer and entity usage reports |
52
+ | Vault | matters, holds, held accounts, exports, saved queries, operations |
53
+ | Cloud Search | query, suggest, sources |
54
+ | Data Transfer | transfers for offboarding |
55
+ | Enterprise License Manager | assign, revoke, list |
56
+ | Groups Settings | group access and moderation settings |
57
+ | Calendar Resources | buildings, rooms, features |
58
+ | Passthrough | one allowlisted raw call per enabled API, for what curated tools miss |
59
+
60
+ ## Authentication
61
+
62
+ One credential: a **Desktop-app OAuth client** in your own Cloud project, with
63
+ the consent screen set to **Internal**. The administrator signs in once; the
64
+ refresh token is stored with owner-only permissions.
65
+
66
+ - No service account, no DWD grant, no key file to rotate.
67
+ - Internal keeps refresh tokens long-lived. A client left in **Testing** expires
68
+ them after seven days; [`docs/SETUP.md`](docs/SETUP.md#the-seven-day-trap)
69
+ explains the fix.
70
+ - Scopes are admin-only. Nothing requested grants another user's mail or files.
71
+
72
+ ## Safety model
73
+
74
+ - **Read-only by default.** Mutating tools are absent unless writes are enabled.
75
+ - **Confirmation on destructive operations** (suspend, delete, revoke, transfer,
76
+ hold removal, export creation) — the caller must pass an explicit confirm flag
77
+ that the tool documents.
78
+ - **Append-only local audit log** of every tool call: timestamp, tool, arguments
79
+ (secrets redacted), outcome.
80
+ - **Edition-aware errors.** Vault and Cloud Search require Enterprise or
81
+ Education; Data Transfer is broadly but not universally available. Those
82
+ tools say so instead of surfacing a bare 403.
83
+
84
+ ## Install
85
+
86
+ ```bash
87
+ export GWS_CLIENT_ID=... # Desktop-app OAuth client, Internal consent screen
88
+ export GWS_CLIENT_SECRET=...
89
+ npx google-workspace-admin-mcp@latest auth
90
+ ```
91
+
92
+ Authorization prints a URL, waits for the loopback callback and stores the
93
+ refresh token. Then add the server to your client:
94
+
95
+ ```json
96
+ {
97
+ "mcpServers": {
98
+ "gwa": {
99
+ "command": "npx",
100
+ "args": ["-y", "google-workspace-admin-mcp@latest"],
101
+ "env": {
102
+ "GWS_CLIENT_ID": "…",
103
+ "GWS_CLIENT_SECRET": "…"
104
+ }
105
+ }
106
+ }
107
+ }
108
+ ```
109
+
110
+ That block is the shape Claude Desktop and Claude Code use; OpenCode puts the
111
+ same command under `mcp.servers` in its config. A client you launch from a shell
112
+ that already exports the two variables needs no `env` block at all.
113
+
114
+ The server starts **read-only**: mutating tools are absent, not merely refused.
115
+ Set `GWS_MODE=write` to register them, and `GWS_PASSTHROUGH=on` for the
116
+ allowlisted raw-call tools.
117
+
118
+ The full walkthrough — six APIs, consent screen, admin roles per surface,
119
+ editions, the seven-day trap — is in [`docs/SETUP.md`](docs/SETUP.md).
120
+
121
+ ## What to ask it
122
+
123
+ - "Find jane@, list her recent logins, her OAuth grants and her devices." →
124
+ directory and audit tools, read-only.
125
+ - "Who changed group membership in the last week?" → flattened audit events.
126
+ - "Offboard jane@: revoke app grants, sign out sessions, list devices, then
127
+ suspend." → the destructive calls each ask for confirmation; run it in write
128
+ mode.
129
+ - "Which licence seats are unused?" → licence list plus user last-login data.
130
+ - "Can this tenant use Vault?" → `gws_auth_status` reports the edition it probed
131
+ and the source of that answer.
132
+
133
+ ## Development
134
+
135
+ ```bash
136
+ npm install
137
+ npm run check # typecheck, lint, scope check, tests
138
+ ```
139
+
140
+ `npm run docs:scopes` regenerates the scope list in `docs/SETUP.md` from
141
+ `ADMIN_SCOPES`; `npm run check` fails when the two disagree.
142
+
143
+ Specs live in `openspec/specs/`, one per capability; the archived change that
144
+ produced them is under `openspec/changes/archive/`. OpenSpec is used for
145
+ planning only; tests are the enforcement mechanism.
146
+
147
+ No live Workspace tenant is needed to contribute. Verification tiers, tenant
148
+ access levels, the redaction rules for smoke output and the smoke commands are in
149
+ [`docs/SMOKE-TESTING.md`](docs/SMOKE-TESTING.md). Smoke never runs in CI, and the
150
+ runner refuses when it detects one.
151
+
152
+ ## Releases
153
+
154
+ Publishing runs from GitHub Actions, never from a laptop:
155
+
156
+ - **Stable** — a merge to `main` that changes shipping files publishes the next
157
+ patch to `latest` with provenance, then tags `vX.Y.Z` and opens a GitHub
158
+ release. A push that only touches `docs/`, `openspec/`, `test/`, `smoke/` or
159
+ the workflows publishes nothing: it cannot change the tarball.
160
+ - **Preview** — a non-draft PR from this repository publishes
161
+ `<version>-beta.<run_number>` to the `beta` dist-tag, so a branch is
162
+ installable before it merges. `v*-beta*` tags and manual runs do the same.
163
+
164
+ No `NPM_TOKEN` secret is used: npm validates the workflow's OIDC identity
165
+ (trusted publisher bound to this repository and `ci.yml`).
166
+
167
+ ## License
168
+
169
+ MIT. Part of the Single Barrel Labs MCP family — `google-services-mcp` covers the
170
+ user plane, this covers the admin plane.
@@ -0,0 +1,14 @@
1
+ export declare const ADMIN_SCOPES: readonly ["https://www.googleapis.com/auth/admin.directory.user", "https://www.googleapis.com/auth/admin.directory.user.security", "https://www.googleapis.com/auth/admin.directory.group", "https://www.googleapis.com/auth/admin.directory.group.member", "https://www.googleapis.com/auth/admin.directory.orgunit", "https://www.googleapis.com/auth/admin.directory.device.mobile", "https://www.googleapis.com/auth/admin.directory.device.chromeos", "https://www.googleapis.com/auth/admin.directory.rolemanagement", "https://www.googleapis.com/auth/admin.directory.domain", "https://www.googleapis.com/auth/admin.directory.customer.readonly", "https://www.googleapis.com/auth/admin.directory.resource.calendar", "https://www.googleapis.com/auth/admin.reports.audit.readonly", "https://www.googleapis.com/auth/admin.reports.usage.readonly", "https://www.googleapis.com/auth/admin.datatransfer", "https://www.googleapis.com/auth/apps.licensing", "https://www.googleapis.com/auth/ediscovery", "https://www.googleapis.com/auth/cloud_search.query", "https://www.googleapis.com/auth/apps.groups.settings"];
2
+ export interface AppConfig {
3
+ mode: "readonly" | "write";
4
+ passthrough: boolean;
5
+ clientId?: string;
6
+ clientSecret?: string;
7
+ tokenPath: string;
8
+ auditPath: string;
9
+ scopes: string[];
10
+ }
11
+ export declare function loadConfig(env?: NodeJS.ProcessEnv): AppConfig;
12
+ /** Fails if a user-content scope ever enters the requested set. */
13
+ export declare function assertAdminOnlyScopes(scopes: string[]): void;
14
+ //# sourceMappingURL=config.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/auth/config.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,YAAY,YACvB,sDAAsD,EACtD,+DAA+D,EAC/D,uDAAuD,EACvD,8DAA8D,EAC9D,yDAAyD,EACzD,+DAA+D,EAC/D,iEAAiE,EACjE,gEAAgE,EAChE,wDAAwD,EACxD,mEAAmE,EACnE,mEAAmE,EACnE,8DAA8D,EAC9D,8DAA8D,EAC9D,oDAAoD,EAIpD,gDAAgD,EAChD,4CAA4C,EAC5C,oDAAoD,EACpD,sDAAsD,CAC9C,CAAC;AAKX,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC;IAC3B,WAAW,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,wBAAgB,UAAU,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,SAAS,CAc1E;AAED,mEAAmE;AACnE,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,CAK5D"}
@@ -0,0 +1,49 @@
1
+ import { homedir } from "node:os";
2
+ import { join } from "node:path";
3
+ // Note: the scope set is admin-only by construction. A user-content scope here
4
+ // would break the project's central guarantee, and the test suite asserts it.
5
+ export const ADMIN_SCOPES = [
6
+ "https://www.googleapis.com/auth/admin.directory.user",
7
+ "https://www.googleapis.com/auth/admin.directory.user.security",
8
+ "https://www.googleapis.com/auth/admin.directory.group",
9
+ "https://www.googleapis.com/auth/admin.directory.group.member",
10
+ "https://www.googleapis.com/auth/admin.directory.orgunit",
11
+ "https://www.googleapis.com/auth/admin.directory.device.mobile",
12
+ "https://www.googleapis.com/auth/admin.directory.device.chromeos",
13
+ "https://www.googleapis.com/auth/admin.directory.rolemanagement",
14
+ "https://www.googleapis.com/auth/admin.directory.domain",
15
+ "https://www.googleapis.com/auth/admin.directory.customer.readonly",
16
+ "https://www.googleapis.com/auth/admin.directory.resource.calendar",
17
+ "https://www.googleapis.com/auth/admin.reports.audit.readonly",
18
+ "https://www.googleapis.com/auth/admin.reports.usage.readonly",
19
+ "https://www.googleapis.com/auth/admin.datatransfer",
20
+ // Alert Center is not a surface: Google requires a service account with
21
+ // domain-wide delegation, so apps.alerts can never be granted to this server.
22
+ // domain-wide delegation, so apps.alerts can never be granted here.
23
+ "https://www.googleapis.com/auth/apps.licensing",
24
+ "https://www.googleapis.com/auth/ediscovery",
25
+ "https://www.googleapis.com/auth/cloud_search.query",
26
+ "https://www.googleapis.com/auth/apps.groups.settings",
27
+ ];
28
+ const USER_CONTENT = /(^|\/)(gmail|drive|documents|spreadsheets|presentations|calendar|chat|meet|keep|tasks|forms|youtube|classroom)(\.|\/|$)/i;
29
+ export function loadConfig(env = process.env) {
30
+ const stateDir = env.GWS_STATE_DIR ?? join(homedir(), ".local", "state", "google-workspace-admin-mcp");
31
+ const mode = env.GWS_MODE === "write" ? "write" : "readonly";
32
+ return {
33
+ mode,
34
+ passthrough: env.GWS_PASSTHROUGH === "on",
35
+ clientId: env.GWS_CLIENT_ID,
36
+ clientSecret: env.GWS_CLIENT_SECRET,
37
+ tokenPath: env.GWS_TOKEN_PATH ?? join(stateDir, "token.json"),
38
+ auditPath: env.GWS_AUDIT_LOG ?? join(stateDir, "audit.jsonl"),
39
+ scopes: [...ADMIN_SCOPES],
40
+ };
41
+ }
42
+ /** Fails if a user-content scope ever enters the requested set. */
43
+ export function assertAdminOnlyScopes(scopes) {
44
+ const offending = scopes.filter((scope) => USER_CONTENT.test(scope));
45
+ if (offending.length > 0) {
46
+ throw new Error(`User-content scopes are a permanent non-goal, found: ${offending.join(", ")}`);
47
+ }
48
+ }
49
+ //# sourceMappingURL=config.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/auth/config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,+EAA+E;AAC/E,8EAA8E;AAE9E,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,sDAAsD;IACtD,+DAA+D;IAC/D,uDAAuD;IACvD,8DAA8D;IAC9D,yDAAyD;IACzD,+DAA+D;IAC/D,iEAAiE;IACjE,gEAAgE;IAChE,wDAAwD;IACxD,mEAAmE;IACnE,mEAAmE;IACnE,8DAA8D;IAC9D,8DAA8D;IAC9D,oDAAoD;IACpD,wEAAwE;IACxE,8EAA8E;IAC9E,oEAAoE;IACpE,gDAAgD;IAChD,4CAA4C;IAC5C,oDAAoD;IACpD,sDAAsD;CAC9C,CAAC;AAEX,MAAM,YAAY,GAChB,0HAA0H,CAAC;AAY7H,MAAM,UAAU,UAAU,CAAC,GAAG,GAAsB,OAAO,CAAC,GAAG;IAC7D,MAAM,QAAQ,GACZ,GAAG,CAAC,aAAa,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,4BAA4B,CAAC,CAAC;IACxF,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU,CAAC;IAE7D,OAAO;QACL,IAAI;QACJ,WAAW,EAAE,GAAG,CAAC,eAAe,KAAK,IAAI;QACzC,QAAQ,EAAE,GAAG,CAAC,aAAa;QAC3B,YAAY,EAAE,GAAG,CAAC,iBAAiB;QACnC,SAAS,EAAE,GAAG,CAAC,cAAc,IAAI,IAAI,CAAC,QAAQ,EAAE,YAAY,CAAC;QAC7D,SAAS,EAAE,GAAG,CAAC,aAAa,IAAI,IAAI,CAAC,QAAQ,EAAE,aAAa,CAAC;QAC7D,MAAM,EAAE,CAAC,GAAG,YAAY,CAAC;KAC1B,CAAC;AACJ,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,qBAAqB,CAAC,MAAgB;IACpD,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IACrE,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CAAC,wDAAwD,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAClG,CAAC;AACH,CAAC"}
@@ -0,0 +1,26 @@
1
+ import type { OAuth2Client } from "google-auth-library";
2
+ export type EditionState = "enterprise" | "not_enterprise" | "unknown";
3
+ export interface EditionReport {
4
+ /** Which call produced the answer, so the answer can be judged. */
5
+ source: string;
6
+ state: EditionState;
7
+ detail: string;
8
+ }
9
+ /**
10
+ * Infers whether the tenant has an Enterprise-class edition by asking Vault for
11
+ * the smallest possible page. Vault is the cheapest surface that only those
12
+ * editions can reach.
13
+ *
14
+ * The inference is deliberately conservative: an API that is not enabled, or an
15
+ * admin without the Vault privilege, proves nothing about the edition, so both
16
+ * report "unknown" instead of being read as an entitlement failure.
17
+ */
18
+ export declare class EditionProbe {
19
+ private readonly auth;
20
+ private cached?;
21
+ constructor(auth: OAuth2Client);
22
+ /** Probes once per process and reuses the answer for every later caller. */
23
+ report(): Promise<EditionReport>;
24
+ private probe;
25
+ }
26
+ //# sourceMappingURL=edition.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"edition.d.ts","sourceRoot":"","sources":["../../src/auth/edition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAIxD,MAAM,MAAM,YAAY,GAAG,YAAY,GAAG,gBAAgB,GAAG,SAAS,CAAC;AAEvE,MAAM,WAAW,aAAa;IAC5B,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,YAAY,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,qBAAa,YAAY;IAGX,OAAO,CAAC,QAAQ,CAAC,IAAI;IAFjC,OAAO,CAAC,MAAM,CAAC,CAAyB;IAExC,YAA6B,IAAI,EAAE,YAAY,EAAI;IAEnD,4EAA4E;IAC5E,MAAM,IAAI,OAAO,CAAC,aAAa,CAAC,CAG/B;YAEa,KAAK;CAmCpB"}
@@ -0,0 +1,64 @@
1
+ import { google } from "googleapis";
2
+ import { mapGoogleError } from "../util/errors.js";
3
+ /**
4
+ * Infers whether the tenant has an Enterprise-class edition by asking Vault for
5
+ * the smallest possible page. Vault is the cheapest surface that only those
6
+ * editions can reach.
7
+ *
8
+ * The inference is deliberately conservative: an API that is not enabled, or an
9
+ * admin without the Vault privilege, proves nothing about the edition, so both
10
+ * report "unknown" instead of being read as an entitlement failure.
11
+ */
12
+ export class EditionProbe {
13
+ auth;
14
+ cached;
15
+ constructor(auth) {
16
+ this.auth = auth;
17
+ }
18
+ /** Probes once per process and reuses the answer for every later caller. */
19
+ report() {
20
+ this.cached ??= this.probe();
21
+ return this.cached;
22
+ }
23
+ async probe() {
24
+ const source = "vault.matters.list";
25
+ try {
26
+ await google.vault({ version: "v1", auth: this.auth }).matters.list({ pageSize: 1 });
27
+ return {
28
+ source,
29
+ state: "enterprise",
30
+ detail: "Vault answered, so this tenant has an Enterprise-class edition.",
31
+ };
32
+ }
33
+ catch (error) {
34
+ const reason = firstReason(error);
35
+ if (reason === "accessNotConfigured") {
36
+ return {
37
+ source,
38
+ state: "unknown",
39
+ detail: "The Vault API is not enabled in this Cloud project, so the edition cannot be inferred.",
40
+ };
41
+ }
42
+ const mapped = mapGoogleError(error, "vault");
43
+ if (mapped.category === "edition_unavailable") {
44
+ return { source, state: "not_enterprise", detail: mapped.message };
45
+ }
46
+ if (mapped.category === "permission_denied") {
47
+ return {
48
+ source,
49
+ state: "unknown",
50
+ detail: "Vault is enabled but this admin has no Vault privilege, so the edition cannot be inferred.",
51
+ };
52
+ }
53
+ return { source, state: "unknown", detail: mapped.message };
54
+ }
55
+ }
56
+ }
57
+ function firstReason(error) {
58
+ const body = error.response?.data?.error;
59
+ if (!body || typeof body === "string")
60
+ return undefined;
61
+ const errors = body.errors ?? [];
62
+ return errors.map((entry) => entry.reason).find(Boolean);
63
+ }
64
+ //# sourceMappingURL=edition.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"edition.js","sourceRoot":"","sources":["../../src/auth/edition.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AACpC,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAWnD;;;;;;;;GAQG;AACH,MAAM,OAAO,YAAY;IAGM,IAAI;IAFzB,MAAM,CAA0B;IAExC,YAA6B,IAAkB;oBAAlB,IAAI;IAAiB,CAAC;IAEnD,4EAA4E;IAC5E,MAAM;QACJ,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC;QAC7B,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAEO,KAAK,CAAC,KAAK;QACjB,MAAM,MAAM,GAAG,oBAAoB,CAAC;QACpC,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,KAAK,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,CAAC,CAAC;YACrF,OAAO;gBACL,MAAM;gBACN,KAAK,EAAE,YAAY;gBACnB,MAAM,EAAE,iEAAiE;aAC1E,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,MAAM,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;YAClC,IAAI,MAAM,KAAK,qBAAqB,EAAE,CAAC;gBACrC,OAAO;oBACL,MAAM;oBACN,KAAK,EAAE,SAAS;oBAChB,MAAM,EACJ,wFAAwF;iBAC3F,CAAC;YACJ,CAAC;YAED,MAAM,MAAM,GAAG,cAAc,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;YAC9C,IAAI,MAAM,CAAC,QAAQ,KAAK,qBAAqB,EAAE,CAAC;gBAC9C,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;YACrE,CAAC;YACD,IAAI,MAAM,CAAC,QAAQ,KAAK,mBAAmB,EAAE,CAAC;gBAC5C,OAAO;oBACL,MAAM;oBACN,KAAK,EAAE,SAAS;oBAChB,MAAM,EACJ,4FAA4F;iBAC/F,CAAC;YACJ,CAAC;YACD,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC;QAC9D,CAAC;IACH,CAAC;CACF;AAED,SAAS,WAAW,CAAC,KAAc;IACjC,MAAM,IAAI,GAAI,KAAuD,CAAC,QAAQ,EAAE,IAAI,EAAE,KAAK,CAAC;IAC5F,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IACxD,MAAM,MAAM,GAAI,IAAgD,CAAC,MAAM,IAAI,EAAE,CAAC;IAC9E,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AAC3D,CAAC"}
@@ -0,0 +1,10 @@
1
+ import { OAuth2Client } from "google-auth-library";
2
+ import type { AppConfig } from "./config.js";
3
+ import type { FileTokenStore, StoredToken } from "./token-store.js";
4
+ export declare function createOAuthClient(config: AppConfig): OAuth2Client;
5
+ /**
6
+ * Loopback consent flow. Prints the URL instead of opening a browser so it works
7
+ * over SSH, and waits for the callback on a local ephemeral port.
8
+ */
9
+ export declare function authorize(config: AppConfig, store: FileTokenStore, timeoutMs?: number): Promise<StoredToken>;
10
+ //# sourceMappingURL=oauth.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"oauth.d.ts","sourceRoot":"","sources":["../../src/auth/oauth.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,GAAG,YAAY,CASjE;AAED;;;GAGG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,cAAc,EACrB,SAAS,SAAgB,GACxB,OAAO,CAAC,WAAW,CAAC,CA4CtB"}
@@ -0,0 +1,84 @@
1
+ import { createServer } from "node:http";
2
+ import { OAuth2Client } from "google-auth-library";
3
+ import { ToolError } from "../util/errors.js";
4
+ export function createOAuthClient(config) {
5
+ if (!config.clientId || !config.clientSecret) {
6
+ throw new ToolError("auth_required", "No OAuth client configured.", "Set GWS_CLIENT_ID and GWS_CLIENT_SECRET from your own Google Cloud project, then run: npx google-workspace-admin-mcp auth");
7
+ }
8
+ return new OAuth2Client({ clientId: config.clientId, clientSecret: config.clientSecret });
9
+ }
10
+ /**
11
+ * Loopback consent flow. Prints the URL instead of opening a browser so it works
12
+ * over SSH, and waits for the callback on a local ephemeral port.
13
+ */
14
+ export async function authorize(config, store, timeoutMs = 5 * 60 * 1000) {
15
+ const client = createOAuthClient(config);
16
+ const { server, port } = await listen();
17
+ const redirectUri = `http://127.0.0.1:${port}`;
18
+ const url = client.generateAuthUrl({
19
+ access_type: "offline",
20
+ prompt: "consent",
21
+ scope: config.scopes,
22
+ redirect_uri: redirectUri,
23
+ });
24
+ process.stderr.write([
25
+ "",
26
+ "Open this URL and approve access with your administrator account:",
27
+ url,
28
+ "",
29
+ "Waiting for the callback. Ctrl+C to abort.",
30
+ "",
31
+ ].join("\n"));
32
+ const code = await waitForCode(server, timeoutMs);
33
+ server.close();
34
+ const { tokens } = await client.getToken({ code, redirect_uri: redirectUri });
35
+ const stored = {
36
+ refresh_token: tokens.refresh_token ?? undefined,
37
+ access_token: tokens.access_token ?? undefined,
38
+ expiry_date: tokens.expiry_date ?? undefined,
39
+ scope: tokens.scope ?? undefined,
40
+ token_type: tokens.token_type ?? undefined,
41
+ };
42
+ if (!stored.refresh_token) {
43
+ throw new ToolError("auth_required", "Google did not return a refresh token.", "Remove the app's existing grant in your Google Account permissions, then run auth again.");
44
+ }
45
+ await store.save(stored);
46
+ return stored;
47
+ }
48
+ function listen() {
49
+ return new Promise((resolve, reject) => {
50
+ const server = createServer();
51
+ server.once("error", reject);
52
+ server.listen(0, "127.0.0.1", () => {
53
+ resolve({ server, port: server.address().port });
54
+ });
55
+ });
56
+ }
57
+ function waitForCode(server, timeoutMs) {
58
+ return new Promise((resolve, reject) => {
59
+ const timer = setTimeout(() => {
60
+ reject(new ToolError("auth_required", "Authorization timed out after five minutes."));
61
+ }, timeoutMs);
62
+ server.on("request", (req, res) => {
63
+ const requestUrl = new URL(req.url ?? "/", "http://127.0.0.1");
64
+ const code = requestUrl.searchParams.get("code");
65
+ const error = requestUrl.searchParams.get("error");
66
+ if (error) {
67
+ clearTimeout(timer);
68
+ res.writeHead(400, { "content-type": "text/plain" }).end(`Authorization failed: ${error}`);
69
+ reject(new ToolError("auth_required", `Google returned: ${error}`));
70
+ return;
71
+ }
72
+ if (!code) {
73
+ res.writeHead(404, { "content-type": "text/plain" }).end("Waiting for the OAuth callback.");
74
+ return;
75
+ }
76
+ clearTimeout(timer);
77
+ res
78
+ .writeHead(200, { "content-type": "text/plain" })
79
+ .end("Authorized. You can close this tab.");
80
+ resolve(code);
81
+ });
82
+ });
83
+ }
84
+ //# sourceMappingURL=oauth.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"oauth.js","sourceRoot":"","sources":["../../src/auth/oauth.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,14 @@
1
+ export interface StoredToken {
2
+ refresh_token?: string;
3
+ access_token?: string;
4
+ expiry_date?: number;
5
+ scope?: string;
6
+ token_type?: string;
7
+ }
8
+ export declare class FileTokenStore {
9
+ private readonly path;
10
+ constructor(path: string);
11
+ load(): Promise<StoredToken | undefined>;
12
+ save(token: StoredToken): Promise<void>;
13
+ }
14
+ //# sourceMappingURL=token-store.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"token-store.d.ts","sourceRoot":"","sources":["../../src/auth/token-store.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,WAAW;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAID,qBAAa,cAAc;IACb,OAAO,CAAC,QAAQ,CAAC,IAAI;IAAjC,YAA6B,IAAI,EAAE,MAAM,EAAI;IAEvC,IAAI,IAAI,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAyB7C;IAEK,IAAI,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAO5C;CACF"}
@@ -0,0 +1,37 @@
1
+ import { chmod, mkdir, readFile, rename, stat, writeFile } from "node:fs/promises";
2
+ import { dirname } from "node:path";
3
+ import { ToolError } from "../util/errors.js";
4
+ const OWNER_ONLY = 0o600;
5
+ export class FileTokenStore {
6
+ path;
7
+ constructor(path) {
8
+ this.path = path;
9
+ }
10
+ async load() {
11
+ let mode;
12
+ try {
13
+ mode = (await stat(this.path)).mode & 0o777;
14
+ }
15
+ catch {
16
+ return undefined;
17
+ }
18
+ if ((mode & 0o077) !== 0) {
19
+ throw new ToolError("auth_required", `The token file at ${this.path} is readable by other users.`, `Run: chmod 600 ${this.path} — or delete it and re-authorize.`);
20
+ }
21
+ try {
22
+ return JSON.parse(await readFile(this.path, "utf8"));
23
+ }
24
+ catch (error) {
25
+ throw new ToolError("auth_required", `The token file at ${this.path} is not valid JSON: ${error.message}`, "Delete it and re-authorize.");
26
+ }
27
+ }
28
+ async save(token) {
29
+ await mkdir(dirname(this.path), { recursive: true, mode: 0o700 });
30
+ const temp = `${this.path}.${process.pid}.tmp`;
31
+ await writeFile(temp, JSON.stringify(token, null, 2), { mode: OWNER_ONLY });
32
+ await chmod(temp, OWNER_ONLY);
33
+ await rename(temp, this.path);
34
+ await chmod(this.path, OWNER_ONLY);
35
+ }
36
+ }
37
+ //# sourceMappingURL=token-store.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"token-store.js","sourceRoot":"","sources":["../../src/auth/token-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AACnF,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAU9C,MAAM,UAAU,GAAG,KAAK,CAAC;AAEzB,MAAM,OAAO,cAAc;IACI,IAAI;IAAjC,YAA6B,IAAY;oBAAZ,IAAI;IAAW,CAAC;IAE7C,KAAK,CAAC,IAAI;QACR,IAAI,IAAY,CAAC;QACjB,IAAI,CAAC;YACH,IAAI,GAAG,CAAC,MAAM,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,GAAG,KAAK,CAAC;QAC9C,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,IAAI,CAAC,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC;YACzB,MAAM,IAAI,SAAS,CACjB,eAAe,EACf,qBAAqB,IAAI,CAAC,IAAI,8BAA8B,EAC5D,kBAAkB,IAAI,CAAC,IAAI,mCAAmC,CAC/D,CAAC;QACJ,CAAC;QAED,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAgB,CAAC;QACtE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,SAAS,CACjB,eAAe,EACf,qBAAqB,IAAI,CAAC,IAAI,uBAAwB,KAAe,CAAC,OAAO,EAAE,EAC/E,6BAA6B,CAC9B,CAAC;QACJ,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI,CAAC,KAAkB;QAC3B,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QAClE,MAAM,IAAI,GAAG,GAAG,IAAI,CAAC,IAAI,IAAI,OAAO,CAAC,GAAG,MAAM,CAAC;QAC/C,MAAM,SAAS,CAAC,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,CAAC;QAC5E,MAAM,KAAK,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;QAC9B,MAAM,MAAM,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC;QAC9B,MAAM,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IACrC,CAAC;CACF"}
@@ -0,0 +1,33 @@
1
+ import type { ZodRawShape } from "zod";
2
+ export type Surface = "directory" | "reports" | "vault" | "cloud-search" | "transfer" | "licensing" | "groups-settings" | "resources" | "system";
3
+ export type Access = "read" | "write" | "destructive";
4
+ export type Edition = "all" | "enterprise";
5
+ export interface ToolResult {
6
+ summary: string;
7
+ data?: unknown;
8
+ /**
9
+ * Effective access for a tool that can do both, such as passthrough. The
10
+ * audit log records this instead of the registration class.
11
+ */
12
+ access?: Access;
13
+ }
14
+ export interface ToolContext {
15
+ dryRun: boolean;
16
+ }
17
+ export interface ToolSpec {
18
+ name: string;
19
+ surface: Surface;
20
+ access: Access;
21
+ edition: Edition;
22
+ description: string;
23
+ inputShape: ZodRawShape;
24
+ run: (input: unknown, ctx: ToolContext) => Promise<ToolResult>;
25
+ }
26
+ export type ConfirmedToolSpec = ToolSpec & {
27
+ access: "destructive";
28
+ confirmNote: string;
29
+ };
30
+ export type AnyToolSpec = ToolSpec | ConfirmedToolSpec;
31
+ export declare function isConfirmed(spec: AnyToolSpec): spec is ConfirmedToolSpec;
32
+ export declare function isMutating(spec: AnyToolSpec): boolean;
33
+ //# sourceMappingURL=catalog.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"catalog.d.ts","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AAEvC,MAAM,MAAM,OAAO,GACf,WAAW,GACX,SAAS,GACT,OAAO,GACP,cAAc,GACd,UAAU,GACV,WAAW,GACX,iBAAiB,GACjB,WAAW,GACX,QAAQ,CAAC;AAEb,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,aAAa,CAAC;AAEtD,MAAM,MAAM,OAAO,GAAG,KAAK,GAAG,YAAY,CAAC;AAE3C,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,WAAW,CAAC;IACxB,GAAG,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,WAAW,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;CAChE;AAID,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG;IACzC,MAAM,EAAE,aAAa,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,iBAAiB,CAAC;AAEvD,wBAAgB,WAAW,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,IAAI,iBAAiB,CAExE;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAErD"}
@@ -0,0 +1,7 @@
1
+ export function isConfirmed(spec) {
2
+ return spec.access === "destructive";
3
+ }
4
+ export function isMutating(spec) {
5
+ return spec.access !== "read";
6
+ }
7
+ //# sourceMappingURL=catalog.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"catalog.js","sourceRoot":"","sources":["../src/catalog.ts"],"names":[],"mappings":"AAkDA,MAAM,UAAU,WAAW,CAAC,IAAiB;IAC3C,OAAO,IAAI,CAAC,MAAM,KAAK,aAAa,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,IAAiB;IAC1C,OAAO,IAAI,CAAC,MAAM,KAAK,MAAM,CAAC;AAChC,CAAC"}
@@ -0,0 +1,8 @@
1
+ export declare const SCOPE_START = "<!-- scopes:start -->";
2
+ export declare const SCOPE_END = "<!-- scopes:end -->";
3
+ /** The generated section, markers included, so it can replace itself in place. */
4
+ export declare function renderScopeBlock(scopes: readonly string[]): string;
5
+ export declare function extractScopeBlock(markdown: string): string | undefined;
6
+ /** Replaces the generated section, leaving the rest of the document alone. */
7
+ export declare function replaceScopeBlock(markdown: string, scopes: readonly string[]): string;
8
+ //# sourceMappingURL=scopes.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"scopes.d.ts","sourceRoot":"","sources":["../../src/docs/scopes.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,WAAW,0BAA0B,CAAC;AACnD,eAAO,MAAM,SAAS,wBAAwB,CAAC;AAE/C,kFAAkF;AAClF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAElE;AAED,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAKtE;AAED,8EAA8E;AAC9E,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CASrF"}
@@ -0,0 +1,23 @@
1
+ export const SCOPE_START = "<!-- scopes:start -->";
2
+ export const SCOPE_END = "<!-- scopes:end -->";
3
+ /** The generated section, markers included, so it can replace itself in place. */
4
+ export function renderScopeBlock(scopes) {
5
+ return [SCOPE_START, "", ...scopes.map((scope) => `- \`${scope}\``), "", SCOPE_END].join("\n");
6
+ }
7
+ export function extractScopeBlock(markdown) {
8
+ const start = markdown.indexOf(SCOPE_START);
9
+ const end = markdown.indexOf(SCOPE_END);
10
+ if (start === -1 || end === -1 || end < start)
11
+ return undefined;
12
+ return markdown.slice(start, end + SCOPE_END.length);
13
+ }
14
+ /** Replaces the generated section, leaving the rest of the document alone. */
15
+ export function replaceScopeBlock(markdown, scopes) {
16
+ const start = markdown.indexOf(SCOPE_START);
17
+ const end = markdown.indexOf(SCOPE_END);
18
+ if (start === -1 || end === -1 || end < start) {
19
+ throw new Error(`docs page is missing the scope markers ${SCOPE_START} / ${SCOPE_END}`);
20
+ }
21
+ return (markdown.slice(0, start) + renderScopeBlock(scopes) + markdown.slice(end + SCOPE_END.length));
22
+ }
23
+ //# sourceMappingURL=scopes.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"scopes.js","sourceRoot":"","sources":["../../src/docs/scopes.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,WAAW,GAAG,uBAAuB,CAAC;AACnD,MAAM,CAAC,MAAM,SAAS,GAAG,qBAAqB,CAAC;AAE/C,kFAAkF;AAClF,MAAM,UAAU,gBAAgB,CAAC,MAAyB;IACxD,OAAO,CAAC,WAAW,EAAE,EAAE,EAAE,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,KAAK,IAAI,CAAC,EAAE,EAAE,EAAE,SAAS,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACjG,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,QAAgB;IAChD,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAC5C,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACxC,IAAI,KAAK,KAAK,CAAC,CAAC,IAAI,GAAG,KAAK,CAAC,CAAC,IAAI,GAAG,GAAG,KAAK;QAAE,OAAO,SAAS,CAAC;IAChE,OAAO,QAAQ,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC;AACvD,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,iBAAiB,CAAC,QAAgB,EAAE,MAAyB;IAC3E,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IAC5C,MAAM,GAAG,GAAG,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACxC,IAAI,KAAK,KAAK,CAAC,CAAC,IAAI,GAAG,KAAK,CAAC,CAAC,IAAI,GAAG,GAAG,KAAK,EAAE,CAAC;QAC9C,MAAM,IAAI,KAAK,CAAC,0CAA0C,WAAW,MAAM,SAAS,EAAE,CAAC,CAAC;IAC1F,CAAC;IACD,OAAO,CACL,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,gBAAgB,CAAC,MAAM,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,GAAG,GAAG,SAAS,CAAC,MAAM,CAAC,CAC7F,CAAC;AACJ,CAAC"}