nostr-tools 0.24.1 → 1.0.0-alpha2

package/.eslintrc.json

@@ -1,5 +1,9 @@
 {
   "root": true,
+
+  "parser": "@typescript-eslint/parser",
+  "plugins": ["@typescript-eslint"],
+
   "parserOptions": {
     "ecmaVersion": 9,
     "ecmaFeatures": {
@@ -14,9 +18,7 @@
     "node": true
   },
 
-  "plugins": [
-    "babel"
-  ],
+  "plugins": ["babel"],
 
   "globals": {
     "document": false,
@@ -33,23 +35,23 @@
 
   "rules": {
     "accessor-pairs": 2,
-    "arrow-spacing": [2, { "before": true, "after": true }],
+    "arrow-spacing": [2, {"before": true, "after": true}],
     "block-spacing": [2, "always"],
-    "brace-style": [2, "1tbs", { "allowSingleLine": true }],
+    "brace-style": [2, "1tbs", {"allowSingleLine": true}],
     "comma-dangle": 0,
-    "comma-spacing": [2, { "before": false, "after": true }],
+    "comma-spacing": [2, {"before": false, "after": true}],
     "comma-style": [2, "last"],
     "constructor-super": 2,
     "curly": [0, "multi-line"],
     "dot-location": [2, "property"],
     "eol-last": 2,
     "eqeqeq": [2, "allow-null"],
-    "generator-star-spacing": [2, { "before": true, "after": true }],
-    "handle-callback-err": [2, "^(err|error)$" ],
+    "generator-star-spacing": [2, {"before": true, "after": true}],
+    "handle-callback-err": [2, "^(err|error)$"],
     "indent": 0,
     "jsx-quotes": [2, "prefer-double"],
-    "key-spacing": [2, { "beforeColon": false, "afterColon": true }],
-    "keyword-spacing": [2, { "before": true, "after": true }],
+    "key-spacing": [2, {"beforeColon": false, "afterColon": true}],
+    "keyword-spacing": [2, {"before": true, "after": true}],
     "new-cap": 0,
     "new-parens": 0,
     "no-array-constructor": 2,
@@ -81,12 +83,12 @@
     "no-irregular-whitespace": 2,
     "no-iterator": 2,
     "no-label-var": 2,
-    "no-labels": [2, { "allowLoop": false, "allowSwitch": false }],
+    "no-labels": [2, {"allowLoop": false, "allowSwitch": false}],
     "no-lone-blocks": 2,
     "no-mixed-spaces-and-tabs": 2,
     "no-multi-spaces": 2,
     "no-multi-str": 2,
-    "no-multiple-empty-lines": [2, { "max": 2 }],
+    "no-multiple-empty-lines": [2, {"max": 2}],
     "no-native-reassign": 2,
     "no-negated-in-lhs": 2,
     "no-new": 0,
@@ -115,23 +117,34 @@
     "no-undef": 2,
     "no-undef-init": 2,
     "no-unexpected-multiline": 2,
-    "no-unneeded-ternary": [2, { "defaultAssignment": false }],
+    "no-unneeded-ternary": [2, {"defaultAssignment": false}],
     "no-unreachable": 2,
-    "no-unused-vars": [2, { "vars": "local", "args": "none", "varsIgnorePattern": "^_"}],
+    "no-unused-vars": [
+      2,
+      {"vars": "local", "args": "none", "varsIgnorePattern": "^_"}
+    ],
     "no-useless-call": 2,
     "no-useless-constructor": 2,
     "no-with": 2,
-    "one-var": [0, { "initialized": "never" }],
-    "operator-linebreak": [2, "after", { "overrides": { "?": "before", ":": "before" } }],
+    "one-var": [0, {"initialized": "never"}],
+    "operator-linebreak": [
+      2,
+      "after",
+      {"overrides": {"?": "before", ":": "before"}}
+    ],
     "padded-blocks": [2, "never"],
-    "quotes": [2, "single", { "avoidEscape": true, "allowTemplateLiterals": true }],
+    "quotes": [
+      2,
+      "single",
+      {"avoidEscape": true, "allowTemplateLiterals": true}
+    ],
     "semi": [2, "never"],
-    "semi-spacing": [2, { "before": false, "after": true }],
+    "semi-spacing": [2, {"before": false, "after": true}],
     "space-before-blocks": [2, "always"],
     "space-before-function-paren": 0,
     "space-in-parens": [2, "never"],
     "space-infix-ops": 2,
-    "space-unary-ops": [2, { "words": true, "nonwords": false }],
+    "space-unary-ops": [2, {"words": true, "nonwords": false}],
     "spaced-comment": 0,
     "template-curly-spacing": [2, "never"],
     "use-isnan": 2,

package/.github/workflows/npm-publish.yml

@@ -0,0 +1,19 @@
+name: publish npm package
+
+on:
+  push:
+    tags: [v*]
+
+jobs:
+  publish-npm:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 18
+      - run: yarn --ignore-engines
+      - run: node build.js
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{secrets.NPM_TOKEN}}

package/.github/workflows/test.yml

@@ -0,0 +1,17 @@
+name: test every commit
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 18
+      - run: yarn --ignore-engines
+      - run: node build.js
+      - run: yarn test

package/README.md

@@ -4,89 +4,160 @@ Tools for developing [Nostr](https://github.com/fiatjaf/nostr) clients.
 
 ## Usage
 
-```js
-import {relayPool} from 'nostr-tools'
+### Generating a private key and a public key
 
-const pool = relayPool()
+```js
+import { generatePrivateKey, getPublicKey } from 'nostr-tools'
 
-pool.setPrivateKey('<hex>') // optional
+let sk = generatePrivateKey() # `sk` is a hex string
+let pk = getPublicKey(sk) # `pk` is a hex string
+```
 
-pool.addRelay('ws://some.relay.com', {read: true, write: true})
-pool.addRelay('ws://other.relay.cool', {read: true, write: true})
+### Creating, signing and verifying events
 
-// example callback function for a subscription
-function onEvent(event, relay) {
-  console.log(`got an event from ${relay.url} which is already validated.`, event)
+```js
+import {
+  validateEvent,
+  verifySignature,
+  signEvent,
+  getEventHash,
+  getPublicKey
+} from 'nostr-tools'
+
+let event = {
+  kind: 1,
+  created_at: Math.floor(Date.now() / 1000),
+  tags: [],
+  content: 'hello'
 }
 
-// subscribing to a single user
-// author is the user's public key
-pool.sub({cb: onEvent, filter: {author: '<hex>'}})
-
-//  or bulk follow
-pool.sub({cb:(event, relay) => {...}, filter: {authors: ['<hex1>', '<hex2>', ..., '<hexn>']}})
-
-// reuse a subscription channel
-const mySubscription = pool.sub({cb: ..., filter: ....})
-mySubscription.sub({filter: ....})
-mySubscription.sub({cb: ...})
-mySubscription.unsub()
-
-// get specific event
-const specificChannel = pool.sub({
-  cb: (event, relay) => {
-    console.log('got specific event from relay', event, relay)
-    specificChannel.unsub()
-  },
-  filter: {id: '<hex>'}
-})
+event.id = getEventHash(event.id)
+event.pubkey = getPublicKey(privateKey)
+event.sig = await signEvent(event, privateKey)
 
-// or get a specific event plus all the events that reference it in the 'e' tag
-pool.sub({ cb: (event, relay) => { ... }, filter: [{id: '<hex>'}, {'#e': '<hex>'}] })
+let ok = validateEvent(event)
+let veryOk = await verifySignature(event)
+```
 
-// get all events
-pool.sub({cb: (event, relay) => {...}, filter: {}})
+### Interacting with a relay
 
-// get recent events
-pool.sub({cb: (event, relay) => {...}, filter: {since: timestamp}})
+```js
+import {
+  relayInit,
+  generatePrivateKey,
+  getPublicKey,
+  getEventHash,
+  signEvent
+} from 'nostr-tools'
+
+const relay = relayInit('wss://relay.example.com')
+relay.connect()
+
+relay.on('connect', () => {
+  console.log(`connected to ${relay.url}`)
+})
+relay.on('error', () => {
+  console.log(`failed to connect to ${relay.url}`)
+})
 
-// publishing events(inside an async function):
-const ev = await pool.publish(eventObject, (status, url) => {
-  if (status === 0) {
-    console.log(`publish request sent to ${url}`)
+// let's query for an event that exists
+let sub = relay.sub([
+  {
+    ids: ['d7dd5eb3ab747e16f8d0212d53032ea2a7cadef53837e5a6c66d42849fcb9027']
   }
-  if (status === 1) {
-    console.log(`event published by ${url}`, ev)
+])
+sub.on('event', event => {
+  console.log('we got the event we wanted:', event)
+})
+sub.on('eose', () => {
+  sub.unsub()
+})
+
+// let's publish a new event while simultaneously monitoring the relay for it
+let sk = generatePrivateKey()
+let pk = getPublicKey(sk)
+
+let sub = relay.sub([
+  {
+    kinds: [1],
+    authors: [pk]
   }
+])
+
+sub.on('event', event => {
+  console.log('got event:', event)
+})
+
+let event = {
+  kind: 1,
+  pubkey: pk,
+  created_at: Math.floor(Date.now() / 1000),
+  tags: [],
+  content: 'hello world'
+}
+event.id = getEventHash(event)
+event.sig = await signEvent(event, sk)
+
+let pub = relay.publish(event)
+pub.on('ok', () => {
+  console.log(`{relay.url} has accepted our event`)
+})
+pub.on('seen', () => {
+  console.log(`we saw the event on {relay.url}`)
+})
+pub.on('failed', reason => {
+  console.log(`failed to publish to {relay.url}: ${reason}`)
 })
-// it will be signed automatically with the key supplied above
-// or pass an already signed event to bypass this
 
-// subscribing to a new relay
-pool.addRelay('<url>')
-// will automatically subscribe to the all the events called with .sub above
+await relay.close()
 ```
 
-All functions expect bytearrays as hex strings and output bytearrays as hex strings.
+### Encrypting and decrypting direct messages
 
-For other utils please read the source (for now).
+```js
+import {nip04, getPublicKey, generatePrivateKey} from 'nostr-tools'
+
+// sender
+let sk1 = generatePrivateKey()
+let pk1 = getPublicKey(sk1)
+
+// receiver
+let sk2 = generatePrivateKey()
+let pk2 = getPublicKey(sk2)
+
+// on the sender side
+let message = 'hello'
+let ciphertext = nip04.encrypt(sk1, pk2, 'hello')
+
+let event = {
+  kind: 4,
+  pubkey: pk1,
+  tags: [['p', pk2]],
+  content: ciphertext,
+  ...otherProperties
+}
 
-### Using from the browser (if you don't want to use a bundler)
+sendEvent(event)
 
-You can import nostr-tools as an ES module. Just add a script tag like this:
+// on the receiver side
 
-```html
-<script type="module">
-  import {generatePrivateKey} from 'https://unpkg.com/nostr-tools/nostr.js'
-  console.log(generatePrivateKey())
-</script>
+sub.on('event', (event) => {
+  let sender = event.tags.find(([k, v]) => k === 'p' && && v && v !== '')[1]
+  pk1 === sender
+  let plaintext = nip04.decrypt(sk2, pk1, event.content)
+})
 ```
 
-And import whatever function you would import from `"nostr-tools"` in a bundler.
+Please consult the tests or [the source code](https://github.com/fiatjaf/nostr-tools) for more information that isn't available here.
 
-## TypeScript
+### Using from the browser (if you don't want to use a bundler)
 
-This module has hand-authored TypeScript declarations. `npm run check-ts` will run a lint-check script to ensure the typings can be loaded and call at least a few standard library functions. It's not at all comprehensive and likely to contain bugs. Issues welcome; tag @rcoder as needed.
+```html
+<script src="https://unpkg.com/nostr-tools/nostr.bundle.js"></script>
+<script>
+  window.NostrTools.generatePrivateKey('...') // and so on
+</script>
+```
 
 ## License
 

package/build.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+
+const esbuild = require('esbuild')
+const alias = require('esbuild-plugin-alias')
+
+let common = {
+  entryPoints: ['index.ts'],
+  bundle: true,
+  plugins: [
+    alias({
+      stream: require.resolve('readable-stream')
+    })
+  ],
+  sourcemap: 'external'
+}
+
+esbuild
+  .build({
+    ...common,
+    outfile: 'lib/nostr.esm.js',
+    format: 'esm',
+    packages: 'external'
+  })
+  .then(() => console.log('esm build success.'))
+
+esbuild
+  .build({
+    ...common,
+    outfile: 'lib/nostr.cjs.js',
+    format: 'cjs',
+    packages: 'external'
+  })
+  .then(() => console.log('cjs build success.'))
+
+esbuild
+  .build({
+    ...common,
+    outfile: 'lib/nostr.bundle.js',
+    format: 'iife',
+    globalName: 'NostrTools',
+    define: {
+      window: 'self',
+      global: 'self',
+      process: '{"env": {}}'
+    }
+  })
+  .then(() => console.log('standalone build success.'))

package/event.test.js

@@ -0,0 +1,49 @@
+/* eslint-env jest */
+
+const {
+  validateEvent,
+  verifySignature,
+  signEvent,
+  getEventHash,
+  getPublicKey
+} = require('./lib/nostr.cjs')
+
+const event = {
+  id: 'd7dd5eb3ab747e16f8d0212d53032ea2a7cadef53837e5a6c66d42849fcb9027',
+  kind: 1,
+  pubkey: '22a12a128a3be27cd7fb250cbe796e692896398dc1440ae3fa567812c8107c1c',
+  created_at: 1670869179,
+  content:
+    'NOSTR "WINE-ACCOUNT" WITH HARVEST DATE STAMPED\n\n\n"The older the wine, the greater its reputation"\n\n\n22a12a128a3be27cd7fb250cbe796e692896398dc1440ae3fa567812c8107c1c\n\n\nNWA 2022-12-12\nAA',
+  tags: [['client', 'astral']],
+  sig: 'f110e4fdf67835fb07abc72469933c40bdc7334615610cade9554bf00945a1cebf84f8d079ec325d26fefd76fe51cb589bdbe208ac9cdbd63351ddad24a57559'
+}
+
+const unsigned = {
+  created_at: 1671217411,
+  kind: 0,
+  tags: [],
+  content:
+    '{"name":"fiatjaf","about":"buy my merch at fiatjaf store","picture":"https://fiatjaf.com/static/favicon.jpg","nip05":"_@fiatjaf.com"}'
+}
+
+const privateKey =
+  '5c6c25b7ef18d8633e97512159954e1aa22809c6b763e94b9f91071836d00217'
+
+test('validate event', () => {
+  expect(validateEvent(event)).toBeTruthy()
+})
+
+test('check signature', async () => {
+  expect(await verifySignature(event)).toBeTruthy()
+})
+
+test('sign event', async () => {
+  let sig = await signEvent(unsigned, privateKey)
+  let hash = getEventHash(unsigned)
+  let pubkey = getPublicKey(privateKey)
+
+  let signed = {...unsigned, id: hash, sig, pubkey}
+
+  expect(await verifySignature(signed)).toBeTruthy()
+})

package/{event.js → event.ts}

@@ -1,18 +1,29 @@
 import {Buffer} from 'buffer'
-import createHash from 'create-hash'
+// @ts-ignore
 import * as secp256k1 from '@noble/secp256k1'
+import {sha256} from '@noble/hashes/sha256'
 
-export function getBlankEvent() {
+export type Event = {
+  id?: string
+  sig?: string
+  kind: number
+  tags: string[][]
+  pubkey: string
+  content: string
+  created_at: number
+}
+
+export function getBlankEvent(): Event {
   return {
     kind: 255,
-    pubkey: null,
+    pubkey: '',
     content: '',
     tags: [],
     created_at: 0
   }
 }
 
-export function serializeEvent(evt) {
+export function serializeEvent(evt: Event): string {
   return JSON.stringify([
     0,
     evt.pubkey,
@@ -23,14 +34,12 @@ export function serializeEvent(evt) {
   ])
 }
 
-export function getEventHash(event) {
-  let eventHash = createHash('sha256')
-    .update(Buffer.from(serializeEvent(event)))
-    .digest()
+export function getEventHash(event: Event): string {
+  let eventHash = sha256(Buffer.from(serializeEvent(event)))
   return Buffer.from(eventHash).toString('hex')
 }
 
-export function validateEvent(event) {
+export function validateEvent(event: Event): boolean {
   if (event.id !== getEventHash(event)) return false
   if (typeof event.content !== 'string') return false
   if (typeof event.created_at !== 'number') return false
@@ -47,12 +56,14 @@ export function validateEvent(event) {
   return true
 }
 
-export function verifySignature(event) {
+export function verifySignature(
+  event: Event & {id: string; sig: string}
+): Promise<boolean> {
   return secp256k1.schnorr.verify(event.sig, event.id, event.pubkey)
 }
 
-export async function signEvent(event, key) {
+export async function signEvent(event: Event, key: string): Promise<string> {
   return Buffer.from(
-    await secp256k1.schnorr.sign(getEventHash(event), key)
+    await secp256k1.schnorr.sign(event.id || getEventHash(event), key)
   ).toString('hex')
 }

package/filter.test.js

@@ -0,0 +1,42 @@
+/* eslint-env jest */
+
+const {matchFilters} = require('./lib/nostr.cjs')
+
+test('test if filters match', () => {
+  ;[
+    {
+      filters: [{ids: ['i']}],
+      good: [{id: 'i'}],
+      bad: [{id: 'j'}]
+    },
+    {
+      filters: [{authors: ['abc']}, {kinds: [1, 3]}],
+      good: [
+        {pubkey: 'xyz', kind: 3},
+        {pubkey: 'abc', kind: 12},
+        {pubkey: 'abc', kind: 1}
+      ],
+      bad: [{pubkey: 'hhh', kind: 12}]
+    },
+    {
+      filters: [{'#e': ['yyy'], since: 444}],
+      good: [
+        {
+          tags: [
+            ['e', 'uuu'],
+            ['e', 'yyy']
+          ],
+          created_at: 555
+        }
+      ],
+      bad: [{tags: [['e', 'uuu']], created_at: 111}]
+    }
+  ].forEach(({filters, good, bad}) => {
+    good.forEach(ev => {
+      expect(matchFilters(filters, ev)).toBeTruthy()
+    })
+    bad.forEach(ev => {
+      expect(matchFilters(filters, ev)).toBeFalsy()
+    })
+  })
+})

package/{filter.js → filter.ts}

@@ -1,4 +1,18 @@
-export function matchFilter(filter, event) {
+import {Event} from './event'
+
+export type Filter = {
+  ids?: string[]
+  kinds?: number[]
+  authors?: string[]
+  since?: number
+  until?: number
+  [key: `#${string}`]: string[]
+}
+
+export function matchFilter(
+  filter: Filter,
+  event: Event & {id: string}
+): boolean {
   if (filter.ids && filter.ids.indexOf(event.id) === -1) return false
   if (filter.kinds && filter.kinds.indexOf(event.kind) === -1) return false
   if (filter.authors && filter.authors.indexOf(event.pubkey) === -1)
@@ -6,10 +20,12 @@ export function matchFilter(filter, event) {
 
   for (let f in filter) {
     if (f[0] === '#') {
+      let tagName = f.slice(1)
+      let values = filter[`#${tagName}`]
       if (
-        filter[f] &&
+        values &&
         !event.tags.find(
-          ([t, v]) => t === f.slice(1) && filter[f].indexOf(v) !== -1
+          ([t, v]) => t === f.slice(1) && values.indexOf(v) !== -1
         )
       )
         return false
@@ -22,7 +38,10 @@ export function matchFilter(filter, event) {
   return true
 }
 
-export function matchFilters(filters, event) {
+export function matchFilters(
+  filters: Filter[],
+  event: Event & {id: string}
+): boolean {
   for (let i = 0; i < filters.length; i++) {
     if (matchFilter(filters[i], event)) return true
   }

package/index.ts

@@ -0,0 +1,8 @@
+export * from './keys'
+export * from './relay'
+export * from './event'
+export * from './filter'
+
+export * as nip04 from './nip04'
+export * as nip05 from './nip05'
+export * as nip06 from './nip06'

package/keys.test.js

@@ -0,0 +1,20 @@
+/* eslint-env jest */
+
+const {generatePrivateKey, getPublicKey} = require('./lib/nostr.cjs')
+
+test('test private key generation', () => {
+  expect(generatePrivateKey()).toMatch(/[a-f0-9]{64}/)
+})
+
+test('test public key generation', () => {
+  expect(getPublicKey(generatePrivateKey())).toMatch(/[a-f0-9]{64}/)
+})
+
+test('test public key from private key deterministic', () => {
+  let sk = generatePrivateKey()
+  let pk = getPublicKey(sk)
+
+  for (let i = 0; i < 5; i++) {
+    expect(getPublicKey(sk)).toEqual(pk)
+  }
+})

package/{keys.js → keys.ts}

@@ -1,10 +1,10 @@
 import * as secp256k1 from '@noble/secp256k1'
 import {Buffer} from 'buffer'
 
-export function generatePrivateKey() {
+export function generatePrivateKey(): string {
   return Buffer.from(secp256k1.utils.randomPrivateKey()).toString('hex')
 }
 
-export function getPublicKey(privateKey) {
+export function getPublicKey(privateKey: string): string {
   return Buffer.from(secp256k1.schnorr.getPublicKey(privateKey)).toString('hex')
 }