Class: Accounts

Defined in: server/accounts.ts:278

A small player backend on D1: accounts with a name and a password, sessions, guests who can sign up without losing what they earned, per-player data, stats and leaderboards, public profiles, and a player's right to download or delete everything about them.

Make one per request; it holds no state of its own beyond its options.

const accounts = new Accounts(env.DB, { secret: env.JOIN_SECRET });
return (await accounts.route(request)) ?? new Response("Not found", { status: 404 });

Constructors

Constructor

new Accounts(db, options): Accounts;

Defined in: server/accounts.ts:296

Parameters

Parameter	Type
db	D1Database
options	AccountsOptions

Returns

Accounts

Methods

migrate()

migrate(): Promise<void>;

Defined in: server/accounts.ts:328

Creates the tables if they are not there yet. Called for you before the first query.

Returns

Promise<void>

---

identify()

identify(request, scope?): Promise<Identity | null>;

Defined in: server/accounts.ts:346

Who is making this request: the account its session cookie or bearer session token belongs to, else the player a join token (?token= or bearer) speaks for, else nobody. scope is checked against scoped join tokens, as tokenAuth does.

Parameters

Parameter	Type
request	Request
scope?	string

Returns

Promise<Identity | null>

---

authenticate()

readonly authenticate(request, scope): Promise<Response | Identity>;

Defined in: server/accounts.ts:372

For routeToRoom and routeToMatchmaker: lets in signed-in players and holders of a join token, guests included, and answers 401 otherwise. The room learns the player's name too.

Parameters

Parameter	Type
request	Request
scope	string

Returns

Promise<Response | Identity>

---

requireAccount()

readonly requireAccount(request, scope): Promise<Response | Identity>;

Defined in: server/accounts.ts:378

Like authenticate, for places that need an account: guests get 401 too.

Parameters

Parameter	Type
request	Request
scope	string

Returns

Promise<Response | Identity>

---

route()

route(request, ctx?): Promise<Response | null>;

Defined in: server/accounts.ts:413

Answers requests to the accounts API, under prefix; null for any other URL so your Worker can try its other routes.

POST   /guest            a guest player and a join token for them
POST   /register         { name, password, email?, guestToken? }
POST   /login            { name, password }
POST   /logout
GET    /me               your account, data and stats
DELETE /me               { password }: delete your account and everything in it
POST   /password         { current, next }: change it and sign out everywhere else
POST   /recovery-code    { password }: a code that sets a new password once, shown this one time
POST   /recover          { name, code, password }: set a new password with that code, and sign in
POST   /forgot           { name } or { email }: send a reset link, if `sendPasswordReset` is set
POST   /reset            { token, password }: set a new password with the link's token, and sign in
POST   /name             { name }: take another name
POST   /email            { password, email }: set or (with null) remove the email address
GET    /export           everything stored about you, as a JSON download
POST   /token            { scope? }: a short-lived join token for a room or queue
GET    /data/:key        PUT /data/:key { value }   DELETE /data/:key
GET    /players/:id      a public profile
GET    /leaderboards/:stat?limit=&offset=

Pass the Worker's ctx as well if you reset passwords by email: the email is then sent after the answer, which takes as long whether or not there was an account to write to.

Parameters

Parameter	Type
request	Request
ctx?	Pick<ExecutionContext<unknown>, "waitUntil">

Returns

Promise<Response | null>

---

register()

register(input): Promise<Identity>;

Defined in: server/accounts.ts:639

Creates an account. id lets a guest keep theirs; it is made up otherwise.

Parameters

Parameter	Type
input	{ name: string; password: string; email?: string | null; id?: string; }
input.name	string
input.password	string
input.email?	string | null
input.id?	string

Returns

Promise<Identity>

---

importAccount()

importAccount(account): Promise<void>;

Defined in: server/accounts.ts:665

Brings in an account from another service. Its password works through verifyImportedPassword.

Parameters

Parameter	Type
account	ImportedAccount

Returns

Promise<void>

---

signIn()

signIn(
   name, 
   password, 
   from?
): Promise<Identity>;

Defined in: server/accounts.ts:678

Checks a name and password. Repeated failures for one name or one address are refused for a while.

Parameters

Parameter	Type	Default value
name	string	undefined
password	string	undefined
from?	string	"unknown"

Returns

Promise<Identity>

---

rename()

rename(accountId, name): Promise<Identity>;

Defined in: server/accounts.ts:696

Gives an account another name, if nobody has it. Sessions and join tokens issued later carry the new one.

Parameters

Parameter	Type
accountId	string
name	string

Returns

Promise<Identity>

---

setEmail()

setEmail(accountId, email): Promise<void>;

Defined in: server/accounts.ts:713

Sets the email address, or removes it with null.

Parameters

Parameter	Type
accountId	string
email	string | null

Returns

Promise<void>

---

setPassword()

setPassword(accountId, password): Promise<void>;

Defined in: server/accounts.ts:725

Sets a new password, ends every session of the account, and makes any password reset token it was sent useless. Its recovery code stays.

Parameters

Parameter	Type
accountId	string
password	string

Returns

Promise<void>

---

createRecoveryCode()

createRecoveryCode(accountId): Promise<string>;

Defined in: server/accounts.ts:746

Makes a recovery code for an account and returns it: twenty letters and digits the player keeps somewhere safe, which set a new password once, with no email involved. It replaces the code the account had, if any. Only its hash is stored, so this is the one time it can be shown.

Parameters

Parameter	Type
accountId	string

Returns

Promise<string>

---

recoverWithCode()

recoverWithCode(
   name, 
   code, 
   password, 
   from?
): Promise<Identity>;

Defined in: server/accounts.ts:764

Sets a new password for the account called name, given its recovery code, and ends its sessions. The code is used up: make another once signed in. Wrong guesses are counted as wrong passwords are.

Parameters

Parameter	Type	Default value
name	string	undefined
code	string	undefined
password	string	undefined
from?	string	"unknown"

Returns

Promise<Identity>

---

startPasswordReset()

startPasswordReset(who): Promise<PasswordReset[]>;

Defined in: server/accounts.ts:796

Makes a password reset token for the account with this name, or for each account with this email address, and returns what to send to whom. Empty if there is no such account or it has no email address. A token replaces the one the account was sent before. POST /forgot calls this and hands each result to sendPasswordReset.

Parameters

Parameter	Type
who	{ name?: string; email?: string; }
who.name?	string
who.email?	string

Returns

Promise<PasswordReset[]>

---

resetPassword()

resetPassword(token, password): Promise<Identity>;

Defined in: server/accounts.ts:828

Sets a new password with a token from startPasswordReset, once, and ends the account's sessions.

Parameters

Parameter	Type
token	string
password	string

Returns

Promise<Identity>

---

createSession()

createSession(accountId): Promise<string>;

Defined in: server/accounts.ts:850

Starts a session for an account and returns its token. Usually done for you by /login.

Parameters

Parameter	Type
accountId	string

Returns

Promise<string>

---

deleteAccount()

deleteAccount(accountId): Promise<void>;

Defined in: server/accounts.ts:862

Deletes an account, its sessions, data and stats. Match records keep the id, but it no longer resolves to a name.

Parameters

Parameter	Type
accountId	string

Returns

Promise<void>

---

exportAccount()

exportAccount(accountId): Promise<Record<string, unknown>>;

Defined in: server/accounts.ts:874

Everything stored about a player, for them to download.

Parameters

Parameter	Type
accountId	string

Returns

Promise<Record<string, unknown>>

---

ownAccount()

ownAccount(accountId): Promise<OwnAccount>;

Defined in: server/accounts.ts:923

The account as its owner sees it.

Parameters

Parameter	Type
accountId	string

Returns

Promise<OwnAccount>

---

profile()

profile(playerId): Promise<PublicProfile | null>;

Defined in: server/accounts.ts:950

A player's public profile, or null if there is no account with that id.

Parameters

Parameter	Type
playerId	string

Returns

Promise<PublicProfile | null>

---

names()

names(playerIds): Promise<Map<string, string>>;

Defined in: server/accounts.ts:964

Account names by player id. Guests and deleted accounts are left out.

Parameters

Parameter	Type
playerIds	readonly string[]

Returns

Promise<Map<string, string>>

---

getData()

getData(playerId, key): Promise<unknown>;

Defined in: server/accounts.ts:982

The value a player has under key, or undefined. Server code reads every key, whatever its policy.

Parameters

Parameter	Type
playerId	string
key	string

Returns

Promise<unknown>

---

setData()

setData(
   playerId, 
   key, 
   value
): Promise<void>;

Defined in: server/accounts.ts:993

Stores a JSON value for a player. Server code may set any key; clients only those with write: "owner".

Parameters

Parameter	Type
playerId	string
key	string
value	unknown

Returns

Promise<void>

---

deleteData()

deleteData(playerId, key): Promise<void>;

Defined in: server/accounts.ts:1019

Removes a player's value under key. Does nothing if there is none.

Parameters

Parameter	Type
playerId	string
key	string

Returns

Promise<void>

---

addStats()

addStats(playerId, increments): Promise<void>;

Defined in: server/accounts.ts:1036

Adds to a player's stats: { wins: 1, kills: 7 }. Server only: clients cannot write stats.

Parameters

Parameter	Type
playerId	string
increments	Record<string, number>

Returns

Promise<void>

---

setStats()

setStats(playerId, values): Promise<void>;

Defined in: server/accounts.ts:1041

Sets stats to these values.

Parameters

Parameter	Type
playerId	string
values	Record<string, number>

Returns

Promise<void>

---

maxStats()

maxStats(playerId, values): Promise<void>;

Defined in: server/accounts.ts:1046

Keeps the higher of the stored and the given value: best scores, longest streaks.

Parameters

Parameter	Type
playerId	string
values	Record<string, number>

Returns

Promise<void>

---

awardStats()

awardStats(key, awards): Promise<boolean>;

Defined in: server/accounts.ts:1056

Writes several players' stats in one go, once per key: a match id, say. Calling it again with the same key changes nothing and returns false, so code that retries after a failure cannot count a result twice. Either all of it is written or none of it.

Parameters

Parameter	Type
key	string
awards	readonly { player: string; add?: Record<string, number>; set?: Record<string, number>; max?: Record<string, number>; }[]

Returns

Promise<boolean>

---

stats()

stats(playerId): Promise<Record<string, number>>;

Defined in: server/accounts.ts:1083

Every stat a player has.

Parameters

Parameter	Type
playerId	string

Returns

Promise<Record<string, number>>

---

statsOf()

statsOf(playerIds, stats?): Promise<Map<string, Record<string, number>>>;

Defined in: server/accounts.ts:1093

Several players' stats at once, by player id. stats limits it to those stats. Players without any are left out.

Parameters

Parameter	Type
playerIds	readonly string[]
stats?	readonly string[]

Returns

Promise<Map<string, Record<string, number>>>

---

leaderboard()

leaderboard(stat, page?): Promise<LeaderboardPage>;

Defined in: server/accounts.ts:1117

The players with the highest value of a stat. Players without an account are not listed.

Parameters

Parameter	Type
stat	string
page?	{ limit?: number; offset?: number; }
page.limit?	number
page.offset?	number

Returns

Promise<LeaderboardPage>

---

rank()

rank(stat, playerId): Promise<
  | Pick<LeaderboardEntry, "value" | "rank">
| null>;

Defined in: server/accounts.ts:1144

A player's place on a leaderboard, or null if they have no value for that stat.

Parameters

Parameter	Type
stat	string
playerId	string

Returns

Promise< | Pick<LeaderboardEntry, "value" | "rank"> | null>