@libp2p/peer-record 0.0.0

package/package.json

@@ -0,0 +1,164 @@
+{
+  "name": "@libp2p/peer-record",
+  "version": "0.0.0",
+  "description": "Used to transfer signed peer data across the network",
+  "license": "Apache-2.0 OR MIT",
+  "homepage": "https://github.com/libp2p/js-libp2p-interfaces/tree/master/packages/libp2p-peer-record#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/libp2p/js-libp2p-interfaces.git"
+  },
+  "bugs": {
+    "url": "https://github.com/libp2p/js-libp2p-interfaces/issues"
+  },
+  "keywords": [
+    "IPFS"
+  ],
+  "engines": {
+    "node": ">=16.0.0",
+    "npm": ">=7.0.0"
+  },
+  "type": "module",
+  "types": "./dist/src/index.d.ts",
+  "files": [
+    "src",
+    "dist/src",
+    "!dist/test",
+    "!**/*.tsbuildinfo"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/src/index.js"
+    }
+  },
+  "eslintConfig": {
+    "extends": "ipfs",
+    "parserOptions": {
+      "sourceType": "module"
+    }
+  },
+  "release": {
+    "branches": [
+      "master"
+    ],
+    "plugins": [
+      [
+        "@semantic-release/commit-analyzer",
+        {
+          "preset": "conventionalcommits",
+          "releaseRules": [
+            {
+              "breaking": true,
+              "release": "major"
+            },
+            {
+              "revert": true,
+              "release": "patch"
+            },
+            {
+              "type": "feat",
+              "release": "minor"
+            },
+            {
+              "type": "fix",
+              "release": "patch"
+            },
+            {
+              "type": "chore",
+              "release": "patch"
+            },
+            {
+              "type": "docs",
+              "release": "patch"
+            },
+            {
+              "type": "test",
+              "release": "patch"
+            },
+            {
+              "scope": "no-release",
+              "release": false
+            }
+          ]
+        }
+      ],
+      [
+        "@semantic-release/release-notes-generator",
+        {
+          "preset": "conventionalcommits",
+          "presetConfig": {
+            "types": [
+              {
+                "type": "feat",
+                "section": "Features"
+              },
+              {
+                "type": "fix",
+                "section": "Bug Fixes"
+              },
+              {
+                "type": "chore",
+                "section": "Trivial Changes"
+              },
+              {
+                "type": "docs",
+                "section": "Trivial Changes"
+              },
+              {
+                "type": "test",
+                "section": "Tests"
+              }
+            ]
+          }
+        }
+      ],
+      "@semantic-release/changelog",
+      "@semantic-release/npm",
+      "@semantic-release/github",
+      "@semantic-release/git"
+    ]
+  },
+  "scripts": {
+    "lint": "aegir lint",
+    "dep-check": "aegir dep-check dist/src/**/*.js test/src/**/*.js",
+    "build": "tsc",
+    "postbuild": "npm run build:copy-proto-files",
+    "generate": "npm run generate:envelope && npm run generate:envelope-types && npm run generate:peer-record && npm run generate:peer-record-types",
+    "generate:envelope": "pbjs -t static-module -w es6 -r libp2p-peer-record-envelope --force-number --no-verify --no-delimited --no-create --no-beautify --no-defaults --lint eslint-disable -o src/envelope/envelope.js ./src/envelope/envelope.proto",
+    "generate:envelope-types": "pbts -o src/envelope/envelope.d.ts src/envelope/envelope.js",
+    "generate:peer-record": "pbjs -t static-module -w es6 -r libp2p-peer-record --force-number --no-verify --no-delimited --no-create --no-beautify --no-defaults --lint eslint-disable -o src/peer-record/peer-record.js ./src/peer-record/peer-record.proto",
+    "generate:peer-record-types": "pbts -o src/peer-record/peer-record.d.ts src/peer-record/peer-record.js",
+    "build:copy-proto-files": "cp src/envelope/envelope.js dist/src/envelope && cp src/envelope/*.d.ts dist/src/envelope && cp src/peer-record/peer-record.js dist/src/peer-record && cp src/peer-record/*.d.ts dist/src/peer-record",
+    "pretest": "npm run build",
+    "test": "aegir test -f ./dist/test",
+    "test:chrome": "npm run test -- -t browser",
+    "test:chrome-webworker": "npm run test -- -t webworker",
+    "test:firefox": "npm run test -- -t browser -- --browser firefox",
+    "test:firefox-webworker": "npm run test -- -t webworker -- --browser firefox",
+    "test:node": "npm run test -- -t node --cov",
+    "test:electron-main": "npm run test -- -t electron-main"
+  },
+  "dependencies": {
+    "@libp2p/interfaces": "^1.2.0",
+    "protobufjs": "^6.10.2",
+    "@libp2p/logger": "^1.0.1",
+    "interface-datastore": "^6.1.0",
+    "@multiformats/multiaddr": "^10.1.5",
+    "it-all": "^1.0.6",
+    "it-filter": "^1.0.3",
+    "it-pipe": "^2.0.3",
+    "it-map": "^1.0.6",
+    "it-foreach": "^0.1.1",
+    "multiformats": "^9.6.3",
+    "@libp2p/crypto": "^0.22.7",
+    "varint": "^6.0.0",
+    "@libp2p/utils": "^1.0.5"
+  },
+  "devDependencies": {
+    "@types/varint": "^6.0.0",
+    "aegir": "^36.1.3",
+    "sinon": "^13.0.1",
+    "@libp2p/peer-id-factory": "^1.0.3",
+    "@libp2p/interface-compliance-tests": "^1.0.8"
+  }
+}

package/src/envelope/envelope.d.ts

@@ -0,0 +1,77 @@
+import * as $protobuf from "protobufjs";
+/** Properties of an Envelope. */
+export interface IEnvelope {
+
+    /** Envelope publicKey */
+    publicKey?: (Uint8Array|null);
+
+    /** Envelope payloadType */
+    payloadType?: (Uint8Array|null);
+
+    /** Envelope payload */
+    payload?: (Uint8Array|null);
+
+    /** Envelope signature */
+    signature?: (Uint8Array|null);
+}
+
+/** Represents an Envelope. */
+export class Envelope implements IEnvelope {
+
+    /**
+     * Constructs a new Envelope.
+     * @param [p] Properties to set
+     */
+    constructor(p?: IEnvelope);
+
+    /** Envelope publicKey. */
+    public publicKey: Uint8Array;
+
+    /** Envelope payloadType. */
+    public payloadType: Uint8Array;
+
+    /** Envelope payload. */
+    public payload: Uint8Array;
+
+    /** Envelope signature. */
+    public signature: Uint8Array;
+
+    /**
+     * Encodes the specified Envelope message. Does not implicitly {@link Envelope.verify|verify} messages.
+     * @param m Envelope message or plain object to encode
+     * @param [w] Writer to encode to
+     * @returns Writer
+     */
+    public static encode(m: IEnvelope, w?: $protobuf.Writer): $protobuf.Writer;
+
+    /**
+     * Decodes an Envelope message from the specified reader or buffer.
+     * @param r Reader or buffer to decode from
+     * @param [l] Message length if known beforehand
+     * @returns Envelope
+     * @throws {Error} If the payload is not a reader or valid buffer
+     * @throws {$protobuf.util.ProtocolError} If required fields are missing
+     */
+    public static decode(r: ($protobuf.Reader|Uint8Array), l?: number): Envelope;
+
+    /**
+     * Creates an Envelope message from a plain object. Also converts values to their respective internal types.
+     * @param d Plain object
+     * @returns Envelope
+     */
+    public static fromObject(d: { [k: string]: any }): Envelope;
+
+    /**
+     * Creates a plain object from an Envelope message. Also converts values to other types if specified.
+     * @param m Envelope
+     * @param [o] Conversion options
+     * @returns Plain object
+     */
+    public static toObject(m: Envelope, o?: $protobuf.IConversionOptions): { [k: string]: any };
+
+    /**
+     * Converts this Envelope to JSON.
+     * @returns JSON object
+     */
+    public toJSON(): { [k: string]: any };
+}

package/src/envelope/envelope.js

@@ -0,0 +1,241 @@
+/*eslint-disable*/
+import $protobuf from "protobufjs/minimal.js";
+
+// Common aliases
+const $Reader = $protobuf.Reader, $Writer = $protobuf.Writer, $util = $protobuf.util;
+
+// Exported root namespace
+const $root = $protobuf.roots["libp2p-peer-record-envelope"] || ($protobuf.roots["libp2p-peer-record-envelope"] = {});
+
+export const Envelope = $root.Envelope = (() => {
+
+    /**
+     * Properties of an Envelope.
+     * @exports IEnvelope
+     * @interface IEnvelope
+     * @property {Uint8Array|null} [publicKey] Envelope publicKey
+     * @property {Uint8Array|null} [payloadType] Envelope payloadType
+     * @property {Uint8Array|null} [payload] Envelope payload
+     * @property {Uint8Array|null} [signature] Envelope signature
+     */
+
+    /**
+     * Constructs a new Envelope.
+     * @exports Envelope
+     * @classdesc Represents an Envelope.
+     * @implements IEnvelope
+     * @constructor
+     * @param {IEnvelope=} [p] Properties to set
+     */
+    function Envelope(p) {
+        if (p)
+            for (var ks = Object.keys(p), i = 0; i < ks.length; ++i)
+                if (p[ks[i]] != null)
+                    this[ks[i]] = p[ks[i]];
+    }
+
+    /**
+     * Envelope publicKey.
+     * @member {Uint8Array} publicKey
+     * @memberof Envelope
+     * @instance
+     */
+    Envelope.prototype.publicKey = $util.newBuffer([]);
+
+    /**
+     * Envelope payloadType.
+     * @member {Uint8Array} payloadType
+     * @memberof Envelope
+     * @instance
+     */
+    Envelope.prototype.payloadType = $util.newBuffer([]);
+
+    /**
+     * Envelope payload.
+     * @member {Uint8Array} payload
+     * @memberof Envelope
+     * @instance
+     */
+    Envelope.prototype.payload = $util.newBuffer([]);
+
+    /**
+     * Envelope signature.
+     * @member {Uint8Array} signature
+     * @memberof Envelope
+     * @instance
+     */
+    Envelope.prototype.signature = $util.newBuffer([]);
+
+    /**
+     * Encodes the specified Envelope message. Does not implicitly {@link Envelope.verify|verify} messages.
+     * @function encode
+     * @memberof Envelope
+     * @static
+     * @param {IEnvelope} m Envelope message or plain object to encode
+     * @param {$protobuf.Writer} [w] Writer to encode to
+     * @returns {$protobuf.Writer} Writer
+     */
+    Envelope.encode = function encode(m, w) {
+        if (!w)
+            w = $Writer.create();
+        if (m.publicKey != null && Object.hasOwnProperty.call(m, "publicKey"))
+            w.uint32(10).bytes(m.publicKey);
+        if (m.payloadType != null && Object.hasOwnProperty.call(m, "payloadType"))
+            w.uint32(18).bytes(m.payloadType);
+        if (m.payload != null && Object.hasOwnProperty.call(m, "payload"))
+            w.uint32(26).bytes(m.payload);
+        if (m.signature != null && Object.hasOwnProperty.call(m, "signature"))
+            w.uint32(42).bytes(m.signature);
+        return w;
+    };
+
+    /**
+     * Decodes an Envelope message from the specified reader or buffer.
+     * @function decode
+     * @memberof Envelope
+     * @static
+     * @param {$protobuf.Reader|Uint8Array} r Reader or buffer to decode from
+     * @param {number} [l] Message length if known beforehand
+     * @returns {Envelope} Envelope
+     * @throws {Error} If the payload is not a reader or valid buffer
+     * @throws {$protobuf.util.ProtocolError} If required fields are missing
+     */
+    Envelope.decode = function decode(r, l) {
+        if (!(r instanceof $Reader))
+            r = $Reader.create(r);
+        var c = l === undefined ? r.len : r.pos + l, m = new $root.Envelope();
+        while (r.pos < c) {
+            var t = r.uint32();
+            switch (t >>> 3) {
+            case 1:
+                m.publicKey = r.bytes();
+                break;
+            case 2:
+                m.payloadType = r.bytes();
+                break;
+            case 3:
+                m.payload = r.bytes();
+                break;
+            case 5:
+                m.signature = r.bytes();
+                break;
+            default:
+                r.skipType(t & 7);
+                break;
+            }
+        }
+        return m;
+    };
+
+    /**
+     * Creates an Envelope message from a plain object. Also converts values to their respective internal types.
+     * @function fromObject
+     * @memberof Envelope
+     * @static
+     * @param {Object.<string,*>} d Plain object
+     * @returns {Envelope} Envelope
+     */
+    Envelope.fromObject = function fromObject(d) {
+        if (d instanceof $root.Envelope)
+            return d;
+        var m = new $root.Envelope();
+        if (d.publicKey != null) {
+            if (typeof d.publicKey === "string")
+                $util.base64.decode(d.publicKey, m.publicKey = $util.newBuffer($util.base64.length(d.publicKey)), 0);
+            else if (d.publicKey.length)
+                m.publicKey = d.publicKey;
+        }
+        if (d.payloadType != null) {
+            if (typeof d.payloadType === "string")
+                $util.base64.decode(d.payloadType, m.payloadType = $util.newBuffer($util.base64.length(d.payloadType)), 0);
+            else if (d.payloadType.length)
+                m.payloadType = d.payloadType;
+        }
+        if (d.payload != null) {
+            if (typeof d.payload === "string")
+                $util.base64.decode(d.payload, m.payload = $util.newBuffer($util.base64.length(d.payload)), 0);
+            else if (d.payload.length)
+                m.payload = d.payload;
+        }
+        if (d.signature != null) {
+            if (typeof d.signature === "string")
+                $util.base64.decode(d.signature, m.signature = $util.newBuffer($util.base64.length(d.signature)), 0);
+            else if (d.signature.length)
+                m.signature = d.signature;
+        }
+        return m;
+    };
+
+    /**
+     * Creates a plain object from an Envelope message. Also converts values to other types if specified.
+     * @function toObject
+     * @memberof Envelope
+     * @static
+     * @param {Envelope} m Envelope
+     * @param {$protobuf.IConversionOptions} [o] Conversion options
+     * @returns {Object.<string,*>} Plain object
+     */
+    Envelope.toObject = function toObject(m, o) {
+        if (!o)
+            o = {};
+        var d = {};
+        if (o.defaults) {
+            if (o.bytes === String)
+                d.publicKey = "";
+            else {
+                d.publicKey = [];
+                if (o.bytes !== Array)
+                    d.publicKey = $util.newBuffer(d.publicKey);
+            }
+            if (o.bytes === String)
+                d.payloadType = "";
+            else {
+                d.payloadType = [];
+                if (o.bytes !== Array)
+                    d.payloadType = $util.newBuffer(d.payloadType);
+            }
+            if (o.bytes === String)
+                d.payload = "";
+            else {
+                d.payload = [];
+                if (o.bytes !== Array)
+                    d.payload = $util.newBuffer(d.payload);
+            }
+            if (o.bytes === String)
+                d.signature = "";
+            else {
+                d.signature = [];
+                if (o.bytes !== Array)
+                    d.signature = $util.newBuffer(d.signature);
+            }
+        }
+        if (m.publicKey != null && m.hasOwnProperty("publicKey")) {
+            d.publicKey = o.bytes === String ? $util.base64.encode(m.publicKey, 0, m.publicKey.length) : o.bytes === Array ? Array.prototype.slice.call(m.publicKey) : m.publicKey;
+        }
+        if (m.payloadType != null && m.hasOwnProperty("payloadType")) {
+            d.payloadType = o.bytes === String ? $util.base64.encode(m.payloadType, 0, m.payloadType.length) : o.bytes === Array ? Array.prototype.slice.call(m.payloadType) : m.payloadType;
+        }
+        if (m.payload != null && m.hasOwnProperty("payload")) {
+            d.payload = o.bytes === String ? $util.base64.encode(m.payload, 0, m.payload.length) : o.bytes === Array ? Array.prototype.slice.call(m.payload) : m.payload;
+        }
+        if (m.signature != null && m.hasOwnProperty("signature")) {
+            d.signature = o.bytes === String ? $util.base64.encode(m.signature, 0, m.signature.length) : o.bytes === Array ? Array.prototype.slice.call(m.signature) : m.signature;
+        }
+        return d;
+    };
+
+    /**
+     * Converts this Envelope to JSON.
+     * @function toJSON
+     * @memberof Envelope
+     * @instance
+     * @returns {Object.<string,*>} JSON object
+     */
+    Envelope.prototype.toJSON = function toJSON() {
+        return this.constructor.toObject(this, $protobuf.util.toJSONOptions);
+    };
+
+    return Envelope;
+})();
+
+export { $root as default };

package/src/envelope/envelope.proto

@@ -0,0 +1,19 @@
+syntax = "proto3";
+
+message Envelope {
+  // public_key is the public key of the keypair the enclosed payload was
+  // signed with.
+  bytes public_key = 1;
+
+  // payload_type encodes the type of payload, so that it can be deserialized
+  // deterministically.
+  bytes payload_type = 2;
+
+  // payload is the actual payload carried inside this envelope.
+  bytes payload = 3;
+
+  // signature is the signature produced by the private key corresponding to
+  // the enclosed public key, over the payload, prefixing a domain string for
+  // additional security.
+  bytes signature = 5;
+}

package/src/envelope/index.ts

@@ -0,0 +1,159 @@
+import errCode from 'err-code'
+import { concat as uint8arraysConcat } from 'uint8arrays/concat'
+import { fromString as uint8arraysFromString }from 'uint8arrays/from-string'
+import { unmarshalPrivateKey, unmarshalPublicKey } from '@libp2p/crypto/keys'
+import varint from 'varint'
+import { equals as uint8arraysEquals } from 'uint8arrays/equals'
+import { codes } from '../errors.js'
+import { Envelope as Protobuf } from './envelope.js'
+import { PeerId } from '@libp2p/peer-id'
+import type { Record, Envelope } from '@libp2p/interfaces/record'
+
+export interface EnvelopeOptions {
+  peerId: PeerId
+  payloadType: Uint8Array
+  payload: Uint8Array
+  signature: Uint8Array
+}
+
+export class RecordEnvelope implements Envelope {
+  /**
+   * Unmarshal a serialized Envelope protobuf message
+   */
+  static createFromProtobuf = async (data: Uint8Array) => {
+    const envelopeData = Protobuf.decode(data)
+    const peerId = await PeerId.fromKeys(envelopeData.publicKey)
+
+    return new RecordEnvelope({
+      peerId,
+      payloadType: envelopeData.payloadType,
+      payload: envelopeData.payload,
+      signature: envelopeData.signature
+    })
+  }
+
+  /**
+   * Seal marshals the given Record, places the marshaled bytes inside an Envelope
+   * and signs it with the given peerId's private key
+   */
+  static seal = async (record: Record, peerId: PeerId) => {
+    const domain = record.domain
+    const payloadType = record.codec
+    const payload = record.marshal()
+
+    const signData = formatSignaturePayload(domain, payloadType, payload)
+
+    if (peerId.privateKey == null) {
+      throw new Error('Missing private key')
+    }
+
+    const key = await unmarshalPrivateKey(peerId.privateKey)
+    const signature = await key.sign(signData)
+
+    return new RecordEnvelope({
+      peerId,
+      payloadType,
+      payload,
+      signature
+    })
+  }
+
+  /**
+   * Open and certify a given marshalled envelope.
+   * Data is unmarshalled and the signature validated for the given domain.
+   */
+  static openAndCertify = async (data: Uint8Array, domain: string) => {
+    const envelope = await RecordEnvelope.createFromProtobuf(data)
+    const valid = await envelope.validate(domain)
+
+    if (!valid) {
+      throw errCode(new Error('envelope signature is not valid for the given domain'), codes.ERR_SIGNATURE_NOT_VALID)
+    }
+
+    return envelope
+  }
+
+  public peerId: PeerId
+  public payloadType: Uint8Array
+  public payload: Uint8Array
+  public signature: Uint8Array
+  public marshaled?: Uint8Array
+
+  /**
+   * The Envelope is responsible for keeping an arbitrary signed record
+   * by a libp2p peer.
+   */
+  constructor (options: EnvelopeOptions) {
+    const { peerId, payloadType, payload, signature } = options
+
+    this.peerId = peerId
+    this.payloadType = payloadType
+    this.payload = payload
+    this.signature = signature
+  }
+
+  /**
+   * Marshal the envelope content
+   */
+  marshal () {
+    if (this.marshaled == null) {
+      this.marshaled = Protobuf.encode({
+        publicKey: this.peerId.publicKey,
+        payloadType: this.payloadType,
+        payload: this.payload,
+        signature: this.signature
+      }).finish()
+    }
+
+    return this.marshaled
+  }
+
+  /**
+   * Verifies if the other Envelope is identical to this one
+   */
+  equals (other: Envelope) {
+    return uint8arraysEquals(this.marshal(), other.marshal())
+  }
+
+  /**
+   * Validate envelope data signature for the given domain
+   */
+  validate (domain: string) {
+    const signData = formatSignaturePayload(domain, this.payloadType, this.payload)
+
+    if (this.peerId.publicKey == null) {
+      throw new Error('Missing public key')
+    }
+
+    const key = unmarshalPublicKey(this.peerId.publicKey)
+
+    return key.verify(signData, this.signature)
+  }
+}
+
+/**
+ * Helper function that prepares a Uint8Array to sign or verify a signature
+ */
+const formatSignaturePayload = (domain: string, payloadType: Uint8Array, payload: Uint8Array) => {
+  // When signing, a peer will prepare a Uint8Array by concatenating the following:
+  // - The length of the domain separation string string in bytes
+  // - The domain separation string, encoded as UTF-8
+  // - The length of the payload_type field in bytes
+  // - The value of the payload_type field
+  // - The length of the payload field in bytes
+  // - The value of the payload field
+
+  const domainUint8Array = uint8arraysFromString(domain)
+  const domainLength = varint.encode(domainUint8Array.byteLength)
+  const payloadTypeLength = varint.encode(payloadType.length)
+  const payloadLength = varint.encode(payload.length)
+
+  return uint8arraysConcat([
+    new Uint8Array(domainLength),
+    domainUint8Array,
+    new Uint8Array(payloadTypeLength),
+    payloadType,
+    new Uint8Array(payloadLength),
+    payload
+  ])
+}

package/src/errors.ts

@@ -0,0 +1,4 @@
+
+export const codes = {
+  ERR_SIGNATURE_NOT_VALID: 'ERR_SIGNATURE_NOT_VALID'
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+
+export { RecordEnvelope } from './envelope/index.js'
+export { PeerRecord } from './peer-record/index.js'

package/src/peer-record/consts.js

@@ -0,0 +1,9 @@
+
+// The domain string used for peer records contained in a Envelope.
+export const ENVELOPE_DOMAIN_PEER_RECORD = 'libp2p-peer-record'
+
+// The type hint used to identify peer records in a Envelope.
+// Defined in https://github.com/multiformats/multicodec/blob/master/table.csv
+// with name "libp2p-peer-record"
+export const ENVELOPE_PAYLOAD_TYPE_PEER_RECORD = Uint8Array.from([3, 1])
+