@ternent/core 0.0.1

package/packages/armour/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@ternent/armour",
+  "version": "0.2.3",
+  "description": "Opinionated identity-aware encryption bridge over @ternent/rage",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ternent/core.git",
+    "directory": "packages/armour"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "SPEC.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "vite build && tsc -p tsconfig.build.json",
+    "test": "pnpm run build && vitest run"
+  },
+  "dependencies": {
+    "@ternent/identity": "workspace:*",
+    "@ternent/rage": "^0.1.3"
+  },
+  "devDependencies": {
+    "@types/node": "^24.3.0",
+    "typescript": "^5.9.3",
+    "vite": "^4.5.3",
+    "vitest": "^1.6.0"
+  }
+}

package/packages/armour/src/constants.ts

@@ -0,0 +1,5 @@
+export const AGE_RECIPIENT_PREFIX = "age1";
+export const AGE_SECRET_KEY_PREFIX = "AGE-SECRET-KEY-";
+
+export const utf8Encoder = new TextEncoder();
+export const utf8Decoder = new TextDecoder("utf-8", { fatal: true });

package/packages/armour/src/deps.d.ts

@@ -0,0 +1,56 @@
+declare module "@ternent/identity" {
+  export type SerializedIdentity = {
+    format: "ternent-identity";
+    version: "2";
+    algorithm: "Ed25519";
+    createdAt: string;
+    publicKey: string;
+    keyId: string;
+    material: {
+      kind: "seed";
+      seed: string;
+    };
+  };
+
+  export function parseIdentity(input: string | SerializedIdentity): SerializedIdentity;
+
+  export function deriveAgeRecipient(input: string | SerializedIdentity): Promise<string>;
+
+  export function deriveAgeSecretKey(input: string | SerializedIdentity): Promise<string>;
+}
+
+declare module "@ternent/rage" {
+  export class RageError extends Error {
+    readonly code: string;
+    readonly cause?: unknown;
+  }
+
+  export class RageInitError extends RageError {}
+  export class RageValidationError extends RageError {}
+  export class RageEncryptionError extends RageError {}
+  export class RageDecryptionError extends RageError {}
+
+  export function initRage(): Promise<void>;
+
+  export function encryptWithRecipients(input: {
+    recipients: string[];
+    data: Uint8Array;
+    output?: "armor" | "binary";
+  }): Promise<Uint8Array>;
+
+  export function decryptWithIdentity(input: {
+    identity: string;
+    data: Uint8Array;
+  }): Promise<Uint8Array>;
+
+  export function encryptWithPassphrase(input: {
+    passphrase: string;
+    data: Uint8Array;
+    output?: "armor" | "binary";
+  }): Promise<Uint8Array>;
+
+  export function decryptWithPassphrase(input: {
+    passphrase: string;
+    data: Uint8Array;
+  }): Promise<Uint8Array>;
+}

package/packages/armour/src/errors.ts

@@ -0,0 +1,172 @@
+import {
+  RageDecryptionError,
+  RageEncryptionError,
+  RageError,
+  RageInitError,
+  RageValidationError,
+} from "@ternent/rage";
+import type { ArmourErrorCode } from "./types.js";
+
+export class ArmourError extends Error {
+  readonly code: ArmourErrorCode;
+  readonly cause?: unknown;
+
+  constructor(code: ArmourErrorCode, message: string, cause?: unknown) {
+    super(message);
+    this.name = new.target.name;
+    this.code = code;
+    if (cause !== undefined) {
+      this.cause = cause;
+    }
+  }
+}
+
+export class ArmourInitError extends ArmourError {}
+export class ArmourValidationError extends ArmourError {}
+export class ArmourIdentityError extends ArmourError {}
+export class ArmourEncryptionError extends ArmourError {}
+export class ArmourDecryptionError extends ArmourError {}
+
+function getMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}
+
+export function toArmourInitError(error: unknown): ArmourInitError {
+  if (error instanceof ArmourInitError) {
+    return error;
+  }
+  return new ArmourInitError("ARMOUR_INIT_FAILED", "Failed to initialize Armour.", error);
+}
+
+export function toArmourIdentityError(
+  error: unknown,
+  code: "ARMOUR_INVALID_IDENTITY" | "ARMOUR_IDENTITY_DERIVATION_FAILED",
+  fallbackMessage: string,
+): ArmourIdentityError {
+  if (error instanceof ArmourIdentityError) {
+    return error;
+  }
+
+  return new ArmourIdentityError(code, fallbackMessage, error);
+}
+
+export function toArmourEncryptionError(error: unknown): ArmourError {
+  if (error instanceof ArmourError) {
+    return error;
+  }
+
+  if (error instanceof RageInitError) {
+    return new ArmourInitError(
+      "ARMOUR_INIT_FAILED",
+      "Armour is not initialized. Call initArmour() before encrypting or decrypting.",
+      error,
+    );
+  }
+
+  if (error instanceof RageValidationError) {
+    switch (error.code) {
+      case "RAGE_EMPTY_DATA":
+        return new ArmourValidationError(
+          "ARMOUR_EMPTY_DATA",
+          "Data must be a non-empty Uint8Array.",
+          error,
+        );
+      case "RAGE_EMPTY_RECIPIENTS":
+        return new ArmourValidationError(
+          "ARMOUR_EMPTY_RECIPIENTS",
+          "At least one recipient is required.",
+          error,
+        );
+      case "RAGE_INVALID_RECIPIENT":
+        return new ArmourValidationError(
+          "ARMOUR_INVALID_RECIPIENT",
+          "Recipient must be an age recipient string.",
+          error,
+        );
+      case "RAGE_EMPTY_PASSPHRASE":
+        return new ArmourValidationError(
+          "ARMOUR_EMPTY_PASSPHRASE",
+          "Passphrase must not be empty.",
+          error,
+        );
+      case "RAGE_DATA_TOO_LARGE":
+        return new ArmourValidationError(
+          "ARMOUR_DATA_TOO_LARGE",
+          "Data exceeds the 64MB maximum message size.",
+          error,
+        );
+      default:
+        break;
+    }
+  }
+
+  if (error instanceof RageEncryptionError || error instanceof RageError) {
+    return new ArmourEncryptionError("ARMOUR_ENCRYPT_FAILED", "Failed to encrypt data.", error);
+  }
+
+  return new ArmourEncryptionError("ARMOUR_ENCRYPT_FAILED", "Failed to encrypt data.", error);
+}
+
+export function toArmourDecryptionError(error: unknown): ArmourError {
+  if (error instanceof ArmourError) {
+    return error;
+  }
+
+  if (error instanceof RageInitError) {
+    return new ArmourInitError(
+      "ARMOUR_INIT_FAILED",
+      "Armour is not initialized. Call initArmour() before encrypting or decrypting.",
+      error,
+    );
+  }
+
+  if (error instanceof RageValidationError) {
+    switch (error.code) {
+      case "RAGE_EMPTY_DATA":
+        return new ArmourValidationError(
+          "ARMOUR_EMPTY_DATA",
+          "Data must be a non-empty Uint8Array.",
+          error,
+        );
+      case "RAGE_INVALID_IDENTITY":
+        return new ArmourValidationError(
+          "ARMOUR_INVALID_SECRET_KEY",
+          "Secret key must be an age secret key string.",
+          error,
+        );
+      case "RAGE_EMPTY_PASSPHRASE":
+        return new ArmourValidationError(
+          "ARMOUR_EMPTY_PASSPHRASE",
+          "Passphrase must not be empty.",
+          error,
+        );
+      default:
+        break;
+    }
+  }
+
+  if (error instanceof RageDecryptionError || error instanceof RageError) {
+    return new ArmourDecryptionError("ARMOUR_DECRYPT_FAILED", "Failed to decrypt data.", error);
+  }
+
+  return new ArmourDecryptionError("ARMOUR_DECRYPT_FAILED", "Failed to decrypt data.", error);
+}
+export function invalidUtf8Error(error: unknown): ArmourDecryptionError {
+  return new ArmourDecryptionError(
+    "ARMOUR_DECRYPT_FAILED",
+    "Decrypted data is not valid UTF-8.",
+    error,
+  );
+}
+
+export function invalidBinaryInputError(value: unknown): ArmourValidationError {
+  const detail =
+    value instanceof ArrayBuffer || value instanceof Uint8Array || value instanceof Blob
+      ? "Data must be a non-empty Blob, File, ArrayBuffer, or Uint8Array."
+      : `Unsupported binary input type: ${getMessage(value)}`;
+
+  return new ArmourValidationError("ARMOUR_EMPTY_DATA", detail, value);
+}

package/packages/armour/src/files.ts

@@ -0,0 +1,73 @@
+import { invalidBinaryInputError } from "./errors.js";
+import { decryptWithIdentity, encryptForIdentities } from "./recipients.js";
+import { decryptWithPassphrase, encryptWithPassphrase } from "./passphrase.js";
+import type {
+  ArmourBinaryInput,
+  DecryptBinaryWithIdentityInput,
+  DecryptBinaryWithPassphraseInput,
+  EncryptBinaryForIdentitiesInput,
+  EncryptBinaryWithPassphraseInput,
+} from "./types.js";
+
+async function toUint8Array(data: ArmourBinaryInput): Promise<Uint8Array> {
+  if (data instanceof Uint8Array) {
+    if (data.byteLength === 0) {
+      throw invalidBinaryInputError(data);
+    }
+    return Uint8Array.from(data);
+  }
+
+  if (data instanceof ArrayBuffer) {
+    if (data.byteLength === 0) {
+      throw invalidBinaryInputError(data);
+    }
+    return new Uint8Array(data.slice(0));
+  }
+
+  if (data instanceof Blob) {
+    if (data.size === 0) {
+      throw invalidBinaryInputError(data);
+    }
+    return new Uint8Array(await data.arrayBuffer());
+  }
+
+  throw invalidBinaryInputError(data);
+}
+
+export async function encryptBinaryForIdentities(
+  input: EncryptBinaryForIdentitiesInput,
+): Promise<Uint8Array> {
+  return encryptForIdentities({
+    identities: input.identities,
+    data: await toUint8Array(input.data),
+    output: input.output,
+  });
+}
+
+export async function decryptBinaryWithIdentity(
+  input: DecryptBinaryWithIdentityInput,
+): Promise<Uint8Array> {
+  return decryptWithIdentity({
+    identity: input.identity,
+    data: await toUint8Array(input.data),
+  });
+}
+
+export async function encryptBinaryWithPassphrase(
+  input: EncryptBinaryWithPassphraseInput,
+): Promise<Uint8Array> {
+  return encryptWithPassphrase({
+    passphrase: input.passphrase,
+    data: await toUint8Array(input.data),
+    output: input.output,
+  });
+}
+
+export async function decryptBinaryWithPassphrase(
+  input: DecryptBinaryWithPassphraseInput,
+): Promise<Uint8Array> {
+  return decryptWithPassphrase({
+    passphrase: input.passphrase,
+    data: await toUint8Array(input.data),
+  });
+}

package/packages/armour/src/identity.ts

@@ -0,0 +1,72 @@
+import {
+  deriveAgeRecipient,
+  deriveAgeSecretKey,
+  parseIdentity,
+  type SerializedIdentity,
+} from "@ternent/identity";
+import { AGE_SECRET_KEY_PREFIX } from "./constants.js";
+import { ArmourIdentityError, ArmourValidationError, toArmourIdentityError } from "./errors.js";
+import type { ArmourIdentityInput } from "./types.js";
+
+export async function resolveIdentity(input: ArmourIdentityInput): Promise<SerializedIdentity> {
+  try {
+    return parseIdentity(input);
+  } catch (error) {
+    throw toArmourIdentityError(
+      error,
+      "ARMOUR_INVALID_IDENTITY",
+      "Identity input must be a valid @ternent/identity serialized identity.",
+    );
+  }
+}
+
+export async function recipientFromIdentity(input: ArmourIdentityInput): Promise<string> {
+  const identity = await resolveIdentity(input);
+
+  try {
+    return await deriveAgeRecipient(identity);
+  } catch (error) {
+    throw toArmourIdentityError(
+      error,
+      "ARMOUR_IDENTITY_DERIVATION_FAILED",
+      "Failed to derive an age recipient from the provided identity.",
+    );
+  }
+}
+
+export async function secretKeyFromIdentity(input: ArmourIdentityInput): Promise<string> {
+  const identity = await resolveIdentity(input);
+
+  try {
+    return await deriveAgeSecretKey(identity);
+  } catch (error) {
+    throw toArmourIdentityError(
+      error,
+      "ARMOUR_IDENTITY_DERIVATION_FAILED",
+      "Failed to derive an age secret key from the provided identity.",
+    );
+  }
+}
+
+export async function normalizeSecretKey(secretKey: string): Promise<string> {
+  const normalized = String(secretKey || "").trim();
+
+  if (!normalized.startsWith(AGE_SECRET_KEY_PREFIX)) {
+    throw new ArmourValidationError(
+      "ARMOUR_INVALID_SECRET_KEY",
+      "Secret key must be an age secret key string.",
+    );
+  }
+
+  return normalized;
+}
+
+export async function assertIdentityCapabilityRoot(
+  input: ArmourIdentityInput,
+): Promise<SerializedIdentity> {
+  const identity = await resolveIdentity(input);
+  if (identity.algorithm !== "Ed25519") {
+    throw new ArmourIdentityError("ARMOUR_INVALID_IDENTITY", "Identity algorithm must be Ed25519.");
+  }
+  return identity;
+}

package/packages/armour/src/index.ts

@@ -0,0 +1,56 @@
+export {
+  ArmourDecryptionError,
+  ArmourEncryptionError,
+  ArmourError,
+  ArmourIdentityError,
+  ArmourInitError,
+  ArmourValidationError,
+} from "./errors.js";
+export {
+  decryptBinaryWithIdentity,
+  decryptBinaryWithPassphrase,
+  encryptBinaryForIdentities,
+  encryptBinaryWithPassphrase,
+} from "./files.js";
+export {
+  assertIdentityCapabilityRoot,
+  recipientFromIdentity,
+  resolveIdentity,
+  secretKeyFromIdentity,
+} from "./identity.js";
+export { decryptWithPassphrase, encryptWithPassphrase } from "./passphrase.js";
+export {
+  decryptWithIdentity,
+  decryptWithSecretKey,
+  encryptForIdentities,
+  encryptForRecipients,
+  recipientsFromIdentities,
+} from "./recipients.js";
+export {
+  decryptTextWithIdentity,
+  decryptTextWithPassphrase,
+  encryptTextForIdentities,
+  encryptTextWithPassphrase,
+} from "./text.js";
+export { initArmour } from "./init.js";
+export type { SerializedIdentity } from "@ternent/identity";
+export type {
+  ArmourBinaryInput,
+  ArmourErrorCode,
+  ArmourIdentityInput,
+  ArmourOutputFormat,
+  DecryptBinaryWithIdentityInput,
+  DecryptBinaryWithPassphraseInput,
+  DecryptTextWithIdentityInput,
+  DecryptTextWithPassphraseInput,
+  DecryptWithIdentityInput,
+  DecryptWithPassphraseInput,
+  DecryptWithSecretKeyInput,
+  EncryptBinaryForIdentitiesInput,
+  EncryptBinaryWithPassphraseInput,
+  EncryptForIdentitiesInput,
+  EncryptForRecipientsInput,
+  EncryptTextForIdentitiesInput,
+  EncryptTextWithPassphraseInput,
+  EncryptWithPassphraseInput,
+} from "./types.js";

package/packages/armour/src/init.ts

@@ -0,0 +1,10 @@
+import { initRage } from "@ternent/rage";
+import { toArmourInitError } from "./errors.js";
+
+export async function initArmour(): Promise<void> {
+  try {
+    await initRage();
+  } catch (error) {
+    throw toArmourInitError(error);
+  }
+}

package/packages/armour/src/passphrase.ts

@@ -0,0 +1,33 @@
+import {
+  decryptWithPassphrase as rageDecryptWithPassphrase,
+  encryptWithPassphrase as rageEncryptWithPassphrase,
+} from "@ternent/rage";
+import { toArmourDecryptionError, toArmourEncryptionError } from "./errors.js";
+import type { DecryptWithPassphraseInput, EncryptWithPassphraseInput } from "./types.js";
+
+export async function encryptWithPassphrase(
+  input: EncryptWithPassphraseInput,
+): Promise<Uint8Array> {
+  try {
+    return await rageEncryptWithPassphrase({
+      passphrase: input.passphrase,
+      data: input.data,
+      output: input.output,
+    });
+  } catch (error) {
+    throw toArmourEncryptionError(error);
+  }
+}
+
+export async function decryptWithPassphrase(
+  input: DecryptWithPassphraseInput,
+): Promise<Uint8Array> {
+  try {
+    return await rageDecryptWithPassphrase({
+      passphrase: input.passphrase,
+      data: input.data,
+    });
+  } catch (error) {
+    throw toArmourDecryptionError(error);
+  }
+}

package/packages/armour/src/recipients.ts

@@ -0,0 +1,73 @@
+import {
+  decryptWithIdentity as rageDecryptWithIdentity,
+  encryptWithRecipients as rageEncryptWithRecipients,
+} from "@ternent/rage";
+import {
+  normalizeSecretKey,
+  recipientFromIdentity,
+  resolveIdentity,
+  secretKeyFromIdentity,
+} from "./identity.js";
+import { toArmourDecryptionError, toArmourEncryptionError } from "./errors.js";
+import type {
+  ArmourIdentityInput,
+  DecryptWithIdentityInput,
+  DecryptWithSecretKeyInput,
+  EncryptForIdentitiesInput,
+  EncryptForRecipientsInput,
+} from "./types.js";
+
+export async function recipientsFromIdentities(
+  identities: ArmourIdentityInput[],
+): Promise<string[]> {
+  const resolved: string[] = [];
+
+  for (const identity of identities) {
+    await resolveIdentity(identity);
+    resolved.push(await recipientFromIdentity(identity));
+  }
+
+  return resolved;
+}
+
+export async function encryptForRecipients(input: EncryptForRecipientsInput): Promise<Uint8Array> {
+  try {
+    return await rageEncryptWithRecipients({
+      recipients: input.recipients,
+      data: input.data,
+      output: input.output,
+    });
+  } catch (error) {
+    throw toArmourEncryptionError(error);
+  }
+}
+
+export async function decryptWithSecretKey(input: DecryptWithSecretKeyInput): Promise<Uint8Array> {
+  try {
+    return await rageDecryptWithIdentity({
+      identity: await normalizeSecretKey(input.secretKey),
+      data: input.data,
+    });
+  } catch (error) {
+    throw toArmourDecryptionError(error);
+  }
+}
+
+export async function encryptForIdentities(input: EncryptForIdentitiesInput): Promise<Uint8Array> {
+  return encryptForRecipients({
+    recipients: await recipientsFromIdentities(input.identities),
+    data: input.data,
+    output: input.output,
+  });
+}
+
+export async function decryptWithIdentity(input: DecryptWithIdentityInput): Promise<Uint8Array> {
+  try {
+    return await rageDecryptWithIdentity({
+      identity: await secretKeyFromIdentity(input.identity),
+      data: input.data,
+    });
+  } catch (error) {
+    throw toArmourDecryptionError(error);
+  }
+}

package/packages/armour/src/text.ts

@@ -0,0 +1,68 @@
+import { utf8Decoder, utf8Encoder } from "./constants.js";
+import { invalidUtf8Error } from "./errors.js";
+import { decryptWithIdentity, encryptForIdentities } from "./recipients.js";
+import { decryptWithPassphrase, encryptWithPassphrase } from "./passphrase.js";
+import type {
+  DecryptTextWithIdentityInput,
+  DecryptTextWithPassphraseInput,
+  EncryptTextForIdentitiesInput,
+  EncryptTextWithPassphraseInput,
+} from "./types.js";
+
+function decodeUtf8(data: Uint8Array): string {
+  try {
+    return utf8Decoder.decode(data);
+  } catch (error) {
+    throw invalidUtf8Error(error);
+  }
+}
+
+function normalizeCiphertext(data: string | Uint8Array): Uint8Array {
+  return typeof data === "string" ? utf8Encoder.encode(data) : data;
+}
+
+export async function encryptTextForIdentities(
+  input: EncryptTextForIdentitiesInput,
+): Promise<string> {
+  const ciphertext = await encryptForIdentities({
+    identities: input.identities,
+    data: utf8Encoder.encode(input.text),
+    output: "armor",
+  });
+
+  return utf8Decoder.decode(ciphertext);
+}
+
+export async function decryptTextWithIdentity(
+  input: DecryptTextWithIdentityInput,
+): Promise<string> {
+  const plaintext = await decryptWithIdentity({
+    identity: input.identity,
+    data: normalizeCiphertext(input.data),
+  });
+
+  return decodeUtf8(plaintext);
+}
+
+export async function encryptTextWithPassphrase(
+  input: EncryptTextWithPassphraseInput,
+): Promise<string> {
+  const ciphertext = await encryptWithPassphrase({
+    passphrase: input.passphrase,
+    data: utf8Encoder.encode(input.text),
+    output: "armor",
+  });
+
+  return utf8Decoder.decode(ciphertext);
+}
+
+export async function decryptTextWithPassphrase(
+  input: DecryptTextWithPassphraseInput,
+): Promise<string> {
+  const plaintext = await decryptWithPassphrase({
+    passphrase: input.passphrase,
+    data: normalizeCiphertext(input.data),
+  });
+
+  return decodeUtf8(plaintext);
+}