@wenathlan/saddle 2.0.153 → 2.0.155

package/dist/api.d.ts

@@ -1,154 +0,0 @@
-/**
- * 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

@@ -1,174 +0,0 @@
-/**
- * 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

@@ -1,268 +0,0 @@
-/**
- * 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 };