@withone/connect 0.8.2 → 0.9.0

package/dist/react.d.ts

@@ -1,23 +1,6 @@
 import type { CSSProperties, ReactElement } from "react";
-import type { ConnectButtonPlatform } from "./types";
-export interface ConnectButtonProps {
-    /** The app's own backend authorize route ("/api/one/authorize" is
-     *  fine — relative resolves against the page). */
-    authorizeUrl: string;
-    /** Theme for One's hosted page (rides the URL fragment). */
-    appTheme?: "light" | "dark";
-    onSuccess?: () => void;
-    onError?: (error: string) => void;
-    onClose?: () => void;
-    label?: string;
-    variant?: "default" | "accent" | "block";
-    /** Matches the host page, not One's card. */
-    theme?: "light" | "dark";
-    platforms?: ConnectButtonPlatform[];
-    moreCount?: number;
-    description?: string;
-    accentColor?: string;
-    connectedLabel?: string;
+import { type ConnectButtonProps as ConnectButtonCoreProps } from "@withone/connect";
+export interface ConnectButtonProps extends ConnectButtonCoreProps {
     className?: string;
     style?: CSSProperties;
 }

package/dist/react.esm.js

@@ -1 +1 @@
-import{useRef as e,useEffect as t,createElement as n}from"react";function o(e,t,n){return(t=function(e){var t=function(e,t){if("object"!=typeof e||!e)return e;var n=e[Symbol.toPrimitive];if(void 0!==n){var o=n.call(e,t);if("object"!=typeof o)return o;throw new TypeError("@@toPrimitive must return a primitive value.")}return("string"===t?String:Number)(e)}(e,"string");return"symbol"==typeof t?t:t+""}(t))in e?Object.defineProperty(e,t,{value:n,enumerable:!0,configurable:!0,writable:!0}):e[t]=n,e}const i="one_connect",r="one_connect_message";let c=!1;const l=e=>{let t=!1;if("undefined"!=typeof window&&!c){const o=new URLSearchParams(window.location.search),l=o.get(i);if("success"===l||"error"===l){var n;c=!0;const s=null!==(n=o.get(r))&&void 0!==n?n:void 0,a=()=>{const e=new URLSearchParams(window.location.search);(e.has(i)||e.has(r))&&(e.delete(i),e.delete(r),window.history.replaceState(null,"",window.location.pathname+(e.toString()?`?${e.toString()}`:"")+window.location.hash))};a();for(const e of[50,500,2e3])window.setTimeout(a,e);window.setTimeout(()=>{if(!t){t=!0;try{var n,o;"success"===l?null===(n=e.onSuccess)||void 0===n||n.call(e):null===(o=e.onError)||void 0===o||o.call(e,null!=s?s:"The connection was not completed.")}catch{}}},0)}}return{open:()=>{"undefined"!=typeof window&&window.location.assign((()=>{try{const t=new URL(e.authorize.url,"undefined"==typeof window?void 0:window.location.origin);return e.appTheme&&(t.hash=`one_theme=${e.appTheme}`),t.toString()}catch{return e.authorize.url}})())},close:e=>{}}},s="one-connect-button-styles",a="cubic-bezier(.2,.9,.25,1)",d={btnBg:"#0A0C0B",btnFg:"#ffffff",surface:"#ffffff",fg:"#0A0C0B",muted:"#6B7280",line:"#D1D5DB",shadow:"0 1px 2px rgba(10,12,11,.08), 0 4px 14px rgba(10,12,11,.06)"},p={btnBg:"#F2F5F3",btnFg:"#0A0C0B",surface:"#101312",fg:"#F2F5F3",muted:"#8A938E",line:"#2A302D",shadow:"0 1px 2px rgba(0,0,0,.4), 0 8px 24px rgba(0,0,0,.35)"},u="#CCFF00",h="#3FE3A5",m="#0A0C0B";const f=(e,t)=>{var n,o;!function(){if("undefined"==typeof document||document.getElementById(s))return;const e=document.createElement("style");e.id=s,e.textContent=[`.owcb{font:500 14.5px/1.2 inherit;font-family:inherit;letter-spacing:-.01em;cursor:pointer;border:0;display:inline-flex;align-items:center;gap:12px;padding:12px 16px 12px 14px;border-radius:12px;transition:transform .2s ${a},box-shadow .2s ${a},opacity .2s ${a}}`,".owcb:hover{transform:translateY(-1px)}",".owcb:active{transform:translateY(0)}",`.owcb:focus-visible{outline:2px solid ${h};outline-offset:3px}`,".owcb[disabled]{cursor:default;opacity:.75;transform:none}",".owcb-stack{display:inline-flex;align-items:center;flex-shrink:0}",`.owcb-chip{width:22px;height:22px;border-radius:6px;display:grid;place-items:center;overflow:hidden;margin-left:-7px;transition:margin-left .28s ${a};position:relative}`,".owcb-chip:first-child{margin-left:0}",".owcb-chip img{width:14px;height:14px;display:block;object-fit:contain}",".owcb-chip.owcb-more{font-family:ui-monospace,monospace;font-size:9px;font-weight:500;letter-spacing:-.02em}",".owcb:hover .owcb-chip{margin-left:-2px}",".owcb:hover .owcb-chip:first-child{margin-left:0}",".owcb-label{white-space:nowrap}",`.owcb-arrow{opacity:.5;transition:transform .2s ${a},opacity .2s ${a}}`,".owcb:hover .owcb-arrow{transform:translateX(2px);opacity:.8}",".owcb-spinner{width:16px;height:16px;border-radius:50%;border:2px solid currentColor;border-top-color:transparent;opacity:.7;animation:owcb-spin .7s linear infinite}","@keyframes owcb-spin{to{transform:rotate(360deg)}}",".owcb.owcb-block{display:flex;flex-direction:column;align-items:stretch;width:100%;max-width:420px;text-align:left;padding:16px;border-radius:14px;gap:0}",".owcb-block-top{display:flex;align-items:center;justify-content:space-between;gap:12px}",".owcb-block-title{font-size:15px;font-weight:600;letter-spacing:-.01em}",".owcb-block-sub{font-size:13px;line-height:1.5;margin-top:6px;font-weight:400}",".owcb-block-foot{margin-top:14px;padding-top:12px;display:flex;align-items:center;gap:6px;font-size:11.5px;font-weight:400}","@media (prefers-reduced-motion:reduce){.owcb,.owcb-chip,.owcb-arrow{transition:none}.owcb-spinner{animation-duration:1.4s}}"].join("\n"),document.head.appendChild(e)}();const i="dark"===t.theme?p:d,r=null!==(n=t.variant)&&void 0!==n?n:"default",c=null!==(o=t.label)&&void 0!==o?o:"Connect your apps";let f="idle",b=!1;const w=l({...t.connect,onSuccess:()=>{var e,n;x("connected"),null===(e=(n=t.connect).onSuccess)||void 0===e||e.call(n)},onError:e=>{var n,o;x("idle"),null===(n=(o=t.connect).onError)||void 0===n||n.call(o,e)},onClose:()=>{var e,n;x("idle"),null===(e=(n=t.connect).onClose)||void 0===e||e.call(n)}}),v=document.createElement("button");v.type="button",v.className="block"===r?"owcb owcb-block":"owcb",v.addEventListener("click",()=>{"idle"!==f&&"connected"!==f||(x("connecting"),w.open())});const g=()=>{var e,n,o;const l="accent"===r,s="block"===r,a=s?i.surface:l?null!==(e=t.accentColor)&&void 0!==e?e:u:i.btnBg,d=s?i.fg:l?m:i.btnFg,p=s?i.surface:a,b=m;v.style.background="connected"!==f||s?a:h,v.style.color="connected"!==f||s?d:m,v.style.boxShadow=s?`inset 0 0 0 1px ${i.line}`:"connected"===f?"none":l?`0 1px 2px rgba(10,12,11,.1), 0 6px 20px ${null!==(n=t.accentColor)&&void 0!==n?n:u}38`:i.shadow,v.disabled="connecting"===f,v.innerHTML="";const w=function(e,t,n){var o,i;const r=null!==(o=e.platforms)&&void 0!==o?o:[];if(0===r.length&&!e.moreCount)return null;const c=document.createElement("span");c.className="owcb-stack",c.setAttribute("aria-hidden","true");for(const e of r.slice(0,3)){const n=document.createElement("span");if(n.className="owcb-chip",n.style.background="#ffffff",n.style.boxShadow=`0 0 0 1.5px ${t}`,e.imageUrl){const t=document.createElement("img");t.alt="",t.src=e.imageUrl,t.addEventListener("error",()=>{t.style.display="none",n.textContent=e.name.charAt(0).toUpperCase(),n.style.font="600 10px ui-monospace,monospace",n.style.color=m}),n.appendChild(t)}else n.textContent=e.name.charAt(0).toUpperCase(),n.style.font="600 10px ui-monospace,monospace",n.style.color=m;c.appendChild(n)}const l=(null!==(i=e.moreCount)&&void 0!==i?i:0)+Math.max(0,r.length-3);if(l>0){const e=document.createElement("span");e.className="owcb-chip owcb-more",e.style.background="#ffffff",e.style.boxShadow=`0 0 0 1.5px ${t}`,e.style.color=n,e.textContent=`+${l}`,c.appendChild(e)}return c}(t,p,b);if(s){var g;const e=document.createElement("span");e.className="owcb-block-top";const n=document.createElement("span");if(n.className="owcb-block-title",n.textContent="connecting"===f?"Connecting…":"connected"===f?null!==(g=t.connectedLabel)&&void 0!==g?g:"Connected":c,e.appendChild(n),"connecting"===f){const t=document.createElement("span");t.className="owcb-spinner",e.appendChild(t)}else w&&e.appendChild(w);if(v.appendChild(e),t.description&&"idle"===f){const e=document.createElement("span");e.className="owcb-block-sub",e.style.color=i.muted,e.textContent=t.description,v.appendChild(e)}const o=document.createElement("span");return o.className="owcb-block-foot",o.style.color=i.muted,o.style.borderTop=`1px solid ${i.line}`,o.innerHTML=`<span style="font-size:11px;color:${i.muted}">Secured by</span><span style="display:inline-flex;color:${i.fg}"><svg viewBox="0 0 24 24" width="12" height="12" fill="none" stroke="currentColor" stroke-width="2.4" style="flex-shrink:0"><circle cx="12" cy="12" r="8.5"/></svg></span><span style="font-size:12px;font-weight:600;letter-spacing:-0.02em;color:${i.fg}">one</span>`,void v.appendChild(o)}if("connecting"===f){const e=document.createElement("span");e.className="owcb-spinner",v.appendChild(e)}else if("connected"===f){const e=document.createElement("span");e.innerHTML='<svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="width:16px;height:16px"><path d="M3 8.5l3.5 3.5L13 5"/></svg>',e.style.display="inline-flex",v.appendChild(e)}else w&&v.appendChild(w);const x=document.createElement("span");if(x.className="owcb-label",x.textContent="connecting"===f?"Connecting…":"connected"===f?null!==(o=t.connectedLabel)&&void 0!==o?o:"Connected":c,v.appendChild(x),"idle"===f){const e=document.createElement("span");e.innerHTML='<svg class="owcb-arrow" width="14" height="14" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"><path d="M6 3l5 5-5 5"/></svg>',e.style.display="inline-flex",v.appendChild(e)}},x=e=>{b||(f=e,g())};return g(),e.appendChild(v),{setState:x,destroy:()=>{b=!0,w.close({keepResult:!0}),v.remove()}}};function b(o){var i;const r=e(null),c=e(null),l=e({onSuccess:o.onSuccess,onError:o.onError,onClose:o.onClose});l.current={onSuccess:o.onSuccess,onError:o.onError,onClose:o.onClose};const s=JSON.stringify(null!==(i=o.platforms)&&void 0!==i?i:[]);return t(()=>{if(!r.current)return;const e={connect:{authorize:{url:o.authorizeUrl},appTheme:o.appTheme,onSuccess:()=>{var e,t;return null===(e=(t=l.current).onSuccess)||void 0===e?void 0:e.call(t)},onError:e=>{var t,n;return null===(t=(n=l.current).onError)||void 0===t?void 0:t.call(n,e)},onClose:()=>{var e,t;return null===(e=(t=l.current).onClose)||void 0===e?void 0:e.call(t)}},label:o.label,variant:o.variant,theme:o.theme,platforms:o.platforms,moreCount:o.moreCount,description:o.description,accentColor:o.accentColor,connectedLabel:o.connectedLabel};return c.current=f(r.current,e),()=>{var e;null===(e=c.current)||void 0===e||e.destroy(),c.current=null}},[o.authorizeUrl,o.appTheme,o.label,o.variant,o.theme,s,o.moreCount,o.description,o.accentColor,o.connectedLabel]),n("div",{ref:r,className:o.className,style:o.style})}!function(){if("undefined"!=typeof window&&"undefined"!=typeof customElements&&!customElements.get("one-connect-button")){class e extends HTMLElement{constructor(...e){super(...e),o(this,"onSuccess",null),o(this,"onError",null),o(this,"onClose",null),o(this,"handle",null)}connectedCallback(){this.mount()}disconnectedCallback(){var e;null===(e=this.handle)||void 0===e||e.destroy(),this.handle=null}attributeChangedCallback(){this.isConnected&&this.handle&&this.mount()}mount(){var e,t,n,o,i,r,c,l;null===(e=this.handle)||void 0===e||e.destroy(),this.handle=null;const s=this.getAttribute("authorize-url");if(!s)return;let a;const d=this.getAttribute("platforms");if(d)try{const e=JSON.parse(d);Array.isArray(e)&&(a=e)}catch{}const p=this.getAttribute("more-count"),u=p?parseInt(p,10):void 0;this.handle=f(this,{connect:{authorize:{url:s},appTheme:null!==(t=this.getAttribute("app-theme"))&&void 0!==t?t:void 0,onSuccess:()=>{var e;null===(e=this.onSuccess)||void 0===e||e.call(this),this.dispatchEvent(new CustomEvent("success"))},onError:e=>{var t;null===(t=this.onError)||void 0===t||t.call(this,e),this.dispatchEvent(new CustomEvent("error",{detail:e}))},onClose:()=>{var e;null===(e=this.onClose)||void 0===e||e.call(this),this.dispatchEvent(new CustomEvent("close"))}},label:null!==(n=this.getAttribute("label"))&&void 0!==n?n:void 0,variant:null!==(o=this.getAttribute("variant"))&&void 0!==o?o:void 0,theme:null!==(i=this.getAttribute("theme"))&&void 0!==i?i:void 0,platforms:a,moreCount:Number.isFinite(u)?u:void 0,description:null!==(r=this.getAttribute("description"))&&void 0!==r?r:void 0,accentColor:null!==(c=this.getAttribute("accent-color"))&&void 0!==c?c:void 0,connectedLabel:null!==(l=this.getAttribute("connected-label"))&&void 0!==l?l:void 0})}}o(e,"observedAttributes",["authorize-url","app-theme","label","variant","theme","platforms","more-count","description","accent-color","connected-label"]),customElements.define("one-connect-button",e)}}();export{b as ConnectButton};
+import{useRef as r,useEffect as n,createElement as o}from"react";import{propsIdentity as c,mountConnectButton as e,optionsFromProps as u}from"@withone/connect";function t(t){const s=r(null),l=r(null),i=r({onSuccess:t.onSuccess,onError:t.onError});i.current={onSuccess:t.onSuccess,onError:t.onError};const a=c(t);return n(()=>{if(s.current)return l.current=e(s.current,u(t,{onSuccess:()=>{var r,n;return null===(r=(n=i.current).onSuccess)||void 0===r?void 0:r.call(n)},onError:r=>{var n,o;return null===(n=(o=i.current).onError)||void 0===n?void 0:n.call(o,r)}})),()=>{var r;null===(r=l.current)||void 0===r||r.destroy(),l.current=null}},[a]),o("div",{ref:s,className:t.className,style:t.style})}export{t as ConnectButton};

package/dist/return.d.ts

@@ -0,0 +1,11 @@
+import type { OneConnectReturn } from "./types";
+/** Reads the outcome the callback route put on the return URL. */
+export declare function parseReturn(search: string): OneConnectReturn | null;
+/** The same URL without the return params, so a refresh does not
+ *  re-fire the callbacks. */
+export declare function stripReturnParams(location: {
+    pathname: string;
+    search: string;
+    hash: string;
+}): string;
+export declare function hasReturnParams(search: string): boolean;

package/dist/server/index.cjs.js

@@ -0,0 +1,349 @@
+'use strict';
+
+var node_crypto = require('node:crypto');
+
+/** Query params the app's callback route puts on its final redirect.
+ *  The SDK reads them off the page URL when the tab comes home, so
+ *  there is no completion page to build. */
+const RETURN_STATUS_PARAM = "one_connect";
+const RETURN_MESSAGE_PARAM = "one_connect_message";
+
+/** One's production API. Point `oneApiUrl` elsewhere for development. */
+const DEFAULT_ONE_API_URL = "https://api.withone.ai";
+
+/** 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. */
+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. */
+const TX_COOKIE_MAX_AGE_SECONDS = 1800;
+const DEFAULT_SCOPES = ["user:connections:read", "user:connections:write", "org:connections:read", "org:connections:write", "project:connections:read", "project:connections:write"];
+function createState() {
+  return node_crypto.randomBytes(16).toString("hex");
+}
+function createPkceVerifier() {
+  return node_crypto.randomBytes(32).toString("base64url");
+}
+function pkceChallenge(verifier) {
+  return node_crypto.createHash("sha256").update(verifier).digest("base64url");
+}
+function txCookieName(state) {
+  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. */
+function txCookie(state, verifier, redirectUri) {
+  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
+    }
+  };
+}
+function basicAuthorization(clientId, clientSecret) {
+  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. */
+function tenancyHeaders(accessToken) {
+  try {
+    const payload = JSON.parse(Buffer.from(accessToken.split(".")[1], "base64url").toString());
+    const headers = {};
+    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. */
+function tokenScopes(accessToken) {
+  try {
+    const payload = JSON.parse(Buffer.from(accessToken.split(".")[1], "base64url").toString());
+    return (payload.scope ?? "").split(" ").filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * 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. */
+
+/**
+ * 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.
+ */
+
+/** The transaction cookie the authorize leg sets and the callback reads. */
+
+/** One connection the grant reaches, with the access it confers. */
+
+/** One catalog action for a platform. */
+
+class OneConnectError extends Error {
+  constructor(code, message, status) {
+    super(message);
+    this.name = "OneConnectError";
+    this.code = code;
+    this.status = status;
+  }
+}
+
+/**
+ * `@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.
+ */
+
+/** 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;
+function createOneConnect(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, message) => {
+    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 => {
+    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();
+  };
+  const toTokens = response => ({
+    accessToken: response.access_token,
+    refreshToken: response.refresh_token,
+    expiresAt: Date.now() + response.expires_in * 1000
+  });
+  const startAuthorization = (input = {}) => {
+    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 => {
+    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, message) => ({
+      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 => {
+    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 => {
+    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, 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);
+    return fetch(`${apiUrl}${path.startsWith("/") ? path : `/${path}`}`, {
+      ...init,
+      headers
+    });
+  };
+  const listConnections = async userId => {
+    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();
+    return body.rows ?? [];
+  };
+  const listActions = async (userId, platform) => {
+    const pageUrl = page => `/knowledge?connectionPlatform=${encodeURIComponent(platform)}&limit=${CATALOG_PAGE_SIZE}&page=${page}`;
+    const slim = rows => 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();
+    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() : null).catch(() => null)));
+    return slim([page1, ...rest].flatMap(page => page?.rows ?? []));
+  };
+  const runAction = async (userId, input) => {
+    const method = input.method.toUpperCase();
+    const query = input.query ? `?${new URLSearchParams(input.query)}` : "";
+    const headers = {
+      "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 = 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;
+    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
+  };
+}
+
+exports.OneConnectError = OneConnectError;
+exports.createOneConnect = createOneConnect;
+exports.tenancyHeaders = tenancyHeaders;
+exports.tokenScopes = tokenScopes;

package/dist/server/index.d.ts

@@ -0,0 +1,32 @@
+import { 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";
+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 declare function createOneConnect(config: OneConnectServerConfig): OneConnect;