@chilkat/react-native 11.6.1

package/src/specs/CodeSign.nitro.ts

@@ -0,0 +1,307 @@
+// Generated by ReactNativeNs.RnGenerator -- do not edit.
+import type { HybridObject } from 'react-native-nitro-modules'
+import type { Cert } from './Cert.nitro'
+import type { JsonObject } from './JsonObject.nitro'
+
+/**
+ * Sign, verify, inspect, and remove Authenticode signatures on Windows executables.
+ *
+ * `CodeSign` works directly with Authenticode signatures on
+ * Windows executable files such as `.exe` and `.dll`.
+ * It provides functionality for applying a code-signing signature, validating
+ * whether a signed executable can be trusted, extracting signature information,
+ * retrieving the signer certificate, and removing an existing signature.
+ *
+ * **Sign EXE and DLL files**
+ *
+ * Apply Authenticode signatures to Windows executable files using a
+ * certificate and associated private key.
+ *
+ * **Validate trust**
+ *
+ * Check whether a signed executable has a valid signature and whether the
+ * signing certificate chain can be trusted.
+ *
+ * **Inspect signatures**
+ *
+ * Extract details about the Authenticode signature, including signer
+ * information and signature-related metadata.
+ *
+ * **Retrieve signer certificates**
+ *
+ * Get the certificate used to sign the executable and inspect it with
+ * `Chilkat.Cert`.
+ *
+ * **Remove signatures**
+ *
+ * Remove an existing Authenticode signature from a Windows executable when
+ * an unsigned output file is required.
+ *
+ * **Diagnostics**
+ *
+ * Use detailed diagnostic output to troubleshoot signing, certificate,
+ * trust-chain, timestamping, or validation problems.
+ *
+ * **Common pattern:**
+ * Load or provide a code-signing certificate that has access to its private
+ * key, sign the target `.exe` or `.dll`, optionally add
+ * timestamping if supported by the signing workflow, then verify the resulting
+ * signature and inspect diagnostics if validation does not succeed.
+ *
+ * For an extended overview, see
+ * [CodeSign Class Overview](https://www.chilkatsoft.com/codesign_class_overview.asp).
+ *
+ * Each `CodeSign` instance owns a native Chilkat object. It is released when the JavaScript object
+ * is
+ * garbage collected, or immediately by `dispose()`; any use after `dispose()` throws.
+ * Create one with `new CodeSign()`.
+ *
+ * Methods that can take a while (network, files, compression, key generation) also have an
+ * `...Async` form returning a `Promise`; it runs on a native worker thread so the UI keeps
+ * rendering. While such a call is pending, every other call on this object throws, except
+ * {@link CodeSign.abort} and assigning {@link CodeSign.onPercentDone} / {@link
+ * CodeSign.onProgressInfo}.
+ */
+export interface CodeSign extends HybridObject<{ ios: 'c++', android: 'c++' }> {
+  // ---- Properties ----
+
+  /**
+   * Provides HTML-formatted information about the last called method or property. If a method call
+   * fails or behaves unexpectedly, check this property for details. Note that information is
+   * available regardless of the method call's success.
+   *
+   * This property is read-only.
+   */
+  readonly lastErrorHtml: string
+
+  /**
+   * Provides plain text information about the last called method or property. If a method call
+   * fails or behaves unexpectedly, check this property for details. Note that information is
+   * available regardless of the method call's success.
+   *
+   * This property is read-only.
+   */
+  readonly lastErrorText: string
+
+  /**
+   * Provides XML-formatted information about the last called method or property. If a method call
+   * fails or behaves unexpectedly, check this property for details. Note that information is
+   * available regardless of the method call's success.
+   *
+   * This property is read-only.
+   */
+  readonly lastErrorXml: string
+
+  /**
+   * Version of the component/library, such as "10.1.0"
+   *
+   * This property is read-only.
+   */
+  readonly version: string
+
+  /**
+   * If set to a file path, this property logs the LastErrorText of each Chilkat method or property
+   * call to the specified file. This logging helps identify the context and history of Chilkat
+   * calls leading up to any crash or hang, aiding in debugging.
+   *
+   * Enabling the VerboseLogging property provides more detailed information.
+   *
+   * This property is mainly used for debugging rare instances where a Chilkat method call causes a
+   * hang or crash, which should generally not happen.
+   *
+   * Possible causes of hangs include:
+   *
+   * - A timeout property set to 0, indicating an infinite timeout.
+   *
+   * - A hang occurring within an event callback in the application code.
+   *
+   * - An internal bug in the Chilkat code causing the hang.
+   */
+  debugLogFilePath: string
+
+  /**
+   * If set to `true`, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may
+   * contain more verbose information. The default value is `false`. Verbose logging should only be
+   * used for debugging. The potentially large quantity of logged information may adversely affect
+   * peformance.
+   */
+  verboseLogging: boolean
+
+  /**
+   * Indicates the success or failure of the most recent method call: `true` means success, `false`
+   * means failure. This property remains unchanged by property setters or getters. This method is
+   * present to address challenges in checking for null or Nothing returns in certain programming
+   * languages. Note: This property does not apply to methods that return integer values or to
+   * boolean-returning methods where the boolean does not indicate success or failure.
+   */
+  lastMethodSuccess: boolean
+
+  /**
+   * Provides a comma-separated list of specialized compatibility or validation options. The default
+   * is an empty string, which is appropriate for normal use.
+   *
+   * OptionEffect
+   *
+   * | `codesign-allow-expired-cert` | | Prevents Authenticode verification from failing solely
+   * because the signing certificate is expired. |
+   *
+   * **Use only for an explicit trust policy:** This option relaxes the certificate-expiration
+   * check; it does not disable file-integrity, signature, chain, or other validation checks. It is
+   * not a substitute for timestamping. A signature carrying a valid trusted timestamp should
+   * ordinarily remain verifiable after the signing certificate expires without this option.
+   */
+  uncommonOptions: string
+
+  /**
+   * Specifies the approximate interval, in milliseconds, between `AbortCheck` event callbacks
+   * during supported operations. An event handler can request that the current operation be
+   * aborted.
+   *
+   * The default is `0`, which disables `AbortCheck` callbacks. Setting a positive value enables
+   * periodic callbacks when an operation is sufficiently long-running; methods that finish quickly
+   * may complete without generating one.
+   *
+   * **Callback interval:** The interval is a scheduling target rather than a real-time guarantee.
+   * Callback timing can vary while waiting for private-key hardware, a timestamp authority,
+   * certificate-chain processing, or other operating-system services.
+   */
+  heartbeatMs: number
+
+  // ---- Methods ----
+
+  /**
+   * Verifies the embedded Microsoft Authenticode signature of the Windows executable or DLL
+   * specified by `path`. Structured information about the signature, signer, certificate chain,
+   * digest algorithms, timestamp, and validation result is written to `sigInfo`.
+   *
+   * Returns `true` when the signature satisfies the applicable Authenticode validation checks under
+   * the current Windows trust configuration. This includes confirming that the signed portions of
+   * the file have not changed and evaluating the signing certificate and timestamp information, as
+   * applicable. An unsigned file or a signature that does not validate causes the method to return
+   * `false`. Inspect `sigInfo` and `LastErrorText` for details.
+   *
+   * **What successful verification means:** Authenticode verifies publisher identity, file
+   * integrity, and certificate trust according to the validation policy. It does not prove that the
+   * software is bug-free, safe to execute, or free of malicious behavior. Trust results can also
+   * depend on the Windows trusted-root store, certificate-chain availability, timestamp validity,
+   * revocation policy, and other system trust settings.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link CodeSign.lastErrorText}.
+   */
+  verifySignature(path: string, sigInfo: JsonObject): void
+
+  /**
+   * Removes the embedded Authenticode signature from the Windows executable or DLL specified by
+   * `path`. The file is modified in place. Returns `true` if the signature is successfully removed;
+   * otherwise returns `false`.
+   *
+   * **Effect of removal:** The resulting file is no longer Authenticode-signed and no longer
+   * carries the removed publisher and timestamp information. This operation does not delete the
+   * signing certificate from a Windows certificate store or alter the private key. Keep a backup
+   * when the original signed file must be retained.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link CodeSign.lastErrorText}.
+   */
+  removeSignature(path: string): void
+
+  /**
+   * Adds a Microsoft Authenticode signature to the Windows executable or DLL specified by `path`.
+   * The file is modified in place. `cert` supplies the code-signing certificate and must provide
+   * access to its associated private key. `options` supplies the signing configuration as JSON.
+   *
+   * Common `options` options include:
+   *
+   * JSON memberPurpose
+   *
+   * | `hashAlg` |  | Selects the file-digest algorithm, such as `sha256`. |
+   *
+   * | `timestampToken.enabled` |  | Enables an RFC 3161 timestamp token. |
+   *
+   * | `timestampToken.tsaUrl` |  | Specifies the timestamp authority URL. |
+   *
+   * | `timestampToken.requestTsaCert` | | Requests inclusion of the timestamp authority
+   * certificate. |
+   *
+   * | `timestampToken.hashAlg` | | Selects the timestamp-request digest algorithm, such as
+   * `sha256`. |
+   *
+   * ```
+   * {
+   *   "hashAlg": "sha256",
+   *   "timestampToken": {
+   *     "enabled": true,
+   *     "tsaUrl": "http://timestamp.example.com",
+   *     "requestTsaCert": true,
+   *     "hashAlg": "sha256"
+   *   }
+   * }
+   * ```
+   *
+   * **Timestamping is strongly recommended:** A trusted timestamp records that the signature
+   * existed while the code-signing certificate was valid. This normally allows the signature to
+   * continue validating after the signing certificate expires, provided the timestamp and
+   * certificate chains remain valid under the verifier's trust policy.
+   *
+   * This call blocks the JavaScript thread until Chilkat returns; from UI code prefer
+   * {@link CodeSign.addSignatureAsync}.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link CodeSign.lastErrorText}.
+   */
+  addSignature(path: string, cert: Cert, options: JsonObject): void
+
+  /**
+   * Asynchronous form of {@link CodeSign.addSignature}: the same call on a native worker thread,
+   * settling on the JavaScript thread. While it is pending, other calls on this object throw,
+   * except {@link CodeSign.abort} (which cancels it) and the {@link CodeSign.onPercentDone} /
+   * {@link CodeSign.onProgressInfo} callbacks, which report progress while it runs.
+   *
+   * The promise rejects with an Error if the call fails; the full log is in
+   * {@link CodeSign.lastErrorText}.
+   */
+  addSignatureAsync(path: string, cert: Cert, options: JsonObject): Promise<void>
+
+  /**
+   * Retrieves the X.509 signer certificate discovered by the most recent call to {@link
+   * CodeSign.verifySignature} on this `CodeSign` object. If the certificate is fully available,
+   * `cert` is loaded with it and the method returns `true`. Otherwise, the method returns `false`.
+   *
+   * The returned object contains the public certificate only; it does not provide the signer's
+   * private key. Call this method after `VerifySignature` and use the same `CodeSign` instance.
+   *
+   * **Certificate retrieval versus trust:** Successfully retrieving the signer certificate does not
+   * independently validate the signature or establish trust. Use the result of `VerifySignature`
+   * and the returned signature information when making a trust decision.
+   *
+   * @throws Error if the call fails (the message names the reason); the full log is in
+   * {@link CodeSign.lastErrorText}.
+   */
+  getSignerCert(cert: Cert): void
+
+  // ---- Events (ReactNativeGen_DESIGN.md §6) ----
+
+  /**
+   * Called with the percent completed (0..100) while a long-running method runs, when Chilkat
+   * can measure progress. Runs on the JavaScript thread, so it is only useful with the
+   * `...Async` methods (during a synchronous call the thread is busy and the events arrive
+   * after it returns). Assign `undefined` to remove.
+   */
+  onPercentDone?: (pctDone: number) => void
+
+  /**
+   * Called with a name/value pair of progress information while a long-running method runs
+   * (what is reported depends on the class and method). Runs on the JavaScript thread; see
+   * {@link CodeSign.onPercentDone}. Assign `undefined` to remove.
+   */
+  onProgressInfo?: (name: string, value: string) => void
+
+  /**
+   * Requests that the pending `...Async` call on this object stop at its next progress check.
+   * The promise then rejects with Chilkat's abort error. Chilkat checks at least every
+   * `heartbeatMs` milliseconds on the classes that have that property, so set it (e.g. 250)
+   * for a responsive cancel. Harmless when nothing is pending.
+   */
+  abort(): void
+}