@aventara/access 0.0.0-stage → 1.0.0-rc.1

package/dist/passwords/passwords.options.js

@@ -0,0 +1,212 @@
+// The `passwords` block of `createAccess`, checked, and the password hook Better
+// Auth is built with. Better Auth hashes with scrypt; Access hashes with argon2id
+// three ways:
+//
+// - by default, when the app sets no `betterAuth.emailAndPassword.password`, at the
+//   `"owasp-minimum"` profile;
+// - at the profile the app names: `passwords: { argon2id: "rfc9106-low-memory" }`;
+// - not at all when the app set `betterAuth.emailAndPassword.password` itself: its
+//   hook passes through untouched, as everything in the `betterAuth` block does.
+//
+// Naming a profile and setting the hook too is refused, so one hasher is never in
+// doubt. The hook goes in whether or not email and password sign-in is on: Better
+// Auth's plugins (`admin`, `username`, `phone-number`, `email-otp`) hash and verify
+// through it too.
+//
+// Better Auth's scrypt hashes verify only with `legacyScrypt: true`. A sign-in whose
+// password matches a hash that is not at the current profile (a scrypt hash, or
+// argon2id at another profile's parameters) rehashes it at the profile (an after
+// hook on Better Auth's `/sign-in/*` routes), so each such account moves to the
+// profile at its next sign-in.
+import { AccessError } from "../access/access.error.js";
+import { isRecord } from "../policies.compiler.js";
+import { ARGON2ID_PROFILES, argon2idHasher, DEFAULT_ARGON2ID_PROFILE, isLegacyScryptHash, needsRehash, rehashPolicyOf, } from "./argon2id.hasher.js";
+import { NODE_RS_ARGON2_VERSION } from "./node-rs-argon2.adapter.js";
+/** Better Auth's default `emailAndPassword.maxPasswordLength`. */
+const BETTER_AUTH_MAX_PASSWORD_LENGTH = 128;
+const refuse = (message) => {
+    throw new AccessError("ACCESS_OPTIONS_INVALID", message);
+};
+const PROFILE_NAMES = Object.keys(ARGON2ID_PROFILES)
+    .map((name) => `"${name}"`)
+    .join(" or ");
+/** The checked `passwords` block, `undefined` when it is absent. */
+export const checkPasswordsOptions = (passwords) => {
+    if (passwords === undefined) {
+        return undefined;
+    }
+    const profile = isRecord(passwords) ? passwords.argon2id : undefined;
+    const legacy = isRecord(passwords) ? passwords.legacyScrypt : undefined;
+    if (!isRecord(passwords) ||
+        Object.keys(passwords).some((key) => key !== "argon2id" && key !== "legacyScrypt") ||
+        typeof profile !== "string" ||
+        !Object.hasOwn(ARGON2ID_PROFILES, profile) ||
+        (legacy !== undefined && typeof legacy !== "boolean")) {
+        return refuse(`\`passwords\` is \`{ argon2id: ${PROFILE_NAMES}, legacyScrypt?: boolean }\`; it was ${JSON.stringify(passwords)}.`);
+    }
+    return {
+        profile: profile,
+        legacyScrypt: legacy === true,
+    };
+};
+/**
+ * The after hook that moves a password to the current profile: on a sign-in that
+ * started a session with a password, when Better Auth's password hook is Access's
+ * and the user's credential holds a hash {@link needsRehash} names (a scrypt hash
+ * under `legacyScrypt`, or argon2id at other parameters than the profile's), and
+ * this password matches it (checked again here, so no route's own reading of
+ * `password` is trusted), the password is hashed at the profile and stored in its
+ * place.
+ *
+ * The write is a compare-and-set through Better Auth's adapter: it changes the
+ * account only while it still holds the hash just checked. A password changed or
+ * reset meanwhile is never overwritten, and of two sign-ins at once the later write
+ * wins with an equally valid hash. It goes past Better Auth's account update hooks:
+ * the password is the same one, encoded anew. On a current hash it costs one read
+ * and nothing else. A failure is logged (never the password or a hash) and leaves
+ * the stored hash; the sign-in stands.
+ */
+export const passwordRehashHook = (modules) => ({
+    matcher: (ctx) => typeof ctx?.path === "string" && ctx.path.startsWith("/sign-in/"),
+    handler: modules.createAuthMiddleware(async (ctx) => {
+        const context = ctx?.context;
+        const userId = context?.newSession?.user?.id;
+        const password = ctx?.body?.password;
+        const policy = rehashPolicyOf(context?.password?.verify);
+        if (context === undefined ||
+            policy === undefined ||
+            typeof userId !== "string" ||
+            typeof password !== "string") {
+            return undefined;
+        }
+        try {
+            const account = await context.internalAdapter.findCredentialAccount(userId);
+            const stored = account?.password;
+            const accountId = account?.id;
+            if (typeof stored !== "string" ||
+                typeof accountId !== "string" ||
+                !needsRehash(stored, policy)) {
+                return undefined;
+            }
+            const matches = isLegacyScryptHash(stored)
+                ? await modules.passwords.verifyScrypt({ hash: stored, password })
+                : await context.password.verify({ hash: stored, password });
+            if (matches !== true) {
+                return undefined;
+            }
+            await context.adapter.updateMany({
+                model: "account",
+                where: [
+                    { field: "id", value: accountId },
+                    { field: "password", value: stored },
+                ],
+                update: { password: await context.password.hash(password) },
+            });
+        }
+        catch {
+            context.logger.error("Aventara Access: rehashing a password at the current profile failed; the stored hash stays until the next sign-in.");
+        }
+        return undefined;
+    }),
+});
+/**
+ * The password hook Better Auth runs with: argon2id at the checked block's profile,
+ * or `undefined` when the app set `emailAndPassword.password` itself (its hook
+ * passes through). `at` names that option as the app writes it.
+ */
+export const passwordHookOf = (settings, emailAndPassword, modules, 
+/** Better Auth's context, once it is built: where the hook logs. */
+context, at) => {
+    const given = emailAndPassword ?? {};
+    if (!isRecord(given)) {
+        return refuse(`\`${at}\` holds Better Auth's email and password options, as \`betterAuth({...})\` takes them.`);
+    }
+    if (given.password !== undefined) {
+        if (settings !== undefined) {
+            refuse(`\`passwords\` and \`${at}.password\` both say how passwords are hashed: keep \`passwords\` for Access's argon2id, or your own \`password\` hook alone.`);
+        }
+        return undefined;
+    }
+    const { crypto, verifyScrypt } = modules.passwords;
+    if (typeof crypto.argon2 !== "function") {
+        return refuse(`argon2id needs Node.js's \`crypto.argon2\` (Node.js 24.7.0 and later), which this runtime does not have: on Node.js 22, install @node-rs/argon2 (npm install --save-exact @node-rs/argon2@${NODE_RS_ARGON2_VERSION}); or set \`${at}.password\` to hash passwords yourself.`);
+    }
+    return argon2idHasher({
+        profile: settings?.profile ?? DEFAULT_ARGON2ID_PROFILE,
+        // Better Auth's own reading of it, so the cap is the one its routes check.
+        maxPasswordLength: given.maxPasswordLength ||
+            BETTER_AUTH_MAX_PASSWORD_LENGTH,
+        crypto: crypto,
+        verifyScrypt,
+        legacyScrypt: settings?.legacyScrypt === true,
+        tooLong: () => new modules.APIError("BAD_REQUEST", {
+            code: "PASSWORD_TOO_LONG",
+            message: "Password too long",
+        }),
+        log: async (level, message) => {
+            try {
+                const built = (await context());
+                built.logger[level](`Aventara Access: ${message}`);
+            }
+            catch {
+                // Better Auth could not be built: there is no logger to report to.
+            }
+        },
+    });
+};
+/**
+ * What `createAccess` builds Better Auth with for passwords: its `emailAndPassword`
+ * block, the app's with the argon2id hook in it, or `undefined` when the app set
+ * `password` itself and its block passes through as given; and, with the argon2id
+ * hook, the after hook the Access plugin adds to rehash a password at the profile.
+ */
+export const passwordsOf = (passwords, betterAuth, modules, 
+/** Better Auth's context, once it is built: where the hook logs. */
+context) => {
+    const settings = checkPasswordsOptions(passwords);
+    const hook = passwordHookOf(settings, betterAuth.emailAndPassword, modules, context, "betterAuth.emailAndPassword");
+    return hook === undefined
+        ? { emailAndPassword: undefined, rehash: undefined }
+        : {
+            emailAndPassword: {
+                ...betterAuth.emailAndPassword,
+                password: hook,
+            },
+            rehash: passwordRehashHook(modules),
+        };
+};
+/**
+ * The kiosk profile's PIN hasher: argon2id at the `passwords` block's profile (the
+ * default without one), whatever hashes the app's passwords, since a PIN is a weak
+ * secret and its hash must be slow wherever it is read. A PIN is at most
+ * `maxPinLength` digits; Better Auth's scrypt hashes never verify as PINs.
+ */
+export const pinHasherOf = (passwords, modules, 
+/** Better Auth's context, once it is built: where the hasher logs. */
+context, maxPinLength) => {
+    const settings = checkPasswordsOptions(passwords);
+    const { crypto, verifyScrypt } = modules.passwords;
+    if (typeof crypto.argon2 !== "function") {
+        return refuse(`the kiosk profile hashes PINs with argon2id, which needs Node.js's \`crypto.argon2\` (Node.js 24.7.0 and later): on Node.js 22, install @node-rs/argon2 (npm install --save-exact @node-rs/argon2@${NODE_RS_ARGON2_VERSION}).`);
+    }
+    return argon2idHasher({
+        profile: settings?.profile ?? DEFAULT_ARGON2ID_PROFILE,
+        maxPasswordLength: maxPinLength,
+        crypto: crypto,
+        verifyScrypt,
+        legacyScrypt: false,
+        tooLong: () => new modules.APIError("BAD_REQUEST", {
+            code: "PIN_TOO_WEAK",
+            message: "A PIN is at most 12 digits.",
+        }),
+        log: async (level, message) => {
+            try {
+                const built = (await context());
+                built.logger[level](`Aventara Access: ${message.replace(/password/g, "PIN")}`);
+            }
+            catch {
+                // Better Auth could not be built: there is no logger to report to.
+            }
+        },
+    });
+};

package/dist/policies-contract.d.ts

@@ -0,0 +1,219 @@
+/** The format marker of every `@1` file. */
+export declare const POLICIES_FORMAT = "aventara-access/policies@1";
+/** The format marker of the unstable v0 files, refused by name (no users, no shim). */
+export declare const RETIRED_POLICIES_FORMAT = "aventara-access/policies@0";
+/** The four standard operations a rule names. */
+export type AccessAction = "read" | "create" | "update" | "delete";
+/** The layer a request runs under (core's `AvRequestOrigin`, copied by shape). */
+export type AccessOrigin = "application" | "client" | "agent";
+/** The two built-in subjects: `signedIn` (a non-null principal) and `anyone` (null included). */
+export type AccessBuiltInSubject = "signedIn" | "anyone";
+/** A literal a rule compares with. */
+export type AccessLiteral = string | number | boolean | null;
+/** A value read off the principal at question time (`me.id` → `{ principal: ["id"] }`). */
+export type AccessPrincipalOperand = {
+    readonly principal: readonly [string, ...string[]];
+};
+/** What a field comparison compares with. */
+export type AccessOperand = AccessLiteral | AccessPrincipalOperand;
+/** The comparisons a rule may make. Each maps one-to-one to an Aventara filter operator. */
+export type AccessComparison = "eq" | "ne" | "in" | "notIn";
+/**
+ * A row condition in Access's neutral form. Field names are the Resource's own;
+ * a relation step names its target so the file needs no schema to walk it.
+ */
+export type AccessPredicate = {
+    readonly op: "true";
+} | {
+    readonly op: "false";
+} | {
+    readonly op: "and";
+    readonly args: readonly AccessPredicate[];
+} | {
+    readonly op: "or";
+    readonly args: readonly AccessPredicate[];
+} | {
+    readonly op: "not";
+    readonly arg: AccessPredicate;
+} | {
+    readonly op: "cmp";
+    readonly field: string;
+    readonly cmp: AccessComparison;
+    readonly value: AccessOperand | readonly AccessOperand[];
+} | {
+    readonly op: "rel";
+    readonly relation: string;
+    readonly target: string;
+    readonly where: AccessPredicate;
+} | {
+    readonly op: "some" | "every" | "none";
+    readonly relation: string;
+    readonly target: string;
+    readonly where: AccessPredicate;
+} | {
+    readonly op: "role";
+    readonly role: string;
+};
+/** A condition on the principal alone: its claims and the request's origin. */
+export type AccessPrincipalCondition = {
+    readonly op: "and";
+    readonly args: readonly AccessPrincipalCondition[];
+} | {
+    readonly op: "cmp";
+    readonly claim: readonly [string, ...string[]];
+    readonly cmp: "eq";
+    readonly value: AccessLiteral;
+} | {
+    readonly op: "origin";
+    readonly value: AccessOrigin;
+};
+/** A role: global (read from claims) or held on a row of one Resource. */
+export type AccessRoleDefinition = {
+    readonly global: AccessPrincipalCondition;
+} | {
+    readonly on: string;
+    readonly where: AccessPredicate;
+};
+/** One grant. Any grant allows (default deny). */
+export type AccessGrantRule = {
+    readonly id: string;
+    readonly subjects: readonly string[];
+    readonly actions: readonly AccessAction[];
+    readonly resource: string;
+    /** The to-one relation whose target holds each subject's row role. */
+    readonly in?: string;
+    readonly where?: AccessPredicate;
+    /** Governed fields this grant opens, as `Resource.field`. */
+    readonly fields?: readonly string[];
+    /** Fields this grant does not let a create or update write. */
+    readonly write?: {
+        readonly except: readonly string[];
+    };
+    /** A condition the row an update leaves must still meet. */
+    readonly after?: AccessPredicate;
+};
+/** One deny. Any deny wins over every grant. */
+export type AccessDenyRule = {
+    readonly id: string;
+    readonly actions: "*" | readonly AccessAction[];
+    readonly resource: string;
+    readonly where?: AccessPredicate;
+    readonly if?: AccessPrincipalCondition;
+};
+/** A relation as the engine needs it: where it leads, and the reference pairs when this end holds them. */
+export type AccessSchemaRelationFact = {
+    readonly target: string;
+    readonly cardinality: "one" | "many";
+    readonly referenceFields?: readonly [string, ...string[]];
+    readonly references?: readonly [string, ...string[]];
+};
+/** The schema facts the engine reads, per Resource. */
+export type AccessSchemaResourceFacts = {
+    readonly identifiers: readonly (readonly string[])[];
+    readonly fields: readonly string[];
+    /**
+     * The scalar fields that may hold NULL, when there are any. A scope negates a
+     * comparison on one of them null-safely (`NOT (f = v) OR f IS NULL`), so it keeps
+     * the rows `can` keeps.
+     */
+    readonly nullable?: readonly string[];
+    /**
+     * The scalar fields `can` compares by their type rather than by their JavaScript
+     * value, when there are any: a `decimal` as its canonical decimal digits (a decimal
+     * object, a string and a number alike), a `datetime` as its instant, a `bigint`
+     * exactly. A file without `types` has none of them.
+     */
+    readonly types?: {
+        readonly [field: string]: "bigint" | "datetime" | "decimal";
+    };
+    readonly relations: {
+        readonly [relation: string]: AccessSchemaRelationFact;
+    };
+    /**
+     * The namespace that owns this Resource, when it is not this file's. A foreign
+     * Resource is read in conditions and never granted on.
+     */
+    readonly foreign?: string;
+};
+/** A claim's type, never its value. */
+export type AccessClaimType = {
+    readonly scalar: "string" | "number" | "boolean";
+};
+/**
+ * The `@1` policies file. `Governed` keeps the `govern` block's literal type through
+ * the builder: per Resource, the list form (each field governed for reading and
+ * writing) or the object form (a mode per field).
+ */
+export type AccessPolicies<Governed extends {
+    readonly [resource: string]: readonly string[] | {
+        readonly [field: string]: "read" | "write" | "both";
+    };
+} = {
+    readonly [resource: string]: readonly string[];
+}> = {
+    readonly format: typeof POLICIES_FORMAT;
+    /** The namespace that owns this file's Resources. A single app needs none. */
+    readonly namespace?: string;
+    readonly claims: {
+        readonly [claim: string]: AccessClaimType;
+    };
+    readonly schema: {
+        readonly [resource: string]: AccessSchemaResourceFacts;
+    };
+    readonly roles: {
+        readonly [role: string]: AccessRoleDefinition;
+    };
+    /** Every governed field, by Resource, whatever its mode. */
+    readonly govern: {
+        readonly [R in keyof Governed]: Governed[R] extends readonly string[] ? Governed[R] : readonly (keyof Governed[R] & string)[];
+    };
+    /**
+     * The governed fields governed for one access only, by Resource: `"write"`, read by
+     * default and written only through a grant that names the field; `"read"`, written
+     * by default and read only through a grant that names it. A governed field with no
+     * entry is governed for both, and a file without `governModes` has no other kind.
+     */
+    readonly governModes?: {
+        readonly [resource: string]: {
+            readonly [field: string]: "read" | "write";
+        };
+    };
+    readonly grants: readonly AccessGrantRule[];
+    readonly denies: readonly AccessDenyRule[];
+};
+/**
+ * A policies file as a JSON import types it: `resolveJsonModule` widens `format` to
+ * `string` and each tuple to an array, so the file `avaccess pull` wrote, imported
+ * with `import policies from "./access/blog.policies.json" with { type: "json" }`,
+ * is not an `AccessPolicies`. `policies.rules` and `createAccessEngine` take it as it
+ * is: only its outline is typed, and the engine checks the rest when it is built.
+ */
+export type AccessPoliciesJson<Governed extends {
+    readonly [resource: string]: readonly string[] | {
+        readonly [field: string]: "read" | "write" | "both";
+    };
+} = {
+    readonly [resource: string]: readonly string[];
+}> = {
+    readonly format: string;
+    readonly namespace?: string;
+    readonly claims: {
+        readonly [claim: string]: {
+            readonly scalar: string;
+        };
+    };
+    readonly schema: {
+        readonly [resource: string]: object;
+    };
+    readonly roles: {
+        readonly [role: string]: object;
+    };
+    readonly govern: Governed;
+    readonly governModes?: {
+        readonly [resource: string]: {
+            readonly [field: string]: string;
+        };
+    };
+    readonly grants: readonly object[];
+    readonly denies: readonly object[];
+};

package/dist/policies-contract.js

@@ -0,0 +1,8 @@
+// The declarative policies file, format `aventara-access/policies@1`. The builder
+// compiles to it and the engine runs from it alone. It is passive JSON: no closures,
+// no claim values, no provider names. `@1` is frozen: a change to its shape is `policies@2` beside it, never an
+// edit of `@1`. Its canonical byte form and hash are `policies.hash.ts`'s.
+/** The format marker of every `@1` file. */
+export const POLICIES_FORMAT = "aventara-access/policies@1";
+/** The format marker of the unstable v0 files, refused by name (no users, no shim). */
+export const RETIRED_POLICIES_FORMAT = "aventara-access/policies@0";

package/dist/policies.compiler.d.ts

@@ -0,0 +1,38 @@
+import type { AccessDefinition } from "./access.builder.js";
+import { type AccessAction, type AccessClaimType, type AccessOrigin, type AccessPolicies, type AccessPrincipalCondition } from "./policies-contract.js";
+/** The marker a `me` value carries; the compiler writes it as `{ principal: [...] }`. */
+export declare const PRINCIPAL_REF: unique symbol;
+export declare const ACTIONS: readonly AccessAction[];
+export declare const ORIGINS: readonly AccessOrigin[];
+export declare const CLAIM_SCALARS: readonly string[];
+export declare const fail: (where: string, message: string) => never;
+export declare const isRecord: (value: unknown) => value is {
+    readonly [key: string]: unknown;
+};
+export declare const asList: <T>(value: T | readonly T[]) => readonly T[];
+/** The claims a file compares, by the type each is compared as. */
+export type ClaimTypes = Record<string, AccessClaimType>;
+export declare const idAllocator: () => (prefix: string, name: unknown) => string;
+/**
+ * A rule's `if` (`{ claims?, origin? }`), compiled to a condition on the principal
+ * alone. Each claim's type is recorded in `claimTypes`, and a claim compared as two
+ * types is refused.
+ */
+export declare const compilePrincipalIf: (rule: string, condition: unknown, claimTypes: ClaimTypes) => AccessPrincipalCondition;
+/** Compiles the builder's rules to the `@1` policies file and checks it. */
+export declare const compilePolicies: <Governed extends {
+    readonly [resource: string]: readonly string[] | {
+        readonly [field: string]: "read" | "write" | "both";
+    };
+}>(definition: AccessDefinition) => AccessPolicies<Governed>;
+export declare const checkActions: (rule: string, actions: readonly string[]) => void;
+/** Whether `value` is a name a file may give a Resource or a field. */
+export declare const isName: (value: unknown) => value is string;
+/** Whether `value` is a namespace name. */
+export declare const isNamespace: (value: unknown) => value is string;
+/**
+ * Checks a policies file before an engine runs from it. Throws an `Error` naming
+ * the rule. The file is trusted for nothing it can be checked for. `composed`: the
+ * file the engine composed itself, whose denies may take the reserved ids.
+ */
+export declare const checkPolicies: (policies: AccessPolicies, composed?: boolean) => void;