@openlfcp/crypto 0.1.2 → 0.1.4

package/README.md

@@ -12,9 +12,9 @@ ESM only; Node.js 24 or later (browsers and Electron for every package except `@
 
 Part of the OpenLFCP TypeScript SDK, which implements the OpenLFCP MVP 0.1
 subset of [LFCP-WIRE-01](https://github.com/openlfcp/spec/blob/main/wire/LFCP-WIRE-01.md)
-at `mvp-0.1-baseline.9`, not every deferred WIRE-01 feature. It does not
+at `mvp-0.1-baseline.10`, not every deferred WIRE-01 feature. It does not
 claim full LFCP-WIRE-01 conformance. This is the MVP 0.1 release
-(`0.1.2`, npm dist-tag `latest`). Until 1.0, minor versions may change APIs.
+(`0.1.4`, npm dist-tag `latest`). Until 1.0, minor versions may change APIs.
 
 ## Links
 

package/dist/aead.d.ts

@@ -0,0 +1,19 @@
+import { type ActorSequence } from "@openlfcp/core";
+import { ActorDataKey, SnapshotKey } from "./epoch.js";
+/** ciphertext || 16-byte tag of `plaintext` under the actor key, the sequence nonce and `aad` (§26). */
+export declare function encryptDataUnit(key: ActorDataKey, seq: ActorSequence, aad: Uint8Array, plaintext: Uint8Array): Uint8Array;
+/**
+ * The plaintext of `ciphertext` (ciphertext || tag). Any authentication
+ * failure (wrong key, sequence, AAD or tampered bytes) is
+ * AEAD_AUTHENTICATION_FAILED: client-local, no wire code (§26.3, ADR 0001 N3).
+ */
+export declare function decryptDataUnit(key: ActorDataKey, seq: ActorSequence, aad: Uint8Array, ciphertext: Uint8Array): Uint8Array;
+/**
+ * ciphertext || 16-byte tag of a Snapshot plaintext under the publisher's
+ * Snapshot key, the sequence nonce and `aad` (§29.1.4). The sequence must
+ * never be reused for one (resource, epoch, publisher) (§29.1.2).
+ */
+export declare function encryptSnapshot(key: SnapshotKey, seq: bigint, aad: Uint8Array, plaintext: Uint8Array): Uint8Array;
+/** The Snapshot plaintext, or AEAD_AUTHENTICATION_FAILED: client-local, no wire code (§29.1.4). */
+export declare function decryptSnapshot(key: SnapshotKey, seq: bigint, aad: Uint8Array, ciphertext: Uint8Array): Uint8Array;
+//# sourceMappingURL=aead.d.ts.map

package/dist/aead.js

@@ -0,0 +1,104 @@
+import { chacha20poly1305 } from "@noble/ciphers/chacha.js";
+import { LfcpError } from "@openlfcp/core";
+import { ActorDataKey, dataUnitNonce, SnapshotKey, snapshotNonce, symmetricSecretBytes, } from "./epoch.js";
+/**
+ * ChaCha20-Poly1305 for Data Units (LFCP-WIRE-01 §9, §12, §26) and
+ * Snapshots (§29.1), from @noble/ciphers. The functions take the
+ * ActorDataKey or SnapshotKey itself, so the key bytes never leave this
+ * package, and derive the nonce from the actor or Snapshot sequence
+ * (0x00000000 || uint64_be(seq), §12, §29.1.2): there is no random nonce
+ * and no way to pass another one.
+ *
+ * The sequence must come from the writer's ActorSequenceReservation
+ * (@openlfcp/storage, §8): a sequence used twice under one actor key reuses
+ * a nonce. Use createDataUnit (@openlfcp/client) rather than these
+ * building blocks.
+ *
+ * Errors never include key, plaintext or ciphertext bytes.
+ */
+const TAG_LENGTH = 16;
+function keyBytes(key) {
+    if (!(key instanceof ActorDataKey))
+        throw new LfcpError("CRYPTO_FAILURE", "expected an ActorDataKey");
+    return symmetricSecretBytes(key);
+}
+/** ciphertext || 16-byte tag of `plaintext` under the actor key, the sequence nonce and `aad` (§26). */
+export function encryptDataUnit(key, seq, aad, plaintext) {
+    const nonce = dataUnitNonce(seq);
+    const k = Uint8Array.from(keyBytes(key));
+    try {
+        return chacha20poly1305(k, nonce, aad).encrypt(plaintext);
+    }
+    catch {
+        throw new LfcpError("CRYPTO_FAILURE", "ChaCha20-Poly1305 encryption failed");
+    }
+    finally {
+        k.fill(0);
+    }
+}
+/**
+ * The plaintext of `ciphertext` (ciphertext || tag). Any authentication
+ * failure (wrong key, sequence, AAD or tampered bytes) is
+ * AEAD_AUTHENTICATION_FAILED: client-local, no wire code (§26.3, ADR 0001 N3).
+ */
+export function decryptDataUnit(key, seq, aad, ciphertext) {
+    const nonce = dataUnitNonce(seq);
+    if (!(ciphertext instanceof Uint8Array) || ciphertext.length < TAG_LENGTH)
+        throw new LfcpError("AEAD_AUTHENTICATION_FAILED", "the ciphertext is shorter than the tag");
+    const k = Uint8Array.from(keyBytes(key));
+    try {
+        return chacha20poly1305(k, nonce, aad).decrypt(ciphertext);
+    }
+    catch {
+        throw new LfcpError("AEAD_AUTHENTICATION_FAILED", "the Data Unit does not authenticate under this key, sequence and AAD");
+    }
+    finally {
+        k.fill(0);
+    }
+}
+function snapshotKeyBytes(key) {
+    if (!(key instanceof SnapshotKey))
+        throw new LfcpError("CRYPTO_FAILURE", "expected a SnapshotKey");
+    return symmetricSecretBytes(key);
+}
+/** §29: Snapshot Sequences begin at 1 and fit in uint64. */
+function snapshotSequenceNonce(seq) {
+    if (typeof seq !== "bigint" || seq < 1n)
+        throw new LfcpError("OUT_OF_RANGE", "a Snapshot Sequence starts at 1 (§29)");
+    return snapshotNonce(seq);
+}
+/**
+ * ciphertext || 16-byte tag of a Snapshot plaintext under the publisher's
+ * Snapshot key, the sequence nonce and `aad` (§29.1.4). The sequence must
+ * never be reused for one (resource, epoch, publisher) (§29.1.2).
+ */
+export function encryptSnapshot(key, seq, aad, plaintext) {
+    const nonce = snapshotSequenceNonce(seq);
+    const k = Uint8Array.from(snapshotKeyBytes(key));
+    try {
+        return chacha20poly1305(k, nonce, aad).encrypt(plaintext);
+    }
+    catch {
+        throw new LfcpError("CRYPTO_FAILURE", "ChaCha20-Poly1305 encryption failed");
+    }
+    finally {
+        k.fill(0);
+    }
+}
+/** The Snapshot plaintext, or AEAD_AUTHENTICATION_FAILED: client-local, no wire code (§29.1.4). */
+export function decryptSnapshot(key, seq, aad, ciphertext) {
+    const nonce = snapshotSequenceNonce(seq);
+    if (!(ciphertext instanceof Uint8Array) || ciphertext.length < TAG_LENGTH)
+        throw new LfcpError("AEAD_AUTHENTICATION_FAILED", "the ciphertext is shorter than the tag");
+    const k = Uint8Array.from(snapshotKeyBytes(key));
+    try {
+        return chacha20poly1305(k, nonce, aad).decrypt(ciphertext);
+    }
+    catch {
+        throw new LfcpError("AEAD_AUTHENTICATION_FAILED", "the Snapshot does not authenticate under this key, sequence and AAD");
+    }
+    finally {
+        k.fill(0);
+    }
+}
+//# sourceMappingURL=aead.js.map

package/dist/epoch.d.ts

@@ -0,0 +1,54 @@
+import { type ActorSequence, type DataEpoch, type Hash32, type PrincipalId, type ResourceId } from "@openlfcp/core";
+declare const INSPECT: unique symbol;
+/** 32 secret bytes with redacted diagnostics. */
+declare abstract class SymmetricSecret {
+    #private;
+    protected constructor(kind: string, bytes: Uint8Array);
+    toJSON(): string;
+    toString(): string;
+    [INSPECT](): string;
+}
+/** A Resource Data Encryption Key for one Data Epoch (§11). */
+export declare class ResourceDEK extends SymmetricSecret {
+    readonly kind = "ResourceDEK";
+    private constructor();
+}
+/** A writer's ChaCha20-Poly1305 key for one (Resource, Data Epoch) (§12). */
+export declare class ActorDataKey extends SymmetricSecret {
+    readonly kind = "ActorDataKey";
+    private constructor();
+}
+/** A Snapshot publisher's ChaCha20-Poly1305 key for one (Resource, Data Epoch) (§29.1.1). */
+export declare class SnapshotKey extends SymmetricSecret {
+    readonly kind = "SnapshotKey";
+    private constructor();
+}
+/** True for the symmetric secrets of this module. */
+export declare const isSymmetricSecret: (value: unknown) => value is SymmetricSecret;
+/** The secret bytes (for exportSecretKeyBytes only). */
+export declare const symmetricSecretBytes: (secret: SymmetricSecret) => Uint8Array;
+/** A fresh DEK: 32 bytes from the platform CSPRNG (§11 "MUST be generated randomly"). */
+export declare function generateResourceDEK(): ResourceDEK;
+/** Restores a DEK from its 32 bytes (a received Key Package, local secret storage). The input is copied. */
+export declare function importResourceDEK(bytes: Uint8Array): ResourceDEK;
+/** dek_commitment = SHA-256(ASCII("LFCP-DEK-v1") || resource_id || uint64_be(E) || DEK) (§11). */
+export declare function dekCommitment(resource: ResourceId, epoch: DataEpoch, dek: ResourceDEK): Hash32;
+/**
+ * actor_key = HKDF-Expand(HKDF-Extract(R || uint64_be(E), DEK),
+ *                         ASCII("LFCP-DATA-KEY-v1") || A, 32)   (§12)
+ */
+export declare function deriveActorDataKey(dek: ResourceDEK, resource: ResourceId, epoch: DataEpoch, actor: PrincipalId): ActorDataKey;
+/**
+ * snapshot_key = HKDF-Expand(HKDF-Extract(resource_id || uint64_be(E), DEK),
+ *                            ASCII("LFCP-SNAPSHOT-KEY-v1") || publisher, 32)   (§29.1.1)
+ */
+export declare function deriveSnapshotKey(dek: ResourceDEK, resource: ResourceId, epoch: DataEpoch, publisher: PrincipalId): SnapshotKey;
+/** nonce = 0x00000000 || uint64_be(seq), 12 bytes, for actor sequence 1..2^64-1 (§8, §12). */
+export declare function dataUnitNonce(seq: ActorSequence): Uint8Array;
+/**
+ * snapshot_nonce = 0x00000000 || uint64_be(snapshot_sequence), 12 bytes
+ * (§29.1.2). The sequence must fit in uint64; §29 sets no lower bound.
+ */
+export declare function snapshotNonce(snapshotSequence: bigint): Uint8Array;
+export {};
+//# sourceMappingURL=epoch.d.ts.map

package/dist/epoch.js

@@ -0,0 +1,176 @@
+import { randomBytes } from "@noble/hashes/utils.js";
+import { actorSequence, dataEpoch, hash32, ID32_LENGTH, LfcpError, uint64BE, } from "@openlfcp/core";
+import { sha256 } from "./hash.js";
+import { hkdfExpand, hkdfExtract } from "./hkdf.js";
+/**
+ * Data Epoch key material (LFCP-WIRE-01 §11, §12, §29.1.1, §29.1.2).
+ *
+ * - The Resource DEK is 32 random bytes per (Resource, Data Epoch), from the
+ *   platform CSPRNG; it is never derived from IDs, identities or time.
+ * - Its public commitment is SHA-256("LFCP-DEK-v1" || R || uint64_be(E) || DEK).
+ * - Each writer encrypts with its own actor key,
+ *   HKDF-Expand(HKDF-Extract(R || uint64_be(E), DEK), "LFCP-DATA-KEY-v1" || A, 32),
+ *   and nonce 0x00000000 || uint64_be(seq). The same sequence is safe for
+ *   different Principals because their keys differ; reusing a sequence for
+ *   one (Resource, Principal) is forbidden (§8, §12), across epochs too.
+ * - A Snapshot publisher uses the same construction with the label
+ *   "LFCP-SNAPSHOT-KEY-v1" and its Snapshot Sequence.
+ *
+ * All IDs are the raw 32 bytes, never text forms. Secrets (ResourceDEK,
+ * ActorDataKey, SnapshotKey) keep their bytes in a private field and print
+ * as "[redacted]" through toJSON, toString and inspect; the only way out is
+ * `exportSecretKeyBytes`. Errors never include key bytes.
+ */
+const REDACTED = "[redacted]";
+const INSPECT = Symbol.for("nodejs.util.inspect.custom");
+const KEY_LENGTH = 32;
+const ascii = (text) => Uint8Array.from(text, (c) => c.charCodeAt(0));
+const DEK_LABEL = ascii("LFCP-DEK-v1");
+const DATA_KEY_LABEL = ascii("LFCP-DATA-KEY-v1");
+const SNAPSHOT_KEY_LABEL = ascii("LFCP-SNAPSHOT-KEY-v1");
+const NONCE_PREFIX = new Uint8Array(4);
+let readSecret;
+/** 32 secret bytes with redacted diagnostics. */
+class SymmetricSecret {
+    #bytes;
+    static {
+        readSecret = (secret) => secret.#bytes;
+    }
+    constructor(kind, bytes) {
+        if (!(bytes instanceof Uint8Array) || bytes.length !== KEY_LENGTH)
+            throw new LfcpError("INVALID_LENGTH", `${kind} must be exactly ${KEY_LENGTH} bytes`);
+        this.#bytes = Uint8Array.from(bytes);
+    }
+    toJSON() {
+        return REDACTED;
+    }
+    toString() {
+        return REDACTED;
+    }
+    [INSPECT]() {
+        return REDACTED;
+    }
+}
+let makeDek;
+let makeActorKey;
+let makeSnapshotKey;
+/** A Resource Data Encryption Key for one Data Epoch (§11). */
+export class ResourceDEK extends SymmetricSecret {
+    kind = "ResourceDEK";
+    static {
+        makeDek = (bytes) => new ResourceDEK(bytes);
+    }
+    constructor(bytes) {
+        super("a Resource DEK", bytes);
+    }
+}
+/** A writer's ChaCha20-Poly1305 key for one (Resource, Data Epoch) (§12). */
+export class ActorDataKey extends SymmetricSecret {
+    kind = "ActorDataKey";
+    static {
+        makeActorKey = (bytes) => new ActorDataKey(bytes);
+    }
+    constructor(bytes) {
+        super("an actor data key", bytes);
+    }
+}
+/** A Snapshot publisher's ChaCha20-Poly1305 key for one (Resource, Data Epoch) (§29.1.1). */
+export class SnapshotKey extends SymmetricSecret {
+    kind = "SnapshotKey";
+    static {
+        makeSnapshotKey = (bytes) => new SnapshotKey(bytes);
+    }
+    constructor(bytes) {
+        super("a Snapshot key", bytes);
+    }
+}
+/** True for the symmetric secrets of this module. */
+export const isSymmetricSecret = (value) => value instanceof SymmetricSecret;
+/** The secret bytes (for exportSecretKeyBytes only). */
+export const symmetricSecretBytes = (secret) => readSecret(secret);
+function id32(what, id) {
+    if (!(id instanceof Uint8Array) || id.length !== ID32_LENGTH)
+        throw new LfcpError("INVALID_LENGTH", `${what} must be the raw ${ID32_LENGTH}-byte ID`);
+    return id;
+}
+function concat(...parts) {
+    const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0));
+    let at = 0;
+    for (const p of parts) {
+        out.set(p, at);
+        at += p.length;
+    }
+    return out;
+}
+function dekOf(dek) {
+    if (!(dek instanceof ResourceDEK))
+        throw new LfcpError("CRYPTO_FAILURE", "expected a ResourceDEK");
+    return readSecret(dek);
+}
+/** A fresh DEK: 32 bytes from the platform CSPRNG (§11 "MUST be generated randomly"). */
+export function generateResourceDEK() {
+    let bytes;
+    try {
+        bytes = randomBytes(KEY_LENGTH);
+    }
+    catch {
+        throw new LfcpError("NO_SECURE_RANDOM", "no CSPRNG (crypto.getRandomValues) is available");
+    }
+    return makeDek(bytes);
+}
+/** Restores a DEK from its 32 bytes (a received Key Package, local secret storage). The input is copied. */
+export function importResourceDEK(bytes) {
+    return makeDek(bytes);
+}
+/** dek_commitment = SHA-256(ASCII("LFCP-DEK-v1") || resource_id || uint64_be(E) || DEK) (§11). */
+export function dekCommitment(resource, epoch, dek) {
+    return hash32(sha256(concat(DEK_LABEL, id32("the Resource ID", resource), uint64BE(dataEpoch(epoch)), dekOf(dek))));
+}
+function epochKey(dek, resource, epoch, label, principal) {
+    const salt = concat(id32("the Resource ID", resource), uint64BE(dataEpoch(epoch)));
+    const prk = hkdfExtract(salt, dekOf(dek));
+    try {
+        return hkdfExpand(prk, concat(label, id32("the Principal ID", principal)), KEY_LENGTH);
+    }
+    finally {
+        prk.fill(0);
+    }
+}
+/**
+ * actor_key = HKDF-Expand(HKDF-Extract(R || uint64_be(E), DEK),
+ *                         ASCII("LFCP-DATA-KEY-v1") || A, 32)   (§12)
+ */
+export function deriveActorDataKey(dek, resource, epoch, actor) {
+    const bytes = epochKey(dek, resource, epoch, DATA_KEY_LABEL, actor);
+    try {
+        return makeActorKey(bytes);
+    }
+    finally {
+        bytes.fill(0);
+    }
+}
+/**
+ * snapshot_key = HKDF-Expand(HKDF-Extract(resource_id || uint64_be(E), DEK),
+ *                            ASCII("LFCP-SNAPSHOT-KEY-v1") || publisher, 32)   (§29.1.1)
+ */
+export function deriveSnapshotKey(dek, resource, epoch, publisher) {
+    const bytes = epochKey(dek, resource, epoch, SNAPSHOT_KEY_LABEL, publisher);
+    try {
+        return makeSnapshotKey(bytes);
+    }
+    finally {
+        bytes.fill(0);
+    }
+}
+/** nonce = 0x00000000 || uint64_be(seq), 12 bytes, for actor sequence 1..2^64-1 (§8, §12). */
+export function dataUnitNonce(seq) {
+    return concat(NONCE_PREFIX, uint64BE(actorSequence(seq)));
+}
+/**
+ * snapshot_nonce = 0x00000000 || uint64_be(snapshot_sequence), 12 bytes
+ * (§29.1.2). The sequence must fit in uint64; §29 sets no lower bound.
+ */
+export function snapshotNonce(snapshotSequence) {
+    return concat(NONCE_PREFIX, uint64BE(snapshotSequence));
+}
+//# sourceMappingURL=epoch.js.map

package/dist/hash.d.ts

@@ -0,0 +1,3 @@
+/** SHA-256 (FIPS 180-4), the `hash32` function of LFCP-WIRE-01 §5.3. */
+export declare function sha256(data: Uint8Array): Uint8Array;
+//# sourceMappingURL=hash.d.ts.map

package/dist/hash.js

@@ -0,0 +1,6 @@
+import { sha256 as nobleSha256 } from "@noble/hashes/sha2.js";
+/** SHA-256 (FIPS 180-4), the `hash32` function of LFCP-WIRE-01 §5.3. */
+export function sha256(data) {
+    return nobleSha256(data);
+}
+//# sourceMappingURL=hash.js.map

package/dist/hkdf.d.ts

@@ -0,0 +1,5 @@
+/** HKDF-Extract(salt, IKM) with SHA-256: the 32-byte PRK. The result is secret material. */
+export declare function hkdfExtract(salt: Uint8Array, ikm: Uint8Array): Uint8Array;
+/** HKDF-Expand(PRK, info, L) with SHA-256. The result is secret material. */
+export declare function hkdfExpand(prk: Uint8Array, info: Uint8Array, length: number): Uint8Array;
+//# sourceMappingURL=hkdf.d.ts.map

package/dist/hkdf.js

@@ -0,0 +1,20 @@
+import { expand, extract } from "@noble/hashes/hkdf.js";
+import { sha256 as nobleSha256 } from "@noble/hashes/sha2.js";
+import { LfcpError } from "@openlfcp/core";
+// HKDF-SHA256 (RFC 5869), the KDF of the LFCP crypto profile (LFCP-WIRE-01 §9).
+const MAX_OUTPUT = 255 * 32;
+/** HKDF-Extract(salt, IKM) with SHA-256: the 32-byte PRK. The result is secret material. */
+export function hkdfExtract(salt, ikm) {
+    if (!(salt instanceof Uint8Array) || !(ikm instanceof Uint8Array))
+        throw new LfcpError("INVALID_LENGTH", "HKDF-Extract takes byte strings");
+    return extract(nobleSha256, ikm, salt);
+}
+/** HKDF-Expand(PRK, info, L) with SHA-256. The result is secret material. */
+export function hkdfExpand(prk, info, length) {
+    if (!(prk instanceof Uint8Array) || prk.length < 32 || !(info instanceof Uint8Array))
+        throw new LfcpError("INVALID_LENGTH", "HKDF-Expand takes a PRK of at least 32 bytes and info bytes");
+    if (!Number.isSafeInteger(length) || length < 1 || length > MAX_OUTPUT)
+        throw new LfcpError("OUT_OF_RANGE", `HKDF-Expand length must be in 1..${MAX_OUTPUT}`);
+    return expand(nobleSha256, prk, info, length);
+}
+//# sourceMappingURL=hkdf.js.map

package/dist/hpke.d.ts

@@ -0,0 +1,19 @@
+import { type ResourceDEK } from "./epoch.js";
+import { type AgreementKeyPair } from "./keys.js";
+/** HPKE output: the encapsulated key (enc) and the ciphertext of the DEK. */
+export interface SealedDek {
+    readonly enc: Uint8Array;
+    readonly ciphertext: Uint8Array;
+}
+/** Seals `dek` to the recipient's X25519 public key with `info` and `aad` (§25.1). */
+export declare function sealDek(recipientPublicKey: Uint8Array, dek: ResourceDEK, info: Uint8Array, aad: Uint8Array): Promise<SealedDek>;
+/**
+ * Opens an HPKE-sealed DEK with the recipient's X25519 key pair. An HPKE
+ * failure (wrong key, tampered enc, ciphertext, info or AAD) is
+ * KEY_PACKAGE_OPEN_FAILED. A plaintext that is not 32 bytes is
+ * DEK_COMMITMENT_MISMATCH (LFCP-WIRE-01 §25.2: "A decrypted plaintext that
+ * is not exactly 32 bytes long is a DEK that does not match the
+ * commitment"). Both are client-local (ADR 0001 N5).
+ */
+export declare function openDek(recipient: AgreementKeyPair, enc: Uint8Array, ciphertext: Uint8Array, info: Uint8Array, aad: Uint8Array): Promise<ResourceDEK>;
+//# sourceMappingURL=hpke.d.ts.map

package/dist/hpke.js

@@ -0,0 +1,62 @@
+import { LfcpError } from "@openlfcp/core";
+import { AEAD_ChaCha20Poly1305, KDF_HKDF_SHA256, KEM_DHKEM_X25519_HKDF_SHA256, } from "@panva/hpke-noble";
+import { CipherSuite } from "hpke";
+import { importResourceDEK, symmetricSecretBytes } from "./epoch.js";
+import { agreementSecretBytes } from "./keys.js";
+/**
+ * RFC 9180 HPKE for LFCP Key Packages (LFCP-WIRE-01 §9, §25): Base mode
+ * with DHKEM(X25519, HKDF-SHA256) 0x0020, HKDF-SHA256 0x0001 and
+ * ChaCha20-Poly1305 0x0003. The protocol is the `hpke` library's; the
+ * primitives are the audited noble packages through @panva/hpke-noble.
+ *
+ * The plaintext is exactly the 32-byte DEK. Sealing always draws a fresh
+ * ephemeral key from the platform CSPRNG; there is no way to pass one in.
+ * Secrets (the DEK, the recipient key, the ephemeral key, the shared
+ * secret) never appear in errors.
+ */
+const SUITE = new CipherSuite(KEM_DHKEM_X25519_HKDF_SHA256, KDF_HKDF_SHA256, AEAD_ChaCha20Poly1305);
+const KEY_LENGTH = 32;
+/** Seals `dek` to the recipient's X25519 public key with `info` and `aad` (§25.1). */
+export async function sealDek(recipientPublicKey, dek, info, aad) {
+    if (!(recipientPublicKey instanceof Uint8Array) || recipientPublicKey.length !== KEY_LENGTH)
+        throw new LfcpError("INVALID_LENGTH", "an X25519 public key must be exactly 32 bytes");
+    const plaintext = Uint8Array.from(symmetricSecretBytes(dek));
+    try {
+        const pk = await SUITE.DeserializePublicKey(Uint8Array.from(recipientPublicKey));
+        const sealed = await SUITE.Seal(pk, plaintext, { info, aad });
+        return Object.freeze({ enc: sealed.encapsulatedSecret, ciphertext: sealed.ciphertext });
+    }
+    catch {
+        throw new LfcpError("CRYPTO_FAILURE", "HPKE seal failed");
+    }
+    finally {
+        plaintext.fill(0);
+    }
+}
+/**
+ * Opens an HPKE-sealed DEK with the recipient's X25519 key pair. An HPKE
+ * failure (wrong key, tampered enc, ciphertext, info or AAD) is
+ * KEY_PACKAGE_OPEN_FAILED. A plaintext that is not 32 bytes is
+ * DEK_COMMITMENT_MISMATCH (LFCP-WIRE-01 §25.2: "A decrypted plaintext that
+ * is not exactly 32 bytes long is a DEK that does not match the
+ * commitment"). Both are client-local (ADR 0001 N5).
+ */
+export async function openDek(recipient, enc, ciphertext, info, aad) {
+    let plaintext;
+    try {
+        const sk = await SUITE.DeserializePrivateKey(Uint8Array.from(agreementSecretBytes(recipient)), false);
+        plaintext = await SUITE.Open(sk, enc, ciphertext, { info, aad });
+    }
+    catch {
+        throw new LfcpError("KEY_PACKAGE_OPEN_FAILED", "the Key Package does not open with this recipient key");
+    }
+    try {
+        if (plaintext.length !== KEY_LENGTH)
+            throw new LfcpError("DEK_COMMITMENT_MISMATCH", "the Key Package plaintext is not a 32-byte DEK, so it matches no commitment");
+        return importResourceDEK(plaintext);
+    }
+    finally {
+        plaintext.fill(0);
+    }
+}
+//# sourceMappingURL=hpke.js.map

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Cryptographic primitives for LFCP, as a thin wrapper over the audited
+ * @noble libraries. No other package imports @noble directly.
+ */
+export declare const PACKAGE = "@openlfcp/crypto";
+export { decryptDataUnit, decryptSnapshot, encryptDataUnit, encryptSnapshot } from "./aead.js";
+export { ActorDataKey, dataUnitNonce, dekCommitment, deriveActorDataKey, deriveSnapshotKey, generateResourceDEK, importResourceDEK, ResourceDEK, SnapshotKey, snapshotNonce, } from "./epoch.js";
+export { sha256 } from "./hash.js";
+export { hkdfExpand, hkdfExtract } from "./hkdf.js";
+export { openDek, type SealedDek, sealDek } from "./hpke.js";
+export { InvitationSecret } from "./invitation.js";
+export { AgreementKeyPair, exportSecretKeyBytes, generateAgreementKeyPair, generateSigningKeyPair, importAgreementKey, importSigningKey, isValidEd25519PublicKey, SigningKeyPair, verifyEd25519, } from "./keys.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,13 @@
+/**
+ * Cryptographic primitives for LFCP, as a thin wrapper over the audited
+ * @noble libraries. No other package imports @noble directly.
+ */
+export const PACKAGE = "@openlfcp/crypto";
+export { decryptDataUnit, decryptSnapshot, encryptDataUnit, encryptSnapshot } from "./aead.js";
+export { ActorDataKey, dataUnitNonce, dekCommitment, deriveActorDataKey, deriveSnapshotKey, generateResourceDEK, importResourceDEK, ResourceDEK, SnapshotKey, snapshotNonce, } from "./epoch.js";
+export { sha256 } from "./hash.js";
+export { hkdfExpand, hkdfExtract } from "./hkdf.js";
+export { openDek, sealDek } from "./hpke.js";
+export { InvitationSecret } from "./invitation.js";
+export { AgreementKeyPair, exportSecretKeyBytes, generateAgreementKeyPair, generateSigningKeyPair, importAgreementKey, importSigningKey, isValidEd25519PublicKey, SigningKeyPair, verifyEd25519, } from "./keys.js";
+//# sourceMappingURL=index.js.map

package/dist/invitation.d.ts

@@ -0,0 +1,29 @@
+import { type AgreementKeyPair, type SigningKeyPair } from "./keys.js";
+/**
+ * The key material of an Invitation Principal (LFCP-WIRE-01 §18, §18.2):
+ * the ephemeral Principal an inviter creates for one invitation, whose
+ * private keys travel in the `#secret=` fragment of a bearer invitation
+ * URI.
+ *
+ * Like every key in this package, it is redacted: `toJSON`, `toString`
+ * and Node's inspect hook print "[redacted]", and the two key pairs it
+ * holds are redacted themselves. The secret is encoded only by the
+ * invitation codec of @openlfcp/wire, for the URI fragment. §18.2: it MUST
+ * NOT be logged, placed in analytics or transmitted to a synchronization
+ * server.
+ */
+export declare class InvitationSecret {
+    #private;
+    private constructor();
+    /** A fresh Invitation Principal: independent Ed25519 and X25519 keys from the platform CSPRNG. */
+    static generate(): InvitationSecret;
+    /** An Invitation Principal from its key pairs (for example, decoded from a URI fragment). */
+    static fromKeys(signing: SigningKeyPair, agreement: AgreementKeyPair): InvitationSecret;
+    /** The Ed25519 key pair: signs the CAPABILITY_CLAIM record (§18.1). */
+    get signingKey(): SigningKeyPair;
+    /** The X25519 key pair: opens the Key Package sealed to the Invitation Principal (§18, §25). */
+    get agreementKey(): AgreementKeyPair;
+    toJSON(): string;
+    toString(): string;
+}
+//# sourceMappingURL=invitation.d.ts.map

package/dist/invitation.js

@@ -0,0 +1,48 @@
+import { generateAgreementKeyPair, generateSigningKeyPair, } from "./keys.js";
+/**
+ * The key material of an Invitation Principal (LFCP-WIRE-01 §18, §18.2):
+ * the ephemeral Principal an inviter creates for one invitation, whose
+ * private keys travel in the `#secret=` fragment of a bearer invitation
+ * URI.
+ *
+ * Like every key in this package, it is redacted: `toJSON`, `toString`
+ * and Node's inspect hook print "[redacted]", and the two key pairs it
+ * holds are redacted themselves. The secret is encoded only by the
+ * invitation codec of @openlfcp/wire, for the URI fragment. §18.2: it MUST
+ * NOT be logged, placed in analytics or transmitted to a synchronization
+ * server.
+ */
+export class InvitationSecret {
+    #signing;
+    #agreement;
+    constructor(signing, agreement) {
+        this.#signing = signing;
+        this.#agreement = agreement;
+    }
+    /** A fresh Invitation Principal: independent Ed25519 and X25519 keys from the platform CSPRNG. */
+    static generate() {
+        return new InvitationSecret(generateSigningKeyPair(), generateAgreementKeyPair());
+    }
+    /** An Invitation Principal from its key pairs (for example, decoded from a URI fragment). */
+    static fromKeys(signing, agreement) {
+        return new InvitationSecret(signing, agreement);
+    }
+    /** The Ed25519 key pair: signs the CAPABILITY_CLAIM record (§18.1). */
+    get signingKey() {
+        return this.#signing;
+    }
+    /** The X25519 key pair: opens the Key Package sealed to the Invitation Principal (§18, §25). */
+    get agreementKey() {
+        return this.#agreement;
+    }
+    toJSON() {
+        return "[redacted]";
+    }
+    toString() {
+        return "[redacted]";
+    }
+    [Symbol.for("nodejs.util.inspect.custom")]() {
+        return "[redacted]";
+    }
+}
+//# sourceMappingURL=invitation.js.map

package/dist/keys.d.ts

@@ -0,0 +1,76 @@
+import { type ActorDataKey, type ResourceDEK, type SnapshotKey } from "./epoch.js";
+declare const INSPECT: unique symbol;
+/** An Ed25519 key pair. The secret is the 32-byte RFC 8032 seed. */
+export declare class SigningKeyPair {
+    #private;
+    /** The 32-byte Ed25519 public key. */
+    readonly publicKey: Uint8Array;
+    private constructor();
+    /** Ed25519 signature (64 bytes) over `message`. */
+    sign(message: Uint8Array): Uint8Array;
+    toJSON(): string;
+    toString(): string;
+    [INSPECT](): string;
+}
+/** An X25519 key pair. The secret is the 32-byte RFC 7748 scalar. */
+export declare class AgreementKeyPair {
+    #private;
+    /** The 32-byte X25519 public key. */
+    readonly publicKey: Uint8Array;
+    private constructor();
+    /**
+     * X25519 shared secret with `peerPublicKey` (RFC 7748). The result is
+     * secret material: treat it like a private key.
+     */
+    sharedSecret(peerPublicKey: Uint8Array): Uint8Array;
+    toJSON(): string;
+    toString(): string;
+    [INSPECT](): string;
+}
+/** A fresh Ed25519 key pair from the platform CSPRNG. */
+export declare function generateSigningKeyPair(): SigningKeyPair;
+/** A fresh X25519 key pair from the platform CSPRNG, independent of any signing key. */
+export declare function generateAgreementKeyPair(): AgreementKeyPair;
+/** Restores an Ed25519 key pair from its 32-byte seed. The input is copied. */
+export declare function importSigningKey(secret: Uint8Array): SigningKeyPair;
+/** Restores an X25519 key pair from its 32-byte secret scalar. The input is copied. */
+export declare function importAgreementKey(secret: Uint8Array): AgreementKeyPair;
+/**
+ * Returns a copy of the secret bytes of a key pair or a Data Epoch key, for
+ * persistence (or, for a DEK, HPKE delivery to a recipient) only.
+ *
+ * WARNING: the result is secret. Never log it, put it in errors or
+ * diagnostics, or send it anywhere except an encrypted local secret store.
+ */
+export declare function exportSecretKeyBytes(key: SigningKeyPair | AgreementKeyPair | ResourceDEK | ActorDataKey | SnapshotKey): Uint8Array;
+/**
+ * The X25519 secret of a key pair, for this package's HPKE module only. It
+ * is not re-exported from the package index.
+ */
+export declare const agreementSecretBytes: (key: AgreementKeyPair) => Uint8Array;
+/**
+ * Whether `publicKey` is a canonical Ed25519 point encoding that is not of
+ * small order (LFCP-WIRE-01 §7, §10.5.1 rules 2 and 3), as required of every
+ * descriptor's Ed25519 key at receipt.
+ */
+export declare function isValidEd25519PublicKey(publicKey: Uint8Array): boolean;
+/**
+ * Strict Ed25519 verification, LFCP-WIRE-01 §10.5.1. Returns false (never
+ * throws) for any malformed or invalid input. The checks run in this order:
+ *
+ * 1. decode: A and R are canonical point encodings (y < p; x = 0 with the
+ *    sign bit set is refused) — rule 2;
+ * 2. S < L — rule 1;
+ * 3. neither A nor R is of small order — rule 3;
+ * 4. the cofactorless equation [S]B = R + [k]A, where k = SHA-512 of the
+ *    exact received R bytes, the exact A bytes and M, reduced mod L — rule 4.
+ *
+ * noble's `ed25519.verify` is not used: it checks the cofactored equation
+ * ([8][S]B = [8]R + [8][k]A) and does not refuse a small-order R, so it
+ * accepts signatures §10.5.1 rejects (a mixed-order A or R, a small-order
+ * R). The rules are composed here from noble's point decoding and
+ * arithmetic, and R and A are never re-encoded.
+ */
+export declare function verifyEd25519(publicKey: Uint8Array, message: Uint8Array, signature: Uint8Array): boolean;
+export {};
+//# sourceMappingURL=keys.d.ts.map

package/dist/keys.js

@@ -0,0 +1,206 @@
+import { ed25519, x25519 } from "@noble/curves/ed25519.js";
+import { bytesToNumberLE, concatBytes } from "@noble/curves/utils.js";
+import { sha512 } from "@noble/hashes/sha2.js";
+import { LfcpError } from "@openlfcp/core";
+import { isSymmetricSecret, symmetricSecretBytes, } from "./epoch.js";
+/**
+ * Key material for an LFCP Principal (LFCP-WIRE-01 §7): an Ed25519 signing
+ * key and an independent X25519 key-agreement key. Neither is derived from
+ * the other.
+ *
+ * Private bytes live only in a private class field. `toJSON`, `toString`
+ * and Node's inspect hook all print "[redacted]", no enumerable property
+ * holds secret bytes, and errors never include key bytes. The only way to
+ * read the bytes is `exportSecretKeyBytes`.
+ */
+const REDACTED = "[redacted]";
+const INSPECT = Symbol.for("nodejs.util.inspect.custom");
+const KEY_LENGTH = 32;
+function requireKeyBytes(kind, bytes) {
+    if (!(bytes instanceof Uint8Array) || bytes.length !== KEY_LENGTH) {
+        throw new LfcpError("INVALID_LENGTH", `${kind} must be exactly ${KEY_LENGTH} bytes`);
+    }
+    return Uint8Array.from(bytes);
+}
+/** Runs a primitive and replaces any error with one that cannot carry key material. */
+function guarded(what, fn) {
+    try {
+        return fn();
+    }
+    catch {
+        throw new LfcpError("CRYPTO_FAILURE", `${what} failed`);
+    }
+}
+// Module-private access, assigned in the class static blocks, so the only
+// public ways in and out are the import/export functions below.
+let makeSigningKeyPair;
+let readSigningSecret;
+let makeAgreementKeyPair;
+let readAgreementSecret;
+/** An Ed25519 key pair. The secret is the 32-byte RFC 8032 seed. */
+export class SigningKeyPair {
+    #secret;
+    /** The 32-byte Ed25519 public key. */
+    publicKey;
+    static {
+        makeSigningKeyPair = (secret) => new SigningKeyPair(requireKeyBytes("an Ed25519 secret key", secret));
+        readSigningSecret = (key) => key.#secret;
+    }
+    constructor(secret) {
+        this.#secret = secret;
+        this.publicKey = guarded("Ed25519 public key derivation", () => ed25519.getPublicKey(secret));
+    }
+    /** Ed25519 signature (64 bytes) over `message`. */
+    sign(message) {
+        return guarded("Ed25519 signing", () => ed25519.sign(message, this.#secret));
+    }
+    toJSON() {
+        return REDACTED;
+    }
+    toString() {
+        return REDACTED;
+    }
+    [INSPECT]() {
+        return REDACTED;
+    }
+}
+/** An X25519 key pair. The secret is the 32-byte RFC 7748 scalar. */
+export class AgreementKeyPair {
+    #secret;
+    /** The 32-byte X25519 public key. */
+    publicKey;
+    static {
+        makeAgreementKeyPair = (secret) => new AgreementKeyPair(requireKeyBytes("an X25519 secret key", secret));
+        readAgreementSecret = (key) => key.#secret;
+    }
+    constructor(secret) {
+        this.#secret = secret;
+        this.publicKey = guarded("X25519 public key derivation", () => x25519.getPublicKey(secret));
+    }
+    /**
+     * X25519 shared secret with `peerPublicKey` (RFC 7748). The result is
+     * secret material: treat it like a private key.
+     */
+    sharedSecret(peerPublicKey) {
+        if (!(peerPublicKey instanceof Uint8Array) || peerPublicKey.length !== KEY_LENGTH) {
+            throw new LfcpError("INVALID_LENGTH", `an X25519 public key must be exactly ${KEY_LENGTH} bytes`);
+        }
+        return guarded("X25519 agreement", () => x25519.getSharedSecret(this.#secret, peerPublicKey));
+    }
+    toJSON() {
+        return REDACTED;
+    }
+    toString() {
+        return REDACTED;
+    }
+    [INSPECT]() {
+        return REDACTED;
+    }
+}
+/** A fresh Ed25519 key pair from the platform CSPRNG. */
+export function generateSigningKeyPair() {
+    return makeSigningKeyPair(guarded("Ed25519 key generation", () => ed25519.utils.randomSecretKey()));
+}
+/** A fresh X25519 key pair from the platform CSPRNG, independent of any signing key. */
+export function generateAgreementKeyPair() {
+    return makeAgreementKeyPair(guarded("X25519 key generation", () => x25519.utils.randomSecretKey()));
+}
+/** Restores an Ed25519 key pair from its 32-byte seed. The input is copied. */
+export function importSigningKey(secret) {
+    return makeSigningKeyPair(secret);
+}
+/** Restores an X25519 key pair from its 32-byte secret scalar. The input is copied. */
+export function importAgreementKey(secret) {
+    return makeAgreementKeyPair(secret);
+}
+/**
+ * Returns a copy of the secret bytes of a key pair or a Data Epoch key, for
+ * persistence (or, for a DEK, HPKE delivery to a recipient) only.
+ *
+ * WARNING: the result is secret. Never log it, put it in errors or
+ * diagnostics, or send it anywhere except an encrypted local secret store.
+ */
+export function exportSecretKeyBytes(key) {
+    if (key instanceof SigningKeyPair)
+        return Uint8Array.from(readSigningSecret(key));
+    if (key instanceof AgreementKeyPair)
+        return Uint8Array.from(readAgreementSecret(key));
+    if (isSymmetricSecret(key))
+        return Uint8Array.from(symmetricSecretBytes(key));
+    throw new LfcpError("CRYPTO_FAILURE", "not a secret key of this package");
+}
+/**
+ * The X25519 secret of a key pair, for this package's HPKE module only. It
+ * is not re-exported from the package index.
+ */
+export const agreementSecretBytes = (key) => readAgreementSecret(key);
+const POINT = ed25519.Point;
+/** The Ed25519 group order L. */
+const L = POINT.Fn.ORDER;
+/**
+ * Decodes an Ed25519 point under §10.5.1 rule 2: y < p, and x = 0 with the
+ * sign bit set is refused. Returns undefined for a non-canonical or
+ * off-curve encoding.
+ */
+function decodePoint(bytes) {
+    try {
+        return POINT.fromBytes(bytes, false);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Whether `publicKey` is a canonical Ed25519 point encoding that is not of
+ * small order (LFCP-WIRE-01 §7, §10.5.1 rules 2 and 3), as required of every
+ * descriptor's Ed25519 key at receipt.
+ */
+export function isValidEd25519PublicKey(publicKey) {
+    if (!(publicKey instanceof Uint8Array) || publicKey.length !== KEY_LENGTH)
+        return false;
+    const a = decodePoint(publicKey);
+    return a !== undefined && !a.isSmallOrder();
+}
+/**
+ * Strict Ed25519 verification, LFCP-WIRE-01 §10.5.1. Returns false (never
+ * throws) for any malformed or invalid input. The checks run in this order:
+ *
+ * 1. decode: A and R are canonical point encodings (y < p; x = 0 with the
+ *    sign bit set is refused) — rule 2;
+ * 2. S < L — rule 1;
+ * 3. neither A nor R is of small order — rule 3;
+ * 4. the cofactorless equation [S]B = R + [k]A, where k = SHA-512 of the
+ *    exact received R bytes, the exact A bytes and M, reduced mod L — rule 4.
+ *
+ * noble's `ed25519.verify` is not used: it checks the cofactored equation
+ * ([8][S]B = [8]R + [8][k]A) and does not refuse a small-order R, so it
+ * accepts signatures §10.5.1 rejects (a mixed-order A or R, a small-order
+ * R). The rules are composed here from noble's point decoding and
+ * arithmetic, and R and A are never re-encoded.
+ */
+export function verifyEd25519(publicKey, message, signature) {
+    try {
+        if (!(publicKey instanceof Uint8Array) ||
+            !(message instanceof Uint8Array) ||
+            !(signature instanceof Uint8Array) ||
+            publicKey.length !== KEY_LENGTH ||
+            signature.length !== 2 * KEY_LENGTH)
+            return false;
+        const rBytes = signature.subarray(0, KEY_LENGTH);
+        const a = decodePoint(publicKey);
+        const r = decodePoint(rBytes);
+        if (a === undefined || r === undefined)
+            return false;
+        const s = bytesToNumberLE(signature.subarray(KEY_LENGTH));
+        if (s >= L)
+            return false;
+        if (a.isSmallOrder() || r.isSmallOrder())
+            return false;
+        const k = bytesToNumberLE(sha512(concatBytes(rBytes, publicKey, message))) % L;
+        return POINT.BASE.multiplyUnsafe(s).equals(r.add(a.multiplyUnsafe(k)));
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=keys.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openlfcp/crypto",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "The cryptography of LFCP (SHA-256, Ed25519, X25519, HKDF, ChaCha20-Poly1305, HPKE) on audited primitives (@noble, hpke).",
   "keywords": [
     "openlfcp",
@@ -49,6 +49,6 @@
     "@noble/hashes": "^2.4.0",
     "@panva/hpke-noble": "^1.1.7",
     "hpke": "^1.1.7",
-    "@openlfcp/core": "^0.1.2"
+    "@openlfcp/core": "^0.1.4"
   }
 }