@codefox-inc/oauth-provider 0.2.0

package/src/component/schema.ts

@@ -0,0 +1,92 @@
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+
+export default defineSchema({
+    /**
+     * OAuth Clients
+     * Registered applications that can request authorization
+     */
+    oauthClients: defineTable({
+        name: v.string(),
+        description: v.optional(v.string()),
+        logoUrl: v.optional(v.string()),
+        website: v.optional(v.string()),
+        tosUrl: v.optional(v.string()),
+        policyUrl: v.optional(v.string()),
+
+        // Client Credentials
+        clientId: v.string(), // Public ID (UUID v4)
+        clientSecret: v.optional(v.string()), // Hashed Secret (for confidential clients)
+        type: v.union(v.literal("confidential"), v.literal("public")),
+
+        redirectUris: v.array(v.string()), // Must be exact match
+        allowedScopes: v.array(v.string()), // e.g. ["openid", "profile", "email"]
+
+        isInternal: v.optional(v.boolean()), // Internal tool flag
+
+        createdAt: v.number(),
+    }).index("by_client_id", ["clientId"]),
+
+    /**
+     * OAuth Authorization Codes
+     * Short-lived codes for authorization code flow
+     */
+    oauthCodes: defineTable({
+        code: v.string(),
+        clientId: v.string(),
+        userId: v.string(), // Convex users table Id (string, not v.id since component doesn't know about users table)
+        scopes: v.array(v.string()),
+        redirectUri: v.string(),
+
+        // PKCE
+        codeChallenge: v.string(),
+        codeChallengeMethod: v.string(), // "S256" or "plain"
+        nonce: v.optional(v.string()), // OIDC Nonce
+
+        expiresAt: v.number(), // Usually 10 minutes
+        usedAt: v.optional(v.number()), // RFC Line 1136: Track code usage for replay detection
+    }).index("by_code", ["code"]),
+
+    /**
+     * OAuth Tokens
+     * Access and Refresh tokens
+     */
+    oauthTokens: defineTable({
+        accessToken: v.string(),
+        refreshToken: v.optional(v.string()),
+
+        clientId: v.string(),
+        userId: v.string(), // Convex users table Id (string)
+        scopes: v.array(v.string()),
+
+        expiresAt: v.number(), // Access Token Expiry
+        refreshTokenExpiresAt: v.optional(v.number()), // Refresh Token Expiry
+
+        // RFC Line 1136: Track which authorization code issued this token for replay detection
+        authorizationCode: v.optional(v.string()), // Hashed authorization code
+    })
+        .index("by_access_token", ["accessToken"])
+        .index("by_refresh_token", ["refreshToken"])
+        .index("by_user", ["userId"])
+        .index("by_authorization_code", ["authorizationCode"]),
+
+    /**
+     * OAuth Authorizations
+     * User consent records - persists beyond token expiry
+     */
+    oauthAuthorizations: defineTable({
+        userId: v.string(), // Convex users table Id (string)
+        clientId: v.string(),
+
+        // Authorized scopes
+        scopes: v.array(v.string()),
+
+        // When the user first authorized this client
+        authorizedAt: v.number(),
+
+        // Last time a token was issued for this authorization
+        lastUsedAt: v.optional(v.number()),
+    })
+        .index("by_user", ["userId"])
+        .index("by_user_client", ["userId", "clientId"]),
+});

package/src/component/token_security.ts

@@ -0,0 +1,102 @@
+/**
+ * Token Security Utilities for OAuth Provider (Web Crypto API)
+ *
+ * Provides secure token hashing for database storage.
+ * Tokens are hashed using SHA-256 before storage - the original token
+ * value is never stored, only returned to the client during issuance.
+ *
+ * This is more secure than encryption because:
+ * 1. Even with DB access + encryption key, tokens can't be recovered
+ * 2. Token validation only requires hash comparison
+ * 3. Clients already have the original token
+ *
+ * @see https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html
+ */
+
+/**
+ * Convert string to Uint8Array
+ */
+function stringToBytes(str: string): Uint8Array {
+    return new TextEncoder().encode(str);
+}
+
+/**
+ * Creates a SHA-256 hash of a token for secure storage.
+ *
+ * @param token - The plaintext token to hash
+ * @returns Hex-encoded hash suitable for database storage and indexing
+ *
+ * @example
+ * ```typescript
+ * const accessToken = generateCode(64);
+ * const accessTokenHash = await hashToken(accessToken);
+ * // Store accessTokenHash in DB, return accessToken to client
+ * ```
+ */
+export async function hashToken(token: string): Promise<string> {
+    const tokenBytes = stringToBytes(token);
+    const hashBuffer = await crypto.subtle.digest(
+        "SHA-256",
+        tokenBytes.buffer as ArrayBuffer
+    );
+    const hashArray = new Uint8Array(hashBuffer);
+    return Array.from(hashArray)
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+
+/**
+ * Timing-safe string comparison to prevent timing attacks.
+ * Compares two strings in constant time regardless of where they differ.
+ */
+function timingSafeEqual(a: string, b: string): boolean {
+    if (a.length !== b.length) {
+        return false;
+    }
+    let result = 0;
+    for (let i = 0; i < a.length; i++) {
+        result |= a.charCodeAt(i) ^ b.charCodeAt(i);
+    }
+    return result === 0;
+}
+
+/**
+ * Verifies a token against its stored hash.
+ *
+ * @param token - The plaintext token to verify
+ * @param hash - The stored hash to compare against
+ * @returns true if the token matches the hash
+ */
+export async function verifyToken(
+    token: string,
+    hash: string
+): Promise<boolean> {
+    const tokenHash = await hashToken(token);
+    // Use timing-safe comparison to prevent timing attacks
+    return timingSafeEqual(tokenHash, hash);
+}
+
+/**
+ * Checks if a value looks like a SHA-256 hash (64 hex characters).
+ * Used for backward compatibility during migration.
+ *
+ * @param value - The value to check
+ * @returns true if the value appears to be a hash
+ */
+export function isHashedToken(value: string): boolean {
+    return /^[a-f0-9]{64}$/.test(value);
+}
+
+/**
+ * Hash a token if it's not already hashed.
+ * Used for backward compatibility during migration.
+ *
+ * @param token - Token that may or may not be hashed
+ * @returns The hash (either computed or passed through if already hashed)
+ */
+export async function ensureHashed(token: string): Promise<string> {
+    if (isHashedToken(token)) {
+        return token;
+    }
+    return hashToken(token);
+}

package/src/lib/__tests__/oauth-helpers.test.ts

@@ -0,0 +1,143 @@
+import { describe, it, expect } from "vitest";
+import {
+    isOAuthToken,
+    getOAuthClientId,
+    DEFAULT_OAUTH_ISSUER_PATTERN,
+    generateCode,
+    generateClientSecret
+} from "../oauth";
+
+describe("OAuth Token Helpers", () => {
+    describe("DEFAULT_OAUTH_ISSUER_PATTERN", () => {
+        it("should be /oauth", () => {
+            expect(DEFAULT_OAUTH_ISSUER_PATTERN).toBe("/oauth");
+        });
+    });
+
+    describe("isOAuthToken", () => {
+        it("should return true for valid OAuth token identity", () => {
+            const identity = {
+                issuer: "https://example.com/oauth",
+                subject: "user123",
+            };
+            expect(isOAuthToken(identity)).toBe(true);
+        });
+
+        it("should return true when issuer ends with /oauth", () => {
+            const identity = {
+                issuer: "https://my-app.convex.site/oauth",
+                subject: "jh7abcdefghijk123456789",
+            };
+            expect(isOAuthToken(identity)).toBe(true);
+        });
+
+        it("should return false for Convex Auth identity", () => {
+            const identity = {
+                issuer: "https://convex.dev",
+                subject: "user123",
+            };
+            expect(isOAuthToken(identity)).toBe(false);
+        });
+
+        it("should return false when issuer is missing", () => {
+            const identity = { subject: "user123" };
+            expect(isOAuthToken(identity)).toBe(false);
+        });
+
+        it("should return false when subject is missing", () => {
+            const identity = { issuer: "https://example.com/oauth" };
+            expect(isOAuthToken(identity)).toBe(false);
+        });
+
+        it("should return false for null identity", () => {
+            expect(isOAuthToken(null)).toBe(false);
+        });
+
+        it("should return false for undefined identity", () => {
+            expect(isOAuthToken(undefined)).toBe(false);
+        });
+
+        it("should accept custom issuer pattern", () => {
+            const identity = {
+                issuer: "https://example.com/custom-oauth-path",
+                subject: "user123",
+            };
+            expect(isOAuthToken(identity, "/custom-oauth-path")).toBe(true);
+            expect(isOAuthToken(identity, "/oauth")).toBe(false);
+        });
+    });
+
+    describe("getOAuthClientId", () => {
+        it("should return client ID when present", () => {
+            const identity = { cid: "client123" };
+            expect(getOAuthClientId(identity)).toBe("client123");
+        });
+
+        it("should return undefined when cid is missing", () => {
+            const identity = {};
+            expect(getOAuthClientId(identity)).toBeUndefined();
+        });
+
+        it("should return undefined for null identity", () => {
+            expect(getOAuthClientId(null)).toBeUndefined();
+        });
+
+        it("should return undefined for undefined identity", () => {
+            expect(getOAuthClientId(undefined)).toBeUndefined();
+        });
+    });
+
+    describe("generateCode", () => {
+        it("should generate a code with default length", () => {
+            const code = generateCode();
+            expect(code).toBeDefined();
+            expect(typeof code).toBe("string");
+            expect(code.length).toBeGreaterThan(0);
+        });
+
+        it("should generate a code with specified length", () => {
+            const code = generateCode(32);
+            expect(code).toBeDefined();
+            expect(code.length).toBeGreaterThanOrEqual(32);
+        });
+
+        it("should generate different codes on each call", () => {
+            const code1 = generateCode();
+            const code2 = generateCode();
+            expect(code1).not.toBe(code2);
+        });
+
+        it("should generate URL-safe codes", () => {
+            const code = generateCode(100);
+            // OAuth unreserved characters: A-Za-z0-9-._~
+            expect(code).toMatch(/^[A-Za-z0-9_~.-]+$/);
+        });
+    });
+
+    describe("generateClientSecret", () => {
+        it("should generate a secret with default length", () => {
+            const secret = generateClientSecret();
+            expect(secret).toBeDefined();
+            expect(typeof secret).toBe("string");
+            expect(secret.length).toBeGreaterThan(0);
+        });
+
+        it("should generate a secret with specified length", () => {
+            const secret = generateClientSecret(64);
+            expect(secret).toBeDefined();
+            expect(secret.length).toBeGreaterThanOrEqual(64);
+        });
+
+        it("should generate different secrets on each call", () => {
+            const secret1 = generateClientSecret();
+            const secret2 = generateClientSecret();
+            expect(secret1).not.toBe(secret2);
+        });
+
+        it("should generate hex secrets", () => {
+            const secret = generateClientSecret(100);
+            expect(secret).toMatch(/^[A-Fa-f0-9]+$/);
+        });
+    });
+
+});