@opencampus/ocid-connect-js 1.2.6 → 2.0.1

package/README.md

@@ -1,4 +1,3 @@
-
 ## Table of Contents
 
 - [Setup](#setup)
@@ -7,6 +6,15 @@
 - [Javascript Integration](#javascript-integration)
 - [License](#license)
 
+## Pre-Requisites
+
+An Auth Client ID is required to use OCID Connect in Live (Production) mode. Please contact your Open Campus Ambassador to request access to an Open Campus Developer Account and Auth Client ID.
+For Live mode integration, you will need to configure the Redirect URIs for you Auth Client and only configured Redirect URIs are allowed to be passed to the SDK.
+
+You **do not need a Client ID when testing integration in Sandbox mode**. Sandbox mode connect to the sandbox OCID environment which is separate from the production environment. An OCID registered in the sandbox environment does not exist in the production environment and vice versa. Sandbox mode has no restriction for Redirect URIs and hence does not require a Client ID at the moment. Client ID can be passed to the SDK in sandbox mode, but **does not have any effect**.
+
+> If you were onboarded to live integration before Apr 2025 and did not have an Open Campus Developer Account, you would **need to** use the V1.x SDK. Please get in touch with your Open Campus point of contact to get your Open Campus Developer Account and migrate to the V2 SDK. Thanks!
+
 ## Setup
 
 **yarn**
@@ -33,6 +41,7 @@ Setup Context to hook up state variables and override configuration
 import { OCConnect } from '@opencampus/ocid-connect-js';
 
 const opts = {
+    clientId: '<Does_Not_Matter_For_Sandbox_mode>',
     redirectUri: 'http://localhost:3001/redirect',
     referralCode: 'PARTNER6'
 }
@@ -46,20 +55,22 @@ return (
 )
 ```
 
-OCConnect Property
+OCConnect Props
 
 | Property | Description |
 | --- | --- |
 | opts | Authentication's properties that can be overriden |
 | sandboxMode | Connect to sandbox if it is set, default to live mode |
 
-Opts Property
+opts Properties
 
 | Property | Description |
 | --- | --- |
+| clientId | Your Auth Client ID. Required for live mode, optional for sandbox mode |
 | redirectUri | URL to return after the login process is completed |
 | referralCode | Unique identifiers assigned to partners for tracking during OCID account's registration. |
-| domain | Domain to store cookie. Leave it blank to tell the browser to use the current domain |
+| storageType | Storage type to store the auth state. Use cookie if specified as `cookie`. Otherwise if not defined, local storage is used. |
+| domain | Domain to store cookie. Only meaningful if `cookie` type storaged is used. Leave it blank to tell the browser to use the current domain. |
 | sameSite | Specify the SameSite behavior when using cookie as storage. When `true` - SameSite: strict; when `false` - SameSite: None, when not set - default SameSite behavior browser dependent |
 
 Setup LoginCallBack to handle flow's result
@@ -187,6 +198,7 @@ export default function RootLayout({
   children,
 }) {
   const opts = {
+    clientId: '<Does_Not_Matter_For_Sandbox_mode>',    
     redirectUri: 'http://localhost:3000/redirect', // Adjust this URL
     referralCode: 'PARTNER6', // Assign partner code
   };
@@ -289,17 +301,17 @@ import LoginButton from '../components/LoginButton';
 import { useOCAuth } from '@opencampus/ocid-connect-js';
 
 export default function Home() {
-  const { authState, ocAuth } = useOCAuth();
-
-  if (authState.error) {
-    return <div>Error: {authState.error.message}</div>;
-  }
+  const { isInitialized, authState, ocAuth } = useOCAuth();
 
   // Add a loading state
-  if (authState.isLoading) {
+  if (!isInitialized) {
     return <div>Loading...</div>;
   }
 
+  if (authState.error) {
+    return <div>Error: {authState.error.message}</div>;
+  }
+
   return (
     <div>
       <h1>Welcome to My App</h1>
@@ -328,6 +340,15 @@ import { OCAuthSandbox } from '@opencampus/ocid-connect-js';
 const authSdk = new OCAuthSandbox();
 ```
 
+In live mode, we need to provide the client id.
+
+```js
+import { OCAuthLive } from '@opencampus/ocid-connect-js';
+const authSdk = new OCAuthLive({
+  clientId: 'your_client_id',
+});
+```
+
 Main Methods of Auth SDK
 
 | Method | Description |
@@ -336,6 +357,7 @@ Main Methods of Auth SDK
 | handleLoginRedirect | Return the auth state of the login process |
 | getAuthState | Return auth state data { accessToken, idToken, OCId, ethAddress, isAuthenticated } |
 | getStateParameter() | Return the state that was initialized in signin process |
+| logout() | Logout the current user. Accept "returnUrl" as an input so user can be redirected to the app after logout |
 
 Sample usage
 
@@ -384,3 +406,52 @@ Access OCId info of Auth SDK
 
 ### License
 ocid-connect-js is released under the MIT license.
+
+## JWT Verification Example
+
+Below is a sample code snippet demonstrating how to fetch the JSON Web Key Set (JWKS) from a remote URL and verify a JWT. Depending on the environment, it will choose either the Sandbox or Live JWKS URL.
+
+Sandbox:
+https://static.opencampus.xyz/jwks/jwks-sandbox.json
+
+Live:
+https://static.opencampus.xyz/jwks/jwks-live.json
+
+
+### This  is just an example, you can use any library to verify the JWT. Do not use this code in production.
+
+```js
+import * as jose from 'jose';
+
+const fetchJWKS = async (jwkUrl) => {
+  const resp = await fetch(jwkUrl);
+  json = await resp.json();
+  return await jose.createLocalJWKSet(json);
+};
+
+const verifyJwt = async (jwt, jwkUrl) => {
+  const JWK = await fetchJWKS(jwkUrl);
+  const { payload } = await jose.jwtVerify(jwt, JWK);
+  return payload;
+};
+
+// Example usage
+const verifyTokenExample = async (jwt) => {
+  try {
+    // Choose the JWKS URL based on the environment
+    const jwkUrl = process.env.NODE_ENV === 'production'
+      ? 'https://static.opencampus.xyz/jwks/jwks-live.json'
+      : 'https://static.opencampus.xyz/certs/jwks-sandbox.json';
+      
+    const payload = await verifyJwt(jwt, jwkUrl);
+    console.log('JWT verified successfully:', payload);
+  } catch (error) {
+    console.error('JWT verification failed:', error);
+  }
+};
+
+// Replace 'your_jwt_here' with your actual JWT token
+verifyTokenExample('your_jwt_here');
+```
+
+