From a61461d611156de121cbb0233fd18a0e6a767e44 Mon Sep 17 00:00:00 2001
From: Juan Cobo Betancourt <juan@neogranadina.org>
Date: Sat, 30 May 2026 09:55:42 -0700
Subject: [PATCH 1/2] Forward return_to from the login page into the GitHub
 OAuth start link

The login page dropped return_to: the "Continue with GitHub" button read
the error param but never forwarded return_to, so the OAuth start route
stored an empty github_return_to cookie and the callback redirected to
/auth instead of the deep-link destination. Read return_to from the URL
and append it (encoded) to the start link, preserving the error handling.
Add tests for the login-button forwarding (with a no-return_to parity
case) and for a forwarded return_to landing in the github_return_to cookie.
---
 app/routes/auth.login.tsx        | 18 +++++++++++++---
 tests/routes/auth.github.test.ts | 31 ++++++++++++++++++++++++++
 tests/routes/auth.login.test.ts  | 37 ++++++++++++++++++++++++++++++++
 3 files changed, 83 insertions(+), 3 deletions(-)

diff --git a/app/routes/auth.login.tsx b/app/routes/auth.login.tsx
index 5a6582f..77a1d89 100644
--- a/app/routes/auth.login.tsx
+++ b/app/routes/auth.login.tsx
@@ -12,13 +12,16 @@
  * Applies the AMPL design language: kit Button + AuthError.
  *
  * Component behaviour:
- *   - Renders a kit Button ("Continue with GitHub") → withBase("/github").
+ *   - Renders a kit Button ("Continue with GitHub") → withBase("/github"),
+ *     forwarding any ?return_to= (percent-encoded) onto the start link so the
+ *     deep-link destination survives the OAuth round-trip. Without this the
+ *     param is dropped at the button and the user lands at /auth after login.
  *   - Reads ?error= from useSearchParams() and renders AuthError with the
  *     matching errors.* i18n key via the existing t(`errors.${errorCode}`,
  *     { defaultValue }) safe pattern.
  *   - Bilingual via the common namespace (login.* + errors.*).
  *
- * @version v0.1.0
+ * @version v0.2.2
  */
 
 import { useSearchParams } from "react-router";
@@ -36,6 +39,15 @@ export default function LoginPage() {
   const [searchParams] = useSearchParams();
   const errorCode = searchParams.get("error");
 
+  // Forward the deep-link destination into the OAuth start link. Without this
+  // the param is dropped at the button, so auth.github sets an empty
+  // github_return_to cookie and the callback lands the user at /auth instead
+  // of where they were heading. Encoded so the path survives the round-trip.
+  const returnTo = searchParams.get("return_to");
+  const githubHref = withBase(
+    "/github" + (returnTo ? `?return_to=${encodeURIComponent(returnTo)}` : ""),
+  );
+
   return (
     <main className="flex flex-1 flex-col items-center justify-center px-[30px] py-20">
       <div className="w-full max-w-[400px]">
@@ -47,7 +59,7 @@ export default function LoginPage() {
           />
         )}
 
-        <Button as="a" variant="dark" href={withBase("/github")}>
+        <Button as="a" variant="dark" href={githubHref}>
           {/* Inline Octocat — official GitHub mark, white fill, no runtime dependency */}
           <svg
             aria-hidden="true"
diff --git a/tests/routes/auth.github.test.ts b/tests/routes/auth.github.test.ts
index f697660..7c1c9aa 100644
--- a/tests/routes/auth.github.test.ts
+++ b/tests/routes/auth.github.test.ts
@@ -122,6 +122,37 @@ describe("auth.github loader", () => {
     expect(returnToCookie!.attrs).toHaveProperty("path", "/auth");
   });
 
+  it("G1b: a forwarded return_to query lands (decoded) in the github_return_to cookie", async () => {
+    const returnTo = "/palaeography/invite/accept?token=abc";
+    // Unique IP so this call doesn't consume the shared "unknown"-IP rate-limit
+    // budget that the other tests rely on.
+    const { loader } = await import("~/routes/auth.github");
+    const request = new Request(
+      `https://ampl.tools/auth/github?return_to=${encodeURIComponent(returnTo)}`,
+      { headers: { "CF-Connecting-IP": "10.3.0.1" } },
+    );
+    let thrown: unknown;
+    try {
+      await loader({ request, context: buildContext(), params: {} } as any);
+    } catch (err) {
+      thrown = err;
+    }
+    if (!(thrown instanceof Response)) {
+      throw new Error(`loader did not throw a Response; got: ${String(thrown)}`);
+    }
+    const resp = thrown;
+
+    let returnToCookie: ReturnType<ReturnType<typeof parseSetCookie>["get"]>;
+    for (const raw of getAllSetCookies(resp)) {
+      const parsed = parseSetCookie(raw);
+      if (parsed.has("github_return_to")) returnToCookie = parsed.get("github_return_to");
+    }
+
+    expect(returnToCookie).toBeDefined();
+    // The cookie value is percent-encoded; decoding recovers the original path.
+    expect(decodeURIComponent(returnToCookie!.value)).toBe(returnTo);
+  });
+
   it("G2: HTTP origin (dev) emits cookies WITHOUT Secure", async () => {
     const resp = await callLoader("http://localhost:8787/auth/github");
 
diff --git a/tests/routes/auth.login.test.ts b/tests/routes/auth.login.test.ts
index e9258f2..dfcf46f 100644
--- a/tests/routes/auth.login.test.ts
+++ b/tests/routes/auth.login.test.ts
@@ -81,6 +81,43 @@ describe("auth.login page", () => {
     expect(html).toContain('href="/auth/github"');
   });
 
+  it("forwards return_to to the GitHub button href (encoded)", async () => {
+    const { default: LoginPage } = await import("~/routes/auth.login");
+    const { StaticRouter } = await import("react-router");
+
+    const returnTo = "/palaeography/invite/accept?token=abc";
+    const html = renderToString(
+      React.createElement(
+        StaticRouter,
+        { location: `/auth/login?return_to=${encodeURIComponent(returnTo)}` },
+        React.createElement(LoginPage as React.ComponentType),
+      ),
+    );
+
+    // The GitHub start link must carry the return_to, percent-encoded, so the
+    // deep-link destination survives the OAuth round-trip.
+    expect(html).toContain(
+      `href="/auth/github?return_to=${encodeURIComponent(returnTo)}"`,
+    );
+  });
+
+  it("parity: no return_to → GitHub button href stays plain /auth/github", async () => {
+    const { default: LoginPage } = await import("~/routes/auth.login");
+    const { StaticRouter } = await import("react-router");
+
+    const html = renderToString(
+      React.createElement(
+        StaticRouter,
+        { location: "/auth/login" },
+        React.createElement(LoginPage as React.ComponentType),
+      ),
+    );
+
+    // Without a return_to, the href carries no query string.
+    expect(html).toContain('href="/auth/github"');
+    expect(html).not.toContain("return_to");
+  });
+
   it("sign-in button uses the dark variant", async () => {
     const { default: LoginPage } = await import("~/routes/auth.login");
     const { StaticRouter } = await import("react-router");

From 2d4903719cd14da94bb39eec31adef714614f3db Mon Sep 17 00:00:00 2001
From: Juan Cobo Betancourt <juan@neogranadina.org>
Date: Sat, 30 May 2026 09:56:11 -0700
Subject: [PATCH 2/2] Bump @ampl/kit to 0.2.2 and document the login return_to
 fix

Service-side fix to the hosted auth login page; no change to the
@ampl/kit package API. Note the affected versions in CONSUMING.md.
---
 CONSUMING.md      | 27 +++++++++++++++++++++------
 package-lock.json |  4 ++--
 package.json      |  2 +-
 3 files changed, 24 insertions(+), 9 deletions(-)

diff --git a/CONSUMING.md b/CONSUMING.md
index f262f95..682a7c7 100644
--- a/CONSUMING.md
+++ b/CONSUMING.md
@@ -184,6 +184,17 @@ redirects there directly after login — the absolute-URL redirect avoids
 the double-prefix issue (`/auth/auth/...`) that arises when a relative
 `redirect()` path collides with React Router's basename prepend.
 
+> **Fixed in v0.2.2 — `return_to` dropped at the login button.** A
+> hosted `ampl-auth` service deployed at **v0.2.1 or earlier** dropped
+> `return_to` on the login page: the "Continue with GitHub" button did
+> not forward the param into the OAuth start link, so the callback always
+> landed the user at `/auth` instead of the deep-link destination. This is
+> a **service-side fix** — it takes effect when the shared `ampl.tools/auth`
+> service is deployed at v0.2.2, and benefits every consumer at once.
+> Consumers do not need to change any code; bumping the pinned
+> `@ampl/kit` ref to `#v0.2.2` simply keeps the vendored types in step.
+> (Calamus, pinned at `#v0.2.1`, is one affected consumer.)
+
 ---
 
 ## Git dependency — pinning and updating
@@ -506,12 +517,16 @@ The git tag is the contract for `@ampl/kit`. Consumers pin to an exact tag:
 "@ampl/kit": "github:UCSB-AMPLab/ampl-kit#v0.2.1"
 ```
 
-**This release:** `v0.2.1` exports the `send()` RPC contract (`SendMessage`,
-`SendResult`) from `./email` so consumers type their `EMAIL` service binding
-against the published contract instead of vendoring it — additive, no breaking
-change. (`v0.2.0` added the `./email` subpath itself: `renderEmailShell`,
-`buildIcs`, `EmailShellInput`, `EmailBlock`, `IcsEvent`.) Consumers on `v0.1.0`
-are unaffected — the `./auth` and `./ui` subpaths are unchanged.
+**This release:** `v0.2.2` fixes a `return_to` bug in the hosted `ampl-auth`
+service: the login page dropped `return_to` at the "Continue with GitHub"
+button, so deep-link-after-login always landed at `/auth` (see the note in
+section 4). It is a service-side fix with no library API change — every
+consuming tool benefits once the shared service is deployed at v0.2.2, and no
+consumer code change is required. (`v0.2.1` exported the `send()` RPC contract —
+`SendMessage`, `SendResult` — from `./email`; `v0.2.0` added the `./email`
+subpath itself: `renderEmailShell`, `buildIcs`, `EmailShellInput`, `EmailBlock`,
+`IcsEvent`.) Consumers on `v0.1.0` are unaffected at the library level — the
+`./auth` and `./ui` subpaths are unchanged.
 
 **Policy:**
 
diff --git a/package-lock.json b/package-lock.json
index 884c264..f2f631b 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
   "name": "@ampl/kit",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@ampl/kit",
-      "version": "0.2.1",
+      "version": "0.2.2",
       "hasInstallScript": true,
       "dependencies": {
         "@oslojs/crypto": "^1.0.1",
diff --git a/package.json b/package.json
index 8f1e4d7..dc3e2e1 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@ampl/kit",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "private": true,
   "type": "module",
   "description": "Shared foundation for the AMPL tools suite: the ampl-auth Worker (ampl.tools/auth) + the @ampl/kit design system, surfaces, and session-validation helper consumed by every tool.",