@phreshos/server 0.1.15 → 0.1.17

package/README.md

@@ -113,12 +113,17 @@ waiter.
 Server Program handles add `install()` and `fork()`. `install()` is an async
 generator that opens immediately, yields ordered `stdout` and `stderr` command
 chunks, completes only after installation succeeds, and throws the owning
-System error when installation fails. Their filesystem areas also expose
+System error when installation fails. Their `Storage` values also expose
 `path()` and traversal-safe `resolve()`, because filesystem work is performed
 locally in the Server SDK after the Host supplies only the area root.
 Object descriptions passed to `host.program.create()` therefore require an
 explicit absolute storage root as well as at least one declared Endpoint.
 
+`host.storage` implements that same refined `Storage` contract against the
+native operating-system home directory. The System supplies the authoritative
+root; traversal and symbolic-link escape remain rejected by the SDK before any
+filesystem operation.
+
 Host registries are separated by owner. Reads, commands, and the complete
 subscription contract live on their relevant capability rather than directly
 on `host`:

package/dist/domain.d.ts

@@ -1,18 +1,12 @@
-import { Client as CoreClient, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, Server as CoreServer, type AnswerCapture, type AskCapture, type Cleanup, type ClientDeclaration, type Exit, type Launch, type Position, type ProgramCommandChunk, type ProgramPermission, type ProgramProcess as CoreProgramProcess, type ProgramArea as CoreProgramArea, type Size, type TrafficMessage, type Window as CoreWindow, type WindowState } from "@phreshos/core";
+import { Client as CoreClient, Endpoint as CoreEndpoint, Process as CoreProcess, Program as CoreProgram, Server as CoreServer, type AnswerCapture, type AskCapture, type Cleanup, type ClientDeclaration, type Exit, type Launch, type Position, type ProgramCommandChunk, type ProgramPermission, type ProgramProcess as CoreProgramProcess, type Size, type TrafficMessage, type Window as CoreWindow, type WindowState } from "@phreshos/core";
 import Events from "./events.js";
+import { type Storage } from "./storage.js";
 import { type ProgramStartup } from "./startup.js";
 import { type ClientServiceHandler, type ServerServiceHandler } from "./service.js";
 export interface HandleAddress {
     identity: string;
     reference: string;
 }
-/** Server-side filesystem storage with access to its resolved host path. */
-export interface ProgramArea extends CoreProgramArea {
-    /** Returns the absolute host path of this storage area. */
-    path(): Promise<string>;
-    /** Resolves path segments within this storage area without permitting escape. */
-    resolve(...path: string[]): Promise<string>;
-}
 /** Client-safe Program data transported by the authoritative host. */
 export interface EndpointDeclarationRecord {
     start: boolean;
@@ -54,9 +48,9 @@ export type WindowRecord = WindowState;
 /** Server-visible Program handle and privileged Program operations. */
 export interface Program<Events extends object = {}> extends Omit<CoreProgram<Events>, "process"> {
     /** Persistent filesystem data shared by every Process of this Program. */
-    readonly data: ProgramArea;
+    readonly data: Storage;
     /** Disposable filesystem data shared by every Process of this Program. */
-    readonly cache: ProgramArea;
+    readonly cache: Storage;
     /** Persistent Process launch used when the system starts. */
     readonly startup: ProgramStartup;
     /** Persistent permission decisions owned by this Program. */

package/dist/host.d.ts

@@ -1,6 +1,7 @@
 import type { DesktopWallpaper, Exit, FileWallpaper, Layer, Position, ServedFile, ServiceKey, Size, Subscribable, ThemeProperties, WritableTheme } from "@phreshos/core";
 import type { ClientServiceHandler, ServerServiceHandler } from "./service.js";
 import { type Client, type Process, type Program, type Server } from "./domain.js";
+import { type Storage } from "./storage.js";
 /** Resolved production description for a Program's Server. */
 export type ServerDescription = Readonly<{
     /** Absolute directory containing the production Server files. */
@@ -104,6 +105,8 @@ export interface HostProcess extends Subscribable<ProcessHostEvents, never> {
 }
 /** Authoritative system capabilities available to a Server endpoint. */
 export interface Host {
+    /** Native operating-system home storage available to Server endpoints. */
+    readonly storage: Storage;
     /** Observable system Theme authority. */
     readonly theme: WritableTheme<ThemeProperties>;
     /** Authoritative wallpaper visible before authentication. */

package/dist/host.js

@@ -5,7 +5,9 @@ import ServerTheme from "./theme.js";
 import { ServerDesktopWallpaper, ServerSignInWallpaper } from "./wallpaper.js";
 import wire from "./wire.js";
 import { prepareService } from "./service.js";
+import { hostStorage } from "./storage.js";
 class ServerHost {
+    storage = hostStorage();
     theme = new ServerTheme();
     signInWallpaper = new ServerSignInWallpaper();
     desktopWallpaper = new ServerDesktopWallpaper();

package/dist/main.d.ts

@@ -2,7 +2,8 @@ export { host, type Host, type HostProcess, type HostProgram, type ClientDescrip
 export { current, type Current, type CurrentClient } from "./current.js";
 export { type Answerer, type Channel } from "./channel.js";
 export { type ProgramStartup } from "./startup.js";
+export { type Storage } from "./storage.js";
 export { ClientServiceHandler, ServerServiceHandler } from "./service.js";
 export { ServiceHandler, type ClientServiceChannel, type ServerServiceChannel, type ServiceChannel, type ServiceKey, type ServiceLifecycleEvents } from "@phreshos/core";
-export { Client, Endpoint, Process, Program, Server, type Window, type ProgramArea, type ProgramProcess } from "./domain.js";
+export { Client, Endpoint, Process, Program, Server, type Window, type ProgramProcess } from "./domain.js";
 export type { AnswerCapture, AnswerMessage, AnswerObserver, Askable, AskCapture, AskMessage, AskObserver, Capture, Captures, ChannelCapture, ChannelEvents, ChannelMessage, ClientTraffic, ClientDeclaration, Cleanup, DirectoryStat, EndpointDeclaration, EndpointTraffic, EntryStat, EventMessage, EventName, EventObserver, EventOptions, EventSubscriber, Exit, FileStat, Launch, LaunchClient, Layer, LogKind, LogRecord, LogSource, Message, OtherStat, Outcome, Position, ProgramEvents, ProgramPermission, ProgramProcessEvents, ProgramProcessExit, ProgramSql, ProgramStore, ProcessEvents, Publishable, ServedFile, ServerTraffic, Size, Subscribable, SubscribableEvents, SubscribableFallback, TimedAskable, TrafficCapture, TrafficEvents, TrafficMessage, Value, Theme, ThemeEvents, ThemeProperties, WallpaperLaunch, FileWallpaper, DesktopWallpaper, WritableTheme, WindowEvents, WindowGeometry, WindowLayer, WindowState } from "@phreshos/core";

package/dist/main.js

@@ -2,6 +2,7 @@ export { host } from "./host.js";
 export { current } from "./current.js";
 export {} from "./channel.js";
 export {} from "./startup.js";
+export {} from "./storage.js";
 export { ClientServiceHandler, ServerServiceHandler } from "./service.js";
 export { ServiceHandler } from "@phreshos/core";
 export { Client, Endpoint, Process, Program, Server } from "./domain.js";

package/dist/storage.d.ts

@@ -1,11 +1,13 @@
-import type { ProgramArea, ProgramSql, ProgramStore } from "@phreshos/core";
+import type { ProgramSql, ProgramStore, Storage as CoreStorage } from "@phreshos/core";
 import type { HandleAddress } from "./domain.js";
-export interface ServerArea extends ProgramArea {
+export interface Storage extends CoreStorage {
     path(): Promise<string>;
     resolve(...path: string[]): Promise<string>;
 }
 /** Server-local implementation of one Program-owned filesystem area. */
-export declare function area(program: HandleAddress, which: "data" | "cache"): ServerArea;
+export declare function area(program: HandleAddress, which: "data" | "cache"): Storage;
+/** Server-local access to the native home directory supplied by the System. */
+export declare function hostStorage(): Storage;
 export declare function store(program: HandleAddress): ProgramStore;
 export declare function sql(kind: "database" | "logs", program: HandleAddress): ProgramSql;
 export declare function content(value: unknown): {

package/dist/storage.js

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { createReadStream, createWriteStream, mkdirSync, readdirSync, renameSync, rmSync, statSync } from "node:fs";
+import { createReadStream, createWriteStream, mkdirSync, lstatSync, readdirSync, renameSync, rmSync, statSync } from "node:fs";
 import { rm } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, sep } from "node:path";
 import { Readable } from "node:stream";
@@ -7,31 +7,50 @@ import { pipeline } from "node:stream/promises";
 import wire from "./wire.js";
 /** Server-local implementation of one Program-owned filesystem area. */
 export function area(program, which) {
-    async function path() {
+    return createStorage(async function () {
         const answer = await wire.request([which, program, "path"]);
         return answer[0];
+    }, `this Program's ${which}`);
+}
+/** Server-local access to the native home directory supplied by the System. */
+export function hostStorage() {
+    return createStorage(async function () {
+        const answer = await wire.request(["host-storage", "path"]);
+        return answer[0];
+    }, "the native home directory");
+}
+function createStorage(root, label) {
+    let resolvedRoot = null;
+    async function path() {
+        if (!resolvedRoot) {
+            const resolving = root().then(value => {
+                if (!isAbsolute(value))
+                    throw new Error("The host returned an invalid Storage directory");
+                return value;
+            });
+            const retained = resolving.catch(error => {
+                if (resolvedRoot === retained)
+                    resolvedRoot = null;
+                throw error;
+            });
+            resolvedRoot = retained;
+        }
+        return resolvedRoot;
     }
     async function resolve(...parts) {
         const root = await path();
-        const destination = join(root, ...parts);
-        const step = relative(root, destination);
-        if (step === ".." || step.startsWith(`..${sep}`) || isAbsolute(step)) {
-            throw new Error("A storage path may not leave its area");
-        }
-        return destination;
+        return contained(root, parts);
     }
     async function stream(...parts) {
         const destination = await resolve(...parts);
         const found = describe(destination);
         if (!found)
-            throw new Error(`There is no ${parts.join("/")} in this Program's ${which}`);
+            throw new Error(`There is no ${parts.join("/")} in ${label}`);
         if (found.kind !== "file")
             throw new Error(`${parts.join("/")} is not a file`);
         return Readable.toWeb(createReadStream(destination));
     }
     async function write(...args) {
-        if (args.length < 2)
-            throw new Error("Writing takes a file name and what to write");
         const parts = args.slice(0, -1);
         const destination = await resolve(...parts);
         const temporary = join(dirname(destination), `.${randomUUID()}.writing`);
@@ -70,13 +89,38 @@ export function area(program, which) {
                 throw new Error("Emptying a place is clear, not delete");
             rmSync(await resolve(...parts), { recursive: true, force: true });
         },
-        async clear() {
-            const root = await path();
-            rmSync(root, { recursive: true, force: true });
-            mkdirSync(root, { recursive: true });
+        async clear(...parts) {
+            const destination = await resolve(...parts);
+            const found = describe(destination);
+            if (found && found.kind !== "directory")
+                throw new Error("Only a storage directory can be cleared");
+            rmSync(destination, { recursive: true, force: true });
+            mkdirSync(destination, { recursive: true });
         }
     };
 }
+function contained(root, parts) {
+    const destination = join(root, ...parts);
+    const step = relative(root, destination);
+    if (step === ".." || step.startsWith(`..${sep}`) || isAbsolute(step)) {
+        throw new Error("A storage path may not leave its configured directory");
+    }
+    let current = root;
+    for (const part of step.split(sep).filter(Boolean)) {
+        current = join(current, part);
+        try {
+            if (lstatSync(current).isSymbolicLink()) {
+                throw new Error("A storage path may not pass through a symbolic link");
+            }
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                break;
+            throw error;
+        }
+    }
+    return destination;
+}
 export function store(program) {
     async function ask(operation, ...values) {
         const answer = await wire.request(["store", program, operation, ...values]);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/server",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "description": "The SDK used by a Program's server endpoint.",
   "type": "module",
   "main": "dist/main.js",
@@ -46,13 +46,13 @@
     "prepack": "node --run build"
   },
   "peerDependencies": {
-    "@phreshos/core": "^0.1.12"
+    "@phreshos/core": "^0.1.14"
   },
   "dependencies": {
     "@msgpack/msgpack": "^3.1.3"
   },
   "devDependencies": {
-    "@phreshos/core": "^0.1.13",
+    "@phreshos/core": "^0.1.14",
     "@types/node": "^26.2.0",
     "typescript": "^6.0.3"
   }