@dxos/keys 0.5.8 → 0.5.9-main.079a532

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/keys",
-  "version": "0.5.8",
+  "version": "0.5.9-main.079a532",
   "description": "Key utils and definitions.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -21,9 +21,13 @@
     "src"
   ],
   "dependencies": {
-    "@dxos/debug": "0.5.8",
-    "@dxos/invariant": "0.5.8",
-    "@dxos/node-std": "0.5.8"
+    "@dxos/debug": "0.5.9-main.079a532",
+    "@dxos/invariant": "0.5.9-main.079a532",
+    "@dxos/node-std": "0.5.9-main.079a532"
+  },
+  "devDependencies": {
+    "base32-decode": "^1.0.0",
+    "base32-encode": "^2.0.0"
   },
   "publishConfig": {
     "access": "public"

package/src/dxn.ts

@@ -0,0 +1,88 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { invariant } from '@dxos/invariant';
+
+/**
+ * DXN unambiguously names a resource like an ECHO object, schema definition, plugin, etc.
+ * Each DXN starts with a dx prefix, followed by a resource kind.
+ * Colon Symbol : is used a delimiter between parts.
+ * DXNs may contain slashes.
+ * '@' in the place of the space id is used to denote that the DXN should be resolved in the local space.
+ *
+ * @example
+ *
+ * ```
+ * dx:echo:<space key>:<echo id>
+ * dx:echo:BA25QRC2FEWCSAMRP4RZL65LWJ7352CKE:01J00J9B45YHYSGZQTQMSKMGJ6
+ * dx:echo:@:01J00J9B45YHYSGZQTQMSKMGJ6
+ * dx:type:dxos.org/type/Calendar
+ * dx:plugin:dxos.org/agent/plugin/functions
+ * ```
+ */
+export class DXN {
+  /**
+   * Kind constants.
+   */
+  static kind = Object.freeze({
+    ECHO: 'echo',
+    TYPE: 'type',
+  });
+
+  static parse(dxn: string): DXN {
+    const [prefix, kind, ...parts] = dxn.split(':');
+    if (!(prefix === 'dxn')) {
+      throw new Error('Invalid DXN');
+    }
+    if (!(typeof kind === 'string' && kind.length > 0)) {
+      throw new Error('Invalid DXN');
+    }
+    if (!(parts.length > 0)) {
+      throw new Error('Invalid DXN');
+    }
+    return new DXN(kind, parts);
+  }
+
+  #kind: string;
+  #parts: string[];
+
+  constructor(kind: string, parts: string[]) {
+    invariant(parts.length > 0);
+    invariant(parts.every((part) => typeof part === 'string' && part.length > 0 && part.indexOf(':') === -1));
+
+    // Per-type validation.
+    switch (kind) {
+      case DXN.kind.ECHO:
+        invariant(parts.length === 2);
+        break;
+      case DXN.kind.TYPE:
+        invariant(parts.length === 1);
+        break;
+    }
+
+    this.#kind = kind;
+    this.#parts = parts;
+  }
+
+  get kind() {
+    return this.#kind;
+  }
+
+  get parts() {
+    return this.#parts;
+  }
+
+  isTypeDXNOf(typename: string) {
+    return this.#kind === DXN.kind.TYPE && this.#parts.length === 1 && this.#parts[0] === typename;
+  }
+
+  toString() {
+    return `dxn:${this.#kind}:${this.#parts.join(':')}`;
+  }
+}
+
+/**
+ * Tags for ECHO DXNs that should resolve the object ID in the local space.
+ */
+export const LOCAL_SPACE_TAG = '@';

package/src/index.ts

@@ -4,3 +4,5 @@
 
 export * from './public-key';
 export * from './types';
+export * from './space-id';
+export * from './dxn';

package/src/public-key.test.ts

@@ -60,4 +60,11 @@ describe('PublicKey', () => {
     const key = PublicKey.random();
     expect(PublicKey.equals(key, PublicKey.from(key.toHex()))).to.be.true;
   });
+
+  test('base32', () => {
+    const key = PublicKey.randomOfLength(20); // Space keys will be cut to first 20 bytes of sha-256 hash.
+    const encoded = key.toMultibase32();
+
+    expect(PublicKey.fromMultibase32(encoded).toHex()).to.equal(key.toHex());
+  });
 });

package/src/public-key.ts

@@ -2,11 +2,15 @@
 // Copyright 2020 DXOS.org
 //
 
+import base32Decode from 'base32-decode';
+import base32Encode from 'base32-encode';
 import { inspect, type InspectOptionsStylized } from 'node:util';
 
 import { truncateKey, devtoolsFormatter, type DevtoolsFormatter, equalsSymbol, type Equatable } from '@dxos/debug';
 import { invariant } from '@dxos/invariant';
 
+import { randomBytes } from './random-bytes';
+
 export const PUBLIC_KEY_LENGTH = 32;
 export const SECRET_KEY_LENGTH = 64;
 
@@ -89,6 +93,10 @@ export class PublicKey implements Equatable {
     return PublicKey.from(randomBytes(PUBLIC_KEY_LENGTH));
   }
 
+  static randomOfLength(length: number): PublicKey {
+    return PublicKey.from(randomBytes(length));
+  }
+
   static *randomSequence(): Generator<PublicKey> {
     for (let i = 0; i < 1_0000; i++) {
       // Counter just to protect against infinite loops.
@@ -157,6 +165,12 @@ export class PublicKey implements Equatable {
     return key.toHex();
   }
 
+  static fromMultibase32(encoded: string): PublicKey {
+    invariant(encoded.startsWith('B'), 'Invalid multibase32 encoding');
+
+    return new PublicKey(new Uint8Array(base32Decode(encoded.slice(1), 'RFC4648')));
+  }
+
   constructor(private readonly _value: Uint8Array) {
     if (!(_value instanceof Uint8Array)) {
       throw new TypeError(`Expected Uint8Array, got: ${_value}`);
@@ -183,6 +197,10 @@ export class PublicKey implements Equatable {
     return this.asBuffer().toString('hex');
   }
 
+  toMultibase32(): string {
+    return 'B' + base32Encode(this._value, 'RFC4648');
+  }
+
   truncate(length = undefined) {
     return truncateKey(this, length);
   }
@@ -291,13 +309,3 @@ export class PublicKey implements Equatable {
     return this.equals(other);
   }
 }
-
-const randomBytes = (length: number) => {
-  // globalThis.crypto is not available in Node.js when running in vitest even though the documentation says it should be.
-  // eslint-disable-next-line @typescript-eslint/no-var-requires
-  const webCrypto = globalThis.crypto ?? require('node:crypto').webcrypto;
-
-  const bytes = new Uint8Array(length);
-  webCrypto.getRandomValues(bytes);
-  return bytes;
-};

package/src/random-bytes.ts

@@ -0,0 +1,13 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+export const randomBytes = (length: number) => {
+  // globalThis.crypto is not available in Node.js when running in vitest even though the documentation says it should be.
+  // eslint-disable-next-line @typescript-eslint/no-var-requires
+  const webCrypto = globalThis.crypto ?? require('node:crypto').webcrypto;
+
+  const bytes = new Uint8Array(length);
+  webCrypto.getRandomValues(bytes);
+  return bytes;
+};

package/src/space-id.test.ts

@@ -0,0 +1,17 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { expect, test } from 'vitest';
+
+import { SpaceId } from './space-id';
+
+test('space-id', () => {
+  const id = SpaceId.random();
+
+  expect(SpaceId.isValid(id)).toBe(true);
+  expect(id.length).toBe(33);
+  const decoded = SpaceId.decode(id);
+  expect(decoded.length).toBe(SpaceId.byteLength);
+  expect(SpaceId.encode(decoded)).toBe(id);
+});

package/src/space-id.ts

@@ -0,0 +1,45 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import base32Decode from 'base32-decode';
+import base32Encode from 'base32-encode';
+
+import { invariant } from '@dxos/invariant';
+
+import { randomBytes } from './random-bytes';
+
+/**
+ * A unique identifier for a space.
+ * Space keys are generated by creating a keypair, and then taking the first 20 bytes of the SHA-256 hash of the public key and encoding them to multibase RFC4648 base-32 format (prefixed with B, see Multibase Table).
+ * @example BA25QRC2FEWCSAMRP4RZL65LWJ7352CKE
+ */
+export type SpaceId = string & { __SpaceId: true };
+
+export const SpaceId = Object.freeze({
+  byteLength: 20,
+  encode: (value: Uint8Array): SpaceId => {
+    invariant(value instanceof Uint8Array, 'Invalid type');
+    invariant(value.length === SpaceId.byteLength, 'Invalid length');
+
+    return (MULTIBASE_PREFIX + base32Encode(value, 'RFC4648')) as SpaceId;
+  },
+  decode: (value: SpaceId): Uint8Array => {
+    invariant(value.startsWith(MULTIBASE_PREFIX), 'Invalid multibase32 encoding');
+
+    return new Uint8Array(base32Decode(value.slice(1), 'RFC4648'));
+  },
+  isValid: (value: string): value is SpaceId => {
+    return typeof value === 'string' && value.startsWith(MULTIBASE_PREFIX) && value.length === ENCODED_LENGTH;
+  },
+  random: (): SpaceId => {
+    return SpaceId.encode(randomBytes(SpaceId.byteLength));
+  },
+});
+
+/**
+ * Denotes RFC4648 base-32 format.
+ */
+const MULTIBASE_PREFIX = 'B';
+
+const ENCODED_LENGTH = 33;

package/src/types.ts

@@ -2,7 +2,6 @@
 // Copyright 2022 DXOS.org
 //
 
-// TODO(burdon): Replace with hypercore-crypto type.
 export type KeyPair = {
   publicKey: Buffer;
   secretKey: Buffer;