@lanes-sh/link 0.6.2 → 0.6.4

package/.dockerignore

@@ -0,0 +1,45 @@
+# The build context for src/deployments/gcp/Dockerfile is this directory.
+#
+# The first block is a security control, not an image-size optimisation. `data/`
+# holds the encrypted credential store *and* the key that opens it, and `*.key`
+# catches the same file wherever else it lands. A credential baked into an image
+# is pushed to a registry, cached on every builder that touched it, and readable
+# by anyone who can pull the tag — and the deployed target does not want them
+# anyway, because it reads credentials from Secret Manager.
+data/
+*.key
+*.pem
+*.enc
+*.p12
+.env
+.env.*
+
+# Not needed at runtime, and `.git` in particular carries every branch.
+.git/
+.gitignore
+.worktrees/
+node_modules/
+**/node_modules/
+coverage/
+dist/
+build/
+*.tsbuildinfo
+
+# Tests, docs, and tooling: the image runs the endpoint and nothing else.
+#
+# `instructions/` is what the CLI installs into a client — a skill and an agent
+# definition. The endpoint describes itself from code (`server/mcp/instructions.ts`)
+# precisely so a deployed revision does not need these files.
+**/*.test.ts
+**/*.test.json
+docs/
+instructions/
+**/README.md
+.lanes/
+.claude/
+.vscode/
+.idea/
+.DS_Store
+
+# The compiled binary from `bun build --compile`, if one was made locally.
+/lanes

package/README.md

@@ -69,6 +69,20 @@ Your agents can now use it. Memory, tasks, files, skills, and the vault hold you
 rather than an account, so they are already there — nothing to connect, no credentials, no browser.
 Mail and calendar are the next step. **[Full quickstart →](docs/quickstart.md)**
 
+## In the Lanes desktop app
+
+Prefer not to use a terminal? The [Lanes desktop app](https://lanes.sh/desktop) drives this CLI from
+a settings page. **Settings → Integrations → Lanes Link** installs it, holds the profile and target
+every command runs against, connects your accounts, starts and stops the endpoint, and registers it
+with Claude Code or Codex.
+
+![The Lanes Link page in the Lanes desktop app: the CLI status card and its version, the target and profile selectors, the endpoint row with its running state, and the list of connected accounts.](docs/images/lanes-link-desktop.png)
+
+It runs the commands above rather than reimplementing them, so consent and the token stay here where
+they belong, and an endpoint set up in the app is the same one you get from a shell. Available from
+Lanes v0.47.0, as a research preview.
+**[How to use it →](https://lanes.sh/docs/desktop/lanes-link)**
+
 ## What your agent gets
 
 | | | Manage it with |
@@ -166,6 +180,7 @@ than being rebuilt.
 ## Docs
 
 - **[Quickstart](docs/quickstart.md)** — from nothing to a working endpoint
+- **[In the Lanes desktop app](https://lanes.sh/docs/desktop/lanes-link)** — the page that drives it
 - **[Connect your accounts](docs/connect.md)** — every provider, and what each one needs
 - **[Add it to your agent](docs/clients.md)** — Claude Code, Codex, Claude Desktop, claude.ai, ChatGPT
 - **[Deploy to your own cloud](docs/deploy.md)** — five commands to a URL

package/bunfig.toml

@@ -0,0 +1,17 @@
+[install]
+# Supply chain: this repository holds live OAuth refresh tokens, so a
+# dependency compromise is a live threat. The common attack is to publish a
+# compromised version and yank it within hours; a release-age floor keeps a
+# version that young out of the lockfile entirely.
+#
+# 604800 seconds = 7 days.
+#
+# An urgent security fix can be pulled in ahead of the window by installing an
+# exact version explicitly, or by adding the package to minimumReleaseAgeExcludes.
+minimumReleaseAge = 604800
+minimumReleaseAgeExcludes = []
+
+# Pin exact versions rather than ranges, so the lockfile is the only thing
+# that decides what gets installed. Bun does not run dependency lifecycle
+# scripts unless a package is listed in trustedDependencies; keep that empty.
+exact = true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lanes-sh/link",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "A self-hostable MCP gateway for all your connections, memory, tasks, files, and secrets",
   "license": "Apache-2.0",
   "homepage": "https://lanes.sh/link",
@@ -42,7 +42,9 @@
     "!src/**/*.test.ts",
     "instructions",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "bunfig.toml",
+    ".dockerignore"
   ],
   "scripts": {
     "test": "bun test",

package/src/cli/commands/connect/bind-credential.ts

@@ -0,0 +1,48 @@
+import { bindConnectionCredentials, type BindOutcome } from '#deployments/bind.ts';
+import type { Runtime } from '../../runtime.ts';
+
+/**
+ * Step 7 of `connect`: bind the credential to the revision that will serve it.
+ *
+ * Split out for the reason every other step in this directory was — `index.ts`
+ * holds the order, not the substance, and the file has a size budget
+ * (`architecture.test.ts`) that exists to keep it that way.
+ *
+ * What it is for is in `deployments/bind.ts`. Two decisions belong here.
+ *
+ * **It is called ahead of `connect`'s early return, not after it.** Re-running
+ * `connect` against an existing connection is what an operator does to repair
+ * one, and that run reaches the end with no config changes to make. Binding
+ * after the return would skip the repair path, leaving the command that looks
+ * like the fix doing nothing about the actual fault.
+ *
+ * **A failure is a note, never a throw.** The credential is in the store and the
+ * config is about to be saved by the time this runs, so failing the command
+ * would report "connect failed" about a connect that happened — and connecting
+ * an account against a deployed target from a machine that has never had
+ * `gcloud` installed has to keep working.
+ *
+ * The third decision is which connection to bind. The declared row is
+ * preferred over one assembled from the arguments, because an operator may have
+ * written a `credential_ref` into the profile by hand and that field decides
+ * where a `local` provider's credential lives — binding the derived ref instead
+ * would grant a secret nobody writes and leave the written one unbound, which is
+ * the failure `rotatableCredentialRefsFor` documents from the other direction.
+ */
+export function bindNewCredential(
+  runtime: Runtime,
+  providerId: string,
+  connectionId: string,
+  account: string,
+): Promise<BindOutcome> {
+  const declared = runtime.config.connections.find(
+    (candidate) => candidate.provider === providerId && candidate.id === connectionId,
+  );
+
+  return bindConnectionCredentials({
+    deploy: runtime.declared.deploy,
+    target: runtime.target,
+    connection: declared ?? { provider: providerId, id: connectionId, account },
+    manifest: runtime.manifestFor(providerId),
+  });
+}

package/src/cli/commands/connect/index.ts

@@ -16,6 +16,7 @@ import { chooseAuthMethod } from './method.ts';
 import { preflight } from './requirements.ts';
 import { ALREADY, NOTHING, renderOutcome, where, type ConnectOutcome } from './outcome.ts';
 import { nextAfterEdit, publishRuntimeEdit } from '#cli/publish.ts';
+import { bindNewCredential } from './bind-credential.ts';
 import { ensureStaticCredential } from './setup.ts';
 import { settleIdentity } from './settle.ts';
 import { runStrategySetup } from './strategy.ts';
@@ -356,6 +357,9 @@ export async function runConnect(
       ? ['that is your own memory, tasks, assets, skills and vault — no account, nothing stored until you use them']
       : [];
 
+    // 7. Bind the credential to the revision that serves it — `bind-credential.ts`.
+    const bound = await bindNewCredential(runtime, providerId, connectionId, account);
+    if (bound.failed) notes.push(bound.failed);
     if (changes.length === 0 && granted.length === 0) {
       return {
         ...NOTHING,
@@ -364,6 +368,7 @@ export async function runConnect(
         account,
         label,
         ...where(runtime),
+        ...(notes.length > 0 ? { notes } : {}),
         discovered: discovered.length,
         next: ALREADY,
       };

package/src/cli/commands/operate/inspect.ts

@@ -4,6 +4,7 @@ import { announce, announceProfile, emit, fail, ok, print, warn } from '../../ou
 import { staleNudge } from '../../release.ts';
 import { openRuntime, resolveProfileOnly, type GlobalFlags, type Runtime } from '../../runtime.ts';
 import type { FetchLike } from '#deployments/knowledge.ts';
+import { unboundRotatableRefs } from '#deployments/bind.ts';
 import { credentialAge, reportCapabilityDrift } from './findings.ts';
 import { migratedContract, migratedRenamedProviders } from './migrate.ts';
 
@@ -276,6 +277,37 @@ export async function doctor(flags: DoctorFlags): Promise<void> {
       });
     }
 
+    // Whether the revision can still rewrite what it serves.
+    //
+    // A *problem*, not a warning: an unbound credential is a connection that
+    // works until its access token expires and then stops, and every other
+    // report on this machine calls it healthy in the meantime — `status` and
+    // `setup_overview` read the state store, and the state store knows nothing
+    // about IAM. This is the only place that asks the thing that decides.
+    //
+    // Skipped entirely for a local target, where credentials are a file this
+    // process owns and there is no revision to grant anything to.
+    const rotation = await unboundRotatableRefs({
+      deploy: runtime.declared.deploy,
+      target: runtime.target,
+      connections: runtime.config.connections,
+      manifestFor: runtime.manifestFor,
+    });
+    if (rotation.unbound.length > 0) {
+      problems.push({
+        kind: 'unbound_credentials',
+        message:
+          `the deployed endpoint can read ${rotation.unbound.join(', ')} but not rotate ` +
+          `${rotation.unbound.length === 1 ? 'it' : 'them'} — so ${rotation.unbound.length === 1 ? 'that connection' : 'those connections'} ` +
+          'will fail about an hour after each use, when the token refresh tries to persist. ' +
+          'A connection made since the last deploy is the usual cause',
+        fix: forSelection('lanes link deploy'),
+      });
+    }
+    if (rotation.unavailable) {
+      warnings.push({ kind: 'rotation_uncheckable', message: rotation.unavailable });
+    }
+
     if (problems.length > 0) process.exitCode = 1;
 
     return emit(flags.json, { ok: problems.length === 0, checks, warnings, problems }, () => {

package/src/deployments/bind.ts

@@ -0,0 +1,214 @@
+import type { ConnectionConfig, DeployConfig } from '#profile';
+import { credentialRefFor, rotatableCredentialRefsFor } from '#registry';
+import type { SecretRef } from '#secrets';
+import type { DeployDriver } from './driver.ts';
+import { driverFor } from './drivers.ts';
+import { secretGrantSteps } from './gcp/provision.ts';
+import { requireProject } from './gcp/gcloud.ts';
+import { encodeRef } from './adapters/gcp-secret-manager.ts';
+
+/**
+ * Binding one connection's credentials to the revision that will serve them.
+ *
+ * **The invariant this restores: a revision can rotate every credential it
+ * serves.** `provisionSteps` establishes it over the connections the config held
+ * *at deploy time*, one secret at a time, which is the right shape — a
+ * resource-level grant needs no condition to be scoped. What nothing did was
+ * keep it true afterwards. `connect` writes a credential into the same store and
+ * binds nothing, so from the next connect until the next deploy the invariant is
+ * false and no command says so.
+ *
+ * The failure it produces is the worst shape available. Read is unaffected, so
+ * the connection authorises, answers, and reports `active`; only the *write* on
+ * the far side of the first token refresh is denied, roughly an hour later, by
+ * which time the connect that caused it is not the recent event. `status` and
+ * `setup_overview` both keep saying "connected and reachable" throughout,
+ * because both read the state store and the state store knows nothing about IAM.
+ *
+ * **Every path that writes a credential reaches this one.** `connect custom`
+ * delegates to `runConnect` after writing its manifest, and `connectFamily`
+ * calls `runConnect` per member, so binding at that one call site covers all
+ * three. The reverse direction needs nothing: `disconnect` deletes the whole
+ * secret rather than a version, and a secret's IAM policy goes with it, so there
+ * is no orphaned binding to revoke.
+ *
+ * Same steps as the deploy, from the same functions, over one connection's refs.
+ * Not a second implementation of the grant: `reconcile.ts` argues that a preview
+ * computed differently from the mutation eventually becomes a lie, and the
+ * argument is stronger here, because two spellings of a grant do not disagree on
+ * screen — they disagree about which permission actually exists.
+ */
+
+export interface BindOutcome {
+  /** Refs the revision can now read and rotate. Empty is a normal result. */
+  readonly bound: readonly SecretRef[];
+  /**
+   * Why nothing was bound, when nothing was and that is fine: a local target, a
+   * deployment with no runtime service account, or a provider holding no
+   * credential at all.
+   */
+  readonly skipped?: string | undefined;
+  /**
+   * A binding that could not be applied, as a sentence for the operator.
+   *
+   * Carried rather than thrown, and that is deliberate. By the time this runs
+   * the credential is already in the store and the config is already saved, so
+   * failing the command would report "connect failed" about a connect that
+   * happened. It also must not require `gcloud` to be installed: someone can
+   * legitimately connect an account against a deployed target from a machine
+   * that has never deployed one.
+   */
+  readonly failed?: string | undefined;
+}
+
+const NOTHING_TO_BIND = 'this provider stores no credential';
+
+export async function bindConnectionCredentials(input: {
+  readonly deploy: DeployConfig | undefined;
+  readonly target: string;
+  readonly connection: ConnectionConfig;
+  /**
+   * The provider's manifest, so an omitted `credential_ref` can be derived.
+   *
+   * Typed off `#registry`'s own signature rather than by importing
+   * `ProviderManifest`: `#deployments` may not import `#connectivity`
+   * (`architecture.test.ts`), which is the same rule that put `credentialRefFor`
+   * in `#registry` in the first place. `prepare.ts` avoids it by never naming
+   * the type; this one has to name it, so it derives it.
+   */
+  readonly manifest: Parameters<typeof rotatableCredentialRefsFor>[1];
+  /** Injectable so a test asserts the argv without a cloud project near it. */
+  readonly driver?: DeployDriver | undefined;
+}): Promise<BindOutcome> {
+  const { deploy, connection, manifest } = input;
+  if (!deploy) return { bound: [], skipped: 'this target runs here, not on a platform' };
+
+  const cloudrun = requireProject(deploy, input.target);
+  const serviceAccount = cloudrun.service_account;
+  if (!serviceAccount) {
+    return { bound: [], skipped: 'this deployment declares no runtime service account' };
+  }
+
+  // Both halves, because a connection made since the last deploy has neither.
+  // The read grant is the one an older deployment's project-wide
+  // `secretAccessor` happens to cover, which is exactly what made this failure
+  // partial and therefore slow to find; a deployment provisioned since that
+  // changed has no read on it either.
+  const readable = credentialRefFor(connection, manifest);
+  const rotatable = rotatableCredentialRefsFor(connection, manifest);
+  if (!readable && rotatable.length === 0) return { bound: [], skipped: NOTHING_TO_BIND };
+
+  const steps = secretGrantSteps({
+    project: cloudrun.project,
+    serviceAccount,
+    readable: readable ? [readable] : [],
+    rotatable,
+  });
+
+  const driver = input.driver ?? (await driverFor(deploy.platform));
+
+  for (const step of steps) {
+    const result = await driver.run(step.argv, { quiet: true });
+    // `tolerateFailure` on these means "the secret may already exist", which is
+    // the create step's success case. A binding that genuinely could not be
+    // applied is still worth saying out loud — quietly tolerating it here is how
+    // the deploy path let this class of gap through in the first place.
+    if (!result.ok && !step.argv.includes('add-iam-policy-binding')) continue;
+    if (!result.ok) {
+      return {
+        bound: [],
+        failed:
+          `could not bind ${connection.provider}.${connection.id}'s credential to ` +
+          `${serviceAccount}, so the deployed endpoint will be able to read it and not ` +
+          'rotate it — which fails about an hour after the first use. ' +
+          `Run \`lanes link deploy --target ${input.target}\` to bind it. ` +
+          `(${driver.tool}: ${result.stderr.trim().split('\n').slice(-1)[0] ?? 'failed'})`,
+      };
+    }
+  }
+
+  return { bound: readable ? [readable, ...rotatable] : rotatable };
+}
+
+/**
+ * The credentials a deployed revision serves but cannot rewrite.
+ *
+ * The detection half of the same invariant `bindConnectionCredentials` keeps.
+ * Binding at connect time closes the gap going forward; this one answers for a
+ * workspace that already has it, and for every way a binding can go missing that
+ * no command is watching — a secret rebuilt by hand, a service account replaced,
+ * a profile edited in an editor, a connection made by an older CLI.
+ *
+ * Asked of the platform rather than derived from a record this repository keeps,
+ * because a record would only ever agree with itself. IAM is the thing that
+ * actually decides, so IAM is what gets read.
+ *
+ * One call per ref, concurrently. `doctor` is the command where a few seconds
+ * buys an answer nothing else on the machine can give — and the alternative,
+ * finding out from a 403 an hour after a connect, is the failure this exists to
+ * pre-empt.
+ */
+export async function unboundRotatableRefs(input: {
+  readonly deploy: DeployConfig | undefined;
+  readonly target: string;
+  readonly connections: readonly ConnectionConfig[];
+  readonly manifestFor: (providerId: string) => Parameters<typeof rotatableCredentialRefsFor>[1];
+  readonly driver?: DeployDriver | undefined;
+}): Promise<{ unbound: readonly SecretRef[]; unavailable?: string | undefined }> {
+  const { deploy } = input;
+  if (!deploy) return { unbound: [] };
+
+  const cloudrun = requireProject(deploy, input.target);
+  const serviceAccount = cloudrun.service_account;
+  if (!serviceAccount) return { unbound: [] };
+
+  const refs = new Set<SecretRef>();
+  for (const connection of input.connections) {
+    for (const ref of rotatableCredentialRefsFor(connection, input.manifestFor(connection.provider))) {
+      refs.add(ref);
+    }
+  }
+  if (refs.size === 0) return { unbound: [] };
+
+  const driver = input.driver ?? (await driverFor(deploy.platform));
+  const member = `serviceAccount:${serviceAccount}`;
+
+  const verdicts = await Promise.all(
+    [...refs].map(async (ref) => {
+      const result = await driver.run(
+        ['secrets', 'get-iam-policy', encodeRef(ref), '--project', cloudrun.project, '--format', 'json'],
+        { quiet: true },
+      );
+      // A ref whose policy cannot be read is not reported as unbound: "could not
+      // look" and "is not granted" send an operator to different places, and
+      // this command exists to be trusted about the second one.
+      if (!result.ok) return { ref, bound: true, unreadable: true };
+
+      try {
+        const policy = JSON.parse(result.stdout) as {
+          bindings?: { role?: string; members?: string[] }[];
+        };
+        const bound = (policy.bindings ?? []).some(
+          (binding) =>
+            binding.role === 'roles/secretmanager.secretVersionAdder' &&
+            (binding.members ?? []).includes(member),
+        );
+        return { ref, bound, unreadable: false };
+      } catch {
+        return { ref, bound: true, unreadable: true };
+      }
+    }),
+  );
+
+  const unreadable = verdicts.filter((verdict) => verdict.unreadable).length;
+  return {
+    unbound: verdicts.filter((verdict) => !verdict.bound).map((verdict) => verdict.ref),
+    ...(unreadable > 0
+      ? {
+          unavailable:
+            `${unreadable} of ${refs.size} credential policies could not be read, so this ` +
+            `check covered the rest. ${driver.tool} has to be installed and authorised for it.`,
+        }
+      : {}),
+  };
+}

package/src/deployments/gcp/Dockerfile

@@ -18,9 +18,31 @@ WORKDIR /app
 # The manifest first, so a source-only change reuses the install layer. One
 # package now, rather than fifteen manifests copied ahead of the install to
 # satisfy workspace resolution.
-COPY package.json bun.lock bunfig.toml ./
+#
+# `bun.lock*`, not `bun.lock`, and the star is the whole point: **npm strips a
+# root lockfile out of a published tarball whatever `files` says.** Verified
+# against npm 12, which is what `release.yml` installs before publishing; npm
+# 11.6 still packs it, so a local `npm pack` says the opposite and the gap only
+# shows up in what people actually install.
+#
+# This image is built from whichever tree `lanes link deploy` is run against, and
+# there are two of them. From a checkout the lockfile is present and pins the
+# whole transitive set. From a bun-global install — the only install method this
+# CLI documents — it cannot be there at all, and naming it outright made deploy
+# impossible for every one of those users: the build pulled the base image,
+# pushed a context, and then died on `stat bun.lock: file does not exist`.
+COPY package.json bunfig.toml bun.lock* ./
 
-RUN bun install --frozen-lockfile
+# Not `--frozen-lockfile || bun install`: that swallows a genuine
+# lockfile-versus-manifest disagreement in a checkout build, which is the one
+# thing the frozen flag is for. The branch says which tree it is building and
+# holds the guarantee that tree can offer.
+#
+# What the fallback gives up is narrower than it looks. Every runtime dependency
+# in `package.json` is an exact version, so the direct set is identical either
+# way; the lockfile pins what those depend on in turn, and a published package
+# has never been able to carry one.
+RUN if [ -f bun.lock ]; then bun install --frozen-lockfile; else bun install; fi
 
 COPY src/ src/
 

package/src/deployments/gcp/provision.ts

@@ -1,4 +1,4 @@
-import { VAULT_DOCUMENT_REF } from '#secrets';
+import { VAULT_DOCUMENT_REF, type SecretRef } from '#secrets';
 import type { DeployStep, ProvisionInput } from '../driver.ts';
 import { encodeRef } from '../adapters/gcp-secret-manager.ts';
 import { requireProject } from './gcloud.ts';
@@ -43,6 +43,109 @@ const REQUIRED_SERVICES = [
   'cloudresourcemanager.googleapis.com',
 ];
 
+/**
+ * Who the grant is for, and on what.
+ *
+ * A named type because these two functions are now called from two places that
+ * must not disagree — see the note on `secretGrantSteps`.
+ */
+export interface SecretGrant {
+  readonly project: string;
+  readonly serviceAccount: string;
+  readonly refs: readonly SecretRef[];
+}
+
+/** Read, named one secret at a time, so the grant needs no condition to be scoped. */
+export function readSteps({ project, serviceAccount, refs }: SecretGrant): DeployStep[] {
+  return refs.map((ref) => ({
+    title: `let the revision read ${ref}`,
+    argv: [
+      'secrets',
+      'add-iam-policy-binding',
+      encodeRef(ref),
+      '--project',
+      project,
+      '--member',
+      `serviceAccount:${serviceAccount}`,
+      '--role',
+      'roles/secretmanager.secretAccessor',
+      // Bindings are printed as the whole policy otherwise, which is pages
+      // of YAML per deploy and buries everything after it.
+      '--condition',
+      'None',
+    ],
+    tolerateFailure: true,
+  }));
+}
+
+/**
+ * Write, two steps each, and the first is what keeps the second narrow: the
+ * secret is created here so the revision only ever needs to *add a version*,
+ * never `secrets.create`, which is a project-level permission that would let it
+ * mint credential references of its own.
+ */
+export function rotateSteps({ project, serviceAccount, refs }: SecretGrant): DeployStep[] {
+  return refs.flatMap((ref) => {
+    const id = encodeRef(ref);
+    return [
+      {
+        title: `create the secret ${id}, so the revision never needs secrets.create`,
+        argv: ['secrets', 'create', id, '--project', project, '--replication-policy', 'automatic'],
+        tolerateFailure: true,
+      },
+      {
+        title: `let the revision rewrite ${ref}, and nothing else in the store`,
+        argv: [
+          'secrets',
+          'add-iam-policy-binding',
+          id,
+          '--project',
+          project,
+          '--member',
+          `serviceAccount:${serviceAccount}`,
+          '--role',
+          'roles/secretmanager.secretVersionAdder',
+          '--condition',
+          'None',
+        ],
+        tolerateFailure: true,
+      },
+    ];
+  });
+}
+
+/**
+ * Both halves for one connection's credentials, for a caller that is not a deploy.
+ *
+ * **This exists because the grant was a deploy-time snapshot of a set that
+ * changes between deploys.** `provisionSteps` walks the config's connections and
+ * binds each secret it finds; `connect` then adds a connection, writes its
+ * credential, and binds nothing. The revision can read the new secret — an older
+ * deployment's project-wide `secretAccessor` covers it, and a current one does
+ * not — but it cannot add a version, so the first OAuth refresh 403s. The
+ * connection works for exactly as long as its initial access token lasts, which
+ * is about an hour, and then stops for a reason nothing on the connection says.
+ *
+ * So the same steps are reachable from `connect`, over one connection's refs
+ * rather than the whole config's. Deliberately the *same functions* rather than
+ * a second implementation: `reconcile.ts` makes the same argument for planning
+ * and applying, and it holds harder here, because a second spelling of a grant
+ * is not a wrong answer on screen, it is a permission that is missing in one
+ * path and present in the other.
+ */
+export function secretGrantSteps(
+  grant: Omit<SecretGrant, 'refs'> & {
+    readonly readable: readonly SecretRef[];
+    readonly rotatable: readonly SecretRef[];
+  },
+): DeployStep[] {
+  const { project, serviceAccount } = grant;
+  return [
+    ...readSteps({ project, serviceAccount, refs: grant.readable }),
+    ...rotateSteps({ project, serviceAccount, refs: grant.rotatable }),
+  ];
+}
+
 export function provisionSteps(input: ProvisionInput): Promise<DeployStep[]> {
   const cloudrun = requireProject(input.deploy, input.target);
   const { project, region, service_account: serviceAccount } = cloudrun;
@@ -116,27 +219,7 @@ export function provisionSteps(input: ProvisionInput): Promise<DeployStep[]> {
     // Affordable because the serving path reads by explicit ref: `list()` is a
     // CLI call, and `secretAccessor` never carried `secrets.list` anyway.
     // `readableRefs` derives the set from config and manifests at deploy time.
-    for (const ref of input.readable ?? []) {
-      steps.push({
-        title: `let the revision read ${ref}`,
-        argv: [
-          'secrets',
-          'add-iam-policy-binding',
-          encodeRef(ref),
-          '--project',
-          project,
-          '--member',
-          `serviceAccount:${serviceAccount}`,
-          '--role',
-          'roles/secretmanager.secretAccessor',
-          // Bindings are printed as the whole policy otherwise, which is pages
-          // of YAML per deploy and buries everything after it.
-          '--condition',
-          'None',
-        ],
-        tolerateFailure: true,
-      });
-    }
+    steps.push(...readSteps({ project, serviceAccount, refs: input.readable ?? [] }));
   }
 
   // What a revision rewrites in its own credential store, named one secret at a
@@ -165,32 +248,8 @@ export function provisionSteps(input: ProvisionInput): Promise<DeployStep[]> {
       ]
     : [];
 
-  for (const ref of writable) {
-    const id = encodeRef(ref);
-
-    steps.push({
-      title: `create the secret ${id}, so the revision never needs secrets.create`,
-      argv: ['secrets', 'create', id, '--project', project, '--replication-policy', 'automatic'],
-      tolerateFailure: true,
-    });
-
-    steps.push({
-      title: `let the revision rewrite ${ref}, and nothing else in the store`,
-      argv: [
-        'secrets',
-        'add-iam-policy-binding',
-        id,
-        '--project',
-        project,
-        '--member',
-        `serviceAccount:${serviceAccount}`,
-        '--role',
-        'roles/secretmanager.secretVersionAdder',
-        '--condition',
-        'None',
-      ],
-      tolerateFailure: true,
-    });
+  if (serviceAccount) {
+    steps.push(...rotateSteps({ project, serviceAccount, refs: writable }));
   }
 
   // Any target that addresses a bucket, which deployed means all of them:
@@ -241,8 +300,18 @@ export function provisionSteps(input: ProvisionInput): Promise<DeployStep[]> {
       // what the revision owns from what declares what it is. Anchored to the
       // profile segment rather than matched loosely: `contains("/providers.d/")`
       // would also catch a blob whose own key happened to spell it.
+      //
+      // The dot is a character class, not `\.`, and that is the fix rather than
+      // a style: this string is a *CEL string literal* holding a regex, so it is
+      // unescaped once by CEL before the regex engine ever sees it. `\.` is not
+      // a CEL escape sequence, so the whole expression failed to compile —
+      // `token recognition error at: '"^projects/_/buckets/...providers\.'` —
+      // and both bindings below carry `tolerateFailure`, so a deploy printed two
+      // warnings and carried on with the scoping silently not applied. `[.]` is
+      // the same regex and survives a layer of string unescaping unchanged,
+      // which is what keeps the next person from reintroducing it.
       const providerManifests =
-        `resource.name.matches("^projects/_/buckets/${bucket}/objects/data/[^/]+/providers\\.d/")`;
+        `resource.name.matches("^projects/_/buckets/${bucket}/objects/data/[^/]+/providers[.]d/")`;
 
       steps.push({
         title: 'let the revision write its own data, but not the manifests in it',