README.md

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.