@aiwg/cli 2026.8.4 → 2026.8.5

package/dist/src/resources/web-release.d.ts

@@ -49,6 +49,13 @@ export interface WebReleaseOptions {
     credentialProvider?: () => Promise<string | null>;
     /** Test/development escape hatch. HTTP remains restricted to loopback. */
     allowInsecureLoopbackHttp?: boolean;
+    /** Structured cache diagnostics; never includes URLs, headers, or credentials. */
+    onDiagnostic?: (diagnostic: WebReleaseDiagnostic) => void;
+}
+export interface WebReleaseDiagnostic {
+    resource: "channel" | "version-index";
+    outcome: "conditional-hit" | "revalidated" | "unconditional";
+    validator: "etag" | "last-modified" | "none";
 }
 export interface VerifiedReleaseDescriptor {
     path: string;

package/dist/src/resources/web-release.js

@@ -386,6 +386,69 @@ async function fetchBytes(fetcher, url, label, maxBytes, bearerToken) {
         clearTimeout(timeout);
     }
 }
+function validatorFromResponse(response, payloadSha256) {
+    // Preserve the origin's ETag octets, including the W/ prefix for weak tags.
+    // HTTP validators only suppress transfer; Ed25519 and SHA-256 remain the
+    // authority for every cached representation accepted by this module.
+    const etag = response.headers.get("etag")?.trim();
+    const lastModified = response.headers.get("last-modified")?.trim();
+    if (!etag && !lastModified)
+        return undefined;
+    return {
+        schemaVersion: "aiwg.http-validator/v1",
+        payloadSha256,
+        ...(etag ? { etag } : { lastModified: lastModified }),
+    };
+}
+function readMetadataValidator(pathname, payloadSha256) {
+    if (!fs.existsSync(pathname))
+        return undefined;
+    const value = parseJson(readVerifiedRegularFile(pathname, {
+        label: "cached HTTP metadata validator",
+        maxBytes: MAX_COMPLETION_MARKER_BYTES,
+    }), "cached HTTP metadata validator");
+    if (!isRecord(value) || value.schemaVersion !== "aiwg.http-validator/v1" || value.payloadSha256 !== payloadSha256) {
+        throw new Error("cached HTTP metadata validator does not match the verified signed payload");
+    }
+    const etag = typeof value.etag === "string" && value.etag.trim() ? value.etag.trim() : undefined;
+    const lastModified = typeof value.lastModified === "string" && value.lastModified.trim() ? value.lastModified.trim() : undefined;
+    if (!etag && !lastModified)
+        throw new Error("cached HTTP metadata validator is empty");
+    return { schemaVersion: "aiwg.http-validator/v1", payloadSha256, ...(etag ? { etag } : { lastModified }) };
+}
+async function fetchMetadata(fetcher, url, label, maxBytes, cachedValidator) {
+    const headers = { "accept-encoding": "identity" };
+    if (cachedValidator?.etag)
+        headers["if-none-match"] = cachedValidator.etag;
+    else if (cachedValidator?.lastModified)
+        headers["if-modified-since"] = cachedValidator.lastModified;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), RESOURCE_FETCH_TIMEOUT_MS);
+    let response;
+    try {
+        response = await fetcher(url, { redirect: "error", headers, signal: controller.signal });
+    }
+    catch (error) {
+        if (controller.signal.aborted)
+            throw new Error(`${label} request timed out after ${RESOURCE_FETCH_TIMEOUT_MS}ms`);
+        throw error;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+    if (response.status === 304) {
+        if (!cachedValidator)
+            throw new Error(`${label} returned 304 without a verified cached representation`);
+        return {
+            notModified: true,
+            validator: validatorFromResponse(response, cachedValidator.payloadSha256) ?? cachedValidator,
+        };
+    }
+    if (!response.ok)
+        throw new Error(`${label} fetch failed (${response.status}): ${url}`);
+    const bytes = await fetchBytes(async () => response, url, label, maxBytes);
+    return { notModified: false, bytes, validator: validatorFromResponse(response, sha256(bytes)) };
+}
 function verifyDescriptor(bytes, descriptor, label = descriptor.path) {
     if (bytes.byteLength !== descriptor.size || sha256(bytes) !== descriptor.sha256) {
         throw new Error(`release descriptor size or digest verification failed: ${label}`);
@@ -623,7 +686,14 @@ function readCachedChannel(cacheRoot, channel, publicKeyPem) {
             if (candidate.name !== `${manifest.sequence}-${digest}`) {
                 throw new Error(`cached channel ${channel} generation name does not match its signed metadata`);
             }
-            valid.push({ manifest, bytes, signatureBytes, digest });
+            let validator;
+            try {
+                validator = readMetadataValidator(path.join(dir, "http-validator.json"), digest);
+            }
+            catch {
+                validator = undefined;
+            }
+            valid.push({ manifest, bytes, signatureBytes, digest, validator });
         }
         catch {
             corrupt = true;
@@ -658,10 +728,23 @@ function readCachedVersionIndex(cacheRoot, publicKeyPem) {
         label: "cached resource version index signature",
         maxBytes: MAX_SIGNATURE_BYTES,
     });
-    verifySignedResourceBytes(bytes, signatureBytes, publicKeyPem, "cached resource version index");
-    return validateVersionIndex(parseJson(bytes, "cached resource version index"));
+    const digest = verifySignedResourceBytes(bytes, signatureBytes, publicKeyPem, "cached resource version index");
+    return {
+        index: validateVersionIndex(parseJson(bytes, "cached resource version index")),
+        bytes,
+        signatureBytes,
+        digest,
+        validator: (() => {
+            try {
+                return readMetadataValidator(path.join(dir, "http-validator.json"), digest);
+            }
+            catch {
+                return undefined;
+            }
+        })(),
+    };
 }
-function cacheVersionIndex(cacheRoot, bytes, signatureBytes) {
+function cacheVersionIndex(cacheRoot, bytes, signatureBytes, validator) {
     const target = versionIndexCacheDir(cacheRoot);
     const stagingRoot = path.join(cacheRoot, ".staging", "versions");
     fs.mkdirSync(stagingRoot, { recursive: true });
@@ -669,6 +752,8 @@ function cacheVersionIndex(cacheRoot, bytes, signatureBytes) {
     try {
         fs.writeFileSync(path.join(stage, "versions.json"), bytes, { flag: "wx" });
         fs.writeFileSync(path.join(stage, "versions.sig"), signatureBytes, { flag: "wx" });
+        if (validator)
+            fs.writeFileSync(path.join(stage, "http-validator.json"), `${JSON.stringify(validator)}\n`, { flag: "wx" });
         if (fs.existsSync(target))
             fs.rmSync(target, { recursive: true, force: true });
         installGeneration(stage, target);
@@ -678,19 +763,33 @@ function cacheVersionIndex(cacheRoot, bytes, signatureBytes) {
         throw error;
     }
 }
-async function fetchAndCacheVersionIndex(base, fetcher, cacheRoot, publicKeyPem) {
-    const indexBytes = await fetchBytes(fetcher, resourceUrl(base, "resources/versions.json"), "resource version index", MAX_VERSION_INDEX_BYTES);
+async function fetchAndCacheVersionIndex(base, fetcher, cacheRoot, publicKeyPem, diagnostic) {
+    let cached = null;
+    try {
+        cached = readCachedVersionIndex(cacheRoot, publicKeyPem);
+    }
+    catch {
+        cached = null;
+    }
+    const fetched = await fetchMetadata(fetcher, resourceUrl(base, "resources/versions.json"), "resource version index", MAX_VERSION_INDEX_BYTES, cached?.validator);
+    if (fetched.notModified) {
+        cacheVersionIndex(cacheRoot, cached.bytes, cached.signatureBytes, fetched.validator);
+        diagnostic?.({ resource: "version-index", outcome: "conditional-hit", validator: cached.validator.etag ? "etag" : "last-modified" });
+        return cached.index;
+    }
+    const indexBytes = fetched.bytes;
     const signatureBytes = await fetchBytes(fetcher, resourceUrl(base, "resources/versions.sig"), "resource version index signature", MAX_SIGNATURE_BYTES);
     verifySignedResourceBytes(indexBytes, signatureBytes, publicKeyPem, "resource version index");
     const index = validateVersionIndex(parseJson(indexBytes, "resource version index"));
-    cacheVersionIndex(cacheRoot, indexBytes, signatureBytes);
+    cacheVersionIndex(cacheRoot, indexBytes, signatureBytes, fetched.validator);
+    diagnostic?.({ resource: "version-index", outcome: cached?.validator ? "revalidated" : "unconditional", validator: fetched.validator?.etag ? "etag" : fetched.validator?.lastModified ? "last-modified" : "none" });
     return index;
 }
-async function resolveVersionIndex(base, fetcher, cacheRoot, publicKeyPem, offline) {
+async function resolveVersionIndex(base, fetcher, cacheRoot, publicKeyPem, offline, diagnostic) {
     if (offline) {
         const cached = readCachedVersionIndex(cacheRoot, publicKeyPem);
         if (cached)
-            return cached;
+            return cached.index;
         const versions = cachedReleaseVersions(cacheRoot).flatMap((version) => cachedDigests(cacheRoot, version).map((digest) => ({
             version,
             releaseManifest: `/resources/${version}/manifest.json`,
@@ -703,12 +802,14 @@ async function resolveVersionIndex(base, fetcher, cacheRoot, publicKeyPem, offli
     if (!fetcher)
         throw new Error("No fetch implementation is available for AIWG web resources");
     try {
-        return await fetchAndCacheVersionIndex(base, fetcher, cacheRoot, publicKeyPem);
+        return await fetchAndCacheVersionIndex(base, fetcher, cacheRoot, publicKeyPem, diagnostic);
     }
     catch (error) {
+        if (error instanceof Error && /fetch failed \((?:401|403|429|5\d\d)\)/.test(error.message))
+            throw error;
         const cached = readCachedVersionIndex(cacheRoot, publicKeyPem);
         if (cached)
-            return cached;
+            return cached.index;
         throw error;
     }
 }
@@ -776,7 +877,7 @@ function fsyncTree(root) {
     }
     fsyncDirectory(root);
 }
-function cacheChannel(cacheRoot, manifest, bytes, signatureBytes, digest) {
+function cacheChannel(cacheRoot, manifest, bytes, signatureBytes, digest, validator) {
     const root = channelGenerationRoot(cacheRoot, manifest.channel);
     const stagingRoot = path.join(cacheRoot, ".staging", "channels");
     fs.mkdirSync(stagingRoot, { recursive: true });
@@ -784,6 +885,8 @@ function cacheChannel(cacheRoot, manifest, bytes, signatureBytes, digest) {
     try {
         fs.writeFileSync(path.join(stage, "channel.json"), bytes, { flag: "wx" });
         fs.writeFileSync(path.join(stage, "channel.sig"), signatureBytes, { flag: "wx" });
+        if (validator)
+            fs.writeFileSync(path.join(stage, "http-validator.json"), `${JSON.stringify(validator)}\n`, { flag: "wx" });
         const target = path.join(root, `${manifest.sequence}-${digest}`);
         if (fs.existsSync(target)) {
             let matches = false;
@@ -797,7 +900,11 @@ function cacheChannel(cacheRoot, manifest, bytes, signatureBytes, digest) {
                         readVerifiedRegularFile(path.join(target, "channel.sig"), {
                             label: `cached channel ${manifest.channel} signature`,
                             maxBytes: MAX_SIGNATURE_BYTES,
-                        }).equals(Buffer.from(signatureBytes));
+                        }).equals(Buffer.from(signatureBytes)) &&
+                        (validator
+                            ? readMetadataValidator(path.join(target, "http-validator.json"), digest)?.etag === validator.etag &&
+                                readMetadataValidator(path.join(target, "http-validator.json"), digest)?.lastModified === validator.lastModified
+                            : !fs.existsSync(path.join(target, "http-validator.json")));
             }
             catch {
                 matches = false;
@@ -921,8 +1028,20 @@ export async function resolveWebRelease(options = {}) {
         return fetchAndCacheRelease(base, fetcher, cacheRoot, selector, selector.value, publicKeyPem);
     }
     if (selector.kind === "range" || selector.kind === "digest") {
+        if (!options.offline && selector.kind === "digest") {
+            for (const version of cachedReleaseVersions(cacheRoot)) {
+                if (!cachedDigests(cacheRoot, version).includes(selector.digest))
+                    continue;
+                try {
+                    return verifyCachedGeneration(cacheRoot, version, selector.digest, selector, publicKeyPem, base, selector.digest);
+                }
+                catch {
+                    // A corrupt immutable generation cannot bypass signed index resolution.
+                }
+            }
+        }
         const fetcher = authorize;
-        const index = await resolveVersionIndex(base, fetcher, cacheRoot, publicKeyPem, options.offline);
+        const index = await resolveVersionIndex(base, fetcher, cacheRoot, publicKeyPem, options.offline, options.onDiagnostic);
         const selected = selectVersionFromIndex(index, selector);
         if (options.offline) {
             return resolveOfflineExact(cacheRoot, selector, selected.version, publicKeyPem, base, selected.releaseManifestSha256);
@@ -941,11 +1060,23 @@ export async function resolveWebRelease(options = {}) {
     if (!fetcher)
         throw new Error("No fetch implementation is available for AIWG web resources");
     const channelPrefix = `resources/channels/${selector.value}`;
-    const channelBytes = await fetchBytes(fetcher, resourceUrl(base, `${channelPrefix}.json`), `channel ${selector.value}`, MAX_SIGNED_METADATA_BYTES);
+    let prior = null;
+    try {
+        prior = readCachedChannel(cacheRoot, selector.value, publicKeyPem);
+    }
+    catch {
+        prior = null;
+    }
+    const fetched = await fetchMetadata(fetcher, resourceUrl(base, `${channelPrefix}.json`), `channel ${selector.value}`, MAX_SIGNED_METADATA_BYTES, prior?.validator);
+    if (fetched.notModified) {
+        cacheChannel(cacheRoot, prior.manifest, prior.bytes, prior.signatureBytes, prior.digest, fetched.validator);
+        options.onDiagnostic?.({ resource: "channel", outcome: "conditional-hit", validator: prior.validator.etag ? "etag" : "last-modified" });
+        return fetchAndCacheRelease(base, fetcher, cacheRoot, selector, prior.manifest.version, publicKeyPem, prior.manifest.releaseManifestSha256, prior.manifest.sequence);
+    }
+    const channelBytes = fetched.bytes;
     const channelSignatureBytes = await fetchBytes(fetcher, resourceUrl(base, `${channelPrefix}.sig`), `channel ${selector.value} signature`, MAX_SIGNATURE_BYTES);
     const channelDigest = verifySignedResourceBytes(channelBytes, channelSignatureBytes, publicKeyPem, `channel ${selector.value}`);
     const channel = validateChannelManifest(parseJson(channelBytes, `channel ${selector.value}`), selector.value);
-    const prior = readCachedChannel(cacheRoot, selector.value, publicKeyPem);
     if (prior && channel.sequence < prior.manifest.sequence) {
         throw new Error(`channel ${selector.value} sequence rollback detected (${channel.sequence} < ${prior.manifest.sequence})`);
     }
@@ -957,7 +1088,8 @@ export async function resolveWebRelease(options = {}) {
         throw new Error(`channel ${selector.value} sequence ${channel.sequence} has conflicting signed metadata`);
     }
     const release = await fetchAndCacheRelease(base, fetcher, cacheRoot, selector, channel.version, publicKeyPem, channel.releaseManifestSha256, channel.sequence);
-    cacheChannel(cacheRoot, channel, channelBytes, channelSignatureBytes, channelDigest);
+    cacheChannel(cacheRoot, channel, channelBytes, channelSignatureBytes, channelDigest, fetched.validator);
+    options.onDiagnostic?.({ resource: "channel", outcome: prior?.validator ? "revalidated" : "unconditional", validator: fetched.validator?.etag ? "etag" : fetched.validator?.lastModified ? "last-modified" : "none" });
     return release;
 }
 export async function fetchVerifiedRawResource(release, resourcePath, options = {}) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiwg/cli",
-  "version": "2026.8.4",
+  "version": "2026.8.5",
   "description": "Lightweight AIWG CLI for signed, versioned web-backed resources.",
   "type": "module",
   "license": "MIT",