Classes
NoMail
There's no mail provider: nothing can be sent.
Extends
Error
Constructors
Constructor
new NoMail(): NoMail;
Returns
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
| Parameter | Type |
|---|---|
kind | Kind |
id | string |
Returns
void
get()
get(kind, id): string | undefined;
Parameters
| Parameter | Type |
|---|---|
kind | Kind |
id | string |
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
| Parameter | Type |
|---|---|
kind | Kind |
Returns
Iterable<string>
put()
put( kind, id, text ): void;
Parameters
| Parameter | Type |
|---|---|
kind | Kind |
id | string |
text | string |
Returns
void
size()
size(kind, id): number;
The bytes held under an id, 0 for none.
Parameters
| Parameter | Type |
|---|---|
kind | Kind |
id | string |
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
| Parameter | Type |
|---|---|
message | MailMessage |
Returns
Promise<void>
Type Aliases
Directory
type Directory = ReturnType<typeof createDirectory>;
DirectoryHandler
type DirectoryHandler = (req, res) => void & object;
Type Declaration
| Name | Type |
|---|---|
close() | () => void |
route() | (url) => boolean |
DirectoryLimits
type DirectoryLimits = typeof DIRECTORY_LIMITS;
DirectoryOptions
type DirectoryOptions = object;
Properties
| Property | Type | Description |
|---|---|---|
collect | string | Where case 2's email links to: the key goes after the '#'. |
key | Uint8Array | The OPRF key (32 bytes, a ristretto255 scalar's seed: directoryKey), made once and kept. |
limits? | DirectoryLimits | - |
mail | MailPort | The email port (mail.ts). |
now? | () => number | - |
storage | MailboxStorage | Where 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
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
| Property | Type | Description |
|---|---|---|
maxBody | number | The 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
| Parameter | Type |
|---|---|
kind | Kind |
id | string |
after? | string | null |
query? | { at?: string | null; versions?: boolean; } |
query.at? | string | null |
query.versions? | boolean |
Returns
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
| Parameter | Type |
|---|---|
kind | Kind |
id | string |
body | string |
client | string |
Returns
route()
route(kind, id): kind is Kind;
Whether {kind}/{id} names something the API serves (anything else is 404 "not here").
Parameters
| Parameter | Type |
|---|---|
kind | string | undefined |
id | string | 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
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
| Property | Type | Description |
|---|---|---|
freeBytes? | () => number | Free 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? | StoreLimits | Its limits (STORE_LIMITS by default). |
now? | () => number | The time, in milliseconds; tests move it. |
storage | MailboxStorage | Where 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
| Name | Type | Description |
|---|---|---|
mailbox | Mailbox | Its rules (core.ts), for a neighbour on the same server: wellknown.id's directory checks a parcel there. |
close() | () => void | Stops 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
| Name | Type | Description |
|---|---|---|
origins? | string[] | Web pages that may use it (CORS), by origin. |
prefix? | string | The 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
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
| Name | Type | Description |
|---|---|---|
dir? | string | A 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
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
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
| Parameter | Type |
|---|---|
req | IncomingMessage |
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
| Parameter | Type |
|---|---|
log | (line) => void |
Returns
createDirectory()
function createDirectory(opts): object;
The directory's rules: each request as a call, answered as status and body.
Parameters
| Parameter | Type |
|---|---|
opts | DirectoryOptions |
Returns
| Name | Type | Default value | Description |
|---|---|---|---|
limits | object | - | - |
limits.addressBurst | number | 3 | - |
limits.addressPerHour | number | 2 | - |
limits.codeMs | number | - | - |
limits.codeTries | number | 5 | - |
limits.evaluateBurst | number | 30 | - |
limits.evaluatePerMinute | number | 30 | - |
limits.keepDays | number | 30 | - |
limits.maxClients | number | 100_000 | - |
limits.recordBytes | number | 1024 | - |
limits.sendBurst | number | 5 | - |
limits.sendPerHour | number | 6 | - |
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
| Parameter | Type |
|---|---|
opts | MailboxCoreOptions |
Returns
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
| Parameter | Type |
|---|---|
opts | ServerOptions |
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
| Parameter | Type |
|---|---|
opts | DirectoryOptions & object |
Returns
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
| Parameter | Type |
|---|---|
seed | Uint8Array |
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
| Parameter | Type |
|---|---|
dir | string |
Returns
mailboxHandler()
function mailboxHandler(opts): MailboxHandler;
The mailbox's HTTP handler.
Parameters
| Parameter | Type |
|---|---|
opts | MailboxOptions |
Returns
memoryStorage()
function memoryStorage(): MailboxStorage;
Storage in memory: gone when the process ends.
Returns
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
| Parameter | Type |
|---|---|
address | string |
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
| Parameter | Type |
|---|---|
sealed | Uint8Array |
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
| Parameter | Type | Default value |
|---|---|---|
id | string | undefined |
action | string | undefined |
iat | number | undefined |
extra | string | '' |
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
| Parameter | Type |
|---|---|
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
| Parameter | Type |
|---|---|
older | readonly object[] |
now | number |
max | number |
days | number |
Returns
object[]
withheld()
function withheld(text): string;
A message's text with every link's fragment (a persona link's key) withheld.
Parameters
| Parameter | Type |
|---|---|
text | string |
Returns
string
writeBuckets()
function writeBuckets(limits, now?): object;
Token buckets by client, in memory only; full buckets are forgotten.
Parameters
| Parameter | Type |
|---|---|
limits | Pick<StoreLimits, "writesBurst" | "writesPerSecond" | "maxClients"> |
now | () => number |
Returns
| Name | Type | Description |
|---|---|---|
close() | () => void | - |
size() | () => number | - |
take() | (client) => boolean | Takes a token from client's bucket; false when it's empty. |