@lanes-sh/link 0.2.1 → 0.3.0

package/src/server/generations.ts

@@ -1,5 +1,5 @@
 import type { Logger } from '#connectivity';
-import { clearUpstreamTokens } from '#connectivity/auth/index.ts';
+import { clearMintedTokens, clearUpstreamTokens } from '#connectivity/auth/index.ts';
 import type { ProfileRuntime } from '#server/mcp';
 import { Generation } from './generation.ts';
 
@@ -52,6 +52,8 @@ export interface GenerationDeps {
   readonly primary: string;
   readonly log: Logger;
   readonly version?: string | undefined;
+  /** Whether an authorization surface is published. See `BuildServerOptions`. */
+  readonly remoteClients?: boolean | undefined;
 }
 
 /** What a reload did, as the `/reload` route reports it. */
@@ -182,12 +184,21 @@ export class Generations {
     // cloud target is a network write, so this is reachable rather than
     // theoretical.
     try {
-      // Module-global and keyed per connection, so it survives a reload that
+      // Module-global and keyed per connection, so they survive a reload that
       // replaced everything else. Re-connecting `<provider>.<id>` to a different
       // account would otherwise serve the previous account's access token until
       // it expired — up to an hour after the config said otherwise. Unchanged
       // connections pay one refresh.
+      //
+      // Both caches, because a connection authenticates one way at a time and
+      // re-connecting is how it changes: the route is settled by what `connect`
+      // last stored, so a reload that cleared only the authorization-code cache
+      // would keep serving a token minted from a key for a connection that no
+      // longer authenticates with one — and, worse, keep acting as the
+      // previously impersonated user, since the minted cache is keyed by
+      // connection with no subject in it.
       clearUpstreamTokens();
+      clearMintedTokens();
 
       // After the swap: a request arriving during the retire already gets the
       // new generation, and this only waits on requests that started before it.

package/src/server/harness.ts

@@ -86,6 +86,14 @@ export { parseConfig } from '#profile';
 export interface HarnessOptions {
   profile: string;
   log?: Logger;
+  /**
+   * The clock the authorization server and its store share.
+   *
+   * Shared deliberately: a tombstone's `consumedAt` is written by the store and
+   * compared by the server, so two clocks would make the reuse interval
+   * untestable in the one direction that matters. Absent means `Date.now`.
+   */
+  now?: () => number;
   port: number;
   policy: string;
   token?: string;
@@ -113,6 +121,8 @@ export interface HarnessOptions {
    * serving the old generation" case is reached; absent means nothing new.
    */
   reopen?: () => Promise<ReadonlyMap<string, ProfileRuntime>>;
+  /** Serve `/dashboard`, as `lanes link start` does and a container never does. */
+  dashboard?: boolean;
 }
 
 /**
@@ -173,6 +183,10 @@ export function wireProfiles(options: HarnessOptions): WiredProfiles {
       dispatcher,
       policy,
       ...(options.refreshSkills ? { refreshSkills: () => options.refreshSkills!(registry) } : {}),
+      // As `profileRuntimes` supplies them for real. A harness that claims to
+      // be the real wiring and omits a field leaves that field untested.
+      target: 'local',
+      connections: () => state.connections.list(),
     }),
   );
 
@@ -218,13 +232,17 @@ export function startHarness(options: HarnessOptions): Harness {
   // The real wiring from `endpoint.ts`, not a stand-in: the flow under test is
   // the one a connector drives over HTTP, and a fake authorization server would
   // demonstrate that the fake works.
-  const store = options.authorization ? new OAuthStore(state.kv) : null;
+  const log = options.log ?? silentLogger();
+
+  const store = options.authorization ? new OAuthStore(state.kv, options.now) : null;
   const gate = store
     ? {
         surface: {
           server: new OAuthServer({
             store,
             accessTokenTtlMs: 3_600_000,
+            log,
+            ...(options.now ? { now: options.now } : {}),
             verifyOwner: (presented) => Promise.resolve(tokensMatch(presented, token)),
           }),
           issuer: (origin: string) => origin,
@@ -235,8 +253,6 @@ export function startHarness(options: HarnessOptions): Harness {
       }
     : null;
 
-  const log = options.log ?? silentLogger();
-
   const nothing = () => Promise.resolve();
   const generations = new Generations(
     { profiles, close: nothing },
@@ -249,6 +265,7 @@ export function startHarness(options: HarnessOptions): Harness {
     primary: options.profile,
     authenticator: gate ? new AuthenticatorChain([bearer, gate.authenticator]) : bearer,
     ...(gate ? { authorization: gate.surface } : {}),
+    ...(options.dashboard ? { dashboard: true } : {}),
     log,
   });
 

package/src/server/index.ts

@@ -1,8 +1,15 @@
-import { challenge, type Authenticator } from '#auth';
+import { challenge, type Authenticator, type AuthOutcome, type ChallengeError } from '#auth';
 import type { Logger } from '#connectivity';
 import { capabilityIdForToolName } from '#server/mcp';
 import { ATTACHMENTS_PATH, stageAttachment } from './attachments.ts';
 import { allowedHostnamesFor, rebindingRefusal } from './rebinding.ts';
+import { ANY_ORIGIN, corsAware, type CorsPolicy } from './cors.ts';
+import {
+  DASHBOARD_PATH,
+  dashboardSessions,
+  handleDashboard,
+  servesDashboard,
+} from './dashboard.ts';
 import type { Generation } from './generation.ts';
 import type { Generations } from './generations.ts';
 import { callerKey, failedAuthLimiter, FAILED_AUTH_PER_MINUTE, tooManyAttempts } from './edge.ts';
@@ -49,8 +56,45 @@ export interface ServerOptions {
   readonly authorization?: AuthorizationSurface | undefined;
   /** Hostnames this endpoint answers to. See `./rebinding.ts`. */
   readonly allowedHostnames?: readonly string[] | undefined;
+  /**
+   * Serve the dashboard.
+   *
+   * Off unless asked for, and `serve()` withholds it anyway when the bind
+   * address is not loopback. `lanes link start` asks; `container.ts` does not.
+   * See `./dashboard.ts` for why a deployed instance has no browser-shaped door
+   * to put it behind.
+   */
+  readonly dashboard?: boolean | undefined;
 }
 
+type RefusalReason = Extract<AuthOutcome, { ok: false }>['reason'];
+
+/**
+ * What a caller should do about each refusal.
+ *
+ * `invalid` is the only one a client can act on by itself: it presented a
+ * credential and this endpoint did not accept it, which is what a refresh is
+ * for. RFC 6750 §3.1 has a name for that and clients branch on it; the others
+ * mean there is nothing to refresh, and §3 says to stay quiet rather than send
+ * a client after a token it does not hold. `malformed` says nothing either —
+ * `invalid_request` carries a SHOULD of a 400 status, and changing that path's
+ * status is a larger question than this answers.
+ */
+const CHALLENGE: Partial<Record<RefusalReason, ChallengeError>> = {
+  invalid: {
+    code: 'invalid_token',
+    description: 'The credential is expired, revoked, or not one this endpoint issued.',
+  },
+};
+
+/** The same four, for whoever is reading the body rather than the header. */
+const HINTS: Record<RefusalReason, string> = {
+  missing: 'Present the profile token as: Authorization: Bearer <token>',
+  malformed: 'Present the profile token as: Authorization: Bearer <token>',
+  invalid: 'Refresh the credential. Authorize again only if the refresh is refused too.',
+  not_configured: 'This profile has no token yet. Run: lanes link token rotate',
+};
+
 export const MCP_PATH = '/mcp';
 export const RELOAD_PATH = '/reload';
 
@@ -82,6 +126,7 @@ export interface RequestHandler {
 export function createRequestHandler(options: ServerOptions): RequestHandler {
   let probedAt = 0;
   const failedAuth = failedAuthLimiter();
+  const sessions = dashboardSessions();
 
   /**
    * Re-read the config because a call named a tool we do not serve.
@@ -141,6 +186,19 @@ export function createRequestHandler(options: ServerOptions): RequestHandler {
         });
       }
 
+      // Above the 404 gate and outside the bearer path below, because a
+      // top-level browser navigation carries no `Authorization` header — so it
+      // authenticates itself, against the same authenticator. Unset, this is
+      // never reached and `/dashboard` is a 404 like any other unknown path.
+      if (options.dashboard && url.pathname === DASHBOARD_PATH) {
+        return await handleDashboard(request, {
+          generations: options.generations,
+          authenticator: options.authenticator,
+          primary: options.primary,
+          sessions,
+        });
+      }
+
       if (
         url.pathname !== MCP_PATH &&
         url.pathname !== ATTACHMENTS_PATH &&
@@ -174,16 +232,13 @@ export function createRequestHandler(options: ServerOptions): RequestHandler {
           JSON.stringify({
             error: 'unauthorized',
             reason: outcome.reason,
-            hint:
-              outcome.reason === 'not_configured'
-                ? 'This profile has no token yet. Run: lanes link token rotate'
-                : 'Present the profile token as: Authorization: Bearer <token>',
+            hint: HINTS[outcome.reason],
           }),
           {
             status: 401,
             headers: {
               'content-type': 'application/json',
-              'www-authenticate': challenge(metadata),
+              'www-authenticate': challenge(metadata, CHALLENGE[outcome.reason]),
             },
           },
         );
@@ -310,17 +365,26 @@ export function serve(options: ServeOptions): RunningServer {
   const host = options.host ?? primary.config.instance.host;
   const port = options.port ?? primary.config.instance.port;
 
-  const allowedHostnames = options.allowedHostnames ?? allowedHostnamesFor(host, isLoopback(host));
+  const loopback = isLoopback(host);
+  const allowedHostnames = options.allowedHostnames ?? allowedHostnamesFor(host, loopback);
+
+  // Cross-origin access, and its absence, are decided here for the same reason
+  // `allowedHostnames` and `dashboard` are: they are all properties of what this
+  // is bound to. The two are mutually exclusive and the exclusion is the
+  // decision — see `./cors.ts`, and ADR-040.
+  const cors: CorsPolicy | undefined = loopback
+    ? undefined
+    : { allowedOrigins: primary.config.auth.allowed_origins ?? [ANY_ORIGIN] };
   const handler = createRequestHandler({
     ...options,
+    dashboard: servesDashboard(options.dashboard, loopback),
     ...(allowedHostnames ? { allowedHostnames } : {}),
   });
 
-  const server = Bun.serve({
-    hostname: host,
-    port,
-    fetch: (request: Request) => handler.fetch(request),
-  });
+  const route = (request: Request): Promise<Response> => handler.fetch(request);
+  const fetch = cors ? corsAware(route, [MCP_PATH, ATTACHMENTS_PATH], cors) : route;
+
+  const server = Bun.serve({ hostname: host, port, fetch });
 
   return {
     url: `http://${host}:${port}${MCP_PATH}`,

package/src/server/mcp/build.ts

@@ -46,7 +46,7 @@ export function buildMcpServer(options: BuildServerOptions): McpServer {
     // and `Implementation` would take it as an unknown extra and drop it from
     // `initialize` without complaining.
     {
-      instructions: serverInstructions(names, merged),
+      instructions: serverInstructions(names, merged, options.remoteClients),
       // Declared `false` because it is false, and the SDK defaults it to `true`.
       //
       // `listChanged` is a promise to send `notifications/tools/list_changed`

package/src/server/mcp/index.ts

@@ -28,6 +28,7 @@ export {
   visibleCapabilities,
   visibleToolCount,
   type BuildServerOptions,
+  type ConnectionState,
   type MergedCapability,
   type ProfileRuntime,
 } from './visibility.ts';

package/src/server/mcp/instructions.ts

@@ -34,10 +34,10 @@ import type { MergedCapability } from './visibility.ts';
 /**
  * The habits, in the order they are needed.
  *
- * Routing first because it gates every call; refusals last because that is when
- * an agent is most tempted to improvise. Second person, and specific about what
- * *not* to do — "ask which profile" is advice, "do not default to the first" is
- * a rule.
+ * Routing first because it gates every call; the two ways a call ends badly last,
+ * because that is when an agent is most tempted to improvise. Second person, and
+ * specific about what *not* to do — "ask which profile" is advice, "do not
+ * default to the first" is a rule.
  *
  * **Four of these are conditional**, and that is a correctness property rather
  * than a saving. This used to be one fixed string that told every client to
@@ -87,6 +87,23 @@ const SETUP = `**What is set up is answerable.** Before saying something cannot
 that an account must be added, call \`setup_overview\` — then \`setup_provider\`
 for the exact command. Running it is the owner's to do; inventing it is not.`;
 
+/**
+ * The one about not signing as the wrong person.
+ *
+ * It carries no names, and that is deliberate rather than thrift. Inlining the
+ * declaration would put a per-profile list into a string with a fixed ceiling —
+ * so the workspace with the most identities to keep straight is exactly the one
+ * whose list would be summarised away first. A pointer costs the same for one
+ * profile as for twenty, and `identity_list` has room to say when each applies,
+ * which is the half that actually prevents the mistake.
+ *
+ * Conditional like the rest: a profile that declares nothing has no `identity`
+ * connection, so the capability is unreachable and this paragraph is unspent.
+ */
+const IDENTITY = `**Identity is declared, not inferred.** Where a name, address or handle of the
+owner's is needed, call \`identity_list\`: a profile may hold several, each with a
+note on when it applies.`;
+
 const FILES = `**Files are named, not carried.** Where a tool takes attachments, give a path, an
 HTTPS URL, or an attachment already on another message; the endpoint reads the
 bytes. Never encode a file into a call — that is the thing this replaces.`;
@@ -95,12 +112,34 @@ const REFUSAL = `**A refused call is the permission system working**, not an obs
 around. Report what was refused and let the owner decide whether to widen it.
 Every call, including a refused one, is recorded.`;
 
+/**
+ * The one about not reaching here at all.
+ *
+ * Only for a client that authorises against this endpoint over the network —
+ * the one that cannot be handed the bundled skill, and the one whose connector
+ * decides on its own whether this endpoint is available. Observed: with the
+ * endpoint up and idle, a connector reported it unreachable without issuing a
+ * request at all, and the model read that as a fault, then re-derived an answer
+ * it had already given and re-composed an entry it had already written. Nothing
+ * here can prevent it, because nothing here is consulted — the call never
+ * arrives. Telling the model what the state means is the whole of what is left.
+ *
+ * Deliberately *not* "the endpoint is asleep". Usually it is not, and prose
+ * asserting a cause the model cannot check is how a wrong diagnosis gets
+ * repeated with confidence.
+ */
+const AVAILABILITY = `**A call may simply not go through.** This endpoint is one machine its owner
+runs, and a client can report it unreachable while it is up. That is ordinary —
+not a fault to diagnose, and not authorization you have lost. Say the call did
+not land, do not redo what already succeeded, and offer to retry.`;
+
 /** Which paragraph each owner-layer provider brings, when it is reachable. */
 const OWNER_HABITS: Record<string, string> = {
   memory: MEMORY,
   skills: SKILLS,
   vault: VAULT,
   setup: SETUP,
+  identity: IDENTITY,
 };
 
 /**
@@ -111,6 +150,20 @@ const OWNER_HABITS: Record<string, string> = {
  * it is the prompt to ask whether the paragraph belongs in the skill instead,
  * where it is loaded only when relevant.
  *
+ * It was raised once, from 2000, for `AVAILABILITY` — and that question was
+ * asked and answered the other way: the client that paragraph exists for is
+ * precisely the one that holds no skills directory, so the skill is not a place
+ * it can go. Only an endpoint serving remote clients spends it.
+ *
+ * Raised a second time, to 2500, for `IDENTITY`, and the same answer for the
+ * same reason: an agent signing as the wrong person has already sent the
+ * message, and a skill loaded only when relevant is not loaded at the moment
+ * that happens. The measured worst case — twenty profiles, twenty connections
+ * each, every owner provider reachable, remote clients — is 2474, so this is
+ * the measurement plus a little, not a round number picked first. Two things
+ * hold it there: the paragraph names no identity, and it is spent only by a
+ * profile that declared one.
+ *
  * Exported because the test asserted `2000` as a literal while the code
  * reserved room against a second, differently-derived number — so the two could
  * disagree, and did. There is no separate listing allowance any more: `spent`
@@ -118,7 +171,7 @@ const OWNER_HABITS: Record<string, string> = {
  * exactly the final length, because `join` adds the same two characters the
  * reduce already counted.
  */
-export const MAX_INSTRUCTIONS = 2000;
+export const MAX_INSTRUCTIONS = 2500;
 
 /** Which of the owner-layer providers this principal can actually reach. */
 function ownerProviders(merged: ReadonlyMap<string, MergedCapability>): string[] {
@@ -172,6 +225,9 @@ function connectionsByProfile(
 export function serverInstructions(
   profiles: readonly string[],
   merged: ReadonlyMap<string, MergedCapability>,
+  /** Whether a client authorises against this endpoint rather than being handed
+   * a token — see `AVAILABILITY`, the only paragraph that reads it. */
+  remoteClients = false,
 ): string {
   const reachable = connectionsByProfile(profiles, merged);
   const owner = ownerProviders(merged);
@@ -185,6 +241,7 @@ export function serverInstructions(
     ...owner.map((id) => OWNER_HABITS[id]).filter((habit): habit is string => habit !== undefined),
     FILES,
     REFUSAL,
+    ...(remoteClients ? [AVAILABILITY] : []),
   ];
 
   if (reachable.size === 0) {

package/src/server/mcp/visibility.ts

@@ -20,6 +20,20 @@ import { allowedConnections } from '#policy';
  * still a leak.
  */
 
+/**
+ * A connection's reconciled state, as much of it as a reader needs.
+ *
+ * Structural rather than the store's own `ConnectionRecord`: `server` does not
+ * import `stores` (`src/architecture.test.ts`), and what a surface that reports
+ * wants from a connection is its key and whether it is working — not the
+ * timestamps and credential expiry the repository keeps behind it.
+ */
+export interface ConnectionState {
+  readonly provider: string;
+  readonly id: string;
+  readonly status: string;
+}
+
 /** Everything one profile contributes to the endpoint. */
 export interface ProfileRuntime {
   readonly config: Config;
@@ -35,6 +49,25 @@ export interface ProfileRuntime {
    * how often to ask (ADR-014).
    */
   refreshSkills?(): Promise<void>;
+  /**
+   * Which target's adapters this profile was opened against.
+   *
+   * Not derivable from `config`: a target is *selected* per run, and the config
+   * only says which one is the default. Optional for the same reason the one
+   * below is — a runtime built to answer "what is visible" was never opened
+   * against anything.
+   */
+  readonly target?: string | undefined;
+  /**
+   * Reconciled connection state, for a surface that reports rather than
+   * dispatches.
+   *
+   * Optional exactly as `refreshSkills` is: only a served endpoint holds the
+   * state handle this reads through, and nothing on the dispatch path asks —
+   * a capability's visibility is decided by policy, not by whether the
+   * credential behind it currently works.
+   */
+  connections?(): Promise<readonly ConnectionState[]>;
 }
 
 export interface BuildServerOptions {
@@ -53,6 +86,15 @@ export interface BuildServerOptions {
   /** Self-reported by the client. Recorded in audit; never used to authorize. */
   readonly clientLabel?: string | undefined;
   readonly version?: string;
+  /**
+   * Whether this endpoint publishes an authorization surface, and therefore
+   * serves clients that arrived by URL alone.
+   *
+   * Read only by the instructions, which gain a paragraph for them. Absent over
+   * a pipe and on a loopback endpoint, where the client holds the skill and the
+   * transport cannot fail the way this describes.
+   */
+  readonly remoteClients?: boolean | undefined;
 }
 
 /** One profile as the map the builder wants. */

package/src/stores/blobs/route.ts

@@ -0,0 +1,123 @@
+import { containedKey, type BlobKey, type BlobMetadata, type BlobStore } from './index.ts';
+
+/**
+ * Sending part of a store's key space somewhere else.
+ *
+ * `scopeBlobStore` narrows a store to a namespace; this one splits a store
+ * between backends. A key under a route's prefix is served by that route's
+ * store — which is rooted *at* the prefix, so the prefix is stripped on the way
+ * in and put back on the way out — and every other key falls through to the
+ * base.
+ *
+ * It exists for one shape and it is worth naming it, because the alternative
+ * was much larger. A profile's memory is not addressed by a name anything
+ * declares: core scopes the profile's blob root to `<provider>/<connection>`
+ * inside `buildProviderContext`, and `lanes link memory` reaches the same bytes
+ * by calling the same two functions. So "put memory somewhere else" is not a
+ * question the provider, the dispatcher, or the CLI can be asked — it is a
+ * property of the store all three were handed. Routing the root means none of
+ * them changes, and none of them can disagree about where an entry went.
+ *
+ * A route's store is expected to enforce its own containment: it is a
+ * `BlobStore` like any other, and the base's rules do not travel across the
+ * boundary.
+ */
+
+export interface BlobRoute {
+  /**
+   * The key prefix this route claims, ending in `/`.
+   *
+   * Directory-shaped on purpose. A bare `memory` would also claim
+   * `memory-archive/x`, and a store that quietly swallows a neighbouring
+   * namespace is the kind of bug that surfaces as missing data rather than as
+   * an error.
+   */
+  readonly prefix: string;
+  /** A store rooted at `prefix`, so it never sees the prefix itself. */
+  readonly store: BlobStore;
+}
+
+export function routeBlobStore(base: BlobStore, routes: readonly BlobRoute[]): BlobStore {
+  if (routes.length === 0) return base;
+
+  const normalised = routes.map((route) => {
+    if (route.prefix.length === 0) {
+      throw new Error('A blob route prefix must not be empty — that is the base store.');
+    }
+    return { ...route, prefix: route.prefix.endsWith('/') ? route.prefix : `${route.prefix}/` };
+  });
+
+  /**
+   * Which store owns this key, and what it calls it.
+   *
+   * Contained first, so `memory/../elsewhere.md` is judged by where it lands
+   * rather than by how it is spelled — routing on the raw string would let a
+   * traversal pick its own backend, which is a weaker answer than either store
+   * gives on its own.
+   */
+  const routeFor = (key: BlobKey): { store: BlobStore; key: BlobKey } => {
+    const resolved = containedKey(key);
+    for (const route of normalised) {
+      if (resolved.startsWith(route.prefix)) {
+        return { store: route.store, key: resolved.slice(route.prefix.length) };
+      }
+    }
+    return { store: base, key };
+  };
+
+  return {
+    async put(key, data, options) {
+      const to = routeFor(key);
+      return to.store.put(to.key, data, options);
+    },
+
+    async get(key) {
+      const to = routeFor(key);
+      return to.store.get(to.key);
+    },
+
+    async has(key) {
+      const to = routeFor(key);
+      return to.store.has(to.key);
+    },
+
+    async delete(key) {
+      const to = routeFor(key);
+      return to.store.delete(to.key);
+    },
+
+    /**
+     * Merge the listings, with routed keys removed from the base's.
+     *
+     * Three cases, and the middle one is the one that is easy to miss: a
+     * listing prefix *inside* a route belongs wholly to that route, a listing
+     * prefix *containing* a route has to include everything that route holds,
+     * and a listing that touches neither is the base's alone. Sorted at the end
+     * because callers rely on it — `skillFingerprint` sorts its own output, but
+     * `loadProfileSkills` reads the listing in order.
+     */
+    async list(prefix) {
+      const asked = prefix ?? '';
+
+      for (const route of normalised) {
+        if (asked.startsWith(route.prefix)) {
+          const inner = await route.store.list(asked.slice(route.prefix.length));
+          return inner.map((entry) => ({ ...entry, key: `${route.prefix}${entry.key}` }));
+        }
+      }
+
+      const results: BlobMetadata[] = (await base.list(asked)).filter(
+        (entry) => !normalised.some((route) => entry.key.startsWith(route.prefix)),
+      );
+
+      for (const route of normalised) {
+        if (!route.prefix.startsWith(asked)) continue;
+        for (const entry of await route.store.list()) {
+          results.push({ ...entry, key: `${route.prefix}${entry.key}` });
+        }
+      }
+
+      return results.sort((a, b) => a.key.localeCompare(b.key));
+    },
+  };
+}