@lanes-sh/link 0.1.0

package/src/server/container.ts

@@ -0,0 +1,96 @@
+#!/usr/bin/env bun
+import { startEndpoint } from './endpoint.ts';
+import { streamLogger } from './logging.ts';
+
+/**
+ * The container entrypoint — `src/deployments/gcp/Dockerfile` runs this.
+ *
+ * Not `lanes link start`. That command is a terminal UI: it announces the
+ * resolved profile with colour, mints a token if none exists, and expects
+ * someone to be reading. A container needs the opposite of each — plain lines
+ * on stdout for Cloud Logging, a refusal rather than an invention when the
+ * token is missing, and a clean SIGTERM. Everything between those two is the
+ * same `startEndpoint`, which is the point: the deployed instance runs the
+ * same bootstrap as the local one, against a different adapter set.
+ *
+ * What the environment has to provide:
+ *
+ *   LANES_LINK_HOME     the workspace root, as `gs://<bucket>`. Set by
+ *                      `lanes link deploy` at rollout rather than baked into
+ *                      the image, because the bucket is the operator's and the
+ *                      image is meant to serve any workspace (ADR-023).
+ *                      Unset, `resolveWorkspaceRoot` falls back to
+ *                      `~/.lanes-link`, which in a container is a directory
+ *                      nobody wrote — so the endpoint refuses rather than
+ *                      serving an empty workspace.
+ *   LANES_LINK_TARGET   which target's adapters to open. Baked to `cloud`.
+ *   LANES_LINK_PROFILE  optional; the workspace default otherwise.
+ *   PORT               injected by Cloud Run. 8080 is its default.
+ */
+
+const env = process.env;
+
+// Cloud Run routes to whatever the container listens on at $PORT, and health
+// checks fail against a process bound to loopback.
+const port = Number(env['PORT'] ?? 8080);
+if (!Number.isInteger(port) || port < 1 || port > 65535) {
+  // Refuse rather than fall back to a default: a container listening somewhere
+  // other than where its platform routes is a startup probe that never passes,
+  // reported as a health failure with nothing to explain it.
+  process.stderr.write(`PORT is ${JSON.stringify(env['PORT'])}, which is not a port number.\n`);
+  process.exit(1);
+}
+const host = env['LANES_LINK_HOST'] ?? '0.0.0.0';
+
+const log = (message: string): void => {
+  process.stdout.write(`${new Date().toISOString()} ${message}\n`);
+};
+
+try {
+  const endpoint = await startEndpoint({
+    flags: {
+      ...(env['LANES_LINK_PROFILE'] ? { profile: env['LANES_LINK_PROFILE'] } : {}),
+      ...(env['LANES_LINK_TARGET'] ? { target: env['LANES_LINK_TARGET'] } : {}),
+      quiet: true,
+    },
+    port,
+    host,
+    // A deployed instance never mints its own token: see `endpoint.ts`.
+    mintToken: false,
+    // Stdout is where Cloud Run collects logs, and a rejected credential on a
+    // public URL is the event this exists for.
+    log: streamLogger((line) => process.stdout.write(`${line}\n`)),
+    reporter: {
+      reconciled({ profile, plan }) {
+        // Reconcile output is the record of what a deploy changed, and it is
+        // the only place that record exists — the config it applied is baked
+        // into an image that will be replaced.
+        log(`reconciled ${profile}\n${plan}`);
+      },
+      tokenMinted() {},
+    },
+  });
+
+  log(`serving ${endpoint.url}`);
+  log(`profiles: ${endpoint.profiles.join(', ')}`);
+
+  // Cloud Run sends SIGTERM and then waits. Closing the runtimes is what writes
+  // each audit run's close marker, which is the difference between a run that
+  // ended and one whose tail was cut off — see ADR-020.
+  const shutdown = async (): Promise<void> => {
+    log('shutting down');
+    await endpoint.stop();
+    process.exit(0);
+  };
+
+  process.on('SIGTERM', () => void shutdown());
+  process.on('SIGINT', () => void shutdown());
+
+  await new Promise(() => {});
+} catch (error) {
+  // Exit non-zero so the revision fails to go healthy and Cloud Run keeps
+  // serving the previous one, rather than rolling out an endpoint that answers
+  // every request with an error.
+  process.stderr.write(`${(error as Error).message}\n`);
+  process.exit(1);
+}

package/src/server/edge.ts

@@ -0,0 +1,53 @@
+import { RateLimiter } from '#policy';
+
+/**
+ * A ceiling on failed authentication.
+ *
+ * Every credential that does not match the cached one costs a re-read of the
+ * credential store — a decrypt locally, a network call on a deployed instance.
+ * That re-read is what makes a rotated-in token work on its first call, and it
+ * is also a way to make the endpoint do expensive work on behalf of a caller
+ * holding no credential at all. This bounds it.
+ *
+ * Not a security boundary, and `#policy`'s own note says so: 256 bits behind
+ * `llk_` is what makes guessing hopeless. This is about cost, and about giving
+ * a sustained probe a shape in the log rather than an unbroken run of 401s.
+ */
+export const FAILED_AUTH_PER_MINUTE = 30;
+
+/**
+ * Who an attempt is counted against.
+ *
+ * `x-forwarded-for`'s first hop is the client as the platform's front door saw
+ * it, which is the only address that means anything on Cloud Run — the socket
+ * peer there is Google's frontend, identical for every caller. It is trivially
+ * spoofable by anyone talking to the endpoint directly, which is why the
+ * fallback is a single shared bucket rather than something that looks
+ * per-caller and is not: a loopback endpoint has one caller, and an attacker
+ * who can already reach it can read the config file holding the token anyway.
+ */
+export function callerKey(request: Request): string {
+  return request.headers.get('x-forwarded-for')?.split(',')[0]?.trim() || 'direct';
+}
+
+/** Refused for rate rather than for credential — deliberately a different status. */
+export function tooManyAttempts(retryAfterMs: number): Response {
+  return new Response(
+    JSON.stringify({
+      error: 'too_many_requests',
+      hint: 'Too many failed authentication attempts. Wait, then retry.',
+    }),
+    {
+      status: 429,
+      headers: {
+        'content-type': 'application/json',
+        'retry-after': String(Math.max(1, Math.ceil(retryAfterMs / 1000))),
+      },
+    },
+  );
+}
+
+/** One bucket set per endpoint. Idle callers are dropped so keys do not accumulate. */
+export function failedAuthLimiter(): RateLimiter {
+  return new RateLimiter();
+}

package/src/server/endpoint.ts

@@ -0,0 +1,352 @@
+import { MCP_PATH, serve } from './index.ts';
+import { serveOverStdio } from './stdio.ts';
+import { Generations, type OpenedWorkspace } from './generations.ts';
+import type { AuthorizationSurface } from './oauth.ts';
+import type { ProfileRuntime } from './mcp/index.ts';
+import {
+  AuthenticatorChain,
+  IssuedTokenAuthenticator,
+  OAuthServer,
+  OAuthStore,
+  OidcAuthenticator,
+  OidcVerifier,
+  tokensMatch,
+  type Authenticator,
+} from '#auth';
+import type { Logger } from '#connectivity';
+import { silentLogger } from './logging.ts';
+import { listProfiles } from '#profile';
+import {
+  applyReconcile,
+  formatPlan,
+  planIsNoop,
+  planReconcile,
+  toPolicyDocument,
+} from '#registry';
+import { ensureProfileToken, openRuntime, type GlobalFlags, type Runtime } from '#cli/runtime.ts';
+
+/**
+ * Bringing the endpoint up: open a runtime per profile, reconcile, and serve.
+ *
+ * This is the bootstrap, and it exists as its own function because there are
+ * now two callers with genuinely different needs. `lanes link start` runs it on
+ * an operator's machine, prints to a terminal, and mints a profile token when
+ * none exists. The container entrypoint runs it under Cloud Run, logs to
+ * stdout, and must *not* mint anything — a token invented inside a container
+ * that scales to zero is one nobody can read back, so the endpoint would come
+ * up healthy and reject every agent.
+ *
+ * The alternative was for the image to shell out to `lanes link start`, which
+ * would have made the container's behaviour a side effect of a CLI command's
+ * presentation code. Everything below the reporter is identical on both paths,
+ * which is what makes "the same config with only the target switched" true.
+ */
+
+export interface EndpointReporter {
+  /** A profile whose runtime state differed from its config, and what was applied. */
+  reconciled(input: { profile: string; plan: string; ofMany: boolean }): void;
+  /** No profile token existed and one was minted. */
+  tokenMinted(minted: { target: string }): void;
+}
+
+const SILENT: EndpointReporter = { reconciled() {}, tokenMinted() {} };
+
+export interface EndpointOptions {
+  readonly flags: GlobalFlags;
+  readonly port?: number | undefined;
+  readonly host?: string | undefined;
+  /** Serve just the resolved profile, rather than every profile in the workspace. */
+  readonly only?: boolean | undefined;
+  /**
+   * Mint a profile token when the store has none. True for `lanes link start`,
+   * false in a container — see the note above.
+   */
+  readonly mintToken?: boolean | undefined;
+  readonly reporter?: EndpointReporter | undefined;
+  /** Operational events. Silent when absent, which is what the tests want. */
+  readonly log?: Logger | undefined;
+}
+
+export interface RunningEndpoint {
+  readonly url: string;
+  readonly profiles: readonly string[];
+  stop(): Promise<void>;
+}
+
+/**
+ * Every profile this workspace serves, opened and reconciled.
+ *
+ * Shared by both transports because it is the whole of what "bring the
+ * workspace up" means — which profiles, in what state. What differs after it is
+ * only how they are reached: a port and a token, or a pipe.
+ */
+async function openReconciled(options: {
+  readonly flags: GlobalFlags;
+  readonly only?: boolean | undefined;
+  readonly reporter?: EndpointReporter | undefined;
+}): Promise<{ primary: Runtime; runtimes: Map<string, Runtime> }> {
+  const reporter = options.reporter ?? SILENT;
+  const primary = await openRuntime(options.flags);
+
+  // One endpoint, every profile. The alternative — a port each — meant an agent
+  // registering N servers to reach N profiles, and the ports leaked a detail
+  // nobody wants to think about. What it costs is that a single token now
+  // reaches every profile and the caller names which, so the boundary between
+  // them is a policy decision per call rather than a separate URL.
+  const names = options.only
+    ? [primary.resolution.profile]
+    : await listProfiles(primary.resolution.workspaceRoot);
+
+  const runtimes = new Map<string, Runtime>();
+  runtimes.set(primary.resolution.profile, primary);
+
+  try {
+    for (const name of names) {
+      if (runtimes.has(name)) continue;
+      runtimes.set(name, await openRuntime({ ...options.flags, profile: name }));
+    }
+
+    for (const [name, runtime] of runtimes) {
+      const result = await planReconcile(
+        runtime.config,
+        runtime.state,
+        runtime.credentials,
+        runtime.manifestFor,
+      );
+      if (!planIsNoop(result)) {
+        reporter.reconciled({
+          profile: name,
+          plan: formatPlan(result),
+          ofMany: runtimes.size > 1,
+        });
+        await applyReconcile(runtime.config, runtime.state, result);
+      }
+    }
+
+    return { primary, runtimes };
+  } catch (error) {
+    // A runtime opened before the failure holds a state handle, and in a
+    // container a leaked pool keeps connections checked out of the pooler
+    // while the process crash-loops.
+    await closeAll(runtimes);
+    throw error;
+  }
+}
+
+/** What the transports need from a runtime, which is less than a runtime. */
+function profileRuntimes(runtimes: ReadonlyMap<string, Runtime>): Map<string, ProfileRuntime> {
+  return new Map(
+    [...runtimes].map(([name, runtime]) => [
+      name,
+      {
+        config: runtime.config,
+        registry: runtime.registry,
+        dispatcher: runtime.dispatcher,
+        policy: toPolicyDocument(runtime.config),
+        // So a skill written since this endpoint started — by an agent
+        // through `skills.manage.write`, or by `lanes link skills add` in another
+        // terminal — is a prompt without a restart (ADR-014).
+        refreshSkills: runtime.refreshSkills,
+      },
+    ]),
+  );
+}
+
+function closeAll(runtimes: ReadonlyMap<string, Runtime>): Promise<unknown> {
+  return Promise.all([...runtimes.values()].map((runtime) => runtime.close()));
+}
+
+/**
+ * The remote-client gate, if this profile declares one.
+ *
+ * Endpoint-scoped rather than per profile, like the bearer token and for the
+ * same reason (ADR-009): one URL serves every profile in the workspace, so
+ * there is one place a client authorises and one set of tokens.
+ *
+ * Returns null when `auth.authorization` is absent, and everything downstream
+ * treats null as "exactly as before" — no metadata published, no pointer on the
+ * `401`, one authenticator instead of a chain.
+ */
+async function openAuthorization(
+  primary: Runtime,
+): Promise<{ surface: AuthorizationSurface; authenticator: Authenticator } | null> {
+  const declared = primary.config.auth.authorization;
+  if (!declared) return null;
+
+  const profile = primary.resolution.profile;
+
+  if (declared.mode === 'oidc') {
+    const audience = await primary.credentials.get(declared.client_id_ref);
+    if (!audience) {
+      // Refuse rather than verify without an audience. A verifier that cannot
+      // check who a token was issued for accepts every token the issuer minted
+      // for anything, which is the failure this mode exists to prevent.
+      throw new Error(
+        `auth.authorization.client_id_ref names "${declared.client_id_ref}", which is not in ` +
+          `this target's credential store. Store it with: lanes link secrets set ${declared.client_id_ref}`,
+      );
+    }
+
+    const verifier = new OidcVerifier({
+      issuer: declared.issuer,
+      audience,
+      allowedSubjects: declared.allowed_subjects,
+      ...(declared.introspection_endpoint
+        ? { introspectionEndpoint: declared.introspection_endpoint }
+        : {}),
+    });
+
+    return {
+      // The issuer is somebody else's origin, so it is a constant here rather
+      // than derived from the request.
+      surface: { issuer: () => declared.issuer, mcpPath: MCP_PATH, target: primary.target },
+      authenticator: new OidcAuthenticator(verifier, profile),
+    };
+  }
+
+  const store = new OAuthStore(primary.state.kv);
+  const expected = primary.config.auth.token_ref;
+
+  const server = new OAuthServer({
+    store,
+    accessTokenTtlMs: declared.access_token_ttl_minutes * 60_000,
+    // Approval is proof of holding the endpoint token, compared the same way
+    // the request path compares it. There is one person behind this endpoint
+    // and they already have exactly one credential; a second one invented for
+    // the consent screen would be a password to lose.
+    verifyOwner: async (presented) => {
+      const token = await primary.credentials.get(expected);
+      return token !== null && tokensMatch(presented, token);
+    },
+  });
+
+  return {
+    surface: { server, issuer: (origin) => origin, mcpPath: MCP_PATH, target: primary.target },
+    authenticator: new IssuedTokenAuthenticator(store, profile),
+  };
+}
+
+export async function startEndpoint(options: EndpointOptions): Promise<RunningEndpoint> {
+  const reporter = options.reporter ?? SILENT;
+  const { primary, runtimes } = await openReconciled(options);
+
+  try {
+    if (options.mintToken) {
+      const { created } = await ensureProfileToken(
+        primary.credentials,
+        primary.config.auth.token_ref,
+      );
+      if (created) reporter.tokenMinted({ target: primary.target });
+    } else {
+      // Deployed, the token is written by the operator's CLI into the target's
+      // credential store and read back here. Refusing to start beats serving an
+      // endpoint whose token nobody holds.
+      const token = await primary.credentials.get(primary.config.auth.token_ref);
+      if (!token) {
+        throw new Error(
+          `No profile token at "${primary.config.auth.token_ref}" in this target's credential store. ` +
+            'A deployed instance never mints its own — run `lanes link token rotate --target <target>` ' +
+            'from your machine, or `lanes link secrets push --from local --to cloud`, then redeploy.',
+        );
+      }
+    }
+
+    const gate = await openAuthorization(primary);
+
+    // The authenticator and the authorization gate are built once, from the
+    // runtime this endpoint booted with, and are deliberately not part of what
+    // a reload replaces (ADR-029). Retiring that generation stays safe for them
+    // because `Runtime.close()` ends connector sessions and the audit log — it
+    // does not close the credential store or the state handle these hold.
+    const generations = new Generations(
+      { profiles: profileRuntimes(runtimes), close: () => closeAll(runtimes).then(() => {}) },
+      async (): Promise<OpenedWorkspace> => {
+        const reopened = await openReconciled(options);
+        return {
+          profiles: profileRuntimes(reopened.runtimes),
+          close: () => closeAll(reopened.runtimes).then(() => {}),
+        };
+      },
+      { primary: primary.resolution.profile, log: { debug() {}, info() {}, warn() {}, error() {} } },
+    );
+
+    const server = serve({
+      generations,
+      primary: primary.resolution.profile,
+      authenticator: gate
+        ? new AuthenticatorChain([primary.authenticator, gate.authenticator])
+        : primary.authenticator,
+      log: options.log ?? silentLogger(),
+      ...(gate ? { authorization: gate.surface } : {}),
+      ...(options.port !== undefined ? { port: options.port } : {}),
+      ...(options.host !== undefined ? { host: options.host } : {}),
+    });
+
+    return {
+      url: server.url,
+      profiles: [...runtimes.keys()],
+      // `server.stop()` closes the request handler, which closes whichever
+      // generation is current — and a generation owns the runtimes it opened.
+      // Closing `runtimes` here too would reach past a reload and close a set
+      // nothing is serving from any more.
+      stop: () => server.stop(),
+    };
+  } catch (error) {
+    await closeAll(runtimes);
+    throw error;
+  }
+}
+
+export interface StdioEndpointOptions {
+  readonly flags: GlobalFlags;
+  /** Serve just the resolved profile, rather than every profile in the workspace. */
+  readonly only?: boolean | undefined;
+  /**
+   * Where reconcile output goes.
+   *
+   * Not the terminal, on this path: stdout carries JSON-RPC, and a single line
+   * written to it corrupts the stream for the client. The caller reports to
+   * stderr or not at all.
+   */
+  readonly reporter?: EndpointReporter | undefined;
+  readonly log?: Logger | undefined;
+  readonly clientLabel?: string | undefined;
+}
+
+export interface RunningStdioEndpoint {
+  readonly profiles: readonly string[];
+  stop(): Promise<void>;
+}
+
+/**
+ * The same workspace, served over this process's stdin and stdout.
+ *
+ * No port, no token, no reachability question — see `stdio.ts` for why the pipe
+ * replaces the authenticator. Used by clients that cannot be handed a URL at
+ * all, which is most desktop applications.
+ */
+export async function startStdioEndpoint(
+  options: StdioEndpointOptions,
+): Promise<RunningStdioEndpoint> {
+  const { primary, runtimes } = await openReconciled(options);
+
+  try {
+    const surface = serveOverStdio({
+      profiles: profileRuntimes(runtimes),
+      primary: primary.resolution.profile,
+      log: options.log ?? silentLogger(),
+      ...(options.clientLabel ? { clientLabel: options.clientLabel } : {}),
+    });
+
+    return {
+      profiles: [...runtimes.keys()],
+      async stop() {
+        await surface.close();
+        await closeAll(runtimes);
+      },
+    };
+  } catch (error) {
+    await closeAll(runtimes);
+    throw error;
+  }
+}