@aventara/access 0.0.0-stage → 0.1.0-rc.0

package/dist/client/access-client.factory.js

@@ -0,0 +1,269 @@
+// `access.client`: what the framework's `$access` reads from an Access instance,
+// through the provider member `AvAccessProvider.client`. Where Access is mounted (`url`,
+// from Better Auth's `baseURL` and `basePath`), and for each verb the instance
+// serves, its route, its shapes and its server call.
+//
+// A verb is offered only where its route answers: `signIn`, `signUp` and
+// `resetPassword` with Better Auth's `emailAndPassword` on (`signUp` not with
+// `disableSignUp`), no verb whose path `disabledPaths` lists, and on the `service`
+// profile no verb that starts a session (`signIn`, `signUp`), by the same rule its
+// hooks refuse those routes with.
+//
+// On the `kiosk` profile, `verbs` holds the kiosk's verbs too (`switchUser`,
+// `lock`, `setPin`, `enrollDevice`, `revokeDevice`), in the same form: the
+// framework's `$access` takes them as known optional verbs. A manager's device list
+// (`GET /kiosk/list-devices`, and `access.kiosk` on the server) is no verb: the
+// framework's set of verbs is closed.
+//
+// `call` is the server's way in (a Server Action, a Nest controller): it runs the
+// verb in-process through Better Auth's API, so a cookie plugin such as Better
+// Auth's `nextCookies()` sets the browser's cookie from the answer. It runs the
+// verb as the request it stands for: Better Auth gets a request built from the
+// caller's headers, so everything Better Auth and Access hold a request to holds
+// here too (the `service` profile's refusals, the endpoint's own CSRF check, the
+// audit log's `client` origin), and the Access plugin runs Better Auth's own origin
+// check on it, the one its router runs before every route (`originCheckMiddleware`:
+// the `Origin` of a request with a cookie, and every `callbackURL` and `redirectTo`
+// against `trustedOrigins`). Its arguments are held to the verb's schema, and its
+// answer is cut to the verb's result schema: no session token and no user field
+// leaves it. `me` reads the request's identity as `access.state` does, from its
+// bearer token or (profile `web`) its session cookie, and answers it, `{ sub,
+// claims }`, or `null`.
+import { servesRoute, } from "../access/profile.policy.js";
+import { KIOSK_VERBS, } from "../kiosk/kiosk-verbs.schema.js";
+import { BETTER_AUTH_VERBS, ME_PATH, meSchema, projected, schemaDefect, } from "./access-verbs.schema.js";
+/** Better Auth's names for the statuses a plugin refuses with; another status is thrown as its number. */
+const STATUS_NAMES = {
+    400: "BAD_REQUEST",
+    401: "UNAUTHORIZED",
+    403: "FORBIDDEN",
+    404: "NOT_FOUND",
+    429: "TOO_MANY_REQUESTS",
+    500: "INTERNAL_SERVER_ERROR",
+};
+const NO_ARGS = {
+    type: "object",
+    properties: {},
+    additionalProperties: false,
+};
+const headersOf = (given) => {
+    const headers = new Headers();
+    given.forEach((value, name) => {
+        headers.append(name, value);
+    });
+    return headers;
+};
+/** The verbs on Better Auth's routes, in the order `access.client` lists them. */
+const BETTER_AUTH_VERB_NAMES = [
+    "signIn",
+    "signUp",
+    "signOut",
+    "resetPassword",
+];
+/** Freezes a verb, the verbs or the client: published data, not to be changed. */
+const freeze = Object.freeze;
+/** A path without its trailing slashes, `/` kept as `/`. */
+const trimmed = (path) => path.replace(/\/+$/, "") || "/";
+/**
+ * Builds `access.client` for an instance: from its Better Auth options (`baseURL`,
+ * `basePath`, `emailAndPassword`, `disabledPaths`), its profile and its declared
+ * claims.
+ */
+export const accessClient = (input) => {
+    const { block, kind } = input;
+    const basePath = typeof block.basePath === "string" ? block.basePath : undefined;
+    const dynamic = input.isDynamicBaseURL(block.baseURL);
+    // A dynamic base URL follows the request's host: the client reaches Access on its
+    // own origin, at the base path. A fixed one (or Better Auth's environment
+    // variables) is where Access is.
+    const absolute = dynamic
+        ? input.baseOf(block.baseURL.fallback, basePath)
+        : input.baseOf(typeof block.baseURL === "string" ? block.baseURL : undefined, basePath);
+    if (absolute === undefined) {
+        // `createAccess` refuses an instance without a base URL before it gets here.
+        throw new TypeError("access.client: Better Auth has no base URL");
+    }
+    const base = trimmed(absolute);
+    const url = dynamic ? trimmed(new URL(absolute).pathname) : base;
+    const emailAndPassword = (block.emailAndPassword ?? {});
+    const disabled = Array.isArray(block.disabledPaths)
+        ? block.disabledPaths
+        : [];
+    const passwords = emailAndPassword.enabled === true;
+    const offered = {
+        signIn: passwords,
+        signUp: passwords && emailAndPassword.disableSignUp !== true,
+        signOut: true,
+        resetPassword: passwords,
+    };
+    const argsChecked = (verb, schema, args) => {
+        const defect = schemaDefect(schema ?? NO_ARGS, args ?? {}, "args");
+        if (defect !== undefined) {
+            throw new input.refusal("BAD_REQUEST", {
+                message: `$access.${verb}: ${defect}.`,
+            });
+        }
+    };
+    /**
+     * The identifier a call names, for its rate limit's target: the email, read as
+     * the sign-in route reads it (sign-up's too, so one address is one target), or a
+     * password reset's token.
+     */
+    const identifierOf = (verb, args) => {
+        if (verb !== "resetPassword") {
+            return input.identify("/sign-in/email", args);
+        }
+        const { token } = args;
+        return `reset-token:${token}`;
+    };
+    /**
+     * Every plugin's `onRequest`, in the order Better Auth's router runs them before
+     * a route (a server call skips them): a refusal is thrown as Better Auth's
+     * `APIError` with the plugin's status and body; a new request takes the place of
+     * the old one. Answers the request the route runs with.
+     */
+    const pluginsAdmit = async (request) => {
+        const context = await input.context();
+        const plugins = context.options.plugins;
+        let current = request;
+        for (let at = 0; plugins !== undefined && at < plugins.length; at += 1) {
+            const onRequest = plugins[at]?.onRequest;
+            if (onRequest === undefined) {
+                continue;
+            }
+            const answer = ((await onRequest(current, context)) ?? {});
+            const refused = answer.response;
+            if (refused !== undefined) {
+                let body;
+                try {
+                    body = (await refused.clone().json());
+                }
+                catch {
+                    body = { message: await refused.text() };
+                }
+                const headers = {};
+                refused.headers.forEach((value, name) => {
+                    headers[name] = value;
+                });
+                throw new input.refusal(STATUS_NAMES[refused.status] ?? refused.status, body, headers);
+            }
+            if (answer.request !== undefined) {
+                current = answer.request;
+            }
+        }
+        return current;
+    };
+    /**
+     * One verb on a route of Better Auth's router (Better Auth's own or Access's), as
+     * published: its route, its shapes and its `call`. `limited` puts the call under
+     * the rate limit first (`signOut` and `lock` are not), `identifier` names its
+     * target for the limit's second bucket.
+     */
+    const routed = (verb, route, limited, identifier) => {
+        const published = {
+            method: route.method,
+            path: route.path,
+            result: route.result,
+            call: async ({ args, headers, }) => {
+                argsChecked(verb, route.args, args);
+                const forwarded = headersOf(headers);
+                // The request this call stands for, as the route would get it: the
+                // caller's headers and the arguments as its JSON body.
+                forwarded.delete("content-length");
+                forwarded.delete("transfer-encoding");
+                if (args !== undefined) {
+                    forwarded.set("content-type", "application/json");
+                }
+                const built = new Request(`${base}${route.path}`, {
+                    method: route.method,
+                    headers: forwarded,
+                    body: args === undefined ? null : JSON.stringify(args),
+                });
+                // In the router's order: its rate limit, then the plugins' `onRequest`.
+                const settle = limited
+                    ? await input.limit({
+                        path: route.path,
+                        headers: forwarded,
+                        request: built,
+                        identifier: identifier(args),
+                    })
+                    : undefined;
+                const request = await pluginsAdmit(built);
+                let body = args;
+                if (request !== built && args !== undefined) {
+                    // A plugin's new request: its body is what the route reads.
+                    body = await request.clone().json();
+                    argsChecked(verb, route.args, body);
+                }
+                input.calls.add(request);
+                // A refusal keeps the target's count; a success clears it.
+                const answer = await input.api()[route.endpoint]({
+                    body,
+                    headers: request.headers,
+                    request,
+                    asResponse: false,
+                });
+                await settle?.();
+                return projected(route.result, answer);
+            },
+        };
+        if (route.args !== undefined) {
+            published.args = route.args;
+        }
+        freeze(published);
+        return published;
+    };
+    const verbs = {};
+    for (let at = 0; at < BETTER_AUTH_VERB_NAMES.length; at += 1) {
+        const verb = BETTER_AUTH_VERB_NAMES[at];
+        const route = BETTER_AUTH_VERBS[verb];
+        if (!offered[verb] ||
+            !servesRoute(kind, route.path) ||
+            disabled.includes(route.path)) {
+            continue;
+        }
+        verbs[verb] = routed(verb, route, verb !== "signOut", (args) => verb === "signOut" ? undefined : identifierOf(verb, args));
+    }
+    if (!disabled.includes(ME_PATH)) {
+        const me = {
+            method: "GET",
+            path: ME_PATH,
+            result: meSchema(input.claims),
+            call: async ({ args, headers, request, }) => {
+                argsChecked("me", undefined, args);
+                return input.identityOf(headers, request);
+            },
+        };
+        freeze(me);
+        verbs.me = me;
+    }
+    if (kind === "kiosk") {
+        for (const verb of Object.keys(KIOSK_VERBS)) {
+            const route = KIOSK_VERBS[verb];
+            if (!disabled.includes(route.path)) {
+                verbs[verb] = routed(verb, route, verb !== "lock", () => undefined);
+            }
+        }
+    }
+    freeze(verbs);
+    const client = { url, verbs };
+    freeze(client);
+    return client;
+};
+/**
+ * Access's `GET /me` route (under Better Auth's base path), keyed as Better Auth keys
+ * a plugin's endpoints (`access.api.accessMe`): the request's identity, `{ sub,
+ * claims }`, or `null`, as `access.client.verbs.me.call` answers it. Never cached.
+ */
+export const meEndpoint = (endpoint, identityOf) => ({
+    accessMe: endpoint(ME_PATH, { method: "GET" }, async (context) => {
+        const identity = await identityOf(context.headers ?? new Headers(), context.request);
+        return new Response(JSON.stringify(identity), {
+            status: 200,
+            headers: {
+                "content-type": "application/json",
+                "cache-control": "no-store",
+            },
+        });
+    }),
+});

package/dist/client/access-verbs.schema.d.ts

@@ -0,0 +1,66 @@
+import type { AccessClaimsDeclaration } from "../access/claims.mapper.js";
+/** A verb `$access` offers through Access's routes (`can` is the framework's own). */
+export type AccessVerbName = "signIn" | "signUp" | "signOut" | "resetPassword" | "me";
+/** A closed object, in the ClientContract's form: its properties, the required ones, and no other key. */
+type ObjectSchema = {
+    readonly type: "object";
+    readonly properties: {
+        readonly [key: string]: AccessVerbSchema;
+    };
+    readonly required?: readonly string[];
+    readonly additionalProperties: false;
+};
+/** A JSON Schema in the ClientContract's forms, as Access writes them: scalars and closed objects. */
+export type AccessVerbSchema = {
+    readonly type: "string" | "number" | "boolean";
+} | ObjectSchema;
+/** One verb's route: the method, the path under Better Auth's base path, and the schemas. */
+export type AccessVerbRoute = {
+    readonly method: "GET" | "POST";
+    readonly path: string;
+    readonly args?: ObjectSchema;
+    readonly result: ObjectSchema;
+    /** The key of Better Auth's server API (`access.api.<key>`) the verb's server call runs. */
+    readonly endpoint: "signInEmail" | "signUpEmail" | "signOut" | "resetPassword" | "kioskSwitchUser" | "kioskLock" | "kioskSetPin" | "kioskEnrollDevice" | "kioskRevokeDevice";
+};
+export declare const STRING: {
+    readonly type: "string";
+};
+export declare const BOOLEAN: {
+    readonly type: "boolean";
+};
+/** A closed object schema: its properties, the required ones, and no other key. */
+export declare const closed: (properties: {
+    readonly [key: string]: AccessVerbSchema;
+}, required: readonly string[]) => ObjectSchema;
+/** The signed-in user, as a result names it: its id, the token's `sub`, and nothing of its record. */
+export declare const USER: ObjectSchema;
+/**
+ * The verbs on Better Auth's routes (better-auth 1.7.12 to 1.7.14): the arguments its client
+ * sends on each, and what Access promises of each answer.
+ */
+export declare const BETTER_AUTH_VERBS: {
+    readonly signIn: AccessVerbRoute;
+    readonly signUp: AccessVerbRoute;
+    readonly signOut: AccessVerbRoute;
+    readonly resetPassword: AccessVerbRoute;
+};
+/** Access's own route for `me`, under Better Auth's base path. */
+export declare const ME_PATH = "/me";
+/**
+ * `me`'s result: the token identity, `sub` and the declared claims, each typed as
+ * declared and each optional (a user may hold none of them). Nothing else.
+ */
+export declare const meSchema: (claims: AccessClaimsDeclaration) => ObjectSchema;
+/**
+ * Why `value` does not fit `schema`, or `undefined` when it does: a key the schema
+ * does not name, a required key missing, or a value of another type. The sentence
+ * names the key and the type, never the value.
+ */
+export declare const schemaDefect: (schema: AccessVerbSchema, value: unknown, at: string) => string | undefined;
+/**
+ * Better Auth's answer, cut to what `schema` names: a key it does not name (the
+ * session token, a user field) is left out, and so is a value of another type.
+ */
+export declare const projected: (schema: AccessVerbSchema, value: unknown) => unknown;
+export {};

package/dist/client/access-verbs.schema.js

@@ -0,0 +1,159 @@
+// The `$access` verbs' routes and shapes: what `access.client` publishes for the
+// framework's clients. Each verb is one of Better Auth's routes (its method and its
+// path under Better Auth's base path), except `me`, which is Access's own. Its
+// arguments are the ones Better Auth's client takes on that route
+// (`authClient.signIn.email({ email, password })`), and its result names what Access
+// promises of the answer: the signed-in user's id (`sub`) and Better Auth's own
+// flags, never a session token or a user field. `me`'s result is the token identity,
+// `{ sub, claims }`, with the claims `policies.claims` declares and nothing else.
+//
+// The schemas are written in the JSON Schema forms the framework's ClientContract
+// takes (`validateClientContractStructure`): every object closed
+// (`additionalProperties: false`), an optional key left out of `required`, and no
+// keyword beyond those forms.
+import { isRecord } from "../policies.compiler.js";
+export const STRING = { type: "string" };
+export const BOOLEAN = { type: "boolean" };
+/** A closed object schema: its properties, the required ones, and no other key. */
+export const closed = (properties, required) => required.length === 0
+    ? { type: "object", properties, additionalProperties: false }
+    : { type: "object", properties, required, additionalProperties: false };
+/** The signed-in user, as a result names it: its id, the token's `sub`, and nothing of its record. */
+export const USER = closed({ id: STRING }, ["id"]);
+/**
+ * The verbs on Better Auth's routes (better-auth 1.7.12 to 1.7.14): the arguments its client
+ * sends on each, and what Access promises of each answer.
+ */
+export const BETTER_AUTH_VERBS = {
+    signIn: {
+        method: "POST",
+        path: "/sign-in/email",
+        args: closed({
+            email: STRING,
+            password: STRING,
+            callbackURL: STRING,
+            rememberMe: BOOLEAN,
+        }, ["email", "password"]),
+        result: closed({ redirect: BOOLEAN, url: STRING, user: USER }, [
+            "redirect",
+            "user",
+        ]),
+        endpoint: "signInEmail",
+    },
+    signUp: {
+        method: "POST",
+        path: "/sign-up/email",
+        args: closed({
+            name: STRING,
+            email: STRING,
+            password: STRING,
+            image: STRING,
+            callbackURL: STRING,
+            rememberMe: BOOLEAN,
+        }, ["name", "email", "password"]),
+        result: closed({ user: USER }, ["user"]),
+        endpoint: "signUpEmail",
+    },
+    signOut: {
+        method: "POST",
+        path: "/sign-out",
+        result: closed({ success: BOOLEAN }, ["success"]),
+        endpoint: "signOut",
+    },
+    resetPassword: {
+        method: "POST",
+        path: "/reset-password",
+        args: closed({ newPassword: STRING, token: STRING }, [
+            "newPassword",
+            "token",
+        ]),
+        result: closed({ status: BOOLEAN }, ["status"]),
+        endpoint: "resetPassword",
+    },
+};
+/** Access's own route for `me`, under Better Auth's base path. */
+export const ME_PATH = "/me";
+/**
+ * `me`'s result: the token identity, `sub` and the declared claims, each typed as
+ * declared and each optional (a user may hold none of them). Nothing else.
+ */
+export const meSchema = (claims) => {
+    const declared = {};
+    for (const claim of Object.keys(claims)) {
+        declared[claim] = {
+            type: claims[claim],
+        };
+    }
+    return closed({ sub: STRING, claims: closed(declared, []) }, [
+        "sub",
+        "claims",
+    ]);
+};
+/** What a refused value is, never the value: arguments carry passwords. */
+const kindOf = (value) => Array.isArray(value)
+    ? "an array"
+    : value === null
+        ? "null"
+        : typeof value === "object"
+            ? "an object"
+            : `a ${typeof value}`;
+/**
+ * Why `value` does not fit `schema`, or `undefined` when it does: a key the schema
+ * does not name, a required key missing, or a value of another type. The sentence
+ * names the key and the type, never the value.
+ */
+export const schemaDefect = (schema, value, at) => {
+    if (schema.type !== "object") {
+        return typeof value === schema.type
+            ? undefined
+            : `${at} is ${kindOf(value)}, not a ${schema.type}`;
+    }
+    if (!isRecord(value)) {
+        return `${at} is ${kindOf(value)}, not an object`;
+    }
+    for (const key of Object.keys(value)) {
+        if (!Object.hasOwn(schema.properties, key)) {
+            return `${at} has \`${key}\`, which it does not take (it takes ${Object.keys(schema.properties).join(", ") || "nothing"})`;
+        }
+    }
+    const required = schema.required;
+    for (let index = 0; required !== undefined && index < required.length; index += 1) {
+        const key = required[index];
+        if (value[key] === undefined) {
+            return `${at} lacks \`${key}\``;
+        }
+    }
+    for (const key of Object.keys(schema.properties)) {
+        const member = value[key];
+        const property = schema.properties[key];
+        if (member === undefined || property === undefined) {
+            continue;
+        }
+        const defect = schemaDefect(property, member, `${at}.${key}`);
+        if (defect !== undefined) {
+            return defect;
+        }
+    }
+    return undefined;
+};
+/**
+ * Better Auth's answer, cut to what `schema` names: a key it does not name (the
+ * session token, a user field) is left out, and so is a value of another type.
+ */
+export const projected = (schema, value) => {
+    if (schema.type !== "object") {
+        return typeof value === schema.type ? value : undefined;
+    }
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    const kept = {};
+    for (const key of Object.keys(schema.properties)) {
+        const property = schema.properties[key];
+        const member = property === undefined ? undefined : projected(property, value[key]);
+        if (member !== undefined) {
+            kept[key] = member;
+        }
+    }
+    return kept;
+};

package/dist/client/verb-rate.limiter.d.ts

@@ -0,0 +1,116 @@
+import type { AuditLog } from "../audit/audit.log.js";
+/** One rule: at most `max` calls in `window` seconds. */
+type RateRule = {
+    readonly window: number;
+    readonly max: number;
+};
+type Decision = {
+    readonly allowed: boolean;
+    readonly retryAfter: number | null;
+};
+/** A storage's one step: count the call, and say whether it is allowed. */
+type Consume = (key: string, rule: RateRule) => Promise<Decision>;
+/** A rate-limit row of the database's `rateLimit` table. */
+type RateRow = {
+    readonly key: string;
+    readonly count: number;
+    lastRequest: number;
+};
+type Where = {
+    readonly field: string;
+    readonly value: unknown;
+    readonly operator?: string;
+};
+/** What the limiter reads of Better Auth's context, once Better Auth is built. */
+export type LimiterContext = {
+    readonly rateLimit: {
+        readonly enabled: boolean;
+        readonly window: number;
+        readonly max: number;
+        readonly storage: string;
+        /** A rule, `false`, or a function of the request and the current rule to either (or a promise of it). */
+        readonly customRules?: {
+            readonly [path: string]: unknown;
+        };
+    };
+    readonly options: {
+        readonly rateLimit?: {
+            readonly window?: number;
+            readonly customStorage?: {
+                readonly consume: Consume;
+            };
+        };
+        readonly secondaryStorage?: {
+            readonly increment?: (key: string, ttl: number) => Promise<number>;
+            delete(key: string): unknown;
+        };
+        readonly plugins?: readonly {
+            readonly rateLimit?: readonly {
+                pathMatcher(path: string): boolean;
+                readonly window: number;
+                readonly max: number;
+            }[];
+        }[];
+        readonly advanced?: {
+            readonly ipAddress?: {
+                readonly disableIpTracking?: boolean;
+            };
+        };
+    };
+    readonly adapter: {
+        findMany(input: {
+            readonly model: string;
+            readonly where: readonly Where[];
+        }): Promise<unknown[]>;
+        create(input: {
+            readonly model: string;
+            readonly data: RateRow;
+        }): Promise<unknown>;
+        incrementOne(input: {
+            readonly model: string;
+            readonly where: readonly Where[];
+            readonly increment: {
+                readonly [field: string]: number;
+            };
+            readonly set: {
+                readonly [field: string]: number;
+            };
+        }): Promise<unknown>;
+        deleteMany(input: {
+            readonly model: string;
+            readonly where: readonly Where[];
+        }): Promise<unknown>;
+    };
+    readonly secret: unknown;
+};
+/** Better Auth's 429, as the limiter throws it. */
+type TooManyRequests = new (status: "TOO_MANY_REQUESTS", body: {
+    readonly message: string;
+}, headers: {
+    readonly [name: string]: string;
+}) => Error;
+/** What `call` hands the limiter about one call. */
+export type LimitedCall = {
+    /** The verb's route, under Better Auth's base path: `/sign-in/email`. */
+    readonly path: string;
+    readonly headers: Headers;
+    readonly request: Request;
+    /** The identifier the call names (`email:<address>`), `undefined` when none. */
+    readonly identifier: string | undefined;
+};
+/** What the limiter is told once the call has succeeded: the target's count is cleared. */
+export type LimitSettle = () => Promise<void>;
+/**
+ * The limiter: throws Better Auth's 429 when the call's address has used up the
+ * route's rule or its target has failed too often, and logs the refusal. Otherwise
+ * it answers what clears the target's count, which `call` runs once the call has
+ * succeeded: a refused call keeps its count.
+ */
+export declare const verbRateLimiter: (input: {
+    readonly context: () => Promise<LimiterContext>;
+    /** Better Auth's `getIP`: the client address its options read from a request's headers. */
+    readonly ipOf: (headers: Headers, options: unknown) => string | null;
+    readonly refusal: TooManyRequests;
+    readonly auditLog: AuditLog | undefined;
+}) => (call: LimitedCall) => Promise<LimitSettle | undefined>;
+export {};