@lanes-sh/link 0.2.2 → 0.3.1

package/src/profile/targets.ts

@@ -6,147 +6,160 @@ import type { Config } from './schema.ts';
  *
  * A target names an adapter set — where credentials are kept and where bytes
  * go — and choosing one is a different subject from finding the workspace and
- * the profile, which is why it is a different file. `workspace.ts` reached the
- * size budget holding both, and the budget's job is to say which of the two
- * things a file is doing should leave.
+ * the profile, which is why it is a different file.
  *
- * The order is `--target`, then `LANES_LINK_TARGET`, then
- * `instance.default_target`. `deploy` resolves it differently and deliberately;
- * see `resolveDeployTarget`.
+ * **`--target`, or the command does not run** (ADR-037). There is no fallback:
+ * not `LANES_LINK_TARGET`, not `instance.default_target`. Both are still
+ * parsed, so no existing config file has to change, and neither is read.
+ *
+ * The chain this replaces resolved `--target`, then the variable, then the key,
+ * and printed which of the three it landed on. What that bought was one flag
+ * saved per command. What it cost was that an *ignored* flag still produced a
+ * working command — `profile add --target cloud` dropped the flag on the floor
+ * and the next command carried on from a different source, so the mistake
+ * surfaced one command later with nothing connecting it to its cause. A
+ * resolver with nowhere to fall back to cannot fail that way.
  */
 
-/** The variable that names a target for every command in a shell. */
-export const TARGET_ENV = 'LANES_LINK_TARGET';
-
 /**
- * The target somebody asked for, before the config gets a say.
- *
- * Split out because two callers need this precedence and must not disagree
- * about it: `resolveSelection` records a provisional answer for `announce`
- * before any config is loaded, and `resolveTarget` settles it afterwards. While
- * the flag was the only source, both could spell it `targetFlag ?? …` and stay
- * accidentally correct. With a second source, one of them learning about it and
- * the other not is a line reading `config-default` beside a target the
- * environment chose — which is the one line that exists to prevent exactly that.
+ * The target this command named, checked against what the profile declares.
  *
- * Returns no target rather than a default: what an unanswered question falls
- * back to is `instance.default_target`, and that is the config's to supply.
+ * `allowUndeclared` is for the one command whose job is to create the target it
+ * was given — `deploy`, on a first run. Every other command naming a target that
+ * does not exist has made a typo, and the list of what does exist is the useful
+ * answer.
  */
-export function askedTarget(
+export function requireTarget(
+  config: Config,
   targetFlag: string | undefined,
-  env: Record<string, string | undefined>,
-): { target: string | undefined; source: 'flag' | 'environment' | undefined } {
-  if (targetFlag) return { target: targetFlag, source: 'flag' };
+  options: { allowUndeclared?: boolean; profile?: string } = {},
+): string {
+  if (!targetFlag) throw noTargetNamed(config, options.profile);
 
-  const fromEnv = env[TARGET_ENV];
-  if (fromEnv) return { target: fromEnv, source: 'environment' };
+  if (options.allowUndeclared !== true && !(targetFlag in config.targets)) {
+    throw undeclaredTarget(targetFlag, config, options.profile);
+  }
 
-  return { target: undefined, source: undefined };
+  return targetFlag;
 }
 
 /**
- * The refusal for a target that is not in the file, in one spelling.
+ * The refusal for a command that named no target.
  *
- * It was two — here and in the CLI's `openSecretStoreFor` — which is one more
- * than a sentence naming the available targets survives: the copies drift the
- * moment either learns something the other does not. This one knows about
- * `LANES_LINK_TARGET`, and that is precisely the knowledge a copy would lack —
- * an exported typo otherwise fails every command in the shell with a message
- * that reads as a problem with the config file.
+ * It lists the targets with their adapters, because "which one" is the question
+ * being asked and the adapter set is what distinguishes them. It also reports
+ * the two things that used to answer this and no longer do — an exported
+ * variable and the key still sitting in the file — since an operator looking at
+ * either has every reason to believe it is still working.
  */
-export function undeclaredTarget(
-  target: string,
+export function noTargetNamed(
   config: Config,
-  source?: 'flag' | 'environment' | 'config-default',
+  profile?: string,
+  env: Record<string, string | undefined> = process.env as Record<string, string | undefined>,
 ): ConfigError {
-  const have = Object.keys(config.targets).join(', ') || 'none';
+  const names = Object.keys(config.targets);
+  const whose = profile ? ` by profile "${profile}"` : '';
+
+  const rows = names
+    .map((name) => {
+      const declared = config.targets[name]!;
+      const deployed = declared.deploy ? '  deployed' : '';
+      return `    ${name}    ${declared.credentials.adapter}  ${declared.storage.adapter}${deployed}`;
+    })
+    .join('\n');
+
+  const stale = env[LEGACY_TARGET_ENV];
+  const inert = config.instance.default_target;
+
   return new ConfigError(
-    `Target "${target}" is not declared in this profile (have: ${have})` +
-      (source === 'environment'
-        ? `\n${TARGET_ENV}=${target} is set in this shell — unset it, or pass --target.`
+    '--target is required. This command opens a target\'s stores, and nothing\n' +
+      'else selects one.\n\n' +
+      `  Targets declared${whose}\n${rows}\n` +
+      `\n  e.g. lanes link status --profile ${profile ?? '<name>'} --target ${names[0] ?? '<target>'}` +
+      (stale
+        ? `\n\n  ${LEGACY_TARGET_ENV}=${stale} is set in this shell and is no longer read.\n` +
+          '  Unset it, or pass --target.'
+        : '') +
+      (inert
+        ? `\n\n  instance.default_target: ${inert} is still in this profile. It is no longer\n` +
+          '  read either, and is safe to delete.'
         : ''),
   );
 }
 
 /**
- * Fill in the target once the profile's config has been loaded.
+ * The variable that used to name a target, kept only to say it is ignored.
  *
- * Order: `--target`, then `LANES_LINK_TARGET`, then `instance.default_target`.
- * The middle one is the same bargain `LANES_LINK_PROFILE` already offers — a
- * shell's worth of commands without retyping a flag, somewhere `env` shows it.
+ * Not read by anything that resolves. It exists so a refusal can name the thing
+ * an operator is looking at and reasonably believes is still working — which is
+ * the whole difference between "this stopped working" and "this stopped working
+ * and here is why".
+ */
+export const LEGACY_TARGET_ENV = 'LANES_LINK_TARGET';
+
+/**
+ * The refusal for a target that is not in the file, in one spelling.
  *
- * `allowUndeclared` is for the one command whose job is to create the target it
- * was given — `deploy`, on a first run. Every other command naming a target that
- * does not exist has made a typo, and the list of what does exist is the useful
- * answer; refusing there is what stops `--target clod` opening the default one.
+ * It was two — here and in the CLI's `openSecretStoreFor` — which is one more
+ * than a sentence naming the available targets survives: the copies drift the
+ * moment either learns something the other does not.
  */
-export function resolveTarget(
-  config: Config,
-  targetFlag?: string,
-  options: {
-    allowUndeclared?: boolean;
-    env?: Record<string, string | undefined>;
-  } = {},
-): { target: string; source: 'flag' | 'environment' | 'config-default' } {
-  const env = options.env ?? (process.env as Record<string, string | undefined>);
-  const asked = askedTarget(targetFlag, env);
-
-  const target = asked.target ?? config.instance.default_target;
-  const source = asked.source ?? 'config-default';
-
-  if (options.allowUndeclared !== true && !(target in config.targets)) {
-    throw undeclaredTarget(target, config, source);
-  }
-  return { target, source };
+export function undeclaredTarget(target: string, config: Config, profile?: string): ConfigError {
+  const have = Object.keys(config.targets).join(', ') || 'none';
+  const whose = profile ? `profile "${profile}"` : 'this profile';
+
+  return new ConfigError(`Target "${target}" is not declared by ${whose} (have: ${have})`);
 }
 
 /**
- * The target a deploy means, when nobody said.
- *
- * `--target cloud` was required on every deploy, and the reason was an accident:
- * an absent flag falls back to `instance.default_target`, which is `local` —
- * a target that by definition is not deployed anywhere. So the one command whose
- * subject is never ambiguous was the one command that made you say it, and the
- * default it would otherwise have taken was not merely unhelpful but wrong.
- *
- * The rule is what someone would say out loud: deploy the target that has a
- * deployment. One is the answer; none means the first run, which conventionally
- * creates `cloud` and is what every example in the docs names; several is a
- * genuine question, and asking beats rolling a revision to whichever came first
- * in a YAML mapping.
+ * The refusal for a target-scoped command that named no target.
  *
- * `--target` still wins, which is how you deploy the second one.
+ * The twin of `noTargetNamed`, for the commands whose subject is the target
+ * rather than one profile's view of it (ADR-043). It lists the target names the
+ * *workspace* declares and who declares each, because the question those
+ * commands are asking is "which endpoint", and a target only one profile knows
+ * about is the answer to a different question than one they all share.
  *
- * **`LANES_LINK_TARGET` is deliberately not read here.** It is the same kind of
- * answer as `instance.default_target` — a shell-wide "where do my commands
- * run" — and the paragraph above is why that kind of answer is the wrong one
- * for this question. It is also the only place where being wrong creates cloud
- * resources rather than an error: `deploy` is the one caller that passes
- * `allowUndeclared`, so an exported typo would not be refused, it would be
- * surveyed, written into the profile, and rolled out as a new service. An
- * environment variable must not be able to name a Cloud Run service into
- * existence. Say `--target`; `deploy` is rare enough to afford it.
+ * Naming the profiles is not decoration. A target declared by one profile and
+ * not its sibling is precisely the state that reads as a deployment having
+ * disappeared, and it is invisible from inside either profile alone.
  */
-export const CONVENTIONAL_DEPLOY_TARGET = 'cloud';
-
-export function resolveDeployTarget(
-  config: Config,
-  targetFlag?: string,
-): { target: string; source: 'flag' | 'deployable' } {
-  if (targetFlag) return { target: targetFlag, source: 'flag' };
-
-  // `deploy` alone: the legacy `cloudrun:` spelling is normalised into it by the
-  // loader, so exactly one shape reaches here.
-  const deployable = Object.entries(config.targets)
-    .filter(([, declared]) => declared.deploy !== undefined)
-    .map(([name]) => name);
-
-  if (deployable.length > 1) {
-    throw new ConfigError(
-      `This profile declares ${deployable.length} deployable targets (${deployable.join(', ')}). ` +
-        'Name the one you mean with --target.',
+export function noTargetInWorkspace(
+  declared: ReadonlyMap<string, readonly string[]>,
+  workspaceRoot: string,
+  env: Record<string, string | undefined> = process.env as Record<string, string | undefined>,
+): ConfigError {
+  if (declared.size === 0) {
+    return new ConfigError(
+      `--target is required, and no profile in ${workspaceRoot} declares one.\n` +
+        '  Create a profile with: lanes link profile add <name> --target local',
     );
   }
 
-  return { target: deployable[0] ?? CONVENTIONAL_DEPLOY_TARGET, source: 'deployable' };
+  const total = new Set(
+    [...declared.values()].flatMap((profiles) => profiles as readonly string[]),
+  ).size;
+
+  const rows = [...declared.entries()]
+    .map(([name, profiles]) => {
+      // "every profile" rather than the list once it is all of them: the list is
+      // there to show a gap, and a complete one shows none.
+      const whose = profiles.length === total ? 'every profile' : profiles.join(', ');
+      return `    ${name}    ${whose}`;
+    })
+    .join('\n');
+
+  const first = [...declared.keys()][0]!;
+  const stale = env[LEGACY_TARGET_ENV];
+
+  return new ConfigError(
+    '--target is required. This command acts on a target, and every profile\n' +
+      'that declares it.\n\n' +
+      `  Targets in ${workspaceRoot}\n${rows}\n` +
+      `\n  e.g. lanes link status --target ${first}` +
+      (stale
+        ? `\n\n  ${LEGACY_TARGET_ENV}=${stale} is set in this shell and is no longer read.\n` +
+          '  Unset it, or pass --target.'
+        : ''),
+  );
 }

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.'
+        : ''),
+  );
 }
 
 /**
@@ -252,11 +249,74 @@ export function workspacePath(workspaceRoot: string, path: string): string {
 }
 
 /**
- * The line every command prints before acting, read-only commands included.
+ * One profile, loaded, for the commands whose subject is the whole workspace.
+ *
+ * `profilePath` rather than a bare name because a caller reporting on several
+ * profiles at once has nowhere to recompute it from without knowing whether the
+ * root is a bucket.
+ */
+export interface LoadedProfile {
+  readonly profile: string;
+  readonly profilePath: string;
+  readonly config: Config;
+}
+
+/**
+ * Every profile in the workspace, and the ones that would not open.
+ *
+ * **Skipping rather than failing** is the same rule `openReconciled` follows for
+ * a deployed endpoint: a workspace holding one broken profile still has a true
+ * answer to give about the others, and a listing that dies on the first bad file
+ * is one that stops working exactly when it is needed. What it must not do is
+ * skip *silently* — `unreadable` is the half a caller has to print, and the
+ * reason it carries the message rather than the error is that a caller rendering
+ * a table has no use for a stack.
+ */
+export interface WorkspaceProfiles {
+  readonly workspaceRoot: string;
+  readonly loaded: readonly LoadedProfile[];
+  readonly unreadable: readonly { readonly profile: string; readonly reason: string }[];
+}
+
+export async function loadWorkspaceProfiles(workspaceRoot: string): Promise<WorkspaceProfiles> {
+  const loaded: LoadedProfile[] = [];
+  const unreadable: { profile: string; reason: string }[] = [];
+
+  for (const profile of await listProfiles(workspaceRoot)) {
+    try {
+      const { config } = await loadProfileConfig(workspaceRoot, profile);
+      loaded.push({ profile, profilePath: profilePath(workspaceRoot, profile), config });
+    } catch (error) {
+      // First line only: a `ConfigError` from the loader carries every schema
+      // issue on its own line, and a row in a table has room for none of them.
+      const message = error instanceof Error ? error.message : String(error);
+      unreadable.push({ profile, reason: message.split('\n')[0] ?? 'could not be read' });
+    }
+  }
+
+  return { workspaceRoot, loaded, unreadable };
+}
+
+/**
+ * Which profiles declare each target name, across the whole workspace.
  *
- * This is the primary guard against operating on the wrong instance, and it
- * costs one line.
+ * A target is declared per profile and the endpoint serves every profile in the
+ * workspace (ADR-009), so "who has `cloud`" is a question with a list for an
+ * answer rather than a yes or no. The disagreement — one profile declaring it
+ * and its sibling not — is the state that reads as a target having vanished.
  */
-export function describeSelection(resolution: Resolution): string {
-  return `profile: ${resolution.profile} (${resolution.profileSource})   target: ${resolution.target} (${resolution.targetSource})`;
+export function targetsByName(
+  workspace: WorkspaceProfiles,
+): ReadonlyMap<string, readonly string[]> {
+  const byName = new Map<string, string[]>();
+
+  for (const { profile, config } of workspace.loaded) {
+    for (const target of Object.keys(config.targets)) {
+      const profiles = byName.get(target);
+      if (profiles) profiles.push(profile);
+      else byName.set(target, [profile]);
+    }
+  }
+
+  return byName;
 }

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.