WebCred

A robust TypeScript wrapper around the Web Credential Management API. The credentialContainer class provides a clean, user-friendly API to handle browser credentials, enhancing the native browser APIs.

Table of Contents

• Installation
• API Reference
  • Enums & Types
  • Feature Detection
  • Password Credentials
  • Federated Credentials
  • OTP Credentials
  • Public Key Credentials (WebAuthn)
• Browser Support
• Contributing
• License
• Issues

Installation

Install the package via npm:

npm install webcred

Ensure your project is configured for TypeScript!

API Reference

The credentialContainer class exposes type-safe utilities to interact with the Web Credential Management API. All methods include built-in feature detection, so they’ll gracefully return null or false in unsupported environments instead of throwing.

Enums & Types

• credentialType Represents the type of credentials handled by the API:

  • password → PasswordCredential
  • federated → FederatedCredential
  • otp → OTPCredential
  • publicKey → PublicKeyCredential

• mediation Controls how the browser mediates the credential retrieval process:

  • silent — No UI; fails if the user has not granted permission.
  • optional — Tries to retrieve credentials without requiring user interaction.
  • required — Always requires user interaction.
  • conditional — Enables Conditional UI.

Feature Detection

These methods let you check support before performing any operations:

• isSecureContextOrLocalhost(): boolean Returns true if the current environment is HTTPS or localhost.

• isSupported(): boolean Returns true if the browser supports the Credential Management API.

• isPasswordCredentialSupported(): boolean

• isFederatedCredentialSupported(): boolean

• isOTPCredentialSupported(): boolean

• isPublicKeyCredentialSupported(): boolean Return true if the corresponding credential type is supported.

Password Credentials

• storePasswordCredential(data: PasswordCredentialData): Promise<PasswordCredential | null> Stores a password credential using navigator.credentials.store.

• getPasswordCredential(mediation?: CredentialMediationRequirement, signal?: AbortSignal): Promise<PasswordCredential | null> Retrieves a stored password credential. Default mediation is "optional".

Federated Credentials

• storeFederatedCredential(data: FederatedCredentialData): Promise<FederatedCredential | null> Stores a federated credential (e.g., Google, Facebook, etc.).

• getFederatedCredential(options: FederatedCredentialRequestOptions, mediation?: CredentialMediationRequirement, signal?: AbortSignal): Promise<FederatedCredential | null> Retrieves a federated credential based on the given provider options.

OTP Credentials

• storeOTPCredential(data: OTPCredentialData): Promise<OTPCredential | null> Stores a one-time password credential.

• getOTPCredential(options: OTPCredentialRequestOptions, mediation?: CredentialMediationRequirement, signal?: AbortSignal): Promise<OTPCredential | null> Retrieves an OTP credential via the browser’s Web OTP API.

Public Key Credentials (WebAuthn)

• storePublicKeyCredential(data: PublicKeyCredentialCreationOptions, signal?: AbortSignal): Promise<PublicKeyCredential | null> Registers a new credential using the WebAuthn create() API.

• getPublicKeyCredential(options: PublicKeyCredentialRequestOptions, mediation?: CredentialMediationRequirement, signal?: AbortSignal): Promise<PublicKeyCredential | null> Retrieves a previously registered WebAuthn credential using the get() API.

Browser Support

The Credential Management API is available in most modern browsers, but support varies depending on the credential type.

| Credential Type | Chrome / Edge | Firefox | Safari | Notes | | ------------------- | ------------- | ------- | ------ | --------------------------------------------------------------------- | | PasswordCredential | ✅ | ✅ | ⚠️ | Safari has partial support and may not implement storage consistently | | FederatedCredential | ✅ | ⚠️ | ❌ | Firefox support is experimental; Safari does not support it | | OTPCredential | ✅ | ❌ | ❌ | Supported through the Web OTP API | | PublicKeyCredential | ✅ | ✅ | ✅ | WebAuthn is well supported across major browsers |

Requirements

• Must run in a secure context (HTTPS or localhost).
• Some features depend on user permissions or browser autofill settings.
• Always check support with isSupported() and is*CredentialSupported() before calling any methods.

This library performs these checks automatically, so in unsupported environments, calls will safely return null or false without throwing.

Contributing

Contributions are welcome! Whether it's fixing a typo, improving docs, or adding new features — your help makes this library better. Please follow these steps:

1. Clone the repository.
2. Create a feature branch (git checkout -b feature/my-feature).
3. Commit changes (git commit -m 'Add my feature').
4. Push to the branch (git push origin feature/my-feature).
5. Open a pull request.

License

MIT License. See LICENSE for details.

Issues

Report bugs or suggest features via the GitHub Issues page.