@withone/connect 0.12.2 → 0.13.0

package/dist/server/key.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 } from "./credential";
+import { type OneConnectUserReference, type OneConnectUserStore } from "./types";
+/**
+ * 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 declare function encodeUserReference(reference: OneConnectUserReference): string;
+/** Reads a stored value back. Null when it is not one this SDK wrote. */
+export declare function parseUserReference(value: string): OneConnectUserReference | null;
+export interface KeyCredential extends Credential {
+    getConnectUserId: (userId: string) => Promise<string | null>;
+}
+export declare function createKeyCredential(connectKey: string, userStore: OneConnectUserStore): KeyCredential;

package/dist/server/token.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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 } from "./credential";
+import { type OneConnectTokenStore, type OneConnectTokens, type RefreshIfExpiringOptions } from "./types";
+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 declare function createTokenCredential(tokenStore: OneConnectTokenStore, postToken: PostToken): TokenCredential;

package/dist/server/types.d.ts

@@ -2,6 +2,39 @@
  * Types for `@withone/connect/server`: the half of the SDK that runs on
  * 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;
@@ -47,10 +80,13 @@ 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. */
@@ -69,8 +105,35 @@ 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;
@@ -160,18 +223,23 @@ 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" | "refresh_failed" | "request_failed";
+export type OneConnectErrorCode = "not_connected" | "reconnect_required" | "refresh_failed" | "request_failed";
 export declare class OneConnectError extends Error {
     readonly code: OneConnectErrorCode;
     readonly status?: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@withone/connect",
-  "version": "0.12.2",
+  "version": "0.13.0",
   "description": "One Connect for your app: the button your users press, the two backend routes as one import, and a server client that calls One with the grant. Users keep their connections in One; your app holds only what they granted.",
   "files": [
     "dist",

package/skills/one-connect/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: one-connect
-description: Add One Connect to an application so its users can grant the app scoped, revocable access to their own One-connected tools (Gmail, Slack, Notion, Stripe and 500 more). Use when wiring @withone/connect into an app - the button, the two backend routes, and calling One with the grant.
+description: Add One Connect to an application so its users can grant the app scoped, revocable access to their own One-connected tools (Gmail, Slack, Notion, Stripe and 500 more). Use when wiring @withone/connect into an app - the button, the two backend routes, choosing key mode or token mode, and calling One with the grant.
 ---
 
 # One Connect
@@ -13,12 +13,12 @@ you wire three things: a button, two routes, and the calls made with the grant.
 Browser                    Your backend                          One
 <ConnectButton>  ------>   GET /api/one/authorize   ---302--->  hosted page: sign in, pick tools, set access
                            GET /api/one/callback    <--302----  ?code&state
-                             stores the tokens, redirects home
+                             saves one id for the user, redirects home
                  <------   onSuccess fires
 Later:                     oneConnect.runAction(userId, ...) -> One, grant enforced
 ```
 
-Secrets and tokens stay on the server.
+The client secret and the connect key stay on the server.
 
 ## 1 - Ask the human for these
 
@@ -28,30 +28,91 @@ They create the app in the One dashboard: Developers -> Connect -> New app.
 |---|---|
 | `ONE_CLIENT_ID` | From the app. |
 | `ONE_CLIENT_SECRET` | Starts with `one_secret_`. Shown once. |
+| `ONE_CONNECT_KEY` | Key mode only. On the app's page: Credentials -> Connect key -> Create key. Shown once. It is made for the environment the dashboard is on (Production or Sandbox). |
 | Redirect URI | Registered on the app. Must match the callback route exactly, e.g. `http://localhost:3000/api/one/callback`. |
 | `ONE_PERMISSION_SET` | Optional. The tools and access levels to ask for. |
 | `ONE_API_URL` | Optional. Production when unset; `https://development-api.withone.ai` for the development dashboard. |
 
+Never ask the human to paste the secret or the connect key into the chat.
+Tell them which environment variable to set and read it from there.
+
 ## 2 - Environment (server only)
 
 ```bash
 ONE_CLIENT_ID=...
 ONE_CLIENT_SECRET=one_secret_...
+ONE_CONNECT_KEY=sk_live_...   # key mode
 ONE_REDIRECT_URI=https://yourapp.com/api/one/callback
 ONE_PERMISSION_SET=...        # optional
 ONE_API_URL=...               # optional
 ```
 
-## 3 - Install and create the client
+## 3 - Choose a mode
+
+The server holds a user's grant in one of two ways. The button, the two
+routes and every call are identical in both. The mode is whichever
+credential you pass to `createOneConnect`.
+
+| | Key mode (default) | Token mode |
+|---|---|---|
+| The server holds | one connect key for the app | nothing app-wide |
+| Stored per user | one string, saved once | an access token and a refresh token |
+| Expires | nothing; One checks the consent on every call | the tokens, on the lifetime set on the app |
+| Refreshing | none | the SDK does it; several servers need a shared lock |
+
+How to decide:
+
+- New integration: **key mode**.
+- The app already passes a `tokenStore`: it is in token mode. Leave it as it
+  is unless the human asks to move.
+- The human asks for OAuth bearer tokens: token mode.
+
+```ts
+// key mode
+createOneConnect({ ...app, connectKey: process.env.ONE_CONNECT_KEY!, userStore });
+
+// token mode
+createOneConnect({ ...app, tokenStore });
+```
+
+`mode: "key"` or `mode: "token"` may be added to be explicit.
+`oneConnect.mode` reports which one is running.
+
+## 4 - Install and create the client
 
 ```bash
 npm install @withone/connect
 ```
 
+Key mode:
+
 ```ts
 // lib/one.ts  (server only)
 import { createOneConnect } from "@withone/connect/server";
 
+export const oneConnect = createOneConnect({
+  clientId: process.env.ONE_CLIENT_ID!,
+  clientSecret: process.env.ONE_CLIENT_SECRET!,
+  redirectUri: process.env.ONE_REDIRECT_URI!,
+  permissionSet: process.env.ONE_PERMISSION_SET,
+  oneApiUrl: process.env.ONE_API_URL,
+  connectKey: process.env.ONE_CONNECT_KEY!,
+  userStore: {
+    saveUser: (userId, reference) => /* save the string on the app's user row */,
+    loadUser: (userId) => /* read it; null when never connected */,
+    clearUser: (userId) => /* set it to null */,
+  },
+});
+```
+
+`reference` is one short string: the user's permanent One id and the space
+they granted from. One text column on the user row is enough. Store it as
+given and hand it back unchanged; do not parse or rebuild it. It is an
+identifier, not a secret, so it needs no encryption and no lock.
+
+Token mode:
+
+```ts
 export const oneConnect = createOneConnect({
   clientId: process.env.ONE_CLIENT_ID!,
   clientSecret: process.env.ONE_CLIENT_SECRET!,
@@ -66,13 +127,21 @@ export const oneConnect = createOneConnect({
 });
 ```
 
-Use the app's own user id as the key and the database it already has.
+In token mode, if the app runs more than one server process or a background
+worker, also add `withLock: (userId, run) => ...`, which runs `run()` while
+holding a per-user lock all processes share (for example a Postgres advisory
+lock). The access token lives as long as the app's Token lifetime says (30
+days unless changed under Advanced when creating the app); the refresh token
+lives 30 days. Required: once a day, for each connected user, call
+`oneConnect.refreshIfExpiring(userId, { withinMs: 3 * 24 * 3_600_000 })`. It
+renews both tokens when either is within 3 days of expiring; without it,
+users have to connect again when the tokens run out. Keep the window shorter
+than the Token lifetime, or every run refreshes.
 
-If the app runs more than one server process or a background worker, also
-add `withLock: (userId, run) => ...`, which runs `run()` while holding a
-per-user lock all processes share (for example a Postgres advisory lock).
+In both modes use the app's own user id as the key and the database it
+already has.
 
-## 4 - The two routes
+## 5 - The two routes
 
 Next.js App Router (also Remix, SvelteKit, Hono, Bun):
 
@@ -92,7 +161,7 @@ Express or plain Node: `createOneConnectHandlers(oneConnect, { identifyUser })`
 from `@withone/connect/node`, mounted at `/api/one/authorize` and
 `/api/one/callback`.
 
-## 5 - The button
+## 6 - The button
 
 ```tsx
 import { ConnectButton } from "@withone/connect/react";
@@ -115,7 +184,7 @@ Vue: `@withone/connect/vue`, same props. Svelte: `use:connectButton` from
 `<one-connect-button authorize-url="/api/one/authorize" platforms="gmail, stripe">`.
 A custom button in React: `useOneConnect({ authorizeUrl })` returns `{ open, status }`.
 
-## 6 - Calling One with the grant
+## 7 - Calling One with the grant
 
 ```ts
 const connections = await oneConnect.listConnections(userId);   // [{ key, platform, access }]
@@ -128,26 +197,63 @@ const reply = await oneConnect.runAction(userId, {
   path: action.path,
   body: payload,
 });
-// { status, ok, data }
+// { status, ok, blockedByGrant, data }
+```
+
+A `403` reply means the call is outside what the user granted. Do not retry
+it. In key mode `blockedByGrant` is `true` for those.
+
+Errors are `OneConnectError` with a `code`. Handle them where the app calls One:
+
+| `code` | Mode | Meaning | Do |
+|---|---|---|---|
+| `not_connected` | both | Nothing is stored for this user. | Show the Connect button. |
+| `reconnect_required` | key | One will not act for this user: they revoked access, or the app is deactivated. The stored value is kept. | Ask the user to connect again. |
+| `refresh_failed` | token | The grant ended. The tokens were cleared. | Ask the user to connect again. |
+| `request_failed` | both | One answered with an error or could not be reached. Nothing stored changed. | Retry later. |
+
+```ts
+import { OneConnectError } from "@withone/connect/server";
+
+try {
+  await oneConnect.runAction(userId, action);
+} catch (error) {
+  if (
+    error instanceof OneConnectError &&
+    ["not_connected", "reconnect_required", "refresh_failed"].includes(error.code)
+  ) {
+    // show the Connect button again
+  } else {
+    throw error;
+  }
+}
 ```
 
-A `403` means the call is outside what the user granted. Do not retry it.
-A `refresh_failed` error means the grant ended; ask the user to connect again.
+In key mode `isConnected(userId)` says the user has connected before. One
+confirms the consent on each call, so a user who revoked is found by the
+next call throwing `reconnect_required`.
 
-## 7 - Rules
+## 8 - Rules
 
-- Never put the client secret in browser code, logs or error reports.
-- Store tokens encrypted, keyed by the app's user.
+- Never put the client secret or the connect key in browser code, logs,
+  error reports, source files or prompts. Environment variables only.
+- A connect key works in one environment. Use the Production key against
+  production and the Sandbox key against sandbox.
+- Key mode: store the per-user string as given. Token mode: store tokens
+  encrypted, keyed by the app's user.
 - The registered redirect URI and `ONE_REDIRECT_URI` must be identical.
 - Do not build a completion page; the callback redirect is the completion.
-- Do not write OAuth steps by hand; use the package.
+- Do not write OAuth steps or One request headers by hand; use the package.
+- Do not switch an existing app from one mode to the other unless asked.
 
-## 8 - Done when
+## 9 - Done when
 
 1. The button leads to One's page; after signing in and authorizing, the user
    lands back in the app and `onSuccess` fires.
-2. `listConnections` returns only the granted connections.
-3. `runAction` works for an action inside the grant and returns `403` for
+2. Key mode: one string is saved for the user. Token mode: the tokens are saved.
+3. `listConnections` returns only the granted connections.
+4. `runAction` works for an action inside the grant and returns `403` for
    one outside it.
-4. After the user revokes the app in their One dashboard, the app asks them
-   to connect again.
+5. After the user revokes the app in their One dashboard, the next call
+   fails with `reconnect_required` (key mode) or `refresh_failed` (token
+   mode) and the app asks them to connect again.

package/src/next.ts

@@ -14,7 +14,7 @@
  * That serves /api/one/authorize and /api/one/callback. Register
  * `https://yourapp.com/api/one/callback` as the app's redirect URI.
  */
-import type { OneConnect } from "./server";
+import type { OneConnectClient } from "./server";
 
 export interface OneConnectRoutesOptions {
   /** The app's own id for the signed-in user, or null when nobody is
@@ -80,7 +80,7 @@ export function routeFor(url: string): string {
 }
 
 export function createOneConnectRoutes(
-  oneConnect: OneConnect,
+  oneConnect: Pick<OneConnectClient, "startAuthorization" | "completeAuthorization">,
   options: OneConnectRoutesOptions,
 ): OneConnectRoutes {
   const cookiePath = (): string =>

package/src/node.ts

@@ -17,7 +17,7 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 
 import { createOneConnectRoutes, type OneConnectRoutesOptions } from "@withone/connect/next";
-import type { OneConnect } from "./server";
+import type { OneConnectClient } from "./server";
 
 export interface OneConnectNodeOptions {
   /** The app's own id for the signed-in user, or null when nobody is
@@ -76,7 +76,7 @@ async function send(response: ServerResponse, web: Response): Promise<void> {
 }
 
 export function createOneConnectHandlers(
-  oneConnect: OneConnect,
+  oneConnect: Pick<OneConnectClient, "startAuthorization" | "completeAuthorization">,
   options: OneConnectNodeOptions,
 ): OneConnectHandlers {
   // The web adapter receives a Request; the Node callbacks want the

package/src/server/credential.ts

@@ -0,0 +1,44 @@
+/**
+ * The seam between the two ways an app can hold a user's grant.
+ *
+ * Everything around it is shared: the authorize leg, the callback, and
+ * the calls made with the grant. A credential answers only what differs:
+ * what to keep when a user connects, what to send on a call, and how to
+ * read One refusing it.
+ *
+ * - key mode (`./key`): the app's connect key plus a permanent id for
+ *   the user. Nothing expires, so nothing is refreshed.
+ * - token mode (`./token`): an access token and a refresh token per
+ *   user, rotated before they expire.
+ */
+import type { OneConnectError } from "./types";
+
+/** What One's token endpoint answers on success. `connect_user_id` is
+ *  present whenever a durable grant backs the token. */
+export interface TokenResponse {
+  access_token: string;
+  refresh_token: string;
+  expires_in: number;
+  connect_user_id?: string;
+}
+
+/** What One's token endpoint answered. A network failure throws instead. */
+export type TokenAnswer =
+  | { ok: true; body: TokenResponse }
+  | { ok: false; status: number; error?: string };
+
+export type PostToken = (body: URLSearchParams) => Promise<TokenAnswer>;
+
+export interface Credential {
+  /** The callback exchanged the code: keep what this mode needs. */
+  connected: (userId: string, response: TokenResponse) => Promise<void>;
+  /** The headers that make a /v1 call act for this user. Throws
+   *  `not_connected` when the user has nothing stored. */
+  headers: (userId: string) => Promise<Record<string, string>>;
+  isConnected: (userId: string) => Promise<boolean>;
+  /** Drops the app's copy. The user revokes the grant itself in One. */
+  disconnect: (userId: string) => Promise<void>;
+  /** One refused the credential itself, rather than the call it carried:
+   *  the error to throw, or null when this answer is not that. */
+  refusal: (status: number, body: string) => OneConnectError | null;
+}