@lanes-sh/link 0.2.2 → 0.3.0

package/src/profile/workspace.ts

@@ -6,7 +6,6 @@ import { homedir } from 'node:os';
 import { parse as parseYaml } from 'yaml';
 import { ConfigError } from './load.ts';
 import { workspaceSchema, type Config, type WorkspaceConfig } from './schema.ts';
-import { askedTarget } from './targets.ts';
 
 /**
  * Workspace and profile resolution.
@@ -19,50 +18,52 @@ import { askedTarget } from './targets.ts';
  *     work.yaml
  *   data/               local state per profile, gitignored
  *
- * There is deliberately no sticky `lanes link use` that persists a *hidden*
- * current selection. Persisted context state is the standard way operators run
- * destructive commands against the wrong target, and the version of it that
- * bites is the dotfile nothing prints.
+ * **A command says which profile it means, or it does not run** (ADR-037).
+ * `--profile` is the only thing that selects one. `LANES_LINK_PROFILE` and
+ * `default_profile` are parsed and ignored.
  *
- * So both ways of not retyping a flag are visible ones.
- * `export LANES_LINK_PROFILE=work` and `export LANES_LINK_TARGET=cloud` live in
- * the shell, where `env` shows them; `default_profile` and
- * `instance.default_target` live in files the operator reads and `check`
- * validates, written by `lanes link profile default` and `lanes link target
- * use`. Every command prints which of the four it landed on and where that came
- * from — see `announce`.
+ * The argument this replaces was that persisted selection is how operators act
+ * on the wrong thing, and that a *visible* fallback — an exported variable, a
+ * key in a file the operator reads, and a line printed before every command —
+ * was therefore safe. The first half stands and is why this rule exists at all.
+ * What did not survive is the conclusion: the printed line is a dim grey one,
+ * and a fallback made an ignored flag survivable, so `profile add --target
+ * cloud` dropping its flag surfaced on the *next* command, from a different
+ * source, detached from its cause. A resolver with nothing to fall back to
+ * cannot do that.
+ *
+ * The workspace root is deliberately not part of this and keeps its chain —
+ * `LANES_LINK_HOME`, then an ancestor holding `lanes-link.yaml`, then
+ * `~/.lanes-link`. Getting it wrong yields "no profiles here" rather than an
+ * action against the wrong account, it is the only channel a container has for
+ * its bucket (ADR-023), and the ancestor walk is what makes a per-repository
+ * workspace work at all.
  */
 
 export const WORKSPACE_FILE = 'lanes-link.yaml';
 
-export interface Resolution {
+/** A profile, found. Everything a command needs before it has read the config. */
+export interface ProfileSelection {
   readonly workspaceRoot: string;
   readonly profile: string;
   readonly profilePath: string;
+}
+
+/**
+ * A profile and the target whose stores a command will open.
+ *
+ * There is no `profileSource`/`targetSource` any more, and nothing should
+ * reintroduce them: with one way to select each, a source field has one
+ * inhabitant, and `announce` would print `(flag)` twice on every line of every
+ * command forever. `target.ts` already makes that argument about a line printed
+ * unconditionally — it stops being read.
+ */
+export interface Resolution extends ProfileSelection {
   readonly target: string;
-  /** Where the value came from, so every command can print how it got here. */
-  readonly profileSource: 'flag' | 'environment' | 'workspace-default';
-  /**
-   * `deployable` is `deploy` choosing the only target it could have meant.
-   *
-   * It is its own source rather than reusing `config-default` because it is a
-   * different claim: the config default is what *commands* run against, and for
-   * every other command that is the local target. Printing "config-default"
-   * beside a target the config does not default to would be a lie on the one
-   * line that exists to say how the command got here.
-   *
-   * `environment` is `LANES_LINK_TARGET`, and it earns its own name for the
-   * same reason: a target chosen by a variable exported in another terminal an
-   * hour ago is the one an operator is most likely to be surprised by, and the
-   * fix — `unset` — is not the fix for a config default. `deploy` never
-   * produces it; `resolveDeployTarget` says why.
-   */
-  readonly targetSource: 'flag' | 'environment' | 'config-default' | 'deployable';
 }
 
 export interface ResolveOptions {
   readonly profileFlag?: string | undefined;
-  readonly targetFlag?: string | undefined;
   readonly cwd?: string;
   readonly env?: Record<string, string | undefined>;
 }
@@ -172,45 +173,20 @@ export async function listProfiles(workspaceRoot: string): Promise<string[]> {
 }
 
 /**
- * Resolve which profile and target a command acts on.
+ * Find the profile a command names, or refuse saying what there is.
  *
- * Order: `--profile`, then `LANES_LINK_PROFILE`, then the workspace's
- * `default_profile`, then an error that lists what is available — never a
- * silent pick, because the wrong guess here operates on the wrong accounts.
+ * `--profile` and nothing else. The refusal lists the workspace's profiles,
+ * because "which one" is the question it is asking, and it names
+ * `LANES_LINK_PROFILE` when that is set — the shell still configured for the old
+ * world is the single most confusing state to be in during the change, and it
+ * is self-limiting: the line disappears the moment the variable does.
  */
-export async function resolveSelection(options: ResolveOptions = {}): Promise<Resolution> {
+export async function resolveSelection(options: ResolveOptions = {}): Promise<ProfileSelection> {
   const env = options.env ?? (process.env as Record<string, string | undefined>);
   const workspaceRoot = resolveWorkspaceRoot(options);
+  const profile = options.profileFlag;
 
-  let profile: string | undefined;
-  let profileSource: Resolution['profileSource'] = 'workspace-default';
-
-  if (options.profileFlag) {
-    profile = options.profileFlag;
-    profileSource = 'flag';
-  } else if (env['LANES_LINK_PROFILE']) {
-    profile = env['LANES_LINK_PROFILE'];
-    profileSource = 'environment';
-  } else {
-    profile = (await readWorkspace(workspaceRoot))?.default_profile;
-    profileSource = 'workspace-default';
-  }
-
-  if (!profile) {
-    const available = await listProfiles(workspaceRoot);
-    throw new ConfigError(
-      `No profile selected in workspace ${workspaceRoot}.\n` +
-        (available.length > 0
-          ? `Available: ${available.join(', ')}\n` +
-            `Pass --profile <name>, set LANES_LINK_PROFILE, or set default_profile in ${WORKSPACE_FILE}.`
-          : `No profiles exist yet. Create one with: lanes link profile add <name> --default`),
-    );
-  }
-
-  // Provisional: the config has not been read yet, so `instance.default_target`
-  // is not available to fall back to. `resolveTarget` settles it, from the same
-  // helper, so the two cannot disagree about what beats what.
-  const asked = askedTarget(options.targetFlag, env);
+  if (!profile) throw noProfileNamed(workspaceRoot, await listProfiles(workspaceRoot), env);
 
   const path = profilePath(workspaceRoot, profile);
   if (!(await workspaceFiles(workspaceRoot).has(`profiles/${profile}.yaml`))) {
@@ -221,14 +197,35 @@ export async function resolveSelection(options: ResolveOptions = {}): Promise<Re
     );
   }
 
-  return {
-    workspaceRoot,
-    profile,
-    profilePath: path,
-    target: asked.target ?? '',
-    profileSource,
-    targetSource: asked.source ?? 'config-default',
-  };
+  return { workspaceRoot, profile, profilePath: path };
+}
+
+/** The refusal for a command that named no profile. Exported so it can be tested. */
+export function noProfileNamed(
+  workspaceRoot: string,
+  available: readonly string[],
+  env: Record<string, string | undefined> = process.env as Record<string, string | undefined>,
+): ConfigError {
+  if (available.length === 0) {
+    return new ConfigError(
+      `--profile is required, and ${workspaceRoot} holds no profiles yet.\n` +
+        '  Create one with: lanes link profile add <name> --target local',
+    );
+  }
+
+  const stale = env['LANES_LINK_PROFILE'];
+
+  return new ConfigError(
+    '--profile is required. Every command names the profile it acts on, and\n' +
+      'nothing else selects one.\n\n' +
+      `  Profiles in ${workspaceRoot}\n` +
+      available.map((name) => `    ${name}`).join('\n') +
+      `\n\n  e.g. lanes link status --profile ${available[0]} --target <target>` +
+      (stale
+        ? `\n\n  LANES_LINK_PROFILE=${stale} is set in this shell and is no longer read.\n` +
+          '  Unset it, or pass --profile.'
+        : ''),
+  );
 }
 
 /**
@@ -250,13 +247,3 @@ export function workspacePath(workspaceRoot: string, path: string): string {
   }
   return isAbsolute(path) ? path : resolve(workspaceRoot, path);
 }
-
-/**
- * The line every command prints before acting, read-only commands included.
- *
- * This is the primary guard against operating on the wrong instance, and it
- * costs one line.
- */
-export function describeSelection(resolution: Resolution): string {
-  return `profile: ${resolution.profile} (${resolution.profileSource})   target: ${resolution.target} (${resolution.targetSource})`;
-}

package/src/providers/google/calendar/index.ts

@@ -1,5 +1,6 @@
 import { defineProvider } from '#connectivity';
 import { CALENDAR_IDENTITY, GOOGLE_APP, GOOGLE_OAUTH, specPath } from '../shared/oauth.ts';
+import { googleServiceAccount } from '../shared/service-account.ts';
 import { googleSetup } from '../shared/setup.ts';
 import { CALENDAR_REDACT } from './redact.ts';
 
@@ -53,6 +54,7 @@ export const calendar = defineProvider({
     app: GOOGLE_APP,
     scopes: CALENDAR_SCOPES,
     ...GOOGLE_OAUTH,
+    assertion: googleServiceAccount('Calendar', CALENDAR_SCOPES, 'optional', ['calendar-json.googleapis.com']),
   },
   identity: CALENDAR_IDENTITY,
   setup: googleSetup('Calendar', CALENDAR_SCOPES, {

package/src/providers/google/contacts/index.ts

@@ -1,5 +1,6 @@
 import { defineProvider } from '#connectivity';
 import { GOOGLE_APP, GOOGLE_OAUTH, PEOPLE_IDENTITY, specPath } from '../shared/oauth.ts';
+import { googleServiceAccount } from '../shared/service-account.ts';
 import { googleSetup } from '../shared/setup.ts';
 import { CONTACTS_REDACT } from './redact.ts';
 
@@ -43,6 +44,7 @@ export const contacts = defineProvider({
     app: GOOGLE_APP,
     scopes: CONTACTS_SCOPES,
     ...GOOGLE_OAUTH,
+    assertion: googleServiceAccount('Contacts', CONTACTS_SCOPES, 'required', ['people.googleapis.com']),
   },
   identity: PEOPLE_IDENTITY,
   setup: googleSetup('Contacts', CONTACTS_SCOPES, { apis: ['people.googleapis.com'] }),

package/src/providers/google/docs/index.ts

@@ -1,5 +1,6 @@
 import { defineProvider } from '#connectivity';
 import { DRIVE_IDENTITY, GOOGLE_APP, GOOGLE_OAUTH, specPath } from '../shared/oauth.ts';
+import { googleServiceAccount } from '../shared/service-account.ts';
 import { googleSetup } from '../shared/setup.ts';
 
 /**
@@ -32,6 +33,7 @@ export const docs = defineProvider({
     app: GOOGLE_APP,
     scopes: DOCS_SCOPES,
     ...GOOGLE_OAUTH,
+    assertion: googleServiceAccount('Docs', DOCS_SCOPES, 'optional', ['docs.googleapis.com', 'drive.googleapis.com']),
   },
   identity: DRIVE_IDENTITY,
   setup: googleSetup('Docs', DOCS_SCOPES, {

package/src/providers/google/drive/index.ts

@@ -1,5 +1,6 @@
 import { defineProvider } from '#connectivity';
 import { DRIVE_IDENTITY, GOOGLE_APP, GOOGLE_OAUTH, specPath } from '../shared/oauth.ts';
+import { googleServiceAccount } from '../shared/service-account.ts';
 import { googleSetup } from '../shared/setup.ts';
 import { DRIVE_HINTS } from './hints.ts';
 import { DRIVE_REDACT } from './redact.ts';
@@ -26,6 +27,7 @@ export const drive = defineProvider({
     app: GOOGLE_APP,
     scopes: DRIVE_SCOPES,
     ...GOOGLE_OAUTH,
+    assertion: googleServiceAccount('Drive', DRIVE_SCOPES, 'optional', ['drive.googleapis.com']),
   },
   identity: DRIVE_IDENTITY,
   setup: googleSetup('Drive', DRIVE_SCOPES),

package/src/providers/google/gmail/index.ts

@@ -1,5 +1,6 @@
 import { defineProvider, defineProviderWithCapabilities } from '#connectivity';
 import { GMAIL_IDENTITY, GOOGLE_APP, GOOGLE_OAUTH, specPath } from '../shared/oauth.ts';
+import { googleServiceAccount } from '../shared/service-account.ts';
 import { googleSetup } from '../shared/setup.ts';
 import { GMAIL_HOST } from './api.ts';
 import { GMAIL_HINTS } from './hints.ts';
@@ -85,6 +86,7 @@ const manifest = defineProvider({
     app: GOOGLE_APP,
     scopes: GMAIL_SCOPES,
     ...GOOGLE_OAUTH,
+    assertion: googleServiceAccount('Gmail', GMAIL_SCOPES, 'required', ['gmail.googleapis.com'], 'gmail_imap'),
   },
   // The REST API rather than the MCP server: it answers with the address under
   // scopes we already hold, so labelling a connection costs no extra consent.

package/src/providers/google/gmail-imap/index.ts

@@ -0,0 +1,125 @@
+import { defineProvider } from '#connectivity';
+
+/**
+ * Gmail over IMAP, for the account that cannot use either other route.
+ *
+ * A personal Google account has exactly one way to a mailbox that does not
+ * expire, and this is it. The two alternatives both fail for a reason that is
+ * not about effort:
+ *
+ * - The REST provider (`gmail`) authorises in a browser, and an OAuth client
+ *   left in "Testing" has every refresh token it issues expired after seven
+ *   days. Publishing the client fixes that and is the better answer where it is
+ *   available — see ADR-038 and `docs/detailed/setup/google.md`.
+ * - The key route (`auth.assertion` on `gmail`) does not apply at all. A service
+ *   account has no mailbox of its own, so it can only reach one by acting as
+ *   somebody, and that grant is domain-wide delegation — made in a Workspace
+ *   admin console that a personal account does not have.
+ *
+ * An app password has neither problem. It is issued by the account holder to
+ * themselves, it does not expire, and IMAP asks no authorization server for
+ * anything. What it costs is reach and shape: this is a mailbox over IMAP and
+ * SMTP, so it is the mail capability set rather than Gmail's API — no labels
+ * vocabulary, no threads resource, no drafts. Searching, reading, flagging,
+ * moving and sending, which is most of what a mailbox is for.
+ *
+ * The mirror image of `../shared/service-account.ts`, and deliberately so: that
+ * one covers Workspace and not personal accounts, this one covers personal
+ * accounts and not Workspace. Google turned off basic authentication for
+ * Workspace in March 2025, and an administrator can disable app passwords
+ * outright, so an account under a domain should take one of the other two.
+ *
+ * A separate manifest rather than a route on `gmail` because a manifest has one
+ * connector, and IMAP is a different protocol from HTTPS — the same reason
+ * iCloud is three providers rather than one. It also makes the policy line
+ * separable: `gmail_imap.*` can be allowed without granting the REST surface,
+ * or the other way round.
+ */
+export const gmailImap = defineProvider({
+  id: 'gmail_imap',
+  name: 'Gmail (IMAP)',
+  description:
+    'Read, search, and send mail in a personal Gmail mailbox over IMAP and SMTP, with an app password that does not expire.',
+  connector: {
+    kind: 'imap',
+    host: 'imap.gmail.com',
+    port: 993,
+    smtp: {
+      host: 'smtp.gmail.com',
+      port: 587,
+      starttls: true,
+      // Gmail's limit is 25 MB for the whole encoded message rather than the
+      // 20 MB default, and the send path derives the usable weight of the files
+      // from it. Declaring the real number is what makes an oversized message
+      // refused before dialling rather than part-way through DATA.
+      max_message_bytes: 25 * 1024 * 1024,
+    },
+  },
+  // Not a choice. `defineProvider` refuses anything else on an imap connector,
+  // because every mail host that matters issues an app password and expects it
+  // over Basic — and Gmail's OAuth path belongs to the REST provider.
+  auth: { kind: 'basic' },
+  // No `app`: this is one provider rather than a family, so the credential
+  // lands at `gmail_imap/<connection>` and is shared with nothing. An app
+  // password is issued per app rather than per account, so there would be
+  // nothing to share it with even if there were siblings.
+  identity: { kind: 'connector' },
+  setup: {
+    summary:
+      'Gmail over IMAP uses an app password — a sixteen-character password you issue to yourself, ' +
+      'which is not your Google account password and does not expire. Nothing is authorised in a ' +
+      'browser and nothing has to be re-approved later. This is the personal-account route: ' +
+      'Google turned off basic authentication for Workspace accounts in March 2025, and a Workspace ' +
+      'administrator can disable app passwords for the whole domain.',
+    docs: 'docs/detailed/setup/google.md',
+    docs_url: 'https://support.google.com/accounts/answer/185833',
+    steps: [
+      'Two-Step Verification has to be on. Without it Google does not offer app passwords at all, and the page below returns "the setting you are looking for is not available for your account" rather than saying why. Turn it on at https://myaccount.google.com/signinoptions/twosv.',
+      'Open https://myaccount.google.com/apppasswords and create one. Name it "Lanes Link" — the name is the only way to revoke this one later without cutting off your other devices.',
+      'Copy the sixteen characters. Google shows them once, in four groups of four; the spaces are cosmetic and it is accepted either way.',
+      'You are asked for your full address next, which is the one you sign in with, ending @gmail.com.',
+      'IMAP is on by default. If a login is refused with a mailbox error rather than an authentication error, check Gmail → Settings → See all settings → Forwarding and POP/IMAP → IMAP access.',
+    ],
+    // What a transport cannot say for itself, because it must not know which
+    // vendor it is talking to. The first sentence is the mistake this route
+    // actually produces: an app password looks enough like a password that the
+    // account password gets pasted instead, and IMAP reports both identically.
+    troubleshooting:
+      'For Gmail this is almost always a Google account password used where an app password belongs, ' +
+      'or an account without Two-Step Verification — app passwords do not exist without it. Generate ' +
+      'one at https://myaccount.google.com/apppasswords and re-run: lanes link connect gmail_imap --replace.',
+    prompts: [
+      {
+        key: 'username',
+        label: 'Google account (the full email address)',
+        secret: false,
+        scope: 'connection' as const,
+        field: 'username' as const,
+      },
+      {
+        key: 'password',
+        label: 'App password (sixteen characters)',
+        secret: true,
+        scope: 'connection' as const,
+        field: 'password' as const,
+      },
+    ],
+  },
+  // The mail capability set, so the same reasoning as `icloud_mail` applies
+  // verbatim: opted back in one key at a time, everything unlisted withheld.
+  redact: {
+    // Never the search terms — a query is content, and "who did I email about
+    // the diagnosis" is the whole message.
+    search_messages: ['mailbox', 'limit', 'unseen', 'flagged'],
+    get_message: ['mailbox', 'uid', 'include_body'],
+    mark_messages: ['mailbox', 'add_flags', 'remove_flags'],
+    // `destination_flag` alongside `destination`: two spellings of the same
+    // fact, and keeping only one means a junk move logs with no destination.
+    move_messages: ['mailbox', 'destination', 'destination_flag'],
+    // Nothing. The recipients and the body are the message, and `attachments`
+    // may literally contain a file. What was attached is recorded by the send
+    // path itself through `audit.annotate` — filename, size, type, SHA-256 and
+    // origin. Identifiers, not content.
+    send_message: [],
+  },
+});

package/src/providers/google/index.ts

@@ -1,10 +1,11 @@
-/** Google's nine providers. Each folder holds all of its own vendor knowledge. */
+/** Google's ten providers. Each folder holds all of its own vendor knowledge. */
 export { calendar } from './calendar/index.ts';
 export { contacts } from './contacts/index.ts';
 export { docs } from './docs/index.ts';
 export { drive, DRIVE_SCOPES } from './drive/index.ts';
 export { driveMcp } from './drive-mcp/index.ts';
 export { gmail, GMAIL_SCOPES } from './gmail/index.ts';
+export { gmailImap } from './gmail-imap/index.ts';
 export { gmailMcp } from './gmail-mcp/index.ts';
 export { sheets } from './sheets/index.ts';
 export { tasks } from './tasks/index.ts';

package/src/providers/google/shared/oauth.ts

@@ -24,10 +24,18 @@ export const GOOGLE_APP = 'google';
  * and there is no way to withdraw one copy of a secret.
  *
  * What this buys the operator is the whole of `setup/google.md`: no project, no
- * console, no scope list to transcribe, and no seven-day refresh-token expiry,
- * because that expiry is a property of a project left in "Testing" and this one
- * is not. What it costs is recorded in ADR-028 and in the guarantee table in
- * `docs/detailed/security.md` — chiefly that the exchange stops being local.
+ * console, and no scope list to transcribe. What it costs is recorded in
+ * ADR-028 and in the guarantee table in `docs/detailed/security.md` — chiefly
+ * that the exchange stops being local.
+ *
+ * What it does *not* buy, and used to claim to: escape from the seven-day
+ * refresh-token expiry. That expiry is a property of the client's publishing
+ * status rather than of its verification, and a client under review has the
+ * status it has — so a connection made this way is re-authorised weekly until
+ * the review lands, exactly like one made against a client of the operator's
+ * own that was left in "Testing". The way around it is not a different client.
+ * It is `auth.assertion`: a key does not expire because nothing consented, and
+ * `./service-account.ts` is that route.
  */
 const BROKER_ORIGIN = 'https://api.lanes.sh';
 const BROKER_PATH = '/v1/auth/link/google';
@@ -62,8 +70,12 @@ export const GOOGLE_OAUTH = {
   authorize_params: { access_type: 'offline', prompt: 'select_account consent' },
   // Every REST provider here spreads this block, so one line turns brokering on
   // for all seven. `gmail_mcp` and `drive_mcp` write their auth longhand and do
-  // not spread it, which is what keeps them bring-your-own — the SDK owns their
-  // exchange and `defineProvider` refuses a broker on an mcp connector.
+  // not spread it, which is what keeps them bring-your-own.
+  //
+  // That is now a choice rather than a constraint. ADR-040 made a broker legal
+  // on an mcp connector that names its own endpoints, so these two could follow
+  // Slack — what stops them is that nobody has established which client Google
+  // would have us use for its MCP servers, not that the machinery refuses.
   broker: GOOGLE_BROKER,
 } as const;
 

package/src/providers/google/shared/service-account.ts

@@ -0,0 +1,110 @@
+import { GOOGLE_APP } from './oauth.ts';
+
+/**
+ * The other way into a Google account: a key, instead of a browser.
+ *
+ * Google issues service accounts, and a service account holds a private key
+ * that does not expire. It is the answer to the one complaint the browser flow
+ * cannot fix — that a client left in "Testing" has its refresh tokens expired
+ * after seven days, so every connection has to be re-approved weekly until
+ * verification lands. A key is not subject to that, or to any other policy the
+ * issuer applies to consent, because nobody consented.
+ *
+ * What it costs is reach, and the cost is different per product, which is why
+ * `delegation` is a parameter rather than a constant. A service account is an
+ * identity in its own right: it has a Drive, and a calendar, and no mailbox and
+ * no contacts. So Drive, Sheets, Docs and Calendar work by *sharing* something
+ * with its address, and Gmail, Contacts and Tasks work only if a Workspace
+ * administrator lets the key act as a person. A personal Google account has no
+ * administrator, so for those three there is no key route at all and the
+ * walkthrough says so rather than letting someone find out later.
+ */
+
+/** Where the key lives. One file per profile, covering every Google provider. */
+export const GOOGLE_KEY_REF = `${GOOGLE_APP}/service_account_key`;
+
+const SHARE_HINT: Record<string, string> = {
+  Drive: 'a folder (Share → paste the address → Editor)',
+  Sheets: 'a spreadsheet (Share → paste the address → Editor)',
+  Docs: 'a document (Share → paste the address → Editor)',
+  Calendar:
+    'a calendar (Settings for that calendar → "Share with specific people" → paste the address)',
+};
+
+/**
+ * Where a personal account should go instead, for the products that have
+ * somewhere.
+ *
+ * Only Gmail does. A key needs delegation for mail, contacts and task lists
+ * alike, and delegation needs an administrator — but mail is the one Google
+ * still serves over a protocol that takes a password, so `gmail_imap` is a real
+ * answer rather than a consolation. Contacts and Tasks have none, and saying so
+ * plainly beats sending somebody to look.
+ */
+export const googleServiceAccount = (
+  product: string,
+  scopes: readonly string[],
+  delegation: 'optional' | 'required',
+  apis: readonly string[],
+  instead?: string,
+) => ({
+  method: 'service_account',
+  label: 'Service account key',
+  delegation,
+  key_ref: GOOGLE_KEY_REF,
+  reach:
+    delegation === 'optional'
+      ? `a JSON key that never expires, and no browser. Reaches only what you share with the ` +
+        `key's own address, so nothing in the account moves until you share it.`
+      : `a JSON key that never expires, and no browser. ${product} has nothing that belongs to ` +
+        `a key, so this needs a Google Workspace administrator to let it act as you — a personal ` +
+        `Google account cannot do it` +
+        (instead ? `, and wants ${instead} instead.` : '.'),
+  subject_label:
+    delegation === 'optional'
+      ? 'Google account to act as, if an administrator has granted it'
+      : 'Google account to act as',
+  setup: {
+    summary:
+      delegation === 'optional'
+        ? `${product} can authenticate with a service account key instead of signing in. The key ` +
+          `does not expire, so this is connected once and stays connected. It reaches only what ` +
+          `is shared with it, which is the trade: you pick what it can see, one resource at a time.`
+        : `${product} can authenticate with a service account key instead of signing in. The key ` +
+          `does not expire — but a key has no mailbox, contacts or task lists of its own, so this ` +
+          `route works only where a Google Workspace administrator has authorised the key to act ` +
+          `as a user in their domain. On a personal Google account, use the browser instead` +
+          (instead ? `, or ${instead}, which is an app password over IMAP and does not expire either.` : '.'),
+    docs: 'docs/detailed/setup/google.md',
+    docs_url: 'https://console.cloud.google.com/iam-admin/serviceaccounts',
+    steps: [
+      'Create or pick a project at https://console.cloud.google.com',
+      `Enable the APIs:\n       gcloud services enable ${apis.join(' ')} --project=YOUR_PROJECT\n       Without gcloud: APIs & Services → Library, and search for each by name.`,
+      'IAM & Admin → Service Accounts → Create service account. Name it "Lanes Link". Grant it no project roles — the roles page governs Google Cloud resources, and nothing here is one.',
+      'Open the account → Keys → Add key → Create new key → JSON. It downloads once. You are asked for the path to that file next; its contents go to the credential store and the file itself is not read again.',
+      ...(delegation === 'required'
+        ? [
+            'THIS PRODUCT NEEDS DOMAIN-WIDE DELEGATION, which only a Google Workspace administrator can grant. Copy the service account\'s numeric "Unique ID" (the client ID, not the email) from its Details tab.',
+            `In the Workspace Admin console → Security → Access and data control → API controls → Domain-wide delegation → Add new. Paste that client ID, and paste this scope list exactly:\n       ${scopes.join(',\n       ')}\n       All of them, comma-separated, in one field. A partial list is refused the same way a missing one is, and the refusal does not say which scope was short.`,
+            'Delegation can take a few minutes to take effect. If the first connect is refused with "unauthorized_client", wait and run it again — nothing was stored.',
+          ]
+        : [
+            `Share what you want reachable with the service account's email address — it ends in .iam.gserviceaccount.com and is printed once the key is stored. For ${product} that means ${SHARE_HINT[product] ?? 'the resource itself'}.`,
+            'Nothing else in the account is reachable, including files the same person owns. That is the point of this route, and it is also the thing to remember when something is "missing" — it has not been shared yet.',
+            'A Workspace administrator can instead grant domain-wide delegation, which lets the key act as a user and reach everything they can. The connect prompt asks which account to act as; leaving it blank means the key acts as itself.',
+          ]),
+    ],
+    prompts: [
+      {
+        key: 'service_account_key',
+        label: 'Path to the downloaded JSON key (or paste its contents)',
+        // Read from a path in the ordinary case, so this is not a secret typed
+        // into a terminal — but it may be pasted, and a pasted private key must
+        // not land in scrollback.
+        secret: true,
+        scope: 'shared' as const,
+        credential_ref: GOOGLE_KEY_REF,
+      },
+    ],
+  },
+});

package/src/providers/google/shared/setup.ts

@@ -56,11 +56,14 @@ export const googleSetup = (
       }\n       Without gcloud: APIs & Services → Library, and search for each by name.`,
       'The rest is under Google Auth Platform — https://console.cloud.google.com/auth — in this order:',
       '  BRANDING — app name and a support email. Seen by nobody but you.',
-      '  AUDIENCE — User type: EXTERNAL (even with a Workspace domain: "Internal" admits only that one domain, so a mix of personal and Workspace accounts needs External). Add every account you will connect under "Test users". LEAVE the status as "Testing".',
+      '  AUDIENCE — User type: EXTERNAL (even with a Workspace domain: "Internal" admits only that one domain, so a mix of personal and Workspace accounts needs External). Add every account you will connect under "Test users".',
+      '  AUDIENCE, again — PUBLISH the app. This is the setting that decides whether your connections survive the week, and it is not the same thing as verification: a client left in "Testing" has every refresh token it issues expired after exactly seven days, and one set to "In production" does not, review pending or not.',
       `  DATA ACCESS — where scopes live now. Add:\n       ${scopes.join('\n       ')}\n       Note drive.file is filed under "sensitive" rather than "restricted", so it appears in a different section of that page.`,
       '  CLIENTS — Create OAuth client → type: DESKTOP APP. Google\'s docs say "Web application" with a redirect URI for Claude or Antigravity, because they assume the agent host runs the OAuth. Here the CLI does, on a loopback port — which is also why this stays Desktop even when the server runs on Cloud Run.',
       'Copy the client ID and secret — you are asked for them next.',
-      'Not publishing is deliberate: these are restricted scopes, and publishing them means Google verification with a CASA assessment taking months. Testing needs none. The cost is that refresh tokens expire after 7 days, so expect to re-run "lanes link connect" weekly — "lanes link doctor" says which are stale.',
+      'What publishing unverified costs, so it is a decision rather than a surprise: everyone you connect sees a "Google hasn\'t verified this app" screen and has to click through Advanced, and the project gains a cap of 100 new users granted these scopes. That cap is for the lifetime of the project and cannot be reset — which does not matter for a client only you use, and matters a great deal for one you intend to hand out.',
+      'Verification itself is the other path and a much longer one — restricted scopes mean a review with a security assessment measured in months. It is worth starting and not worth waiting on: publishing above removes the weekly re-authorisation today.',
+      'If none of that suits — an organisation that forbids publishing, or a client that must stay in Testing — connect with a service account key instead. It does not expire at all: lanes link connect ' + product.toLowerCase().split(' ')[0] + ' --auth service_account',
     ],
     prompts: [
       {

package/src/providers/google/sheets/index.ts

@@ -1,5 +1,6 @@
 import { defineProvider } from '#connectivity';
 import { DRIVE_IDENTITY, GOOGLE_APP, GOOGLE_OAUTH, specPath } from '../shared/oauth.ts';
+import { googleServiceAccount } from '../shared/service-account.ts';
 import { googleSetup } from '../shared/setup.ts';
 import { SHEETS_HINTS } from './hints.ts';
 import { SHEETS_REDACT } from './redact.ts';
@@ -60,6 +61,7 @@ export const sheets = defineProvider({
     app: GOOGLE_APP,
     scopes: SHEETS_SCOPES,
     ...GOOGLE_OAUTH,
+    assertion: googleServiceAccount('Sheets', SHEETS_SCOPES, 'optional', ['sheets.googleapis.com', 'drive.googleapis.com']),
   },
   identity: DRIVE_IDENTITY,
   setup: googleSetup('Sheets', SHEETS_SCOPES, {

package/src/providers/google/tasks/index.ts

@@ -1,5 +1,6 @@
 import { defineProvider } from '#connectivity';
 import { GOOGLE_APP, GOOGLE_OAUTH, specPath } from '../shared/oauth.ts';
+import { googleServiceAccount } from '../shared/service-account.ts';
 import { googleSetup } from '../shared/setup.ts';
 import { TASKS_REDACT } from './redact.ts';
 
@@ -47,6 +48,7 @@ export const tasks = defineProvider({
     app: GOOGLE_APP,
     scopes: TASKS_SCOPES,
     ...GOOGLE_OAUTH,
+    assertion: googleServiceAccount('Tasks', TASKS_SCOPES, 'required', ['tasks.googleapis.com']),
   },
   setup: googleSetup('Tasks', TASKS_SCOPES, { apis: ['tasks.googleapis.com'] }),
   redact: TASKS_REDACT,