@ledgerhq/hw-ledger-key-ring-protocol 0.2.1-nightly.0

package/src/CommandBlock.ts

@@ -0,0 +1,247 @@
+import { CommandStreamEncoder } from "./CommandStreamEncoder";
+import { crypto } from "./Crypto";
+
+/**
+ *
+ */
+export interface Command {
+  getType(): CommandType;
+}
+
+/**
+ *
+ */
+export enum CommandType {
+  Seed = 0x10,
+  AddMember = 0x11,
+  PublishKey = 0x12,
+  EditMember = 0x14,
+  Derive = 0x15,
+  CloseStream = 0x13,
+}
+
+/**
+ *
+ */
+export const Permissions = {
+  KEY_READER: 0x01,
+  KEY_CREATOR: 0x02,
+  KEY_REVOKER: 0x04,
+  ADD_MEMBER: 0x08,
+  REMOVE_MEMBER: 0x16,
+  CHANGE_MEMBER_PERMISSIONS: 0x32,
+  CHANGE_MEMBER_NAME: 0x64,
+
+  MEMBER: 0,
+  OWNER: 0xffffffff,
+};
+
+/**
+ *
+ */
+export class Seed implements Command {
+  topic: Uint8Array | null;
+  protocolVersion: number;
+  groupKey: Uint8Array;
+  initializationVector: Uint8Array;
+  encryptedXpriv: Uint8Array;
+  ephemeralPublicKey: Uint8Array;
+
+  constructor(
+    topic: Uint8Array | null,
+    protocolVersion: number,
+    groupKey: Uint8Array,
+    initializationVector: Uint8Array,
+    encryptedXpriv: Uint8Array,
+    ephemerPublicKey: Uint8Array,
+  ) {
+    this.topic = topic;
+    this.protocolVersion = protocolVersion;
+    this.groupKey = groupKey.length == 0 ? new Uint8Array(33) : groupKey;
+    this.initializationVector =
+      initializationVector.length == 0 ? new Uint8Array(16) : initializationVector;
+    this.encryptedXpriv = encryptedXpriv.length == 0 ? new Uint8Array(64) : encryptedXpriv;
+    this.ephemeralPublicKey = ephemerPublicKey.length == 0 ? new Uint8Array(33) : ephemerPublicKey;
+  }
+
+  getType(): CommandType {
+    return CommandType.Seed;
+  }
+}
+
+/**
+ *
+ */
+export class Derive implements Command {
+  path: number[];
+  groupKey: Uint8Array;
+  initializationVector: Uint8Array;
+  encryptedXpriv: Uint8Array;
+  ephemeralPublicKey: Uint8Array;
+
+  constructor(
+    path: number[],
+    groupKey: Uint8Array,
+    initializationVector: Uint8Array,
+    encryptedXpriv: Uint8Array,
+    ephemeralPublicKey: Uint8Array,
+  ) {
+    this.path = path;
+    this.groupKey = groupKey;
+    this.initializationVector = initializationVector;
+    this.encryptedXpriv = encryptedXpriv;
+    this.ephemeralPublicKey = ephemeralPublicKey;
+  }
+
+  getType(): CommandType {
+    return CommandType.Derive;
+  }
+}
+
+/**
+ *
+ */
+export class AddMember implements Command {
+  name: string;
+  publicKey: Uint8Array;
+  permissions: number;
+
+  constructor(name: string, publicKey: Uint8Array, permissions: number) {
+    this.name = name;
+    this.publicKey = publicKey;
+    this.permissions = permissions;
+  }
+
+  getType(): CommandType {
+    return CommandType.AddMember;
+  }
+}
+
+/**
+ *
+ */
+export class PublishKey implements Command {
+  initializationVector: Uint8Array;
+  encryptedXpriv: Uint8Array;
+  recipient: Uint8Array;
+  ephemeralPublicKey: Uint8Array;
+
+  constructor(
+    initializationVector: Uint8Array,
+    encryptedXpriv: Uint8Array,
+    recipient: Uint8Array,
+    ephemeralPublicKey: Uint8Array,
+  ) {
+    this.encryptedXpriv = encryptedXpriv;
+    this.initializationVector = initializationVector;
+    this.recipient = recipient;
+    this.ephemeralPublicKey = ephemeralPublicKey;
+  }
+
+  getType(): CommandType {
+    return CommandType.PublishKey;
+  }
+}
+
+/**
+ *
+ */
+export class EditMember implements Command {
+  member: Uint8Array;
+  name: string | null;
+  permissions: number | null;
+
+  constructor(member: Uint8Array, name: string | null, permissions: number | null) {
+    this.name = name;
+    this.permissions = permissions;
+    this.member = member;
+  }
+
+  getType(): CommandType {
+    return CommandType.EditMember;
+  }
+}
+
+/**
+ *
+ */
+export class CloseStream implements Command {
+  constructor() {}
+
+  getType(): CommandType {
+    return CommandType.CloseStream;
+  }
+}
+
+/*
+    Version   | VARINT  | 1     # Format version
+    Parent    | HASH    | 32    # The hash of the parent command block (Random 32 bytes for the first command block)
+    Issuer    | HASH    | 32    # Hash of the issuer public key
+    Length    | VARINT  | 1     # Number of command in this command block
+    ....
+    Signature | SIG     | var   # Signature of the command block
+*/
+export interface CommandBlock {
+  // The version of the command block format
+  version: number;
+  // The hash of the parent command block. For the first command block, parent must be a random 32 bytes number
+  parent: Uint8Array;
+  // The public key of the command block issuer
+  issuer: Uint8Array;
+  // The list of commands in this command block
+  commands: Command[];
+  // The signature of the command block
+  signature: Uint8Array;
+}
+
+/**
+ * Create a new command block.
+ * @param issuer The public key of the command block issuer
+ * @param commands The list of commands in this command block
+ * @param signature The signature of the command block (by default the block is not signed)
+ * @param parent The parent command block hash (if null, the block is the first block and a parent will be generated)
+ * @returns
+ */
+export async function createCommandBlock(
+  issuer: Uint8Array,
+  commands: Command[],
+  signature: Uint8Array = new Uint8Array(),
+  parent: Uint8Array | null = null,
+): Promise<CommandBlock> {
+  if (parent === null) {
+    parent = parent = await crypto.randomBytes(32);
+  }
+  return {
+    version: 1,
+    issuer,
+    parent,
+    commands,
+    signature,
+  };
+}
+
+export async function signCommandBlock(
+  block: CommandBlock,
+  issuer: Uint8Array,
+  secretKey: Uint8Array,
+): Promise<CommandBlock> {
+  const signature = await crypto.sign(
+    await hashCommandBlock(block),
+    await crypto.keypairFromSecretKey(secretKey),
+  );
+  return {
+    ...block,
+    signature,
+  };
+}
+
+export async function hashCommandBlock(block: CommandBlock): Promise<Uint8Array> {
+  return await crypto.hash(CommandStreamEncoder.encode([block]));
+}
+
+export async function verifyCommandBlock(block: CommandBlock): Promise<boolean> {
+  const unsignedBlock = { ...block };
+  unsignedBlock.signature = new Uint8Array();
+  const hash = await hashCommandBlock(unsignedBlock);
+  return await crypto.verify(hash, block.signature, block.issuer);
+}

package/src/CommandStream.ts

@@ -0,0 +1,262 @@
+import {
+  CommandBlock,
+  Command,
+  createCommandBlock,
+  hashCommandBlock,
+  CommandType,
+  Seed,
+  Derive,
+  AddMember,
+  PublishKey,
+  CloseStream,
+} from "./CommandBlock";
+import CommandStreamResolver, { ResolvedCommandStream } from "./CommandStreamResolver";
+import { DerivationPath } from "./Crypto";
+import { Device, ISSUER_PLACEHOLDER } from "./Device";
+import { StreamTree } from "./StreamTree";
+
+const EMPTY = new Uint8Array();
+
+/**
+ *
+ */
+export type CommandIssuer = (
+  device: Device,
+  tempStream: CommandStream,
+  streamTree?: StreamTree | null,
+) => Promise<Command[]>;
+
+/**
+ *
+ */
+export class CommandStreamIssuer {
+  private _stream: CommandStream;
+  private _steps: CommandIssuer[] = [];
+
+  constructor(stream: CommandStream) {
+    this._stream = stream;
+  }
+
+  public seed(topic: Uint8Array | null = null): CommandStreamIssuer {
+    const step: CommandIssuer = async (
+      device: Device,
+      tempStream: CommandStream,
+      streamTree?: StreamTree | null,
+    ) => {
+      device as Device;
+      tempStream as CommandStream;
+      streamTree as StreamTree;
+      return [new Seed(topic, 0, EMPTY, EMPTY, EMPTY, EMPTY)];
+    };
+    this._steps.push(step);
+    return this;
+  }
+
+  public derive(path: number[]): CommandStreamIssuer {
+    const step: CommandIssuer = async (
+      device: Device,
+      tempStream: CommandStream,
+      streamTree?: StreamTree | null,
+    ) => {
+      device as Device;
+      tempStream as CommandStream;
+      streamTree as StreamTree;
+      const derivationPath = DerivationPath.toIndexArray(path);
+      return [new Derive(derivationPath, EMPTY, EMPTY, EMPTY, EMPTY)];
+    };
+    this._steps.push(step);
+    return this;
+  }
+
+  public addMember(
+    name: string,
+    publicKey: Uint8Array,
+    permissions: number,
+    publishKey: boolean = true,
+  ): CommandStreamIssuer {
+    const step: CommandIssuer = async (
+      device: Device,
+      tempStream: CommandStream,
+      streamTree?: StreamTree | null,
+    ) => {
+      device as Device;
+      tempStream as CommandStream;
+      streamTree as StreamTree;
+      if (publishKey) {
+        return [
+          new AddMember(name, publicKey, permissions),
+          new PublishKey(EMPTY, EMPTY, publicKey, EMPTY),
+        ];
+      } else {
+        return [new AddMember(name, publicKey, permissions)];
+      }
+    };
+    this._steps.push(step);
+    return this;
+  }
+
+  public publishKey(publicKey: Uint8Array): CommandStreamIssuer {
+    const step: CommandIssuer = async (
+      device: Device,
+      tempStream: CommandStream,
+      streamTree?: StreamTree | null,
+    ) => {
+      device as Device;
+      tempStream as CommandStream;
+      streamTree as StreamTree;
+      return [new PublishKey(EMPTY, EMPTY, publicKey, EMPTY)];
+    };
+    this._steps.push(step);
+    return this;
+  }
+
+  public close(): CommandStreamIssuer {
+    const step: CommandIssuer = async (
+      device: Device,
+      tempStream: CommandStream,
+      streamTree?: StreamTree | null,
+    ) => {
+      device as Device;
+      tempStream as CommandStream;
+      streamTree as StreamTree;
+      return [new CloseStream()];
+    };
+    this._steps.push(step);
+    return this;
+  }
+
+  public async issue(
+    device: Device,
+    streamTree?: StreamTree | null,
+    parentHash?: Uint8Array | null,
+  ): Promise<CommandStream> {
+    const lastBlockHash =
+      this._stream.blocks.length > 0
+        ? await hashCommandBlock(this._stream.blocks[this._stream.blocks.length - 1])
+        : null;
+    const block = await createCommandBlock(
+      ISSUER_PLACEHOLDER,
+      [],
+      new Uint8Array(),
+      parentHash || lastBlockHash,
+    );
+    const stream = new CommandStream(this._stream.blocks.concat([]));
+    const tempStream = new CommandStream(this._stream.blocks.concat([block]));
+    let commands: Command[] = [];
+    for (const step of this._steps) {
+      const newCommands = await step(device, tempStream, streamTree);
+      commands = commands.concat(newCommands);
+      tempStream.blocks[tempStream.blocks.length - 1].commands = commands;
+    }
+    return await stream.issue(device, commands, streamTree, parentHash);
+  }
+}
+
+/**
+ *
+ */
+export default class CommandStream {
+  private _blocks: CommandBlock[] = [];
+
+  constructor(blocks: CommandBlock[] = []) {
+    this._blocks = blocks;
+  }
+
+  public resolve(incomplete: boolean = false): Promise<ResolvedCommandStream> {
+    incomplete as boolean;
+    return CommandStreamResolver.resolve(this._blocks);
+  }
+
+  public getRootHash(): Promise<Uint8Array> {
+    return hashCommandBlock(this._blocks[0]);
+  }
+
+  public getStreamPath(): string | null {
+    if (this._blocks.length === 0) return null;
+    if (this._blocks[0].commands[0].getType() === CommandType.Seed) {
+      return "";
+    } else if (this._blocks[0].commands[0].getType() === CommandType.Derive) {
+      return DerivationPath.toString((this._blocks[0].commands[0] as Derive).path);
+    } else {
+      throw new Error("Malformed CommandStream");
+    }
+  }
+
+  public async push(
+    block: CommandBlock,
+    issuer: Device,
+    tree: StreamTree | null,
+  ): Promise<CommandStream> {
+    let stream: CommandBlock[] = [];
+
+    if (block.commands.length === 0) {
+      throw new Error("Attempts to create an empty block");
+    }
+
+    // If the first command of the new block is not a seed and the first command of the stream is not a seed either, prepend the root block
+
+    if (
+      (this._blocks.length == 0 || this._blocks[0].commands[0].getType() !== CommandType.Seed) &&
+      block.commands[0].getType() !== CommandType.Seed
+    ) {
+      const root = tree?.getRoot();
+      if (!root || root.blocks.length === 0) {
+        throw new Error("Null or empty tree cannot be used to sign the new block");
+      }
+      stream = [root.blocks[0]].concat(this._blocks);
+    } else {
+      stream = this._blocks;
+    }
+
+    if (block.commands[0].getType() === CommandType.Derive) {
+      // Set the parent hash of the block to the root hash
+      const b = { ...block };
+      b.parent = await hashCommandBlock(stream[0]);
+      stream = stream.concat([b]);
+    } else {
+      stream = stream.concat([block]);
+    }
+    const signedBlock = await issuer.sign(stream, tree || undefined);
+    return new CommandStream(this._blocks.concat([signedBlock]));
+  }
+
+  public async issue(
+    device: Device,
+    commands: Command[],
+    tree: StreamTree | null = null,
+    parentHash: Uint8Array | null = null,
+  ): Promise<CommandStream> {
+    const lastBlockHash =
+      this._blocks.length > 0
+        ? await hashCommandBlock(this._blocks[this._blocks.length - 1])
+        : null;
+    const block = await createCommandBlock(
+      ISSUER_PLACEHOLDER,
+      commands,
+      new Uint8Array(),
+      parentHash || lastBlockHash,
+    );
+    return this.push(block, device, tree);
+  }
+
+  public edit(): CommandStreamIssuer {
+    return new CommandStreamIssuer(this);
+  }
+
+  public async getStreamPublicKey(): Promise<Uint8Array> {
+    // Group public must be the first command in the first block othwerwise it is malformed
+    if (this._blocks.length === 0 || this._blocks[0].commands.length === 0)
+      throw new Error("Empty CommandStream");
+    if (this._blocks[0].commands[0].getType() === CommandType.Seed) {
+      return (this._blocks[0].commands[0] as Seed).groupKey;
+    }
+    if (this._blocks[0].commands[0].getType() === CommandType.Derive) {
+      return (this._blocks[0].commands[0] as Derive).groupKey;
+    }
+    throw new Error("Malformed CommandStream");
+  }
+
+  get blocks(): CommandBlock[] {
+    return this._blocks;
+  }
+}

package/src/CommandStreamDecoder.ts

@@ -0,0 +1,142 @@
+import {
+  Command,
+  CommandBlock,
+  Seed,
+  AddMember,
+  CloseStream,
+  Derive,
+  EditMember,
+  PublishKey,
+  CommandType,
+} from "./CommandBlock";
+import { TLV, TLVField } from "./tlv";
+
+export const TLVCommandStreamDecoder = {
+  // Read command from TLV
+
+  readCommand: function (tlv: TLVField): Command {
+    switch (tlv.type) {
+      case CommandType.Seed:
+        return TLVCommandStreamDecoder.readSeedCommand(tlv.value);
+      case CommandType.Derive:
+        return TLVCommandStreamDecoder.readDeriveCommand(tlv.value);
+      case CommandType.AddMember:
+        return TLVCommandStreamDecoder.readAddMemberCommand(tlv.value);
+      case CommandType.PublishKey:
+        return TLVCommandStreamDecoder.readPublishKeyCommand(tlv.value);
+      case CommandType.EditMember:
+        return TLVCommandStreamDecoder.readEditMemberCommand(tlv.value);
+      case CommandType.CloseStream:
+        return TLVCommandStreamDecoder.readCloseStreamCommand(tlv.value);
+      default:
+        throw new Error("Unknown command type");
+    }
+  },
+
+  readSeedCommand: function (buffer: Uint8Array): Command {
+    const readTopic = TLV.readNullOr(TLV.readTLV(buffer, 0), TLV.readBytes);
+    const readProtocolVersion = TLV.readVarInt(TLV.readTLV(buffer, readTopic.offset));
+    const readGroupKey = TLV.readPublicKey(TLV.readTLV(buffer, readProtocolVersion.offset));
+    const readIV = TLV.readBytes(TLV.readTLV(buffer, readGroupKey.offset));
+    const readEncryptedXpriv = TLV.readBytes(TLV.readTLV(buffer, readIV.offset));
+    const readEphemeralPublicKey = TLV.readPublicKey(
+      TLV.readTLV(buffer, readEncryptedXpriv.offset),
+    );
+    return new Seed(
+      readTopic.value,
+      readProtocolVersion.value,
+      readGroupKey.value,
+      readIV.value,
+      readEncryptedXpriv.value,
+      readEphemeralPublicKey.value,
+    );
+  },
+
+  readDeriveCommand: function (buffer: Uint8Array): Command {
+    const readPath = TLV.readDerivationPath(TLV.readTLV(buffer, 0));
+    const readGroupKey = TLV.readPublicKey(TLV.readTLV(buffer, readPath.offset));
+    const readIV = TLV.readBytes(TLV.readTLV(buffer, readGroupKey.offset));
+    const readEncryptedXpriv = TLV.readBytes(TLV.readTLV(buffer, readIV.offset));
+    const readEphemeralPublicKey = TLV.readPublicKey(
+      TLV.readTLV(buffer, readEncryptedXpriv.offset),
+    );
+    return new Derive(
+      readPath.value,
+      readGroupKey.value,
+      readIV.value,
+      readEncryptedXpriv.value,
+      readEphemeralPublicKey.value,
+    );
+  },
+
+  readAddMemberCommand: function (buffer: Uint8Array): Command {
+    const readName = TLV.readString(TLV.readTLV(buffer, 0));
+    const pubkey = TLV.readPublicKey(TLV.readTLV(buffer, readName.offset));
+    const permissions = TLV.readVarInt(TLV.readTLV(buffer, pubkey.offset));
+    return new AddMember(readName.value, pubkey.value, permissions.value);
+  },
+
+  readPublishKeyCommand: function (buffer: Uint8Array): Command {
+    const IV = TLV.readBytes(TLV.readTLV(buffer, 0));
+    const encryptedXpriv = TLV.readBytes(TLV.readTLV(buffer, IV.offset));
+    const recipient = TLV.readPublicKey(TLV.readTLV(buffer, encryptedXpriv.offset));
+    const ephemeralPublicKey = TLV.readPublicKey(TLV.readTLV(buffer, recipient.offset));
+
+    return new PublishKey(
+      IV.value,
+      encryptedXpriv.value,
+      recipient.value,
+      ephemeralPublicKey.value,
+    );
+  },
+
+  readCloseStreamCommand: function (buffer: Uint8Array): Command {
+    buffer as Uint8Array;
+    return new CloseStream();
+  },
+
+  readEditMemberCommand: function (buffer: Uint8Array): Command {
+    const member = TLV.readPublicKey(TLV.readTLV(buffer, 0));
+    const permissions = TLV.readNullOr(TLV.readTLV(buffer, member.offset), TLV.readVarInt);
+    const name = TLV.readNullOr(TLV.readTLV(buffer, permissions.offset), TLV.readString);
+    return new EditMember(member.value, name.value, permissions.value);
+  },
+};
+
+function unpack(buffer: Uint8Array): CommandBlock[] {
+  const stream: CommandBlock[] = [];
+  let offset = 0;
+
+  while (offset < buffer.length) {
+    const version = TLV.readVarInt(TLV.readTLV(buffer, offset));
+    const parent = TLV.readHash(TLV.readTLV(buffer, version.offset));
+    const issuer = TLV.readPublicKey(TLV.readTLV(buffer, parent.offset));
+    const length = TLV.readVarInt(TLV.readTLV(buffer, issuer.offset));
+    offset = length.offset;
+
+    const commands: Command[] = [];
+    for (let index = 0; index < length.value; index++) {
+      const commandBuffer = TLV.readTLV(buffer, offset);
+      const command = TLVCommandStreamDecoder.readCommand(commandBuffer.tlv);
+      commands.push(command);
+      offset = commandBuffer.offset;
+    }
+
+    const signature = TLV.readSignature(TLV.readTLV(buffer, offset));
+    offset = signature.offset;
+    stream.push({
+      version: version.value,
+      parent: parent.value,
+      issuer: issuer.value,
+      commands,
+      signature: signature.value,
+    });
+  }
+  return stream;
+}
+
+export class CommandStreamDecoder {
+  public static decode(buffer: Uint8Array): CommandBlock[] {
+    return unpack(buffer);
+  }
+}