@bb-labs/pkce 0.0.1

package/README.md

@@ -0,0 +1,125 @@
+# @bb-labs/pkce
+
+A lightweight, zero-dependency PKCE (Proof Key for Code Exchange) library for OAuth 2.0 that works across platforms.
+
+## Features
+
+- 🎯 **Zero Dependencies**: No external crypto libraries required
+- 🔄 **Cross-Platform**: Works in React Native (expo-crypto), Node.js (built-in crypto), and browsers
+- 🚀 **Auto-Detection**: Automatically uses the best available crypto implementation
+- 📦 **Tree-Shakable**: Import only what you need
+
+## Installation
+
+```bash
+npm install @bb-labs/pkce
+```
+
+## Usage
+
+### Automatic Environment Detection (Recommended)
+
+```typescript
+import { generateCodeVerifier, createCodeChallenge } from "@bb-labs/pkce";
+
+// Generate a cryptographically secure code verifier
+const verifier = generateCodeVerifier();
+
+// Create the corresponding code challenge
+const challenge = await createCodeChallenge(verifier);
+
+console.log("Verifier:", verifier);
+console.log("Challenge:", challenge);
+```
+
+### Platform-Specific Imports
+
+#### React Native / Expo
+
+```typescript
+import { generateCodeVerifier, createCodeChallenge } from "@bb-labs/pkce/expo";
+
+// Make sure expo-crypto is installed in your React Native app
+// npm install expo-crypto
+
+const verifier = generateCodeVerifier();
+const challenge = await createCodeChallenge(verifier);
+```
+
+#### Node.js
+
+```typescript
+import { generateCodeVerifier, createCodeChallenge } from "@bb-labs/pkce/nodejs";
+
+const verifier = generateCodeVerifier();
+const challenge = await createCodeChallenge(verifier);
+```
+
+## API
+
+### `generateCodeVerifier(): string`
+
+Generates a cryptographically secure random code verifier (43-128 characters, base64url encoded).
+
+### `createCodeChallenge(verifier: string): Promise<string>`
+
+Creates a code challenge by SHA-256 hashing the verifier and base64url encoding the result.
+
+## Requirements
+
+### React Native / Expo Apps
+
+- Install `expo-crypto`: `npm install expo-crypto`
+- The library will automatically detect and use expo-crypto
+
+### Node.js Apps
+
+- Node.js built-in `crypto` module (available in all modern Node.js versions)
+- No additional dependencies required
+
+### Browser Apps
+
+- Modern browsers with Web Crypto API support
+- Or use a polyfill for older browsers
+
+## PKCE Flow Example
+
+```typescript
+import { generateCodeVerifier, createCodeChallenge } from "@bb-labs/pkce";
+
+// 1. Generate verifier and challenge
+const verifier = generateCodeVerifier();
+const challenge = await createCodeChallenge(verifier);
+
+// 2. Send challenge to authorization server
+const authUrl =
+  `https://auth.example.com/oauth/authorize?` +
+  `client_id=your_client_id&` +
+  `redirect_uri=your_redirect_uri&` +
+  `response_type=code&` +
+  `code_challenge=${challenge}&` +
+  `code_challenge_method=S256`;
+
+// 3. After user authorization, exchange code for tokens using the verifier
+const tokenResponse = await fetch("https://auth.example.com/oauth/token", {
+  method: "POST",
+  body: new URLSearchParams({
+    grant_type: "authorization_code",
+    code: authorizationCode,
+    redirect_uri: redirectUri,
+    client_id: clientId,
+    code_verifier: verifier, // ← Send the original verifier
+  }),
+});
+```
+
+## Error Handling
+
+The library will throw descriptive errors if no suitable crypto implementation is found:
+
+- React Native: `"expo-crypto is required for React Native PKCE operations. Install expo-crypto or use a different PKCE implementation."`
+- Node.js: `"Node.js crypto is required for server-side PKCE operations."`
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * as expo from "./pkce/expo";
+export * as nodejs from "./pkce/nodejs";
+export declare const generateCodeVerifier: any;
+export declare const createCodeChallenge: any;

package/dist/index.js

@@ -0,0 +1,23 @@
+// Direct exports for specific platforms
+export * as expo from "./pkce/expo";
+export * as nodejs from "./pkce/nodejs";
+// Default export - try to auto-detect environment
+let defaultExport;
+try {
+    // Try React Native/expo first
+    require("expo-crypto");
+    defaultExport = require("./pkce/expo");
+}
+catch {
+    try {
+        // Try Node.js crypto
+        require("crypto");
+        defaultExport = require("./pkce/nodejs");
+    }
+    catch {
+        // Fallback - neither crypto is available
+        throw new Error("No suitable crypto implementation found. Install expo-crypto for React Native or use Node.js.");
+    }
+}
+export const generateCodeVerifier = defaultExport.generateCodeVerifier;
+export const createCodeChallenge = defaultExport.createCodeChallenge;

package/dist/pkce/expo.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Generates a cryptographically secure random code verifier for PKCE
+ * Uses expo-crypto if available, otherwise throws an error
+ */
+export declare function generateCodeVerifier(): string;
+/**
+ * Creates a code challenge from a code verifier using SHA-256
+ * Uses expo-crypto if available, otherwise throws an error
+ */
+export declare function createCodeChallenge(verifier: string): Promise<string>;

package/dist/pkce/expo.js

@@ -0,0 +1,55 @@
+/**
+ * Generates a cryptographically secure random code verifier for PKCE
+ * Uses expo-crypto if available, otherwise throws an error
+ */
+export function generateCodeVerifier() {
+    try {
+        const Crypto = require("expo-crypto");
+        // Generate 32 bytes (256 bits) of random data
+        const randomBytes = Crypto.getRandomBytes(32);
+        // Convert to base64url encoding (RFC 4648)
+        return base64UrlEncode(randomBytes);
+    }
+    catch (error) {
+        throw new Error("expo-crypto is required for React Native PKCE operations. Install expo-crypto or use a different PKCE implementation.");
+    }
+}
+/**
+ * Creates a code challenge from a code verifier using SHA-256
+ * Uses expo-crypto if available, otherwise throws an error
+ */
+export async function createCodeChallenge(verifier) {
+    try {
+        const Crypto = require("expo-crypto");
+        // Hash the verifier using SHA-256
+        const hashBuffer = await Crypto.digestStringAsync(Crypto.CryptoDigestAlgorithm.SHA256, verifier, {
+            encoding: Crypto.CryptoEncoding.BASE64,
+        });
+        // Return base64url encoded hash
+        return base64UrlEncode(hashBuffer);
+    }
+    catch (error) {
+        throw new Error("expo-crypto is required for React Native PKCE operations. Install expo-crypto or use a different PKCE implementation.");
+    }
+}
+/**
+ * Converts input to base64url encoding (RFC 4648)
+ * Replaces '+' with '-', '/' with '_', and removes padding
+ */
+function base64UrlEncode(input) {
+    let base64;
+    if (typeof input === "string") {
+        // If input is already a base64 string, use it directly
+        base64 = input;
+    }
+    else {
+        // Convert Uint8Array to base64
+        base64 = "";
+        for (let i = 0; i < input.length; i++) {
+            base64 += String.fromCharCode(input[i]);
+        }
+        base64 = btoa(base64);
+    }
+    // Convert to base64url
+    return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}

package/dist/pkce/nodejs.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Generates a cryptographically secure random code verifier for PKCE
+ * Node.js implementation using built-in crypto
+ */
+export declare function generateCodeVerifier(): string;
+/**
+ * Creates a code challenge from a code verifier using SHA-256
+ * Node.js implementation using built-in crypto
+ */
+export declare function createCodeChallenge(verifier: string): Promise<string>;

package/dist/pkce/nodejs.js

@@ -0,0 +1,49 @@
+/**
+ * Generates a cryptographically secure random code verifier for PKCE
+ * Node.js implementation using built-in crypto
+ */
+export function generateCodeVerifier() {
+    try {
+        const { randomBytes } = require("crypto");
+        // Generate 32 bytes (256 bits) of random data
+        const randomBytesData = randomBytes(32);
+        // Convert to base64url encoding (RFC 4648)
+        return base64UrlEncode(randomBytesData);
+    }
+    catch (error) {
+        throw new Error("Node.js crypto is required for server-side PKCE operations.");
+    }
+}
+/**
+ * Creates a code challenge from a code verifier using SHA-256
+ * Node.js implementation using built-in crypto
+ */
+export async function createCodeChallenge(verifier) {
+    try {
+        const { createHash } = require("crypto");
+        // Hash the verifier using SHA-256
+        const hash = createHash("sha256").update(verifier).digest();
+        // Return base64url encoded hash
+        return base64UrlEncode(hash);
+    }
+    catch (error) {
+        throw new Error("Node.js crypto is required for server-side PKCE operations.");
+    }
+}
+/**
+ * Converts input to base64url encoding (RFC 4648)
+ * Replaces '+' with '-', '/' with '_', and removes padding
+ */
+function base64UrlEncode(input) {
+    let base64;
+    if (typeof input === "string") {
+        // If input is already a base64 string, use it directly
+        base64 = input;
+    }
+    else {
+        // Convert Buffer to base64
+        base64 = input.toString("base64");
+    }
+    // Convert to base64url
+    return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@bb-labs/pkce",
+  "version": "0.0.1",
+  "description": "A library for PKCE",
+  "homepage": "https://github.com/beepbop-labs/pkce",
+  "keywords": [
+    "pkce",
+    "pkce-challenge",
+    "pkce-verifier"
+  ],
+  "author": "Beepbop",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/beepbop-labs/pkce.git"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "pack": "npm run build && npm pack --pack-destination ./archive/"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}