@serfab/cadre-core 1.6.0 → 1.8.0

package/src/seed-bootstrap.ts

@@ -4,8 +4,9 @@ import { digest, sign, verify, getPublicKey } from '@optimystic/quereus-plugin-c
 import type { Libp2p, Connection } from '@libp2p/interface';
 import { multiaddr, type Multiaddr } from '@multiformats/multiaddr';
 import { peerIdFromString } from '@libp2p/peer-id';
-import { type ControlStream, writeFrame, withDeadline, exchangeFrame, readStreamToEnd } from './control-stream.js';
-import { dialPeerAddrs, DEFAULT_PEER_DIAL_BUDGET, type PeerDialBudget } from './peer-dial.js';
+import { type ControlStream, withDeadline, exchangeFrame, readStreamToEnd, replyAndClose } from './control-stream.js';
+import { dialPeerAddrs, SelfRelayOnlyError, DEFAULT_PEER_DIAL_BUDGET, type PeerDialBudget } from './peer-dial.js';
+import { relayedRequestBudgetMs } from './link-budget.js';
 import type {
   ControlNetworkSeed,
   SeedPeer,
@@ -42,15 +43,16 @@ export const SEED_PROTOCOL = '/sereus/seed/1.0.0';
 /** Maximum seed message size (1MB) */
 const MAX_SEED_SIZE = 1024 * 1024;
 
-/** Default time the receiver waits for an inbound seed frame before aborting (ms). */
+/**
+ * Default time the receiver waits for an inbound seed frame before aborting (ms). It covers the
+ * read only: the trust decision and the peer-store merge run after it.
+ */
+// eslint-disable-next-line no-restricted-syntax -- link-independent: a receiver cap on one seed frame on a stream the peer already opened; it bounds a peer that opens a stream and never sends, not the dial
 const DEFAULT_SEED_READ_TIMEOUT_MS = 10_000;
 
 /** Default cap on concurrent inbound seed streams a single peer can pin open. */
 const DEFAULT_MAX_CONCURRENT_SEEDS = 100;
 
-/** Default time the sender waits for a seed delivery (dial + ack read) before aborting (ms). */
-const DEFAULT_SEED_DELIVER_TIMEOUT_MS = 10_000;
-
 /**
  * Decode a 4-byte big-endian length-prefixed frame; returns the body bytes.
  *
@@ -122,6 +124,9 @@ function seedRejected(error: string): ApplySeedResult {
   return { success: false, peersAdded: 0, error, ownerDialsAttempted: 0, ownerDialsFailed: 0 };
 }
 
+/** What dialing a seed's owner peers produced — the owner-dial half of an {@link ApplySeedResult}. */
+type OwnerDialCounts = Pick<ApplySeedResult, 'ownerDialsAttempted' | 'ownerDialsFailed'>;
+
 /**
  * Parse each address, dropping (and logging) any that is malformed, so one bad
  * entry cannot keep a peer's valid addresses from being dialed.
@@ -192,13 +197,28 @@ export interface SeedBootstrapConfig {
    * returned without applying any seed.
    */
   maxConcurrentSeeds?: number;
+  /**
+   * The host's declared link round trip (`NetworkConfig.linkRoundTripMs`), from which
+   * {@link seedDeliverTimeoutMs}'s default is derived. Unset means the declared default.
+   */
+  linkRoundTripMs?: number;
   /**
    * Time {@link SeedBootstrapService.deliverSeed} waits for the whole exchange —
-   * dial, write, ack read — before aborting (ms). Defaults to
-   * {@link DEFAULT_SEED_DELIVER_TIMEOUT_MS}. Bounds the SENDER against a seed
+   * dial, write, ack read — before aborting (ms). Bounds the SENDER against a seed
    * target that accepts the stream and then never replies; the target is a
    * not-yet-trusted node during onboarding, so this is the more exposed
    * direction than the receiver knobs above.
+   *
+   * Defaults to `relayedRequestBudgetMs(linkRoundTripMs)` (`link-budget.ts`; 23 s at the
+   * default declaration): one dial that may need a relay, then one request and its answer.
+   * Delivery does not set `runOnLimitedConnection`, so it does not use a limited relayed
+   * connection today; the relayed-dial count is the upper bound on the dial it can use, the
+   * same choice `CadreNode.controlDialBudget` makes for every address. It holds only link work
+   * because the receiver acks before its owner dials.
+   *
+   * NOTE: no transfer allowance — a seed is a peer list of a few KB, and `MAX_SEED_SIZE` (1 MiB)
+   * is a defensive cap. If seeds ever grow toward that cap, add an allowance the way
+   * `PUSH_TRANSFER_ALLOWANCE_MS` does.
    */
   seedDeliverTimeoutMs?: number;
   /**
@@ -256,7 +276,7 @@ export class SeedBootstrapService {
     this.trustPolicy = config.trustPolicy ?? anchoredTrustPolicy();
     this.seedReadTimeoutMs = config.seedReadTimeoutMs ?? DEFAULT_SEED_READ_TIMEOUT_MS;
     this.maxConcurrentSeeds = config.maxConcurrentSeeds ?? DEFAULT_MAX_CONCURRENT_SEEDS;
-    this.seedDeliverTimeoutMs = config.seedDeliverTimeoutMs ?? DEFAULT_SEED_DELIVER_TIMEOUT_MS;
+    this.seedDeliverTimeoutMs = config.seedDeliverTimeoutMs ?? relayedRequestBudgetMs(config.linkRoundTripMs);
     this.dialBudget = config.dialBudget ?? DEFAULT_PEER_DIAL_BUDGET;
 
     // Derive public key from private key if not provided
@@ -305,20 +325,23 @@ export class SeedBootstrapService {
    * `controlDatabase` for dialing and known-key lookup, and must NOT bind a
    * discarded closure to the shared node (a handler leak, and a second
    * `handle()` of the same protocol throws `DuplicateProtocolHandlerError`).
+   *
+   * Rejects when libp2p refuses the registration; the node and database are
+   * kept only once the handler is in place, so a failed service holds nothing
+   * for {@link shutdown} to unhandle.
    */
-  initialize(
+  async initialize(
     libp2pNode: Libp2p,
     controlDatabase: ControlDatabase,
     options?: { registerHandler?: boolean }
-  ): void {
-    this.libp2pNode = libp2pNode;
-    this.controlDatabase = controlDatabase;
-
+  ): Promise<void> {
     // Register the seed protocol handler unless the caller opted out (temp services).
     if (options?.registerHandler ?? true) {
-      this.registerProtocolHandler();
+      await this.registerProtocolHandler(libp2pNode);
     }
 
+    this.libp2pNode = libp2pNode;
+    this.controlDatabase = controlDatabase;
     log('SeedBootstrapService initialized');
   }
 
@@ -738,6 +761,22 @@ export class SeedBootstrapService {
   async applySeed(
     seed: ControlNetworkSeed,
     options?: { trustPolicy?: SeedTrustPolicy }
+  ): Promise<ApplySeedResult> {
+    const merged = await this.verifyAndMergeSeed(seed, options);
+    if (!merged.success) {
+      return merged;
+    }
+    return { ...merged, ...await this.dialSeedOwners(seed) };
+  }
+
+  /**
+   * The first half of {@link applySeed}: check the signature and the signer's trust, then merge
+   * the seed's peer addresses into the peer store. Every rejection happens here, so this result is
+   * what the inbound handler acks with; the owner dials that follow cannot change it.
+   */
+  private async verifyAndMergeSeed(
+    seed: ControlNetworkSeed,
+    options?: { trustPolicy?: SeedTrustPolicy }
   ): Promise<ApplySeedResult> {
     if (!this.libp2pNode) {
       return seedRejected('Service not initialized');
@@ -796,12 +835,28 @@ export class SeedBootstrapService {
       }
     }
 
-    // Dial owner peers to establish connections. Best-effort and COUNTED: an
-    // owner that is momentarily down leaves this node seeded but unconnected,
-    // which the caller can only see if the outcome is reported (see
-    // `ApplySeedResult.ownerDialsFailed`). Recovery is not this loop's job —
-    // `CadreNode.dialColdStartBootstrap` retries these same addresses on every
-    // control-cohort reconcile pass until the control database has siblings.
+    log('Merged seed: %d peers added', peersAdded);
+    return { success: true, peersAdded, ownerDialsAttempted: 0, ownerDialsFailed: 0 };
+  }
+
+  /**
+   * The second half of {@link applySeed}: dial the seed's owner peers to establish connections.
+   *
+   * Best-effort and COUNTED: an owner that is momentarily down leaves this node seeded but
+   * unconnected, which the caller can only see if the outcome is reported (see
+   * `ApplySeedResult.ownerDialsFailed`). Recovery is not this loop's job —
+   * `CadreNode.dialColdStartBootstrap` retries these same addresses on every control-cohort
+   * reconcile pass until the control database has siblings.
+   *
+   * The inbound handler runs this AFTER it has acked and closed the stream
+   * ({@link handleSeedStream}), because an unreachable owner can take `dialBudget.totalMs`.
+   */
+  private async dialSeedOwners(seed: ControlNetworkSeed): Promise<OwnerDialCounts> {
+    const node = this.libp2pNode;
+    if (!node) {
+      log('Seed service shut down before its owner dials; none attempted');
+      return { ownerDialsAttempted: 0, ownerDialsFailed: 0 };
+    }
     // `createSeed` projects every non-revoked CadrePeer row, so an owner applying
     // a seed minted after it joined finds ITSELF in the owner list. Dialing self always
     // throws, which would report a healthy owner as "seeded but stranded".
@@ -810,12 +865,7 @@ export class SeedBootstrapService {
     // Every one of an owner's addresses is a candidate, each on its own time limit
     // (`dialPeerAddrs`), so an owner whose first address never answers neither
     // stalls seed application nor goes undialed at its other addresses.
-    // NOTE: `handleSeedStream` acks only after this loop, so an unreachable owner
-    // can hold the ack for up to `dialBudget.totalMs` each — 56 s at the default declared link
-    // round trip, more on a host that declared a slower one (`link-budget.ts`) — past a sender's
-    // 10 s `seedDeliverTimeoutMs`; the seed is still applied. If senders start
-    // reporting accepted seeds as timed out, ack before dialing.
-    const selfPeerId = this.libp2pNode.peerId?.toString();
+    const selfPeerId = node.peerId?.toString();
     let ownerDialsAttempted = 0;
     let ownerDialsFailed = 0;
     for (const peer of seed.peers.filter(p => p.isOwner)) {
@@ -827,17 +877,22 @@ export class SeedBootstrapService {
         const addrs = parseDialAddrs(peer.multiaddrs);
 
         log('Dialing owner peer: %s (%d addr(s))', peer.peerId, addrs.length);
-        await dialPeerAddrs(this.libp2pNode, addrs, this.dialBudget, `Owner dial of ${peer.peerId}`);
+        await dialPeerAddrs(node, addrs, this.dialBudget, `Owner dial of ${peer.peerId}`);
       } catch (error) {
+        // Counted even when the owner reaches us only through our own relay: this node is still
+        // not connected to it, and `ownerDialsFailed` is how the caller learns that.
         ownerDialsFailed++;
-        log('Failed to dial peer %s: %o', peer.peerId, error);
+        if (error instanceof SelfRelayOnlyError) {
+          log('Owner peer %s is reachable only by relaying through this node; waiting for it to reconnect', peer.peerId);
+        } else {
+          log('Failed to dial peer %s: %o', peer.peerId, error);
+        }
         // Continue - not all peers need to be reachable
       }
     }
 
-    log('Applied seed: %d peers added, %d/%d owner dial(s) failed',
-      peersAdded, ownerDialsFailed, ownerDialsAttempted);
-    return { success: true, peersAdded, ownerDialsAttempted, ownerDialsFailed };
+    log('Dialed seed owners: %d/%d owner dial(s) failed', ownerDialsFailed, ownerDialsAttempted);
+    return { ownerDialsAttempted, ownerDialsFailed };
   }
 
   /**
@@ -1069,10 +1124,8 @@ export class SeedBootstrapService {
    * {@link handleSeedStream} — extracted as a method so it has a unit-test seam
    * (mirroring wake's `handleStream`) the inline closure never had.
    */
-  private registerProtocolHandler(): void {
-    if (!this.libp2pNode) return;
-
-    void this.libp2pNode.handle(SEED_PROTOCOL, async (rawStream: unknown, rawConnection: unknown) => {
+  private async registerProtocolHandler(libp2pNode: Libp2p): Promise<void> {
+    await libp2pNode.handle(SEED_PROTOCOL, async (rawStream: unknown, rawConnection: unknown) => {
       const remotePeerId = (rawConnection as Connection).remotePeer.toString();
       await this.handleSeedStream(rawStream as ControlStream, remotePeerId);
     });
@@ -1081,92 +1134,81 @@ export class SeedBootstrapService {
   }
 
   /**
-   * Read one inbound seed frame, apply it, and write the ack.
+   * Read one inbound seed frame, verify and merge it, write the ack and close the
+   * stream, then dial the seed's owners.
+   *
+   * The ack and the close come BEFORE the owner dials: an unreachable owner can hold
+   * a dial for `dialBudget.totalMs` (64 s at the default declared link), which is not
+   * link time and does not belong inside the sender's delivery deadline. The close is
+   * what releases the sender, which reads the ack to end-of-stream. The stream stays
+   * counted in {@link activeStreams} through the dials, so {@link maxConcurrentSeeds}
+   * still bounds concurrent owner-dial phases.
    *
    * Hardened against a buggy/compromised own-cadre node: a concurrency cap (over
    * {@link maxConcurrentSeeds}, reply without applying), a read timeout (a peer
    * that never half-closes is aborted inside `readStreamToEnd`), and the existing
    * malformed/oversized-frame guard — all reported as a non-accepting
    * {@link SeedAckMessage} rather than a dropped/hung stream.
+   *
+   * NOTE: a receiver configured with an interactive trust-on-first-use policy asks a
+   * human before acking, and that wait sits inside the sender's delivery deadline. If
+   * TOFU is ever used on this wire path, ack "pending" or move the confirmation out of
+   * the exchange.
    */
   private async handleSeedStream(stream: ControlStream, remotePeerId: string): Promise<void> {
     log('Incoming seed delivery from: %s', remotePeerId);
 
     if (this.activeStreams >= this.maxConcurrentSeeds) {
       log('Rejecting seed from %s: %d concurrent streams at cap %d', remotePeerId, this.activeStreams, this.maxConcurrentSeeds);
-      const ack: SeedAckMessage = { accepted: false, reason: 'Too many concurrent seed deliveries' };
-      try {
-        writeFrame(stream, ack);
-      } catch {
-        // Ignore send errors on the reject path.
-      }
-      try {
-        await stream.close();
-      } catch {
-        // Ignore close errors.
-      }
+      await replyAndClose(stream, { accepted: false, reason: 'Too many concurrent seed deliveries' } satisfies SeedAckMessage, 'Seed');
       return;
     }
 
     this.activeStreams++;
+    let acked = false;
     try {
-      // Read the seed frame to EOF (bounded + size-capped), then decode it.
-      const data = await readStreamToEnd(stream, {
-        maxBytes: MAX_SEED_SIZE,
-        timeoutMs: this.seedReadTimeoutMs,
-        label: 'Seed',
-      });
-
-      const messageBody = decodeLengthPrefixedFrame(data);
-      const messageJson = new TextDecoder().decode(messageBody);
-      const message = JSON.parse(messageJson) as SeedMessage;
-
-      // Emit seed received event
-      this.eventCallbacks.onSeedReceived?.(message.partyId, remotePeerId);
-
-      // Convert to seed and apply
-      const seed: ControlNetworkSeed = {
-        partyId: message.partyId,
-        peers: message.peers,
-        signature: message.signature,
-        signerKey: message.signerKey,
-      };
+      const seed = await this.readSeedFrame(stream);
+      this.eventCallbacks.onSeedReceived?.(seed.partyId, remotePeerId);
 
-      const result = await this.applySeed(seed);
+      const merged = await this.verifyAndMergeSeed(seed);
+      acked = true;
+      await replyAndClose(stream, { accepted: merged.success, reason: merged.error } satisfies SeedAckMessage, 'Seed');
 
-      // Emit appropriate event based on result
-      if (result.success) {
-        this.eventCallbacks.onSeedApplied?.(seed.partyId, result.peersAdded, seed);
+      if (merged.success) {
+        await this.dialSeedOwners(seed);
+        this.eventCallbacks.onSeedApplied?.(seed.partyId, merged.peersAdded, seed);
       } else {
-        this.eventCallbacks.onSeedError?.(seed.partyId, result.error ?? 'Unknown error');
+        this.eventCallbacks.onSeedError?.(seed.partyId, merged.error ?? 'Unknown error');
       }
-
-      const ack: SeedAckMessage = { accepted: result.success, reason: result.error };
-      writeFrame(stream, ack);
     } catch (error) {
       log('Error handling seed delivery: %o', error);
       const errorMessage = error instanceof Error ? error.message : 'Unknown error';
-
-      // Emit error event
       this.eventCallbacks.onSeedError?.(this.config.partyId, errorMessage);
-
-      // Send error acknowledgment (best-effort on the still-open write side).
-      const ack: SeedAckMessage = { accepted: false, reason: errorMessage };
-      try {
-        writeFrame(stream, ack);
-      } catch {
-        // Ignore send errors
+      // Once acked the stream is closed, so a later failure has no reply to make.
+      if (!acked) {
+        await replyAndClose(stream, { accepted: false, reason: errorMessage } satisfies SeedAckMessage, 'Seed');
       }
     } finally {
       this.activeStreams--;
-      try {
-        await stream.close();
-      } catch {
-        // Ignore close errors.
-      }
     }
   }
 
+  /** Read the inbound seed frame to EOF (bounded and size-capped) and decode it. */
+  private async readSeedFrame(stream: ControlStream): Promise<ControlNetworkSeed> {
+    const data = await readStreamToEnd(stream, {
+      maxBytes: MAX_SEED_SIZE,
+      timeoutMs: this.seedReadTimeoutMs,
+      label: 'Seed',
+    });
+    const message = JSON.parse(new TextDecoder().decode(decodeLengthPrefixedFrame(data))) as SeedMessage;
+    return {
+      partyId: message.partyId,
+      peers: message.peers,
+      signature: message.signature,
+      signerKey: message.signerKey,
+    };
+  }
+
   /**
    * Shutdown the service.
    */

package/src/storage-scope.ts

@@ -18,18 +18,26 @@
  * its shape, and the React Native reference app lets a user type one into Settings.
  * Scope keys reach real namespaces unescaped: cadre-cli builds `${config.path}/${scope}`,
  * React Native a LevelDB filename, the browser an IndexedDB database name. A party id
- * containing `/` or `..` would escape the CLI's storage directory. Base64url keeps every
- * key inside `[A-Za-z0-9._-]` — the charset embedders already rely on, and the same
- * encoding the React Native app's `secureStoreKeySegment` uses on a party id for the
- * same reason.
+ * containing `/` or `..` would escape the CLI's storage directory. Lowercase hex keeps
+ * every key inside `[a-z0-9._-]`, the charset embedders rely on.
+ *
+ * WHY THE CHARSET HAS NO UPPERCASE. Windows (NTFS) and macOS (APFS/HFS+ by default)
+ * compare file names without regard to case, while everything above the filesystem
+ * compares with it. Two keys differing only in case — `control-YWFA` and `control-YWFa`,
+ * the base64url keys of party ids `aa@` and `aaZ`, or strand ids `strand-ABC` and
+ * `strand-abc` — would be two stores in memory and one folder on disk. With no uppercase
+ * letter in the charset, two different keys are two different names on every
+ * filesystem.
  *
  * THE STRAND ARM OF THAT CHARSET RULE IS ENFORCED HERE. A strand's scope key is
  * `StrandRow.Id`, and a strand row replicated into the control database by another
  * node in the party carries whatever id THAT node wrote. `assertStrandScopeKey`
  * (below) is the check that makes the charset true of strand keys too; it runs
  * unconditionally at the top of `StrandInstanceManager.startStrand`, so no strand id
- * reaches an embedder's provider — or a libp2p protocol prefix — unvalidated. Ids
- * cadre-core mints come from `strand-id.ts`, which is built on the same predicate.
+ * reaches an embedder's provider — or a libp2p protocol prefix — unvalidated. A
+ * mixed-case id is refused, not lowercased: lowercasing would silently merge two
+ * distinct strands into one store. Ids cadre-core mints come from `strand-id.ts`, which
+ * is built on the same predicate.
  */
 
 import { toString as uint8ArrayToString, fromString as uint8ArrayFromString } from 'uint8arrays';
@@ -45,23 +53,29 @@ const CONTROL_SCOPE_PREFIX = 'control-';
 /**
  * The storage scope key for a party's control database.
  *
- * Returns `control-` followed by the base64url encoding of `partyId`'s UTF-8 bytes,
- * so the whole key stays within `[A-Za-z0-9._-]` and is safe to use directly as a
- * file name, directory name or database name. See the module comment for why the
- * encoding is load-bearing rather than decorative.
+ * Returns `control-` followed by the lowercase hexadecimal encoding of `partyId`'s
+ * UTF-8 bytes, so the whole key stays within `[a-z0-9._-]` and is safe to use directly
+ * as a file name, directory name or database name — and two party ids give two names
+ * even on a filesystem that ignores case. See the module comment for why the encoding
+ * is load-bearing rather than decorative.
  *
  * To read a party id back off a device — from, say, a LevelDB file named
- * `sereus-control-MTExMTExMTEtMjIyMi00MzMzLTg0NDQtNTU1NTU1NTU1NTU1` — in a browser or
- * Node console, with no dependency on this package:
+ * `sereus-control-7061727479` — in a browser or Node console, with no dependency on
+ * this package:
  * ```js
- * const b64 = key.slice('control-'.length).replace(/-/g, '+').replace(/_/g, '/');
- * new TextDecoder().decode(Uint8Array.from(atob(b64), (c) => c.charCodeAt(0)))
+ * const hex = key.slice(key.indexOf('control-') + 'control-'.length);
+ * new TextDecoder().decode(Uint8Array.from(hex.match(/../g) ?? [], (h) => parseInt(h, 16)))
  * ```
- * The `TextDecoder` step is not optional: `atob` alone yields one character per BYTE,
- * so a party id with any non-ASCII character in it decodes to mojibake.
+ * The `TextDecoder` step is not optional: each hex pair is one BYTE, so a party id with
+ * any non-ASCII character in it decodes to mojibake without it.
+ *
+ * NOTE: the key is twice the party id's UTF-8 byte length plus 8, so a party id over
+ * ~120 bytes overflows the 255-byte limit filesystems put on one path component. Party
+ * ids today are UUIDs (an 80-character key); if long party ids ever appear, hash the
+ * party id rather than encoding it.
  */
 export function controlStorageScope(partyId: string): string {
-	return CONTROL_SCOPE_PREFIX + uint8ArrayToString(uint8ArrayFromString(partyId, 'utf8'), 'base64url');
+	return CONTROL_SCOPE_PREFIX + uint8ArrayToString(uint8ArrayFromString(partyId, 'utf8'), 'base16');
 }
 
 /**
@@ -86,8 +100,11 @@ export function isControlStorageScope(scope: string): boolean {
  */
 const MAX_STRAND_SCOPE_KEY_LENGTH = 128;
 
-/** The charset every scope key stays within — see the module comment. */
-const SCOPE_KEY_CHARSET = /^[A-Za-z0-9._-]+$/;
+/**
+ * The charset every scope key stays within — see the module comment. Lowercase only,
+ * so keys that differ as strings also differ as names on a filesystem that ignores case.
+ */
+const SCOPE_KEY_CHARSET = /^[a-z0-9._-]+$/;
 
 /**
  * Whether a strand id is usable as a storage scope key and as a libp2p network name.
@@ -100,7 +117,9 @@ const SCOPE_KEY_CHARSET = /^[A-Za-z0-9._-]+$/;
  *
  * Valid means all of:
  * - non-empty, and at most {@link MAX_STRAND_SCOPE_KEY_LENGTH} characters;
- * - within `[A-Za-z0-9._-]`, so no separator, drive letter, NUL or non-ASCII text;
+ * - within `[a-z0-9._-]`, so no separator, drive letter, NUL or non-ASCII text, and no
+ *   uppercase letter, so no two valid ids name one folder on a filesystem that ignores
+ *   case;
  * - not `.` or `..`, which the charset admits but every filesystem reads as a
  *   directory rather than a name;
  * - not `control-`-prefixed, which would let a strand's store masquerade as a
@@ -128,7 +147,8 @@ export class InvalidStrandIdError extends Error {
 	constructor(strandId: string) {
 		super(
 			`Strand id ${JSON.stringify(strandId)} cannot be used as a storage scope key: ` +
-			`a strand id must be 1-${MAX_STRAND_SCOPE_KEY_LENGTH} characters within [A-Za-z0-9._-], ` +
+			`a strand id must be 1-${MAX_STRAND_SCOPE_KEY_LENGTH} characters within [a-z0-9._-] ` +
+			'(lowercase only, because Windows and macOS file names ignore case), ' +
 			"must not be '.' or '..', and must not begin 'control-'. " +
 			'This strand was created by a node that does not mint conforming ids; it cannot be ' +
 			'started here, because the id becomes a file, directory or database name.'
@@ -156,8 +176,9 @@ export function assertStrandScopeKey(strandId: string): void {
 export function assertScopeKeyCharset(scope: string): void {
 	if (!SCOPE_KEY_CHARSET.test(scope)) {
 		throw new Error(
-			`Storage scope key ${JSON.stringify(scope)} leaves the [A-Za-z0-9._-] charset ` +
-			'embedders rely on to use it directly as a file, directory or database name.'
+			`Storage scope key ${JSON.stringify(scope)} leaves the [a-z0-9._-] charset ` +
+			'embedders rely on to use it directly as a file, directory or database name ' +
+			'(lowercase only, so two keys never share one name on a filesystem that ignores case).'
 		);
 	}
 }