@oxyhq/core 16.0.0 → 17.0.0

package/src/server/userInvalidation.ts

@@ -0,0 +1,221 @@
+/**
+ * Oxy user-invalidation publish/consume helpers for Oxy backends.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * Every Oxy backend caches Oxy identity, and none of them find out when it
+ * changes. The `OxyServices` GET response cache holds `GET /users/:id` and
+ * `GET /profiles/username/:name` for five minutes; it is swept when THIS process
+ * writes the profile (see the `clearCacheEntry` calls in the user mixin) and
+ * never when somebody else does — which is the normal case, since profiles are
+ * edited in Oxy's own apps. So an avatar or display-name change is invisible to
+ * every consuming backend for up to five minutes, per process.
+ *
+ * oxy-api broadcasts {@link OXY_USER_INVALIDATION_CHANNEL} on the shared Valkey
+ * when a user's identity changes. This module is the consumer half: it parses
+ * and validates the event, sweeps the SDK's own cache, and hands the event to
+ * app-specific eviction. Wiring it is two lines and every backend that does so
+ * stops serving stale identity.
+ *
+ * WHY THE TRANSPORT IS THE CALLER'S JOB
+ * -------------------------------------
+ * This module deliberately does NOT take a Redis client. ioredis and node-redis
+ * disagree about how to subscribe — node-redis passes the listener to
+ * `subscribe(channel, listener)`, ioredis takes `subscribe(channel)` and then
+ * emits `'message'` on the client — and a helper that accepted "a client" would
+ * have to sniff which library it was handed. That kind of detection is exactly
+ * what breaks silently when a consumer upgrades a client library.
+ *
+ * So the split is: this module owns parsing, validation, dispatch and the
+ * never-throw guarantee (the parts that are easy to get wrong and identical
+ * everywhere), and the caller owns its own client's two-line subscribe idiom
+ * (trivial, but library-specific).
+ *
+ *     // node-redis
+ *     await subscriber.subscribe(
+ *       OXY_USER_INVALIDATION_CHANNEL,
+ *       createOxyUserInvalidationHandler({ oxy: oxyClient }),
+ *     );
+ *
+ *     // ioredis
+ *     const handle = createOxyUserInvalidationHandler({ oxy: oxyClient });
+ *     await subscriber.subscribe(OXY_USER_INVALIDATION_CHANNEL);
+ *     subscriber.on('message', (_channel, raw) => handle(raw));
+ *
+ * Subscribe on EVERY task, not just an elected leader. The SDK cache this sweeps
+ * is per-process in-memory, so a leader-only subscriber would leave every other
+ * task stale — and leader-gating would add a failure mode (leader down means no
+ * invalidation anywhere) to a signal whose whole point is that losing it is
+ * merely slow, never wrong.
+ *
+ * Node-only; exported solely from `@oxyhq/core/server`.
+ */
+
+import {
+  OXY_USER_INVALIDATION_CHANNEL,
+  isPublishedOxyUserChangeReason,
+  oxyUserInvalidationEventSchema,
+  type OxyUserChangeReason,
+  type OxyUserInvalidationEvent,
+} from '@oxyhq/contracts';
+
+/**
+ * The publish surface of a Redis client. Both `ioredis` and `node-redis`
+ * satisfy this structurally, so neither library is a dependency here.
+ */
+export interface OxyInvalidationPublisher {
+  publish(channel: string, message: string): unknown;
+}
+
+/**
+ * The cache-eviction surface of an {@link OxyServices} instance. Declared
+ * structurally so this Node-only module does not pull in the client.
+ */
+export interface OxyIdentityCacheEvictor {
+  clearCacheEntry(key: string): void;
+  clearCacheByPrefix(prefix: string): number;
+}
+
+/**
+ * Broadcast that an Oxy user's record changed.
+ *
+ * Returns `true` when a message was put on the wire and `false` when the reason
+ * is not a broadcast one ({@link isPublishedOxyUserChangeReason}) — the latter is
+ * a deliberate no-op, not a failure. Suppressing at the publisher rather than
+ * letting every subscriber discard matters at bulk-follow scale, where a single
+ * call moves up to 200 edges.
+ *
+ * NEVER THROWS AND NEVER RETURNS A REJECTED PROMISE. This is called from inside
+ * cache invalidation, which itself runs after a successful database write on the
+ * request path: a publish failure must not turn a completed profile update into
+ * a 500. A dropped message costs a consumer its TTL and nothing more.
+ *
+ * @param publisher - A connected Redis client. Must NOT be a client currently in
+ *                    subscriber mode — Redis forbids `PUBLISH` on a subscribed
+ *                    connection, so pass the publisher half of a pub/sub pair.
+ * @param userId    - The Oxy user whose record changed.
+ * @param reason    - How the record changed. See {@link OxyUserChangeReason}.
+ * @param onError   - Optional diagnostic sink for a failed publish.
+ */
+export function publishOxyUserInvalidation(
+  publisher: OxyInvalidationPublisher,
+  userId: string,
+  reason: OxyUserChangeReason,
+  onError?: (error: unknown) => void,
+): boolean {
+  if (!userId || !isPublishedOxyUserChangeReason(reason)) {
+    return false;
+  }
+
+  const event: OxyUserInvalidationEvent = { userId, reason, at: Date.now() };
+
+  try {
+    const result = publisher.publish(OXY_USER_INVALIDATION_CHANNEL, JSON.stringify(event));
+    // node-redis returns a promise; ioredis returns a promise too, but a mocked
+    // or synchronous client may return anything. Only attach a rejection handler
+    // when there is actually something thenable to reject.
+    if (isPromiseLike(result)) {
+      Promise.resolve(result).catch((error: unknown) => onError?.(error));
+    }
+    return true;
+  } catch (error) {
+    onError?.(error);
+    return false;
+  }
+}
+
+function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as { then?: unknown }).then === 'function'
+  );
+}
+
+/** Options for {@link createOxyUserInvalidationHandler}. */
+export interface OxyUserInvalidationHandlerOptions {
+  /**
+   * The backend's `OxyServices` instance. When supplied, its GET response cache
+   * is swept for the invalidated user — this is the whole reason a backend that
+   * has no cache of its own still benefits from subscribing.
+   */
+  oxy?: OxyIdentityCacheEvictor;
+  /**
+   * App-specific eviction (e.g. a Redis identity cache the app maintains itself).
+   * May be async; a rejection is routed to `onError` and never escapes.
+   */
+  onInvalidate?: (event: OxyUserInvalidationEvent) => void | Promise<void>;
+  /** Diagnostic sink for an unparseable message or a failing `onInvalidate`. */
+  onError?: (error: unknown, raw: string) => void;
+}
+
+/**
+ * Build the message handler for {@link OXY_USER_INVALIDATION_CHANNEL}.
+ *
+ * The returned function NEVER THROWS and never returns a rejected promise. It
+ * runs inside the Redis client's message dispatch, where an exception either
+ * takes down the subscriber connection or surfaces as an unhandled rejection —
+ * and losing the subscription is strictly worse than losing one message, because
+ * it is silent and permanent.
+ *
+ * A message that fails schema validation is dropped, not retried: the payload is
+ * produced by a contract both sides compile against, so a malformed one means a
+ * version skew or an unrelated publisher on the channel, neither of which a retry
+ * fixes.
+ */
+export function createOxyUserInvalidationHandler(
+  options: OxyUserInvalidationHandlerOptions = {},
+): (raw: string) => void {
+  const { oxy, onInvalidate, onError } = options;
+
+  return (raw: string): void => {
+    let event: OxyUserInvalidationEvent;
+    try {
+      const parsed = oxyUserInvalidationEventSchema.safeParse(JSON.parse(raw));
+      if (!parsed.success) {
+        onError?.(parsed.error, raw);
+        return;
+      }
+      event = parsed.data;
+    } catch (error) {
+      onError?.(error, raw);
+      return;
+    }
+
+    if (oxy) {
+      try {
+        evictOxyIdentityCache(oxy, event.userId);
+      } catch (error) {
+        // A cache sweep must never cost us the app-specific eviction below.
+        onError?.(error, raw);
+      }
+    }
+
+    if (!onInvalidate) return;
+    try {
+      const result = onInvalidate(event);
+      if (isPromiseLike(result)) {
+        Promise.resolve(result).catch((error: unknown) => onError?.(error, raw));
+      }
+    } catch (error) {
+      onError?.(error, raw);
+    }
+  };
+}
+
+/**
+ * Sweep an `OxyServices` GET response cache of everything that could carry the
+ * given user's identity.
+ *
+ * The by-id entry is exact. The by-username and resolve entries are keyed by
+ * HANDLE, which cannot be derived from an id without the very lookup we are
+ * invalidating, so those are swept by prefix — the same imprecision the SDK
+ * already accepts when it sweeps its own cache after a local profile write, and
+ * bounded by the fact that over-eviction costs a refetch and can never serve
+ * wrong data.
+ */
+export function evictOxyIdentityCache(oxy: OxyIdentityCacheEvictor, userId: string): void {
+  oxy.clearCacheEntry(`GET:/users/${userId}`);
+  oxy.clearCacheByPrefix('GET:/profiles/username/');
+  oxy.clearCacheByPrefix('GET:/profiles/resolve');
+}

package/src/utils/__tests__/coldBoot.test.ts

@@ -241,13 +241,17 @@ describe('runColdBoot', () => {
     it('hangs forever when a step never settles and no deadline is set', async () => {
       const terminalRan = jest.fn();
       let settled = false;
+      let releaseHang: (() => void) | undefined;
 
       const outcomePromise = runColdBoot<TestSession>({
         steps: [
           {
             id: 'never-settles',
-            // Never resolves or rejects — models a hung async call.
-            run: () => new Promise<ColdBootStepResult<TestSession>>(() => {}),
+            // Never resolves or rejects until the test tears down — models a hung async call.
+            run: () =>
+              new Promise<ColdBootStepResult<TestSession>>((resolve) => {
+                releaseHang = () => resolve({ kind: 'skip' });
+              }),
           },
           {
             id: 'terminal',
@@ -268,8 +272,9 @@ describe('runColdBoot', () => {
       expect(settled).toBe(false);
       expect(terminalRan).not.toHaveBeenCalled();
 
-      // Avoid a dangling unhandled promise in the test runner.
-      void outcomePromise;
+      // Tear down the intentional hang so Jest workers can exit cleanly.
+      releaseHang?.();
+      await outcomePromise;
     });
 
     /**

package/src/utils/__tests__/validationUtils.test.ts

@@ -13,6 +13,7 @@ import {
   DISPLAY_NAME_ALLOWED_SCRIPTS,
   DISPLAY_NAME_DISALLOWED_SOURCE,
   DISPLAY_NAME_ORPHANED_MARK_SOURCE,
+  DISPLAY_NAME_UNFLANKED_SEPARATOR_SOURCE,
   isValidUUID,
   isValidDate,
   isValidFileSize,
@@ -21,6 +22,16 @@ import {
   sanitizeHTML,
   validateAndSanitizeUserInput
 } from '../validationUtils';
+// Imported from the generated module rather than re-exported through
+// `validationUtils`: the broad letters class is an internal operand of the
+// orphaned-mark lookbehind, and the denylist is a generation-time operand
+// already subtracted from the allowlist — neither is part of the policy's
+// public runtime surface.
+import {
+  DISPLAY_NAME_DENIED_SYMBOL_LETTERS_RANGES,
+  DISPLAY_NAME_LETTERS_RANGES,
+  DISPLAY_NAME_NAME_SEPARATORS_RANGES,
+} from '../displayNamePolicyRanges.generated';
 
 describe('Validation Utils', () => {
   describe('isRequiredString', () => {
@@ -214,6 +225,7 @@ describe('Validation Utils', () => {
       expect(PROPERTY_ESCAPE.test(DISPLAY_NAME_ALLOWED_SCRIPTS)).toBe(false);
       expect(PROPERTY_ESCAPE.test(DISPLAY_NAME_DISALLOWED_SOURCE)).toBe(false);
       expect(PROPERTY_ESCAPE.test(DISPLAY_NAME_ORPHANED_MARK_SOURCE)).toBe(false);
+      expect(PROPERTY_ESCAPE.test(DISPLAY_NAME_UNFLANKED_SEPARATOR_SOURCE)).toBe(false);
     });
 
     it('only uses code-point escapes (\\x / \\u) in the class bodies', () => {
@@ -221,7 +233,11 @@ describe('Validation Utils', () => {
       // code-point escapes. Every backslash-escape in the runtime sources must
       // be one of those forms — never a property escape.
       const escapeLeads = new Set<string>();
-      for (const src of [DISPLAY_NAME_DISALLOWED_SOURCE, DISPLAY_NAME_ORPHANED_MARK_SOURCE]) {
+      for (const src of [
+        DISPLAY_NAME_DISALLOWED_SOURCE,
+        DISPLAY_NAME_ORPHANED_MARK_SOURCE,
+        DISPLAY_NAME_UNFLANKED_SEPARATOR_SOURCE,
+      ]) {
         for (const [, lead] of src.matchAll(/\\(.)/g)) {
           escapeLeads.add(lead);
         }
@@ -299,6 +315,281 @@ describe('Validation Utils', () => {
     });
   });
 
+  // A Unicode script is not only its letters: `scx=X` also carries script X's
+  // own digits, punctuation and symbols. The allowlist is therefore generated as
+  // `scripts ∩ General_Category L`. Before that intersection existed the class
+  // admitted 1831 non-letter code points, so the documented policy ("digits,
+  // hyphens, dots, symbols are removed") held for ASCII input only — a federated
+  // actor could keep Arabic-Indic digits, a Bengali currency sign, or the U+061C
+  // bidi control in their display name. This block is the regression guard.
+  describe('display-name allowlist admits ONLY letters', () => {
+    const allowed = new RegExp(`[${DISPLAY_NAME_ALLOWED_SCRIPTS}]`, 'u');
+    // Built from the same generated ranges the policy ships, so this assertion
+    // stays property-escape-free and cannot drift from the runtime regex.
+    const letter = new RegExp(`[${DISPLAY_NAME_LETTERS_RANGES}]`, 'u');
+
+    // Scanning the FULL code-point space, not a sample: one leaked invisible
+    // control is a spoofing vector, and a sample cannot prove its absence.
+    const leaks: number[] = [];
+    let admitted = 0;
+    for (let cp = 0; cp <= 0x10ffff; cp++) {
+      if (cp >= 0xd800 && cp <= 0xdfff) continue; // lone surrogates
+      const ch = String.fromCodePoint(cp);
+      if (!allowed.test(ch)) continue;
+      admitted++;
+      if (!letter.test(ch)) leaks.push(cp);
+    }
+
+    it('admits no non-letter code point anywhere in Unicode', () => {
+      const named = leaks
+        .slice(0, 16)
+        .map((cp) => `U+${cp.toString(16).toUpperCase().padStart(4, '0')}`);
+      expect({ count: leaks.length, sample: named }).toEqual({ count: 0, sample: [] });
+    });
+
+    // Vacuity floor: an allowlist that collapsed to (near) nothing would satisfy
+    // the assertion above while silently rejecting every real name.
+    it('still admits the expected bulk of letters', () => {
+      expect(admitted).toBeGreaterThan(100_000);
+    });
+
+    it.each([
+      ['٥', 'Arabic-Indic digit (scx=Arabic, GC=Nd)'],
+      ['०', 'Devanagari digit (scx=Devanagari, GC=Nd)'],
+      ['۞', 'Arabic ornament (scx=Arabic, GC=So)'],
+      ['৳', 'Bengali rupee sign (scx=Bengali, GC=Sc)'],
+      ['।', 'Devanagari danda (scx=Devanagari, GC=Po)'],
+      ['،', 'Arabic comma (scx=Arabic, GC=Po)'],
+      ['؜', 'ARABIC LETTER MARK - invisible bidi control (scx=Arabic, GC=Cf)'],
+      ['᠎', 'MONGOLIAN VOWEL SEPARATOR - invisible (scx=Mongolian, GC=Cf)'],
+    ])('rejects %p, a non-letter from an allowlisted script (%s)', (ch) => {
+      expect(isValidDisplayName(ch)).toBe(false);
+    });
+
+    // The intersection narrows the allowlist, so every previously-accepted real
+    // name must still pass — these are the ones whose scripts own the code
+    // points removed above.
+    it.each([
+      ['مُحَمَد', 'Arabic letters + harakat survive'],
+      ['नमस्ते', 'Devanagari'],
+      ['ᠰᠣᠩᠭᠣᠯ', 'Mongolian'],
+      ['বাংলা', 'Bengali'],
+    ])('still accepts %p (%s)', (name) => {
+      expect(isValidDisplayName(name)).toBe(true);
+    });
+  });
+
+  // A character policy classifies FORM, never MEANING. `卐` U+5350 and `卍`
+  // U+534D are CJK Unified Ideographs (GC=Lo, scx=Han) — to Unicode they are the
+  // same kind of thing as `山` in `山田太郎`, so no script- or category-level rule
+  // can reject them without also rejecting every real Chinese, Japanese and
+  // Korean name. They are therefore subtracted from the allowlist by an explicit
+  // code-point denylist at generation time. This block is the regression guard,
+  // and asserts the division of labour: the denylist covers ONLY what the
+  // intersection cannot.
+  describe('display-name denylist — letters that function as symbols', () => {
+    // The glyphs below are visually confusable with each other and with ordinary
+    // ideographs, so pin them to their code points before relying on them.
+    it('the fixtures below really are U+5350 and U+534D', () => {
+      expect('卐'.codePointAt(0)).toBe(0x5350);
+      expect('卍'.codePointAt(0)).toBe(0x534d);
+    });
+
+    it.each([
+      ['卐', 'U+5350 right-facing swastika (GC=Lo, scx=Han)'],
+      ['卍', 'U+534D left-facing swastika (GC=Lo, scx=Han)'],
+      ['卐 Glowniggers 卐', 'the production display name that motivated the denylist'],
+      ['卍 卐', 'both, alone'],
+      ['山田卍太郎', 'embedded mid-name, between real Han letters'],
+    ])('rejects %p (%s)', (name) => {
+      expect(isValidDisplayName(name)).toBe(false);
+    });
+
+    // The whole point of a per-code-point denylist instead of a script rule.
+    it.each([
+      ['山田太郎', 'Han (Japanese)'],
+      ['김철수', 'Hangul (Korean)'],
+      ['王小明', 'Han (Chinese)'],
+      ['田中\u{20000}', 'Han incl. astral CJK Extension B'],
+      // The four immediate neighbours of the denied pair: the subtraction must
+      // punch out exactly two code points, not a range around them.
+      ['卌', 'U+534C, immediately below U+534D'],
+      ['华', 'U+534E, immediately above U+534D (as in 中华)'],
+      ['协', 'U+534F, immediately below U+5350'],
+      ['卑', 'U+5351, immediately above U+5350'],
+    ])('still accepts %p (%s)', (name) => {
+      expect(isValidDisplayName(name)).toBe(true);
+    });
+
+    // Enumerate what is ACTUALLY denied from the generated class rather than
+    // trusting the literals above, so a future entry that is added to the list
+    // but not enforced by the emitted allowlist fails here.
+    const denied = new RegExp(`[${DISPLAY_NAME_DENIED_SYMBOL_LETTERS_RANGES}]`, 'u');
+    const deniedCodePoints: number[] = [];
+    for (let cp = 0; cp <= 0x10ffff; cp++) {
+      if (cp >= 0xd800 && cp <= 0xdfff) continue; // lone surrogates
+      if (denied.test(String.fromCodePoint(cp))) deniedCodePoints.push(cp);
+    }
+
+    it('denies exactly the two swastika ideographs', () => {
+      expect(deniedCodePoints).toEqual([0x534d, 0x5350]);
+    });
+
+    it('rejects every code point on the denylist', () => {
+      const accepted = deniedCodePoints.filter((cp) =>
+        isValidDisplayName(String.fromCodePoint(cp))
+      );
+      expect(
+        accepted.map((cp) => `U+${cp.toString(16).toUpperCase().padStart(4, '0')}`)
+      ).toEqual([]);
+      // Vacuity floor: an empty denylist would satisfy the assertion above while
+      // enforcing nothing.
+      expect(deniedCodePoints.length).toBeGreaterThanOrEqual(2);
+    });
+
+    // Hermes safety for the new class (see the property-escape block above).
+    it('the denylist ranges contain NO Unicode property escape', () => {
+      expect(/\\[pP]\{/.test(DISPLAY_NAME_DENIED_SYMBOL_LETTERS_RANGES)).toBe(false);
+      expect(() => new RegExp(`[${DISPLAY_NAME_DENIED_SYMBOL_LETTERS_RANGES}]`, 'u')).not.toThrow();
+    });
+
+    // Division of labour: the Tibetan svasti signs look like the entries above
+    // but are GC=So, so the `scripts ∩ General_Category L` intersection already
+    // excludes them. They are rejected — and deliberately NOT on the denylist,
+    // where they would be dead weight that reads as load-bearing. The generator
+    // fails the build if such a redundant entry is added.
+    it.each([
+      ['࿕', 'U+0FD5 RIGHT-FACING SVASTI SIGN'],
+      ['࿖', 'U+0FD6 LEFT-FACING SVASTI SIGN'],
+      ['࿗', 'U+0FD7 RIGHT-FACING SVASTI SIGN WITH DOTS'],
+      ['࿘', 'U+0FD8 LEFT-FACING SVASTI SIGN WITH DOTS'],
+    ])('rejects %p (%s) via the intersection, not the denylist', (ch) => {
+      expect(isValidDisplayName(ch)).toBe(false);
+      expect(denied.test(ch)).toBe(false);
+    });
+  });
+
+  // Four punctuation code points JOIN two letters inside one real name. All are
+  // General_Category P, so `scripts ∩ L` strips them by default and stripping
+  // SPLITS the name (`Codeur·euses` → `Codeur euses`). They are re-admitted, but
+  // ONLY between two letters — the same characters are also used as ornament
+  // (a trailing `Roberto ·`), which must keep being trimmed. The conditional is
+  // the whole rule, so it is tested from both sides.
+  describe('display-name name separators — allowed only between letters', () => {
+    // Visually confusable with each other and with ASCII punctuation.
+    it('the fixtures below really are U+00B7 U+05BE U+0F0B U+30FB', () => {
+      expect('·'.codePointAt(0)).toBe(0x00b7);
+      expect('־'.codePointAt(0)).toBe(0x05be);
+      expect('་'.codePointAt(0)).toBe(0x0f0b);
+      expect('・'.codePointAt(0)).toBe(0x30fb);
+    });
+
+    it.each([
+      ['Codeur·euses en Liberté', 'U+00B7 French inclusive writing (production value)'],
+      ['Codeur·euses', 'U+00B7 bare'],
+      ['Pouet·te', 'U+00B7 short form'],
+      ['お坐・エガード', 'U+30FB Japanese name separator (production value)'],
+      ['אייר אברמסקי־קרוננברג', 'U+05BE Hebrew maqaf compound surname (production value)'],
+      ['འོད་ཟེར', 'U+0F0B Tibetan intersyllabic tsheg (production value)'],
+    ])('accepts letter-flanked %p (%s)', (name) => {
+      expect(isValidDisplayName(name)).toBe(true);
+    });
+
+    // A base letter can carry a combining mark, and that mark sits between the
+    // letter and the separator. If the flanking test only looked for a letter,
+    // these would be misread as unflanked and the separator stripped. Both
+    // fixtures use marks that do NOT recompose under NFC, so the mark really
+    // reaches the flanking test instead of being folded into a precomposed
+    // letter — the Tibetan one is the ordinary shape of Tibetan text.
+    it.each([
+      ['ཀི་ཁ', 'Tibetan letter + vowel sign U+0F72 + tsheg + letter'],
+      ['مُ·م', 'Arabic letter + damma U+064F + middle dot + letter'],
+    ])('accepts %p where a combining mark precedes the separator (%s)', (name) => {
+      expect(isValidDisplayName(name)).toBe(true);
+    });
+
+    it.each([
+      ['Roberto ·', 'trailing ornament (production value)'],
+      ['Michał rysiek Woźniak ·', 'trailing ornament (production value)'],
+      ['·Roberto', 'leading'],
+      ['a··b', 'doubled — neither is letter-flanked on both sides'],
+      ['·', 'alone'],
+      ['お坐・', 'trailing katakana middle dot'],
+      ['・エガード', 'leading katakana middle dot'],
+      ['a ·b', 'space on the left'],
+      ['a· b', 'space on the right'],
+    ])('rejects unflanked %p (%s)', (name) => {
+      expect(isValidDisplayName(name)).toBe(false);
+    });
+
+    // Enumerate what is ACTUALLY admitted from the generated class rather than
+    // trusting the literals above, and exercise both sides of the rule for each.
+    const separator = new RegExp(`[${DISPLAY_NAME_NAME_SEPARATORS_RANGES}]`, 'u');
+    const separatorCodePoints: number[] = [];
+    for (let cp = 0; cp <= 0x10ffff; cp++) {
+      if (cp >= 0xd800 && cp <= 0xdfff) continue; // lone surrogates
+      if (separator.test(String.fromCodePoint(cp))) separatorCodePoints.push(cp);
+    }
+
+    it('admits exactly the four name separators', () => {
+      expect(separatorCodePoints).toEqual([0x00b7, 0x05be, 0x0f0b, 0x30fb]);
+    });
+
+    it('every separator is valid between letters and invalid unflanked', () => {
+      const wrongWhenFlanked: string[] = [];
+      const wrongWhenUnflanked: string[] = [];
+      for (const cp of separatorCodePoints) {
+        const ch = String.fromCodePoint(cp);
+        const label = `U+${cp.toString(16).toUpperCase().padStart(4, '0')}`;
+        if (!isValidDisplayName(`a${ch}b`)) wrongWhenFlanked.push(label);
+        if (isValidDisplayName(`a ${ch}`)) wrongWhenUnflanked.push(label);
+      }
+      expect({ wrongWhenFlanked, wrongWhenUnflanked }).toEqual({
+        wrongWhenFlanked: [],
+        wrongWhenUnflanked: [],
+      });
+      // Vacuity floor: an empty separator class would satisfy both loops above.
+      expect(separatorCodePoints.length).toBe(4);
+    });
+
+    // The ASCII hyphen decision is untouched: U+05BE is General_Category Pd like
+    // U+002D, but admitting one says nothing about the other.
+    it('does not admit the ASCII hyphen', () => {
+      expect(separator.test('-')).toBe(false);
+      expect(isValidDisplayName('Jean-Luc')).toBe(false);
+      expect(isValidDisplayName('a-b')).toBe(false);
+    });
+
+    // Hermes safety for the new pattern (see the property-escape block above).
+    it('the unflanked-separator source contains NO Unicode property escape', () => {
+      expect(/\\[pP]\{/.test(DISPLAY_NAME_UNFLANKED_SEPARATOR_SOURCE)).toBe(false);
+      expect(/\\[pP]\{/.test(DISPLAY_NAME_NAME_SEPARATORS_RANGES)).toBe(false);
+      expect(() => new RegExp(DISPLAY_NAME_UNFLANKED_SEPARATOR_SOURCE, 'u')).not.toThrow();
+      // Global variant is what @oxyhq/api compiles for the strip path.
+      expect(() => new RegExp(DISPLAY_NAME_UNFLANKED_SEPARATOR_SOURCE, 'gu')).not.toThrow();
+    });
+
+    // Nothing the policy already rejected may become valid.
+    it.each([
+      ['卐', 'denied symbol letter'],
+      ['卍', 'denied symbol letter'],
+      ['Agent007', 'digit'],
+      ['J.R.', 'dot'],
+      ['ᯅ', 'non-allowlisted script'],
+      ['nixCraft \u{1f427}', 'emoji'],
+    ])('still rejects %p (%s)', (name) => {
+      expect(isValidDisplayName(name)).toBe(false);
+    });
+
+    it.each([
+      ['山田太郎', 'Han'],
+      ['김철수', 'Hangul'],
+      ["Renée O'Brien", 'Latin with accent + apostrophe'],
+    ])('still accepts %p (%s)', (name) => {
+      expect(isValidDisplayName(name)).toBe(true);
+    });
+  });
+
   describe('isValidUUID', () => {
     it('should return true for valid UUIDs', () => {
       expect(isValidUUID('123e4567-e89b-12d3-a456-426614174000')).toBe(true);