@withone/connect 0.8.2 → 0.9.0

package/src/server/index.ts

@@ -0,0 +1,382 @@
+/**
+ * `@withone/connect/server`: the half of One Connect that runs on the
+ * app's server. It starts the flow, completes it, keeps the tokens fresh
+ * and makes every call with the grant. The client secret never leaves
+ * here.
+ *
+ *   const oneConnect = createOneConnect({ clientId, clientSecret,
+ *     redirectUri, permissionSet, tokenStore });
+ *
+ *   // in the authorize route
+ *   const { redirectUrl, cookie } = oneConnect.startAuthorization({ loginHint });
+ *   // in the callback route
+ *   const result = await oneConnect.completeAuthorization({ userId, url, getCookie });
+ *   // afterwards
+ *   const rows = await oneConnect.listConnections(userId);
+ *   const reply = await oneConnect.runAction(userId, { connectionKey, actionId, method, path });
+ *
+ * The Next.js and Node adapters turn the first two into route handlers.
+ */
+import { DEFAULT_ONE_API_URL, RETURN_MESSAGE_PARAM, RETURN_STATUS_PARAM } from "../constants";
+import {
+  DEFAULT_SCOPES,
+  basicAuthorization,
+  createPkceVerifier,
+  createState,
+  pkceChallenge,
+  tenancyHeaders,
+  txCookie,
+  txCookieName,
+} from "./oauth";
+import {
+  OneConnectError,
+  type CompleteAuthorizationInput,
+  type CompleteAuthorizationResult,
+  type OneConnectServerConfig,
+  type OneConnectTokens,
+  type PlatformAction,
+  type ReachableConnection,
+  type RunActionInput,
+  type RunActionResult,
+  type StartAuthorizationInput,
+  type StartAuthorizationResult,
+} from "./types";
+
+export * from "./types";
+export { tenancyHeaders, tokenScopes } from "./oauth";
+
+/** Refresh this long before expiry, so a call never races the clock. */
+const REFRESH_MARGIN_MS = 60_000;
+const CATALOG_PAGE_SIZE = 100;
+const CATALOG_MAX_PAGES = 20;
+
+interface TokenResponse {
+  access_token: string;
+  refresh_token: string;
+  expires_in: number;
+}
+
+export interface OneConnect {
+  /** The authorize leg: where to send the browser and the cookie to set. */
+  startAuthorization: (
+    input?: StartAuthorizationInput,
+  ) => StartAuthorizationResult;
+  /** The callback leg: verifies state, exchanges the code, stores the
+   *  tokens, and says where to send the browser next. Never throws for
+   *  a failed flow; read `outcome`. */
+  completeAuthorization: (
+    input: CompleteAuthorizationInput,
+  ) => Promise<CompleteAuthorizationResult>;
+  /** Whether the user has tokens stored. */
+  isConnected: (userId: string) => Promise<boolean>;
+  /** A live access token, refreshed first when it is about to expire. */
+  getAccessToken: (userId: string) => Promise<string>;
+  /** The stored tokens, for display. Null when not connected. */
+  getTokens: (userId: string) => Promise<OneConnectTokens | null>;
+  /** Forces a refresh now. */
+  refreshTokens: (userId: string) => Promise<OneConnectTokens>;
+  /** Drops the app's copy of the tokens. The user revokes the grant
+   *  itself from their One dashboard. */
+  disconnect: (userId: string) => Promise<void>;
+  /** The connections the grant reaches, each with its access. */
+  listConnections: (userId: string) => Promise<ReachableConnection[]>;
+  /** Every catalog action of a platform. What exists, not what is
+   *  permitted; the grant decides that when the action runs. */
+  listActions: (userId: string, platform: string) => Promise<PlatformAction[]>;
+  /** Runs one action through One with the grant. */
+  runAction: (userId: string, input: RunActionInput) => Promise<RunActionResult>;
+  /** Any authenticated request to One's /v1 API, headers handled. */
+  fetch: (
+    userId: string,
+    path: string,
+    init?: RequestInit,
+  ) => Promise<Response>;
+}
+
+export function createOneConnect(config: OneConnectServerConfig): OneConnect {
+  const oneApiUrl = (config.oneApiUrl ?? DEFAULT_ONE_API_URL).replace(/\/+$/, "");
+  const authorizeUrl = `${oneApiUrl}/oauth/authorize`;
+  const tokenUrl = `${oneApiUrl}/oauth/token`;
+  const apiUrl = `${oneApiUrl}/v1`;
+  const returnTo = config.returnTo ?? "/";
+  const scopes = config.scopes ?? DEFAULT_SCOPES;
+  const { tokenStore } = config;
+
+  /** One refresh in flight per user: two concurrent refreshes with the
+   *  same refresh token trip One's reuse detection. */
+  const refreshing = new Map<string, Promise<OneConnectTokens>>();
+
+  const returnUrl = (status: "success" | "error", message?: string): string => {
+    const url = new URL(returnTo, config.redirectUri);
+    url.searchParams.set(RETURN_STATUS_PARAM, status);
+    if (message) url.searchParams.set(RETURN_MESSAGE_PARAM, message);
+    return url.toString();
+  };
+
+  const exchange = async (body: URLSearchParams): Promise<TokenResponse> => {
+    const response = await fetch(tokenUrl, {
+      method: "POST",
+      headers: {
+        Authorization: basicAuthorization(config.clientId, config.clientSecret),
+        "Content-Type": "application/x-www-form-urlencoded",
+      },
+      body,
+    });
+    if (!response.ok) {
+      throw new OneConnectError(
+        "request_failed",
+        `One refused the token request (HTTP ${response.status}).`,
+        response.status,
+      );
+    }
+    return (await response.json()) as TokenResponse;
+  };
+
+  const toTokens = (response: TokenResponse): OneConnectTokens => ({
+    accessToken: response.access_token,
+    refreshToken: response.refresh_token,
+    expiresAt: Date.now() + response.expires_in * 1000,
+  });
+
+  const startAuthorization = (
+    input: StartAuthorizationInput = {},
+  ): StartAuthorizationResult => {
+    const state = createState();
+    const verifier = createPkceVerifier();
+    const url = new URL(authorizeUrl);
+    url.searchParams.set("client_id", config.clientId);
+    url.searchParams.set("redirect_uri", config.redirectUri);
+    url.searchParams.set("response_type", "code");
+    url.searchParams.set("scope", scopes.join(" "));
+    url.searchParams.set("state", state);
+    url.searchParams.set("code_challenge", pkceChallenge(verifier));
+    url.searchParams.set("code_challenge_method", "S256");
+    if (config.permissionSet)
+      url.searchParams.set("permission_set", config.permissionSet);
+    if (input.loginHint) url.searchParams.set("login_hint", input.loginHint);
+    return {
+      redirectUrl: url.toString(),
+      cookie: txCookie(state, verifier, config.redirectUri),
+    };
+  };
+
+  const completeAuthorization = async (
+    input: CompleteAuthorizationInput,
+  ): Promise<CompleteAuthorizationResult> => {
+    const params = new URL(input.url).searchParams;
+    const code = params.get("code");
+    const state = params.get("state");
+    const oauthError = params.get("error");
+    const cookieName = state ? txCookieName(state) : undefined;
+    const verifier = cookieName ? input.getCookie(cookieName) : undefined;
+
+    const fail = (
+      outcome: "declined" | "failed",
+      message: string,
+    ): CompleteAuthorizationResult => ({
+      outcome,
+      message,
+      redirectUrl: returnUrl("error", message),
+      clearCookieName: cookieName,
+    });
+
+    if (oauthError === "access_denied")
+      return fail("declined", "You cancelled the request.");
+    if (oauthError)
+      return fail("failed", `One reported an error: ${oauthError}.`);
+    // The returned state names its own cookie. No cookie means a forged
+    // or stale state; the code is never exchanged in that case.
+    if (!code || !state || !verifier)
+      return fail("failed", "The sign-in attempt expired or was tampered with.");
+
+    try {
+      const tokens = toTokens(
+        await exchange(
+          new URLSearchParams({
+            grant_type: "authorization_code",
+            code,
+            redirect_uri: config.redirectUri,
+            code_verifier: verifier,
+          }),
+        ),
+      );
+      await tokenStore.saveTokens(input.userId, tokens);
+    } catch (error) {
+      const status = error instanceof OneConnectError ? error.status : undefined;
+      return fail(
+        "failed",
+        status
+          ? `One rejected the code exchange (HTTP ${status}).`
+          : "One could not be reached to complete the connection.",
+      );
+    }
+
+    return {
+      outcome: "connected",
+      redirectUrl: returnUrl("success"),
+      clearCookieName: cookieName,
+    };
+  };
+
+  const refreshTokens = (userId: string): Promise<OneConnectTokens> => {
+    const inFlight = refreshing.get(userId);
+    if (inFlight) return inFlight;
+    const job = (async () => {
+      const current = await tokenStore.loadTokens(userId);
+      if (!current)
+        throw new OneConnectError("not_connected", "This user is not connected.");
+      try {
+        const next = toTokens(
+          await exchange(
+            new URLSearchParams({
+              grant_type: "refresh_token",
+              refresh_token: current.refreshToken,
+            }),
+          ),
+        );
+        // Both tokens: One rotates the pair on every refresh.
+        await tokenStore.saveTokens(userId, next);
+        return next;
+      } catch (error) {
+        // The family is dead: revoked, expired or reused. Keeping the
+        // pair would only fail again; the user has to reconnect.
+        await tokenStore.clearTokens(userId);
+        const status = error instanceof OneConnectError ? error.status : undefined;
+        throw new OneConnectError(
+          "refresh_failed",
+          "The connection to One has expired or was revoked. Ask the user to connect again.",
+          status,
+        );
+      } finally {
+        refreshing.delete(userId);
+      }
+    })();
+    refreshing.set(userId, job);
+    return job;
+  };
+
+  const getAccessToken = async (userId: string): Promise<string> => {
+    const tokens = await tokenStore.loadTokens(userId);
+    if (!tokens)
+      throw new OneConnectError("not_connected", "This user is not connected.");
+    if (Date.now() < tokens.expiresAt - REFRESH_MARGIN_MS) return tokens.accessToken;
+    return (await refreshTokens(userId)).accessToken;
+  };
+
+  const oneFetch = async (
+    userId: string,
+    path: string,
+    init: RequestInit = {},
+  ): Promise<Response> => {
+    const accessToken = await getAccessToken(userId);
+    const headers = new Headers(init.headers);
+    headers.set("Authorization", `Bearer ${accessToken}`);
+    for (const [name, value] of Object.entries(tenancyHeaders(accessToken)))
+      headers.set(name, value);
+    return fetch(`${apiUrl}${path.startsWith("/") ? path : `/${path}`}`, {
+      ...init,
+      headers,
+    });
+  };
+
+  const listConnections = async (userId: string): Promise<ReachableConnection[]> => {
+    const response = await oneFetch(userId, "/connections/reachable");
+    if (!response.ok) {
+      throw new OneConnectError(
+        "request_failed",
+        `One refused the connections request (HTTP ${response.status}).`,
+        response.status,
+      );
+    }
+    const body = (await response.json()) as { rows?: ReachableConnection[] };
+    return body.rows ?? [];
+  };
+
+  const listActions = async (
+    userId: string,
+    platform: string,
+  ): Promise<PlatformAction[]> => {
+    const pageUrl = (page: number) =>
+      `/knowledge?connectionPlatform=${encodeURIComponent(platform)}&limit=${CATALOG_PAGE_SIZE}&page=${page}`;
+    const slim = (rows: Record<string, unknown>[]): PlatformAction[] =>
+      rows.map((row) => ({
+        _id: String(row._id ?? ""),
+        title: String(row.title ?? ""),
+        method: String(row.method ?? ""),
+        path: String(row.path ?? ""),
+      }));
+    const first = await oneFetch(userId, pageUrl(1));
+    if (!first.ok) {
+      throw new OneConnectError(
+        "request_failed",
+        `One refused the catalog request (HTTP ${first.status}).`,
+        first.status,
+      );
+    }
+    const page1 = (await first.json()) as {
+      rows?: Record<string, unknown>[];
+      pages?: number;
+    };
+    const pages = Math.min(Math.max(page1.pages ?? 1, 1), CATALOG_MAX_PAGES);
+    const rest = await Promise.all(
+      Array.from({ length: pages - 1 }, (_, index) =>
+        oneFetch(userId, pageUrl(index + 2))
+          .then((response) =>
+            response.ok
+              ? (response.json() as Promise<{ rows?: Record<string, unknown>[] }>)
+              : null,
+          )
+          .catch(() => null),
+      ),
+    );
+    return slim([page1, ...rest].flatMap((page) => page?.rows ?? []));
+  };
+
+  const runAction = async (
+    userId: string,
+    input: RunActionInput,
+  ): Promise<RunActionResult> => {
+    const method = input.method.toUpperCase();
+    const query = input.query ? `?${new URLSearchParams(input.query)}` : "";
+    const headers: Record<string, string> = {
+      "x-one-connection-key": input.connectionKey,
+      "x-one-action-id": input.actionId,
+    };
+    const hasBody = method !== "GET" && method !== "HEAD" && input.body !== undefined;
+    if (hasBody) headers["Content-Type"] = "application/json";
+    const response = await oneFetch(userId, `/passthrough${input.path}${query}`, {
+      method,
+      headers,
+      body: hasBody ? JSON.stringify(input.body) : undefined,
+    });
+    const text = await response.text();
+    let data: unknown = text;
+    try {
+      data = JSON.parse(text);
+    } 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 };
+  };
+
+  return {
+    startAuthorization,
+    completeAuthorization,
+    isConnected: async (userId) => (await tokenStore.loadTokens(userId)) !== null,
+    getAccessToken,
+    getTokens: (userId) => tokenStore.loadTokens(userId),
+    refreshTokens,
+    disconnect: (userId) => tokenStore.clearTokens(userId),
+    listConnections,
+    listActions,
+    runAction,
+    fetch: oneFetch,
+  };
+}

package/src/server/oauth.ts

@@ -0,0 +1,98 @@
+import { createHash, randomBytes } from "node:crypto";
+
+import type { OneConnectCookie } from "./types";
+
+/** One cookie per flow, named by its state, so a retry or a second tab
+ *  never overwrites the verifier of a flow still in progress. */
+export const TX_COOKIE_PREFIX = "one_tx_";
+
+/** One gives the consent 10 minutes and then the code 10 minutes, so a
+ *  legitimate callback can arrive up to twenty minutes after the start.
+ *  Thirty minutes leaves a margin. */
+export const TX_COOKIE_MAX_AGE_SECONDS = 1800;
+
+export const DEFAULT_SCOPES = [
+  "user:connections:read",
+  "user:connections:write",
+  "org:connections:read",
+  "org:connections:write",
+  "project:connections:read",
+  "project:connections:write",
+];
+
+export function createState(): string {
+  return randomBytes(16).toString("hex");
+}
+
+export function createPkceVerifier(): string {
+  return randomBytes(32).toString("base64url");
+}
+
+export function pkceChallenge(verifier: string): string {
+  return createHash("sha256").update(verifier).digest("base64url");
+}
+
+export function txCookieName(state: string): string {
+  return `${TX_COOKIE_PREFIX}${state}`;
+}
+
+/** 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,
+): OneConnectCookie {
+  const url = new URL(redirectUri);
+  const path = url.pathname.replace(/\/[^/]*$/, "") || "/";
+  return {
+    name: txCookieName(state),
+    value: verifier,
+    options: {
+      httpOnly: true,
+      secure: url.protocol === "https:",
+      sameSite: "lax",
+      maxAge: TX_COOKIE_MAX_AGE_SECONDS,
+      path,
+    },
+  };
+}
+
+export function basicAuthorization(
+  clientId: string,
+  clientSecret: string,
+): string {
+  return `Basic ${Buffer.from(`${clientId}:${clientSecret}`).toString("base64")}`;
+}
+
+/** The tenant headers a grant needs on every call. A grant made into an
+ *  organization or project lives there; One resolves the tenant from
+ *  these headers, and without them the call runs in the user's personal
+ *  space. The access token's claims name the tenant, so echo them. */
+export function tenancyHeaders(accessToken: string): Record<string, string> {
+  try {
+    const payload = JSON.parse(
+      Buffer.from(accessToken.split(".")[1], "base64url").toString(),
+    ) as { organization_ids?: string[]; project_ids?: string[] };
+    const headers: Record<string, string> = {};
+    const organizationId = payload.organization_ids?.[0];
+    const projectId = payload.project_ids?.[0];
+    if (organizationId) headers["X-One-Organization-Id"] = organizationId;
+    if (projectId) headers["X-One-Project-Id"] = projectId;
+    return headers;
+  } catch {
+    return {};
+  }
+}
+
+/** The scopes the token was granted, from its claims. Display only. */
+export function tokenScopes(accessToken: string): string[] {
+  try {
+    const payload = JSON.parse(
+      Buffer.from(accessToken.split(".")[1], "base64url").toString(),
+    ) as { scope?: string };
+    return (payload.scope ?? "").split(" ").filter(Boolean);
+  } catch {
+    return [];
+  }
+}

package/src/server/types.ts

@@ -0,0 +1,155 @@
+/**
+ * Types for `@withone/connect/server`: the half of the SDK that runs on
+ * the app's server and holds the client secret.
+ */
+
+/** What the app stores per user after the exchange. */
+export interface OneConnectTokens {
+  accessToken: string;
+  refreshToken: string;
+  /** Epoch milliseconds when the access token expires. */
+  expiresAt: number;
+}
+
+/**
+ * Where the app keeps each user's tokens: its database, a cache, an
+ * encrypted cookie. The SDK never sees a token outside these three
+ * calls. `userId` is the app's own id for its user.
+ */
+export interface OneConnectTokenStore {
+  saveTokens: (userId: string, tokens: OneConnectTokens) => Promise<void>;
+  loadTokens: (userId: string) => Promise<OneConnectTokens | null>;
+  clearTokens: (userId: string) => Promise<void>;
+}
+
+export interface OneConnectServerConfig {
+  /** The app's client id from the dashboard. */
+  clientId: string;
+  /** The app's client secret. Server only. */
+  clientSecret: string;
+  /** Exactly the callback URL registered on the app, character for
+   *  character, for example "https://yourapp.com/api/one/callback". */
+  redirectUri: string;
+  /** The ask (permission set) to open the consent card on. Omit to ask
+   *  for everything the user has connected. */
+  permissionSet?: string;
+  /** One's API origin. Production when omitted. */
+  oneApiUrl?: string;
+  /** Where the callback sends the browser afterwards. "/" when omitted;
+   *  the outcome is appended as `?one_connect=…`. */
+  returnTo?: string;
+  /** OAuth scopes. All three tenancy tiers when omitted, so the user may
+   *  grant from any space. */
+  scopes?: string[];
+  tokenStore: OneConnectTokenStore;
+}
+
+/** The transaction cookie the authorize leg sets and the callback reads. */
+export interface OneConnectCookie {
+  name: string;
+  value: string;
+  options: {
+    httpOnly: true;
+    secure: boolean;
+    sameSite: "lax";
+    maxAge: number;
+    path: string;
+  };
+}
+
+export interface StartAuthorizationInput {
+  /** Pre-fills the sign-in email on One's page. Never locks it. */
+  loginHint?: string;
+}
+
+export interface StartAuthorizationResult {
+  /** Send the browser here with a 302. */
+  redirectUrl: string;
+  /** Set this cookie on the same response. */
+  cookie: OneConnectCookie;
+}
+
+export interface CompleteAuthorizationInput {
+  /** The app's user the grant belongs to. */
+  userId: string;
+  /** The full callback URL One redirected to, with its query string. */
+  url: string;
+  /** Reads a cookie by name from the incoming request. */
+  getCookie: (name: string) => string | undefined;
+}
+
+export type AuthorizationOutcome = "connected" | "declined" | "failed";
+
+export interface CompleteAuthorizationResult {
+  outcome: AuthorizationOutcome;
+  /** Safe to show to the user when the outcome is not "connected". */
+  message?: string;
+  /** Send the browser here with a 302; it carries `?one_connect=…`. */
+  redirectUrl: string;
+  /** Delete this cookie on the same response, when one was involved. */
+  clearCookieName?: string;
+}
+
+/** One connection the grant reaches, with the access it confers. */
+export interface ReachableConnection {
+  key: string;
+  platform: string;
+  name?: string;
+  title?: string;
+  image?: string;
+  access: ConnectionAccess;
+}
+
+export type ConnectionAccess =
+  | { policy: "full" }
+  | { policy: "methods"; methods: string[] }
+  | {
+      policy: "actions";
+      actions: { actionId: string; title: string; method: string }[];
+    };
+
+/** One catalog action for a platform. */
+export interface PlatformAction {
+  _id: string;
+  title: string;
+  method: string;
+  path: string;
+}
+
+export interface RunActionInput {
+  /** From `listConnections`. */
+  connectionKey: string;
+  /** From `listActions`. */
+  actionId: string;
+  method: string;
+  /** The action's path, appended to /v1/passthrough. */
+  path: string;
+  body?: unknown;
+  query?: Record<string, string>;
+}
+
+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. */
+  blockedByGrant: boolean;
+  data: unknown;
+}
+
+export type OneConnectErrorCode =
+  | "not_connected"
+  | "refresh_failed"
+  | "request_failed";
+
+export class OneConnectError extends Error {
+  readonly code: OneConnectErrorCode;
+  readonly status?: number;
+
+  constructor(code: OneConnectErrorCode, message: string, status?: number) {
+    super(message);
+    this.name = "OneConnectError";
+    this.code = code;
+    this.status = status;
+  }
+}

package/src/svelte.ts

@@ -1,37 +1,37 @@
 /**
- * Svelte — `import { connectButton } from "@withone/connect/svelte"`.
+ * Svelte: `import { connectButton } from "@withone/connect/svelte"`.
  *
- * A Svelte ACTION (the idiomatic Svelte shape for DOM-mounting
- * libraries), so no Svelte compiler or dependency is involved:
+ * A Svelte action, the idiomatic shape for DOM-mounting libraries, so no
+ * Svelte compiler or dependency is involved:
  *
  *   <div use:connectButton={{ authorizeUrl: "/api/one/authorize",
- *     platforms: [{ name: "Stripe", imageUrl: "/icons/stripe.svg" }],
+ *     platforms: ["stripe", "notion"],
  *     onSuccess: () => { ... } }} />
  */
-import { mountConnectButton } from "./button";
 import {
-  optionsFromWrapperProps,
-  type ConnectButtonWrapperProps,
-} from "./wrapper-options";
-import type { ConnectButtonHandle } from "./types";
+  mountConnectButton,
+  optionsFromProps,
+  type ConnectButtonHandle,
+  type ConnectButtonProps,
+} from "@withone/connect";
 
-export type { ConnectButtonWrapperProps as ConnectButtonProps };
+export type { ConnectButtonProps };
 
 export function connectButton(
   node: HTMLElement,
-  props: ConnectButtonWrapperProps,
+  props: ConnectButtonProps,
 ): {
-  update: (next: ConnectButtonWrapperProps) => void;
+  update: (next: ConnectButtonProps) => void;
   destroy: () => void;
 } {
   let handle: ConnectButtonHandle = mountConnectButton(
     node,
-    optionsFromWrapperProps(props),
+    optionsFromProps(props),
   );
   return {
-    update(next: ConnectButtonWrapperProps) {
+    update(next: ConnectButtonProps) {
       handle.destroy();
-      handle = mountConnectButton(node, optionsFromWrapperProps(next));
+      handle = mountConnectButton(node, optionsFromProps(next));
     },
     destroy() {
       handle.destroy();