@ultimabase/auth 0.0.0-stage → 0.1.1

package/dist/token.js

@@ -0,0 +1,32 @@
+/** The longest a browser keeps a cookie: 400 days. */
+export const cookieAge = 400 * 24 * 60 * 60;
+/** Secure and `__Host-` in production, so it works on `http://localhost`. */
+export function cookieOf() {
+    const secure = process.env['NODE_ENV'] === 'production';
+    const name = secure ? '__Host-ultimabase_session' : 'ultimabase_session';
+    return {
+        name,
+        options: { httpOnly: true, sameSite: 'Lax', path: '/', secure },
+    };
+}
+/**
+ * The token the `Authorization` header sends, `''` for a Bearer without one,
+ * `undefined` without a Bearer header, which another plugin may read.
+ */
+export function bearerOf(request) {
+    const header = request.headers.get('authorization');
+    const match = header === null ? null : /^bearer(?: +(.*))?$/i.exec(header);
+    if (match === null)
+        return undefined;
+    return match[1]?.trim() ?? '';
+}
+/** The token the cookie sends, if any. */
+export function cookieTokenOf(request, cookie) {
+    const header = request.headers.get('cookie') ?? '';
+    for (const pair of header.split(';')) {
+        const [name, ...value] = pair.split('=');
+        if (name?.trim() === cookie.name)
+            return value.join('=').trim();
+    }
+    return undefined;
+}

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@ultimabase/auth",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Authentication for UltimaBase: the user model, sessions and the caller of each request.",
+  "type": "module",
+  "license": "Apache-2.0",
+  "homepage": "https://ultimabase.dev/docs/auth",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MrEkinox/ultimabase.git",
+    "directory": "packages/auth"
+  },
+  "engines": {
+    "node": ">=24.7.0"
+  },
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/test"
+  ],
+  "scripts": {
+    "prepack": "rm -rf dist && yarn run -T tsc --project tsconfig.build.json"
+  },
+  "publishConfig": {
+    "exports": {
+      ".": "./dist/index.js"
+    }
+  },
+  "peerDependencies": {
+    "@ultimabase/http": "^0.1.1",
+    "ultimabase": "^0.1.1"
+  },
+  "devDependencies": {
+    "@types/pg": "8.23.1",
+    "@ultimabase/graphql": "0.1.1",
+    "@ultimabase/http": "0.1.1",
+    "@ultimabase/postgres": "0.1.1",
+    "@ultimabase/testing": "0.1.1",
+    "graphql": "17.0.2",
+    "pg": "8.23.1",
+    "ultimabase": "0.1.1",
+    "vite": "8.3.4",
+    "vitest": "5.0.5"
+  }
 }

package/src/accounts.ts

@@ -0,0 +1,65 @@
+// Linked accounts (D-113): one row per way a user signs in, unique on its
+// method and the subject that method knows the user by.
+import type { Field, ModelOf, ScalarOptions } from 'ultimabase'
+import { defineModel, master } from 'ultimabase'
+
+const M = { as: master }
+
+type AccountFields = {
+	readonly userId: Field<string, ScalarOptions<string>>
+	readonly method: Field<string, ScalarOptions<string>>
+	readonly subject: Field<string, ScalarOptions<string>>
+}
+
+/** auth's own model (D-110). */
+export const AuthAccount: ModelOf<'AuthAccount', AccountFields, []> =
+	defineModel({
+		name: 'AuthAccount',
+		fields: (f) => ({
+			userId: f.string(),
+			method: f.string(),
+			subject: f.string(),
+		}),
+		indexes: [
+			{ fields: ['method', 'subject'], unique: true },
+			{ fields: ['userId'] },
+		],
+	})
+
+/** Links `userId` to `subject` of `method`; a taken pair is a `UNIQUE_VIOLATION`. */
+export async function linkAccount(
+	userId: string,
+	method: string,
+	subject: string,
+): Promise<void> {
+	await AuthAccount.create({ data: { userId, method, subject } }, M)
+}
+
+/** The user `subject` of `method` signs in as, if any. */
+export async function accountOf(
+	method: string,
+	subject: string,
+): Promise<{ readonly userId: string } | undefined> {
+	const [account] = await AuthAccount.findMany(
+		{ where: { method, subject }, take: 1 },
+		M,
+	)
+	return account === undefined ? undefined : { userId: account.userId }
+}
+
+/** The subject `userId` is known by to `method`, if linked (D-117). */
+export async function subjectOf(
+	userId: string,
+	method: string,
+): Promise<string | undefined> {
+	const [account] = await AuthAccount.findMany(
+		{ where: { userId, method }, take: 1 },
+		M,
+	)
+	return account?.subject
+}
+
+/** Unlinks every account of a user. */
+export async function unlinkAccounts(userId: string): Promise<void> {
+	await AuthAccount.deleteMany({ where: { userId } }, M)
+}

package/src/define-user.ts

@@ -0,0 +1,42 @@
+// auth's `define<Kind>` entry (D-13, D-62): the application's one user model,
+// an ordinary model with auth first in its `use`.
+import type {
+	FieldShapes,
+	IndexShape,
+	ModelFields,
+	ModelIndexes,
+	ModelOf,
+	ModelUse,
+	PluginTypes,
+} from 'ultimabase'
+import { defineModel } from 'ultimabase'
+import type { Auth } from './plugin.ts'
+import { authUse, userModels } from './plugin.ts'
+
+type Uses = readonly ModelUse<string, PluginTypes>[]
+/** The user model's `use`: auth first, then the developer's plugins. */
+type WithAuth<U extends Uses> = readonly [ModelUse<'auth', Auth>, ...U]
+
+/** The application's one user model (D-62). */
+export function defineUser<
+	const N extends string,
+	const F extends FieldShapes,
+	const U extends Uses = [],
+	const X extends readonly IndexShape[] = [],
+>(definition: {
+	readonly name: N
+	/** The stored table's or collection's name (D-63). */
+	readonly dbName?: string
+	readonly use?: U
+	readonly fields: ModelFields<F, WithAuth<U>>
+	readonly indexes?: ModelIndexes<X, F, WithAuth<U>>
+}): ModelOf<N, F, WithAuth<U>, X> {
+	const model: object = defineModel({
+		...definition,
+		use: [authUse(), ...(definition.use ?? [])],
+	})
+	// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- defineModel's own model, with auth in its use; an omitted `use` leaves `U` at its default only when nobody passes it (D-62).
+	const user = model as ModelOf<N, F, WithAuth<U>, X>
+	userModels.set(model, user.nullable())
+	return user
+}

package/src/functions.ts

@@ -0,0 +1,44 @@
+// auth's functions (D-113): `signOut`, which ends the request's session and
+// clears its cookie, and `viewer`, the caller's user read again as the caller.
+import type { FunctionShape, ModelQueries, OutputSpec } from 'ultimabase'
+import { allow, defineFunction } from 'ultimabase'
+import { closeSession } from './sessions.ts'
+import type { Cookie } from './token.ts'
+
+/** Each session's token, by the user row `identify` read for it (D-121). */
+export const callerTokens: WeakMap<object, string> = new WeakMap()
+
+/** The user model's queries, and its output `User`, or `null`. */
+export interface Users {
+	readonly queries: ModelQueries
+	readonly output: OutputSpec
+}
+
+/** `signOut` and `viewer`, public: each reads the caller only. */
+export function authFunctions(
+	cookie: Cookie,
+	users: Users,
+): readonly FunctionShape[] {
+	const signOut = defineFunction({
+		name: 'signOut',
+		run: async ({ caller, client }) => {
+			const token =
+				caller.kind === 'user' ? callerTokens.get(caller.user) : undefined
+			if (token !== undefined) await closeSession(token)
+			client?.cookies.clear(cookie.name, cookie.options)
+		},
+	}).with({ access: allow.public })
+	const viewer = defineFunction({
+		name: 'viewer',
+		query: true,
+		output: users.output,
+		run: async ({ caller }) =>
+			caller.kind === 'user'
+				? users.queries.findUnique(
+						{ where: { id: caller.user.id } },
+						{ as: caller },
+					)
+				: null,
+	}).with({ access: allow.public })
+	return [signOut, viewer]
+}

package/src/index.ts

@@ -0,0 +1,12 @@
+// `@ultimabase/auth` (D-112, D-113): the user model, sessions, linked
+// accounts, the caller of each request, and the rules that read it.
+export { defineUser } from './define-user.ts'
+export type { Auth, AuthApi, AuthCommands, Opened } from './plugin.ts'
+export { authPlugin } from './plugin.ts'
+export {
+	currentUser,
+	isAuthenticated,
+	isOwner,
+	isSelf,
+	signedIn,
+} from './rules.ts'

package/src/plugin.ts

@@ -0,0 +1,229 @@
+// `authPlugin()` (D-112, D-113): the caller of each request from its
+// session, the API sign-in methods open sessions and link accounts with, and
+// its functions and command.
+import type { Http } from '@ultimabase/http'
+import { httpPlugin } from '@ultimabase/http'
+import type {
+	Client,
+	Identity,
+	OutputSpec,
+	PluginOf,
+	PluginTypes,
+	Register,
+	UseOf,
+	UserOf,
+} from 'ultimabase'
+import {
+	definePlugin,
+	isLocalHost,
+	isMaster,
+	master,
+	PublicError,
+	Refused,
+} from 'ultimabase'
+import manifest from '../package.json' with { type: 'json' }
+import {
+	accountOf,
+	AuthAccount,
+	linkAccount,
+	subjectOf,
+	unlinkAccounts,
+} from './accounts.ts'
+import type { Users } from './functions.ts'
+import { authFunctions, callerTokens } from './functions.ts'
+import type { Opened } from './sessions.ts'
+import {
+	AuthSession,
+	closeSession,
+	openSession,
+	revokeSessions,
+	sessionOf,
+} from './sessions.ts'
+import type { Cookie } from './token.ts'
+import { bearerOf, cookieAge, cookieOf, cookieTokenOf } from './token.ts'
+
+export type { Opened } from './sessions.ts'
+
+/** What auth offers the sign-in methods (D-33, D-112, D-113). */
+export interface AuthApi {
+	/**
+	 * Opens a session for `userId`, and sets its cookie when a transport's
+	 * `client` is given, ending the session the cookie it replaces held.
+	 */
+	signIn(userId: string, client?: Client): Promise<Opened>
+	/** Ends every session of a user. */
+	revokeSessions(userId: string): Promise<void>
+	/** Links `userId` to `subject` of `method`; a taken pair is a `UNIQUE_VIOLATION`. */
+	linkAccount(userId: string, method: string, subject: string): Promise<void>
+	/** The user `subject` of `method` signs in as, if any. */
+	accountOf(
+		method: string,
+		subject: string,
+	): Promise<{ readonly userId: string } | undefined>
+	/** The subject `userId` is known by to `method`, if linked (D-117). */
+	subjectOf(userId: string, method: string): Promise<string | undefined>
+}
+
+/** auth's commands on the user model (D-113). */
+export interface AuthCommands {
+	/** Ends every session of the user, as Master or as the user. */
+	revokeSessions(
+		where: { readonly id: string },
+		options?: { readonly as?: Identity },
+	): Promise<void>
+}
+
+/** auth's types (D-57). */
+export interface Auth extends PluginTypes {
+	readonly name: 'auth'
+	readonly requires: Http
+	readonly api: AuthApi
+	readonly commands: AuthCommands
+}
+
+/** The models `defineUser` returned, each with its output `User`, or `null`. */
+export const userModels: WeakMap<object, OutputSpec> = new WeakMap()
+
+/** What each running application's auth reads, by its context. */
+interface State {
+	readonly cookie: Cookie
+	readonly users: Users
+}
+const states = new WeakMap<object, State>()
+/** The contexts whose insecure cookie was warned about (D-115). */
+const warned = new WeakSet<object>()
+
+const M = { as: master }
+
+function stateOf(context: object): State {
+	const state = states.get(context)
+	if (state === undefined) throw new Error('auth has not started.')
+	return state
+}
+
+/** The one user model among the application's models (D-62). */
+function usersOf(
+	models: readonly { readonly queries: Users['queries'] }[],
+): Users {
+	const [first, second] = models.flatMap(({ queries }) => {
+		const output = userModels.get(queries)
+		return output === undefined ? [] : [{ queries, output }]
+	})
+	if (first === undefined) {
+		throw new Refused(
+			'authPlugin() needs a user model: declare it with defineUser.',
+		)
+	}
+	if (second !== undefined) {
+		throw new Refused(
+			'models lists two models defineUser returned: an application has one user model.',
+		)
+	}
+	return first
+}
+
+/** A session token's caller, until it ends; `undefined` for an unknown one. */
+async function callerOf(
+	token: string,
+	users: Users,
+	expires: (at: Date) => void,
+): Promise<Identity | undefined> {
+	const session = await sessionOf(token)
+	if (session === undefined) return undefined
+	// A transport's queries are untyped; this is the user model's row.
+	const user: unknown = await users.queries.findUnique(
+		{ where: { id: session.userId } },
+		M,
+	)
+	if (user === null) return undefined
+	expires(session.expiresAt)
+	// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- the user model is the one the application registers (D-62, D-80).
+	const caller: Identity = { kind: 'user', user: user as UserOf<Register> }
+	// The completed caller keeps this row (D-121).
+	callerTokens.set(caller.user, token)
+	return caller
+}
+
+const auth = definePlugin<Auth>({
+	name: 'auth',
+	manifest,
+	requires: { http: httpPlugin },
+	models: [AuthSession, AuthAccount],
+	hooks: {
+		// The user's sessions and accounts go with them (D-111, D-113).
+		afterDelete: async ({ record }) => {
+			await revokeSessions(record.id)
+			await unlinkAccounts(record.id)
+		},
+	},
+	commands: () => ({
+		revokeSessions: async ({ id }, options) => {
+			const caller = options?.as
+			const self = caller?.kind === 'user' && caller.user.id === id
+			if (!self && (caller === undefined || !isMaster(caller))) {
+				throw new PublicError(
+					'ACCESS_DENIED',
+					'User.revokeSessions runs as Master or as the user.',
+				)
+			}
+			await revokeSessions(id)
+		},
+	}),
+	// Its own cookie and user model: this context is not the API's.
+	functions: ({ models }) => authFunctions(cookieOf(), usersOf(models)),
+	// Built before any plugin starts, so before the server listens.
+	api: (context) => {
+		const cookie = cookieOf()
+		states.set(context, { cookie, users: usersOf(context.models) })
+		return {
+			signIn: async (userId, client) => {
+				// The cookie it replaces would leave a session nobody can end (D-115).
+				const replaced = client?.cookies.get(cookie.name)
+				if (replaced !== undefined) await closeSession(replaced)
+				const opened = await openSession(userId)
+				client?.cookies.set(cookie.name, opened.token, {
+					...cookie.options,
+					maxAge: cookieAge,
+				})
+				return opened
+			},
+			revokeSessions,
+			linkAccount,
+			accountOf,
+			subjectOf,
+		}
+	},
+	identify: async (request, context) => {
+		const { cookie, users } = stateOf(context)
+		const { hostname } = new URL(request.url)
+		if (
+			!cookie.options.secure &&
+			!warned.has(context) &&
+			!isLocalHost(hostname)
+		) {
+			warned.add(context)
+			context.logger.warn(
+				`auth serves ${hostname} a session cookie without Secure: set NODE_ENV=production.`,
+			)
+		}
+		const bearer = bearerOf(request)
+		if (bearer !== undefined) {
+			const caller = await callerOf(bearer, users, context.expires)
+			if (caller !== undefined) return caller
+			throw new PublicError(
+				'UNAUTHENTICATED',
+				'The session expired or was revoked: sign in again.',
+			)
+		}
+		// A stale cookie is anonymous: it must not lock a browser out of
+		// signing in again (D-112).
+		const token = cookieTokenOf(request, cookie)
+		if (token === undefined) return undefined
+		return callerOf(token, users, context.expires)
+	},
+})
+
+/** Sessions and the caller of each request; it requires `httpPlugin()`. */
+export const authPlugin: PluginOf<Auth> = auth.plugin
+/** auth's entry in the user model's `use`, which `defineUser` adds. */
+export const authUse: UseOf<Auth> = auth.use

package/src/rules.ts

@@ -0,0 +1,112 @@
+// auth's ready-made rules and default (D-10, D-62, D-79, D-83): each reads
+// the caller, the record's stored keys (D-77) and the value written.
+import type { Caller, CallerRule, Register, UserOf } from 'ultimabase'
+
+/** The rule "the caller is signed in" (D-10). */
+export const isAuthenticated: CallerRule = ({ caller }) =>
+	caller.kind === 'user'
+
+/**
+ * A rule for signed-in callers only, which receives `user` (D-79); it is
+ * `false` for anyone else. Its facts come from where it is used, as `anyOf`'s
+ * do; a read rule may still return a filter.
+ */
+export function signedIn<
+	Facts extends { readonly caller: Caller },
+	R extends boolean | object,
+>(
+	rule: (facts: Facts & { readonly user: UserOf<Register> }) => R,
+): (facts: Facts) => R | false {
+	return (facts) =>
+		facts.caller.kind === 'user'
+			? rule({ ...facts, user: facts.caller.user })
+			: false
+}
+
+type Ref = { readonly id: string } | null
+type Connected = { readonly connect: { readonly id: string } }
+type Keys<V, Shape> = {
+	[P in keyof V]-?: NonNullable<V[P]> extends Shape ? P : never
+}[keyof V]
+/** The relations a write may connect, which may also create (D-128). */
+type Connects<V> = {
+	[P in keyof V]-?: [Extract<NonNullable<V[P]>, Connected>] extends [never]
+		? never
+		: P
+}[keyof V]
+/**
+ * The record's `one` relations, those a create connects, or any name outside
+ * a model's rules.
+ */
+type OwnerKey<Facts> = [Facts] extends [never]
+	? string
+	: Facts extends { readonly record: infer R }
+		? Keys<R, Ref>
+		: Facts extends { readonly where: unknown }
+			? 'a read rule has no record to own'
+			: Facts extends { readonly value: infer V }
+				? Connects<V>
+				: string
+
+/** The facts it needs; a read rule's are refused on the name alone. */
+type Owned<Facts, K extends string> = Facts extends { readonly where: unknown }
+	? Facts
+	: Facts extends { readonly record: unknown }
+		? Facts & { readonly record: { readonly [P in K]: Ref } }
+		: Facts extends { readonly value: unknown }
+			? Facts
+			: Facts & { readonly record: { readonly [P in K]: Ref } }
+
+const get = (value: unknown, key: string): unknown =>
+	typeof value === 'object' && value !== null
+		? Reflect.get(value, key)
+		: undefined
+
+/**
+ * The rule "the caller is the user this `one` relation points to, before and
+ * after the write" (D-79): the stored key (D-77) when there is one, and the
+ * value written, which may only connect the caller. A create that does not
+ * write the relation leaves it to its default. Its facts come from where it
+ * is used, so a wrong name fails on the name.
+ */
+export function isOwner<
+	Facts extends { readonly caller: Caller },
+	const K extends OwnerKey<Facts>,
+>(field: K): (facts: Owned<Facts, K>) => boolean {
+	return (facts) => {
+		const { caller } = facts
+		if (caller.kind !== 'user') return false
+		const record = get(facts, 'record')
+		if (
+			record !== undefined &&
+			get(get(record, field), 'id') !== caller.user.id
+		)
+			return false
+		const written = get(get(facts, 'value'), field)
+		return (
+			written === undefined ||
+			get(get(written, 'connect'), 'id') === caller.user.id
+		)
+	}
+}
+
+/** The rule "the caller is this record" (D-62). */
+export function isSelf(facts: {
+	readonly caller: Caller
+	readonly record: { readonly id: string }
+}): boolean {
+	return (
+		facts.caller.kind === 'user' && facts.caller.user.id === facts.record.id
+	)
+}
+
+/**
+ * The default "whoever creates the record" (D-53, D-62): the signed-in
+ * caller's `{ id }`, no value otherwise. Its declared return type spares the
+ * user model's own defaults the annotation.
+ */
+export function currentUser(facts: {
+	readonly caller: Caller
+}): { readonly id: string } | undefined {
+	return facts.caller.kind === 'user' ? { id: facts.caller.user.id } : undefined
+}

package/src/sessions.ts

@@ -0,0 +1,103 @@
+// Sessions (D-112): an opaque token, of which the database keeps only the
+// SHA-256 digest, ending 30 days after its last use and one year after its
+// sign-in (D-115).
+import { createHash, randomBytes } from 'node:crypto'
+import type { Field, ModelOf, ScalarOptions } from 'ultimabase'
+import { defineModel, master, PublicError } from 'ultimabase'
+
+const M = { as: master }
+const day = 24 * 60 * 60 * 1000
+const lifetime = 30 * day
+/** A session used with less left gets its lifetime again. */
+const renewal = 15 * day
+/** No renewal takes a session past this long after its sign-in (D-115). */
+const longest = 365 * day
+
+type SessionFields = {
+	readonly tokenHash: Field<string, { readonly unique: true }>
+	readonly userId: Field<string, ScalarOptions<string>>
+	readonly expiresAt: Field<Date, ScalarOptions<Date>>
+}
+
+/** auth's own model (D-110). */
+export const AuthSession: ModelOf<'AuthSession', SessionFields, []> =
+	defineModel({
+		name: 'AuthSession',
+		fields: (f) => ({
+			tokenHash: f.string({ unique: true }),
+			userId: f.string(),
+			expiresAt: f.dateTime(),
+		}),
+		indexes: [{ fields: ['userId'] }, { fields: ['expiresAt'] }],
+	})
+
+const digest = (token: string): string =>
+	createHash('sha256').update(token).digest('base64url')
+
+/** A token shown once, and the session it opens. */
+export interface Opened {
+	readonly token: string
+	readonly expiresAt: Date
+}
+
+/** Opens a session for `userId`, ending every expired one (D-115). */
+export async function openSession(userId: string): Promise<Opened> {
+	const now = Date.now()
+	await AuthSession.deleteMany(
+		{ where: { expiresAt: { lte: new Date(now) } } },
+		M,
+	)
+	const token = randomBytes(32).toString('base64url')
+	const expiresAt = new Date(now + lifetime)
+	await AuthSession.create(
+		{ data: { tokenHash: digest(token), userId, expiresAt } },
+		M,
+	)
+	return { token, expiresAt }
+}
+
+/**
+ * The session `token` opened, renewed when it has less than 15 days left, up
+ * to one year after its sign-in; `undefined` for an unknown one, or an
+ * expired one, deleted.
+ */
+export async function sessionOf(
+	token: string,
+): Promise<{ readonly userId: string; readonly expiresAt: Date } | undefined> {
+	const tokenHash = digest(token)
+	const session = await AuthSession.findUnique({ where: { tokenHash } }, M)
+	if (session === null) return undefined
+	const now = Date.now()
+	const left = session.expiresAt.getTime() - now
+	if (left <= 0) {
+		await AuthSession.deleteMany({ where: { tokenHash } }, M)
+		return undefined
+	}
+	const end = Math.min(now + lifetime, session.createdAt.getTime() + longest)
+	if (left < renewal && end > session.expiresAt.getTime()) {
+		try {
+			await AuthSession.update(
+				{ where: { tokenHash }, data: { expiresAt: new Date(end) } },
+				M,
+			)
+		} catch (error) {
+			// Signed out between the read and the renewal: the session ended.
+			if (error instanceof PublicError && error.code === 'NOT_FOUND') {
+				return undefined
+			}
+			throw error
+		}
+		return { userId: session.userId, expiresAt: new Date(end) }
+	}
+	return session
+}
+
+/** Ends the session `token` opened, if any. */
+export async function closeSession(token: string): Promise<void> {
+	await AuthSession.deleteMany({ where: { tokenHash: digest(token) } }, M)
+}
+
+/** Ends every session of a user. */
+export async function revokeSessions(userId: string): Promise<void> {
+	await AuthSession.deleteMany({ where: { userId } }, M)
+}