@nativesquare/soma 0.5.0 → 0.7.0

package/src/garmin/auth.ts

@@ -1,249 +1,185 @@
-// ─── Garmin OAuth 1.0a Helpers ───────────────────────────────────────────────
-// Pure helper functions for the Garmin OAuth 1.0a three-legged flow.
-// Uses the Web Crypto API for HMAC-SHA1 signing and global `fetch`.
+// ─── Garmin OAuth 2.0 PKCE Helpers ──────────────────────────────────────────
+// Pure helper functions for the Garmin OAuth 2.0 PKCE flow.
+// Uses the Web Crypto API for SHA-256 challenge generation and global `fetch`.
 
-import type {
-  GarminOAuthRequestTokenResponse,
-  GarminOAuthAccessTokenResponse,
-} from "./types.js";
+import type { GarminOAuth2TokenResponse } from "./types.js";
 
-const OAUTH_BASE_URL = "https://connectapi.garmin.com";
-const AUTH_CONFIRM_URL = "https://connect.garmin.com/oauthConfirm";
+const AUTH_URL = "https://connect.garmin.com/oauth2Confirm";
+const TOKEN_URL =
+  "https://diauth.garmin.com/di-oauth2-service/oauth/token";
 
-// ─── OAuth 1.0a Signature ───────────────────────────────────────────────────
+// ─── PKCE Helpers ───────────────────────────────────────────────────────────
+
+const PKCE_CHARSET =
+  "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~";
 
 /**
- * Generate a random nonce for OAuth 1.0a requests.
+ * Generate a cryptographically random code verifier for PKCE.
+ * Returns a 64-character string from the unreserved character set.
  */
-export function generateNonce(): string {
-  const bytes = new Uint8Array(16);
+export function generateCodeVerifier(length = 64): string {
+  const bytes = new Uint8Array(length);
   crypto.getRandomValues(bytes);
-  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+  return Array.from(bytes, (b) => PKCE_CHARSET[b % PKCE_CHARSET.length]).join(
+    "",
+  );
 }
 
 /**
- * Get the current Unix timestamp in seconds.
+ * Generate a random state parameter for CSRF protection.
  */
-export function getTimestamp(): string {
-  return String(Math.floor(Date.now() / 1000));
+export function generateState(): string {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
 }
 
 /**
- * Percent-encode a string per RFC 3986 (used by OAuth 1.0a).
- * Unlike encodeURIComponent, this also encodes `!`, `*`, `'`, `(`, `)`.
+ * Compute the S256 code challenge from a code verifier.
+ * Returns `base64url(sha256(verifier))`.
  */
-export function percentEncode(str: string): string {
-  return encodeURIComponent(str).replace(
-    /[!'()*]/g,
-    (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`,
-  );
+export async function generateCodeChallenge(verifier: string): Promise<string> {
+  const encoder = new TextEncoder();
+  const digest = await crypto.subtle.digest("SHA-256", encoder.encode(verifier));
+  const base64 = btoa(String.fromCharCode(...new Uint8Array(digest)));
+  return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
 
-/**
- * Build the OAuth 1.0a signature base string and compute the HMAC-SHA1 signature.
- *
- * @param method - HTTP method (e.g., "POST", "GET")
- * @param url - The base URL (without query string)
- * @param params - All OAuth + request parameters sorted alphabetically
- * @param consumerSecret - The application's consumer secret
- * @param tokenSecret - The token secret (empty string for request token step)
- */
-export async function buildOAuthSignature(
-  method: string,
-  url: string,
-  params: Record<string, string>,
-  consumerSecret: string,
-  tokenSecret: string = "",
-): Promise<string> {
-  const sortedKeys = Object.keys(params).sort();
-  const paramString = sortedKeys
-    .map((key) => `${percentEncode(key)}=${percentEncode(params[key])}`)
-    .join("&");
-
-  const signatureBaseString = [
-    method.toUpperCase(),
-    percentEncode(url),
-    percentEncode(paramString),
-  ].join("&");
-
-  const signingKey = `${percentEncode(consumerSecret)}&${percentEncode(tokenSecret)}`;
-  const encoder = new TextEncoder();
-  const key = await crypto.subtle.importKey(
-    "raw",
-    encoder.encode(signingKey),
-    { name: "HMAC", hash: "SHA-1" },
-    false,
-    ["sign"],
-  );
-  const signature = await crypto.subtle.sign(
-    "HMAC",
-    key,
-    encoder.encode(signatureBaseString),
-  );
-  return btoa(String.fromCharCode(...new Uint8Array(signature)));
+// ─── Build Authorization URL ────────────────────────────────────────────────
+
+export interface BuildAuthUrlOptions {
+  /** Your Garmin application's Client ID. */
+  clientId: string;
+  /** The code challenge derived from the PKCE code verifier. */
+  codeChallenge: string;
+  /** The URL Garmin will redirect to after authorization. */
+  redirectUri?: string;
+  /** State parameter for CSRF protection (echoed back in the callback). */
+  state?: string;
 }
 
 /**
- * Build the `Authorization: OAuth ...` header value from OAuth parameters.
+ * Build the Garmin OAuth 2.0 authorization URL.
+ *
+ * Redirect the user to this URL to begin the OAuth flow. After the user
+ * grants access, Garmin will redirect back to `redirectUri` with `code`
+ * and `state` query parameters.
  */
-export function buildOAuthHeader(params: Record<string, string>): string {
-  const entries = Object.entries(params)
-    .map(([key, value]) => `${percentEncode(key)}="${percentEncode(value)}"`)
-    .join(", ");
-  return `OAuth ${entries}`;
-}
+export function buildAuthUrl(opts: BuildAuthUrlOptions): string {
+  const params = new URLSearchParams({
+    client_id: opts.clientId,
+    response_type: "code",
+    code_challenge: opts.codeChallenge,
+    code_challenge_method: "S256",
+  });
 
-// ─── Step 1: Get Request Token ──────────────────────────────────────────────
+  if (opts.redirectUri) {
+    params.set("redirect_uri", opts.redirectUri);
+  }
+  if (opts.state) {
+    params.set("state", opts.state);
+  }
+
+  return `${AUTH_URL}?${params.toString()}`;
+}
 
-export interface GetRequestTokenOptions {
-  consumerKey: string;
-  consumerSecret: string;
-  callbackUrl?: string;
+// ─── Exchange Authorization Code ────────────────────────────────────────────
+
+export interface ExchangeCodeOptions {
+  /** Your Garmin application's Client ID. */
+  clientId: string;
+  /** Your Garmin application's Client Secret. */
+  clientSecret: string;
+  /** The authorization code from the OAuth callback. */
+  code: string;
+  /** The original PKCE code verifier (generated in Step 1). */
+  codeVerifier: string;
+  /** The redirect URI used in the authorization request. */
+  redirectUri?: string;
 }
 
 /**
- * Obtain an unauthorized request token from Garmin.
+ * Exchange an authorization code for access and refresh tokens.
  *
- * This is Step 1 of the OAuth 1.0a three-legged flow:
- * 1. Your server calls this function to get a temporary request token
- * 2. Redirect the user to the returned `authUrl`
- * 3. After the user authorizes, exchange the verifier for an access token
+ * Call this from your OAuth callback endpoint after receiving the `code`
+ * query parameter from Garmin.
  *
- * @returns The request token, token secret, and the authorization URL
+ * @returns The token response including `access_token`, `refresh_token`,
+ *          `expires_in`, and `refresh_token_expires_in`.
  */
-export async function getRequestToken(
-  opts: GetRequestTokenOptions,
-): Promise<GarminOAuthRequestTokenResponse & { authUrl: string }> {
-  const url = `${OAUTH_BASE_URL}/oauth-service/oauth/request_token`;
-  const nonce = generateNonce();
-  const timestamp = getTimestamp();
-
-  const oauthParams: Record<string, string> = {
-    oauth_consumer_key: opts.consumerKey,
-    oauth_nonce: nonce,
-    oauth_signature_method: "HMAC-SHA1",
-    oauth_timestamp: timestamp,
-    oauth_version: "1.0",
-  };
-
-  if (opts.callbackUrl) {
-    oauthParams.oauth_callback = opts.callbackUrl;
-  }
+export async function exchangeCode(
+  opts: ExchangeCodeOptions,
+): Promise<GarminOAuth2TokenResponse> {
+  const body = new URLSearchParams({
+    grant_type: "authorization_code",
+    client_id: opts.clientId,
+    client_secret: opts.clientSecret,
+    code: opts.code,
+    code_verifier: opts.codeVerifier,
+  });
 
-  const signature = await buildOAuthSignature(
-    "POST",
-    url,
-    oauthParams,
-    opts.consumerSecret,
-  );
-  oauthParams.oauth_signature = signature;
+  if (opts.redirectUri) {
+    body.set("redirect_uri", opts.redirectUri);
+  }
 
-  const response = await fetch(url, {
+  const response = await fetch(TOKEN_URL, {
     method: "POST",
-    headers: {
-      Authorization: buildOAuthHeader(oauthParams),
-    },
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: body.toString(),
   });
 
   if (!response.ok) {
-    const body = await response.text().catch(() => "");
-    throw new Error(
-      `Garmin OAuth error (getRequestToken): ${response.status} ${response.statusText} — ${body}`,
-    );
-  }
-
-  const responseText = await response.text();
-  const parsed = new URLSearchParams(responseText);
-  const oauthToken = parsed.get("oauth_token");
-  const oauthTokenSecret = parsed.get("oauth_token_secret");
-
-  if (!oauthToken || !oauthTokenSecret) {
+    const text = await response.text().catch(() => "");
     throw new Error(
-      `Garmin OAuth error: unexpected response format — ${responseText}`,
+      `Garmin OAuth error (exchangeCode): ${response.status} ${response.statusText} — ${text}`,
     );
   }
 
-  const authUrl = opts.callbackUrl
-    ? `${AUTH_CONFIRM_URL}?oauth_token=${encodeURIComponent(oauthToken)}&oauth_callback=${encodeURIComponent(opts.callbackUrl)}`
-    : `${AUTH_CONFIRM_URL}?oauth_token=${encodeURIComponent(oauthToken)}`;
-
-  return {
-    oauthToken,
-    oauthTokenSecret,
-    authUrl,
-  };
+  return (await response.json()) as GarminOAuth2TokenResponse;
 }
 
-// ─── Step 3: Exchange for Access Token ──────────────────────────────────────
-
-export interface GetAccessTokenOptions {
-  consumerKey: string;
-  consumerSecret: string;
-  /** The request token from Step 1. */
-  token: string;
-  /** The request token secret from Step 1. */
-  tokenSecret: string;
-  /** The verifier from the OAuth callback (Step 2). */
-  verifier: string;
+// ─── Refresh Token ──────────────────────────────────────────────────────────
+
+export interface RefreshTokenOptions {
+  /** Your Garmin application's Client ID. */
+  clientId: string;
+  /** Your Garmin application's Client Secret. */
+  clientSecret: string;
+  /** The refresh token from a previous token exchange or refresh. */
+  refreshToken: string;
 }
 
 /**
- * Exchange a request token + verifier for a permanent access token.
+ * Refresh an expired access token using a refresh token.
+ *
+ * Garmin access tokens expire after ~24 hours. Call this when the token
+ * is near expiry to obtain a fresh access token. A new refresh token
+ * is returned each time.
  *
- * This is Step 3 of the OAuth 1.0a three-legged flow.
- * The returned access token and secret are permanent — Garmin tokens
- * do not expire and there is no refresh flow.
+ * @returns A new token response with fresh `access_token` and `refresh_token`.
  */
-export async function getAccessToken(
-  opts: GetAccessTokenOptions,
-): Promise<GarminOAuthAccessTokenResponse> {
-  const url = `${OAUTH_BASE_URL}/oauth-service/oauth/access_token`;
-  const nonce = generateNonce();
-  const timestamp = getTimestamp();
-
-  const oauthParams: Record<string, string> = {
-    oauth_consumer_key: opts.consumerKey,
-    oauth_nonce: nonce,
-    oauth_signature_method: "HMAC-SHA1",
-    oauth_timestamp: timestamp,
-    oauth_token: opts.token,
-    oauth_verifier: opts.verifier,
-    oauth_version: "1.0",
-  };
-
-  const signature = await buildOAuthSignature(
-    "POST",
-    url,
-    oauthParams,
-    opts.consumerSecret,
-    opts.tokenSecret,
-  );
-  oauthParams.oauth_signature = signature;
+export async function refreshToken(
+  opts: RefreshTokenOptions,
+): Promise<GarminOAuth2TokenResponse> {
+  const body = new URLSearchParams({
+    grant_type: "refresh_token",
+    client_id: opts.clientId,
+    client_secret: opts.clientSecret,
+    refresh_token: opts.refreshToken,
+  });
 
-  const response = await fetch(url, {
+  const response = await fetch(TOKEN_URL, {
     method: "POST",
-    headers: {
-      Authorization: buildOAuthHeader(oauthParams),
-    },
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: body.toString(),
   });
 
   if (!response.ok) {
-    const body = await response.text().catch(() => "");
-    throw new Error(
-      `Garmin OAuth error (getAccessToken): ${response.status} ${response.statusText} — ${body}`,
-    );
-  }
-
-  const responseText = await response.text();
-  const parsed = new URLSearchParams(responseText);
-  const oauthToken = parsed.get("oauth_token");
-  const oauthTokenSecret = parsed.get("oauth_token_secret");
-
-  if (!oauthToken || !oauthTokenSecret) {
+    const text = await response.text().catch(() => "");
     throw new Error(
-      `Garmin OAuth error: unexpected access token response — ${responseText}`,
+      `Garmin OAuth error (refreshToken): ${response.status} ${response.statusText} — ${text}`,
     );
   }
 
-  return { oauthToken, oauthTokenSecret };
+  return (await response.json()) as GarminOAuth2TokenResponse;
 }