@ternent/core 0.0.1

package/packages/armour/src/types.ts

@@ -0,0 +1,93 @@
+import type { SerializedIdentity } from "@ternent/identity";
+
+export type ArmourIdentityInput = string | SerializedIdentity;
+export type ArmourOutputFormat = "armor" | "binary";
+export type ArmourBinaryInput = Uint8Array | ArrayBuffer | Blob;
+
+export type ArmourErrorCode =
+  | "ARMOUR_INIT_FAILED"
+  | "ARMOUR_EMPTY_DATA"
+  | "ARMOUR_EMPTY_RECIPIENTS"
+  | "ARMOUR_INVALID_RECIPIENT"
+  | "ARMOUR_INVALID_SECRET_KEY"
+  | "ARMOUR_EMPTY_PASSPHRASE"
+  | "ARMOUR_DATA_TOO_LARGE"
+  | "ARMOUR_INVALID_IDENTITY"
+  | "ARMOUR_IDENTITY_DERIVATION_FAILED"
+  | "ARMOUR_ENCRYPT_FAILED"
+  | "ARMOUR_DECRYPT_FAILED";
+
+export interface EncryptForRecipientsInput {
+  recipients: string[];
+  data: Uint8Array;
+  output?: ArmourOutputFormat;
+}
+
+export interface DecryptWithSecretKeyInput {
+  secretKey: string;
+  data: Uint8Array;
+}
+
+export interface EncryptForIdentitiesInput {
+  identities: ArmourIdentityInput[];
+  data: Uint8Array;
+  output?: ArmourOutputFormat;
+}
+
+export interface DecryptWithIdentityInput {
+  identity: ArmourIdentityInput;
+  data: Uint8Array;
+}
+
+export interface EncryptWithPassphraseInput {
+  passphrase: string;
+  data: Uint8Array;
+  output?: ArmourOutputFormat;
+}
+
+export interface DecryptWithPassphraseInput {
+  passphrase: string;
+  data: Uint8Array;
+}
+
+export interface EncryptTextForIdentitiesInput {
+  identities: ArmourIdentityInput[];
+  text: string;
+}
+
+export interface DecryptTextWithIdentityInput {
+  identity: ArmourIdentityInput;
+  data: string | Uint8Array;
+}
+
+export interface EncryptTextWithPassphraseInput {
+  passphrase: string;
+  text: string;
+}
+
+export interface DecryptTextWithPassphraseInput {
+  passphrase: string;
+  data: string | Uint8Array;
+}
+
+export interface EncryptBinaryForIdentitiesInput {
+  identities: ArmourIdentityInput[];
+  data: ArmourBinaryInput;
+  output?: ArmourOutputFormat;
+}
+
+export interface DecryptBinaryWithIdentityInput {
+  identity: ArmourIdentityInput;
+  data: ArmourBinaryInput;
+}
+
+export interface EncryptBinaryWithPassphraseInput {
+  passphrase: string;
+  data: ArmourBinaryInput;
+  output?: ArmourOutputFormat;
+}
+
+export interface DecryptBinaryWithPassphraseInput {
+  passphrase: string;
+  data: ArmourBinaryInput;
+}

package/packages/armour/test/armour.test.ts

@@ -0,0 +1,270 @@
+import { dirname, resolve } from "node:path";
+import { readFile } from "node:fs/promises";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { describe, expect, it, vi } from "vitest";
+import { createIdentity, serializeIdentity } from "../../identity-v2/src/index.ts";
+
+const testDir = dirname(fileURLToPath(import.meta.url));
+const packageDir = resolve(testDir, "..");
+
+async function loadSourceModule() {
+  vi.resetModules();
+  return import("../src/index.ts");
+}
+
+describe("@ternent/armour", () => {
+  it("requires manual init before use", async () => {
+    const armour = await loadSourceModule();
+
+    await expect(
+      armour.encryptWithPassphrase({
+        passphrase: "correct horse battery staple",
+        data: new TextEncoder().encode("hello"),
+      }),
+    ).rejects.toMatchObject({
+      name: "ArmourInitError",
+      code: "ARMOUR_INIT_FAILED",
+    });
+  });
+
+  it("initializes idempotently", async () => {
+    const armour = await loadSourceModule();
+
+    await expect(armour.initArmour()).resolves.toBeUndefined();
+    await expect(armour.initArmour()).resolves.toBeUndefined();
+  });
+
+  it("derives age recipients and secrets from identity objects and strings", async () => {
+    const armour = await loadSourceModule();
+    const identity = await createIdentity("2026-03-17T00:00:00.000Z");
+    const serialized = serializeIdentity(identity);
+
+    const recipientFromObject = await armour.recipientFromIdentity(identity);
+    const recipientFromString = await armour.recipientFromIdentity(serialized);
+    const secret = await armour.secretKeyFromIdentity(identity);
+
+    expect(recipientFromObject).toMatch(/^age1/);
+    expect(recipientFromString).toBe(recipientFromObject);
+    expect(secret).toMatch(/^AGE-SECRET-KEY-1/);
+  });
+
+  it("rejects malformed identity input with structured errors", async () => {
+    const armour = await loadSourceModule();
+
+    await expect(
+      armour.recipientFromIdentity('{"format":"ternent-identity","version":"nope"}'),
+    ).rejects.toMatchObject({
+      name: "ArmourIdentityError",
+      code: "ARMOUR_INVALID_IDENTITY",
+    });
+  });
+
+  it("encrypts for one identity and decrypts with the same identity", async () => {
+    const armour = await loadSourceModule();
+    await armour.initArmour();
+    const identity = await createIdentity();
+
+    const ciphertext = await armour.encryptForIdentities({
+      identities: [identity],
+      data: new TextEncoder().encode("hello"),
+    });
+    const plaintext = await armour.decryptWithIdentity({
+      identity,
+      data: ciphertext,
+    });
+
+    expect(new TextDecoder().decode(plaintext)).toBe("hello");
+  });
+
+  it("encrypts for multiple identities in one pass", async () => {
+    const armour = await loadSourceModule();
+    await armour.initArmour();
+    const alice = await createIdentity();
+    const bob = await createIdentity();
+
+    const ciphertext = await armour.encryptForIdentities({
+      identities: [alice, bob],
+      data: new TextEncoder().encode("shared"),
+    });
+    const plaintext = await armour.decryptWithIdentity({
+      identity: bob,
+      data: ciphertext,
+    });
+
+    expect(new TextDecoder().decode(plaintext)).toBe("shared");
+  });
+
+  it("supports raw recipient passthrough and raw secret decryption", async () => {
+    const armour = await loadSourceModule();
+    await armour.initArmour();
+    const identity = await createIdentity();
+    const recipient = await armour.recipientFromIdentity(identity);
+    const secretKey = await armour.secretKeyFromIdentity(identity);
+
+    const ciphertext = await armour.encryptForRecipients({
+      recipients: [recipient],
+      data: new TextEncoder().encode("raw"),
+      output: "binary",
+    });
+    const plaintext = await armour.decryptWithSecretKey({
+      secretKey,
+      data: ciphertext,
+    });
+
+    expect(new TextDecoder().decode(plaintext)).toBe("raw");
+  });
+
+  it("normalizes recipient validation failures", async () => {
+    const armour = await loadSourceModule();
+    await armour.initArmour();
+
+    await expect(
+      armour.encryptForRecipients({
+        recipients: [],
+        data: new TextEncoder().encode("hello"),
+      }),
+    ).rejects.toMatchObject({
+      name: "ArmourValidationError",
+      code: "ARMOUR_EMPTY_RECIPIENTS",
+    });
+  });
+
+  it("round trips passphrase encryption and rejects wrong passphrases", async () => {
+    const armour = await loadSourceModule();
+    await armour.initArmour();
+
+    const ciphertext = await armour.encryptWithPassphrase({
+      passphrase: "correct horse battery staple",
+      data: new TextEncoder().encode("secret"),
+    });
+    const plaintext = await armour.decryptWithPassphrase({
+      passphrase: "correct horse battery staple",
+      data: ciphertext,
+    });
+
+    expect(new TextDecoder().decode(plaintext)).toBe("secret");
+
+    await expect(
+      armour.decryptWithPassphrase({
+        passphrase: "wrong",
+        data: ciphertext,
+      }),
+    ).rejects.toMatchObject({
+      name: "ArmourDecryptionError",
+      code: "ARMOUR_DECRYPT_FAILED",
+    });
+  });
+
+  it("rejects empty passphrases with structured validation errors", async () => {
+    const armour = await loadSourceModule();
+    await armour.initArmour();
+
+    await expect(
+      armour.encryptWithPassphrase({
+        passphrase: "",
+        data: new TextEncoder().encode("hello"),
+      }),
+    ).rejects.toMatchObject({
+      name: "ArmourValidationError",
+      code: "ARMOUR_EMPTY_PASSPHRASE",
+    });
+  });
+
+  it("round trips text helpers", async () => {
+    const armour = await loadSourceModule();
+    await armour.initArmour();
+    const identity = await createIdentity();
+
+    const ciphertext = await armour.encryptTextForIdentities({
+      identities: [identity],
+      text: "hello utf8",
+    });
+    const plaintext = await armour.decryptTextWithIdentity({
+      identity,
+      data: ciphertext,
+    });
+
+    expect(ciphertext).toContain("-----BEGIN AGE ENCRYPTED FILE-----");
+    expect(plaintext).toBe("hello utf8");
+  });
+
+  it("accepts ArrayBuffer, Blob, and File-compatible inputs for binary helpers", async () => {
+    const armour = await loadSourceModule();
+    await armour.initArmour();
+    const identity = await createIdentity();
+    const fileLike =
+      typeof File === "undefined"
+        ? new Blob(["blob data"], { type: "text/plain" })
+        : new File(["blob data"], "demo.txt", { type: "text/plain" });
+
+    const ciphertextFromArrayBuffer = await armour.encryptBinaryForIdentities({
+      identities: [identity],
+      data: new TextEncoder().encode("buffer data").buffer,
+      output: "binary",
+    });
+    const plaintextFromArrayBuffer = await armour.decryptBinaryWithIdentity({
+      identity,
+      data: ciphertextFromArrayBuffer,
+    });
+    const ciphertextFromFile = await armour.encryptBinaryForIdentities({
+      identities: [identity],
+      data: fileLike,
+    });
+    const plaintextFromFile = await armour.decryptBinaryWithIdentity({
+      identity,
+      data: ciphertextFromFile,
+    });
+
+    expect(new TextDecoder().decode(plaintextFromArrayBuffer)).toBe("buffer data");
+    expect(new TextDecoder().decode(plaintextFromFile)).toBe("blob data");
+  });
+
+  it("keeps the package boundary clean", async () => {
+    const sourceFiles = [
+      resolve(packageDir, "src/index.ts"),
+      resolve(packageDir, "src/identity.ts"),
+      resolve(packageDir, "src/recipients.ts"),
+      resolve(packageDir, "src/passphrase.ts"),
+      resolve(packageDir, "src/text.ts"),
+      resolve(packageDir, "src/files.ts"),
+    ];
+    const source = (await Promise.all(sourceFiles.map((file) => readFile(file, "utf8")))).join(
+      "\n",
+    );
+    const armour = await loadSourceModule();
+    const identity = await createIdentity();
+
+    expect(source).not.toMatch(/@ternent\/seal-/);
+    expect(source).not.toMatch(/\benvelope\b/i);
+    expect(source).not.toMatch(/\b(sign|verify)(Utf8|Bytes)?\b/);
+    expect(source).not.toMatch(/\bencryptText\b(?!ForIdentities|WithPassphrase)/);
+    expect(source).not.toMatch(/\bdecryptText\b(?!WithIdentity|WithPassphrase)/);
+
+    await armour.initArmour();
+    await expect(
+      armour.encryptForIdentities({
+        identities: [identity],
+        data: new TextEncoder().encode("async"),
+      }),
+    ).resolves.toBeInstanceOf(Uint8Array);
+  });
+
+  it("imports from built ESM output without manual path hacks", async () => {
+    const entryUrl = pathToFileURL(resolve(packageDir, "dist/index.js")).href;
+    const armour = await import(entryUrl);
+    const identity = await createIdentity();
+
+    await armour.initArmour();
+
+    const ciphertext = await armour.encryptForIdentities({
+      identities: [identity],
+      data: new TextEncoder().encode("built package"),
+    });
+    const plaintext = await armour.decryptWithIdentity({
+      identity,
+      data: ciphertext,
+    });
+
+    expect(new TextDecoder().decode(plaintext)).toBe("built package");
+  });
+});

package/packages/armour/tsconfig.build.json

@@ -0,0 +1,12 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "declaration": true,
+    "declarationMap": true,
+    "emitDeclarationOnly": true
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["src/**/*.test.*", "test", "dist", "node_modules"]
+}

package/packages/armour/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2020", "DOM"],
+    "types": ["node", "vitest/globals"]
+  },
+  "include": ["src/**/*.ts", "test/**/*.ts", "vite.config.ts"],
+  "exclude": ["dist", "node_modules"]
+}

package/packages/armour/vite.config.ts

@@ -0,0 +1,29 @@
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { defineConfig } from "vite";
+import { createPackageExternal, resolvePackageDir } from "../../scripts/vite/package-lib-config";
+
+const configDir = dirname(fileURLToPath(import.meta.url));
+const external = createPackageExternal(resolvePackageDir(import.meta.url));
+
+export default defineConfig({
+  build: {
+    outDir: "dist",
+    sourcemap: true,
+    target: "es2020",
+    minify: false,
+    lib: {
+      entry: resolve(configDir, "src/index.ts"),
+      name: "ternentArmour",
+      fileName: "index",
+      formats: ["es"],
+    },
+    rollupOptions: {
+      external,
+      output: {
+        format: "es",
+        entryFileNames: "index.js",
+      },
+    },
+  },
+});

package/packages/concord/CHANGELOG.md

@@ -0,0 +1,83 @@
+# @ternent/concord
+
+## 0.2.9
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @ternent/ledger@0.1.8
+
+## 0.2.8
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @ternent/ledger@0.1.7
+
+## 0.2.7
+
+### Patch Changes
+
+- Updated dependencies []:
+  - @ternent/ledger@0.1.6
+
+## 0.2.6
+
+### Patch Changes
+
+- [`583a65c2dc6917a634019ea53c6987dc3960a8b2`](https://github.com/samternent/home/commit/583a65c2dc6917a634019ea53c6987dc3960a8b2) Thanks [@samternent](https://github.com/samternent)! - Update concord
+
+## 0.2.5
+
+### Patch Changes
+
+- [`42a5b52f19d93079ca76a07f44c647d5e6866009`](https://github.com/samternent/home/commit/42a5b52f19d93079ca76a07f44c647d5e6866009) Thanks [@samternent](https://github.com/samternent)! - Align build with identity
+
+## 0.2.4
+
+### Patch Changes
+
+- [`cb63d9c1dc91e0cd3924bafd5abcde89cc02992f`](https://github.com/samternent/home/commit/cb63d9c1dc91e0cd3924bafd5abcde89cc02992f) Thanks [@samternent](https://github.com/samternent)! - Fix workflows
+
+- Updated dependencies [[`cb63d9c1dc91e0cd3924bafd5abcde89cc02992f`](https://github.com/samternent/home/commit/cb63d9c1dc91e0cd3924bafd5abcde89cc02992f)]:
+  - @ternent/ledger@0.1.5
+
+## 0.2.3
+
+### Patch Changes
+
+- [`acf974919a1176da235e7ec7468c46df8bc13402`](https://github.com/samternent/home/commit/acf974919a1176da235e7ec7468c46df8bc13402) Thanks [@samternent](https://github.com/samternent)! - Update build configs
+
+- Updated dependencies [[`acf974919a1176da235e7ec7468c46df8bc13402`](https://github.com/samternent/home/commit/acf974919a1176da235e7ec7468c46df8bc13402)]:
+  - @ternent/ledger@0.1.4
+
+## 0.2.2
+
+### Patch Changes
+
+- [`3fd51c9f51ccc3d816d044aa8aa161d9683534c3`](https://github.com/samternent/home/commit/3fd51c9f51ccc3d816d044aa8aa161d9683534c3) Thanks [@samternent](https://github.com/samternent)! - alias utils
+
+- Updated dependencies []:
+  - @ternent/ledger@0.1.3
+
+## 0.2.1
+
+### Patch Changes
+
+- [`109f8c3989b16a161a34b933dcad68390d9219c5`](https://github.com/samternent/home/commit/109f8c3989b16a161a34b933dcad68390d9219c5) Thanks [@samternent](https://github.com/samternent)! - Fix deps
+
+- Updated dependencies [[`109f8c3989b16a161a34b933dcad68390d9219c5`](https://github.com/samternent/home/commit/109f8c3989b16a161a34b933dcad68390d9219c5)]:
+  - @ternent/ledger@0.1.2
+
+## 0.2.0
+
+### Minor Changes
+
+- [`92050833da54cacbd6fe33349d9b8fb66754d82c`](https://github.com/samternent/home/commit/92050833da54cacbd6fe33349d9b8fb66754d82c) Thanks [@samternent](https://github.com/samternent)! - Add the initial Concord command runtime on top of `@ternent/ledger`.
+
+### Patch Changes
+
+- [`92050833da54cacbd6fe33349d9b8fb66754d82c`](https://github.com/samternent/home/commit/92050833da54cacbd6fe33349d9b8fb66754d82c) Thanks [@samternent](https://github.com/samternent)! - Concord library migration
+
+- Updated dependencies [[`92050833da54cacbd6fe33349d9b8fb66754d82c`](https://github.com/samternent/home/commit/92050833da54cacbd6fe33349d9b8fb66754d82c)]:
+  - @ternent/ledger@0.1.1

package/packages/concord/CLAUDE.md

@@ -0,0 +1,9 @@
+# CLAUDE.md
+
+`@ternent/concord` is the command/replay runtime over `@ternent/ledger`.
+
+- Do not add app-domain behavior here; keep this package runtime-generic.
+- Replay flow is entry-first: for each entry, every plugin runs `applyEntry` in plugin order.
+- Decrypt capability is identity-derived; plugins receive `plain`, `decrypted`, or `encrypted` replay payloads.
+- Keep integrity strict: invalid committed history must not produce trusted runtime state.
+- Preserve plugin contract stability (`reset/beginReplay/applyEntry/endReplay`).

package/packages/concord/README.md

@@ -0,0 +1,146 @@
+# `@ternent/concord`
+
+Command-driven replay runtime for building non-custodial applications on top of `@ternent/ledger`.
+
+Concord is replay-first:
+
+- ledger history is truth
+- replay is the primary abstraction
+- replay plugins are the only replay consumer type
+- state, reactivity, databases, and indexes are all projection
+
+```ts
+import { createConcordApp, type ConcordReplayPlugin } from "@ternent/concord";
+
+const todoPlugin: ConcordReplayPlugin<{
+  items: Record<string, { id: string; title: string; completed: boolean }>;
+}> = {
+  id: "todo",
+  initialState() {
+    return { items: {} };
+  },
+  commands: {
+    "todo.create-item": async (_ctx, input: { id: string; title: string }) => ({
+      kind: "todo.item.created",
+      payload: input,
+    }),
+  },
+  applyEntry(entry, ctx) {
+    if (entry.kind !== "todo.item.created" || entry.payload.type !== "plain") {
+      return;
+    }
+
+    const payload = entry.payload.data as { id: string; title: string };
+    ctx.setState((state) => ({
+      items: {
+        ...state.items,
+        [payload.id]: {
+          id: payload.id,
+          title: payload.title,
+          completed: false,
+        },
+      },
+    }));
+  },
+};
+
+const app = await createConcordApp({
+  identity,
+  storage,
+  plugins: [todoPlugin],
+});
+
+await app.load();
+
+await app.command("todo.create-item", {
+  id: crypto.randomUUID(),
+  title: "Buy milk",
+});
+
+await app.commit({
+  metadata: {
+    message: "Create first todo",
+  },
+});
+
+const todoState = app.getReplayState("todo");
+```
+
+## Identity
+
+Concord now supports two runtime modes:
+
+- read-only: omit `identity` and use Concord for load/import/verify/replay only
+- interactive: provide `identity` and use Concord for signed commands and commits
+
+Interactive mode:
+
+```ts
+const app = await createConcordApp({
+  identity,
+  storage,
+  plugins,
+});
+```
+
+Concord derives author, signer, and decrypt capability internally. Command handlers receive the same high-level `SerializedIdentity` at `ctx.identity`. Ledger-facing identity adaptation stays private to Concord.
+
+Read-only mode:
+
+```ts
+const app = await createConcordApp({
+  storage,
+  plugins,
+});
+```
+
+In read-only mode:
+
+- `load`, `importLedger`, `verify`, `replay`, and `recompute` are allowed
+- `create`, `command`, `commit`, and `clearStaged` fail with `READ_ONLY_RUNTIME`
+- encrypted entries remain encrypted unless an identity is present for decrypt capability
+
+## Replay Plugins
+
+Replay plugins are the only replay consumer type.
+
+- a replay plugin may keep replay-derived state with `initialState()` and `ctx.setState(...)`
+- a replay plugin may materialize into external systems like Loki, Vue refs, React stores, or IndexedDB
+- commands remain typed entry producers
+
+`reset` has a narrow meaning:
+
+- `reset` prepares plugin-local replay workspace for a new replay pass
+- `reset` does not imply clearing previously published external surfaces
+- if a plugin needs external atomic swap behavior, that belongs to the plugin and usually happens in `endReplay`
+
+Concord only guarantees atomicity at the published Concord state boundary. External projection atomicity is plugin-owned.
+
+## Replay And Integrity
+
+The core lifecycle is:
+
+1. `command(...)` stages one or more entries
+2. local replay reflects committed truth plus staged truth
+3. `commit(...)` groups staged entries into a signed commit
+4. replay rebuilds published runtime state from that history
+
+Concord treats committed history as atomic truth. If any reachable committed byte is invalid, Concord does not present the runtime state as trustworthy.
+
+## Partial Replay
+
+Concord supports ranged replay options:
+
+```ts
+await app.replay({
+  fromEntryId: "entry_a",
+  toEntryId: "entry_b",
+});
+```
+
+Two distinctions matter:
+
+- replay of any ordered slice is deterministic
+- authoritative full-state reconstruction still requires replay from genesis or a valid checkpoint
+
+That distinction is intentional. Partial replay metadata exists so Concord stays compatible with future timeline scrubbing and replay-slider UX without redesigning the plugin contract.