@symbiote-native/crypto 3.0.2 → 3.0.3

package/README.md

@@ -1,12 +1,12 @@
 # @symbiote-native/crypto
 
 A wrapper package for [SymbioteNative](../../README.md) that makes
-[`expo-crypto`](https://github.com/expo/expo/tree/main/packages/expo-crypto) — cryptographically
-secure random bytes, `randomUUID`, and string/buffer digest hashing — usable from **every**
+[`expo-crypto`](https://github.com/expo/expo/tree/main/packages/expo-crypto) - cryptographically
+secure random bytes, `randomUUID`, and string/buffer digest hashing - usable from **every**
 adapter, React, Vue, Svelte, Solid, and Angular. Like `@symbiote-native/local-auth`, every
 function here is a plain sync/async call with no per-instance state or event stream, so there is
-no hook/composable/service to wrap — every adapter's entry point is a plain re-export of the same
-`core`. AES encryption (`expo-crypto`'s `aes/` subfolder) is out of scope for this pass.
+no hook/composable/service to wrap - every adapter's entry point is a plain re-export of the same
+`core`. AES-GCM encryption (`expo-crypto`'s `aes/` subfolder) is ported too.
 
 ## Install
 
@@ -22,39 +22,39 @@ npx @symbiote-native/cli new my-app --crypto
 npx @symbiote-native/cli add --crypto
 ```
 
-Either way: installs `@symbiote-native/crypto` and wires the native autolinking automatically — see
+Either way: installs `@symbiote-native/crypto` and wires the native autolinking automatically - see
 [`@symbiote-native/cli`](../cli).
 
 <details>
-<summary>Manual install (no CLI — installing and wiring native autolinking by hand)</summary>
+<summary>Manual install (no CLI - installing and wiring native autolinking by hand)</summary>
 
 ```bash
 npm install @symbiote-native/crypto
 ```
 
 `expo-crypto` and `expo-modules-core` come along as regular dependencies, pinned to exact
-versions — never install either yourself, and never add the `expo` meta-package to your project
+versions - never install either yourself, and never add the `expo` meta-package to your project
 (it bundles its own Metro/Babel pipeline, which conflicts with this project's own).
 
 ## Required one-time step: native autolinking wiring
 
 Unlike a plain RN native module, `expo-crypto`'s native code is discovered by
-`expo-modules-autolinking`, not RN's own `react-native.config.cjs` mechanism — this needs wiring
+`expo-modules-autolinking`, not RN's own `react-native.config.cjs` mechanism - this needs wiring
 into the native host app **once**, covering this package and every other `expo-modules-core`
 package with zero further changes:
 
 | Platform | Touches                                                                                                                                             |
 | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| iOS      | `ios/Podfile` — add `use_expo_modules!`                                                                                                             |
-| iOS      | `AppDelegate.swift` — Expo's runtime-bootstrap hook                                                                                                 |
-| Android  | `settings.gradle` / `app/build.gradle` — resolve and include the Expo Gradle projects                                                               |
-| Android  | `MainApplication.kt` — Expo's bootstrap hook, plus a hand-written native-module name map (there's no `expo` meta-package here to auto-generate one) |
+| iOS      | `ios/Podfile` - add `use_expo_modules!`                                                                                                             |
+| iOS      | `AppDelegate.swift` - Expo's runtime-bootstrap hook                                                                                                 |
+| Android  | `settings.gradle` / `app/build.gradle` - resolve and include the Expo Gradle projects                                                               |
+| Android  | `MainApplication.kt` - Expo's bootstrap hook, plus a hand-written native-module name map (there's no `expo` meta-package here to auto-generate one) |
 
 Full mechanics live in the `symbiote-expo-native-module` project skill. Reference
 implementation: `examples/expo-react/ios/Podfile` and
 `examples/expo-react/android/app/src/main/java/com/canaryexpo/MainApplication.kt`.
 
-No platform permission strings are needed for this package — random-byte generation and
+No platform permission strings are needed for this package - random-byte generation and
 digest hashing touch no protected device capability.
 
 </details>
@@ -67,11 +67,11 @@ src/core/     getRandomBytes / getRandomBytesAsync / getRandomValues / randomUUI
               option/result types, and the CryptoError validation-error class.
               native-module.ts resolves the native module via expo-modules-core's
               requireNativeModule.
-src/angular/  @symbiote-native/crypto/angular — export * from '../core'
+src/angular/  @symbiote-native/crypto/angular - export * from '../core'
 ```
 
-`./react`, `./vue`, `./svelte`, and `./solid` are `exports`-map aliases straight onto `src/core/`
-— no physical per-framework file, since there's nothing to subscribe to or clean up. `./angular`
+`./react`, `./vue`, `./svelte`, and `./solid` are `exports`-map aliases straight onto `src/core/`:
+no physical per-framework file, since there's nothing to subscribe to or clean up. `./angular`
 stays a physical file/subpath since Angular ships through a separate `ngc`/AOT build (`build-ngc/`).
 
 ## Use it
@@ -245,9 +245,9 @@ export class CryptoScreen {
 }
 ```
 
-There's no per-instance service to `inject()` in the Angular case — every function is a plain
+There's no per-instance service to `inject()` in the Angular case - every function is a plain
 free function off the core package, called straight from the component body (or the constructor,
-on Angular). All six examples mirror the real canary demo screens —
+on Angular). All six examples mirror the real canary demo screens:
 `examples/expo-react/screens/CryptoScreen.tsx`, `examples/expo-vue-sfc/screens/CryptoScreen.vue`,
 `examples/expo-vue-tsx/screens/CryptoScreen.tsx`, `examples/expo-svelte/screens/CryptoScreen.svelte`,
 `examples/expo-solid/screens/CryptoScreen.tsx`, `examples/expo-angular/src/screens/CryptoScreen.ts`.
@@ -271,13 +271,39 @@ digest(algorithm: CryptoDigestAlgorithm, data: BufferSource): Promise<ArrayBuffe
 
 Plus `CryptoDigestAlgorithm` (`SHA1`/`SHA256`/`SHA384`/`SHA512`/`MD2`\*/`MD4`\*/`MD5`, \*iOS
 only), `CryptoEncoding` (`HEX`/`BASE64`), `ICryptoDigestOptions`, `IDigest`, `ITypedArray` (and its
-`IUintBasedTypedArray`/`IIntBasedTypedArray` halves), and the `CryptoError` validation-error class
-— ported from upstream's `Crypto.types.ts`/`Crypto.ts`, renamed with this repo's `I`-prefix
+`IUintBasedTypedArray`/`IIntBasedTypedArray` halves), and the `CryptoError` validation-error class,
+ported from upstream's `Crypto.types.ts`/`Crypto.ts`, renamed with this repo's `I`-prefix
 convention for exported types (`ts-js-best-practices`).
 
+### AES-GCM
+
+Ported from upstream's `aes/` subfolder onto a second native module, `ExpoCryptoAES`:
+
+```ts
+import {
+  AESEncryptionKey,
+  AESKeySize,
+  AESSealedData,
+  aesDecryptAsync,
+  aesEncryptAsync,
+} from '@symbiote-native/crypto';
+
+const key = await AESEncryptionKey.generate(AESKeySize.AES256);
+const sealed = await aesEncryptAsync(plaintextBase64, key);
+const plain = await aesDecryptAsync(sealed, key, { output: 'base64' });
+```
+
+`AESEncryptionKey` and `AESSealedData` extend the native classes: `generate`/`import`/`bytes`/
+`encoded` on the key, `fromParts`/`fromCombined` plus `iv`/`tag`/`ciphertext`/`combined` on the
+sealed data. A string input is base64. `ArrayBuffer` inputs become a `Uint8Array`, and binary
+`nonce.bytes`/`additionalData` go to native as base64, as upstream does. `tagLength` is ignored on
+Apple (always 16), and `AES192` is unsupported on web. Option and input types carry the
+`I`-prefix: `IAesEncryptOptions`, `IAesDecryptOptions`, `IAesSealedDataConfig`, `IBinaryInput`,
+`IGcmNonceParam`, `IGcmTagByteLength`.
+
 ```ts
 import { digestStringAsync, randomUUID } from '@symbiote-native/crypto';
-// or the framework-scoped entry points — identical surface, re-exported verbatim:
+// or the framework-scoped entry points - identical surface, re-exported verbatim:
 import { randomUUID } from '@symbiote-native/crypto/react';
 import { randomUUID } from '@symbiote-native/crypto/vue';
 import { randomUUID } from '@symbiote-native/crypto/svelte';
@@ -288,21 +314,32 @@ import { randomUUID } from '@symbiote-native/crypto/angular';
 ## Notes
 
 - `getRandomBytes`/`getRandomBytesAsync` validate `byteCount` is a number in `0`-`1024`
-  (inclusive), throwing a plain `TypeError` otherwise, and floor a fractional count — matching
+  (inclusive), throwing a plain `TypeError` otherwise, and floor a fractional count - matching
   upstream exactly. This port skips upstream's `__DEV__`/remote-debugger `Math.random` fallback:
   that's a React Native debugging-tool concern, not applicable to this package's native-call
   path.
 - `digestStringAsync` validates `algorithm`/`data`/`options.encoding` and throws `CryptoError` (a
-  `TypeError` subclass, `code: 'ERR_CRYPTO'`) on an invalid value — mirroring upstream's own
+  `TypeError` subclass, `code: 'ERR_CRYPTO'`) on an invalid value - mirroring upstream's own
   `CryptoError`.
 - `digest` prefers a native `digestAsync` when present; otherwise it allocates a fixed-size
   output buffer (sized via the `digestLengths` lookup table) and calls the sync native `digest`.
 
+## Common questions
+
+- **`digestStringAsync` is `undefined`.** The native module did not load: rebuild after install.
+- **`randomUUID` returns a promise.** Reported after a native binary update; restart and rebuild.
+- **Which algorithms?** Prefer SHA-256 / SHA-512; SHA-1 is not recommended for security use.
+- **`undefined` under Jest.** The native module is absent in tests; inject a fake.
+
+Sources: [expo/expo#18215](https://github.com/expo/expo/issues/18215),
+[expo/expo#24021](https://github.com/expo/expo/issues/24021),
+[expo/expo#6512](https://github.com/expo/expo/issues/6512).
+
 ## Test it
 
-No Fabric/Descriptor angle at all — every function here is a pure sync/async-function surface,
+No Fabric/Descriptor angle at all - every function here is a pure sync/async-function surface,
 never a view or per-instance state. Tests inject a fake native-module object in place of the
-real `requireNativeModule` resolution (`src/core/crypto.test.ts`, `vitest`) — no
+real `requireNativeModule` resolution (`src/core/crypto.test.ts`, `src/core/aes/aes.test.ts`, `vitest`) - no
 `installFabric()`, no ViewConfig. Native rendering itself is verified on-device (see the parent
 [README](../../README.md) for the project's testing model).
 

package/build/core/aes/aes-native-module.d.ts

@@ -0,0 +1,55 @@
+import { NativeModule } from 'expo-modules-core';
+import type { IAesDecryptOptions, IAesEncryptOptions, IAesSealedDataConfig, IBinaryInput, IGcmTagByteLength, AESKeySize } from './aes-types';
+type IEncoding = 'hex' | 'base64';
+declare class EncryptionKey {
+    static generate(size?: AESKeySize): Promise<EncryptionKey>;
+    static import(bytes: Uint8Array): Promise<EncryptionKey>;
+    static import(hexString: string, encoding: IEncoding): Promise<EncryptionKey>;
+    /** Key size in bits */
+    size: AESKeySize;
+    bytes(): Promise<Uint8Array>;
+    encoded(encoding: IEncoding): Promise<string>;
+}
+declare class SealedData {
+    static fromCombined(combined: IBinaryInput, config?: IAesSealedDataConfig): SealedData;
+    static fromParts(iv: IBinaryInput, ciphertext: IBinaryInput, tag: IBinaryInput): SealedData;
+    static fromParts(iv: IBinaryInput, ciphertextWithTag: IBinaryInput, tagLength?: number): SealedData;
+    ciphertext(options: {
+        includeTag?: boolean;
+        encoding: 'base64';
+    }): Promise<string>;
+    ciphertext(options?: {
+        includeTag?: boolean;
+        encoding?: 'bytes';
+    }): Promise<Uint8Array>;
+    ciphertext(options: {
+        includeTag?: boolean;
+        encoding?: 'base64' | 'bytes';
+    }): Promise<string | Uint8Array>;
+    iv(encoding?: 'bytes'): Promise<Uint8Array>;
+    iv(encoding: 'base64'): Promise<string>;
+    iv(encoding?: 'bytes' | 'base64'): Promise<string | Uint8Array>;
+    tag(encoding?: 'bytes'): Promise<Uint8Array>;
+    tag(encoding: 'base64'): Promise<string>;
+    tag(encoding?: 'bytes' | 'base64'): Promise<string | Uint8Array>;
+    combined(encoding?: 'bytes'): Promise<Uint8Array>;
+    combined(encoding: 'base64'): Promise<string>;
+    combined(encoding?: 'bytes' | 'base64'): Promise<string | Uint8Array>;
+    /** IV + ciphertext + tag, in bytes */
+    readonly combinedSize: number;
+    readonly ivSize: number;
+    readonly tagSize: IGcmTagByteLength;
+}
+export type INativeAesEncryptOptions = Omit<IAesEncryptOptions, 'nonce'> & {
+    nonce?: number | IBinaryInput | undefined;
+};
+declare class NativeAesCryptoModule extends NativeModule {
+    EncryptionKey: typeof EncryptionKey;
+    SealedData: typeof SealedData;
+    generateKey(size?: AESKeySize): Promise<EncryptionKey>;
+    importKey(keyInput: string | Uint8Array, encoding?: IEncoding): Promise<EncryptionKey>;
+    encryptAsync(plaintext: IBinaryInput, key: EncryptionKey, options?: INativeAesEncryptOptions): Promise<SealedData>;
+    decryptAsync(sealedData: SealedData, key: EncryptionKey, options?: IAesDecryptOptions): Promise<string | Uint8Array>;
+}
+export declare const expoCryptoAes: NativeAesCryptoModule;
+export {};

package/build/core/aes/aes-native-module.js

@@ -0,0 +1,2 @@
+import { NativeModule, requireNativeModule } from 'expo-modules-core';
+export const expoCryptoAes = requireNativeModule('ExpoCryptoAES');

package/build/core/aes/aes-types.d.ts

@@ -0,0 +1,36 @@
+export type IBinaryInput = string | Uint8Array | ArrayBuffer;
+export declare enum AESKeySize {
+    AES128 = 128,
+    AES192 = 192,
+    AES256 = 256
+}
+export type IGcmTagByteLength = 16 | 15 | 14 | 13 | 12 | 8 | 4;
+export type IAesSealedDataConfig = {
+    /** @default 12 */
+    ivLength: number;
+    /** @default 16 */
+    tagLength: IGcmTagByteLength;
+};
+export type IAesDecryptOptions = {
+    /** @default 'bytes' */
+    output?: 'bytes' | 'base64';
+    additionalData?: IBinaryInput;
+};
+export type IBase64DecryptOptions = IAesDecryptOptions & {
+    output: 'base64';
+};
+export type IBytesDecryptOptions = IAesDecryptOptions & {
+    output?: 'bytes';
+};
+export type IGcmNonceParam = {
+    /** Byte length of the nonce to generate. @default 12 */
+    length: number;
+} | {
+    bytes: IBinaryInput;
+};
+export type IAesEncryptOptions = {
+    /** @default { length: 12 } */
+    nonce?: IGcmNonceParam;
+    tagLength?: IGcmTagByteLength;
+    additionalData?: IBinaryInput;
+};

package/build/core/aes/aes-types.js

@@ -0,0 +1,7 @@
+export var AESKeySize;
+(function (AESKeySize) {
+    AESKeySize[AESKeySize["AES128"] = 128] = "AES128";
+    // Unsupported on web
+    AESKeySize[AESKeySize["AES192"] = 192] = "AES192";
+    AESKeySize[AESKeySize["AES256"] = 256] = "AES256";
+})(AESKeySize || (AESKeySize = {}));

package/build/core/aes/aes.d.ts

@@ -0,0 +1,16 @@
+import { expoCryptoAes } from './aes-native-module';
+import type { IAesDecryptOptions, IAesEncryptOptions, IAesSealedDataConfig, IBase64DecryptOptions, IBinaryInput, IBytesDecryptOptions } from './aes-types';
+export declare class AESEncryptionKey extends expoCryptoAes.EncryptionKey {
+}
+export declare class AESSealedData extends expoCryptoAes.SealedData {
+    /** `tag` is a separate tag, or the tag length when the ciphertext already carries it */
+    static fromParts(iv: IBinaryInput, ciphertext: IBinaryInput, tag: IBinaryInput): AESSealedData;
+    static fromParts(iv: IBinaryInput, ciphertextWithTag: IBinaryInput, tagLength?: number): AESSealedData;
+    /** `combined` holds IV, ciphertext and tag back to back */
+    static fromCombined(combined: IBinaryInput, config?: IAesSealedDataConfig): AESSealedData;
+}
+/** AES-GCM encryption. A string plaintext must be base64-encoded */
+export declare function aesEncryptAsync(plaintext: IBinaryInput, key: AESEncryptionKey, options?: IAesEncryptOptions): Promise<AESSealedData>;
+export declare function aesDecryptAsync(sealedData: AESSealedData, key: AESEncryptionKey, options: IBase64DecryptOptions): Promise<string>;
+export declare function aesDecryptAsync(sealedData: AESSealedData, key: AESEncryptionKey, options?: IBytesDecryptOptions): Promise<Uint8Array>;
+export declare function aesDecryptAsync(sealedData: AESSealedData, key: AESEncryptionKey, options?: IAesDecryptOptions): Promise<string | Uint8Array>;

package/build/core/aes/aes.js

@@ -0,0 +1,59 @@
+import { expoCryptoAes, } from './aes-native-module.js';
+// Native has no ArrayBuffer support, and encodes binary options as base64 strings
+function convertBinaryInput(input, useBase64 = false) {
+    const bytes = input instanceof ArrayBuffer ? new Uint8Array(input) : input;
+    if (typeof bytes !== 'string' && useBase64) {
+        return uint8ArrayToBase64(bytes);
+    }
+    return bytes;
+}
+function uint8ArrayToBase64(bytes) {
+    let binaryString = '';
+    for (const byte of bytes) {
+        binaryString += String.fromCharCode(byte);
+    }
+    return btoa(binaryString);
+}
+export class AESEncryptionKey extends expoCryptoAes.EncryptionKey {
+}
+export class AESSealedData extends expoCryptoAes.SealedData {
+    static fromParts(iv, ciphertext, tag) {
+        const processedIv = convertBinaryInput(iv);
+        const processedCiphertext = convertBinaryInput(ciphertext);
+        if (tag === undefined || typeof tag === 'number') {
+            return expoCryptoAes.SealedData.fromParts(processedIv, processedCiphertext, tag);
+        }
+        return expoCryptoAes.SealedData.fromParts(processedIv, processedCiphertext, convertBinaryInput(tag));
+    }
+    /** `combined` holds IV, ciphertext and tag back to back */
+    static fromCombined(combined, config) {
+        return expoCryptoAes.SealedData.fromCombined(convertBinaryInput(combined), config);
+    }
+}
+/** AES-GCM encryption. A string plaintext must be base64-encoded */
+export function aesEncryptAsync(plaintext, key, options = {}) {
+    const { nonce, additionalData, ...rest } = options;
+    let nativeOptions = { ...rest };
+    if (nonce) {
+        nativeOptions = {
+            ...nativeOptions,
+            nonce: 'bytes' in nonce ? convertBinaryInput(nonce.bytes, true) : nonce.length,
+        };
+    }
+    if (additionalData) {
+        nativeOptions = {
+            ...nativeOptions,
+            additionalData: convertBinaryInput(additionalData, true),
+        };
+    }
+    return expoCryptoAes.encryptAsync(convertBinaryInput(plaintext), key, nativeOptions);
+}
+export function aesDecryptAsync(sealedData, key, options = {}) {
+    const { additionalData, ...rest } = options;
+    return expoCryptoAes.decryptAsync(sealedData, key, {
+        ...rest,
+        additionalData: additionalData
+            ? convertBinaryInput(additionalData, true)
+            : undefined,
+    });
+}

package/build/core/aes/index.d.ts

@@ -0,0 +1,2 @@
+export { AESEncryptionKey, AESSealedData, aesEncryptAsync, aesDecryptAsync, } from './aes';
+export { AESKeySize, type IAesDecryptOptions, type IAesEncryptOptions, type IAesSealedDataConfig, type IBase64DecryptOptions, type IBinaryInput, type IBytesDecryptOptions, type IGcmNonceParam, type IGcmTagByteLength, } from './aes-types';

package/build/core/aes/index.js

@@ -0,0 +1,2 @@
+export { AESEncryptionKey, AESSealedData, aesEncryptAsync, aesDecryptAsync, } from './aes.js';
+export { AESKeySize, } from './aes-types.js';

package/build/core/index.d.ts

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

package/build/core/index.js

@@ -1,2 +1,3 @@
 export { CryptoError, getRandomBytes, getRandomBytesAsync, getRandomValues, randomUUID, digestStringAsync, digest, } from './crypto.js';
+export * from './aes/index.js';
 export { CryptoDigestAlgorithm, CryptoEncoding, } from './types.js';

package/build-ngc/core/aes/aes-native-module.d.ts

@@ -0,0 +1,55 @@
+import { NativeModule } from 'expo-modules-core';
+import type { IAesDecryptOptions, IAesEncryptOptions, IAesSealedDataConfig, IBinaryInput, IGcmTagByteLength, AESKeySize } from './aes-types';
+type IEncoding = 'hex' | 'base64';
+declare class EncryptionKey {
+    static generate(size?: AESKeySize): Promise<EncryptionKey>;
+    static import(bytes: Uint8Array): Promise<EncryptionKey>;
+    static import(hexString: string, encoding: IEncoding): Promise<EncryptionKey>;
+    /** Key size in bits */
+    size: AESKeySize;
+    bytes(): Promise<Uint8Array>;
+    encoded(encoding: IEncoding): Promise<string>;
+}
+declare class SealedData {
+    static fromCombined(combined: IBinaryInput, config?: IAesSealedDataConfig): SealedData;
+    static fromParts(iv: IBinaryInput, ciphertext: IBinaryInput, tag: IBinaryInput): SealedData;
+    static fromParts(iv: IBinaryInput, ciphertextWithTag: IBinaryInput, tagLength?: number): SealedData;
+    ciphertext(options: {
+        includeTag?: boolean;
+        encoding: 'base64';
+    }): Promise<string>;
+    ciphertext(options?: {
+        includeTag?: boolean;
+        encoding?: 'bytes';
+    }): Promise<Uint8Array>;
+    ciphertext(options: {
+        includeTag?: boolean;
+        encoding?: 'base64' | 'bytes';
+    }): Promise<string | Uint8Array>;
+    iv(encoding?: 'bytes'): Promise<Uint8Array>;
+    iv(encoding: 'base64'): Promise<string>;
+    iv(encoding?: 'bytes' | 'base64'): Promise<string | Uint8Array>;
+    tag(encoding?: 'bytes'): Promise<Uint8Array>;
+    tag(encoding: 'base64'): Promise<string>;
+    tag(encoding?: 'bytes' | 'base64'): Promise<string | Uint8Array>;
+    combined(encoding?: 'bytes'): Promise<Uint8Array>;
+    combined(encoding: 'base64'): Promise<string>;
+    combined(encoding?: 'bytes' | 'base64'): Promise<string | Uint8Array>;
+    /** IV + ciphertext + tag, in bytes */
+    readonly combinedSize: number;
+    readonly ivSize: number;
+    readonly tagSize: IGcmTagByteLength;
+}
+export type INativeAesEncryptOptions = Omit<IAesEncryptOptions, 'nonce'> & {
+    nonce?: number | IBinaryInput | undefined;
+};
+declare class NativeAesCryptoModule extends NativeModule {
+    EncryptionKey: typeof EncryptionKey;
+    SealedData: typeof SealedData;
+    generateKey(size?: AESKeySize): Promise<EncryptionKey>;
+    importKey(keyInput: string | Uint8Array, encoding?: IEncoding): Promise<EncryptionKey>;
+    encryptAsync(plaintext: IBinaryInput, key: EncryptionKey, options?: INativeAesEncryptOptions): Promise<SealedData>;
+    decryptAsync(sealedData: SealedData, key: EncryptionKey, options?: IAesDecryptOptions): Promise<string | Uint8Array>;
+}
+export declare const expoCryptoAes: NativeAesCryptoModule;
+export {};

package/build-ngc/core/aes/aes-native-module.js

@@ -0,0 +1,3 @@
+import { NativeModule, requireNativeModule } from 'expo-modules-core';
+export const expoCryptoAes = requireNativeModule('ExpoCryptoAES');
+//# sourceMappingURL=aes-native-module.js.map

package/build-ngc/core/aes/aes-native-module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aes-native-module.js","sourceRoot":"","sources":["../../../src/core/aes/aes-native-module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAmGtE,MAAM,CAAC,MAAM,aAAa,GACxB,mBAAmB,CAAwB,eAAe,CAAC,CAAC"}

package/build-ngc/core/aes/aes-types.d.ts

@@ -0,0 +1,36 @@
+export type IBinaryInput = string | Uint8Array | ArrayBuffer;
+export declare enum AESKeySize {
+    AES128 = 128,
+    AES192 = 192,
+    AES256 = 256
+}
+export type IGcmTagByteLength = 16 | 15 | 14 | 13 | 12 | 8 | 4;
+export type IAesSealedDataConfig = {
+    /** @default 12 */
+    ivLength: number;
+    /** @default 16 */
+    tagLength: IGcmTagByteLength;
+};
+export type IAesDecryptOptions = {
+    /** @default 'bytes' */
+    output?: 'bytes' | 'base64';
+    additionalData?: IBinaryInput;
+};
+export type IBase64DecryptOptions = IAesDecryptOptions & {
+    output: 'base64';
+};
+export type IBytesDecryptOptions = IAesDecryptOptions & {
+    output?: 'bytes';
+};
+export type IGcmNonceParam = {
+    /** Byte length of the nonce to generate. @default 12 */
+    length: number;
+} | {
+    bytes: IBinaryInput;
+};
+export type IAesEncryptOptions = {
+    /** @default { length: 12 } */
+    nonce?: IGcmNonceParam;
+    tagLength?: IGcmTagByteLength;
+    additionalData?: IBinaryInput;
+};

package/build-ngc/core/aes/aes-types.js

@@ -0,0 +1,8 @@
+export var AESKeySize;
+(function (AESKeySize) {
+    AESKeySize[AESKeySize["AES128"] = 128] = "AES128";
+    // Unsupported on web
+    AESKeySize[AESKeySize["AES192"] = 192] = "AES192";
+    AESKeySize[AESKeySize["AES256"] = 256] = "AES256";
+})(AESKeySize || (AESKeySize = {}));
+//# sourceMappingURL=aes-types.js.map

package/build-ngc/core/aes/aes-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aes-types.js","sourceRoot":"","sources":["../../../src/core/aes/aes-types.ts"],"names":[],"mappings":"AAGA,MAAM,CAAN,IAAY,UAKX;AALD,WAAY,UAAU;IACpB,iDAAY,CAAA;IACZ,qBAAqB;IACrB,iDAAY,CAAA;IACZ,iDAAY,CAAA;AACd,CAAC,EALW,UAAU,KAAV,UAAU,QAKrB"}

package/build-ngc/core/aes/aes.d.ts

@@ -0,0 +1,16 @@
+import { expoCryptoAes } from './aes-native-module';
+import type { IAesDecryptOptions, IAesEncryptOptions, IAesSealedDataConfig, IBase64DecryptOptions, IBinaryInput, IBytesDecryptOptions } from './aes-types';
+export declare class AESEncryptionKey extends expoCryptoAes.EncryptionKey {
+}
+export declare class AESSealedData extends expoCryptoAes.SealedData {
+    /** `tag` is a separate tag, or the tag length when the ciphertext already carries it */
+    static fromParts(iv: IBinaryInput, ciphertext: IBinaryInput, tag: IBinaryInput): AESSealedData;
+    static fromParts(iv: IBinaryInput, ciphertextWithTag: IBinaryInput, tagLength?: number): AESSealedData;
+    /** `combined` holds IV, ciphertext and tag back to back */
+    static fromCombined(combined: IBinaryInput, config?: IAesSealedDataConfig): AESSealedData;
+}
+/** AES-GCM encryption. A string plaintext must be base64-encoded */
+export declare function aesEncryptAsync(plaintext: IBinaryInput, key: AESEncryptionKey, options?: IAesEncryptOptions): Promise<AESSealedData>;
+export declare function aesDecryptAsync(sealedData: AESSealedData, key: AESEncryptionKey, options: IBase64DecryptOptions): Promise<string>;
+export declare function aesDecryptAsync(sealedData: AESSealedData, key: AESEncryptionKey, options?: IBytesDecryptOptions): Promise<Uint8Array>;
+export declare function aesDecryptAsync(sealedData: AESSealedData, key: AESEncryptionKey, options?: IAesDecryptOptions): Promise<string | Uint8Array>;

package/build-ngc/core/aes/aes.js

@@ -0,0 +1,60 @@
+import { expoCryptoAes, } from './aes-native-module';
+// Native has no ArrayBuffer support, and encodes binary options as base64 strings
+function convertBinaryInput(input, useBase64 = false) {
+    const bytes = input instanceof ArrayBuffer ? new Uint8Array(input) : input;
+    if (typeof bytes !== 'string' && useBase64) {
+        return uint8ArrayToBase64(bytes);
+    }
+    return bytes;
+}
+function uint8ArrayToBase64(bytes) {
+    let binaryString = '';
+    for (const byte of bytes) {
+        binaryString += String.fromCharCode(byte);
+    }
+    return btoa(binaryString);
+}
+export class AESEncryptionKey extends expoCryptoAes.EncryptionKey {
+}
+export class AESSealedData extends expoCryptoAes.SealedData {
+    static fromParts(iv, ciphertext, tag) {
+        const processedIv = convertBinaryInput(iv);
+        const processedCiphertext = convertBinaryInput(ciphertext);
+        if (tag === undefined || typeof tag === 'number') {
+            return expoCryptoAes.SealedData.fromParts(processedIv, processedCiphertext, tag);
+        }
+        return expoCryptoAes.SealedData.fromParts(processedIv, processedCiphertext, convertBinaryInput(tag));
+    }
+    /** `combined` holds IV, ciphertext and tag back to back */
+    static fromCombined(combined, config) {
+        return expoCryptoAes.SealedData.fromCombined(convertBinaryInput(combined), config);
+    }
+}
+/** AES-GCM encryption. A string plaintext must be base64-encoded */
+export function aesEncryptAsync(plaintext, key, options = {}) {
+    const { nonce, additionalData, ...rest } = options;
+    let nativeOptions = { ...rest };
+    if (nonce) {
+        nativeOptions = {
+            ...nativeOptions,
+            nonce: 'bytes' in nonce ? convertBinaryInput(nonce.bytes, true) : nonce.length,
+        };
+    }
+    if (additionalData) {
+        nativeOptions = {
+            ...nativeOptions,
+            additionalData: convertBinaryInput(additionalData, true),
+        };
+    }
+    return expoCryptoAes.encryptAsync(convertBinaryInput(plaintext), key, nativeOptions);
+}
+export function aesDecryptAsync(sealedData, key, options = {}) {
+    const { additionalData, ...rest } = options;
+    return expoCryptoAes.decryptAsync(sealedData, key, {
+        ...rest,
+        additionalData: additionalData
+            ? convertBinaryInput(additionalData, true)
+            : undefined,
+    });
+}
+//# sourceMappingURL=aes.js.map

package/build-ngc/core/aes/aes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"aes.js","sourceRoot":"","sources":["../../../src/core/aes/aes.ts"],"names":[],"mappings":"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"}

package/build-ngc/core/aes/index.d.ts

@@ -0,0 +1,2 @@
+export { AESEncryptionKey, AESSealedData, aesEncryptAsync, aesDecryptAsync, } from './aes';
+export { AESKeySize, type IAesDecryptOptions, type IAesEncryptOptions, type IAesSealedDataConfig, type IBase64DecryptOptions, type IBinaryInput, type IBytesDecryptOptions, type IGcmNonceParam, type IGcmTagByteLength, } from './aes-types';

package/build-ngc/core/aes/index.js

@@ -0,0 +1,3 @@
+export { AESEncryptionKey, AESSealedData, aesEncryptAsync, aesDecryptAsync, } from './aes';
+export { AESKeySize, } from './aes-types';
+//# sourceMappingURL=index.js.map

package/build-ngc/core/aes/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/aes/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,eAAe,GAChB,MAAM,OAAO,CAAC;AACf,OAAO,EACL,UAAU,GASX,MAAM,aAAa,CAAC"}

package/build-ngc/core/index.d.ts

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

package/build-ngc/core/index.js

@@ -1,3 +1,4 @@
 export { CryptoError, getRandomBytes, getRandomBytesAsync, getRandomValues, randomUUID, digestStringAsync, digest, } from './crypto';
+export * from './aes';
 export { CryptoDigestAlgorithm, CryptoEncoding, } from './types';
 //# sourceMappingURL=index.js.map

package/build-ngc/core/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,cAAc,EACd,mBAAmB,EACnB,eAAe,EACf,UAAU,EACV,iBAAiB,EACjB,MAAM,GACP,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,qBAAqB,EACrB,cAAc,GAMf,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,cAAc,EACd,mBAAmB,EACnB,eAAe,EACf,UAAU,EACV,iBAAiB,EACjB,MAAM,GACP,MAAM,UAAU,CAAC;AAClB,cAAc,OAAO,CAAC;AACtB,OAAO,EACL,qBAAqB,EACrB,cAAc,GAMf,MAAM,SAAS,CAAC"}

package/native-link.json

@@ -6,6 +6,11 @@
         "importPath": "expo.modules.crypto.CryptoModule",
         "className": "CryptoModule",
         "nativeName": "ExpoCrypto"
+      },
+      {
+        "importPath": "expo.modules.crypto.aes.AesCryptoModule",
+        "className": "AesCryptoModule",
+        "nativeName": "ExpoCryptoAES"
       }
     ]
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@symbiote-native/crypto",
-  "version": "3.0.2",
+  "version": "3.0.3",
   "description": "expo-crypto wrapped for SymbioteNative — one framework-agnostic core, built once and reachable from the React, Vue, Svelte, Solid, and Angular adapters. Cryptographically secure random bytes, randomUUID, and string/buffer digest hashing (SHA-1/256/384/512, MD2/MD4/MD5).",
   "license": "MIT",
   "repository": {
@@ -70,7 +70,7 @@
   },
   "dependencies": {
     "expo-crypto": "57.0.1",
-    "expo-modules-core": "57.0.5"
+    "expo-modules-core": "57.0.20"
   },
   "peerDependencies": {
     "@angular/core": ">=20",
@@ -80,12 +80,12 @@
     "solid-js": ">=1.9.0",
     "svelte": ">=5.56.0",
     "vue": ">=3.5.0",
-    "@symbiote-native/angular": "^3.1.2",
-    "@symbiote-native/engine": "^1.3.1",
-    "@symbiote-native/react": "^3.0.4",
-    "@symbiote-native/solid": "^3.0.4",
-    "@symbiote-native/svelte": "^3.0.4",
-    "@symbiote-native/vue": "^3.0.4"
+    "@symbiote-native/angular": "^3.2.0",
+    "@symbiote-native/engine": "^1.5.0",
+    "@symbiote-native/react": "^3.2.0",
+    "@symbiote-native/solid": "^3.1.0",
+    "@symbiote-native/svelte": "^3.1.0",
+    "@symbiote-native/vue": "^3.2.0"
   },
   "peerDependenciesMeta": {
     "@symbiote-native/angular": {
@@ -133,13 +133,13 @@
     "solid-js": "^1.9.14",
     "svelte": "^5.56.0",
     "typescript": "~6.0.0",
-    "@symbiote-native/angular": "3.1.2",
-    "@symbiote-native/engine": "1.3.1",
-    "@symbiote-native/react": "3.0.4",
-    "@symbiote-native/solid": "3.0.4",
-    "@symbiote-native/svelte": "3.0.4",
-    "@symbiote-native/test-utils": "0.4.4",
-    "@symbiote-native/vue": "3.0.4"
+    "@symbiote-native/angular": "3.2.0",
+    "@symbiote-native/engine": "1.5.0",
+    "@symbiote-native/react": "3.2.0",
+    "@symbiote-native/solid": "3.1.0",
+    "@symbiote-native/svelte": "3.1.0",
+    "@symbiote-native/test-utils": "0.4.6",
+    "@symbiote-native/vue": "3.2.0"
   },
   "scripts": {
     "typecheck": "tsc --build",

package/src/core/aes/aes-native-module.ts

@@ -0,0 +1,101 @@
+import { NativeModule, requireNativeModule } from 'expo-modules-core';
+
+import type {
+  IAesDecryptOptions,
+  IAesEncryptOptions,
+  IAesSealedDataConfig,
+  IBinaryInput,
+  IGcmTagByteLength,
+  AESKeySize,
+} from './aes-types';
+
+type IEncoding = 'hex' | 'base64';
+
+declare class EncryptionKey {
+  static generate(size?: AESKeySize): Promise<EncryptionKey>;
+  static import(bytes: Uint8Array): Promise<EncryptionKey>;
+  static import(hexString: string, encoding: IEncoding): Promise<EncryptionKey>;
+
+  /** Key size in bits */
+  size: AESKeySize;
+
+  bytes(): Promise<Uint8Array>;
+  encoded(encoding: IEncoding): Promise<string>;
+}
+
+declare class SealedData {
+  static fromCombined(
+    combined: IBinaryInput,
+    config?: IAesSealedDataConfig,
+  ): SealedData;
+  static fromParts(
+    iv: IBinaryInput,
+    ciphertext: IBinaryInput,
+    tag: IBinaryInput,
+  ): SealedData;
+  static fromParts(
+    iv: IBinaryInput,
+    ciphertextWithTag: IBinaryInput,
+    tagLength?: number,
+  ): SealedData;
+
+  ciphertext(options: {
+    includeTag?: boolean;
+    encoding: 'base64';
+  }): Promise<string>;
+  ciphertext(options?: {
+    includeTag?: boolean;
+    encoding?: 'bytes';
+  }): Promise<Uint8Array>;
+  ciphertext(options: {
+    includeTag?: boolean;
+    encoding?: 'base64' | 'bytes';
+  }): Promise<string | Uint8Array>;
+
+  iv(encoding?: 'bytes'): Promise<Uint8Array>;
+  iv(encoding: 'base64'): Promise<string>;
+  iv(encoding?: 'bytes' | 'base64'): Promise<string | Uint8Array>;
+
+  tag(encoding?: 'bytes'): Promise<Uint8Array>;
+  tag(encoding: 'base64'): Promise<string>;
+  tag(encoding?: 'bytes' | 'base64'): Promise<string | Uint8Array>;
+
+  combined(encoding?: 'bytes'): Promise<Uint8Array>;
+  combined(encoding: 'base64'): Promise<string>;
+  combined(encoding?: 'bytes' | 'base64'): Promise<string | Uint8Array>;
+
+  /** IV + ciphertext + tag, in bytes */
+  readonly combinedSize: number;
+  readonly ivSize: number;
+  readonly tagSize: IGcmTagByteLength;
+}
+
+// Native takes the nonce as a bare length (to generate) or as bytes
+export type INativeAesEncryptOptions = Omit<IAesEncryptOptions, 'nonce'> & {
+  nonce?: number | IBinaryInput | undefined;
+};
+
+declare class NativeAesCryptoModule extends NativeModule {
+  EncryptionKey: typeof EncryptionKey;
+  SealedData: typeof SealedData;
+
+  generateKey(size?: AESKeySize): Promise<EncryptionKey>;
+  importKey(
+    keyInput: string | Uint8Array,
+    encoding?: IEncoding,
+  ): Promise<EncryptionKey>;
+
+  encryptAsync(
+    plaintext: IBinaryInput,
+    key: EncryptionKey,
+    options?: INativeAesEncryptOptions,
+  ): Promise<SealedData>;
+  decryptAsync(
+    sealedData: SealedData,
+    key: EncryptionKey,
+    options?: IAesDecryptOptions,
+  ): Promise<string | Uint8Array>;
+}
+
+export const expoCryptoAes =
+  requireNativeModule<NativeAesCryptoModule>('ExpoCryptoAES');

package/src/core/aes/aes-types.ts

@@ -0,0 +1,48 @@
+// A string input must be base64-encoded
+export type IBinaryInput = string | Uint8Array | ArrayBuffer;
+
+export enum AESKeySize {
+  AES128 = 128,
+  // Unsupported on web
+  AES192 = 192,
+  AES256 = 256,
+}
+
+// GCM tag length in bytes: 16 is the default and the only value Apple supports for encryption
+export type IGcmTagByteLength = 16 | 15 | 14 | 13 | 12 | 8 | 4;
+
+export type IAesSealedDataConfig = {
+  /** @default 12 */
+  ivLength: number;
+  /** @default 16 */
+  tagLength: IGcmTagByteLength;
+};
+
+export type IAesDecryptOptions = {
+  /** @default 'bytes' */
+  output?: 'bytes' | 'base64';
+  // GCM additional authenticated data, base64 when a string
+  additionalData?: IBinaryInput;
+};
+
+export type IBase64DecryptOptions = IAesDecryptOptions & { output: 'base64' };
+
+export type IBytesDecryptOptions = IAesDecryptOptions & { output?: 'bytes' };
+
+export type IGcmNonceParam =
+  | {
+      /** Byte length of the nonce to generate. @default 12 */
+      length: number;
+    }
+  | {
+      bytes: IBinaryInput;
+    };
+
+export type IAesEncryptOptions = {
+  /** @default { length: 12 } */
+  nonce?: IGcmNonceParam;
+  // Ignored on Apple, where the tag is always 16 bytes
+  tagLength?: IGcmTagByteLength;
+  // GCM additional authenticated data, base64 when a string
+  additionalData?: IBinaryInput;
+};

package/src/core/aes/aes.ts

@@ -0,0 +1,142 @@
+import {
+  expoCryptoAes,
+  type INativeAesEncryptOptions,
+} from './aes-native-module';
+import type {
+  IAesDecryptOptions,
+  IAesEncryptOptions,
+  IAesSealedDataConfig,
+  IBase64DecryptOptions,
+  IBinaryInput,
+  IBytesDecryptOptions,
+} from './aes-types';
+
+// Hermes global, absent from the ES2022 lib
+declare function btoa(data: string): string;
+
+// Native has no ArrayBuffer support, and encodes binary options as base64 strings
+function convertBinaryInput(
+  input: IBinaryInput,
+  useBase64 = false,
+): IBinaryInput {
+  const bytes = input instanceof ArrayBuffer ? new Uint8Array(input) : input;
+  if (typeof bytes !== 'string' && useBase64) {
+    return uint8ArrayToBase64(bytes);
+  }
+  return bytes;
+}
+
+function uint8ArrayToBase64(bytes: Uint8Array): string {
+  let binaryString = '';
+  for (const byte of bytes) {
+    binaryString += String.fromCharCode(byte);
+  }
+  return btoa(binaryString);
+}
+
+export class AESEncryptionKey extends expoCryptoAes.EncryptionKey {}
+
+export class AESSealedData extends expoCryptoAes.SealedData {
+  /** `tag` is a separate tag, or the tag length when the ciphertext already carries it */
+  static override fromParts(
+    iv: IBinaryInput,
+    ciphertext: IBinaryInput,
+    tag: IBinaryInput,
+  ): AESSealedData;
+  static override fromParts(
+    iv: IBinaryInput,
+    ciphertextWithTag: IBinaryInput,
+    tagLength?: number,
+  ): AESSealedData;
+
+  static override fromParts(
+    iv: IBinaryInput,
+    ciphertext: IBinaryInput,
+    tag?: IBinaryInput | number,
+  ): AESSealedData {
+    const processedIv = convertBinaryInput(iv);
+    const processedCiphertext = convertBinaryInput(ciphertext);
+
+    if (tag === undefined || typeof tag === 'number') {
+      return expoCryptoAes.SealedData.fromParts(
+        processedIv,
+        processedCiphertext,
+        tag,
+      );
+    }
+    return expoCryptoAes.SealedData.fromParts(
+      processedIv,
+      processedCiphertext,
+      convertBinaryInput(tag),
+    );
+  }
+
+  /** `combined` holds IV, ciphertext and tag back to back */
+  static override fromCombined(
+    combined: IBinaryInput,
+    config?: IAesSealedDataConfig,
+  ): AESSealedData {
+    return expoCryptoAes.SealedData.fromCombined(
+      convertBinaryInput(combined),
+      config,
+    );
+  }
+}
+
+/** AES-GCM encryption. A string plaintext must be base64-encoded */
+export function aesEncryptAsync(
+  plaintext: IBinaryInput,
+  key: AESEncryptionKey,
+  options: IAesEncryptOptions = {},
+): Promise<AESSealedData> {
+  const { nonce, additionalData, ...rest } = options;
+  let nativeOptions: INativeAesEncryptOptions = { ...rest };
+  if (nonce) {
+    nativeOptions = {
+      ...nativeOptions,
+      nonce:
+        'bytes' in nonce ? convertBinaryInput(nonce.bytes, true) : nonce.length,
+    };
+  }
+  if (additionalData) {
+    nativeOptions = {
+      ...nativeOptions,
+      additionalData: convertBinaryInput(additionalData, true),
+    };
+  }
+  return expoCryptoAes.encryptAsync(
+    convertBinaryInput(plaintext),
+    key,
+    nativeOptions,
+  );
+}
+
+export function aesDecryptAsync(
+  sealedData: AESSealedData,
+  key: AESEncryptionKey,
+  options: IBase64DecryptOptions,
+): Promise<string>;
+export function aesDecryptAsync(
+  sealedData: AESSealedData,
+  key: AESEncryptionKey,
+  options?: IBytesDecryptOptions,
+): Promise<Uint8Array>;
+export function aesDecryptAsync(
+  sealedData: AESSealedData,
+  key: AESEncryptionKey,
+  options?: IAesDecryptOptions,
+): Promise<string | Uint8Array>;
+
+export function aesDecryptAsync(
+  sealedData: AESSealedData,
+  key: AESEncryptionKey,
+  options: IAesDecryptOptions = {},
+): Promise<string | Uint8Array> {
+  const { additionalData, ...rest } = options;
+  return expoCryptoAes.decryptAsync(sealedData, key, {
+    ...rest,
+    additionalData: additionalData
+      ? convertBinaryInput(additionalData, true)
+      : undefined,
+  });
+}

package/src/core/aes/index.ts

@@ -0,0 +1,17 @@
+export {
+  AESEncryptionKey,
+  AESSealedData,
+  aesEncryptAsync,
+  aesDecryptAsync,
+} from './aes';
+export {
+  AESKeySize,
+  type IAesDecryptOptions,
+  type IAesEncryptOptions,
+  type IAesSealedDataConfig,
+  type IBase64DecryptOptions,
+  type IBinaryInput,
+  type IBytesDecryptOptions,
+  type IGcmNonceParam,
+  type IGcmTagByteLength,
+} from './aes-types';

package/src/core/index.ts

@@ -7,6 +7,7 @@ export {
   digestStringAsync,
   digest,
 } from './crypto';
+export * from './aes';
 export {
   CryptoDigestAlgorithm,
   CryptoEncoding,