@lanes-sh/link 0.2.2 → 0.3.1

package/src/cli/oauth.ts

@@ -1,7 +1,20 @@
 import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
-import { completionPage } from './callback-page.ts';
 import { OAuthError } from './oauth-error.ts';
-import { directExchange, type ExchangeCode, type OAuthTokens } from './oauth-exchange.ts';
+import {
+  captureOAuthCallback,
+  connectedPage,
+  failedPage,
+  shutdown,
+  stateMatches,
+  withTimeout,
+  type CallbackCapture,
+} from './oauth-callback.ts';
+import {
+  directExchange,
+  type ExchangeCode,
+  type OAuthTokens,
+  type RefreshTokenPolicy,
+} from './oauth-exchange.ts';
 
 /**
  * The OAuth authorization-code exchange, run entirely from the CLI.
@@ -36,7 +49,23 @@ export interface OAuthFlowOptions {
    * state check, and the browser cannot drift apart between the two paths.
    */
   readonly exchange?: ExchangeCode;
+  /** What a response carrying no refresh token means for this vendor. */
+  readonly refreshToken: RefreshTokenPolicy;
   readonly authorizeParams?: Readonly<Record<string, string>>;
+  /**
+   * An HTTPS URL to name as the redirect, for a vendor that will take no other.
+   *
+   * Absent for every vendor that accepts a loopback callback, which is all of
+   * them but Slack — there the listener names itself and this is the whole of
+   * it. Present where the vendor's redirect must be HTTPS: the browser then
+   * lands on that URL, which bounces it down to the listener opened here, and
+   * the port it needs to bounce to travels in `state`.
+   *
+   * The listener is unchanged either way. It still binds loopback on a port the
+   * kernel picked, still serves exactly one callback, and still checks `state`
+   * on the way back. What changes is only the address the vendor is told.
+   */
+  readonly relayRedirect?: string;
   /** What the completion page names as connected. A provider's display name. */
   readonly connectionLabel?: string;
   /** How long to wait for the operator to finish in the browser. */
@@ -49,7 +78,12 @@ export interface OAuthFlowOptions {
 // Re-exported so the flow stays one import for its callers even though the
 // exchange half now lives next door.
 export { OAuthError };
-export type { ExchangeCode, OAuthTokens };
+export type { ExchangeCode, OAuthTokens, RefreshTokenPolicy };
+
+// Re-exported so a caller wanting a loopback callback still has one import to
+// reach for. Which file it lives in is this module's business, not theirs.
+export { captureOAuthCallback };
+export type { CallbackCapture };
 
 const base64url = (input: Buffer): string => input.toString('base64url');
 
@@ -60,13 +94,6 @@ export function createPkcePair(): { verifier: string; challenge: string } {
   return { verifier, challenge };
 }
 
-/** Compare the returned state in constant time — it is a CSRF defence. */
-function stateMatches(expected: string, received: string): boolean {
-  const a = createHash('sha256').update(expected).digest();
-  const b = createHash('sha256').update(received).digest();
-  return timingSafeEqual(a, b);
-}
-
 export function defaultOpenBrowser(url: string): void {
   const command =
     process.platform === 'darwin'
@@ -85,24 +112,6 @@ export function defaultOpenBrowser(url: string): void {
   }
 }
 
-/**
- * What the browser is left looking at, in the two shapes it comes in.
- *
- * The label is what the caller knows and this file cannot: which provider the
- * grant was for. Given one, the page names it under "Connected" the way the
- * invite page names the workspace; without one it says only that the flow
- * finished, which is what every path said before.
- */
-const connectedPage = (label?: string): Response =>
-  completionPage({
-    ...(label ? { label: 'Connected', heading: label } : { heading: 'Connected' }),
-    detail: 'You can close this tab and return to the terminal.',
-    ok: true,
-  });
-
-const failedPage = (detail: string): Response =>
-  completionPage({ heading: 'Authorization failed', detail, ok: false });
-
 /**
  * Run the flow and return the tokens.
  *
@@ -112,7 +121,6 @@ const failedPage = (detail: string): Response =>
  */
 export async function runOAuthFlow(options: OAuthFlowOptions): Promise<OAuthTokens> {
   const { verifier, challenge } = createPkcePair();
-  const state = base64url(randomBytes(24));
   const timeoutMs = options.timeoutMs ?? 5 * 60_000;
 
   let resolveCode: (code: string) => void;
@@ -124,7 +132,7 @@ export async function runOAuthFlow(options: OAuthFlowOptions): Promise<OAuthToke
 
   const server = Bun.serve({
     hostname: '127.0.0.1',
-    port: 0, // let the OS choose; Google's Desktop client type accepts any loopback port
+    port: 0, // let the OS choose; nothing outside this machine names this port
     fetch(request) {
       const url = new URL(request.url);
       if (url.pathname !== '/callback') return new Response('Not found', { status: 404 });
@@ -143,8 +151,9 @@ export async function runOAuthFlow(options: OAuthFlowOptions): Promise<OAuthToke
 
       const returnedState = url.searchParams.get('state');
       if (!returnedState || !stateMatches(state, returnedState)) {
-        // A mismatched state means this callback did not come from the request
-        // we started. Refuse it rather than redeeming whatever code it carries.
+        // A mismatched state means this callback did not come from the
+        // request we started. Refuse it rather than redeeming whatever code
+        // it carries.
         rejectCode(new OAuthError('State mismatch — ignoring an unexpected callback.'));
         return failedPage('Unexpected callback.');
       }
@@ -160,7 +169,25 @@ export async function runOAuthFlow(options: OAuthFlowOptions): Promise<OAuthToke
     },
   });
 
-  const redirectUri = `http://127.0.0.1:${server.port}/callback`;
+  // Where the vendor is told to send the browser. The relay bounces it back
+  // here; without one it comes here directly, which is every other provider.
+  const redirectUri = options.relayRedirect ?? `http://127.0.0.1:${server.port}/callback`;
+
+  /**
+   * The CSRF binding, and — behind a relay — the only way home.
+   *
+   * Built after the listener because half of it is the port the kernel just
+   * chose. The relay has nowhere else to learn that from: `state` is opaque to
+   * the vendor, round-trips untouched, and is already checked on the way back,
+   * so carrying the port in it costs no extra parameter and no state held
+   * anywhere. Without a relay it stays what it always was.
+   *
+   * Safe to declare after the handler that reads it: `Bun.serve` returns
+   * synchronously and nothing can be served until this frame yields.
+   */
+  const state = options.relayRedirect
+    ? `${base64url(randomBytes(24))}.${server.port}`
+    : base64url(randomBytes(24));
 
   try {
     const authorizeUrl = new URL(options.authorizeUrl);
@@ -196,159 +223,22 @@ export async function runOAuthFlow(options: OAuthFlowOptions): Promise<OAuthToke
   }
 }
 
-/**
- * Close the listener without cutting off the response in flight.
- *
- * Forcing the socket shut the instant the code is read leaves the operator
- * looking at a connection error on a flow that in fact succeeded. So: stop
- * gracefully, wait for the in-flight callback to drain, and force only if
- * graceful genuinely did not finish — a keep-alive connection must not be able
- * to hold the CLI open forever either.
- */
-async function shutdown(server: { stop(force?: boolean): Promise<void> }): Promise<void> {
-  let drained = false;
-  const graceful = server.stop().then(() => {
-    drained = true;
-  });
-
-  await withTimeout(graceful, 2_000).catch(() => {});
-  if (!drained) await server.stop(true);
-}
-
-/**
- * Race a promise against a deadline, and **clear the timer either way**.
- *
- * A bare `Promise.race` with `setTimeout` leaks: when the real promise wins,
- * the timer is still pending, and a pending timer keeps the event loop alive
- * for its full duration. With a five-minute OAuth deadline that turns a
- * finished `connect` into a terminal that prints "Next: lanes link start" and
- * then sits there for five minutes — which is exactly what it did.
- *
- * Rejects with `OAuthError(message)` if given one, otherwise resolves to
- * undefined at the deadline, which is what the shutdown path wants.
- */
-async function withTimeout<T>(promise: Promise<T>, ms: number, message?: string): Promise<T> {
-  let timer: ReturnType<typeof setTimeout> | undefined;
-
-  try {
-    return await Promise.race([
-      promise,
-      new Promise<T>((resolve, reject) => {
-        timer = setTimeout(
-          () => (message ? reject(new OAuthError(message)) : resolve(undefined as T)),
-          ms,
-        );
-      }),
-    ]);
-  } finally {
-    if (timer) clearTimeout(timer);
-  }
-}
-
 function defaultExchange(options: OAuthFlowOptions): ExchangeCode {
-  if (!options.tokenUrl || !options.clientSecret) {
+  // The secret is no longer part of this condition. A public client has none —
+  // its id ships in the manifest and PKCE is what protects the exchange — so
+  // requiring one here refused the shipped-client path before it sent anything.
+  if (!options.tokenUrl) {
     throw new OAuthError(
-      'runOAuthFlow needs either a tokenUrl and clientSecret to redeem the code with, or an exchange to redeem it through.',
+      'runOAuthFlow needs a tokenUrl to redeem the code at, or an exchange to redeem it through.',
     );
   }
   return directExchange({
     tokenUrl: options.tokenUrl,
     clientId: options.clientId,
-    clientSecret: options.clientSecret,
+    refreshToken: options.refreshToken,
+    ...(options.clientSecret ? { clientSecret: options.clientSecret } : {}),
     ...(options.fetch ? { fetch: options.fetch } : {}),
   });
 }
 
 
-/**
- * Capture exactly one OAuth callback on loopback.
- *
- * Split out from `runOAuthFlow` so the SDK can drive the protocol — discovery,
- * registration, PKCE, exchange — while we supply only the redirect target. The
- * listener exists for the duration of one consent and no longer.
- */
-export interface CallbackCapture {
-  readonly redirectUri: string;
-  /**
-   * The `state` this listener will accept, for the provider to put on the
-   * authorization URL. The SDK asks its provider for one and sends whatever it
-   * gets; nothing generates it for us.
-   */
-  readonly state: string;
-  wait(timeoutMs?: number): Promise<{ code: string; iss?: string }>;
-  close(): Promise<void>;
-}
-
-export function captureOAuthCallback(options: { label?: string } = {}): CallbackCapture {
-  const state = base64url(randomBytes(24));
-  let resolveCode: (value: { code: string; iss?: string }) => void;
-  let rejectCode: (error: Error) => void;
-
-  const received = new Promise<{ code: string; iss?: string }>((resolve, reject) => {
-    resolveCode = resolve;
-    rejectCode = reject;
-  });
-
-  const server = Bun.serve({
-    hostname: '127.0.0.1',
-    port: 0,
-    fetch(request) {
-      const url = new URL(request.url);
-      if (url.pathname !== '/callback') return new Response('Not found', { status: 404 });
-
-      const error = url.searchParams.get('error');
-      if (error) {
-        rejectCode(
-          new OAuthError(
-            error === 'access_denied'
-              ? 'Authorization was declined in the browser.'
-              : `Authorization failed: ${error}`,
-          ),
-        );
-        return failedPage('You can close this tab.');
-      }
-
-      const code = url.searchParams.get('code');
-      if (!code) {
-        rejectCode(new OAuthError('The callback carried no authorization code.'));
-        return failedPage('No code returned.');
-      }
-
-      // Checked here because nothing else checks it. The SDK's own docs say it
-      // does not validate `state`, and it only sends one if the provider hands
-      // it over — so this listener mints the value, `CredentialOAuthProvider`
-      // returns it from `state()`, and the two are compared on the way back.
-      //
-      // Without it this resolves on the first `/callback?code=` to reach the
-      // port, whoever sent it: any local process, or a page the operator has
-      // open, can sweep loopback during the five-minute window. PKCE usually
-      // turns that into a failed exchange, but a manifest is free to name an
-      // authorization server that does not enforce it, and there the code
-      // would be redeemed and the connection bound to someone else's account.
-      const returnedState = url.searchParams.get('state');
-      if (!returnedState || !stateMatches(state, returnedState)) {
-        rejectCode(new OAuthError('State mismatch — ignoring an unexpected callback.'));
-        return failedPage('Unexpected callback.');
-      }
-
-      const iss = url.searchParams.get('iss');
-      resolveCode({ code, ...(iss ? { iss } : {}) });
-      return connectedPage(options.label);
-    },
-  });
-
-  return {
-    redirectUri: `http://127.0.0.1:${server.port}/callback`,
-    state,
-
-    async wait(timeoutMs = 5 * 60_000) {
-      return withTimeout(
-        received,
-        timeoutMs,
-        `Timed out after ${Math.round(timeoutMs / 1000)}s waiting for the browser.`,
-      );
-    },
-
-    close: () => shutdown(server),
-  };
-}

package/src/cli/output.ts

@@ -106,15 +106,31 @@ export async function waiting<T>(label: string, work: () => Promise<T>): Promise
  * The line every command prints before acting, read-only commands included.
  *
  * This is the primary guard against operating on the wrong instance, and it
- * costs one line. It names where each value came from, because "profile: work"
- * is much less useful than knowing it came from an environment variable you
- * forgot you exported.
+ * costs one line. It used to name where each value came from, which mattered
+ * while four things could supply them. Only the command line can now (ADR-037),
+ * so the parenthetical would say `(flag)` twice on every line forever — which
+ * `target.ts` already argues is how a line stops being read.
  */
+/**
+ * The same line for a command that opens no target.
+ *
+ * `identity list` reads a block declared once in the YAML, so it takes no
+ * `--target` (ADR-037) and there is none to name. Printing `target undefined`
+ * or omitting the line entirely were the alternatives; the first is a lie and
+ * the second loses the guard that this line exists to be.
+ */
+export function announceProfile(selection: {
+  readonly profile: string;
+  readonly workspaceRoot: string;
+}): void {
+  print(style.dim(`profile ${style.bold(selection.profile)}  ${selection.workspaceRoot}`));
+}
+
 export function announce(resolution: Resolution): void {
   print(
     style.dim(
-      `profile ${style.bold(resolution.profile)} (${resolution.profileSource})  ` +
-        `target ${style.bold(resolution.target)} (${resolution.targetSource})  ` +
+      `profile ${style.bold(resolution.profile)}  ` +
+        `target ${style.bold(resolution.target)}  ` +
         `${resolution.workspaceRoot}`,
     ),
   );

package/src/cli/provider-marks.ts

@@ -0,0 +1,45 @@
+/**
+ * A brand mark per provider, drawn rather than fetched.
+ *
+ * Vendored from Simple Icons 16.28.0, which dedicates its paths to the public
+ * domain under CC0-1.0. **The trademarks themselves remain their owners'** —
+ * these identify the service a connection reaches, which is what nominative use
+ * is for, and nothing here implies that any of them endorses this.
+ *
+ * Inlined because there is nowhere else to put them. The page is served under a
+ * strict `default-src 'none'`, so it fetches nothing; the alternative — a CDN —
+ * would tell a third party which dashboard the owner is looking at, every time
+ * they look. There is also no static-asset pipeline to serve them from.
+ *
+ * Every path is one shape on a `0 0 24 24` canvas, filled with `currentColor`,
+ * so a mark inherits the page's text colour and is correct in either theme
+ * without a second copy. That is also why these are monochrome rather than the
+ * full-colour originals: `callback-page.ts` reserves colour for status, and a
+ * row of brand hues would spend it on decoration.
+ *
+ * Ids sharing a mark do so deliberately — `gmail` and `gmail_mcp` reach the same
+ * mailbox by different transports, and the four `icloud_*` providers are one
+ * service. The mark names the vendor; the name beside it names the product.
+ *
+ * Absent here, `dashboard-page.ts` falls back to a monogram. That covers every
+ * provider an operator writes themselves, and the two shipped ones Simple Icons
+ * does not carry: Slack, whose mark was withdrawn at the brand's request, and
+ * Google Contacts, which it never had.
+ */
+export const PROVIDER_MARKS: Readonly<Record<string, string>> = {
+  calendar: 'M18.316 5.684H24v12.632h-5.684V5.684zM5.684 24h12.632v-5.684H5.684V24zM18.316 5.684V0H1.895A1.894 1.894 0 0 0 0 1.895v16.421h5.684V5.684h12.632zm-7.207 6.25v-.065c.272-.144.5-.349.687-.617s.279-.595.279-.982c0-.379-.099-.72-.3-1.025a2.05 2.05 0 0 0-.832-.714 2.703 2.703 0 0 0-1.197-.257c-.6 0-1.094.156-1.481.467-.386.311-.65.671-.793 1.078l1.085.452c.086-.249.224-.461.413-.633.189-.172.445-.257.767-.257.33 0 .602.088.816.264a.86.86 0 0 1 .322.703c0 .33-.12.589-.36.778-.24.19-.535.284-.886.284h-.567v1.085h.633c.407 0 .748.109 1.02.327.272.218.407.499.407.843 0 .336-.129.614-.387.832s-.565.327-.924.327c-.351 0-.651-.103-.897-.311-.248-.208-.422-.502-.521-.881l-1.096.452c.178.616.505 1.082.977 1.401.472.319.984.478 1.538.477a2.84 2.84 0 0 0 1.293-.291c.382-.193.684-.458.902-.794.218-.336.327-.72.327-1.149 0-.429-.115-.797-.344-1.105a2.067 2.067 0 0 0-.881-.689zm2.093-1.931l.602.913L15 10.045v5.744h1.187V8.446h-.827l-2.158 1.557zM22.105 0h-3.289v5.184H24V1.895A1.894 1.894 0 0 0 22.105 0zm-3.289 23.5l4.684-4.684h-4.684V23.5zM0 22.105C0 23.152.848 24 1.895 24h3.289v-5.184H0v3.289z',
+  docs: 'M14.727 6.727H14V0H4.91c-.905 0-1.637.732-1.637 1.636v20.728c0 .904.732 1.636 1.636 1.636h14.182c.904 0 1.636-.732 1.636-1.636V6.727h-6zm-.545 10.455H7.09v-1.364h7.09v1.364zm2.727-3.273H7.091v-1.364h9.818v1.364zm0-3.273H7.091V9.273h9.818v1.363zM14.727 6h6l-6-6v6z',
+  drive: 'M12.01 1.485c-2.082 0-3.754.02-3.743.047.01.02 1.708 3.001 3.774 6.62l3.76 6.574h3.76c2.081 0 3.753-.02 3.742-.047-.005-.02-1.708-3.001-3.775-6.62l-3.76-6.574zm-4.76 1.73a789.828 789.861 0 0 0-3.63 6.319L0 15.868l1.89 3.298 1.885 3.297 3.62-6.335 3.618-6.33-1.88-3.287C8.1 4.704 7.255 3.22 7.25 3.214zm2.259 12.653-.203.348c-.114.198-.96 1.672-1.88 3.287a423.93 423.948 0 0 1-1.698 2.97c-.01.026 3.24.042 7.222.042h7.244l1.796-3.157c.992-1.734 1.85-3.23 1.906-3.323l.104-.167h-7.249z',
+  drive_mcp: 'M12.01 1.485c-2.082 0-3.754.02-3.743.047.01.02 1.708 3.001 3.774 6.62l3.76 6.574h3.76c2.081 0 3.753-.02 3.742-.047-.005-.02-1.708-3.001-3.775-6.62l-3.76-6.574zm-4.76 1.73a789.828 789.861 0 0 0-3.63 6.319L0 15.868l1.89 3.298 1.885 3.297 3.62-6.335 3.618-6.33-1.88-3.287C8.1 4.704 7.255 3.22 7.25 3.214zm2.259 12.653-.203.348c-.114.198-.96 1.672-1.88 3.287a423.93 423.948 0 0 1-1.698 2.97c-.01.026 3.24.042 7.222.042h7.244l1.796-3.157c.992-1.734 1.85-3.23 1.906-3.323l.104-.167h-7.249z',
+  github: 'M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12',
+  gmail: 'M24 5.457v13.909c0 .904-.732 1.636-1.636 1.636h-3.819V11.73L12 16.64l-6.545-4.91v9.273H1.636A1.636 1.636 0 0 1 0 19.366V5.457c0-2.023 2.309-3.178 3.927-1.964L5.455 4.64 12 9.548l6.545-4.91 1.528-1.145C21.69 2.28 24 3.434 24 5.457z',
+  gmail_mcp: 'M24 5.457v13.909c0 .904-.732 1.636-1.636 1.636h-3.819V11.73L12 16.64l-6.545-4.91v9.273H1.636A1.636 1.636 0 0 1 0 19.366V5.457c0-2.023 2.309-3.178 3.927-1.964L5.455 4.64 12 9.548l6.545-4.91 1.528-1.145C21.69 2.28 24 3.434 24 5.457z',
+  icloud_calendar: 'M13.762 4.29a6.51 6.51 0 0 0-5.669 3.332 3.571 3.571 0 0 0-1.558-.36 3.571 3.571 0 0 0-3.516 3A4.918 4.918 0 0 0 0 14.796a4.918 4.918 0 0 0 4.92 4.914 4.93 4.93 0 0 0 .617-.045h14.42c2.305-.272 4.041-2.258 4.043-4.589v-.009a4.594 4.594 0 0 0-3.727-4.508 6.51 6.51 0 0 0-6.511-6.27z',
+  icloud_contacts: 'M13.762 4.29a6.51 6.51 0 0 0-5.669 3.332 3.571 3.571 0 0 0-1.558-.36 3.571 3.571 0 0 0-3.516 3A4.918 4.918 0 0 0 0 14.796a4.918 4.918 0 0 0 4.92 4.914 4.93 4.93 0 0 0 .617-.045h14.42c2.305-.272 4.041-2.258 4.043-4.589v-.009a4.594 4.594 0 0 0-3.727-4.508 6.51 6.51 0 0 0-6.511-6.27z',
+  icloud_drive: 'M13.762 4.29a6.51 6.51 0 0 0-5.669 3.332 3.571 3.571 0 0 0-1.558-.36 3.571 3.571 0 0 0-3.516 3A4.918 4.918 0 0 0 0 14.796a4.918 4.918 0 0 0 4.92 4.914 4.93 4.93 0 0 0 .617-.045h14.42c2.305-.272 4.041-2.258 4.043-4.589v-.009a4.594 4.594 0 0 0-3.727-4.508 6.51 6.51 0 0 0-6.511-6.27z',
+  icloud_mail: 'M13.762 4.29a6.51 6.51 0 0 0-5.669 3.332 3.571 3.571 0 0 0-1.558-.36 3.571 3.571 0 0 0-3.516 3A4.918 4.918 0 0 0 0 14.796a4.918 4.918 0 0 0 4.92 4.914 4.93 4.93 0 0 0 .617-.045h14.42c2.305-.272 4.041-2.258 4.043-4.589v-.009a4.594 4.594 0 0 0-3.727-4.508 6.51 6.51 0 0 0-6.511-6.27z',
+  linear: 'M2.886 4.18A11.982 11.982 0 0 1 11.99 0C18.624 0 24 5.376 24 12.009c0 3.64-1.62 6.903-4.18 9.105L2.887 4.18ZM1.817 5.626l16.556 16.556c-.524.33-1.075.62-1.65.866L.951 7.277c.247-.575.537-1.126.866-1.65ZM.322 9.163l14.515 14.515c-.71.172-1.443.282-2.195.322L0 11.358a12 12 0 0 1 .322-2.195Zm-.17 4.862 9.823 9.824a12.02 12.02 0 0 1-9.824-9.824Z',
+  notion: 'M4.459 4.208c.746.606 1.026.56 2.428.466l13.215-.793c.28 0 .047-.28-.046-.326L17.86 1.968c-.42-.326-.981-.7-2.055-.607L3.01 2.295c-.466.046-.56.28-.374.466zm.793 3.08v13.904c0 .747.373 1.027 1.214.98l14.523-.84c.841-.046.935-.56.935-1.167V6.354c0-.606-.233-.933-.748-.887l-15.177.887c-.56.047-.747.327-.747.933zm14.337.745c.093.42 0 .84-.42.888l-.7.14v10.264c-.608.327-1.168.514-1.635.514-.748 0-.935-.234-1.495-.933l-4.577-7.186v6.952L12.21 19s0 .84-1.168.84l-3.222.186c-.093-.186 0-.653.327-.746l.84-.233V9.854L7.822 9.76c-.094-.42.14-1.026.793-1.073l3.456-.233 4.764 7.279v-6.44l-1.215-.139c-.093-.514.28-.887.747-.933zM1.936 1.035l13.31-.98c1.634-.14 2.055-.047 3.082.7l4.249 2.986c.7.513.934.653.934 1.213v16.378c0 1.026-.373 1.634-1.68 1.726l-15.458.934c-.98.047-1.448-.093-1.962-.747l-3.129-4.06c-.56-.747-.793-1.306-.793-1.96V2.667c0-.839.374-1.54 1.447-1.632z',
+  sheets: 'M11.318 12.545H7.91v-1.909h3.41v1.91zM14.728 0v6h6l-6-6zm1.363 10.636h-3.41v1.91h3.41v-1.91zm0 3.273h-3.41v1.91h3.41v-1.91zM20.727 6.5v15.864c0 .904-.732 1.636-1.636 1.636H4.909a1.636 1.636 0 0 1-1.636-1.636V1.636C3.273.732 4.005 0 4.909 0h9.318v6.5h6.5zm-3.273 2.773H6.545v7.909h10.91v-7.91zm-6.136 4.636H7.91v1.91h3.41v-1.91z',
+  tasks: 'M11.383.617C5.097.617 0 5.714 0 12c0 6.286 5.097 11.383 11.383 11.383 6.286 0 11.38-5.097 11.38-11.383a11.34 11.34 0 0 0-.878-4.389l-3.203 3.203c.062.387.1.782.1 1.186a7.398 7.398 0 1 1-7.4-7.398c1.499 0 2.889.448 4.054 1.214l2.857-2.857a11.325 11.325 0 0 0-6.91-2.342zm9.674.756c-.292 0-.583.112-.805.334-2.97 2.965-5.934 5.934-8.9 8.902L9.596 8.854a1.139 1.139 0 0 0-1.61 0l-1.775 1.773a1.139 1.139 0 0 0 0 1.61l4.166 4.163a1.421 1.421 0 0 0 2.012 0L23.666 5.121a1.136 1.136 0 0 0 0-1.61l-1.805-1.804a1.136 1.136 0 0 0-.804-.334z',
+};

package/src/cli/runtime/open.ts

@@ -6,9 +6,10 @@ import type { BlobStore } from '#stores/blobs';
 import type { AnyConnector, ProviderManifest } from '#connectivity';
 import { RateLimiter, allowedConnections } from '#policy';
 import {
-  ConfigError,
+  KNOWLEDGE_LAYOUT,
   layout,
   listProfiles,
+  undeclaredTarget,
   workspacePath,
   type Config,
   type Resolution,
@@ -16,12 +17,7 @@ import {
 import { ProviderRegistry, toPolicyDocument } from '#registry';
 import { Dispatcher, createConsoleLogger } from '#dispatch';
 import { PROVIDER_MANIFESTS } from '#providers/index.ts';
-import {
-  createBlobVaultStore,
-  createFileVaultStore,
-  createSecretVaultStore,
-  type VaultStore,
-} from '#providers/owner.ts';
+import type { VaultStore } from '#providers/owner.ts';
 import {
   openAuditSinks,
   openState,
@@ -30,11 +26,14 @@ import {
   type StorageFactory,
   type TargetInput,
 } from '#deployments/target.ts';
+import { openKnowledge, type FetchLike, type KnowledgeStores } from '#deployments/knowledge.ts';
+import { routeBlobStore } from '#stores/blobs/route.ts';
 import { connectorFactory } from '#connectivity/transports';
 import { requestAuthorizer } from '#connectivity/auth/index.ts';
 import { resolveProfile, type GlobalFlags } from './select.ts';
-import { buildRegistryWithWorkspace, reloadSkills, skillFingerprint } from './registry.ts';
+import { buildRegistryWithWorkspace, readSkillsForStart, reloadSkills } from './registry.ts';
 import { discoveryProbe } from './discovery.ts';
+import { openVault } from './vault.ts';
 
 /**
  * Assembling a profile's runtime from its declared target.
@@ -56,6 +55,16 @@ export interface Runtime {
   readonly storage: BlobStore;
   /** Where skills are kept — `data/<profile>/skills.d/` locally. */
   readonly skills: BlobStore;
+  /**
+   * Present only when this target keeps memory and skills in a repository.
+   *
+   * Nothing on the dispatch path reads it: `storage` and `skills` above are
+   * already pointed at the right bytes, which is the whole design. It is here
+   * so `target show` and `doctor` can say where those bytes are without
+   * re-reading the config, and so the migration can reach the repository it is
+   * committing to.
+   */
+  readonly knowledge?: KnowledgeStores | undefined;
   /** The vault's own store, so `lanes link vault` reaches the same bytes MCP does. */
   readonly vault: VaultStore;
   readonly registry: ProviderRegistry;
@@ -99,50 +108,29 @@ function skillStore(storage: StorageFactory, profile: string): BlobStore {
 }
 
 /**
- * The vault's encrypted document, wherever this target keeps it.
+ * What a caller may hand the runtime that is not a flag somebody typed.
  *
- * Defaults to `file`, so a profile written before ADR-014 needs no change and a
- * local run needs no vault configuration at all. `blob` exists because the file
- * adapter was unconditional before: a deployed instance wrote its vault to a
- * container filesystem, and every item in it was discarded by the next
- * revision without an error to say so.
+ * One field, and it exists for the same reason `connect`'s does: the only thing
+ * a runtime reaches over the network at open time is a knowledge repository,
+ * and a test that could not replace it would either hit github.com or not run.
  */
-function openVault(
-  input: TargetInput,
-  storage: StorageFactory,
-  credentials: SecretStore,
-): VaultStore {
-  const { declared, config, root } = input;
-  const vault = declared.vault ?? { adapter: 'file' as const };
-
-  switch (vault.adapter) {
-    case 'file':
-      return createFileVaultStore({
-        path: workspacePath(root, vault.path ?? layout.vault(config.instance.profile)),
-      });
-
-    case 'secret':
-      // The document is sealed under LANES_LINK_VAULT_KEY before it gets here,
-      // so the credential store holds ciphertext it cannot read. Separate
-      // document, separate key, separate environment variable — the backend
-      // was never what kept the two stores apart. ADR-022.
-      return createSecretVaultStore({
-        store: credentials,
-        ...(vault.ref !== undefined ? { ref: vault.ref } : {}),
-      });
-
-    case 'blob':
-      return createBlobVaultStore({
-        store: storage(),
-        ...(vault.path !== undefined ? { key: vault.path } : {}),
-      });
-  }
+export interface OpenOptions {
+  /** Injected for tests. */
+  readonly fetch?: FetchLike | undefined;
 }
 
-export async function openRuntime(flags: GlobalFlags): Promise<Runtime> {
+export async function openRuntime(
+  flags: GlobalFlags,
+  options: OpenOptions = {},
+): Promise<Runtime> {
   const { resolution, config, target } = await resolveProfile(flags);
   const declared = config.targets[target];
-  if (!declared) throw new ConfigError(`Target "${target}" is not declared`);
+  // `resolveProfile` has already checked this, so reaching it means a caller
+  // passed `allowUndeclaredTarget`. Through the shared refusal all the same:
+  // this was a fourth spelling of that sentence with the profile name and the
+  // list of what exists both missing, and the comment on `undeclaredTarget`
+  // says why one copy is the most that survives.
+  if (!declared) throw undeclaredTarget(target, config, resolution.profile);
 
   const root = resolution.workspaceRoot;
   const adapters: TargetInput = { declared, config, root, target };
@@ -154,7 +142,23 @@ export async function openRuntime(flags: GlobalFlags): Promise<Runtime> {
   // no schema left to migrate.
   const credentials = await openSecrets(adapters);
   const storageFor = await openStorage(adapters, credentials);
-  const storage = storageFor();
+
+  // Memory and skills, where a profile keeps them somewhere else (ADR-041).
+  //
+  // The redirection happens *here*, on the store every consumer was already
+  // handed, and that is deliberate. Memory is not addressed by a name anything
+  // declares: `buildProviderContext` scopes the profile's blob root to
+  // `memory/<connection>`, and `lanes link memory` reaches the same bytes by
+  // calling the same two functions. So the dispatcher, the provider, and the
+  // CLI need no knowledge of this and cannot disagree about where an entry
+  // went — the one thing they are handed already points at the repository.
+  //
+  // The audit log, `state.kv`, the credential store and the vault keep their
+  // own roots on the target's own storage and are untouched.
+  const knowledge = await openKnowledge(adapters, credentials, options.fetch);
+  const storage = knowledge
+    ? routeBlobStore(storageFor(), [{ prefix: `${KNOWLEDGE_LAYOUT.memory}/`, store: knowledge.memory }])
+    : storageFor();
   const state = openState(storageFor, config.instance.profile);
 
   // The durable log, plus any copies the target declares. `sink` is what
@@ -168,7 +172,7 @@ export async function openRuntime(flags: GlobalFlags): Promise<Runtime> {
     (message) => logger.warn(message),
   );
 
-  const skills = skillStore(storageFor, config.instance.profile);
+  const skills = knowledge?.skills ?? skillStore(storageFor, config.instance.profile);
 
   // The vault's own store, beside the credential store and never it: a separate
   // document, a separate key, and a separate environment variable
@@ -228,21 +232,39 @@ export async function openRuntime(flags: GlobalFlags): Promise<Runtime> {
         account: connection.account,
       }));
 
+  // Read before the registry is built, so a store that cannot be reached is a
+  // warning rather than the end of the process — see `readSkillsForStart`. Only
+  // tolerated when the store is a repository: a local directory that will not
+  // read is a real fault worth failing on, exactly as it always was.
+  const loaded = await readSkillsForStart(
+    skills,
+    knowledge !== undefined,
+    (message) => logger.warn(message),
+    ` --profile ${config.instance.profile} --target ${target}`,
+  );
+
   registry = await buildRegistryWithWorkspace(root, config.instance.profile, {
     skillStore: skills,
+    skills: loaded.skills,
     onSkillsChanged: refreshSkills,
     vault: { store: vaultStore, items: await vaultStore.ids() },
     setup: {
       profile: config.instance.profile,
+      target,
       profiles: await listProfiles(root),
       catalogue: PROVIDER_MANIFESTS,
       ownClients: Object.keys(config.oauth_apps),
       reachable,
     },
+    // Straight off the config: unlike `reachable`, nothing has to be filtered
+    // through policy first. Whether the surface is reachable at all is still
+    // policy's answer, given once by `mergeCapabilities` — this only decides
+    // what it says when it is.
+    identity: { profile: config.instance.profile, target, entries: config.identity },
   });
-  // Seeded from the build that just happened, so the first refresh compares
-  // against what is registered rather than rebuilding once to find out.
-  fingerprint = await skillFingerprint(skills);
+  // Seeded from the read above, so the first refresh compares against what is
+  // registered rather than rebuilding once to find out.
+  fingerprint = loaded.fingerprint;
 
   // Discovered capabilities never come from a live call on the dispatch path —
   // that is what keeps the server stateless. But "not live" is not the same as
@@ -312,6 +334,7 @@ export async function openRuntime(flags: GlobalFlags): Promise<Runtime> {
     credentials,
     storage,
     skills,
+    ...(knowledge ? { knowledge } : {}),
     vault: vaultStore,
     registry,
     refreshSkills,