mcp-google-multi 6.0.0-beta.3 → 6.0.0-beta.5

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 (126) hide show
  1. package/README.md +20 -6
  2. package/dist/accounts.d.ts +3 -3
  3. package/dist/accounts.js +18 -31
  4. package/dist/arg-normalize.js +15 -35
  5. package/dist/arg-strict.js +8 -28
  6. package/dist/auth.d.ts +1 -1
  7. package/dist/auth.js +5 -10
  8. package/dist/boot-gates.d.ts +1 -1
  9. package/dist/boot-gates.js +3 -5
  10. package/dist/cimd-cache.js +5 -11
  11. package/dist/client-config.d.ts +2 -2
  12. package/dist/client-config.js +8 -14
  13. package/dist/client.js +0 -0
  14. package/dist/compose.d.ts +8 -1
  15. package/dist/compose.js +11 -11
  16. package/dist/config-file.js +7 -12
  17. package/dist/discover.js +6 -12
  18. package/dist/discovery-client.js +14 -33
  19. package/dist/doctor.d.ts +3 -3
  20. package/dist/doctor.js +12 -18
  21. package/dist/env-load.js +2 -5
  22. package/dist/executor.js +2 -4
  23. package/dist/fanout.js +8 -17
  24. package/dist/fs-atomic.d.ts +0 -3
  25. package/dist/fs-atomic.js +104 -22
  26. package/dist/hint-provider.d.ts +4 -1
  27. package/dist/hint-provider.js +4 -10
  28. package/dist/http-config.d.ts +2 -2
  29. package/dist/http-config.js +3 -7
  30. package/dist/http-transport.d.ts +5 -5
  31. package/dist/http-transport.js +39 -92
  32. package/dist/identity.d.ts +2 -2
  33. package/dist/identity.js +6 -9
  34. package/dist/index.js +19 -31
  35. package/dist/master-key.d.ts +3 -3
  36. package/dist/master-key.js +11 -22
  37. package/dist/mcp-token.d.ts +40 -16
  38. package/dist/mcp-token.js +121 -44
  39. package/dist/metrics-cli.d.ts +1 -1
  40. package/dist/metrics-cli.js +1 -1
  41. package/dist/metrics-tap.js +2 -5
  42. package/dist/migrate-config.d.ts +1 -2
  43. package/dist/migrate-config.js +3 -5
  44. package/dist/net-tuning.js +2 -4
  45. package/dist/oauth-as.d.ts +7 -2
  46. package/dist/oauth-as.js +45 -78
  47. package/dist/oauth-consent.js +4 -10
  48. package/dist/outbound-allowlist.js +4 -9
  49. package/dist/reauth-hint.js +2 -5
  50. package/dist/registry-transfer.d.ts +1 -1
  51. package/dist/registry-transfer.js +5 -13
  52. package/dist/registry.d.ts +3 -9
  53. package/dist/registry.js +97 -76
  54. package/dist/scope-catalog.d.ts +5 -0
  55. package/dist/scope-catalog.js +17 -7
  56. package/dist/scope-observability.d.ts +2 -3
  57. package/dist/scope-observability.js +8 -14
  58. package/dist/services.d.ts +3 -0
  59. package/dist/services.js +5 -10
  60. package/dist/ssrf-guard.js +11 -22
  61. package/dist/tenant-purge.js +2 -4
  62. package/dist/token-store.js +0 -0
  63. package/dist/tools/_coerce.d.ts +4 -4
  64. package/dist/tools/_errors.js +22 -39
  65. package/dist/tools/_local-files.js +4 -8
  66. package/dist/tools/account-wizard.d.ts +4 -3
  67. package/dist/tools/account-wizard.js +48 -54
  68. package/dist/tools/accounts-tool.d.ts +8 -1
  69. package/dist/tools/accounts-tool.js +18 -7
  70. package/dist/tools/admin.js +8 -4
  71. package/dist/tools/analytics.js +32 -16
  72. package/dist/tools/calendar.d.ts +5 -0
  73. package/dist/tools/calendar.js +63 -7
  74. package/dist/tools/chat.js +2 -3
  75. package/dist/tools/contacts.js +19 -14
  76. package/dist/tools/docs.js +45 -21
  77. package/dist/tools/drive.js +72 -39
  78. package/dist/tools/forms.js +2 -3
  79. package/dist/tools/generated/gmail.js +0 -14
  80. package/dist/tools/generated/method-map.js +1 -1
  81. package/dist/tools/gmail-mime.d.ts +1 -1
  82. package/dist/tools/gmail-mime.js +7 -12
  83. package/dist/tools/gmail.d.ts +3 -3
  84. package/dist/tools/gmail.js +135 -52
  85. package/dist/tools/google-api.js +5 -7
  86. package/dist/tools/meet.js +2 -3
  87. package/dist/tools/searchconsole.js +2 -3
  88. package/dist/tools/sheets.d.ts +10 -0
  89. package/dist/tools/sheets.js +111 -5
  90. package/dist/tools/slides.js +2 -3
  91. package/dist/tools/tasks.js +2 -3
  92. package/dist/trim.js +2 -3
  93. package/dist/usage-metrics.js +5 -12
  94. package/dist/write-control.d.ts +4 -8
  95. package/dist/write-control.js +18 -6
  96. package/package.json +24 -22
  97. package/skills/google-workspace/SKILL.md +162 -0
  98. package/skills/google-workspace/reference/admin.md +105 -0
  99. package/skills/google-workspace/reference/analytics.md +70 -0
  100. package/skills/google-workspace/reference/appsmarket.md +5 -0
  101. package/skills/google-workspace/reference/calendar.md +175 -0
  102. package/skills/google-workspace/reference/chat.md +59 -0
  103. package/skills/google-workspace/reference/classroom.md +5 -0
  104. package/skills/google-workspace/reference/cloudidentity.md +5 -0
  105. package/skills/google-workspace/reference/cloudsearch.md +5 -0
  106. package/skills/google-workspace/reference/contacts.md +138 -0
  107. package/skills/google-workspace/reference/docs.md +395 -0
  108. package/skills/google-workspace/reference/drive.md +485 -0
  109. package/skills/google-workspace/reference/driveactivity.md +5 -0
  110. package/skills/google-workspace/reference/drivelabels.md +5 -0
  111. package/skills/google-workspace/reference/forms.md +92 -0
  112. package/skills/google-workspace/reference/gmail.md +305 -0
  113. package/skills/google-workspace/reference/groupsmigration.md +5 -0
  114. package/skills/google-workspace/reference/groupssettings.md +5 -0
  115. package/skills/google-workspace/reference/keep.md +5 -0
  116. package/skills/google-workspace/reference/licensing.md +5 -0
  117. package/skills/google-workspace/reference/meet.md +68 -0
  118. package/skills/google-workspace/reference/postmaster.md +5 -0
  119. package/skills/google-workspace/reference/reseller.md +5 -0
  120. package/skills/google-workspace/reference/script.md +5 -0
  121. package/skills/google-workspace/reference/searchconsole.md +128 -0
  122. package/skills/google-workspace/reference/sheets.md +430 -0
  123. package/skills/google-workspace/reference/slides.md +67 -0
  124. package/skills/google-workspace/reference/tasks.md +167 -0
  125. package/skills/google-workspace/reference/vault.md +5 -0
  126. package/skills/google-workspace/reference/workspaceevents.md +5 -0
package/dist/oauth-as.js CHANGED
@@ -1,33 +1,24 @@
1
- // B13: the minimal OAuth 2.1 Authorization Server + Resource Server
2
- // (oauth-authorization-server.md). Federate-and-hold: the server mints its own
3
- // audience-bound HS256 token for the MCP client (leg A), gates on an owner
4
- // Google login (leg B, tokens discarded), and separately holds per-alias Google
5
- // tokens (leg C, unchanged). Mounts into B12's HttpTransportHost as `routes` +
6
- // an `authenticate` for POST /mcp. All Google/CIMD I/O is injectable so the
7
- // whole surface is exercised by an offline harness.
1
+ // The minimal OAuth 2.1 Authorization Server + Resource Server: federate-and-hold
2
+ // (own token / discarded owner login / held per-alias tokens). See docs/internals.md.
8
3
  import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
9
4
  import { isIPv4 } from 'node:net';
10
5
  import { decodeJwt } from 'jose';
11
- import { signAccessToken, verifyAccessToken, signState, verifyState, signAuthzCode, verifyAuthzCode, signReauthLink, verifyReauthLink, signPending, verifyPending, ReplayGuard, RefreshStore, STATE_TTL_DEFAULT, CODE_TTL_DEFAULT, ACCESS_TTL_DEFAULT, } from './mcp-token.js';
6
+ import { signAccessToken, verifyAccessToken, signState, verifyState, signAuthzCode, verifyAuthzCode, signReauthLink, verifyReauthLink, signPending, verifyPending, ReplayGuard, RefreshStore, STATE_TTL_DEFAULT, CODE_TTL_DEFAULT, ACCESS_TTL_DEFAULT, clientFingerprint, refreshMacKey, } from './mcp-token.js';
12
7
  import { fetchCimdDocument } from './ssrf-guard.js';
13
8
  import { CimdClientCache } from './cimd-cache.js';
14
9
  import { logSafe } from './trim.js';
15
10
  const CLAUDE_AI_FIXED_CALLBACK = 'https://claude.ai/api/mcp/auth_callback';
16
- // DCR (/register) is public + unauthenticated, so its in-memory store must be
17
- // bounded like every sibling store (the ReplayGuard cap) or a request loop
18
- // OOMs the process. Cap client count (FIFO-evict the oldest) and
19
- // the per-request redirect_uris shape so one entry can't be arbitrarily large.
11
+ // /register is public and unauthenticated, so its store must stay bounded
12
+ // (FIFO-evict the oldest) like every sibling store, or a request loop OOMs.
20
13
  export const DCR_MAX_CLIENTS = 1000;
21
14
  export const DCR_MAX_REDIRECT_URIS = 10;
22
15
  const DCR_MAX_URI_LEN = 2048;
23
16
  const OIDC_SUB = /^[\x21-\x7e]{1,255}$/;
24
17
  const HOSTED_DOMAIN = /^[a-z0-9-]+(\.[a-z0-9-]+)+$/i;
25
- // RFC 6749's error_description charset: %x20-21 / %x23-5B / %x5D-7E (printable
26
- // ASCII minus the backslash and double-quote that would need escaping in the
27
- // query string). A resolveSubject denial outside this set is dropped rather
28
- // than forwarded unvalidated (H3 PR1).
18
+ // RFC 6749 error_description charset (%x20-21/%x23-5B/%x5D-7E); a denial
19
+ // description outside it is dropped rather than forwarded unvalidated.
29
20
  const ERROR_DESCRIPTION_RE = /^[\x20-\x21\x23-\x5b\x5d-\x7e]{1,200}$/;
30
- /** Only trust the id_token identity when Google marks the email verified (#8).
21
+ /** Only trust the id_token identity when Google marks the email verified.
31
22
  * The token comes straight from Google's token endpoint, so its claims are
32
23
  * read unsigned. A malformed sub or hd is dropped, never passed on. */
33
24
  export function verifiedIdentityFromIdToken(idToken) {
@@ -90,7 +81,7 @@ function isLoopbackHostname(h) {
90
81
  // prefix (which would let "127.evil.com" masquerade as loopback).
91
82
  return isIPv4(host) && host.split('.')[0] === '127';
92
83
  }
93
- /** C6: exact redirect_uri match, with RFC 8252 §7.3 port-agnostic loopback and
84
+ /** Exact redirect_uri match, with RFC 8252 §7.3 port-agnostic loopback and
94
85
  * the fixed claude.ai callback. */
95
86
  export function redirectAllowed(redirectUri, docRedirectUris) {
96
87
  if (redirectUri === CLAUDE_AI_FIXED_CALLBACK)
@@ -118,10 +109,7 @@ export function redirectAllowed(redirectUri, docRedirectUris) {
118
109
  return isLoopbackHostname(du.hostname) && du.protocol === r.protocol && du.pathname === r.pathname;
119
110
  });
120
111
  }
121
- // The owner_gate browser binding (docs/internals.md). One cookie per flow, so
122
- // two sign-ins started in one browser do not overwrite each other. __Host-
123
- // requires Secure, which an http base (the loopback owner) cannot rely on in
124
- // every browser, so an http base gets a plain host-only name instead.
112
+ // Owner-gate browser binding: one cookie per flow; see docs/internals.md.
125
113
  const BIND_HASH = /^[A-Za-z0-9_-]{43}$/;
126
114
  function bindCookieName(base, bind) {
127
115
  return `${base.startsWith('https:') ? '__Host-' : ''}mgm-og-${bind.slice(0, 16)}`;
@@ -193,10 +181,7 @@ export function buildAuthServer(config, deps = {}) {
193
181
  const base = config.base;
194
182
  const resource = config.resourceUri;
195
183
  const secret = config.secret;
196
- // States, approvals and codes live minutes, and their single use rests on an
197
- // in-memory replay guard that a restart empties. So they are signed with a
198
- // key only this AuthServer holds: a restart invalidates every one in flight,
199
- // instead of letting a spent or unreserved one pass the new, empty guard.
184
+ // States/approvals/codes are signed with a per-process secret; see docs/internals.md.
200
185
  const flowSecret = new Uint8Array(randomBytes(32));
201
186
  const accessTtl = config.accessTtlSec ?? ACCESS_TTL_DEFAULT;
202
187
  const cimd = deps.fetchCimd ?? ((clientId) => fetchCimdDocument(clientId));
@@ -204,6 +189,14 @@ export function buildAuthServer(config, deps = {}) {
204
189
  const registered = deps.registeredClients ?? new Map();
205
190
  const now = deps.now ?? (() => Date.now());
206
191
  const log = deps.log ?? (() => undefined);
192
+ const clientAddress = deps.clientAddress ?? ((req) => req.socket.remoteAddress);
193
+ // Not used for authorization, only to tell a concurrent duplicate /token
194
+ // request from a different holder of the same refresh token; keyed on the
195
+ // refresh store's own MAC key so a reader of the store file cannot
196
+ // brute-force the client_id/user-agent/address that produced a stored `by`.
197
+ // See docs/internals.md.
198
+ const fingerprintKey = refreshMacKey(config.masterKey);
199
+ const fingerprintOf = (req, clientId) => clientFingerprint(clientId, req.headers['user-agent'] ?? '', clientAddress(req) ?? '', fingerprintKey);
207
200
  // Silently dropping a lifetime the caller asked for would leave sessions unlimited.
208
201
  if (deps.refreshStore && (config.refreshMaxAgeSec !== undefined || config.refreshIdleSec !== undefined || config.refreshMaxFamiliesPerSub !== undefined)) {
209
202
  throw new Error('E_REFRESH_OPTION_CONFLICT: refreshMaxAgeSec, refreshIdleSec and refreshMaxFamiliesPerSub configure the refresh store buildAuthServer creates; set them on the injected refreshStore instead');
@@ -256,7 +249,7 @@ export function buildAuthServer(config, deps = {}) {
256
249
  const reg = registered.get(clientId);
257
250
  if (reg)
258
251
  return { redirect_uris: reg.redirect_uris, dcr: true };
259
- // C7/#5: validate the issuer host + scheme BEFORE any outbound fetch, so we
252
+ // Validate the issuer host + scheme BEFORE any outbound fetch, so we
260
253
  // only ever fetch an allowlisted issuer (no arbitrary-URL SSRF surface).
261
254
  let issuerHost;
262
255
  let scheme;
@@ -273,15 +266,15 @@ export function buildAuthServer(config, deps = {}) {
273
266
  log(`CIMD rejected: issuer=${logSafe(`${scheme}//${issuerHost}`, 80)} not allowlisted client_id_len=${clientId.length}`);
274
267
  return { error: 'E_CIMD_INVALID', message: 'invalid client' };
275
268
  }
276
- // #15: cached only once it validates; the cache logs a failed fetch.
269
+ // Cached only once it validates; the cache logs a failed fetch.
277
270
  const got = await cimdClients.resolve(clientId, (doc) => doc.client_id === clientId && Array.isArray(doc.redirect_uris) && doc.redirect_uris.length > 0);
278
271
  if ('busy' in got)
279
272
  return got;
280
- // #13: never echo internal fetch details to the caller (blind-SSRF oracle).
273
+ // Never echo internal fetch details to the caller (blind-SSRF oracle).
281
274
  if ('error' in got)
282
275
  return { error: got.error, message: 'invalid client' };
283
276
  const uris = got.doc.redirect_uris;
284
- // C6 #14: warn on a localhost-only redirect set (loopback impersonation),
277
+ // Warn on a localhost-only redirect set (loopback impersonation),
285
278
  // once per fetch rather than on every sign-in the cache serves.
286
279
  if (got.fresh && uris.every((u) => { try {
287
280
  return isLoopbackHostname(new URL(u).hostname);
@@ -299,7 +292,7 @@ export function buildAuthServer(config, deps = {}) {
299
292
  /** `incoming`: the artifact spent to get here. If no slot is left for the
300
293
  * new state it is unspent, so retrying it works once a slot frees. */
301
294
  async function toGoogle(res, sp, incoming) {
302
- // H4 F1: without this, a Google URL minted here and forwarded to someone
295
+ // Without this, a Google URL minted here and forwarded to someone
303
296
  // else signs THEM in and hands their subject to the starting client.
304
297
  const headers = {};
305
298
  if (sp.flow === 'owner_gate') {
@@ -323,8 +316,6 @@ export function buildAuthServer(config, deps = {}) {
323
316
  : `https://accounts.google.com/o/oauth2/v2/auth?state=${encodeURIComponent(state)}`;
324
317
  return redirect(res, authUrl, headers);
325
318
  }
326
- // GET /authorize (validate + interstitial for DCR clients); POST /authorize
327
- // (a DCR consent approval — verify the signed pending token, then proceed).
328
319
  const authorize = async (req, res, url) => {
329
320
  if (req.method === 'POST') {
330
321
  let form;
@@ -341,7 +332,6 @@ export function buildAuthServer(config, deps = {}) {
341
332
  catch {
342
333
  return errorPage(res, 400, 'E_STATE_INVALID', 'the approval is invalid or expired');
343
334
  }
344
- // Only the client leg signs pendings, and it is always the owner sign-in.
345
335
  // Defence in depth: a pending from an earlier release, which could carry
346
336
  // flow=alias_reauth, was signed with MCP_JWT_KEY and no longer verifies.
347
337
  if (pending.flow !== 'owner_gate') {
@@ -364,10 +354,8 @@ export function buildAuthServer(config, deps = {}) {
364
354
  const resourceParam = q.get('resource') ?? '';
365
355
  const clientState = q.get('state') ?? undefined;
366
356
  const aliasParam = q.get('alias') ?? undefined;
367
- // Server-minted alias_add link: the whole request identity (tenant, alias,
368
- // bundles) lives inside the SIGNED state — verify, spend it (single-use),
369
- // then re-sign fresh for the Google leg. A tampered tenantId breaks the
370
- // signature; a caller cannot supply one at all.
357
+ // alias_add: tenant/alias/bundles live inside the SIGNED state, verified
358
+ // and spent single-use before re-signing for Google; a caller can't tamper with them.
371
359
  if (q.get('flow') === 'alias_add' && !clientId) {
372
360
  let minted;
373
361
  try {
@@ -388,11 +376,7 @@ export function buildAuthServer(config, deps = {}) {
388
376
  void _spent;
389
377
  return toGoogle(res, sp, minted.jti);
390
378
  }
391
- // In-call re-auth (BV-1): a user-clicked `flow=alias_reauth` link has NO
392
- // client leg — no code is delivered to any client, the refreshed token is
393
- // written server-side for the alias — so it skips the client_id/redirect/
394
- // PKCE requirements. The link must be one this server signed (reauthLink),
395
- // and /callback still binds the completing identity to the alias's email.
379
+ // alias_reauth skips client_id/redirect/PKCE (no client leg); see docs/internals.md.
396
380
  if (q.get('flow') === 'alias_reauth' && !clientId) {
397
381
  if (config.legacyAliasReauth === false) {
398
382
  // Alias-only, tenant-ambiguous: disabled on multi-tenant deployments.
@@ -413,22 +397,18 @@ export function buildAuthServer(config, deps = {}) {
413
397
  return clientUnavailable(res);
414
398
  if ('error' in client)
415
399
  return json(res, 400, { error: 'invalid_client', message: client.message, iss: base }, issHeader);
416
- // (2) exact redirect_uri match BEFORE minting anything (open-redirect defense)
400
+ // Exact redirect_uri match BEFORE minting anything (open-redirect defense).
417
401
  if (!redirectUri || !redirectAllowed(redirectUri, client.redirect_uris)) {
418
402
  return errorPage(res, 400, 'E_REDIRECT_URI_MISMATCH', 'redirect_uri is not an allowed callback for this client');
419
403
  }
420
- // (3) PKCE S256 required
421
404
  if (!codeChallenge || method !== 'S256') {
422
405
  return json(res, 400, { error: 'invalid_request', message: 'code_challenge with S256 required', iss: base }, issHeader);
423
406
  }
424
- // (4) resource must be the canonical resource URI
425
407
  if (resourceParam !== resource) {
426
408
  return json(res, 400, { error: 'invalid_request', message: `resource must be ${resource}`, iss: base }, issHeader);
427
409
  }
428
- // (5) only after full validation do we build the request artifact.
429
- // A client leg is always the owner sign-in. Re-auth has its own signed
430
- // link: accepting flow=alias_reauth here let any client (a self-registered
431
- // one, or a public CIMD client_id) start it and read the alias's scopes.
410
+ // Only after full validation, and always as owner_gate: a caller-supplied
411
+ // flow here would let any client read an alias's scopes via alias_reauth.
432
412
  const statePayload = {
433
413
  flow: 'owner_gate',
434
414
  client_id: clientId,
@@ -437,19 +417,15 @@ export function buildAuthServer(config, deps = {}) {
437
417
  client_state: clientState,
438
418
  resource,
439
419
  };
440
- // Confused-deputy defense (#3): a self-registered DCR client can pick an
441
- // arbitrary redirect_uri, so before we send the owner to Google (whose
442
- // consent screen names only THIS server, not the requesting app), show an
443
- // approval interstitial naming the client + destination. CIMD clients skip
444
- // it — their redirect_uris come from an issuer-allowlisted document a rogue
445
- // cannot forge, so there is nothing to spoof.
420
+ // DCR clients get a consent interstitial naming the client + destination
421
+ // (confused-deputy defense); CIMD clients skip it. See docs/internals.md.
446
422
  if (client.dcr) {
447
423
  const pendingToken = await signPending(statePayload, base, flowSecret, nowSec());
448
424
  res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store', 'Content-Security-Policy': "frame-ancestors 'none'", 'X-Frame-Options': 'DENY' });
449
425
  res.end(`<!doctype html><meta charset=utf-8><title>Authorize access</title>` +
450
426
  `<body style="font-family:system-ui,sans-serif;max-width:36em;margin:3em auto;line-height:1.5">` +
451
427
  `<h2>Authorize access?</h2>` +
452
- `<p>A newly-registered application (<code>${escapeHtml(clientId)}</code>) is requesting access to your Google Workspace through this server.</p>` +
428
+ `<p>An application (<code>${escapeHtml(clientId)}</code>) asks to connect to this server as you.</p>` +
453
429
  `<p>If approved, it will receive an authorization redirected to:<br><code>${escapeHtml(redirectUri)}</code></p>` +
454
430
  `<p><strong>If you did not start this, close this window.</strong></p>` +
455
431
  `<form method="POST" action="/authorize"><input type="hidden" name="pending" value="${escapeHtml(pendingToken)}">` +
@@ -458,7 +434,6 @@ export function buildAuthServer(config, deps = {}) {
458
434
  }
459
435
  return toGoogle(res, statePayload);
460
436
  };
461
- // GET /callback
462
437
  const callback = async (req, res, url) => {
463
438
  const code = url.searchParams.get('code') ?? '';
464
439
  const stateToken = url.searchParams.get('state') ?? '';
@@ -523,26 +498,22 @@ export function buildAuthServer(config, deps = {}) {
523
498
  }
524
499
  log(`callback ok flow=alias_add alias=${logSafe(st.alias, 64)}`);
525
500
  res.writeHead(200, { 'Content-Type': 'text/html' });
526
- res.end(`<!doctype html><meta charset=utf-8><p>Connected "${escapeHtml(st.alias)}". You can close this window and retry your request.</p>`);
501
+ res.end(`<!doctype html><meta charset=utf-8><p>Linked "${escapeHtml(st.alias)}" to this server. Start a new chat to use it.</p>`);
527
502
  return true;
528
503
  }
529
504
  if (st.flow === 'alias_reauth') {
530
505
  if (!st.alias)
531
506
  return errorPage(res, 400, 'invalid_request', 'alias_reauth without an alias');
532
- // C13 / identity binding (#2/#6): only overwrite the alias's tokens if the
533
- // completing Google identity IS that alias's configured account — else an
534
- // attacker who crafts an alias_reauth link and logs in with their OWN
535
- // account could inject their tokens (account swap). The alias emails (leg
536
- // C) are distinct from MCP_OWNER_EMAILS (leg B), so bind to the alias.
507
+ // Identity binding: only overwrite the alias's tokens if the completing
508
+ // Google identity matches the alias's configured account (else account swap).
537
509
  const gotEmail = (exchanged.email ?? '').toLowerCase();
538
510
  const expected = (deps.aliasEmail?.(st.alias) ?? '').toLowerCase();
539
511
  if (!expected || !gotEmail || gotEmail !== expected) {
540
512
  log(`alias_reauth identity mismatch for "${logSafe(st.alias, 64)}" (got ${logSafe(gotEmail || 'none', 254)})`);
541
513
  return errorPage(res, 403, 'access_denied', 'the Google account you signed in with is not the one configured for this alias');
542
514
  }
543
- // A completion without a refresh token (a Google URL built without
544
- // offline access, say) would replace a working credential with one that
545
- // dies within the hour. Keep the stored token instead.
515
+ // A completion without a refresh token would replace a working credential
516
+ // with one that dies within the hour; keep the stored token instead.
546
517
  const refreshToken = exchanged.tokens.refresh_token;
547
518
  if (typeof refreshToken !== 'string' || refreshToken === '') {
548
519
  log(`alias_reauth for "${logSafe(st.alias, 64)}" returned no refresh token; stored token kept`);
@@ -551,9 +522,8 @@ export function buildAuthServer(config, deps = {}) {
551
522
  const granted = typeof exchanged.tokens.scope === 'string' ? exchanged.tokens.scope : undefined;
552
523
  const missing = deps.missingScopes?.(st.alias, granted) ?? [];
553
524
  const listed = missing.map((m) => `<code>${escapeHtml(m)}</code>`).join(', ');
554
- // A narrower grant replaces nothing that works. The link can be reused
555
- // for an hour and the Google URL's scope is not signed, so a narrower
556
- // grant is not necessarily the account holder's choice.
525
+ // A narrower grant replaces nothing that works: the link is reusable for
526
+ // an hour and the scope isn't signed, so it may not be the holder's choice.
557
527
  if (missing.length > 0 && deps.hasToken?.(st.alias)) {
558
528
  log(`alias_reauth for "${logSafe(st.alias, 64)}" granted ${missing.length} fewer scope(s); stored token kept`);
559
529
  res.writeHead(400, { 'Content-Type': 'text/html' });
@@ -570,9 +540,8 @@ export function buildAuthServer(config, deps = {}) {
570
540
  res.end(`<!doctype html><meta charset=utf-8><p>Re-authenticated "${escapeHtml(st.alias)}". You can close this window.</p>${gap}`);
571
541
  return true;
572
542
  }
573
- // owner_gate: resolve the verified email to its subject (default = the
574
- // owner allowlist -> 'owner'), discard Google tokens. The resolved sub is
575
- // signed into the authz code and flows into every token minted from it.
543
+ // owner_gate: resolve the verified email to its subject (default: owner
544
+ // allowlist -> 'owner'), discard Google tokens; the sub signs into the authz code.
576
545
  const email = (exchanged.email ?? '').toLowerCase();
577
546
  const iss = encodeURIComponent(base);
578
547
  const resolved = email ? resolveSubject(email, { sub: exchanged.sub, hd: exchanged.hd }) : null;
@@ -590,7 +559,6 @@ export function buildAuthServer(config, deps = {}) {
590
559
  const s = st.client_state ? `&state=${encodeURIComponent(st.client_state)}` : '';
591
560
  return redirect(res, `${st.redirect_uri}${sep}code=${encodeURIComponent(authzCode)}${s}&iss=${iss}`);
592
561
  };
593
- // POST /token
594
562
  const token = async (req, res) => {
595
563
  let form;
596
564
  try {
@@ -639,7 +607,7 @@ export function buildAuthServer(config, deps = {}) {
639
607
  return json(res, 400, { error: 'invalid_grant', message: 'the subject is no longer provisioned' });
640
608
  }
641
609
  }
642
- const refreshToken = refresh.issue(now(), code.sub);
610
+ const refreshToken = refresh.issue(now(), code.sub, fingerprintOf(req, form.client_id ?? ''));
643
611
  log('token issued grant=authorization_code');
644
612
  return json(res, 200, { access_token: access, token_type: 'Bearer', expires_in: accessTtl, refresh_token: refreshToken, scope: 'mcp:use' });
645
613
  }
@@ -661,7 +629,7 @@ export function buildAuthServer(config, deps = {}) {
661
629
  : undefined;
662
630
  let next;
663
631
  try {
664
- next = refresh.rotate(form.refresh_token ?? '', now(), accept);
632
+ next = refresh.rotate(form.refresh_token ?? '', now(), accept, fingerprintOf(req, form.client_id ?? ''));
665
633
  }
666
634
  catch (e) {
667
635
  if (!(e instanceof SubjectCheckUnavailable))
@@ -677,8 +645,7 @@ export function buildAuthServer(config, deps = {}) {
677
645
  }
678
646
  return json(res, 400, { error: 'unsupported_grant_type', message: 'authorization_code or refresh_token only' });
679
647
  };
680
- // POST /register (minimal DCR, D2). Parse the raw JSON body directly (the
681
- // redirect_uris array must survive intact).
648
+ // Parse the raw JSON body directly; the redirect_uris array must survive intact.
682
649
  const register = async (req, res) => {
683
650
  let parsed;
684
651
  try {
@@ -1,12 +1,8 @@
1
1
  import { OAuth2Client } from 'googleapis-common';
2
2
  import http from 'node:http';
3
3
  import { URL } from 'node:url';
4
- // Shared loopback OAuth consent (leg C of cc-auth), used by the account wizard
5
- // (B7) and the `auth --account` CLI. Live-server-safe: typed errors instead of
6
- // process.exit, and a timeout so a never-completed consent can't wedge a tool
7
- // call forever. The listener binds an EPHEMERAL loopback port (RFC 8252 §7.3;
8
- // Google Desktop clients accept any http://localhost:<port> redirect), so a
9
- // second local process on a fixed port can never break auth.
4
+ // Shared loopback OAuth consent, used by the account wizard and `auth
5
+ // --account`; a timeout keeps a never-completed consent from wedging a tool call forever.
10
6
  /** Google authorize-URL options for the owner's HTTP authorization server.
11
7
  * alias_reauth asks for the alias's scopes plus openid/email, which /callback
12
8
  * needs to bind the returned identity to the alias. It carries no login_hint:
@@ -44,10 +40,8 @@ export class ConsentDeniedError extends Error {
44
40
  super(`E_CONSENT_DENIED: ${reason}`);
45
41
  }
46
42
  }
47
- // Surfaced after every successful consent: the expiry is invisible until the
48
- // token dies a week later as reauth_required, so the moment of success is the
49
- // one place the warning is guaranteed to be seen. Full walkthrough in
50
- // docs/google-cloud-setup.md.
43
+ // Surfaced after every successful consent: the moment of success is the one
44
+ // place this warning is guaranteed to be seen, before the token dies a week later as reauth_required.
51
45
  export const TESTING_MODE_WARNING = 'Heads-up: while your OAuth client\'s Publishing status is "Testing", Google expires refresh tokens after 7 days (weekly re-auth for every account). ' +
52
46
  'When your setup works, set it to "In production" at https://console.cloud.google.com/auth/audience. ' +
53
47
  'No verification review is needed for personal use; see docs/google-cloud-setup.md.';
@@ -1,8 +1,5 @@
1
- // Opt-in outbound recipient allowlist for unattended deployments: a
2
- // prompt-injection blast-radius control (a hijacked agent cannot mail, invite
3
- // or share outside the operator's list), a safety feature first and an
4
- // enterprise checkbox second. FREE-core forever (ee-definition-v0 handoff).
5
- // Off by default: an unset/empty GOOGLE_OUTBOUND_ALLOWLIST gates nothing.
1
+ // Opt-in outbound recipient allowlist: a prompt-injection blast-radius
2
+ // control (a hijacked agent cannot mail/invite/share outside the operator's list). Off by default.
6
3
  import { hints } from './hint-provider.js';
7
4
  /** Parse GOOGLE_OUTBOUND_ALLOWLIST: comma-separated addresses and @domain
8
5
  * suffixes ("a@b.com, @company.com"). null = feature off (nothing gated). */
@@ -59,10 +56,8 @@ export function checkOutbound(kind, emails, account, env = process.env) {
59
56
  const blocked = outboundViolations(emails, env);
60
57
  return blocked.length > 0 ? outboundDeniedEnvelope(kind, blocked, account, env) : null;
61
58
  }
62
- // Escape-hatch / generated-tool enforcement. Structured bodies are inspected
63
- // for the known recipient fields; RAW compose methods cannot be inspected
64
- // (base64 RFC 822), so with the allowlist active they are refused outright in
65
- // favor of the curated tools that enforce it.
59
+ // RAW compose methods can't be inspected (base64 RFC 822), so with the
60
+ // allowlist active they're refused outright in favor of the curated tools that enforce it.
66
61
  const RAW_SEND_METHODS = new Set(['gmail.users.messages.send', 'gmail.users.drafts.send', 'gmail.users.drafts.create', 'gmail.users.messages.insert', 'gmail.users.messages.import']);
67
62
  export function collectBodyRecipients(body) {
68
63
  const out = [];
@@ -1,8 +1,5 @@
1
- // B13 in-call re-auth (BV-1): a dead/missing per-account Google token is a
2
- // leg-C failure. Over stdio the fix is the `auth --account` CLI; over HTTP the
3
- // user cannot run a CLI, so the hint becomes a clickable, server-signed link
4
- // into the AS's clientless alias_reauth flow (AuthServer.reauthLink). The HTTP
5
- // bootstrap installs the linker when the AS starts; stdio never does.
1
+ // Over stdio the fix is the `auth --account` CLI; over HTTP it's a clickable,
2
+ // server-signed link instead, installed by the AS bootstrap. See docs/internals.md.
6
3
  import { hints } from './hint-provider.js';
7
4
  let httpReauthLink = null;
8
5
  export function setHttpReauthLink(linker) {
@@ -1,4 +1,4 @@
1
- /** D11 (refuse-only for v1): export/import operate on the FLAT single-owner
1
+ /** Refuse-only for v1: export/import operate on the FLAT single-owner
2
2
  * store. A tenant-namespaced layout means the bundle would either miss every
3
3
  * tenant's tokens or exfiltrate all of them in one file — refuse instead.
4
4
  * Returns the offending dir, or null when the store is flat. */
@@ -1,9 +1,5 @@
1
- // B19: encrypted registry export / import (account-registry.md). Moves a whole
2
- // setup to another machine. The bundle is encrypted under a user PASSPHRASE
3
- // (portable across machines with different MASTER_KEYs) via the token-store AES
4
- // primitives; the bundled <alias>.enc token files stay encrypted under the
5
- // SOURCE MASTER_KEY (double-locked), so the target needs the same MASTER_KEY to
6
- // use them. Secrets (MASTER_KEY / client secret) are never in the bundle.
1
+ // Encrypted registry export/import: the bundle is passphrase-encrypted, but
2
+ // the bundled <alias>.enc files stay double-locked under the SOURCE MASTER_KEY.
7
3
  import { existsSync, readFileSync, readdirSync } from 'node:fs';
8
4
  import * as readline from 'node:readline';
9
5
  import path from 'node:path';
@@ -11,7 +7,7 @@ import { createCipheriv, createDecipheriv, randomBytes, scryptSync } from 'node:
11
7
  import { atomicWriteFileSync, atomicWriteWithLock } from './fs-atomic.js';
12
8
  import { ALIAS_RE, configFilePath, CONFIG_VERSION, tenantsDir } from './config-file.js';
13
9
  import { getTokenDir } from './accounts.js';
14
- /** D11 (refuse-only for v1): export/import operate on the FLAT single-owner
10
+ /** Refuse-only for v1: export/import operate on the FLAT single-owner
15
11
  * store. A tenant-namespaced layout means the bundle would either miss every
16
12
  * tenant's tokens or exfiltrate all of them in one file — refuse instead.
17
13
  * Returns the offending dir, or null when the store is flat. */
@@ -61,12 +57,8 @@ export function buildTransferBundle(exportedAt, deps = {}) {
61
57
  }
62
58
  return { manifest: { v: 1, exportedAt, aliases: [...aliasSet].sort() }, config, tokens };
63
59
  }
64
- // Bundle envelope v2: a REAL passphrase KDF. The v1 envelope reused the
65
- // token store's deriveKey, whose passphrase branch is one unsalted sha256 —
66
- // an exported bundle could be brute-forced offline (CodeQL
67
- // js/insufficient-password-hash). scrypt with a per-bundle random salt fixes
68
- // that; v1 bundles (a prerelease-only format, never produced by any stable
69
- // release) are refused with a re-export hint rather than kept decryptable.
60
+ // v2: a REAL passphrase KDF (scrypt, per-bundle salt). v1 reused the token
61
+ // store's unsalted-sha256 passphrase branch (CodeQL js/insufficient-password-hash) and is refused outright.
70
62
  const BUNDLE_VERSION = 2;
71
63
  const SCRYPT_PARAMS = { N: 1 << 15, r: 8, p: 1, maxmem: 64 * 1024 * 1024 };
72
64
  function bundleKey(passphrase, salt) {
@@ -38,6 +38,8 @@ export interface CatalogOperation {
38
38
  * real scope error rather than a bare "not found". */
39
39
  unreachable?: true;
40
40
  }
41
+ /** The leading sentence of a (possibly multi-sentence) tool description. */
42
+ export declare function firstSentence(text: string): string;
41
43
  /** The service a tool name belongs to: its prefix, unless overridden. */
42
44
  export declare function serviceOf(name: string): string;
43
45
  export declare function inferCud(name: string): Cud;
@@ -51,8 +53,6 @@ export declare class ToolRegistry {
51
53
  private readonly revealed;
52
54
  private readonly jsonSchemaCache;
53
55
  private readonly argShapeCache;
54
- /** Memoized isUngrantable verdict per tool: the answer depends on the frozen
55
- * bundle catalog only, so it never changes within a process. */
56
56
  private readonly ungrantable;
57
57
  private readonly compactOutput;
58
58
  private registeringMeta;
@@ -106,7 +106,7 @@ export declare class ToolRegistry {
106
106
  /** discover_all: advertise the full curated set at once. Idempotent. */
107
107
  expand(): boolean;
108
108
  /** discover_reset: back to the lean meta-only surface. Clears reveals too.
109
- * BV-8: if a client mishandles a SHRINKING tools/list, this degrades to a
109
+ * If a client mishandles a SHRINKING tools/list, this degrades to a
110
110
  * no-op for that session — tools stay callable regardless (graceful
111
111
  * dispatch), zero correctness impact. */
112
112
  collapse(): boolean;
@@ -128,11 +128,5 @@ export declare class ToolRegistry {
128
128
  };
129
129
  installListHandler(): void;
130
130
  private toToolJson;
131
- /** Advertise the CURRENT alias enum on every tools/list: account validation
132
- * is (or is becoming) live, so a cached boot-time enum would go stale the
133
- * moment account_add lands mid-session. The structural schema stays cached;
134
- * only the account property's values are refreshed per call. Skipped for
135
- * the subject-taking account tools (their `account` is the OPERAND, e.g. a
136
- * brand-new alias name, not an identity to enumerate). */
137
131
  private withLiveAccountEnum;
138
132
  }