pack-crx 1.0.1 → 1.1.0

package/README.md

@@ -16,15 +16,15 @@ import { serve, type ServeOptions } from "bun";
 import { constants, writeFile } from "node:fs/promises";
 
 const {
-    crx,
-    id: crxId,
-    manifest,
-    rsa
+  crx,
+  id: crxId,
+  manifest,
+  rsa,
 } = await pack({
-    contents: "./extension", // path to extension root
-    privateKey: "./key.pem", // path to key (if it doesn't exist, that's fine)
-    crx: null,
-    id: null
+  contents: "./extension", // path to extension root
+  privateKey: "./key.pem", // path to key (if it doesn't exist, that's fine)
+  crx: null,
+  id: null,
 });
 
 // Write the CRX
@@ -32,25 +32,35 @@ await writeFile("./extension.crx", crx);
 
 // Write the private key unless it already exists
 try {
-await writeFile("./key.pem", rsa.exportKey("pkcs8-private-pem"), {flag: constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY});
+  await writeFile("./key.pem", rsa.exportKey("pkcs8-private-pem"), {
+    flag: constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY,
+  });
 } catch (e) {}
 
 let updateXML: string;
 
 // Serve the extension (optional)
 const server = serve({
-    fetch(request, server) {
-        const url = new URL(request.url);
-        if (url.pathname.startsWith("/updates.xml")) {
-            updateXML ??= generateUpdateXML(crxId, server.url.toString() + "extension.crx", manifest.version);
-            return new Response(updateXML, {headers: {"Content-Type": "application/xml"}});
-        } else if (url.pathname.startsWith("/extension.crx")) {
-            return new Response(crx, {headers: {"Content-Type": "application/x-chrome-extension"}});
-        }
-        return new Response(undefined, {status: 404, statusText: "Not Found"});
-    },
-    port: 3000,
-    hostname: "localhost"
+  fetch(request, server) {
+    const url = new URL(request.url);
+    if (url.pathname.startsWith("/updates.xml")) {
+      updateXML ??= generateUpdateXML(
+        crxId,
+        server.url.toString() + "extension.crx",
+        manifest.version,
+      );
+      return new Response(updateXML, {
+        headers: { "Content-Type": "application/xml" },
+      });
+    } else if (url.pathname.startsWith("/extension.crx")) {
+      return new Response(crx, {
+        headers: { "Content-Type": "application/x-chrome-extension" },
+      });
+    }
+    return new Response(undefined, { status: 404, statusText: "Not Found" });
+  },
+  port: 3000,
+  hostname: "localhost",
 } as ServeOptions);
 
 console.log(`Server opened at ${server.url}`);
@@ -69,7 +79,7 @@ The easiest way to use this package is through the default export, `pack`.
 <!-- It is highly recommended to turn off line wrapping while editing this table -->
 
 | Name               | Type (also can be `undefined`)   | Description                                                                                           | Auto-generation notes                                                                                            |
-|--------------------|----------------------------------|-------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------|
+| ------------------ | -------------------------------- | ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
 | `contents`         | `Uint8Array` or `string`         | The ZIP archive of the contents of the extension, or a path to the folder containing the extension.   | Cannot be auto-generated                                                                                         |
 | `privateKey`       | `Uint8Array`, `string` or `null` | The private key for the extension, or a path to it.                                                   | If loading from a string, the contents should be in pkcs8-pem if the path ends in `.pem`.                        |
 | `keySize`          | `number`                         | The size of key to generate, if needed.                                                               | No dependencies, defaults to 4096                                                                                |
@@ -92,12 +102,16 @@ If `privateKey` or `publicKey` are strings, `pack` will load the file at each pa
 
 `pack` always returns a `Promise`, even if all of the operations inside are synchronous.
 
-However, the return result is the same object as the input - just with the properties modified - so if you *really* want synchronous operations, you can keep a reference to the input object, call the function, and access the synchronous results from that object. Just make sure you don't set `privateKey` or `manifest` to `null` or `contents` to a string, otherwise some of your values might not arrive synchronously.
+However, the return result is the same object as the input - just with the properties modified - so if you _really_ want synchronous operations, you can keep a reference to the input object, call the function, and access the synchronous results from that object. Just make sure you don't set `privateKey` or `manifest` to `null` or `contents` to a string, otherwise some of your values might not arrive synchronously.
 
 ### packCrx3
 
 ```ts
-function packCrx3(privateKey: Uint8Array, publicKey: Uint8Array, contents: Uint8Array): Uint8Array
+function packCrx3(
+  privateKey: Uint8Array,
+  publicKey: Uint8Array,
+  contents: Uint8Array,
+): Uint8Array;
 ```
 
 Pack a CRX3 extension.
@@ -111,7 +125,11 @@ Pack a CRX3 extension.
 ### packCrx2 (deprecated)
 
 ```ts
-function packCrx2(privateKey: Uint8Array, publicKey: Uint8Array, contents: Uint8Array): Uint8Array
+function packCrx2(
+  privateKey: Uint8Array,
+  publicKey: Uint8Array,
+  contents: Uint8Array,
+): Uint8Array;
 ```
 
 Pack a CRX2 extension. Chrome stopped supporting these entirely in version 73.0.3683, which released in October of 2017.
@@ -125,7 +143,7 @@ Pack a CRX2 extension. Chrome stopped supporting these entirely in version 73.0.
 ### generateCrxId
 
 ```ts
-function generateCrxId(publicKey: Uint8Array): string
+function generateCrxId(publicKey: Uint8Array): string;
 ```
 
 Generate an extension's ID (32 characters, a-p) from its public key.
@@ -137,21 +155,29 @@ Generate an extension's ID (32 characters, a-p) from its public key.
 ### packContents
 
 ```ts
-function packContents(where: string): Promise<{contents: Uint8Array, manifest: ChromeManifest}>
+function packContents(
+  where: string,
+): Promise<{ contents: Uint8Array; manifest: ChromeManifest }>;
 ```
 
 Load a directory from the filesystem into a ZIP archive, using the node:fs API.
 
 (param) `where` (`string`) - The path to the directory.
 
-(returns) `object` 
-* `contents` (`Uint8Array`) - The ZIP-encoded data.
-* `manifest` (`ChromeManifest`) - The manifest for the extension, parsed as JSON.
+(returns) `object`
+
+- `contents` (`Uint8Array`) - The ZIP-encoded data.
+- `manifest` (`ChromeManifest`) - The manifest for the extension, parsed as JSON.
 
 ### generateUpdateXML
 
 ```ts
-function generateUpdateXML(crxId: string, url: string, version: string, minChromeVersion?: string): string
+function generateUpdateXML(
+  crxId: string,
+  url: string,
+  version: string,
+  minChromeVersion?: string,
+): string;
 ```
 
 Generate the updates XML file for [serving an extension yourself](https://developer.chrome.com/docs/extensions/how-to/distribute/host-on-linux).
@@ -166,7 +192,7 @@ Generate the updates XML file for [serving an extension yourself](https://develo
 ### unpack
 
 ```ts
-function unpack(crx: Uint8Array): Uint8Array
+function unpack(crx: Uint8Array): Uint8Array;
 ```
 
 Unpack a CRX file and extract its contents as ZIP data.
@@ -174,10 +200,11 @@ Unpack a CRX file and extract its contents as ZIP data.
 (param) `crx` (`Uint8Array`) - The CRX to be unpacked.
 
 (returns) `object`
+
 - `archive` (`Uint8Array`) - The ZIP data.
 - `crxVersion` (`3`) - The CRX format version.
 - `header` (`CrxFileHeader`) - The header for the CRX file, for signatures and things.
-OR
+  OR
 - `archive` (`Uint8Array`) - The ZIP data.
 - `crxVersion` (`2`) - The CRX format version.
 - `key` (`Uint8Array`) - The extension's public key.
@@ -188,10 +215,10 @@ OR
 The following functions are self-explanatory:
 
 ```ts
-function generatePrivateKey(bits?: number): Uint8Array
-function generatePublicKey(privateKey: Uint8Array): Uint8Array
-function convertToPem(key: Uint8Array, type: "private" | "public"): string
-function convertFromPem(key: string, type: "private" | "public"): Uint8Array
+function generatePrivateKey(bits?: number): Uint8Array;
+function generatePublicKey(privateKey: Uint8Array): Uint8Array;
+function convertToPem(key: Uint8Array, type: "private" | "public"): string;
+function convertFromPem(key: string, type: "private" | "public"): Uint8Array;
 ```
 
-However, they all create new NodeRSA instances which are immediately discarded, so it is recommended to make your own RSA instance (or use the one from `pack`) and its methods to export/import keys.
+However, they all create new NodeRSA instances which are immediately discarded, so it is recommended to make your own RSA instance (or use the one from `pack`) and its methods to export/import keys.

package/build/crx3.pb.d.ts

@@ -0,0 +1,15 @@
+export namespace CrxFileHeader {
+    function read(pbf: any, end: any): any;
+    function _readField(tag: any, obj: any, pbf: any): void;
+    function write(obj: any, pbf: any): void;
+}
+export namespace AsymmetricKeyProof {
+    function read(pbf: any, end: any): any;
+    function _readField(tag: any, obj: any, pbf: any): void;
+    function write(obj: any, pbf: any): void;
+}
+export namespace SignedData {
+    function read(pbf: any, end: any): any;
+    function _readField(tag: any, obj: any, pbf: any): void;
+    function write(obj: any, pbf: any): void;
+}

package/build/index.d.ts

@@ -0,0 +1,354 @@
+import RSA from "node-rsa";
+interface ChromeBaseManifest {
+    manifest_version: number;
+    name: string;
+    version: string;
+    description?: string;
+    icons?: {
+        [x: `${number}`]: string;
+    };
+    author?: string;
+    background?: {
+        service_worker?: string;
+        type?: "module";
+    };
+    chrome_settings_overrides?: {
+        alternate_urls?: string[];
+        encoding?: string;
+        favicon_url?: string;
+        homepage?: string;
+        image_url?: string;
+        image_url_post_params?: string;
+        is_default?: boolean;
+        keyword?: string;
+        name?: string;
+        prepopulated_id?: number;
+        search_provider?: object;
+        search_url?: string;
+        search_url_post_params?: string;
+        startup_pages?: string[];
+        suggest_url?: string;
+        suggest_url_post_params?: string;
+    };
+    chrome_url_overrides?: {
+        bookmarks?: string;
+        history?: string;
+        newtab?: string;
+    };
+    commands?: {
+        [x: string]: {
+            description: string;
+            suggested_key?: string;
+        };
+    };
+    content_scripts?: {
+        matches: string[];
+        css?: string[];
+        js?: string[];
+        run_at?: "document_start" | "document_end" | "document_idle";
+        match_about_blank?: boolean;
+        match_origin_as_fallback?: boolean;
+        world?: "ISOLATED" | "MAIN";
+    }[];
+    content_security_policy?: {
+        extension_pages?: string;
+        sandbox?: string;
+    };
+    cross_origin_embedder_policy?: string;
+    cross_origin_opener_policy?: string;
+    declarative_net_request?: {
+        rule_resources?: {
+            id: string;
+            enabled: boolean;
+            path: string;
+        }[];
+    };
+    default_locale?: string;
+    devtools_page?: string;
+    export?: {
+        allowlist?: string[];
+    };
+    externally_connectable?: {
+        ids?: string[];
+        matches?: string[];
+        accepts_tls_channel_id?: boolean;
+    };
+    homepage_url?: string;
+    host_permissions?: string[];
+    import?: {
+        id: string;
+        minimum_version?: string;
+    }[];
+    incognito?: "spanning" | "split" | "not_allowed";
+    key?: string;
+    minimum_chrome_version?: string;
+    oauth2?: {
+        client_id: string;
+        scopes: string[];
+    };
+    omnibox?: {
+        keyword?: string;
+    };
+    optional_host_permissions?: string[];
+    optional_permissions?: string[];
+    options_page?: string;
+    options_ui?: {
+        page: string;
+        open_in_tab?: boolean;
+    };
+    permissions?: string[];
+    requirements?: {
+        [x: string]: {
+            features: string[];
+        };
+    };
+    sandbox?: {
+        pages: string[];
+    };
+    short_name?: string;
+    side_panel?: string;
+    storage?: {
+        managed_schema?: string;
+    };
+    tts_engine?: {
+        voices?: {
+            voice_name: string;
+            lang?: string;
+            event_types?: ("start" | "word" | "sentence" | "marker" | "end" | "error")[];
+        }[];
+    };
+    update_url?: string;
+    version_name?: string;
+    web_accessible_resources?: ({
+        resources: string[];
+    } & ({
+        matches: string[];
+    } | {
+        extension_ids: string[];
+    }))[];
+    file_browser_handlers?: {
+        id: string;
+        default_title: string;
+        file_filters: string[];
+    }[];
+    file_handlers?: {
+        action: string;
+        name: string;
+        accept: {
+            [x: string]: string[];
+        };
+        launch_type?: "single-client" | "multiple-clients";
+    }[];
+    file_system_provider_capabilities?: {
+        configurable?: boolean;
+        multiple_mounts?: boolean;
+        watchable?: boolean;
+        source: "file" | "device" | "network";
+    };
+    input_components?: {
+        name: string;
+        id?: string;
+        language?: string | string[];
+        layouts?: string | string[];
+        input_view?: string;
+        options_page?: string;
+    }[];
+}
+export type ChromeMV2Manifest = ChromeBaseManifest & {
+    manifest_version: 2;
+    browser_action?: {
+        default_icon?: {
+            [x: `${number}`]: string;
+        };
+        default_title?: string;
+        default_popup?: string;
+    };
+    page_action?: {
+        default_icon?: {
+            [x: `${number}`]: string;
+        };
+        default_title?: string;
+        default_popup?: string;
+    };
+};
+export type ChromeMV3Manifest = ChromeBaseManifest & {
+    manifest_version: 3;
+    action?: {
+        default_icon?: {
+            [x: `${number}`]: string;
+        };
+        default_title?: string;
+        default_popup?: string;
+    };
+};
+export type ChromeManifest = ChromeMV2Manifest | ChromeMV3Manifest;
+export interface CrxFileHeader {
+    sha256_with_rsa?: AsymmetricKeyProof[];
+    sha256_with_ecdsa?: AsymmetricKeyProof[];
+    signed_header_data?: Uint8Array;
+}
+export interface AsymmetricKeyProof {
+    public_key?: Uint8Array;
+    signature?: Uint8Array;
+}
+/**
+ * Pack a CRX2 extension. Chrome stopped supporting these entirely in version 73.0.3683, which released in October of 2017.
+ *
+ * @param privateKey The extension's private key.
+ * @param publicKey The extension's public key.
+ * @param contents The zipped contents of the extension. This should contain a `manifest.json` file directly inside it, but we don't validate that in this function.
+ *
+ * @returns The contents of the packaged extension.
+ *
+ * @deprecated
+ */
+export declare function packCrx2(privateKey: Uint8Array, publicKey: Uint8Array, contents: Uint8Array, rsa?: RSA): Uint8Array;
+/**
+ * Pack a CRX3 extension.
+ *
+ * @param privateKey The extension's private key.
+ * @param publicKey The extension's public key.
+ * @param contents The zipped contents of the extension. This should contain a `manifest.json` file directly inside it, but we don't validate that in this function.
+ *
+ * @returns The contents of the packaged extension.
+ */
+export declare function packCrx3(privateKey: Uint8Array, publicKey: Uint8Array, contents: Uint8Array, rsa?: RSA): Uint8Array;
+/**
+ * Generate an extension's ID (32 characters, a-p) from its public key.
+ *
+ * @param publicKey The public key of the extension.
+ *
+ * @returns The generated extension ID.
+ */
+export declare function generateCrxId(publicKey: Uint8Array): string;
+/**
+ * Load a directory from the filesystem into a ZIP archive, using the node:fs API.
+ *
+ * @param where The path to the directory.
+ */
+export declare function packContents(where: string): Promise<{
+    /** The ZIP-encoded data. */
+    contents: Uint8Array;
+    /** The manifest for the extension, parsed as JSON. */
+    manifest: ChromeManifest;
+}>;
+/**
+ * Generate the updates XML file for [serving an extension yourself](https://developer.chrome.com/docs/extensions/how-to/distribute/host-on-linux).
+ *
+ * @param crxId The extension's ID.
+ * @param url The URL where the extension's CRX file will be hosted.
+ * @param version The extension's version.
+ * @param minChromeVersion The minimum Chrome version that the extension can be installed on.
+ *
+ * @returns The updates XML text
+ */
+export declare function generateUpdateXML(crxId: string, url: string, version: string, minChromeVersion?: string): string;
+export declare function generatePrivateKey(bits?: number): Uint8Array;
+export declare function generatePublicKey(privateKey: Uint8Array): Uint8Array;
+export declare function convertToPem(key: Uint8Array, type: "private" | "public"): string;
+export declare function convertFromPem(key: string, type: "private" | "public"): Uint8Array;
+/**
+ * Unpack a CRX file and extract its contents as ZIP data.
+ *
+ * @param crx The CRX to be unpacked.
+ */
+export declare function unpack(crx: Uint8Array): {
+    /** The ZIP data. */
+    archive: Uint8Array;
+    /** The CRX format version. */
+    crxVersion: 2;
+    /** The extension's public key. */
+    key: Uint8Array;
+    /** The signature over the contents of the extension. */
+    sign: Uint8Array;
+} | {
+    /** The ZIP data. */
+    archive: Uint8Array;
+    /** The CRX format version. */
+    crxVersion: 3;
+    /** The header for the CRX file, for signatures and things. */
+    header: CrxFileHeader;
+};
+export interface PackInput {
+    /** The ZIP archive of the contents of the extension, or a path to the folder containing the extension. */
+    contents?: Uint8Array | string;
+    /** The private key for the extension, or a path to it. */
+    privateKey?: Uint8Array | string | null;
+    /** The size of key to generate, if needed. */
+    keySize?: number;
+    /** The public key for the extension, or a path to it. */
+    publicKey?: Uint8Array | string | null;
+    /** The instance of NodeRSA to use. */
+    rsa?: RSA;
+    /** The extension's ID. */
+    id?: string | null;
+    /** The outputted CRX file. */
+    crx?: Uint8Array | null;
+    /** The CRX format version to use. Defaults to 3. */
+    crxVersion?: number;
+    /** The URL to where the CRX file (not the updates XML) will be hosted. */
+    crxUrl?: string;
+    /** The [updates XML file](https://developer.chrome.com/docs/extensions/how-to/distribute/host-on-linux). */
+    updateXML?: string | null;
+    /** The extension's version. */
+    extVersion?: string | null;
+    /** The minimum Chrome version the extension requires. */
+    minChromeVersion?: string | null;
+    /** The extension's [manifest](https://developer.chrome.com/docs/extensions/reference/manifest). */
+    manifest?: ChromeManifest | null;
+}
+type SetKeys<A extends object, B extends object> = {
+    [x in keyof A | keyof B]: x extends keyof B ? unknown extends B[x] ? x extends keyof A ? A[x] : never : B[x] : x extends keyof A ? A[x] : never;
+};
+export type TransformPack<I extends PackInput> = I["privateKey"] extends string ? TransformPack<SetKeys<I, {
+    privateKey: Uint8Array | undefined;
+    rsa: RSA;
+}>> : I["publicKey"] extends string ? TransformPack<SetKeys<I, {
+    publicKey: Uint8Array | undefined;
+}>> : I["updateXML"] extends null ? undefined extends I["crxUrl"] ? never : TransformPack<SetKeys<I, {
+    updateXML: string;
+    id: undefined extends I["id"] ? null : I["id"];
+    extVersion: undefined extends I["extVersion"] ? null : I["extVersion"];
+    minChromeVersion: undefined extends I["minChromeVersion"] ? null : I["minChromeVersion"];
+}>> : I["extVersion"] extends null ? TransformPack<SetKeys<I, {
+    extVersion: string;
+    manifest: undefined extends I["manifest"] ? null : I["manifest"];
+}>> : I["minChromeVersion"] extends null ? TransformPack<SetKeys<I, {
+    minChromeVersion: string | undefined;
+    manifest: undefined extends I["manifest"] ? null : I["manifest"];
+}>> : I["manifest"] extends null ? undefined extends I["contents"] ? never : Uint8Array extends I["contents"] ? never : TransformPack<SetKeys<I, {
+    manifest: ChromeManifest;
+}>> : I["crx"] extends null ? undefined extends I["contents"] ? never : TransformPack<SetKeys<I, {
+    crx: Uint8Array;
+    privateKey: undefined extends I["privateKey"] ? null : I["privateKey"];
+    publicKey: undefined extends I["publicKey"] ? null : I["publicKey"];
+}>> : I["id"] extends null ? TransformPack<SetKeys<I, {
+    id: string;
+    publicKey: undefined extends I["publicKey"] ? null : I["publicKey"];
+}>> : I["publicKey"] extends null ? TransformPack<SetKeys<I, {
+    publicKey: Uint8Array;
+    privateKey: undefined extends I["privateKey"] ? null : I["privateKey"];
+}>> : I["privateKey"] extends null ? TransformPack<SetKeys<I, {
+    privateKey: Uint8Array;
+    rsa: RSA;
+}>> : I["contents"] extends string ? TransformPack<SetKeys<I, {
+    contents: Uint8Array;
+    manifest: ChromeManifest;
+}>> : I;
+/**
+ * Use the entirety of this API in one function.
+ *
+ * @param options An object containing input parameters.
+ *
+ * If `null` is given for a property, then the function will generate a value for it based on the other properties.
+ *
+ * If a property requires another but that property is not requested (with `null`), then it is generated and given anyways.
+ *
+ * If `privateKey` or `publicKey` are strings, `pack` will load the file at each path as a key. If the extension is `.pem`, they are loaded as pkcs8-pem and converted to pkcs8-der.
+ *
+ * `pack` always returns a `Promise`, even if all of the operations inside are synchronous.
+ *
+ * However, the return result is the same object as the input - just with the properties modified - so if you *really* want synchronous operations, you can keep a reference to the input object, call the function, and access the synchronous results from that object. Just make sure you don't set `privateKey` or `manifest` to `null` or `contents` to a string, otherwise some of your values might not arrive synchronously.
+ */
+export declare function pack<I extends PackInput>(options: I): Promise<TransformPack<I>>;
+export default pack;