@ricsam/quickjs-crypto 0.0.1 → 0.2.14

package/dist/types/quickjs.d.ts

@@ -0,0 +1,287 @@
+/**
+ * QuickJS Global Type Definitions for @ricsam/quickjs-crypto
+ *
+ * These types define the globals injected by setupCrypto() into a QuickJS context.
+ * Use these types to typecheck user code that will run inside QuickJS.
+ *
+ * @example
+ * // Generate random bytes
+ * const arr = new Uint8Array(16);
+ * crypto.getRandomValues(arr);
+ *
+ * // Generate UUID
+ * const uuid = crypto.randomUUID();
+ *
+ * // Use SubtleCrypto
+ * const key = await crypto.subtle.generateKey(
+ *   { name: "AES-GCM", length: 256 },
+ *   true,
+ *   ["encrypt", "decrypt"]
+ * );
+ */
+
+export {};
+
+declare global {
+  /**
+   * CryptoKey represents a cryptographic key.
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/CryptoKey
+   */
+  interface CryptoKey {
+    /**
+     * The type of key: "public", "private", or "secret".
+     */
+    readonly type: "public" | "private" | "secret";
+
+    /**
+     * Whether the key can be exported.
+     */
+    readonly extractable: boolean;
+
+    /**
+     * The algorithm used by this key.
+     */
+    readonly algorithm: KeyAlgorithm;
+
+    /**
+     * The usages allowed for this key.
+     */
+    readonly usages: ReadonlyArray<KeyUsage>;
+  }
+
+  /**
+   * CryptoKey constructor (keys cannot be constructed directly).
+   */
+  const CryptoKey: {
+    prototype: CryptoKey;
+  };
+
+  /**
+   * SubtleCrypto interface for cryptographic operations.
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/SubtleCrypto
+   */
+  interface SubtleCrypto {
+    /**
+     * Generate a digest (hash) of the given data.
+     *
+     * @param algorithm - Hash algorithm (e.g., "SHA-256", "SHA-384", "SHA-512")
+     * @param data - Data to hash
+     * @returns Promise resolving to the hash as ArrayBuffer
+     */
+    digest(
+      algorithm: AlgorithmIdentifier,
+      data: BufferSource
+    ): Promise<ArrayBuffer>;
+
+    /**
+     * Generate a new cryptographic key or key pair.
+     *
+     * @param algorithm - Key generation algorithm
+     * @param extractable - Whether the key can be exported
+     * @param keyUsages - Allowed key usages
+     * @returns Promise resolving to a CryptoKey or CryptoKeyPair
+     */
+    generateKey(
+      algorithm: RsaHashedKeyGenParams | EcKeyGenParams | AesKeyGenParams | HmacKeyGenParams,
+      extractable: boolean,
+      keyUsages: KeyUsage[]
+    ): Promise<CryptoKey | CryptoKeyPair>;
+
+    /**
+     * Sign data using a private key.
+     *
+     * @param algorithm - Signing algorithm
+     * @param key - Private key to sign with
+     * @param data - Data to sign
+     * @returns Promise resolving to the signature as ArrayBuffer
+     */
+    sign(
+      algorithm: AlgorithmIdentifier,
+      key: CryptoKey,
+      data: BufferSource
+    ): Promise<ArrayBuffer>;
+
+    /**
+     * Verify a signature.
+     *
+     * @param algorithm - Signing algorithm
+     * @param key - Public key to verify with
+     * @param signature - Signature to verify
+     * @param data - Data that was signed
+     * @returns Promise resolving to true if valid, false otherwise
+     */
+    verify(
+      algorithm: AlgorithmIdentifier,
+      key: CryptoKey,
+      signature: BufferSource,
+      data: BufferSource
+    ): Promise<boolean>;
+
+    /**
+     * Encrypt data.
+     *
+     * @param algorithm - Encryption algorithm
+     * @param key - Encryption key
+     * @param data - Data to encrypt
+     * @returns Promise resolving to encrypted data as ArrayBuffer
+     */
+    encrypt(
+      algorithm: AlgorithmIdentifier,
+      key: CryptoKey,
+      data: BufferSource
+    ): Promise<ArrayBuffer>;
+
+    /**
+     * Decrypt data.
+     *
+     * @param algorithm - Decryption algorithm
+     * @param key - Decryption key
+     * @param data - Data to decrypt
+     * @returns Promise resolving to decrypted data as ArrayBuffer
+     */
+    decrypt(
+      algorithm: AlgorithmIdentifier,
+      key: CryptoKey,
+      data: BufferSource
+    ): Promise<ArrayBuffer>;
+
+    /**
+     * Import a key from external data.
+     *
+     * @param format - Key format ("raw", "pkcs8", "spki", "jwk")
+     * @param keyData - Key data
+     * @param algorithm - Key algorithm
+     * @param extractable - Whether the key can be exported
+     * @param keyUsages - Allowed key usages
+     * @returns Promise resolving to a CryptoKey
+     */
+    importKey(
+      format: "raw" | "pkcs8" | "spki" | "jwk",
+      keyData: BufferSource | JsonWebKey,
+      algorithm: AlgorithmIdentifier,
+      extractable: boolean,
+      keyUsages: KeyUsage[]
+    ): Promise<CryptoKey>;
+
+    /**
+     * Export a key.
+     *
+     * @param format - Export format ("raw", "pkcs8", "spki", "jwk")
+     * @param key - Key to export
+     * @returns Promise resolving to ArrayBuffer or JsonWebKey
+     */
+    exportKey(
+      format: "raw" | "pkcs8" | "spki" | "jwk",
+      key: CryptoKey
+    ): Promise<ArrayBuffer | JsonWebKey>;
+
+    /**
+     * Derive bits from a key.
+     *
+     * @param algorithm - Derivation algorithm
+     * @param baseKey - Base key for derivation
+     * @param length - Number of bits to derive
+     * @returns Promise resolving to derived bits as ArrayBuffer
+     */
+    deriveBits(
+      algorithm: AlgorithmIdentifier,
+      baseKey: CryptoKey,
+      length: number
+    ): Promise<ArrayBuffer>;
+
+    /**
+     * Derive a new key from a base key.
+     *
+     * @param algorithm - Derivation algorithm
+     * @param baseKey - Base key for derivation
+     * @param derivedKeyType - Type of key to derive
+     * @param extractable - Whether the derived key can be exported
+     * @param keyUsages - Allowed usages for derived key
+     * @returns Promise resolving to a CryptoKey
+     */
+    deriveKey(
+      algorithm: AlgorithmIdentifier,
+      baseKey: CryptoKey,
+      derivedKeyType: AlgorithmIdentifier,
+      extractable: boolean,
+      keyUsages: KeyUsage[]
+    ): Promise<CryptoKey>;
+
+    /**
+     * Wrap a key for secure export.
+     *
+     * @param format - Key format
+     * @param key - Key to wrap
+     * @param wrappingKey - Key to wrap with
+     * @param wrapAlgorithm - Wrapping algorithm
+     * @returns Promise resolving to wrapped key as ArrayBuffer
+     */
+    wrapKey(
+      format: "raw" | "pkcs8" | "spki" | "jwk",
+      key: CryptoKey,
+      wrappingKey: CryptoKey,
+      wrapAlgorithm: AlgorithmIdentifier
+    ): Promise<ArrayBuffer>;
+
+    /**
+     * Unwrap a wrapped key.
+     *
+     * @param format - Key format
+     * @param wrappedKey - Wrapped key data
+     * @param unwrappingKey - Key to unwrap with
+     * @param unwrapAlgorithm - Unwrapping algorithm
+     * @param unwrappedKeyAlgorithm - Algorithm for the unwrapped key
+     * @param extractable - Whether the unwrapped key can be exported
+     * @param keyUsages - Allowed usages for unwrapped key
+     * @returns Promise resolving to a CryptoKey
+     */
+    unwrapKey(
+      format: "raw" | "pkcs8" | "spki" | "jwk",
+      wrappedKey: BufferSource,
+      unwrappingKey: CryptoKey,
+      unwrapAlgorithm: AlgorithmIdentifier,
+      unwrappedKeyAlgorithm: AlgorithmIdentifier,
+      extractable: boolean,
+      keyUsages: KeyUsage[]
+    ): Promise<CryptoKey>;
+  }
+
+  /**
+   * Crypto interface providing cryptographic functionality.
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/Crypto
+   */
+  interface Crypto {
+    /**
+     * SubtleCrypto interface for cryptographic operations.
+     */
+    readonly subtle: SubtleCrypto;
+
+    /**
+     * Fill a TypedArray with cryptographically random values.
+     *
+     * @param array - TypedArray to fill (max 65536 bytes)
+     * @returns The same array, filled with random values
+     *
+     * @example
+     * const arr = new Uint8Array(16);
+     * crypto.getRandomValues(arr);
+     */
+    getRandomValues<T extends ArrayBufferView | null>(array: T): T;
+
+    /**
+     * Generate a random UUID v4.
+     *
+     * @returns A random UUID string
+     *
+     * @example
+     * const uuid = crypto.randomUUID();
+     * // "550e8400-e29b-41d4-a716-446655440000"
+     */
+    randomUUID(): string;
+  }
+
+  /**
+   * Crypto object providing cryptographic functionality.
+   */
+  const crypto: Crypto;
+}

package/dist/types/random.d.ts

@@ -0,0 +1,14 @@
+import type { QuickJSContext, QuickJSHandle } from "quickjs-emscripten";
+/**
+ * Create the getRandomValues function for the crypto global
+ *
+ * getRandomValues fills a TypedArray with cryptographically random values
+ * and returns the same array (modified in-place)
+ */
+export declare function createGetRandomValuesFunction(context: QuickJSContext): QuickJSHandle;
+/**
+ * Create the randomUUID function for the crypto global
+ *
+ * randomUUID returns a string containing a randomly generated UUID v4
+ */
+export declare function createRandomUUIDFunction(context: QuickJSContext): QuickJSHandle;

package/dist/types/setup.d.ts

@@ -0,0 +1,43 @@
+import type { QuickJSContext } from "quickjs-emscripten";
+import type { SetupCryptoOptions, CryptoHandle } from "./types.ts";
+/**
+ * Setup crypto globals in a QuickJS context
+ *
+ * Provides: crypto.subtle (SubtleCrypto), crypto.getRandomValues, crypto.randomUUID, CryptoKey
+ *
+ * @example
+ * ```typescript
+ * const handle = setupCrypto(context);
+ *
+ * context.evalCode(`
+ *   // Generate a random UUID
+ *   const uuid = crypto.randomUUID();
+ *
+ *   // Generate random bytes
+ *   const arr = new Uint8Array(16);
+ *   crypto.getRandomValues(arr);
+ *
+ *   // Use SubtleCrypto for encryption
+ *   const key = await crypto.subtle.generateKey(
+ *     { name: "AES-GCM", length: 256 },
+ *     true,
+ *     ["encrypt", "decrypt"]
+ *   );
+ *
+ *   const iv = crypto.getRandomValues(new Uint8Array(12));
+ *   const data = new TextEncoder().encode("secret message");
+ *   const encrypted = await crypto.subtle.encrypt(
+ *     { name: "AES-GCM", iv },
+ *     key,
+ *     data
+ *   );
+ * `);
+ *
+ * handle.dispose();
+ * ```
+ *
+ * @param context - QuickJS context
+ * @param options - Setup options
+ * @returns CryptoHandle for cleanup
+ */
+export declare function setupCrypto(context: QuickJSContext, options?: SetupCryptoOptions): CryptoHandle;

package/dist/types/subtle-crypto.d.ts

@@ -0,0 +1,12 @@
+import type { QuickJSContext, QuickJSHandle } from "quickjs-emscripten";
+/**
+ * Helper to create a CryptoKey instance in QuickJS from a host CryptoKey
+ *
+ * This registers the host key in our state management and creates
+ * a QuickJS CryptoKey object that references it via __instanceId__
+ */
+export declare function createCryptoKeyInstance(context: QuickJSContext, hostKey: globalThis.CryptoKey): QuickJSHandle;
+/**
+ * Create the SubtleCrypto object with all methods
+ */
+export declare function createSubtleCryptoObject(context: QuickJSContext): QuickJSHandle;

package/dist/types/types.d.ts

@@ -0,0 +1,44 @@
+import type { StateMap, CoreHandle } from "@ricsam/quickjs-core";
+export type { StateMap, CoreHandle };
+/**
+ * Key usage types as defined by Web Crypto API
+ */
+export type KeyUsage = "encrypt" | "decrypt" | "sign" | "verify" | "deriveKey" | "deriveBits" | "wrapKey" | "unwrapKey";
+/**
+ * Key type
+ */
+export type KeyType = "public" | "private" | "secret";
+/**
+ * Internal state for CryptoKey instances
+ * The actual CryptoKey stays on the host side
+ */
+export interface CryptoKeyState {
+    /** Reference to host crypto key (actual CryptoKey from host) */
+    hostKey: globalThis.CryptoKey;
+    /** Key type: public, private, or secret */
+    type: KeyType;
+    /** Whether the key can be exported */
+    extractable: boolean;
+    /** Algorithm information */
+    algorithm: KeyAlgorithm;
+    /** Allowed usages for this key */
+    usages: KeyUsage[];
+}
+/**
+ * Options for setupCrypto
+ */
+export interface SetupCryptoOptions {
+    /** Shared state map for instance tracking */
+    stateMap?: StateMap;
+    /** Core handle from setupCore */
+    coreHandle?: CoreHandle;
+}
+/**
+ * Handle returned from setupCrypto
+ */
+export interface CryptoHandle {
+    /** Shared state map */
+    readonly stateMap: StateMap;
+    /** Dispose and cleanup */
+    dispose(): void;
+}

package/package.json

@@ -1,10 +1,58 @@
 {
   "name": "@ricsam/quickjs-crypto",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @ricsam/quickjs-crypto",
+  "version": "0.2.14",
+  "main": "./dist/cjs/index.cjs",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "require": "./dist/cjs/index.cjs",
+      "import": "./dist/mjs/index.mjs"
+    },
+    "./quickjs": {
+      "types": "./dist/types/quickjs.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target bun",
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@ricsam/quickjs-core": "^0.2.14",
+    "quickjs-emscripten": "^0.31.0"
+  },
+  "peerDependencies": {
+    "quickjs-emscripten": "^0.31.0"
+  },
+  "author": "Richard Samuelsson",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ricsam/richie-qjs.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ricsam/richie-qjs/issues"
+  },
+  "homepage": "https://github.com/ricsam/richie-qjs#readme",
   "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
+    "quickjs",
+    "sandbox",
+    "javascript",
+    "runtime",
+    "fetch",
+    "filesystem",
+    "streams",
+    "wasm",
+    "emscripten"
+  ],
+  "description": "Web Crypto API implementation for QuickJS runtime",
+  "module": "./dist/mjs/index.mjs",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md"
   ]
-}
+}