[](https://www.npmjs.org/package/@openfort/shield-js)
npm install @openfort/shield-jsShieldJS is a TypeScript library for interacting with the Openfort Shield API. It provides easy-to-use methods for retrieving and storing secrets.
To use ShieldJS in your project, install it via npm or pnpm:
``bash`
pnpm add @openfort/shield-js
`typescript`
import {
ShieldSDK,
ShieldOptions,
ShieldAuthProvider,
OpenfortAuthOptions,
CustomAuthOptions,
OpenfortOAuthProvider,
OpenfortOAuthTokenType
} from '@openfort/shield-js';
typescript
const shieldOptions: ShieldOptions = {
apiKey: 'your-api-key',
// Optional: Specify a custom base URL
baseURL: 'https://shield.openfort.io'
};const shieldSDK = new ShieldSDK(shieldOptions);
`$3
typescript
import { Share } from '@openfort/shield-js';const share: Share = {
secret: "your-secret-data",
entropy: "optional-entropy",
encryptionParameters: {
salt: "salt-value",
iterations: 10000,
length: 32,
digest: "SHA-256"
}
};
const authOptions: ShieldAuthOptions = {
// ... authentication options
};
await shieldSDK.storeSecret(share, authOptions);
`$3
typescript
// Delete all secrets for the authenticated user
await shieldSDK.deleteSecret(authOptions);// Delete a specific secret by reference
await shieldSDK.deleteSecret(authOptions, undefined, "reference-id");
`$3
typescript
const share = await shieldSDK.getSecret(authOptions);
console.log(share.secret);// Retrieve by specific reference
const shareByRef = await shieldSDK.getSecretByReference(authOptions, "reference-id");
console.log(shareByRef.secret);
`$3
typescript
const encryptionMethods = await shieldSDK.getEncryptionMethodsBySignerReferences(
authOptions,
["ref1", "ref2"]
);
// Returns Map with reference as key and method as value// Get detailed information including passkey details
const detailedMethods = await shieldSDK.getEncryptionMethodsBySignerReferencesDetailed(
authOptions,
["ref1", "ref2"]
);
// Returns Map with additional details
`$3
typescript
const encryptionMethods = await shieldSDK.getEncryptionMethodsByOwnerId(
authOptions,
["user1", "user2"]
);
// Returns Map with userId as key and method as value// Get detailed information including passkey details
const detailedMethods = await shieldSDK.getEncryptionMethodsByOwnerIdDetailed(
authOptions,
["user1", "user2"]
);
// Returns Map with additional details
`$3
#### Update a Secret
typescript
const updatedShare: Share = {
secret: "updated-secret-data",
// ... other share properties
};await shieldSDK.updateSecret(authOptions, updatedShare);
`#### Get Keychain (List of Shares)
typescript
// Get all shares for the authenticated user
const shares = await shieldSDK.keychain(authOptions);// Get shares filtered by reference
const shares = await shieldSDK.keychain(authOptions, "reference-filter");
`#### Pre-register a Secret (Admin)
typescript
await shieldSDK.preRegister(share, authOptions);
`API Reference
$3
-
-
-
-
-
-
-
-
-
-
- Authentication
ShieldSDK supports two types of authentication: Openfort and Custom. The type of authentication you use depends on the configuration set in your Shield Dashboard.$3
When you configure your Shield Dashboard to use Openfort, you should use OpenfortAuthOptions for authentication. You must also set the to ShieldAuthProvider.OPENFORT.Depending on your setup, the way you use OpenfortAuthOptions can vary:
- Using an Openfort Token: If you are using a token generated by Openfort, simply provide the token in openfortOAuthToken.
`typescript
const authOptions: OpenfortAuthOptions = {
authProvider: ShieldAuthProvider.OPENFORT,
openfortOAuthToken: "your-openfort-token",
};
`- Using Third-Party OAuth Tokens: If you are using a third-party authentication provider, you need to provide the identity token, the provider type, and the token type:
typescript
const authOptions: OpenfortAuthOptions = {
authProvider: ShieldAuthProvider.OPENFORT,
openfortOAuthToken: "your-identity-token",
openfortOAuthProvider: OpenfortOAuthProvider.FIREBASE,
openfortOAuthTokenType: OpenfortOAuthTokenType.ID_TOKEN
};
`The Provider and Token Type enums are defined as follows:
typescript
export enum OpenfortOAuthProvider {
ACCELBYTE = "accelbyte",
FIREBASE = "firebase",
LOOTLOCKER = "lootlocker",
SUPABASE = "supabase",
PLAYFAB = "playfab",
CUSTOM = "custom",
OIDC = "oidc",
}export enum OpenfortOAuthTokenType {
ID_TOKEN = "idToken",
CUSTOM_TOKEN = "customToken",
}
`$3
If your Shield Dashboard is configured for Custom Authentication, use CustomAuthOptions. You will need to provide your custom token in the customToken field and set the to ShieldAuthProvider.CUSTOM.`typescript
const authOptions: CustomAuthOptions = {
authProvider: ShieldAuthProvider.CUSTOM,
customToken: "your-custom-token",
};
`Error Handling
The SDK throws specific error types for common scenarios:
-
: Thrown when no secret is found for the given authentication options
- SecretAlreadyExistsError: Thrown when attempting to store a secret that already exists
- EncryptionPartMissingError: Thrown when encryption part is missing from the request
- OTPRequiredError: Thrown when OTP (One-Time Password) is required for the operation`typescript
import {
NoSecretFoundError,
SecretAlreadyExistsError
} from '@openfort/shield-js';try {
const share = await shieldSDK.getSecret(authOptions);
} catch (error) {
if (error instanceof NoSecretFoundError) {
console.log('No secret found');
} else if (error instanceof SecretAlreadyExistsError) {
console.log('Secret already exists');
}
}
`Types
$3
typescript
interface Share {
secret: string;
entropy?: entropy;
encryptionParameters?: EncryptionParameters;
keychainId?: string;
reference?: string;
passkeyReference?: PasskeyReference;
}
`$3
typescript
interface ShieldOptions {
apiKey: string;
baseURL?: string; // Defaults to 'https://shield.openfort.io'
}
``