@modelprofile.com/browser-runtime 5.7.2 → 6.0.0

package/ts/classes.runtimeownership.ts

@@ -6,6 +6,8 @@ const metadataSchema = 1;
 const maximumMetadataBytes = 4096;
 const maximumProcFileBytes = 2 * 1024 * 1024;
 const anchorInitializationAttempts = 200;
+const emptyCommandAttempts = 5;
+const emptyCommandRetryDelayMs = 50;
 const generationIdPattern = /^[A-Za-z0-9_-]{32}$/u;
 const hashPattern = /^[a-f0-9]{64}$/u;
 const bootIdPattern = /^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/u;
@@ -59,7 +61,26 @@ export interface IBrowserRuntimeGeneration {
 }
 
 type TInspectionResult = 'clear' | 'held' | 'indeterminate';
-type TProcessUidState = 'same' | 'other' | 'missing' | 'indeterminate';
+/**
+ * `same` is every one of the four `/proc/<pid>/status` `Uid:` identifiers, `other` is none of
+ * them, and `shared` is a setuid credential transition that names this uid in some but not all
+ * of them (`sudo`, `su`, `passwd`, a daemon that assumed this identity). A `shared` process can
+ * still open this uid's profile, so it is a scan candidate; it is never a whole-scan fence.
+ */
+type TProcessUidState = 'same' | 'other' | 'shared' | 'missing' | 'indeterminate';
+type TEmptyCommandResolution =
+  | { kind: 'clear' }
+  | { kind: 'indeterminate' }
+  | { kind: 'command'; cmdline: plugins.Buffer };
+
+/**
+ * Waits for one bounded retry step. The timer is referenced for its whole lifetime and always
+ * fires, so it is released as soon as the step ends and never outlives the acquisition it
+ * belongs to. An unreferenced timer would let the process exit in the middle of an inspection.
+ */
+const delayStep = (millisecondsArg: number): Promise<void> => new Promise<void>((resolve) => {
+  setTimeout(resolve, millisecondsArg);
+});
 
 const isMissingError = (errorArg: unknown): boolean => (
   (errorArg as NodeJS.ErrnoException).code === 'ENOENT'
@@ -1085,9 +1106,13 @@ export class BrowserRuntimeOwnership {
   }
 
   private async inspectProfileProcesses(profileRootsArg: string[]): Promise<TInspectionResult> {
-    const roots = profileRootsArg.map((root) => plugins.path.resolve(root));
+    const roots = await this.presentProfileRoots(profileRootsArg);
+    // The inspection exists only to protect a profile root that is about to be removed. When no
+    // root is present there is nothing to protect and no containment match is possible, so the
+    // process table is never enumerated.
+    if (roots.length === 0) return 'clear';
     let indeterminate = false;
-    for (const pid of await this.listOwnedProcessIds()) {
+    for (const pid of await this.listCandidateProcessIds()) {
       let cmdline: plugins.Buffer;
       try {
         cmdline = await this.readBoundedBuffer(
@@ -1095,6 +1120,8 @@ export class BrowserRuntimeOwnership {
           maximumProcFileBytes,
         );
       } catch {
+        // A candidate whose command line cannot be read stays fail-closed: its identity is known
+        // to involve this uid and nothing proves it is not using one of these profile roots.
         const uidState = await this.processStillExists(pid);
         if (uidState === 'missing' || uidState === 'other') continue;
         indeterminate = true;
@@ -1102,37 +1129,66 @@ export class BrowserRuntimeOwnership {
       }
       if (cmdline.byteLength === 0) {
         await this.afterEmptyProcessCmdline?.(pid);
-        if (!await this.emptyCommandProcessIsClear(pid)) indeterminate = true;
-        continue;
-      }
-      let cmdlineText: string;
-      try {
-        cmdlineText = new TextDecoder('utf-8', { fatal: true }).decode(cmdline);
-      } catch {
-        indeterminate = true;
-        continue;
-      }
-      const argumentsList = cmdlineText.split('\0');
-      if (argumentsList.at(-1) === '') argumentsList.pop();
-      for (let index = 0; index < argumentsList.length; index += 1) {
-        const argument = argumentsList[index]!;
-        let profilePath: string | undefined;
-        if (argument === '--user-data-dir') {
-          profilePath = argumentsList[index + 1];
-        } else if (argument.startsWith('--user-data-dir=')) {
-          profilePath = argument.slice('--user-data-dir='.length);
-        }
-        if (!profilePath || !plugins.path.isAbsolute(profilePath)) continue;
-        const resolved = plugins.path.resolve(profilePath);
-        if (roots.some((root) => resolved === root || this.pathIsWithin(root, resolved))) {
-          return 'held';
+        const resolution = await this.resolveEmptyCommandProcess(pid);
+        if (resolution.kind === 'clear') continue;
+        if (resolution.kind === 'indeterminate') {
+          indeterminate = true;
+          continue;
         }
+        cmdline = resolution.cmdline;
       }
+      const containment = this.commandLineContainment(cmdline, roots);
+      if (containment === 'held') return 'held';
+      if (containment === 'indeterminate') indeterminate = true;
     }
     return indeterminate ? 'indeterminate' : 'clear';
   }
 
-  private async listOwnedProcessIds(): Promise<number[]> {
+  private commandLineContainment(
+    cmdlineArg: plugins.Buffer,
+    rootsArg: string[],
+  ): TInspectionResult {
+    let cmdlineText: string;
+    try {
+      cmdlineText = new TextDecoder('utf-8', { fatal: true }).decode(cmdlineArg);
+    } catch {
+      return 'indeterminate';
+    }
+    const argumentsList = cmdlineText.split('\0');
+    if (argumentsList.at(-1) === '') argumentsList.pop();
+    for (let index = 0; index < argumentsList.length; index += 1) {
+      const argument = argumentsList[index]!;
+      let profilePath: string | undefined;
+      if (argument === '--user-data-dir') {
+        profilePath = argumentsList[index + 1];
+      } else if (argument.startsWith('--user-data-dir=')) {
+        profilePath = argument.slice('--user-data-dir='.length);
+      }
+      if (!profilePath || !plugins.path.isAbsolute(profilePath)) continue;
+      const resolved = plugins.path.resolve(profilePath);
+      if (rootsArg.some((root) => resolved === root || this.pathIsWithin(root, resolved))) {
+        return 'held';
+      }
+    }
+    return 'clear';
+  }
+
+  private async presentProfileRoots(profileRootsArg: string[]): Promise<string[]> {
+    const roots: string[] = [];
+    for (const profileRoot of profileRootsArg) {
+      const root = plugins.path.resolve(profileRoot);
+      try {
+        await plugins.fsPromises.lstat(root, { bigint: true });
+      } catch (error) {
+        if (isMissingError(error)) continue;
+        throw new BrowserRuntimeError('FENCED', 'runtime profile root is unreadable');
+      }
+      roots.push(root);
+    }
+    return roots;
+  }
+
+  private async listCandidateProcessIds(): Promise<number[]> {
     let entries: string[];
     try {
       // /proc can report DT_UNKNOWN. Node's eager Dirent conversion then
@@ -1161,8 +1217,11 @@ export class BrowserRuntimeOwnership {
         indeterminate = true;
         continue;
       }
+      // A credential state alone never fences the scan. An unrelated process is discarded here
+      // only when it definitely belongs to another uid; every process this uid owns or shares is
+      // a candidate whose command line decides it in inspectProfileProcesses().
       const uidState = await this.processStillExists(pid);
-      if (uidState === 'same') processIds.push(pid);
+      if (uidState === 'same' || uidState === 'shared') processIds.push(pid);
       else if (uidState === 'indeterminate') indeterminate = true;
     }
     if (indeterminate) {
@@ -1208,31 +1267,63 @@ export class BrowserRuntimeOwnership {
     }
     if (ids.every((id) => id === this.uid)) return 'same';
     if (ids.every((id) => id !== this.uid)) return 'other';
-    return 'indeterminate';
+    return 'shared';
   }
 
-  private async emptyCommandProcessIsClear(pidArg: number): Promise<boolean> {
+  /**
+   * An empty `/proc/<pid>/cmdline` is not a decision. A candidate publishes one for a bounded
+   * window while it is mid-`execve` or has already released its mm on the way to becoming a
+   * zombie, and during that window `State:` still reports a running process. Re-read the
+   * identity and the command line across that window before deciding anything.
+   */
+  private async resolveEmptyCommandProcess(pidArg: number): Promise<TEmptyCommandResolution> {
     const processPath = plugins.path.join(this.procRoot, String(pidArg));
-    try {
-      const status = await this.readBoundedFile(
-        plugins.path.join(processPath, 'status'),
-        64 * 1024,
-      );
+    for (let attempt = 0; attempt < emptyCommandAttempts; attempt += 1) {
+      let status: string;
+      try {
+        status = await this.readBoundedFile(
+          plugins.path.join(processPath, 'status'),
+          64 * 1024,
+        );
+      } catch (error) {
+        return await this.departedProcessResolution(processPath, error);
+      }
       const uidState = this.parseProcessUidState(status);
-      if (uidState === 'other') return true;
-      if (uidState !== 'same') return false;
+      if (uidState === 'other') return { kind: 'clear' };
+      if (uidState !== 'same' && uidState !== 'shared') return { kind: 'indeterminate' };
       const stateLines = status.split('\n').filter((line) => line.startsWith('State:'));
-      return stateLines.length === 1 && /^State:[\t ]+Z(?:[\t ]|$)/u.test(stateLines[0]!);
-    } catch (error) {
-      if (!isMissingError(error)) return false;
-      // An empty command line can precede process exit. A missing status file
-      // alone is insufficient: the PID directory must also have disappeared.
+      if (stateLines.length !== 1) return { kind: 'indeterminate' };
+      // A zombie has released its mm, holds no descriptor and cannot be using any profile root.
+      if (/^State:[\t ]+Z(?:[\t ]|$)/u.test(stateLines[0]!)) return { kind: 'clear' };
+      let cmdline: plugins.Buffer;
       try {
-        await plugins.fsPromises.lstat(processPath, { bigint: true });
-        return false;
-      } catch (statError) {
-        return isMissingError(statError);
+        cmdline = await this.readBoundedBuffer(
+          plugins.path.join(processPath, 'cmdline'),
+          maximumProcFileBytes,
+        );
+      } catch (error) {
+        return await this.departedProcessResolution(processPath, error);
       }
+      if (cmdline.byteLength > 0) return { kind: 'command', cmdline };
+      if (attempt + 1 < emptyCommandAttempts) await delayStep(emptyCommandRetryDelayMs);
+    }
+    // Still running and still command-less after the whole window. Nothing proves this process is
+    // not using one of the inspected roots, so it stays fail-closed.
+    return { kind: 'indeterminate' };
+  }
+
+  private async departedProcessResolution(
+    processPathArg: string,
+    errorArg: unknown,
+  ): Promise<TEmptyCommandResolution> {
+    if (!isMissingError(errorArg)) return { kind: 'indeterminate' };
+    // A missing status or command-line file alone is insufficient: the PID directory must also
+    // have disappeared before the process counts as departed.
+    try {
+      await plugins.fsPromises.lstat(processPathArg, { bigint: true });
+      return { kind: 'indeterminate' };
+    } catch (statError) {
+      return isMissingError(statError) ? { kind: 'clear' } : { kind: 'indeterminate' };
     }
   }
 

package/ts/interfaces.ts

@@ -31,7 +31,11 @@ export interface IBrowserResourceKey {
 export interface IBrowserAttachmentBinding {
   attachmentAuthorityId: string;
   attachmentRevision: number;
-  sessionId: TQualifiedBrowserSessionId | null;
+  /**
+   * The set of sessions attached to the resource. Order is not significant and duplicates are
+   * rejected. An empty set is detached, and revision `0` requires an empty set.
+   */
+  sessionIds: TQualifiedBrowserSessionId[];
 }
 
 export interface ICreateBrowserResourceRequest {

package/ts/plugins.ts

@@ -16,12 +16,12 @@ export { Buffer, crypto, dns, fs, fsPromises, http, net, os, path, stream, tls,
 
 // foss.global scopes
 import * as flexharness from '@modelprofile.com/flexharness';
-import * as smartagent from '@push.rocks/smartagent';
+import * as flexharnessTools from '@modelprofile.com/flexharness/tools';
 import * as smartipc from '@push.rocks/smartipc';
 import * as smartmcp from '@push.rocks/smartmcp';
 import * as smartpuppeteer from '@push.rocks/smartpuppeteer';
 
-export { flexharness, smartagent, smartipc, smartmcp, smartpuppeteer };
+export { flexharness, flexharnessTools, smartipc, smartmcp, smartpuppeteer };
 
 // third-party scope
 import ipaddr from 'ipaddr.js';

package/.smartconfig.json

@@ -1,34 +0,0 @@
-{
-  "@git.zone/cli": {
-    "schemaVersion": 2,
-    "projectType": "npm",
-    "module": {
-      "githost": "code.foss.global",
-      "gitscope": "modelprofile.com",
-      "gitrepo": "browser-runtime",
-      "description": "Parent-owned, resource-centric Chromium runtime with revisioned attachment fencing, authenticated human and agent control, fail-closed egress, bounded artifacts, and Flex/MCP adapters.",
-      "npmPackagename": "@modelprofile.com/browser-runtime",
-      "license": "MIT",
-      "projectDomain": "modelprofile.com"
-    },
-    "release": {
-      "targets": {
-        "git": {
-          "enabled": true,
-          "remote": "origin",
-          "pushBranch": true,
-          "pushTags": true
-        },
-        "npm": {
-          "enabled": true,
-          "registries": [
-            "https://verdaccio.lossless.digital",
-            "https://registry.npmjs.org"
-          ],
-          "accessLevel": "public",
-          "alreadyPublished": "success"
-        }
-      }
-    }
-  }
-}