@lanes-sh/link 0.2.1 → 0.3.0

package/README.md

@@ -48,8 +48,8 @@ Needs [Bun](https://bun.com) 1.3.11+. Nothing else — no account anywhere.
 
 ```console
 $ bun install -g @lanes-sh/link                # puts `lanes` on your PATH
-$ lanes link profile add personal --default
-$ lanes link start
+$ lanes link profile add personal --target local
+$ lanes link start --profile personal --target local
 ok    serving http://127.0.0.1:7337/mcp
       profiles: personal
 ```
@@ -57,7 +57,7 @@ ok    serving http://127.0.0.1:7337/mcp
 Then, in another shell:
 
 ```console
-$ lanes link mcp add                           # every agent installed; or name one: claude, codex
+$ lanes link mcp add --profile personal --target local                           # every agent installed; or name one: claude, codex
 ok    registered lanes-link with Claude Code (user scope)
 ok    registered lanes-link with Codex
 ```
@@ -78,6 +78,17 @@ calendar are the next step. **[Full quickstart →](docs/quickstart.md)**
 Memory and skills are plain Markdown files, so a text editor and an agent reach the same bytes. All
 four belong to one profile: what you add under `work` is invisible under `personal`.
 
+Keep those two in a private GitHub repository instead of on this machine, and get history, diffs,
+and the same notes from anywhere you run this:
+
+```console
+$ lanes link knowledge use github --repo <owner/name> --migrate
+```
+
+It moves what you have already stored, in one commit, and `lanes link knowledge use local
+--migrate` brings it back. Nothing else moves — your credentials and your vault stay where they
+are, and there is no setting that would put them in a repository.
+
 ## Connect an account
 
 One command per account. Run it again to add a second mailbox, a second calendar, a second anything.
@@ -99,15 +110,17 @@ One command per account. Run it again to add a second mailbox, a second calendar
 | Linear | `lanes link connect linear` |
 | GitHub | `lanes link connect github` |
 | Slack | `lanes link connect slack` |
+| Gmail (IMAP, app password) | `lanes link connect gmail_imap` |
 | Gmail (Google MCP) | `lanes link connect gmail_mcp` |
 | Drive (Google MCP) | `lanes link connect drive_mcp` |
 
 Three things worth knowing up front. `lanes link connect icloud` sets up Mail, Calendar, and
-Contacts together, because one app-specific password covers all three. Google needs no OAuth client
-of your own: `lanes link connect gmail` authorises against the one Lanes operates, so there is no
-Cloud console to visit — add `--own-client` if you would rather register your own. And GitHub and
-Slack take a token you paste rather than a browser sign-in, because neither will register a client
-for us; for Slack that means creating a Slack app once, which is the one console visit left here.
+Contacts together, because one app-specific password covers all three. Google and Slack need no
+OAuth client of your own: both authorise against the one Lanes operates, so there is no console to
+visit — for Google, add `--own-client` if you would rather register your own, or take a service
+account key or an app password over IMAP where you would rather nothing expired. And GitHub takes a
+token you paste rather than a browser sign-in, because it will not register a client for us; that
+is the one console visit left here.
 
 Full guide — what each one gives your agent, what it needs, and adding your own:
 **[docs/connect.md](docs/connect.md)**.

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

@@ -24,6 +24,13 @@ is listed first.** Quietly picking one crosses the line the profile exists to
 draw. There is no "current profile" to switch — the choice is made per call, and
 `lanes link profile list` shows what exists.
 
+**Every `lanes link` command names its profile and its target.** Both are required
+flags with no default, no environment variable, and nothing in a config file
+behind them, so a command missing either refuses rather than acting somewhere
+else. When you write one out for the owner, either fill both in or leave them as
+`<name>` for them to complete — never drop them. `lanes link target list
+--profile <name>` shows what a profile declares.
+
 A `connection` names an account within that profile. One profile may hold
 several of the same kind, and naming a connection belonging to a *different*
 profile is refused rather than guessed at.
@@ -37,7 +44,7 @@ try more than one wording before deciding it is not there.
 Writing is a separate grant, and it should be. What you write is served back to
 every later session, including to a different agent, so **write when you are
 asked to remember something, not as a habit.** The owner reaches the same
-entries with `lanes link memory list` and a text editor.
+entries with `lanes link memory list --profile <name> --target <name>` and a text editor.
 
 ## Skills are theirs, not yours
 
@@ -47,7 +54,7 @@ cannot read a skill's body; that is deliberate, not a gap to work around.
 
 So when a task has a skill for it, **say the skill exists and let them invoke
 it** rather than improvising your own version of their procedure. They manage
-these with `lanes link skills list` and `lanes link skills show <name>`.
+these with `lanes link skills list --profile <name> --target <name>` and `lanes link skills show <skill> --profile <name> --target <name>`.
 
 ## Vault values are credentials
 
@@ -55,6 +62,27 @@ Use one to do the thing that needs it. Never quote it back, summarise it, echo
 it into a file, or paste it into a command whose output you will show. If a
 value has been printed by accident, say so.
 
+## Who you are writing as is declared, not inferred
+
+A profile may declare the names, addresses and handles its owner wants used when
+something is written as them. Call `identity_list` for the profile in play
+before signing a message, choosing an address to send from, or attributing work
+to a handle — **do not** read a name off the conversation, off a previous
+message's signature, or off the account label on a connection. That label is the
+identity a provider reports for a mailbox; it is not necessarily what they sign
+with.
+
+A profile may declare several of a kind on purpose. The first is the default and
+each carries a note saying when to prefer it, so read the notes rather than
+picking the first unconditionally. If none of them fits what you are doing, ask
+— do not combine two, and do not carry one profile's name into another. That
+crossing is the specific mistake this exists to prevent.
+
+If the tool is not there, the profile has declared nothing. Ask rather than
+inventing something; they add one with `lanes link identity add <kind> <value> --profile <profile>
+--target <target>` — both flags, because neither has a fallback.
+Nothing you can call writes here, deliberately.
+
 ## Attachments are named, not carried
 
 Where a tool takes `attachments`, each entry names **one** source and the endpoint
@@ -84,7 +112,7 @@ its content.
 
 **If the endpoint is not on the same machine as the file**, `path` names the
 *server's* filesystem rather than theirs, and will not find it. Ask them to run
-`lanes link attach <file> --connection <provider>.<account>`, which prints a
+`lanes link attach <file> --profile <name> --target <name> --connection <provider>.<account>`, which prints a
 handle to use instead.
 
 **`draft_only: true`** saves instead of sending, where they should see it before
@@ -104,9 +132,9 @@ granted, and retrying will not reveal it. A call that *is* refused was refused b
 policy on purpose.
 
 Report it plainly and let the owner decide whether to widen the grant —
-`lanes link policy list` shows the rules, `lanes link policy allow <capability>`
+`lanes link policy list --profile <name>` shows the rules, `lanes link policy allow <capability> --profile <name> --target <name>`
 changes them, and that is their call, not yours. **Do not look for another route
-to the same data.** Every call is audited either way; `lanes link audit tail`
+to the same data.** Every call is audited either way; `lanes link audit tail --profile <name> --target <name>`
 shows what was attempted, refusals included.
 
 ## Setting something up
@@ -125,9 +153,9 @@ credential — those are `lanes link` in a terminal, deliberately. What you can
 know exactly what to hand over, and say what it will ask for before they start.
 
 If you have a shell, you can run it yourself for anything that does *not* need a
-browser: `lanes link setup plan <provider> --json` lists what to store,
-`lanes link secrets set <ref>` takes the value on stdin, and
-`lanes link connect <provider> --id <name> --non-interactive --json` finishes.
+browser: `lanes link setup plan <provider> --profile <name> --target <name> --json` lists what to store,
+`lanes link secrets set <ref> --profile <name> --target <name>` takes the value on stdin, and
+`lanes link connect <provider> --profile <name> --target <name> --id <id> --non-interactive --json` finishes.
 Anything with a browser sign-in belongs to whoever owns the account — give them
 the line.
 
@@ -139,10 +167,10 @@ straight after connecting will still not show it. Say so rather than retrying.
 
 ## Registering it, and re-registering it
 
-`lanes link mcp add` runs each harness's own registration command and installs
+`lanes link mcp add --profile <name> --target <name>` runs each harness's own registration command and installs
 this skill where that harness keeps them. With no argument it does every harness
 installed; name one (`claude`, `codex`) to be specific. Run it again after
-`lanes link token rotate` — add `--force`, since Claude Code stores the token as
+`lanes link token rotate --profile <name> --target <name>` — add `--force`, since Claude Code stores the token as
 a value rather than a command.
 
 **Never paste the token.** There is a right way and a wrong way, and the
@@ -151,7 +179,7 @@ difference matters:
 ```bash
 # RIGHT — the token goes from the CLI to the harness. You never see it.
 claude mcp add --transport http lanes-link http://127.0.0.1:7337/mcp \
-  --header "Authorization: Bearer $(lanes link token show --raw)"
+  --header "Authorization: Bearer $(lanes link token show --raw --profile <name> --target <name>)"
 
 # WRONG — the token is now in your context, and in the transcript, forever.
 lanes link token show --show          # then copying the value into the command
@@ -159,9 +187,9 @@ lanes link token show --show          # then copying the value into the command
 
 The token reaches every account of every profile the endpoint serves. Use the
 substitution form. If you have already printed one by accident, say so and offer
-`lanes link token rotate`.
+`lanes link token rotate --profile <name> --target <name>`.
 
-Prefer `lanes link mcp add` to writing the command yourself: it checks the
+Prefer `lanes link mcp add --profile <name> --target <name>` to writing the command yourself: it checks the
 endpoint is reachable, refuses to silently shadow an existing registration, and
 cannot mistype the token. For a harness it does not know, take the command from
 `lanes link outputs` rather than writing it blind — that command checks whether
@@ -173,7 +201,7 @@ If you register Codex, tell the user to export the token — Codex stores only t
 variable name, so nothing works until it is set:
 
 ```bash
-export LANES_LINK_TOKEN="$(lanes link token show --raw)"
+export LANES_LINK_TOKEN="$(lanes link token show --raw --profile <name> --target <name>)"
 ```
 
 One registration covers every profile. Do not add one per profile; they share a
@@ -185,3 +213,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.3.0",
   "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)) {