@ultimabase/auth 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @ultimabase/auth
+
+## 0.1.0
+
+### Minor Changes
+
+- 0e885c4: The first release: the kernel, its adapters, transports and plugins, the testing helpers and the starter.
+
+### Patch Changes
+
+- Updated dependencies [0e885c4]
+  - @ultimabase/http@0.1.0
+  - ultimabase@0.1.0

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# @ultimabase/auth
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Authentication for UltimaBase. It declares the user model, keeps the sessions, and gives each request its caller: the user its session names. A sign-in plugin, as `@ultimabase/password`, adds the way to sign in.
+
+Documentation: [Authentication](https://ultimabase.dev/docs/auth).

package/dist/accounts.d.ts

@@ -0,0 +1,20 @@
+import type { Field, ModelOf, ScalarOptions } from 'ultimabase';
+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 declare const AuthAccount: ModelOf<'AuthAccount', AccountFields, []>;
+/** Links `userId` to `subject` of `method`; a taken pair is a `UNIQUE_VIOLATION`. */
+export declare function linkAccount(userId: string, method: string, subject: string): Promise<void>;
+/** The user `subject` of `method` signs in as, if any. */
+export declare function accountOf(method: string, subject: string): Promise<{
+    readonly userId: string;
+} | undefined>;
+/** The subject `userId` is known by to `method`, if linked (D-117). */
+export declare function subjectOf(userId: string, method: string): Promise<string | undefined>;
+/** Unlinks every account of a user. */
+export declare function unlinkAccounts(userId: string): Promise<void>;
+export {};
+//# sourceMappingURL=accounts.d.ts.map

package/dist/accounts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"accounts.d.ts","sourceRoot":"","sources":["../src/accounts.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAK/D,KAAK,aAAa,GAAG;IACpB,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAAA;IACrD,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAAA;IACrD,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAAA;CACtD,CAAA;AAED,gCAAgC;AAChC,eAAO,MAAM,WAAW,EAAE,OAAO,CAAC,aAAa,EAAE,aAAa,EAAE,EAAE,CAY/D,CAAA;AAEH,qFAAqF;AACrF,wBAAsB,WAAW,CAChC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAEf;AAED,0DAA0D;AAC1D,wBAAsB,SAAS,CAC9B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GACb,OAAO,CAAC;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAAC,CAMlD;AAED,uEAAuE;AACvE,wBAAsB,SAAS,CAC9B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACZ,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAM7B;AAED,uCAAuC;AACvC,wBAAsB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAElE"}

package/dist/accounts.js

@@ -0,0 +1,33 @@
+import { defineModel, master } from 'ultimabase';
+const M = { as: master };
+/** auth's own model (D-110). */
+export const AuthAccount = 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, method, subject) {
+    await AuthAccount.create({ data: { userId, method, subject } }, M);
+}
+/** The user `subject` of `method` signs in as, if any. */
+export async function accountOf(method, subject) {
+    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, method) {
+    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) {
+    await AuthAccount.deleteMany({ where: { userId } }, M);
+}

package/dist/define-user.d.ts

@@ -0,0 +1,16 @@
+import type { FieldShapes, IndexShape, ModelFields, ModelIndexes, ModelOf, ModelUse, PluginTypes } from 'ultimabase';
+import type { Auth } 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 declare 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>;
+export {};
+//# sourceMappingURL=define-user.d.ts.map

package/dist/define-user.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-user.d.ts","sourceRoot":"","sources":["../src/define-user.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACX,WAAW,EACX,UAAU,EACV,WAAW,EACX,YAAY,EACZ,OAAO,EACP,QAAQ,EACR,WAAW,EACX,MAAM,YAAY,CAAA;AAEnB,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAGvC,KAAK,IAAI,GAAG,SAAS,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,EAAE,CAAA;AACpD,wEAAwE;AACxE,KAAK,QAAQ,CAAC,CAAC,SAAS,IAAI,IAAI,SAAS,CAAC,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC,CAAA;AAEvE,+CAA+C;AAC/C,wBAAgB,UAAU,CACzB,KAAK,CAAC,CAAC,SAAS,MAAM,EACtB,KAAK,CAAC,CAAC,SAAS,WAAW,EAC3B,KAAK,CAAC,CAAC,SAAS,IAAI,GAAG,EAAE,EACzB,KAAK,CAAC,CAAC,SAAS,SAAS,UAAU,EAAE,GAAG,EAAE,EACzC,UAAU,EAAE;IACb,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAA;IAChB,sDAAsD;IACtD,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAA;IAChB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAA;IAC5C,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAA;CAClD,GAAG,OAAO,CAAC,CAAC,EAAE,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAShC"}

package/dist/define-user.js

@@ -0,0 +1,13 @@
+import { defineModel } from 'ultimabase';
+import { authUse, userModels } from './plugin.js';
+/** The application's one user model (D-62). */
+export function defineUser(definition) {
+    const model = 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;
+    userModels.set(model, user.nullable());
+    return user;
+}

package/dist/functions.d.ts

@@ -0,0 +1,12 @@
+import type { FunctionShape, ModelQueries, OutputSpec } from 'ultimabase';
+import type { Cookie } from './token.ts';
+/** Each session's token, by the user row `identify` read for it (D-121). */
+export declare const callerTokens: WeakMap<object, string>;
+/** 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 declare function authFunctions(cookie: Cookie, users: Users): readonly FunctionShape[];
+//# sourceMappingURL=functions.d.ts.map

package/dist/functions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"functions.d.ts","sourceRoot":"","sources":["../src/functions.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AAGzE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAExC,4EAA4E;AAC5E,eAAO,MAAM,YAAY,EAAE,OAAO,CAAC,MAAM,EAAE,MAAM,CAAiB,CAAA;AAElE,kEAAkE;AAClE,MAAM,WAAW,KAAK;IACrB,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAA;IAC9B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;CAC3B;AAED,kEAAkE;AAClE,wBAAgB,aAAa,CAC5B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,KAAK,GACV,SAAS,aAAa,EAAE,CAuB1B"}

package/dist/functions.js

@@ -0,0 +1,25 @@
+import { allow, defineFunction } from 'ultimabase';
+import { closeSession } from './sessions.js';
+/** Each session's token, by the user row `identify` read for it (D-121). */
+export const callerTokens = new WeakMap();
+/** `signOut` and `viewer`, public: each reads the caller only. */
+export function authFunctions(cookie, users) {
+    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/dist/index.d.ts

@@ -0,0 +1,5 @@
+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';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAC7C,YAAY,EAAE,IAAI,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACtE,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EACN,WAAW,EACX,eAAe,EACf,OAAO,EACP,MAAM,EACN,QAAQ,GACR,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,5 @@
+// `@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.js';
+export { authPlugin } from './plugin.js';
+export { currentUser, isAuthenticated, isOwner, isSelf, signedIn, } from './rules.js';

package/dist/plugin.d.ts

@@ -0,0 +1,45 @@
+import type { Http } from '@ultimabase/http';
+import type { Client, Identity, OutputSpec, PluginOf, PluginTypes, UseOf } from 'ultimabase';
+import type { Opened } from './sessions.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 declare const userModels: WeakMap<object, OutputSpec>;
+/** Sessions and the caller of each request; it requires `httpPlugin()`. */
+export declare const authPlugin: PluginOf<Auth>;
+/** auth's entry in the user model's `use`, which `defineUser` adds. */
+export declare const authUse: UseOf<Auth>;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AAE5C,OAAO,KAAK,EACX,MAAM,EACN,QAAQ,EACR,UAAU,EACV,QAAQ,EACR,WAAW,EAEX,KAAK,EAEL,MAAM,YAAY,CAAA;AAmBnB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAW3C,YAAY,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAE3C,iEAAiE;AACjE,MAAM,WAAW,OAAO;IACvB;;;OAGG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACxD,oCAAoC;IACpC,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC7C,qFAAqF;IACrF,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC3E,0DAA0D;IAC1D,SAAS,CACR,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GACb,OAAO,CAAC;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC,CAAA;IACnD,uEAAuE;IACvE,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAA;CACtE;AAED,iDAAiD;AACjD,MAAM,WAAW,YAAY;IAC5B,gEAAgE;IAChE,cAAc,CACb,KAAK,EAAE;QAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;KAAE,EAC9B,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,CAAC,EAAE,QAAQ,CAAA;KAAE,GAClC,OAAO,CAAC,IAAI,CAAC,CAAA;CAChB;AAED,2BAA2B;AAC3B,MAAM,WAAW,IAAK,SAAQ,WAAW;IACxC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,EAAE,IAAI,CAAA;IACvB,QAAQ,CAAC,GAAG,EAAE,OAAO,CAAA;IACrB,QAAQ,CAAC,QAAQ,EAAE,YAAY,CAAA;CAC/B;AAED,gFAAgF;AAChF,eAAO,MAAM,UAAU,EAAE,OAAO,CAAC,MAAM,EAAE,UAAU,CAAiB,CAAA;AA6IpE,2EAA2E;AAC3E,eAAO,MAAM,UAAU,EAAE,QAAQ,CAAC,IAAI,CAAe,CAAA;AACrD,uEAAuE;AACvE,eAAO,MAAM,OAAO,EAAE,KAAK,CAAC,IAAI,CAAY,CAAA"}

package/dist/plugin.js

@@ -0,0 +1,124 @@
+import { httpPlugin } from '@ultimabase/http';
+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.js';
+import { authFunctions, callerTokens } from './functions.js';
+import { AuthSession, closeSession, openSession, revokeSessions, sessionOf, } from './sessions.js';
+import { bearerOf, cookieAge, cookieOf, cookieTokenOf } from './token.js';
+/** The models `defineUser` returned, each with its output `User`, or `null`. */
+export const userModels = new WeakMap();
+const states = new WeakMap();
+/** The contexts whose insecure cookie was warned about (D-115). */
+const warned = new WeakSet();
+const M = { as: master };
+function stateOf(context) {
+    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) {
+    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, users, expires) {
+    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 = 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 = { kind: 'user', user: user };
+    // The completed caller keeps this row (D-121).
+    callerTokens.set(caller.user, token);
+    return caller;
+}
+const auth = definePlugin({
+    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 = auth.plugin;
+/** auth's entry in the user model's `use`, which `defineUser` adds. */
+export const authUse = auth.use;

package/dist/rules.d.ts

@@ -0,0 +1,84 @@
+import type { Caller, CallerRule, Register, UserOf } from 'ultimabase';
+/** The rule "the caller is signed in" (D-10). */
+export declare const isAuthenticated: CallerRule;
+/**
+ * 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 declare function signedIn<Facts extends {
+    readonly caller: Caller;
+}, R extends boolean | object>(rule: (facts: Facts & {
+    readonly user: UserOf<Register>;
+}) => R): (facts: Facts) => R | 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;
+    };
+};
+/**
+ * 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 declare function isOwner<Facts extends {
+    readonly caller: Caller;
+}, const K extends OwnerKey<Facts>>(field: K): (facts: Owned<Facts, K>) => boolean;
+/** The rule "the caller is this record" (D-62). */
+export declare function isSelf(facts: {
+    readonly caller: Caller;
+    readonly record: {
+        readonly id: string;
+    };
+}): boolean;
+/**
+ * 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 declare function currentUser(facts: {
+    readonly caller: Caller;
+}): {
+    readonly id: string;
+} | undefined;
+export {};
+//# sourceMappingURL=rules.d.ts.map

package/dist/rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rules.d.ts","sourceRoot":"","sources":["../src/rules.ts"],"names":[],"mappings":"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"}

package/dist/rules.js

@@ -0,0 +1,48 @@
+/** The rule "the caller is signed in" (D-10). */
+export const isAuthenticated = ({ 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(rule) {
+    return (facts) => facts.caller.kind === 'user'
+        ? rule({ ...facts, user: facts.caller.user })
+        : false;
+}
+const get = (value, key) => 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(field) {
+    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) {
+    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) {
+    return facts.caller.kind === 'user' ? { id: facts.caller.user.id } : undefined;
+}

package/dist/sessions.d.ts

@@ -0,0 +1,32 @@
+import type { Field, ModelOf, ScalarOptions } from 'ultimabase';
+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 declare const AuthSession: ModelOf<'AuthSession', SessionFields, []>;
+/** 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 declare function openSession(userId: string): Promise<Opened>;
+/**
+ * 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 declare function sessionOf(token: string): Promise<{
+    readonly userId: string;
+    readonly expiresAt: Date;
+} | undefined>;
+/** Ends the session `token` opened, if any. */
+export declare function closeSession(token: string): Promise<void>;
+/** Ends every session of a user. */
+export declare function revokeSessions(userId: string): Promise<void>;
+export {};
+//# sourceMappingURL=sessions.d.ts.map

package/dist/sessions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.d.ts","sourceRoot":"","sources":["../src/sessions.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAW/D,KAAK,aAAa,GAAG;IACpB,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAA;KAAE,CAAC,CAAA;IAC5D,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,aAAa,CAAC,MAAM,CAAC,CAAC,CAAA;IACrD,QAAQ,CAAC,SAAS,EAAE,KAAK,CAAC,IAAI,EAAE,aAAa,CAAC,IAAI,CAAC,CAAC,CAAA;CACpD,CAAA;AAED,gCAAgC;AAChC,eAAO,MAAM,WAAW,EAAE,OAAO,CAAC,aAAa,EAAE,aAAa,EAAE,EAAE,CAS/D,CAAA;AAKH,oDAAoD;AACpD,MAAM,WAAW,MAAM;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAA;CACxB;AAED,sEAAsE;AACtE,wBAAsB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAajE;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAC9B,KAAK,EAAE,MAAM,GACX,OAAO,CAAC;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAA;CAAE,GAAG,SAAS,CAAC,CA2B5E;AAED,+CAA+C;AAC/C,wBAAsB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/D;AAED,oCAAoC;AACpC,wBAAsB,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAElE"}

package/dist/sessions.js

@@ -0,0 +1,72 @@
+// 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 { 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;
+/** auth's own model (D-110). */
+export const AuthSession = defineModel({
+    name: 'AuthSession',
+    fields: (f) => ({
+        tokenHash: f.string({ unique: true }),
+        userId: f.string(),
+        expiresAt: f.dateTime(),
+    }),
+    indexes: [{ fields: ['userId'] }, { fields: ['expiresAt'] }],
+});
+const digest = (token) => createHash('sha256').update(token).digest('base64url');
+/** Opens a session for `userId`, ending every expired one (D-115). */
+export async function openSession(userId) {
+    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) {
+    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) {
+    await AuthSession.deleteMany({ where: { tokenHash: digest(token) } }, M);
+}
+/** Ends every session of a user. */
+export async function revokeSessions(userId) {
+    await AuthSession.deleteMany({ where: { userId } }, M);
+}

package/dist/token.d.ts

@@ -0,0 +1,19 @@
+import type { CookieOptions } from 'ultimabase';
+/** The longest a browser keeps a cookie: 400 days. */
+export declare const cookieAge: number;
+/** The cookie's name and attributes, read once when the application starts. */
+export interface Cookie {
+    readonly name: string;
+    /** Its attributes but `maxAge`, the same to set and to clear it. */
+    readonly options: CookieOptions;
+}
+/** Secure and `__Host-` in production, so it works on `http://localhost`. */
+export declare function cookieOf(): Cookie;
+/**
+ * The token the `Authorization` header sends, `''` for a Bearer without one,
+ * `undefined` without a Bearer header, which another plugin may read.
+ */
+export declare function bearerOf(request: Request): string | undefined;
+/** The token the cookie sends, if any. */
+export declare function cookieTokenOf(request: Request, cookie: Cookie): string | undefined;
+//# sourceMappingURL=token.d.ts.map

package/dist/token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../src/token.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE/C,sDAAsD;AACtD,eAAO,MAAM,SAAS,EAAE,MAA2B,CAAA;AAEnD,+EAA+E;AAC/E,MAAM,WAAW,MAAM;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,oEAAoE;IACpE,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAA;CAC/B;AAED,6EAA6E;AAC7E,wBAAgB,QAAQ,IAAI,MAAM,CAOjC;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAK7D;AAED,0CAA0C;AAC1C,wBAAgB,aAAa,CAC5B,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,MAAM,GACZ,MAAM,GAAG,SAAS,CAOpB"}