@symbiote-native/crypto 0.0.1

package/src/core/crypto.ts

@@ -0,0 +1,165 @@
+import { UnavailabilityError } from 'expo-modules-core';
+
+import { expoCrypto } from './native-module';
+import { CryptoDigestAlgorithm, CryptoEncoding } from './types';
+import type { ICryptoDigestOptions, IDigest, ITypedArray } from './types';
+
+const NATIVE_MODULE_NAME = 'expo-crypto';
+const MIN_BYTE_COUNT = 0;
+const MAX_BYTE_COUNT = 1024;
+
+export class CryptoError extends TypeError {
+  code = 'ERR_CRYPTO';
+
+  constructor(message: string) {
+    super(`expo-crypto: ${message}`);
+  }
+}
+
+function assertByteCount(value: number, methodName: string): void {
+  if (
+    typeof value !== 'number' ||
+    Number.isNaN(value) ||
+    Math.floor(value) < MIN_BYTE_COUNT ||
+    Math.floor(value) > MAX_BYTE_COUNT
+  ) {
+    throw new TypeError(
+      `expo-crypto: ${methodName}(${value}) expected a valid number from range ${MIN_BYTE_COUNT}...${MAX_BYTE_COUNT}`,
+    );
+  }
+}
+
+function assertAlgorithm(algorithm: CryptoDigestAlgorithm): void {
+  if (!Object.values(CryptoDigestAlgorithm).includes(algorithm)) {
+    throw new CryptoError(
+      `Invalid algorithm provided. Expected one of: CryptoDigestAlgorithm.${Object.keys(
+        CryptoDigestAlgorithm,
+      ).join(', CryptoDigestAlgorithm.')}`,
+    );
+  }
+}
+
+function assertData(data: string): void {
+  if (typeof data !== 'string') {
+    throw new CryptoError('Invalid data provided. Expected a string.');
+  }
+}
+
+function assertEncoding(encoding: CryptoEncoding): void {
+  if (!Object.values(CryptoEncoding).includes(encoding)) {
+    throw new CryptoError(
+      `Invalid encoding provided. Expected one of: CryptoEncoding.${Object.keys(
+        CryptoEncoding,
+      ).join(', CryptoEncoding.')}`,
+    );
+  }
+}
+
+/**
+ * Generates completely random bytes using native implementations. `byteCount` must be within
+ * `0`-`1024` (inclusive), anything else throws a `TypeError`.
+ */
+export function getRandomBytes(byteCount: number): Uint8Array {
+  assertByteCount(byteCount, 'getRandomBytes');
+  const validByteCount = Math.floor(byteCount);
+  if (!expoCrypto.getRandomValues) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'getRandomBytes');
+  }
+  const byteArray = new Uint8Array(validByteCount);
+  expoCrypto.getRandomValues(byteArray);
+  return byteArray;
+}
+
+/**
+ * Generates completely random bytes using native implementations. `byteCount` must be within
+ * `0`-`1024` (inclusive), anything else throws a `TypeError`.
+ */
+export async function getRandomBytesAsync(byteCount: number): Promise<Uint8Array> {
+  assertByteCount(byteCount, 'getRandomBytesAsync');
+  const validByteCount = Math.floor(byteCount);
+  if (!expoCrypto.getRandomValues) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'getRandomBytesAsync');
+  }
+  const byteArray = new Uint8Array(validByteCount);
+  expoCrypto.getRandomValues(byteArray);
+  return byteArray;
+}
+
+/**
+ * Fills the provided `TypedArray` with cryptographically secure random values in place, and
+ * returns it.
+ */
+export function getRandomValues<T extends ITypedArray>(typedArray: T): T {
+  if (!expoCrypto.getRandomValues) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'getRandomValues');
+  }
+  expoCrypto.getRandomValues(typedArray);
+  return typedArray;
+}
+
+/**
+ * Returns a unique identifier based on the V4 UUID spec (RFC4122), using cryptographically
+ * secure random values.
+ */
+export function randomUUID(): string {
+  if (!expoCrypto.randomUUID) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'randomUUID');
+  }
+  return expoCrypto.randomUUID();
+}
+
+/**
+ * Generates a digest of the supplied `data` string with the provided digest `algorithm`,
+ * formatted as one of `CryptoEncoding` (defaults to `HEX`).
+ */
+export async function digestStringAsync(
+  algorithm: CryptoDigestAlgorithm,
+  data: string,
+  options: ICryptoDigestOptions = { encoding: CryptoEncoding.HEX },
+): Promise<IDigest> {
+  if (!expoCrypto.digestStringAsync) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'digestStringAsync');
+  }
+
+  assertAlgorithm(algorithm);
+  assertData(data);
+  assertEncoding(options.encoding);
+
+  return expoCrypto.digestStringAsync(algorithm, data, options);
+}
+
+// Fixed output length (in bytes) per digest algorithm — used only as the sync fallback's
+// preallocated output buffer size when the native module has no digestAsync.
+const digestLengths: Record<CryptoDigestAlgorithm, number> = {
+  [CryptoDigestAlgorithm.SHA1]: 20,
+  [CryptoDigestAlgorithm.SHA256]: 32,
+  [CryptoDigestAlgorithm.SHA384]: 48,
+  [CryptoDigestAlgorithm.SHA512]: 64,
+  [CryptoDigestAlgorithm.MD2]: 16,
+  [CryptoDigestAlgorithm.MD4]: 16,
+  [CryptoDigestAlgorithm.MD5]: 16,
+};
+
+/**
+ * Generates a digest of the supplied `TypedArray`/`ArrayBuffer` of bytes with the provided digest
+ * `algorithm`. Prefers the native async `digestAsync` when present; otherwise falls back to
+ * allocating a fixed-size output buffer (sized via `digestLengths`) and the sync `digest`.
+ */
+export function digest(algorithm: CryptoDigestAlgorithm, data: BufferSource): Promise<ArrayBuffer> {
+  return new Promise((resolve, reject) => {
+    try {
+      if (typeof expoCrypto.digestAsync === 'function') {
+        resolve(expoCrypto.digestAsync(algorithm, data));
+        return;
+      }
+      if (!expoCrypto.digest) {
+        throw new UnavailabilityError(NATIVE_MODULE_NAME, 'digest');
+      }
+      const output = new Uint8Array(digestLengths[algorithm]);
+      expoCrypto.digest(algorithm, output, data);
+      resolve(output.buffer);
+    } catch (error) {
+      reject(error);
+    }
+  });
+}

package/src/core/index.ts

@@ -0,0 +1,18 @@
+export {
+  CryptoError,
+  getRandomBytes,
+  getRandomBytesAsync,
+  getRandomValues,
+  randomUUID,
+  digestStringAsync,
+  digest,
+} from './crypto';
+export {
+  CryptoDigestAlgorithm,
+  CryptoEncoding,
+  type ICryptoDigestOptions,
+  type IDigest,
+  type IUintBasedTypedArray,
+  type IIntBasedTypedArray,
+  type ITypedArray,
+} from './types';

package/src/core/native-module.ts

@@ -0,0 +1,26 @@
+import { requireNativeModule } from 'expo-modules-core';
+
+import type { CryptoDigestAlgorithm, ICryptoDigestOptions, IDigest, ITypedArray } from './types';
+
+const EXPO_CRYPTO_MODULE_NAME = 'ExpoCrypto';
+
+// getRandomValues/randomUUID/digest are unconditionally implemented on both iOS and Android
+// (verified against .vendors/expo's CryptoModule.swift/CryptoModule.kt at sdk-57 — both
+// register the same `Name("ExpoCrypto")` with those three, plus digestStringAsync). digestAsync
+// is the one method genuinely absent from the native side today — upstream's own `digest()`
+// feature-detects it (`typeof ExpoCrypto.digestAsync === 'function'`) and falls back to the sync
+// `digest` otherwise, so only it (and digestStringAsync, guarded the same way upstream guards it)
+// stay optional here.
+export type INativeCryptoModule = {
+  getRandomValues(typedArray: ITypedArray): void;
+  randomUUID(): string;
+  digest(algorithm: CryptoDigestAlgorithm, output: Uint8Array, data: BufferSource): void;
+  digestStringAsync?(
+    algorithm: CryptoDigestAlgorithm,
+    data: string,
+    options: ICryptoDigestOptions,
+  ): Promise<IDigest>;
+  digestAsync?(algorithm: CryptoDigestAlgorithm, data: BufferSource): Promise<ArrayBuffer>;
+};
+
+export const expoCrypto = requireNativeModule<INativeCryptoModule>(EXPO_CRYPTO_MODULE_NAME);

package/src/core/types.ts

@@ -0,0 +1,32 @@
+export enum CryptoDigestAlgorithm {
+  SHA1 = 'SHA-1',
+  SHA256 = 'SHA-256',
+  SHA384 = 'SHA-384',
+  SHA512 = 'SHA-512',
+  /** @platform ios */
+  MD2 = 'MD2',
+  /** @platform ios */
+  MD4 = 'MD4',
+  MD5 = 'MD5',
+}
+
+export enum CryptoEncoding {
+  HEX = 'hex',
+  /** Has trailing padding. Does not wrap lines. Does not have a trailing newline. */
+  BASE64 = 'base64',
+}
+
+export type ICryptoDigestOptions = {
+  /** Format the digest is returned in. */
+  encoding: CryptoEncoding;
+};
+
+export type IDigest = string;
+
+// expo-modules-core exports the equivalent constraint as `UintBasedTypedArray | IntBasedTypedArray`
+// off its own internal typed-array module; we never depend on the `expo` meta-package's re-export
+// path for it (see the symbiote-expo-native-module skill), so this is our own precise union over
+// the standard integer TypedArrays instead.
+export type IUintBasedTypedArray = Uint8Array | Uint16Array | Uint32Array;
+export type IIntBasedTypedArray = Int8Array | Int16Array | Int32Array;
+export type ITypedArray = IUintBasedTypedArray | IIntBasedTypedArray;

package/src/react/index.ts

@@ -0,0 +1,5 @@
+// @symbiote-native/crypto/react: the React entry over the framework-agnostic core.
+// Upstream ships free sync/async functions and two enums, no per-instance state and no event
+// stream — there is nothing for a hook to wrap, so this is a plain re-export, mirroring
+// packages/local-auth/src/react/index.ts.
+export * from '../core';

package/src/vue/index.ts

@@ -0,0 +1,4 @@
+// @symbiote-native/crypto/vue: the Vue entry over the framework-agnostic core. Same reasoning
+// as the React entry — no per-instance state or event stream to wire onto Vue's reactivity, so
+// this is a plain re-export.
+export * from '../core';