
Security News
vlt Launches "reproduce": A New Tool Challenging the Limits of Package Provenance
vlt's new "reproduce" tool verifies npm packages against their source code, outperforming traditional provenance adoption in the JavaScript ecosystem.
@dodgeball/trust-sdk-client
Advanced tools
Dodgeball enables developers to decouple security logic from their application code. This has several benefits including:
The Dodgeball Client Trust SDK for JavaScript makes integration with the Dodgeball API easy and is maintained by the Dodgeball team.
You will need to obtain an API key for your application from the Dodgeball developer center.
Check out the Dodgeball Trust Server SDK for how to integrate Dodgeball into your application's backend.
Use npm
to install the Dodgeball module:
npm install @dodgeball/trust-sdk-client
Alternatively, using yarn
:
yarn add @dodgeball/trust-sdk-client
The Dodgeball Client SDK comes with a useDodgeball
hook that can be used in all of your components.
You'll first need to initialize the SDK with your public API key which can be found on the developer settings page. This only needs to be done once when the application first loads as in the example below:
import { useDodgeball } from "@dodgeball/trust-sdk-client";
import { useEffect, useSelector } from "react";
import { selectCurrentUser, selectCurrentSession } from "./selectors";
export default function MyApp() {
const dodgeball = useDodgeball('public-api-key...');
const currentSession = useSelector(selectCurrentSession);
const currentUser = useSelector(selectCurrentUser);
useEffect(() => {
/*
When you know the ID of the currently logged-in user,
pass it along with a session ID to dodgeball.track():
*/
dodgeball.track(currentSession?.id, currentUser?.id);
}, [currentSession?.id, currentUser?.id]);
return (
<div>
<h1>My App</h1>
<MyComponent/>
</div>
);
}
Below is a simple example of a component that performs a verification when an order is placed:
import { useDodgeball } from "@dodgeball/trust-sdk-client";
import { useState, useEffect } from "react";
import axios from "axios";
export default function MyComponent() {
const dodgeball = useDodgeball(); // Once initialized, you can omit the public API key
const [isPlacingOrder, setIsPlacingOrder] = useState(false);
const [isOrderPlaced, setIsOrderPlaced] = useState(false);
const [isOrderDenied, setIsOrderDenied] = useState(false);
const [error, setError] = useState(null);
useEffect(() => {
setIsPlacingOrder(false);
}, [isOrderPlaced, isOrderDenied])
const placeOrder = async (order, previousVerification = null) => {
const sourceToken = await dodgeball.getSourceToken();
const endpointResponse = await axios.post("/api/orders", { order }, {
headers: {
"x-dodgeball-source-token": sourceToken, // Pass the source token to your API
"x-dodgeball-verification-id": previousVerificationId // If a previous verification was performed, pass it along to your API
}
});
dodgeball.handleVerification(endpointResponse.data.verification, {
onVerified: async (verification) => {
// If an additional check was performed and the request is approved, simply pass the verification ID in to your API
await placeOrder(order, verification.id);
},
onApproved: async () => {
// If no additional check was required, update the view to show that the order was placed
setIsOrderPlaced(true);
},
onDenied: async (verification) => {
// If the action was denied, update the view to show the rejection
setIsOrderDenied(true);
},
onError: async (error) => {
// If there was an error performing the verification, display it
setError(error); // Usage Note: If the user cancels the verification, error.errorType = "CANCELLED"
setIsPlacingOrder(false);
}
});
}
const onPlaceOrderClick = async () => {
setIsPlacingOrder(true);
const order = {} // Fill in with whatever data your API expects
await placeOrder(order);
}
return (
<div>
<h2>My Component</h2>
<p>
This component is using the Dodgeball Client SDK.
</p>
{isOrderPlaced ? (
<p>
Your order was placed!
</p>
) : (
<p>
{isOrderDenied && <span>Order was denied. Contact support.</span>}
<button onClick={onPlaceOrderClick} disabled={isPlacingOrder || isOrderDenied}>
{isPlacingOrder ? 'Placing Order...' : 'Place Order'}
</button>
{error && <div>{error}</div>}
</p>
)}
</div>
);
}
The Dodgeball Client SDK exports a Dodgeball
class that can be passed a public API key and an optional config object. See the constructor section for more information on configuration. You can find your public API key on the developer settings page.
You'll first need to initialize the SDK with your public API key which can be found on the developer settings page. This only needs to be done once when the SDK first loads as in the example below:
import { Dodgeball } from "@dodgeball/trust-sdk-client";
const dodgeball = new Dodgeball('public-api-key...'); // Do this once when your application first loads
const sourceToken = await dodgeball.getSourceToken();
When you know the ID of the currently logged-in user, call dodgeball.track()
.
// As soon as you have a session ID, pass it to dodgeball.track()
const onSession = (currentSession) => {
dodgeball.track(currentSession?.id);
}
// When you know the ID of the currently logged-in user, pass it along with a session ID to dodgeball.track()
const onLogin = (currentSession, currentUser) => {
dodgeball.track(currentSession?.id, currentUser?.id);
}
Later, when you want to verify that a visitor is allowed to perform an action, call dodgeball.getSourceToken()
to get a token representing this device. Pass the returned sourceToken
to your API. Once your API returns a response, pass the verification
to dodgeball.handleVerification
along with a few callback functions:
const placeOrder = async (order, previousVerificationId = null) => {
const sourceToken = await dodgeball.getSourceToken();
const endpointResponse = await axios.post("/api/orders", { order }, {
headers: {
"x-dodgeball-source-token": sourceToken, // Pass the source token to your API
"x-dodgeball-verification-id": previousVerificationId // If a previous verification was performed, pass it along to your API
}
});
dodgeball.handleVerification(endpointResponse.data.verification, {
onVerified: async (verification) => {
// If an additional check was performed and the request is approved, simply pass the verification ID in to your API
await placeOrder(order, verification.id);
},
onApproved: async () => {
// If no additional check was required, update the view to show that the order was placed
setIsOrderPlaced(true);
},
onDenied: async (verification) => {
// If the action was denied, update the view to show the rejection
setIsOrderDenied(true);
},
onError: async (error) => {
// If there was an error performing the verification, display it
setError(error); // Usage Note: If the user cancels the verification, error.errorType = "CANCELLED"
setIsPlacingOrder(false);
}
});
}
The Dodgeball Client SDK is also available via CDN at this url:
https://www.unpkg.com/@dodgeball/trust-sdk-client@latest/dist/umd/index.js
To load this in an HTML document:
<!doctype html>
<html>
<head>
<title>My Application</title>
<script type="text/javascript" async defer src="https://www.unpkg.com/@dodgeball/trust-sdk-client@latest/dist/umd/index.js" onload="onDodgeballLoaded()"></script>
<script>
async function onDodgeballLoaded() {
const dodgeball = new Dodgeball('public-api-key...'); // Do this once when your application first loads
// At some point later, when you are ready to call your API:
const placeOrder = async (order, previousVerificationId = null) => {
const sourceToken = await dodgeball.getSourceToken();
const endpointResponse = await axios.post("/api/orders", { order }, {
headers: {
"x-dodgeball-source-token": sourceToken, // Pass the source token to your API
"x-dodgeball-verification-id": previousVerificationId // If a previous verification was performed, pass it along to your API
}
});
dodgeball.handleVerification(endpointResponse.data.verification, {
onVerified: async (verification) => {
// If an additional check was performed and the request is approved, simply pass the verification ID in to your API
await placeOrder(order, verification.id);
},
onApproved: async () => {
// If no additional check was required, update the view to show that the order was placed
setIsOrderPlaced(true);
},
onDenied: async (verification) => {
// If the action was denied, update the view to show the rejection
setIsOrderDenied(true);
},
onError: async (error) => {
// If there was an error performing the verification, display it
setError(error); // Usage Note: If the user cancels the verification, error.errorType = "CANCELLED"
setIsPlacingOrder(false);
}
});
}
await placeOrder({
cart: [],
paymentMethod: {},
// ... any other data relevant to your API
});
}
</script>
</head>
<body>
Your application's content...
</body>
</html>
The package requires a public API key as the first argument to the constructor.
const dodgeball = new Dodgeball("public-api-key...");
Optionally, you can pass in several configuration options to the constructor:
const dodgeball = new Dodgeball("public-api-key...", {
// Optional configuration
apiVersion: "v1",
apiUrl: "https://api.dodgeballhq.com",
logLevel: "ERROR",
disableCookies: false,
isEnabled: true
});
Option | Default | Description |
---|---|---|
apiVersion | v1 | The Dodgeball API version to use. |
apiUrl | https://api.dodgeballhq.com | The base URL of the Dodgeball API. Useful for sending requests to different environments such as https://api.sandbox.dodgeballhq.com . |
logLevel | INFO | The level of logging to use. Possible options are TRACE , INFO , ERROR , or NONE . TRACE and INFO are useful for debugging. ERROR only logs errors. NONE turns off all logging. |
disableCookies | false | If true , the SDK will not use cookies to store the source token. |
isEnabled | true | If false , the SDK will not make external API calls. This is useful for local development. |
The track
method is used to initialize any session and user information that is known. This method should be called as soon as you have a session ID and optionally a user ID. If you do not have a user ID, you can pass null
or omit the second argument.
dodgeball.track(sessionId, userId);
Argument | Type | Description |
---|---|---|
sessionId | string | The ID of the current session. This may be any unique string representing the user's activity within your system. If you don't have a session ID to use, pass the sourceToken returned from dodgeball.getSourceToken() . |
userId | string | The ID of the current user. |
The getSourceToken
method returns a token that represents a period of activity on the current device. This token should be passed to your API when you want to verify that a user is allowed to perform an action. Source tokens expire after 1 hour and are automatically refreshed by the SDK.
const sourceToken = await dodgeball.getSourceToken();
If async/await isn't your thing, you can invoke the getSourceToken
method with a callback function that will be called with the source token as an argument:
dodgeball.getSourceToken((sourceToken) => {});
The refreshSourceToken
method refreshes the current source token. This is useful if you want to refresh the token before it expires, as in the case of when a user logs out.
const newSourceToken = await dodgeball.refreshSourceToken();
Alternatively, you can invoke the refreshSourceToken
method with a callback function that will be called with the new source token as an argument:
dodgeball.refreshSourceToken((newSourceToken) => {});
The handleVerification
method is used to handle a verification response from your API. This method should be called after your API returns a response containing a verification object. The verification object contains information about the verification that was performed. The handleVerification
method takes a verification object and a config object containing several callback functions. The handleVerification
method will call the appropriate callback function based on the verification response.
dodgeball.handleVerification(
verification, // This is the verification object returned from your API
{
onVerified: async (verification) => {
// If an additional check was performed and the request is approved, the requested action has not yet been taken on your API. To do so, simply retry the request, being sure to pass the verification.id to your API. On your API the verification.id should be passed as the useVerificationId argument to dodgeball.checkpoint()
},
onApproved: async () => {
// If no additional check was required, the requested action was approved and taken on your API, so you should update the view to show that the action was taken
},
onDenied: async (verification) => {
// If the action was denied, update the view to show the rejection
},
onPending: async (verification) => {
// (Optional) This callback will be called if the verification is still processing. This is useful to inform the user that their request is still being processed.
},
onBlocked: async (verification) => {
// (Optional) This callback will be called if the verification requires additional information from the user before it can be processed (e.g. the user needs to complete an MFA challenge or IDV flow)
},
onError: async (verificationError) => {
// (Optional) If there was an error performing the verification, this callback will be called with an error object. If the user cancels the verification, error.errorType = "CANCELLED"
}
},
{
// Optional configuration
maxDuration: 24 * 60 * 60 * 1000, // 24 hours
}
);
Argument | Type | Description |
---|---|---|
verification | object | The verification object returned from your API. |
context | object | An object containing several callback functions described above. |
config | object | An object containing several configuration options. |
config.maxDuration | number | The maximum amount of time to wait for a verification to complete. If the verification is still pending after this amount of time, the onError callback will be called with an error object. |
FAQs
Dodgeball Client SDK
The npm package @dodgeball/trust-sdk-client receives a total of 1,259 weekly downloads. As such, @dodgeball/trust-sdk-client popularity was classified as popular.
We found that @dodgeball/trust-sdk-client demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
vlt's new "reproduce" tool verifies npm packages against their source code, outperforming traditional provenance adoption in the JavaScript ecosystem.
Research
Security News
Socket researchers uncovered a malicious PyPI package exploiting Deezer’s API to enable coordinated music piracy through API abuse and C2 server control.
Research
The Socket Research Team discovered a malicious npm package, '@ton-wallet/create', stealing cryptocurrency wallet keys from developers and users in the TON ecosystem.