@ternent/core 0.0.1

package/packages/seal/src/cli.ts

@@ -0,0 +1,372 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createManifestArtifact } from "./commands/manifest";
+import { createIdentityArtifact } from "./commands/identity";
+import { createProofArtifact, createRecipientArtifact } from "./commands/sign";
+import { createPublicKeyArtifact } from "./commands/publicKey";
+import { verifyArtifactProof, verifyProofArtifact } from "./commands/verify";
+import { resolveSealIdentityFromEnv } from "./node";
+import {
+  EXIT_FAILURE,
+  EXIT_HASH_MISMATCH,
+  EXIT_INVALID_PROOF,
+  EXIT_KEY_CONFIG,
+  EXIT_SIGNATURE_INVALID,
+  EXIT_SUCCESS,
+  SealCliError,
+  getExitCode,
+} from "./errors";
+
+type ProcessEnvLike = Record<string, string | undefined>;
+
+declare const process: {
+  argv: string[];
+  env: ProcessEnvLike;
+  stdout: { write: (value: string) => void };
+  stderr: { write: (value: string) => void };
+  exitCode?: number;
+};
+
+type ParsedArgs = {
+  _: string[];
+  flags: Record<string, string | boolean | string[]>;
+};
+
+type OutputWriter = {
+  stdout: (value: string) => void;
+  stderr: (value: string) => void;
+};
+
+function parseArgs(argv: string[]): ParsedArgs {
+  const result: ParsedArgs = { _: [], flags: {} };
+  for (let index = 0; index < argv.length; index += 1) {
+    const arg = argv[index];
+    if (!arg.startsWith("--")) {
+      result._.push(arg);
+      continue;
+    }
+
+    const [rawKey, inlineValue] = arg.slice(2).split("=");
+    const key = rawKey.trim();
+    const next = argv[index + 1];
+    const hasNextValue = inlineValue === undefined && next && !next.startsWith("--");
+    const value = inlineValue ?? (hasNextValue ? next : undefined);
+
+    if (hasNextValue) {
+      index += 1;
+    }
+
+    if (value === undefined) {
+      result.flags[key] = true;
+      continue;
+    }
+
+    const existing = result.flags[key];
+    if (existing === undefined) {
+      result.flags[key] = value;
+      continue;
+    }
+
+    if (Array.isArray(existing)) {
+      existing.push(value);
+      result.flags[key] = existing;
+      continue;
+    }
+
+    result.flags[key] = [String(existing), value];
+  }
+
+  return result;
+}
+
+function getFlag(flags: ParsedArgs["flags"], key: string): string | undefined {
+  const value = flags[key];
+  if (Array.isArray(value)) {
+    return value[value.length - 1];
+  }
+  return typeof value === "string" ? value : undefined;
+}
+
+function getFlags(flags: ParsedArgs["flags"], key: string): string[] {
+  const value = flags[key];
+  if (Array.isArray(value)) {
+    return value.map(String);
+  }
+  if (typeof value === "string") {
+    return [value];
+  }
+  return [];
+}
+
+function hasFlag(flags: ParsedArgs["flags"], key: string): boolean {
+  return flags[key] === true;
+}
+
+function requireFlag(flags: ParsedArgs["flags"], key: string): string {
+  const value = getFlag(flags, key);
+  if (!value) {
+    throw new SealCliError(`Missing --${key}`, EXIT_FAILURE);
+  }
+  return value;
+}
+
+function parseMnemonicWordCount(flags: ParsedArgs["flags"]): 12 | 24 | undefined {
+  const words = getFlag(flags, "words");
+  if (!words) {
+    return undefined;
+  }
+  if (words === "12" || words === "24") {
+    return Number(words) as 12 | 24;
+  }
+  throw new SealCliError("Mnemonic word count must be 12 or 24.", EXIT_FAILURE);
+}
+
+async function writeOutputFile(filePath: string, content: string): Promise<void> {
+  const resolvedPath = resolve(filePath);
+  await mkdir(dirname(resolvedPath), { recursive: true });
+  await writeFile(resolvedPath, content, "utf8");
+}
+
+function outputResult(writer: OutputWriter, json: boolean, quiet: boolean, value: unknown): void {
+  if (quiet) {
+    return;
+  }
+
+  if (typeof value === "string") {
+    writer.stdout(`${value}\n`);
+    return;
+  }
+
+  if (json) {
+    writer.stdout(`${JSON.stringify(value, null, 2)}\n`);
+    return;
+  }
+
+  writer.stdout(`${JSON.stringify(value, null, 2)}\n`);
+}
+
+function outputError(writer: OutputWriter, json: boolean, error: unknown): number {
+  const exitCode = getExitCode(error);
+  const message = error instanceof Error ? error.message : String(error);
+  if (json) {
+    writer.stderr(`${JSON.stringify({ error: message, exitCode }, null, 2)}\n`);
+  } else {
+    writer.stderr(`${message}\n`);
+  }
+  return exitCode;
+}
+
+export async function runCli(
+  argv: string[],
+  params: {
+    env?: ProcessEnvLike;
+    writer?: OutputWriter;
+  } = {},
+): Promise<number> {
+  const parsed = parseArgs(argv);
+  const env = params.env ?? process.env;
+  const writer: OutputWriter = params.writer ?? {
+    stdout: (value) => process.stdout.write(value),
+    stderr: (value) => process.stderr.write(value),
+  };
+  const json = hasFlag(parsed.flags, "json");
+  const quiet = hasFlag(parsed.flags, "quiet");
+
+  try {
+    const [command, subcommand] = parsed._;
+
+    if (command === "identity" && subcommand === "create") {
+      const mnemonicOutPath = getFlag(parsed.flags, "mnemonic-out");
+      const artifact = await createIdentityArtifact({
+        withMnemonic: Boolean(mnemonicOutPath),
+        words: parseMnemonicWordCount(parsed.flags),
+        passphrase: getFlag(parsed.flags, "passphrase"),
+      });
+      const outPath = getFlag(parsed.flags, "out");
+      if (outPath) {
+        await writeOutputFile(outPath, artifact.content);
+      }
+      if (mnemonicOutPath) {
+        await writeOutputFile(mnemonicOutPath, artifact.mnemonicContent || "");
+      }
+
+      if (outPath) {
+        outputResult(
+          writer,
+          json,
+          quiet,
+          json
+            ? artifact.mnemonic
+              ? {
+                  identity: artifact.identity,
+                  mnemonic: artifact.mnemonic,
+                  mnemonicFile: mnemonicOutPath || null,
+                }
+              : artifact.identity
+            : outPath,
+        );
+      } else {
+        outputResult(
+          writer,
+          true,
+          quiet,
+          artifact.mnemonic
+            ? {
+                identity: artifact.identity,
+                mnemonic: artifact.mnemonic,
+                mnemonicFile: mnemonicOutPath || null,
+              }
+            : artifact.identity,
+        );
+      }
+      return EXIT_SUCCESS;
+    }
+
+    if (command === "manifest" && subcommand === "create") {
+      const artifact = await createManifestArtifact(requireFlag(parsed.flags, "input"));
+      const outPath = getFlag(parsed.flags, "out");
+      if (outPath) {
+        await writeOutputFile(outPath, artifact.content);
+        outputResult(writer, json, quiet, json ? artifact.manifest : outPath);
+      } else {
+        outputResult(writer, true, quiet, artifact.manifest);
+      }
+      return EXIT_SUCCESS;
+    }
+
+    if (command === "sign") {
+      const identity = await resolveSealIdentityFromEnv(env);
+      const recipients = getFlags(parsed.flags, "recipient");
+      const inputPath = requireFlag(parsed.flags, "input");
+      const outPath = getFlag(parsed.flags, "out");
+      if (recipients.length > 0) {
+        const artifact = await createRecipientArtifact({
+          inputPath,
+          identity,
+          recipients,
+        });
+        if (outPath) {
+          await writeOutputFile(outPath, artifact.content);
+          outputResult(writer, json, quiet, json ? artifact.artifact : outPath);
+        } else {
+          outputResult(writer, true, quiet, artifact.artifact);
+        }
+      } else {
+        const artifact = await createProofArtifact({
+          inputPath,
+          identity,
+        });
+        if (outPath) {
+          await writeOutputFile(outPath, artifact.content);
+          outputResult(writer, json, quiet, json ? artifact.proof : outPath);
+        } else {
+          outputResult(writer, true, quiet, artifact.proof);
+        }
+      }
+      return EXIT_SUCCESS;
+    }
+
+    if (command === "verify") {
+      const artifactPath = getFlag(parsed.flags, "artifact");
+      if (artifactPath) {
+        const { result } = await verifyArtifactProof({ artifactPath });
+        outputResult(
+          writer,
+          json,
+          quiet,
+          json
+            ? result
+            : [
+                `valid=${result.valid}`,
+                `hashMatch=${result.hashMatch}`,
+                `signatureValid=${result.signatureValid}`,
+                `encrypted=${result.encrypted}`,
+                `payloadScheme=${result.payloadScheme}`,
+                `payloadMode=${result.payloadMode}`,
+                `keyId=${result.keyId}`,
+                `algorithm=${result.algorithm}`,
+                `subjectHash=${result.subjectHash}`,
+              ].join("\n"),
+        );
+
+        if (!result.hashMatch) {
+          return EXIT_HASH_MISMATCH;
+        }
+        if (!result.signatureValid) {
+          return EXIT_SIGNATURE_INVALID;
+        }
+        return EXIT_SUCCESS;
+      }
+
+      const proofPath = requireFlag(parsed.flags, "proof");
+      const inputPath = requireFlag(parsed.flags, "input");
+      const { result } = await verifyProofArtifact({ proofPath, inputPath });
+      outputResult(
+        writer,
+        json,
+        quiet,
+        json
+          ? result
+          : [
+              `valid=${result.valid}`,
+              `hashMatch=${result.hashMatch}`,
+              `signatureValid=${result.signatureValid}`,
+              `keyId=${result.keyId}`,
+              `algorithm=${result.algorithm}`,
+              `subjectHash=${result.subjectHash}`,
+            ].join("\n"),
+      );
+
+      if (!result.hashMatch) {
+        return EXIT_HASH_MISMATCH;
+      }
+      if (!result.signatureValid) {
+        return EXIT_SIGNATURE_INVALID;
+      }
+      return EXIT_SUCCESS;
+    }
+
+    if (command === "public-key") {
+      const artifact = await createPublicKeyArtifact({
+        identity: await resolveSealIdentityFromEnv(env),
+      });
+      outputResult(writer, true, quiet, artifact);
+      return EXIT_SUCCESS;
+    }
+
+    throw new SealCliError(
+      "Usage: seal identity create [--out <path>] [--words 12|24] [--passphrase <value>] [--mnemonic-out <path>] [--json] [--quiet]\n" +
+        "       seal manifest create --input <path> [--out <path>] [--json] [--quiet]\n" +
+        "       seal sign --input <path> [--recipient <age...>] [--out <path>] [--json] [--quiet]\n" +
+        "       seal verify --proof <proof.json> --input <path> [--json] [--quiet]\n" +
+        "       seal verify --artifact <artifact.json> [--json] [--quiet]\n" +
+        "       seal public-key [--json] [--quiet]",
+      EXIT_FAILURE,
+    );
+  } catch (error) {
+    if (error instanceof Error && error.message.includes("Proof")) {
+      return outputError(writer, json, new SealCliError(error.message, EXIT_INVALID_PROOF));
+    }
+    if (
+      error instanceof Error &&
+      (error.message.includes("public key") ||
+        error.message.includes("SEAL_IDENTITY") ||
+        error.message.includes("identity"))
+    ) {
+      return outputError(writer, json, new SealCliError(error.message, EXIT_KEY_CONFIG));
+    }
+    return outputError(writer, json, error);
+  }
+}
+
+const isDirectRun =
+  typeof process !== "undefined" &&
+  process.argv[1] &&
+  fileURLToPath(import.meta.url) === resolve(process.argv[1]);
+
+if (isDirectRun) {
+  runCli(process.argv.slice(2)).then((exitCode) => {
+    process.exitCode = exitCode;
+  });
+}

package/packages/seal/src/commands/identity.ts

@@ -0,0 +1,52 @@
+import { createSealIdentity, createSealMnemonicIdentity, exportIdentityJson } from "../crypto";
+
+function formatMnemonicBackup(input: { mnemonic: string; passphrase?: string }): string {
+  const lines = ["Seal seed phrase backup", "", "Mnemonic:", input.mnemonic];
+  if (String(input.passphrase || "").trim()) {
+    lines.push("", "Passphrase:", String(input.passphrase));
+  }
+  lines.push(
+    "",
+    "Store this file securely. Anyone with this recovery material can recreate the signer.",
+  );
+  return `${lines.join("\n")}\n`;
+}
+
+export async function createIdentityArtifact(
+  input: {
+    withMnemonic?: boolean;
+    words?: 12 | 24;
+    passphrase?: string;
+  } = {},
+): Promise<{
+  identity: import("@ternent/identity").SerializedIdentity;
+  content: string;
+  mnemonic: string | null;
+  mnemonicContent: string | null;
+}> {
+  const useMnemonic =
+    Boolean(input.withMnemonic) ||
+    input.words === 12 ||
+    input.words === 24 ||
+    Boolean(input.passphrase);
+  const created = useMnemonic
+    ? await createSealMnemonicIdentity({
+        words: input.words,
+        passphrase: input.passphrase,
+      })
+    : {
+        identity: await createSealIdentity(),
+        mnemonic: null,
+      };
+  return {
+    identity: created.identity,
+    content: exportIdentityJson(created.identity),
+    mnemonic: created.mnemonic,
+    mnemonicContent: created.mnemonic
+      ? formatMnemonicBackup({
+          mnemonic: created.mnemonic,
+          passphrase: input.passphrase,
+        })
+      : null,
+  };
+}

package/packages/seal/src/commands/manifest.ts

@@ -0,0 +1,71 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import { basename, join, relative, resolve } from "node:path";
+import { createSealHash } from "../proof";
+import {
+  SEAL_MANIFEST_TYPE,
+  SEAL_MANIFEST_VERSION,
+  stringifySealManifest,
+  type SealManifestV1,
+} from "../manifest";
+
+function normalizeRelativePath(value: string): string {
+  return value.split("\\").join("/");
+}
+
+async function collectFiles(
+  rootPath: string,
+  currentPath: string,
+  files: Record<string, SealManifestV1["files"][string]>,
+): Promise<void> {
+  const entries = await readdir(currentPath, { withFileTypes: true });
+  const sorted = entries
+    .filter((entry) => entry.name !== ".DS_Store")
+    .sort((a, b) => a.name.localeCompare(b.name));
+
+  for (const entry of sorted) {
+    const entryPath = join(currentPath, entry.name);
+    if (entry.isDirectory()) {
+      await collectFiles(rootPath, entryPath, files);
+      continue;
+    }
+    if (!entry.isFile()) {
+      continue;
+    }
+    const bytes = await readFile(entryPath);
+    const relativePath = normalizeRelativePath(relative(rootPath, entryPath));
+    files[relativePath] = await createSealHash(bytes);
+  }
+}
+
+export async function createManifestArtifact(inputPath: string): Promise<{
+  manifest: SealManifestV1;
+  content: string;
+}> {
+  const resolvedInput = resolve(inputPath);
+  const inputStat = await stat(resolvedInput);
+  const root = basename(resolvedInput);
+  const files: SealManifestV1["files"] = {};
+
+  if (inputStat.isDirectory()) {
+    await collectFiles(resolvedInput, resolvedInput, files);
+  } else if (inputStat.isFile()) {
+    const bytes = await readFile(resolvedInput);
+    files[root] = await createSealHash(bytes);
+  } else {
+    throw new Error("Manifest input must be a file or directory.");
+  }
+
+  const manifest: SealManifestV1 = {
+    version: SEAL_MANIFEST_VERSION,
+    type: SEAL_MANIFEST_TYPE,
+    root,
+    files: Object.fromEntries(
+      Object.entries(files).sort(([left], [right]) => left.localeCompare(right)),
+    ),
+  };
+
+  return {
+    manifest,
+    content: `${stringifySealManifest(manifest)}\n`,
+  };
+}

package/packages/seal/src/commands/publicKey.ts

@@ -0,0 +1,7 @@
+import { createSealPublicKeyArtifact } from "../proof";
+
+export async function createPublicKeyArtifact(params: {
+  identity: import("@ternent/identity").SerializedIdentity;
+}) {
+  return createSealPublicKeyArtifact(params);
+}

package/packages/seal/src/commands/sign.ts

@@ -0,0 +1,56 @@
+import { basename } from "node:path";
+import { readFile } from "node:fs/promises";
+import { createSealArtifact, type SealArtifactV1 } from "../artifact";
+import { parseSealManifestJson } from "../manifest";
+import { createSealProof, createSealHash, type SealProofV1 } from "../proof";
+
+export async function createProofArtifact(params: {
+  inputPath: string;
+  identity: import("@ternent/identity").SerializedIdentity;
+}): Promise<{
+  proof: SealProofV1;
+  content: string;
+}> {
+  const bytes = await readFile(params.inputPath);
+  const raw = new TextDecoder().decode(bytes);
+  const parsedManifest = parseSealManifestJson(raw);
+  const proof = await createSealProof({
+    signer: {
+      identity: params.identity,
+    },
+    subject: {
+      kind: parsedManifest.ok ? "manifest" : "file",
+      path: basename(params.inputPath),
+      hash: await createSealHash(bytes),
+    },
+  });
+
+  return {
+    proof,
+    content: `${JSON.stringify(proof, null, 2)}\n`,
+  };
+}
+
+export async function createRecipientArtifact(params: {
+  inputPath: string;
+  identity: import("@ternent/identity").SerializedIdentity;
+  recipients: string[];
+}): Promise<{
+  artifact: SealArtifactV1;
+  content: string;
+}> {
+  const bytes = await readFile(params.inputPath);
+  const artifact = await createSealArtifact({
+    signer: {
+      identity: params.identity,
+    },
+    subjectPath: basename(params.inputPath),
+    payload: bytes,
+    recipients: params.recipients,
+  });
+
+  return {
+    artifact,
+    content: `${JSON.stringify(artifact, null, 2)}\n`,
+  };
+}

package/packages/seal/src/commands/verify.ts

@@ -0,0 +1,54 @@
+import { readFile } from "node:fs/promises";
+import {
+  parseSealArtifactJson,
+  verifySealArtifact,
+  type SealArtifactV1,
+  type VerifySealArtifactResult,
+} from "../artifact";
+import { parseSealProofJson, verifySealProofAgainstBytes, type SealProofV1 } from "../proof";
+
+export type VerifyArtifactResult = {
+  valid: boolean;
+  hashMatch: boolean;
+  signatureValid: boolean;
+  keyId: string;
+  algorithm: "Ed25519";
+  subjectHash: `sha256:${string}`;
+};
+
+export async function verifyProofArtifact(params: {
+  proofPath: string;
+  inputPath: string;
+}): Promise<{
+  proof: SealProofV1;
+  result: VerifyArtifactResult;
+}> {
+  const rawProof = await readFile(params.proofPath, "utf8");
+  const parsed = parseSealProofJson(rawProof);
+  if (!parsed.ok || !parsed.proof) {
+    throw new Error(parsed.errors.join(" "));
+  }
+
+  const subjectBytes = await readFile(params.inputPath);
+  const result = await verifySealProofAgainstBytes(parsed.proof, subjectBytes);
+  return {
+    proof: parsed.proof,
+    result,
+  };
+}
+
+export async function verifyArtifactProof(params: { artifactPath: string }): Promise<{
+  artifact: SealArtifactV1;
+  result: VerifySealArtifactResult;
+}> {
+  const rawArtifact = await readFile(params.artifactPath, "utf8");
+  const parsed = parseSealArtifactJson(rawArtifact);
+  if (!parsed.ok || !parsed.artifact) {
+    throw new Error(parsed.errors.join(" "));
+  }
+
+  return {
+    artifact: parsed.artifact,
+    result: await verifySealArtifact(parsed.artifact),
+  };
+}

package/packages/seal/src/crypto.ts

@@ -0,0 +1,85 @@
+import {
+  createIdentity,
+  createIdentityFromMnemonic,
+  createMnemonicIdentity,
+  deriveKeyId,
+  parseIdentity,
+  serializeIdentity,
+  signUtf8,
+  verifyUtf8,
+  type SerializedIdentity,
+} from "@ternent/identity";
+
+export type SealSignerInput = {
+  identity: SerializedIdentity;
+};
+
+export type ResolvedSealSigner = {
+  identity: SerializedIdentity;
+  publicKey: string;
+  keyId: string;
+};
+
+export const SEAL_SIGNATURE_CONTEXT = "ternent-seal/v2";
+
+export async function createSealIdentity(
+  createdAt = new Date().toISOString(),
+): Promise<SerializedIdentity> {
+  return createIdentity(createdAt);
+}
+
+export async function createSealIdentityFromMnemonic(input: {
+  mnemonic: string;
+  passphrase?: string;
+  createdAt?: string;
+}): Promise<SerializedIdentity> {
+  return createIdentityFromMnemonic(input);
+}
+
+export async function createSealMnemonicIdentity(
+  input: {
+    words?: 12 | 24;
+    passphrase?: string;
+    createdAt?: string;
+  } = {},
+): Promise<{ identity: SerializedIdentity; mnemonic: string }> {
+  return createMnemonicIdentity(input);
+}
+
+export function exportIdentityJson(identity: SerializedIdentity): string {
+  return serializeIdentity(identity);
+}
+
+export async function resolveSealSigner(input: SealSignerInput): Promise<ResolvedSealSigner> {
+  const identity = parseIdentity(input.identity);
+  const keyId = await deriveKeyId(identity.publicKey);
+  if (keyId !== identity.keyId) {
+    throw new Error("Identity keyId does not match the signer public key.");
+  }
+
+  return {
+    identity,
+    publicKey: identity.publicKey,
+    keyId,
+  };
+}
+
+export async function signSealUtf8(identity: SerializedIdentity, value: string): Promise<string> {
+  return signUtf8(identity, value, {
+    context: SEAL_SIGNATURE_CONTEXT,
+  });
+}
+
+export async function verifySealUtf8(
+  signature: string,
+  value: string,
+  publicKey: string,
+): Promise<boolean> {
+  return verifyUtf8(publicKey, value, signature, {
+    context: SEAL_SIGNATURE_CONTEXT,
+  });
+}
+
+export async function verifyPublicKeyKeyId(publicKey: string, keyId: string): Promise<boolean> {
+  return (await deriveKeyId(publicKey)) === keyId;
+}