![\"npm](\"https://img.shields.io/npm/v/@cap-kit/tls-fingerprint?color=blue&label=npm&logo=npm&style=flat-square\")
\n \n \n ![\"CI](\"https://img.shields.io/github/actions/workflow/status/cap-kit/capacitor-plugins/ci.yml?branch=main&label=CI&logo=github&style=flat-square\")
\n \n \n ![\"Capacitor](\"https://img.shields.io/badge/Capacitor-Plugin-blue?logo=capacitor&style=flat-square\"){kind=icon}
\n \n \n ![\"Downloads\"](\"https://img.shields.io/npm/dm/@cap-kit/tls-fingerprint?style=flat-square\")
\n \n \n ![\"License\"](\"https://img.shields.io/npm/l/@cap-kit/tls-fingerprint?style=flat-square&logo=open-source-initiative&logoColor=white&color=green\")
\n \n ![\"Maintained\"](\"https://img.shields.io/maintenance/yes/2026?style=flat-square\")
\n\n
\n \n @cap-kit/tls-fingerprint\n \n
\n Runtime TLS leaf certificate SHA-256 fingerprint validation for Capacitor applications. This plugin establishes a TLS\n connection to a remote HTTPS endpoint, extracts the server’s leaf certificate, computes its SHA-256 fingerprint, and\n compares it against one or more expected fingerprints defined at runtime or via static configuration. It performs\n fingerprint equality validation only and does not override or modify the system trust store.\n
\n\n\n \n
boolean | Enables verbose native logging. When enabled, additional debug information is printed to the native console (Logcat on Android, Xcode on iOS). This option affects native logging behavior only and has no impact on the JavaScript API. | false | 8.0.0 |\n| **`fingerprint`** | string | Default fingerprint used by `checkCertificate()` when `options.fingerprint` is not provided at runtime. | | 8.0.0 |\n| **`fingerprints`** | string[] | Default fingerprints used by `checkCertificates()` when `options.fingerprints` is not provided at runtime. | | 8.0.0 |\n| **`excludedDomains`** | string[] | Domains to bypass. Matches exact domain or subdomains. Do not include schemes or paths. | | 8.0.0 |\n\n### Examples\n\nIn `capacitor.config.json`:\n\n```json\n{\n \"plugins\": {\n \"TLSFingerprint\": {\n \"verboseLogging\": true,\n \"fingerprint\": \"50:4B:A1:B5:48:96:71:F3:9F:87:7E:0A:09:FD:3E:1B:C0:4F:AA:9F:FC:83:3E:A9:3A:00:78:88:F8:BA:60:26\",\n \"fingerprints\": [\n \"50:4B:A1:B5:48:96:71:F3:9F:87:7E:0A:09:FD:3E:1B:C0:4F:AA:9F:FC:83:3E:A9:3A:00:78:88:F8:BA:60:26\"\n ]\n }\n }\n}\n```\n\nIn `capacitor.config.ts`:\n\n```ts\n/// TLSFingerprintOptions |\n\n**Returns:** Promise<TLSFingerprintResult>\n\n**Since:** 8.0.0\n\n--------------------\n\n\n### checkCertificates(...)\n\n```typescript\ncheckCertificates(options: TLSFingerprintMultiOptions) => PromiseTLSFingerprintMultiOptions |\n\n**Returns:** Promise<TLSFingerprintResult>\n\n**Since:** 8.0.0\n\n--------------------\n\n\n### getPluginVersion()\n\n```typescript\ngetPluginVersion() => PromisePromise<PluginVersionResult>\n\n**Since:** 8.0.0\n\n#### Example\n\n```ts\nconst { version } = await TLSFingerprint.getPluginVersion();\n```\n\n--------------------\n\n\n### Interfaces\n\n\n#### TLSFingerprintResult\n\nResult returned by an TLS fingerprint operation.\n\nThis object is returned for ALL outcomes:\n- Success: `fingerprintMatched: true`\n- Mismatch: `fingerprintMatched: false` with error info (RESOLVED, not rejected)\n\nOnly operation failures (invalid input, config missing, network errors,\ntimeout, internal errors) reject the Promise.\n\n| Prop | Type | Description |\n| ------------------------ | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |\n| **`actualFingerprint`** | string | The actual SHA-256 fingerprint of the server certificate. Present in fingerprint and excluded modes. |\n| **`fingerprintMatched`** | boolean | Indicates whether the certificate validation succeeded. - true → Pinning passed - false → Pinning failed |\n| **`matchedFingerprint`** | string | The fingerprint that successfully matched, if any. |\n| **`excludedDomain`** | boolean | Indicates that TLS fingerprint was skipped because the request host matched an excluded domain. |\n| **`mode`** | 'fingerprint' \\| 'excluded' | Indicates which pinning mode was used. - \"fingerprint\" - \"excluded\" |\n| **`error`** | string | Human-readable error message when pinning fails. Present when `fingerprintMatched: false`. |\n| **`errorCode`** | TLSFingerprintErrorCode | Standardized error code aligned with TLSFingerprintErrorCode. |\n\n\n#### TLSFingerprintOptions\n\nOptions for checking a single SSL certificate.\n\n| Prop | Type | Description |\n| ----------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **`url`** | string | HTTPS URL of the server whose SSL certificate must be checked. This value is REQUIRED and cannot be provided via configuration. |\n| **`fingerprint`** | string | Expected SHA-256 fingerprint of the certificate. Resolution order: 1. `options.fingerprint` (runtime) 2. `plugins.TLSFingerprint.fingerprint` (config) If neither is provided, the Promise is rejected with `TLSFingerprintErrorCode.UNAVAILABLE`. |\n\n\n#### TLSFingerprintMultiOptions\n\nOptions for checking an SSL certificate using multiple allowed fingerprints.\n\n| Prop | Type | Description |\n| ------------------ | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **`url`** | string | HTTPS URL of the server whose SSL certificate must be checked. This value is REQUIRED and cannot be provided via configuration. |\n| **`fingerprints`** | string[] | Expected SHA-256 fingerprints of the certificate. Resolution order: 1. `options.fingerprints` (runtime) 2. `plugins.TLSFingerprint.fingerprints` (config) If neither is provided, the Promise is rejected with `TLSFingerprintErrorCode.UNAVAILABLE`. |\n\n\n#### PluginVersionResult\n\nResult returned by the getPluginVersion method.\n\n| Prop | Type | Description |\n| ------------- | ------------------- | ---------------------------------------- |\n| **`version`** | string | The native version string of the plugin. |\n\n\n### Enums\n\n\n#### TLSFingerprintErrorCode\n\n| Members | Value | Description |\n| ----------------------- | -------------------------------- | ------------------------------------------------------------------------------ |\n| **`UNAVAILABLE`** | 'UNAVAILABLE' | Required data is missing or the feature is not available. |\n| **`CANCELLED`** | 'CANCELLED' | The user cancelled an interactive flow. |\n| **`PERMISSION_DENIED`** | 'PERMISSION_DENIED' | The user denied a required permission or the feature is disabled. |\n| **`INIT_FAILED`** | 'INIT_FAILED' | The TLS fingerprint operation failed due to a runtime or initialization error. |\n| **`INVALID_INPUT`** | 'INVALID_INPUT' | The input provided to the plugin method is invalid, missing, or malformed. |\n| **`UNKNOWN_TYPE`** | 'UNKNOWN_TYPE' | Invalid or unsupported input was provided. |\n| **`NOT_FOUND`** | 'NOT_FOUND' | The requested resource does not exist. |\n| **`CONFLICT`** | 'CONFLICT' | The operation conflicts with the current state. |\n| **`TIMEOUT`** | 'TIMEOUT' | The operation did not complete within the expected time. |\n| **`PINNING_FAILED`** | 'PINNING_FAILED' | The server certificate fingerprint did not match any expected fingerprint. |\n| **`EXCLUDED_DOMAIN`** | 'EXCLUDED_DOMAIN' | The request host matched an excluded domain. |\n| **`NETWORK_ERROR`** | 'NETWORK_ERROR' | Network connectivity or TLS handshake error. |\n| **`SSL_ERROR`** | 'SSL_ERROR' | SSL/TLS specific error (certificate expired, handshake failure, etc.). |\n\n