pubky-core/pubky/pkg/README.md

Pubky

JavaScript implementation of Pubky client.

Table of Contents

• Install
• Getting Started
• API
• Test and Development

Install

npm install @synonymdev/pubky

Prerequisites

For Nodejs, you need Node v20 or later.

Getting started

import { Client, Keypair, PublicKey } from '../index.js'

// Initialize Client with Pkarr relay(s).
let client = new Client();

// 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 Client();

    let response = await client.get(url);
}

// Delete public data, by authorized client
await client.delete(url);

API

Client

constructor

let client = new Client()

signup

await client.signup(keypair, homeserver)

• keypair: An instance of Keypair.
• homeserver: An instance of PublicKey representing the 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

let session = await client.session(publicKey)

• publicKey: An instance of PublicKey.
• Returns: A Session object if signed in, or undefined if not.

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 if NOT_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

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 Client

import { Client } from '../index.js'

const client = Client().testnet();