@reallyme/codec 0.1.22 → 0.2.0

package/NOTICE

@@ -0,0 +1,16 @@
+SPDX-FileCopyrightText: Copyright © 2026 ReallyMe LLC. All rights reserved
+
+SPDX-License-Identifier: Apache-2.0
+
+ReallyMe Codec
+Copyright © 2026 ReallyMe LLC. All rights reserved.
+
+This product includes software developed by ReallyMe LLC and distributed under
+the Apache License, Version 2.0.
+
+ReallyMe Codec wraps third-party codec, serialization, protobuf, WASM, JNI, and
+native binding libraries. Dependency license terms are recorded in the package
+manifests and enforced by the repository dependency policy.
+
+This NOTICE file is informational and does not modify the license terms in
+LICENSE or any third-party dependency license.

package/README.md

@@ -9,8 +9,8 @@ SPDX-License-Identifier: Apache-2.0
 `@reallyme/codec` is the TypeScript package for the Rust `reallyme-codec`
 surface. It exposes the same codec families through a WASM-backed facade:
 base64, unpadded base64url, lowercase hex, multibase, multicodec, multikey,
-DAG-CBOR/CID helpers, JCS, PEM armor, and the `reallyme.codec.v1` protobuf
-contract.
+deterministic generic CBOR, DAG-CBOR/CID helpers, JCS, PEM armor, and the
+`reallyme.codec.v1` protobuf contract.
 
 ```sh
 npm install @reallyme/codec
@@ -45,24 +45,61 @@ const decoded = ReallyMeCodec.base64urlDecode(encoded);
 |---|---|
 | Base encodings | `base64Encode`, `base64Decode`, `base64urlEncode`, `base64urlDecode`, `base64urlDecodeBytes`, `bytesToLowerHex`, `lowerHexToBytes` |
 | Multiformats | `base58btcEncode`, `base58btcDecode`, `multibase*`, `multicodec*`, `multikey*`, binding validation |
+| Deterministic CBOR | typed `deterministicCborEncode` and `deterministicCborDecode` for the bounded RFC 8949 profile |
 | DAG-CBOR and CID | `dagCborEncode`, `dagCborDecode`, `dagCborComputeCid`, `dagCborVerifyCid`, content hash and multihash helpers |
 | JCS | `canonicalizeJson`, `canonicalizeJsonText` |
 | PEM | wipeable `Uint8Array` armor through `encodePem`, `decodePem`, with strict label and size policy |
-| Protobuf | `processProto`, `processProtoJson`, and `@reallyme/codec/proto` generated types |
+| Protobuf | `processOperation`, `processOperationJson`, and `@reallyme/codec/proto` generated types |
+
+`processOperation` accepts binary generated `CodecOperationRequest` bytes.
+`processOperationJson` accepts UTF-8 bytes containing the generated ProtoJSON
+view of that same message. Both return binary `CodecOperationResponse` bytes;
+expected validation failures are represented by its typed error outcome and
+are not thrown as backend exceptions. Operation-specific public methods use
+that same fully discriminated response internally; the package does not keep
+operation-specific `*Proto` helper APIs or hand-written structured JSON result
+paths.
+
+The deterministic-CBOR API uses a closed recursive value model with exact
+`bigint` integers, `Uint8Array` byte strings, arrays, and entry-list maps with
+integer or text keys. It does not use JavaScript `number` for integers. Floats,
+tags, indefinite-length items, arbitrary simple values, and
+compound map keys are outside the supported profile. DAG-CBOR remains a
+separate, stricter profile and retains its existing APIs and behavior.
 
-`processProto` accepts binary generated `CodecOperationRequest` bytes.
-`processProtoJson` accepts UTF-8 bytes containing the generated ProtoJSON view
-of that same message. Both return binary `CodecProtoResultEnvelope` bytes;
-expected validation failures are represented in the envelope and are not
-thrown as backend exceptions.
-
-The operation-specific `*Proto` helpers remain ergonomic request builders. They
-encode generated messages and enter the same single WASM boundary rather than
-calling operation-specific WASM exports.
+```ts
+const value = ReallyMeDeterministicCbor.mapText([
+  ["b", ReallyMeDeterministicCbor.unsigned(2n)],
+  ["a", ReallyMeDeterministicCbor.bytes(new Uint8Array([0, 1, 2]))],
+]);
+const encoded = ReallyMeCodec.deterministicCborEncode(value);
+
+const dag = ReallyMeDagCbor.mapText([
+  ["payload", ReallyMeDagCbor.bytes(new Uint8Array([0, 1, 2]))],
+]);
+const dagBytes = ReallyMeCodec.dagCborEncode(dag);
+```
 
-Swift and Kotlin/Java expose the same generic `processProto` and
-`processProtoJson` methods through the Rust C/JNI boundary. The method names
-and envelope semantics are intentionally identical across SDKs.
+Encoding canonicalizes map ordering. Decoding rejects duplicate semantic keys,
+non-canonical input, unsupported CBOR types, and values beyond the documented
+resource limits. DAG-CBOR builders expose text-key maps and byte/integer
+helpers; deterministic CBOR additionally supports integer-key maps and the
+complete documented `u64`/`i64` integer ranges. `Uint8Array` is the canonical
+mutable-byte boundary for browser, Node, and WASM callers.
+
+Encoded CBOR and decoded byte-string values can contain the complete sensitive
+document. Returned buffers belong to the caller and should be cleared with
+`fill(0)` as soon as they are no longer needed. The package snapshots mutable
+inputs and clears its mutable request, response, and intermediate buffers on
+success and failure. JavaScript strings, garbage-collected object graphs, and
+runtime-internal protobuf storage cannot be deterministically erased; callers
+should therefore keep sensitive values short-lived and out of logs and
+telemetry.
+
+Swift and Kotlin/Java expose the same generic `processOperation` and
+`processOperationJson` methods through the Rust C/JNI boundary. The method
+names and generated response semantics are intentionally identical across
+SDKs.
 
 Errors are typed as `ReallyMeCodecError`; they do not include raw input bytes
 or backend exception text.

package/dist/boundary.d.ts

@@ -1,11 +1,17 @@
 export declare const MAX_CODEC_FFI_INPUT_BYTES = 1048576;
 export declare const MAX_CODEC_FFI_OUTPUT_BYTES = 67108864;
-export declare const MAX_CODEC_PROTO_MESSAGE_BYTES = 1048576;
-export declare const MAX_CODEC_PROTO_JSON_BYTES = 1572864;
+export declare const MAX_CODEC_PROTO_MESSAGE_BYTES: number;
+export declare const MAX_CODEC_PROTO_JSON_BYTES: number;
 export declare const MAX_CODEC_BOUNDARY_NODES = 1048576;
 export declare const requireBoundaryAggregate: (lengths: ReadonlyArray<number>, maximum?: number) => void;
 /** Returns UTF-8 length without allocating an encoded copy. */
 export declare const utf8ByteLength: (value: string) => number;
+/**
+ * Returns UTF-8 length while rejecting strings that cannot be represented as
+ * Unicode scalar values. TextEncoder and protobuf runtimes otherwise replace
+ * lone UTF-16 surrogates, silently changing deterministic-CBOR semantics.
+ */
+export declare const strictUtf8ByteLength: (value: string) => number;
 export declare const requireBoundaryUtf8String: (value: string, allowEmpty?: boolean, maximum?: number) => number;
 /** Validates, snapshots, and serializes untrusted JSON within a fixed budget. */
 export declare const stringifyBoundaryJson: (value: unknown) => string;

package/dist/boundary.js

@@ -4,8 +4,19 @@
 import { ReallyMeCodecError } from "./errors.js";
 export const MAX_CODEC_FFI_INPUT_BYTES = 1_048_576;
 export const MAX_CODEC_FFI_OUTPUT_BYTES = 67_108_864;
-export const MAX_CODEC_PROTO_MESSAGE_BYTES = 1_048_576;
-export const MAX_CODEC_PROTO_JSON_BYTES = 1_572_864;
+const MAX_CODEC_PROTO_SENSITIVE_PAYLOAD_BYTES = 2_097_152;
+const MAX_CODEC_PROTO_SEMANTIC_NODES = 65_536;
+const MAX_CODEC_PROTO_STRUCTURAL_BYTES_PER_NODE = 128;
+const MAX_CODEC_PROTO_FIXED_OPERATION_BYTES = 4_096;
+const MAX_CODEC_PROTO_JSON_TEXT_BYTES = 6_291_456;
+const MAX_CODEC_PROTO_JSON_BYTE_STRING_BYTES = 1_398_104;
+export const MAX_CODEC_PROTO_MESSAGE_BYTES = MAX_CODEC_PROTO_SENSITIVE_PAYLOAD_BYTES +
+    MAX_CODEC_PROTO_SEMANTIC_NODES * MAX_CODEC_PROTO_STRUCTURAL_BYTES_PER_NODE +
+    MAX_CODEC_PROTO_FIXED_OPERATION_BYTES;
+export const MAX_CODEC_PROTO_JSON_BYTES = MAX_CODEC_PROTO_JSON_TEXT_BYTES +
+    MAX_CODEC_PROTO_JSON_BYTE_STRING_BYTES +
+    MAX_CODEC_PROTO_SEMANTIC_NODES * MAX_CODEC_PROTO_STRUCTURAL_BYTES_PER_NODE +
+    MAX_CODEC_PROTO_FIXED_OPERATION_BYTES;
 // Every JSON node needs at least one serialized byte. Deriving this traversal
 // guard from the wire limit prevents hostile in-memory graphs from causing
 // unbounded work without rejecting a document the byte-bounded Rust lane accepts.
@@ -31,8 +42,7 @@ export const requireBoundaryAggregate = (lengths, maximum = MAX_CODEC_FFI_INPUT_
         aggregate += length;
     }
 };
-/** Returns UTF-8 length without allocating an encoded copy. */
-export const utf8ByteLength = (value) => {
+const utf8ByteLengthWithPolicy = (value, rejectUnpairedSurrogates) => {
     if (typeof value !== "string") {
         invalidInput();
     }
@@ -55,9 +65,18 @@ export const utf8ByteLength = (value) => {
                 index += 1;
             }
             else {
+                if (rejectUnpairedSurrogates) {
+                    invalidInput();
+                }
                 increment = 3;
             }
         }
+        else if (codeUnit >= 0xd800 && codeUnit <= 0xdfff) {
+            if (rejectUnpairedSurrogates) {
+                invalidInput();
+            }
+            increment = 3;
+        }
         else {
             increment = 3;
         }
@@ -68,6 +87,14 @@ export const utf8ByteLength = (value) => {
     }
     return length;
 };
+/** Returns UTF-8 length without allocating an encoded copy. */
+export const utf8ByteLength = (value) => utf8ByteLengthWithPolicy(value, false);
+/**
+ * Returns UTF-8 length while rejecting strings that cannot be represented as
+ * Unicode scalar values. TextEncoder and protobuf runtimes otherwise replace
+ * lone UTF-16 surrogates, silently changing deterministic-CBOR semantics.
+ */
+export const strictUtf8ByteLength = (value) => utf8ByteLengthWithPolicy(value, true);
 export const requireBoundaryUtf8String = (value, allowEmpty = true, maximum = MAX_CODEC_FFI_INPUT_BYTES) => {
     if (typeof value !== "string" || (!allowEmpty && value.length === 0)) {
         invalidInput();

package/dist/cbor.d.ts

@@ -1,4 +1,3 @@
-import type { ReallyMeCodecProtoResult } from "./readOutput.js";
 export type ReallyMeCborValue = Readonly<{
     type: "null";
 }> | Readonly<{
@@ -12,7 +11,7 @@ export type ReallyMeCborValue = Readonly<{
     value: string;
 }> | Readonly<{
     type: "bytes";
-    value: string;
+    value: Uint8Array;
 }> | Readonly<{
     type: "array";
     value: ReadonlyArray<ReallyMeCborValue>;
@@ -29,12 +28,76 @@ export type ReallyMeDagCborCidVerification = Readonly<{
     expectedCid: string;
     actualCid: string;
 }>;
+export type ReallyMeDeterministicCborInteger = Readonly<{
+    type: "unsigned";
+    value: bigint;
+}> | Readonly<{
+    type: "negative";
+    value: bigint;
+}>;
+export type ReallyMeDeterministicCborMapKey = Readonly<{
+    type: "integer";
+    value: ReallyMeDeterministicCborInteger;
+}> | Readonly<{
+    type: "text";
+    value: string;
+}>;
+export type ReallyMeDeterministicCborMapEntry = Readonly<{
+    key: ReallyMeDeterministicCborMapKey;
+    value: ReallyMeDeterministicCborValue;
+}>;
+export type ReallyMeDeterministicCborValue = Readonly<{
+    type: "null";
+}> | Readonly<{
+    type: "bool";
+    value: boolean;
+}> | Readonly<{
+    type: "integer";
+    value: ReallyMeDeterministicCborInteger;
+}> | Readonly<{
+    type: "text";
+    value: string;
+}> | Readonly<{
+    type: "bytes";
+    value: Uint8Array;
+}> | Readonly<{
+    type: "array";
+    value: ReadonlyArray<ReallyMeDeterministicCborValue>;
+}> | Readonly<{
+    type: "map";
+    value: ReadonlyArray<ReallyMeDeterministicCborMapEntry>;
+}>;
+export declare const ReallyMeDeterministicCbor: {
+    readonly null: () => ReallyMeDeterministicCborValue;
+    readonly bool: (value: boolean) => ReallyMeDeterministicCborValue;
+    readonly unsigned: (value: bigint) => ReallyMeDeterministicCborValue;
+    readonly negative: (value: bigint) => ReallyMeDeterministicCborValue;
+    readonly text: (value: string) => ReallyMeDeterministicCborValue;
+    readonly bytes: (value: Uint8Array) => ReallyMeDeterministicCborValue;
+    readonly array: (value: ReadonlyArray<ReallyMeDeterministicCborValue>) => ReallyMeDeterministicCborValue;
+    readonly mapInt: (entries: ReadonlyArray<readonly [bigint, ReallyMeDeterministicCborValue]>) => ReallyMeDeterministicCborValue;
+    readonly mapText: (entries: ReadonlyArray<readonly [string, ReallyMeDeterministicCborValue]>) => ReallyMeDeterministicCborValue;
+    readonly intKey: (value: bigint) => ReallyMeDeterministicCborMapKey;
+    readonly textKey: (value: string) => ReallyMeDeterministicCborMapKey;
+    readonly entry: (key: ReallyMeDeterministicCborMapKey, value: ReallyMeDeterministicCborValue) => ReallyMeDeterministicCborMapEntry;
+};
+export declare const ReallyMeDagCbor: {
+    readonly null: () => ReallyMeCborValue;
+    readonly bool: (value: boolean) => ReallyMeCborValue;
+    readonly int: (value: number | bigint) => ReallyMeCborValue;
+    readonly unsigned: (value: number | bigint) => ReallyMeCborValue;
+    readonly negative: (value: number | bigint) => ReallyMeCborValue;
+    readonly text: (value: string) => ReallyMeCborValue;
+    readonly bytes: (value: Uint8Array) => ReallyMeCborValue;
+    readonly array: (value: ReadonlyArray<ReallyMeCborValue>) => ReallyMeCborValue;
+    readonly mapText: (entries: ReadonlyArray<readonly [string, ReallyMeCborValue]>) => ReallyMeCborValue;
+};
 export declare const dagCborEncode: (value: ReallyMeCborValue) => Uint8Array;
 export declare const dagCborDecode: (bytes: Uint8Array) => ReallyMeCborValue;
+export declare const deterministicCborEncode: (value: unknown) => Uint8Array;
+export declare const deterministicCborDecode: (bytes: Uint8Array) => ReallyMeDeterministicCborValue;
 export declare const dagCborComputeCid: (bytes: Uint8Array) => string;
 export declare const dagCborVerifyCid: (cid: string, bytes: Uint8Array) => ReallyMeDagCborCidVerification;
-export declare const dagCborVerifyCidProto: (cid: string, bytes: Uint8Array) => Uint8Array;
-export declare const dagCborVerifyCidProtoResult: (cid: string, bytes: Uint8Array) => ReallyMeCodecProtoResult;
 export declare const dagCborSha256ContentHash: (bytes: Uint8Array) => Uint8Array;
 export declare const dagCborMultihash: (bytes: Uint8Array) => Uint8Array;
 export declare const isValidCidString: (cid: string) => boolean;