1. Trusted input
Receive the sensitive identity inside a server route, job, or trusted Node.js process.
Private identity
Server-derived avatars for sensitive identifiers.
Ordinary deterministic output is reproducible by anyone who knows the seed. For emails, account IDs, or other sensitive values, derive an HMAC seed on a trusted Node.js server first.
Derive on the server, render the result.
The private entry point canonicalizes the identifier and namespace, then signs a domain-separated message with HMAC-SHA-256. Only the derived value needs to reach ordinary rendering code.
2. HMAC derivation
Use a secret of at least 32 encoded bytes. Keep the secret exclusively in server-side configuration.
3. Safe rendering seed
Render the returned hmac-sha256: value or call a private avatar helper directly.
Three asynchronous helpers.
Import from the Node.js-only agent-avatars/private entry point. It uses the Web Crypto implementation from node:crypto.
import { derivePrivateSeed } from "agent-avatars/private";
import { createHashAvatar } from "agent-avatars";
const privateSeed = await derivePrivateSeed("person@example.com", {
namespace: "my-product/users",
secret: process.env.AVATAR_HMAC_SECRET,
});
const svg = createHashAvatar(privateSeed, {
seedMode: "raw",
namespace: "my-product/users",
});derivePrivateSeed()
Returns the stable HMAC-derived seed for storage or use by another renderer.
createPrivateAvatarDescriptor()
Returns a complete descriptor using the HMAC-derived seed for avatar selection.
createPrivateHashAvatar()
Derives and renders an SVG string in one asynchronous call.
Treat the secret as production infrastructure.
Use a secret manager or protected environment configuration. Validate that it exists at startup and keep environments isolated.
Do
- Generate a high-entropy value of at least 32 bytes.
- Keep separate secrets for unrelated trust boundaries.
- Limit access to the service that derives identities.
- Back up the secret if identities must remain stable.
Do not
- Commit the secret to source control.
- Prefix a public seed with a fixed string and call it private.
- Expose the private entry point or secret in browser code.
- Log the original identifier and secret together.
Secret rotation changes identity.
HMAC output depends on the secret. Rotating it intentionally produces new derived seeds and therefore new avatars.
Plan rotation like a data migration: version the active secret, keep the previous version during a controlled transition, regenerate stored output, and remove old access only when clients have adopted the new identity.
Your application manages keys, stores identifiers, and migrates existing records.
Privacy boundaries.
HMAC derivation uses a server-side secret to protect the seed. Evaluate avatar privacy alongside the surrounding product context.
Stable output is still linkable
The same private identity remains recognizable wherever the same derivation domain and rendering options are reused.
Access patterns still matter
Application logs, URLs, analytics payloads, and surrounding profile data can reveal identity independently of the avatar.
Keep public and private identity flows separate.
Use ordinary seeds for agents and services that are already public. Use server-side derivation for sensitive identifiers.