@evomap/evolver-adapter-public 2.0.0-beta.19 → 2.0.0-beta.22

package/dist/antiAbuseTelemetry.js

@@ -99,6 +99,7 @@ export function collectIntegrityHashes(packageRoot = resolveAdapterPackageRoot()
 export function buildHeartbeatAntiAbuseTelemetry(opts = {}) {
     const env = opts.env ?? process.env;
     const fp = opts.envFingerprint ?? bootstrap.captureEnvFingerprint({ env });
+    const evolverVersion = bootstrap.normalizeEvolverVersion(Object.hasOwn(opts, 'evolverVersion') ? opts.evolverVersion : fp.evolver_version);
     const salt = opts.salt ?? env['EVOLVER_ANTI_ABUSE_SALT'];
     const saltId = opts.saltId ?? env['EVOLVER_ANTI_ABUSE_SALT_ID'] ?? (salt ? 'env' : null);
     const pseudonymStatus = salt ? 'salt_configured' : 'salt_missing';
@@ -159,7 +160,7 @@ export function buildHeartbeatAntiAbuseTelemetry(opts = {}) {
             // AUTHORITATIVE per-asset model lives on the capsule (threaded from input.model), so 'unknown' on a heartbeat
             // is "this node didn't say", never a contradiction of a capsule's real model.
             model: fp.model,
-            evolver_version: opts.evolverVersion ?? null,
+            evolver_version: evolverVersion ?? null,
             client: '@evomap/evolver-adapter-public',
             client_version: null,
             region: fp.region ?? null,

package/dist/auth/credentialStore.d.ts

@@ -1,4 +1,4 @@
-import { linkSync } from 'node:fs';
+import { linkSync, renameSync } from 'node:fs';
 import type { hub } from '@evomap/evolver-core';
 export interface CredentialStoreOptions {
     /**
@@ -15,6 +15,8 @@ export interface CredentialStoreOptions {
     windowsParentStateReader?: (path: string) => readonly PathSecurityState[];
     /** Injectable filesystem primitive for deterministic no-clobber publication tests. */
     linkFile?: typeof linkSync;
+    /** Injectable filesystem primitive for deterministic atomic replacement tests. */
+    renameFile?: typeof renameSync;
 }
 export interface WindowsCredentialAclOps {
     assertTrustedParent(path: string, strictCreate: boolean): void;
@@ -24,7 +26,7 @@ export interface WindowsCredentialAclOps {
     secureFile(path: string): void;
 }
 export declare class CredentialStoreError extends Error {
-    constructor(message: string);
+    constructor(message: string, options?: ErrorOptions);
 }
 interface FileIdentity {
     dev: bigint;
@@ -44,6 +46,7 @@ export declare class CredentialStore {
     private readonly darwinAclReader;
     private readonly windowsParentStateReader;
     private readonly linkFile;
+    private readonly renameFile;
     private securedDirectoryState;
     private securedCredentialState;
     private readonly securedAncestorStates;

package/dist/auth/credentialStore.js

@@ -2,11 +2,12 @@ import { randomBytes } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
 import { constants, closeSync, fchmodSync, fstatSync, fsyncSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
 import { basename, dirname, resolve, win32 } from 'node:path';
+import { POWERSHELL_STDIN_SCRIPT_COMMAND, windowsAclFailureDetail, } from './windowsPowerShell.js';
 const DIRECTORY_MODE = 0o700;
 const FILE_MODE = 0o600;
 export class CredentialStoreError extends Error {
-    constructor(message) {
-        super(`Unsafe credential path: ${message}`);
+    constructor(message, options) {
+        super(`Unsafe credential path: ${message}`, options);
         this.name = 'CredentialStoreError';
     }
 }
@@ -18,6 +19,7 @@ export class CredentialStore {
     darwinAclReader;
     windowsParentStateReader;
     linkFile;
+    renameFile;
     // ctime detects in-place ACL drift while dev/ino detects entry replacement.
     securedDirectoryState = null;
     securedCredentialState = null;
@@ -32,6 +34,7 @@ export class CredentialStore {
         this.darwinAclReader = options.darwinAclReader ?? readDarwinAcl;
         this.windowsParentStateReader = options.windowsParentStateReader ?? parentSecurityStates;
         this.linkFile = options.linkFile ?? linkSync;
+        this.renameFile = options.renameFile ?? renameSync;
     }
     load() {
         if (!this.prepareDirectory(false))
@@ -152,7 +155,7 @@ export class CredentialStore {
             this.assertDirectoryIdentity(directory, directoryIdentity);
             if (replaceExisting) {
                 this.assertSafeDestination();
-                renameSync(temporaryPath, this.path);
+                this.renameFile(temporaryPath, this.path);
             }
             else if (!this.publishIfAbsent(temporaryPath)) {
                 const incumbentFd = this.openCredentialFile();
@@ -392,8 +395,8 @@ export class CredentialStore {
             try {
                 this.windowsAclOps.assertTrustedFile(this.path);
             }
-            catch {
-                throw new CredentialStoreError('Windows credential file ACL is not trusted');
+            catch (cause) {
+                throw windowsCredentialStoreError('Windows credential file ACL is not trusted', cause);
             }
             const pathStat = bigLstat(this.path);
             const fdStat = bigFstat(fd);
@@ -511,8 +514,8 @@ export class CredentialStore {
         try {
             this.windowsAclOps.secureDirectory(path);
         }
-        catch {
-            throw new CredentialStoreError('Windows directory ACL could not be secured');
+        catch (cause) {
+            throw windowsCredentialStoreError('Windows directory ACL could not be secured', cause);
         }
         const after = bigLstat(path);
         if (after.isSymbolicLink() || !after.isDirectory() || !sameIdentity(after, identity)) {
@@ -532,8 +535,8 @@ export class CredentialStore {
         try {
             this.windowsAclOps.assertTrustedFile(path);
         }
-        catch {
-            throw new CredentialStoreError('Windows credential file ACL is not trusted');
+        catch (cause) {
+            throw windowsCredentialStoreError('Windows credential file ACL is not trusted', cause);
         }
         if (isCredentialPath && this.securedCredentialState &&
             sameSecurityState(this.securedCredentialState, before))
@@ -541,8 +544,8 @@ export class CredentialStore {
         try {
             this.windowsAclOps.secureFile(path);
         }
-        catch {
-            throw new CredentialStoreError('Windows file ACL could not be secured');
+        catch (cause) {
+            throw windowsCredentialStoreError('Windows file ACL could not be secured', cause);
         }
         const pathStat = bigLstat(path);
         const fdStat = bigFstat(fd);
@@ -595,7 +598,8 @@ export class CredentialStore {
                 throw new CredentialStoreError(`ancestor directory ${path} changed during ACL validation`);
             }
             for (let attempt = 0; attempt < 5; attempt += 1) {
-                const initialState = securityStateOf(bigFstat(fd));
+                const initialMetadata = bigFstat(fd);
+                const initialState = securityStateOf(initialMetadata);
                 let output;
                 try {
                     output = this.darwinAclReader(path);
@@ -612,12 +616,33 @@ export class CredentialStore {
                     !sameIdentity(after, identity) || !sameIdentity(openedAfter, identity)) {
                     throw new CredentialStoreError(`ancestor directory ${path} changed during ACL validation`);
                 }
-                const metadataStable = sameSecurityState(initialState, after) &&
-                    sameSecurityState(initialState, openedAfter);
-                if (metadataStable) {
+                if (sameSecurityState(initialState, after) && sameSecurityState(initialState, openedAfter)) {
                     this.securedAncestorStates.set(path, securityStateOf(openedAfter));
                     return;
                 }
+                if (sameDarwinAncestorMetadata(initialMetadata, after)
+                    && sameDarwinAncestorMetadata(initialMetadata, openedAfter)) {
+                    let confirmedOutput;
+                    try {
+                        confirmedOutput = this.darwinAclReader(path);
+                    }
+                    catch {
+                        throw new CredentialStoreError(`ancestor directory ${path} ACL could not be inspected`);
+                    }
+                    if (hasUnsafeDarwinAllowAcl(confirmedOutput, rejectAnyAllow)) {
+                        throw new CredentialStoreError(`ancestor directory ${path} grants access through an extended ACL`);
+                    }
+                    const confirmedPath = bigLstat(path);
+                    const confirmedOpened = bigFstat(fd);
+                    if (confirmedOutput === output
+                        && !confirmedPath.isSymbolicLink()
+                        && confirmedPath.isDirectory()
+                        && sameDarwinAncestorMetadata(initialMetadata, confirmedPath)
+                        && sameDarwinAncestorMetadata(initialMetadata, confirmedOpened)) {
+                        this.securedAncestorStates.set(path, securityStateOf(confirmedOpened));
+                        return;
+                    }
+                }
             }
             throw new CredentialStoreError(`ancestor directory ${path} changed during ACL validation`);
         }
@@ -667,16 +692,58 @@ export class CredentialStore {
                 this.trustedWindowsParentStates.set(cacheKey, after);
             }
         }
-        catch {
-            throw new CredentialStoreError('Windows parent directory chain is not trusted');
+        catch (cause) {
+            throw windowsCredentialStoreError('Windows parent directory chain is not trusted', cause);
         }
     }
     isPosix() {
         return this.platform !== 'win32';
     }
 }
+function windowsCredentialStoreError(message, cause) {
+    const detail = cause instanceof Error ? windowsAclFailureDetail(cause) : '';
+    return new CredentialStoreError(detail ? `${message} (${detail})` : message, { cause });
+}
 const WINDOWS_ACL_SCRIPT = String.raw `
 $ErrorActionPreference = 'Stop'
+# Progress records can be serialized as CLIXML onto redirected stderr and
+# obscure the actual failure. Suppress them so stderr carries only real errors.
+$ProgressPreference = 'SilentlyContinue'
+
+function ConvertTo-OneLineAclDiagnostic([object]$Value) {
+  if ($null -eq $Value) { return '' }
+  return ([string]$Value -replace '[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]+', ' ').Trim()
+}
+
+function Throw-CredentialAclFailure(
+  [string]$Reason,
+  [string]$Path = '',
+  [string]$Sid = '',
+  [object]$Rights = $null,
+  [string]$Principal = ''
+) {
+  $parts = @($Reason)
+  $safePath = ConvertTo-OneLineAclDiagnostic $Path
+  $safeSid = ConvertTo-OneLineAclDiagnostic $Sid
+  $safeRights = ConvertTo-OneLineAclDiagnostic $Rights
+  $safePrincipal = ConvertTo-OneLineAclDiagnostic $Principal
+  if (-not [string]::IsNullOrWhiteSpace($safePath)) { $parts += ('path=' + $safePath) }
+  if (-not [string]::IsNullOrWhiteSpace($safeSid)) { $parts += ('sid=' + $safeSid) }
+  if (-not [string]::IsNullOrWhiteSpace($safePrincipal)) { $parts += ('principal=' + $safePrincipal) }
+  if (-not [string]::IsNullOrWhiteSpace($safeRights)) { $parts += ('rights=' + $safeRights) }
+  throw ($parts -join '; ')
+}
+
+# Windows PowerShell can serialize ordinary error-stream writes as CLIXML when
+# stderr is redirected. Write the terminating exception directly to native stderr so
+# Node receives the actionable message rather than only a serialized record.
+trap {
+  $message = ConvertTo-OneLineAclDiagnostic $_.Exception.Message
+  if ([string]::IsNullOrWhiteSpace($message)) { $message = 'Credential ACL check failed' }
+  [Console]::Error.WriteLine($message)
+  exit 1
+}
+
 $Target = [Environment]::GetEnvironmentVariable('EVOMAP_CREDENTIAL_ACL_TARGET', 'Process')
 $Kind = [Environment]::GetEnvironmentVariable('EVOMAP_CREDENTIAL_ACL_KIND', 'Process')
 if ([string]::IsNullOrEmpty($Target) -or
@@ -711,10 +778,10 @@ function Assert-TrustedParent([string]$ParentPath, [bool]$StrictCreate) {
   $full = [System.IO.Path]::GetFullPath($ParentPath)
   $root = [System.IO.Path]::GetPathRoot($full)
   if ([string]::IsNullOrEmpty($root) -or $root -notmatch '^[A-Za-z]:\\$') {
-    throw 'Credential parent must be on a local drive'
+    Throw-CredentialAclFailure -Reason 'Credential parent must be on a local drive' -Path $full
   }
   if ([System.IO.DriveInfo]::new($root).DriveType -ne [System.IO.DriveType]::Fixed) {
-    throw 'Credential parent must be on a fixed local drive'
+    Throw-CredentialAclFailure -Reason 'Credential parent must be on a fixed local drive' -Path $full
   }
   $current = $root
   $relative = $full.Substring($root.Length)
@@ -741,12 +808,12 @@ function Assert-TrustedParent([string]$ParentPath, [bool]$StrictCreate) {
     $item = Get-Item -LiteralPath $current -Force
     if (-not $item.PSIsContainer -or
         (($item.Attributes -band [System.IO.FileAttributes]::ReparsePoint) -ne 0)) {
-      throw 'Credential parent contains a reparse point or non-directory'
+      Throw-CredentialAclFailure -Reason 'Credential parent contains a reparse point or non-directory' -Path $current
     }
     $parentAcl = Get-Acl -LiteralPath $current
     $ownerSid = $parentAcl.GetOwner([System.Security.Principal.SecurityIdentifier])
     if ($trustedSids -notcontains $ownerSid.Value) {
-      throw 'Credential parent has an untrusted owner'
+      Throw-CredentialAclFailure -Reason 'Credential parent has an untrusted owner' -Path $current -Sid $ownerSid.Value
     }
     foreach ($parentRule in @($parentAcl.Access)) {
       if ($parentRule.AccessControlType -ne [System.Security.AccessControl.AccessControlType]::Allow) {
@@ -783,10 +850,10 @@ function Assert-TrustedParent([string]$ParentPath, [bool]$StrictCreate) {
           [System.Security.Principal.SecurityIdentifier]
         )
       } catch {
-        throw 'Credential parent contains an unresolvable write principal'
+        Throw-CredentialAclFailure -Reason 'Credential parent contains an unresolvable write principal' -Path $current -Principal $parentRule.IdentityReference.Value -Rights $rights
       }
       if ($trustedSids -notcontains $parentRuleSid.Value) {
-        throw 'Credential parent grants write access to an untrusted principal'
+        Throw-CredentialAclFailure -Reason 'Credential parent grants write access to an untrusted principal' -Path $current -Sid $parentRuleSid.Value -Rights $rights
       }
     }
   }
@@ -796,12 +863,12 @@ function Assert-TrustedFile([string]$FilePath) {
   $item = Get-Item -LiteralPath $FilePath -Force
   if ($item.PSIsContainer -or
       (($item.Attributes -band [System.IO.FileAttributes]::ReparsePoint) -ne 0)) {
-    throw 'Credential file is a reparse point or not a regular file'
+    Throw-CredentialAclFailure -Reason 'Credential file is a reparse point or not a regular file' -Path $FilePath
   }
   $fileAcl = Get-Acl -LiteralPath $FilePath
   $ownerSid = $fileAcl.GetOwner([System.Security.Principal.SecurityIdentifier])
   if ($trustedSids -notcontains $ownerSid.Value) {
-    throw 'Credential file has an untrusted owner'
+    Throw-CredentialAclFailure -Reason 'Credential file has an untrusted owner' -Path $FilePath -Sid $ownerSid.Value
   }
   foreach ($fileRule in @($fileAcl.Access)) {
     if ($fileRule.AccessControlType -ne [System.Security.AccessControl.AccessControlType]::Allow) {
@@ -822,10 +889,10 @@ function Assert-TrustedFile([string]$FilePath) {
         [System.Security.Principal.SecurityIdentifier]
       )
     } catch {
-      throw 'Credential file contains an unresolvable write principal'
+      Throw-CredentialAclFailure -Reason 'Credential file contains an unresolvable write principal' -Path $FilePath -Principal $fileRule.IdentityReference.Value -Rights $rights
     }
     if ($trustedSids -notcontains $fileRuleSid.Value) {
-      throw 'Credential file grants write access to an untrusted principal'
+      Throw-CredentialAclFailure -Reason 'Credential file grants write access to an untrusted principal' -Path $FilePath -Sid $fileRuleSid.Value -Rights $rights
     }
   }
 }
@@ -896,7 +963,7 @@ $access = [System.Security.AccessControl.FileSystemAccessRule]::new(
 Set-Acl -LiteralPath $Target -AclObject $acl
 $verified = Get-Acl -LiteralPath $Target
 if (-not (Test-CanonicalCredentialAcl $verified $sid $expectedInheritance)) {
-  throw 'Credential ACL verification failed'
+  Throw-CredentialAclFailure -Reason 'Credential ACL verification failed' -Path $Target -Sid $sid.Value
 }
 `;
 class PowerShellWindowsAclOps {
@@ -923,23 +990,37 @@ class PowerShellWindowsAclOps {
         this.run(path, 'assert-file');
     }
     run(path, kind) {
-        execFileSync(this.executable, [
-            '-NoLogo',
-            '-NoProfile',
-            '-NonInteractive',
-            '-ExecutionPolicy', 'Bypass',
-            '-EncodedCommand', Buffer.from(WINDOWS_ACL_SCRIPT, 'utf16le').toString('base64'),
-        ], {
-            env: {
-                SystemRoot: this.systemRoot,
-                EVOMAP_CREDENTIAL_ACL_TARGET: path,
-                EVOMAP_CREDENTIAL_ACL_KIND: kind,
-            },
-            shell: false,
-            stdio: 'ignore',
-            timeout: 15_000,
-            windowsHide: true,
-        });
+        try {
+            execFileSync(this.executable, [
+                '-NoLogo',
+                '-NoProfile',
+                '-NonInteractive',
+                '-ExecutionPolicy', 'Bypass',
+                // The fixed wrapper parses stdin once. Bare -Command - can execute
+                // PowerShell 5.1 input statement by statement and mask an earlier error.
+                '-Command', POWERSHELL_STDIN_SCRIPT_COMMAND,
+            ], {
+                encoding: 'utf8',
+                env: {
+                    SystemRoot: this.systemRoot,
+                    EVOMAP_CREDENTIAL_ACL_TARGET: path,
+                    EVOMAP_CREDENTIAL_ACL_KIND: kind,
+                },
+                shell: false,
+                // Capture both streams rather than discarding them: the script's own
+                // message names which path level and which SID failed, and without it
+                // every rejection is indistinguishable from "PowerShell is missing".
+                // The script prints nothing on success, so this stays quiet normally.
+                input: WINDOWS_ACL_SCRIPT,
+                stdio: ['pipe', 'pipe', 'pipe'],
+                timeout: 15_000,
+                windowsHide: true,
+            });
+        }
+        catch (cause) {
+            const detail = windowsAclFailureDetail(cause);
+            throw new Error(detail ? `${kind} check failed: ${detail}` : `${kind} check failed`, { cause });
+        }
     }
 }
 function readDarwinAcl(path) {
@@ -999,6 +1080,13 @@ function sameIdentity(left, right) {
 function sameSecurityState(left, right) {
     return sameIdentity(left, right) && left.ctimeNs === right.ctimeNs;
 }
+function sameDarwinAncestorMetadata(left, right) {
+    return sameIdentity(left, right)
+        && right.isDirectory()
+        && !right.isSymbolicLink()
+        && left.uid === right.uid
+        && left.mode === right.mode;
+}
 function samePathSecurityStates(left, right) {
     return left.length === right.length && left.every((state, index) => {
         const candidate = right[index];

package/dist/auth/legacyShim.d.ts

@@ -13,8 +13,8 @@ export type NodeSecretVersionHandler = (nodeSecretVersion?: number) => void;
  */
 export type NodeSecretDivergenceHandler = () => void;
 /**
- * node_secret 双轨过渡(M6-5, 6 个月). 包旧 64-hex node_secret 成 AuthProvider.
- * **node_secret 走 request body**(gep-a2a 契约, 实测 dev: requireNodeSecret 读 body 非 header), 不轮换.
+ * LegacyAuthShim exposes node_secret as a transport-neutral credential field. HubFetch promotes it to
+ * Authorization: Bearer for GET and strict GEP envelope endpoints before egress.
  */
 export declare class LegacyAuthShim implements hub.AuthProvider {
     private nodeSecret;

package/dist/auth/legacyShim.js

@@ -13,8 +13,8 @@ export function parseNodeSecretVersion(value) {
     return Number.isSafeInteger(parsed) ? parsed : undefined;
 }
 /**
- * node_secret 双轨过渡(M6-5, 6 个月). 包旧 64-hex node_secret 成 AuthProvider.
- * **node_secret 走 request body**(gep-a2a 契约, 实测 dev: requireNodeSecret 读 body 非 header), 不轮换.
+ * LegacyAuthShim exposes node_secret as a transport-neutral credential field. HubFetch promotes it to
+ * Authorization: Bearer for GET and strict GEP envelope endpoints before egress.
  */
 export class LegacyAuthShim {
     nodeSecret;

package/dist/auth/windowsPowerShell.d.ts

@@ -0,0 +1,3 @@
+export declare const POWERSHELL_STDIN_SCRIPT_COMMAND = "& ([scriptblock]::Create([Console]::In.ReadToEnd()))";
+export declare function windowsAclFailureDetail(cause: unknown): string;
+export declare function stripPowerShellClixml(text: string): string;

package/dist/auth/windowsPowerShell.js

@@ -0,0 +1,91 @@
+export const POWERSHELL_STDIN_SCRIPT_COMMAND = '& ([scriptblock]::Create([Console]::In.ReadToEnd()))';
+export function windowsAclFailureDetail(cause) {
+    const error = cause;
+    const parts = [];
+    if (typeof error?.code === 'string' && error.code) {
+        parts.push('code ' + normalizePowerShellDiagnostic(error.code));
+    }
+    if (typeof error?.status === 'number')
+        parts.push('exit ' + error.status);
+    if (typeof error?.signal === 'string' && error.signal) {
+        parts.push('signal ' + normalizePowerShellDiagnostic(error.signal));
+    }
+    const streams = [error?.stderr, error?.stdout]
+        .map((stream) => (typeof stream === 'string'
+        ? stream
+        : Buffer.isBuffer(stream) ? stream.toString('utf8') : ''))
+        .map(stripPowerShellClixml)
+        .filter((text) => text.length > 0);
+    if (streams.length > 0) {
+        parts.push(streams.join(' | '));
+    }
+    else {
+        const message = typeof error?.message === 'string' ? error.message : '';
+        const detail = stripPowerShellClixml(message.replace(/-EncodedCommand\s+\S+/g, '-EncodedCommand <omitted>'));
+        if (detail)
+            parts.push(detail);
+    }
+    return boundPowerShellDiagnostic(parts.join('; '));
+}
+export function stripPowerShellClixml(text) {
+    if (/#<\s*CLIXML\b/i.test(text)) {
+        const errorRecords = [];
+        const serializedErrors = /<S\b(?=[^>]*\bS=\x22Error\x22)[^>]*>([\s\S]*?)<\/S>/gi;
+        for (const match of text.matchAll(serializedErrors)) {
+            const record = decodePowerShellClixmlText(match[1] ?? '');
+            const hasLocationBoilerplate = /(?:^|\s)At line:\d+ char:\d+/i.test(record);
+            const decoded = normalizePowerShellDiagnostic(stripPowerShellLocationBoilerplate(record));
+            if (decoded)
+                errorRecords.push(decoded);
+            if (hasLocationBoilerplate)
+                break;
+        }
+        if (errorRecords.length > 0)
+            return [...new Set(errorRecords)].join(' | ');
+    }
+    return normalizePowerShellDiagnostic(stripPowerShellLocationBoilerplate(text)
+        .replace(/<Objs\b[\s\S]*?<\/Objs>/g, ' ')
+        .replace(/<Objs\b[^\n]*/g, ' ')
+        .replace(/#<\s*CLIXML\b/gi, ' '));
+}
+function stripPowerShellLocationBoilerplate(text) {
+    return text.replace(/(?:^|\s)At line:\d+ char:\d+[\s\S]*$/i, ' ');
+}
+function decodePowerShellClixmlText(text) {
+    return text
+        .replace(/_x([0-9a-f]{4})_/gi, (_match, hex) => String.fromCharCode(Number.parseInt(hex, 16)))
+        .replace(/&#x([0-9a-f]+);/gi, (match, value) => decodeXmlCodePoint(match, value, 16))
+        .replace(/&#([0-9]+);/g, (match, value) => decodeXmlCodePoint(match, value, 10))
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, String.fromCharCode(34))
+        .replace(/&apos;/g, String.fromCharCode(39))
+        .replace(/&amp;/g, '&');
+}
+function decodeXmlCodePoint(match, value, radix) {
+    const codePoint = Number.parseInt(value, radix);
+    if (!Number.isInteger(codePoint) || codePoint < 0 || codePoint > 0x10ffff ||
+        (codePoint >= 0xd800 && codePoint <= 0xdfff)) {
+        return match;
+    }
+    return String.fromCodePoint(codePoint);
+}
+const POWERSHELL_DIAGNOSTIC_FORMAT_CHARACTER = /^\p{Cf}$/u;
+function normalizePowerShellDiagnostic(text) {
+    const sanitized = [];
+    for (const character of text) {
+        const codePoint = character.codePointAt(0) ?? 0;
+        const isControl = codePoint <= 0x1f || (codePoint >= 0x7f && codePoint <= 0x9f);
+        const isFormat = POWERSHELL_DIAGNOSTIC_FORMAT_CHARACTER.test(character);
+        sanitized.push(isControl || isFormat || codePoint === 0x2028 || codePoint === 0x2029 ? ' ' : character);
+    }
+    return sanitized.join('').replace(/\s+/g, ' ').trim();
+}
+function boundPowerShellDiagnostic(text) {
+    const limit = 300;
+    if (text.length <= limit)
+        return text;
+    const headLength = Math.ceil((limit - 3) / 2);
+    const tailLength = limit - 3 - headLength;
+    return text.slice(0, headLength) + '...' + text.slice(-tailLength);
+}

package/dist/hubCapability.d.ts

@@ -58,6 +58,9 @@ export interface AccountAssetListResult {
     hasMore: boolean;
     nextCursor?: string;
 }
+export declare class MalformedAccountAssetPageError extends Error {
+    constructor();
+}
 /** 完整 GEP-A2A 信封(实测 dev: publish/fetch/validate 等协议消息端点必须全信封, 非仅 protocol+message_type). */
 export declare function gepEnvelope(messageType: string, payload: unknown, options?: {
     messageId?: string;
@@ -142,12 +145,20 @@ export declare class PublicHubCapability implements hub.HubCapability {
     readonly auth: hub.AuthProvider;
     readonly recipes: hub.RecipeCapability;
     constructor(opts: PublicHubOptions);
+    private evolverVersionForWire;
+    private envFingerprintForWire;
     hello(opts: PublicHelloOptions): Promise<PublicHelloResult>;
     heartbeat(opts?: PublicHeartbeatOptions): Promise<PublicHeartbeatResult>;
     private heartbeatMeta;
     publish(bundle: hub.AssetRecord[], options?: hub.PublishOptions): Promise<hub.PublishReceipt>;
     fetch(query: hub.HubQuery): Promise<hub.AssetRecord[]>;
-    fetchAssetById(assetId: string): Promise<hub.AssetRecord | null>;
+    /**
+     * Fetch one asset AND say why, when the answer is not an asset. `fetchAssetById` collapses every outcome to
+     * `null`, so a caller could not tell "the hub does not have this" from "the hub delivered something the
+     * client refuses" — and the CLI reported both as `not_found` on assets that demonstrably exist (#964).
+     */
+    fetchAssetDeliveryById(assetId: string, options?: hub.FetchAssetByIdOptions): Promise<hub.AssetDeliveryOutcome>;
+    fetchAssetById(assetId: string, options?: hub.FetchAssetByIdOptions): Promise<hub.AssetRecord | null>;
     /**
      * #69: search != fetch. Free-text is the hub's vector endpoint (GET /a2a/assets/semantic-search?q=);
      * signal/id queries use the Hub's free search-only phase on /a2a/fetch. /a2a/fetch does NOT do semantic,
@@ -183,6 +194,8 @@ export declare class PublicHubCapability implements hub.HubCapability {
     createRecipe(request: hub.RecipeCreateRequest): Promise<hub.RecipeReceipt>;
     publishRecipe(recipeId: string, options?: hub.RecipePublishOptions): Promise<hub.RecipeReceipt>;
     getRecipe(recipeId: string): Promise<hub.RecipeFetchReceipt>;
+    searchRecipes(request?: hub.RecipeSearchRequest): Promise<hub.RecipeSearchReceipt>;
+    listRecipes(request?: hub.RecipeSearchRequest): Promise<hub.RecipeSearchReceipt>;
     expressRecipe(recipeId: string, request?: hub.RecipeExpressRequest): Promise<hub.RecipeExpressionReceipt>;
     task: {
         claim: (taskId: string) => Promise<{