@wenathlan/saddle 2.0.150 → 2.0.152

package/dist/api.d.ts

@@ -0,0 +1,154 @@
+/**
+ * shared api client for the React interface: one typed module replaces
+ * the three copies of apibase()/iscrossorigin()/apifetch() that lived
+ * inside login.js, register.js and dashboard.js. the api base resolves
+ * from the ?api= query string (persisted for convenience), the
+ * window.SADDLE_API global, the "saddle_api" localstorage key or
+ * same-origin; cross-origin targets switch to credentials: "include"
+ * so the saddlesession cookie still flows. json in, json out, family
+ * error handling.
+ */
+/** standardized error payload answered by every /api/v1 endpoint. */
+export type ApiErrorBody = {
+    error: {
+        code: string;
+        message: string;
+    };
+};
+/** health endpoint payload (/api/v1/health). */
+export type HealthStatus = {
+    ok: boolean;
+    version: string;
+    uptime: number;
+};
+/** sandbox creation request carried by POST /api/v1/sandboxes. */
+export type SandboxSpecPayload = {
+    model: string;
+    vcpus: number;
+    ramgb: number;
+    gpu: string;
+    mig: string;
+    quotamb?: number;
+};
+/** sandbox creation response. */
+export type SandboxCreated = {
+    id: string;
+    state: string;
+};
+/** exec response shared by the api and the local engine dispatcher. */
+export type ExecResult = {
+    output: string;
+    exitCode: number;
+};
+/** session payload answered by the auth endpoints (/api/v1/auth/*). */
+export type ApiSession = {
+    user: string;
+    role: "admin" | "user";
+    issuedat: string;
+    expiresat: string;
+};
+declare global {
+    interface Window {
+        /** optional api base override for static-edge deployments. */
+        SADDLE_API?: string;
+    }
+}
+/**
+ * resolves the api base: ?api= wins (and persists), then the window
+ * global, then localstorage, then same origin ("").
+ *
+ * @returns the trimmed api base ("" means same-origin).
+ */
+export declare function apibase(): string;
+/**
+ * checks whether the api base points at a different origin.
+ *
+ * @param base the resolved api base ("" means same-origin).
+ * @returns true when the target is cross-origin.
+ */
+export declare function iscrossorigin(base: string): boolean;
+/**
+ * fetch wrapper: json in, json out, credentials follow the origin.
+ * sets the content-type automatically whenever a body is present and
+ * switches to credentials: "include" for cross-origin bases so the
+ * session cookie still reaches the api.
+ *
+ * @param path the api path (must start with "/").
+ * @param init the fetch init; body must already be a json string.
+ * @returns the raw response for ok/status handling by the caller.
+ */
+export declare function apifetch(path: string, init?: RequestInit): Promise<Response>;
+/**
+ * probes the api health endpoint with a short timeout.
+ *
+ * @param base the api base to probe ("" means same-origin).
+ * @param timeoutms abort budget in milliseconds.
+ * @returns the health payload when the api answers ok, null otherwise.
+ */
+export declare function fetchhealth(base: string, timeoutms?: number): Promise<HealthStatus | null>;
+/**
+ * reads the {error:{code,message}} payload the family endpoints answer
+ * with; returns null when the body is not a recognizable error object.
+ *
+ * @param response a non-ok api response.
+ * @returns the error message when present, null otherwise.
+ */
+export declare function apierrormessage(response: Response): Promise<string | null>;
+/**
+ * human label for the resolved api base, used by the auth pages status
+ * line ("api: same origin" or the cross-origin target with credentials).
+ *
+ * @returns the status line text.
+ */
+export declare function apistatustext(): string;
+/** one modality record of the compute plan (the modalities endpoint). */
+export type ModalityRecord = {
+    id: string;
+    label: string;
+    family: string;
+    isolation: string;
+    state: "live" | "host" | "planned";
+    drivers: string[];
+    hardening: string[];
+    boot: "hot" | "warm" | "cold";
+    bootms: number;
+    gpu: boolean;
+    network: boolean;
+    mime: string;
+};
+/** the modality plan payload answered by the modalities endpoint. */
+export type ModalityPlan = {
+    plancount: number;
+    live: number;
+    host: number;
+    planned: number;
+    records: ModalityRecord[];
+};
+/** one edge lane of the sandbox modality surface (the edge lanes endpoint). */
+export type EdgeLane = {
+    modality: string;
+    kind: "live" | "host";
+    runtime: string;
+    probed: boolean;
+    present: boolean;
+};
+/**
+ * fetches the compute modality plan with a short timeout: the counts and
+ * the records the compute face renders. the surface never invents rows —
+ * when the engine does not answer the caller renders the honest line.
+ *
+ * @param base the api base to query ("" means same-origin).
+ * @param timeoutms abort budget in milliseconds.
+ * @returns the plan payload when the api answers ok, null otherwise.
+ */
+export declare function fetchmodalities(base?: string, timeoutms?: number): Promise<ModalityPlan | null>;
+/**
+ * fetches the edge lane table with a short timeout: one row per live or
+ * host modality with its runtime and probe outcome; null when the engine
+ * does not answer.
+ *
+ * @param base the api base to query ("" means same-origin).
+ * @param timeoutms abort budget in milliseconds.
+ * @returns the lane list when the api answers ok, null otherwise.
+ */
+export declare function fetchedgelanes(base?: string, timeoutms?: number): Promise<EdgeLane[]>;

package/dist/api.js

@@ -0,0 +1,174 @@
+/**
+ * shared api client for the React interface: one typed module replaces
+ * the three copies of apibase()/iscrossorigin()/apifetch() that lived
+ * inside login.js, register.js and dashboard.js. the api base resolves
+ * from the ?api= query string (persisted for convenience), the
+ * window.SADDLE_API global, the "saddle_api" localstorage key or
+ * same-origin; cross-origin targets switch to credentials: "include"
+ * so the saddlesession cookie still flows. json in, json out, family
+ * error handling.
+ */
+/** localstorage key carrying the persisted api base override. */
+const apistoragekey = "saddle_api";
+/**
+ * resolves the api base: ?api= wins (and persists), then the window
+ * global, then localstorage, then same origin ("").
+ *
+ * @returns the trimmed api base ("" means same-origin).
+ */
+export function apibase() {
+    try {
+        const fromquery = new URLSearchParams(window.location.search).get("api");
+        if (fromquery !== null && fromquery.trim() !== "") {
+            const trimmed = fromquery.trim().replace(/\/+$/, "");
+            window.localStorage.setItem(apistoragekey, trimmed);
+            return trimmed;
+        }
+        const preset = window.SADDLE_API || window.localStorage.getItem(apistoragekey) || "";
+        return String(preset).trim().replace(/\/+$/, "");
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * checks whether the api base points at a different origin.
+ *
+ * @param base the resolved api base ("" means same-origin).
+ * @returns true when the target is cross-origin.
+ */
+export function iscrossorigin(base) {
+    if (base === "")
+        return false;
+    try {
+        return new URL(base, window.location.href).origin !== window.location.origin;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * fetch wrapper: json in, json out, credentials follow the origin.
+ * sets the content-type automatically whenever a body is present and
+ * switches to credentials: "include" for cross-origin bases so the
+ * session cookie still reaches the api.
+ *
+ * @param path the api path (must start with "/").
+ * @param init the fetch init; body must already be a json string.
+ * @returns the raw response for ok/status handling by the caller.
+ */
+export async function apifetch(path, init = {}) {
+    const base = apibase();
+    const headers = new Headers(init.headers);
+    if (init.body !== undefined && !headers.has("content-type")) {
+        headers.set("content-type", "application/json");
+    }
+    const credentials = iscrossorigin(base) ? "include" : "same-origin";
+    return fetch(`${base}${path}`, { ...init, headers, credentials });
+}
+/**
+ * probes the api health endpoint with a short timeout.
+ *
+ * @param base the api base to probe ("" means same-origin).
+ * @param timeoutms abort budget in milliseconds.
+ * @returns the health payload when the api answers ok, null otherwise.
+ */
+export async function fetchhealth(base, timeoutms = 1500) {
+    try {
+        const url = `${base ? base.replace(/\/+$/, "") : ""}/api/v1/health`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutms);
+        const response = await fetch(url, { signal: controller.signal });
+        clearTimeout(timer);
+        if (!response.ok)
+            return null;
+        const body = (await response.json());
+        return body && body.ok === true ? body : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * reads the {error:{code,message}} payload the family endpoints answer
+ * with; returns null when the body is not a recognizable error object.
+ *
+ * @param response a non-ok api response.
+ * @returns the error message when present, null otherwise.
+ */
+export async function apierrormessage(response) {
+    try {
+        const payload = (await response.json());
+        if (payload?.error && typeof payload.error.message === "string") {
+            return payload.error.message;
+        }
+    }
+    catch {
+        /* keep null: the generic message stays */
+    }
+    return null;
+}
+/**
+ * human label for the resolved api base, used by the auth pages status
+ * line ("api: same origin" or the cross-origin target with credentials).
+ *
+ * @returns the status line text.
+ */
+export function apistatustext() {
+    const base = apibase();
+    return base === "" ? "api: same origin" : `api: ${base} (cross-origin, credentials: include)`;
+}
+/**
+ * fetches the compute modality plan with a short timeout: the counts and
+ * the records the compute face renders. the surface never invents rows —
+ * when the engine does not answer the caller renders the honest line.
+ *
+ * @param base the api base to query ("" means same-origin).
+ * @param timeoutms abort budget in milliseconds.
+ * @returns the plan payload when the api answers ok, null otherwise.
+ */
+export async function fetchmodalities(base = apibase(), timeoutms = 3000) {
+    try {
+        const url = `${base ? base.replace(/\/+$/, "") : ""}/api/v1/modalities`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutms);
+        const response = await fetch(url, { signal: controller.signal });
+        clearTimeout(timer);
+        if (!response.ok)
+            return null;
+        const body = (await response.json());
+        if (body === null || !Array.isArray(body.records))
+            return null;
+        return body;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * fetches the edge lane table with a short timeout: one row per live or
+ * host modality with its runtime and probe outcome; null when the engine
+ * does not answer.
+ *
+ * @param base the api base to query ("" means same-origin).
+ * @param timeoutms abort budget in milliseconds.
+ * @returns the lane list when the api answers ok, null otherwise.
+ */
+export async function fetchedgelanes(base = apibase(), timeoutms = 3000) {
+    try {
+        const url = `${base ? base.replace(/\/+$/, "") : ""}/api/v1/edge/lanes`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutms);
+        const response = await fetch(url, { signal: controller.signal });
+        clearTimeout(timer);
+        if (!response.ok)
+            return null;
+        const body = (await response.json());
+        if (body === null || !Array.isArray(body.lanes))
+            return null;
+        return body.lanes;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/auth.d.ts

@@ -0,0 +1,268 @@
+/**
+ * auth.ts — security layer for the saddle web node (v7-BACK).
+ *
+ * everything that touches credentials and sessions lives here: scrypt
+ * password hashing (n=16384, r=8, p=1) with timing-safe verification,
+ * opaque base64url session tokens stored only as sha256 hashes, the
+ * saddlesession cookie builder, the in-memory ip rate limiter, and the
+ * requireauth/requireadmin request guards. the bootstrap rule is part
+ * of the contract: the first user registered on a node with zero users
+ * is granted role admin (see createsession caller in server.ts), so a
+ * fresh main or standalone node always has one operator.
+ *
+ * contexts (9): passwordhashing, sessiontokens, sessionstore, cookies,
+ * ratelimiter, requestguards, usernamepolicy, timingequalizer,
+ * bootstrap.
+ *
+ * rules: lowercase identifiers, english jsdoc in third person, no emoji,
+ * try/catch on every fallible path, node:* modules only, zero
+ * dependencies, no hardcoded localhost anywhere.
+ */
+import type { IncomingMessage } from 'node:http';
+/** the request context of one session mint plus an optional ttl override. */
+export type SessionContext = {
+    ip?: string;
+    useragent?: string;
+    ttlms?: number;
+};
+/** the minted session values handed to the register/login routes. */
+export type SessionMaterial = {
+    token: string;
+    tokenhash: string;
+    expiresat: string;
+};
+/** a session minted by the main node and relayed to the clone. */
+export type ForwardedSession = {
+    token: string;
+    userid: string;
+    expiresat: string;
+    ip?: string;
+    useragent?: string;
+};
+/** the authenticated user projection resolved by requireauth. */
+export type SessionUser = {
+    id: string;
+    username: string;
+    role: string;
+    expiresat: string;
+};
+/** the success arm of a policy validation. */
+export type ValidationOk = {
+    ok: true;
+};
+/** the failure arm of a policy validation. */
+export type ValidationError = {
+    ok: false;
+    code: string;
+    message: string;
+};
+/** the outcome of a username or password policy check. */
+export type ValidationOutcome = ValidationOk | ValidationError;
+/** one in-memory rate limit bucket. */
+export type RateBucket = {
+    count: number;
+    resetat: number;
+};
+/** the verdict of the in-memory rate limiter. */
+export type RateVerdict = {
+    allowed: boolean;
+    retryafter: number;
+};
+/** one pinned rate limit window. */
+export type RateWindow = {
+    limit: number;
+    windowms: number;
+};
+/** the augmented request shape requireauth injects the resolved user and
+ * the raw token on; the augmentation below carries the two optional
+ * properties onto every node:http incoming message in the project. */
+export type AuthedRequest = IncomingMessage & {
+    user?: SessionUser;
+    sessiontoken?: string;
+};
+declare module 'node:http' {
+    interface IncomingMessage {
+        user?: SessionUser;
+        sessiontoken?: string;
+    }
+}
+/**
+ * hashes one password with scrypt and a fresh 32-byte random salt.
+ *
+ * @param password the plaintext password (8-128 chars,
+ *   enforced by the route layer).
+ * @returns the hex digest and the hex salt, both ready for the users row.
+ */
+export declare function hashpassword(password: string): {
+    passwordhash: string;
+    salt: string;
+};
+/**
+ * verifies one password against a stored hash and salt using
+ * timingSafeEqual; any input or encoding failure resolves to false so
+ * callers never leak the failure reason.
+ *
+ * @param password the plaintext candidate.
+ * @param passwordhash the stored hex digest.
+ * @param salt the stored hex salt.
+ * @returns true when the password matches.
+ */
+export declare function verifypassword(password: string, passwordhash: string, salt: string): boolean;
+/**
+ * burns one scrypt round against the dummy pair so a login for an
+ * unknown username costs the same time as a login for a real one.
+ *
+ * @returns always false.
+ */
+declare function burndummy(): boolean;
+/**
+ * mints one opaque session token: 32 random bytes in base64url.
+ *
+ * @returns the bearer/cookie token.
+ */
+export declare function sessiontoken(): string;
+/**
+ * derives the sha256 hex digest stored in the sessions table; the raw
+ * token never touches the database.
+ *
+ * @param token the raw session token.
+ * @returns the hex token hash.
+ */
+export declare function tokenhash(token: string): string;
+/**
+ * creates one session row for a user and returns the token material.
+ *
+ * @param userid the user id.
+ * @param context the request context and an optional ttl override.
+ * @returns the minted session values.
+ */
+export declare function createsession(userid: string, context?: SessionContext): SessionMaterial;
+/**
+ * caches one session minted elsewhere (the mesh main node) into the
+ * local sessions table with the remote userid.
+ *
+ * @param fields the forwarded session.
+ * @returns void.
+ */
+export declare function cachesession(fields: ForwardedSession): void;
+/**
+ * resolves the user behind one raw token: hash lookup, expiry check and
+ * user projection in one call.
+ *
+ * @param token the raw session token.
+ * @returns the user or null when the session is
+ *   missing, expired or orphaned.
+ */
+export declare function getsessionuser(token: string): SessionUser | null;
+/**
+ * destroys one session by raw token.
+ *
+ * @param token the raw session token.
+ * @returns true when a session row was removed.
+ */
+export declare function destroysession(token: string): boolean;
+/** the session cookie name shared by every node in the mesh. */
+export declare const cookiename = "saddlesession";
+/**
+ * builds the set-cookie value for one session token: HttpOnly,
+ * SameSite=Strict, Path=/, Max-Age=86400 and Secure whenever the
+ * request arrived through https (directly or via x-forwarded-proto).
+ *
+ * @param token the raw session token.
+ * @param req the incoming request, used only to detect https.
+ * @returns the set-cookie header value.
+ */
+export declare function cookiefor(token: string, req?: IncomingMessage): string;
+/**
+ * builds the expiring set-cookie value used by logout.
+ *
+ * @returns the set-cookie header value clearing the cookie.
+ */
+export declare function cookieclear(): string;
+/**
+ * extracts the session token from the saddlesession cookie or the
+ * Authorization: Bearer header of one request.
+ *
+ * @param req the incoming request.
+ * @returns the raw token or null.
+ */
+export declare function extracttoken(req: IncomingMessage): string | null;
+/**
+ * the auth guard: reads the cookie or bearer token, resolves the
+ * session and injects req.user = {id, username, role, expiresat}.
+ *
+ * @param req the incoming request.
+ * @returns the injected user or null when
+ *   unauthenticated.
+ */
+export declare function requireauth(req: IncomingMessage): SessionUser | null;
+/**
+ * the admin guard: requireauth plus the admin role check.
+ *
+ * @param req the incoming request.
+ * @returns the admin user or null.
+ */
+export declare function requireadmin(req: IncomingMessage): SessionUser | null;
+/**
+ * validates one username candidate against the v7 policy; the candidate
+ * is coerced defensively so route layers can pass raw json fields.
+ *
+ * @param username the candidate.
+ * @returns the validation outcome.
+ */
+export declare function validateusername(username: unknown): ValidationOutcome;
+/**
+ * validates one password candidate against the v7 policy (8-128 chars);
+ * the candidate is coerced defensively so route layers can pass raw json
+ * fields.
+ *
+ * @param password the candidate.
+ * @returns the validation outcome.
+ */
+export declare function validatepassword(password: unknown): ValidationOutcome;
+/**
+ * the in-memory rate limiter with lazy sweeping: every hit refreshes
+ * its own window and, once the map grows past the sweep limit, expired
+ * buckets from other keys are dropped.
+ *
+ * @param bucketkey the bucket key (e.g. `login:10.0.0.1`).
+ * @param limit the allowed hits per window.
+ * @param windowms the window length in milliseconds.
+ * @returns the verdict plus the retry-after seconds for 429 responses.
+ */
+export declare function ratelimit(bucketkey: string, limit: number, windowms: number): RateVerdict;
+/** the two pinned buckets from the v7 contract. */
+export declare const ratelimits: {
+    register: RateWindow;
+    login: RateWindow;
+};
+/**
+ * the ONLY admin usernames: the CODEOWNERS allowlist (iakadion,
+ * inathlan, aasblor and nasblor). the web admin surface mirrors the
+ * repository CODEOWNERS file - the two files are the same contract.
+ */
+export declare const adminusernames: string[];
+/**
+ * resolves the role for a new registration: only the CODEOWNERS
+ * usernames are admins; every other account (including the very first
+ * registration) is a plain user. the seeded admins below guarantee the
+ * allowlist accounts exist before anyone registers.
+ *
+ * @param username the requested username.
+ * @returns the role for the new row.
+ */
+export declare function bootstraprole(username?: string): 'admin' | 'user';
+/**
+ * creates the CODEOWNERS admin accounts with the resolved bootstrap
+ * password (the env pin, or the per-boot mint) when the database does not
+ * carry them yet. idempotent: an admin the operator re-registered with a
+ * rotated password is never overwritten. runs on every node boot so a
+ * wiped database never locks the admin surface out. when the password was
+ * minted for this boot, the one-time secret is written to the operator
+ * console exactly once - only for the rows that actually landed.
+ *
+ * @returns the admin usernames that were created.
+ */
+export declare function seedadmins(): string[];
+/** burn dummy re-exported for tests that assert timing equality. */
+export { burndummy };