simple-hpke 0.0.8

package/LICENSE

@@ -0,0 +1,99 @@
+# Big Time Public License
+
+Version 2.0.2
+
+<https://bigtimelicense.com/versions/2.0.2>
+
+## Purpose
+
+These terms let you use and share this software for noncommercial purposes and in small business for free, while also guaranteeing that paid licenses for big businesses will be available on fair, reasonable, and nondiscriminatory terms.
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Noncommercial Purposes
+
+You may use the software for any noncommercial purpose.
+
+## Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, count as use for noncommercial purposes.
+
+## Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution counts as use for noncommercial purposes, regardless of the source of funding or obligations resulting from the funding.
+
+## Small Business
+
+You may use the software for the benefit of your company if it meets all these criteria:
+
+1.  had fewer than 20 total individuals working as employees and independent contractors at all times during the last tax year
+
+2.  earned less than $1,000,000 total revenue in the last tax year
+
+3.  received less than $1,000,000 total debt, equity, and other investment in the last five tax years, counting investment in predecessor companies that reorganized into, merged with, or spun out your company
+
+All dollar figures are United States dollars as of 2019.  Adjust for them inflation according to the United States Bureau of Labor Statistics' consumer price index for all urban consumers, United States city average, for all items, not seasonally adjusted, with 1982–1984=100 reference base.
+
+## Big Business
+
+You may use the software for the benefit of your company:
+
+1.  for 128 days after your company stops qualifying under [Small Business](#small-business)
+
+2.  indefinitely, if the licensor or their legal successor does not offer fair, reasonable, and nondiscriminatory terms for a commercial license for the software within 32 days of [written request](#how-to-request) and negotiate in good faith to conclude a deal
+
+## How to Request
+
+If this software includes an address for the licensor or an agent of the licensor in a standard place, such as in documentation, software package metadata, or an "about" page or screen, try to request a fair commercial license at that address.  If this package includes both online and offline addresses, try online before offline.  If you can't deliver a request that way, or this software doesn't include any addressees, spend one hour online researching an address, recording all your searches and inquiries as you go, and try any addresses that you find.  If you can't find any addresses, or if those addresses also fail, that counts as failure to offer a fair commercial license by the licensor under [Big Business](#big-business).
+
+## Fair, Reasonable, and Nondiscriminatory Terms
+
+Fair, reasonable, and nondiscriminatory terms may license the software perpetually or for a term, and may or may not cover new versions of the software.  If the licensor advertises license terms and a pricing structure for generally available commercial licenses, the licensor proposes license terms and a price as advertised, and a customer not affiliated with the licensor has bought a commercial license for the software on substantially equivalent terms in the past year, the proposal is fair, reasonable, and nondiscriminatory.
+
+## Copyright License
+
+The licensor grants you a copyright license to do everything with the software that would otherwise infringe the licensor's copyright in it for any purpose allowed by these terms.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software.  For example:
+
+> Required Notice: Copyright Nick Thomas (https://nichoth.com)
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else.  These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice.  Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization.  **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise.  Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

package/README.md

@@ -0,0 +1,312 @@
+# Simple HPKE
+[![tests](https://img.shields.io/github/actions/workflow/status/nichoth/simple-hpke/nodejs.yml?style=flat-square)](https://github.com/nichoth/simple-hpke/actions/workflows/nodejs.yml)
+[![types](https://img.shields.io/npm/types/@substrate-system/simple-hpke?style=flat-square)](README.md)
+[![module](https://img.shields.io/badge/module-ESM%2FCJS-blue?style=flat-square)](README.md)
+[![semantic versioning](https://img.shields.io/badge/semver-2.0.0-blue?logo=semver&style=flat-square)](https://semver.org/)
+[![Common Changelog](https://nichoth.github.io/badge/common-changelog.svg)](./CHANGELOG.md)
+[![install size](https://flat.badgen.net/packagephobia/install/@substrate-system/simple-hpke)](https://packagephobia.com/result?p=@substrate-system/simple-hpke)
+[![gzip size](https://flat.badgen.net/bundlephobia/minzip/@substrate-system/simple-hpke)](https://bundlephobia.com/package/@substrate-system/simple-hpke)
+[![license](https://img.shields.io/badge/license-Big_Time-blue?style=flat-square)](LICENSE)
+
+
+Hybrid Public Key Encryption
+([RFC 9180](https://www.rfc-editor.org/rfc/rfc9180.html))
+
+1 dependency -- `uint8arrays`.
+
+<details><summary><h2>Contents</h2></summary>
+
+<!-- toc -->
+
+- [Install](#install)
+- [Example](#example)
+  * [Key Wrapping](#key-wrapping)
+  * [Hybrid Encryption](#hybrid-encryption)
+    + [Encrypt / Decrypt](#encrypt--decrypt)
+      - [`encrypt`](#encrypt)
+      - [Encrypt to a string](#encrypt-to-a-string)
+      - [`decrypt`](#decrypt)
+      - [`decrypt.asString`](#decryptasstring)
+      - [`decrypt.fromString`](#decryptfromstring)
+- [Modules](#modules)
+  * [ESM](#esm)
+  * [Common JS](#common-js)
+  * [pre-built JS](#pre-built-js)
+    + [copy](#copy)
+    + [HTML](#html)
+
+<!-- tocstop -->
+
+</details>
+
+## Install
+
+```sh
+npm i -S @substrate-system/simple-hpke
+```
+
+## Example
+
+Wrap an AES key, or encrypt a message.
+
+### Key Wrapping
+
+Encrypt an AES key to yourself, then recover it later.
+
+```ts
+import { seal, open } from '@substrate-system/simple-hpke'
+
+// An X25519 keypair. The private key can be non-extractable.
+// HPKE needs only `deriveBits`.
+const keypair = await crypto.subtle.generateKey(
+    { name: 'X25519' },
+    false,  // extractable
+    ['deriveBits']
+)
+
+// create a new AES key, and encrypt it to your public key.
+const { wrapped, key } = await seal(keypair)
+
+// Or wrap an existing AES key. The supplied key must be extractable.
+const aesKey = await crypto.subtle.generateKey(
+    { name: 'AES-GCM', length: 256 },
+    true,  // extractable
+    ['encrypt', 'decrypt']
+)
+
+// pass in a key. The return value is just the wrapped key
+const { wrapped } = await seal(keypair, aesKey)
+
+// Later, recover the same key with your private key.
+const recoveredKey = await open(keypair, wrapped)
+```
+
+See [docs/README.md](./docs/README.md) for the full API and rationale.
+
+### Hybrid Encryption
+
+Seal a key, then use it to encrypt a message with AES-GCM.
+The wrapped key is concattenated with the cipher text, along with the
+IV. The recipient uses their private key to open the AES key and decrypt
+the message.
+
+```ts
+import { seal, open } from '@substrate-system/simple-hpke'
+
+const recipient = await crypto.subtle.generateKey(
+    { name: 'X25519' },
+    false,  // not extractable
+    ['deriveBits']
+)
+
+// Create and seal a fresh AES-GCM key, and encrypt a message with it.
+const { wrapped, key } = await seal(recipient)
+const iv = crypto.getRandomValues(new Uint8Array(12))
+const ciphertext = await crypto.subtle.encrypt(
+    { name: 'AES-GCM', iv },
+    key,
+    new TextEncoder().encode('attack at dawn')
+)
+
+// Send `wrapped`, `iv`, and `ciphertext` together. `wrapped` is a fixed
+// 80 bytes for this suite, and the AES-GCM IV is 12 bytes, so the recipient
+// can slice the payload back apart at known offsets.
+const ciphertext = new Uint8Array(ciphertext)
+const message = new Uint8Array(wrapped.length + iv.length + ciphertext.length)
+message.set(wrapped, 0)
+message.set(iv, wrapped.length)
+message.set(ciphertext, wrapped.length + iv.length)
+
+// On the other side, split the payload back into its parts.
+const wrapped2 = message.subarray(0, 80)
+const iv2 = message.subarray(80, 80 + 12)
+const ciphertext2 = message.subarray(80 + 12)
+
+// Recover the key, then decrypt the message.
+const recovered = await open(recipient, wrapped2)
+const plaintext = await crypto.subtle.decrypt(
+    { name: 'AES-GCM', iv: iv2 },
+    recovered,
+    ciphertext2
+)
+
+new TextDecoder().decode(plaintext)  // => 'attack at dawn'
+```
+
+#### Encrypt / Decrypt
+
+So that was a lot of code to encrypt and decrypt a message...
+This package exposes functions `encrypt` and `decrypt` which do the same thing.
+
+`encrypt` seals an AES key to the recipient, encrypts the message under
+that key, and returns a single envelope: `wrappedLen + wrapped + iv + ciphertext`
+(a 2-byte length prefix, the wrapped key, the 12-byte AES-GCM IV, and the
+cipher text). `decrypt` reverses it, returning the plaintext bytes.
+
+>
+> [!NOTE]  
+> See [`decrypt.asString`](#decryptasstring) &
+> [`decrypt.fromString`](#decryptfromstring) below for a convenient way
+> to decrypt from a string.
+>
+> See [`encrypt.asString`](#encrypt-to-a-string) for encrypting and ecoding to
+> a string.
+>
+
+
+```ts
+import {
+    encrypt,
+    decrypt
+} from '@substrate-system/simple-hpke'
+
+// need a public key for the recipient
+const recipient = await crypto.subtle.generateKey(
+    { name: 'X25519' },
+    false,
+    ['deriveBits']
+)
+
+// create a new AES key, encrypt a message, and get back one envelope
+const encryptedMessage = await encrypt(recipient, 'hello encryption')
+
+// the recipient recovers the message with their private key
+const text = await decrypt.asString(recipient, encryptedMessage)
+
+// use `decrypt` to get a Uint8Array
+const bytes = await decrypt(recipient, encryptedMessage)
+
+//
+// use an existing AES key
+//
+const existingKey = await crypto.subtle.generateKey(
+    { name: 'AES-GCM', length: 256 },
+    true,  // extractable
+    ['encrypt', 'decrypt']
+)
+
+const anotherEncryptedMsg = await encrypt(
+    recipient,
+    'hello again',
+    existingKey
+)
+```
+
+##### `encrypt`
+
+The recipient can be a crypto key, a Uint8Array, or a string public key.
+
+```ts
+type RecipientKey =
+    | CryptoKey
+    | CryptoKeyPair
+    | Uint8Array
+    | { publicKey:string; encoding?:Uint8ArrayEncodings }
+
+async function encrypt (
+    recipient:RecipientKey,
+    message:Uint8Array|string,
+    aesKey?:CryptoKey|Uint8Array|null,
+    opts?:{
+        keysize?:128|256
+        info?:Uint8Array|string
+    }
+):Promise<Uint8Array>
+```
+
+##### Encrypt to a string
+
+`encrypt.asString` is `encrypt` with the envelope encoded to a string, handy
+for transports that carry text (JSON, URLs, headers). `opts.encoding` sets the
+string encoding. Default encoding is `base64url`.
+
+```ts
+import { encrypt, decrypt } from '@substrate-system/ecies'
+import { fromString } from 'uint8arrays'
+
+// recipient is any RecipientKey; keypair holds the matching private key
+const encryptedString = await encrypt.asString(
+    recipient,
+    'message for them',
+    null,  // an AES key if you want
+    { encoding: 'base64url' }
+)
+
+// Decode it back to bytes before decrypting.
+const message = fromString(encryptedString, 'base64url')
+const plaintext = await decrypt.asString(keypair, message)
+// 'message for them'
+```
+
+The returned string encodes the same envelope `encrypt` returns, so the
+recipient decodes it with a matching decoder (here `fromString`) and passes the
+bytes to `decrypt` / `decrypt.asString`.
+
+
+##### `decrypt`
+
+Descrypt the given data, return a `Uint8Array`.
+
+```ts
+async function decrypt (
+    keypair:CryptoKeyPair,
+    message:Uint8Array,
+    opts?:{ info?:Uint8Array|string }
+):Promise<Uint8Array>
+```
+
+##### `decrypt.asString`
+
+Take a `Uint8Array`, return a sttring.
+
+```ts
+decrypt.asString = async function decryptToString (
+    keypair:CryptoKeyPair,
+    message:Uint8Array,
+    opts?:{ info?:Uint8Array|string }
+):Promise<string>
+```
+
+##### `decrypt.fromString`
+
+Take a `string` as input. Return either a string, or if `opts.buffer` is true,
+a`Uint8Array`.
+
+```ts
+decrypt.fromString = async function decryptFromString (
+    keypair:CryptoKeyPair,
+    message:string,
+    opts?:{ info?:Uint8Array|string, buffer?:boolean }
+):Promise<string|Uint8Array>
+```
+
+---------------------------------------------------------------
+
+## Modules
+
+This exposes ESM and common JS via
+[package.json `exports` field](https://nodejs.org/api/packages.html#exports).
+
+### ESM
+```js
+import { seal, open, encrypt, decrypt } from '@substrate-system/simple-hpke'
+```
+
+### Common JS
+```js
+require('@substrate-system/simple-hpke')
+```
+
+### pre-built JS
+This package exposes minified JS files too. Copy them to a location that is
+accessible to your web server, then link to them in HTML.
+
+#### copy
+```sh
+cp ./node_modules/@substrate-system/simple-hpke/dist/index.min.js ./public/hpke.min.js
+```
+
+#### HTML
+```html
+<script type="module" src="./hpke.min.js"></script>
+```