@agentique.io/readback 0.1.0 → 0.2.0

package/README.md

@@ -2,9 +2,11 @@
 
 Read-only public readback helpers for Agentique resources.
 
-This package helps integrators consume public Agentique resource status from `agentique.io` when the platform exposes versioned public endpoints. It exposes status, list, detail, download metadata, readback projection, context bundle, and selection readback helpers only.
+This package helps integrators consume public Agentique resource status from `agentique.io` when the platform exposes versioned public endpoints. It exposes status, list, detail, download metadata, readback projection, context bundle, selection readback, catalog normalization, and safe byte-download helpers only.
 
-`agentique.io` remains the source of truth for upload, scan, review, moderation, publication, distribution state, and readback. This package does not publish, edit, delete, moderate, or approve resources.
+`agentique.io` remains the source of truth for upload, scan, review, moderation, publication, distribution state, and readback. This package does not publish, edit, delete, moderate, approve, certify, install, extract, open, or execute resources.
+
+Catalog and direct-download helpers are included in the 0.2.0 package source. The helpers remain read-only or explicit-output only, and they do not make a live direct-download availability claim unless owner-approved disposable byte-transfer evidence is recorded.
 
 ## Install
 
@@ -15,13 +17,29 @@ npm install @agentique.io/readback
 ## Usage
 
 ```js
-import { createBadgeState, createReadbackClient } from "@agentique.io/readback";
+import {
+  createBadgeState,
+  createReadbackClient,
+  downloadResourceArtifact,
+  normalizeDownloadMetadata,
+  normalizeParserVariantReadback,
+  normalizeResourceList,
+  normalizeTrustReadback
+} from "@agentique.io/readback";
 
 const client = createReadbackClient();
+const catalog = normalizeResourceList(await client.listResources({ limit: 10 }));
+const metadata = normalizeDownloadMetadata(await client.getDownloadMetadata("resource-id"));
 const readback = await client.getReadback("resource-id");
+const trust = normalizeTrustReadback(readback);
+const parserVariant = normalizeParserVariantReadback(readback);
 const badge = createBadgeState(readback);
 
 console.log(badge.label);
+console.log(trust.trustPanel?.state ?? trust.platformState);
+console.log(parserVariant.parserEvidence?.parseStatus ?? "unavailable");
+console.log(`${catalog.items.length} catalog entries`);
+console.log(metadata.availability);
 ```
 
 ## Read-Only Client
@@ -44,19 +62,34 @@ Context bundle and selection readback helpers use narrow query allowlists for pu
 
 Returned payloads are normalized with a defense-in-depth projection pass that removes explicitly private fields while preserving public schema fields such as `internalId`, `storageUsage`, `deploymentDate`, `tokenCount`, `objectType`, and `storageMode`. The platform API remains responsible for the authoritative public projection; client-side normalization is not a privacy boundary.
 
+`normalizeTrustReadback()` projects public desired-state, scanner-policy, trust-panel, review-eligibility, report-action, and version-history fields into a stable readback summary when those fields are present.
+
+`normalizeResourceList()` projects public catalog list payloads into stable item and page-info fields. `normalizeDownloadMetadata()` projects public download metadata into availability, filename, media type, size, digest, and expiry fields while filtering private projection fields.
+
+`normalizeParserVariantReadback()` projects public parser evidence and platform variant fields into a bounded summary when those fields are present. It reports digest presence instead of raw digests and keeps parser/variant state descriptive. Source-only variant metadata remains preparation evidence and is not treated as platform download readiness.
+
+`downloadResourceArtifact()` can write available artifact bytes to an explicit output path. It enforces HTTPS outside loopback development, manual redirect handling, no-overwrite by default, safe filename/path checks, temp-file cleanup, size limits, and digest verification. It does not install, extract, open, execute, approve, certify, publish, host, or moderate downloaded content. Treat downloaded bytes as untrusted until separately reviewed.
+
 ## Badge States
 
 Badge helpers return explicit states:
 
 - `published`
+- `parsed`
+- `partial`
+- `unsupported`
+- `variant-available`
 - `review-required`
+- `rescan-required`
 - `blocked`
 - `stale`
 - `unavailable`
 - `rate-limited`
 
+Parser and variant badge states are public readback summaries. They do not prove runtime compatibility, create platform downloads, or replace platform review.
+
 Badge output is a public readback summary, not a safety guarantee.
 
 ## Status
 
-Local implementation exists for review. The package has not been published yet.
+Published as `@agentique.io/readback`. Badge output is a public readback summary, not a platform approval or safety guarantee.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentique.io/readback",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Read-only public readback helpers for Agentique resources.",
   "type": "module",
   "repository": {

package/src/badge.mjs

@@ -1,6 +1,30 @@
 const DEFAULT_STALE_AFTER_SECONDS = 15 * 60;
 
 const BADGE_STATES = Object.freeze({
+  parsed: {
+    state: "parsed",
+    label: "Parsed",
+    color: "0969da",
+    description: "Public readback includes parsed parser metadata."
+  },
+  partial: {
+    state: "partial",
+    label: "Parser partial",
+    color: "bf8700",
+    description: "Public readback shows parser metadata that needs review."
+  },
+  unsupported: {
+    state: "unsupported",
+    label: "Parser unsupported",
+    color: "6e7781",
+    description: "Public readback marks the parser or variant target as unsupported."
+  },
+  "variant-available": {
+    state: "variant-available",
+    label: "Variant available",
+    color: "0969da",
+    description: "Public readback includes a platform variant projection."
+  },
   published: {
     state: "published",
     label: "Published",
@@ -13,6 +37,12 @@ const BADGE_STATES = Object.freeze({
     color: "bf8700",
     description: "The platform readback requires review before normal public use."
   },
+  "rescan-required": {
+    state: "rescan-required",
+    label: "Rescan required",
+    color: "9a6700",
+    description: "The platform readback indicates local content should be scanned again before normal public use."
+  },
   blocked: {
     state: "blocked",
     label: "Blocked",
@@ -56,6 +86,16 @@ export function createBadgeState(readback, options = {}) {
     return badge("stale", { observedAt });
   }
 
+  const parserVariantState = parserVariantBadgeState(readback);
+  if (parserVariantState) {
+    return badge(parserVariantState, { platformUrl: readback.platformUrl ?? readback.url ?? null });
+  }
+
+  const trustState = trustBadgeState(readback);
+  if (trustState) {
+    return badge(trustState, { platformUrl: readback.platformUrl ?? readback.url ?? null });
+  }
+
   const status = normalizeStatus(readback.status ?? readback.publicationStatus ?? readback.state);
 
   if (status === "published") {
@@ -94,6 +134,88 @@ function badge(state, extras = {}) {
   });
 }
 
+function trustBadgeState(readback) {
+  const desiredState = normalizeStatus(readback.desiredState?.readbackState);
+  const scannerFreshness = normalizeStatus(readback.scannerPolicy?.freshness);
+  const trustPanelState = normalizeStatus(readback.trustPanel?.state);
+  const reviewState = normalizeStatus(readback.reviewEligibility?.state);
+  const platformState = normalizeStatus(readback.platformProjection?.publicationState);
+
+  if ([trustPanelState, platformState].some((state) => ["blocked", "quarantined", "rejected"].includes(state))) {
+    return "blocked";
+  }
+
+  if ([desiredState, scannerFreshness, trustPanelState].includes("rescan-required")) {
+    return "rescan-required";
+  }
+
+  if (
+    [desiredState, trustPanelState, platformState].includes("review-required") ||
+    reviewState === "needs-evidence" ||
+    reviewState === "creator-blocked"
+  ) {
+    return "review-required";
+  }
+
+  if (platformState === "published" || trustPanelState === "current") {
+    return "published";
+  }
+
+  if ([desiredState, scannerFreshness, trustPanelState, platformState].includes("stale")) {
+    return "stale";
+  }
+
+  return null;
+}
+
+function parserVariantBadgeState(readback) {
+  const parserVariant = readback?.parserVariant;
+  if (!parserVariant || typeof parserVariant !== "object" || Array.isArray(parserVariant)) {
+    return null;
+  }
+
+  const parserStatus = normalizeStatus(parserVariant.parserEvidence?.parseStatus);
+  const compatibilityStatus = normalizeStatus(parserVariant.compatibility?.status);
+  const platformVariants = Array.isArray(parserVariant.platformVariants) ? parserVariant.platformVariants : [];
+  const variantStates = platformVariants.map((variant) => normalizeStatus(variant?.state));
+  const validationStates = platformVariants.map((variant) => normalizeStatus(variant?.validationState));
+  const downloadStates = platformVariants.map((variant) => normalizeStatus(variant?.download?.availability));
+
+  if (
+    ["blocked", "failed"].includes(parserStatus) ||
+    compatibilityStatus === "blocked" ||
+    variantStates.includes("blocked")
+  ) {
+    return "blocked";
+  }
+
+  if (variantStates.includes("stale") || validationStates.includes("stale")) {
+    return "stale";
+  }
+
+  if (parserStatus === "unsupported" || compatibilityStatus === "unsupported" || variantStates.includes("unsupported")) {
+    return "unsupported";
+  }
+
+  if (parserStatus === "partial" || compatibilityStatus === "partial" || variantStates.includes("review-required")) {
+    return "partial";
+  }
+
+  if (
+    variantStates.includes("available") ||
+    downloadStates.includes("available") ||
+    downloadStates.includes("source-only")
+  ) {
+    return "variant-available";
+  }
+
+  if (parserStatus === "parsed") {
+    return "parsed";
+  }
+
+  return null;
+}
+
 function isStale(value, now, staleAfterSeconds) {
   const observedAt = toDate(value);
   const ageMs = now.getTime() - observedAt.getTime();
@@ -112,5 +234,6 @@ function normalizeStatus(value) {
   return String(value ?? "")
     .trim()
     .toLowerCase()
+    .replace(/_/g, "-")
     .replace(/\s+/g, "-");
 }

package/src/client.mjs

@@ -89,6 +89,21 @@ export function createReadbackClient(options = {}) {
       });
     }
 
+    if (response.status === 404) {
+      throw new ReadbackError("Readback resource was not found.", {
+        code: "not-found",
+        status: 404
+      });
+    }
+
+    if (response.status >= 500) {
+      throw new ReadbackError("Readback endpoint is unavailable.", {
+        code: "unavailable",
+        status: response.status,
+        retryAfter: response.headers?.get?.("retry-after") ?? null
+      });
+    }
+
     if (!response.ok) {
       throw new ReadbackError("Readback request failed.", {
         code: "http-error",
@@ -183,6 +198,278 @@ export function normalizePublicReadback(value) {
   return Object.freeze(normalized);
 }
 
+export function normalizeResourceList(value) {
+  const normalized = normalizePublicReadback(value);
+  if (Array.isArray(normalized)) {
+    return Object.freeze({
+      items: Object.freeze(normalized.filter(isRecord).map(projectResourceListItem)),
+      pageInfo: emptyPageInfo(),
+      observedAt: null
+    });
+  }
+
+  if (!isRecord(normalized)) {
+    return emptyResourceList();
+  }
+
+  const sourceItems = Array.isArray(normalized.items)
+    ? normalized.items
+    : Array.isArray(normalized.resources)
+      ? normalized.resources
+      : [];
+
+  return Object.freeze({
+    items: Object.freeze(sourceItems.filter(isRecord).map(projectResourceListItem)),
+    pageInfo: projectPageInfo(normalized.pageInfo),
+    observedAt: stringOrNull(normalized.observedAt ?? normalized.updatedAt)
+  });
+}
+
+export function normalizeDownloadMetadata(value) {
+  const normalized = normalizePublicReadback(value);
+  if (!isRecord(normalized)) {
+    return emptyDownloadMetadata();
+  }
+
+  const download = isRecord(normalized.download) ? normalized.download : {};
+  const digestValue = firstString(download.digest, normalized.digest, download.sha256, normalized.sha256);
+  const digest = projectDigest(digestValue);
+
+  return Object.freeze({
+    resourceId: stringOrNull(normalized.resourceId ?? normalized.id),
+    platformId: stringOrNull(download.platformId ?? normalized.platformId),
+    artifactKind: stringOrNull(download.artifactKind ?? normalized.artifactKind),
+    availability: normalizePublicState(download.availability ?? normalized.availability ?? normalized.status ?? normalized.state),
+    url: stringOrNull(download.url ?? normalized.downloadUrl ?? normalized.url),
+    filename: stringOrNull(download.filename ?? download.fileName ?? normalized.filename ?? normalized.fileName),
+    mediaType: stringOrNull(download.mediaType ?? normalized.mediaType ?? download.contentType ?? normalized.contentType),
+    sizeBytes: numberOrNull(download.sizeBytes ?? download.size ?? normalized.sizeBytes ?? normalized.size ?? normalized.contentLength),
+    digest,
+    digestPresent: typeof digestValue === "string",
+    digestValid: typeof digestValue !== "string" || digest !== null,
+    reasons: arrayOfStrings(download.reasons ?? normalized.reasons),
+    observedAt: stringOrNull(download.observedAt ?? normalized.observedAt ?? normalized.updatedAt),
+    expiresAt: stringOrNull(download.expiresAt ?? normalized.expiresAt)
+  });
+}
+
+export function normalizeTrustReadback(value) {
+  const normalized = normalizePublicReadback(value);
+  if (!normalized || typeof normalized !== "object" || Array.isArray(normalized)) {
+    return Object.freeze({
+      platformState: "unavailable",
+      desiredState: null,
+      scannerPolicy: null,
+      trustPanel: null,
+      reviewEligibility: null,
+      reportActionState: null,
+      versionHistory: []
+    });
+  }
+
+  const platformProjection = isRecord(normalized.platformProjection) ? normalized.platformProjection : {};
+  const desiredState = isRecord(normalized.desiredState) ? normalized.desiredState : null;
+  const scannerPolicy = isRecord(normalized.scannerPolicy) ? normalized.scannerPolicy : null;
+  const trustPanel = isRecord(normalized.trustPanel) ? normalized.trustPanel : null;
+  const reviewEligibility = isRecord(normalized.reviewEligibility) ? normalized.reviewEligibility : null;
+  const versionHistory = Array.isArray(normalized.versionHistory) ? normalized.versionHistory.filter(isRecord).map(projectVersion) : [];
+
+  return Object.freeze({
+    platformState: normalizePublicState(platformProjection.publicationState ?? normalized.status ?? normalized.state),
+    desiredState: desiredState
+      ? Object.freeze({
+          state: normalizePublicState(desiredState.readbackState),
+          fingerprintPresent: typeof desiredState.fingerprint === "string",
+          reasons: arrayOfStrings(desiredState.reasons)
+        })
+      : null,
+    scannerPolicy: scannerPolicy
+      ? Object.freeze({
+          policyVersion: stringOrNull(scannerPolicy.policyVersion),
+          freshness: normalizePublicState(scannerPolicy.freshness)
+        })
+      : null,
+    trustPanel: trustPanel
+      ? Object.freeze({
+          state: normalizePublicState(trustPanel.state),
+          messages: arrayOfStrings(trustPanel.messages),
+          versionHistoryUrl: stringOrNull(trustPanel.versionHistoryUrl)
+        })
+      : null,
+    reviewEligibility: reviewEligibility
+      ? Object.freeze({
+          state: normalizePublicState(reviewEligibility.state),
+          evidenceTypes: arrayOfStrings(reviewEligibility.evidenceTypes),
+          reasons: arrayOfStrings(reviewEligibility.reasons)
+        })
+      : null,
+    reportActionState: stringOrNull(normalized.reportActionState),
+    versionHistory: Object.freeze(versionHistory)
+  });
+}
+
+export function normalizeParserVariantReadback(value) {
+  const normalized = normalizePublicReadback(value);
+  const parserVariant = isRecord(normalized?.parserVariant) ? normalized.parserVariant : normalized;
+
+  if (!isRecord(parserVariant)) {
+    return emptyParserVariantSummary();
+  }
+
+  const parserEvidence = isRecord(parserVariant.parserEvidence) ? parserVariant.parserEvidence : null;
+  const resourceGraphSummary = isRecord(parserVariant.resourceGraphSummary) ? parserVariant.resourceGraphSummary : null;
+  const compatibility = isRecord(parserVariant.compatibility) ? parserVariant.compatibility : null;
+  const platformVariants = Array.isArray(parserVariant.platformVariants) ? parserVariant.platformVariants.filter(isRecord) : [];
+
+  return Object.freeze({
+    parserEvidence: parserEvidence
+      ? Object.freeze({
+          sourceEcosystem: stringOrNull(parserEvidence.sourceEcosystem),
+          sourceFormat: stringOrNull(parserEvidence.sourceFormat),
+          parseStatus: normalizePublicState(parserEvidence.parseStatus),
+          parseConfidence: normalizePublicState(parserEvidence.parseConfidence),
+          sanitizerStatus: normalizePublicState(parserEvidence.sanitizerStatus),
+          noExecution: parserEvidence.noExecution === true,
+          inputDigestPresent: typeof parserEvidence.inputDigest === "string",
+          outputDigestPresent: typeof parserEvidence.outputDigest === "string",
+          issueCount: Array.isArray(parserEvidence.issues) ? parserEvidence.issues.filter(isRecord).length : 0
+        })
+      : null,
+    resourceGraphSummary: resourceGraphSummary
+      ? Object.freeze({
+          sanitized: resourceGraphSummary.sanitized === true,
+          nodeCount: numberOrNull(resourceGraphSummary.nodeCount),
+          edgeCount: numberOrNull(resourceGraphSummary.edgeCount),
+          capabilityCount: numberOrNull(resourceGraphSummary.capabilityCount),
+          sourceFileCount: numberOrNull(resourceGraphSummary.sourceFileCount),
+          summaryDigestPresent: typeof resourceGraphSummary.summaryDigest === "string"
+        })
+      : null,
+    compatibility: compatibility
+      ? Object.freeze({
+          status: normalizePublicState(compatibility.status),
+          reasons: arrayOfStrings(compatibility.reasons)
+        })
+      : null,
+    platformVariants: Object.freeze(
+      platformVariants.map((variant) => {
+        const download = isRecord(variant.download) ? variant.download : {};
+        return Object.freeze({
+          platformId: stringOrNull(variant.platformId),
+          artifactKind: stringOrNull(variant.artifactKind),
+          state: normalizePublicState(variant.state),
+          validationState: normalizePublicState(variant.validationState),
+          downloadAvailability: normalizePublicState(download.availability),
+          downloadUrl: stringOrNull(download.url),
+          variantDigestPresent: typeof variant.variantDigest === "string",
+          downloadDigestPresent: typeof download.digest === "string",
+          reasons: arrayOfStrings(variant.reasons),
+          observedAt: stringOrNull(variant.observedAt)
+        });
+      })
+    ),
+    observedAt: stringOrNull(parserVariant.observedAt ?? normalized?.observedAt ?? normalized?.updatedAt)
+  });
+}
+
+function emptyParserVariantSummary() {
+  return Object.freeze({
+    parserEvidence: null,
+    resourceGraphSummary: null,
+    compatibility: null,
+    platformVariants: Object.freeze([]),
+    observedAt: null
+  });
+}
+
+function emptyResourceList() {
+  return Object.freeze({
+    items: Object.freeze([]),
+    pageInfo: emptyPageInfo(),
+    observedAt: null
+  });
+}
+
+function emptyPageInfo() {
+  return Object.freeze({
+    page: null,
+    pageSize: null,
+    total: null,
+    cursor: null,
+    nextCursor: null,
+    hasNextPage: false
+  });
+}
+
+function emptyDownloadMetadata() {
+  return Object.freeze({
+    resourceId: null,
+    platformId: null,
+    artifactKind: null,
+    availability: "unavailable",
+    url: null,
+    filename: null,
+    mediaType: null,
+    sizeBytes: null,
+    digest: null,
+    digestPresent: false,
+    digestValid: true,
+    reasons: Object.freeze([]),
+    observedAt: null,
+    expiresAt: null
+  });
+}
+
+function projectResourceListItem(item) {
+  return Object.freeze({
+    resourceId: stringOrNull(item.resourceId ?? item.id),
+    slug: stringOrNull(item.slug),
+    title: stringOrNull(item.title ?? item.name),
+    summary: stringOrNull(item.summary ?? item.description),
+    type: stringOrNull(item.type ?? item.resourceType),
+    status: normalizePublicState(item.status ?? item.state ?? item.publicationState),
+    platformUrl: stringOrNull(item.platformUrl ?? item.resourceUrl ?? item.url),
+    downloadAvailability: normalizePublicState(item.downloadAvailability ?? item.download?.availability),
+    updatedAt: stringOrNull(item.updatedAt ?? item.observedAt)
+  });
+}
+
+function projectPageInfo(value) {
+  if (!isRecord(value)) {
+    return emptyPageInfo();
+  }
+
+  return Object.freeze({
+    page: numberOrNull(value.page),
+    pageSize: numberOrNull(value.pageSize ?? value.limit),
+    total: numberOrNull(value.total),
+    cursor: stringOrNull(value.cursor),
+    nextCursor: stringOrNull(value.nextCursor ?? value.endCursor),
+    hasNextPage: value.hasNextPage === true
+  });
+}
+
+function projectDigest(value) {
+  if (typeof value !== "string") {
+    return null;
+  }
+
+  const trimmed = value.trim();
+  const prefixed = /^([A-Za-z0-9-]+):([A-Fa-f0-9]+)$/.exec(trimmed);
+  if (!prefixed) {
+    return null;
+  }
+
+  return Object.freeze({
+    algorithm: prefixed[1].toLowerCase(),
+    value: prefixed[2].toLowerCase()
+  });
+}
+
+function firstString(...values) {
+  return values.find((value) => typeof value === "string");
+}
+
 function isPrivateProjectionKey(key) {
   const normalized = key.replace(/[-_\s]/g, "").toLowerCase();
   return (
@@ -195,6 +482,39 @@ function isPrivateProjectionKey(key) {
   );
 }
 
+function projectVersion(entry) {
+  return Object.freeze({
+    version: stringOrNull(entry.version),
+    observedAt: stringOrNull(entry.observedAt),
+    state: normalizePublicState(entry.state),
+    desiredStateFingerprintPresent: typeof entry.desiredStateFingerprint === "string"
+  });
+}
+
+function arrayOfStrings(value) {
+  return Object.freeze(Array.isArray(value) ? value.filter((item) => typeof item === "string") : []);
+}
+
+function stringOrNull(value) {
+  return typeof value === "string" ? value : null;
+}
+
+function numberOrNull(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+function normalizePublicState(value) {
+  return String(value ?? "unknown")
+    .trim()
+    .toLowerCase()
+    .replace(/_/g, "-")
+    .replace(/\s+/g, "-");
+}
+
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
 export function assertReadOnlyClientSurface(client) {
   const methodNames = Object.keys(client);
   const violatingMethod = methodNames.find((methodName) =>
@@ -211,7 +531,9 @@ export function assertReadOnlyClientSurface(client) {
 }
 
 function buildUrl(baseUrl, path, params = {}) {
-  const url = new URL(`${baseUrl.pathname}${path}`, baseUrl);
+  const basePath = baseUrl.pathname === "/" ? "" : baseUrl.pathname.replace(/\/+$/, "");
+  const endpointPath = path.startsWith("/") ? path : `/${path}`;
+  const url = new URL(`${basePath}${endpointPath}`, baseUrl);
 
   for (const [key, value] of Object.entries(params)) {
     if (value === undefined || value === null || value === "") {
@@ -224,18 +546,40 @@ function buildUrl(baseUrl, path, params = {}) {
 }
 
 function pickListParams(params) {
+  if (!isRecord(params)) {
+    throw new ReadbackError("List resources params must be an object.", { code: "invalid-list-params" });
+  }
+
   const allowed = ["q", "type", "cursor", "limit", "status"];
   const picked = {};
 
   for (const key of allowed) {
     if (Object.hasOwn(params, key)) {
-      picked[key] = params[key];
+      if (key === "limit") {
+        if (params[key] !== undefined && params[key] !== null && params[key] !== "") {
+          picked[key] = normalizeListLimit(params[key]);
+        }
+      } else if (params[key] !== undefined && params[key] !== null && params[key] !== "") {
+        picked[key] = String(params[key]);
+      }
     }
   }
 
   return picked;
 }
 
+function normalizeListLimit(value) {
+  const numeric = typeof value === "number" ? value : typeof value === "string" && value.trim() !== "" ? Number(value) : NaN;
+
+  if (!Number.isInteger(numeric) || numeric < 1 || numeric > 100) {
+    throw new ReadbackError("List resources limit must be an integer from 1 to 100.", {
+      code: "invalid-list-limit"
+    });
+  }
+
+  return numeric;
+}
+
 function pickContextBundleParams(params) {
   return pickAllowedParams(params, ["intent", "audience", "limit"]);
 }

package/src/download.mjs

@@ -0,0 +1,401 @@
+import { createWriteStream } from "node:fs";
+import { mkdir, rename, rm, stat } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { Readable, Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { ReadbackError, normalizeDownloadMetadata } from "./client.mjs";
+
+const DEFAULT_MAX_REDIRECTS = 3;
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+const WINDOWS_RESERVED_NAMES = /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\..*)?$/i;
+const UNSAFE_FILENAME_PATTERN = /[<>:"/\\|?*\x00-\x1f]/;
+
+export async function downloadResourceArtifact(options = {}) {
+  if (!options || typeof options !== "object" || Array.isArray(options)) {
+    throw new ReadbackError("Download options are required.", { code: "invalid-download-options" });
+  }
+
+  const metadata = await resolveMetadata(options);
+  const normalized = isNormalizedDownloadMetadata(metadata) ? metadata : normalizeDownloadMetadata(metadata);
+
+  if (normalized.availability !== "available") {
+    throw new ReadbackError("Download is not available for this resource.", {
+      code: "download-unavailable"
+    });
+  }
+  if (!normalized.url) {
+    throw new ReadbackError("Download metadata is missing a public URL.", {
+      code: "missing-download-url"
+    });
+  }
+  if (normalized.digestPresent && !normalized.digestValid) {
+    throw new ReadbackError("Download metadata includes an invalid digest.", {
+      code: "invalid-download-digest"
+    });
+  }
+
+  const maxBytes = normalizeMaxBytes(options.maxBytes);
+  if (maxBytes !== null && normalized.sizeBytes !== null && normalized.sizeBytes > maxBytes) {
+    throw new ReadbackError("Download exceeds the configured maximum byte count.", {
+      code: "download-too-large"
+    });
+  }
+
+  const initialUrl = parseSafeDownloadUrl(normalized.url);
+  const target = await resolveOutputTarget({
+    cwd: options.cwd,
+    outputPath: options.outputPath,
+    filename: normalized.filename,
+    url: initialUrl,
+    force: options.force === true
+  });
+
+  let tempPath = target.tempPath;
+  try {
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    if (typeof fetchImpl !== "function") {
+      throw new ReadbackError("A fetch implementation is required.", { code: "missing-fetch" });
+    }
+
+    const { response } = await fetchWithSafeRedirects(initialUrl, {
+      fetchImpl,
+      allowedRedirectOrigins: options.allowedRedirectOrigins,
+      maxRedirects: options.maxRedirects
+    });
+
+    if (!response.ok) {
+      throw new ReadbackError("Download request failed.", {
+        code: "download-http-error",
+        status: response.status
+      });
+    }
+
+    validateContentLength(response.headers?.get?.("content-length") ?? null, {
+      expectedSize: normalized.sizeBytes,
+      maxBytes
+    });
+
+    const digest = prepareDigest(normalized.digest);
+    const result = await streamResponseToTempFile(response, tempPath, {
+      digest,
+      maxBytes
+    });
+
+    if (normalized.sizeBytes !== null && result.bytesWritten !== normalized.sizeBytes) {
+      throw new ReadbackError("Downloaded byte count does not match metadata.", {
+        code: "download-size-mismatch"
+      });
+    }
+    if (digest && result.digestValue !== digest.value) {
+      throw new ReadbackError("Downloaded digest does not match metadata.", {
+        code: "download-digest-mismatch"
+      });
+    }
+
+    if (!options.force && (await pathExists(target.finalPath))) {
+      throw new ReadbackError("Output file already exists.", { code: "output-exists" });
+    }
+
+    await rename(tempPath, target.finalPath);
+    tempPath = null;
+
+    return Object.freeze({
+      ok: true,
+      resourceId: normalized.resourceId,
+      outputPath: target.finalPath,
+      filename: target.filename,
+      bytesWritten: result.bytesWritten,
+      digest: digest ? Object.freeze({ algorithm: digest.algorithm, value: result.digestValue }) : null,
+      mediaType: normalized.mediaType
+    });
+  } catch (error) {
+    if (tempPath) {
+      await rm(tempPath, { force: true });
+    }
+    if (error instanceof ReadbackError) {
+      throw error;
+    }
+    throw new ReadbackError("Download failed.", {
+      code: "download-failed",
+      cause: error
+    });
+  }
+}
+
+async function resolveMetadata(options) {
+  if (options.metadata) {
+    return options.metadata;
+  }
+  if (!options.client || typeof options.client.getDownloadMetadata !== "function") {
+    throw new ReadbackError("Download metadata or a readback client is required.", {
+      code: "missing-download-metadata"
+    });
+  }
+  if (typeof options.resourceId !== "string" || options.resourceId.trim() === "") {
+    throw new ReadbackError("Resource id is required.", { code: "missing-resource-id" });
+  }
+  return options.client.getDownloadMetadata(options.resourceId);
+}
+
+function isNormalizedDownloadMetadata(value) {
+  return Boolean(
+    value &&
+      typeof value === "object" &&
+      !Array.isArray(value) &&
+      typeof value.availability === "string" &&
+      Object.hasOwn(value, "digestPresent") &&
+      Object.hasOwn(value, "digestValid")
+  );
+}
+
+function normalizeMaxBytes(value) {
+  if (value === undefined || value === null) {
+    return null;
+  }
+  const numeric = typeof value === "number" ? value : typeof value === "string" && value.trim() !== "" ? Number(value) : NaN;
+  if (!Number.isSafeInteger(numeric) || numeric < 1) {
+    throw new ReadbackError("maxBytes must be a positive safe integer.", {
+      code: "invalid-max-bytes"
+    });
+  }
+  return numeric;
+}
+
+function parseSafeDownloadUrl(value) {
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch (error) {
+    throw new ReadbackError("Download URL is invalid.", {
+      code: "unsafe-download-url",
+      cause: error
+    });
+  }
+
+  if (parsed.protocol === "https:" || (parsed.protocol === "http:" && LOOPBACK_HOSTS.has(parsed.hostname))) {
+    parsed.hash = "";
+    return parsed;
+  }
+
+  throw new ReadbackError("Download URL must use HTTPS outside loopback development.", {
+    code: "unsafe-download-url"
+  });
+}
+
+async function resolveOutputTarget({ cwd, outputPath, filename, url, force }) {
+  if (typeof outputPath !== "string" || outputPath.trim() === "") {
+    throw new ReadbackError("An output path is required.", { code: "missing-output-path" });
+  }
+  if (hasParentPathSegment(outputPath)) {
+    throw new ReadbackError("Output path must not contain parent-directory traversal.", {
+      code: "unsafe-output-path"
+    });
+  }
+
+  const baseCwd = cwd ? path.resolve(cwd) : process.cwd();
+  const resolvedOutput = path.resolve(baseCwd, outputPath);
+  const directoryMode = outputPath.endsWith("/") || outputPath.endsWith("\\") || (await isDirectory(resolvedOutput));
+  const finalPath = directoryMode
+    ? path.resolve(resolvedOutput, validateSafeFilename(filename || filenameFromUrl(url)))
+    : resolvedOutput;
+  const outputRoot = directoryMode ? resolvedOutput : path.dirname(finalPath);
+  const finalName = path.basename(finalPath);
+
+  validateSafeFilename(finalName);
+  assertPathInside(outputRoot, finalPath);
+  await mkdir(path.dirname(finalPath), { recursive: true });
+
+  if (!force && (await pathExists(finalPath))) {
+    throw new ReadbackError("Output file already exists.", { code: "output-exists" });
+  }
+
+  const tempPath = path.join(path.dirname(finalPath), `.${finalName}.${process.pid}.${Date.now()}.tmp`);
+  return { finalPath, tempPath, filename: finalName };
+}
+
+async function isDirectory(value) {
+  try {
+    return (await stat(value)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+async function pathExists(value) {
+  try {
+    await stat(value);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function validateSafeFilename(value) {
+  if (
+    typeof value !== "string" ||
+    value.trim() === "" ||
+    value === "." ||
+    value === ".." ||
+    value.includes("/") ||
+    value.includes("\\") ||
+    UNSAFE_FILENAME_PATTERN.test(value) ||
+    WINDOWS_RESERVED_NAMES.test(value)
+  ) {
+    throw new ReadbackError("Download filename is unsafe.", { code: "unsafe-output-filename" });
+  }
+  return value;
+}
+
+function filenameFromUrl(url) {
+  const name = path.basename(decodeURIComponent(url.pathname));
+  if (!name || name === "/" || name === ".") {
+    throw new ReadbackError("Download metadata is missing a safe filename.", {
+      code: "missing-download-filename"
+    });
+  }
+  return name;
+}
+
+function assertPathInside(root, target) {
+  const relative = path.relative(path.resolve(root), path.resolve(target));
+  if (relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative))) {
+    return;
+  }
+  throw new ReadbackError("Output path escapes the selected output directory.", {
+    code: "unsafe-output-path"
+  });
+}
+
+function hasParentPathSegment(value) {
+  return String(value)
+    .split(/[\\/]+/)
+    .some((segment) => segment === "..");
+}
+
+async function fetchWithSafeRedirects(initialUrl, { fetchImpl, allowedRedirectOrigins, maxRedirects }) {
+  const allowedOrigins = new Set([initialUrl.origin, ...(Array.isArray(allowedRedirectOrigins) ? allowedRedirectOrigins : [])]);
+  const redirectLimit = maxRedirects === undefined ? DEFAULT_MAX_REDIRECTS : normalizeRedirectLimit(maxRedirects);
+  let current = initialUrl;
+
+  for (let redirectCount = 0; redirectCount <= redirectLimit; redirectCount += 1) {
+    const response = await fetchImpl(current, {
+      method: "GET",
+      redirect: "manual"
+    });
+
+    if (!isRedirect(response.status)) {
+      return { response, url: current };
+    }
+
+    const location = response.headers?.get?.("location");
+    if (!location) {
+      throw new ReadbackError("Download redirect is missing a location.", {
+        code: "unsafe-download-redirect"
+      });
+    }
+    if (redirectCount === redirectLimit) {
+      throw new ReadbackError("Download redirect limit exceeded.", {
+        code: "download-redirect-limit"
+      });
+    }
+
+    const next = parseSafeDownloadUrl(new URL(location, current).href);
+    if (!allowedOrigins.has(next.origin)) {
+      throw new ReadbackError("Download redirect target is not allowed.", {
+        code: "unsafe-download-redirect"
+      });
+    }
+    current = next;
+  }
+
+  throw new ReadbackError("Download redirect limit exceeded.", {
+    code: "download-redirect-limit"
+  });
+}
+
+function normalizeRedirectLimit(value) {
+  if (!Number.isInteger(value) || value < 0 || value > 10) {
+    throw new ReadbackError("maxRedirects must be an integer from 0 to 10.", {
+      code: "invalid-redirect-limit"
+    });
+  }
+  return value;
+}
+
+function isRedirect(status) {
+  return [301, 302, 303, 307, 308].includes(status);
+}
+
+function validateContentLength(value, { expectedSize, maxBytes }) {
+  if (value === null || value === "") {
+    return;
+  }
+  const contentLength = Number(value);
+  if (!Number.isSafeInteger(contentLength) || contentLength < 0) {
+    throw new ReadbackError("Download response has an invalid content length.", {
+      code: "download-size-mismatch"
+    });
+  }
+  if (expectedSize !== null && contentLength !== expectedSize) {
+    throw new ReadbackError("Download content length does not match metadata.", {
+      code: "download-size-mismatch"
+    });
+  }
+  if (maxBytes !== null && contentLength > maxBytes) {
+    throw new ReadbackError("Download exceeds the configured maximum byte count.", {
+      code: "download-too-large"
+    });
+  }
+}
+
+function prepareDigest(value) {
+  if (!value) {
+    return null;
+  }
+  const algorithm = value.algorithm === "sha-256" ? "sha256" : value.algorithm;
+  try {
+    createHash(algorithm);
+  } catch (error) {
+    throw new ReadbackError("Download digest algorithm is not supported.", {
+      code: "unsupported-download-digest",
+      cause: error
+    });
+  }
+  return { algorithm, value: value.value };
+}
+
+async function streamResponseToTempFile(response, tempPath, { digest, maxBytes }) {
+  if (!response.body) {
+    throw new ReadbackError("Download response is missing a body.", {
+      code: "download-empty-body"
+    });
+  }
+
+  let bytesWritten = 0;
+  const hash = digest ? createHash(digest.algorithm) : null;
+  const counter = new Transform({
+    transform(chunk, _encoding, callback) {
+      const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+      bytesWritten += buffer.length;
+      if (maxBytes !== null && bytesWritten > maxBytes) {
+        callback(
+          new ReadbackError("Download exceeds the configured maximum byte count.", {
+            code: "download-too-large"
+          })
+        );
+        return;
+      }
+      hash?.update(buffer);
+      callback(null, buffer);
+    }
+  });
+
+  const readable = typeof response.body.getReader === "function" ? Readable.fromWeb(response.body) : response.body;
+  await pipeline(readable, counter, createWriteStream(tempPath, { flags: "wx" }));
+
+  return {
+    bytesWritten,
+    digestValue: hash ? hash.digest("hex") : null
+  };
+}

package/src/index.mjs

@@ -2,7 +2,12 @@ export {
   ReadbackError,
   assertReadOnlyClientSurface,
   createReadbackClient,
+  normalizeDownloadMetadata,
+  normalizeParserVariantReadback,
+  normalizeResourceList,
+  normalizeTrustReadback,
   normalizeBaseUrl,
   normalizePublicReadback
 } from "./client.mjs";
 export { createBadgeMarkdown, createBadgeState, listBadgeStates } from "./badge.mjs";
+export { downloadResourceArtifact } from "./download.mjs";