@withone/connect 0.12.2 → 0.13.0

package/dist/server/index.esm.js

@@ -98,6 +98,27 @@ function tokenScopes(accessToken) {
  * 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.
+ */
+
+/** Key mode: who a stored user is to One, and where their grant lives. */
+
+/**
+ * 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.
+ */
+
 /** What the app stores per user after the exchange. */
 
 /**
@@ -106,6 +127,24 @@ function tokenScopes(accessToken) {
  * `userId` is the app's own id for its user.
  */
 
+/** What every app configures, whichever mode it uses. */
+
+/**
+ * Key mode, the default: pass the app's connect key and a place to keep
+ * one value per user.
+ */
+
+/**
+ * Token mode: pass a token store and the SDK keeps each user's tokens
+ * fresh.
+ */
+
+/**
+ * The mode is whichever credential is configured: a `connectKey` is key
+ * mode, a `tokenStore` alone is token mode. Set `mode` to say so
+ * explicitly.
+ */
+
 /** The transaction cookie the authorize leg sets and the callback reads. */
 
 /** One connection the grant reaches, with the access it confers. */
@@ -113,11 +152,15 @@ function tokenScopes(accessToken) {
 /** One catalog action for a platform. */
 
 /**
- * - `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.
  */
 
 class OneConnectError extends Error {
@@ -129,12 +172,293 @@ class OneConnectError extends Error {
   }
 }
 
+/**
+ * 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.
+ */
+
+
+/** `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.
+ */
+function encodeUserReference(reference) {
+  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. */
+function parseUserReference(value) {
+  const [connectUserId, ...rest] = value.trim().split(SEPARATOR);
+  if (!CONNECT_USER_ID.test(connectUserId)) return null;
+  const reference = {
+    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, body, reason) => body.trim() === `${status} ${reason}`;
+function createKeyCredential(connectKey, userStore) {
+  const load = async userId => {
+    const stored = await userStore.loadUser(userId);
+    return stored ? parseUserReference(stored) : null;
+  };
+  return {
+    connected: async (userId, response) => {
+      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 = {
+        "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
+  };
+}
+
+/**
+ * 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.
+ */
+
+
+/** 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 => !answer.ok && answer.status === 400 && answer.error === "invalid_grant";
+function createTokenCredential(tokenStore, postToken) {
+  /** One refresh in flight per user: two concurrent refreshes with the
+   *  same refresh token trip One's reuse detection. */
+  const refreshing = new Map();
+
+  /** Runs `run` under the app's cross-process lock for this user, when
+   *  the store has one. */
+  const locked = (userId, run) => tokenStore.withLock ? tokenStore.withLock(userId, run) : run();
+
+  /** Whether either token of the pair stops working within `withinMs`. */
+  const expiresWithin = (tokens, withinMs) => {
+    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 => 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 => {
+    const refreshExpiresAt = refreshTokenExpiresAt(tokens.refreshToken);
+    return refreshExpiresAt !== null && refreshExpiresAt <= Date.now();
+  };
+  const toTokens = response => ({
+    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, failed, status) => {
+    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, stillNeeded) => 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;
+    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, job) => {
+    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 => 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, options = {}) => {
+    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 => (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
+  };
+}
+
 /**
  * `@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.
+ * app's server. It starts the flow, completes it, and makes every call
+ * with the grant. The app's secrets never leave here.
  *
+ * An app holds a user's grant in one of two ways, and picks by what it
+ * configures. Everything else is the same in both.
+ *
+ *   // key mode (default): one connect key for the app, one permanent id
+ *   // per user, nothing to refresh
+ *   const oneConnect = createOneConnect({ clientId, clientSecret,
+ *     redirectUri, permissionSet, connectKey, userStore });
+ *
+ *   // token mode: an access and a refresh token per user, kept fresh
  *   const oneConnect = createOneConnect({ clientId, clientSecret,
  *     redirectUri, permissionSet, tokenStore });
  *
@@ -147,40 +471,52 @@ class OneConnectError extends Error {
  *   const reply = await oneConnect.runAction(userId, { connectionKey, actionId, method, path });
  *
  * The Next.js and Node adapters turn the first two into route handlers.
- *
- * Refresh. One's access token lives an hour by default, its refresh token 30
- * days; every refresh rotates both, 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 One declares the
- * grant dead, and never lets a failing old pair delete a newer one.
+ * See `./key` and `./token` for what each mode stores and sends.
  */
-
-/** 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;
 
-/** What One's token endpoint answered. A network failure throws instead. */
+/** What an app does with One in either mode. */
+
+/** The client key mode returns. */
+
+/** The client token mode returns. */
+
+/**
+ * Which mode a config asks for. A stated `mode` wins; otherwise a
+ * connect key means key mode and a token store alone means token mode,
+ * so an app written before key mode existed keeps working untouched.
+ */
+function resolveMode(config) {
+  const given = config;
+  const mode = given.mode ?? (given.connectKey ? "key" : given.tokenStore ? "token" : undefined);
+  if (mode === undefined) {
+    throw new TypeError("createOneConnect needs a credential: pass `connectKey` and `userStore` (key mode, recommended), or `tokenStore` (token mode).");
+  }
+  if (mode !== "key" && mode !== "token") {
+    throw new TypeError('createOneConnect: `mode` is "key" or "token".');
+  }
+  if (mode === "key" && !(given.connectKey && given.userStore)) {
+    throw new TypeError("createOneConnect: key mode needs `connectKey` (mint one on the app's page in the One dashboard) and `userStore`.");
+  }
+  if (mode === "token" && !given.tokenStore) {
+    throw new TypeError("createOneConnect: token mode needs `tokenStore`.");
+  }
+  return mode;
+}
+
+/** Key mode: a connect key for the app and one permanent id per user. */
+
+/** Token mode: an access and a refresh token per user, kept fresh. */
 
-/** 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 => !answer.ok && answer.status === 400 && answer.error === "invalid_grant";
 function createOneConnect(config) {
+  const mode = resolveMode(config);
   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();
   const returnUrl = (status, code) => {
     const url = new URL(returnTo, config.redirectUri);
     url.searchParams.set(RETURN_STATUS_PARAM, status);
@@ -221,21 +557,11 @@ function createOneConnect(config) {
     return answer.body;
   };
 
-  /** Runs `run` under the app's cross-process lock for this user, when
-   *  the store has one. */
-  const locked = (userId, run) => tokenStore.withLock ? tokenStore.withLock(userId, run) : run();
-
-  /** Whether either token of the pair stops working within `withinMs`. */
-  const expiresWithin = (tokens, withinMs) => {
-    const horizon = Date.now() + withinMs;
-    const refreshExpiresAt = refreshTokenExpiresAt(tokens.refreshToken);
-    return tokens.expiresAt <= horizon || refreshExpiresAt !== null && refreshExpiresAt <= horizon;
-  };
-  const toTokens = response => ({
-    accessToken: response.access_token,
-    refreshToken: response.refresh_token,
-    expiresAt: Date.now() + response.expires_in * 1000
-  });
+  // The one thing the modes differ in: what is kept per user, and what
+  // is sent on a call. `resolveMode` already checked each has its parts.
+  const keyCredential = mode === "key" ? createKeyCredential(config.connectKey, config.userStore) : null;
+  const tokenCredential = mode === "token" ? createTokenCredential(config.tokenStore, postToken) : null;
+  const credential = keyCredential ?? tokenCredential;
   const startAuthorization = (input = {}) => {
     const state = createState();
     const verifier = createPkceVerifier();
@@ -274,18 +600,17 @@ function createOneConnect(config) {
     // foreign or forged state; the code is never exchanged in that case.
     if (!code || !state || !verifier) return fail("expired", "The attempt expired, or its state cookie was missing.");
     try {
-      const tokens = toTokens(await exchange(new URLSearchParams({
+      const response = await exchange(new URLSearchParams({
         grant_type: "authorization_code",
         code,
         redirect_uri: config.redirectUri,
         code_verifier: verifier
-      })));
-      // Under the lock, so a refresh in flight on another server cannot
-      // interleave with this save.
-      await locked(input.userId, () => tokenStore.saveTokens(input.userId, tokens));
+      }));
+      // Tokens in token mode, the user's permanent id in key mode.
+      await credential.connected(input.userId, response);
     } 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 fail("failed", status ? `One rejected the code exchange (HTTP ${status}).` : error instanceof OneConnectError ? error.message : "One could not be reached to complete the connection.");
     }
     return {
       outcome: "connected",
@@ -293,94 +618,32 @@ function createOneConnect(config) {
       clearCookieName: cookieName
     };
   };
-  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, failed, status) => {
-    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, stillNeeded) => 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.
-    const refreshExpiresAt = refreshTokenExpiresAt(current.refreshToken);
-    if (refreshExpiresAt !== null && refreshExpiresAt <= Date.now()) return retire(userId, current);
-    let answer;
-    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, job) => {
-    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 => 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, options = {}) => {
-    const withinMs = options.withinMs ?? REFRESH_MARGIN_MS;
-    const tokens = await tokenStore.loadTokens(userId);
-    if (!tokens) throw notConnected();
-    if (!expiresWithin(tokens, withinMs)) return tokens;
-    return singleFlight(userId, () => refreshUnderLock(userId, current => expiresWithin(current, withinMs)));
-  };
-  const getAccessToken = async userId => (await refreshIfExpiring(userId)).accessToken;
   const oneFetch = async (userId, path, init = {}) => {
-    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);
+    for (const [name, value] of Object.entries(await credential.headers(userId))) headers.set(name, value);
     return fetch(`${apiUrl}${path.startsWith("/") ? path : `/${path}`}`, {
       ...init,
       headers
     });
   };
+
+  /**
+   * Whether One still acts for this user at all, asked of the one route
+   * that needs nothing but the credential. Throws when the question
+   * itself cannot be answered, rather than guessing.
+   */
+  const consentStands = async (userId, refused) => {
+    const probe = await oneFetch(userId, "/connections/reachable?limit=1");
+    if (probe.ok) return true;
+    const verdict = credential.refusal(probe.status, await probe.text());
+    if (verdict?.code === refused.code) return false;
+    throw verdict ?? new OneConnectError("request_failed", `One could not confirm the user's consent (HTTP ${probe.status}). Nothing stored was changed; try again.`, probe.status);
+  };
   const listConnections = async userId => {
     const response = await oneFetch(userId, "/connections/reachable");
     if (!response.ok) {
+      const refused = credential.refusal(response.status, await response.text());
+      if (refused) throw refused;
       throw new OneConnectError("request_failed", `One refused the connections request (HTTP ${response.status}).`, response.status);
     }
     const body = await response.json();
@@ -396,6 +659,17 @@ function createOneConnect(config) {
     }));
     const first = await oneFetch(userId, pageUrl(1));
     if (!first.ok) {
+      const refused = credential.refusal(first.status, await first.text());
+      if (refused?.code === "reconnect_required") {
+        // The same bare 403 is what a One API answers when its catalog
+        // does not take the connect key. If the consent stands, that is
+        // what happened, and asking the user to reconnect would not help.
+        if (await consentStands(userId, refused)) {
+          throw new OneConnectError("request_failed", "One's action catalog refused the connect key (HTTP 403) although the user's consent stands: this One API does not accept the connect key on the catalog.", first.status);
+        }
+        throw refused;
+      }
+      if (refused) throw refused;
       throw new OneConnectError("request_failed", `One refused the catalog request (HTTP ${first.status}).`, first.status);
     }
     const page1 = await first.json();
@@ -420,6 +694,24 @@ function createOneConnect(config) {
       body: hasBody ? JSON.stringify(input.body) : undefined
     });
     const text = await response.text();
+    if (!response.ok) {
+      const refused = credential.refusal(response.status, text);
+      if (refused?.code === "reconnect_required") {
+        // One answers a call outside the grant with the same bare 403 it
+        // gives a consent that is gone. Asking what the grant reaches
+        // 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
+        };
+        throw refused;
+      }
+      // One refusing the credential is not an answer to the action.
+      if (refused) throw refused;
+    }
     let data = text;
     try {
       data = JSON.parse(text);
@@ -436,20 +728,32 @@ function createOneConnect(config) {
       data
     };
   };
-  return {
+  const shared = {
     startAuthorization,
     completeAuthorization,
-    isConnected: async userId => (await tokenStore.loadTokens(userId)) !== null,
-    getAccessToken,
-    getTokens: userId => tokenStore.loadTokens(userId),
-    refreshTokens,
-    refreshIfExpiring,
-    disconnect: userId => tokenStore.clearTokens(userId),
+    isConnected: credential.isConnected,
+    disconnect: credential.disconnect,
     listConnections,
     listActions,
     runAction,
     fetch: oneFetch
   };
+  if (keyCredential) {
+    return {
+      mode: "key",
+      ...shared,
+      getConnectUserId: keyCredential.getConnectUserId
+    };
+  }
+  const tokens = tokenCredential;
+  return {
+    mode: "token",
+    ...shared,
+    getAccessToken: tokens.getAccessToken,
+    getTokens: tokens.getTokens,
+    refreshTokens: tokens.refreshTokens,
+    refreshIfExpiring: tokens.refreshIfExpiring
+  };
 }
 
-export { OneConnectError, createOneConnect, refreshTokenExpiresAt, tenancyHeaders, tokenScopes };
+export { OneConnectError, createOneConnect, encodeUserReference, parseUserReference, refreshTokenExpiresAt, tenancyHeaders, tokenScopes };