@lanes-sh/link 0.1.0

package/src/deployments/gcp/survey.ts

@@ -0,0 +1,319 @@
+import { ConfigError, type DeployConfig, type TargetConfig } from '#profile';
+import { heading, print, style, waiting } from '#cli/output.ts';
+import { ask, confirm } from '#cli/prompt.ts';
+import type { SurveyInput, SurveyResult } from '../driver.ts';
+import { activeProject, openBillingAccounts, projectExists } from './gcloud.ts';
+
+/**
+ * Asking for what the config does not say yet.
+ *
+ * `deploy` used to refuse a target with no deployment block and tell the
+ * operator which four keys to go and write. That is a correct error message and
+ * a bad first run: the command knows what it needs, it can offer a sensible
+ * value for every one of them, and the answers belong in the file rather than in
+ * a flag the operator has to remember next time.
+ *
+ * It then refused a target that did not exist at all, which was the same mistake
+ * one level up. `credentials`, `storage` and `vault` have exactly one workable
+ * answer each on Cloud Run — Secret Manager, a bucket, and the sealed document
+ * beside the credentials — so a hand-written block could only ever be a
+ * transcription, and a wrong transcription fails somewhere unhelpful. The
+ * `filesystem` adapter in particular *appears* to work up here and loses
+ * everything on the next instance recycle.
+ *
+ * Every default is something already true rather than something invented — the
+ * project `gcloud` is pointed at, the profile's own name — so the common case is
+ * a handful of presses of return.
+ */
+
+const DEFAULT_REGION = 'europe-west1';
+
+/**
+ * Five random letters, for the two namespaces that are global to all of Google.
+ *
+ * A project id and a bucket name are both unique across every Google Cloud
+ * customer, so a memorable name is a name somebody already has. Google's own
+ * console does the same thing for the same reason.
+ *
+ * Letters rather than digits so the result is still pronounceable, and drawn
+ * from `crypto` rather than `Math.random` — not because a guessable bucket name
+ * is an vulnerability on its own, but because these names end up published in a
+ * URL and an unseeded PRNG that repeats across two machines produces a collision
+ * that looks like a permissions bug.
+ */
+function randomSuffix(length = 5): string {
+  const alphabet = 'abcdefghijklmnopqrstuvwxyz';
+  const bytes = crypto.getRandomValues(new Uint8Array(length));
+
+  return [...bytes].map((byte) => alphabet[byte % alphabet.length]).join('');
+}
+
+/**
+ * The globally-unique name this deploy proposes for itself.
+ *
+ * One suffix, one name, used for **both** the project and the bucket — they are
+ * separate namespaces, so the same string is free in one when it is free in the
+ * other, and a deployment whose project and bucket are called the same thing is
+ * one you can find either way round from either console.
+ *
+ * Generated exactly once. Every later deploy reads the name back out of the
+ * profile, because the survey only runs for what the config does not say — a
+ * second suffix would name a second empty project beside the one holding
+ * everything.
+ *
+ * Sixteen characters, inside the project id limit of 30 and the bucket limit of
+ * 63, with no profile name in it: the profile is in the *service* name, which is
+ * the thing that has to differ when one project holds two of these.
+ */
+export function proposedName(suffix = randomSuffix()): string {
+  return `lanes-link-${suffix}`;
+}
+
+/**
+ * What the service is called when nobody says.
+ *
+ * It used to be the bare profile name — `personal`, in a project that may hold
+ * a dozen unrelated services, saying nothing about what it is or who put it
+ * there. `mcp` is the useful half: what this serves is an MCP endpoint, and that
+ * is what someone finds it looking for months later.
+ *
+ * The profile stays in the middle because one workspace can deploy several, and
+ * two profiles deploying to one project must not collide on a name.
+ */
+export function defaultServiceName(profile: string): string {
+  return `lanes-link-${profile}-mcp`;
+}
+
+/**
+ * The local part of the runtime service account, which has its own length rule.
+ *
+ * Service account ids are capped at 30 characters and a Cloud Run service name
+ * at 49, so a legal service name can derive an illegal account. That failure is
+ * one `gcloud iam service-accounts create` away from being silent — the step
+ * tolerates failure, so the deploy would carry on and roll a revision with no
+ * identity, and the first symptom would be it failing to read a secret.
+ */
+export function accountId(service: string): string {
+  const proposed = `${service}-run`;
+  if (proposed.length <= 30) return proposed;
+
+  // Trim the service, not the suffix: `-run` is what says which account this is.
+  return `${service.slice(0, 30 - '-run'.length).replace(/-+$/, '')}-run`;
+}
+
+export async function surveyCloudRun(input: SurveyInput): Promise<SurveyResult> {
+  const { current, profile, gated, adapters } = input;
+
+  heading('Where should this deploy?');
+  print(style.dim('  Answers are written into your profile, so this is asked once.'));
+  print('');
+
+  const project = await askProject(current.project);
+  const billing = await askBilling(project, current.billing_account);
+  const region = await askWithDefault('  Region', current.region ?? DEFAULT_REGION);
+  const service = await askWithDefault(
+    '  Cloud Run service name',
+    current.service ?? defaultServiceName(profile),
+  );
+
+  // Not asked. A revision needs an identity that can read the credential store,
+  // and the only interesting choice is *whether* it is dedicated — which it
+  // should always be, because the default compute account is shared with
+  // everything else in the project.
+  const serviceAccount =
+    current.service_account ?? `${accountId(service)}@${project}.iam.gserviceaccount.com`;
+
+  const access = await askAccess(current.access, gated);
+
+  const deploy: DeployConfig = {
+    platform: 'cloudrun',
+    project,
+    region,
+    service,
+    access,
+    service_account: serviceAccount,
+    ...(billing ? { billing_account: billing } : {}),
+  };
+
+  // Only the `deploy` block was missing: the adapters are already chosen, and
+  // re-asking would be offering to overwrite a working target.
+  if (!adapters) return { target: { deploy } as TargetConfig };
+
+  // The project's own name. One deployment, one string: the bucket namespace is
+  // separate from the project namespace, so a name free in one is free in the
+  // other, and finding either from the other needs nothing written down.
+  const bucket = await askBucket(project);
+
+  return {
+    target: {
+      credentials: { adapter: 'gcp-secret-manager', project },
+      storage: { adapter: 'gcs', bucket },
+      // Not optional, and not a preference. The default is `file`, which wants a
+      // filesystem path, and this workspace lives in a bucket — so a target
+      // without this line parses, deploys, and refuses to boot.
+      vault: { adapter: 'secret' },
+      deploy,
+    } as TargetConfig,
+    ...(access === 'public' && !gated && (await askRemoteClients()) ? { authorization: { mode: 'self' } } : {}),
+  };
+}
+
+/**
+ * Which project this deploys into, or the one it is about to create.
+ *
+ * The default used to be whatever `gcloud config` was pointed at, which is
+ * whichever project you last worked on — a value that is *always* set, rarely
+ * the right one, and wrong in the most expensive direction: accepting it deploys
+ * a personal gateway holding live refresh tokens into a project shared with
+ * something else. A fresh id proposes the opposite default, and typing an
+ * existing name over it is one line.
+ */
+async function askProject(current: string | undefined): Promise<string> {
+  const active = await waiting('reading your gcloud configuration', activeProject);
+
+  print('  A project of its own is the cleanest home for this — it holds the bucket,');
+  print(
+    style.dim(
+      '  the credential store, and nothing else. A new id is proposed; type the name\n' +
+        `  of an existing project to deploy into that instead${active ? ` (yours is ${active})` : ''}.`,
+    ),
+  );
+
+  return askWithDefault('  Google Cloud project', current ?? proposedName());
+}
+
+/**
+ * The billing account, asked only when there is a project to attach it to.
+ *
+ * Skipped entirely for a project that already exists — it is already billed, or
+ * it is not and that is not this command's business. Asking anyway would be a
+ * question with no consequence, which is the kind that teaches people to press
+ * return without reading.
+ *
+ * Refused rather than defaulted when there is no open account: a project created
+ * without billing enables no APIs, and every step after it fails with a message
+ * about the API rather than about billing.
+ */
+async function askBilling(project: string, current: string | undefined): Promise<string | undefined> {
+  if (current) return current;
+  if (await waiting(`checking whether ${project} exists`, () => projectExists(project))) {
+    return undefined;
+  }
+
+  const accounts = await waiting('listing your billing accounts', openBillingAccounts);
+  print('');
+  print(`  ${style.bold(project)} does not exist yet, so this deploy will create it.`);
+  print(style.dim('    A new project needs a billing account before any API can be enabled.'));
+
+  if (accounts.length === 0) {
+    throw new ConfigError(
+      `No open billing account found for this login, and "${project}" would have to be created.\n` +
+        '  Either name an existing project at the prompt, or set one up at\n' +
+        '  https://console.cloud.google.com/billing and re-run.',
+    );
+  }
+
+  for (const account of accounts) print(style.dim(`    ${account.id}  ${account.name}`));
+  return askWithDefault('  Billing account', accounts[0]!.id);
+}
+
+/**
+ * The one derived name that can collide with a stranger's.
+ *
+ * Bucket names are global across every Google Cloud customer, so this is asked
+ * rather than assumed even though the default is almost always free. `taken` is
+ * not a failure worth a stack trace three steps later.
+ */
+async function askBucket(project: string): Promise<string> {
+  print('');
+  print('  A bucket holds everything this endpoint remembers:');
+  print(
+    style.dim(
+      '    its config, its connection state, the audit log, memory, skills and\n' +
+        '    attachments. Named after the project by default; bucket names are\n' +
+        '    globally unique, so this one may be taken even when the project was not.',
+    ),
+  );
+  return askWithDefault('  Bucket', project);
+}
+
+/**
+ * Whether a remote client has to reach this, which is what `mode: self` decides.
+ *
+ * Asked, and asked here, because nothing else in a first run does. `access:
+ * public` opens the platform's door; it does not give a Claude or ChatGPT
+ * connector any way to *obtain* a token, and those clients have nowhere to paste
+ * a fixed one. Without `auth.authorization` the endpoint answers a connector's
+ * handshake with a 401 carrying nothing to act on, which reads as a broken
+ * server rather than a missing setting — so the previous default outcome of a
+ * first deploy was an endpoint that could not be added to a phone, and no
+ * message anywhere said why.
+ */
+async function askRemoteClients(): Promise<boolean> {
+  print('');
+  print('  Will you add this to Claude or ChatGPT, including on a phone?');
+  print(
+    style.dim(
+      '    yes  this endpoint issues its own tokens — the client registers itself,\n' +
+        '         a browser opens on its approval page, you paste the token once.\n' +
+        '         Nothing to set up: no OAuth client, no console, no redirect URI.\n' +
+        '    no   the bearer token is the only way in, which is all a local\n' +
+        '         registration needs. Add it later under auth.authorization.',
+    ),
+  );
+  return confirm('  Issue tokens for remote clients?');
+}
+
+/**
+ * Which door the platform leaves open.
+ *
+ * Asked rather than assumed, and asked with the consequence attached, because
+ * the two answers fail in opposite directions and neither failure is legible
+ * from the outside: `iam` looks like a broken endpoint to every MCP client, and
+ * `public` on a profile with no gate of its own is an open endpoint that answers
+ * normally.
+ */
+async function askAccess(
+  current: DeployConfig['access'] | undefined,
+  gated: boolean,
+): Promise<DeployConfig['access']> {
+  const proposed = current ?? (gated ? 'public' : 'iam');
+
+  print('');
+  print('  Who may reach the service?');
+  print(
+    style.dim(
+      '    iam     the platform checks a Google identity token first. Nothing that\n' +
+        '            cannot mint one gets through — which includes every agent harness.\n' +
+        '    public  the platform lets the request in and this endpoint authenticates it.',
+    ),
+  );
+  if (gated) {
+    print(
+      style.dim(
+        '    This profile authenticates requests itself, so "public" is the working\n' +
+          '    choice — "iam" in front of it would lock out the clients it exists for.',
+      ),
+    );
+  }
+
+  const answer = (await askWithDefault('  Access', proposed)).toLowerCase();
+  return answer === 'public' ? 'public' : 'iam';
+}
+
+/**
+ * Ask, showing the default, and take it on an empty answer.
+ *
+ * Refuses an empty value with no default rather than writing one: an empty
+ * service name parses, reaches `gcloud`, and fails several minutes into a build.
+ */
+async function askWithDefault(question: string, fallback: string | null | undefined): Promise<string> {
+  const shown = fallback ? `${question} ${style.dim(`[${fallback}]`)}` : question;
+
+  for (;;) {
+    const answer = (await ask(shown)).trim();
+    if (answer) return answer;
+    if (fallback) return fallback;
+    print(style.dim('    Required.'));
+  }
+}

package/src/deployments/local/README.md

@@ -0,0 +1,12 @@
+# Local — the default target
+
+SQLite, an encrypted file, and a directory. No network, no account, no
+credential beyond the two encryption keys, and everything under one workspace
+root that a `cp -R` backs up.
+
+There is no `target.ts` here: the local branches of `../target.ts` are three
+lines each and inlining them keeps the whole mapping readable in one place. A
+deployment earns a folder when it has machinery of its own — `../gcp/` has a
+Dockerfile, a build config, and a rollout driver.
+
+What lives on disk, and where, is `#profile`'s `workspace.ts`.

package/src/deployments/prepare.ts

@@ -0,0 +1,257 @@
+import { credentialRefFor, ownClientRefsFor, rotatableCredentialRefsFor } from '#registry';
+import { listProfiles, loadProfileConfig, type Config, type TargetConfig } from '#profile';
+import { VAULT_DOCUMENT_REF, VAULT_KEY_REF, generateVaultKey, type SecretStore } from '#secrets';
+import { ok, print, style, warn } from '#cli/output.ts';
+import { buildRegistryWithWorkspace, ensureProfileToken } from '#cli/runtime.ts';
+
+/**
+ * Getting the target's credential store to the state a revision can boot from.
+ *
+ * This began as a refusal — list what is missing, name the command that stores
+ * each one, exit. That is a correct refusal and three round trips: the operator
+ * runs `deploy`, reads the list, runs `token rotate`, runs `secrets set`, runs
+ * `deploy` again. Two of those values the command can produce or ask for right
+ * here, and the third is genuinely somebody else's to create.
+ *
+ * What blocks versus what warns follows what the runtime does with each: without
+ * the profile token the endpoint refuses to start, and without the database URL
+ * it cannot open a database at all. A connection credential that is missing
+ * leaves that connection `unauthorized`, which is a documented state rather than
+ * an outage — so it is said out loud and not treated as a failure.
+ */
+
+export interface PrepareInput {
+  readonly config: Config;
+  readonly credentials: SecretStore;
+  readonly root: string;
+  readonly target: string;
+  /** Never prompt; report only. `--dry-run` must not write to a credential store. */
+  readonly readOnly: boolean;
+}
+
+export interface PrepareResult {
+  /** Refs still missing after any seeding, which a revision cannot start without. */
+  readonly blocking: readonly string[];
+  readonly warnings: readonly string[];
+}
+
+/**
+ * Every credential reference a *running* revision rewrites — what `provision`
+ * needs in order to grant `secretVersionAdder` on each one and nothing else.
+ *
+ * Kept apart from the connection loop below rather than derived from it, because
+ * the two answer different questions and diverge on purpose: that loop asks
+ * where a connection's credential lives, which a hand-placed `credential_ref`
+ * may decide, and this asks what gets written while serving, which the refresh
+ * path derives from the manifest and has never read config for. Sharing one list
+ * would silently pick one answer for both.
+ *
+ * **Scoped exactly as the upload is**, for the reason `repairSetupSurface`
+ * states and one more: a profile this deploy sends is a profile the endpoint may
+ * serve, and a connection whose secret nobody bound fails an hour after the
+ * revision reports healthy. The asymmetry decides it — an extra binding is a
+ * resource-level grant on a secret the operator already owns, and a missing one
+ * is a 403 in somebody's chat window.
+ *
+ * A profile that cannot be read is skipped rather than fatal, matching the
+ * repair: `deploy` validates the profile it resolved, and a broken sibling
+ * should not cost the rollout. It goes up either way, and if it is served at
+ * all it is served broken for reasons that have nothing to do with IAM.
+ *
+ * Called before `provision`, which is before any store is opened — so it reads
+ * config and manifests only, and touches no credential.
+ */
+export async function rotatableRefs(root: string, profile: string | undefined): Promise<string[]> {
+  const refs = new Set<string>();
+
+  for (const name of await listProfiles(root)) {
+    if (profile !== undefined && name !== profile) continue;
+
+    let config: Config;
+    try {
+      ({ config } = await loadProfileConfig(root, name));
+    } catch {
+      continue;
+    }
+
+    // Inside the loop because manifests are the profile's own (ADR-030): a
+    // connection in `work` naming a provider only `work` declares resolves to
+    // nothing against `personal`'s registry, and a missed ref here is a 403 an
+    // hour after the revision reports healthy.
+    const registry = await buildRegistryWithWorkspace(root, name);
+
+    for (const connection of config.connections) {
+      const manifest = registry.manifest(connection.provider);
+      for (const ref of rotatableCredentialRefsFor(connection, manifest)) refs.add(ref);
+    }
+  }
+
+  // Sorted, and a set: two Gmail connections share one dynamically registered
+  // client ref, and two profiles may name the same connection. A step list that
+  // repeated one would read as two different grants.
+  return [...refs].sort();
+}
+
+/**
+ * Every credential reference a running revision *reads*, so provision can bind
+ * `secretAccessor` on each one instead of on the whole project.
+ *
+ * The project-level grant this replaces was not an oversight — the adapter
+ * argued for it, on the grounds that the line worth defending is
+ * `secrets.create` — but it is broader than the revision ever needs, and the
+ * survey happily points a deploy at a project the operator already uses for
+ * other things. An SSRF or an RCE in the endpoint should reach this profile's
+ * own credentials, not every secret sharing a project with it.
+ *
+ * Feasible because the serving path only ever reads by explicit ref: `list()`
+ * is a CLI call, and `secretAccessor` never granted `secrets.list` anyway. So
+ * the set is knowable at deploy time, and it is the same walk `rotatableRefs`
+ * does — profiles, their connections, and the manifests behind them.
+ *
+ * Deliberately a superset, matching the asymmetry `rotatableRefs` states: an
+ * extra resource-level binding on a secret the operator already owns costs
+ * nothing, and a missing one is a 403 an hour after the revision reports
+ * healthy. Both `credentialRefFor` and `rotatableCredentialRefsFor` go in
+ * because the first honours a hand-placed `credential_ref` and the second is
+ * blind to it by design — the revision may read either.
+ *
+ * The same deploy-time bound the write side already lives with applies here: a
+ * connection authorised after a rollout is unreadable until the next one. That
+ * is not new, and `provision` is re-run by every deploy.
+ */
+export async function readableRefs(
+  root: string,
+  profile: string | undefined,
+  declared: TargetConfig | undefined,
+): Promise<string[]> {
+  const refs = new Set<string>();
+
+  if (declared?.vault?.adapter === 'secret') {
+    refs.add(VAULT_KEY_REF);
+    refs.add(declared.vault.ref ?? VAULT_DOCUMENT_REF);
+  } else if (declared?.vault?.adapter === 'blob') {
+    // Ciphertext lives in the bucket, but the key that opens it is still here.
+    refs.add(VAULT_KEY_REF);
+  }
+
+  for (const name of await listProfiles(root)) {
+    if (profile !== undefined && name !== profile) continue;
+
+    let config: Config;
+    try {
+      ({ config } = await loadProfileConfig(root, name));
+    } catch {
+      continue;
+    }
+
+    refs.add(config.auth.token_ref);
+    // The OIDC audience check reads this on every verify (`server/endpoint.ts`).
+    if (config.auth.authorization?.mode === 'oidc') {
+      refs.add(config.auth.authorization.client_id_ref);
+    }
+
+    // Per profile, for the reason `rotatableRefs` gives: a manifest is this
+    // profile's, so the registry that resolves its connections must be too.
+    const registry = await buildRegistryWithWorkspace(root, name);
+
+    for (const connection of config.connections) {
+      const manifest = registry.manifest(connection.provider);
+      const ref = credentialRefFor(connection, manifest);
+      if (ref) refs.add(ref);
+      for (const rotatable of rotatableCredentialRefsFor(connection, manifest)) refs.add(rotatable);
+      for (const client of ownClientRefsFor(manifest, config.oauth_apps)) refs.add(client);
+    }
+  }
+
+  return [...refs].sort();
+}
+
+export async function prepareSecrets(input: PrepareInput): Promise<PrepareResult> {
+  const { config, credentials, root, target, readOnly } = input;
+  const blocking: string[] = [];
+  const warnings: string[] = [];
+
+  await seedProfileToken({ config, credentials, readOnly, blocking });
+  await seedVaultKey({ declared: config.targets[target], credentials, readOnly });
+
+  // Connection credentials are written by `connect`, against a real account, in
+  // a browser. Nothing here can produce one, and a deploy that stopped for one
+  // would be refusing to roll a revision over a mailbox that has not been
+  // authorised yet — which is a thing you might reasonably want to do.
+  //
+  // The command is spelled out rather than described. This is the one manual
+  // step a deploy genuinely cannot take for you, so it should cost a paste
+  // rather than a trip to the docs to work out how the id is spelled.
+  const registry = await buildRegistryWithWorkspace(root, config.instance.profile);
+  for (const connection of config.connections) {
+    const ref = credentialRefFor(connection, registry.manifest(connection.provider));
+    if (!ref || (await credentials.has(ref))) continue;
+    warnings.push(
+      `${connection.provider}.${connection.id} is not authorised yet — no credential at "${ref}"\n` +
+        `    lanes link connect ${connection.provider} --target ${target} --id ${connection.id}`,
+    );
+  }
+
+  return { blocking, warnings };
+}
+
+/**
+ * The key that seals the vault document.
+ *
+ * Minted here for the same reason the profile token is: it is a random string
+ * this process generates correctly and nobody can usefully choose. It used to be
+ * three manual commands in `docs/detailed/deployment-cloudrun.md` — generate, store,
+ * mount — whose only failure mode was forgetting them and finding out when the
+ * first `vault.*` call failed against a revision that had booted healthy.
+ *
+ * Only for a target whose credential store can hold it. A `file` vault is a
+ * local run, where the environment variable is the operator's own business.
+ *
+ * Never regenerated. A second key does not fail — it decrypts nothing, and the
+ * document it cannot open is the one holding every password the owner put
+ * there.
+ */
+async function seedVaultKey(input: {
+  declared: TargetConfig | undefined;
+  credentials: SecretStore;
+  readOnly: boolean;
+}): Promise<void> {
+  const adapter = input.declared?.vault?.adapter;
+  if (adapter !== 'secret' && adapter !== 'blob') return;
+  if (input.readOnly || (await input.credentials.has(VAULT_KEY_REF))) return;
+
+  await input.credentials.set(VAULT_KEY_REF, generateVaultKey());
+  print(ok(`minted the vault key at "${VAULT_KEY_REF}" — the revision reads it from there`));
+}
+
+/**
+ * The endpoint's own bearer token.
+ *
+ * Minted rather than demanded, and not even asked about: it is a random string
+ * this process generates correctly and the operator cannot usefully choose, so a
+ * prompt would be a question with one answer. `ensureProfileToken` is the same
+ * call `outputs` makes for a local target, which is what keeps "the token" one
+ * thing rather than a per-command notion.
+ *
+ * The deployed container deliberately will *not* do this — a token invented
+ * inside something that scales to zero is a token nobody can read back, and the
+ * endpoint would come up healthy while rejecting every agent.
+ */
+async function seedProfileToken(input: {
+  config: Config;
+  credentials: SecretStore;
+  readOnly: boolean;
+  blocking: string[];
+}): Promise<void> {
+  const ref = input.config.auth.token_ref;
+  if (await input.credentials.has(ref)) return;
+
+  if (input.readOnly) {
+    input.blocking.push(`the endpoint bearer token — nothing at "${ref}"`);
+    return;
+  }
+
+  const { created } = await ensureProfileToken(input.credentials, ref);
+  if (created) print(ok(`minted an endpoint token at "${ref}" — read it with: lanes link token show`));
+}
+