@lanes-sh/link 0.7.2 → 0.9.0

package/src/auth/index.ts

@@ -28,13 +28,61 @@ import type { SecretRef, SecretStore } from '#secrets';
 export interface Principal {
   readonly id: string;
   readonly profile: string;
-  readonly kind: 'owner';
+  readonly kind: 'owner' | 'member' | 'machine';
+  /**
+   * Every profile this caller may reach, or `undefined` for "all of them".
+   *
+   * `undefined` is the machine token and the stdio pipe: neither is a person,
+   * both reach the whole workspace, and saying so explicitly is better than
+   * enumerating a list that would then need keeping in step. A `member` always
+   * carries a list, because the list *is* the delegation (ADR-060).
+   */
+  readonly profiles?: readonly string[] | undefined;
 }
 
 export function ownerPrincipal(profile: string): Principal {
   return { id: `${profile}:owner`, profile, kind: 'owner' };
 }
 
+/**
+ * A person, and the profiles whose `members:` name them.
+ *
+ * `profile` carries the one this call is acting within, which is what the audit
+ * log records and what policy is evaluated against. `profiles` is the whole set
+ * they may choose from, and `mayReach` is the check — kept here rather than in
+ * the dispatcher so discovery and enforcement cannot answer it differently,
+ * which is the same rule `allowedConnections` follows on the capability axis.
+ */
+export function memberPrincipal(
+  subject: string,
+  profile: string,
+  profiles: readonly string[],
+): Principal {
+  return { id: subject, profile, kind: 'member', profiles };
+}
+
+/**
+ * The same caller, acting within a different profile.
+ *
+ * An endpoint serves several profiles and a principal is built once, from the
+ * primary — so the profile on it is where the *connection* was opened, not
+ * where this call is going. Every dispatch has to say which, because
+ * `principal.profile` is what the audit event records and what `mayReach` is
+ * checked against; without this the log attributes a member's call to a profile
+ * they may never have been able to reach.
+ *
+ * It does not widen anything. `profiles` carries over untouched, so a name this
+ * caller may not reach is still refused — one step later, by the check below.
+ */
+export function forProfile(principal: Principal, profile: string): Principal {
+  return principal.profile === profile ? principal : { ...principal, profile };
+}
+
+/** Whether this caller may act within the named profile. */
+export function mayReach(principal: Principal, profile: string): boolean {
+  return principal.profiles === undefined || principal.profiles.includes(profile);
+}
+
 export type AuthOutcome =
   | { readonly ok: true; readonly principal: Principal }
   | { readonly ok: false; readonly reason: 'missing' | 'malformed' | 'invalid' | 'not_configured' };
@@ -215,7 +263,15 @@ export {
   type ChallengeError,
   type ResourceIdentity,
 } from './oauth/metadata.ts';
-export { OAuthServer, pkceChallengeFor, type AuthorizeRequest, type OAuthResult } from './oauth/server.ts';
+export {
+  OAuthServer,
+  pkceChallengeFor,
+  type EndpointIdentity,
+  type Federation,
+  type OAuthResult,
+} from './oauth/server.ts';
+export { AssertionVerifier, type Assertion } from './lanes/assertion.ts';
+export { lanesFederation, DEFAULT_WEB_URL, type FederationOptions } from './lanes/federation.ts';
 export { matchesRegistered } from './oauth/redirects.ts';
 export { OAuthStore, hashToken, randomToken } from './oauth/store.ts';
 export { OidcVerifier, type OidcVerifierOptions, type VerifiedSubject } from './oidc.ts';

package/src/auth/lanes/assertion.ts

@@ -0,0 +1,256 @@
+import type { FetchLike } from './login.ts';
+
+/**
+ * Verifying that lanes.sh vouched for the person at the browser.
+ *
+ * This is what replaces the pasted endpoint token on the consent screen
+ * (ADR-062). The endpoint no longer asks "do you hold the owner's credential" —
+ * it asks lanes.sh "who is this", and gets back a signed statement it can check
+ * without trusting the browser that carried it.
+ *
+ * Four checks, and each of them is load-bearing:
+ *
+ *  - **Signature**, against the API's published JWKS. Without it the assertion
+ *    is a string the browser handed us and anyone could write one.
+ *  - **Audience**, which must be *this endpoint's own resource URL*. An
+ *    assertion minted for somebody else's endpoint is a valid assertion; using
+ *    it here is the confused-deputy case the MCP authorization spec calls out,
+ *    and this is the only thing that stops it.
+ *  - **Nonce**, single-use, minted by this endpoint when the flow began. It
+ *    binds the assertion to *this* authorization request, so one captured on a
+ *    different endpoint of ours cannot be replayed into this one.
+ *  - **Expiry**, tight. The assertion crosses one redirect, so a minute is
+ *    generous and anything longer is a bearer credential in a browser history.
+ *
+ * Verification is intentionally a public-key check and not a call back to the
+ * API. The endpoint may be behind somebody's firewall; it must be able to
+ * verify while only ever having *fetched* a key, and a cached JWKS makes the
+ * whole flow work with the API unreachable for the length of the cache.
+ *
+ * No JWT library. RS256 over a JWK is `crypto.subtle.importKey` plus
+ * `crypto.subtle.verify`, which is 30 lines and no supply chain — the same
+ * reasoning that has `connectivity/auth/oauth-jwt/key.ts` signing with subtle
+ * rather than pulling one in.
+ */
+
+/** What an assertion says once it has been believed. */
+export interface Assertion {
+  /** `lanes:<uid>`, the same string `lanes auth login` stores and `members:` names. */
+  readonly subject: string;
+  readonly email: string | null;
+}
+
+export interface AssertionVerifierOptions {
+  /** Where the signing keys are published. */
+  readonly jwksUrl: string;
+  /** Who is allowed to have signed. Checked against `iss`. */
+  readonly issuer: string;
+  readonly fetch?: FetchLike | undefined;
+  readonly now?: (() => number) | undefined;
+  /** How long a fetched key set is reused. */
+  readonly cacheTtlMs?: number | undefined;
+}
+
+/**
+ * One published key, as it arrives.
+ *
+ * Loose on purpose: `importKey` is the thing that decides whether a JWK is
+ * usable, and re-deciding that here with a stricter type would mean a key the
+ * platform accepts being dropped by our own schema.
+ */
+type Jwk = Record<string, unknown> & { kid?: unknown; kty?: unknown; alg?: unknown };
+
+/** An hour. A key rotation is noticed within it, and a miss refetches anyway. */
+const DEFAULT_CACHE_TTL_MS = 60 * 60_000;
+
+/**
+ * The shortest interval between two refetches provoked by an unknown key id.
+ *
+ * Without it, a token naming a key that does not exist costs a round trip to
+ * the API — and since anyone can send one unauthenticated, every endpoint
+ * becomes an amplifier pointed at us. A minute bounds that at one request per
+ * endpoint per minute while still letting a genuine rotation land promptly.
+ */
+const MISS_REFETCH_MS = 60_000;
+
+/** Assertions cross one redirect; more than this is a credential left lying about. */
+const MAX_LIFETIME_MS = 120_000;
+
+/** Clocks differ. Small enough that it does not extend the window meaningfully. */
+const CLOCK_SKEW_MS = 30_000;
+
+/** What `importKey('jwk', …)` takes, without depending on a lib.dom global. */
+type JsonWebKeyLike = Parameters<typeof crypto.subtle.importKey>[1] extends infer T
+  ? Extract<T, { kty?: string | undefined }>
+  : never;
+
+export class AssertionVerifier {
+  readonly #options: AssertionVerifierOptions;
+  readonly #fetch: FetchLike;
+  readonly #now: () => number;
+  #keys: { at: number; byKid: Map<string, CryptoKey> } | null = null;
+  #missedAt = Number.NEGATIVE_INFINITY;
+
+  constructor(options: AssertionVerifierOptions) {
+    this.#options = options;
+    this.#fetch = options.fetch ?? ((input, init) => globalThis.fetch(input, init));
+    this.#now = options.now ?? Date.now;
+  }
+
+  /**
+   * The person this assertion names, or null.
+   *
+   * Null rather than a reason. The caller renders an error page to whoever is
+   * at the browser, and "the signature did not verify" versus "the audience was
+   * wrong" tells an attacker which of their attempts got closer while telling a
+   * legitimate user nothing they can act on. What *is* actionable — expiry — is
+   * the one case the caller can infer by retrying.
+   */
+  async verify(token: string, expected: { audience: string; nonce: string }): Promise<Assertion | null> {
+    const parts = token.split('.');
+    if (parts.length !== 3) return null;
+
+    const [encodedHeader, encodedPayload, encodedSignature] = parts as [string, string, string];
+
+    const header = decodeJson(encodedHeader);
+    const payload = decodeJson(encodedPayload);
+    if (header === null || payload === null) return null;
+
+    // Pinned, not read. `alg` arrives inside the token, so honouring it is how
+    // the `none` algorithm and the HMAC-with-the-public-key confusions work.
+    if (header['alg'] !== 'RS256') return null;
+
+    const kid = typeof header['kid'] === 'string' ? header['kid'] : null;
+    if (kid === null) return null;
+
+    const key = await this.#key(kid);
+    if (key === null) return null;
+
+    const signed = new TextEncoder().encode(`${encodedHeader}.${encodedPayload}`);
+    const signature = base64url(encodedSignature);
+    if (signature === null) return null;
+
+    const valid = await crypto.subtle.verify(
+      { name: 'RSASSA-PKCS1-v1_5' },
+      key,
+      signature,
+      signed,
+    );
+    if (!valid) return null;
+
+    return this.#claims(payload, expected);
+  }
+
+  /** Everything that is true of a verified signature but not yet of this token. */
+  #claims(payload: Record<string, unknown>, expected: { audience: string; nonce: string }): Assertion | null {
+    if (payload['iss'] !== this.#options.issuer) return null;
+
+    // Exact match, per RFC 8707. A prefix or suffix comparison here would admit
+    // an assertion minted for a different endpoint on the same host.
+    const audience = payload['aud'];
+    const audiences = Array.isArray(audience) ? audience : [audience];
+    if (!audiences.includes(expected.audience)) return null;
+
+    if (payload['nonce'] !== expected.nonce) return null;
+
+    const now = this.#now();
+    const exp = typeof payload['exp'] === 'number' ? payload['exp'] * 1000 : 0;
+    const iat = typeof payload['iat'] === 'number' ? payload['iat'] * 1000 : 0;
+
+    if (exp <= now - CLOCK_SKEW_MS) return null;
+    if (iat > now + CLOCK_SKEW_MS) return null;
+
+    // Checked here as well as trusted from the issuer. A deployment that
+    // widened its own expiry would silently turn a redirect-scoped assertion
+    // into a long-lived bearer token, and this endpoint is the party that has
+    // to live with that.
+    if (exp - iat > MAX_LIFETIME_MS + CLOCK_SKEW_MS) return null;
+
+    const subject = payload['sub'];
+    if (typeof subject !== 'string' || subject.length === 0) return null;
+
+    return {
+      // The API signs the raw uid; the prefix is added at exactly one place in
+      // the client, here and in `login.ts`, so the two cannot disagree about
+      // what a subject looks like.
+      subject: subject.startsWith('lanes:') ? subject : `lanes:${subject}`,
+      email: typeof payload['email'] === 'string' ? payload['email'] : null,
+    };
+  }
+
+  /**
+   * The signing key with that id.
+   *
+   * A miss against a warm cache refetches, because that is what a key rotation
+   * looks like from here and the alternative is every endpoint refusing until
+   * its cache lapses. It refetches at most once a minute, because the *other*
+   * thing a miss looks like is an invented key id, and those arrive
+   * unauthenticated and as fast as anyone cares to send them.
+   */
+  async #key(kid: string): Promise<CryptoKey | null> {
+    const ttl = this.#options.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS;
+    const now = this.#now();
+    const fresh = this.#keys !== null && now - this.#keys.at < ttl;
+
+    if (fresh) {
+      const hit = this.#keys?.byKid.get(kid);
+      if (hit) return hit;
+      if (now - this.#missedAt < MISS_REFETCH_MS) return null;
+      this.#missedAt = now;
+    }
+
+    const loaded = await this.#load();
+    return loaded.get(kid) ?? null;
+  }
+
+  async #load(): Promise<Map<string, CryptoKey>> {
+    const byKid = new Map<string, CryptoKey>();
+
+    const response = await this.#fetch(this.#options.jwksUrl).catch(() => null);
+    if (response === null || !response.ok) {
+      // Left uncached, so the next attempt tries again rather than treating an
+      // outage as "there are no keys" for an hour. Whatever was already known
+      // still answers, which is what keeps a verified endpoint working while
+      // the API is down.
+      return this.#keys?.byKid ?? byKid;
+    }
+
+    const body = (await response.json().catch(() => ({}))) as { keys?: Jwk[] };
+
+    for (const jwk of body.keys ?? []) {
+      if (jwk.kty !== 'RSA' || (jwk.alg !== undefined && jwk.alg !== 'RS256')) continue;
+      if (typeof jwk.kid !== 'string') continue;
+
+      const key = await crypto.subtle
+        .importKey('jwk', jwk as JsonWebKeyLike, { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' }, false, [
+          'verify',
+        ])
+        .catch(() => null);
+
+      if (key !== null) byKid.set(jwk.kid, key);
+    }
+
+    this.#keys = { at: this.#now(), byKid };
+    return byKid;
+  }
+}
+
+function base64url(value: string): ArrayBuffer | null {
+  try {
+    const bytes = Buffer.from(value, 'base64url');
+    return bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength) as ArrayBuffer;
+  } catch {
+    return null;
+  }
+}
+
+function decodeJson(value: string): Record<string, unknown> | null {
+  const bytes = base64url(value);
+  if (bytes === null) return null;
+  try {
+    const parsed: unknown = JSON.parse(new TextDecoder().decode(bytes));
+    return typeof parsed === 'object' && parsed !== null ? (parsed as Record<string, unknown>) : null;
+  } catch {
+    return null;
+  }
+}

package/src/auth/lanes/callback.ts

@@ -0,0 +1,135 @@
+/**
+ * The loopback listener a browser comes back to, and nothing else.
+ *
+ * Split from `login.ts` because the two have one value between them — an
+ * authorization code — and everything else they know is disjoint. This file
+ * knows about sockets, `state`, and the page somebody is left looking at; it
+ * knows nothing about Google, Firebase, or where a session is stored.
+ */
+
+/** What the browser should be told, for whoever is rendering it. */
+export interface LandingPage {
+  readonly ok: boolean;
+  /** One line. The reason, when something went wrong. */
+  readonly detail: string;
+}
+
+/**
+ * Serve exactly one callback, then stop.
+ *
+ * Bound to `127.0.0.1` on a port the kernel picks, which is RFC 8252's loopback
+ * redirect. Google matches loopback by host and ignores the port, so nothing
+ * has to be registered per machine — the property `link_auth.py`'s
+ * `_is_loopback_redirect` relies on at the other end.
+ */
+export async function awaitCallback(
+  state: string,
+  onListening: (redirectUri: string) => Promise<void>,
+  render: (outcome: LandingPage) => Response,
+): Promise<{ code: string; redirectUri: string }> {
+  const page = (outcome: LandingPage): Response => closing(render(outcome));
+  const { promise, resolve, reject } = Promise.withResolvers<string>();
+
+  const server = Bun.serve({
+    hostname: '127.0.0.1',
+    port: 0,
+    fetch(request) {
+      const url = new URL(request.url);
+      // Anything else, including the favicon a browser asks for unprompted.
+      // It closes its connection too, so a stray request cannot keep the server
+      // alive past the redirect it is waiting for.
+      if (url.pathname !== '/callback') {
+        return closing(new Response('Not found', { status: 404 }));
+      }
+
+      const error = url.searchParams.get('error');
+      if (error) {
+        reject(new Error(`Google refused the sign-in: ${error}`));
+        return page({ ok: false, detail: `Google refused the sign-in: ${error}` });
+      }
+
+      // Checked before the code is read. `state` is the only thing standing
+      // between this listener and a page on the machine feeding it a code from
+      // somebody else's authorization.
+      if (url.searchParams.get('state') !== state) {
+        reject(new Error('The sign-in came back with the wrong state, so it was discarded.'));
+        return page({
+          ok: false,
+          detail: 'That sign-in came back with the wrong state, so it was discarded.',
+        });
+      }
+
+      const code = url.searchParams.get('code');
+      if (!code) {
+        reject(new Error('The sign-in came back without a code.'));
+        return page({ ok: false, detail: 'That sign-in came back without a code.' });
+      }
+
+      resolve(code);
+      return page({ ok: true, detail: 'You can close this tab and go back to your terminal.' });
+    },
+  });
+
+  const timeout = setTimeout(
+    () => reject(new Error('Timed out waiting for the browser. Nothing was changed.')),
+    300_000,
+  );
+
+  // The redirect URI is returned rather than stashed. Google checks that the
+  // exchange sends back the *same* one, and a module-level variable holding it
+  // would be shared by two logins running at once — which is not hypothetical
+  // on a machine where somebody re-runs a command that seemed to hang.
+  const redirectUri = `http://127.0.0.1:${server.port}/callback`;
+
+  try {
+    await onListening(redirectUri);
+    return { code: await promise, redirectUri };
+  } finally {
+    clearTimeout(timeout);
+
+    // Graceful, and this is the whole of the fix for a login that worked and
+    // looked like it had not. `stop(true)` closes active connections
+    // immediately, and the active connection is the one carrying the page the
+    // person is waiting to see: `resolve` runs inside the handler, before Bun
+    // has written the response, so forcing here raced the browser and won every
+    // time. What they got was a connection error on a sign-in that had already
+    // succeeded, which is the worst possible way for this to fail.
+    //
+    // Nothing can hold a graceful stop open, because every response closes its
+    // own connection — see `closing`. That is what makes this safe to await
+    // rather than force.
+    await server.stop();
+  }
+}
+
+/**
+ * `Connection: close` on whatever was rendered.
+ *
+ * Applied here rather than asked of the renderer, because it is a property of
+ * *this* listener rather than of the page. The server is torn down the moment
+ * the code arrives, and a keep-alive connection would either hold the graceful
+ * stop open or be severed mid-response — the second is what used to happen.
+ * Telling the browser not to reuse the socket makes "respond, then stop" a
+ * sequence rather than a race.
+ */
+function closing(response: Response): Response {
+  const headers = new Headers(response.headers);
+  headers.set('connection', 'close');
+  return new Response(response.body, { status: response.status, headers });
+}
+
+/**
+ * The page when nobody supplied one.
+ *
+ * Deliberately plain, and deliberately not what a person sees: `lanes auth
+ * login` passes the branded card. This is for tests, and for a caller that has
+ * no opinion about presentation.
+ */
+export function plainPage(outcome: LandingPage): Response {
+  return new Response(
+    `<!doctype html><meta charset="utf-8"><title>Lanes</title>` +
+      `<body style="font:16px system-ui;display:grid;place-items:center;height:100vh;margin:0">` +
+      `<p>${outcome.ok ? 'Signed in.' : 'That did not work.'} ${outcome.detail}</p></body>`,
+    { headers: { 'content-type': 'text/html; charset=utf-8' } },
+  );
+}

package/src/auth/lanes/federation.ts

@@ -0,0 +1,50 @@
+import { AssertionVerifier } from './assertion.ts';
+import { DEFAULT_API_URL } from './login.ts';
+import type { Federation } from '../oauth/server.ts';
+
+/**
+ * The Lanes side of an endpoint's authorization, assembled.
+ *
+ * Three URLs and a membership lookup. It lives here rather than in
+ * `server/endpoint.ts` so that "who does this endpoint believe about identity"
+ * is one file with one answer, and so that a self-hoster changing it changes
+ * one thing — which is the same reasoning that keeps `oidc` a URL in config
+ * rather than a branch in the code.
+ *
+ * **Both URLs are overridable and neither is a vendor name in the request
+ * path.** `LANES_API_URL` and `LANES_WEB_URL` are what a self-hosted
+ * deployment sets, and they are also what makes `lanes dev` work against the
+ * API running on this machine.
+ */
+
+/** Where the consent page lives, unless told otherwise. */
+export const DEFAULT_WEB_URL = 'https://lanes.sh';
+
+export interface FederationOptions {
+  /** Which profiles a subject may consume, read at the moment a token is minted. */
+  readonly profilesFor: (subject: string) => Promise<readonly string[]>;
+  readonly apiUrl?: string | undefined;
+  readonly webUrl?: string | undefined;
+  /** Injected for tests. Nothing in production passes one. */
+  readonly fetch?: ConstructorParameters<typeof AssertionVerifier>[0]['fetch'];
+}
+
+export function lanesFederation(options: FederationOptions): Federation {
+  const apiUrl = options.apiUrl ?? process.env['LANES_API_URL'] ?? DEFAULT_API_URL;
+  const webUrl = options.webUrl ?? process.env['LANES_WEB_URL'] ?? DEFAULT_WEB_URL;
+
+  const verifier = new AssertionVerifier({
+    jwksUrl: `${apiUrl}/.well-known/jwks.json`,
+    // The API is the issuer of the assertion, and the audience is *us*. Getting
+    // these the wrong way round is the mistake that makes both checks
+    // decorative, so they are named rather than positional.
+    issuer: apiUrl,
+    ...(options.fetch ? { fetch: options.fetch } : {}),
+  });
+
+  return {
+    consentUrl: `${webUrl}/link/authorize`,
+    verify: (assertion, expected) => verifier.verify(assertion, expected),
+    profilesFor: options.profilesFor,
+  };
+}