@lanes-sh/link 0.2.1 → 0.2.2

package/instructions/skills/lanes-link/SKILL.md

@@ -185,3 +185,20 @@ URL and a token.
 user the command rather than backgrounding it silently on their behalf.
 Registration works while it is down — the harness simply cannot reach it yet,
 and the first symptom is a failed call much later.
+
+## When a call does not land
+
+Different from the above, and more common: calls were working, and then one does
+not go through. A deployed endpoint is one machine its owner runs, and a client
+can report it unreachable while it is up — sometimes without sending anything at
+all, which is why the endpoint's own log can show no trace of the attempt.
+
+Treat it as ordinary. **Say the call did not land, and stop there.** It is not a
+fault to diagnose, and it is not authorization that has lapsed — do not tell them
+to sign in again unless the endpoint itself said so.
+
+**Do not redo what already succeeded.** A call that returned is done, and the
+next one failing does not undo it. Re-deriving a finished answer, or rewriting a
+memory entry that was already written, is the expensive mistake here and the one
+that actually gets made. Say which parts landed, which did not, and offer to
+retry the rest.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lanes-sh/link",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "A self-hostable MCP gateway for all your connections, memory, skills, and secrets",
   "license": "Apache-2.0",
   "homepage": "https://lanes.sh/link",

package/src/auth/index.ts

@@ -212,9 +212,11 @@ export {
   challenge,
   protectedResourceMetadata,
   MCP_SCOPE,
+  type ChallengeError,
   type ResourceIdentity,
 } from './oauth/metadata.ts';
-export { OAuthServer, matchesRegistered, pkceChallengeFor, type AuthorizeRequest, type OAuthResult } from './oauth/server.ts';
+export { OAuthServer, pkceChallengeFor, type AuthorizeRequest, type OAuthResult } from './oauth/server.ts';
+export { matchesRegistered } from './oauth/redirects.ts';
 export { OAuthStore, hashToken, randomToken } from './oauth/store.ts';
 export { OidcVerifier, type OidcVerifierOptions, type VerifiedSubject } from './oidc.ts';
 export { IssuedTokenAuthenticator, OidcAuthenticator } from './remote.ts';

package/src/auth/oauth/metadata.ts

@@ -22,21 +22,62 @@ export interface ResourceIdentity {
 }
 
 /**
- * One scope, and it is not a permission axis.
+ * Two scopes, and neither is a permission axis.
  *
  * What a caller may do is decided by the profile's policy, per capability, per
  * call, and recorded in the audit log. A second permission system expressed as
  * scopes could only either duplicate that or disagree with it, and a client
- * cannot be trusted to ask for less than it wants anyway. The scope exists
- * because the protocol has a slot for one.
+ * cannot be trusted to ask for less than it wants anyway. The scopes exist
+ * because the protocol has a slot for them, and because a client reads that
+ * slot to decide what this endpoint will do for it.
  */
 export const MCP_SCOPE = 'mcp';
 
+/**
+ * OIDC Core §11's name for "issue me a refresh token", and the reason this
+ * endpoint stopped sending its owner back to a browser.
+ *
+ * A refresh token has always been issued here, unconditionally. What was missing
+ * was saying so. A client's requested scope defaults to whatever the *resource*
+ * document lists, and the reference MCP client appends `offline_access` only
+ * when the *authorization server* document advertises it:
+ *
+ * ```js
+ * let effectiveScope = requestedScope || resourceMetadata?.scopes_supported?.join(" ") || …
+ * if (effectiveScope && authServerMetadata?.scopes_supported?.includes("offline_access") && …)
+ *   effectiveScope = `${effectiveScope} offline_access`;
+ * ```
+ *
+ * So both documents matter and they matter differently. Advertising it in
+ * neither left a client no grounds to request, persist, or use the refresh
+ * token it was being handed — and a client with no grounds reconnects, which
+ * means its owner approving in a browser.
+ */
+export const OFFLINE_ACCESS_SCOPE = 'offline_access';
+
+/** Everything grantable here. A request for anything else is narrowed, not refused. */
+export const SUPPORTED_SCOPES = [MCP_SCOPE, OFFLINE_ACCESS_SCOPE] as const;
+
+/**
+ * The grantable part of what was asked for.
+ *
+ * Empty means the request named nothing we recognise, and the caller falls back
+ * to `MCP_SCOPE` — refusing with `invalid_scope` would turn an unknown token in
+ * a client's default string into a connector that cannot be added at all, and
+ * scope is not the thing protecting anything here.
+ */
+export function grantableScope(requested: string | null | undefined): string {
+  const asked = new Set((requested ?? '').split(/\s+/).filter(Boolean));
+  return SUPPORTED_SCOPES.filter((scope) => asked.has(scope)).join(' ');
+}
+
 export function protectedResourceMetadata(identity: ResourceIdentity): Record<string, unknown> {
   return {
     resource: identity.resource,
     authorization_servers: [identity.issuer],
-    scopes_supported: [MCP_SCOPE],
+    // Where a client's *default* requested scope comes from, so this is the
+    // list that decides what an untouched connector asks for.
+    scopes_supported: [...SUPPORTED_SCOPES],
     bearer_methods_supported: ['header'],
   };
 }
@@ -47,7 +88,9 @@ export function authorizationServerMetadata(origin: string): Record<string, unkn
     authorization_endpoint: `${origin}/authorize`,
     token_endpoint: `${origin}/token`,
     registration_endpoint: `${origin}/register`,
-    scopes_supported: [MCP_SCOPE],
+    // And this is the list that gates whether `offline_access` is appended at
+    // all. Both documents have to carry it; neither one alone is enough.
+    scopes_supported: [...SUPPORTED_SCOPES],
     response_types_supported: ['code'],
     grant_types_supported: ['authorization_code', 'refresh_token'],
     // Advertised because a spec-compliant client checks for it before starting
@@ -60,6 +103,27 @@ export function authorizationServerMetadata(origin: string): Record<string, unkn
   };
 }
 
+/**
+ * Why a credential was refused, in RFC 6750 §3.1's vocabulary.
+ *
+ * There is one code worth sending and it carries the whole distinction a client
+ * needs: `invalid_token` says the credential was *rejected*, where an otherwise
+ * identical challenge says only that authorization is required. A client that
+ * cannot tell those apart cannot tell "refresh — you hold a refresh token for
+ * this" from "start a new authorization", and the safe-looking guess is the
+ * second, which means the owner approving in a browser for a credential a
+ * silent refresh would have replaced.
+ *
+ * Deliberately absent when nothing was presented. RFC 6750 §3: a resource
+ * server SHOULD NOT include an error code where the request carried no
+ * authentication information — and sending one would set a client refreshing a
+ * credential it does not have.
+ */
+export interface ChallengeError {
+  readonly code: 'invalid_token';
+  readonly description: string;
+}
+
 /**
  * The `WWW-Authenticate` value on a 401.
  *
@@ -67,9 +131,19 @@ export function authorizationServerMetadata(origin: string): Record<string, unkn
  * has to guess the document's location by probing well-known paths, which costs
  * round trips and fails entirely on a host that does not serve them. Clients do
  * not honour this header on a `200`, so the status has to be right too.
+ *
+ * It stays on the header even when a token was rejected. A client that decides
+ * to authorize after all — because the refresh was refused too — must not have
+ * to go and find the document a second time.
  */
-export function challenge(metadataUrl: string | null): string {
-  return metadataUrl
-    ? `Bearer realm="lanes-link", resource_metadata="${metadataUrl}"`
-    : 'Bearer realm="lanes-link"';
+export function challenge(metadataUrl: string | null, error?: ChallengeError): string {
+  // Every value is a quoted-string, so none may contain a quote. Both of these
+  // are constants in this repository and the types keep them that way.
+  const parts = [
+    'realm="lanes-link"',
+    ...(error ? [`error="${error.code}"`, `error_description="${error.description}"`] : []),
+    ...(metadataUrl ? [`resource_metadata="${metadataUrl}"`] : []),
+  ];
+
+  return `Bearer ${parts.join(', ')}`;
 }

package/src/auth/oauth/redirects.ts

@@ -0,0 +1,70 @@
+/**
+ * Which redirect URIs this server will send an authorization code to.
+ *
+ * Its own file because it is its own subject. `server.ts` is the flow as
+ * decisions — a code exchanged, a token rotated, an owner approving — and none
+ * of it is about URL shapes. Both halves stayed inside the file-size budget
+ * until they did not, and the budget exists to point at exactly this: it was
+ * not too long, it was two things.
+ *
+ * Nothing here consults configuration. What a client registered is checked
+ * against what it now presents, and the rules are RFC 8252's rather than ours.
+ */
+
+/**
+ * https, or loopback for a native client.
+ *
+ * A native client cannot receive an https redirect, so RFC 8252 has it listen
+ * on a loopback port instead. Everything else is refused: a redirect to `http://`
+ * on a routable host puts an authorization code on the wire in clear text.
+ */
+export function isSafeRedirect(uri: string): boolean {
+  let parsed: URL;
+  try {
+    parsed = new URL(uri);
+  } catch {
+    return false;
+  }
+
+  if (parsed.protocol === 'https:') return true;
+  return parsed.protocol === 'http:' && isLoopbackHost(parsed.hostname);
+}
+
+function isLoopbackHost(hostname: string): boolean {
+  return hostname === '127.0.0.1' || hostname === '::1' || hostname === '[::1]' || hostname === 'localhost';
+}
+
+/**
+ * Exact match, except for the port of a loopback URI.
+ *
+ * RFC 8252 §7.3 requires ignoring the port for the IP-literal form, because a
+ * native client binds an ephemeral one it cannot know at registration time.
+ * Claude Code declares `http://localhost/callback` and `http://127.0.0.1/callback`
+ * and then listens on whatever port it got, so the same allowance has to cover
+ * `localhost` or it never connects.
+ */
+export function matchesRegistered(candidate: string, registered: readonly string[]): boolean {
+  if (registered.includes(candidate)) return true;
+
+  let parsed: URL;
+  try {
+    parsed = new URL(candidate);
+  } catch {
+    return false;
+  }
+  if (!isLoopbackHost(parsed.hostname)) return false;
+
+  return registered.some((uri) => {
+    try {
+      const other = new URL(uri);
+      return (
+        isLoopbackHost(other.hostname) &&
+        other.protocol === parsed.protocol &&
+        other.hostname === parsed.hostname &&
+        other.pathname === parsed.pathname
+      );
+    } catch {
+      return false;
+    }
+  });
+}

package/src/auth/oauth/server.ts

@@ -1,4 +1,5 @@
-import { MCP_SCOPE } from './metadata.ts';
+import { grantableScope, MCP_SCOPE } from './metadata.ts';
+import { isSafeRedirect, matchesRegistered } from './redirects.ts';
 import {
   hashToken,
   randomToken,
@@ -26,6 +27,21 @@ import {
 const CODE_TTL_MS = 60_000;
 const REFRESH_TTL_MS = 30 * 24 * 60 * 60 * 1000;
 
+/**
+ * How long a spent refresh token still answers.
+ *
+ * A client whose refresh succeeded but whose *response* was lost holds a token
+ * the server has already spent, and retrying with it is the only move it has.
+ * Without a window that retry is `invalid_grant`, and the reference MCP client
+ * rethrows every `OAuthError` but `server_error` rather than recovering — so
+ * the connector dies and its owner is sent to a browser, over a network blip.
+ *
+ * Thirty seconds is the band Auth0's reuse interval (0–60 s) and Okta's grace
+ * period occupy. What it costs: a captured refresh token keeps working for up
+ * to this long after the real client next rotates it.
+ */
+const REFRESH_REUSE_MS = 30_000;
+
 export type OAuthResult =
   | { readonly kind: 'json'; readonly status: number; readonly body: unknown }
   | { readonly kind: 'redirect'; readonly location: string }
@@ -61,6 +77,9 @@ export interface OAuthServerOptions {
   /** Proof of being the owner. The same token the endpoint already accepts. */
   readonly verifyOwner: (presented: string) => Promise<boolean>;
   readonly accessTokenTtlMs: number;
+  /** Where a replayed refresh token is recorded. Structural, because this layer
+   * may not import `#connectivity`; the endpoint's own logger satisfies it. */
+  readonly log?: { warn(message: string, detail?: Record<string, unknown>): void };
   readonly now?: () => number;
 }
 
@@ -163,7 +182,11 @@ export class OAuthServer {
         redirectUri,
         codeChallenge: challenge,
         state: params.get('state') ?? undefined,
-        scope: params.get('scope') || MCP_SCOPE,
+        // The grantable part of what was asked for, not the request verbatim.
+        // Echoing it back through `#issue` was granting by echo, which was inert
+        // while `mcp` was the only scope and stops being inert now that there is
+        // a second one that means something.
+        scope: grantableScope(params.get('scope')) || MCP_SCOPE,
         resource: params.get('resource') ?? undefined,
       },
     };
@@ -198,7 +221,12 @@ export class OAuthServer {
       clientId: request.clientId,
       redirectUri: request.redirectUri,
       codeChallenge: request.codeChallenge,
-      scope: request.scope,
+      // Narrowed here as well as in `authorize`, and this is the one that
+      // matters: the request arrives back through hidden form fields, so a
+      // caller can post any scope it likes straight to this endpoint. Nothing
+      // round-tripped through the form is trusted — the client and the redirect
+      // URI are re-checked above for the same reason.
+      scope: grantableScope(request.scope) || MCP_SCOPE,
       ...(request.resource ? { resource: request.resource } : {}),
       expiresAt: this.#now() + CODE_TTL_MS,
     };
@@ -252,15 +280,25 @@ export class OAuthServer {
       return invalid('invalid_grant', 'That refresh token is unknown or expired.');
     }
 
-    // A spent token presented again is the one signal that it has been copied.
-    // Rotation alone does not answer it: whoever refreshes first walks away
-    // with a live pair, and rejecting only the token in hand leaves that pair
-    // working while the other party — usually the real client — is locked out.
-    // So the whole chain goes. A client retrying a response it never saw and a
-    // thief replaying are indistinguishable from here, and re-authorising is
-    // the cheaper of the two mistakes.
+    // A spent token presented again used to take its whole family with it, on
+    // the reading that a replay is a theft. Against a real connector that was
+    // wrong twice over, and ADR-035 has the evidence. Two answers replace it,
+    // and the tombstone's age is what tells them apart.
     if (record.kind === 'consumed') {
-      await this.#options.store.revokeFamily(record.family);
+      // Inside the window it is a retry of a request already answered, and the
+      // client is owed the answer rather than a dead connector. Not re-consumed:
+      // a client retrying twice is still retrying.
+      const spentAt = record.consumedAt;
+      if (spentAt !== undefined && this.#now() - spentAt <= REFRESH_REUSE_MS) {
+        return this.#issue(record.clientId, record.scope, randomToken('llr'), record.family);
+      }
+
+      // Outside it, refused on its own — and the family survives, which is the
+      // half that was taking live sessions down with it.
+      this.#options.log?.warn('refresh token replayed', {
+        clientId: record.clientId,
+        family: record.family,
+      });
       return invalid('invalid_grant', 'That refresh token has already been used.');
     }
 
@@ -324,62 +362,4 @@ function invalid(error: string, description: string): OAuthResult {
   return { kind: 'json', status: 400, body: { error, error_description: description } };
 }
 
-/**
- * https, or loopback for a native client.
- *
- * A native client cannot receive an https redirect, so RFC 8252 has it listen
- * on a loopback port instead. Everything else is refused: a redirect to `http://`
- * on a routable host puts an authorization code on the wire in clear text.
- */
-function isSafeRedirect(uri: string): boolean {
-  let parsed: URL;
-  try {
-    parsed = new URL(uri);
-  } catch {
-    return false;
-  }
-
-  if (parsed.protocol === 'https:') return true;
-  return parsed.protocol === 'http:' && isLoopbackHost(parsed.hostname);
-}
-
-function isLoopbackHost(hostname: string): boolean {
-  return hostname === '127.0.0.1' || hostname === '::1' || hostname === '[::1]' || hostname === 'localhost';
-}
-
-/**
- * Exact match, except for the port of a loopback URI.
- *
- * RFC 8252 §7.3 requires ignoring the port for the IP-literal form, because a
- * native client binds an ephemeral one it cannot know at registration time.
- * Claude Code declares `http://localhost/callback` and `http://127.0.0.1/callback`
- * and then listens on whatever port it got, so the same allowance has to cover
- * `localhost` or it never connects.
- */
-export function matchesRegistered(candidate: string, registered: readonly string[]): boolean {
-  if (registered.includes(candidate)) return true;
-
-  let parsed: URL;
-  try {
-    parsed = new URL(candidate);
-  } catch {
-    return false;
-  }
-  if (!isLoopbackHost(parsed.hostname)) return false;
-
-  return registered.some((uri) => {
-    try {
-      const other = new URL(uri);
-      return (
-        isLoopbackHost(other.hostname) &&
-        other.protocol === parsed.protocol &&
-        other.hostname === parsed.hostname &&
-        other.pathname === parsed.pathname
-      );
-    } catch {
-      return false;
-    }
-  });
-}
-
 export { hashToken };

package/src/auth/oauth/store.ts

@@ -53,6 +53,9 @@ export interface AuthorizationCode {
  * it arrived. A tombstone keeps the family id and nothing else useful, and it
  * opens no more than a deleted row does — every check that admits a credential
  * tests for `access` by name.
+ *
+ * What is *done* about a detected replay changed in ADR-035: the presented
+ * token is refused and the replay logged, rather than the family revoked.
  */
 export type TokenKind = 'access' | 'refresh' | 'consumed';
 
@@ -71,6 +74,15 @@ export interface IssuedToken {
    * the theft and the retry look identical from here.
    */
   readonly family: string;
+  /**
+   * When this token was spent, on a `consumed` tombstone and nowhere else.
+   *
+   * What makes the reuse interval possible: without it a spent token carries no
+   * hint whether it was spent a second ago or a month ago, and those are a retry
+   * and a replay. A tombstone written before this existed has no `consumedAt`
+   * and is read as the older one, which is the safe direction.
+   */
+  readonly consumedAt?: number;
 }
 
 export function hashToken(value: string): string {
@@ -182,16 +194,18 @@ export class OAuthStore {
     const key = hashToken(token);
     const record = await this.#read<IssuedToken>(TOKENS, key);
     if (!record) return;
-    await this.#state.set(TOKENS, key, JSON.stringify({ ...record, kind: 'consumed' }));
+    const spent: IssuedToken = { ...record, kind: 'consumed', consumedAt: this.#now() };
+    await this.#state.set(TOKENS, key, JSON.stringify(spent));
   }
 
   /**
    * Drop every token in a refresh family.
    *
-   * Called when a rotated-away refresh token is presented again, which is
-   * either a client retrying or a thief replaying. Both are answered the same
-   * way, because from here they are indistinguishable and the safe reading is
-   * the expensive one.
+   * A replay no longer calls this, and a replay was the only thing that did —
+   * see `OAuthServer.#refresh` and ADR-035. Kept because it is the shape a
+   * deliberate revocation takes: one authorization's whole chain, dropped on
+   * purpose. Nothing in `src/` reaches it today, so read a call site as new
+   * policy rather than as the old one returning.
    */
   async revokeFamily(family: string): Promise<void> {
     for (const key of await this.#state.keys(TOKENS)) {

package/src/deployments/gcp/driver.ts

@@ -113,6 +113,12 @@ export function deployPlan(input: PlanInput): DeployStep[] {
         // harness can mint one — so a target reached by a remote MCP client
         // declares `public` and gates the request in the application instead.
         cloudrun.access === 'iam' ? '--no-allow-unauthenticated' : '--allow-unauthenticated',
+        // Always passed, including the zero. Config is the source of truth here
+        // (ADR-004), and a flag sent only when non-zero would let a value be
+        // raised and never lowered — the revision would keep whatever the last
+        // deploy that bothered to mention it had set.
+        '--min-instances',
+        String(cloudrun.min_instances),
       ],
     },
   ];

package/src/deployments/gcp/survey.ts

@@ -127,6 +127,9 @@ export async function surveyCloudRun(input: SurveyInput): Promise<SurveyResult>
 
   const deploy: DeployConfig = {
     platform: 'cloudrun',
+    // Not asked about. Zero is right for almost every target and the question
+    // would cost every operator a decision to buy one of them a knob.
+    min_instances: current.min_instances ?? 0,
     project,
     region,
     service,

package/src/profile/authorization.ts

@@ -34,11 +34,20 @@ const selfAuthorizationSchema = z.object({
   /**
    * How long an issued access token lives.
    *
-   * Short by design and refreshed rather than lengthened: a client that holds a
-   * long-lived token has something worth stealing, and the refresh path is the
-   * one that can be revoked by dropping a row.
+   * Twelve hours, where this used to be one. The old reading — short by design,
+   * refreshed rather than lengthened — assumed the refresh happens. Expiry is
+   * in practice where a remote client loses its session: one observed against
+   * this endpoint let its access token lapse and reported needing authorization
+   * while the matching refresh token sat in the store unused, weeks from its
+   * own expiry. That is the client's bug and nothing here can fix it. What the
+   * endpoint can do is stop offering the chance twenty-four times a day.
+   *
+   * What is given up is real and bounded: a stolen access token is useful for
+   * longer. The revocable half is unchanged — the refresh path is still what a
+   * dropped row closes — and the refresh token was already the longer-lived of
+   * the pair at thirty days. `1440` is the ceiling, for one window a day.
    */
-  access_token_ttl_minutes: z.number().int().positive().max(1440).default(60),
+  access_token_ttl_minutes: z.number().int().positive().max(1440).default(720),
 });
 
 const oidcAuthorizationSchema = z.object({

package/src/profile/schema.ts

@@ -178,6 +178,20 @@ export const deployTargetSchema = z.object({
   billing_account: z.string().optional(),
   /** The identity the running revision assumes. Needs read access to the credential store. */
   service_account: z.string().optional(),
+  /**
+   * Instances kept running when nothing is calling.
+   *
+   * Zero is the default and the right answer for almost everything here: a cold
+   * start on the MCP path measures under three seconds, and the platform queues
+   * the request behind it, so scaling to zero is invisible to a caller.
+   *
+   * It is a knob because one path is not a caller. A client refreshes its token
+   * exactly when it wakes after an idle gap — which is exactly when the instance
+   * is cold — and a refresh that fails at the network level sends a remote
+   * client through a fresh browser authorization rather than surfacing an error.
+   * Raise it if a re-authorization ever lines up with a cold `/token`.
+   */
+  min_instances: z.number().int().min(0).max(10).default(0),
 });
 
 /**
@@ -221,7 +235,18 @@ export const targetSchema = z
   .transform(({ cloudrun, ...target }) =>
     target.deploy || !cloudrun
       ? target
-      : { ...target, deploy: { ...cloudrun, platform: 'cloudrun' as const, access: 'iam' as const } },
+      : {
+          ...target,
+          // The pre-`deploy` spelling predates both of these, so it gets the
+          // same defaults the current one would: the closed door, and no
+          // instance kept warm.
+          deploy: {
+            ...cloudrun,
+            platform: 'cloudrun' as const,
+            access: 'iam' as const,
+            min_instances: 0,
+          },
+        },
   );
 
 /**

package/src/server/endpoint.ts

@@ -169,6 +169,7 @@ function closeAll(runtimes: ReadonlyMap<string, Runtime>): Promise<unknown> {
  */
 async function openAuthorization(
   primary: Runtime,
+  log: Logger,
 ): Promise<{ surface: AuthorizationSurface; authenticator: Authenticator } | null> {
   const declared = primary.config.auth.authorization;
   if (!declared) return null;
@@ -210,6 +211,10 @@ async function openAuthorization(
   const server = new OAuthServer({
     store,
     accessTokenTtlMs: declared.access_token_ttl_minutes * 60_000,
+    // So a replayed refresh token leaves a line. It is refused rather than
+    // acted on (ADR-035), and a refusal nobody can see is how a connector
+    // losing its authorization came to need log forensics to explain.
+    log,
     // 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
@@ -228,6 +233,7 @@ async function openAuthorization(
 
 export async function startEndpoint(options: EndpointOptions): Promise<RunningEndpoint> {
   const reporter = options.reporter ?? SILENT;
+  const log = options.log ?? silentLogger();
   const { primary, runtimes } = await openReconciled(options);
 
   try {
@@ -251,7 +257,7 @@ export async function startEndpoint(options: EndpointOptions): Promise<RunningEn
       }
     }
 
-    const gate = await openAuthorization(primary);
+    const gate = await openAuthorization(primary, log);
 
     // The authenticator and the authorization gate are built once, from the
     // runtime this endpoint booted with, and are deliberately not part of what
@@ -273,7 +279,10 @@ export async function startEndpoint(options: EndpointOptions): Promise<RunningEn
       // not refresh skills`, and every `mcp handler error` the endpoint raises
       // all went to those empty methods. A silent endpoint is not a quiet one —
       // it is one whose failures have to be reconstructed from request sizes.
-      { primary: primary.resolution.profile, log: options.log ?? silentLogger() },
+      // `remoteClients` is the gate's existence, not a second setting: a profile
+      // declaring `auth.authorization` is one a connector reaches by URL, which
+      // is exactly the client the extra paragraph is written for.
+      { primary: primary.resolution.profile, log, ...(gate ? { remoteClients: true } : {}) },
     );
 
     const server = serve({
@@ -282,7 +291,7 @@ export async function startEndpoint(options: EndpointOptions): Promise<RunningEn
       authenticator: gate
         ? new AuthenticatorChain([primary.authenticator, gate.authenticator])
         : primary.authenticator,
-      log: options.log ?? silentLogger(),
+      log,
       ...(gate ? { authorization: gate.surface } : {}),
       ...(options.port !== undefined ? { port: options.port } : {}),
       ...(options.host !== undefined ? { host: options.host } : {}),

package/src/server/generation.ts

@@ -204,6 +204,7 @@ export class Generation {
           principal,
           clientLabel,
           ...(this.#deps.version ? { version: this.#deps.version } : {}),
+          ...(this.#deps.remoteClients ? { remoteClients: true } : {}),
         }),
       {
         onerror: (error: Error) =>

package/src/server/generations.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. */

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;
@@ -218,13 +226,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 +247,6 @@ export function startHarness(options: HarnessOptions): Harness {
       }
     : null;
 
-  const log = options.log ?? silentLogger();
-
   const nothing = () => Promise.resolve();
   const generations = new Generations(
     { profiles, close: nothing },

package/src/server/index.ts

@@ -1,4 +1,4 @@
-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';
@@ -51,6 +51,34 @@ export interface ServerOptions {
   readonly allowedHostnames?: readonly string[] | 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';
 
@@ -174,16 +202,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]),
             },
           },
         );

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/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
@@ -95,6 +95,27 @@ 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,
@@ -111,6 +132,11 @@ 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.
+ *
  * 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 +144,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 = 2300;
 
 /** Which of the owner-layer providers this principal can actually reach. */
 function ownerProviders(merged: ReadonlyMap<string, MergedCapability>): string[] {
@@ -172,6 +198,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 +214,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

@@ -53,6 +53,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. */