GizStack
View .mdOpen in ChatGPTOpen in Claude

gizapp/auth/main

Auth: who is asking, for every gizapp app. It owns the people, their sessions, teams and roles, proofs of a mailbox, API tokens and (with the passkey and OAuth modules) the other ways in. An app asks current for the person of a request, and the Gate judges with their team grants (Gate.grantOf): pages, tools, agents and APIs share that one rule. The rows are the app's own: every function takes the Data.Db of the thread that serves the request (see records.giz).

gizlang
import * as Main from "gizapp/auth/main";

Types

Site

gizlang
type Site<C> = { prefix: string; home: string; origin: string; title: string; password: bool; secret: bytes; db: (context: C) => Data.Db; shell: (context: C) => App.Shell; mail: (context: C, to: string, link: string) => bool; providers?: Vec<OAuth.Provider>; sso?: bool; texts?: (context: C, host: string) => Vec<string>; signInPage?: string; enter?: (context: C, request: Http.Request, person: Person) => Http.Response; }

What the sign-in routes need of an app. PREFIX is where they are served ("/auth"), HOME where a signed-in person goes, ORIGIN the app's own address (a mailed link starts with it, never with the request's Host, which a client chooses). PASSWORD turns on the password field; without it a person signs in by a mailed link only. MAIL sends LINK to the address TO and says whether it was sent. The other functions read the app's context: its records (this thread's Data.Db), its System and its page shell.

Opaque: create and use it through this module's functions.

Functions

principalOf

gizlang
function principalOf(p: Person): Security.Principal

The principal of a person, for the Gate.

install

gizlang
function install(db: Data.Db): bool throws Model.Rejection

The tables of this module, made when missing. Their changes are additive: an existing table keeps its rows. Call it once on the app's records before it serves.

Effects: fail, read, write, console, io, alloc.

shapes

gizlang
function shapes(): Vec<Model.Shape>

The records of this module: a service that installs them lazily checks that all their tables are there.

Effects: fail, read, write, console, io, alloc.

personByEmail

gizlang
function personByEmail(db: Data.Db, address: string): Option<Person> throws Model.Rejection

The person with the address ADDRESS, or undefined.

Effects: fail, read, write, console, io, alloc.

signUp

gizlang
function signUp(db: Data.Db, email: string, name: string, password: string, now: i64): Person throws Model.Rejection

A new account of EMAIL named NAME. A password is optional: "" makes an account for a passkey or a link.

Effects: fail, read, write, console, io, alloc.

newPerson

gizlang
function newPerson(email: string, name: string, password: string, verified: i64, now: i64): Person throws Model.Rejection

The row of a new account, not stored yet: its address checked and lowercase, its name trimmed, its password (optional) hashed, a new id, and VERIFIED (0, or when a provider proved the mailbox). signUp stores it alone; Teams.personal with its personal team.

Effects: fail, io, alloc.

insertPerson

gizlang
function insertPerson(db: Data.Db, person: Person): Person throws Model.Rejection

Adds PERSON with the id it has (an importer's account: its principal id, its bcrypt hash, its verified time). The address is kept lowercase, and an address that is taken is refused.

Effects: fail, read, write, console, io, alloc.

signIn

gizlang
function signIn(db: Data.Db, email: string, password: string): Person throws Model.Rejection

The person of EMAIL with PASSWORD. Its failure is SIGN_IN_FAILED, whichever part was wrong. A password under an older hash (PBKDF2, or bcrypt that an import brought) is stored again as Argon2id at its first use (Password.stale).

Effects: fail, read, write, console, io, alloc.

startSession

gizlang
function startSession(db: Data.Db, person: Person, label: string, now: i64): string throws Model.Rejection

A new session of PERSON on the device LABEL: the token for its cookie.

Effects: fail, read, write, console, io, alloc.

current

gizlang
function current(db: Data.Db, request: Http.Request, now: i64): Option<Person> throws Model.Rejection

The person a request is signed in as at NOW, or undefined: by a session row or an API token.

Effects: fail, read, write, console, io, alloc.

personOf

gizlang
function personOf(db: Data.Db, token: string, now: i64): Option<Person> throws Model.Rejection

The person of TOKEN at NOW (as current reads it from a request), or undefined.

Effects: fail, read, write, console, io, alloc.

personById

gizlang
function personById(db: Data.Db, id: string): Option<Person> throws Model.Rejection

The person with the id ID, or undefined.

Effects: fail, read, write, console, io, alloc.

signOut

gizlang
function signOut(db: Data.Db, token: string, now: i64): bool throws Model.Rejection

Signs out one session by its token: this device only.

Effects: fail, read, write, console, io, alloc.

signOutEverywhere

gizlang
function signOutEverywhere(db: Data.Db, person: string, now: i64): bool throws Model.Rejection

Signs PERSON out of every device, and of every older token.

Effects: fail, read, write, console, io, alloc.

linkFor

gizlang
function linkFor(db: Data.Db, email: string, purpose: string, now: i64): Option<string> throws Model.Rejection

The raw token of a new proof of PURPOSE ("verify", "reset" or "login") for EMAIL, when an account has it. The caller mails the link whatever the answer, so an address is never revealed by the reply.

Effects: fail, read, write, console, io, alloc.

gizlang
function signInWithLink(db: Data.Db, raw: string, now: i64): Person throws Model.Rejection

The person of a magic link (purpose "login"), who is then proven to own the address.

Effects: fail, read, write, console, io, alloc.

verifyMailbox

gizlang
function verifyMailbox(db: Data.Db, raw: string, now: i64): bool throws Model.Rejection

Proves the mailbox of the verify link RAW.

Effects: fail, read, write, console, io, alloc.

linkOpen

gizlang
function linkOpen(db: Data.Db, raw: string, purpose: string, now: i64): bool throws Model.Rejection

Whether RAW is a live link of PURPOSE at NOW, without using it: what a page checks before it shows the form the link opens.

Effects: fail, read, write, console, io, alloc.

resetPassword

gizlang
function resetPassword(db: Data.Db, raw: string, password: string, now: i64): Person throws Model.Rejection

Sets the password of the reset link RAW to PASSWORD and gives the person, to sign in. Every session of the person ends with it. A dead link is refused before the password is hashed, which is slow on purpose.

Effects: fail, read, write, console, io, alloc.

newApiToken

gizlang
function newApiToken(db: Data.Db, person: string, name: string, expires: i64, now: i64): string throws Model.Rejection

A new API token of PERSON named NAME, ending at EXPIRES (ms, 0 never). Returned once; only its digest is stored.

Effects: fail, read, write, console, io, alloc.

revokeApiToken

gizlang
function revokeApiToken(db: Data.Db, person: string, digest: string, now: i64): bool throws Model.Rejection

Ends one of PERSON's API tokens at NOW. DIGEST is the token's digest as tokensOf lists it, so a page never holds a secret.

Effects: fail, read, write, console, io, alloc.

devicesOf

gizlang
function devicesOf(db: Data.Db, person: string, now: i64): Vec<Session> throws Model.Rejection

The sessions of PERSON open at NOW, for a devices list.

Effects: fail, read, write, console, io, alloc.

revokeDevice

gizlang
function revokeDevice(db: Data.Db, person: string, digest: string, now: i64): bool throws Model.Rejection

Ends one of PERSON's sessions by its digest (a devices list's row), at NOW.

Effects: fail, read, write, console, io, alloc.

tokensOf

gizlang
function tokensOf(db: Data.Db, person: string): Vec<ApiToken> throws Model.Rejection

PERSON's API tokens, newest first.

Effects: fail, read, write, console, io, alloc.

revokeClient

gizlang
function revokeClient(db: Data.Db, person: string, client: string, now: i64): bool throws Model.Rejection

PERSON takes back their approval of the registered client CLIENT (Oidc.approve) at NOW: the client's refresh and access tokens for them end with it, and its next authorize asks again.

Effects: fail, read, write, console, io, alloc.

addPasskey

gizlang
function addPasskey(secret: bytes, db: Data.Db, person: string, name: string, rpId: string, origin: string, challengeText: string, json: bytes, attestation: bytes, now: i64): bool throws Model.Rejection

Keeps the passkey that the registration ceremony ATTESTATION answers (see Passkeys.register) for PERSON, named NAME.

Effects: fail, read, write, console, io, alloc.

signInWithPasskey

gizlang
function signInWithPasskey(secret: bytes, db: Data.Db, rpId: string, origin: string, challengeText: string, id: string, json: bytes, data: bytes, signature: bytes, now: i64): Person throws Model.Rejection

The person who signs in with the passkey ID, once its assertion (DATA, SIGNATURE, over the client data JSON) answers the challenge. The counter it reports is kept, so a copy of the credential is refused.

Effects: fail, read, write, console, io, alloc.

passkeysOf

gizlang
function passkeysOf(db: Data.Db, person: string): Vec<Passkey> throws Model.Rejection

The passkeys of PERSON, the newest first.

Effects: fail, read, write, console, io, alloc.

removePasskey

gizlang
function removePasskey(db: Data.Db, person: string, id: string): bool throws Model.Rejection

Forgets PERSON's passkey ID (its credential id, as passkeysOf lists it).

Effects: fail, read, write, console, io, alloc.

signInWithIdentity

gizlang
function signInWithIdentity(db: Data.Db, id: Identity, now: i64): Person throws Model.Rejection

The person of a sign-in with a provider's IDENTITY, at NOW. A linked subject is its person. Otherwise the verified address decides: a verified account of it is linked and signed in; an unverified one is taken over, as the mailbox owner (its password and its sessions end); a new address makes an account. The link is kept for the next sign-in.

Effects: fail, read, write, console, io, alloc.

ssoProvider

gizlang
function ssoProvider(connection: string): string

The provider of an enterprise SSO connection: each connection is a provider of its own, sso:${connection}.

Effects: fail, alloc.

linkSso

gizlang
function linkSso(db: Data.Db, connection: string, subject: string, person: string, email: string, active: bool, profile: string, now: i64): bool throws Model.Rejection

Records what the directory of CONNECTION says about SUBJECT: its PERSON, whether it may sign in (ACTIVE) and its PROFILE (JSON text, "" when none). A sync calls it for each user it reads; the row is updated when it exists. A link that is not active refuses sign-in, so a user the directory removed cannot sign in with it, and holds none of its team memberships.

Effects: fail, read, write, console, io, alloc.

linksOf

gizlang
function linksOf(db: Data.Db, person: string): Vec<ProviderLink> throws Model.Rejection

The provider links of PERSON, in the order they were made.

Effects: fail, read, write, console, io, alloc.

importCarried

gizlang
function importCarried(db: Data.Db, refreshToken: string, person: string, now: i64, expires: i64): bool throws Model.Rejection

Records a carried refresh session of PERSON, from its cookie REFRESHTOKEN, made at NOW and good until EXPIRES.

Effects: fail, read, write, console, io, alloc.

adoptRefresh

gizlang
function adoptRefresh(db: Data.Db, refreshToken: string, now: i64): Option<Sessions.Carried> throws Model.Rejection

The session of a refreshToken cookie at NOW, once (see Sessions.adoptRefresh). The caller sets the new session cookie and clears refreshToken when this gives a session.

Effects: fail, read, write, console, io, alloc.

oidcToken

gizlang
function oidcToken(db: Data.Db, issuer: Oidc.OidcIssuer, req: Oidc.OidcToken, now: i64): string throws Model.Rejection

The token response of a token request (see Oidc.grant): the ID token, an access token (an API token of the person, for ACCESS_LIFE) and the refresh token that replaces the one used.

Effects: fail, read, write, console, io, alloc.

oidcUserinfo

gizlang
function oidcUserinfo(db: Data.Db, token: string, now: i64): Option<string> throws Model.Rejection

The userinfo claims of an access token from oidcToken, at NOW; undefined when it is not a live one.

Effects: fail, read, write, console, io, alloc.

person

gizlang
function person<C>(site: Site<C>, context: C, request: Http.Request, now: i64): Option<Person>

The person of REQUEST at NOW (a session cookie or an API token), or undefined: what a route checks before it serves.

routes

gizlang
function routes<C>(site: Site<C>): Vec<Http.Route<App.Handle<C>>>

The sign-in of an app in one call: routes.push(...Auth.routes(site)) serves PREFIX/sign-in (the page, and the password sign-in when PASSWORD is on), PREFIX/link (a mailed one-use link, which also makes the account of a new address), PREFIX/two-factor (the code that completes either for a person with two-factor sign-in on), PREFIX/with/NAME (the sign-in with each of PROVIDERS, which comes back to PREFIX/with/NAME/callback) and PREFIX/sign-out. Call Auth.install on the database once first.

teamSignIn

gizlang
function teamSignIn(db: Data.Db, team: string, id: Identity, now: i64): Person throws Model.Rejection

The person whom TEAM's single sign-on vouches for (IDENTITY, from its issuer) at NOW. Only an address at a domain the team verified signs in: the team holds those mailboxes, so its issuer may make or link their accounts, and never anyone else's. A person it signs in is a member of the team (Teams.SSO_ROLE the first time).

Effects: fail, read, write, console, io, alloc.

ssoRoutes

gizlang
function ssoRoutes<C>(site: Site<C>): Vec<Http.Route<App.Handle<C>>>

PREFIX/sso (the address, then its team's issuer) and its callback, and PREFIX/teams/TEAM/sso for the team's managers; none unless the site lets teams sign in with their own (Site.sso). An app with its own router serves them with App.serve(Http.router(Auth.ssoRoutes(site)), context, request).

Constants

SIGN_IN_FAILED

gizlang
const SIGN_IN_FAILED = "The email or the password is wrong."

The answer of every sign-in that fails: the same for an unknown address and a wrong password.

SIGN_IN_PAUSED

gizlang
const SIGN_IN_PAUSED = Records.PAUSED

The answer of a password sign-in of an address that failed too often lately (a 429; Records.attempt).

gizlang
const COOKIE = Sessions.COOKIE

The cookie that holds a session, and the parts of the identity an app uses on its own: teams and their Gate, the provider sign-in, and the passkey challenge.