@dxos/keys 0.7.5-labs.5f04cf6 → 0.7.5-labs.8a82073

package/dist/types/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"version":"5.7.2"}
+{"version":"5.7.3"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/keys",
-  "version": "0.7.5-labs.5f04cf6",
+  "version": "0.7.5-labs.8a82073",
   "description": "Key utils and definitions.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -26,9 +26,9 @@
     "src"
   ],
   "dependencies": {
-    "@dxos/debug": "0.7.5-labs.5f04cf6",
-    "@dxos/invariant": "0.7.5-labs.5f04cf6",
-    "@dxos/node-std": "0.7.5-labs.5f04cf6"
+    "@dxos/debug": "0.7.5-labs.8a82073",
+    "@dxos/node-std": "0.7.5-labs.8a82073",
+    "@dxos/invariant": "0.7.5-labs.8a82073"
   },
   "devDependencies": {
     "base32-decode": "^1.0.0",

package/src/dxn.ts

@@ -11,7 +11,7 @@ import type { SpaceId } from './space-id';
 
 /**
  * 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.
+ * Each DXN starts with a dxn 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.
@@ -19,11 +19,11 @@ import type { SpaceId } from './space-id';
  * @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
+ * dxn:echo:<space key>:<echo id>
+ * dxn:echo:BA25QRC2FEWCSAMRP4RZL65LWJ7352CKE:01J00J9B45YHYSGZQTQMSKMGJ6
+ * dxn:echo:@:01J00J9B45YHYSGZQTQMSKMGJ6
+ * dxn:type:dxos.org/type/Calendar
+ * dxn:plugin:dxos.org/agent/plugin/functions
  * ```
  */
 export class DXN {
@@ -41,7 +41,8 @@ export class DXN {
      */
     ECHO: 'echo',
     /**
-     * dxn:queue:<subspace tag>:<space id>:<queue id>[:object id]
+     * The subspace tag enables us to partition queues by usage within the context of a space.
+     * dxn:queue:<subspace_tag>:<space_id>:<queue_id>[:object_id]
      * dxn:queue:data:BA25QRC2FEWCSAMRP4RZL65LWJ7352CKE:01J00J9B45YHYSGZQTQMSKMGJ6
      * dxn:queue:trace:BA25QRC2FEWCSAMRP4RZL65LWJ7352CKE:01J00J9B45YHYSGZQTQMSKMGJ6
      */
@@ -56,38 +57,32 @@ export class DXN {
     return dxn.startsWith('dxn:');
   }
 
-  static parse(dxn: string): DXN;
-  static parse(dxn: string, noThrow: boolean): DXN | undefined;
-  static parse(dxn: string, noThrow?: boolean): DXN | undefined {
+  static parse(dxn: string): DXN {
     if (typeof dxn !== 'string') {
-      if (noThrow) {
-        return undefined;
-      }
       throw new Error(`Invalid DXN: ${dxn}`);
     }
     const [prefix, kind, ...parts] = dxn.split(':');
     if (!(prefix === 'dxn')) {
-      if (noThrow) {
-        return undefined;
-      }
       throw new Error(`Invalid DXN: ${dxn}`);
     }
     if (!(typeof kind === 'string' && kind.length > 0)) {
-      if (noThrow) {
-        return undefined;
-      }
       throw new Error(`Invalid DXN: ${dxn}`);
     }
     if (!(parts.length > 0)) {
-      if (noThrow) {
-        return undefined;
-      }
       throw new Error(`Invalid DXN: ${dxn}`);
     }
 
     return new DXN(kind, parts);
   }
 
+  static tryParse(dxn: string) {
+    try {
+      return DXN.parse(dxn);
+    } catch (error) {
+      return undefined;
+    }
+  }
+
   /**
    * @example `dxn:type:example.com/type/Contact`
    */
@@ -185,6 +180,7 @@ export class DXN {
     if (typeof queueId !== 'string') {
       return undefined;
     }
+
     return {
       subspaceTag,
       spaceId: spaceId as SpaceId,

package/src/identity-did.test.ts

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

package/src/identity-did.ts

@@ -0,0 +1,49 @@
+//
+// 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 did:halo:BA25QRC2FEWCSAMRP4RZL65LWJ7352CKE
+ */
+export type IdentityDid = string & { __IdentityDid: true };
+
+export const IdentityDid = Object.freeze({
+  byteLength: 20,
+  encode: (value: Uint8Array): IdentityDid => {
+    invariant(value instanceof Uint8Array, 'Invalid type');
+    invariant(value.length === IdentityDid.byteLength, 'Invalid length');
+
+    return (DID_PREFIX + MULTIBASE_PREFIX + base32Encode(value, 'RFC4648')) as IdentityDid;
+  },
+  decode: (value: IdentityDid): Uint8Array => {
+    invariant(value.startsWith(DID_PREFIX + MULTIBASE_PREFIX), 'Invalid multibase32 encoding');
+
+    return new Uint8Array(base32Decode(value.slice(10), 'RFC4648'));
+  },
+  isValid: (value: string): value is IdentityDid => {
+    return (
+      typeof value === 'string' && value.startsWith(DID_PREFIX + MULTIBASE_PREFIX) && value.length === ENCODED_LENGTH
+    );
+  },
+  random: (): IdentityDid => {
+    return IdentityDid.encode(randomBytes(IdentityDid.byteLength));
+  },
+});
+
+/**
+ * Denotes RFC4648 base-32 format.
+ */
+const MULTIBASE_PREFIX = 'B';
+
+const DID_PREFIX = 'did:halo:';
+
+const ENCODED_LENGTH = 42;

package/src/index.ts

@@ -2,6 +2,7 @@
 // Copyright 2020 DXOS.org
 //
 
+export * from './identity-did';
 export * from './public-key';
 export * from './types';
 export * from './space-id';