@synonymdev/pubky
v0.2.1
Published
Pubky client
Downloads
940
Readme
Pubky
JavaScript implementation of Pubky.
Table of Contents
Install
npm install @synonymdev/pubky
Prerequisites
For Nodejs, you need Node v20 or later.
Getting started
import { PubkyClient, Keypair, PublicKey } from '../index.js'
// Initialize PubkyClient with Pkarr relay(s).
let client = new PubkyClient();
// Generate a keypair
let keypair = Keypair.random();
// Create a new account
let homeserver = PublicKey.from("8pinxxgqs41n4aididenw5apqp1urfmzdztr8jt4abrkdn435ewo");
await client.signup(keypair, homeserver)
const publicKey = keypair.publicKey();
// Pubky URL
let url = `pubky://${publicKey.z32()}/pub/example.com/arbitrary`;
// Verify that you are signed in.
const session = await client.session(publicKey)
const body = Buffer.from(JSON.stringify({ foo: 'bar' }))
// PUT public data, by authorized client
await client.put(url, body);
// GET public data without signup or signin
{
const client = new PubkyClient();
let response = await client.get(url);
}
// Delete public data, by authorized client
await client.delete(url);
API
PubkyClient
constructor
let client = new PubkyClient()
signup
await client.signup(keypair, homeserver)
Returns:
- session: An instance of Session.
signin
let session = await client.signin(keypair)
- keypair: An instance of Keypair.
Returns:
- An instance of Session.
signout
await client.signout(publicKey)
- publicKey: An instance of PublicKey.
authRequest
let [pubkyauthUrl, sessionPromise] = client.authRequest(relay, capabilities);
showQr(pubkyauthUrl);
let pubky = await sessionPromise;
Sign in to a user's Homeserver, without access to their Keypair, nor even PublicKey, instead request permissions (showing the user pubkyauthUrl), and await a Session after the user consenting to that request.
- relay: A URL to an HTTP relay endpoint.
- capabilities: A list of capabilities required for the app for example
/pub/pubky.app/:rw,/pub/example.com/:r
.
Returns:
- pubkyauthUrl: A url to show to the user to scan or paste into an Authenticator app holding the user Keypair
- sessionPromise: A promise that resolves into a PublicKey on success, which you can use in
client.session(pubky)
to resolve more information about the Session.
sendAuthToken
await client.sendAuthToken(keypair, pubkyauthUrl);
Consenting to authentication or authorization according to the required capabilities in the pubkyauthUrl
, and sign and send an auth token to the requester.
- keypair: An instance of KeyPair
- pubkyauthUrl: A string
pubkyauth://
url
session {#session-method}
let session = await client.session(publicKey)
put
let response = await client.put(url, body);
- url: A string representing the Pubky URL.
- body: A Buffer containing the data to be stored.
get
let response = await client.get(url)
- url: A string representing the Pubky URL.
- Returns: A Uint8Array object containing the requested data, or
undefined
ifNOT_FOUND
.
delete
let response = await client.delete(url);
- url: A string representing the Pubky URL.
list
let response = await client.list(url, cursor, reverse, limit)
- url: A string representing the Pubky URL. The path in that url is the prefix that you want to list files within.
- cursor: Usually the last URL from previous calls. List urls after/before (depending on
reverse
) the cursor. - reverse: Whether or not return urls in reverse order.
- limit: Number of urls to return.
- Returns: A list of URLs of the files in the
url
you passed.
Keypair
random
let keypair = Keypair.random()
- Returns: A new random Keypair.
fromSecretKey
let keypair = Keypair.fromSecretKey(secretKey)
- secretKey: A 32 bytes Uint8array.
- Returns: A new Keypair.
publicKey {#publickey-method}
let publicKey = keypair.publicKey()
- Returns: The PublicKey associated with the Keypair.
secretKey
let secretKey = keypair.secretKey()
- Returns: The Uint8array secret key associated with the Keypair.
PublicKey
from
let publicKey = PublicKey.from(string);
- string: A string representing the public key.
- Returns: A new PublicKey instance.
z32
let pubky = publicKey.z32();
Returns: The z-base-32 encoded string representation of the PublicKey.
Session
pubky
let pubky = session.pubky();
Returns an instance of PublicKey
capabilities
let capabilities = session.capabilities();
Returns an array of capabilities, for example ["/pub/pubky.app/:rw"]
Helper functions
createRecoveryFile
let recoveryFile = createRecoveryFile(keypair, passphrase)
- keypair: An instance of Keypair.
- passphrase: A utf-8 string passphrase.
- Returns: A recovery file with a spec line and an encrypted secret key.
createRecoveryFile
let keypair = decryptRecoveryfile(recoveryFile, passphrase)
- recoveryFile: An instance of Uint8Array containing the recovery file blob.
- passphrase: A utf-8 string passphrase.
- Returns: An instance of Keypair.
Test and Development
For test and development, you can run a local homeserver in a test network.
If you don't have Cargo Installed, start by installing it:
curl https://sh.rustup.rs -sSf | sh
Clone the Pubky repository:
git clone https://github.com/pubky/pubky
cd pubky/pkg
Run the local testnet server
npm run testnet
Use the logged addresses as inputs to PubkyClient
import { PubkyClient } from '../index.js'
const client = PubkyClient().testnet();