@withone/connect 0.16.1 → 0.17.1

package/src/react.ts

@@ -38,6 +38,8 @@ const visualKey = (props: ConnectButtonCoreProps): string =>
     props.fullWidth,
     props.theme,
     props.connectTheme,
+    props.connector,
+    props.returnTo,
     props.label,
     props.connectedLabel,
     props.description,

package/src/server/index.ts

@@ -38,6 +38,8 @@ import {
   createPkceVerifier,
   createState,
   pkceChallenge,
+  appPath,
+  parseTxCookieValue,
   txCookie,
   txCookieName,
 } from "./oauth";
@@ -57,6 +59,7 @@ import {
   type ReachableConnection,
   type RefreshIfExpiringOptions,
   type RunActionInput,
+  type OneRefusal,
   type RunActionResult,
   type SearchActionsOptions,
   type StartAuthorizationInput,
@@ -67,6 +70,24 @@ export * from "./types";
 export { encodeUserReference, parseUserReference } from "./key";
 export { refreshTokenExpiresAt, tenancyHeaders, tokenScopes } from "./oauth";
 
+/**
+ * Why One itself refused a call, from its reply. One's own errors carry a
+ * correlationId; a provider's error does not, so it reads `null`. Only a
+ * 403 is the grant: One also answers a plan limit (402), a rate limit
+ * (429) and its own failures (5xx) with a correlationId, and none of those
+ * mean the call is outside what the user granted.
+ */
+function oneRefusal(response: Response, data: unknown): OneRefusal | null {
+  if (response.ok) return null;
+  const fromOne =
+    typeof data === "object" && data !== null && "correlationId" in (data as Record<string, unknown>);
+  if (!fromOne) return null;
+  if (response.status === 403) return "grant";
+  if (response.status === 402) return "plan_limit";
+  if (response.status === 429) return "rate_limit";
+  return "one_error";
+}
+
 const CATALOG_PAGE_SIZE = 100;
 const CATALOG_MAX_PAGES = 20;
 const SEARCH_DEFAULT_LIMIT = 5;
@@ -246,8 +267,12 @@ export function createOneConnect(
   const returnTo = config.returnTo ?? "/";
   const scopes = config.scopes ?? DEFAULT_SCOPES;
 
-  const returnUrl = (status: "success" | "error", code?: ConnectFailureCode): string => {
-    const url = new URL(returnTo, config.redirectUri);
+  const returnUrl = (
+    status: "success" | "error",
+    code?: ConnectFailureCode,
+    flowReturnTo?: string,
+  ): string => {
+    const url = new URL(flowReturnTo ?? returnTo, config.redirectUri);
     url.searchParams.set(RETURN_STATUS_PARAM, status);
     if (code) url.searchParams.set(RETURN_ERROR_PARAM, code);
     return url.toString();
@@ -319,7 +344,7 @@ export function createOneConnect(
     if (input.loginHint) url.searchParams.set("login_hint", input.loginHint);
     return {
       redirectUrl: url.toString(),
-      cookie: txCookie(state, verifier, config.redirectUri),
+      cookie: txCookie(state, verifier, config.redirectUri, appPath(input.returnTo)),
     };
   };
 
@@ -331,7 +356,10 @@ export function createOneConnect(
     const state = params.get("state");
     const oauthError = params.get("error");
     const cookieName = state ? txCookieName(state) : undefined;
-    const verifier = cookieName ? input.getCookie(cookieName) : undefined;
+    const stored = cookieName ? input.getCookie(cookieName) : undefined;
+    const { verifier, returnTo: flowReturnTo } = stored
+      ? parseTxCookieValue(stored)
+      : { verifier: undefined, returnTo: undefined };
 
     const fail = (
       failure: ConnectFailureCode,
@@ -340,7 +368,7 @@ export function createOneConnect(
       outcome: failure === "declined" ? "declined" : "failed",
       code: failure,
       message,
-      redirectUrl: returnUrl("error", failure),
+      redirectUrl: returnUrl("error", failure, flowReturnTo),
       clearCookieName: cookieName,
     });
 
@@ -378,7 +406,7 @@ export function createOneConnect(
 
     return {
       outcome: "connected",
-      redirectUrl: returnUrl("success"),
+      redirectUrl: returnUrl("success", undefined, flowReturnTo),
       clearCookieName: cookieName,
     };
   };
@@ -615,7 +643,7 @@ export function createOneConnect(
         // tells them apart: if that still answers, the consent stands
         // and it was this call One refused.
         if (await consentStands(userId, refused))
-          return { status: response.status, ok: false, blockedByGrant: true, data: text };
+          return { status: response.status, ok: false, blockedByGrant: true, refusal: "grant", data: text };
         throw refused;
       }
       // One refusing the credential is not an answer to the action.
@@ -627,14 +655,8 @@ export function createOneConnect(
     } catch {
       /* the provider answered with something other than JSON */
     }
-    // One's own refusals carry a correlationId; a provider's error does
-    // not. A One-shaped 403 is the grant working, not the provider.
-    const blockedByGrant =
-      !response.ok &&
-      typeof data === "object" &&
-      data !== null &&
-      "correlationId" in (data as Record<string, unknown>);
-    return { status: response.status, ok: response.ok, blockedByGrant, data };
+    const refusal = oneRefusal(response, data);
+    return { status: response.status, ok: response.ok, blockedByGrant: refusal === "grant", refusal, data };
   };
 
   const shared = {

package/src/server/oauth.ts

@@ -36,18 +36,49 @@ export function txCookieName(state: string): string {
   return `${TX_COOKIE_PREFIX}${state}`;
 }
 
+/** A return path this one flow may use: a path on the app itself. A
+ *  full URL, a protocol-relative one or anything else is dropped, so
+ *  the callback never sends a user to another site. */
+export function appPath(value: string | undefined): string | undefined {
+  if (!value || !value.startsWith("/")) return undefined;
+  if (value.startsWith("//") || value.startsWith("/\\")) return undefined;
+  return value;
+}
+
+/** The cookie value: the verifier, then the flow's own return path when
+ *  it has one. A dot separates them; the verifier is base64url, which
+ *  never contains one, so a value written before 0.17 still reads. */
+export function txCookieValue(verifier: string, returnTo?: string): string {
+  return returnTo
+    ? `${verifier}.${Buffer.from(returnTo).toString("base64url")}`
+    : verifier;
+}
+
+export function parseTxCookieValue(value: string): {
+  verifier: string;
+  returnTo?: string;
+} {
+  const dot = value.indexOf(".");
+  if (dot < 0) return { verifier: value };
+  return {
+    verifier: value.slice(0, dot),
+    returnTo: appPath(Buffer.from(value.slice(dot + 1), "base64url").toString()),
+  };
+}
+
 /** The cookie scoped to the routes that need it: the directory of the
  *  callback path, which is also where the authorize route lives. */
 export function txCookie(
   state: string,
   verifier: string,
   redirectUri: string,
+  returnTo?: string,
 ): OneConnectCookie {
   const url = new URL(redirectUri);
   const path = url.pathname.replace(/\/[^/]*$/, "") || "/";
   return {
     name: txCookieName(state),
-    value: verifier,
+    value: txCookieValue(verifier, returnTo),
     options: {
       httpOnly: true,
       secure: url.protocol === "https:",

package/src/server/types.ts

@@ -161,6 +161,10 @@ export interface OneConnectCookie {
 export interface StartAuthorizationInput {
   /** Pre-fills the sign-in email on One's page. Never locks it. */
   loginHint?: string;
+  /** Where this one flow returns to: a path on your app ("/chat/42").
+   *  Kept in the flow's cookie, never sent to One. Anything that is not
+   *  a plain path is ignored and the configured `returnTo` applies. */
+  returnTo?: string;
 }
 
 export interface StartAuthorizationResult {
@@ -275,13 +279,31 @@ export interface RunActionInput {
   encoding?: ActionBodyEncoding;
 }
 
+/**
+ * Why One itself turned a call down, when it did. A provider's own error
+ * (Gmail's 404, Stripe's 400) is not One's refusal and reads `null`.
+ *
+ * - `grant`: the call is outside what the user granted (403). Do not retry.
+ * - `plan_limit`: a plan limit was hit (402, "Please try again later or
+ *   upgrade your plan"). Not about the grant: wait and retry later.
+ * - `rate_limit`: too many calls (429). Wait and retry later.
+ * - `one_error`: any other error from One (for example a 5xx). Retry with
+ *   a backoff.
+ */
+export type OneRefusal = "grant" | "plan_limit" | "rate_limit" | "one_error";
+
 export interface RunActionResult {
   status: number;
   ok: boolean;
-  /** True when One refused the call because it is outside the grant.
-   *  The provider was never called. Do not retry. Key mode sets it; in
-   *  token mode it stays false today, so treat any 403 there as refused. */
+  /** True only when One refused the call because it is outside the grant
+   *  (a 403). The provider was never called. Do not retry. Key mode sets
+   *  it; in token mode it stays false today, so treat any 403 there as
+   *  refused. One's other refusals (plan limit, rate limit, its own
+   *  errors) are not about the grant: see `refusal`. */
   blockedByGrant: boolean;
+  /** Why One turned the call down, or `null` when it didn't (the call
+   *  succeeded, or the provider answered with its own error). */
+  refusal: OneRefusal | null;
   data: unknown;
 }
 

package/src/types.ts

@@ -31,6 +31,14 @@ export interface OneConnectFlowOptions {
   /** Theme for One's hosted page. Carried on the URL fragment, which
    *  survives the redirect chain, so the backend forwards nothing. */
   connectTheme?: OneConnectTheme;
+  /** A connector slug ("gmail"). One's page opens that connector's
+   *  connect screen first, then shows the full list as usual. Carried
+   *  on the URL fragment like the theme. */
+  connector?: string;
+  /** Where the user lands afterwards, for this flow only: a path on
+   *  your app such as "/chat/42". Your authorize route reads it and
+   *  the callback uses it instead of the server's `returnTo`. */
+  returnTo?: string;
   /** The grant completed and the backend stored the tokens. Fires once
    *  per page load, on the first flow still mounted when the tab
    *  returns. Treat it as a hint to refetch: your server is the truth. */
@@ -75,9 +83,9 @@ export interface ConnectButtonLogo {
   imageUrl: string;
 }
 
-/** @deprecated Renamed to `ConnectButtonLogoInput`; removed in 0.17.0. */
+/** @deprecated Renamed to `ConnectButtonLogoInput`; removed in 0.18.0. */
 export type ConnectButtonPlatformInput = ConnectButtonLogoInput;
-/** @deprecated Renamed to `ConnectButtonLogo`; removed in 0.17.0. */
+/** @deprecated Renamed to `ConnectButtonLogo`; removed in 0.18.0. */
 export type ConnectButtonPlatform = ConnectButtonLogo;
 
 export type ConnectButtonVariant = "default" | "accent" | "block";
@@ -94,7 +102,7 @@ export interface ConnectButtonProps {
    *  into a "+N" chip. Decoration only; the permission set decides what
    *  One asks for. */
   logos?: ConnectButtonLogoInput[];
-  /** @deprecated Renamed to `logos`; removed in 0.17.0. */
+  /** @deprecated Renamed to `logos`; removed in 0.18.0. */
   platforms?: ConnectButtonLogoInput[];
   /** Whether this user has a live grant, from your server. When set, it
    *  decides the Connected state. When omitted, the button shows
@@ -113,6 +121,10 @@ export interface ConnectButtonProps {
   theme?: ConnectButtonTheme;
   /** Theme of One's hosted page. */
   connectTheme?: OneConnectTheme;
+  /** A connector slug ("gmail") to open first on One's page. */
+  connector?: string;
+  /** Where this flow returns to: a path on your app. */
+  returnTo?: string;
   /** "Connect your apps" unless set. */
   label?: string;
   /** "Connected" unless set. */

package/src/vue.ts

@@ -62,6 +62,8 @@ export const ConnectButton = defineComponent({
       type: String as PropType<OneConnectTheme>,
       default: undefined,
     },
+    connector: { type: String, default: undefined },
+    returnTo: { type: String, default: undefined },
     label: { type: String, default: undefined },
     connectedLabel: { type: String, default: undefined },
     description: { type: String, default: undefined },