@clipin/convex-wearables 0.0.2 → 0.1.0

package/src/component/oauthActions.ts

@@ -0,0 +1,261 @@
+/**
+ * OAuth flow Convex actions.
+ *
+ * Actions (not mutations) because they make external HTTP calls to
+ * provider token endpoints and APIs.
+ */
+
+import { v } from "convex/values";
+import { api, internal } from "./_generated/api";
+import { action, internalAction } from "./_generated/server";
+import {
+  buildAuthorizationUrl,
+  exchangeCodeForTokens,
+  generateCodeChallenge,
+  generateRandomString,
+  refreshAccessToken,
+} from "./providers/oauth";
+import { getProvider } from "./providers/registry";
+import type { ProviderCredentials } from "./providers/types";
+import { providerName } from "./schema";
+
+// ---------------------------------------------------------------------------
+// Generate authorization URL
+// ---------------------------------------------------------------------------
+
+/**
+ * Generate an OAuth authorization URL for a provider.
+ *
+ * Stores the state token in the oauthStates table and returns the URL
+ * the client should redirect the user to.
+ */
+export const generateAuthUrl = action({
+  args: {
+    userId: v.string(),
+    provider: providerName,
+    clientId: v.string(),
+    clientSecret: v.string(),
+    subscriptionKey: v.optional(v.string()),
+    redirectUri: v.string(),
+  },
+  returns: v.string(),
+  handler: async (ctx, args) => {
+    await ctx.runMutation(internal.providerSettings.upsertCredentials, {
+      provider: args.provider,
+      clientId: args.clientId,
+      clientSecret: args.clientSecret,
+      subscriptionKey: args.subscriptionKey,
+    });
+
+    const providerDef = getProvider(args.provider);
+    if (!providerDef) {
+      throw new Error(`Provider "${args.provider}" is not implemented`);
+    }
+
+    const credentials: ProviderCredentials = {
+      clientId: args.clientId,
+      clientSecret: args.clientSecret,
+      subscriptionKey: args.subscriptionKey,
+    };
+    const config = providerDef.oauthConfig(credentials);
+
+    // Generate state token
+    const state = generateRandomString(32);
+
+    // PKCE if the provider requires it
+    let codeVerifier: string | undefined;
+    let codeChallenge: string | undefined;
+    if (config.usePkce) {
+      codeVerifier = generateRandomString(64);
+      codeChallenge = await generateCodeChallenge(codeVerifier);
+    }
+
+    // Store state in the database for validation during callback
+    await ctx.runMutation(internal.oauthStates.store, {
+      state,
+      userId: args.userId,
+      provider: args.provider,
+      codeVerifier,
+      redirectUri: args.redirectUri,
+    });
+
+    // Build the authorization URL
+    const url = buildAuthorizationUrl({
+      config,
+      redirectUri: args.redirectUri,
+      state,
+      codeChallenge,
+    });
+
+    return url;
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Handle OAuth callback (exchange code for tokens)
+// ---------------------------------------------------------------------------
+
+/**
+ * Handle the OAuth callback. Consumes the state token, exchanges the
+ * authorization code for access/refresh tokens, fetches the user's
+ * provider profile, and creates/updates the connection.
+ */
+export const handleCallback = action({
+  args: {
+    state: v.string(),
+    code: v.string(),
+    clientId: v.string(),
+    clientSecret: v.string(),
+    subscriptionKey: v.optional(v.string()),
+  },
+  returns: v.object({
+    provider: v.string(),
+    userId: v.string(),
+    connectionId: v.string(),
+  }),
+  handler: async (ctx, args) => {
+    // Consume the state token
+    const oauthState = await ctx.runMutation(internal.oauthStates.consume, {
+      state: args.state,
+    });
+
+    if (!oauthState) {
+      throw new Error("Invalid or expired OAuth state");
+    }
+
+    const providerDef = getProvider(oauthState.provider);
+    if (!providerDef) {
+      throw new Error(`Provider "${oauthState.provider}" is not implemented`);
+    }
+
+    await ctx.runMutation(internal.providerSettings.upsertCredentials, {
+      provider: oauthState.provider,
+      clientId: args.clientId,
+      clientSecret: args.clientSecret,
+      subscriptionKey: args.subscriptionKey,
+    });
+
+    const credentials: ProviderCredentials = {
+      clientId: args.clientId,
+      clientSecret: args.clientSecret,
+      subscriptionKey: args.subscriptionKey,
+    };
+    const config = providerDef.oauthConfig(credentials);
+
+    // Exchange code for tokens
+    const tokenResponse = await exchangeCodeForTokens(
+      config,
+      args.code,
+      oauthState.redirectUri ?? "",
+      oauthState.codeVerifier,
+    );
+
+    // Fetch user info from the provider
+    if (providerDef.postConnect) {
+      await providerDef.postConnect(
+        tokenResponse.access_token,
+        tokenResponse,
+        oauthState.userId,
+        credentials,
+      );
+    }
+
+    const userInfo = await providerDef.getUserInfo(
+      tokenResponse.access_token,
+      tokenResponse,
+      oauthState.userId,
+      credentials,
+    );
+
+    // Calculate token expiry
+    const tokenExpiresAt = tokenResponse.expires_in
+      ? Date.now() + tokenResponse.expires_in * 1000
+      : undefined;
+
+    // Create or update the connection
+    const connectionId = await ctx.runMutation(internal.connections.createConnection, {
+      userId: oauthState.userId,
+      provider: oauthState.provider,
+      providerUserId: userInfo.providerUserId ?? undefined,
+      providerUsername: userInfo.username ?? undefined,
+      accessToken: tokenResponse.access_token,
+      refreshToken: tokenResponse.refresh_token,
+      tokenExpiresAt,
+      scope: tokenResponse.scope,
+    });
+
+    // Create a data source for this connection
+    await ctx.runMutation(api.dataSources.getOrCreate, {
+      userId: oauthState.userId,
+      provider: oauthState.provider,
+      connectionId,
+      source: oauthState.provider,
+    });
+
+    return {
+      provider: oauthState.provider,
+      userId: oauthState.userId,
+      connectionId: String(connectionId),
+    };
+  },
+});
+
+/**
+ * Ensure a connection has a valid (non-expired) access token.
+ * If expired, refreshes the token and updates the connection.
+ * Returns the valid access token.
+ */
+export const ensureValidToken = internalAction({
+  args: {
+    connectionId: v.id("connections"),
+    provider: providerName,
+    accessToken: v.string(),
+    refreshToken: v.optional(v.string()),
+    tokenExpiresAt: v.optional(v.number()),
+    clientId: v.string(),
+    clientSecret: v.string(),
+    subscriptionKey: v.optional(v.string()),
+  },
+  returns: v.string(), // valid access token
+  handler: async (ctx, args) => {
+    // Check if token is still valid (with 5-minute buffer)
+    const bufferMs = 5 * 60 * 1000;
+    if (args.tokenExpiresAt && args.tokenExpiresAt - bufferMs > Date.now()) {
+      return args.accessToken;
+    }
+
+    // Token is expired or about to expire — refresh it
+    if (!args.refreshToken) {
+      throw new Error(
+        `Token expired for ${args.provider} connection and no refresh token available`,
+      );
+    }
+
+    const providerDef = getProvider(args.provider);
+    if (!providerDef) {
+      throw new Error(`Provider "${args.provider}" is not implemented`);
+    }
+
+    const credentials: ProviderCredentials = {
+      clientId: args.clientId,
+      clientSecret: args.clientSecret,
+      subscriptionKey: args.subscriptionKey,
+    };
+    const config = providerDef.oauthConfig(credentials);
+    const tokenResponse = await refreshAccessToken(config, args.refreshToken);
+
+    const newExpiresAt = tokenResponse.expires_in
+      ? Date.now() + tokenResponse.expires_in * 1000
+      : undefined;
+
+    // Update the connection with new tokens
+    await ctx.runMutation(internal.connections.updateTokens, {
+      connectionId: args.connectionId,
+      accessToken: tokenResponse.access_token,
+      refreshToken: tokenResponse.refresh_token ?? args.refreshToken,
+      tokenExpiresAt: newExpiresAt,
+    });
+
+    return tokenResponse.access_token;
+  },
+});

package/src/component/oauthStates.test.ts

@@ -0,0 +1,170 @@
+import { convexTest } from "convex-test";
+import { describe, expect, it } from "vitest";
+import schema from "./schema";
+import { modules } from "./test.setup";
+
+describe("oauthStates", () => {
+  it("stores and retrieves a state by token", async () => {
+    const t = convexTest(schema, modules);
+
+    const id = await t.run(async (ctx) => {
+      return await ctx.db.insert("oauthStates", {
+        state: "random-state-abc",
+        userId: "user-1",
+        provider: "strava",
+        createdAt: Date.now(),
+      });
+    });
+
+    const found = await t.run(async (ctx) => {
+      return await ctx.db
+        .query("oauthStates")
+        .withIndex("by_state", (idx) => idx.eq("state", "random-state-abc"))
+        .first();
+    });
+
+    expect(found).not.toBeNull();
+    expect(found?._id).toBe(id);
+    expect(found?.userId).toBe("user-1");
+    expect(found?.provider).toBe("strava");
+  });
+
+  it("stores PKCE code verifier and redirect URI", async () => {
+    const t = convexTest(schema, modules);
+
+    await t.run(async (ctx) => {
+      await ctx.db.insert("oauthStates", {
+        state: "pkce-state-123",
+        userId: "user-1",
+        provider: "suunto",
+        codeVerifier: "verifier-abc-xyz",
+        redirectUri: "https://example.com/callback",
+        createdAt: Date.now(),
+      });
+    });
+
+    const found = await t.run(async (ctx) => {
+      return await ctx.db
+        .query("oauthStates")
+        .withIndex("by_state", (idx) => idx.eq("state", "pkce-state-123"))
+        .first();
+    });
+
+    expect(found?.codeVerifier).toBe("verifier-abc-xyz");
+    expect(found?.redirectUri).toBe("https://example.com/callback");
+  });
+
+  it("consumes state (read and delete)", async () => {
+    const t = convexTest(schema, modules);
+
+    await t.run(async (ctx) => {
+      await ctx.db.insert("oauthStates", {
+        state: "consume-me",
+        userId: "user-1",
+        provider: "strava",
+        createdAt: Date.now(),
+      });
+    });
+
+    // Consume: read and delete
+    const consumed = await t.run(async (ctx) => {
+      const record = await ctx.db
+        .query("oauthStates")
+        .withIndex("by_state", (idx) => idx.eq("state", "consume-me"))
+        .first();
+      if (record) {
+        await ctx.db.delete(record._id);
+      }
+      return record;
+    });
+
+    expect(consumed).not.toBeNull();
+    expect(consumed?.provider).toBe("strava");
+
+    // Verify it's gone
+    const afterConsume = await t.run(async (ctx) => {
+      return await ctx.db
+        .query("oauthStates")
+        .withIndex("by_state", (idx) => idx.eq("state", "consume-me"))
+        .first();
+    });
+
+    expect(afterConsume).toBeNull();
+  });
+
+  it("returns null when consuming non-existent state", async () => {
+    const t = convexTest(schema, modules);
+
+    const result = await t.run(async (ctx) => {
+      return await ctx.db
+        .query("oauthStates")
+        .withIndex("by_state", (idx) => idx.eq("state", "does-not-exist"))
+        .first();
+    });
+
+    expect(result).toBeNull();
+  });
+
+  it("handles multiple states for same user (different providers)", async () => {
+    const t = convexTest(schema, modules);
+
+    await t.run(async (ctx) => {
+      await ctx.db.insert("oauthStates", {
+        state: "state-strava",
+        userId: "user-1",
+        provider: "strava",
+        createdAt: Date.now(),
+      });
+      await ctx.db.insert("oauthStates", {
+        state: "state-garmin",
+        userId: "user-1",
+        provider: "garmin",
+        createdAt: Date.now(),
+      });
+    });
+
+    const strava = await t.run(async (ctx) => {
+      return await ctx.db
+        .query("oauthStates")
+        .withIndex("by_state", (idx) => idx.eq("state", "state-strava"))
+        .first();
+    });
+
+    const garmin = await t.run(async (ctx) => {
+      return await ctx.db
+        .query("oauthStates")
+        .withIndex("by_state", (idx) => idx.eq("state", "state-garmin"))
+        .first();
+    });
+
+    expect(strava?.provider).toBe("strava");
+    expect(garmin?.provider).toBe("garmin");
+  });
+
+  it("cleanup deletes state by ID", async () => {
+    const t = convexTest(schema, modules);
+
+    const id = await t.run(async (ctx) => {
+      return await ctx.db.insert("oauthStates", {
+        state: "to-cleanup",
+        userId: "user-1",
+        provider: "whoop",
+        createdAt: Date.now(),
+      });
+    });
+
+    // Simulate scheduled cleanup
+    await t.run(async (ctx) => {
+      const record = await ctx.db.get(id);
+      if (record) {
+        await ctx.db.delete(id);
+      }
+    });
+
+    const after = await t.run(async (ctx) => {
+      return await ctx.db.get(id);
+    });
+
+    expect(after).toBeNull();
+  });
+});

package/src/component/oauthStates.ts

@@ -0,0 +1,85 @@
+import { v } from "convex/values";
+import { internal } from "./_generated/api";
+import { internalMutation, internalQuery } from "./_generated/server";
+import { providerName } from "./schema";
+
+// ---------------------------------------------------------------------------
+// Queries
+// ---------------------------------------------------------------------------
+
+/**
+ * Look up an OAuth state by its state token.
+ */
+export const getByState = internalQuery({
+  args: { state: v.string() },
+  returns: v.any(),
+  handler: async (ctx, args) => {
+    return await ctx.db
+      .query("oauthStates")
+      .withIndex("by_state", (idx) => idx.eq("state", args.state))
+      .first();
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Mutations
+// ---------------------------------------------------------------------------
+
+/**
+ * Store a new OAuth state. Schedules automatic cleanup after 15 minutes.
+ */
+export const store = internalMutation({
+  args: {
+    state: v.string(),
+    userId: v.string(),
+    provider: providerName,
+    codeVerifier: v.optional(v.string()),
+    redirectUri: v.optional(v.string()),
+  },
+  returns: v.id("oauthStates"),
+  handler: async (ctx, args) => {
+    const id = await ctx.db.insert("oauthStates", {
+      ...args,
+      createdAt: Date.now(),
+    });
+
+    // Schedule cleanup in 15 minutes
+    await ctx.scheduler.runAfter(15 * 60 * 1000, internal.oauthStates.deleteById, {
+      id,
+    });
+
+    return id;
+  },
+});
+
+/**
+ * Consume an OAuth state (read and delete). Used during the callback.
+ */
+export const consume = internalMutation({
+  args: { state: v.string() },
+  returns: v.any(),
+  handler: async (ctx, args) => {
+    const record = await ctx.db
+      .query("oauthStates")
+      .withIndex("by_state", (idx) => idx.eq("state", args.state))
+      .first();
+
+    if (!record) return null;
+
+    await ctx.db.delete(record._id);
+    return record;
+  },
+});
+
+/**
+ * Delete an OAuth state by ID (used by scheduled cleanup).
+ */
+export const deleteById = internalMutation({
+  args: { id: v.id("oauthStates") },
+  handler: async (ctx, args) => {
+    const record = await ctx.db.get(args.id);
+    if (record) {
+      await ctx.db.delete(args.id);
+    }
+  },
+});

package/src/component/providerSettings.ts

@@ -0,0 +1,66 @@
+import { v } from "convex/values";
+import { internalMutation, internalQuery } from "./_generated/server";
+import { providerName } from "./schema";
+
+export const upsertCredentials = internalMutation({
+  args: {
+    provider: providerName,
+    clientId: v.string(),
+    clientSecret: v.string(),
+    subscriptionKey: v.optional(v.string()),
+  },
+  handler: async (ctx, args) => {
+    const existing = await ctx.db
+      .query("providerSettings")
+      .withIndex("by_provider", (idx) => idx.eq("provider", args.provider))
+      .first();
+
+    const patch = {
+      provider: args.provider,
+      isEnabled: true,
+      clientId: args.clientId,
+      clientSecret: args.clientSecret,
+      subscriptionKey: args.subscriptionKey,
+      updatedAt: Date.now(),
+    };
+
+    if (existing) {
+      await ctx.db.patch(existing._id, patch);
+      return existing._id;
+    }
+
+    return await ctx.db.insert("providerSettings", patch);
+  },
+});
+
+export const getCredentials = internalQuery({
+  args: {
+    provider: providerName,
+  },
+  returns: v.union(
+    v.object({
+      provider: providerName,
+      clientId: v.string(),
+      clientSecret: v.string(),
+      subscriptionKey: v.optional(v.string()),
+    }),
+    v.null(),
+  ),
+  handler: async (ctx, args) => {
+    const settings = await ctx.db
+      .query("providerSettings")
+      .withIndex("by_provider", (idx) => idx.eq("provider", args.provider))
+      .first();
+
+    if (!settings?.clientId || !settings.clientSecret) {
+      return null;
+    }
+
+    return {
+      provider: settings.provider,
+      clientId: settings.clientId,
+      clientSecret: settings.clientSecret,
+      subscriptionKey: settings.subscriptionKey,
+    };
+  },
+});