signing-enclave/README.md

A code signing and notarization tool for macOS and Windows applications. Uses Azure Key Vault for secret and certificate management.

# signing-enclave

A code signing and notarization tool for macOS and Windows
applications. Uses Azure Key Vault for secret and certificate management.

## Features

- Watch folders for new files to process
- Code signing for macOS and Windows applications
- Notarization for macOS applications
- Secure secret and certificate management using Azure Key Vault
- Support for various certificate types (Mac, Mac Installer, MAS Development, MAS
  Distribution, MAS Installer, Windows)
- Flexible command-line interface

## Installation

```bash
npm install -g signing-enclave
```

## How it works

The **priviliged process** can read certificate and secrets from Azure KeyVault.
The **unpriviledged process** has no direct access to the KeyVault and instead
communicates with the privileged process via adding request files to a
folder that the privileged process is watching.

1. The priviledged watcher will listen for `x.request.json` files in the watched folder. When it finds one, it will process the request on behalf of the unprivileged process.
2. The unprivileged process can request certificates and secrets. It can also place an application to be signed/notarized in the same folder as the request file.
3. The privileged process will log the status of the request to a `x.receipt.json` file.
4. The unprivileged process can check the status of the request by reading the receipt file. It is constantly polling the receipt file until it is processed.
5. The privileged process will write the desired output file to the same folder as the request/receipt files when completed.
6. The unprivileged process can then read the output file.

![Infrastructure diagram](./signing-enclave.png)

## Usage

### Basic Command

```bash
signing-enclave watch -f /path/to/watch/folder
```

### Options

- `-f, --folder <path>`: Path to the folder to watch (default: "./watched_folder")
- `--mac-cert <name>`: Name of the Mac certificate to use in Azure KeyVault
- `--mac-notarize <json>`: JSON object containing appleId, teamId, and the name of
  the appSpecificPassword reference in Azure KeyVault
- `--mac-installer-cert <name>`: Name of the Mac installer certificate to use in
  Azure KeyVault
- `--mas-development-cert <name>`: Name of the Mac App Store development certificate
  to use in Azure KeyVault
- `--mas-distribution-cert <name>`: Name of the Mac App Store distribution
  certificate to use in Azure KeyVault
- `--mas-installer-cert <name>`: Name of the Mac App Store installer certificate to
  use in Azure KeyVault
- `--windows-cert <name>`: Name of the Windows certificate to use in Azure KeyVault
- `--secrets <json>`: JSON object containing the secrets to use in Azure KeyVault

### Example command

```bash
signing-enclave watch -f /path/to/watch/folder --mac-cert "azure-keyvault-reference-to-cert" --mac-notarize '{"appleId": "appleId", "teamId": "teamId", "$appSpecificPassword": "azure-keyvault-reference-to-secret"}' --secrets='[{"GITHUB_PAT":"5072cc0c-3de0-4b88-be27-b054bdbbf8dd"}]'
```

### Environment Variables

- `AZURE_KEY_VAULT_CREDENTIALS`: Base64 encoded JSON string containing Azure Key
  Vault credentials (url, id, secret, tenantId)

## Request File Format

The watcher looks for `.request.json` files in the watched folder. The request file
should have the following format:

```js
{
  "path": "path/to/file/to/process",
  "actions": ["sign", "notarize", "getCert", "getSecret"],
  "secretName": "optional_secret_name",
  "platform": "mac" | "mas" | "macPkg" | "win",
  "type": "distribution" | "development" | "installer",
  "provisioningProfile": "optional_provisioning_profile_path"
}
```

## Receipt File

After processing a request, a `.receipt.json` file is created with information about
the processing status and any errors encountered.

## Examples

1. Request a secret:

```ts
import { requestSecret } from "signing-enclave";

const secret = await requestSecret({
  secretName: "GITHUBPAT",
});
```

2. Request a certificate:

```ts
import { requestCert } from "signing-enclave";

const cert = await requestCert({
  platform: "mac",
});
```

3. Request notarization:

```ts
import { requestNotarize } from "signing-enclave";

const cert = await requestNotarize({
  path: "/path/to/app.app",
});
```

## Development

1. Clone the repository
2. Install dependencies: `npm install`
3. Build the project: `npm run build`
4. Run tests: `npm test`

## License

MIT