@lanes-sh/link 0.7.1 → 0.8.0

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

@@ -151,14 +151,14 @@ export async function tokenInvocation(
   target: string,
 ): Promise<{ command: string; onPath: boolean }> {
   // Both, always, and from the *resolved* selection rather than the flags. A
-  // token is per-target, so `outputs --target cloud` printing a bare
+  // token is per-target, so `outputs --workspace cloud` printing a bare
   // `token show --raw` hands over the local one beside a deployed URL — a
   // credential that looks like an answer and fails as a wrong password. Naming
   // the profile as well makes the line pasteable into any shell rather than
   // only into one where the same default happens to resolve.
-  const selection = ` --profile ${profile} --target ${target}`;
+  const selection = ` --profile ${profile} --workspace ${target}`;
   const short = `lanes link token show --raw${selection}`;
-  const argv = ['link', 'token', 'show', '--raw', '--profile', profile, '--target', target];
+  const argv = ['link', 'token', 'show', '--raw', '--profile', profile, '--workspace', target];
 
   const resolved = Bun.which('lanes');
   if (resolved) {

package/src/cli/commands/operate/pair-certificate.ts

@@ -0,0 +1,141 @@
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { ConfigError, PAIR_CERT_REF, PAIR_KEY_REF } from '#profile';
+import type { SecretStore } from '#secrets';
+import { print, style, warn } from '../../output.ts';
+import { confirm, isInteractive } from '../../prompt.ts';
+import type { PairDeps, PairFlags } from './pair.ts';
+
+/**
+ * Making a loopback address one this machine's browsers will trust.
+ *
+ * Split from `./pair.ts` because it is the half of pairing that only loopback
+ * has. A deployed endpoint terminates TLS with a certificate a browser already
+ * trusts, so none of this runs for one — and keeping it beside the command made
+ * a file most of which did not apply to half its callers.
+ *
+ * It is also the largest side effect any command in this CLI has: a persistent
+ * change to the machine's trust store, made by a CLI. That is why everything
+ * here asks first, and why a run with nobody at the terminal is refused rather
+ * than assumed.
+ */
+
+/** The names the certificate has to cover. All three are this machine. */
+const HOSTS = ['127.0.0.1', 'localhost', '::1'];
+
+/**
+ * A certificate a browser on this machine will accept.
+ *
+ * mkcert and nothing else, deliberately. It is the one tool that installs into
+ * the system trust store *and* Firefox's separate NSS store, across macOS,
+ * Linux and Windows — and a self-signed certificate this command generated
+ * itself would fail in the browser with an error the page cannot read, which is
+ * the worst of both: the work is done and the feature does not work.
+ */
+export async function ensureCertificate(
+  credentials: SecretStore,
+  flags: PairFlags,
+  deps: PairDeps,
+): Promise<'reused' | 'installed'> {
+  const held =
+    (await credentials.get(PAIR_CERT_REF)) !== null &&
+    (await credentials.get(PAIR_KEY_REF)) !== null;
+
+  if (held && flags.rotate !== true) return 'reused';
+
+  const which = deps.which ?? ((binary: string) => Bun.which(binary));
+  const run = deps.run ?? runCommand;
+
+  let mkcert = which('mkcert');
+  if (!mkcert) mkcert = await installMkcert(flags, deps, which, run);
+
+  // Installs the local CA if it is not already there, and says nothing if it
+  // is. This is the step that touches the trust store, and it has already been
+  // consented to by the time it runs.
+  const installed = await run([mkcert, '-install']);
+  if (installed !== null) {
+    throw new ConfigError(`mkcert -install failed.\n${installed || '  It said nothing.'}`);
+  }
+
+  const scratch = await mkdtemp(join(tmpdir(), 'lanes-pair-'));
+  try {
+    const certPath = join(scratch, 'cert.pem');
+    const keyPath = join(scratch, 'key.pem');
+
+    const failed = await run([mkcert, '-cert-file', certPath, '-key-file', keyPath, ...HOSTS]);
+    if (failed !== null) {
+      throw new ConfigError(`mkcert failed to issue a certificate.\n${failed || '  It said nothing.'}`);
+    }
+
+    // Into the credential store rather than left on disk. The private key is a
+    // secret by any reading, and the store is the one place in a workspace that
+    // is encrypted at rest.
+    await credentials.set(PAIR_CERT_REF, await readFile(certPath, 'utf8'));
+    await credentials.set(PAIR_KEY_REF, await readFile(keyPath, 'utf8'));
+  } finally {
+    await rm(scratch, { recursive: true, force: true });
+  }
+
+  return 'installed';
+}
+
+async function installMkcert(
+  flags: PairFlags,
+  deps: PairDeps,
+  which: (binary: string) => string | null,
+  run: (command: readonly string[]) => Promise<string | null>,
+): Promise<string> {
+  const line = 'brew install mkcert';
+  const brew = which('brew');
+
+  if (!brew) {
+    // The one path where this command cannot finish the job, so it hands over
+    // the whole of it rather than half.
+    throw new ConfigError(
+      'Pairing needs mkcert, which issues a certificate this machine\'s browsers trust.\n' +
+        `  With Homebrew: ${line}\n` +
+        '  Otherwise: https://github.com/FiloSottile/mkcert#installation\n' +
+        '  Then run "lanes link pair" again.',
+    );
+  }
+
+  print(warn('pairing needs mkcert, and it is not installed'));
+  print(
+    style.dim(
+      '  It issues a certificate for 127.0.0.1 that this machine trusts, which is what\n' +
+        '  lets a page on lanes.sh read your endpoint at all. Safari will not fetch\n' +
+        '  http://127.0.0.1 from an https page, and offers no way to allow it.\n' +
+        '\n' +
+        '  This installs a local certificate authority into your system trust store.\n' +
+        `  ${line}`,
+    ),
+  );
+
+  if (flags.yes !== true) {
+    if (!(deps.interactive ?? isInteractive())) {
+      throw new ConfigError(
+        'Nothing here can answer a prompt, and installing a certificate authority because\n' +
+          '  nobody was there to say no is the wrong way to resolve that.\n' +
+          `  Run "${line}" yourself, or pass --yes.`,
+      );
+    }
+    if (!(await (deps.confirm ?? ((question: string) => confirm(question)))('Install it now?'))) {
+      throw new ConfigError(`Not paired. When you want it: ${line}`);
+    }
+  }
+
+  const failed = await run([brew, 'install', 'mkcert']);
+  if (failed !== null) throw new ConfigError(`${line} failed.\n${failed || '  It said nothing.'}`);
+
+  const found = which('mkcert');
+  if (!found) throw new ConfigError(`${line} reported success but mkcert is still not on PATH.`);
+  return found;
+}
+
+/** Runs it. Null on success; whatever it said on failure. */
+async function runCommand(command: readonly string[]): Promise<string | null> {
+  const spawned = Bun.spawn([...command], { stdout: 'pipe', stderr: 'pipe' });
+  const [code, stderr] = await Promise.all([spawned.exited, new Response(spawned.stderr).text()]);
+  return code === 0 ? null : stderr.trim();
+}

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

@@ -0,0 +1,324 @@
+import { randomBytes } from 'node:crypto';
+import {
+  ConfigError,
+  PAIR_CERT_REF,
+  PAIR_KEY_REF,
+  PAIR_TOKEN_REF,
+  loadWorkspaceProfiles,
+  openTarget,
+  type LoadedProfile,
+  resolveWorkspaceRoot,
+} from '#profile';
+import type { ResolvedTarget } from '#profile';
+import { deployedUrl } from '../../endpoint-url.ts';
+import { ensureCertificate } from './pair-certificate.ts';
+import { recordConfigChange } from '../../audit-change.ts';
+import { ok, print, style } from '../../output.ts';
+import type { SecretStore } from '#secrets';
+import { openSecretStoreFor, type GlobalFlags } from '../../runtime.ts';
+
+/**
+ * `lanes link pair` — let the Lanes dashboard read this machine (ADR-063).
+ *
+ * Three things, and each is the operator's to decline. It installs a locally
+ * trusted certificate, mints a credential that reads the whole workspace, and
+ * hands the browser a link carrying it. None of that happens without being
+ * asked for, and none of it is implied by `start`.
+ *
+ * **The certificate is the largest side effect any command in this CLI has.**
+ * It is a persistent change to the machine's trust store, made by a CLI, and
+ * ADR-053's precedent applies unchanged: offer it, name what it is, and stop if
+ * declined. A run with nobody at the terminal is refused rather than assumed.
+ *
+ * **The token travels in a fragment.** `#pair=` is never sent to a server, so a
+ * credential for a surface whose entire point is that Lanes cannot see it does
+ * not end up in a Lanes access log, a proxy, or a referrer header.
+ *
+ * **A deployed workspace pairs too, and skips all of that** (ADR-064). The
+ * certificate was the whole of the old refusal — installing one for an address
+ * this machine does not answer on is meaningless — and it is the one piece a
+ * deployed endpoint does not need, because the platform terminates TLS with a
+ * certificate a browser already trusts. What remains is a token and an address.
+ *
+ * **It names a workspace, not a profile**, because that is what it pairs. The
+ * surface it opens lists every connection and every profile the workspace holds,
+ * and the credential it mints reads all of them — so asking which profile was
+ * asking a question with no answer, and implying a per-profile pairing that does
+ * not exist. `--profile` is still accepted, and picks the port when profiles
+ * disagree about one.
+ */
+
+/**
+ * Where the three pieces live in the credential store.
+ *
+ * Declared in `#profile` rather than here, because three components read these
+ * names now and only one of them is the CLI — the server opens the read surface
+ * with them and a deploy binds the token so the revision may read it. Importing
+ * a *command* module for a string constant pulled the CLI's output and prompt
+ * handling into the container's runtime graph. Re-exported because a year of
+ * callers spell them from here.
+ */
+export { PAIR_CERT_REF, PAIR_KEY_REF, PAIR_TOKEN_REF };
+
+/** Where the dashboard lives, overridable so `lanes dev` can pair against it. */
+const DASHBOARD_URL = process.env['LANES_WEB_URL'] ?? 'https://lanes.sh';
+
+export interface PairFlags extends GlobalFlags {
+  /** Print the link for an existing pairing and change nothing. */
+  readonly print?: boolean | undefined;
+  /** Mint a fresh token, invalidating whatever a browser already holds. */
+  readonly rotate?: boolean | undefined;
+  /** Do not ask before installing mkcert. */
+  readonly yes?: boolean | undefined;
+}
+
+export interface PairDeps {
+  readonly which?: (binary: string) => string | null;
+  readonly run?: (command: readonly string[]) => Promise<string | null>;
+  readonly confirm?: (question: string) => Promise<boolean>;
+  readonly interactive?: boolean;
+}
+
+export async function pair(flags: PairFlags, deps: PairDeps = {}): Promise<void> {
+  const target = flags.target!;
+  const root = resolveWorkspaceRoot();
+  const resolved = await openTarget(root, target);
+  const { loaded: profiles } = await loadWorkspaceProfiles(resolved.workspaceRoot);
+
+  if (profiles.length === 0) {
+    throw new ConfigError(
+      `Workspace "${target}" holds no profiles, so there is no endpoint to pair.\n` +
+        `  Create one with: lanes link profile add <name> --workspace ${target}`,
+    );
+  }
+
+  // One endpoint serves every profile in a workspace, so they normally agree on
+  // a port and the choice is not a choice. Where they do not, the ambiguity is
+  // real and `--profile` is how it is settled — refused rather than guessed,
+  // because pairing the wrong port produces a dashboard that says "not
+  // connected" with everything working.
+  const named = flags.profile
+    ? profiles.find((one: LoadedProfile) => one.profile === flags.profile)
+    : undefined;
+
+  if (flags.profile && !named) {
+    throw new ConfigError(
+      `Workspace "${target}" has no profile "${flags.profile}".\n` +
+        `  It holds: ${profiles.map((one: LoadedProfile) => one.profile).join(', ')}`,
+    );
+  }
+
+  const ports = new Set(profiles.map((one: LoadedProfile) => one.config.instance.port));
+  if (!named && ports.size > 1) {
+    throw new ConfigError(
+      `The profiles in "${target}" do not agree on a port, so it is not clear which endpoint to pair.\n` +
+        profiles
+          .map((one: LoadedProfile) => `    ${one.profile}  ${one.config.instance.port}`)
+          .join('\n') +
+        '\n  Name one: lanes link pair --profile <name>',
+    );
+  }
+
+  const chosen = named ?? profiles[0]!;
+  const host = chosen.config.instance.host;
+  const credentials = await openSecretStoreFor(chosen.config, root, target);
+
+  // A workspace that declares a deployment is paired over the address the
+  // platform gave it, not over loopback — which is what `declared.deploy`
+  // answers and what `instance.host` does not: a deployed revision takes its
+  // host from the container's environment, so a profile bound to `127.0.0.1`
+  // in config is still serving `0.0.0.0` on Cloud Run.
+  if (resolved.declared.deploy) {
+    await pairDeployed({ flags, target, chosen, root, credentials, deploy: resolved.declared.deploy });
+    return;
+  }
+
+  if (!isLoopback(host)) {
+    // Not deployed, and not on this machine either. There is no certificate
+    // this command could install for an address this machine does not answer
+    // on, and no platform URL to hand the browser instead.
+    throw new ConfigError(
+      `"${target}" is bound to ${host}, which is neither loopback nor a deployment.\n` +
+        '  Pairing reaches an endpoint on *this* machine, or one `lanes link deploy` put\n' +
+        '  somewhere with an address of its own.',
+    );
+  }
+
+  const readPort = chosen.config.instance.port + 1;
+
+  // `127.0.0.1` rather than `instance.host`, even though `localhost` and `::1`
+  // are equally loopback and equally covered by the certificate. It is one
+  // address for one machine, and the browser has to agree with `open.ts` about
+  // which spelling it is: two pairings of the same endpoint under two names
+  // would be two entries in the switcher, both working, neither wrong.
+  const address = `https://127.0.0.1:${readPort}`;
+
+  if (flags.print === true) {
+    const existing = await credentials.get(PAIR_TOKEN_REF);
+    if (existing === null) throw new ConfigError('Not paired yet. Run: lanes link pair');
+    print(pairingLink(existing, address));
+    return;
+  }
+
+  const certificate = await ensureCertificate(credentials, flags, deps);
+
+  const rotating = flags.rotate === true;
+  const existing = rotating ? null : await credentials.get(PAIR_TOKEN_REF);
+  const token = existing ?? `llp_${randomBytes(32).toString('base64url')}`;
+  if (existing === null) await credentials.set(PAIR_TOKEN_REF, token);
+
+  // The token itself never goes in, obviously. What is worth recording is that
+  // a credential reading the whole workspace now exists, and when — and for a
+  // rotation, that whatever a browser was holding stopped working at that
+  // moment.
+  if (existing === null) {
+    await recordConfigChange(chosen.config, root, target, {
+      capability: rotating ? 'config.pair.rotate' : 'config.pair.mint',
+      scope: target,
+      arguments: { readPort, certificate },
+    });
+  }
+
+  print(ok(certificate === 'reused' ? 'certificate already installed' : 'certificate installed'));
+  if (rotating) {
+    print(style.dim('      The previous pairing link no longer works. Re-open the new one.'));
+  }
+  print('');
+  print(ok(`the dashboard may now read ${style.bold(address)}`));
+  print('');
+  print(pairingLink(token, address));
+  print('');
+  print(
+    style.dim(
+      '      Open that in a browser on this machine. The token is in the URL fragment,\n' +
+        '      so it never reaches a Lanes server.\n' +
+        '      It reads every connection, profile and audit entry in this workspace, and\n' +
+        '      can change nothing. Take it back with: lanes link pair --rotate\n' +
+        '\n' +
+        `      The endpoint has to be running: lanes link start --workspace ${target}`,
+    ),
+  );
+}
+
+/**
+ * Pairing a workspace that lives somewhere with an address of its own (ADR-064).
+ *
+ * The half of `pair` that is *not* shared with loopback is the certificate, and
+ * that was always the whole of the old refusal: installing one for an address
+ * this machine does not answer on is meaningless, and it is still meaningless.
+ * What was never the thing being refused is the credential and the address —
+ * the endpoint terminates TLS with a certificate a browser already trusts, so
+ * the two pieces that remain are a token and a URL.
+ *
+ * So there is no `mkcert` here, nothing is installed, and nothing is asked. The
+ * command writes one secret and prints a link.
+ */
+async function pairDeployed(input: {
+  flags: PairFlags;
+  target: string;
+  chosen: LoadedProfile;
+  root: string;
+  credentials: SecretStore;
+  deploy: NonNullable<ResolvedTarget['declared']['deploy']>;
+}): Promise<void> {
+  const { flags, target, chosen, root, credentials } = input;
+
+  // `deployedUrl` asks the platform where the service ended up and degrades to
+  // null for every reason that is not this command's business — no driver, not
+  // deployed yet, no credentials for the project. A link with no address in it
+  // reads nothing, so this refuses rather than printing half of one.
+  const mcpUrl = await deployedUrl(input.deploy);
+  if (mcpUrl === null) {
+    throw new ConfigError(
+      `Could not find the address of "${target}".\n` +
+        '  The service may not be deployed yet, or the platform CLI may not be signed in.\n' +
+        `  Check it with: lanes link outputs --workspace ${target}`,
+    );
+  }
+
+  // The read surface answers on the endpoint's own origin, beside `/mcp` rather
+  // than on a port of its own — Cloud Run routes exactly one.
+  const endpoint = mcpUrl.replace(/\/mcp$/, '');
+
+  if (flags.print === true) {
+    const existing = await credentials.get(PAIR_TOKEN_REF);
+    if (existing === null || existing === '') {
+      throw new ConfigError(`Not paired yet. Run: lanes link pair --workspace ${target}`);
+    }
+    print(pairingLink(existing, endpoint));
+    return;
+  }
+
+  const rotating = flags.rotate === true;
+  const held = rotating ? null : await credentials.get(PAIR_TOKEN_REF);
+
+  // An empty string, not just a missing ref: `lanes link deploy` creates this
+  // secret with no version so the revision's IAM binding has something to
+  // attach to, and a secret that exists with no version reads back as null
+  // here and as `unpaired` there. Either shape means nobody has paired yet.
+  const existing = held === '' ? null : held;
+  const token = existing ?? `llp_${randomBytes(32).toString('base64url')}`;
+  if (existing === null) await credentials.set(PAIR_TOKEN_REF, token);
+
+  if (existing === null) {
+    await recordConfigChange(chosen.config, root, target, {
+      capability: rotating ? 'config.pair.rotate' : 'config.pair.mint',
+      scope: target,
+      arguments: { endpoint },
+    });
+  }
+
+  print(ok('no certificate needed — this endpoint already has one a browser trusts'));
+  if (rotating) {
+    print(style.dim('      The previous pairing link no longer works. Re-open the new one.'));
+  }
+  print('');
+  print(ok(`the dashboard may now read ${style.bold(endpoint)}`));
+  print('');
+  print(pairingLink(token, endpoint));
+  print('');
+  print(
+    style.dim(
+      '      Open that in any browser, on any machine. The token is in the URL fragment,\n' +
+        '      so it never reaches a Lanes server.\n' +
+        '      It reads every connection, profile and audit entry in this workspace, and\n' +
+        '      can change nothing. Take it back with:\n' +
+        `        lanes link pair --workspace ${target} --rotate\n` +
+        '\n' +
+        '      A rotation takes up to five seconds to be refused, because the endpoint\n' +
+        '      caches what it read rather than calling Secret Manager per request.',
+    ),
+  );
+}
+
+/**
+ * The link the browser opens.
+ *
+ * The token rides in the fragment, which is never sent to a server — so a
+ * credential for a surface whose entire point is that Lanes cannot see this
+ * data does not land in a Lanes access log, a proxy, or a referrer header. The
+ * address rides beside it for the same reason and one more: it is the only
+ * thing telling the page which of several paired endpoints this link is for,
+ * and a query parameter would put a workspace's public address in that log.
+ *
+ * **A loopback link carries its address too**, and the parameter is required so
+ * that it cannot quietly stop. It used to be omitted here on the reasoning that
+ * loopback is derivable — and it is not: the read listener sits one port above
+ * whatever `instance.port` says, so an endpoint on any port but the default
+ * printed a link the dashboard then read at `7338`, reported unreachable, and
+ * gave no way to correct. The page still treats a link with no `at=` as
+ * loopback on the default port, because every link minted before this is that
+ * shape.
+ *
+ * Exported for `pair.test.ts` and for nothing else. The whole of the defect
+ * above was a shape nothing asserted on, in a command whose output no test
+ * reads, so the fix is not worth much without something that fails when the
+ * address goes missing again.
+ */
+export function pairingLink(token: string, endpoint: string): string {
+  return `${DASHBOARD_URL}/dashboard/link#pair=${token}&at=${encodeURIComponent(endpoint)}`;
+}
+
+function isLoopback(host: string): boolean {
+  return host === '127.0.0.1' || host === 'localhost' || host === '::1';
+}

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

@@ -1,6 +1,7 @@
 import { loadConfigFile } from '#profile';
+import { recordConfigChange } from '../../audit-change.ts';
 import { ConfigDocument } from '../../config-edit.ts';
-import { announce, announceProfile, heading, ok, print, style, table } from '../../output.ts';
+import { announce, announceProfile, heading, ok, print, style, table, warn } from '../../output.ts';
 import { resolveProfile, resolveProfileOnly, type GlobalFlags } from '../../runtime.ts';
 import { nextAfterEdit, publishProfileEdit } from '../../publish.ts';
 
@@ -15,56 +16,106 @@ export async function policyList(flags: GlobalFlags): Promise<void> {
   const { selection, config } = await resolveProfileOnly(flags);
   announceProfile(selection);
 
-  if (config.policy.allow.length === 0 && config.policy.deny.length === 0) {
-    print(style.dim('No rules. Default deny is in effect: nothing is reachable.'));
+  if (config.grants.length === 0) {
+    print(style.dim('No grants. Default deny is in effect: nothing is reachable.'));
     return;
   }
 
   const expiry = (rule: { capability: string; expires_at?: string | undefined }) =>
     rule.expires_at ? style.dim(`until ${rule.expires_at}`) : '';
 
-  if (config.policy.allow.length > 0) {
-    heading('Allow');
-    table(config.policy.allow.map((rule) => [`  ${style.green('+')}`, rule.capability, expiry(rule)]));
-  }
+  // Grouped by connection rather than by effect, which reverses how this used to
+  // read. A rule governs one account now (ADR-058), so "what may be done with
+  // the work mailbox" is the question the listing should answer in one place —
+  // and the old shape, two lists of capabilities with the account nowhere in
+  // them, could not answer it at all.
+  for (const grant of config.grants) {
+    heading(grant.connection);
+
+    if (grant.allow.length === 0 && grant.deny.length === 0) {
+      print(style.dim('  Granted nothing. The connection is reachable and no capability is.'));
+      continue;
+    }
 
-  if (config.policy.deny.length > 0) {
-    heading('Deny');
-    print(style.dim('  A deny beats any allow, whatever the order in the file.'));
-    table(config.policy.deny.map((rule) => [`  ${style.red('-')}`, rule.capability, expiry(rule)]));
+    table([
+      ...grant.allow.map((rule) => [`  ${style.green('+')}`, rule.capability, expiry(rule)]),
+      ...grant.deny.map((rule) => [`  ${style.red('-')}`, rule.capability, expiry(rule)]),
+    ]);
   }
 
   print('');
+  print(style.dim('A deny beats any allow on the same connection, whatever the order in the file.'));
   print(
-    style.dim('Rules cover every account of a provider. For different grants, use a second profile.'),
+    style.dim('A connection with no row above is not reachable at all, and is never advertised.'),
   );
 }
 
+export interface PolicyFlags extends GlobalFlags {
+  readonly connection?: string | undefined;
+}
+
 export async function policyRule(
   effect: 'allow' | 'deny',
   capability: string,
-  flags: GlobalFlags,
+  flags: PolicyFlags,
 ): Promise<void> {
   const { resolution, config, target } = await resolveProfile(flags);
-  const document = await ConfigDocument.open(resolution.workspaceRoot, resolution.profile);
 
-  if (config.policy[effect].some((rule) => rule.capability === capability)) {
-    print(style.dim(`${effect} ${capability} is already declared.`));
+  // Required, and refused rather than guessed. A rule has to land in a row, and
+  // with two mailboxes granted there is no answer to "which one" that is not a
+  // guess about which account the operator meant to widen.
+  const key = flags.connection;
+  if (key === undefined) {
+    throw new Error(
+      `--connection is required. A rule governs one connection (ADR-058).\n` +
+        (config.grants.length > 0
+          ? `  This profile grants: ${config.grants.map((grant) => grant.connection).join(', ')}`
+          : `  This profile grants nothing yet. Run: lanes link status --profile ${resolution.profile}`),
+    );
+  }
+
+  const index = config.grants.findIndex((grant) => grant.connection === key);
+  if (index === -1) {
+    throw new Error(
+      `Profile "${resolution.profile}" does not grant "${key}".\n` +
+        `  Grant it first, then narrow it:\n` +
+        `    lanes link grant ${key} --profile ${resolution.profile}`,
+    );
+  }
+
+  const grant = config.grants[index]!;
+  if (grant[effect].some((rule) => rule.capability === capability)) {
+    print(style.dim(`${effect} ${capability} on ${key} is already declared.`));
     return;
   }
 
+  const document = await ConfigDocument.open(resolution.workspaceRoot, resolution.profile);
+
   // A bare string, because that is what the file should read like. The object
   // form exists for `expires_at` and is not worth writing by default.
-  document.addTo(['policy', effect], capability, { inline: true });
-  // Validation runs before the write, so a rule naming a provider with no
-  // connection fails here rather than silently granting nothing at runtime.
+  document.addTo(['grants', index, effect], capability, { inline: true });
+  // Validation runs before the write, so a rule naming a provider other than the
+  // row's own fails here rather than matching nothing at runtime.
   await document.save();
 
+  await recordConfigChange(
+    config,
+    resolution.workspaceRoot,
+    target,
+    {
+      capability: effect === 'allow' ? 'config.policy.allow' : 'config.policy.deny',
+      scope: resolution.profile,
+      connection: key,
+      arguments: { capability },
+    },
+    (note) => print(warn(note)),
+  );
+
   announce(resolution);
-  print(ok(`${effect} ${style.bold(capability)}`));
+  print(ok(`${effect} ${style.bold(capability)} on ${style.bold(key)}`));
 
-  if (effect === 'deny' && config.policy.allow.some((rule) => rule.capability === '*')) {
-    print(style.dim('  This narrows the catch-all allow; a deny always wins.'));
+  if (effect === 'deny' && grant.allow.some((rule) => rule.capability === '*')) {
+    print(style.dim("  This narrows that row's catch-all allow; a deny always wins."));
   }
 
   // A deny the endpoint has not heard about is still granting what it names, so