@openlfcp/core 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

@@ -0,0 +1,27 @@
+# @openlfcp/core
+
+Identifiers, shared protocol types, errors and byte helpers used by every other `@openlfcp/*` package: Resource, Principal, Control Record and Data Unit IDs, uint64 sequences and epochs, `LfcpError` with the LFCP wire codes, hex and base64url helpers.
+
+```sh
+npm install @openlfcp/core@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/bytes.d.ts

@@ -0,0 +1,18 @@
+/** Lowercase hexadecimal, two digits per byte. */
+export declare function toHex(bytes: Uint8Array): string;
+/**
+ * Parses lowercase, even-length hexadecimal. Upper case, a `0x` prefix and
+ * odd lengths are rejected with `INVALID_HEX`.
+ */
+export declare function fromHex(hex: string): Uint8Array;
+/** Unpadded base64url (RFC 4648 §5), the encoding LFCP uses in URIs and references. */
+export declare function toBase64url(bytes: Uint8Array): string;
+/**
+ * Parses canonical unpadded base64url. Rejects padding, characters outside
+ * the URL-safe alphabet, a length of 1 modulo 4 and non-zero trailing bits,
+ * so every byte string has exactly one accepted encoding.
+ */
+export declare function fromBase64url(text: string): Uint8Array;
+/** Byte-for-byte equality. Not constant-time: do not use it to compare secrets. */
+export declare function bytesEqual(a: Uint8Array, b: Uint8Array): boolean;
+//# sourceMappingURL=bytes.d.ts.map

package/dist/bytes.js

@@ -0,0 +1,99 @@
+import { LfcpError } from "./errors.js";
+const HEX = "0123456789abcdef";
+const B64URL = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+const B64URL_VALUE = new Map([...B64URL].map((c, i) => [c, i]));
+/** Lowercase hexadecimal, two digits per byte. */
+export function toHex(bytes) {
+    let out = "";
+    for (const b of bytes)
+        out += HEX.charAt(b >> 4) + HEX.charAt(b & 0x0f);
+    return out;
+}
+/**
+ * Parses lowercase, even-length hexadecimal. Upper case, a `0x` prefix and
+ * odd lengths are rejected with `INVALID_HEX`.
+ */
+export function fromHex(hex) {
+    if (!/^(?:[0-9a-f]{2})*$/.test(hex)) {
+        throw new LfcpError("INVALID_HEX", "expected lowercase hexadecimal with an even number of digits");
+    }
+    const out = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < out.length; i += 1)
+        out[i] = Number.parseInt(hex.slice(2 * i, 2 * i + 2), 16);
+    return out;
+}
+/** Unpadded base64url (RFC 4648 §5), the encoding LFCP uses in URIs and references. */
+export function toBase64url(bytes) {
+    let out = "";
+    let i = 0;
+    for (; i + 3 <= bytes.length; i += 3) {
+        const n = (bytes[i] << 16) | (bytes[i + 1] << 8) | bytes[i + 2];
+        out +=
+            B64URL.charAt(n >> 18) +
+                B64URL.charAt((n >> 12) & 63) +
+                B64URL.charAt((n >> 6) & 63) +
+                B64URL.charAt(n & 63);
+    }
+    const rest = bytes.length - i;
+    if (rest === 1) {
+        const n = bytes[i] << 16;
+        out += B64URL.charAt(n >> 18) + B64URL.charAt((n >> 12) & 63);
+    }
+    else if (rest === 2) {
+        const n = (bytes[i] << 16) | (bytes[i + 1] << 8);
+        out += B64URL.charAt(n >> 18) + B64URL.charAt((n >> 12) & 63) + B64URL.charAt((n >> 6) & 63);
+    }
+    return out;
+}
+/**
+ * Parses canonical unpadded base64url. Rejects padding, characters outside
+ * the URL-safe alphabet, a length of 1 modulo 4 and non-zero trailing bits,
+ * so every byte string has exactly one accepted encoding.
+ */
+export function fromBase64url(text) {
+    const fail = (why) => {
+        throw new LfcpError("INVALID_BASE64URL", `not canonical unpadded base64url: ${why}`);
+    };
+    const rem = text.length % 4;
+    if (rem === 1)
+        fail("length is 1 modulo 4");
+    const values = [];
+    // The input may be a secret (a stored key, an invitation fragment): an
+    // error names the position of a bad character, never the character.
+    let i = 0;
+    for (const c of text) {
+        const v = B64URL_VALUE.get(c);
+        if (v === undefined)
+            fail(c === "=" ? "padding is not allowed" : `a character outside the alphabet at ${i}`);
+        values.push(v);
+        i += 1;
+    }
+    // The last character of a 2- or 3-character group carries 4 or 2 bits that
+    // are not part of any byte; they must be zero (RFC 4648 §3.5).
+    const last = values[values.length - 1] ?? 0;
+    if ((rem === 2 && (last & 0x0f) !== 0) || (rem === 3 && (last & 0x03) !== 0))
+        fail("non-zero trailing bits");
+    const out = new Uint8Array((values.length * 6) >> 3);
+    let acc = 0;
+    let bits = 0;
+    let o = 0;
+    for (const v of values) {
+        acc = ((acc << 6) | v) & 0xffff;
+        bits += 6;
+        if (bits >= 8) {
+            bits -= 8;
+            out[o++] = (acc >> bits) & 0xff;
+        }
+    }
+    return out;
+}
+/** Byte-for-byte equality. Not constant-time: do not use it to compare secrets. */
+export function bytesEqual(a, b) {
+    if (a.length !== b.length)
+        return false;
+    for (let i = 0; i < a.length; i += 1)
+        if (a[i] !== b[i])
+            return false;
+    return true;
+}
+//# sourceMappingURL=bytes.js.map

package/dist/errors.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Validation codes raised by the SDK while checking local input.
+ *
+ * These are SDK-internal codes, not the LFCP-WIRE-01 §62 wire error codes
+ * that are sent in NACK and ERROR messages. At the wire boundary, every
+ * `CBOR_*` failure of a received persistent object surfaces as
+ * `MALFORMED_MESSAGE` (LFCP-WIRE-01 §5.2).
+ */
+export type LfcpErrorCode = "INVALID_LENGTH" | "INVALID_HEX" | "INVALID_BASE64URL" | "INVALID_UUIDV7" | "NO_SECURE_RANDOM"
+/** Valid CBOR, but not the deterministic encoding (non-shortest head, unsorted map keys). */
+ | "CBOR_NON_CANONICAL"
+/** A map contains the same key twice. */
+ | "CBOR_DUPLICATE_KEY"
+/** An indefinite-length item or a break code. */
+ | "CBOR_INDEFINITE_LENGTH"
+/** A type LFCP does not use: tags, floats, undefined, other simple values, reserved encodings, unsupported JS values. */
+ | "CBOR_UNSUPPORTED_TYPE"
+/** An integer outside the CBOR range -2^64 .. 2^64-1, or an unsafe JS number. */
+ | "CBOR_OUT_OF_RANGE"
+/** The input ends inside an item. */
+ | "CBOR_TRUNCATED"
+/** Bytes remain after the single top-level item. */
+ | "CBOR_TRAILING_BYTES"
+/** A text string that is not well-formed UTF-8 (or a JS string with lone surrogates). */
+ | "CBOR_INVALID_UTF8"
+/** Nesting deeper than the SDK's safety limit. */
+ | "CBOR_TOO_DEEP"
+/** A cryptographic operation failed (e.g. a low-order X25519 public key). Never carries key bytes. */
+ | "CRYPTO_FAILURE"
+/** A Principal Descriptor has the wrong shape, field set, key lengths or encoding (LFCP-WIRE-01 §7). */
+ | "INVALID_PRINCIPAL_DESCRIPTOR"
+/** A Principal Descriptor's ID is not the §7 hash of its public keys. */
+ | "PRINCIPAL_ID_MISMATCH"
+/**
+ * A signed object is not the canonical LFCP COSE_Sign1 shape (LFCP-WIRE-01 §10):
+ * tagged, wrong arity, extra or missing protected parameters, non-empty
+ * unprotected header, detached payload or a non-64-byte signature. Surfaces
+ * on the wire as MALFORMED_MESSAGE.
+ */
+ | "COSE_MALFORMED"
+/** The signing key does not belong to the Principal Descriptor it is used with. */
+ | "COSE_SIGNER_MISMATCH"
+/**
+ * Deterministic CBOR that does not have the structure a Wire rule requires:
+ * wrong field set, field type or byte-string length, or a broken structural
+ * rule (actor sequence 0 §8, a non-canonical actor-have or frontier §28.1,
+ * §28.2, Genesis not at control_seq 0 with a null link §13.1). Surfaces on
+ * the wire as MALFORMED_MESSAGE.
+ */
+ | "INVALID_STRUCTURE"
+/**
+ * A well-formed value that LFCP reserves but this version does not define:
+ * a core Control Record type 9–31. §14: "Unknown core Control Record types
+ * MUST cause validation failure, with INVALID_CONTROL_CHAIN."
+ */
+ | "UNSUPPORTED_VALUE"
+/**
+ * An integer outside the range a construction requires: a Data Epoch or
+ * uint64 value outside 0..2^64-1, an actor sequence outside 1..2^64-1, or
+ * a number that is not a safe integer. Values are never truncated.
+ * SDK-local; decoded wire values are range-checked by the decoders.
+ */
+ | "OUT_OF_RANGE"
+/**
+ * A local attempt to use an actor sequence twice for one (Resource,
+ * Principal) (LFCP-WIRE-01 §8, §12: nonce reuse). SDK-local; never sent.
+ */
+ | "SEQUENCE_REUSE"
+/**
+ * A local transaction that would produce a Shared Objects change over the
+ * change expansion limits (SHARED-OBJECTS-PROFILE-01 §11.1). Nothing was
+ * written; the application splits the transaction (§12). SDK-local.
+ */
+ | "CHANGE_TOO_LARGE"
+/**
+ * A Control Chain that is not one valid linear chain (LFCP-WIRE-01 §13,
+ * §13.1): no Genesis, a sequence that is not previous + 1, a link that is
+ * not the previous record ID, a different Resource, or a record that
+ * links to nothing. INVALID_CONTROL_CHAIN on the wire (§13.1).
+ */
+ | "INVALID_CONTROL_CHAIN"
+/**
+ * A record whose issuer cannot be resolved to a Principal Descriptor, or
+ * an object that references a Control Head the receiver does not have.
+ * MISSING_DEPENDENCY on the wire (§13.1); the receiver may fetch and retry.
+ */
+ | "MISSING_DEPENDENCY"
+/**
+ * Something this implementation does not support by scope: a Control
+ * Chain containing a Coordinator Recovery (7) or Resource Tombstone (8)
+ * record (MVP-0.1-PROTOCOL-SCOPE §4, DV1). PROTOCOL_UNSUPPORTED on the wire.
+ */
+ | "PROTOCOL_UNSUPPORTED"
+/** A signed object whose kid or signature is wrong for its expected signer (G1/N2). INVALID_SIGNATURE on the wire. */
+ | "INVALID_SIGNATURE"
+/** A record the authorization policy (LFCP-021) refuses. AUTHORIZATION_FAILED on the wire. */
+ | "AUTHORIZATION_FAILED"
+/**
+ * Shared Objects state that violates SHARED-OBJECTS-PROFILE-01 (§74.1):
+ * reported with one §74.1 diagnostic per failure. A profile-level code,
+ * never an LFCP Wire error code.
+ */
+ | "PROFILE_INVALID"
+/**
+ * A Resource whose Data Profile this client does not implement (§27):
+ * its plaintext is never applied. PROFILE_UNSUPPORTED on the wire (§62).
+ */
+ | "PROFILE_UNSUPPORTED"
+/**
+ * Two concurrent Shared Objects under one Object ID (SHARED-OBJECTS-
+ * PROFILE-01 §21). A profile error of its own, not PROFILE_INVALID.
+ */
+ | "OBJECT_ID_COLLISION"
+/**
+ * A received second, different change or unit for one (resource, actor,
+ * sequence) (§26.2). ACTOR_EQUIVOCATION on the wire (§62). A local attempt
+ * to reuse a sequence is SEQUENCE_REUSE instead.
+ */
+ | "ACTOR_EQUIVOCATION"
+/**
+ * The keys given to open a Key Package are not those of the Principal it
+ * names (§25: recipient binding). Client-local, no wire code (ADR 0001 N5).
+ */
+ | "KEY_PACKAGE_RECIPIENT_MISMATCH"
+/** An LFCP message above the size limit in force (§31). MESSAGE_TOO_LARGE on the wire. */
+ | "MESSAGE_TOO_LARGE"
+/** A Data Profile codec used with a Resource of another data_profile (§15, §27). SDK-local misuse. */
+ | "DATA_PROFILE_MISMATCH"
+/**
+ * A Data Unit that fails ChaCha20-Poly1305 authentication (§26.3). Only a
+ * client holding the DEK detects it; client-local, no wire code (ADR 0001 N3).
+ */
+ | "AEAD_AUTHENTICATION_FAILED"
+/** A Key Package does not open (HPKE failure). Client-local, no wire code (N5). */
+ | "KEY_PACKAGE_OPEN_FAILED"
+/**
+ * An opened DEK does not match the epoch's DEK commitment, or the
+ * plaintext is not 32 bytes (§25.2). Client-local, no wire code (N5).
+ */
+ | "DEK_COMMITMENT_MISMATCH"
+/**
+ * An invitation URI or invitation secret that is not the §18.2 form, or
+ * a secret whose recomputed Invitation Principal is not the subject of
+ * the referenced invitation grant. Client-local, never sent.
+ */
+ | "INVALID_INVITATION";
+/** Error with a stable machine-readable `code`; the message is for humans only. */
+export declare class LfcpError extends Error {
+    readonly code: LfcpErrorCode;
+    constructor(code: LfcpErrorCode, message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.js

@@ -0,0 +1,10 @@
+/** Error with a stable machine-readable `code`; the message is for humans only. */
+export class LfcpError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "LfcpError";
+        this.code = code;
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/ids.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 32-byte LFCP identifiers, as raw bytes.
+ *
+ * Each kind is a distinct branded Uint8Array, so one kind cannot be passed
+ * where another is expected. The constructors check the length and copy the
+ * input, so later writes to the caller's buffer cannot change a validated
+ * identifier. The returned array is still a Uint8Array: treat it as
+ * read-only.
+ */
+declare const brand: unique symbol;
+type Id32<Kind extends string> = Uint8Array & {
+    readonly [brand]: Kind;
+};
+/** LFCP-WIRE-01 §6: 32 random bytes. */
+export type ResourceId = Id32<"ResourceId">;
+/** LFCP-WIRE-01 §7: SHA-256 over the Principal's public keys (derivation is LFCP-014). */
+export type PrincipalId = Id32<"PrincipalId">;
+/** LFCP-WIRE-01 §5.3: a SHA-256 value encoded as 32 bytes. */
+export type Hash32 = Id32<"Hash32">;
+/** LFCP-WIRE-01 §13, §10.6: SHA-256 of a Control Record's exact COSE_Sign1 bytes. */
+export type ControlRecordId = Id32<"ControlRecordId">;
+/** LFCP-WIRE-01 §26, §10.6: SHA-256 of a Data Unit's exact COSE_Sign1 bytes. */
+export type DataUnitId = Id32<"DataUnitId">;
+export declare const ID32_LENGTH = 32;
+export declare const resourceId: (bytes: Uint8Array) => ResourceId;
+/**
+ * A new Resource ID: 32 bytes from the platform CSPRNG (LFCP-WIRE-01 §6).
+ * It never encodes a hostname, owner, account, path or time, and nothing
+ * derives it from Genesis content.
+ */
+export declare const generateResourceId: () => ResourceId;
+export declare const principalId: (bytes: Uint8Array) => PrincipalId;
+export declare const hash32: (bytes: Uint8Array) => Hash32;
+export declare const controlRecordId: (bytes: Uint8Array) => ControlRecordId;
+export declare const dataUnitId: (bytes: Uint8Array) => DataUnitId;
+/** Equality of two identifiers of the same kind. */
+export declare function idEquals<T extends Id32<string>>(a: T, b: T): boolean;
+/**
+ * Orders Principal IDs by their raw bytes, compared as unsigned bytes, as
+ * LFCP-WIRE-01 §28.2 requires for canonical frontier entries. This is byte
+ * order only; it carries no meaning of time, causality or precedence.
+ * Returns a negative number, zero or a positive number like Array.sort expects.
+ */
+export declare function compareCanonicalFrontierOrder(a: PrincipalId, b: PrincipalId): number;
+export {};
+//# sourceMappingURL=ids.d.ts.map

package/dist/ids.js

@@ -0,0 +1,41 @@
+import { bytesEqual } from "./bytes.js";
+import { LfcpError } from "./errors.js";
+import { secureRandom } from "./random.js";
+export const ID32_LENGTH = 32;
+function id32(kind, bytes) {
+    if (!(bytes instanceof Uint8Array) || bytes.length !== ID32_LENGTH) {
+        const got = bytes instanceof Uint8Array ? `${bytes.length} bytes` : typeof bytes;
+        throw new LfcpError("INVALID_LENGTH", `${kind} must be exactly ${ID32_LENGTH} bytes, got ${got}`);
+    }
+    return Uint8Array.from(bytes);
+}
+export const resourceId = (bytes) => id32("ResourceId", bytes);
+/**
+ * A new Resource ID: 32 bytes from the platform CSPRNG (LFCP-WIRE-01 §6).
+ * It never encodes a hostname, owner, account, path or time, and nothing
+ * derives it from Genesis content.
+ */
+export const generateResourceId = () => resourceId(secureRandom(ID32_LENGTH));
+export const principalId = (bytes) => id32("PrincipalId", bytes);
+export const hash32 = (bytes) => id32("Hash32", bytes);
+export const controlRecordId = (bytes) => id32("ControlRecordId", bytes);
+export const dataUnitId = (bytes) => id32("DataUnitId", bytes);
+/** Equality of two identifiers of the same kind. */
+export function idEquals(a, b) {
+    return bytesEqual(a, b);
+}
+/**
+ * Orders Principal IDs by their raw bytes, compared as unsigned bytes, as
+ * LFCP-WIRE-01 §28.2 requires for canonical frontier entries. This is byte
+ * order only; it carries no meaning of time, causality or precedence.
+ * Returns a negative number, zero or a positive number like Array.sort expects.
+ */
+export function compareCanonicalFrontierOrder(a, b) {
+    for (let i = 0; i < ID32_LENGTH; i += 1) {
+        const d = a[i] - b[i];
+        if (d !== 0)
+            return d;
+    }
+    return 0;
+}
+//# sourceMappingURL=ids.js.map

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+/** Name of this package. */
+export declare const PACKAGE = "@openlfcp/core";
+export { bytesEqual, fromBase64url, fromHex, toBase64url, toHex } from "./bytes.js";
+export { LfcpError, type LfcpErrorCode } from "./errors.js";
+export { type ControlRecordId, compareCanonicalFrontierOrder, controlRecordId, type DataUnitId, dataUnitId, generateResourceId, type Hash32, hash32, ID32_LENGTH, idEquals, type PrincipalId, principalId, type ResourceId, resourceId, } from "./ids.js";
+export { formatObjectId, type GenerateObjectIdOptions, generateObjectId, isObjectId, type ObjectId, parseObjectId, } from "./object-id.js";
+export { secureRandom } from "./random.js";
+export { type ActorSequence, actorSequence, type DataEpoch, dataEpoch, UINT64_MAX, uint64BE, } from "./uint64.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,9 @@
+/** Name of this package. */
+export const PACKAGE = "@openlfcp/core";
+export { bytesEqual, fromBase64url, fromHex, toBase64url, toHex } from "./bytes.js";
+export { LfcpError } from "./errors.js";
+export { compareCanonicalFrontierOrder, controlRecordId, dataUnitId, generateResourceId, hash32, ID32_LENGTH, idEquals, principalId, resourceId, } from "./ids.js";
+export { formatObjectId, generateObjectId, isObjectId, parseObjectId, } from "./object-id.js";
+export { secureRandom } from "./random.js";
+export { actorSequence, dataEpoch, UINT64_MAX, uint64BE, } from "./uint64.js";
+//# sourceMappingURL=index.js.map

package/dist/object-id.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Shared Object ID (SHARED-OBJECTS-PROFILE-01 §19): a UUIDv7 (RFC 9562) in its
+ * canonical lowercase hyphenated string form.
+ *
+ * Object IDs identify objects; they do not order them. The UUIDv7 timestamp
+ * and lexical order are NOT LFCP causality, conflict precedence or
+ * authorization order, so this module deliberately offers no comparison,
+ * sorting or timestamp extraction.
+ */
+declare const brand: unique symbol;
+export type ObjectId = string & {
+    readonly [brand]: "ObjectId";
+};
+/** True when `text` is a canonical UUIDv7 Object ID. */
+export declare function isObjectId(text: string): text is ObjectId;
+/** Returns `text` as an ObjectId, or throws `INVALID_UUIDV7`. Non-canonical forms (e.g. upper case) are rejected, not normalized. */
+export declare function parseObjectId(text: string): ObjectId;
+/** The canonical string form (Object IDs are stored canonically, so this is the value itself). */
+export declare function formatObjectId(id: ObjectId): string;
+export interface GenerateObjectIdOptions {
+    /** Unix time in milliseconds for the 48-bit timestamp; defaults to Date.now(). */
+    readonly now?: number;
+    /** Source of 10 random bytes; defaults to globalThis.crypto.getRandomValues. */
+    readonly random?: (length: number) => Uint8Array;
+}
+/**
+ * Generates a new UUIDv7 Object ID (RFC 9562 §5.7): 48-bit Unix millisecond
+ * timestamp, version 7, 12 random bits, variant 10, 62 random bits. No
+ * within-millisecond counter is kept.
+ */
+export declare function generateObjectId(options?: GenerateObjectIdOptions): ObjectId;
+export {};
+//# sourceMappingURL=object-id.d.ts.map

package/dist/object-id.js

@@ -0,0 +1,44 @@
+import { LfcpError } from "./errors.js";
+import { secureRandom } from "./random.js";
+// Lowercase, standard hyphen positions, version 7, variant bits 10.
+const UUIDV7 = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+/** True when `text` is a canonical UUIDv7 Object ID. */
+export function isObjectId(text) {
+    return UUIDV7.test(text);
+}
+/** Returns `text` as an ObjectId, or throws `INVALID_UUIDV7`. Non-canonical forms (e.g. upper case) are rejected, not normalized. */
+export function parseObjectId(text) {
+    if (!isObjectId(text))
+        throw new LfcpError("INVALID_UUIDV7", "not a canonical lowercase UUIDv7");
+    return text;
+}
+/** The canonical string form (Object IDs are stored canonically, so this is the value itself). */
+export function formatObjectId(id) {
+    return id;
+}
+/**
+ * Generates a new UUIDv7 Object ID (RFC 9562 §5.7): 48-bit Unix millisecond
+ * timestamp, version 7, 12 random bits, variant 10, 62 random bits. No
+ * within-millisecond counter is kept.
+ */
+export function generateObjectId(options = {}) {
+    const now = options.now ?? Date.now();
+    if (!Number.isSafeInteger(now) || now < 0 || now > 0xffff_ffff_ffff) {
+        throw new LfcpError("INVALID_UUIDV7", "timestamp must be an integer in [0, 2^48)");
+    }
+    const rnd = (options.random ?? secureRandom)(10);
+    if (rnd.length !== 10)
+        throw new LfcpError("INVALID_LENGTH", "random source must return 10 bytes");
+    const b = new Uint8Array(16);
+    let t = now;
+    for (let i = 5; i >= 0; i -= 1) {
+        b[i] = t % 256;
+        t = Math.floor(t / 256);
+    }
+    b.set(rnd, 6);
+    b[6] = 0x70 | (b[6] & 0x0f);
+    b[8] = 0x80 | (b[8] & 0x3f);
+    const hex = [...b].map((x) => x.toString(16).padStart(2, "0")).join("");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+//# sourceMappingURL=object-id.js.map

package/dist/random.d.ts

@@ -0,0 +1,3 @@
+/** `length` bytes from the platform CSPRNG (globalThis.crypto.getRandomValues), or NO_SECURE_RANDOM. */
+export declare function secureRandom(length: number): Uint8Array;
+//# sourceMappingURL=random.d.ts.map

package/dist/random.js

@@ -0,0 +1,10 @@
+import { LfcpError } from "./errors.js";
+/** `length` bytes from the platform CSPRNG (globalThis.crypto.getRandomValues), or NO_SECURE_RANDOM. */
+export function secureRandom(length) {
+    const c = globalThis.crypto;
+    if (typeof c?.getRandomValues !== "function") {
+        throw new LfcpError("NO_SECURE_RANDOM", "globalThis.crypto.getRandomValues is not available");
+    }
+    return c.getRandomValues(new Uint8Array(length));
+}
+//# sourceMappingURL=random.js.map

package/dist/uint64.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Unsigned 64-bit values of LFCP-WIRE-01 as branded bigints.
+ *
+ * Constructions such as `uint64_be(epoch)` (§11, §12) need the full uint64
+ * range, which a JavaScript number cannot hold exactly above 2^53. The
+ * constructors accept a bigint or a safe-integer number and reject anything
+ * out of range with OUT_OF_RANGE; a value is never truncated or wrapped.
+ */
+declare const brand: unique symbol;
+/** A Data Epoch (§11, §19): 0 <= epoch <= 2^64 - 1. */
+export type DataEpoch = bigint & {
+    readonly [brand]: "DataEpoch";
+};
+/** A per-(Resource, Principal) actor sequence (§8): 1 <= seq <= 2^64 - 1. */
+export type ActorSequence = bigint & {
+    readonly [brand]: "ActorSequence";
+};
+export declare const UINT64_MAX: bigint;
+export declare const dataEpoch: (value: bigint | number) => DataEpoch;
+export declare const actorSequence: (value: bigint | number) => ActorSequence;
+/** `uint64_be(value)`: 8 big-endian bytes; OUT_OF_RANGE outside 0..2^64-1. */
+export declare function uint64BE(value: bigint | number): Uint8Array;
+export {};
+//# sourceMappingURL=uint64.d.ts.map

package/dist/uint64.js

@@ -0,0 +1,27 @@
+import { LfcpError } from "./errors.js";
+export const UINT64_MAX = 2n ** 64n - 1n;
+function uint(what, value, min) {
+    let n;
+    if (typeof value === "bigint")
+        n = value;
+    else if (typeof value === "number" && Number.isSafeInteger(value))
+        n = BigInt(value);
+    else
+        throw new LfcpError("OUT_OF_RANGE", `${what} must be a bigint or a safe integer, got ${typeof value === "number" ? String(value) : typeof value}`);
+    if (n < min || n > UINT64_MAX)
+        throw new LfcpError("OUT_OF_RANGE", `${what} must be in ${min}..2^64-1, got ${n}`);
+    return n;
+}
+export const dataEpoch = (value) => uint("a Data Epoch", value, 0n);
+export const actorSequence = (value) => uint("an actor sequence", value, 1n);
+/** `uint64_be(value)`: 8 big-endian bytes; OUT_OF_RANGE outside 0..2^64-1. */
+export function uint64BE(value) {
+    let n = uint("a uint64 value", value, 0n);
+    const out = new Uint8Array(8);
+    for (let i = 7; i >= 0; i -= 1) {
+        out[i] = Number(n & 0xffn);
+        n >>= 8n;
+    }
+    return out;
+}
+//# sourceMappingURL=uint64.js.map

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@openlfcp/core",
+  "version": "0.1.0-rc.1",
+  "description": "Identifiers, shared protocol types, errors and byte helpers for LFCP.",
+  "keywords": [
+    "openlfcp",
+    "lfcp",
+    "local-first",
+    "end-to-end-encryption",
+    "identifiers",
+    "errors",
+    "bytes"
+  ],
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/openlfcp/sdk-ts/tree/main/packages/core#readme",
+  "bugs": {
+    "url": "https://github.com/openlfcp/sdk-ts/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/openlfcp/sdk-ts.git",
+    "directory": "packages/core"
+  },
+  "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"
+  }
+}