@n24q02m/hull 0.0.0-stage → 0.4.0-beta.9

package/build/token-auth/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/token-auth/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAkBpD,MAAM,OAAO,GAAG,IAAI,iBAAiB,EAAe,CAAA;AAEpD,qEAAqE;AACrE,MAAM,UAAU,gBAAgB;IAC9B,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,GAAG,EAAE,OAAO;QACZ,SAAS,EAAE,SAAS;QACpB,IAAI,EAAE,SAAS;QACf,YAAY,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,CAAsB;QACpD,GAAG,EAAE,IAAI;QACT,QAAQ,EAAE,KAAK;QACf,UAAU,EAAE,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC;KAC9B,CAAC,CAAA;AACJ,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,WAAW;IACzB,OAAO,OAAO,CAAC,QAAQ,EAAE,IAAI,gBAAgB,EAAE,CAAA;AACjD,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,kBAAkB,CAAI,GAAgB,EAAE,EAAW;IACjE,OAAO,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,CAAC,CAAA;AAC7B,CAAC"}

package/build/token-auth/http-guard.d.ts

@@ -0,0 +1,26 @@
+/**
+ * node:http guard that authenticates a request and binds the identity,
+ * the counterpart of core-py `hull_core.auth.asgi.HullAuthMiddleware`.
+ *
+ * Rejections are byte-identical to core-py: a JSON body
+ * `{"error": <status text>, "detail": <detail>}` (Python `json.dumps`
+ * formatting), `content-type: application/json`, an explicit
+ * `content-length`, and `www-authenticate: Bearer` on 401.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { AuthOutcome } from './authenticator.js';
+/** Status -> `error` field, same table as core-py `_STATUS_TEXT`. */
+export declare const AUTH_STATUS_TEXT: Readonly<Record<number, string>>;
+/** Minimal authenticator surface the guard needs. */
+export interface RequestAuthenticator {
+    authenticate(authz: string | null | undefined): Promise<AuthOutcome>;
+}
+/** Write a core-py-compatible JSON auth rejection. */
+export declare function writeAuthRejection(res: ServerResponse, status: number, detail: string): void;
+/**
+ * Authenticate `req`; on success run `next` with the resolved `AuthContext`
+ * bound for its whole async scope (so `currentUser()` works inside MCP tool
+ * handlers), otherwise write the rejection and never call `next`.
+ */
+export declare function guardRequest(authenticator: RequestAuthenticator, req: IncomingMessage, res: ServerResponse, next: () => Promise<void>): Promise<void>;
+//# sourceMappingURL=http-guard.d.ts.map

package/build/token-auth/http-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-guard.d.ts","sourceRoot":"","sources":["../../src/token-auth/http-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAChE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAIrD,qEAAqE;AACrE,eAAO,MAAM,gBAAgB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAK5D,CAAA;AAEF,qDAAqD;AACrD,MAAM,WAAW,oBAAoB;IACnC,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC,CAAA;CACrE;AAED,sDAAsD;AACtD,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAS5F;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAChC,aAAa,EAAE,oBAAoB,EACnC,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,cAAc,EACnB,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GACxB,OAAO,CAAC,IAAI,CAAC,CAcf"}

package/build/token-auth/http-guard.js

@@ -0,0 +1,51 @@
+/**
+ * node:http guard that authenticates a request and binds the identity,
+ * the counterpart of core-py `hull_core.auth.asgi.HullAuthMiddleware`.
+ *
+ * Rejections are byte-identical to core-py: a JSON body
+ * `{"error": <status text>, "detail": <detail>}` (Python `json.dumps`
+ * formatting), `content-type: application/json`, an explicit
+ * `content-length`, and `www-authenticate: Bearer` on 401.
+ */
+import { runWithAuthContext } from './context.js';
+import { pyJsonDumps } from './py-compat.js';
+/** Status -> `error` field, same table as core-py `_STATUS_TEXT`. */
+export const AUTH_STATUS_TEXT = Object.freeze({
+    401: 'unauthorized',
+    403: 'forbidden',
+    429: 'rate limit exceeded',
+    500: 'server misconfiguration'
+});
+/** Write a core-py-compatible JSON auth rejection. */
+export function writeAuthRejection(res, status, detail) {
+    const body = Buffer.from(pyJsonDumps({ error: AUTH_STATUS_TEXT[status] ?? 'error', detail }), 'utf8');
+    const headers = {
+        'content-type': 'application/json',
+        'content-length': String(body.length)
+    };
+    if (status === 401)
+        headers['www-authenticate'] = 'Bearer';
+    res.writeHead(status, headers);
+    res.end(body);
+}
+/**
+ * Authenticate `req`; on success run `next` with the resolved `AuthContext`
+ * bound for its whole async scope (so `currentUser()` works inside MCP tool
+ * handlers), otherwise write the rejection and never call `next`.
+ */
+export async function guardRequest(authenticator, req, res, next) {
+    const result = await authenticator.authenticate(req.headers.authorization);
+    if (!result.ok) {
+        writeAuthRejection(res, result.status ?? 500, result.detail);
+        return;
+    }
+    const context = result.context;
+    if (context === null) {
+        // ok=true always carries a context; fail closed rather than bind a
+        // null identity for the rest of the request.
+        writeAuthRejection(res, 500, 'authenticator returned no context');
+        return;
+    }
+    await runWithAuthContext(context, next);
+}
+//# sourceMappingURL=http-guard.js.map

package/build/token-auth/http-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-guard.js","sourceRoot":"","sources":["../../src/token-auth/http-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAE5C,qEAAqE;AACrE,MAAM,CAAC,MAAM,gBAAgB,GAAqC,MAAM,CAAC,MAAM,CAAC;IAC9E,GAAG,EAAE,cAAc;IACnB,GAAG,EAAE,WAAW;IAChB,GAAG,EAAE,qBAAqB;IAC1B,GAAG,EAAE,yBAAyB;CAC/B,CAAC,CAAA;AAOF,sDAAsD;AACtD,MAAM,UAAU,kBAAkB,CAAC,GAAmB,EAAE,MAAc,EAAE,MAAc;IACpF,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,KAAK,EAAE,gBAAgB,CAAC,MAAM,CAAC,IAAI,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,CAAC,CAAA;IACrG,MAAM,OAAO,GAA2B;QACtC,cAAc,EAAE,kBAAkB;QAClC,gBAAgB,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;KACtC,CAAA;IACD,IAAI,MAAM,KAAK,GAAG;QAAE,OAAO,CAAC,kBAAkB,CAAC,GAAG,QAAQ,CAAA;IAC1D,GAAG,CAAC,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC9B,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,aAAmC,EACnC,GAAoB,EACpB,GAAmB,EACnB,IAAyB;IAEzB,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,YAAY,CAAC,GAAG,CAAC,OAAO,CAAC,aAAa,CAAC,CAAA;IAC1E,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;QACf,kBAAkB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,IAAI,GAAG,EAAE,MAAM,CAAC,MAAM,CAAC,CAAA;QAC5D,OAAM;IACR,CAAC;IACD,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAA;IAC9B,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACrB,mEAAmE;QACnE,6CAA6C;QAC7C,kBAAkB,CAAC,GAAG,EAAE,GAAG,EAAE,mCAAmC,CAAC,CAAA;QACjE,OAAM;IACR,CAAC;IACD,MAAM,kBAAkB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAA;AACzC,CAAC"}

package/build/token-auth/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * HTTP token-table auth (`no-auth` / `token` / `multi`), the TS port of
+ * core-py `hull_core.auth` + `hull_core.limits`. Self-contained: nothing
+ * here imports the relay, OAuth, or transport modules.
+ */
+export { AuthConfigError, Authenticator, type AuthOutcome, defaultUsersFile, HTTP_AUTH_MODES, type HttpAuthConfig, parseBearer } from './authenticator.js';
+export { type TokenCliHandler, type TokenCliIO, tokenCliHandler } from './cli.js';
+export { type AuthContext, currentUser, type HttpAuthMode, localAuthContext, runWithAuthContext } from './context.js';
+export { AUTH_STATUS_TEXT, guardRequest, type RequestAuthenticator, writeAuthRejection } from './http-guard.js';
+export { SlidingWindowLimiter } from './limiter.js';
+export { assertNoAuthLoopback, inetAton, isLoopbackHost, ServerConfigError } from './loopback.js';
+export { hashToken, isValidTokenHash, TokenHashError, verifyToken } from './tokens.js';
+export { ensurePathAllowed, findUserByToken, loadUsers, PathNotAllowedError, type PathScope, type TokenUser, type TokenUserLimits, UsersError } from './users.js';
+//# sourceMappingURL=index.d.ts.map

package/build/token-auth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/token-auth/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,eAAe,EACf,aAAa,EACb,KAAK,WAAW,EAChB,gBAAgB,EAChB,eAAe,EACf,KAAK,cAAc,EACnB,WAAW,EACZ,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAAE,KAAK,eAAe,EAAE,KAAK,UAAU,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AACjF,OAAO,EAAE,KAAK,WAAW,EAAE,WAAW,EAAE,KAAK,YAAY,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AACrH,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,KAAK,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAC/G,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AACnD,OAAO,EAAE,oBAAoB,EAAE,QAAQ,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AACjG,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACtF,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,SAAS,EACT,mBAAmB,EACnB,KAAK,SAAS,EACd,KAAK,SAAS,EACd,KAAK,eAAe,EACpB,UAAU,EACX,MAAM,YAAY,CAAA"}

package/build/token-auth/index.js

@@ -0,0 +1,14 @@
+/**
+ * HTTP token-table auth (`no-auth` / `token` / `multi`), the TS port of
+ * core-py `hull_core.auth` + `hull_core.limits`. Self-contained: nothing
+ * here imports the relay, OAuth, or transport modules.
+ */
+export { AuthConfigError, Authenticator, defaultUsersFile, HTTP_AUTH_MODES, parseBearer } from './authenticator.js';
+export { tokenCliHandler } from './cli.js';
+export { currentUser, localAuthContext, runWithAuthContext } from './context.js';
+export { AUTH_STATUS_TEXT, guardRequest, writeAuthRejection } from './http-guard.js';
+export { SlidingWindowLimiter } from './limiter.js';
+export { assertNoAuthLoopback, inetAton, isLoopbackHost, ServerConfigError } from './loopback.js';
+export { hashToken, isValidTokenHash, TokenHashError, verifyToken } from './tokens.js';
+export { ensurePathAllowed, findUserByToken, loadUsers, PathNotAllowedError, UsersError } from './users.js';
+//# sourceMappingURL=index.js.map

package/build/token-auth/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/token-auth/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,eAAe,EACf,aAAa,EAEb,gBAAgB,EAChB,eAAe,EAEf,WAAW,EACZ,MAAM,oBAAoB,CAAA;AAC3B,OAAO,EAAyC,eAAe,EAAE,MAAM,UAAU,CAAA;AACjF,OAAO,EAAoB,WAAW,EAAqB,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AACrH,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAA6B,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAC/G,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AACnD,OAAO,EAAE,oBAAoB,EAAE,QAAQ,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAA;AACjG,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACtF,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,SAAS,EACT,mBAAmB,EAInB,UAAU,EACX,MAAM,YAAY,CAAA"}

package/build/token-auth/limiter.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Per-principal request limiter, mirroring core-py
+ * `hull_core.limits.limiter.SlidingWindowLimiter`.
+ *
+ * Deliberately in-memory: limits guard a single server process. Hosts that
+ * shard one namespace across processes terminate the limiter at their load
+ * balancer instead.
+ */
+export declare class SlidingWindowLimiter {
+    private readonly events;
+    /**
+     * Record a request for `key` and report whether it is allowed.
+     *
+     * `rpm = null` means unlimited. The request is recorded either way so
+     * bursts cannot pre-load the window after a limit change. `now` is in
+     * seconds on a monotonic clock (tests inject it).
+     */
+    check(key: string, rpm: number | null, now?: number): boolean;
+}
+//# sourceMappingURL=limiter.d.ts.map

package/build/token-auth/limiter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limiter.d.ts","sourceRoot":"","sources":["../../src/token-auth/limiter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8B;IAErD;;;;;;OAMG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAa5D;CACF"}

package/build/token-auth/limiter.js

@@ -0,0 +1,41 @@
+/**
+ * Per-principal request limiter, mirroring core-py
+ * `hull_core.limits.limiter.SlidingWindowLimiter`.
+ *
+ * Deliberately in-memory: limits guard a single server process. Hosts that
+ * shard one namespace across processes terminate the limiter at their load
+ * balancer instead.
+ */
+const WINDOW_SECONDS = 60;
+function monotonicSeconds() {
+    return performance.now() / 1000;
+}
+export class SlidingWindowLimiter {
+    constructor() {
+        this.events = new Map();
+    }
+    /**
+     * Record a request for `key` and report whether it is allowed.
+     *
+     * `rpm = null` means unlimited. The request is recorded either way so
+     * bursts cannot pre-load the window after a limit change. `now` is in
+     * seconds on a monotonic clock (tests inject it).
+     */
+    check(key, rpm, now) {
+        const current = now ?? monotonicSeconds();
+        let events = this.events.get(key);
+        if (events === undefined) {
+            events = [];
+            this.events.set(key, events);
+        }
+        const cutoff = current - WINDOW_SECONDS;
+        let drop = 0;
+        while (drop < events.length && events[drop] <= cutoff)
+            drop++;
+        if (drop > 0)
+            events.splice(0, drop);
+        events.push(current);
+        return rpm === null || events.length <= rpm;
+    }
+}
+//# sourceMappingURL=limiter.js.map

package/build/token-auth/limiter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"limiter.js","sourceRoot":"","sources":["../../src/token-auth/limiter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,cAAc,GAAG,EAAE,CAAA;AAEzB,SAAS,gBAAgB;IACvB,OAAO,WAAW,CAAC,GAAG,EAAE,GAAG,IAAI,CAAA;AACjC,CAAC;AAED,MAAM,OAAO,oBAAoB;IAAjC;QACmB,WAAM,GAAG,IAAI,GAAG,EAAoB,CAAA;IAuBvD,CAAC;IArBC;;;;;;OAMG;IACH,KAAK,CAAC,GAAW,EAAE,GAAkB,EAAE,GAAY;QACjD,MAAM,OAAO,GAAG,GAAG,IAAI,gBAAgB,EAAE,CAAA;QACzC,IAAI,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACjC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;YACzB,MAAM,GAAG,EAAE,CAAA;YACX,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAA;QAC9B,CAAC;QACD,MAAM,MAAM,GAAG,OAAO,GAAG,cAAc,CAAA;QACvC,IAAI,IAAI,GAAG,CAAC,CAAA;QACZ,OAAO,IAAI,GAAG,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,MAAM;YAAE,IAAI,EAAE,CAAA;QAC7D,IAAI,IAAI,GAAG,CAAC;YAAE,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,CAAA;QACpC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;QACpB,OAAO,GAAG,KAAK,IAAI,IAAI,MAAM,CAAC,MAAM,IAAI,GAAG,CAAA;IAC7C,CAAC;CACF"}

package/build/token-auth/loopback.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Loopback detection for the `no-auth` bind guard, mirroring core-py
+ * `hull_core.server.run._is_loopback`: the literal names `localhost`,
+ * `127.0.0.1`, `::1`, or any IPv4 address in 127.0.0.0/8 written in the
+ * classic `inet_aton` forms (`127.1`, `0x7f.1`, `017700000001`, ...).
+ */
+/** Invalid server start configuration (core-py `ServerConfigError`). */
+export declare class ServerConfigError extends Error {
+    constructor(message: string);
+}
+/** Strict BSD `inet_aton`: returns the 32-bit address, or `null` when invalid. */
+export declare function inetAton(host: string): number | null;
+/** True when `host` is a loopback bind address under core-py's rules. */
+export declare function isLoopbackHost(host: string): boolean;
+/** Throw core-py's `ServerConfigError` when `no-auth` would bind beyond loopback. */
+export declare function assertNoAuthLoopback(host: string): void;
+//# sourceMappingURL=loopback.d.ts.map

package/build/token-auth/loopback.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loopback.d.ts","sourceRoot":"","sources":["../../src/token-auth/loopback.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,wEAAwE;AACxE,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AASD,kFAAkF;AAClF,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAepD;AAED,yEAAyE;AACzE,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAIpD;AAED,qFAAqF;AACrF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAMvD"}

package/build/token-auth/loopback.js

@@ -0,0 +1,62 @@
+/**
+ * Loopback detection for the `no-auth` bind guard, mirroring core-py
+ * `hull_core.server.run._is_loopback`: the literal names `localhost`,
+ * `127.0.0.1`, `::1`, or any IPv4 address in 127.0.0.0/8 written in the
+ * classic `inet_aton` forms (`127.1`, `0x7f.1`, `017700000001`, ...).
+ */
+import { pyRepr } from './py-compat.js';
+const LOOPBACK_NAMES = new Set(['localhost', '127.0.0.1', '::1']);
+/** Invalid server start configuration (core-py `ServerConfigError`). */
+export class ServerConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ServerConfigError';
+    }
+}
+function parsePart(part) {
+    if (/^0[xX][0-9a-fA-F]+$/.test(part))
+        return Number.parseInt(part.slice(2), 16);
+    if (/^0[0-7]*$/.test(part))
+        return part.length === 1 ? 0 : Number.parseInt(part.slice(1), 8);
+    if (/^[1-9][0-9]*$/.test(part))
+        return Number.parseInt(part, 10);
+    return null;
+}
+/** Strict BSD `inet_aton`: returns the 32-bit address, or `null` when invalid. */
+export function inetAton(host) {
+    const parts = host.split('.');
+    if (parts.length < 1 || parts.length > 4)
+        return null;
+    const values = [];
+    for (const part of parts) {
+        const value = parsePart(part);
+        if (value === null)
+            return null;
+        values.push(value);
+    }
+    const last = values.length - 1;
+    for (let i = 0; i < last; i++)
+        if (values[i] > 0xff)
+            return null;
+    if (values[last] >= 2 ** (8 * (4 - last)))
+        return null;
+    let address = 0;
+    for (let i = 0; i < last; i++)
+        address += values[i] * 2 ** (8 * (3 - i));
+    return address + values[last];
+}
+/** True when `host` is a loopback bind address under core-py's rules. */
+export function isLoopbackHost(host) {
+    if (LOOPBACK_NAMES.has(host))
+        return true;
+    const address = inetAton(host);
+    return address !== null && Math.floor(address / 2 ** 24) === 0x7f;
+}
+/** Throw core-py's `ServerConfigError` when `no-auth` would bind beyond loopback. */
+export function assertNoAuthLoopback(host) {
+    if (isLoopbackHost(host))
+        return;
+    throw new ServerConfigError(`auth = 'no-auth' only permits loopback binds, refusing host ${pyRepr(host)} ` +
+        "(set [server] auth to 'token' or 'multi' for a shared listener)");
+}
+//# sourceMappingURL=loopback.js.map

package/build/token-auth/loopback.js.map

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

package/build/token-auth/py-compat.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Small helpers that reproduce Python string semantics the core-py auth stack
+ * leaks into its wire output and error messages, so the TS port emits the
+ * same bytes: `repr()` of a str, `str.strip()`, code-point slicing, and
+ * `json.dumps()` of a flat string map.
+ *
+ * Internal to `token-auth`; not part of the public API.
+ */
+/** Python `str.strip()` with no argument. */
+export declare function pyStrip(value: string): string;
+/** Python `s[:n]` (code points, not UTF-16 units). */
+export declare function pyPrefix(value: string, n: number): string;
+/**
+ * Python `repr()` of a str: single quotes unless the text contains a single
+ * quote and no double quote; backslash, the chosen quote, and non-printable
+ * characters escaped the way CPython escapes them.
+ */
+export declare function pyRepr(value: string): string;
+/**
+ * Python `json.dumps(obj)` for a flat `str -> str` map with default settings
+ * (`ensure_ascii=True`, separators `', '` and `': '`).
+ */
+export declare function pyJsonDumps(obj: Readonly<Record<string, string>>): string;
+//# sourceMappingURL=py-compat.d.ts.map

package/build/token-auth/py-compat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"py-compat.d.ts","sourceRoot":"","sources":["../../src/token-auth/py-compat.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAaH,6CAA6C;AAC7C,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAO7C;AAED,sDAAsD;AACtD,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAEzD;AAMD;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAgB5C;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,MAAM,CAKzE"}

package/build/token-auth/py-compat.js

@@ -0,0 +1,76 @@
+/**
+ * Small helpers that reproduce Python string semantics the core-py auth stack
+ * leaks into its wire output and error messages, so the TS port emits the
+ * same bytes: `repr()` of a str, `str.strip()`, code-point slicing, and
+ * `json.dumps()` of a flat string map.
+ *
+ * Internal to `token-auth`; not part of the public API.
+ */
+// Every code point for which Python's `str.isspace()` is true. JS `trim()`
+// differs: it strips U+FEFF but not U+001C..U+001F or U+0085.
+const PY_WHITESPACE = new Set([
+    0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x1c, 0x1d, 0x1e, 0x1f, 0x20, 0x85, 0xa0, 0x1680, 0x2000, 0x2001, 0x2002, 0x2003,
+    0x2004, 0x2005, 0x2006, 0x2007, 0x2008, 0x2009, 0x200a, 0x2028, 0x2029, 0x202f, 0x205f, 0x3000
+]);
+function isPySpace(ch) {
+    return PY_WHITESPACE.has(ch.codePointAt(0));
+}
+/** Python `str.strip()` with no argument. */
+export function pyStrip(value) {
+    const chars = Array.from(value);
+    let start = 0;
+    let end = chars.length;
+    while (start < end && isPySpace(chars[start]))
+        start++;
+    while (end > start && isPySpace(chars[end - 1]))
+        end--;
+    return chars.slice(start, end).join('');
+}
+/** Python `s[:n]` (code points, not UTF-16 units). */
+export function pyPrefix(value, n) {
+    return Array.from(value).slice(0, n).join('');
+}
+// Python's `str.isprintable()` is false for categories Cc, Cf, Cs, Co, Cn,
+// Zl, Zp and Zs, except the ASCII space.
+const NON_PRINTABLE = /^[\p{C}\p{Z}]$/u;
+/**
+ * Python `repr()` of a str: single quotes unless the text contains a single
+ * quote and no double quote; backslash, the chosen quote, and non-printable
+ * characters escaped the way CPython escapes them.
+ */
+export function pyRepr(value) {
+    const quote = value.includes("'") && !value.includes('"') ? '"' : "'";
+    let out = quote;
+    for (const ch of value) {
+        const code = ch.codePointAt(0);
+        if (ch === quote || ch === '\\')
+            out += `\\${ch}`;
+        else if (ch === '\t')
+            out += '\\t';
+        else if (ch === '\n')
+            out += '\\n';
+        else if (ch === '\r')
+            out += '\\r';
+        else if (ch !== ' ' && NON_PRINTABLE.test(ch)) {
+            if (code < 0x100)
+                out += `\\x${code.toString(16).padStart(2, '0')}`;
+            else if (code < 0x10000)
+                out += `\\u${code.toString(16).padStart(4, '0')}`;
+            else
+                out += `\\U${code.toString(16).padStart(8, '0')}`;
+        }
+        else
+            out += ch;
+    }
+    return out + quote;
+}
+/**
+ * Python `json.dumps(obj)` for a flat `str -> str` map with default settings
+ * (`ensure_ascii=True`, separators `', '` and `': '`).
+ */
+export function pyJsonDumps(obj) {
+    const encode = (s) => JSON.stringify(s).replace(/[^\x20-\x7e]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, '0')}`);
+    const items = Object.entries(obj).map(([k, v]) => `${encode(k)}: ${encode(v)}`);
+    return `{${items.join(', ')}}`;
+}
+//# sourceMappingURL=py-compat.js.map

package/build/token-auth/py-compat.js.map

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

package/build/token-auth/tokens.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Bearer token hashing and verification for the HTTP token table.
+ *
+ * Byte-compatible with core-py `hull_core.auth.tokens`: tokens never reach
+ * disk in plaintext; the host stores a scrypt hash in `users.toml` /
+ * `config.toml` and verifies presented bearer tokens against it. Format:
+ *
+ *     scrypt$<n>$<r>$<p>$<salt-hex>$<derived-key-hex>
+ *
+ * Defaults match Python exactly (N=2^15, r=8, p=1, 32-byte key, 16-byte
+ * salt, 64 MiB scrypt memory ceiling), so a hash minted by either language
+ * verifies in the other.
+ */
+/** Raised when an encoded token hash is malformed. */
+export declare class TokenHashError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Hash a bearer token into the storable `scrypt$...` encoding. */
+export declare function hashToken(token: string): Promise<string>;
+/**
+ * Constant-time verify a presented token against an encoded hash.
+ *
+ * Rejects with `TokenHashError` when `encoded` is malformed (never resolves
+ * `true` for a hash it cannot parse); resolves `false` on a mismatch.
+ */
+export declare function verifyToken(token: string, encoded: string): Promise<boolean>;
+/**
+ * True when `encoded` parses as a scrypt token hash whose parameters the
+ * local scrypt accepts. Like core-py `is_valid_encoding`, it runs one full
+ * derivation so parameters that only fail inside scrypt (memory ceiling)
+ * are caught at load time instead of on the first request. Never throws.
+ */
+export declare function isValidTokenHash(encoded: string): boolean;
+//# sourceMappingURL=tokens.d.ts.map

package/build/token-auth/tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../src/token-auth/tokens.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAmBH,sDAAsD;AACtD,qBAAa,cAAe,SAAQ,KAAK;IACvC,YAAY,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAGzD;CACF;AAiDD,mEAAmE;AACnE,wBAAsB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAW9D;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CASlF;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAQzD"}

package/build/token-auth/tokens.js

@@ -0,0 +1,115 @@
+/**
+ * Bearer token hashing and verification for the HTTP token table.
+ *
+ * Byte-compatible with core-py `hull_core.auth.tokens`: tokens never reach
+ * disk in plaintext; the host stores a scrypt hash in `users.toml` /
+ * `config.toml` and verifies presented bearer tokens against it. Format:
+ *
+ *     scrypt$<n>$<r>$<p>$<salt-hex>$<derived-key-hex>
+ *
+ * Defaults match Python exactly (N=2^15, r=8, p=1, 32-byte key, 16-byte
+ * salt, 64 MiB scrypt memory ceiling), so a hash minted by either language
+ * verifies in the other.
+ */
+import { randomBytes, scrypt, scryptSync, timingSafeEqual } from 'node:crypto';
+import { pyPrefix, pyRepr } from './py-compat.js';
+const SCRYPT_N = 2 ** 15;
+const SCRYPT_R = 8;
+const SCRYPT_P = 1;
+const DKLEN = 32;
+const SALT_BYTES = 16;
+const PREFIX = 'scrypt';
+// 128 * N * r = 32 MiB working memory; grant the same explicit 64 MiB
+// ceiling core-py passes to hashlib.scrypt.
+const MAXMEM = 64 * 1024 * 1024;
+const DECIMAL = /^[0-9]+$/;
+const HEX = /^(?:[0-9a-fA-F]{2})+$/;
+/** Raised when an encoded token hash is malformed. */
+export class TokenHashError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'TokenHashError';
+    }
+}
+function malformed(encoded, cause) {
+    const shown = typeof encoded === 'string' ? pyRepr(pyPrefix(encoded, 24)) : String(encoded);
+    return new TokenHashError(`malformed token hash encoding: ${shown}`, cause === undefined ? undefined : { cause });
+}
+function parseInteger(text) {
+    if (!DECIMAL.test(text))
+        return null;
+    const value = Number(text);
+    return Number.isSafeInteger(value) ? value : null;
+}
+function parseHash(encoded) {
+    if (typeof encoded !== 'string')
+        throw malformed(encoded);
+    const parts = encoded.split('$');
+    if (parts.length !== 6)
+        throw malformed(encoded);
+    const [prefix, nText, rText, pText, saltHex, dkHex] = parts;
+    const n = parseInteger(nText);
+    const r = parseInteger(rText);
+    const p = parseInteger(pText);
+    if (prefix !== PREFIX || n === null || r === null || p === null)
+        throw malformed(encoded);
+    // scrypt requires N to be a power of two greater than one, r and p >= 1.
+    if (n < 2 || (n & (n - 1)) !== 0 || n > 2 ** 30 || r < 1 || p < 1)
+        throw malformed(encoded);
+    if (!HEX.test(saltHex) || !HEX.test(dkHex))
+        throw malformed(encoded);
+    return { n, r, p, salt: Buffer.from(saltHex, 'hex'), expected: Buffer.from(dkHex, 'hex') };
+}
+function scryptOptions(parsed) {
+    return { N: parsed.n, r: parsed.r, p: parsed.p, maxmem: MAXMEM };
+}
+function scryptAsync(password, salt, keylen, options) {
+    return new Promise((resolve, reject) => {
+        scrypt(password, salt, keylen, options, (err, derived) => {
+            if (err)
+                reject(err);
+            else
+                resolve(derived);
+        });
+    });
+}
+/** Hash a bearer token into the storable `scrypt$...` encoding. */
+export async function hashToken(token) {
+    const salt = randomBytes(SALT_BYTES);
+    const dk = await scryptAsync(Buffer.from(token, 'utf8'), salt, DKLEN, scryptOptions({ n: SCRYPT_N, r: SCRYPT_R, p: SCRYPT_P }));
+    return [PREFIX, String(SCRYPT_N), String(SCRYPT_R), String(SCRYPT_P), salt.toString('hex'), dk.toString('hex')].join('$');
+}
+/**
+ * Constant-time verify a presented token against an encoded hash.
+ *
+ * Rejects with `TokenHashError` when `encoded` is malformed (never resolves
+ * `true` for a hash it cannot parse); resolves `false` on a mismatch.
+ */
+export async function verifyToken(token, encoded) {
+    const parsed = parseHash(encoded);
+    let actual;
+    try {
+        actual = await scryptAsync(Buffer.from(token, 'utf8'), parsed.salt, parsed.expected.length, scryptOptions(parsed));
+    }
+    catch (err) {
+        throw malformed(encoded, err);
+    }
+    return timingSafeEqual(actual, parsed.expected);
+}
+/**
+ * True when `encoded` parses as a scrypt token hash whose parameters the
+ * local scrypt accepts. Like core-py `is_valid_encoding`, it runs one full
+ * derivation so parameters that only fail inside scrypt (memory ceiling)
+ * are caught at load time instead of on the first request. Never throws.
+ */
+export function isValidTokenHash(encoded) {
+    try {
+        const parsed = parseHash(encoded);
+        scryptSync(Buffer.alloc(0), parsed.salt, parsed.expected.length, scryptOptions(parsed));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=tokens.js.map

package/build/token-auth/tokens.js.map

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

package/build/token-auth/users.d.ts

@@ -0,0 +1,62 @@
+/**
+ * users.toml: the multi-user token table (auth mode `multi`).
+ *
+ * Same schema and validation order as core-py `hull_core.auth.users`:
+ *
+ *     [users.<uid>]
+ *     token_hash = "scrypt$..."        # mint with `hull token hash`
+ *     enabled = true
+ *     namespace = "<uid-or-shared>"    # data isolation root
+ *     allowed_roots = ["/data/alice"]  # filesystem roots tools may touch
+ *     [users.<uid>.limits]
+ *     rpm = 60                         # optional per-minute request cap
+ *
+ * Admin is host-side only: edit the file, restart the server. There is no
+ * admin API and no self-service.
+ */
+/** Raised when users.toml is missing, malformed, or semantically invalid. */
+export declare class UsersError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** Raised by `ensurePathAllowed` (core-py raises `PermissionError`). */
+export declare class PathNotAllowedError extends Error {
+    readonly code = "EACCES";
+    constructor(message: string);
+}
+export interface TokenUserLimits {
+    /** Per-minute request cap; `null` means unlimited. */
+    readonly rpm: number | null;
+}
+/** One validated `[users.<uid>]` row. */
+export interface TokenUser {
+    readonly uid: string;
+    readonly tokenHash: string;
+    readonly enabled: boolean;
+    readonly namespace: string;
+    readonly allowedRoots: readonly string[];
+    readonly limits: TokenUserLimits;
+}
+/** Anything carrying a caller's filesystem roots (a `TokenUser` or an `AuthContext`). */
+export interface PathScope {
+    readonly uid: string;
+    readonly allowedRoots: readonly string[];
+}
+/**
+ * Parse and validate users.toml into a `uid -> TokenUser` map.
+ *
+ * Synchronous on purpose: it runs once at server build time, and each
+ * `token_hash` is checked with one full scrypt derivation (like core-py
+ * `is_valid_encoding`) so an unusable row fails the boot, not a request.
+ */
+export declare function loadUsers(path: string): Map<string, TokenUser>;
+/** Return the first user whose `tokenHash` verifies `token`, else `null`. */
+export declare function findUserByToken(users: ReadonlyMap<string, TokenUser>, token: string): Promise<TokenUser | null>;
+/**
+ * Enforce the caller's `allowedRoots`. An empty list grants nothing. Both
+ * sides are resolved first, so a symlinked escape needs its resolved target
+ * to sit under a root too. Throws `PathNotAllowedError` on denial.
+ */
+export declare function ensurePathAllowed(scope: PathScope, path: string): void;
+//# sourceMappingURL=users.d.ts.map