@withone/connect 0.12.1 → 0.13.0

package/src/server/key.ts

@@ -0,0 +1,142 @@
+/**
+ * Key mode: the app holds one connect key, and one permanent id per
+ * user. Both go on every call; One reads the user's consent live each
+ * time. Nothing expires, so there is nothing to refresh, rotate or lock.
+ *
+ *   X-One-Secret:           the app's connect key
+ *   X-One-Connect-User-Id:  cu_… for the user being acted for
+ *
+ * The id comes from the one code exchange the callback makes. It is the
+ * same for a user for the life of the app, through revocation and
+ * re-consent, so it is saved once and never deleted by the SDK.
+ */
+import type { Credential, TokenResponse } from "./credential";
+import { tenancyHeaders } from "./oauth";
+import {
+  OneConnectError,
+  type OneConnectUserReference,
+  type OneConnectUserStore,
+} from "./types";
+
+/** `cu_` and a hex HMAC-SHA256, as One derives it. */
+const CONNECT_USER_ID = /^cu_[0-9a-f]{64}$/;
+const ORGANIZATION = "org=";
+const PROJECT = "project=";
+const SEPARATOR = ";";
+
+const ORGANIZATION_HEADER = "X-One-Organization-Id";
+const PROJECT_HEADER = "X-One-Project-Id";
+
+/**
+ * The one value an app stores per user, as a string for one column:
+ * `cu_…`, then the space the user granted from when it is not their
+ * personal one (`cu_…;org=<id>;project=<id>`).
+ *
+ * The space travels with the id because One resolves a call's tenant
+ * from headers: a grant made from an organization lives there, and a
+ * call that names none runs in the user's personal space and reaches
+ * nothing. In token mode the access token names the space on every
+ * call; here there is no token after the exchange, so it is kept.
+ */
+export function encodeUserReference(reference: OneConnectUserReference): string {
+  const parts = [reference.connectUserId];
+  if (reference.organizationId) parts.push(`${ORGANIZATION}${reference.organizationId}`);
+  if (reference.projectId) parts.push(`${PROJECT}${reference.projectId}`);
+  return parts.join(SEPARATOR);
+}
+
+/** Reads a stored value back. Null when it is not one this SDK wrote. */
+export function parseUserReference(value: string): OneConnectUserReference | null {
+  const [connectUserId, ...rest] = value.trim().split(SEPARATOR);
+  if (!CONNECT_USER_ID.test(connectUserId)) return null;
+  const reference: OneConnectUserReference = { connectUserId };
+  for (const part of rest) {
+    if (part.startsWith(ORGANIZATION)) reference.organizationId = part.slice(ORGANIZATION.length);
+    else if (part.startsWith(PROJECT)) reference.projectId = part.slice(PROJECT.length);
+  }
+  return reference;
+}
+
+/**
+ * One answers a credential it will not accept with the bare status line
+ * and nothing else. Anything richer came from the route or from the
+ * provider behind a passthrough, and is not a verdict on the credential.
+ */
+const isBareRefusal = (status: number, body: string, reason: string): boolean =>
+  body.trim() === `${status} ${reason}`;
+
+export interface KeyCredential extends Credential {
+  getConnectUserId: (userId: string) => Promise<string | null>;
+}
+
+export function createKeyCredential(
+  connectKey: string,
+  userStore: OneConnectUserStore,
+): KeyCredential {
+  const load = async (userId: string): Promise<OneConnectUserReference | null> => {
+    const stored = await userStore.loadUser(userId);
+    return stored ? parseUserReference(stored) : null;
+  };
+
+  return {
+    connected: async (userId, response: TokenResponse) => {
+      const connectUserId = response.connect_user_id;
+      if (!connectUserId || !CONNECT_USER_ID.test(connectUserId)) {
+        throw new OneConnectError(
+          "request_failed",
+          "One did not return a connect user id for this user, so key mode cannot act for them.",
+        );
+      }
+      // The space the user granted from, read once from the token that
+      // named it. The token itself is not kept.
+      const space = tenancyHeaders(response.access_token);
+      await userStore.saveUser(
+        userId,
+        encodeUserReference({
+          connectUserId,
+          organizationId: space[ORGANIZATION_HEADER],
+          projectId: space[PROJECT_HEADER],
+        }),
+      );
+    },
+
+    headers: async (userId) => {
+      const reference = await load(userId);
+      if (!reference)
+        throw new OneConnectError("not_connected", "This user is not connected.");
+      const headers: Record<string, string> = {
+        "X-One-Secret": connectKey,
+        "X-One-Connect-User-Id": reference.connectUserId,
+      };
+      if (reference.organizationId) headers[ORGANIZATION_HEADER] = reference.organizationId;
+      if (reference.projectId) headers[PROJECT_HEADER] = reference.projectId;
+      return headers;
+    },
+
+    isConnected: async (userId) => (await load(userId)) !== null,
+    disconnect: (userId) => userStore.clearUser(userId),
+
+    refusal: (status, body) => {
+      // One does not say which: the consent was revoked, was never given
+      // in this key's environment, or the app is deactivated. The saved id
+      // is kept either way, because it is the same id after a reconnect.
+      if (status === 403 && isBareRefusal(status, body, "Forbidden")) {
+        return new OneConnectError(
+          "reconnect_required",
+          "One will not act for this user: their consent was revoked, or the app is deactivated. Ask the user to connect again. If every user fails, check that the connect key is for this environment and that the app is active.",
+          status,
+        );
+      }
+      if (status === 401 && isBareRefusal(status, body, "Unauthorized")) {
+        return new OneConnectError(
+          "request_failed",
+          "One did not accept the connect key. Check that it is this app's connect key, minted on the app's page in the One dashboard.",
+          status,
+        );
+      }
+      return null;
+    },
+
+    getConnectUserId: async (userId) => (await load(userId))?.connectUserId ?? null,
+  };
+}

package/src/server/token.ts

@@ -0,0 +1,235 @@
+/**
+ * Token mode: the app holds an access token and a refresh token per
+ * user, and the SDK refreshes them with One.
+ *
+ * Lifetimes. The access token lives as long as the app's Token lifetime
+ * setting says (dashboard, Advanced, when creating or editing the app: 7
+ * days, 30 days, 90 days or 1 year; 30 days unless changed). An app that
+ * never had the setting gets an hour. The refresh token always lives 30
+ * days, whatever the access token's lifetime, and only a live refresh
+ * token can buy a new pair.
+ *
+ * Who refreshes. Before each call the client refreshes a pair that is
+ * within a minute of expiring. Refreshing earlier than that is the app's
+ * job: it runs `refreshIfExpiring` on a schedule, so the refresh token
+ * never runs out. When it has run out, the access token is used until it
+ * expires too, and only then is the user asked to connect again.
+ *
+ * Rotation. Every refresh rotates both tokens, and One treats a second
+ * use of a rotated refresh token as theft and revokes the whole grant.
+ * So the client refreshes one user at a time (in this process always,
+ * across processes through `tokenStore.withLock`), re-reads the store
+ * before spending a refresh token, clears tokens only when the grant is
+ * dead, and never lets a failing old pair delete a newer one.
+ */
+import type { Credential, PostToken, TokenAnswer, TokenResponse } from "./credential";
+import { refreshTokenExpiresAt, tenancyHeaders } from "./oauth";
+import {
+  OneConnectError,
+  type OneConnectTokenStore,
+  type OneConnectTokens,
+  type RefreshIfExpiringOptions,
+} from "./types";
+
+/** Refresh this long before expiry, so a call never races the clock. */
+const REFRESH_MARGIN_MS = 60_000;
+
+/** The one refusal that means the grant is gone for good: revoked by the
+ *  user, expired, or burned by a reused refresh token (RFC 6749 §5.2). */
+const isDeadGrant = (answer: TokenAnswer): boolean =>
+  !answer.ok && answer.status === 400 && answer.error === "invalid_grant";
+
+export interface TokenCredential extends Credential {
+  getAccessToken: (userId: string) => Promise<string>;
+  getTokens: (userId: string) => Promise<OneConnectTokens | null>;
+  refreshTokens: (userId: string) => Promise<OneConnectTokens>;
+  refreshIfExpiring: (
+    userId: string,
+    options?: RefreshIfExpiringOptions,
+  ) => Promise<OneConnectTokens>;
+}
+
+export function createTokenCredential(
+  tokenStore: OneConnectTokenStore,
+  postToken: PostToken,
+): TokenCredential {
+  /** 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>>();
+
+  /** Runs `run` under the app's cross-process lock for this user, when
+   *  the store has one. */
+  const locked = <T>(userId: string, run: () => Promise<T>): Promise<T> =>
+    tokenStore.withLock ? tokenStore.withLock(userId, run) : run();
+
+  /** Whether either token of the pair stops working within `withinMs`. */
+  const expiresWithin = (tokens: OneConnectTokens, withinMs: number): boolean => {
+    const horizon = Date.now() + withinMs;
+    const refreshExpiresAt = refreshTokenExpiresAt(tokens.refreshToken);
+    return (
+      tokens.expiresAt <= horizon ||
+      (refreshExpiresAt !== null && refreshExpiresAt <= horizon)
+    );
+  };
+
+  /** Whether the access token is too close to expiry to make a call with. */
+  const accessEnding = (tokens: OneConnectTokens): boolean =>
+    tokens.expiresAt <= Date.now() + REFRESH_MARGIN_MS;
+
+  /** Whether the refresh token has run out. One with no readable expiry
+   *  counts as live: only One can say otherwise. */
+  const refreshSpent = (tokens: OneConnectTokens): boolean => {
+    const refreshExpiresAt = refreshTokenExpiresAt(tokens.refreshToken);
+    return refreshExpiresAt !== null && refreshExpiresAt <= Date.now();
+  };
+
+  const toTokens = (response: TokenResponse): OneConnectTokens => ({
+    accessToken: response.access_token,
+    refreshToken: response.refresh_token,
+    expiresAt: Date.now() + response.expires_in * 1000,
+  });
+
+  const notConnected = () =>
+    new OneConnectError("not_connected", "This user is not connected.");
+
+  /**
+   * The grant behind `failed` is dead. Clears it, unless a newer pair
+   * landed while it was failing (a reconnect's callback, another
+   * server's refresh): that pair is returned instead, because the user
+   * did nothing wrong and deleting it would disconnect them.
+   */
+  const retire = async (
+    userId: string,
+    failed: OneConnectTokens,
+    status?: number,
+  ): Promise<OneConnectTokens> => {
+    const latest = await tokenStore.loadTokens(userId);
+    if (latest && latest.refreshToken !== failed.refreshToken) return latest;
+    await tokenStore.clearTokens(userId, failed);
+    throw new OneConnectError(
+      "refresh_failed",
+      "The connection to One has expired or was revoked. Ask the user to connect again.",
+      status,
+    );
+  };
+
+  /**
+   * The one place a refresh token is spent. Under the app's lock it
+   * re-reads the store, and refreshes only when `stillNeeded` says the
+   * stored pair still needs it: another process may have refreshed while
+   * this one waited, and spending the same refresh token twice makes One
+   * revoke the grant.
+   */
+  const refreshUnderLock = (
+    userId: string,
+    stillNeeded: (current: OneConnectTokens) => boolean,
+  ): Promise<OneConnectTokens> =>
+    locked(userId, async () => {
+      const current = await tokenStore.loadTokens(userId);
+      if (!current) throw notConnected();
+      if (!stillNeeded(current)) return current;
+
+      // An expired refresh token cannot work, and One answers one with a
+      // server error rather than invalid_grant, so settle it here. The
+      // access token may outlive it (a 90-day or 1-year lifetime): that
+      // one still works, so the pair is kept until it ends too.
+      if (refreshSpent(current))
+        return accessEnding(current) ? retire(userId, current) : current;
+
+      let answer: TokenAnswer;
+      try {
+        answer = await postToken(
+          new URLSearchParams({
+            grant_type: "refresh_token",
+            refresh_token: current.refreshToken,
+          }),
+        );
+      } catch {
+        throw new OneConnectError(
+          "request_failed",
+          "One could not be reached to refresh the connection. The tokens were kept; try again.",
+        );
+      }
+
+      if (answer.ok) {
+        // Both tokens: One rotates the pair on every refresh.
+        const next = toTokens(answer.body);
+        await tokenStore.saveTokens(userId, next);
+        return next;
+      }
+      if (isDeadGrant(answer)) return retire(userId, current, answer.status);
+      // A server error, a rate limit, a misconfigured secret: nothing says
+      // the grant is gone, so keep the tokens and let the caller retry.
+      throw new OneConnectError(
+        "request_failed",
+        `One could not refresh the connection (HTTP ${answer.status}). The tokens were kept; try again.`,
+        answer.status,
+      );
+    });
+
+  /** One refresh per user in this process; concurrent callers share it. */
+  const singleFlight = (
+    userId: string,
+    job: () => Promise<OneConnectTokens>,
+  ): Promise<OneConnectTokens> => {
+    const inFlight = refreshing.get(userId);
+    if (inFlight) return inFlight;
+    const running = job().finally(() => refreshing.delete(userId));
+    refreshing.set(userId, running);
+    return running;
+  };
+
+  const refreshTokens = (userId: string): Promise<OneConnectTokens> =>
+    singleFlight(userId, async () => {
+      const before = await tokenStore.loadTokens(userId);
+      if (!before) throw notConnected();
+      // Rotate the pair seen now; a pair someone else rotated since is
+      // already fresh.
+      return refreshUnderLock(
+        userId,
+        (current) => current.refreshToken === before.refreshToken,
+      );
+    });
+
+  const refreshIfExpiring = async (
+    userId: string,
+    options: RefreshIfExpiringOptions = {},
+  ): Promise<OneConnectTokens> => {
+    const withinMs = options.withinMs ?? REFRESH_MARGIN_MS;
+    const tokens = await tokenStore.loadTokens(userId);
+    if (!tokens) throw notConnected();
+    if (!expiresWithin(tokens, withinMs)) return tokens;
+    // Nothing left to refresh with, and the access token still works.
+    if (refreshSpent(tokens) && !accessEnding(tokens)) return tokens;
+    return singleFlight(userId, () =>
+      refreshUnderLock(userId, (current) => expiresWithin(current, withinMs)),
+    );
+  };
+
+  const getAccessToken = async (userId: string): Promise<string> =>
+    (await refreshIfExpiring(userId)).accessToken;
+
+  return {
+    // Under the lock, so a refresh in flight on another server cannot
+    // interleave with this save.
+    connected: (userId, response) => {
+      const tokens = toTokens(response);
+      return locked(userId, () => tokenStore.saveTokens(userId, tokens));
+    },
+    headers: async (userId) => {
+      const accessToken = await getAccessToken(userId);
+      return {
+        Authorization: `Bearer ${accessToken}`,
+        ...tenancyHeaders(accessToken),
+      };
+    },
+    isConnected: async (userId) => (await tokenStore.loadTokens(userId)) !== null,
+    disconnect: (userId) => tokenStore.clearTokens(userId),
+    // A dead grant surfaces at the refresh, before any call is made.
+    refusal: () => null,
+    getAccessToken,
+    getTokens: (userId) => tokenStore.loadTokens(userId),
+    refreshTokens,
+    refreshIfExpiring,
+  };
+}

package/src/server/types.ts

@@ -3,6 +3,42 @@
  * the app's server and holds the client secret.
  */
 
+/**
+ * How the app holds a user's grant.
+ *
+ * - `"key"`: the app's connect key plus a permanent id per user. Nothing
+ *   expires, so there is nothing to refresh. The default.
+ * - `"token"`: an access token and a refresh token per user, which the
+ *   SDK keeps fresh.
+ */
+export type OneConnectMode = "key" | "token";
+
+/** Key mode: who a stored user is to One, and where their grant lives. */
+export interface OneConnectUserReference {
+  /** One's permanent id for this user, for this app: `cu_…`. */
+  connectUserId: string;
+  /** The organization the user granted from; absent for their personal
+   *  space. */
+  organizationId?: string;
+  /** The project the user granted from, when it was one. */
+  projectId?: string;
+}
+
+/**
+ * Key mode: where the app keeps the one value the SDK gives it per user.
+ * A single string, written when the user connects and the same until
+ * they connect again, so one column on the app's user row is enough.
+ * `userId` is the app's own id for its user.
+ *
+ * It is an identifier, not a credential: it does nothing without the
+ * app's connect key. No lock is needed, because nothing rotates.
+ */
+export interface OneConnectUserStore {
+  saveUser: (userId: string, reference: string) => Promise<void>;
+  loadUser: (userId: string) => Promise<string | null>;
+  clearUser: (userId: string) => Promise<void>;
+}
+
 /** What the app stores per user after the exchange. */
 export interface OneConnectTokens {
   accessToken: string;
@@ -50,11 +86,14 @@ export interface OneConnectTokenStore {
 
 export interface RefreshIfExpiringOptions {
   /** Refresh when the access token or the refresh token expires within
-   *  this many milliseconds. One minute when omitted. */
+   *  this many milliseconds. One minute when omitted. A refresh token
+   *  that has already run out cannot be refreshed: the pair is returned
+   *  as it is while its access token still works. */
   withinMs?: number;
 }
 
-export interface OneConnectServerConfig {
+/** What every app configures, whichever mode it uses. */
+export interface OneConnectBaseConfig {
   /** The app's client id from the dashboard. */
   clientId: string;
   /** The app's client secret. Server only. */
@@ -73,9 +112,39 @@ export interface OneConnectServerConfig {
   /** OAuth scopes. All three tenancy tiers when omitted, so the user may
    *  grant from any space. */
   scopes?: string[];
+}
+
+/**
+ * Key mode, the default: pass the app's connect key and a place to keep
+ * one value per user.
+ */
+export interface OneConnectKeyConfig extends OneConnectBaseConfig {
+  mode?: "key";
+  /** The app's connect key, minted on the app's page in the dashboard.
+   *  Server only. One key per environment. */
+  connectKey: string;
+  userStore: OneConnectUserStore;
+  tokenStore?: never;
+}
+
+/**
+ * Token mode: pass a token store and the SDK keeps each user's tokens
+ * fresh.
+ */
+export interface OneConnectTokenConfig extends OneConnectBaseConfig {
+  mode?: "token";
   tokenStore: OneConnectTokenStore;
+  connectKey?: never;
+  userStore?: never;
 }
 
+/**
+ * The mode is whichever credential is configured: a `connectKey` is key
+ * mode, a `tokenStore` alone is token mode. Set `mode` to say so
+ * explicitly.
+ */
+export type OneConnectServerConfig = OneConnectKeyConfig | OneConnectTokenConfig;
+
 /** The transaction cookie the authorize leg sets and the callback reads. */
 export interface OneConnectCookie {
   name: string;
@@ -170,20 +239,26 @@ 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. */
+   *  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. */
   blockedByGrant: boolean;
   data: unknown;
 }
 
 /**
- * - `not_connected`: no tokens are stored for this user.
- * - `refresh_failed`: One declared the grant dead (revoked, expired or
- *   reused). The tokens were cleared; ask the user to connect again.
+ * - `not_connected`: nothing is stored for this user.
+ * - `reconnect_required` (key mode): One will not act for this user.
+ *   Their consent was revoked, or the app is deactivated. What the app
+ *   stored is kept; ask the user to connect again.
+ * - `refresh_failed` (token mode): One declared the grant dead (revoked,
+ *   expired or reused). The tokens were cleared; ask the user to connect
+ *   again.
  * - `request_failed`: One answered with an error or could not be
- *   reached. During a refresh the tokens are kept, so retry later.
+ *   reached. Nothing stored was changed, so retry later.
  */
 export type OneConnectErrorCode =
   | "not_connected"
+  | "reconnect_required"
   | "refresh_failed"
   | "request_failed";