@knolo/cli 5.2.1 → 5.2.3

package/bin/registry/commands.mjs

@@ -1,19 +1,59 @@
-import { chmod, copyFile, lstat, mkdir, readFile, rename, unlink } from 'node:fs/promises';
+import {
+  chmod,
+  copyFile,
+  lstat,
+  mkdir,
+  readFile,
+  rename,
+  unlink,
+} from 'node:fs/promises';
 import { createHash, randomUUID } from 'node:crypto';
+import { isIP } from 'node:net';
 import { homedir } from 'node:os';
 import path from 'node:path';
-import { registryApiUrl, resolveRegistryUrl } from './config.mjs';
-import { downloadBlobToTemp, MAX_ARTIFACT_BYTES, readArtifact, stageCachedArtifact } from './artifacts.mjs';
+import {
+  normalizeRegistryUrl,
+  registryApiUrl,
+  resolveRegistryUrl,
+} from './config.mjs';
+import {
+  downloadBlobToTemp,
+  MAX_ARTIFACT_BYTES,
+  readArtifact,
+  stageCachedArtifact,
+} from './artifacts.mjs';
 import { RegistryError } from './errors.mjs';
 import { getJson, postJson, putBytes } from './http.mjs';
-import { cachePath, stageLockfileUpdate, validateLockfileUpdate } from './lockfile.mjs';
+import {
+  cachePath,
+  stageLockfileUpdate,
+  validateLockfileUpdate,
+} from './lockfile.mjs';
 import { validatePackManifest } from './manifest.mjs';
 import { parsePackName, parsePackSpec } from './specs.mjs';
-import { loadCredentials, promptForToken, removeCredentials, saveCredentials, validateToken } from './credentials.mjs';
+import {
+  loadCredentials,
+  promptForToken,
+  removeCredentials,
+  saveCredentials,
+  validateToken,
+} from './credentials.mjs';
 
 const PACK_SHA256_PATTERN = /^[0-9a-f]{64}$/;
-
-export async function runHubSearch(args, { env = process.env, fetchImpl = globalThis.fetch, print = console.log } = {}) {
+const LOCAL_ONLY_HOSTNAMES = new Set([
+  'localhost',
+  'localhost.localdomain',
+  'ip6-localhost',
+  'ip6-loopback',
+  'broadcasthost',
+  'local',
+  'internal',
+]);
+
+export async function runHubSearch(
+  args,
+  { env = process.env, fetchImpl = globalThis.fetch, print = console.log } = {}
+) {
   const { query, flags } = parseSearchArgs(args);
   const registry = resolveRegistryUrl({ value: flags.registry, env });
   const url = registryApiUrl(registry, ['packs'], {
@@ -32,7 +72,10 @@ export async function runHubSearch(args, { env = process.env, fetchImpl = global
   return { registry, url: String(url), body };
 }
 
-export async function runHubInfo(args, { env = process.env, fetchImpl = globalThis.fetch, print = console.log } = {}) {
+export async function runHubInfo(
+  args,
+  { env = process.env, fetchImpl = globalThis.fetch, print = console.log } = {}
+) {
   const { positional, flags } = parseInfoArgs(args);
   const pack = parsePackName(positional[0]);
   const registry = resolveRegistryUrl({ value: flags.registry, env });
@@ -46,31 +89,52 @@ export async function runHubInfo(args, { env = process.env, fetchImpl = globalTh
   return { registry, url: String(url), body };
 }
 
-export async function runHubAdd(args, {
-  env = process.env,
-  fetchImpl = globalThis.fetch,
-  core,
-  cwd = process.cwd(),
-  homeDir,
-  print = console.log,
-  warn = console.error,
-} = {}) {
+export async function runHubAdd(
+  args,
+  {
+    env = process.env,
+    fetchImpl = globalThis.fetch,
+    core,
+    cwd = process.cwd(),
+    homeDir,
+    print = console.log,
+    warn = console.error,
+  } = {}
+) {
   const { spec, flags } = parseAddArgs(args);
-  if (!core) throw new Error('Could not load @knolo/core for Hub artifact validation.');
+  if (!core)
+    throw new Error('Could not load @knolo/core for Hub artifact validation.');
   const registry = resolveRegistryUrl({ value: flags.registry, env });
-  const manifestUrl = registryApiUrl(registry, ['packs', spec.publisher, spec.slug, spec.version]);
+  const manifestUrl = registryApiUrl(registry, [
+    'packs',
+    spec.publisher,
+    spec.slug,
+    spec.version,
+  ]);
 
   let manifest;
   let yanked = false;
   try {
     const body = await getJson(manifestUrl, { fetchImpl });
-    manifest = validatePackManifest(body, { expectedName: spec.name, requestedVersion: spec.version });
+    manifest = validatePackManifest(body, {
+      expectedName: spec.name,
+      requestedVersion: spec.version,
+    });
   } catch (error) {
-    if (error instanceof RegistryError && (error.status === 404 || error.code === 'not_found')) {
+    if (
+      error instanceof RegistryError &&
+      (error.status === 404 || error.code === 'not_found')
+    ) {
       throw new Error('pack version not found');
     }
-    if (error instanceof RegistryError && (error.status === 410 || error.code === 'yanked')) {
-      manifest = validatePackManifest(error.body, { expectedName: spec.name, requestedVersion: spec.version });
+    if (
+      error instanceof RegistryError &&
+      (error.status === 410 || error.code === 'yanked')
+    ) {
+      manifest = validatePackManifest(error.body, {
+        expectedName: spec.name,
+        requestedVersion: spec.version,
+      });
       yanked = true;
     } else {
       throw error;
@@ -78,10 +142,15 @@ export async function runHubAdd(args, {
   }
 
   if (manifest.yanked) yanked = true;
-  if (yanked && !flags.force) throw new Error('version yanked; use --force to download yanked bytes');
-  if (yanked) warn(`warning: downloading yanked version ${manifest.name}@${manifest.version}`);
+  if (yanked && !flags.force)
+    throw new Error('version yanked; use --force to download yanked bytes');
+  if (yanked)
+    warn(
+      `warning: downloading yanked version ${manifest.name}@${manifest.version}`
+    );
   if (!manifest.url) throw new Error('artifact bytes are not stored yet');
-  if (!PACK_SHA256_PATTERN.test(manifest.sha256)) throw new Error('manifest sha256 is invalid');
+  if (!PACK_SHA256_PATTERN.test(manifest.sha256))
+    throw new Error('manifest sha256 is invalid');
 
   const artifactHome = homeDir || homedir();
   await validateLockfileUpdate({ cwd, registry, manifest, force: flags.force });
@@ -95,29 +164,56 @@ export async function runHubAdd(args, {
   const stagedFiles = [];
   try {
     if (download.sha256 !== manifest.sha256) {
-      throw new Error(`artifact sha256 mismatch: expected ${manifest.sha256}, got ${download.sha256}`);
+      throw new Error(
+        `artifact sha256 mismatch: expected ${manifest.sha256}, got ${download.sha256}`
+      );
     }
     const bytes = await readArtifact(download.tempPath);
     const validation = await validateKnowledgeImage(core, bytes);
-    if (manifest.format && String(manifest.format).toUpperCase() !== validation.format) {
-      throw new Error(`artifact format mismatch: manifest=${manifest.format}, bytes=${validation.format}`);
+    if (
+      manifest.format &&
+      String(manifest.format).toUpperCase() !== validation.format
+    ) {
+      throw new Error(
+        `artifact format mismatch: manifest=${manifest.format}, bytes=${validation.format}`
+      );
     }
     if (validation.format === 'V5' && !manifest.stateRoot) {
       throw new Error('V5 artifact requires manifest stateRoot.');
     }
-    if (manifest.stateRoot !== undefined && manifest.stateRoot !== validation.stateRoot) {
-      throw new Error(`artifact stateRoot mismatch: expected ${manifest.stateRoot}, got ${validation.stateRoot || 'none'}`);
+    if (
+      manifest.stateRoot !== undefined &&
+      manifest.stateRoot !== validation.stateRoot
+    ) {
+      throw new Error(
+        `artifact stateRoot mismatch: expected ${manifest.stateRoot}, got ${validation.stateRoot || 'none'}`
+      );
     }
-    const stagedCachePath = await stageCachedArtifact(download.tempPath, finalCachePath);
+    const stagedCachePath = await stageCachedArtifact(
+      download.tempPath,
+      finalCachePath
+    );
     stagedFiles.push({ targetPath: finalCachePath, tempPath: stagedCachePath });
     let outputPath = finalCachePath;
     if (flags.out) {
-      const stagedOutput = await stageArtifactCopy(download.tempPath, flags.out, cwd);
+      const stagedOutput = await stageArtifactCopy(
+        download.tempPath,
+        flags.out,
+        cwd
+      );
       stagedFiles.push(stagedOutput);
       outputPath = stagedOutput.targetPath;
     }
-    const stagedLock = await stageLockfileUpdate({ cwd, registry, manifest, force: flags.force });
-    stagedFiles.push({ targetPath: stagedLock.path, tempPath: stagedLock.tempPath });
+    const stagedLock = await stageLockfileUpdate({
+      cwd,
+      registry,
+      manifest,
+      force: flags.force,
+    });
+    stagedFiles.push({
+      targetPath: stagedLock.path,
+      tempPath: stagedLock.tempPath,
+    });
     await commitStagedFiles(stagedFiles);
     const lock = { path: stagedLock.path, entry: stagedLock.entry };
     const result = { ...manifest, path: outputPath, lockfile: lock.path };
@@ -131,21 +227,31 @@ export async function runHubAdd(args, {
     return result;
   } finally {
     await unlinkIfPresent(download.tempPath);
-    await Promise.all(stagedFiles.map(({ tempPath }) => unlinkIfPresent(tempPath)));
+    await Promise.all(
+      stagedFiles.map(({ tempPath }) => unlinkIfPresent(tempPath))
+    );
   }
 }
 
-export async function runHubLogin(args, {
-  env = process.env,
-  homeDir,
-  input = process.stdin,
-  output = process.stderr,
-  print = console.log,
-} = {}) {
+export async function runHubLogin(
+  args,
+  {
+    env = process.env,
+    homeDir,
+    input = process.stdin,
+    output = process.stderr,
+    print = console.log,
+  } = {}
+) {
   const { flags } = parseLoginArgs(args);
   const registry = resolveRegistryUrl({ value: flags.registry, env });
-  print(`Create a token at ${registry}/dashboard/tokens (Sign in with GitHub).`);
-  const token = (flags.token ?? await promptForToken({ input, output, forceStdin: flags.stdin })).trim();
+  print(
+    `Create a token at ${registry}/dashboard/tokens (Sign in with GitHub).`
+  );
+  const token = (
+    flags.token ??
+    (await promptForToken({ input, output, forceStdin: flags.stdin }))
+  ).trim();
   validateToken(token);
   const saved = await saveCredentials({ registry, token, env, homeDir });
   print(`logged in to ${saved.registry}`);
@@ -154,7 +260,10 @@ export async function runHubLogin(args, {
   return saved;
 }
 
-export async function runHubWhoami(args, { env = process.env, homeDir, print = console.log } = {}) {
+export async function runHubWhoami(
+  args,
+  { env = process.env, homeDir, print = console.log } = {}
+) {
   if (args.length) throw new Error('Usage: knolo whoami');
   const credentials = await loadCredentials({ env, homeDir });
   print(`registry ${credentials.registry}`);
@@ -162,69 +271,114 @@ export async function runHubWhoami(args, { env = process.env, homeDir, print = c
   return { registry: credentials.registry, prefix: credentials.prefix };
 }
 
-export async function runHubLogout(args, { env = process.env, homeDir, print = console.log } = {}) {
+export async function runHubLogout(
+  args,
+  { env = process.env, homeDir, print = console.log } = {}
+) {
   if (args.length) throw new Error('Usage: knolo logout');
   const result = await removeCredentials({ env, homeDir });
   print(result.removed ? 'logged out' : 'not logged in');
   return result;
 }
 
-export async function runHubPublish(args, {
-  env = process.env,
-  fetchImpl = globalThis.fetch,
-  cwd = process.cwd(),
-  homeDir,
-  print = console.log,
-  sleep = wait,
-  pollIntervalMs = 1000,
-  maxPollAttempts = 120,
-} = {}) {
+export async function runHubPublish(
+  args,
+  {
+    env = process.env,
+    fetchImpl = globalThis.fetch,
+    cwd = process.cwd(),
+    homeDir,
+    print = console.log,
+    sleep = wait,
+    pollIntervalMs = 1000,
+    maxPollAttempts = 120,
+  } = {}
+) {
   const { packPath, flags } = parsePublishArgs(args);
   const credentials = await loadCredentials({ env, homeDir });
-  const registry = resolveRegistryUrl({ value: flags.registry || credentials.registry, env });
+  const registry = resolveCredentialRegistry(
+    flags.registry,
+    credentials.registry
+  );
   const authHeaders = authorizationHeaders(credentials.token);
 
   // This request is deliberately first: it proves the stored dashboard token
   // is a Hub Bearer credential before any upload or publish mutation starts.
-  const account = await getJson(registryApiUrl(registry, ['account']), { fetchImpl, headers: authHeaders });
+  const account = await getJson(registryApiUrl(registry, ['account']), {
+    fetchImpl,
+    headers: authHeaders,
+  });
   const accountPublisher = extractPublisherHandle(account);
-  if (flags.publisher && accountPublisher && flags.publisher !== accountPublisher) {
-    throw new Error(`Token is scoped to publisher ${accountPublisher}, not ${flags.publisher}.`);
+  if (
+    flags.publisher &&
+    accountPublisher &&
+    flags.publisher !== accountPublisher
+  ) {
+    throw new Error(
+      `Token is scoped to publisher ${accountPublisher}, not ${flags.publisher}.`
+    );
   }
   const publisher = flags.publisher || accountPublisher;
 
   const packFile = path.resolve(cwd, packPath);
   const bytes = await readFile(packFile);
-  if (bytes.length > MAX_ARTIFACT_BYTES) throw new Error('Artifact exceeds Hub’s 250 MB limit.');
+  if (bytes.length > MAX_ARTIFACT_BYTES)
+    throw new Error('Artifact exceeds Hub’s 250 MB limit.');
   const sha256 = createSha256(bytes);
+  const pathname = `sha256/${sha256}.knolo`;
+
+  const grant = await postJson(
+    hubApiUrl(registry, ['upload', 'token']),
+    { sha256, contentLength: bytes.length },
+    { fetchImpl, headers: authHeaders }
+  );
+  const upload = resolveUploadGrant(grant, sha256);
+  let blobUrl;
+  if (upload.reused) {
+    blobUrl = assertPublicPackBlobUrl(upload.url, 'reused artifact').toString();
+  } else {
+    assertGrantPutUrl(upload.putUrl, 'upload grant');
+    const uploaded = await putBytes(upload.putUrl, bytes, {
+      fetchImpl,
+      headers: {
+        'content-type': 'application/octet-stream',
+        ...(upload.putHeaders || {}),
+        'content-length': String(bytes.length),
+      },
+    });
+    if (uploaded.pathname !== undefined && uploaded.pathname !== pathname) {
+      throw new Error(
+        `Public Blob upload pathname is not locked to ${pathname}.`
+      );
+    }
+    blobUrl = assertPublicPackBlobUrl(
+      uploaded.url,
+      'uploaded artifact'
+    ).toString();
+  }
 
-  const uploadToken = await postJson(hubApiUrl(registry, ['upload', 'token']), {
-    sha256,
-    contentLength: bytes.length,
-  }, { fetchImpl, headers: authHeaders });
-  const upload = validateUploadTokenResponse(uploadToken, sha256);
-  assertPublicBlobUrl(upload.url, 'upload');
-  const uploaded = await putBytes(upload.url, bytes, {
-    fetchImpl,
-    headers: { 'content-length': String(bytes.length) },
-  });
-  assertPublicBlobUrl(uploaded.url, 'uploaded artifact');
-
-  const completed = await postJson(hubApiUrl(registry, ['upload', 'complete']), {
-    sha256,
-    url: upload.url,
-    sizeBytes: bytes.length,
-    pathname: upload.pathname,
-  }, { fetchImpl, headers: authHeaders });
-  const blobUrl = extractBlobUrl(completed) || upload.url;
-  assertPublicBlobUrl(blobUrl, 'completed upload');
-
-  const verifyResponse = await postJson(registryApiUrl(registry, ['publish', 'verify']), { sha256 }, {
-    fetchImpl,
-    headers: authHeaders,
-  });
+  await postJson(
+    hubApiUrl(registry, ['upload', 'complete']),
+    {
+      sha256,
+      url: blobUrl,
+      sizeBytes: bytes.length,
+      pathname,
+    },
+    { fetchImpl, headers: authHeaders }
+  );
+
+  const verifyResponse = await postJson(
+    registryApiUrl(registry, ['publish', 'verify']),
+    { sha256 },
+    {
+      fetchImpl,
+      headers: authHeaders,
+    }
+  );
   const jobId = extractId(verifyResponse, ['jobId', 'id', 'job']);
-  if (!jobId) throw new Error('Hub verify response did not include a publish job id.');
+  if (!jobId)
+    throw new Error('Hub verify response did not include a publish job id.');
   const job = await waitForPublishJob(registry, jobId, {
     fetchImpl,
     headers: authHeaders,
@@ -241,19 +395,30 @@ export async function runHubPublish(args, {
     attested: true,
     ...(flags.readme !== undefined ? { readme: flags.readme } : {}),
     ...(flags.sources !== undefined ? { sources: flags.sources } : {}),
-    ...(flags.intendedUse !== undefined ? { intendedUse: flags.intendedUse } : {}),
+    ...(flags.intendedUse !== undefined
+      ? { intendedUse: flags.intendedUse }
+      : {}),
   };
-  const draftResponse = await postJson(registryApiUrl(registry, ['publish', 'drafts']), draftPayload, {
-    fetchImpl,
-    headers: authHeaders,
-  });
+  const draftResponse = await postJson(
+    registryApiUrl(registry, ['publish', 'drafts']),
+    draftPayload,
+    {
+      fetchImpl,
+      headers: authHeaders,
+    }
+  );
   const draftId = extractId(draftResponse, ['draftId', 'id', 'draft']);
-  if (!draftId) throw new Error('Hub draft response did not include a draft id.');
-
-  const releaseResponse = await postJson(registryApiUrl(registry, ['publish', 'drafts', draftId, 'release']), undefined, {
-    fetchImpl,
-    headers: authHeaders,
-  });
+  if (!draftId)
+    throw new Error('Hub draft response did not include a draft id.');
+
+  const releaseResponse = await postJson(
+    registryApiUrl(registry, ['publish', 'drafts', draftId, 'release']),
+    undefined,
+    {
+      fetchImpl,
+      headers: authHeaders,
+    }
+  );
   const name = `${publisher ? `${publisher}/` : ''}${flags.slug}`;
   const result = {
     registry,
@@ -263,7 +428,7 @@ export async function runHubPublish(args, {
     version: flags.version,
     sha256,
     sizeBytes: bytes.length,
-    pathname: upload.pathname,
+    pathname,
     url: blobUrl,
     jobId: String(jobId),
     draftId: String(draftId),
@@ -281,19 +446,35 @@ export async function runHubPublish(args, {
   return result;
 }
 
-export async function runHubYank(args, {
-  env = process.env,
-  fetchImpl = globalThis.fetch,
-  homeDir,
-  print = console.log,
-} = {}) {
+export async function runHubYank(
+  args,
+  {
+    env = process.env,
+    fetchImpl = globalThis.fetch,
+    homeDir,
+    print = console.log,
+  } = {}
+) {
   const { spec, flags } = parseYankArgs(args);
   const credentials = await loadCredentials({ env, homeDir });
-  const registry = resolveRegistryUrl({ value: flags.registry || credentials.registry, env });
-  const response = await postJson(registryApiUrl(registry, ['packs', spec.publisher, spec.slug, spec.version, 'yank']), undefined, {
-    fetchImpl,
-    headers: authorizationHeaders(credentials.token),
-  });
+  const registry = resolveCredentialRegistry(
+    flags.registry,
+    credentials.registry
+  );
+  const response = await postJson(
+    registryApiUrl(registry, [
+      'packs',
+      spec.publisher,
+      spec.slug,
+      spec.version,
+      'yank',
+    ]),
+    undefined,
+    {
+      fetchImpl,
+      headers: authorizationHeaders(credentials.token),
+    }
+  );
   const result = {
     registry,
     name: spec.name,
@@ -326,21 +507,37 @@ export function parsePublishArgs(args) {
     }
     if (valueFlags.has(arg)) {
       const value = args[++i];
-      if (value === undefined || value.startsWith('--')) throw new Error(`Missing value for ${arg}`);
+      if (value === undefined || value.startsWith('--'))
+        throw new Error(`Missing value for ${arg}`);
       flags[valueFlags.get(arg)] = value;
       continue;
     }
-    if (arg.startsWith('--')) throw new Error(`Unknown flag for publish: ${arg}`);
+    if (arg.startsWith('--'))
+      throw new Error(`Unknown flag for publish: ${arg}`);
     positional.push(arg);
   }
 
-  if (positional.length !== 1 || !flags.slug || !flags.version || !flags.license) {
-    throw new Error('Usage: knolo publish <pack.knolo> --slug <slug> --version <version> --license <SPDX> [--publisher <handle>] [--readme <text>] [--sources <text>] [--intended-use <text>] [--json] [--registry <url>]');
+  if (
+    positional.length !== 1 ||
+    !flags.slug ||
+    !flags.version ||
+    !flags.license
+  ) {
+    throw new Error(
+      'Usage: knolo publish <pack.knolo> --slug <slug> --version <version> --license <SPDX> [--publisher <handle>] [--readme <text>] [--sources <text>] [--intended-use <text>] [--json] [--registry <url>]'
+    );
   }
-  if (!/^[a-z0-9-]+$/.test(flags.slug)) throw new Error('Publish slug must contain lowercase letters, numbers, and hyphens.');
-  if (!flags.version.trim() || flags.version.includes('@')) throw new Error('Publish version must be a non-empty version without @.');
+  if (!/^[a-z0-9-]+$/.test(flags.slug))
+    throw new Error(
+      'Publish slug must contain lowercase letters, numbers, and hyphens.'
+    );
+  if (!flags.version.trim() || flags.version.includes('@'))
+    throw new Error('Publish version must be a non-empty version without @.');
   if (!flags.license.trim()) throw new Error('Publish license is required.');
-  if (flags.publisher && !/^[a-z0-9-]+$/.test(flags.publisher)) throw new Error('Publish publisher must contain lowercase letters, numbers, and hyphens.');
+  if (flags.publisher && !/^[a-z0-9-]+$/.test(flags.publisher))
+    throw new Error(
+      'Publish publisher must contain lowercase letters, numbers, and hyphens.'
+    );
   return { packPath: positional[0], flags };
 }
 
@@ -355,16 +552,23 @@ export function parseYankArgs(args) {
     }
     if (arg === '--registry') {
       const value = args[++i];
-      if (value === undefined || value.startsWith('--')) throw new Error('Missing value for --registry');
+      if (value === undefined || value.startsWith('--'))
+        throw new Error('Missing value for --registry');
       flags.registry = value;
       continue;
     }
     if (arg.startsWith('--')) throw new Error(`Unknown flag for yank: ${arg}`);
     positional.push(arg);
   }
-  if (positional.length !== 1) throw new Error('Usage: knolo yank <publisher>/<slug>@<version> [--json] [--registry <url>]');
+  if (positional.length !== 1)
+    throw new Error(
+      'Usage: knolo yank <publisher>/<slug>@<version> [--json] [--registry <url>]'
+    );
   const spec = parsePackSpec(positional[0]);
-  if (spec.version === 'latest') throw new Error('Yank requires an exact version: <publisher>/<slug>@<version>.');
+  if (spec.version === 'latest')
+    throw new Error(
+      'Yank requires an exact version: <publisher>/<slug>@<version>.'
+    );
   return { spec, flags };
 }
 
@@ -372,6 +576,18 @@ function authorizationHeaders(token) {
   return { Authorization: `Bearer ${token}` };
 }
 
+function resolveCredentialRegistry(requestedRegistry, storedRegistry) {
+  const stored = normalizeRegistryUrl(storedRegistry);
+  if (!requestedRegistry) return stored;
+  const requested = normalizeRegistryUrl(requestedRegistry);
+  if (requested !== stored) {
+    throw new Error(
+      `Stored credentials belong to ${stored}; refusing to send them to ${requested}. Log in to the requested registry first.`
+    );
+  }
+  return requested;
+}
+
 function hubApiUrl(registry, segments) {
   const url = new URL(registry);
   url.pathname = `/api/${segments.map((segment) => encodeURIComponent(String(segment))).join('/')}`;
@@ -382,54 +598,87 @@ function createSha256(bytes) {
   return createHash('sha256').update(bytes).digest('hex');
 }
 
+function resolveUploadGrant(body, sha256) {
+  const pathname = body?.pathname || body?.upload?.pathname;
+  const expectedPathname = `sha256/${sha256}.knolo`;
+  if (typeof pathname !== 'string' || pathname !== expectedPathname) {
+    throw new Error(`Hub upload pathname is not locked to ${expectedPathname}.`);
+  }
+
+  const reusedUrl =
+    (body?.reused && (body?.artifact?.url || body?.url)) ||
+    body?.artifact?.url;
+  if (typeof reusedUrl === 'string' && reusedUrl) {
+    return { reused: true, pathname, url: reusedUrl };
+  }
+
+  const upload = body?.upload && typeof body.upload === 'object' ? body.upload : body;
+  if (!upload || typeof upload.url !== 'string' || !upload.url) {
+    if (body?.clientToken || upload?.clientToken) {
+      throw new Error(
+        'Hub returned a Blob client token without upload.url. This CLI PUTs to upload.url; it does not use PACKS_READ_WRITE_TOKEN.'
+      );
+    }
+    throw new Error('Hub upload token response is missing upload.url.');
+  }
+  return {
+    reused: false,
+    pathname,
+    putUrl: upload.url,
+    putHeaders:
+      upload.headers && typeof upload.headers === 'object' ? upload.headers : {},
+  };
+}
+
+function assertGrantPutUrl(value, label) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new Error(`Hub ${label} URL is invalid.`);
+  }
+  if (url.protocol !== 'https:')
+    throw new Error(`Hub ${label} URL must use HTTPS.`);
+  const hostname = url.hostname.toLowerCase();
+  if (
+    hostname.includes('.private.') ||
+    hostname.startsWith('private.') ||
+    isPrivateOrLocalIp(hostname) ||
+    isLocalOnlyHostname(hostname)
+  ) {
+    throw new Error(
+      `Refusing private Blob URL for ${label}; Hub verification requires a public Blob URL.`
+    );
+  }
+  return url;
+}
+
 function extractPublisherHandle(account) {
   const candidates = [
     account?.publisherHandle,
     account?.publisher?.handle,
     account?.publisher?.slug,
     account?.handle,
+    account?.account?.handle,
     account?.account?.publisherHandle,
     account?.account?.publisher?.handle,
+    account?.user?.handle,
     account?.user?.publisherHandle,
     account?.publishers?.[0]?.handle,
     account?.publishers?.[0]?.slug,
     typeof account?.publisher === 'string' ? account.publisher : undefined,
   ];
-  return candidates.find((value) => typeof value === 'string' && value.trim())?.trim();
-}
-
-function validateUploadTokenResponse(body, sha256) {
-  const upload = body?.upload && typeof body.upload === 'object' ? body.upload : body;
-  if (!upload || typeof upload !== 'object' || typeof upload.url !== 'string' || !upload.url) {
-    if (upload?.clientToken || body?.clientToken) {
-      throw new Error('Hub returned a Blob client token; this CLI requires an upload.url for direct public-Blob PUT.');
-    }
-    throw new Error('Hub upload token response is missing upload.url.');
-  }
-  const pathname = upload.pathname || body?.pathname;
-  if (typeof pathname !== 'string' || !pathname) throw new Error('Hub upload token response is missing upload.pathname.');
-  const expectedPathname = `sha256/${sha256}.knolo`;
-  if (pathname !== expectedPathname) {
-    throw new Error(`Hub upload pathname is not locked to ${expectedPathname}.`);
-  }
-  return { url: upload.url, pathname };
-}
-
-function extractBlobUrl(body) {
-  const candidates = [
-    body?.url,
-    body?.publicUrl,
-    body?.blobUrl,
-    body?.artifact?.url,
-    body?.artifact?.publicUrl,
-    body?.upload?.url,
-    body?.upload?.publicUrl,
-    body?.pack?.url,
-  ];
-  return candidates.find((value) => typeof value === 'string' && value.trim())?.trim();
+  return candidates
+    .find((value) => typeof value === 'string' && value.trim())
+    ?.trim();
 }
 
 function assertPublicBlobUrl(value, label) {
+  if (typeof value !== 'string' || value.includes('.private.')) {
+    throw new Error(
+      `Refusing private Blob URL for ${label}; Hub verification requires a public Blob URL.`
+    );
+  }
   let url;
   try {
     url = new URL(value);
@@ -437,13 +686,136 @@ function assertPublicBlobUrl(value, label) {
     throw new Error(`Hub ${label} URL is invalid.`);
   }
   const hostname = url.hostname.toLowerCase();
-  if (url.protocol !== 'https:') throw new Error(`Hub ${label} URL must use HTTPS.`);
-  if (hostname.includes('.private.') || hostname.startsWith('private.')) {
-    throw new Error(`Refusing private Blob URL for ${label}; Hub verification requires a public Blob URL.`);
+  if (url.protocol !== 'https:')
+    throw new Error(`Hub ${label} URL must use HTTPS.`);
+  if (
+    hostname.includes('.private.') ||
+    hostname.startsWith('private.') ||
+    isPrivateOrLocalIp(hostname)
+  ) {
+    throw new Error(
+      `Refusing private Blob URL for ${label}; Hub verification requires a public Blob URL.`
+    );
+  }
+  if (isLocalOnlyHostname(hostname)) {
+    throw new Error(
+      `Refusing local-only Blob URL for ${label}; Hub verification requires a public Blob URL.`
+    );
+  }
+  return url;
+}
+
+function assertPublicPackBlobUrl(value, label) {
+  const url = assertPublicBlobUrl(value, label);
+  const hostname = url.hostname.toLowerCase();
+  const blobHost =
+    hostname === 'blob.vercel-storage.com' ||
+    hostname.endsWith('.blob.vercel-storage.com');
+  if (!blobHost || hostname.includes('.private.')) {
+    throw new Error(
+      `Hub ${label} URL must be a public Vercel Blob pack URL (not a signed grant URL).`
+    );
   }
   return url;
 }
 
+function isLocalOnlyHostname(hostname) {
+  const normalized = hostname.replace(/^\[|\]$/g, '').replace(/\.$/, '');
+  return (
+    LOCAL_ONLY_HOSTNAMES.has(normalized) ||
+    normalized.endsWith('.localhost') ||
+    normalized.endsWith('.local') ||
+    normalized.endsWith('.internal') ||
+    normalized.endsWith('.home.arpa')
+  );
+}
+
+function isPrivateOrLocalIp(hostname) {
+  const normalized = hostname.replace(/^\[|\]$/g, '');
+  const version = isIP(normalized);
+  if (version === 4) return isPrivateIpv4(normalized);
+  if (version !== 6) return false;
+
+  const words = parseIpv6Words(normalized);
+  if (!words) return false;
+  const first = words[0];
+  const allZero = words.every((word) => word === 0);
+  const loopback =
+    words.slice(0, 7).every((word) => word === 0) && words[7] === 1;
+  const uniqueLocal = (first & 0xfe00) === 0xfc00;
+  const linkLocal = (first & 0xffc0) === 0xfe80;
+  const mappedIpv4 =
+    words.slice(0, 5).every((word) => word === 0) && words[5] === 0xffff;
+  const mappedAddress = mappedIpv4
+    ? `${words[6] >> 8}.${words[6] & 0xff}.${words[7] >> 8}.${words[7] & 0xff}`
+    : undefined;
+  return (
+    allZero ||
+    loopback ||
+    uniqueLocal ||
+    linkLocal ||
+    (mappedAddress ? isPrivateIpv4(mappedAddress) : false)
+  );
+}
+
+function isPrivateIpv4(value) {
+  const octets = value.split('.').map(Number);
+  if (
+    octets.length !== 4 ||
+    octets.some((octet) => !Number.isInteger(octet) || octet < 0 || octet > 255)
+  )
+    return false;
+  const [first, second] = octets;
+  return (
+    first === 0 ||
+    first === 10 ||
+    first === 127 ||
+    (first === 100 && second >= 64 && second <= 127) ||
+    (first === 169 && second === 254) ||
+    (first === 172 && second >= 16 && second <= 31) ||
+    (first === 192 && (second === 0 || second === 168)) ||
+    (first === 198 && (second === 18 || second === 19)) ||
+    first >= 224
+  );
+}
+
+function parseIpv6Words(value) {
+  const sections = value.toLowerCase().split('::');
+  if (sections.length > 2) return undefined;
+  const left = parseIpv6Section(sections[0]);
+  const right = sections.length === 2 ? parseIpv6Section(sections[1]) : [];
+  if (!left || !right) return undefined;
+  const zeroCount = sections.length === 2 ? 8 - left.length - right.length : 0;
+  if (
+    zeroCount < (sections.length === 2 ? 1 : 0) ||
+    left.length + right.length + zeroCount !== 8
+  )
+    return undefined;
+  return [...left, ...new Array(zeroCount).fill(0), ...right];
+}
+
+function parseIpv6Section(section) {
+  if (!section) return [];
+  const words = [];
+  for (const part of section.split(':')) {
+    if (part.includes('.')) {
+      const octets = part.split('.').map(Number);
+      if (
+        octets.length !== 4 ||
+        octets.some(
+          (octet) => !Number.isInteger(octet) || octet < 0 || octet > 255
+        )
+      )
+        return undefined;
+      words.push((octets[0] << 8) | octets[1], (octets[2] << 8) | octets[3]);
+    } else {
+      if (!/^[0-9a-f]{1,4}$/.test(part)) return undefined;
+      words.push(Number.parseInt(part, 16));
+    }
+  }
+  return words;
+}
+
 function extractId(body, keys) {
   for (const key of keys) {
     const value = body?.[key];
@@ -451,37 +823,62 @@ function extractId(body, keys) {
     if (typeof value === 'number' && Number.isSafeInteger(value)) return value;
     if (value && typeof value === 'object') {
       if (typeof value.id === 'string' && value.id) return value.id;
-      if (typeof value.id === 'number' && Number.isSafeInteger(value.id)) return value.id;
+      if (typeof value.id === 'number' && Number.isSafeInteger(value.id))
+        return value.id;
       if (typeof value.jobId === 'string' && value.jobId) return value.jobId;
-      if (typeof value.draftId === 'string' && value.draftId) return value.draftId;
+      if (typeof value.draftId === 'string' && value.draftId)
+        return value.draftId;
     }
   }
   return undefined;
 }
 
-async function waitForPublishJob(registry, jobId, {
-  fetchImpl,
-  headers,
-  sleep: sleepImpl = wait,
-  pollIntervalMs = 1000,
-  maxPollAttempts = 120,
-} = {}) {
-  if (!Number.isSafeInteger(maxPollAttempts) || maxPollAttempts < 1) throw new Error('maxPollAttempts must be a positive integer.');
-  if (!Number.isFinite(pollIntervalMs) || pollIntervalMs < 0) throw new Error('pollIntervalMs must be a non-negative number.');
+async function waitForPublishJob(
+  registry,
+  jobId,
+  {
+    fetchImpl,
+    headers,
+    sleep: sleepImpl = wait,
+    pollIntervalMs = 1000,
+    maxPollAttempts = 120,
+  } = {}
+) {
+  if (!Number.isSafeInteger(maxPollAttempts) || maxPollAttempts < 1)
+    throw new Error('maxPollAttempts must be a positive integer.');
+  if (!Number.isFinite(pollIntervalMs) || pollIntervalMs < 0)
+    throw new Error('pollIntervalMs must be a non-negative number.');
 
   for (let attempt = 0; attempt < maxPollAttempts; attempt++) {
     if (attempt > 0 && pollIntervalMs > 0) await sleepImpl(pollIntervalMs);
-    const body = await getJson(registryApiUrl(registry, ['publish', 'jobs', jobId]), { fetchImpl, headers });
+    const body = await getJson(
+      registryApiUrl(registry, ['publish', 'jobs', jobId]),
+      { fetchImpl, headers }
+    );
     const job = body?.job && typeof body.job === 'object' ? body.job : body;
     const status = String(job?.status || job?.state || '').toLowerCase();
-    if (['passed', 'pass', 'complete', 'completed', 'succeeded', 'success'].includes(status)) return job;
+    if (
+      [
+        'passed',
+        'pass',
+        'complete',
+        'completed',
+        'succeeded',
+        'success',
+      ].includes(status)
+    )
+      return job;
     if (['failed', 'failure', 'error', 'rejected'].includes(status)) {
       const detail = job?.error || job?.message || body?.error;
-      throw new Error(`Hub publish verification failed${detail ? `: ${detail}` : '.'}`);
+      throw new Error(
+        `Hub publish verification failed${detail ? `: ${detail}` : '.'}`
+      );
     }
   }
 
-  throw new Error(`Timed out waiting for Hub publish verification job ${jobId}.`);
+  throw new Error(
+    `Timed out waiting for Hub publish verification job ${jobId}.`
+  );
 }
 
 function wait(milliseconds) {
@@ -499,14 +896,18 @@ export function parseAddArgs(args) {
     }
     if (['--out', '--registry'].includes(arg)) {
       const value = args[++i];
-      if (value === undefined || value.startsWith('--')) throw new Error(`Missing value for ${arg}`);
+      if (value === undefined || value.startsWith('--'))
+        throw new Error(`Missing value for ${arg}`);
       flags[arg.slice(2)] = value;
       continue;
     }
     if (arg.startsWith('--')) throw new Error(`Unknown flag for add: ${arg}`);
     positional.push(arg);
   }
-  if (positional.length !== 1) throw new Error('Usage: knolo add <publisher>/<slug>[@<version>] [--out <path>] [--force] [--json] [--registry <url>]');
+  if (positional.length !== 1)
+    throw new Error(
+      'Usage: knolo add <publisher>/<slug>[@<version>] [--out <path>] [--force] [--json] [--registry <url>]'
+    );
   return { spec: parsePackSpec(positional[0]), flags };
 }
 
@@ -520,12 +921,15 @@ export function parseLoginArgs(args) {
     }
     if (arg === '--token' || arg === '--registry') {
       const value = args[++i];
-      if (value === undefined || value.startsWith('--')) throw new Error(`Missing value for ${arg}`);
+      if (value === undefined || value.startsWith('--'))
+        throw new Error(`Missing value for ${arg}`);
       flags[arg.slice(2)] = value;
       continue;
     }
     if (arg.startsWith('--')) throw new Error(`Unknown flag for login: ${arg}`);
-    throw new Error('Usage: knolo login [--token kno_…] [--stdin] [--registry <url>]');
+    throw new Error(
+      'Usage: knolo login [--token kno_…] [--stdin] [--registry <url>]'
+    );
   }
   return { flags };
 }
@@ -563,17 +967,25 @@ export function parseSearchArgs(args) {
     }
     if (['--format', '--license', '--registry'].includes(arg)) {
       const value = args[++i];
-      if (value === undefined || value.startsWith('--')) throw new Error(`Missing value for ${arg}`);
+      if (value === undefined || value.startsWith('--'))
+        throw new Error(`Missing value for ${arg}`);
       flags[arg.slice(2)] = value;
       continue;
     }
-    if (arg.startsWith('--')) throw new Error(`Unknown flag for search: ${arg}`);
+    if (arg.startsWith('--'))
+      throw new Error(`Unknown flag for search: ${arg}`);
     positional.push(arg);
   }
 
   const query = positional.join(' ').trim();
-  if (!query) throw new Error('Usage: knolo search <query> [--format V4|V5] [--license <id>] [--official] [--agents] [--json] [--registry <url>]');
-  if (flags.format && !['V4', 'V5'].includes(String(flags.format).toUpperCase())) {
+  if (!query)
+    throw new Error(
+      'Usage: knolo search <query> [--format V4|V5] [--license <id>] [--official] [--agents] [--json] [--registry <url>]'
+    );
+  if (
+    flags.format &&
+    !['V4', 'V5'].includes(String(flags.format).toUpperCase())
+  ) {
     throw new Error('--format must be V4 or V5.');
   }
   if (flags.format) flags.format = String(flags.format).toUpperCase();
@@ -591,14 +1003,18 @@ export function parseInfoArgs(args) {
     }
     if (arg === '--registry') {
       const value = args[++i];
-      if (value === undefined || value.startsWith('--')) throw new Error('Missing value for --registry');
+      if (value === undefined || value.startsWith('--'))
+        throw new Error('Missing value for --registry');
       flags.registry = value;
       continue;
     }
     if (arg.startsWith('--')) throw new Error(`Unknown flag for info: ${arg}`);
     positional.push(arg);
   }
-  if (positional.length !== 1) throw new Error('Usage: knolo info <publisher>/<slug> [--json] [--registry <url>]');
+  if (positional.length !== 1)
+    throw new Error(
+      'Usage: knolo info <publisher>/<slug> [--json] [--registry <url>]'
+    );
   return { positional, flags };
 }
 
@@ -609,7 +1025,13 @@ function validatePacksResponse(body) {
 }
 
 function validatePackInfoResponse(body) {
-  if (!body || typeof body !== 'object' || typeof body.name !== 'string' || !body.pack || typeof body.pack !== 'object') {
+  if (
+    !body ||
+    typeof body !== 'object' ||
+    typeof body.name !== 'string' ||
+    !body.pack ||
+    typeof body.pack !== 'object'
+  ) {
     throw new Error('Registry returned an invalid pack response.');
   }
 }
@@ -620,17 +1042,24 @@ async function validateKnowledgeImage(core, bytes) {
       const verification = core.verifyKnowledgeImageV5(bytes);
       return { format: 'V5', stateRoot: verification.stateRoot };
     } catch (error) {
-      throw new Error(`invalid V5 Knowledge Image: ${error instanceof Error ? error.message : String(error)}`);
+      throw new Error(
+        `invalid V5 Knowledge Image: ${error instanceof Error ? error.message : String(error)}`
+      );
     }
   }
 
-  const buffer = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+  const buffer = bytes.buffer.slice(
+    bytes.byteOffset,
+    bytes.byteOffset + bytes.byteLength
+  );
   if (core.isPackV4?.(buffer)) {
     try {
       await core.mountPack({ src: bytes });
       return { format: 'V4' };
     } catch (error) {
-      throw new Error(`invalid V4 Knowledge Image: ${error instanceof Error ? error.message : String(error)}`);
+      throw new Error(
+        `invalid V4 Knowledge Image: ${error instanceof Error ? error.message : String(error)}`
+      );
     }
   }
   throw new Error('not a Knowledge Image');
@@ -653,7 +1082,8 @@ async function stageArtifactCopy(sourcePath, outputPath, cwd) {
 async function commitStagedFiles(entries) {
   const targets = new Set();
   const records = entries.map((entry) => {
-    if (targets.has(entry.targetPath)) throw new Error(`Install paths must be unique: ${entry.targetPath}`);
+    if (targets.has(entry.targetPath))
+      throw new Error(`Install paths must be unique: ${entry.targetPath}`);
     targets.add(entry.targetPath);
     return {
       ...entry,
@@ -666,7 +1096,8 @@ async function commitStagedFiles(entries) {
   try {
     for (const record of records) {
       const existing = await statIfPresent(record.targetPath);
-      if (existing?.isDirectory()) throw new Error(`Cannot replace directory at ${record.targetPath}.`);
+      if (existing?.isDirectory())
+        throw new Error(`Cannot replace directory at ${record.targetPath}.`);
     }
 
     for (const record of records) {
@@ -677,11 +1108,10 @@ async function commitStagedFiles(entries) {
       await rename(record.tempPath, record.targetPath);
       record.committed = true;
     }
-
   } catch (error) {
     for (const record of [...records].reverse()) {
       if (record.committed) await unlinkIfPresent(record.targetPath);
-      if (record.hadOriginal && await pathExists(record.backupPath)) {
+      if (record.hadOriginal && (await pathExists(record.backupPath))) {
         await unlinkIfPresent(record.targetPath);
         await rename(record.backupPath, record.targetPath);
       }
@@ -690,7 +1120,8 @@ async function commitStagedFiles(entries) {
   }
 
   for (const record of records) {
-    if (record.hadOriginal) await unlinkIfPresent(record.backupPath).catch(() => {});
+    if (record.hadOriginal)
+      await unlinkIfPresent(record.backupPath).catch(() => {});
   }
 }
 
@@ -718,24 +1149,36 @@ async function unlinkIfPresent(filePath) {
 export function renderSearchTable(packs) {
   if (!packs.length) return 'No packs found.';
 
-  const rows = packs.map((pack) => [
-    pack.id || pack.name || `${pack.publisher || ''}/${pack.slug || ''}`,
-    pack.version ?? '',
-    pack.format ?? '',
-    pack.license ?? '',
-    pack.pulls ?? 0,
-    pack.description ?? '',
-  ].map((value) => String(value)));
+  const rows = packs.map((pack) =>
+    [
+      pack.id || pack.name || `${pack.publisher || ''}/${pack.slug || ''}`,
+      pack.version ?? '',
+      pack.format ?? '',
+      pack.license ?? '',
+      pack.pulls ?? 0,
+      pack.description ?? '',
+    ].map((value) => String(value))
+  );
   const widths = [24, 9, 6, 11, 8];
-  const header = ['NAME', 'VERSION', 'FORMAT', 'LICENSE', 'PULLS', 'DESCRIPTION'];
-  const formatRow = (row) => [
-    pad(truncate(row[0], widths[0]), widths[0]),
-    pad(truncate(row[1], widths[1]), widths[1]),
-    pad(truncate(row[2], widths[2]), widths[2]),
-    pad(truncate(row[3], widths[3]), widths[3]),
-    pad(truncate(row[4], widths[4]), widths[4]),
-    truncate(row[5], 72),
-  ].join('  ').trimEnd();
+  const header = [
+    'NAME',
+    'VERSION',
+    'FORMAT',
+    'LICENSE',
+    'PULLS',
+    'DESCRIPTION',
+  ];
+  const formatRow = (row) =>
+    [
+      pad(truncate(row[0], widths[0]), widths[0]),
+      pad(truncate(row[1], widths[1]), widths[1]),
+      pad(truncate(row[2], widths[2]), widths[2]),
+      pad(truncate(row[3], widths[3]), widths[3]),
+      pad(truncate(row[4], widths[4]), widths[4]),
+      truncate(row[5], 72),
+    ]
+      .join('  ')
+      .trimEnd();
 
   return [formatRow(header), ...rows.map(formatRow)].join('\n');
 }