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

package/dist/sha256.digest.js

@@ -0,0 +1,81 @@
+// SHA-256 (FIPS 180-4) over UTF-8 text, synchronous and dependency-free, so the engine
+// entry hashes a policies file the same way in Node, a browser, Electron or a build
+// step, without `node:crypto` and without WebCrypto's async API. It hashes a few
+// kilobytes at build and startup time; it is not on any request path.
+const K = new Uint32Array([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1,
+    0x923f82a4, 0xab1c5ed5, 0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3,
+    0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174, 0xe49b69c1, 0xefbe4786,
+    0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147,
+    0x06ca6351, 0x14292967, 0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13,
+    0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85, 0xa2bfe8a1, 0xa81a664b,
+    0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a,
+    0x5b9cca4f, 0x682e6ff3, 0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208,
+    0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+const rotr = (x, n) => (x >>> n) | (x << (32 - n));
+/** The SHA-256 digest of `text`'s UTF-8 bytes, as 64 lowercase hex digits. */
+export const sha256Hex = (text) => {
+    const bytes = new TextEncoder().encode(text);
+    const bitLength = bytes.length * 8;
+    // Message, a 0x80 byte, zero padding, and the 64-bit big-endian bit length.
+    const blocks = Math.ceil((bytes.length + 9) / 64);
+    const padded = new Uint8Array(blocks * 64);
+    padded.set(bytes);
+    padded[bytes.length] = 0x80;
+    const view = new DataView(padded.buffer);
+    view.setUint32(padded.length - 8, Math.floor(bitLength / 0x1_0000_0000));
+    view.setUint32(padded.length - 4, bitLength >>> 0);
+    const h = new Uint32Array([
+        0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c,
+        0x1f83d9ab, 0x5be0cd19,
+    ]);
+    const w = new Uint32Array(64);
+    for (let offset = 0; offset < padded.length; offset += 64) {
+        for (let t = 0; t < 16; t++) {
+            w[t] = view.getUint32(offset + t * 4);
+        }
+        for (let t = 16; t < 64; t++) {
+            const w15 = w[t - 15];
+            const w2 = w[t - 2];
+            const s0 = rotr(w15, 7) ^ rotr(w15, 18) ^ (w15 >>> 3);
+            const s1 = rotr(w2, 17) ^ rotr(w2, 19) ^ (w2 >>> 10);
+            w[t] = (w[t - 16] + s0 + w[t - 7] + s1) >>> 0;
+        }
+        let a = h[0];
+        let b = h[1];
+        let c = h[2];
+        let d = h[3];
+        let e = h[4];
+        let f = h[5];
+        let g = h[6];
+        let hh = h[7];
+        for (let t = 0; t < 64; t++) {
+            const s1 = rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25);
+            const choose = (e & f) ^ (~e & g);
+            const t1 = (hh + s1 + choose + K[t] + w[t]) >>> 0;
+            const s0 = rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22);
+            const majority = (a & b) ^ (a & c) ^ (b & c);
+            const t2 = (s0 + majority) >>> 0;
+            hh = g;
+            g = f;
+            f = e;
+            e = (d + t1) >>> 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (t1 + t2) >>> 0;
+        }
+        h[0] = (h[0] + a) >>> 0;
+        h[1] = (h[1] + b) >>> 0;
+        h[2] = (h[2] + c) >>> 0;
+        h[3] = (h[3] + d) >>> 0;
+        h[4] = (h[4] + e) >>> 0;
+        h[5] = (h[5] + f) >>> 0;
+        h[6] = (h[6] + g) >>> 0;
+        h[7] = (h[7] + hh) >>> 0;
+    }
+    return Array.from(h, (word) => word.toString(16).padStart(8, "0")).join("");
+};

package/dist/standalone/access.server.d.ts

@@ -0,0 +1,41 @@
+/** `serve`'s options. */
+export type AccessServeOptions = {
+    /** The port to listen on; `0` picks a free one. Default `3000`. */
+    readonly port?: number;
+    /**
+     * The interface to listen on. Default `"127.0.0.1"`, this host only; `"0.0.0.0"`
+     * listens on every interface (in a container, behind a proxy that terminates TLS).
+     */
+    readonly hostname?: string;
+    /** The largest request body taken, in bytes. Default 1 MiB (`1048576`). */
+    readonly maxBodyBytes?: number;
+};
+/** A running standalone host. */
+export type AccessServer = {
+    /** The port it listens on (the one picked, when `port` was `0`). */
+    readonly port: number;
+    /** Its base URL, such as `http://127.0.0.1:3000`. */
+    readonly url: string;
+    /**
+     * Stops accepting, lets the requests in flight finish for up to 10 s, then ends
+     * the connections left; resolves once the server is closed.
+     */
+    close(): Promise<void>;
+};
+/**
+ * What `serve` takes: an instance with a handler (`createAccess`'s, or any), and the
+ * options Better Auth runs with, which it reads for the base path and how the
+ * client's address is read; and whether the registry is on.
+ */
+type Served = {
+    readonly handler: (request: Request) => Promise<Response>;
+    readonly options?: object;
+    readonly registry?: unknown;
+};
+/**
+ * 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 declare const serve: (access: Served, options?: AccessServeOptions) => Promise<AccessServer>;
+export {};

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,105 @@
 {
   "name": "@aventara/access",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "1.0.0-rc.1",
+  "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",
+    "skill",
+    "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.11",
+    "@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"
+  }
 }