@stage-labs/metro 0.1.0-beta.270 → 0.1.0-beta.272

package/runtime/node_modules/@metro-labs/daemon/src/stations/attach-gmail.ts

@@ -0,0 +1,78 @@
+import { parseMailbox, pkcePair, SignInError } from '@metro-labs/core/stations/oauth';
+import { managedRequest, managedTokens } from '@metro-labs/gmail/managed';
+import { ApiError } from '@metro-labs/http/api-error';
+import { stringOf } from '@metro-labs/http/api-http';
+import type { AttachOwner } from './attach-session.js';
+import type { AttachOutcome, DriverHooks, StartedAttach } from './attach-driver.js';
+
+interface ManagedStart {
+  host: string;
+  owner: AttachOwner;
+  mailbox: unknown;
+  sendEnabled: boolean;
+  check: () => void;
+}
+
+function authorizationOf(owner: AttachOwner): string {
+  if (!owner.userId || !owner.sessionId || !owner.organization || !owner.authorization) throw new ApiError('Sign in to Metro again before connecting Gmail.', 401);
+  return owner.authorization;
+}
+
+function signInLink(started: Record<string, unknown>): { state: string; authorizeUrl: string; expiresAt: number } {
+  const state = stringOf(started.state);
+  const authorizeUrl = stringOf(started.authorizeUrl);
+  const url = new URL(authorizeUrl);
+  const expiresAt = started.expiresAt;
+  if (!state || url.origin !== 'https://accounts.google.com' || url.pathname !== '/o/oauth2/v2/auth' || url.searchParams.get('state') !== state || url.searchParams.get('redirect_uri') !== 'https://metro.box/' || typeof expiresAt !== 'number' || !Number.isFinite(expiresAt) || expiresAt <= Date.now()) throw new SignInError('Metro returned an invalid Gmail sign-in link.');
+  return { state, authorizeUrl, expiresAt };
+}
+
+function outcomeOf(result: Record<string, unknown>, input: ManagedStart, mailbox: string | null): AttachOutcome {
+  const accountEmail = parseMailbox(result.accountEmail);
+  if (accountEmail === null || (mailbox !== null && accountEmail !== mailbox) || result.managed !== true || result.managedHost !== input.host || result.sendEnabled !== input.sendEnabled) throw new SignInError('Metro returned a Gmail connection for a different mailbox or access level.');
+  return { config: { ...managedTokens(result), accountEmail, managed: true, managedHost: input.host, managedOrganization: input.owner.organization, sendEnabled: input.sendEnabled }, identity: { email: accountEmail } };
+}
+
+export async function startManagedGmail(input: ManagedStart, hooks: DriverHooks): Promise<StartedAttach> {
+  const { host, owner, sendEnabled, check } = input;
+  const bearer = authorizationOf(owner);
+  const pair = pkcePair();
+  const mailbox = parseMailbox(input.mailbox);
+  check();
+  const started = await managedRequest('start', { host, agentId: owner.agentId, challenge: pair.challenge, ...(mailbox === null ? {} : { mailbox }), sendEnabled }, bearer);
+  check();
+  const { state, authorizeUrl, expiresAt } = signInLink(started);
+  let cancelled = false;
+  let used = false;
+  return {
+    expiresAt,
+    prompt: { step: 'browser', prompt: sendEnabled ? 'Approve sending for this mailbox on Google. Metro write permissions stay unchanged.' : 'Choose a Google account and approve read-only Gmail access. Metro cannot send mail with this connection.', authorizeUrl },
+    driver: {
+      cancel: async () => {
+        cancelled = true;
+        await managedRequest('cancel', { state, host, agentId: owner.agentId }, bearer);
+      },
+      submit: async (value, authorization) => {
+        if (cancelled || used || Date.now() >= expiresAt) throw new ApiError('This sign-in is finished or expired. Start again.', 409);
+        if (stringOf(value.state) !== state) throw new ApiError('This sign-in belongs to another attempt.', 400);
+        if (!authorization) throw new ApiError('Sign in to Metro again.', 401);
+        used = true;
+        try {
+          if (stringOf(value.error)) {
+            await managedRequest('cancel', { state, host, agentId: owner.agentId }, authorization);
+            hooks.fail('Google sign-in was declined or blocked. Nothing was connected.');
+            return;
+          }
+          const code = stringOf(value.code);
+          if (!code) throw new ApiError('Google did not return a sign-in code.', 400);
+          check();
+          const result = await managedRequest('exchange', { state, code, verifier: pair.verifier, host, agentId: owner.agentId }, authorization);
+          check();
+          if (!cancelled) hooks.done(outcomeOf(result, input, mailbox));
+        } catch {
+          hooks.fail('Metro could not finish this Gmail sign-in. Start again.');
+        }
+      },
+    },
+  };
+}

package/runtime/node_modules/@metro-labs/daemon/src/stations/attach-session.ts

@@ -18,6 +18,7 @@ export type StartAttach = (
   station: InteractiveStation,
   input: Record<string, unknown>,
   hooks: DriverHooks,
+  owner: AttachOwner,
 ) => Promise<StartedAttach>;
 
 export const ATTACH_ID_RE = /^as_[A-Za-z0-9_-]{22}$/;
@@ -30,6 +31,10 @@ const MAX_TOTAL = 40;
 
 export interface AttachOwner {
   agentId: string;
+  organization?: string;
+  userId?: string;
+  sessionId?: string;
+  authorization?: string;
 }
 
 export interface AttachView {
@@ -54,6 +59,7 @@ type CompleteAttach = (
   owner: AttachOwner,
   station: StationName,
   config: Record<string, unknown>,
+  active: () => boolean,
 ) => Promise<{ accountId: string; activated: boolean }>;
 
 type AuthorizeAttach = (owner: AttachOwner) => Promise<void>;
@@ -68,6 +74,8 @@ interface Session {
   owner: AttachOwner;
   driver: AttachDriver | null;
   view: AttachView;
+  finishing?: boolean;
+  committing?: boolean;
 }
 
 const missing = (): ApiError => new ApiError('no such attach session', 404);
@@ -114,7 +122,8 @@ export class AttachSessions {
 
   private own(owner: AttachOwner, attachId: string): Session {
     const session = this.sessions.get(attachId);
-    if (session?.owner.agentId !== owner.agentId) throw missing();
+    if (session === undefined || session.owner.agentId !== owner.agentId || session.owner.organization !== owner.organization || session.owner.userId !== owner.userId || session.owner.sessionId !== owner.sessionId) throw missing();
+    if (session.view.expiresAt <= Date.now()) throw new ApiError('this sign-in expired; start again', 410);
     return session;
   }
 
@@ -153,12 +162,21 @@ export class AttachSessions {
     outcome: AttachOutcome,
   ): Promise<void> {
     const session = this.sessions.get(attachId);
-    if (session?.view.status !== 'pending') return;
+    const active = (): boolean => session !== undefined && this.sessions.get(attachId) === session && session.view.status === 'pending' && session.view.expiresAt > Date.now();
+    if (!active() || session === undefined || session.finishing === true) return;
+    session.finishing = true;
     try {
+      await this.deps.authorize(session.owner);
+      if (!active()) return;
       const landed = await this.deps.complete(
         session.owner,
         station,
         outcome.config,
+        () => {
+          if (!active()) return false;
+          session.committing = true;
+          return true;
+        },
       );
       this.settle(session, {
         status: 'done',
@@ -229,7 +247,12 @@ export class AttachSessions {
         station,
         input,
         this.hooksFor(attachId, station),
+        owner,
       );
+      if (this.sessions.get(attachId) !== session || session.view.expiresAt <= Date.now()) {
+        await started.driver.cancel();
+        throw new ApiError('this sign-in expired or stopped; start again', 410);
+      }
       session.driver = started.driver;
       if (started.expiresAt !== undefined) session.view.expiresAt = started.expiresAt;
       this.hooksFor(attachId, station).prompt(started.prompt);
@@ -257,12 +280,15 @@ export class AttachSessions {
     const driver = session.driver;
     if (session.view.status !== 'pending' || !driver)
       throw new ApiError('this sign-in is already finished', 409);
-    await driver.submit(input);
+    await this.deps.authorize(owner);
+    this.own(owner, attachId);
+    await driver.submit(input, owner.authorization);
     return { ...session.view };
   }
 
   async cancel(owner: AttachOwner, attachId: string): Promise<void> {
     const session = this.own(owner, attachId);
+    if (session.committing === true) throw new ApiError('this sign-in has already been saved', 409);
     this.sessions.delete(attachId);
     await session.driver?.cancel().catch(() => undefined);
     log.info({ attachId }, 'attach-session: cancelled');
@@ -270,7 +296,7 @@ export class AttachSessions {
 
   async sweep(now = Date.now()): Promise<void> {
     for (const [attachId, session] of [...this.sessions]) {
-      if (session.view.expiresAt > now) continue;
+      if (session.view.expiresAt > now || (session.committing === true && session.view.status === 'pending')) continue;
       this.sessions.delete(attachId);
       const driver = session.driver;
       session.driver = null;

package/runtime/node_modules/@metro-labs/gmail/package.json

@@ -6,7 +6,9 @@
   "exports": {
     ".": "./src/station.ts",
     "./train": "./src/index.ts",
-    "./login": "./src/login.ts"
+    "./login": "./src/login.ts",
+    "./managed": "./src/managed.ts",
+    "./managed-binding": "./src/managed-binding.ts"
   },
   "scripts": {
     "build": "tsc",

package/runtime/node_modules/@metro-labs/gmail/src/accounts.ts

@@ -3,13 +3,18 @@ import { threadOfLine } from '@metro-labs/core/stations/mail';
 import { TokenKeeper, type FetchLike } from '@metro-labs/core/stations/oauth';
 import { TrainError } from '@metro-labs/core/train-error';
 import { refreshTokens } from './auth.js';
+import { renewManaged, revokeManaged } from './managed.js';
+import { checkManagedBinding, type ManagedBinding } from './managed-binding.js';
 import { loadState, saveState, type AccountState } from './state.js';
 
-export interface AccountConfig {
+export interface AccountConfig extends ManagedBinding {
   id: string;
   accountEmail: string;
-  clientId: string;
-  clientSecret: string;
+  clientId?: string;
+  clientSecret?: string;
+  refreshGrant?: string;
+  authorizationId?: string;
+  sendEnabled?: boolean;
   refreshToken: string;
   accessToken?: string;
   expiresAt?: number;
@@ -18,9 +23,15 @@ export interface AccountConfig {
 
 const filled = (v: unknown): boolean => typeof v === 'string' && v !== '';
 
+function checkClient(a: AccountConfig, die: Die): void {
+  if (a.managed === true) {
+    if (!filled(a.refreshGrant) || !filled(a.managedHost) || !filled(a.managedOrganization) || !filled(a.authorizationId) || typeof a.sendEnabled !== 'boolean') die(`account '${a.id}' has an incomplete managed sign-in`);
+  } else if (!filled(a.clientId) || !filled(a.clientSecret)) die(`account '${a.id}' has no OAuth client`);
+}
+
 function checkAccount(a: AccountConfig, die: Die): void {
   if (!filled(a.accountEmail) || !a.accountEmail.includes('@')) die(`account '${a.id}' has no mailbox address`);
-  if (!filled(a.clientId) || !filled(a.clientSecret)) die(`account '${a.id}' has no OAuth client`);
+  checkClient(a, die);
   if (!filled(a.refreshToken)) die(`account '${a.id}' has no refresh token`);
 }
 
@@ -39,15 +50,24 @@ export class Account {
   readonly email: string;
   readonly state: AccountState;
   private readonly keeper: TokenKeeper;
+  private readonly pendingTokens = new Set<Promise<string>>();
+  private closing = false;
+  private revoked = false;
 
   constructor(
     readonly cfg: AccountConfig,
     private readonly fetchImpl: FetchLike = (input, init) => fetch(input, init),
   ) {
     this.email = cfg.accountEmail.toLowerCase();
-    this.state = loadState(cfg.id, { refreshToken: cfg.refreshToken, accessToken: cfg.accessToken ?? '', expiresAt: cfg.expiresAt ?? 0 });
-    const client = { clientId: cfg.clientId, clientSecret: cfg.clientSecret };
-    this.keeper = new TokenKeeper(this.state, (refreshToken) => refreshTokens(client, refreshToken, this.fetchImpl).catch(signedOut), () => {
+    this.state = loadState(cfg.id, cfg);
+    const client = { clientId: cfg.clientId ?? '', clientSecret: cfg.clientSecret ?? '' };
+    this.keeper = new TokenKeeper(this.state, async (refreshToken) => {
+      checkManagedBinding(cfg);
+      const tokens = await (cfg.managed === true
+        ? renewManaged(refreshToken, this.state.refreshGrant ?? '', cfg.managedHost ?? '', this.fetchImpl)
+        : refreshTokens(client, refreshToken, this.fetchImpl, Date.now(), cfg.sendEnabled)).catch(signedOut);
+      return tokens;
+    }, () => {
       this.save();
     });
   }
@@ -60,12 +80,44 @@ export class Account {
     saveState(this.cfg.id, this.state);
   }
 
-  token(force = false): Promise<string> {
-    return this.keeper.token(force);
+  check(): void {
+    if (this.closing) throw new TrainError('gmail_disconnecting', 'This Gmail connection is disconnecting.', { retryable: false });
+    checkManagedBinding(this.cfg);
+  }
+
+  async token(force = false): Promise<string> {
+    this.check();
+    const pending = this.keeper.token(force);
+    this.pendingTokens.add(pending);
+    try {
+      const token = await pending;
+      this.check();
+      return token;
+    } finally {
+      this.pendingTokens.delete(pending);
+    }
+  }
+
+  async disconnect(authorizationId: unknown): Promise<void> {
+    if (this.cfg.managed !== true || !authorizationId || authorizationId !== this.cfg.authorizationId) throw new TrainError('gmail_connection_changed', 'This Gmail connection changed. Try deleting again.', { retryable: false });
+    if (this.revoked) return;
+    if (this.closing) throw new TrainError('gmail_disconnecting', 'This Gmail connection is disconnecting.', { retryable: false });
+    this.closing = true;
+    try {
+      await Promise.allSettled([...this.pendingTokens]);
+      await revokeManaged(this.state.refreshToken, this.state.refreshGrant ?? '', this.cfg.managedHost ?? '', this.fetchImpl);
+      this.revoked = true;
+    } catch (err) {
+      this.closing = false;
+      throw err;
+    }
   }
 
-  fetch(input: string, init?: RequestInit): Promise<Response> {
-    return this.fetchImpl(input, init);
+  async fetch(input: string, init?: RequestInit): Promise<Response> {
+    this.check();
+    const result = await this.fetchImpl(input, init);
+    this.check();
+    return result;
   }
 }
 

package/runtime/node_modules/@metro-labs/gmail/src/actions.ts

@@ -1,14 +1,19 @@
 import { makeStation, respond } from '@metro-labs/core/stations/station-runtime';
-import { accounts } from './accounts.js';
+import { accountOf, accounts } from './accounts.js';
 import { MAILBOX_URL } from './config.js';
 import { reply, send } from './outbound.js';
 import { read } from './query.js';
 
 function listAccounts(id: string): void {
-  const list = [...accounts.values()].map((a) => ({ id: a.id, handle: a.email, url: `${MAILBOX_URL}mail/u/${a.email}/`, email: a.email }));
+  const list = [...accounts.values()].map((a) => ({ id: a.id, handle: a.email, url: `${MAILBOX_URL}mail/u/${a.email}/`, email: a.email, managed: a.cfg.managed === true, ...(a.cfg.sendEnabled === undefined ? {} : { sendEnabled: a.cfg.sendEnabled }) }));
   respond(id, { result: { accounts: list } });
 }
 
+async function disconnect(id: string, args: Record<string, unknown>): Promise<void> {
+  await accountOf(args).disconnect(args.authorizationId);
+  respond(id, { result: { revoked: true } });
+}
+
 export const handleCall = makeStation({
-  handlers: { accounts: listAccounts, send, reply, read },
+  handlers: { accounts: listAccounts, send, reply, read, disconnect },
 });

package/runtime/node_modules/@metro-labs/gmail/src/api.ts

@@ -21,11 +21,14 @@ export async function gmail(acct: Account, path: string, init: RequestInit = {})
   if (res.status === 401) res = await call(acct, path, init, true);
   if (res.ok) return res;
   const detail = await googleMessage(res);
+  acct.check();
   throw res.status === 404 && path.startsWith(`${USER}/history`) ? new HistoryGone(detail) : refusalOf(GMAIL, res.status, detail);
 }
 
 export async function gmailJson<T>(acct: Account, path: string, init: RequestInit = {}): Promise<T> {
-  return (await (await gmail(acct, path, init)).json()) as T;
+  const body = (await (await gmail(acct, path, init)).json()) as T;
+  acct.check();
+  return body;
 }
 
 export const queryOf = (params: [string, string][]): string => new URLSearchParams(params).toString();

package/runtime/node_modules/@metro-labs/gmail/src/attachments.ts

@@ -20,7 +20,10 @@ export async function saveFile(acct: Account, messageId: string, file: MailFile,
   if (file.size !== undefined) assertAttachmentSize(file.size);
   const data = file.data ?? (file.attachmentId === null ? null : await attachmentData(acct, messageId, file.attachmentId));
   if (data === null) throw new TrainError('gmail_file_missing', `Gmail gave no content for ${file.name}`, { retryable: false });
-  return saveBufferToCache(new Uint8Array(Buffer.from(data, 'base64url')), messageId, index, { mime: file.mime, name: file.name });
+  acct.check();
+  const saved = await saveBufferToCache(new Uint8Array(Buffer.from(data, 'base64url')), messageId, index, { mime: file.mime, name: file.name });
+  acct.check();
+  return saved;
 }
 
 export async function assertSendable(files: OutgoingFile[]): Promise<void> {

package/runtime/node_modules/@metro-labs/gmail/src/auth.ts

@@ -1,5 +1,12 @@
 import { postForm, SignInError, tokensOf, type FetchLike, type OAuthBody, type Tokens } from '@metro-labs/core/stations/oauth';
-import { apiBase, authorizeBase, redirectUri, SCOPES, tokenUrl } from './config.js';
+import { apiBase, authorizeBase, redirectUri, scopesFor, tokenUrl } from './config.js';
+
+export function checkScopes(scope: unknown, sendEnabled: boolean): void {
+  const granted = typeof scope === 'string' ? scope.split(/\s+/).filter(Boolean) : [];
+  const wanted = scopesFor(sendEnabled).split(' ');
+  if (wanted.some((s) => !granted.includes(s)) || granted.some((s) => !wanted.includes(s)))
+    throw new SignInError('Google did not grant exactly the requested Gmail access. Review this app in your Google Account, then connect again.');
+}
 
 export interface GmailClient {
   clientId: string;
@@ -30,13 +37,14 @@ export function failureOf(body: OAuthBody): string {
   return detail === '' ? `Google refused the sign-in (${error === '' ? 'no reason given' : error}).` : `Google refused the sign-in: ${detail}`;
 }
 
-export function authorizeUrl(client: GmailClient, challenge: string, state: string, loginHint: string | null): string {
+export function authorizeUrl(client: GmailClient, challenge: string, state: string, loginHint: string | null, sendEnabled = false): string {
   const query = new URLSearchParams({
     ...(loginHint === null ? {} : { login_hint: loginHint }),
     client_id: client.clientId,
     redirect_uri: redirectUri(),
     response_type: 'code',
-    scope: SCOPES,
+    scope: scopesFor(sendEnabled),
+    ...(sendEnabled ? { include_granted_scopes: 'true' } : {}),
     state,
     code_challenge: challenge,
     code_challenge_method: 'S256',
@@ -49,7 +57,7 @@ export function authorizeUrl(client: GmailClient, challenge: string, state: stri
 const post = (fields: Record<string, string>, fetchImpl: FetchLike): Promise<{ status: number; body: OAuthBody }> =>
   postForm(tokenUrl(), fields, fetchImpl, 'Google');
 
-export async function redeemCode(client: GmailClient, code: string, verifier: string, fetchImpl: FetchLike, now = Date.now()): Promise<Tokens> {
+export async function redeemCode(client: GmailClient, code: string, verifier: string, fetchImpl: FetchLike, now = Date.now(), sendEnabled = false): Promise<Tokens> {
   const { status, body } = await post(
     {
       grant_type: 'authorization_code',
@@ -62,15 +70,17 @@ export async function redeemCode(client: GmailClient, code: string, verifier: st
     fetchImpl,
   );
   if (status !== 200) throw new SignInError(failureOf(body));
+  checkScopes(body.scope, sendEnabled);
   return tokensOf(body, now, 'Google');
 }
 
-export async function refreshTokens(client: GmailClient, refreshToken: string, fetchImpl: FetchLike, now = Date.now()): Promise<Tokens> {
+export async function refreshTokens(client: GmailClient, refreshToken: string, fetchImpl: FetchLike, now = Date.now(), sendEnabled?: boolean): Promise<Tokens> {
   const { status, body } = await post(
     { grant_type: 'refresh_token', refresh_token: refreshToken, client_id: client.clientId, client_secret: client.clientSecret },
     fetchImpl,
   );
   if (status !== 200) throw new SignInError(`Google refused to renew this mailbox's sign-in, so connect Gmail again. ${failureOf(body)}`);
+  if (sendEnabled !== undefined) checkScopes(body.scope, sendEnabled);
   return tokensOf(body, now, 'Google', refreshToken);
 }
 

package/runtime/node_modules/@metro-labs/gmail/src/config.ts

@@ -1,6 +1,8 @@
 import { envUrl, envValue } from '@metro-labs/core/stations/oauth';
 
-export const SCOPES = ['https://www.googleapis.com/auth/gmail.readonly', 'https://www.googleapis.com/auth/gmail.send'].join(' ');
+export const READ_SCOPE = 'https://www.googleapis.com/auth/gmail.readonly';
+export const SEND_SCOPE = 'https://www.googleapis.com/auth/gmail.send';
+export const scopesFor = (sendEnabled = false): string => [READ_SCOPE, ...(sendEnabled ? [SEND_SCOPE] : [])].join(' ');
 
 export const MAILBOX_URL = 'https://mail.google.com/';
 

package/runtime/node_modules/@metro-labs/gmail/src/inbound.ts

@@ -46,6 +46,7 @@ async function deliver(acct: Account, messageId: string): Promise<boolean> {
   }
   const files = mailFilesOf(m);
   const env = mailEnvelope('gmail', acct.id, acct.email, item, files.map(metaOf), verdict.verified);
+  acct.check();
   emitInbound(acct.id, env);
   const at = { station: 'gmail', account: acct.id, line: String(env.line), forId: String(env.id) };
   for (const [index, file] of files.entries())

package/runtime/node_modules/@metro-labs/gmail/src/login.ts

@@ -12,6 +12,7 @@ export interface GmailLoginDeps {
   clientId?: unknown;
   clientSecret?: unknown;
   mailbox?: unknown;
+  sendEnabled?: boolean;
   fetch?: FetchLike;
   now?: () => number;
 }
@@ -22,13 +23,14 @@ export class GmailBrowserLogin extends BrowserSignIn<GmailLoginResult> {
     const mailbox = parseMailbox(deps.mailbox);
     const fetchImpl: FetchLike = deps.fetch ?? ((input, init) => fetch(input, init));
     const now = deps.now ?? Date.now;
+    const sendEnabled = deps.sendEnabled === true;
     super({
-      authorize: (challenge, state) => authorizeUrl(client, challenge, state, mailbox),
+      authorize: (challenge, state) => authorizeUrl(client, challenge, state, mailbox, sendEnabled),
       redeem: async (code, verifier) => {
-        const tokens = await redeemCode(client, code, verifier, fetchImpl, now());
+        const tokens = await redeemCode(client, code, verifier, fetchImpl, now(), sendEnabled);
         const email = await verifyMailbox(tokens.accessToken, fetchImpl, mailbox);
         return {
-          config: { accountEmail: email, ...client, ...tokens, createdAt: new Date(now()).toISOString() },
+          config: { accountEmail: email, ...client, ...tokens, sendEnabled, createdAt: new Date(now()).toISOString() },
           identity: { email },
         };
       },

package/runtime/node_modules/@metro-labs/gmail/src/managed-binding.ts

@@ -0,0 +1,33 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { ensureSecureDir, writeSecure } from '@metro-labs/core/secure-fs';
+import { TrainError } from '@metro-labs/core/train-error';
+
+export interface ManagedBinding {
+  managed?: boolean;
+  managedOrganization?: string;
+  managedHost?: string;
+}
+
+const bindingDir = (): string => process.env.METRO_AGENTS_DIR ?? join(homedir(), '.metro', 'agents');
+
+export function setManagedHost(url: string | null): void {
+  const dir = bindingDir();
+  ensureSecureDir(dir);
+  writeSecure(join(dir, '.gmail-host'), url === null ? '' : new URL(url).host);
+}
+
+export function checkManagedBinding(config: ManagedBinding): void {
+  if (config.managed !== true) return;
+  let owner = '';
+  let host = '';
+  try {
+    owner = readFileSync(join(bindingDir(), '.owner'), 'utf8').trim();
+    host = readFileSync(join(bindingDir(), '.gmail-host'), 'utf8').trim();
+  } catch {
+    throw new TrainError('gmail_binding_changed', 'Reconnect managed Gmail on this box before using it.', { retryable: false });
+  }
+  if (!owner || owner !== config.managedOrganization || !host || host !== config.managedHost)
+    throw new TrainError('gmail_binding_changed', 'This box changed owner or address. Reconnect managed Gmail before using it.', { retryable: false });
+}

package/runtime/node_modules/@metro-labs/gmail/src/managed.ts

@@ -0,0 +1,45 @@
+import { SignInError, type FetchLike, type Tokens } from '@metro-labs/core/stations/oauth';
+
+const BASE = 'https://api.metro.box/api/gmail';
+const reach: FetchLike = (input, init) => fetch(input, init);
+
+export interface ManagedTokens extends Tokens {
+  refreshGrant: string;
+}
+
+export async function managedRequest(path: 'start' | 'exchange' | 'cancel' | 'refresh' | 'revoke', body: Record<string, unknown>, bearer?: string, fetchImpl = reach): Promise<Record<string, unknown>> {
+  let response: Response;
+  try {
+    response = await fetchImpl(`${BASE}/${path}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', ...(bearer === undefined ? {} : { authorization: bearer }) },
+      body: JSON.stringify(body),
+      redirect: 'error',
+      signal: AbortSignal.timeout(25_000),
+    });
+  } catch {
+    throw new SignInError('Metro could not reach managed Gmail sign-in. Try again.');
+  }
+  if (!response.ok) {
+    const retry = response.status >= 500 ? 'Try again later.' : 'Start Gmail sign-in again. Your Google Workspace administrator may need to allow the app.';
+    throw new SignInError(`Metro could not complete managed Gmail sign-in. ${retry}`);
+  }
+  const value: unknown = await response.json().catch(() => null);
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) throw new SignInError('Metro returned an invalid Gmail answer.');
+  return value as Record<string, unknown>;
+}
+
+export function managedTokens(value: Record<string, unknown>): ManagedTokens {
+  if (typeof value.accessToken !== 'string' || !value.accessToken || typeof value.refreshToken !== 'string' || !value.refreshToken || typeof value.refreshGrant !== 'string' || !value.refreshGrant || typeof value.expiresAt !== 'number' || !Number.isFinite(value.expiresAt))
+    throw new SignInError('Metro returned an incomplete Gmail sign-in.');
+  return { accessToken: value.accessToken, refreshToken: value.refreshToken, refreshGrant: value.refreshGrant, expiresAt: value.expiresAt };
+}
+
+export async function renewManaged(refreshToken: string, refreshGrant: string, host: string, fetchImpl = reach): Promise<ManagedTokens> {
+  return managedTokens(await managedRequest('refresh', { refreshToken, refreshGrant, host }, undefined, fetchImpl));
+}
+
+export async function revokeManaged(refreshToken: string, refreshGrant: string, host: string, fetchImpl = reach): Promise<void> {
+  const result = await managedRequest('revoke', { refreshToken, refreshGrant, host }, undefined, fetchImpl);
+  if (result.revoked !== true) throw new SignInError('Metro did not confirm Google revocation. Try again.');
+}

package/runtime/node_modules/@metro-labs/gmail/src/outbound.ts

@@ -74,6 +74,7 @@ async function outgoing(args: Args): Promise<Outgoing> {
   const parsed = threadOfLine('gmail', line);
   if (parsed === null) throw new TrainError('gmail_bad_line', `not a valid gmail line: ${line}`, { retryable: false });
   const acct = accountOf(args);
+  if (acct.cfg.sendEnabled === false) throw new TrainError('gmail_read_only', 'This Gmail connection is read-only. Allow sending with Google in channel settings, then choose a Metro write policy.', { retryable: false });
   const files = filesOf(args.attachments);
   const text = typeof args.text === 'string' ? args.text : '';
   if (text.trim() === '' && files.length === 0) throw new TrainError('gmail_text_required', 'give some text or a file to send', { retryable: false });

package/runtime/node_modules/@metro-labs/gmail/src/query.ts

@@ -69,6 +69,7 @@ async function searched(acct: Account, q: ReadQuery, beforeAt: string): Promise<
 async function list(id: string, acct: Account, q: ReadQuery): Promise<void> {
   const beforeAt = await receivedAt(acct, q.before);
   const found = q.threadId !== null && q.query === '' ? await inThread(acct, q, q.threadId, beforeAt) : await searched(acct, q, beforeAt);
+  acct.check();
   respond(id, {
     result: {
       account: acct.id,
@@ -85,6 +86,7 @@ async function one(id: string, acct: Account, messageId: string): Promise<void>
     const saved = await saveFile(acct, m.id, file, index);
     attachments.push({ name: file.name, mime: file.mime, kind: file.kind, size: saved.bytes, local_path: saved.path });
   }
+  acct.check();
   respond(id, { result: { account: acct.id, message: { ...mailFull('gmail', acct.id, itemOf(m)), attachments } } });
 }
 

package/runtime/node_modules/@metro-labs/gmail/src/state.ts

@@ -4,16 +4,22 @@ import { seenOf } from '@metro-labs/core/stations/mail';
 import { tokenStateOf, type Tokens } from '@metro-labs/core/stations/oauth';
 
 export interface AccountState extends Tokens {
+  refreshGrant?: string;
+  authorizationId?: string;
   historyId: string | null;
   seen: string[];
 }
 
 export const stateFiles = accountFiles('GMAIL_STATE_DIR', 'gmail-state-');
 
-export function loadState(accountId: string, seed: Partial<Tokens>): AccountState {
+export function loadState(accountId: string, seed: Partial<AccountState>): AccountState {
   const saved = readJson<Record<string, unknown>>(stateFiles.path(accountId), {});
+  const same = saved.authorizationId === seed.authorizationId;
+  const held = same ? saved : {};
   return {
-    ...tokenStateOf(saved, seed),
+    ...tokenStateOf(held, seed),
+    refreshGrant: typeof held.refreshGrant === 'string' ? held.refreshGrant : seed.refreshGrant,
+    authorizationId: seed.authorizationId,
     historyId: typeof saved.historyId === 'string' && saved.historyId !== '' ? saved.historyId : null,
     seen: seenOf(saved.seen),
   };

package/runtime/node_modules/@metro-labs/http/src/api-http.ts

@@ -8,6 +8,8 @@ export type Role = 'admin' | 'member';
 
 export interface ApiSession {
   subject: string;
+  userId?: string;
+  sessionId?: string;
   role: Role;
   operator?: true;
 }

package/runtime/runtime.json

@@ -1,3 +1,3 @@
 {
-  "version": "0.1.0-beta.270"
+  "version": "0.1.0-beta.272"
 }

package/runtime/sdk-runner/node_modules/@metro-labs/core/src/tickets.ts

@@ -2,6 +2,7 @@ import { randomBytes } from 'node:crypto';
 
 export interface TicketStore<T> {
   mint: (value: T, now?: number) => { ticket: string; expiresAt: number };
+  peek: (ticket: string, now?: number) => T | undefined;
   take: (ticket: string, now?: number) => T | undefined;
   size: (now?: number) => number;
 }
@@ -24,6 +25,12 @@ export function ticketStore<T>(ttlMs: number, max: number): TicketStore<T> {
       open.set(ticket, { value, expiresAt });
       return { ticket, expiresAt };
     },
+    peek(ticket, now = Date.now()) {
+      const entry = open.get(ticket);
+      if (entry !== undefined && entry.expiresAt > now) return entry.value;
+      open.delete(ticket);
+      return undefined;
+    },
     take(ticket, now = Date.now()) {
       const entry = open.get(ticket);
       open.delete(ticket);

package/runtime/sdk-runner/runner.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.0-beta.270",
+  "version": "0.1.0-beta.272",
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "0.3.287",
     "@modelcontextprotocol/sdk": "^1.29.0",