API reference

@wellknown-id/mailbox

A mailbox that keeps ciphertext under ids its writers choose, and answers anyone who knows an id: wellknown.id's relay runs one, and a site that accepts delegation may run its own. It can't read what it holds, tell whose it is or link one id to another, logs nothing, and throws away what's extinct. Mount mailboxHandler in a server of your own, or run createMailboxServer (or the wellknown-mailbox command).

Classes

NoMail

There's no mail provider: nothing can be sent.

Extends

  • Error

Constructors

Constructor
new NoMail(): NoMail;
Returns

NoMail

Overrides
Error.constructor

Interfaces

MailboxStorage

What a mailbox keeps, as text by kind and id. Synchronous, so a request reads and writes without interleaving.

Methods

delete()
delete(kind, id): void;
Parameters
ParameterType
kindKind
idstring
Returns

void

get()
get(kind, id): string | undefined;
Parameters
ParameterType
kindKind
idstring
Returns

string | undefined

ids()
ids(kind): Iterable<string>;

Every id held of a kind (for counting what's held at start, and for garbage collection).

Parameters
ParameterType
kindKind
Returns

Iterable<string>

put()
put(
   kind, 
   id, 
   text
): void;
Parameters
ParameterType
kindKind
idstring
textstring
Returns

void

size()
size(kind, id): number;

The bytes held under an id, 0 for none.

Parameters
ParameterType
kindKind
idstring
Returns

number


MailPort

Sends email. Rejects where it couldn't (the route answers 502); NoMail where there's no provider at all (503).

Methods

send()
send(message): Promise<void>;
Parameters
ParameterType
messageMailMessage
Returns

Promise<void>

Type Aliases

Directory

type Directory = ReturnType<typeof createDirectory>;

DirectoryHandler

type DirectoryHandler = (req, res) => void & object;

Type Declaration

NameType
close()() => void
route()(url) => boolean

DirectoryLimits

type DirectoryLimits = typeof DIRECTORY_LIMITS;

DirectoryOptions

type DirectoryOptions = object;

Properties

PropertyTypeDescription
collectstringWhere case 2's email links to: the key goes after the '#'.
keyUint8ArrayThe OPRF key (32 bytes, a ristretto255 scalar's seed: directoryKey), made once and kept.
limits?DirectoryLimits-
mailMailPortThe email port (mail.ts).
now?() => number-
storageMailboxStorageWhere entries are kept (kind 'store' of a storage of the directory's own: apps/relay keeps files under its volume).
store?Pick<Mailbox, "get" | "post">The mailbox whose store holds case 2's parcels and whose inboxes hold the wallets' (core.ts): a parcel is checked there before its email goes, and a re-link's notice left there. None: the persona email is refused (503), and no notice is left.

GcOptions

type GcOptions = object;

When garbage collection runs: every intervalMs (0: never by the clock), and after every everyRequests requests (0: never).

Properties

PropertyType
batchnumber
everyRequestsnumber
intervalMsnumber

Kind

type Kind = "store" | "box" | "drop";

What a mailbox keeps: blobs (store), records boxes (box) and drop boxes (drop).


Mailbox

type Mailbox = object;

A mailbox: its API's requests as calls, answered as status and body, whatever carries them.

Properties

PropertyTypeDescription
maxBodynumberThe most a POST's body may be: a carrier stops reading past it.

Methods

close()
close(): void;

Stops the clock that runs garbage collection, and the write buckets' sweep.

Returns

void

gc()
gc(): Promise<number>;

Runs garbage collection now (or joins the run under way); resolves with how many ids it threw away.

Returns

Promise<number>

get()
get(
   kind, 
   id, 
   after?, 
   query?
): MailboxAnswer;

GET {kind}/{id}, after: from the query (box and drop); query: a store blob's versions, or one of them (at).

Parameters
ParameterType
kindKind
idstring
after?string | null
query?{ at?: string | null; versions?: boolean; }
query.at?string | null
query.versions?boolean
Returns

MailboxAnswer

post()
post(
   kind, 
   id, 
   body, 
   client
): MailboxAnswer;

POST {kind}/{id} with body (the request's text) from client (for its write bucket: an address, or an IPv6 /64).

Parameters
ParameterType
kindKind
idstring
bodystring
clientstring
Returns

MailboxAnswer

route()
route(kind, id): kind is Kind;

Whether {kind}/{id} names something the API serves (anything else is 404 "not here").

Parameters
ParameterType
kindstring | undefined
idstring | undefined
Returns

kind is Kind

seen()
seen(): void;

Counts a request toward garbage collection by requests (gc.everyRequests).

Returns

void


MailboxAnswer

type MailboxAnswer = object;

What the mailbox answers: an HTTP status and a JSON body.

Properties

PropertyType
bodyobject
statusnumber

MailboxCoreOptions

type MailboxCoreOptions = object;

How a mailbox is made: where it keeps things and its limits. (Who may use it from a web page is the HTTP side's: ./http.ts.)

Properties

PropertyTypeDescription
freeBytes?() => numberFree bytes on the disk the storage writes to (Infinity, for storage that isn't a disk).
gc?Partial<GcOptions>When garbage collection runs (GC_DEFAULTS by default).
limits?StoreLimitsIts limits (STORE_LIMITS by default).
now?() => numberThe time, in milliseconds; tests move it.
storageMailboxStorageWhere it keeps what it's given (fileStorage, memoryStorage, or your own).

MailboxHandler

type MailboxHandler = (req, res) => void & object;

A Node HTTP request handler answering the mailbox's API, with garbage collection on demand and a way to stop.

Type Declaration

NameTypeDescription
mailboxMailboxIts rules (core.ts), for a neighbour on the same server: wellknown.id's directory checks a parcel there.
close()() => voidStops the clock that runs garbage collection, and the write buckets' sweep.
gc()() => Promise<number>Runs garbage collection now (or joins the run under way); resolves with how many ids it threw away.

MailboxOptions

type MailboxOptions = MailboxCoreOptions & object;

How a mailbox is made: where it keeps things, who may use it from a web page, and its limits.

Type Declaration

NameTypeDescription
origins?string[]Web pages that may use it (CORS), by origin.
prefix?stringThe path it answers under: '/relay' on wellknown.id's relay.

MailMessage

type MailMessage = object;

One email: to whom, its subject and its plain text (no HTML: nothing to track with, no links rewritten).

Properties

PropertyType
subjectstring
textstring
tostring

ServerOptions

type ServerOptions = Partial<Omit<MailboxOptions, "storage">> & object;

A mailbox server's options: the mailbox's own (MailboxOptions, but storage), and a directory to keep files in.

Type Declaration

NameTypeDescription
dir?stringA directory to keep files in; in memory without one.

StoreLimits

type StoreLimits = typeof STORE_LIMITS;

A mailbox's limits (STORE_LIMITS has the defaults and what each is for).

Variables

DIRECTORY_LIMITS

const DIRECTORY_LIMITS: object;

The directory's limits: how long a code lasts, wrong codes allowed, and the brakes per client and per address.

Type Declaration

NameTypeDefault value
addressBurstnumber3
addressPerHournumber2
codeMsnumber-
codeTriesnumber5
evaluateBurstnumber30
evaluatePerMinutenumber30
keepDaysnumber30
maxClientsnumber100_000
recordBytesnumber1024
sendBurstnumber5
sendPerHournumber6

GC_DEFAULTS

const GC_DEFAULTS: GcOptions;

Garbage collection by default: hourly, and after every 1000 requests, 200 ids at a time.


KINDS

const KINDS: readonly Kind[];

Every kind, in the order storage lists them.


noMail

const noMail: MailPort;

No provider (a relay without SMTP set): every send refused.


STORE_LIMITS

const STORE_LIMITS: object;

The default limits: sizes per blob, records entry and drop-box item, what's held in all, and writes per client.

Type Declaration

NameTypeDefault value
blobBytesnumber-
depositsBurstnumber10
depositsPerMinutenumber1
dropDaysnumber30
entriesPerBoxnumber5000
entryBytesnumber-
inboxItemBytesnumber-
itemBytesnumber-
itemsPerDropnumber2000
itemsPerInboxnumber500
maxClientsnumber100_000
maxLifetimeDaysnumber400
maxTotalBytesnumber-
minFreeBytesnumber-
onceBurstnumber400
onceBytesnumber-
oncePerMinutenumber30
recoveryKeysnumber1
recoverySkewSnumber300
versionDaysnumber30
versionsnumber80
writesBurstnumber120
writesPerSecondnumber2

Functions

clientOf()

function clientOf(req): string;

Which client a request is from, for its bucket only: the address the nearest proxy saw (the rightmost X-Forwarded-For).

Parameters

ParameterType
reqIncomingMessage

Returns

string


consoleMail()

function consoleMail(log?): MailPort;

A development relay's mail: each message written to the console, for the developer, with any link's key withheld (review R13-9: a development relay may be behind a tunnel, and its console isn't the holder's). The six-digit code that links an address is shown: it's what a developer types back. Never in production.

Parameters

ParameterType
log(line) => void

Returns

MailPort


createDirectory()

function createDirectory(opts): object;

The directory's rules: each request as a call, answered as status and body.

Parameters

ParameterType
optsDirectoryOptions

Returns

NameTypeDefault valueDescription
limitsobject--
limits.addressBurstnumber3-
limits.addressPerHournumber2-
limits.codeMsnumber--
limits.codeTriesnumber5-
limits.evaluateBurstnumber30-
limits.evaluatePerMinutenumber30-
limits.keepDaysnumber30-
limits.maxClientsnumber100_000-
limits.recordBytesnumber1024-
limits.sendBurstnumber5-
limits.sendPerHournumber6-
route()(path) => boolean-Every path it answers, under its prefix: directory/... and mail/persona.
close()() => void--
get()(path) => MailboxAnswer--
post()( path, body, client ) => Promise<MailboxAnswer>--

createMailbox()

function createMailbox(opts): Mailbox;

The mailbox's rules over storage.

Parameters

ParameterType
optsMailboxCoreOptions

Returns

Mailbox


createMailboxServer()

function createMailboxServer(opts?): Server<typeof IncomingMessage, typeof ServerResponse> & object;

A server answering the mailbox's API (and GET {prefix}/health), not yet listening.

Parameters

ParameterType
optsServerOptions

Returns

Server<typeof IncomingMessage, typeof ServerResponse> & object


directoryHandler()

function directoryHandler(opts): DirectoryHandler;

The directory's HTTP handler; route(url) says whether a request's path is the directory's.

Parameters

ParameterType
optsDirectoryOptions & object

Returns

DirectoryHandler


directoryKey()

function directoryKey(seed): ScalarBytes & Uint8Array<ArrayBuffer>;

The directory's OPRF key from a 32-byte seed (RFC 9497 DeriveKeyPair, info "wellknown.id directory"): the seed is what's kept on the volume.

Parameters

ParameterType
seedUint8Array

Returns

ScalarBytes & Uint8Array<ArrayBuffer>


fakeMail()

function fakeMail(): MailPort & object;

Tests' mail: kept in sent, in order.

Returns

MailPort & object


fileStorage()

function fileStorage(dir): MailboxStorage;

Storage in files under dir: {dir}/{kind}/{id}.json, each written whole (to a temporary file, then renamed).

Parameters

ParameterType
dirstring

Returns

MailboxStorage


mailboxHandler()

function mailboxHandler(opts): MailboxHandler;

The mailbox's HTTP handler.

Parameters

ParameterType
optsMailboxOptions

Returns

MailboxHandler


memoryStorage()

function memoryStorage(): MailboxStorage;

Storage in memory: gone when the process ends.

Returns

MailboxStorage


normaliseAddress()

function normaliseAddress(address): string | undefined;

An address as the directory takes it: trimmed, NFC, lower case. Undefined if it isn't an address.

Parameters

ParameterType
addressstring

Returns

string | undefined


parcelProof()

function parcelProof(sealed): string;

What a persona email's request proves its parcel with: a hash of the parcel's sealed bytes (the wallet's borrowed.ts says the same).

Parameters

ParameterType
sealedUint8Array

Returns

string


recoveryMessage()

function recoveryMessage(
   id, 
   action, 
   iat, 
   extra?
): Uint8Array<ArrayBufferLike>;

What a recovery signature signs (the header): the same bytes on every side (the wallet's recovery-keys.ts).

Parameters

ParameterTypeDefault value
idstringundefined
actionstringundefined
iatnumberundefined
extrastring''

Returns

Uint8Array<ArrayBufferLike>


signedExtra()

function signedExtra(action, o): string;

A signed action's extra, beyond a retirement's note (the header): the data's SHA-256 (base64url), and the keys.

Parameters

ParameterType
action"file" | "put" | "rekey"
o{ data?: string; keys?: readonly string[]; }
o.data?string
o.keys?readonly string[]

Returns

string


thinVersions()

function thinVersions(
   older, 
   now, 
   max, 
   days
): object[];

The versions a blob kept with them holds (the header): those of the last days; past max, the latest of each of the last 48 hours and the latest of each day, together (a version can be both), then at most max, the newest kept. So a run of writes (a thief's, before the holder freezes it) pushes out at most what was written earlier in its own hour (review R8-41), and a sustained one (a write an hour, for days) never the days before it: the hours take 48 at most, the days days + 1, and max holds both (review R9-30: past 50, the hours left room for two days, so an hourly run of four days left no version from before it). Oldest first.

Parameters

ParameterType
olderreadonly object[]
nownumber
maxnumber
daysnumber

Returns

object[]


withheld()

function withheld(text): string;

A message's text with every link's fragment (a persona link's key) withheld.

Parameters

ParameterType
textstring

Returns

string


writeBuckets()

function writeBuckets(limits, now?): object;

Token buckets by client, in memory only; full buckets are forgotten.

Parameters

ParameterType
limitsPick<StoreLimits, "writesBurst" | "writesPerSecond" | "maxClients">
now() => number

Returns

NameTypeDescription
close()() => void-
size()() => number-
take()(client) => booleanTakes a token from client's bucket; false when it's empty.