@nativesquare/soma 0.5.0 → 0.6.0

package/src/component/garmin.ts

@@ -1,5 +1,5 @@
 // ─── Garmin Component Actions ────────────────────────────────────────────────
-// Public actions that handle the full Garmin OAuth + sync lifecycle.
+// Public actions that handle the full Garmin OAuth 2.0 PKCE + sync lifecycle.
 // The host app calls these through the Soma class, which threads the
 // credentials automatically from env vars or constructor config.
 //
@@ -12,7 +12,14 @@ import {
   internalMutation,
   internalQuery,
 } from "./_generated/server.js";
-import { getRequestToken, getAccessToken } from "../garmin/auth.js";
+import {
+  generateCodeVerifier,
+  generateCodeChallenge,
+  generateState,
+  buildAuthUrl,
+  exchangeCode,
+  refreshToken,
+} from "../garmin/auth.js";
 import { GarminClient } from "../garmin/client.js";
 import { transformActivity } from "../garmin/activity.js";
 import { transformDaily } from "../garmin/daily.js";
@@ -29,15 +36,18 @@ const internalApi: any = anyApi;
 // Default sync window: last 30 days
 const DEFAULT_SYNC_DAYS = 30;
 
+// Refresh buffer: refresh tokens 10 minutes before expiry
+const REFRESH_BUFFER_SECONDS = 600;
+
 // ─── Internal Pending OAuth CRUD ─────────────────────────────────────────────
-// Temporary storage for in-progress Garmin OAuth 1.0a flows.
-// Bridges Step 1 (getGarminRequestToken) and Step 3 (completeGarminOAuth).
+// Temporary storage for in-progress Garmin OAuth 2.0 PKCE flows.
+// Bridges getGarminAuthUrl and completeGarminOAuth.
 
 export const storePendingOAuth = internalMutation({
   args: {
     provider: v.string(),
-    oauthToken: v.string(),
-    tokenSecret: v.string(),
+    state: v.string(),
+    codeVerifier: v.string(),
     userId: v.string(),
   },
   returns: v.null(),
@@ -51,14 +61,14 @@ export const storePendingOAuth = internalMutation({
 });
 
 export const getPendingOAuth = internalQuery({
-  args: { oauthToken: v.string() },
+  args: { state: v.string() },
   returns: v.union(
     v.object({
       _id: v.id("pendingOAuth"),
       _creationTime: v.number(),
       provider: v.string(),
-      oauthToken: v.string(),
-      tokenSecret: v.string(),
+      state: v.string(),
+      codeVerifier: v.string(),
       userId: v.string(),
       createdAt: v.number(),
     }),
@@ -67,18 +77,18 @@ export const getPendingOAuth = internalQuery({
   handler: async (ctx, args) => {
     return await ctx.db
       .query("pendingOAuth")
-      .withIndex("by_oauthToken", (q) => q.eq("oauthToken", args.oauthToken))
+      .withIndex("by_state", (q) => q.eq("state", args.state))
       .first();
   },
 });
 
 export const deletePendingOAuth = internalMutation({
-  args: { oauthToken: v.string() },
+  args: { state: v.string() },
   returns: v.null(),
   handler: async (ctx, args) => {
     const pending = await ctx.db
       .query("pendingOAuth")
-      .withIndex("by_oauthToken", (q) => q.eq("oauthToken", args.oauthToken))
+      .withIndex("by_state", (q) => q.eq("state", args.state))
       .first();
     if (pending) {
       await ctx.db.delete(pending._id);
@@ -90,14 +100,15 @@ export const deletePendingOAuth = internalMutation({
 // ─── Internal Token CRUD ─────────────────────────────────────────────────────
 
 /**
- * Store OAuth 1.0a tokens for a Garmin connection.
+ * Store OAuth 2.0 tokens for a Garmin connection.
  * Upserts by connectionId — one token record per connection.
  */
 export const storeTokens = internalMutation({
   args: {
     connectionId: v.id("connections"),
     accessToken: v.string(),
-    tokenSecret: v.string(),
+    refreshToken: v.string(),
+    expiresAt: v.number(),
   },
   returns: v.null(),
   handler: async (ctx, args) => {
@@ -111,7 +122,8 @@ export const storeTokens = internalMutation({
     if (existing) {
       await ctx.db.patch(existing._id, {
         accessToken: args.accessToken,
-        tokenSecret: args.tokenSecret,
+        refreshToken: args.refreshToken,
+        expiresAt: args.expiresAt,
       });
       return null;
     }
@@ -119,7 +131,8 @@ export const storeTokens = internalMutation({
     await ctx.db.insert("providerTokens", {
       connectionId: args.connectionId,
       accessToken: args.accessToken,
-      tokenSecret: args.tokenSecret,
+      refreshToken: args.refreshToken,
+      expiresAt: args.expiresAt,
     });
     return null;
   },
@@ -137,7 +150,6 @@ export const getTokens = internalQuery({
       connectionId: v.id("connections"),
       accessToken: v.string(),
       refreshToken: v.optional(v.string()),
-      tokenSecret: v.optional(v.string()),
       expiresAt: v.optional(v.number()),
     }),
     v.null(),
@@ -176,67 +188,66 @@ export const deleteTokens = internalMutation({
 // ─── Public Actions ──────────────────────────────────────────────────────────
 
 /**
- * Step 1 of OAuth: obtain a request token and return the authorization URL.
+ * Generate a Garmin OAuth 2.0 authorization URL with PKCE.
  *
- * If `userId` is provided, the request token and secret are stored in the
+ * If `userId` is provided, the PKCE code verifier and state are stored in the
  * component's `pendingOAuth` table so that `completeGarminOAuth` can look
  * them up automatically when the callback fires. This is the recommended
  * flow when using `registerRoutes`.
  *
- * If `userId` is omitted, the host app must store the returned `token`
- * and `tokenSecret` itself and pass them to `connectGarmin` manually.
+ * If `userId` is omitted, the host app must store the returned `codeVerifier`
+ * itself and pass it to `connectGarmin` manually.
  */
-export const getGarminRequestToken = action({
+export const getGarminAuthUrl = action({
   args: {
-    consumerKey: v.string(),
-    consumerSecret: v.string(),
-    callbackUrl: v.optional(v.string()),
+    clientId: v.string(),
+    redirectUri: v.optional(v.string()),
     userId: v.optional(v.string()),
   },
   returns: v.object({
-    token: v.string(),
-    tokenSecret: v.string(),
     authUrl: v.string(),
+    state: v.string(),
+    codeVerifier: v.string(),
   }),
   handler: async (ctx, args) => {
-    const result = await getRequestToken({
-      consumerKey: args.consumerKey,
-      consumerSecret: args.consumerSecret,
-      callbackUrl: args.callbackUrl,
+    const codeVerifier = generateCodeVerifier();
+    const codeChallenge = await generateCodeChallenge(codeVerifier);
+    const state = generateState();
+
+    const authUrl = buildAuthUrl({
+      clientId: args.clientId,
+      codeChallenge,
+      redirectUri: args.redirectUri,
+      state,
     });
 
     if (args.userId) {
       await ctx.runMutation(internalApi.garmin.storePendingOAuth, {
         provider: "GARMIN",
-        oauthToken: result.oauthToken,
-        tokenSecret: result.oauthTokenSecret,
+        state,
+        codeVerifier,
         userId: args.userId,
       });
     }
 
-    return {
-      token: result.oauthToken,
-      tokenSecret: result.oauthTokenSecret,
-      authUrl: result.authUrl,
-    };
+    return { authUrl, state, codeVerifier };
   },
 });
 
 /**
- * Step 3 of OAuth + initial sync.
+ * Exchange an authorization code for tokens + initial sync.
  *
- * Exchanges the request token + verifier for permanent access tokens,
- * creates/reactivates the Soma connection, stores tokens, and syncs
- * the last 30 days of all data types.
+ * Used in the manual flow where the host app stores the code verifier
+ * and handles the callback itself.
  */
 export const connectGarmin = action({
   args: {
     userId: v.string(),
-    consumerKey: v.string(),
-    consumerSecret: v.string(),
-    token: v.string(),
-    tokenSecret: v.string(),
-    verifier: v.string(),
+    clientId: v.string(),
+    clientSecret: v.string(),
+    code: v.string(),
+    codeVerifier: v.string(),
+    redirectUri: v.optional(v.string()),
   },
   returns: v.object({
     connectionId: v.string(),
@@ -252,34 +263,29 @@ export const connectGarmin = action({
     ),
   }),
   handler: async (ctx, args) => {
-    // 1. Exchange request token for permanent access token
-    const accessTokenResult = await getAccessToken({
-      consumerKey: args.consumerKey,
-      consumerSecret: args.consumerSecret,
-      token: args.token,
-      tokenSecret: args.tokenSecret,
-      verifier: args.verifier,
+    const tokenResult = await exchangeCode({
+      clientId: args.clientId,
+      clientSecret: args.clientSecret,
+      code: args.code,
+      codeVerifier: args.codeVerifier,
+      redirectUri: args.redirectUri,
     });
 
-    // 2. Create/reactivate the Soma connection
     const connectionId = await ctx.runMutation(publicApi.public.connect, {
       userId: args.userId,
       provider: "GARMIN",
     });
 
-    // 3. Store permanent OAuth tokens
+    const expiresAt = Math.floor(Date.now() / 1000) + tokenResult.expires_in;
     await ctx.runMutation(internalApi.garmin.storeTokens, {
       connectionId,
-      accessToken: accessTokenResult.oauthToken,
-      tokenSecret: accessTokenResult.oauthTokenSecret,
+      accessToken: tokenResult.access_token,
+      refreshToken: tokenResult.refresh_token,
+      expiresAt,
     });
 
-    // 4. Sync last 30 days of all data types
     const client = new GarminClient({
-      consumerKey: args.consumerKey,
-      consumerSecret: args.consumerSecret,
-      accessToken: accessTokenResult.oauthToken,
-      tokenSecret: accessTokenResult.oauthTokenSecret,
+      accessToken: tokenResult.access_token,
     });
 
     const now = Math.floor(Date.now() / 1000);
@@ -292,12 +298,9 @@ export const connectGarmin = action({
     const result = await syncAllTypes(ctx, client, {
       connectionId,
       userId: args.userId,
-      consumerKey: args.consumerKey,
-      consumerSecret: args.consumerSecret,
       timeRange,
     });
 
-    // 5. Update lastDataUpdate timestamp
     await ctx.runMutation(publicApi.public.updateConnection, {
       connectionId,
       lastDataUpdate: new Date().toISOString(),
@@ -312,20 +315,21 @@ export const connectGarmin = action({
 });
 
 /**
- * Complete a Garmin OAuth flow using stored pending state.
+ * Complete a Garmin OAuth 2.0 flow using stored pending state.
  *
  * Used by `registerRoutes` — the callback handler calls this with the
- * `oauth_token` and `oauth_verifier` from the redirect. The action looks
- * up the pending state (tokenSecret, userId) stored during Step 1,
- * exchanges for permanent tokens, creates the connection, syncs data,
- * and cleans up the pending entry.
+ * `code` and `state` from the redirect. The action looks up the pending
+ * state (codeVerifier, userId) stored during `getGarminAuthUrl`,
+ * exchanges for tokens, creates the connection, syncs data, and
+ * cleans up the pending entry.
  */
 export const completeGarminOAuth = action({
   args: {
-    oauthToken: v.string(),
-    oauthVerifier: v.string(),
-    consumerKey: v.string(),
-    consumerSecret: v.string(),
+    code: v.string(),
+    state: v.string(),
+    clientId: v.string(),
+    clientSecret: v.string(),
+    redirectUri: v.optional(v.string()),
   },
   returns: v.object({
     connectionId: v.string(),
@@ -341,50 +345,43 @@ export const completeGarminOAuth = action({
     ),
   }),
   handler: async (ctx, args) => {
-    // 1. Look up pending state
     const pending = await ctx.runQuery(internalApi.garmin.getPendingOAuth, {
-      oauthToken: args.oauthToken,
+      state: args.state,
     });
     if (!pending) {
       throw new Error(
-        "No pending Garmin OAuth state found for this token. " +
-          "The request token may have expired or was already used.",
+        "No pending Garmin OAuth state found for this state parameter. " +
+          "The authorization may have expired or was already used.",
       );
     }
 
-    // 2. Exchange request token for permanent access token
-    const accessTokenResult = await getAccessToken({
-      consumerKey: args.consumerKey,
-      consumerSecret: args.consumerSecret,
-      token: args.oauthToken,
-      tokenSecret: pending.tokenSecret,
-      verifier: args.oauthVerifier,
+    const tokenResult = await exchangeCode({
+      clientId: args.clientId,
+      clientSecret: args.clientSecret,
+      code: args.code,
+      codeVerifier: pending.codeVerifier,
+      redirectUri: args.redirectUri,
     });
 
-    // 3. Delete pending state (no longer needed)
     await ctx.runMutation(internalApi.garmin.deletePendingOAuth, {
-      oauthToken: args.oauthToken,
+      state: args.state,
     });
 
-    // 4. Create/reactivate the Soma connection
     const connectionId = await ctx.runMutation(publicApi.public.connect, {
       userId: pending.userId,
       provider: "GARMIN",
     });
 
-    // 5. Store permanent OAuth tokens
+    const expiresAt = Math.floor(Date.now() / 1000) + tokenResult.expires_in;
     await ctx.runMutation(internalApi.garmin.storeTokens, {
       connectionId,
-      accessToken: accessTokenResult.oauthToken,
-      tokenSecret: accessTokenResult.oauthTokenSecret,
+      accessToken: tokenResult.access_token,
+      refreshToken: tokenResult.refresh_token,
+      expiresAt,
     });
 
-    // 6. Sync last 30 days of all data types
     const client = new GarminClient({
-      consumerKey: args.consumerKey,
-      consumerSecret: args.consumerSecret,
-      accessToken: accessTokenResult.oauthToken,
-      tokenSecret: accessTokenResult.oauthTokenSecret,
+      accessToken: tokenResult.access_token,
     });
 
     const now = Math.floor(Date.now() / 1000);
@@ -397,12 +394,9 @@ export const completeGarminOAuth = action({
     const result = await syncAllTypes(ctx, client, {
       connectionId,
       userId: pending.userId,
-      consumerKey: args.consumerKey,
-      consumerSecret: args.consumerSecret,
       timeRange,
     });
 
-    // 7. Update lastDataUpdate timestamp
     await ctx.runMutation(publicApi.public.updateConnection, {
       connectionId,
       lastDataUpdate: new Date().toISOString(),
@@ -419,14 +413,14 @@ export const completeGarminOAuth = action({
 /**
  * Incremental Garmin sync for an already-connected user.
  *
- * Looks up the stored tokens and syncs all data types for the specified
- * time range (defaults to last 30 days).
+ * Looks up the stored tokens, refreshes if expired, and syncs all data
+ * types for the specified time range (defaults to last 30 days).
  */
 export const syncGarmin = action({
   args: {
     userId: v.string(),
-    consumerKey: v.string(),
-    consumerSecret: v.string(),
+    clientId: v.string(),
+    clientSecret: v.string(),
     startTimeInSeconds: v.optional(v.number()),
     endTimeInSeconds: v.optional(v.number()),
   },
@@ -443,7 +437,6 @@ export const syncGarmin = action({
     ),
   }),
   handler: async (ctx, args) => {
-    // 1. Look up connection
     const connection = await ctx.runQuery(
       internalApi.private.getConnectionByProvider,
       { userId: args.userId, provider: "GARMIN" },
@@ -462,24 +455,42 @@ export const syncGarmin = action({
 
     const connectionId = connection._id;
 
-    // 2. Get stored tokens
     const tokenDoc = await ctx.runQuery(internalApi.garmin.getTokens, {
       connectionId,
     });
-    if (!tokenDoc || !tokenDoc.tokenSecret) {
+    if (!tokenDoc) {
       throw new Error(
         "No Garmin tokens found for this connection. " +
           "The connection may have been created before token storage was available.",
       );
     }
 
-    // 3. Create client and sync
-    const client = new GarminClient({
-      consumerKey: args.consumerKey,
-      consumerSecret: args.consumerSecret,
-      accessToken: tokenDoc.accessToken,
-      tokenSecret: tokenDoc.tokenSecret,
-    });
+    let accessToken = tokenDoc.accessToken;
+
+    // Refresh the token if it's expired or about to expire
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    if (
+      tokenDoc.expiresAt &&
+      tokenDoc.refreshToken &&
+      nowSeconds >= tokenDoc.expiresAt - REFRESH_BUFFER_SECONDS
+    ) {
+      const refreshed = await refreshToken({
+        clientId: args.clientId,
+        clientSecret: args.clientSecret,
+        refreshToken: tokenDoc.refreshToken,
+      });
+
+      accessToken = refreshed.access_token;
+      const newExpiresAt = nowSeconds + refreshed.expires_in;
+      await ctx.runMutation(internalApi.garmin.storeTokens, {
+        connectionId,
+        accessToken: refreshed.access_token,
+        refreshToken: refreshed.refresh_token,
+        expiresAt: newExpiresAt,
+      });
+    }
+
+    const client = new GarminClient({ accessToken });
 
     const now = Math.floor(Date.now() / 1000);
     const timeRange = {
@@ -491,12 +502,9 @@ export const syncGarmin = action({
     const result = await syncAllTypes(ctx, client, {
       connectionId,
       userId: args.userId,
-      consumerKey: args.consumerKey,
-      consumerSecret: args.consumerSecret,
       timeRange,
     });
 
-    // 4. Update lastDataUpdate timestamp
     await ctx.runMutation(publicApi.public.updateConnection, {
       connectionId,
       lastDataUpdate: new Date().toISOString(),
@@ -509,8 +517,8 @@ export const syncGarmin = action({
 /**
  * Disconnect a user from Garmin.
  *
- * Deletes stored tokens and sets the connection to inactive.
- * Garmin OAuth 1.0a tokens can't be revoked via API, so we just clean up locally.
+ * Deregisters the user via the Garmin API (best-effort), deletes stored
+ * tokens, and sets the connection to inactive.
  */
 export const disconnectGarmin = action({
   args: {
@@ -518,7 +526,6 @@ export const disconnectGarmin = action({
   },
   returns: v.null(),
   handler: async (ctx, args) => {
-    // 1. Look up connection
     const connection = await ctx.runQuery(
       internalApi.private.getConnectionByProvider,
       { userId: args.userId, provider: "GARMIN" },
@@ -531,10 +538,21 @@ export const disconnectGarmin = action({
 
     const connectionId = connection._id;
 
-    // 2. Delete stored tokens
+    // Best-effort: deregister user at Garmin
+    const tokenDoc = await ctx.runQuery(internalApi.garmin.getTokens, {
+      connectionId,
+    });
+    if (tokenDoc) {
+      try {
+        const client = new GarminClient({ accessToken: tokenDoc.accessToken });
+        await client.deleteUserRegistration();
+      } catch {
+        // Deregistration is best-effort; proceed with local cleanup
+      }
+    }
+
     await ctx.runMutation(internalApi.garmin.deleteTokens, { connectionId });
 
-    // 3. Set connection inactive
     await ctx.runMutation(publicApi.public.disconnect, {
       userId: args.userId,
       provider: "GARMIN",
@@ -549,8 +567,6 @@ export const disconnectGarmin = action({
 interface SyncAllConfig {
   connectionId: string;
   userId: string;
-  consumerKey: string;
-  consumerSecret: string;
   timeRange: { uploadStartTimeInSeconds: number; uploadEndTimeInSeconds: number };
 }
 

package/src/component/schema.ts

@@ -115,26 +115,25 @@ export default defineSchema({
     .index("by_userId_plannedDate", ["userId", "metadata.planned_date"]),
 
   // ── Provider Tokens ────────────────────────────────────────────────────────
-  // OAuth tokens for cloud-based providers (Strava, Garmin, etc.).
+  // OAuth 2.0 tokens for cloud-based providers (Strava, Garmin, etc.).
   // Stored separately from connections to keep the connection table
   // provider-agnostic. One token record per connection.
   providerTokens: defineTable({
     connectionId: v.id("connections"),
     accessToken: v.string(),
-    refreshToken: v.optional(v.string()), // OAuth 2.0 providers (Strava)
-    tokenSecret: v.optional(v.string()), // OAuth 1.0a providers (Garmin)
-    expiresAt: v.optional(v.number()), // Unix epoch seconds; absent for permanent tokens
+    refreshToken: v.optional(v.string()),
+    expiresAt: v.optional(v.number()),
   }).index("by_connectionId", ["connectionId"]),
 
   // ── Pending OAuth ─────────────────────────────────────────────────────────
-  // Temporary storage for in-progress OAuth flows. Bridges the gap between
-  // initiating OAuth (Step 1) and the callback (Step 3) for providers like
-  // Garmin that use OAuth 1.0a and don't have a `state` parameter.
+  // Temporary storage for in-progress OAuth 2.0 PKCE flows. Bridges the gap
+  // between initiating OAuth (auth URL) and the callback (code exchange).
+  // The `state` parameter links the callback back to the pending entry.
   pendingOAuth: defineTable({
     provider: v.string(),
-    oauthToken: v.string(),
-    tokenSecret: v.string(),
+    state: v.string(),
+    codeVerifier: v.string(),
     userId: v.string(),
     createdAt: v.number(),
-  }).index("by_oauthToken", ["oauthToken"]),
+  }).index("by_state", ["state"]),
 });

package/src/component/strava.ts

@@ -75,7 +75,6 @@ export const getTokens = internalQuery({
       connectionId: v.id("connections"),
       accessToken: v.string(),
       refreshToken: v.optional(v.string()),
-      tokenSecret: v.optional(v.string()),
       expiresAt: v.optional(v.number()),
     }),
     v.null(),