@bcts/seedtool-cli 1.0.0-alpha.14

package/src/formats/multipart.ts

@@ -0,0 +1,64 @@
+/**
+ * Multipart UR format
+ * Ported from seedtool-cli-rust/src/formats/multipart.rs
+ */
+
+import type { Cli } from "../cli.js";
+import type { InputFormat, OutputFormat } from "./format.js";
+import { Seed } from "../seed.js";
+import { Envelope } from "@bcts/envelope";
+import { MultipartEncoder, MultipartDecoder } from "@bcts/uniform-resources";
+
+/**
+ * Multipart UR format handler.
+ * Round-trippable: multipart URs → seed → multipart URs.
+ * Uses fountain encoding for reliable transmission.
+ */
+export class MultipartFormat implements InputFormat, OutputFormat {
+  name(): string {
+    return "multipart";
+  }
+
+  roundTrippable(): boolean {
+    return true;
+  }
+
+  processInput(state: Cli): Cli {
+    const input = state.expectInput();
+    const shares = input.split(/\s+/).filter((s) => s.length > 0);
+
+    const decoder = new MultipartDecoder();
+    for (const share of shares) {
+      decoder.receive(share);
+      if (decoder.isComplete()) {
+        break;
+      }
+    }
+
+    if (!decoder.isComplete()) {
+      throw new Error("Insufficient multipart shares");
+    }
+
+    const ur = decoder.message();
+    if (ur === undefined) {
+      throw new Error("Failed to decode multipart message");
+    }
+
+    const envelope = Envelope.fromUR(ur);
+    state.seed = Seed.fromEnvelope(envelope);
+    return state;
+  }
+
+  processOutput(state: Cli): string {
+    const ur = state.toEnvelope().ur();
+    const encoder = new MultipartEncoder(ur, state.maxFragmentLen);
+    const partsCount = encoder.partsCount() + state.additionalParts;
+
+    const parts: string[] = [];
+    for (let i = 0; i < partsCount; i++) {
+      parts.push(encoder.nextPart());
+    }
+
+    return parts.join("\n");
+  }
+}

package/src/formats/random.ts

@@ -0,0 +1,28 @@
+/**
+ * Random format
+ * Ported from seedtool-cli-rust/src/formats/random.rs
+ */
+
+import type { Cli } from "../cli.js";
+import type { InputFormat } from "./format.js";
+import { Seed } from "../seed.js";
+
+/**
+ * Random seed generation format.
+ * Input-only: generates a new random seed.
+ */
+export class RandomFormat implements InputFormat {
+  name(): string {
+    return "random";
+  }
+
+  roundTrippable(): boolean {
+    return true;
+  }
+
+  processInput(state: Cli): Cli {
+    const data = state.randomData(state.count);
+    state.seed = Seed.new(data);
+    return state;
+  }
+}

package/src/formats/seed-format.ts

@@ -0,0 +1,37 @@
+/**
+ * Seed UR format
+ * Ported from seedtool-cli-rust/src/formats/seed.rs
+ */
+
+import type { Cli } from "../cli.js";
+import type { InputFormat, OutputFormat } from "./format.js";
+import { Seed } from "../seed.js";
+import { Seed as ComponentsSeed } from "@bcts/components";
+
+/**
+ * Seed UR format handler.
+ * Round-trippable: seed UR → seed → seed UR.
+ * Uses the ur:seed format from bc-components.
+ */
+export class SeedFormat implements InputFormat, OutputFormat {
+  name(): string {
+    return "seed";
+  }
+
+  roundTrippable(): boolean {
+    return true;
+  }
+
+  processInput(state: Cli): Cli {
+    const input = state.expectInput();
+    const componentsSeed = ComponentsSeed.fromURString(input);
+    state.seed = Seed.fromComponentsSeed(componentsSeed);
+    return state;
+  }
+
+  processOutput(state: Cli): string {
+    const seed = state.seedWithOverrides();
+    const componentsSeed = seed.toComponentsSeed();
+    return componentsSeed.urString();
+  }
+}

package/src/formats/sskr.ts

@@ -0,0 +1,290 @@
+/**
+ * SSKR format
+ * Ported from seedtool-cli-rust/src/formats/sskr.rs
+ */
+
+import type { Cli, SSKRFormatKey } from "../cli.js";
+import type { InputFormat, OutputFormat } from "./format.js";
+import { Seed } from "../seed.js";
+import { Envelope } from "@bcts/envelope";
+import { SymmetricKey } from "@bcts/envelope";
+import { SSKRShare, SSKRShareCbor, SSKRSecret, sskrGenerate, sskrCombine } from "@bcts/components";
+import { encodeBytewords, decodeBytewords, BytewordsStyle, UR } from "@bcts/uniform-resources";
+import { SSKR_SHARE, SSKR_SHARE_V1 } from "@bcts/tags";
+import { toByteString, toTaggedValue, decodeCbor, expectBytes } from "@bcts/dcbor";
+
+/**
+ * SSKR format handler.
+ * Round-trippable: sskr shares → seed → sskr shares.
+ * Supports multiple sub-formats: envelope, btw, btwm, btwu, ur.
+ */
+export class SSKRFormat implements InputFormat, OutputFormat {
+  name(): string {
+    return "sskr";
+  }
+
+  roundTrippable(): boolean {
+    return true;
+  }
+
+  processInput(state: Cli): Cli {
+    const input = state.expectInput();
+    state.seed = parseSskrSeed(input);
+    return state;
+  }
+
+  processOutput(state: Cli): string {
+    const spec = state.sskrSpec();
+    const seed = state.expectSeed();
+    const format = state.sskrFormat;
+    return outputSskrSeed(seed, spec, format);
+  }
+}
+
+//
+// Output Helpers
+//
+
+function outputSskrSeed(
+  seed: Seed,
+  spec: import("@bcts/sskr").Spec,
+  format: SSKRFormatKey,
+): string {
+  switch (format) {
+    case "envelope": {
+      const envelope = seed.toEnvelope();
+      const contentKey = SymmetricKey.new();
+      const encryptedEnvelope = envelope.wrap().encryptSubject(contentKey);
+      const shareEnvelopes = encryptedEnvelope.sskrSplitFlattened(spec, contentKey);
+      const shareEnvelopesStrings = shareEnvelopes.map((envelope) => envelope.urString());
+      return shareEnvelopesStrings.join("\n");
+    }
+    case "btw": {
+      return makeBytewordsShares(spec, seed, BytewordsStyle.Standard);
+    }
+    case "btwm": {
+      return makeBytewordsShares(spec, seed, BytewordsStyle.Minimal);
+    }
+    case "btwu": {
+      return makeBytewordsShares(spec, seed, BytewordsStyle.Uri);
+    }
+    case "ur": {
+      const shares = makeShares(spec, seed);
+      const urStrings = shares.map((share) => {
+        const ur = UR.fromCbor("sskr", toByteString(share.asBytes()));
+        return ur.toString();
+      });
+      return urStrings.join("\n");
+    }
+  }
+}
+
+function makeShares(spec: import("@bcts/sskr").Spec, seed: Seed): SSKRShareCbor[] {
+  const secret = SSKRSecret.new(seed.data());
+  const shareGroups = sskrGenerate(spec, secret);
+  const flatShares: SSKRShareCbor[] = [];
+  for (const group of shareGroups) {
+    for (const shareData of group) {
+      flatShares.push(SSKRShare.fromData(shareData));
+    }
+  }
+  return flatShares;
+}
+
+function makeBytewordsShares(
+  spec: import("@bcts/sskr").Spec,
+  seed: Seed,
+  style: BytewordsStyle,
+): string {
+  const shares = makeShares(spec, seed);
+  const cborShares = shares.map((share) =>
+    toTaggedValue(SSKR_SHARE.value, toByteString(share.asBytes())),
+  );
+  const sharesStrings = cborShares.map((share) => encodeBytewords(share.toData(), style));
+  return sharesStrings.join("\n");
+}
+
+//
+// Input Helpers
+//
+
+function parseEnvelopes(input: string): Seed | null {
+  try {
+    const shareStrings = input.split(/\s+/).filter((s) => s.length > 0);
+    const shareEnvelopes: Envelope[] = [];
+    for (const str of shareStrings) {
+      try {
+        const envelope = Envelope.fromURString(str);
+        shareEnvelopes.push(envelope);
+      } catch {
+        // Skip non-envelope strings
+      }
+    }
+
+    if (shareEnvelopes.length === 0) {
+      return null;
+    }
+
+    const recoveredEnvelope = Envelope.sskrJoin(shareEnvelopes).unwrap();
+    return Seed.fromEnvelope(recoveredEnvelope);
+  } catch {
+    return null;
+  }
+}
+
+function fromUntaggedCborShares(untaggedCborShares: Uint8Array[]): Seed | null {
+  try {
+    const recoveredSecret = sskrCombine(untaggedCborShares);
+    return Seed.new(recoveredSecret.getData());
+  } catch {
+    return null;
+  }
+}
+
+function fromTaggedCborShares(taggedCborDataShares: Uint8Array[]): Seed | null {
+  try {
+    const untaggedShares: Uint8Array[] = [];
+    for (const data of taggedCborDataShares) {
+      const cbor = decodeCbor(data);
+      // Extract the tagged value and ensure it's the expected tag
+      const tagged = cbor as { tag?: number; value?: unknown };
+      if (tagged.tag !== SSKR_SHARE.value && tagged.tag !== SSKR_SHARE_V1.value) {
+        return null;
+      }
+      const content = (tagged.value as { buffer?: Uint8Array }) || cbor;
+      const bytes = expectBytes(content as ReturnType<typeof decodeCbor>);
+      untaggedShares.push(bytes);
+    }
+    return fromUntaggedCborShares(untaggedShares);
+  } catch {
+    return null;
+  }
+}
+
+function parseBytewords(input: string, style: BytewordsStyle): Seed | null {
+  try {
+    // Standard bytewords include spaces, so we can only split on newlines.
+    let shareStrings: string[];
+    if (style === BytewordsStyle.Standard) {
+      shareStrings = input.split("\n").filter((s) => s.length > 0);
+    } else {
+      shareStrings = input.split(/\s+/).filter((s) => s.length > 0);
+    }
+
+    const cborDataShares: Uint8Array[] = [];
+    for (const s of shareStrings) {
+      try {
+        const decoded = decodeBytewords(s, style);
+        cborDataShares.push(decoded);
+      } catch {
+        // Skip invalid bytewords
+      }
+    }
+
+    if (cborDataShares.length === 0) {
+      return null;
+    }
+
+    return fromTaggedCborShares(cborDataShares);
+  } catch {
+    return null;
+  }
+}
+
+function parseUr(input: string, expectedTagValue: number, allowTaggedCbor: boolean): Seed | null {
+  try {
+    // Get the expected type name
+    const expectedType = expectedTagValue === SSKR_SHARE.value ? "sskr" : "crypto-sskr";
+
+    const shareStrings = input.split(/\s+/).filter((s) => s.length > 0);
+    const urs: UR[] = [];
+
+    for (const str of shareStrings) {
+      try {
+        const ur = UR.fromURString(str);
+        urs.push(ur);
+      } catch {
+        // Skip non-UR strings
+      }
+    }
+
+    if (urs.length === 0) {
+      return null;
+    }
+
+    // Ensure every UR is of the expected type
+    for (const ur of urs) {
+      if (ur.type() !== expectedType) {
+        return null;
+      }
+    }
+
+    const untaggedCborShares: Uint8Array[] = [];
+    for (const ur of urs) {
+      let cbor = ur.cbor();
+
+      // Legacy SSKR shares might have tagged CBOR, even though they're
+      // URs so they shouldn't be.
+      if (allowTaggedCbor) {
+        try {
+          const decoded = decodeCbor(cbor.toData());
+          const tagged = decoded as { tag?: number; value?: unknown };
+          if (tagged.tag === SSKR_SHARE.value || tagged.tag === SSKR_SHARE_V1.value) {
+            const content = tagged.value as { buffer?: Uint8Array };
+            cbor = content as unknown as ReturnType<typeof toByteString>;
+          }
+        } catch {
+          // Not tagged CBOR, use as-is
+        }
+      }
+
+      // The CBOR should be a byte string
+      const bytes = expectBytes(cbor);
+      untaggedCborShares.push(bytes);
+    }
+
+    return fromUntaggedCborShares(untaggedCborShares);
+  } catch {
+    return null;
+  }
+}
+
+function parseSskrSeed(input: string): Seed {
+  // Try envelope format first
+  const envelopeResult = parseEnvelopes(input);
+  if (envelopeResult !== null) {
+    return envelopeResult;
+  }
+
+  // Try bytewords standard format
+  const btwResult = parseBytewords(input, BytewordsStyle.Standard);
+  if (btwResult !== null) {
+    return btwResult;
+  }
+
+  // Try bytewords minimal format
+  const btwmResult = parseBytewords(input, BytewordsStyle.Minimal);
+  if (btwmResult !== null) {
+    return btwmResult;
+  }
+
+  // Try bytewords uri format
+  const btwuResult = parseBytewords(input, BytewordsStyle.Uri);
+  if (btwuResult !== null) {
+    return btwuResult;
+  }
+
+  // Try UR format (current tag)
+  const urResult = parseUr(input, SSKR_SHARE.value, false);
+  if (urResult !== null) {
+    return urResult;
+  }
+
+  // Try legacy UR format (v1 tag, allow tagged cbor)
+  const urLegacyResult = parseUr(input, SSKR_SHARE_V1.value, true);
+  if (urLegacyResult !== null) {
+    return urLegacyResult;
+  }
+
+  throw new Error("Insufficient or invalid SSKR shares.");
+}

package/src/index.ts

@@ -0,0 +1,44 @@
+/**
+ * seedtool-cli
+ * A tool for generating and transforming cryptographic seeds.
+ * Ported from seedtool-cli-rust
+ */
+
+// Re-export CLI types
+export {
+  Cli,
+  InputFormatKey,
+  OutputFormatKey,
+  SSKRFormatKey,
+  type RngSource,
+  parseLowInt,
+  parseHighInt,
+  parseGroupThreshold,
+  parseDate,
+  parseGroupSpec,
+} from "./cli.js";
+
+// Re-export Seed type
+export { Seed } from "./seed.js";
+
+// Re-export random utilities
+export {
+  DeterministicRandomNumberGenerator,
+  hkdfHmacSha256,
+  sha256DeterministicRandom,
+  deterministicRandom,
+} from "./random.js";
+
+// Re-export utility functions
+export {
+  dataToHex,
+  hexToData,
+  dataToBase,
+  dataToAlphabet,
+  parseInts,
+  dataToInts,
+  digitsToData,
+} from "./util.js";
+
+// Re-export formats
+export * from "./formats/index.js";

package/src/main.ts

@@ -0,0 +1,227 @@
+/**
+ * A tool for generating and transforming cryptographic seeds.
+ * Ported from seedtool-cli-rust/src/main.rs
+ */
+
+import { Command, Option } from "commander";
+import { SecureRandomNumberGenerator } from "@bcts/rand";
+import { SSKRGroupSpec } from "@bcts/components";
+import { Cli, type InputFormatKey, type OutputFormatKey, type SSKRFormatKey } from "./cli.js";
+import { selectInputFormat, selectOutputFormat } from "./formats/index.js";
+import { DeterministicRandomNumberGenerator } from "./random.js";
+import * as fs from "node:fs";
+
+const VERSION = "0.4.0";
+
+function parseLowInt(value: string): number {
+  const num = parseInt(value, 10);
+  if (isNaN(num) || num < 0 || num > 254) {
+    throw new Error("LOW must be between 0 and 254");
+  }
+  return num;
+}
+
+function parseHighInt(value: string): number {
+  const num = parseInt(value, 10);
+  if (isNaN(num) || num < 1 || num > 255) {
+    throw new Error("HIGH must be between 1 and 255");
+  }
+  return num;
+}
+
+function parseGroupThreshold(value: string): number {
+  const num = parseInt(value, 10);
+  if (isNaN(num) || num < 1 || num > 16) {
+    throw new Error("THRESHOLD must be between 1 and 16");
+  }
+  return num;
+}
+
+function parseCliDate(value: string): Date {
+  if (value === "now") {
+    return new Date();
+  }
+  const date = new Date(value);
+  if (isNaN(date.getTime())) {
+    throw new Error(`Invalid date: ${value}. Use ISO-8601 format or 'now'.`);
+  }
+  return date;
+}
+
+function parseGroupSpec(value: string, previous: SSKRGroupSpec[]): SSKRGroupSpec[] {
+  const spec = SSKRGroupSpec.parse(value);
+  return [...previous, spec];
+}
+
+async function main(): Promise<void> {
+  const program = new Command();
+
+  program
+    .name("seedtool")
+    .description(
+      "A tool for generating and transforming cryptographic seeds.\n\n" +
+        "by Wolf McNally and Christopher Allen\n\n" +
+        "Report bugs to ChristopherA@BlockchainCommons.com.\n" +
+        "© 2024 Blockchain Commons.",
+    )
+    .version(VERSION)
+    .argument(
+      "[INPUT]",
+      "The input to be transformed. If required and not present, it will be read from stdin.",
+    )
+    .option(
+      "-c, --count <COUNT>",
+      "The number of output units (hex bytes, base-10 digits, etc.)",
+      "16",
+    )
+    .addOption(
+      new Option(
+        "-i, --in <INPUT_TYPE>",
+        "The input format. If not specified, a new random seed is generated using a secure random number generator.",
+      )
+        .choices([
+          "random",
+          "hex",
+          "btw",
+          "btwm",
+          "btwu",
+          "bits",
+          "cards",
+          "dice",
+          "base6",
+          "base10",
+          "ints",
+          "bip39",
+          "sskr",
+          "envelope",
+          "seed",
+          "multipart",
+        ])
+        .default("random"),
+    )
+    .addOption(
+      new Option("-o, --out <OUTPUT_TYPE>", "The output format.")
+        .choices([
+          "hex",
+          "btw",
+          "btwm",
+          "btwu",
+          "bits",
+          "cards",
+          "dice",
+          "base6",
+          "base10",
+          "ints",
+          "bip39",
+          "sskr",
+          "envelope",
+          "seed",
+          "multipart",
+        ])
+        .default("hex"),
+    )
+    .option("--low <LOW>", "The lowest int returned (0-254)", parseLowInt, 0)
+    .option("--high <HIGH>", "The highest int returned (1-255), low < high", parseHighInt, 9)
+    .option("--name <NAME>", "The name of the seed.")
+    .option("--note <NOTE>", "The note associated with the seed.")
+    .option("--date <DATE>", "The seed's creation date, in ISO-8601 format. May also be `now`.")
+    .option(
+      "--max-fragment-len <MAX_FRAG_LEN>",
+      "For `multipart` output, the UR will be segmented into parts with fragments no larger than MAX_FRAG_LEN",
+      "500",
+    )
+    .option(
+      "--additional-parts <NUM_PARTS>",
+      "For `multipart` output, the number of additional parts above the minimum to generate using fountain encoding.",
+      "0",
+    )
+    .option(
+      "-g, --groups <M-of-N>",
+      "Group specifications. May appear more than once. M must be < N",
+      parseGroupSpec,
+      [],
+    )
+    .option(
+      "-t, --group-threshold <THRESHOLD>",
+      "The number of groups that must meet their threshold. Must be <= the number of group specifications.",
+      parseGroupThreshold,
+      1,
+    )
+    .addOption(
+      new Option("-s, --sskr-format <SSKR_FORMAT>", "SSKR output format.")
+        .choices(["envelope", "btw", "btwm", "btwu", "ur"])
+        .default("envelope"),
+    )
+    .option(
+      "-d, --deterministic <SEED_STRING>",
+      "Use a deterministic random number generator with the given seed string. Output generated from this seed will be the same every time, so generated seeds are only as secure as the seed string.",
+    );
+
+  program.parse();
+
+  const options = program.opts();
+  const args = program.args;
+
+  // Create the CLI state
+  const cli = new Cli();
+
+  // Set input from argument or stdin
+  if (args.length > 0) {
+    cli.input = args[0];
+  } else if (!process.stdin.isTTY) {
+    // Read from stdin if it's piped
+    cli.input = fs.readFileSync(0, "utf-8").trim();
+  }
+
+  // Set options
+  cli.count = parseInt(options.count, 10);
+  cli.in = options.in as InputFormatKey;
+  cli.out = options.out as OutputFormatKey;
+  cli.low = options.low;
+  cli.high = options.high;
+  cli.name = options.name;
+  cli.note = options.note;
+  if (options.date) {
+    cli.date = parseCliDate(options.date);
+  }
+  cli.maxFragmentLen = parseInt(options.maxFragmentLen, 10);
+  cli.additionalParts = parseInt(options.additionalParts, 10);
+  cli.groups = options.groups;
+  cli.groupThreshold = options.groupThreshold;
+  cli.sskrFormat = options.sskrFormat as SSKRFormatKey;
+
+  // Set up RNG
+  if (options.deterministic) {
+    cli.rng = {
+      type: "deterministic",
+      rng: DeterministicRandomNumberGenerator.newWithSeed(options.deterministic),
+    };
+  } else {
+    cli.rng = {
+      type: "secure",
+      rng: new SecureRandomNumberGenerator(),
+    };
+  }
+
+  // Get formats
+  const inputFormat = selectInputFormat(cli.in);
+  const outputFormat = selectOutputFormat(cli.out);
+
+  // Validate round-trippability
+  if (!outputFormat.roundTrippable() && inputFormat.name() !== "random") {
+    console.error(`Input for output form "${outputFormat.name()}" must be random.`);
+    process.exit(1);
+  }
+
+  // Process input
+  const processedCli = inputFormat.processInput(cli);
+
+  // Process output
+  const output = outputFormat.processOutput(processedCli);
+  console.log(output);
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exit(1);
+});