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

package/dist/standalone/access.server.js

@@ -0,0 +1,301 @@
+// The standalone host: an Access instance as its own HTTP server. It is one more
+// mount of `access.handler`, the way a Node.js app mounts Better Auth's (Better Auth's
+// own `toNodeHandler`), plus a health route outside the auth routes for a load
+// balancer or a container's health check. It holds no auth logic of its own; what it
+// adds is what a server facing the network owes the handler behind it:
+//
+// - It listens on 127.0.0.1 unless told otherwise, and speaks plain HTTP: put it
+//   behind a proxy that terminates TLS before anything outside the host reaches it.
+// - A request body is capped (1 MiB unless `maxBodyBytes` says) before any of it is
+//   handed on: a declared length over the cap is refused unread, a streamed one when
+//   it passes the cap. A write to the registry has its key checked before its body
+//   is read at all.
+// - The client's address is the socket's. A forwarded-for header is believed only
+//   from a proxy Better Auth's `advanced.ipAddress.trustedProxies` names; from anyone
+//   else it is replaced with the socket's address, so Better Auth's rate limit counts
+//   each client in its own bucket and a client cannot pick its own.
+// - `close()` stops accepting, lets requests in flight finish for up to 10 s, then
+//   ends what is left.
+import { createServer, } from "node:http";
+import { BlockList, isIP } from "node:net";
+import { toNodeHandler } from "better-auth/node";
+/** The path of the health route: `GET` or `HEAD` answers `200 {"status":"ok"}`. */
+const HEALTH = "/health";
+const DEFAULT_PORT = 3000;
+const DEFAULT_HOSTNAME = "127.0.0.1";
+const DEFAULT_MAX_BODY = 1_048_576;
+const DRAIN_MS = 10_000;
+/** The header a registry key travels in, and the route that names a key's namespace. */
+const KEY_HEADER = "x-access-key";
+const KEY_OWNER = "/access/v1/key";
+/** An IPv4-mapped IPv6 address (`::ffff:127.0.0.1`) as the IPv4 address it is. */
+const plainAddress = (address) => {
+    if (address === undefined) {
+        return undefined;
+    }
+    const mapped = /^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/i.exec(address);
+    return mapped?.[1] ?? address;
+};
+/** Better Auth's `trustedProxies` (addresses and CIDR ranges) as a list `check` reads. */
+const proxyList = (entries) => {
+    if (entries.length === 0) {
+        return undefined;
+    }
+    const list = new BlockList();
+    for (const entry of entries) {
+        const [address = "", prefix] = entry.split("/");
+        const family = isIP(address);
+        if (family === 0) {
+            continue;
+        }
+        const type = family === 4 ? "ipv4" : "ipv6";
+        if (prefix === undefined) {
+            list.addAddress(address, type);
+        }
+        else if (/^\d+$/.test(prefix)) {
+            list.addSubnet(address, Number(prefix), type);
+        }
+    }
+    return list;
+};
+/** Whether `address` is one of `list`'s. */
+const listed = (list, address) => {
+    const family = isIP(address);
+    return (list !== undefined &&
+        family !== 0 &&
+        list.check(address, family === 4 ? "ipv4" : "ipv6"));
+};
+/** An absolute-form request target (RFC 9112 section 3.2.2): `http://host/path`. */
+const ABSOLUTE_FORM = /^[a-z][a-z0-9+.-]*:\/\//i;
+/**
+ * A request target in origin form: an absolute-form one (`http://host/path?query`)
+ * as its path and query, which a server must take (RFC 9112 section 3.2.2) and which
+ * the handler's mount would otherwise read as a path.
+ */
+const originForm = (target) => {
+    if (!ABSOLUTE_FORM.test(target)) {
+        return target;
+    }
+    try {
+        const url = new URL(target);
+        return `${url.pathname}${url.search}`;
+    }
+    catch {
+        return "/";
+    }
+};
+/**
+ * A path as a router could match it: resolved as a URL is (its dot segments, `%2e`
+ * among them, and a backslash read as a slash, as Better Auth's mount reads it),
+ * decoded, its slashes collapsed, in lower case.
+ */
+const routePath = (url) => {
+    let path = url.split("?")[0] ?? "/";
+    try {
+        path = new URL(path, "http://localhost").pathname;
+    }
+    catch {
+        // Kept as sent.
+    }
+    let decoded = path;
+    try {
+        decoded = decodeURIComponent(path);
+    }
+    catch {
+        // Kept as sent.
+    }
+    return decoded.replace(/\/{2,}/g, "/").toLowerCase();
+};
+/** Reads a request's body, up to `max` bytes; `undefined` once it passes `max`. */
+const bodyOf = (request, max) => new Promise((resolve, reject) => {
+    const chunks = [];
+    let size = 0;
+    let settled = false;
+    request.on("data", (chunk) => {
+        if (settled) {
+            return;
+        }
+        size += chunk.length;
+        if (size > max) {
+            settled = true;
+            resolve(undefined);
+            return;
+        }
+        chunks.push(chunk);
+    });
+    request.on("end", () => {
+        if (settled) {
+            return;
+        }
+        settled = true;
+        const body = new Uint8Array(size);
+        let offset = 0;
+        for (const chunk of chunks) {
+            body.set(chunk, offset);
+            offset += chunk.length;
+        }
+        resolve(body);
+    });
+    request.on("error", (error) => {
+        if (!settled) {
+            settled = true;
+            reject(error);
+        }
+    });
+});
+const tooLarge = (max) => JSON.stringify({
+    code: "PAYLOAD_TOO_LARGE",
+    message: `Aventara Access: the request body is larger than this server takes (${max} bytes)`,
+});
+/** A refusal `serve` answers itself; the connection is closed after it, so no unread body is drained. */
+const refuse = (request, response, status, body) => {
+    response.statusCode = status;
+    response.setHeader("content-type", "application/json");
+    response.setHeader("connection", "close");
+    response.end(body, () => {
+        request.destroy();
+    });
+};
+/**
+ * Serves an Access instance over HTTP: its routes, as `access.handler` answers them
+ * (Better Auth's base path, `/api/auth` unless `betterAuth.basePath` says otherwise),
+ * and `GET /health`. Resolves once the server listens.
+ */
+export const serve = (access, options = {}) => {
+    const handle = toNodeHandler(access);
+    const maxBody = options.maxBodyBytes ?? DEFAULT_MAX_BODY;
+    const betterAuth = (access.options ?? {});
+    const ip = betterAuth.advanced?.ipAddress;
+    const ipHeaders = (ip?.ipAddressHeaders ?? ["x-forwarded-for"]).map((header) => header.toLowerCase());
+    const proxies = proxyList(ip?.trustedProxies ?? []);
+    const basePath = routePath(betterAuth.basePath ?? "/api/auth").replace(/\/+$/, "");
+    const registryOn = access.registry !== undefined;
+    let closing = false;
+    /**
+     * Sets the client's address where Better Auth reads it (its first
+     * `ipAddressHeaders`, `x-forwarded-for` by default): the socket's, unless the
+     * socket is a trusted proxy's, whose forwarded headers are then kept.
+     */
+    const addressed = (request) => {
+        if (ip?.disableIpTracking === true) {
+            return;
+        }
+        const peer = plainAddress(request.socket.remoteAddress);
+        const headers = request.headers;
+        if (peer === undefined || !listed(proxies, peer)) {
+            for (const header of ipHeaders) {
+                delete headers[header];
+            }
+            delete headers["x-forwarded-proto"];
+            delete headers["x-forwarded-host"];
+        }
+        const first = ipHeaders[0];
+        if (peer !== undefined && first !== undefined && !(first in headers)) {
+            headers[first] = peer;
+        }
+    };
+    /** The registry's refusal of a write's key, asked before its body is read; `undefined` for a key it has. */
+    const keyRefusal = async (request) => {
+        const key = request.headers[KEY_HEADER];
+        const forwarded = Object.fromEntries(ipHeaders.flatMap((header) => {
+            const value = request.headers[header];
+            return typeof value === "string" ? [[header, value]] : [];
+        }));
+        const answer = await access.handler(new Request(new URL(`${basePath}${KEY_OWNER}`, "http://localhost"), {
+            headers: {
+                ...forwarded,
+                [KEY_HEADER]: typeof key === "string" ? key : "",
+            },
+        }));
+        return answer.status === 200 ? undefined : answer;
+    };
+    const answer = async (request, response) => {
+        const method = request.method ?? "GET";
+        request.url = originForm(request.url ?? "/");
+        const path = request.url.split("?")[0];
+        if (path === HEALTH && (method === "GET" || method === "HEAD")) {
+            response.statusCode = 200;
+            response.setHeader("content-type", "application/json");
+            response.end(method === "HEAD" ? undefined : '{"status":"ok"}');
+            return;
+        }
+        if (closing) {
+            response.setHeader("connection", "close");
+        }
+        addressed(request);
+        if (method !== "GET" && method !== "HEAD") {
+            const declared = Number(request.headers["content-length"]);
+            if (Number.isFinite(declared) && declared > maxBody) {
+                refuse(request, response, 413, tooLarge(maxBody));
+                return;
+            }
+            if (registryOn &&
+                routePath(request.url ?? "/").startsWith(`${basePath}/access/`)) {
+                const refused = await keyRefusal(request);
+                if (refused !== undefined) {
+                    refuse(request, response, refused.status, await refused.text());
+                    return;
+                }
+            }
+            const body = await bodyOf(request, maxBody);
+            if (body === undefined) {
+                refuse(request, response, 413, tooLarge(maxBody));
+                return;
+            }
+            if (body.length > 0 && request.headers["content-type"] !== undefined) {
+                // Read whole: Better Auth's Node.js mount takes a body read before it.
+                request.body = new TextDecoder().decode(body);
+            }
+        }
+        await handle(request, response);
+    };
+    const server = createServer((request, response) => {
+        answer(request, response).catch(() => {
+            if (!response.headersSent) {
+                response.statusCode = 500;
+            }
+            response.end();
+        });
+    });
+    const port = options.port ?? DEFAULT_PORT;
+    const hostname = options.hostname ?? DEFAULT_HOSTNAME;
+    return new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, hostname, () => {
+            server.off("error", reject);
+            const address = server.address();
+            const bound = typeof address === "object" && address !== null ? address.port : port;
+            const host = hostname === "0.0.0.0" || hostname === "::"
+                ? "localhost"
+                : hostname.includes(":")
+                    ? `[${hostname}]`
+                    : hostname;
+            resolve({
+                port: bound,
+                url: `http://${host}:${bound}`,
+                close: () => new Promise((closed, failed) => {
+                    closing = true;
+                    // Ends every connection still open once the drain is over.
+                    const force = setTimeout(() => {
+                        server.closeAllConnections();
+                    }, DRAIN_MS);
+                    // A connection whose request was answered is idle: ended as it gets so.
+                    const idle = setInterval(() => {
+                        server.closeIdleConnections();
+                    }, 50);
+                    server.close((error) => {
+                        clearTimeout(force);
+                        clearInterval(idle);
+                        if (error) {
+                            failed(error);
+                        }
+                        else {
+                            closed();
+                        }
+                    });
+                    server.closeIdleConnections();
+                }),
+            });
+        });
+    });
+};

package/dist/standalone/index.d.ts

@@ -0,0 +1 @@
+export { type AccessServeOptions, type AccessServer, serve, } from "./access.server.js";

package/dist/standalone/index.js

@@ -0,0 +1 @@
+export { serve, } from "./access.server.js";

package/package.json

@@ -1,6 +1,104 @@
 {
   "name": "@aventara/access",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-rc.0",
+  "license": "SEE LICENSE IN LICENSE",
+  "description": "A policy engine for Aventara: role-first rules typed from your schema, compiled to a passive policies file.",
+  "type": "module",
+  "engines": {
+    "node": "^22.23.4 || >=24.22.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mhmd-hatem/Aventara-Access.git",
+    "directory": "packages/access"
+  },
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "avaccess": "./dist/cli/avaccess.bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./auth": {
+      "types": "./dist/auth/index.d.ts",
+      "import": "./dist/auth/index.js",
+      "default": "./dist/auth/index.js"
+    },
+    "./better-auth": {
+      "types": "./dist/better-auth/index.d.ts",
+      "import": "./dist/better-auth/index.js",
+      "default": "./dist/better-auth/index.js"
+    },
+    "./standalone": {
+      "types": "./dist/standalone/index.d.ts",
+      "import": "./dist/standalone/index.js",
+      "default": "./dist/standalone/index.js"
+    }
+  },
+  "imports": {
+    "#better-auth.require": {
+      "node": "./dist/access/better-auth.require.node.js",
+      "default": "./dist/access/better-auth.require.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/policies-contract.ts",
+    "src/scope.resolver.ts",
+    "src/aventara-where.translator.ts",
+    "src/predicate.evaluator.ts",
+    "src/canonical-json.writer.ts",
+    "src/sha256.digest.ts",
+    "src/policies.decider.ts",
+    "src/beacon/beacon.check.ts",
+    "src/generator/prisma7/prisma-where.translator.ts",
+    "LICENSE-ADDITIONAL-PERMISSION.md",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "get-tsconfig": "4.10.0",
+    "jiti": "2.7.0",
+    "jose": "6.2.13"
+  },
+  "peerDependencies": {
+    "@better-auth/cimd": "~1.7.12",
+    "@better-auth/oauth-provider": "~1.7.12",
+    "@node-rs/argon2": "2.2.2",
+    "better-auth": "~1.7.12"
+  },
+  "peerDependenciesMeta": {
+    "@better-auth/cimd": {
+      "optional": true
+    },
+    "@better-auth/oauth-provider": {
+      "optional": true
+    },
+    "@node-rs/argon2": {
+      "optional": true
+    },
+    "better-auth": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@aventara/core": "1.0.0-rc.9",
+    "@better-auth/cimd": "1.7.14",
+    "@better-auth/expo": "1.7.14",
+    "@better-auth/oauth-provider": "1.7.14",
+    "@node-rs/argon2": "2.2.2",
+    "better-auth": "1.7.14"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.typecheck.json --noEmit",
+    "test": "vitest run --typecheck"
+  }
 }

package/src/aventara-where.translator.ts

@@ -0,0 +1,116 @@
+// Folded condition → Aventara's `where` grammar, with explicit operators
+// (`{ equals: … }`), as core validates it against the Core Contract.
+
+import type { AccessComparison, AccessLiteral } from "./policies-contract.js";
+import type { Resolved } from "./scope.resolver.js";
+
+/** A fragment of Aventara's `where` (core's `AvPolicyWhere`, by shape). */
+export type AccessWhere = { readonly [key: string]: unknown };
+
+const OPERATOR: Record<AccessComparison, string> = {
+	eq: "equals",
+	ne: "not",
+	in: "in",
+	notIn: "notIn",
+};
+
+/** The Aventara filter operator a comparison is written with. */
+export const operatorOf = (cmp: AccessComparison): string => OPERATOR[cmp];
+
+const isField = (
+	node: Resolved,
+): node is Extract<Resolved, { field: string } | { relation: string }> =>
+	node.k === "cmp" ||
+	node.k === "rel" ||
+	node.k === "some" ||
+	node.k === "every" ||
+	node.k === "none";
+
+const keyOf = (
+	node: Extract<Resolved, { field: string } | { relation: string }>,
+): string => (node.k === "cmp" ? node.field : node.relation);
+
+/**
+ * Sets `key` on `target` as its own data member. An assignment would read
+ * `__proto__` as the prototype setter and drop the condition.
+ */
+export const defineMember = (
+	target: Record<string, unknown>,
+	key: string,
+	value: unknown,
+): void => {
+	Object.defineProperty(target, key, {
+		value,
+		enumerable: true,
+		writable: true,
+		configurable: true,
+	});
+};
+
+/** An object with one own member. */
+const one = (key: string, value: unknown): AccessWhere => {
+	const where: Record<string, unknown> = {};
+	defineMember(where, key, value);
+	return where;
+};
+
+/** Merges fragments into one object when no key repeats; otherwise `undefined`. */
+export const mergeWhere = (
+	fragments: readonly AccessWhere[],
+): AccessWhere | undefined => {
+	const merged: Record<string, unknown> = {};
+	for (const fragment of fragments) {
+		for (const [key, value] of Object.entries(fragment)) {
+			if (Object.hasOwn(merged, key)) {
+				return undefined;
+			}
+			defineMember(merged, key, value);
+		}
+	}
+	return merged;
+};
+
+/** Translates a row condition that is neither `true` nor `false` at its root. */
+export const translateWhere = (node: Resolved): AccessWhere => {
+	switch (node.k) {
+		case "true":
+			return {};
+		case "false":
+			// Aventara's `where` has no `false`: the empty `OR` is its one way to match no
+			// row, and an ORM reads it so.
+			return { OR: [] };
+		case "cmp":
+			return one(node.field, {
+				[operatorOf(node.cmp)]: Array.isArray(node.value)
+					? [...(node.value as readonly AccessLiteral[])]
+					: node.value,
+			});
+		case "rel":
+			return one(node.relation, translateWhere(node.where));
+		case "some":
+		case "every":
+		case "none":
+			return one(node.relation, { [node.k]: translateWhere(node.where) });
+		case "not":
+			return { NOT: translateWhere(node.arg) };
+		case "or":
+			return { OR: node.args.map(translateWhere) };
+		case "all":
+			return { AND: node.args.map(translateWhere) };
+		case "and": {
+			// Written by the author as one object: written back as one when every part is
+			// a field condition and no field repeats.
+			if (
+				node.args.every(isField) &&
+				new Set(node.args.map(keyOf)).size === node.args.length
+			) {
+				return mergeWhere(node.args.map(translateWhere)) as AccessWhere;
+			}
+			return { AND: node.args.map(translateWhere) };
+		}
+	}
+};
+
+/** A seam answer: `true` every row, `false` none, or a `where`. */
+export const translateAnswer = (node: Resolved): boolean | AccessWhere =>
+	node.k === "true" ? true : node.k === "false" ? false : translateWhere(node);