@atproto/lex-cbor 0.0.0

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@atproto/lex-cbor",
+  "version": "0.0.0",
+  "license": "MIT",
+  "description": "Lexicon encoding utilities for AT Lexicon data in CBOR format",
+  "keywords": [
+    "atproto",
+    "lex",
+    "data",
+    "cbor",
+    "encoding",
+    "utilities"
+  ],
+  "homepage": "https://atproto.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bluesky-social/atproto",
+    "directory": "packages/lex/lex-cbor"
+  },
+  "files": [
+    "./src",
+    "./dist"
+  ],
+  "sideEffects": false,
+  "main": "./dist/index.cjs.js",
+  "module": "./dist/index.es.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.es.js",
+      "require": "./dist/index.cjs.js"
+    }
+  },
+  "dependencies": {
+    "@atproto/lex-data": "workspace:*",
+    "multiformats": "^9.9.0",
+    "tslib": "^2.8.1"
+  },
+  "devDependencies": {
+    "@atproto/lex-json": "workspace:*",
+    "cborg": "^4.3.0",
+    "jest": "^28.1.2",
+    "vite": "^6.2.0"
+  },
+  "scripts": {
+    "dev": "vite build --watch",
+    "prebuild": "vite build --emptyOutDir",
+    "build": "tsc --build tsconfig.build.json",
+    "test": "jest"
+  }
+}

package/src/encoding.ts

@@ -0,0 +1,101 @@
+import {
+  DecodeOptions,
+  EncodeOptions,
+  TagDecoder,
+  Token,
+  Type,
+  decode as cborgDecode,
+  decodeFirst as cborgDecodeFirst,
+  encode as cborgEncode,
+} from 'cborg'
+import type { ByteView } from 'multiformats/block'
+import { CID, LexValue } from '@atproto/lex-data'
+
+// @NOTE This was inspired by @ipld/dag-cbor implementation, but adapted to
+// match the AT Data Model constraints. Floats, in particular, are not allowed.
+
+// @NOTE "cborg" version 4 is required to support multi-decoding via the
+// "decodeFirst" function. However, that version only exposes ES modules.
+// Because this package is using "commonjs", "cborg" will be bundled instead of
+// depending on it directly.
+
+const CID_CBOR_TAG = 42
+
+function cidEncoder(obj: object): Token[] | null {
+  const cid = CID.asCID(obj)
+  if (!cid) return null
+
+  const bytes = new Uint8Array(cid.bytes.byteLength + 1)
+  bytes.set(cid.bytes, 1) // prefix is 0x00, for historical reasons
+  return [new Token(Type.tag, CID_CBOR_TAG), new Token(Type.bytes, bytes)]
+}
+
+function undefinedEncoder(): null {
+  throw new Error('`undefined` is not allowed by the AT Data Model')
+}
+
+function numberEncoder(num: number): null {
+  if (Number.isInteger(num)) return null
+
+  throw new Error('Non-integer numbers are not allowed by the AT Data Model')
+}
+
+function mapEncoder(map: Map<unknown, unknown>): null {
+  for (const key of map.keys()) {
+    if (typeof key !== 'string') {
+      throw new Error(
+        'Only string keys are allowed in CBOR "map" by the AT Data Model',
+      )
+    }
+  }
+  // @NOTE Map will be encoded as CBOR "map", which will be decoded as object.
+  return null
+}
+
+const encodeOptions: EncodeOptions = {
+  typeEncoders: {
+    Map: mapEncoder,
+    Object: cidEncoder,
+    undefined: undefinedEncoder,
+    number: numberEncoder,
+  },
+}
+
+function cidDecoder(bytes: Uint8Array): CID {
+  if (bytes[0] !== 0) {
+    throw new Error('Invalid CID for CBOR tag 42; expected leading 0x00')
+  }
+  return CID.decode(bytes.subarray(1)) // ignore leading 0x00
+}
+
+const tagDecoders: TagDecoder[] = []
+tagDecoders[CID_CBOR_TAG] = cidDecoder
+const decodeOptions: DecodeOptions = {
+  allowIndefinite: false,
+  coerceUndefinedToNull: true,
+  allowNaN: false,
+  allowInfinity: false,
+  allowBigInt: true,
+  strict: true,
+  useMaps: false,
+  rejectDuplicateMapKeys: true,
+  tags: tagDecoders,
+}
+
+export function encode<T extends LexValue>(data: T): ByteView<T> {
+  return cborgEncode(data, encodeOptions)
+}
+
+export function decode<T extends LexValue>(bytes: ByteView<T>): T {
+  return cborgDecode(bytes, decodeOptions)
+}
+
+export function* decodeAll<T = LexValue>(
+  data: ByteView<T>,
+): Generator<T, void, unknown> {
+  do {
+    const [result, remainingBytes] = cborgDecodeFirst(data, decodeOptions)
+    yield result
+    data = remainingBytes
+  } while (data.byteLength > 0)
+}

package/src/index.ts

@@ -0,0 +1,73 @@
+import { create as createDigest } from 'multiformats/hashes/digest'
+import { sha256 as hasher } from 'multiformats/hashes/sha2'
+import {
+  CID,
+  DAG_CBOR_MULTICODEC,
+  LexValue,
+  RAW_BIN_MULTICODEC,
+  SHA2_256_MULTIHASH_CODE,
+} from '@atproto/lex-data'
+import { encode } from './encoding.js'
+
+export { CID, hasher }
+export { decode, decodeAll, encode } from './encoding.js'
+export type { LexValue }
+
+export async function cidForLex(value: LexValue): Promise<CID> {
+  return cidForCbor(encode(value))
+}
+
+export async function cidForCbor(bytes: Uint8Array): Promise<CID> {
+  const digest = await hasher.digest(bytes)
+  return CID.createV1(DAG_CBOR_MULTICODEC, digest)
+}
+
+export async function verifyCidForBytes(cid: CID, bytes: Uint8Array) {
+  const digest = await hasher.digest(bytes)
+  const expected = CID.createV1(cid.code, digest)
+  if (!cid.equals(expected)) {
+    throw new Error(
+      `Not a valid CID for bytes. Expected: ${expected.toString()} Got: ${cid.toString()}`,
+    )
+  }
+}
+
+export async function cidForRawBytes(bytes: Uint8Array): Promise<CID> {
+  const digest = await hasher.digest(bytes)
+  return CID.createV1(RAW_BIN_MULTICODEC, digest)
+}
+
+export function cidForRawHash(hash: Uint8Array): CID {
+  const digest = createDigest(hasher.code, hash)
+  return CID.createV1(RAW_BIN_MULTICODEC, digest)
+}
+
+/**
+ * @note Only supports DASL CIDs
+ * @see {@link https://dasl.ing/cid.html}
+ * @throws if the input do not represent a valid DASL {@link CID}
+ */
+export function parseCidFromBytes(cidBytes: Uint8Array): CID {
+  const version = cidBytes[0]
+  if (version !== 0x01) {
+    throw new Error(`Unsupported CID version: ${version}`)
+  }
+  const code = cidBytes[1]
+  if (code !== RAW_BIN_MULTICODEC && code !== DAG_CBOR_MULTICODEC) {
+    throw new Error(`Unsupported CID codec: ${code}`)
+  }
+  const hashType = cidBytes[2]
+  if (hashType !== SHA2_256_MULTIHASH_CODE) {
+    throw new Error(`Unsupported CID hash function: ${hashType}`)
+  }
+  const hashLength = cidBytes[3]
+  if (hashLength !== 32) {
+    throw new Error(`Unexpected CID hash length: ${hashLength}`)
+  }
+  if (hashLength !== cidBytes.length - 4) {
+    throw new Error(`Unexpected CID bytes length: ${hashLength}`)
+  }
+  const hashBytes = cidBytes.slice(4)
+  const digest = createDigest(hashType, hashBytes)
+  return CID.create(version, code, digest)
+}