@usenavii/core 0.6.0 → 0.7.0

package/dist/index.d.cts

@@ -82,6 +82,28 @@ declare function renderGroup(seeds: string[], options?: GroupOptions): string;
  * it with `createdAt` makes the result globally unique while remaining
  * stable across renders (assuming `createdAt` is set once at signup).
  */
+/**
+ * Normalize an email the same way Gravatar does — trim + lowercase, NFC.
+ * Exported so callers can reproduce the canonical form before hashing.
+ */
+declare function normalizeEmail(email: string): string;
+/**
+ * Turn an email into a stable, opaque seed using Gravatar's scheme:
+ * `sha256(trim(lowercase(email)))` → lowercase hex.
+ *
+ * Why: passing raw emails as seeds leaks them through URLs (server logs,
+ * Referer headers, browser history, CDN cache keys, analytics). The hash
+ * is stable across systems that normalize the same way, so two products
+ * looking up the same person get the same avatar.
+ *
+ * @example
+ * ```ts
+ * const s = seedFromEmail(user.email);
+ * createAvatar(s);                          // safe to log
+ * // or hit the API: `/avatar/${s}.svg`     // no plaintext email on the wire
+ * ```
+ */
+declare function seedFromEmail(email: string): string;
 interface SeedFields {
     /** Stable primary key (database id, UUID, OAuth sub). Best choice. */
     id?: string | number | null | undefined;
@@ -92,6 +114,18 @@ interface SeedFields {
     /** Account creation time. Combined with `name` to bake uniqueness in at signup. */
     createdAt?: string | number | Date | null | undefined;
 }
+interface SeedOptions {
+    /**
+     * When the email branch is used, hash the email instead of returning it
+     * raw. Hashing keeps the seed stable but stops the address from leaking
+     * into URLs, server logs, and Referer headers. Default `true` from v1.
+     *
+     * Set to `false` to opt back into the legacy plaintext-email behavior —
+     * useful for migrations where existing avatars are keyed off the raw
+     * email and you don't want every user's face to change.
+     */
+    hashEmail?: boolean;
+}
 /**
  * Compose a stable seed string from the most unique field available.
  *
@@ -107,9 +141,27 @@ interface SeedFields {
  * // → "Alice|1700000000000"
  * ```
  *
+ * @example Opt out of email hashing (legacy behavior):
+ * ```ts
+ * seed({ email: 'a@b.c' }, { hashEmail: false });
+ * // → "a@b.c"  — avoid; only for migrating off the old default.
+ * ```
+ *
  * @throws if no usable field is provided.
  */
-declare function seed(fields: SeedFields): string;
+declare function seed(fields: SeedFields, options?: SeedOptions): string;
+
+/**
+ * Sync SHA-256 (FIPS 180-4) → lowercase hex.
+ *
+ * Used by `seedFromEmail()` to match Gravatar's seed format
+ * (sha256 of trimmed, lowercased email). Sync API on purpose —
+ * a seed helper that returns a Promise is a footgun in render code.
+ *
+ * ~50 lines, no deps, zero allocations after init. Not for crypto
+ * use beyond opaque-identifier hashing.
+ */
+declare function sha256Hex(input: string): string;
 
 /**
  * Direct construction of an avatar from explicit part choices — no seed.
@@ -382,7 +434,8 @@ declare const Navii: {
     readonly select: typeof selectAvatar;
     readonly group: typeof renderGroup;
     readonly seed: typeof seed;
+    readonly seedFromEmail: typeof seedFromEmail;
     readonly build: typeof build;
 };
 
-export { AccessoryId, AntennaStyleId, AvatarOptions, AvatarSpec, BUILT_IN_PACKS, BackgroundId, BodyShapeId, type BuildSpec, EyeStyleId, type GroupOptions, MouthStyleId, Navii, OutfitId, PACK_REGISTRY, type Pack, type PackRegistry, Palette, type SeedFields, TopperId, build, createAvatar, createRng, cyrb53, random, renderAvatar, renderAvatarInner, renderGroup, resolvePacks, seed, selectAvatar };
+export { AccessoryId, AntennaStyleId, AvatarOptions, AvatarSpec, BUILT_IN_PACKS, BackgroundId, BodyShapeId, type BuildSpec, EyeStyleId, type GroupOptions, MouthStyleId, Navii, OutfitId, PACK_REGISTRY, type Pack, type PackRegistry, Palette, type SeedFields, type SeedOptions, TopperId, build, createAvatar, createRng, cyrb53, normalizeEmail, random, renderAvatar, renderAvatarInner, renderGroup, resolvePacks, seed, seedFromEmail, selectAvatar, sha256Hex };

package/dist/index.d.ts

@@ -82,6 +82,28 @@ declare function renderGroup(seeds: string[], options?: GroupOptions): string;
  * it with `createdAt` makes the result globally unique while remaining
  * stable across renders (assuming `createdAt` is set once at signup).
  */
+/**
+ * Normalize an email the same way Gravatar does — trim + lowercase, NFC.
+ * Exported so callers can reproduce the canonical form before hashing.
+ */
+declare function normalizeEmail(email: string): string;
+/**
+ * Turn an email into a stable, opaque seed using Gravatar's scheme:
+ * `sha256(trim(lowercase(email)))` → lowercase hex.
+ *
+ * Why: passing raw emails as seeds leaks them through URLs (server logs,
+ * Referer headers, browser history, CDN cache keys, analytics). The hash
+ * is stable across systems that normalize the same way, so two products
+ * looking up the same person get the same avatar.
+ *
+ * @example
+ * ```ts
+ * const s = seedFromEmail(user.email);
+ * createAvatar(s);                          // safe to log
+ * // or hit the API: `/avatar/${s}.svg`     // no plaintext email on the wire
+ * ```
+ */
+declare function seedFromEmail(email: string): string;
 interface SeedFields {
     /** Stable primary key (database id, UUID, OAuth sub). Best choice. */
     id?: string | number | null | undefined;
@@ -92,6 +114,18 @@ interface SeedFields {
     /** Account creation time. Combined with `name` to bake uniqueness in at signup. */
     createdAt?: string | number | Date | null | undefined;
 }
+interface SeedOptions {
+    /**
+     * When the email branch is used, hash the email instead of returning it
+     * raw. Hashing keeps the seed stable but stops the address from leaking
+     * into URLs, server logs, and Referer headers. Default `true` from v1.
+     *
+     * Set to `false` to opt back into the legacy plaintext-email behavior —
+     * useful for migrations where existing avatars are keyed off the raw
+     * email and you don't want every user's face to change.
+     */
+    hashEmail?: boolean;
+}
 /**
  * Compose a stable seed string from the most unique field available.
  *
@@ -107,9 +141,27 @@ interface SeedFields {
  * // → "Alice|1700000000000"
  * ```
  *
+ * @example Opt out of email hashing (legacy behavior):
+ * ```ts
+ * seed({ email: 'a@b.c' }, { hashEmail: false });
+ * // → "a@b.c"  — avoid; only for migrating off the old default.
+ * ```
+ *
  * @throws if no usable field is provided.
  */
-declare function seed(fields: SeedFields): string;
+declare function seed(fields: SeedFields, options?: SeedOptions): string;
+
+/**
+ * Sync SHA-256 (FIPS 180-4) → lowercase hex.
+ *
+ * Used by `seedFromEmail()` to match Gravatar's seed format
+ * (sha256 of trimmed, lowercased email). Sync API on purpose —
+ * a seed helper that returns a Promise is a footgun in render code.
+ *
+ * ~50 lines, no deps, zero allocations after init. Not for crypto
+ * use beyond opaque-identifier hashing.
+ */
+declare function sha256Hex(input: string): string;
 
 /**
  * Direct construction of an avatar from explicit part choices — no seed.
@@ -382,7 +434,8 @@ declare const Navii: {
     readonly select: typeof selectAvatar;
     readonly group: typeof renderGroup;
     readonly seed: typeof seed;
+    readonly seedFromEmail: typeof seedFromEmail;
     readonly build: typeof build;
 };
 
-export { AccessoryId, AntennaStyleId, AvatarOptions, AvatarSpec, BUILT_IN_PACKS, BackgroundId, BodyShapeId, type BuildSpec, EyeStyleId, type GroupOptions, MouthStyleId, Navii, OutfitId, PACK_REGISTRY, type Pack, type PackRegistry, Palette, type SeedFields, TopperId, build, createAvatar, createRng, cyrb53, random, renderAvatar, renderAvatarInner, renderGroup, resolvePacks, seed, selectAvatar };
+export { AccessoryId, AntennaStyleId, AvatarOptions, AvatarSpec, BUILT_IN_PACKS, BackgroundId, BodyShapeId, type BuildSpec, EyeStyleId, type GroupOptions, MouthStyleId, Navii, OutfitId, PACK_REGISTRY, type Pack, type PackRegistry, Palette, type SeedFields, type SeedOptions, TopperId, build, createAvatar, createRng, cyrb53, normalizeEmail, random, renderAvatar, renderAvatarInner, renderGroup, resolvePacks, seed, seedFromEmail, selectAvatar, sha256Hex };

package/dist/index.js

@@ -1666,13 +1666,176 @@ function clamp(n, lo, hi) {
   return Math.max(lo, Math.min(hi, n));
 }
 
+// src/sha256.ts
+var K = new Uint32Array([
+  1116352408,
+  1899447441,
+  3049323471,
+  3921009573,
+  961987163,
+  1508970993,
+  2453635748,
+  2870763221,
+  3624381080,
+  310598401,
+  607225278,
+  1426881987,
+  1925078388,
+  2162078206,
+  2614888103,
+  3248222580,
+  3835390401,
+  4022224774,
+  264347078,
+  604807628,
+  770255983,
+  1249150122,
+  1555081692,
+  1996064986,
+  2554220882,
+  2821834349,
+  2952996808,
+  3210313671,
+  3336571891,
+  3584528711,
+  113926993,
+  338241895,
+  666307205,
+  773529912,
+  1294757372,
+  1396182291,
+  1695183700,
+  1986661051,
+  2177026350,
+  2456956037,
+  2730485921,
+  2820302411,
+  3259730800,
+  3345764771,
+  3516065817,
+  3600352804,
+  4094571909,
+  275423344,
+  430227734,
+  506948616,
+  659060556,
+  883997877,
+  958139571,
+  1322822218,
+  1537002063,
+  1747873779,
+  1955562222,
+  2024104815,
+  2227730452,
+  2361852424,
+  2428436474,
+  2756734187,
+  3204031479,
+  3329325298
+]);
+function rotr(x, n) {
+  return (x >>> n | x << 32 - n) >>> 0;
+}
+function utf8Encode(str) {
+  if (typeof TextEncoder !== "undefined") return new TextEncoder().encode(str);
+  const out = [];
+  for (let i = 0; i < str.length; i++) {
+    let c = str.charCodeAt(i);
+    if (c < 128) out.push(c);
+    else if (c < 2048) {
+      out.push(192 | c >> 6, 128 | c & 63);
+    } else if (c < 55296 || c >= 57344) {
+      out.push(224 | c >> 12, 128 | c >> 6 & 63, 128 | c & 63);
+    } else {
+      i++;
+      c = 65536 + ((c & 1023) << 10 | str.charCodeAt(i) & 1023);
+      out.push(
+        240 | c >> 18,
+        128 | c >> 12 & 63,
+        128 | c >> 6 & 63,
+        128 | c & 63
+      );
+    }
+  }
+  return new Uint8Array(out);
+}
+function sha256Hex(input) {
+  const msg = utf8Encode(input);
+  const bitLen = msg.length * 8;
+  const padLen = (msg.length + 9 + 63 & -64) - msg.length;
+  const buf = new Uint8Array(msg.length + padLen);
+  buf.set(msg);
+  buf[msg.length] = 128;
+  const dv = new DataView(buf.buffer);
+  dv.setUint32(buf.length - 4, bitLen >>> 0, false);
+  dv.setUint32(buf.length - 8, Math.floor(bitLen / 4294967296), false);
+  const H = new Uint32Array([
+    1779033703,
+    3144134277,
+    1013904242,
+    2773480762,
+    1359893119,
+    2600822924,
+    528734635,
+    1541459225
+  ]);
+  const W = new Uint32Array(64);
+  for (let chunk = 0; chunk < buf.length; chunk += 64) {
+    for (let i = 0; i < 16; i++) W[i] = dv.getUint32(chunk + i * 4, false);
+    for (let i = 16; i < 64; i++) {
+      const s0 = rotr(W[i - 15], 7) ^ rotr(W[i - 15], 18) ^ W[i - 15] >>> 3;
+      const s1 = rotr(W[i - 2], 17) ^ rotr(W[i - 2], 19) ^ W[i - 2] >>> 10;
+      W[i] = W[i - 16] + s0 + W[i - 7] + s1 >>> 0;
+    }
+    let a = H[0], b = H[1], c = H[2], d = H[3];
+    let e = H[4], f = H[5], g = H[6], h = H[7];
+    for (let i = 0; i < 64; i++) {
+      const S1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+      const ch = e & f ^ ~e & g;
+      const t1 = h + S1 + ch + K[i] + W[i] >>> 0;
+      const S0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+      const mj = a & b ^ a & c ^ b & c;
+      const t2 = S0 + mj >>> 0;
+      h = g;
+      g = f;
+      f = e;
+      e = d + t1 >>> 0;
+      d = c;
+      c = b;
+      b = a;
+      a = t1 + t2 >>> 0;
+    }
+    H[0] = H[0] + a >>> 0;
+    H[1] = H[1] + b >>> 0;
+    H[2] = H[2] + c >>> 0;
+    H[3] = H[3] + d >>> 0;
+    H[4] = H[4] + e >>> 0;
+    H[5] = H[5] + f >>> 0;
+    H[6] = H[6] + g >>> 0;
+    H[7] = H[7] + h >>> 0;
+  }
+  let out = "";
+  for (let i = 0; i < 8; i++) out += H[i].toString(16).padStart(8, "0");
+  return out;
+}
+
 // src/seed.ts
-function seed(fields) {
+function normalizeEmail(email) {
+  return email.trim().toLowerCase().normalize("NFC");
+}
+function seedFromEmail(email) {
+  if (typeof email !== "string" || email.length === 0) {
+    throw new Error("navii: seedFromEmail() requires a non-empty string");
+  }
+  return sha256Hex(normalizeEmail(email));
+}
+function seed(fields, options = {}) {
+  const hashEmail = options.hashEmail ?? true;
   if (fields.id !== null && fields.id !== void 0 && String(fields.id).length > 0) {
     return String(fields.id);
   }
   if (fields.email && fields.email.length > 0) {
-    return fields.email;
+    return hashEmail ? seedFromEmail(fields.email) : fields.email;
   }
   if (fields.name && fields.name.length > 0) {
     if (fields.createdAt !== null && fields.createdAt !== void 0) {
@@ -1731,9 +1894,10 @@ var Navii = {
   select: selectAvatar,
   group: renderGroup,
   seed,
+  seedFromEmail,
   build
 };
 
-export { BUILT_IN_PACKS, Navii, PACK_REGISTRY, build, createAvatar, createRng, cyrb53, random, renderAvatar, renderAvatarInner, renderGroup, resolvePacks, seed, selectAvatar };
+export { BUILT_IN_PACKS, Navii, PACK_REGISTRY, build, createAvatar, createRng, cyrb53, normalizeEmail, random, renderAvatar, renderAvatarInner, renderGroup, resolvePacks, seed, seedFromEmail, selectAvatar, sha256Hex };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map