@openlfcp/crypto 0.0.0-stage → 0.1.0-rc.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,27 @@
-# Temporary Holding Version
+# @openlfcp/crypto
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The cryptography of LFCP on audited primitives: SHA-256, Ed25519 signatures (strict verification), X25519, HKDF, ChaCha20-Poly1305 and HPKE for Key Packages, Resource DEKs and their commitments. It is the only package that uses `@noble/*` and `hpke` directly.
+
+```sh
+npm install @openlfcp/crypto@next
+```
+
+ESM only; Node.js 24 or later (browsers and Electron for every package except `@openlfcp/storage-node`).
+
+## Scope
+
+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.8`, not every deferred WIRE-01 feature. It does not
+claim full LFCP-WIRE-01 conformance. This is a release candidate
+(`0.1.0-rc.1`, npm dist-tag `next`): APIs may still change.
+
+## Links
+
+- Specification: [openlfcp/spec](https://github.com/openlfcp/spec)
+- Source and the other SDK packages: [openlfcp/sdk-ts](https://github.com/openlfcp/sdk-ts)
+- Issues: [openlfcp/sdk-ts/issues](https://github.com/openlfcp/sdk-ts/issues)
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).

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,54 @@
 {
   "name": "@openlfcp/crypto",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-rc.1",
+  "description": "The cryptography of LFCP (SHA-256, Ed25519, X25519, HKDF, ChaCha20-Poly1305, HPKE) on audited primitives (@noble, hpke).",
+  "keywords": [
+    "openlfcp",
+    "lfcp",
+    "local-first",
+    "end-to-end-encryption",
+    "ed25519",
+    "x25519",
+    "hpke",
+    "chacha20-poly1305",
+    "cryptography"
+  ],
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/openlfcp/sdk-ts/tree/main/packages/crypto#readme",
+  "bugs": {
+    "url": "https://github.com/openlfcp/sdk-ts/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/openlfcp/sdk-ts.git",
+    "directory": "packages/crypto"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=24"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "!dist/**/*.tsbuildinfo"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  },
+  "dependencies": {
+    "@noble/ciphers": "^2.4.0",
+    "@noble/curves": "^2.4.0",
+    "@noble/hashes": "^2.4.0",
+    "@panva/hpke-noble": "^1.1.7",
+    "hpke": "^1.1.7",
+    "@openlfcp/core": "^0.1.0-rc.1"
+  }
 }