feat(auth): add the device grant protocol and token binding checks

Author: chajac

src/core/deviceAuth/pollState.test.ts

@@ -0,0 +1,160 @@
+import { describe, expect, it } from "bun:test";
+
+import { nextPollStep, slowDownIncrementMs } from "./pollState.js";
+import type { DeviceTokens, PollState } from "./types.js";
+
+const state: PollState = { intervalMs: 5_000, deadlineMs: 300_000 };
+
+const tokens: DeviceTokens = {
+  accessToken: "access",
+  refreshToken: "refresh",
+  expiresAt: undefined,
+  organizationId: undefined,
+};
+
+describe("nextPollStep", () => {
+  it("finishes when the response carries tokens", () => {
+    const step = nextPollStep(state, { kind: "tokens", tokens }, 0);
+
+    expect(step).toEqual({ action: "done", tokens });
+  });
+
+  it("finishes on tokens even after the deadline has passed", () => {
+    const step = nextPollStep(state, { kind: "tokens", tokens }, 300_001);
+
+    expect(step).toEqual({ action: "done", tokens });
+  });
+
+  it("polls again at the current interval while authorization is pending", () => {
+    const step = nextPollStep(state, { kind: "pending" }, 0);
+
+    expect(step).toEqual({ action: "poll", delayMs: 5_000, state });
+  });
+
+  it("raises the interval by five seconds on slow-down", () => {
+    const step = nextPollStep(state, { kind: "slow-down" }, 0);
+
+    expect(step).toEqual({
+      action: "poll",
+      delayMs: 5_000 + slowDownIncrementMs,
+      state: { intervalMs: 5_000 + slowDownIncrementMs, deadlineMs: 300_000 },
+    });
+  });
+
+  it("keeps the raised interval for later pending responses", () => {
+    const slowed = nextPollStep(state, { kind: "slow-down" }, 0);
+    if (slowed.action !== "poll") throw Error("expected to keep polling");
+
+    const step = nextPollStep(slowed.state, { kind: "pending" }, 0);
+
+    expect(step).toEqual({
+      action: "poll",
+      delayMs: 10_000,
+      state: slowed.state,
+    });
+  });
+
+  it("fails when the person rejects the request", () => {
+    const step = nextPollStep(state, { kind: "denied" }, 0);
+
+    expect(step).toEqual({
+      action: "fail",
+      reason: "access-denied",
+      detail: undefined,
+    });
+  });
+
+  it("fails when the device code expires", () => {
+    const step = nextPollStep(state, { kind: "expired" }, 0);
+
+    expect(step).toEqual({
+      action: "fail",
+      reason: "expired",
+      detail: undefined,
+    });
+  });
+
+  it("times out once the deadline passes, however long the server stalls", () => {
+    const step = nextPollStep(state, { kind: "pending" }, 300_001);
+
+    expect(step).toEqual({
+      action: "fail",
+      reason: "timeout",
+      detail: undefined,
+    });
+  });
+
+  it("keeps polling at the deadline itself", () => {
+    const step = nextPollStep(state, { kind: "pending" }, 300_000);
+
+    expect(step).toEqual({ action: "poll", delayMs: 5_000, state });
+  });
+
+  it("retries a server it could not reach, at double the interval", () => {
+    const step = nextPollStep(state, { kind: "unreachable", detail: "x" }, 0);
+
+    expect(step).toEqual({
+      action: "poll",
+      delayMs: 10_000,
+      state: { intervalMs: 10_000, deadlineMs: 300_000 },
+    });
+  });
+
+  it("doubles again while it still cannot reach the server", () => {
+    const first = nextPollStep(state, { kind: "unreachable", detail: "x" }, 0);
+    if (first.action !== "poll") throw Error("expected to keep polling");
+
+    const second = nextPollStep(
+      first.state,
+      { kind: "unreachable", detail: "x" },
+      0,
+    );
+
+    expect(second).toEqual({
+      action: "poll",
+      delayMs: 20_000,
+      state: { intervalMs: 20_000, deadlineMs: 300_000 },
+    });
+  });
+
+  it("keeps the backed-off interval once the server answers again", () => {
+    const backedOff = nextPollStep(
+      state,
+      { kind: "unreachable", detail: "x" },
+      0,
+    );
+    if (backedOff.action !== "poll") throw Error("expected to keep polling");
+
+    const step = nextPollStep(backedOff.state, { kind: "pending" }, 0);
+
+    expect(step).toEqual({
+      action: "poll",
+      delayMs: 10_000,
+      state: backedOff.state,
+    });
+  });
+
+  it("stops retrying an unreachable server once the deadline passes", () => {
+    const step = nextPollStep(
+      state,
+      { kind: "unreachable", detail: "x" },
+      300_001,
+    );
+
+    expect(step).toEqual({
+      action: "fail",
+      reason: "timeout",
+      detail: undefined,
+    });
+  });
+
+  it("fails with the detail from an unexpected error", () => {
+    const step = nextPollStep(state, { kind: "error", detail: "boom" }, 0);
+
+    expect(step).toEqual({
+      action: "fail",
+      reason: "network",
+      detail: "boom",
+    });
+  });
+});

src/core/deviceAuth/pollState.ts

@@ -0,0 +1,68 @@
+import type { PollResponse, PollState, PollStep } from "./types.js";
+
+/**
+ * The increase lasts for the rest of the flow. Treating it as a one-off skip
+ * would return to the very rate the server just objected to.
+ */
+export const slowDownIncrementMs = 5_000;
+
+/**
+ * RFC 8628 asks a client meeting a connection error to slow down before
+ * retrying, and recommends doubling. Persists for the rest of the flow: a
+ * network that dropped one request is likelier to drop the next.
+ */
+const unreachableBackoffFactor = 2;
+
+/** Pure, so the protocol is testable without a clock or a socket. */
+export function nextPollStep(
+  state: PollState,
+  response: PollResponse,
+  nowMs: number,
+): PollStep {
+  // Tokens win over the deadline. An approval that lands as the code expires is
+  // still an approval, and rejecting it would strand someone who just finished.
+  if (response.kind === "tokens") {
+    return { action: "done", tokens: response.tokens };
+  }
+
+  if (nowMs > state.deadlineMs) {
+    return { action: "fail", reason: "timeout", detail: undefined };
+  }
+
+  switch (response.kind) {
+    case "pending":
+      return { action: "poll", delayMs: state.intervalMs, state };
+
+    case "slow-down": {
+      const slowed: PollState = {
+        intervalMs: state.intervalMs + slowDownIncrementMs,
+        deadlineMs: state.deadlineMs,
+      };
+      return { action: "poll", delayMs: slowed.intervalMs, state: slowed };
+    }
+
+    case "denied":
+      return { action: "fail", reason: "access-denied", detail: undefined };
+
+    case "expired":
+      return { action: "fail", reason: "expired", detail: undefined };
+
+    // Retryable, unlike `error`. The person has often already approved in the
+    // browser by now, so abandoning the flow over one dropped request would
+    // throw away work they have done and cannot see failing.
+    case "unreachable": {
+      const backedOff: PollState = {
+        intervalMs: state.intervalMs * unreachableBackoffFactor,
+        deadlineMs: state.deadlineMs,
+      };
+      return {
+        action: "poll",
+        delayMs: backedOff.intervalMs,
+        state: backedOff,
+      };
+    }
+
+    case "error":
+      return { action: "fail", reason: "network", detail: response.detail };
+  }
+}

src/core/deviceAuth/resource.test.ts

@@ -0,0 +1,49 @@
+import { describe, expect, it } from "bun:test";
+
+import { apiResource, sameIssuer } from "./resource.js";
+
+describe("apiResource", () => {
+  it("is the deployment origin followed by /api", () => {
+    expect(apiResource("https://app.qawolf.com")).toBe(
+      "https://app.qawolf.com/api",
+    );
+  });
+
+  it("keeps the port, which is part of the deployment's identity", () => {
+    expect(apiResource("http://localhost:3000")).toBe(
+      "http://localhost:3000/api",
+    );
+  });
+
+  it("does not double a slash the host url carries", () => {
+    expect(apiResource("https://app.qawolf.com/")).toBe(
+      "https://app.qawolf.com/api",
+    );
+  });
+
+  it("ignores a path on the host url; the resource is the origin's", () => {
+    expect(apiResource("https://app.qawolf.com/some/page")).toBe(
+      "https://app.qawolf.com/api",
+    );
+  });
+});
+
+describe("sameIssuer", () => {
+  it("matches an issuer regardless of a trailing slash", () => {
+    expect(
+      sameIssuer("https://signin.example/", "https://signin.example"),
+    ).toBe(true);
+  });
+
+  it("does not match a different host", () => {
+    expect(sameIssuer("https://signin.example", "https://other.example")).toBe(
+      false,
+    );
+  });
+
+  it("does not match a different scheme", () => {
+    expect(sameIssuer("http://signin.example", "https://signin.example")).toBe(
+      false,
+    );
+  });
+});

src/core/deviceAuth/resource.ts

@@ -0,0 +1,21 @@
+/**
+ * The API resource a deployment's tokens must be bound to: its origin followed
+ * by `/api`. The API derives the same string from its own configured origin, so
+ * scheme, host and port all have to agree, and `/api/` is a different string.
+ */
+export function apiResource(hostUrl: string): string {
+  return new URL("/api", hostUrl).href;
+}
+
+function withoutTrailingSlash(url: string): string {
+  return url.replace(/\/+$/, "");
+}
+
+/**
+ * Issuers compare as strings once a trailing slash is discounted. Anything
+ * looser — case folding, resolving a path — would let one server's metadata
+ * or token pass for another's.
+ */
+export function sameIssuer(a: string, b: string): boolean {
+  return withoutTrailingSlash(a) === withoutTrailingSlash(b);
+}