generated from 47ng/typescript-library-starter
-
-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
9 changed files
with
1,503 additions
and
1,143 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,7 +1,7 @@ | ||
| node_modules/ | ||
| dist/ | ||
| coverage/ | ||
| .env | ||
| yarn-error.log | ||
|
|
||
| # Docker containers with persistance | ||
| .volumes/ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,44 +1,68 @@ | ||
| # `typescript-library-starter` | ||
| # `@47ng/simple-e2ee` | ||
|
|
||
| [](https://www.npmjs.com/package/typescript-library-starter) | ||
| [](https://github.com/47ng/typescript-library-starter/blob/master/LICENSE) | ||
| [](https://travis-ci.com/47ng/typescript-library-starter) | ||
| [](https://dependabot.com) | ||
| [](https://isitmaintained.com/project/47ng/typescript-library-starter) | ||
| [](https://isitmaintained.com/project/47ng/typescript-library-starter) | ||
| [](https://www.npmjs.com/package/@47ng/simple-e2ee) | ||
| [](https://github.com/47ng/simple-e2ee/blob/next/LICENSE) | ||
| [](https://github.com/47ng/simple-e2ee/actions) | ||
| [](https://coveralls.io/github/47ng/simple-e2ee?branch=next) | ||
| [](https://dependabot.com) | ||
|
|
||
| Template repository for TypeScript libraries. | ||
| Simple end-to-end encryption for web apps. Inspired from [Excalidraw](https://excalidraw.com) and [Firefox Send](https://github.com/mozilla/send) (RIP). | ||
|
|
||
| ## Installation | ||
|
|
||
| ✂️--- | ||
| _Cut here_ | ||
| ## How it works | ||
|
|
||
| 1. [Use this repository as a template](https://github.com/47ng/typescript-library-starter/generate) to create your own. | ||
| 2. Replace all mentions of `typescript-library-starter` with the name | ||
| of your package. | ||
| 3. Setup Travis CI by adding an NPM deploy token and a Slack channel token: | ||
| You encrypt your data in the browser, send the encrypted data | ||
| to a server, and use the hash part of the URL (which never | ||
| hits the server) to share the key with someone else. | ||
|
|
||
| ```zsh | ||
| # Copy your NPM deploy token to clipboard, then: | ||
| $ travis encrypt $(pbpaste) --add deploy.api_key --com | ||
| On the other side, the recipient obtains the key from the URL, | ||
| the payload from the server and decrypts the data. | ||
|
|
||
| # Copy your Slack channel token to clipboard, then: | ||
| $ travis encrypt $(pbpaste) --add notifications.slack.rooms --com | ||
| ``` | ||
| This library does not handle any of the server upload/download | ||
| side, it's up to you. It only deals with encryption, decryption | ||
| and moving keys in and out of URLs. | ||
|
|
||
| --- ✂️ | ||
| ## Installation | ||
|
|
||
| ```shell | ||
| $ yarn add typescript-library-starter | ||
| $ yarn add @47ng/simple-e2ee | ||
| # or | ||
| $ npm i typescript-library-starter | ||
| $ npm i @47ng/simple-e2ee | ||
| ``` | ||
|
|
||
| ## Usage | ||
|
|
||
| ## Configuration | ||
| ```ts | ||
| import { | ||
| encrypt, | ||
| decrypt, | ||
| applyKeyToURL, | ||
| getKeyFromURL | ||
| } from '@47ng/simple-e2ee' | ||
|
|
||
| // Before sending data to the server, encrypt it: | ||
| const { payload, key } = encrypt( | ||
| "whatever you want, as long as it's JSON-serialisable" | ||
| ) | ||
|
|
||
| // Upload `payload` to the server | ||
| // Stick the key onto the current URL: | ||
| const shareURL = applyKeyToURL(key) | ||
|
|
||
| // Optionally, apply the key to another URL | ||
| // (example, with an ID returned from the server): | ||
| const shareURL = applyKeyToURL(key, `https://example.com/share/${id}`) | ||
|
|
||
| // On the other side, get the key from the current URL, | ||
| // and the payload from the server: | ||
| const key = getKeyFromURL() | ||
| const message = decrypt(payload, key) | ||
|
|
||
| // Optionally, obtain the key from any URL: | ||
| const key = getKeyFromURL( | ||
| `https://example.com/share/foo#KatLceVEOM2znzX_FGPKu6Zz1adWkhlq9b2R9WRjUsM=` | ||
| ) | ||
| ``` | ||
|
|
||
| ## License | ||
|
|
||
| [MIT](https://github.com/47ng/typescript-library-starter/blob/master/LICENSE) - Made with ❤️ by [François Best](https://francoisbest.com). | ||
| [MIT](https://github.com/47ng/simple-e2ee/blob/master/LICENSE) - Made with ❤️ by [François Best](https://francoisbest.com). |
This file was deleted.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,7 +1,100 @@ | ||
| import lib from './index' | ||
| import { | ||
| encrypt, | ||
| decrypt, | ||
| PAYLOAD_REGEX_V1, | ||
| applyKeyToURL, | ||
| getKeyFromURL | ||
| } from './index' | ||
|
|
||
| describe('typescript-library-starter', () => { | ||
| test('testing works', () => { | ||
| expect(lib).toBe('Hello, World !') | ||
| }) | ||
| test('encrypt generates a key and a payload', () => { | ||
| expect(encrypt('').payload).toMatch(PAYLOAD_REGEX_V1) | ||
| expect(encrypt({}).payload).toMatch(PAYLOAD_REGEX_V1) | ||
| expect(encrypt([]).payload).toMatch(PAYLOAD_REGEX_V1) | ||
| expect(encrypt(null).payload).toMatch(PAYLOAD_REGEX_V1) | ||
| expect(encrypt(42).payload).toMatch(PAYLOAD_REGEX_V1) | ||
| expect(encrypt({ hello: 'world' }).payload).toMatch(PAYLOAD_REGEX_V1) | ||
| }) | ||
|
|
||
| test('Encrypt => Decrypt', () => { | ||
| function testEncryptionDecryption<T>(input: T) { | ||
| const { payload, key } = encrypt(input) | ||
| expect(decrypt(payload, key)).toEqual(input) | ||
| } | ||
|
|
||
| testEncryptionDecryption('') | ||
| testEncryptionDecryption({}) | ||
| testEncryptionDecryption([]) | ||
| testEncryptionDecryption(null) | ||
| testEncryptionDecryption(42) | ||
| testEncryptionDecryption({ hello: 'world' }) | ||
| }) | ||
|
|
||
| test('Failure - Invalid payload', () => { | ||
| const run = () => decrypt('not a payload', 'not a key') | ||
| expect(run).toThrowError('Invalid payload format') | ||
| }) | ||
|
|
||
| test('Failure - Invalid key', () => { | ||
| const run = () => | ||
| decrypt( | ||
| '1.G3Yvm4G3X97h2-ky8ORVIlVMBbHNVFd_.cNFG6eisWeBkC-Rer6I4J7kZ', | ||
| 'not a key' | ||
| ) | ||
| expect(run).toThrowError('bad key size') | ||
| }) | ||
|
|
||
| test('Failure - Wrong key', () => { | ||
| const run = () => | ||
| decrypt( | ||
| '1.G3Yvm4G3X97h2-ky8ORVIlVMBbHNVFd_.cNFG6eisWeBkC-Rer6I4J7kZ', | ||
| 'KatLceVEOM2znzX_FGPKu6Zz1adWkhlq9b2R9WRjUsM=' | ||
| ) | ||
| expect(run).toThrowError('Could not decrypt payload (wrong key)') | ||
| }) | ||
|
|
||
| // -- | ||
|
|
||
| test('Inject key in current URL', () => { | ||
| const url = applyKeyToURL('KatLceVEOM2znzX_FGPKu6Zz1adWkhlq9b2R9WRjUsM=') | ||
| expect(url).toEqual( | ||
| 'http://localhost/#KatLceVEOM2znzX_FGPKu6Zz1adWkhlq9b2R9WRjUsM=' | ||
| ) | ||
| }) | ||
|
|
||
| test('Inject key in URL', () => { | ||
| const url = applyKeyToURL( | ||
| 'KatLceVEOM2znzX_FGPKu6Zz1adWkhlq9b2R9WRjUsM=', | ||
| 'https://example.com' | ||
| ) | ||
| expect(url).toEqual( | ||
| 'https://example.com/#KatLceVEOM2znzX_FGPKu6Zz1adWkhlq9b2R9WRjUsM=' | ||
| ) | ||
| }) | ||
|
|
||
| test('Inject key in URL that already has a hash', () => { | ||
| const run = () => | ||
| applyKeyToURL( | ||
| 'KatLceVEOM2znzX_FGPKu6Zz1adWkhlq9b2R9WRjUsM=', | ||
| 'https://example.com#already-hashed' | ||
| ) | ||
| expect(run).toThrow() | ||
| }) | ||
|
|
||
| test('Get key from URL', () => { | ||
| const key = getKeyFromURL( | ||
| 'https://example.com#KatLceVEOM2znzX_FGPKu6Zz1adWkhlq9b2R9WRjUsM=' | ||
| ) | ||
| expect(key).toEqual('KatLceVEOM2znzX_FGPKu6Zz1adWkhlq9b2R9WRjUsM=') | ||
| }) | ||
|
|
||
| test('Get key from URL without a hash', () => { | ||
| const run = () => getKeyFromURL() | ||
| expect(run).toThrow('Could not retrieve key: no hash in URL') | ||
| }) | ||
|
|
||
| test('Get key from current URL', () => { | ||
| window.location.hash = 'KatLceVEOM2znzX_FGPKu6Zz1adWkhlq9b2R9WRjUsM=' | ||
| const key = getKeyFromURL() | ||
| expect(key).toEqual('KatLceVEOM2znzX_FGPKu6Zz1adWkhlq9b2R9WRjUsM=') | ||
| window.location.hash = '' | ||
| }) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1 +1,52 @@ | ||
| export default 'Hello, World !' | ||
| import nacl from 'tweetnacl' | ||
| import b64 from '@47ng/codec/dist/b64' | ||
| import utf8 from '@47ng/codec/dist/utf8' | ||
| import { URL } from 'url' | ||
|
|
||
| export function encrypt<T>(message: T) { | ||
| const key = nacl.randomBytes(nacl.secretbox.keyLength) | ||
| const nonce = nacl.randomBytes(nacl.secretbox.nonceLength) | ||
| const payload = utf8.encode(JSON.stringify(message)) | ||
| const ciphertext = nacl.secretbox(payload, nonce, key) | ||
| return { | ||
| payload: ['1', b64.encode(nonce), b64.encode(ciphertext)].join('.'), | ||
| key: b64.encode(key) | ||
| } | ||
| } | ||
|
|
||
| export const PAYLOAD_REGEX_V1 = /^1\.([a-zA-Z0-9-_]{32})\.([a-zA-Z0-9-_]{24,})={0,2}$/ | ||
|
|
||
| export function decrypt<T>(payload: string, key: string): T { | ||
| const match = payload.match(PAYLOAD_REGEX_V1) | ||
| if (!match) { | ||
| throw new Error('Invalid payload format') | ||
| } | ||
| const nonce = b64.decode(match[1]) | ||
| const ciphertext = b64.decode(match[2]) | ||
| const message = nacl.secretbox.open(ciphertext, nonce, b64.decode(key)) | ||
| if (!message) { | ||
| throw new Error('Could not decrypt payload (wrong key)') | ||
| } | ||
| const json = utf8.decode(message) | ||
| return JSON.parse(json) | ||
| } | ||
|
|
||
| export function applyKeyToURL(key: string, baseURL?: string) { | ||
| const url = new URL(baseURL ?? window.location.toString()) | ||
| if (!!url.hash) { | ||
| throw new Error( | ||
| 'URL already has a hash part, this will conflict with the E2EE key' | ||
| ) | ||
| } | ||
| url.hash = key | ||
| return url.toString() | ||
| } | ||
|
|
||
| export function getKeyFromURL(baseURL?: string) { | ||
| const url = baseURL ? new URL(baseURL) : window.location | ||
| const hash = url.hash.replace(/^#/, '') | ||
| if (hash === '') { | ||
| throw new Error('Could not retrieve key: no hash in URL') | ||
| } | ||
| return hash | ||
| } |
Oops, something went wrong.