windows-development-sandbox 1.14.0 → 1.15.0

package/dist/selftest/support/live.js

@@ -98,6 +98,8 @@ export function startDaemon(t, f, options) {
         AGENT_DATA_DIR: data,
         AGENT_WORKSPACE: options.workspace,
         AGENT_LOCAL_DIR: f.at(path.basename(data) + '-local'),
+        // The daemon's live-folder state: a temp folder, never C:\ProgramData of the machine running the test.
+        AGENT_DAEMON_STATE_DIR: f.at(path.basename(data) + '-daemon-state'),
         AGENT_LOG_PREFIX: 'daemon',
         AGENT_NO_TABS: '1',
         ...options.env,

package/dist/shared/channel/index.d.ts

@@ -1,3 +1,4 @@
 export * from './schema.js';
 export * from './run-dir.js';
 export * from './secrets.js';
+export * from './live.js';

package/dist/shared/channel/index.js

@@ -1,3 +1,4 @@
 export * from './schema.js';
 export * from './run-dir.js';
 export * from './secrets.js';
+export * from './live.js';

package/dist/shared/channel/live.d.ts

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+/** This tool's vSMB share names: never the 64-hex names Windows Sandbox gives its own shares. */
+export declare const LIVE_SHARE_NAME: RegExp;
+/** A folder name under C:\Workspace: no dots or spaces, so no "..", "foo." or "foo " aliases of other folders. */
+export declare const LIVE_FOLDER_NAME: RegExp;
+export declare const LIVE_KEY: RegExp;
+export declare const LIVE_TOKEN: RegExp;
+/** How old (or how far in the future) a request may be, by the guest's clock. */
+export declare const LIVE_MAX_AGE_MS: number;
+export declare const LivePayloadSchema: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    kind: z.ZodEnum<{
+        map: "map";
+        canary: "canary";
+        unmap: "unmap";
+    }>;
+    id: z.ZodString;
+    launchId: z.ZodString;
+    share: z.ZodOptional<z.ZodString>;
+    folder: z.ZodString;
+    readOnly: z.ZodBoolean;
+    createdAt: z.ZodString;
+}, z.core.$strict>;
+export type LivePayload = z.output<typeof LivePayloadSchema>;
+export declare const LiveEnvelopeSchema: z.ZodObject<{
+    payload: z.ZodString;
+    mac: z.ZodString;
+}, z.core.$strict>;
+export type LiveEnvelope = z.output<typeof LiveEnvelopeSchema>;
+/** run\live-replies\<id>.json (guest-written: checked, capped; the host only ever compares the token). */
+export declare const LiveReplySchema: z.ZodObject<{
+    id: z.ZodString;
+    ok: z.ZodBoolean;
+    message: z.ZodString;
+    token: z.ZodOptional<z.ZodString>;
+    finishedAt: z.ZodString;
+}, z.core.$strict>;
+export type LiveReply = z.output<typeof LiveReplySchema>;
+/** A signed request for `payload` (host side). */
+export declare function signLive(key: string, payload: LivePayload): LiveEnvelope;
+/** Why a request is refused (guest side), or the payload it carries. */
+export declare function openLive(key: string | null, envelope: unknown, o: {
+    launchId: string;
+    now: number;
+}): {
+    payload: LivePayload;
+} | {
+    refused: string;
+};
+/** A new random share name (host side). */
+export declare function newShareName(): string;
+/** A new launch key (host side). */
+export declare function newLiveKey(): string;

package/dist/shared/channel/live.js

@@ -0,0 +1,92 @@
+// Live folders through HCS (opt-in alpha, docs/design/hcs-live-folders.md): the host -> guest messages that make a
+// folder the host shared into the running sandbox appear at C:\Workspace\<name>. Requests go in run\live, replies in
+// run\live-replies. Every request is signed: {payload: "<the JSON text>", mac: HMAC-SHA256(key, payload)}; the MAC is
+// over the exact payload text, never over a re-serialised object. The key is made per launch, travels to the sandbox
+// only in the one-shot secrets file (other users of a shared sandbox may write run\, never secrets\) and is kept on the
+// host sealed with DPAPI. The agent is an administrator in the sandbox, so it can read the key there: the signature
+// keeps other users and stale or replayed files from driving the daemon, and the real boundary is that only the host
+// decides what is shared (a guest can only show or hide what it was given).
+import crypto from 'node:crypto';
+import { z } from 'zod';
+import { IdSchema } from './schema.js';
+/** This tool's vSMB share names: never the 64-hex names Windows Sandbox gives its own shares. */
+export const LIVE_SHARE_NAME = /^agentsbx-[0-9a-f]{8,32}$/;
+/** A folder name under C:\Workspace: no dots or spaces, so no "..", "foo." or "foo " aliases of other folders. */
+export const LIVE_FOLDER_NAME = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+export const LIVE_KEY = /^[0-9a-f]{64}$/;
+export const LIVE_TOKEN = /^[0-9a-f]{32}$/;
+/** How old (or how far in the future) a request may be, by the guest's clock. */
+export const LIVE_MAX_AGE_MS = 2 * 60 * 1000;
+const MAX_PAYLOAD = 4096;
+export const LivePayloadSchema = z.strictObject({
+    v: z.literal(1),
+    /** canary: show the share, read token.txt, hide it again and reply with the token; map / unmap: the real folder. */
+    kind: z.enum(['canary', 'map', 'unmap']),
+    id: IdSchema,
+    launchId: z.string().min(1).max(64),
+    share: z.string().regex(LIVE_SHARE_NAME).optional(),
+    folder: z.string().regex(LIVE_FOLDER_NAME),
+    readOnly: z.boolean(),
+    createdAt: z.string().max(64),
+});
+export const LiveEnvelopeSchema = z.strictObject({
+    payload: z.string().min(2).max(MAX_PAYLOAD),
+    mac: z.string().regex(/^[0-9a-f]{64}$/),
+});
+/** run\live-replies\<id>.json (guest-written: checked, capped; the host only ever compares the token). */
+export const LiveReplySchema = z.strictObject({
+    id: IdSchema,
+    ok: z.boolean(),
+    message: z.string().max(1000),
+    token: z.string().regex(LIVE_TOKEN).optional(),
+    finishedAt: z.string().max(64),
+});
+function mac(key, payload) {
+    return crypto.createHmac('sha256', Buffer.from(key, 'hex')).update(payload, 'utf8').digest('hex');
+}
+/** A signed request for `payload` (host side). */
+export function signLive(key, payload) {
+    if (!LIVE_KEY.test(key))
+        throw new Error('not a live-folder key');
+    const text = JSON.stringify(LivePayloadSchema.parse(payload));
+    return { payload: text, mac: mac(key, text) };
+}
+/** Why a request is refused (guest side), or the payload it carries. */
+export function openLive(key, envelope, o) {
+    if (!key || !LIVE_KEY.test(key))
+        return { refused: 'no live-folder key (live folders were off when the sandbox started)' };
+    const env = LiveEnvelopeSchema.safeParse(envelope);
+    if (!env.success)
+        return { refused: 'not a live-folder request' };
+    const want = Buffer.from(mac(key, env.data.payload), 'hex');
+    const got = Buffer.from(env.data.mac, 'hex');
+    if (want.length !== got.length || !crypto.timingSafeEqual(want, got))
+        return { refused: 'the signature does not match' };
+    let json;
+    try {
+        json = JSON.parse(env.data.payload);
+    }
+    catch {
+        return { refused: 'the signed payload is not JSON' };
+    }
+    const parsed = LivePayloadSchema.safeParse(json);
+    if (!parsed.success)
+        return { refused: 'the signed payload has the wrong shape' };
+    const p = parsed.data;
+    if (p.launchId !== o.launchId)
+        return { refused: 'it is for another launch' };
+    const at = Date.parse(p.createdAt);
+    if (!Number.isFinite(at) || Math.abs(o.now - at) > LIVE_MAX_AGE_MS)
+        return { refused: 'it is too old' };
+    if (p.kind !== 'unmap' && !p.share)
+        return { refused: 'it names no share' };
+    return { payload: p };
+}
+/** A new random share name (host side). */
+export function newShareName() {
+    return 'agentsbx-' + crypto.randomBytes(8).toString('hex');
+}
+/** A new launch key (host side). */
+export function newLiveKey() {
+    return crypto.randomBytes(32).toString('hex');
+}

package/dist/shared/channel/run-dir.d.ts

@@ -24,7 +24,12 @@ export declare class RunDir {
     readonly treesDir: string;
     /** One-shot secrets the host hands over (see secrets.ts). Next to run, not in it: shared-use users can change run. */
     readonly secretsDir: string;
+    /** Live folders (live.ts): signed host requests, and the daemon's replies. */
+    readonly liveDir: string;
+    readonly liveRepliesDir: string;
     constructor(dataDir: string);
+    liveFile(id: string): string;
+    liveReplyFile(id: string): string;
     requestFile(id: string): string;
     responseFile(id: string): string;
     sessionFile(id: string): string;

package/dist/shared/channel/run-dir.js

@@ -51,6 +51,9 @@ export class RunDir {
     treesDir;
     /** One-shot secrets the host hands over (see secrets.ts). Next to run, not in it: shared-use users can change run. */
     secretsDir;
+    /** Live folders (live.ts): signed host requests, and the daemon's replies. */
+    liveDir;
+    liveRepliesDir;
     constructor(dataDir) {
         this.root = path.join(dataDir, 'run');
         this.sandboxFile = path.join(this.root, 'sandbox.json');
@@ -64,6 +67,14 @@ export class RunDir {
         this.auditDir = path.join(this.root, 'audit');
         this.treesDir = path.join(this.root, 'trees');
         this.secretsDir = path.join(dataDir, 'secrets');
+        this.liveDir = path.join(this.root, 'live');
+        this.liveRepliesDir = path.join(this.root, 'live-replies');
+    }
+    liveFile(id) {
+        return path.join(this.liveDir, safeId(id) + '.json');
+    }
+    liveReplyFile(id) {
+        return path.join(this.liveRepliesDir, safeId(id) + '.json');
     }
     requestFile(id) {
         return path.join(this.requestsDir, safeId(id) + '.json');

package/dist/shared/channel/secrets.d.ts

@@ -10,6 +10,7 @@ export declare const SecretsFileSchema: z.ZodObject<{
     }, z.core.$strict>>;
     wireguardConfig: z.ZodOptional<z.ZodString>;
     githubToken: z.ZodOptional<z.ZodString>;
+    liveFoldersKey: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 export type SecretsFile = z.output<typeof SecretsFileSchema>;
 interface WithHarnesses {

package/dist/shared/channel/secrets.js

@@ -28,6 +28,11 @@ export const SecretsFileSchema = z.strictObject({
         .optional(),
     /** The GitHub token you saved for sandboxes (github.shareToken), only with git access "full". */
     githubToken: GithubTokenSchema.optional(),
+    /** projects.liveFolders "hcs": this launch's key for signed live-folder requests (live.ts). */
+    liveFoldersKey: z
+        .string()
+        .regex(/^[0-9a-f]{64}$/)
+        .optional(),
 });
 /** The environment a harness gets: its own, then the values that travelled in the secrets file. */
 const withEnvironment = (harness, environment) => (environment ? { ...harness, environment: { ...harness.environment, ...environment } } : harness);

package/dist/shared/paths/projects.d.ts

@@ -11,7 +11,7 @@ export declare const WORKSPACES_GUEST = "C:\\Workspace";
  */
 export declare function autoGuestFolder(hostDir: string): string;
 /** How a project got into the sandbox. */
-export type Mechanism = 'launch' | 'root' | 'boot' | 'wsb';
+export type Mechanism = 'launch' | 'root' | 'boot' | 'wsb' | 'hcs';
 /** One project the running sandbox works on. */
 export interface ProjectEntry {
     name: string;
@@ -65,6 +65,11 @@ export declare function usableRoots(roots: string[], exists: (dir: string) => bo
  * when the sandbox can show it there, else C:\Workspace\<name>. -2, -3, ... when that overlaps a folder in `taken`.
  */
 export declare function ownGuestFolder(hostDir: string, mirror: boolean, taken?: string[]): string;
+/**
+ * Where a live folder (projects.liveFolders "hcs") appears: C:\Workspace\<name>, the name in the strict form the guest
+ * daemon accepts (lower-case letters, digits, '-' and '_'; no dots or spaces), -2, -3, ... when it overlaps `taken`.
+ */
+export declare function liveGuestFolder(hostDir: string, taken?: string[]): string;
 /**
  * Guest folders for the project roots (C:\Projects\<name>, unique; with guestWorkspace "mirror" at its PC path when
  * the sandbox can show it there) and the projects mapped at boot (ownGuestFolder, unique against `taken` and each

package/dist/shared/paths/projects.js

@@ -4,7 +4,8 @@
 //  - a folder inside a project root (projects.roots: whole folders of projects, mapped at every start), including
 //    projects created after boot;
 //  - projects mapped at boot because they were in use when the sandbox was restarted to add them;
-//  - a folder shared into the running sandbox with `wsb share` (Windows 11 24H2+, untested).
+//  - a folder shared into the running sandbox with `wsb share` (Windows 11 24H2+, untested);
+//  - a folder shared into the running sandbox through HCS (projects.liveFolders "hcs", alpha, untested on a PC).
 // A project is at the same place inside the sandbox whichever project started it (git worktrees and Claude's project
 // folders store absolute paths):
 //  - a project inside a root is always under the root's folder, C:\Projects\<root>\<name> (also as the launch folder);
@@ -115,6 +116,25 @@ export function ownGuestFolder(hostDir, mirror, taken = []) {
         if (free(base + '-' + i))
             return base + '-' + i;
 }
+/**
+ * Where a live folder (projects.liveFolders "hcs") appears: C:\Workspace\<name>, the name in the strict form the guest
+ * daemon accepts (lower-case letters, digits, '-' and '_'; no dots or spaces), -2, -3, ... when it overlaps `taken`.
+ */
+export function liveGuestFolder(hostDir, taken = []) {
+    const base = path.win32
+        .basename(resolveDir(hostDir))
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, '-')
+        .replace(/^[-_]+|-+$/g, '')
+        .slice(0, 56) || 'project';
+    const free = (guest) => !taken.some((t) => isWithin(t, guest) || isWithin(guest, t));
+    const at = (name) => WORKSPACES_GUEST + '\\' + name;
+    if (free(at(base)))
+        return at(base);
+    for (let i = 2;; i++)
+        if (free(at(base + '-' + i)))
+            return at(base + '-' + i);
+}
 /**
  * Guest folders for the project roots (C:\Projects\<name>, unique; with guestWorkspace "mirror" at its PC path when
  * the sandbox can show it there) and the projects mapped at boot (ownGuestFolder, unique against `taken` and each

package/dist/sync/watcher.js

@@ -18,6 +18,7 @@ import { SandboxChannel } from '../host/channel/index.js';
 import { ProjectRegistry } from '../host/projects/registry.js';
 import { ContainedStorage, setNameOf, storageOf } from '../host/storage/index.js';
 import { clearSecrets } from '../host/secrets/index.js';
+import { clearLiveRecord } from '../host/engines/index.js';
 import { endSharing, sharingDeps } from '../host/sharing/index.js';
 import { PACKAGE_ROOT } from '../core/package-info.js';
 import { syncBack } from './sync-cycle.js';
@@ -373,6 +374,14 @@ export class Watcher {
         catch (e) {
             this.note('could not remove the one-shot secrets: ' + errMsg(e));
         }
+        // Live folders (HCS): their shares ended with the sandbox, so their record and key go too.
+        try {
+            if (!isSandboxRunning() && clearLiveRecord(this.storageRoot, this.dataPath))
+                this.note('live folders: record cleared');
+        }
+        catch (e) {
+            this.note('could not clear the live-folder record: ' + errMsg(e));
+        }
         // An all-users install: the record of whose sandbox this was goes, and the group loses access to the folders.
         const sharing = sharingDeps(PACKAGE_ROOT);
         if (sharing)

package/dist/web/index.html

@@ -6,7 +6,7 @@
     <title>Sandbox</title>
     <link rel="icon" href="data:," />
     <link rel="stylesheet" href="/main-UAQPI5XD.css" />
-    <script type="module" src="/main-6XNBTJLT.js"></script>
+    <script type="module" src="/main-7DJZ2M27.js"></script>
   </head>
   <body>
     <div id="root"></div>