@unavatar/core 3.24.0 → 3.25.0

package/README.md

@@ -52,6 +52,7 @@
   - [X/Twitter](#xtwitter)
   - [Xbox Gamertag](#xbox-gamertag)
   - [YouTube](#youtube)
+- [Privacy](#privacy)
 - [Response Format](#response-format)
 - [Response Headers](#response-headers)
 - [Response Errors](#response-errors)
@@ -68,13 +69,15 @@ It's proudly powered by [microlink.io](https://microlink.io/), the headless brow
 
 The service is exposed in **unavatar.io** via provider endpoints:
 
-- an **email (auto-detect)**: [unavatar.io/hello@microlink.io](https://unavatar.io/hello@microlink.io) — tries Gravatar, then GitHub
+- an **email**: [unavatar.io/email/hello@microlink.io](https://unavatar.io/email/hello@microlink.io)
+- an **email hash** (auto-detected as hashed email): [unavatar.io/email/295dee0d3dbb93aac67e72ae4af40f728f050e5fd18417ad60d1ed19186ae03b](https://unavatar.io/email/295dee0d3dbb93aac67e72ae4af40f728f050e5fd18417ad60d1ed19186ae03b)
+- a **domain**: [unavatar.io/domain/reddit.com](https://unavatar.io/domain/reddit.com)
 - an **email** via Gravatar: [unavatar.io/gravatar/hello@microlink.io](https://unavatar.io/gravatar/hello@microlink.io)
 - an **email** via GitHub: [unavatar.io/github/sindresorhus@gmail.com](https://unavatar.io/github/sindresorhus@gmail.com)
 - an **username**: [unavatar.io/github/kikobeats](https://unavatar.io/github/kikobeats)
 - a **domain**: [unavatar.io/google/reddit.com](https://unavatar.io/google/reddit.com)
 
-Use `/:provider/:key` for provider-specific lookups, or pass an email as the only path segment for automatic resolution. You can read more in [Email avatars](https://unavatar.io/email) and [providers](https://unavatar.io/docs#providers).
+Use `/email/:key` and `/domain/:key` for type-based resolution. You can read more in [Email avatars](https://unavatar.io/email) and [providers](https://unavatar.io/docs#providers).
 
 ## Authentication
 
@@ -410,6 +413,10 @@ Get any user's avatar by their email address via Gravatar. The most widely used
 Available inputs:
 
 - Email address, e.g., [unavatar.io/gravatar/hello@microlink.io](https://unavatar.io/gravatar/hello@microlink.io)
+- SHA256 hash, e.g., [unavatar.io/gravatar/295dee0d3dbb93aac67e72ae4af40f728f050e5fd18417ad60d1ed19186ae03b](https://unavatar.io/gravatar/295dee0d3dbb93aac67e72ae4af40f728f050e5fd18417ad60d1ed19186ae03b)
+- MD5 hash (legacy), e.g., [unavatar.io/gravatar/0bc83cb571cd1c50ba6f3e8a78ef1346](https://unavatar.io/gravatar/0bc83cb571cd1c50ba6f3e8a78ef1346)
+
+Passing a pre-computed hash instead of the raw email avoids exposing the email address in the URL. See [Privacy](#privacy) for details.
 
 ### Instagram
 
@@ -651,7 +658,7 @@ Available inputs:
 
 ### YouTube
 
-Get any YouTube channel's thumbnail by their handle, legacy username, or channel ID.
+Get any YouTube channel's thumbnail by their handle, username, or channel ID.
 
 e.g., [unavatar.io/youtube/casey](https://unavatar.io/youtube/casey)
 
@@ -664,6 +671,27 @@ Available inputs:
 - `username`: [unavatar.io/youtube/casey](https://unavatar.io/youtube/casey)
 - `channel`: [unavatar.io/youtube/UC_x5XG1OV2P6uZZ5FSM9Ttw](https://unavatar.io/youtube/UC_x5XG1OV2P6uZZ5FSM9Ttw)
 
+## Privacy
+
+When you pass an email address directly in the URL, it is visible in plain text — both in server logs and to any intermediary that inspects the request.
+
+To avoid this, pass a pre-computed **MD5** or **SHA256** hash of the email instead. Unavatar detects the hash automatically and routes it to Gravatar, which natively supports both hash formats.
+
+```bash
+# Instead of exposing the raw email:
+https://unavatar.io/hello@example.com
+
+# Pass the SHA256 hash:
+https://unavatar.io/295dee0d3dbb93aac67e72ae4af40f728f050e5fd18417ad60d1ed19186ae03b
+
+# Or the MD5 hash (legacy, still supported by Gravatar):
+https://unavatar.io/0bc83cb571cd1c50ba6f3e8a78ef1346
+```
+
+The hash must be exactly 32 hex characters (MD5) or 64 hex characters (SHA256), lowercase or uppercase — unavatar normalises it automatically.
+
+Note: hash-based lookup is only supported for Gravatar. Other providers such as GitHub require the raw email address and cannot reverse a hash.
+
 ## Response Format
 
 A response is returning the user avatar by default.
@@ -745,4 +773,4 @@ Expected errors are known operational cases returned with stable codes.
 
 ## Contact
 
-If you have any suggestion or bug to report, please contact to ust mailing to [hello@unavatar.io](mailto:hello@unavatar.io).
+If you have any suggestion or bug to report, please contact to ust mailing to [hello@unavatar.io](mailto:hello@unavatar.io).

package/package.json

@@ -2,7 +2,7 @@
   "name": "@unavatar/core",
   "description": "Get unified user avatar from social networks, including Instagram, SoundCloud, Telegram, Twitter, YouTube & more.",
   "homepage": "https://unavatar.io",
-  "version": "3.24.0",
+  "version": "3.25.0",
   "main": "src/index.js",
   "exports": {
     ".": "./src/index.js",
@@ -50,6 +50,10 @@
       "name": "Nicolas Hedger",
       "email": "649677+nhedger@users.noreply.github.com"
     },
+    {
+      "name": "Mariano Álvarez",
+      "email": "66380259+creativoma@users.noreply.github.com"
+    },
     {
       "name": "Angel M De Miguel",
       "email": "angel@bitnami.com"

package/src/avatar/auto.js

@@ -15,8 +15,10 @@ const ExtendableError = require('../util/error')
 const DATA_URI_REGEX = dataUriRegex()
 const DOMAIN_REGEX = urlRegex({ strict: false })
 
+const isHash = require('../util/is-hash')
+
 const getInputType = input => {
-  if (isEmail(input)) return 'email'
+  if (isEmail(input) || isHash(input)) return 'email'
   if (stableRegex(DOMAIN_REGEX, input)) return 'domain'
   return 'username'
 }
@@ -84,7 +86,12 @@ const factory = ({ constants, providers, providersBy, reachableUrl }) => {
   }
 
   const resolveAutoByType = async (inputType, input, context) => {
-    const collection = providerEntriesByType[inputType]
+    let collection = providerEntriesByType[inputType]
+
+    if (inputType === 'email' && isHash(input)) {
+      collection = collection.filter(([provider]) => provider === 'gravatar')
+    }
+
     const promises = new Array(collection.length)
 
     for (let index = 0; index < collection.length; index++) {

package/src/index.js

@@ -61,6 +61,11 @@ module.exports = ({ constants: userConstants, redis, onFetchHTML } = {}) => {
     unavatar[name] = input => getAvatar(providers[name], name, input, {})
   })
 
+  const createTypedAutoResolver = inputType => input => auto(inputType)(input, {})
+
+  unavatar.email = createTypedAutoResolver('email')
+  unavatar.domain = createTypedAutoResolver('domain')
+
   unavatar.auto = auto
   unavatar.getInputType = getInputType
   unavatar.getAvatar = getAvatar

package/src/providers/gravatar.js

@@ -3,14 +3,16 @@
 const crypto = require('crypto')
 
 const stringify = require('../util/stringify')
+const isHash = require('../util/is-hash')
 
-const md5 = str => crypto.createHash('md5').update(str).digest('hex')
+const sha256 = str => crypto.createHash('sha256').update(str).digest('hex')
+
+const toHash = input =>
+  isHash(input) ? input.toLowerCase() : sha256(input.trim().toLowerCase())
 
 module.exports = ({ constants }) =>
   function gravatar (input) {
-    return `https://gravatar.com/avatar/${md5(
-      input.trim().toLowerCase()
-    )}?${stringify({
+    return `https://gravatar.com/avatar/${toHash(input)}?${stringify({
       size: constants.AVATAR_SIZE,
       d: '404'
     })}`

package/src/util/is-hash.js

@@ -0,0 +1,5 @@
+'use strict'
+
+const HASH_REGEX = /^[0-9a-f]{32}$|^[0-9a-f]{64}$/i
+
+module.exports = input => HASH_REGEX.test(input)