@mapeo/crypto v1.0.0-alpha.8
@mapeo/crypto
Key management and encryption / decryption functions for Mapeo.
Table of Contents
API
KeyManager
const { KeyManager } = require('@mapeo/crypto')
const km = new KeyManager(identityKey)
The KeyManager class derives the key pairs used for identifying the device and for all the hypercores on the device. All the key pairs are generated deterministically from a single 16-byte identity key. The backup code can be used to backup this identity and recover it on a new device. The identity key and backup code must be kept secret at all times - someone who has this key can impersonate the user to another Mapeo user.
Parameters
identityKey: Buffer
16-bytes of random data that uniquely identify the device, used to derive a 32-byte master key, which is used to derive all the keypairs used for Mapeo
km.getIdentityKeypair()
Generate a deterministic ed25519 signing keypair that uniquely identifies this device. Used for identifying the device on the network to other peers.
Returns { publicKey: Buffer, secretKey: Buffer }
km.getIdentityBackupCode()
Generate a backup code for the identityKey
. The backup code will be a
30-character string, starting with the letter M
. It encodes the identity key
and can be used to recover the identity key on another device. It should be
treated as a secure password: someone with access to a backup code can
impersonate the identity of the holder.
Returns string
km.getHypercoreKeypair(name, namespace)
Generate a deterministic signing keypair for a given project key and name. API compatible with Corestore-next.
Parameters
name: string
Local name for the keypairnamespace: Buffer
32-byte namespace
Returns { publicKey: Buffer, secretKey: Buffer }
KeyManager.generateIdentityKey()
Static method to generate a new random identity key. This is used to derive a master key: all keys are deterministically derived from this identity key, so this should only be used once on each device and the key should be securely stored.
Returns 16-byte Buffer
of random data
KeyManager.decodeBackupCode(backupCode)
Static method to decode an identity key from a backup code. Throws an error if the CRC check fails.
Parameters
backupCode: string
30-character base32 encoded backup code
Returns Buffer
The 16-byte identity key encoded in the backup code
Project Invites
const { invites } = require('@mapeo/crypto`)
Functions for generating project join requests and responding with an encrypted invite.
invites.encodeJoinRequest(joinRequest, options)
Encode a join request encoded to a string for use in a QR code or a URL. A
join request includes (unencrypted) the identity public key of the device
sending the join request. The optional name
is used to give context to the
receiver of the join request. It is unencrypted, so the user should not
reveal secret information in this field, or should ensure that the join
request is sent via a secure channel.
base32
is used for a QR code because it enables alphanumeric encoding
(uppercase A-Z, 0-9) which is more compact. base62
is used for URLs, rather
than base64
, because symbols like +
can break URL parsing (e.g. in an SMS
message, only part of a URL before a +
might be clickable).
Parameters
joinRequest
JoinRequest A join request messageoptions: object
options.encoding: 'base32' | 'base62'
Use base32 if using for an alphanumeric encoded QR Code (uppercase A-Z, 0-9), or base62 for a URL.
Returns string
Encoded join request
invites.decodeJoinRequest(str, options)
Decode a join request from a string-encoded join request. Will throw if the string does not encode a valid join request message.
Parameters
str: string
Join request encoded as a stringoptions: object
options.encoding: 'base32' | 'base62'
Use base32 if using for an alphanumeric encoded QR Code (uppercase A-Z, 0-9), or base62 for a URL.
Returns JoinRequest Decoded join request
invites.generateInvite(joinRequest, options)
Generate an encrypted invite encoded as a string for use in a QR code or a URL. Invites are encrypted and can only be decrypted by the owner of the private key associated with the identity public key sent in the join request.
base32
is used for a QR code because it enables alphanumeric encoding
(uppercase A-Z, 0-9) which is more compact. base62
is used for URLs, rather
than base64
, because symbols like +
can break URL parsing (e.g. in an SMS
message, only part of a URL before a +
might be clickable).
Parameters
joinRequest: JoinRequest
options
options.encoding: 'base32' | 'base62'
Use base32 if using for an alphanumeric encoded QR Code (uppercase A-Z, 0-9), or base62 for a URL.options.projectKey: Buffer
Project key for project you wish to generate the invite for[options.encryptionKey: Buffer]
Optional encryption key, used for on-disk encryption/decryption of an encrypted project.
Returns string
Encoded invite
invites.decodeInviteSecretMessage(invite, identityPublicKey, identitySecretKey, options)
Decode and decrypt an invite secret message from a string-encoded invite. The decrypted message includes the project key for the project the invite is for.
Parameters
invite: string
Invite encoded as a stringidentityPublicKey: Buffer
32-byte signing public key for the device receiving the inviteidentitySecretKey: Buffer
32-byte signing secret key for the device receiving the inviteoptions
options.encoding: 'base32' | 'base62'
Use base32 if using for an alphanumeric encoded QR Code (uppercase A-Z, 0-9), or base62 for a URL.
Returns { projectKey: Buffer, encryptionKey?: Buffer }
Decrypted secret project key and optional encryption key.
Type JoinRequest
{
identityPublicKey: Buffer,
host?: { host: string, port: number },
name?: string
}
8 months ago
8 months ago
7 months ago
9 months ago
7 months ago
8 months ago
1 year ago
1 year ago
2 years ago
2 years ago