@dxos/keys 0.10.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/keys",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "description": "Key utils and definitions.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -27,9 +27,9 @@
   ],
   "dependencies": {
     "ulidx": "^2.3.0",
-    "@dxos/debug": "0.10.0",
-    "@dxos/node-std": "0.10.0",
-    "@dxos/invariant": "0.10.0"
+    "@dxos/debug": "0.11.0",
+    "@dxos/invariant": "0.11.0",
+    "@dxos/node-std": "0.11.0"
   },
   "devDependencies": {
     "base32-decode": "^1.0.0",

package/src/DXN.test.ts

@@ -45,6 +45,9 @@ describe('DXN.Name', () => {
       // No dots — single segment.
       // @ts-expect-error
       DXN.make('unknown');
+      // One dot — two segments, below the three-segment minimum.
+      // @ts-expect-error
+      DXN.make('a.b');
       // Hyphen in the FINAL segment.
       // @ts-expect-error
       DXN.make('com.example.type.registry-entry');

package/src/DXN.ts

@@ -31,30 +31,52 @@ const DXN_SPEC_REGEXP =
 export type DXN = URI.URI & { readonly __DXN: unique symbol };
 
 /**
- * Compile-time validation for NSID strings (the `dxn:` prefix is absent here).
- *
- * Checks two rules expressible with template literal types:
- * - Must contain at least one dot (multi-segment).
- * - Final segment (after the last dot) must not contain a hyphen.
+ * Recursive segment-chain check used by {@link Name}: hyphens are permitted in
+ * every segment except the truly final one.
  *
  * TypeScript template literal inference is non-greedy: `${string}.${infer Rest}`
  * always splits at the first dot. The type recurses until `Rest` has no more dots,
  * at which point it is the true final segment and is checked for hyphens.
+ */
+type ValidSegmentChain<T extends string> = T extends `${string}.${infer Rest}`
+  ? Rest extends `${string}.${string}`
+    ? [ValidSegmentChain<Rest>] extends [never]
+      ? never
+      : T
+    : Rest extends `${string}-${string}`
+      ? never
+      : T
+  : never;
+
+/**
+ * Compile-time validation for NSID strings (the `dxn:` prefix is absent here).
+ *
+ * Checks two rules expressible with template literal types:
+ * - Three-segment minimum (at least two dots) for names that are fully known at
+ *   compile time — matches the runtime grammar in {@link DXN_SPEC_REGEXP} and
+ *   `parse`.
+ * - Final segment (after the last dot) must not contain a hyphen.
  *
- * Broad `string` passes through unchanged so that template-literal call sites
- * whose prefix segment is `string` are not rejected — those are validated at
+ * The three-segment minimum only applies once `Head` (the portion before the
+ * first dot) resolves to a concrete literal, so a fully literal two-segment
+ * name like `a.b` is rejected. Template-literal call sites whose prefix is a
+ * runtime `string` (e.g. `` `${meta.key}.event` ``) can't be proven to have
+ * enough segments at compile time — `Head` there infers as `string` itself —
+ * so only the known final segment is checked; the rest is validated at
  * runtime by the regex inside `parse`.
  */
 export type Name<T extends string> = [string] extends [T]
   ? string
-  : T extends `${string}.${infer Rest}`
+  : T extends `${infer Head}.${infer Rest}`
     ? Rest extends `${string}.${string}`
-      ? [Name<Rest>] extends [never]
-        ? never
-        : T
-      : Rest extends `${string}-${string}`
+      ? [ValidSegmentChain<Rest>] extends [never]
         ? never
         : T
+      : [string] extends [Head]
+        ? Rest extends `${string}-${string}`
+          ? never
+          : T
+        : never
     : never;
 
 /**

package/src/EID.test.ts

@@ -18,7 +18,7 @@ describe('EID.make', () => {
   });
 
   test('produces local echo URI from objectId only', ({ expect }) => {
-    expect(EID.make({ entityId: OBJECT })).toBe(`echo:/${OBJECT}`);
+    expect(EID.make({ entityId: OBJECT })).toBe(`echo:///${OBJECT}`);
   });
 
   test('produces space-only echo URI from spaceId only', ({ expect }) => {
@@ -52,6 +52,11 @@ describe('EID.parse', () => {
   test('passes through canonical format unchanged', ({ expect }) => {
     const id = `echo://${SPACE}/${OBJECT}`;
     expect(EID.parse(id)).toBe(id);
+    expect(EID.parse(`echo:///${OBJECT}`)).toBe(`echo:///${OBJECT}`);
+  });
+
+  test('normalizes the legacy single-slash local form to triple-slash', ({ expect }) => {
+    expect(EID.parse(`echo:/${OBJECT}`)).toBe(`echo:///${OBJECT}`);
   });
 
   test('throws on invalid input', ({ expect }) => {
@@ -67,7 +72,7 @@ describe('EID.parse', () => {
 describe('EID.tryParse', () => {
   test('returns undefined on failure instead of throwing', ({ expect }) => {
     expect(EID.tryParse('not-a-uri')).toBeUndefined();
-    expect(EID.tryParse(`echo:/${OBJECT}`)).toBe(`echo:/${OBJECT}`);
+    expect(EID.tryParse(`echo:/${OBJECT}`)).toBe(`echo:///${OBJECT}`);
   });
 });
 
@@ -124,6 +129,10 @@ describe('EID.equals', () => {
     const b = EID.make({ spaceId: SPACE, entityId: OBJECT2 });
     expect(EID.equals(a, b)).toBe(false);
   });
+
+  test('treats the legacy single-slash and canonical triple-slash local forms as equal', ({ expect }) => {
+    expect(EID.equals(`echo:/${OBJECT}` as EID.EID, `echo:///${OBJECT}` as EID.EID)).toBe(true);
+  });
 });
 
 describe('EID.toLocal', () => {

package/src/EID.ts

@@ -10,25 +10,38 @@ import type { EntityId } from './entity-id';
 import type { SpaceId } from './space-id';
 import type * as URI from './URI';
 
-// Canonical-form regex covering all three EID shapes.
+// Canonical-form regex covering all accepted EID shapes.
 //   echo://<spaceId>/<objectId>
 //   echo://<spaceId>
-//   echo:/<objectId>      (local)
-//   echo:///<objectId>    (local, alt form)
+//   echo:///<objectId>    (local, canonical)
+//   echo:/<objectId>      (local, legacy — accepted on read, normalized to the canonical triple-slash form)
 const ECHO_URI_REGEXP = /^echo:(?:\/\/[^/]+(?:\/[^/]+)?|(?:\/\/\/|\/)[^/]+)$/;
 
 // Sub-patterns used for extraction.
 const QUALIFIED_RE = /^echo:\/\/([^/]+)\/([^/]+)$/;
 const SPACE_ONLY_RE = /^echo:\/\/([^/]+)$/;
 const LOCAL_RE = /^echo:(?:\/\/\/|\/)([^/]+)$/;
+// Legacy single-slash local form (`echo:/<objectId>`), distinguished from the canonical
+// triple-slash form so `parse` can normalize it. The negative lookahead rejects `echo://…`.
+const LOCAL_LEGACY_RE = /^echo:\/(?!\/)([^/]+)$/;
 
 /**
  * Addresses an ECHO object or space. Uses the `echo:` URI scheme.
  *
+ * Canonical forms:
+ * - `echo://<spaceId>/<objectId>` — fully-qualified object.
+ * - `echo://<spaceId>` — space.
+ * - `echo:///<objectId>` — local (space-less) object.
+ *
+ * @deprecated form: the single-slash local form `echo:/<objectId>` is retired in favour of the
+ * triple-slash `echo:///<objectId>` form. It is still accepted on read (and normalized by `parse`)
+ * so existing persisted data keeps resolving, but it is no longer produced — do not emit it in new
+ * code. Construct local EIDs with `make({ entityId })`.
+ *
  * @example
  * ```
  * echo://BA25QRC2FEWCSAMRP4RZL65LWJ7352CKE/01J00J9B45YHYSGZQTQMSKMGJ6
- * echo:/01J00J9B45YHYSGZQTQMSKMGJ6
+ * echo:///01J00J9B45YHYSGZQTQMSKMGJ6
  * echo://BA25QRC2FEWCSAMRP4RZL65LWJ7352CKE
  * ```
  */
@@ -40,13 +53,18 @@ export type EID = URI.URI & { readonly __EID: unique symbol };
 export const isEID = (value: unknown): value is EID => typeof value === 'string' && value.startsWith('echo:');
 
 /**
- * Parses a string to EID. Throws if the string is not a valid canonical `echo:` EID.
+ * Parses a string to EID. Throws if the string is not a valid `echo:` EID.
+ *
+ * The legacy single-slash local form (`echo:/<objectId>`) is accepted and normalized to the
+ * canonical triple-slash form (`echo:///<objectId>`) so that legacy and freshly-produced EIDs
+ * compare equal.
  */
 export const parse = (uri: string): EID => {
   if (!ECHO_URI_REGEXP.test(uri)) {
     throw new Error(`Invalid EID: ${uri}`);
   }
-  return uri as EID;
+  const legacy = LOCAL_LEGACY_RE.exec(uri);
+  return (legacy ? `echo:///${legacy[1]}` : uri) as EID;
 };
 
 /**
@@ -64,7 +82,7 @@ export const tryParse = (uri: string): EID | undefined => {
  * Constructs an EID. Validates the result via `parse`.
  *
  * - `{ spaceId, entityId }` → `echo://<spaceId>/<entityId>` (fully qualified)
- * - `{ entityId }`          → `echo:/<entityId>` (local — current space)
+ * - `{ entityId }`          → `echo:///<entityId>` (local — current space)
  * - `{ spaceId }`           → `echo://<spaceId>` (space-only)
  *
  * Throws if neither id is provided, or if the result is not a valid EID.
@@ -74,7 +92,7 @@ export const make = ({ spaceId, entityId }: { spaceId?: SpaceId; entityId?: Enti
   if (spaceId != null && entityId != null) {
     raw = `echo://${spaceId}/${entityId}`;
   } else if (entityId != null) {
-    raw = `echo:/${entityId}`;
+    raw = `echo:///${entityId}`;
   } else if (spaceId != null) {
     raw = `echo://${spaceId}`;
   } else {
@@ -145,7 +163,7 @@ const Schema_: Schema.Schema<EID, EID> = Schema.String.pipe(
   }),
   Schema.annotations({
     title: 'EID',
-    description: 'ECHO object/space URI: echo://<spaceId>[/<objectId>] or echo:/<objectId>',
+    description: 'ECHO object/space URI: echo://<spaceId>[/<objectId>] or echo:///<objectId>',
   }),
 ) as unknown as Schema.Schema<EID, EID>;
 export { Schema_ as Schema };

package/src/keys.workerd.test.ts

@@ -0,0 +1,47 @@
+//
+// Copyright 2026 DXOS.org
+//
+
+// Runs in the Cloudflare Workers runtime (`workerd`) via `@cloudflare/vitest-pool-workers`,
+// opted in with `workerd: true` in this package's vitest config. Guards that the core key
+// primitives keep working against the runtime our production Cloudflare functions execute on
+// (Buffer + web-crypto `getRandomValues` under `nodejs_compat`), not just under Node.
+
+import { describe, test } from 'vitest';
+
+import { EntityId } from './entity-id';
+import { PublicKey } from './public-key';
+
+describe('keys in workerd', () => {
+  test('runs inside the Cloudflare Workers runtime', ({ expect }) => {
+    // workerd sets a fixed navigator.userAgent; asserts the pool actually swapped the runtime.
+    expect(navigator.userAgent).toBe('Cloudflare-Workers');
+  });
+
+  test('PublicKey.random produces distinct hex-encoded keys', ({ expect }) => {
+    const first = PublicKey.random();
+    const second = PublicKey.random();
+    expect(first.toHex()).toHaveLength(64);
+    expect(PublicKey.equals(first, first)).toBe(true);
+    expect(PublicKey.equals(first, second)).toBe(false);
+  });
+
+  test('PublicKey round-trips through hex', ({ expect }) => {
+    const key = PublicKey.random();
+    expect(PublicKey.from(key.toHex()).equals(key)).toBe(true);
+  });
+
+  test('EntityId.random yields valid ids', ({ expect }) => {
+    const id = EntityId.random();
+    expect(EntityId.isValid(id)).toBe(true);
+  });
+
+  test('EntityId.deterministic is stable and avoids the platform RNG', ({ expect }) => {
+    // Workerd forbids `crypto.getRandomValues()` in global scope, so deterministic() must be
+    // reachable at module-eval time — its stability doubles as that guard here.
+    const first = EntityId.deterministic('org.dxos.type.person', '0.1.0');
+    const second = EntityId.deterministic('org.dxos.type.person', '0.1.0');
+    expect(first).toBe(second);
+    expect(EntityId.isValid(first)).toBe(true);
+  });
+});