Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Refine README. #447

Merged
merged 1 commit into from
Nov 4, 2024
Merged

Refine README. #447

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
667 changes: 34 additions & 633 deletions README.md
View file
Open in desktop

Large diffs are not rendered by default.

87 changes: 39 additions & 48 deletions packages/chacha20poly1305/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,40 +21,32 @@ Documentation: [jsr.io](https://jsr.io/@hpke/chacha20poly1305/doc) |
- [Node.js](#nodejs)
- [Deno](#deno)
- [Web Browsers](#web-browsers)
- [Cloudflare Workers](#cloudflare-workers)
- [Usage](#usage)
- [Contributing](#contributing)

## Installation

`@hpke/chacha20poly1305` need to be used with
[@hpke/core](https://github.com/dajiaji/hpke-js/blob/main/packages/core/README.md),
which can be installed in the same manner as desribed below.

### Node.js

Using npm:
You can install the package with npm, yarn or pnpm.

```sh
# Using npm:
npm install @hpke/chacha20poly1305
```

Using yarn:

```sh
yarn add @hpke/chacha20poly1305
pnpm install @hpke/chacha20poly1305
# Using jsr:
npx jsr add @hpke/chacha20poly1305
yarn dlx jsr add @hpke/chacha20poly1305
pnpm dlx jsr add @hpke/chacha20poly1305
```

### Deno

Starting from version 1.3.0, hpke-js packages are available from the JSR
registry. From this version onwards, please use JSR import instead of HTTPS
import in Deno.

**JSR imoprt (recommended on `>=1.3.0`):**

Add hpke-js packages using the commands below:

```sh
deno add @hpke/core
deno add @hpke/chacha20poly1305
```
The above manner can be used with other JavaScript runtimes that support npm,
such as Cloudflare Workers and Bun.

Then, you can use the module from code like this:

Expand All @@ -63,15 +55,12 @@ import { CipherSuite, DhkemP256HkdfSha256, HkdfSha256 } from "@hpke/core";
import { Chacha20Poly1305 } from "@hpke/chacha20poly1305";
```

**HTTPS imoprt (deprecated):**
### Deno

```ts
import {
CipherSuite,
DhkemP256HkdfSha256,
HkdfSha256,
} from "https://deno.land/x/hpke/core/mod.ts";
import { Chacha20Poly1305 } from "https://deno.land/x/hpke/x/chacha20poly1305/mod.ts";
For Deno, it is recommended to use the jsr.io registry.

```sh
deno add jsr:@hpke/chacha20poly1305
```

### Web Browsers
Expand All @@ -84,15 +73,23 @@ Using esm.sh:
```html
<!-- use a specific version -->
<script type="module">
import * as hpke from "https://esm.sh/@hpke/core@<SEMVER>";
import * as chacha20 from "https://esm.sh/@hpke/chacha20poly1305@<SEMVER>";
import {
CipherSuite,
DhkemP256HkdfSha256,
HkdfSha256,
} from "https://esm.sh/@hpke/core@<SEMVER>";
import { Chacha20Poly1305 } from "https://esm.sh/@hpke/chacha20poly1305@<SEMVER>";
// ...
</script>

<!-- use the latest stable version -->
<script type="module">
import * as hpke from "https://esm.sh/@hpke/core";
import * as chacha20 from "https://esm.sh/@hpke/chacha20poly1305";
import {
CipherSuite,
DhkemP256HkdfSha256,
HkdfSha256,
} from "https://esm.sh/@hpke/core";
import { Chacha20Poly1305 } from "https://esm.sh/@hpke/chacha20poly1305";
// ...
</script>
```
Expand All @@ -102,22 +99,16 @@ Using unpkg:
```html
<!-- use a specific version -->
<script type="module">
import * as hpke from "https://unpkg.com/@hpke/core@<SEMVER>/esm/mod.js";
import * as chacha20 from "https://unpkg.com/@hpke/chacha20poly1305@<SEMVER>/esm/mod.js";
import {
CipherSuite,
DhkemP256HkdfSha256,
HkdfSha256,
} from "https://unpkg.com/@hpke/core@<SEMVER>/esm/mod.js";
import { Chacha20Poly1305 } from "https://unpkg.com/@hpke/chacha20poly1305@<SEMVER>/esm/mod.js";
// ...
</script>
```

### Cloudflare Workers

```sh
git clone [email protected]:dajiaji/hpke-js.git
cd hpke-js/x/chacha20poly1305
npm install -g esbuild
deno task dnt
deno task minify > $YOUR_SRC_PATH/hpke-chacha20poly1305.js
```

## Usage

This section shows some typical usage examples.
Expand Down Expand Up @@ -207,7 +198,7 @@ try {
}
```

### Browsers
### Web Browsers

```html
<html>
Expand All @@ -219,8 +210,8 @@ try {
CipherSuite,
DhkemP256HkdfSha256,
HkdfSha256,
} from "https://esm.sh/@hpke/core@<SEMVER>";
import { Chacha20Poly1305 } from "https://esm.sh/@hpke/chacha20poly1305@<SEMVER>";
} from "https://esm.sh/@hpke/core";
import { Chacha20Poly1305 } from "https://esm.sh/@hpke/chacha20poly1305";

globalThis.doHpke = async () => {
try {
Expand Down
77 changes: 31 additions & 46 deletions packages/core/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,39 +21,31 @@ Documentation: [jsr.io](https://jsr.io/@hpke/core/doc) |
- [Node.js](#nodejs)
- [Deno](#deno)
- [Web Browsers](#web-browsers)
- [Cloudflare Workers](#cloudflare-workers)
- [Usage](#usage)
- [Contributing](#contributing)

## Installation

Where possible, it is recommended to use `@hpke/core` along with extension
modules (such as `@hpke/chacha20poly1305`) instead of `hpke-js`.

### Node.js

Using npm:
You can install the package with npm, yarn or pnpm.

```sh
# Using npm:
npm install @hpke/core
```

Using yarn:

```sh
yarn add @hpke/core
pnpm install @hpke/core
# Using jsr:
npx jsr add @hpke/core
yarn dlx jsr add @hpke/core
pnpm dlx jsr add @@hpke/core
```

### Deno

Starting from version 1.3.0, hpke-js packages are available from the JSR
registry. From this version onwards, please use JSR import instead of HTTPS
import in Deno.

**JSR imoprt (recommended on `>=1.3.0`):**

Add an hpke-js package using the commands below:

```sh
deno add @hpke/core
```
The above manner can be used with other JavaScript runtimes that support npm,
such as Cloudflare Workers and Bun.

Then, you can use the module from code like this:

Expand All @@ -66,15 +58,12 @@ import {
} from "@hpke/core";
```

**HTTPS imoprt (deprecated):**
### Deno

For Deno, it is recommended to use the jsr.io registry.

```ts
import {
Aes128Gcm,
CipherSuite,
DhkemP256HkdfSha256,
HkdfSha256,
} from "https://deno.land/x/hpke/core/mod.ts";
```sh
deno add jsr:@hpke/core
```

### Web Browsers
Expand All @@ -87,13 +76,23 @@ Using esm.sh:
```html
<!-- use a specific version -->
<script type="module">
import * as hpke from "https://esm.sh/@hpke/core@<SEMVER>";
import {
Aes128Gcm,
CipherSuite,
DhkemP256HkdfSha256,
HkdfSha256,
} from "https://esm.sh/@hpke/core@<SEMVER>";
// ...
</script>

<!-- use the latest stable version -->
<script type="module">
import * as hpke from "https://esm.sh/@hpke/core";
import {
Aes128Gcm,
CipherSuite,
DhkemP256HkdfSha256,
HkdfSha256,
} from "https://esm.sh/@hpke/core";
// ...
</script>
```
Expand All @@ -108,16 +107,6 @@ Using unpkg:
</script>
```

### Cloudflare Workers

```sh
git clone [email protected]:dajiaji/hpke-js.git
cd hpke-js/core
npm install -g esbuild
deno task dnt
deno task minify > $YOUR_SRC_PATH/hpke-core.js
```

## Usage

This section shows some typical usage examples.
Expand All @@ -131,9 +120,6 @@ import {
DhkemP256HkdfSha256,
HkdfSha256,
} from "@hpke/core";
// const {
// Aes128Gcm, CipherSuite, DhkemP256HkdfSha256, HkdfSha256,
// } = require("@hpke/core");

async function doHpke() {
// setup
Expand Down Expand Up @@ -217,20 +203,19 @@ try {
}
```

### Browsers
### Web Browsers

```html
<html>
<head></head>
<body>
<script type="module">
// import * as hpke from "https://esm.sh/hpke-js@<SEMVER>";
import {
Aes128Gcm,
CipherSuite,
DhkemP256HkdfSha256,
HkdfSha256,
} from "https://esm.sh/@hpke/core@<SEMVER>";
} from "https://esm.sh/@hpke/core";

globalThis.doHpke = async () => {
const suite = new CipherSuite({
Expand Down
Loading
Loading