feat(oauth): Sign in with Spoo client half

PKCE S256 pair generation on WebCrypto, authorization URL builder, code
exchange, refresh with rotation, and a single-flight self-refreshing
token provider for the token option. Rejected refreshes throw the new
SessionExpiredError so apps can prompt re-login instead of string
matching. Verified against the RFC 7636 appendix B vector.

Author: Zingzy

CHANGELOG.md

@@ -1,5 +1,14 @@
 # spoo.me
 
+## 0.2.0
+
+### Minor Changes
+
+- Sign in with Spoo for connected apps: spoo.oauth with PKCE pair generation,
+  authorization URL building, code exchange, token refresh with rotation, and a
+  self-refreshing single-flight token provider for `new Spoo({ token })`.
+  Rejected refreshes throw the new SessionExpiredError.
+
 ## 0.1.0
 
 ### Minor Changes

README.md

@@ -110,6 +110,29 @@ const stats = await spoo.public.stats("alias");
 const preview = await spoo.public.preview("alias");
 ```
 
+## Sign in with Spoo (connected apps)
+
+Building an app that acts on behalf of a spoo.me user? The SDK ships the
+client half of the PKCE flow: pair generation, the consent URL, code
+exchange, and a self-refreshing token provider that handles rotation.
+
+```ts
+const pkce = await generatePkcePair();
+const url = spoo.oauth.authorizationUrl({ appId, redirectUri, state, codeChallenge: pkce.challenge });
+// open `url`, receive ?code=... on your redirect URI
+const tokens = await spoo.oauth.exchangeCode({ code, codeVerifier: pkce.verifier });
+
+const client = new Spoo({
+  token: spoo.oauth.tokenProvider({ tokens, onRefresh: persist }),
+});
+```
+
+Your app drives the browser and stores tokens; the SDK never does either.
+Refresh tokens rotate on every refresh, so persist what `onRefresh` hands
+you. A rejected refresh throws `SessionExpiredError`: send the user back
+through login. App ids and redirect URIs are registered with spoo.me and
+matched exactly. See [`examples/sign-in-with-spoo.ts`](./examples/sign-in-with-spoo.ts).
+
 ## Errors
 
 Failed requests throw a typed subclass of `SpooError`:

examples/sign-in-with-spoo.ts

@@ -0,0 +1,43 @@
+// Sign in with Spoo from a connected app (authorization-code + PKCE).
+// The SDK handles the protocol; your app drives the browser and stores tokens.
+// Your app_id and its exact redirect URI must be registered with spoo.me.
+import { Spoo, generatePkcePair, generateState } from "spoo.me";
+
+const spoo = new Spoo(); // anonymous: the flow endpoints need no credentials
+
+// 1. Send the user to consent
+const pkce = await generatePkcePair();
+const state = generateState();
+const url = spoo.oauth.authorizationUrl({
+  appId: "your-app",
+  redirectUri: "http://127.0.0.1:53682/callback",
+  state,
+  codeChallenge: pkce.challenge,
+});
+console.log("Open:", url);
+
+// 2. Your callback receives ?code=...&state=... — verify state, then exchange.
+declare const codeFromCallback: string;
+const tokens = await spoo.oauth.exchangeCode({
+  code: codeFromCallback,
+  codeVerifier: pkce.verifier,
+});
+console.log("Signed in as", tokens.user.email);
+
+// 3. Wrap the pair in a self-refreshing provider and use the API.
+// Refresh tokens rotate: persist every pair onRefresh hands you, the old
+// refresh token is dead the moment it fires.
+const provider = spoo.oauth.tokenProvider({
+  tokens,
+  onRefresh: (next) => saveToSecureStorage(next),
+});
+
+const client = new Spoo({ token: provider });
+for await (const link of await client.links.list()) {
+  console.log(link.alias, link.total_clicks);
+}
+
+// When the refresh token is rejected (grant revoked, session expired), calls
+// throw SessionExpiredError: catch it and send the user back to step 1.
+
+declare function saveToSecureStorage(t: { access_token: string; refresh_token: string }): void;

package.json

@@ -1,6 +1,6 @@
 {
   "name": "spoo.me",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Official TypeScript SDK for the spoo.me link management API",
   "keywords": [
     "spoo.me",

src/client.ts

@@ -4,6 +4,7 @@ import { Stats } from "./resources/stats.js";
 import { PublicLinks } from "./resources/public.js";
 import { Emoji } from "./resources/emoji.js";
 import { Misc } from "./resources/misc.js";
+import { OAuth } from "./resources/oauth.js";
 
 export interface SpooOptions {
   /**
@@ -41,13 +42,17 @@ export class Spoo {
   readonly public: PublicLinks;
   readonly emoji: Emoji;
   readonly misc: Misc;
+  /** Sign in with Spoo, client half: PKCE, code exchange, refreshing tokens. */
+  readonly oauth: OAuth;
 
   /** @internal Transport shared by every resource namespace. */
   readonly _transport: Transport;
 
   constructor(options: SpooOptions = {}) {
     const apiKey = options.apiKey ?? readEnv("SPOO_API_KEY");
 
+    const baseUrl = options.baseUrl ?? "https://spoo.me";
+
     if (apiKey !== undefined && isBrowser() && options.dangerouslyAllowBrowser !== true) {
       throw new Error(
         "Refusing to use an API key in a browser: it would be visible to every visitor. " +
@@ -57,7 +62,7 @@ export class Spoo {
     }
 
     this._transport = new Transport({
-      baseUrl: options.baseUrl ?? "https://spoo.me",
+      baseUrl,
       ...(apiKey !== undefined ? { apiKey } : {}),
       ...(options.token !== undefined ? { token: options.token } : {}),
       ...(options.fetch !== undefined ? { fetch: options.fetch } : {}),
@@ -72,6 +77,7 @@ export class Spoo {
     this.public = new PublicLinks(this._transport);
     this.emoji = new Emoji(this._transport);
     this.misc = new Misc(this._transport);
+    this.oauth = new OAuth(this._transport, baseUrl.replace(/\/+$/, ""));
   }
 }
 

src/core/errors.ts

@@ -168,6 +168,20 @@ export class ServiceUnavailableError extends APIError {
   override name = "ServiceUnavailableError";
 }
 
+/**
+ * A connected-app session can no longer be refreshed: the refresh token was
+ * rejected (rotated away, grant revoked, or expired). The only recovery is
+ * sending the user through Sign in with Spoo again.
+ */
+export class SessionExpiredError extends SpooError {
+  override name = "SessionExpiredError";
+
+  constructor(options?: { cause?: unknown }) {
+    super("Session expired: the refresh token was rejected. Re-authenticate the user.");
+    if (options?.cause !== undefined) this.cause = options.cause;
+  }
+}
+
 /** The request never produced a response (network failure, DNS, reset). */
 export class APIConnectionError extends SpooError {
   override name = "APIConnectionError";

src/core/pkce.ts

@@ -0,0 +1,45 @@
+/**
+ * PKCE (RFC 7636) primitives on WebCrypto, so they run everywhere the SDK
+ * does. spoo.me's device flow mandates S256; plain is not supported.
+ */
+
+export interface PkcePair {
+  /** Random secret the app keeps until the code exchange. 43 chars, base64url. */
+  verifier: string;
+  /** S256 challenge derived from the verifier, sent in the authorization URL. */
+  challenge: string;
+}
+
+export async function generatePkcePair(): Promise<PkcePair> {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  const verifier = base64url(bytes);
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+  return { verifier, challenge: base64url(new Uint8Array(digest)) };
+}
+
+/** Random state parameter for CSRF binding of the authorization redirect. */
+export function generateState(): string {
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  return base64url(bytes);
+}
+
+export function base64url(bytes: Uint8Array): string {
+  let binary = "";
+  for (const b of bytes) binary += String.fromCharCode(b);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+/** Decode a JWT payload without verifying it. Verification is the server's job;
+ * the client only reads `exp` to schedule proactive refresh. */
+export function decodeJwtPayload(token: string): Record<string, unknown> | undefined {
+  const part = token.split(".")[1];
+  if (part === undefined) return undefined;
+  try {
+    const padded = part.replace(/-/g, "+").replace(/_/g, "/");
+    return JSON.parse(atob(padded)) as Record<string, unknown>;
+  } catch {
+    return undefined;
+  }
+}

src/index.ts

@@ -13,6 +13,7 @@ export {
   PayloadTooLargeError,
   ValidationError,
   RateLimitError,
+  SessionExpiredError,
   ContentBlockedError,
   InternalServerError,
   ServiceUnavailableError,
@@ -52,4 +53,12 @@ export {
 } from "./resources/public.js";
 export { Emoji, type EmojiSet, type EmojiEntry } from "./resources/emoji.js";
 export { Misc, type HealthStatus } from "./resources/misc.js";
+export {
+  OAuth,
+  type DeviceTokens,
+  type RefreshedTokens,
+  type AuthorizationUrlParams,
+  type TokenProviderOptions,
+} from "./resources/oauth.js";
+export { generatePkcePair, generateState, type PkcePair } from "./core/pkce.js";
 export type { components as ApiSchema } from "./generated/schema.js";

src/resources/oauth.ts

@@ -0,0 +1,140 @@
+import type { components } from "../generated/schema.js";
+import type { Transport, RequestOptions } from "../core/http.js";
+import { APIError, SessionExpiredError } from "../core/errors.js";
+import { decodeJwtPayload } from "../core/pkce.js";
+
+type Schemas = components["schemas"];
+
+export type DeviceTokens = Schemas["DeviceTokenResponse"];
+export type RefreshedTokens = Schemas["DeviceRefreshResponse"];
+
+export interface AuthorizationUrlParams {
+  /** Your app's id from the spoo.me connected-apps registry. */
+  appId: string;
+  /**
+   * Must exactly match the redirect URI registered for the app; the server
+   * rejects everything else, including a different port.
+   */
+  redirectUri: string;
+  /** CSRF-binding state echoed back on the callback. See `generateState()`. */
+  state: string;
+  /** The S256 challenge from `generatePkcePair()`. */
+  codeChallenge: string;
+}
+
+export interface TokenProviderOptions {
+  /** Current token pair, e.g. from the initial code exchange or app storage. */
+  tokens: { access_token: string; refresh_token: string };
+  /**
+   * Called after every successful refresh with the ROTATED pair. Persist it:
+   * the previous refresh token is dead the moment this fires.
+   */
+  onRefresh?: (tokens: RefreshedTokens) => void | Promise<void>;
+  /** Seconds before `exp` to refresh proactively. Default 30. */
+  expirySkew?: number;
+}
+
+/**
+ * The client half of Sign in with Spoo (authorization-code + PKCE). The SDK
+ * never opens browsers, renders consent, or stores secrets; it provides the
+ * protocol pieces and a self-refreshing credential for `new Spoo({ token })`.
+ */
+export class OAuth {
+  constructor(
+    private readonly transport: Transport,
+    private readonly baseUrl: string,
+  ) {}
+
+  /** The consent-page URL your app opens in a browser. S256 is mandatory. */
+  authorizationUrl(params: AuthorizationUrlParams): string {
+    const url = new URL(this.baseUrl + "/auth/device/login");
+    url.searchParams.set("app_id", params.appId);
+    url.searchParams.set("redirect_uri", params.redirectUri);
+    url.searchParams.set("state", params.state);
+    url.searchParams.set("code_challenge", params.codeChallenge);
+    url.searchParams.set("code_challenge_method", "S256");
+    return url.toString();
+  }
+
+  /**
+   * Exchange the one-time code from the callback for tokens. The code and
+   * verifier are the credentials; no auth header is involved.
+   */
+  async exchangeCode(
+    params: { code: string; codeVerifier: string },
+    opts?: RequestOptions,
+  ): Promise<DeviceTokens> {
+    return this.transport.request(
+      {
+        method: "POST",
+        path: "/auth/device/token",
+        body: { code: params.code, code_verifier: params.codeVerifier },
+      },
+      opts,
+    );
+  }
+
+  /**
+   * Trade a refresh token for a fresh pair. Refresh tokens rotate: the one
+   * you sent is invalid afterwards, and grant scope changes propagate here.
+   * Prefer `tokenProvider`, which handles rotation and persistence for you.
+   */
+  async refreshTokens(refreshToken: string, opts?: RequestOptions): Promise<RefreshedTokens> {
+    try {
+      return await this.transport.request(
+        {
+          method: "POST",
+          path: "/auth/device/refresh",
+          body: { refresh_token: refreshToken },
+        },
+        opts,
+      );
+    } catch (err) {
+      if (err instanceof APIError && (err.status === 401 || err.status === 400)) {
+        throw new SessionExpiredError({ cause: err });
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * A self-refreshing credential for `new Spoo({ token })`. Refreshes
+   * proactively before the access token's `exp`, single-flight (concurrent
+   * calls share one refresh, so a rotated pair is never persisted twice),
+   * and reports every rotation through `onRefresh` for storage.
+   *
+   * Throws `SessionExpiredError` from the pending call when the refresh
+   * token is rejected; catch it to send the user back through login.
+   */
+  tokenProvider(options: TokenProviderOptions): () => Promise<string> {
+    const skewMs = (options.expirySkew ?? 30) * 1000;
+    let access = options.tokens.access_token;
+    let refresh = options.tokens.refresh_token;
+    let expiresAt = readExpiry(access);
+    let inflight: Promise<void> | undefined;
+
+    const doRefresh = async (): Promise<void> => {
+      const next = await this.refreshTokens(refresh);
+      access = next.access_token;
+      refresh = next.refresh_token;
+      expiresAt = readExpiry(access);
+      await options.onRefresh?.(next);
+    };
+
+    return async () => {
+      if (expiresAt === undefined || Date.now() < expiresAt - skewMs) {
+        return access;
+      }
+      inflight ??= doRefresh().finally(() => {
+        inflight = undefined;
+      });
+      await inflight;
+      return access;
+    };
+  }
+}
+
+function readExpiry(accessToken: string): number | undefined {
+  const exp = decodeJwtPayload(accessToken)?.["exp"];
+  return typeof exp === "number" ? exp * 1000 : undefined;
+}

src/version.ts

@@ -1,2 +1,2 @@
 // Generated by scripts/write-version.mjs — do not edit.
-export const SDK_VERSION = "0.1.0";
+export const SDK_VERSION = "0.2.0";