@dxos/keys 0.7.4 → 0.7.5-labs.071a3e2

package/dist/types/src/dxn.d.ts

@@ -1,5 +1,6 @@
 import type { inspect, InspectOptionsStylized } from 'node:util';
 import { inspectCustom } from '@dxos/debug';
+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.
@@ -23,19 +24,47 @@ export declare class DXN {
      * Kind constants.
      */
     static kind: Readonly<{
+        /**
+         * dxn:type:<type name>[:<version>]
+         */
         TYPE: "type";
+        /**
+         * dxn:echo:<space id>:<echo id>
+         * dxn:echo:@:<echo id>
+         */
         ECHO: "echo";
+        /**
+         * 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
+         */
+        QUEUE: "queue";
     }>;
     static equals(a: DXN, b: DXN): boolean;
     static isDXNString(dxn: string): boolean;
     static parse(dxn: string): DXN;
+    static tryParse(dxn: string): DXN | undefined;
+    /**
+     * @example `dxn:type:example.com/type/Contact`
+     */
     static fromTypename(type: string): DXN;
+    /**
+     * @example `dxn:type:example.com/type/Contact:0.1.0`
+     */
+    static fromTypenameAndVersion(type: string, version: string): DXN;
+    /**
+     * @example `dxn:echo:@:01J00J9B45YHYSGZQTQMSKMGJ6`
+     */
     static fromLocalObjectId(id: string): DXN;
     constructor(kind: string, parts: string[]);
     get kind(): string;
     get parts(): string[];
     toTypename(): string;
     hasTypenameOf(typename: string): boolean;
+    asTypeDXN(): DXN.TypeDXN | undefined;
+    asEchoDXN(): DXN.EchoDXN | undefined;
+    asQueueDXN(): DXN.QueueDXN | undefined;
     isLocalObjectId(): boolean;
     toString(): string;
     /**
@@ -43,8 +72,28 @@ export declare class DXN {
      */
     [inspectCustom](depth: number, options: InspectOptionsStylized, inspectFn: typeof inspect): string;
 }
+export declare namespace DXN {
+    type TypeDXN = {
+        type: string;
+        version?: string;
+    };
+    type EchoDXN = {
+        spaceId?: SpaceId;
+        echoId: string;
+    };
+    type QueueDXN = {
+        subspaceTag: string;
+        spaceId: SpaceId;
+        queueId: string;
+        objectId?: string;
+    };
+}
 /**
  * Tags for ECHO DXNs that should resolve the object ID in the local space.
  */
 export declare const LOCAL_SPACE_TAG = "@";
+export declare const QueueSubspaceTags: Readonly<{
+    DATA: "data";
+    TRACE: "trace";
+}>;
 //# sourceMappingURL=dxn.d.ts.map

package/dist/types/src/dxn.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dxn.d.ts","sourceRoot":"","sources":["../../../src/dxn.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAEjE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG5C;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,GAAG;;IACd;;OAEG;IACH,MAAM,CAAC,IAAI;;;OAGR;IAEH,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG;IAI5B,MAAM,CAAC,WAAW,CAAC,GAAG,EAAE,MAAM;IAI9B,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG;IAkB9B,MAAM,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM;IAIhC,MAAM,CAAC,iBAAiB,CAAC,EAAE,EAAE,MAAM;gBAOvB,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE;IAsBzC,IAAI,IAAI,WAEP;IAED,IAAI,KAAK,aAER;IAED,UAAU;IAKV,aAAa,CAAC,QAAQ,EAAE,MAAM;IAI9B,eAAe;IAIf,QAAQ;IAIR;;OAEG;IACH,CAAC,aAAa,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,sBAAsB,EAAE,SAAS,EAAE,OAAO,OAAO;CAS1F;AAED;;GAEG;AACH,eAAO,MAAM,eAAe,MAAM,CAAC"}
+{"version":3,"file":"dxn.d.ts","sourceRoot":"","sources":["../../../src/dxn.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAC;AAEjE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAG5C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,GAAG;;IACd;;OAEG;IACH,MAAM,CAAC,IAAI;QACT;;WAEG;;QAEH;;;WAGG;;QAEH;;;;;WAKG;;OAEF;IAEH,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,EAAE,GAAG;IAI5B,MAAM,CAAC,WAAW,CAAC,GAAG,EAAE,MAAM;IAI9B,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG;IAkB9B,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,MAAM;IAQ3B;;OAEG;IACH,MAAM,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM;IAIhC;;OAEG;IAEH,MAAM,CAAC,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;IAI3D;;OAEG;IACH,MAAM,CAAC,iBAAiB,CAAC,EAAE,EAAE,MAAM;gBAOvB,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE;IAsBzC,IAAI,IAAI,WAEP;IAED,IAAI,KAAK,aAER;IAED,UAAU;IAKV,aAAa,CAAC,QAAQ,EAAE,MAAM;IAI9B,SAAS,IAAI,GAAG,CAAC,OAAO,GAAG,SAAS;IAYpC,SAAS,IAAI,GAAG,CAAC,OAAO,GAAG,SAAS;IAYpC,UAAU,IAAI,GAAG,CAAC,QAAQ,GAAG,SAAS;IAkBtC,eAAe;IAIf,QAAQ;IAIR;;OAEG;IACH,CAAC,aAAa,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,sBAAsB,EAAE,SAAS,EAAE,OAAO,OAAO;CAS1F;AAED,MAAM,CAAC,OAAO,WAAW,GAAG,CAAC;IAC3B,KAAY,OAAO,GAAG;QACpB,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;IAEF,KAAY,OAAO,GAAG;QACpB,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC;IAEF,KAAY,QAAQ,GAAG;QACrB,WAAW,EAAE,MAAM,CAAC;QACpB,OAAO,EAAE,OAAO,CAAC;QACjB,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED;;GAEG;AACH,eAAO,MAAM,eAAe,MAAM,CAAC;AAEnC,eAAO,MAAM,iBAAiB;;;EAG5B,CAAC"}

package/dist/types/src/identity-did.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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 declare const IdentityDid: Readonly<{
+    byteLength: 20;
+    encode: (value: Uint8Array) => IdentityDid;
+    decode: (value: IdentityDid) => Uint8Array;
+    isValid: (value: string) => value is IdentityDid;
+    random: () => IdentityDid;
+}>;
+//# sourceMappingURL=identity-did.d.ts.map

package/dist/types/src/identity-did.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-did.d.ts","sourceRoot":"","sources":["../../../src/identity-did.ts"],"names":[],"mappings":"AAWA;;;;GAIG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG;IAAE,aAAa,EAAE,IAAI,CAAA;CAAE,CAAC;AAE3D,eAAO,MAAM,WAAW;;oBAEN,UAAU,KAAG,WAAW;oBAMxB,WAAW,KAAG,UAAU;qBAKvB,MAAM,KAAG,KAAK,IAAI,WAAW;kBAKlC,WAAW;EAGvB,CAAC"}

package/dist/types/src/identity-did.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=identity-did.test.d.ts.map

package/dist/types/src/identity-did.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-did.test.d.ts","sourceRoot":"","sources":["../../../src/identity-did.test.ts"],"names":[],"mappings":""}

package/dist/types/src/index.d.ts

@@ -1,3 +1,4 @@
+export * from './identity-did';
 export * from './public-key';
 export * from './types';
 export * from './space-id';

package/dist/types/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAIA,cAAc,cAAc,CAAC;AAC7B,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,OAAO,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/index.ts"],"names":[],"mappings":"AAIA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,SAAS,CAAC;AACxB,cAAc,YAAY,CAAC;AAC3B,cAAc,OAAO,CAAC"}

package/dist/types/src/random-bytes.d.ts

@@ -1,2 +1,2 @@
-export declare const randomBytes: (length: number) => Uint8Array;
+export declare const randomBytes: (length: number) => Uint8Array<ArrayBuffer>;
 //# sourceMappingURL=random-bytes.d.ts.map

package/dist/types/src/random-bytes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"random-bytes.d.ts","sourceRoot":"","sources":["../../../src/random-bytes.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,WAAW,WAAY,MAAM,eAQzC,CAAC"}
+{"version":3,"file":"random-bytes.d.ts","sourceRoot":"","sources":["../../../src/random-bytes.ts"],"names":[],"mappings":"AAIA,eAAO,MAAM,WAAW,WAAY,MAAM,4BAQzC,CAAC"}

package/dist/types/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"version":"5.7.3"}

package/package.json

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

package/src/dxn.ts

@@ -7,6 +7,8 @@ import type { inspect, InspectOptionsStylized } from 'node:util';
 import { inspectCustom } from '@dxos/debug';
 import { invariant } from '@dxos/invariant';
 
+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.
@@ -29,8 +31,22 @@ export class DXN {
    * Kind constants.
    */
   static kind = Object.freeze({
+    /**
+     * dxn:type:<type name>[:<version>]
+     */
     TYPE: 'type',
+    /**
+     * dxn:echo:<space id>:<echo id>
+     * dxn:echo:@:<echo id>
+     */
     ECHO: 'echo',
+    /**
+     * 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
+     */
+    QUEUE: 'queue',
   });
 
   static equals(a: DXN, b: DXN) {
@@ -43,26 +59,48 @@ export class DXN {
 
   static parse(dxn: string): DXN {
     if (typeof dxn !== 'string') {
-      throw new Error('Invalid DXN');
+      throw new Error(`Invalid DXN: ${dxn}`);
     }
     const [prefix, kind, ...parts] = dxn.split(':');
     if (!(prefix === 'dxn')) {
-      throw new Error('Invalid DXN');
+      throw new Error(`Invalid DXN: ${dxn}`);
     }
     if (!(typeof kind === 'string' && kind.length > 0)) {
-      throw new Error('Invalid DXN');
+      throw new Error(`Invalid DXN: ${dxn}`);
     }
     if (!(parts.length > 0)) {
-      throw new Error('Invalid DXN');
+      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`
+   */
   static fromTypename(type: string) {
     return new DXN(DXN.kind.TYPE, [type]);
   }
 
+  /**
+   * @example `dxn:type:example.com/type/Contact:0.1.0`
+   */
+  // TODO(dmaretskyi): Consider using @ as the version separator.
+  static fromTypenameAndVersion(type: string, version: string) {
+    return new DXN(DXN.kind.TYPE, [type, version]);
+  }
+
+  /**
+   * @example `dxn:echo:@:01J00J9B45YHYSGZQTQMSKMGJ6`
+   */
   static fromLocalObjectId(id: string) {
     return new DXN(DXN.kind.ECHO, [LOCAL_SPACE_TAG, id]);
   }
@@ -77,7 +115,7 @@ export class DXN {
     // Per-type validation.
     switch (kind) {
       case DXN.kind.TYPE:
-        if (parts.length !== 1) {
+        if (parts.length > 2) {
           throw new Error('Invalid "type" DXN');
         }
         break;
@@ -109,6 +147,48 @@ export class DXN {
     return this.#kind === DXN.kind.TYPE && this.#parts.length === 1 && this.#parts[0] === typename;
   }
 
+  asTypeDXN(): DXN.TypeDXN | undefined {
+    if (this.kind !== DXN.kind.TYPE) {
+      return undefined;
+    }
+
+    const [type, version] = this.#parts;
+    return {
+      type,
+      version: version as string | undefined,
+    };
+  }
+
+  asEchoDXN(): DXN.EchoDXN | undefined {
+    if (this.kind !== DXN.kind.ECHO) {
+      return undefined;
+    }
+
+    const [spaceId, echoId] = this.#parts;
+    return {
+      spaceId: spaceId === LOCAL_SPACE_TAG ? undefined : (spaceId as SpaceId | undefined),
+      echoId,
+    };
+  }
+
+  asQueueDXN(): DXN.QueueDXN | undefined {
+    if (this.kind !== DXN.kind.QUEUE) {
+      return undefined;
+    }
+
+    const [subspaceTag, spaceId, queueId, objectId] = this.#parts;
+    if (typeof queueId !== 'string') {
+      return undefined;
+    }
+
+    return {
+      subspaceTag,
+      spaceId: spaceId as SpaceId,
+      queueId,
+      objectId: objectId as string | undefined,
+    };
+  }
+
   isLocalObjectId() {
     return this.#kind === DXN.kind.ECHO && this.#parts[0] === LOCAL_SPACE_TAG && this.#parts.length === 2;
   }
@@ -131,7 +211,31 @@ export class DXN {
   }
 }
 
+export declare namespace DXN {
+  export type TypeDXN = {
+    type: string;
+    version?: string;
+  };
+
+  export type EchoDXN = {
+    spaceId?: SpaceId;
+    echoId: string; // TODO(dmaretskyi): ObjectId.
+  };
+
+  export type QueueDXN = {
+    subspaceTag: string;
+    spaceId: SpaceId;
+    queueId: string; // TODO(dmaretskyi): ObjectId.
+    objectId?: string; // TODO(dmaretskyi): ObjectId.
+  };
+}
+
 /**
  * Tags for ECHO DXNs that should resolve the object ID in the local space.
  */
 export const LOCAL_SPACE_TAG = '@';
+
+export const QueueSubspaceTags = Object.freeze({
+  DATA: 'data',
+  TRACE: 'trace',
+});

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';