@fgv/ts-web-extras 5.1.0-16 → 5.1.0-18

package/dist/ts-web-extras.d.ts

@@ -24,7 +24,7 @@ import { Result } from '@fgv/ts-utils';
  *
  * @public
  */
-declare class BrowserCryptoProvider implements ICryptoProvider {
+declare class BrowserCryptoProvider implements CryptoUtils_2.ICryptoProvider {
     private readonly _crypto;
     /**
      * Creates a new {@link CryptoUtils.BrowserCryptoProvider | BrowserCryptoProvider}.
@@ -37,7 +37,7 @@ declare class BrowserCryptoProvider implements ICryptoProvider {
      * @param key - 32-byte encryption key
      * @returns `Success` with encryption result, or `Failure` with an error.
      */
-    encrypt(plaintext: string, key: Uint8Array): Promise<Result<IEncryptionResult>>;
+    encrypt(plaintext: string, key: Uint8Array): Promise<Result<CryptoUtils_2.IEncryptionResult>>;
     /**
      * Decrypts ciphertext using AES-256-GCM.
      * @param encryptedData - Encrypted bytes
@@ -84,6 +84,31 @@ declare class BrowserCryptoProvider implements ICryptoProvider {
      * @returns Success with decoded bytes, or Failure if invalid base64
      */
     fromBase64(base64: string): Result<Uint8Array>;
+    /**
+     * Generates a new asymmetric keypair via Web Crypto.
+     * @param algorithm - The algorithm to use.
+     * @param extractable - Whether the resulting keys may be exported.
+     * @returns `Success` with the generated `CryptoKeyPair`, or `Failure` with an error.
+     */
+    generateKeyPair(algorithm: CryptoUtils_2.KeyPairAlgorithm, extractable: boolean): Promise<Result<CryptoKeyPair>>;
+    /**
+     * Exports a public `CryptoKey` as a JSON Web Key.
+     * @remarks
+     * Rejects non-public keys at runtime. WebCrypto's `exportKey('jwk', ...)`
+     * does not enforce public-vs-private; without this guard a caller that
+     * passed an extractable private key would receive its private fields
+     * (`d`, `p`, `q`, ...) as JWK, defeating the method's name.
+     * @param publicKey - Extractable public key to export.
+     * @returns `Success` with the JWK, or `Failure` if not a public key or if export fails.
+     */
+    exportPublicKeyJwk(publicKey: CryptoKey): Promise<Result<JsonWebKey>>;
+    /**
+     * Imports a public-key JWK as a `CryptoKey` for the requested algorithm.
+     * @param jwk - The JSON Web Key produced by a prior export.
+     * @param algorithm - The algorithm the key was generated for.
+     * @returns `Success` with the imported public `CryptoKey`, or `Failure` with an error.
+     */
+    importPublicKeyJwk(jwk: JsonWebKey, algorithm: CryptoUtils_2.KeyPairAlgorithm): Promise<Result<CryptoKey>>;
 }
 
 /**
@@ -331,7 +356,7 @@ declare function extractFileListMetadata(fileList: FileList): Array<IFileMetadat
      static getOriginalFile(fileList: FileList, targetPath: string): Result<File>;
      /**
       * Extract file metadata from a File.
-      * @param fileList - The File to extract metadata from
+      * @param file - The File to extract metadata from
       * @returns The {@link IFileMetadata | file metadata}
       */
      static extractFileMetadata(file: File): IFileMetadata;
@@ -751,8 +776,6 @@ declare function extractFileListMetadata(fileList: FileList): Array<IFileMetadat
      private static _requestWithParams;
  }
 
- declare type ICryptoProvider = CryptoUtils_2.ICryptoProvider;
-
  /**
   * Tree initializer for File System Access API directory handles.
   * @public
@@ -763,8 +786,6 @@ declare function extractFileListMetadata(fileList: FileList): Array<IFileMetadat
      readonly nonRecursive?: boolean;
  }
 
- declare type IEncryptionResult = CryptoUtils_2.IEncryptionResult;
-
  /**
   * Tree initializer for File System Access API file handles.
   * @public

package/docs/CryptoUtils/classes/BrowserCryptoProvider.exportPublicKeyJwk.md

@@ -0,0 +1,24 @@
+[Home](../../README.md) > [CryptoUtils](../README.md) > [BrowserCryptoProvider](./BrowserCryptoProvider.md) > exportPublicKeyJwk
+
+## BrowserCryptoProvider.exportPublicKeyJwk() method
+
+Exports a public `CryptoKey` as a JSON Web Key.
+
+**Signature:**
+
+```typescript
+exportPublicKeyJwk(publicKey: CryptoKey): Promise<Result<JsonWebKey>>;
+```
+
+**Parameters:**
+
+<table><thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead>
+<tbody>
+<tr><td>publicKey</td><td>CryptoKey</td><td>Extractable public key to export.</td></tr>
+</tbody></table>
+
+**Returns:**
+
+Promise&lt;Result&lt;JsonWebKey&gt;&gt;
+
+`Success` with the JWK, or `Failure` if not a public key or if export fails.

package/docs/CryptoUtils/classes/BrowserCryptoProvider.generateKeyPair.md

@@ -0,0 +1,25 @@
+[Home](../../README.md) > [CryptoUtils](../README.md) > [BrowserCryptoProvider](./BrowserCryptoProvider.md) > generateKeyPair
+
+## BrowserCryptoProvider.generateKeyPair() method
+
+Generates a new asymmetric keypair via Web Crypto.
+
+**Signature:**
+
+```typescript
+generateKeyPair(algorithm: KeyPairAlgorithm, extractable: boolean): Promise<Result<CryptoKeyPair>>;
+```
+
+**Parameters:**
+
+<table><thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead>
+<tbody>
+<tr><td>algorithm</td><td>KeyPairAlgorithm</td><td>The algorithm to use.</td></tr>
+<tr><td>extractable</td><td>boolean</td><td>Whether the resulting keys may be exported.</td></tr>
+</tbody></table>
+
+**Returns:**
+
+Promise&lt;Result&lt;CryptoKeyPair&gt;&gt;
+
+`Success` with the generated `CryptoKeyPair`, or `Failure` with an error.

package/docs/CryptoUtils/classes/BrowserCryptoProvider.importPublicKeyJwk.md

@@ -0,0 +1,25 @@
+[Home](../../README.md) > [CryptoUtils](../README.md) > [BrowserCryptoProvider](./BrowserCryptoProvider.md) > importPublicKeyJwk
+
+## BrowserCryptoProvider.importPublicKeyJwk() method
+
+Imports a public-key JWK as a `CryptoKey` for the requested algorithm.
+
+**Signature:**
+
+```typescript
+importPublicKeyJwk(jwk: JsonWebKey, algorithm: KeyPairAlgorithm): Promise<Result<CryptoKey>>;
+```
+
+**Parameters:**
+
+<table><thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead>
+<tbody>
+<tr><td>jwk</td><td>JsonWebKey</td><td>The JSON Web Key produced by a prior export.</td></tr>
+<tr><td>algorithm</td><td>KeyPairAlgorithm</td><td>The algorithm the key was generated for.</td></tr>
+</tbody></table>
+
+**Returns:**
+
+Promise&lt;Result&lt;CryptoKey&gt;&gt;
+
+`Success` with the imported public `CryptoKey`, or `Failure` with an error.

package/docs/CryptoUtils/classes/BrowserCryptoProvider.md

@@ -160,5 +160,44 @@ Encodes binary data to base64 string.
 
 Decodes base64 string to binary data.
 
+</td></tr>
+<tr><td>
+
+[generateKeyPair(algorithm, extractable)](./BrowserCryptoProvider.generateKeyPair.md)
+
+</td><td>
+
+
+
+</td><td>
+
+Generates a new asymmetric keypair via Web Crypto.
+
+</td></tr>
+<tr><td>
+
+[exportPublicKeyJwk(publicKey)](./BrowserCryptoProvider.exportPublicKeyJwk.md)
+
+</td><td>
+
+
+
+</td><td>
+
+Exports a public `CryptoKey` as a JSON Web Key.
+
+</td></tr>
+<tr><td>
+
+[importPublicKeyJwk(jwk, algorithm)](./BrowserCryptoProvider.importPublicKeyJwk.md)
+
+</td><td>
+
+
+
+</td><td>
+
+Imports a public-key JWK as a `CryptoKey` for the requested algorithm.
+
 </td></tr>
 </tbody></table>

package/docs/classes/BrowserCryptoProvider.exportPublicKeyJwk.md

@@ -0,0 +1,24 @@
+[Home](../README.md) > [BrowserCryptoProvider](./BrowserCryptoProvider.md) > exportPublicKeyJwk
+
+## BrowserCryptoProvider.exportPublicKeyJwk() method
+
+Exports a public `CryptoKey` as a JSON Web Key.
+
+**Signature:**
+
+```typescript
+exportPublicKeyJwk(publicKey: CryptoKey): Promise<Result<JsonWebKey>>;
+```
+
+**Parameters:**
+
+<table><thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead>
+<tbody>
+<tr><td>publicKey</td><td>CryptoKey</td><td>Extractable public key to export.</td></tr>
+</tbody></table>
+
+**Returns:**
+
+Promise&lt;Result&lt;JsonWebKey&gt;&gt;
+
+`Success` with the JWK, or `Failure` if not a public key or if export fails.

package/docs/classes/BrowserCryptoProvider.generateKeyPair.md

@@ -0,0 +1,25 @@
+[Home](../README.md) > [BrowserCryptoProvider](./BrowserCryptoProvider.md) > generateKeyPair
+
+## BrowserCryptoProvider.generateKeyPair() method
+
+Generates a new asymmetric keypair via Web Crypto.
+
+**Signature:**
+
+```typescript
+generateKeyPair(algorithm: KeyPairAlgorithm, extractable: boolean): Promise<Result<CryptoKeyPair>>;
+```
+
+**Parameters:**
+
+<table><thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead>
+<tbody>
+<tr><td>algorithm</td><td>KeyPairAlgorithm</td><td>The algorithm to use.</td></tr>
+<tr><td>extractable</td><td>boolean</td><td>Whether the resulting keys may be exported.</td></tr>
+</tbody></table>
+
+**Returns:**
+
+Promise&lt;Result&lt;CryptoKeyPair&gt;&gt;
+
+`Success` with the generated `CryptoKeyPair`, or `Failure` with an error.

package/docs/classes/BrowserCryptoProvider.importPublicKeyJwk.md

@@ -0,0 +1,25 @@
+[Home](../README.md) > [BrowserCryptoProvider](./BrowserCryptoProvider.md) > importPublicKeyJwk
+
+## BrowserCryptoProvider.importPublicKeyJwk() method
+
+Imports a public-key JWK as a `CryptoKey` for the requested algorithm.
+
+**Signature:**
+
+```typescript
+importPublicKeyJwk(jwk: JsonWebKey, algorithm: KeyPairAlgorithm): Promise<Result<CryptoKey>>;
+```
+
+**Parameters:**
+
+<table><thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead>
+<tbody>
+<tr><td>jwk</td><td>JsonWebKey</td><td>The JSON Web Key produced by a prior export.</td></tr>
+<tr><td>algorithm</td><td>KeyPairAlgorithm</td><td>The algorithm the key was generated for.</td></tr>
+</tbody></table>
+
+**Returns:**
+
+Promise&lt;Result&lt;CryptoKey&gt;&gt;
+
+`Success` with the imported public `CryptoKey`, or `Failure` with an error.

package/docs/classes/BrowserCryptoProvider.md

@@ -160,5 +160,44 @@ Encodes binary data to base64 string.
 
 Decodes base64 string to binary data.
 
+</td></tr>
+<tr><td>
+
+[generateKeyPair(algorithm, extractable)](./BrowserCryptoProvider.generateKeyPair.md)
+
+</td><td>
+
+
+
+</td><td>
+
+Generates a new asymmetric keypair via Web Crypto.
+
+</td></tr>
+<tr><td>
+
+[exportPublicKeyJwk(publicKey)](./BrowserCryptoProvider.exportPublicKeyJwk.md)
+
+</td><td>
+
+
+
+</td><td>
+
+Exports a public `CryptoKey` as a JSON Web Key.
+
+</td></tr>
+<tr><td>
+
+[importPublicKeyJwk(jwk, algorithm)](./BrowserCryptoProvider.importPublicKeyJwk.md)
+
+</td><td>
+
+
+
+</td><td>
+
+Imports a public-key JWK as a `CryptoKey` for the requested algorithm.
+
 </td></tr>
 </tbody></table>

package/docs/classes/FileApiTreeAccessors.extractFileMetadata.md

@@ -14,7 +14,7 @@ static extractFileMetadata(file: File): IFileMetadata;
 
 <table><thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead>
 <tbody>
-<tr><td>file</td><td>File</td><td></td></tr>
+<tr><td>file</td><td>File</td><td>The File to extract metadata from</td></tr>
 </tbody></table>
 
 **Returns:**

package/docs/classes/FileSystemAccessTreeAccessors.md

@@ -152,7 +152,7 @@ Implements `FileTree.IMutableFileTreeAccessors.fileIsMutable`
 
 </td><td>
 
-FileTree.IFileTreeAccessors.resolveAbsolutePath
+Resolves paths to an absolute path.
 
 </td></tr>
 <tr><td>
@@ -165,7 +165,7 @@ FileTree.IFileTreeAccessors.resolveAbsolutePath
 
 </td><td>
 
-FileTree.IFileTreeAccessors.getExtension
+Gets the extension of a path.
 
 </td></tr>
 <tr><td>
@@ -178,7 +178,7 @@ FileTree.IFileTreeAccessors.getExtension
 
 </td><td>
 
-FileTree.IFileTreeAccessors.getBaseName
+Gets the base name of a path.
 
 </td></tr>
 <tr><td>
@@ -191,7 +191,7 @@ FileTree.IFileTreeAccessors.getBaseName
 
 </td><td>
 
-FileTree.IFileTreeAccessors.joinPaths
+Joins paths together.
 
 </td></tr>
 <tr><td>
@@ -204,7 +204,7 @@ FileTree.IFileTreeAccessors.joinPaths
 
 </td><td>
 
-FileTree.IFileTreeAccessors.getItem
+Gets an item from the file tree.
 
 </td></tr>
 <tr><td>
@@ -217,7 +217,7 @@ FileTree.IFileTreeAccessors.getItem
 
 </td><td>
 
-FileTree.IFileTreeAccessors.getFileContents
+Gets the contents of a file in the file tree.
 
 </td></tr>
 <tr><td>
@@ -230,7 +230,7 @@ FileTree.IFileTreeAccessors.getFileContents
 
 </td><td>
 
-FileTree.IFileTreeAccessors.getFileContentType
+Gets the content type of a file in the file tree.
 
 </td></tr>
 <tr><td>
@@ -243,7 +243,7 @@ FileTree.IFileTreeAccessors.getFileContentType
 
 </td><td>
 
-FileTree.IFileTreeAccessors.getChildren
+Gets the children of a directory in the file tree.
 
 </td></tr>
 <tr><td>
@@ -256,7 +256,7 @@ FileTree.IFileTreeAccessors.getChildren
 
 </td><td>
 
-FileTree.IMutableFileTreeAccessors.createDirectory
+Creates a directory at the given path, including any missing parent directories.
 
 </td></tr>
 <tr><td>
@@ -269,7 +269,7 @@ FileTree.IMutableFileTreeAccessors.createDirectory
 
 </td><td>
 
-FileTree.IMutableFileTreeAccessors.deleteDirectory
+Deletes a directory at the given path.
 
 </td></tr>
 </tbody></table>

package/docs/classes/HttpTreeAccessors.deleteFile.md

@@ -2,7 +2,7 @@
 
 ## HttpTreeAccessors.deleteFile() method
 
-FileTree.IMutableFileTreeAccessors.deleteFile
+Deletes a file at the given path.
 
 **Signature:**
 
@@ -14,9 +14,11 @@ deleteFile(path: string): Result<boolean>;
 
 <table><thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead>
 <tbody>
-<tr><td>path</td><td>string</td><td></td></tr>
+<tr><td>path</td><td>string</td><td>The path of the file to delete.</td></tr>
 </tbody></table>
 
 **Returns:**
 
 Result&lt;boolean&gt;
+
+`Success` with `true` if the file was deleted, or `Failure` with an error message.

package/docs/classes/HttpTreeAccessors.md

@@ -99,7 +99,7 @@ Gets the list of paths for all dirty files.
 
 </td><td>
 
-FileTree.IMutableFileTreeAccessors.deleteFile
+Deletes a file at the given path.
 
 </td></tr>
 <tr><td>
@@ -138,7 +138,7 @@ Checks if a file is mutable (can be modified).
 
 </td><td>
 
-FileTree.IFileTreeAccessors.resolveAbsolutePath
+Resolves paths to an absolute path.
 
 </td></tr>
 <tr><td>
@@ -151,7 +151,7 @@ FileTree.IFileTreeAccessors.resolveAbsolutePath
 
 </td><td>
 
-FileTree.IFileTreeAccessors.getExtension
+Gets the extension of a path.
 
 </td></tr>
 <tr><td>
@@ -164,7 +164,7 @@ FileTree.IFileTreeAccessors.getExtension
 
 </td><td>
 
-FileTree.IFileTreeAccessors.getBaseName
+Gets the base name of a path.
 
 </td></tr>
 <tr><td>
@@ -177,7 +177,7 @@ FileTree.IFileTreeAccessors.getBaseName
 
 </td><td>
 
-FileTree.IFileTreeAccessors.joinPaths
+Joins paths together.
 
 </td></tr>
 <tr><td>
@@ -190,7 +190,7 @@ FileTree.IFileTreeAccessors.joinPaths
 
 </td><td>
 
-FileTree.IFileTreeAccessors.getItem
+Gets an item from the file tree.
 
 </td></tr>
 <tr><td>
@@ -203,7 +203,7 @@ FileTree.IFileTreeAccessors.getItem
 
 </td><td>
 
-FileTree.IFileTreeAccessors.getFileContents
+Gets the contents of a file in the file tree.
 
 </td></tr>
 <tr><td>
@@ -216,7 +216,7 @@ FileTree.IFileTreeAccessors.getFileContents
 
 </td><td>
 
-FileTree.IFileTreeAccessors.getFileContentType
+Gets the content type of a file in the file tree.
 
 </td></tr>
 <tr><td>
@@ -229,7 +229,7 @@ FileTree.IFileTreeAccessors.getFileContentType
 
 </td><td>
 
-FileTree.IFileTreeAccessors.getChildren
+Gets the children of a directory in the file tree.
 
 </td></tr>
 <tr><td>
@@ -242,7 +242,7 @@ FileTree.IFileTreeAccessors.getChildren
 
 </td><td>
 
-FileTree.IMutableFileTreeAccessors.createDirectory
+Creates a directory at the given path, including any missing parent directories.
 
 </td></tr>
 <tr><td>
@@ -255,7 +255,7 @@ FileTree.IMutableFileTreeAccessors.createDirectory
 
 </td><td>
 
-FileTree.IMutableFileTreeAccessors.deleteDirectory
+Deletes a directory at the given path.
 
 </td></tr>
 </tbody></table>

package/docs/classes/LocalStorageTreeAccessors.md

@@ -147,7 +147,7 @@ Check if a file is mutable and return persistence detail.
 
 </td><td>
 
-FileTree.IFileTreeAccessors.resolveAbsolutePath
+Resolves paths to an absolute path.
 
 </td></tr>
 <tr><td>
@@ -160,7 +160,7 @@ FileTree.IFileTreeAccessors.resolveAbsolutePath
 
 </td><td>
 
-FileTree.IFileTreeAccessors.getExtension
+Gets the extension of a path.
 
 </td></tr>
 <tr><td>
@@ -173,7 +173,7 @@ FileTree.IFileTreeAccessors.getExtension
 
 </td><td>
 
-FileTree.IFileTreeAccessors.getBaseName
+Gets the base name of a path.
 
 </td></tr>
 <tr><td>
@@ -186,7 +186,7 @@ FileTree.IFileTreeAccessors.getBaseName
 
 </td><td>
 
-FileTree.IFileTreeAccessors.joinPaths
+Joins paths together.
 
 </td></tr>
 <tr><td>
@@ -199,7 +199,7 @@ FileTree.IFileTreeAccessors.joinPaths
 
 </td><td>
 
-FileTree.IFileTreeAccessors.getItem
+Gets an item from the file tree.
 
 </td></tr>
 <tr><td>
@@ -212,7 +212,7 @@ FileTree.IFileTreeAccessors.getItem
 
 </td><td>
 
-FileTree.IFileTreeAccessors.getFileContents
+Gets the contents of a file in the file tree.
 
 </td></tr>
 <tr><td>
@@ -225,7 +225,7 @@ FileTree.IFileTreeAccessors.getFileContents
 
 </td><td>
 
-FileTree.IFileTreeAccessors.getFileContentType
+Gets the content type of a file in the file tree.
 
 </td></tr>
 <tr><td>
@@ -238,7 +238,7 @@ FileTree.IFileTreeAccessors.getFileContentType
 
 </td><td>
 
-FileTree.IFileTreeAccessors.getChildren
+Gets the children of a directory in the file tree.
 
 </td></tr>
 <tr><td>
@@ -251,7 +251,7 @@ FileTree.IFileTreeAccessors.getChildren
 
 </td><td>
 
-FileTree.IMutableFileTreeAccessors.createDirectory
+Creates a directory at the given path, including any missing parent directories.
 
 </td></tr>
 <tr><td>
@@ -264,7 +264,7 @@ FileTree.IMutableFileTreeAccessors.createDirectory
 
 </td><td>
 
-FileTree.IMutableFileTreeAccessors.deleteDirectory
+Deletes a directory at the given path.
 
 </td></tr>
 </tbody></table>

package/etc/ts-web-extras.api.md

@@ -10,19 +10,19 @@ import { FileTree } from '@fgv/ts-json-base';
 import { Logging } from '@fgv/ts-utils';
 import { Result } from '@fgv/ts-utils';
 
-// Warning: (ae-forgotten-export) The symbol "ICryptoProvider" needs to be exported by the entry point index.d.ts
-//
 // @public
-class BrowserCryptoProvider implements ICryptoProvider {
+class BrowserCryptoProvider implements CryptoUtils_2.ICryptoProvider {
     // Warning: (ae-unresolved-link) The @link reference could not be resolved: This type of declaration is not supported yet by the resolver
     constructor(cryptoApi?: Crypto);
     decrypt(encryptedData: Uint8Array, key: Uint8Array, iv: Uint8Array, authTag: Uint8Array): Promise<Result<string>>;
     deriveKey(password: string, salt: Uint8Array, iterations: number): Promise<Result<Uint8Array>>;
-    // Warning: (ae-forgotten-export) The symbol "IEncryptionResult" needs to be exported by the entry point index.d.ts
-    encrypt(plaintext: string, key: Uint8Array): Promise<Result<IEncryptionResult>>;
+    encrypt(plaintext: string, key: Uint8Array): Promise<Result<CryptoUtils_2.IEncryptionResult>>;
+    exportPublicKeyJwk(publicKey: CryptoKey): Promise<Result<JsonWebKey>>;
     fromBase64(base64: string): Result<Uint8Array>;
     generateKey(): Promise<Result<Uint8Array>>;
+    generateKeyPair(algorithm: CryptoUtils_2.KeyPairAlgorithm, extractable: boolean): Promise<Result<CryptoKeyPair>>;
     generateRandomBytes(length: number): Result<Uint8Array>;
+    importPublicKeyJwk(jwk: JsonWebKey, algorithm: CryptoUtils_2.KeyPairAlgorithm): Promise<Result<CryptoKey>>;
     sha256(data: string): Promise<Result<string>>;
     toBase64(data: Uint8Array): string;
 }