@stigmer/server 3.22.1-dev.20260922095755 → 3.23.0

package/src/authorization/store-test-kit.ts

@@ -41,18 +41,26 @@
  * `skipped` is therefore complete once every case has run; a consumer
  * pins it after the cases, which is the order a test file declares them.
  *
- * The parser is strict on purpose: an unknown key anywhere is a thrown
- * fault, so a change to the format upstream is loud here rather than
- * half-run. The model declares no condition, so the format's `condition`
- * on a tuple and `context` on a check are among the keys refused: a
- * document that still carries them is written against a model this
- * evaluator does not answer, and saying so beats running it half-blind.
+ * Context. A check's `context.allow` is the `allow_public` parameter
+ * (tuples.ts). A check without a context runs with `allow: false`, the
+ * listing posture: OpenFGA itself would fault on a conditional tuple it
+ * reached with the parameter missing, so the cloud's documents never do
+ * that — their CI would already fail — and the choice cannot change an
+ * answer the oracle gives. The parser is strict on purpose: an unknown
+ * key anywhere is a thrown fault, so a change to the format upstream is
+ * loud here rather than half-run.
  */
 import assert from "node:assert/strict";
 
 import { checkRelation } from "./evaluator.js";
 import type { Model } from "./model/index.js";
-import type { Person, Subject, Tuple, TupleSource } from "./tuples.js";
+import type {
+  CheckContext,
+  Person,
+  Subject,
+  Tuple,
+  TupleSource,
+} from "./tuples.js";
 import {
   ACCOUNT_TYPE,
   newInMemoryTupleSource,
@@ -68,17 +76,20 @@ export interface StoreTestTuple {
   readonly user: string;
   readonly relation: string;
   readonly object: string;
+  readonly condition?: { readonly name: string };
 }
 
 export interface StoreTestCheck {
   readonly user: string;
   readonly object: string;
+  readonly context?: CheckContext;
   readonly assertions: Readonly<Record<string, boolean>>;
 }
 
 export interface StoreTestListObjects {
   readonly user: string;
   readonly type: string;
+  readonly context?: CheckContext;
   readonly assertions: Readonly<Record<string, ReadonlyArray<string>>>;
 }
 
@@ -121,12 +132,28 @@ export function parseStoreTestDocument(
 }
 
 function parseTuple(value: unknown, where: string): StoreTestTuple {
-  const entry = record(value, where, ["user", "relation", "object"]);
-  return {
+  const entry = record(value, where, [
+    "user",
+    "relation",
+    "object",
+    "condition",
+  ]);
+  const tuple: StoreTestTuple = {
     user: text(entry["user"], `${where}.user`),
     relation: text(entry["relation"], `${where}.relation`),
     object: text(entry["object"], `${where}.object`),
   };
+  if (entry["condition"] === undefined) {
+    return tuple;
+  }
+  const condition = record(entry["condition"], `${where}.condition`, [
+    "name",
+    "context",
+  ]);
+  return {
+    ...tuple,
+    condition: { name: text(condition["name"], `${where}.condition.name`) },
+  };
 }
 
 function parseTest(value: unknown, where: string): StoreTest {
@@ -146,7 +173,12 @@ function parseTest(value: unknown, where: string): StoreTest {
 }
 
 function parseCheck(value: unknown, where: string): StoreTestCheck {
-  const entry = record(value, where, ["user", "object", "assertions"]);
+  const entry = record(value, where, [
+    "user",
+    "object",
+    "context",
+    "assertions",
+  ]);
   const assertions = record(entry["assertions"], `${where}.assertions`);
   const parsed: Record<string, boolean> = {};
   for (const [relation, expected] of Object.entries(assertions)) {
@@ -155,15 +187,17 @@ function parseCheck(value: unknown, where: string): StoreTestCheck {
     }
     parsed[relation] = expected;
   }
+  const context = parseContext(entry["context"], `${where}.context`);
   return {
     user: text(entry["user"], `${where}.user`),
     object: text(entry["object"], `${where}.object`),
+    ...(context === undefined ? {} : { context }),
     assertions: parsed,
   };
 }
 
 function parseListObjects(value: unknown, where: string): StoreTestListObjects {
-  const entry = record(value, where, ["user", "type", "assertions"]);
+  const entry = record(value, where, ["user", "type", "context", "assertions"]);
   const assertions = record(entry["assertions"], `${where}.assertions`);
   const parsed: Record<string, ReadonlyArray<string>> = {};
   for (const [relation, expected] of Object.entries(assertions)) {
@@ -171,13 +205,26 @@ function parseListObjects(value: unknown, where: string): StoreTestListObjects {
       (item, index) => text(item, `${where}.assertions.${relation}[${index}]`),
     );
   }
+  const context = parseContext(entry["context"], `${where}.context`);
   return {
     user: text(entry["user"], `${where}.user`),
     type: text(entry["type"], `${where}.type`),
+    ...(context === undefined ? {} : { context }),
     assertions: parsed,
   };
 }
 
+function parseContext(value: unknown, where: string): CheckContext | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  const entry = record(value, where, ["allow"]);
+  if (typeof entry["allow"] !== "boolean") {
+    throw new Error(`${where}.allow: expected a boolean`);
+  }
+  return { allow: entry["allow"] };
+}
+
 function record(
   value: unknown,
   where: string,
@@ -250,6 +297,9 @@ export interface StoreTestKit {
   readonly skipped: ReadonlyArray<StoreTestSkip>;
 }
 
+/** The listing posture, for a check the document leaves without a context (the module header). */
+const CONTEXT_WHEN_ABSENT: CheckContext = { allow: false };
+
 /**
  * The document's tests as runnable cases over `model`, plus every
  * assertion group the kit does not run.
@@ -296,6 +346,7 @@ export function storeTestCases(
         for (const item of runnable) {
           const object = parseObjectRef(item.object);
           const person = personOf(item.user);
+          const context = item.context ?? CONTEXT_WHEN_ABSENT;
           for (const [relation, expected] of Object.entries(item.assertions)) {
             const recording = recordUndeclaredTypes(source, model);
             const actual = await checkRelation(
@@ -303,6 +354,7 @@ export function storeTestCases(
               object,
               relation,
               person,
+              context,
             );
             if (recording.reached.size > 0) {
               skipped.push({
@@ -319,7 +371,7 @@ export function storeTestCases(
             assert.equal(
               actual,
               expected,
-              `${document.name} :: ${test.name}: ${item.user} ${relation} ${item.object} expected ${String(expected)}, got ${String(actual)}`,
+              `${document.name} :: ${test.name}: ${item.user} ${relation} ${item.object} (allow: ${String(context.allow)}) expected ${String(expected)}, got ${String(actual)}`,
             );
           }
         }
@@ -337,9 +389,10 @@ interface RecordingTupleSource extends TupleSource {
 /**
  * A view of `inner` that records, for one walk, every subject type the
  * evaluator read that `model` does not declare. A person
- * (`identity_account:<id>`) is a subject the evaluator compares, never a
- * type it resolves, so it is not a "reach" whatever the model declares; a
- * userset or a parent object of an undeclared type is.
+ * (`identity_account:<id>`, the wildcard) is a subject the evaluator
+ * compares, never a type it resolves, so it is not a "reach" whatever
+ * the model declares; a userset or a parent object of an undeclared
+ * type is.
  */
 function recordUndeclaredTypes(
   inner: TupleSource,
@@ -370,6 +423,8 @@ function resolvedTypeOf(subject: Subject): string | undefined {
         : subject.object.type;
     case "userset":
       return subject.object.type;
+    case "wildcard":
+      return undefined;
     default: {
       const exhaustive: never = subject;
       throw new Error(`unknown subject form: ${JSON.stringify(exhaustive)}`);
@@ -378,10 +433,14 @@ function resolvedTypeOf(subject: Subject): string | undefined {
 }
 
 function tupleOf(entry: StoreTestTuple): Tuple {
+  const subject = parseSubject(entry.user);
   return {
     object: parseObjectRef(entry.object),
     relation: entry.relation,
-    subject: parseSubject(entry.user),
+    subject:
+      subject.form === "wildcard" && entry.condition !== undefined
+        ? { ...subject, condition: entry.condition.name }
+        : subject,
   };
 }
 

package/src/authorization/tuples.ts

@@ -1,11 +1,9 @@
 /**
  * The tuple vocabulary of the built-in authorizer — the OpenFGA notions
  * the cloud's model is written in (object, relation, subject; a subject
- * being an object or a userset `type:id#relation`), typed once so the
- * evaluator, the derivation and the store-test kit speak one language. The
- * model declares no wildcard subject and no condition: every reader of a
- * row is an account or the holder of a relation on an object, which is
- * why a check needs no context parameter. Nothing here is
+ * being an object, a userset `type:id#relation`, or the public wildcard
+ * `type:*` under a condition), typed once so the evaluator, the
+ * derivation and the store-test kit speak one language. Nothing here is
  * stored: open source derives every tuple from a row (derived-tuples.ts)
  * or reads it from an IamPolicy row, and this module only names what a
  * tuple IS.
@@ -20,18 +18,28 @@
  * The type is named here; the construction (`personFor`, `resolvePerson`)
  * is person.ts's, so this module stays vocabulary with no I/O.
  *
- * The string forms (`agent:x`, `organization:acme#viewer`) are the
- * notation the cloud's store tests and the IamPolicy proto both use; parse
- * and format are here so the kit and the tests never spell them a second
- * way. The wildcard notation `type:*` is refused by the parser: the model
- * has no line that admits one, so a fixture or a policy that spells it is
- * a mistake to surface, never a subject to carry.
+ * `CheckContext` is the FGA condition context. The one condition the
+ * model declares is `allow_public(allow: bool)` on the public wildcard,
+ * and the cloud's own posture (stigmer-cloud authorizer/fga-authorizer.ts,
+ * the Java BuildCheckRequest) is `allow: true` on a point check — a public
+ * resource reads for any authenticated caller — and `allow: false` in a
+ * listing, which keeps a public wildcard from flooding an organization's
+ * catalog. The parameter is required so a caller states which posture it
+ * is in; there is no default because either one is wrong for the other.
+ *
+ * The string forms (`agent:x`, `organization:acme#viewer`,
+ * `identity_account:*`) are the notation the cloud's store tests and the
+ * IamPolicy proto both use; parse and format are here so the kit and the
+ * tests never spell them a second way.
  */
 import type { Message } from "@bufbuild/protobuf";
 
 /** The FGA type name of the kind every person is: `identity_account:<id>`. */
 export const ACCOUNT_TYPE = "identity_account";
 
+/** The one condition the model declares; it guards the public wildcard. */
+export const ALLOW_PUBLIC_CONDITION = "allow_public";
+
 /** `type:id` — an object of the model. */
 export interface ObjectRef {
   readonly type: string;
@@ -47,6 +55,12 @@ export type Subject =
       readonly form: "userset";
       readonly object: ObjectRef;
       readonly relation: string;
+    }
+  /** `type:*` — every object of the type, honoured only when its condition holds. */
+  | {
+      readonly form: "wildcard";
+      readonly type: string;
+      readonly condition: string | undefined;
     };
 
 export interface Tuple {
@@ -83,6 +97,11 @@ export interface Person {
   readonly aliases: ReadonlySet<string>;
 }
 
+/** The condition parameters of a check (the module header). */
+export interface CheckContext {
+  readonly allow: boolean;
+}
+
 // ---------------------------------------------------------------------------
 // The string notation.
 // ---------------------------------------------------------------------------
@@ -101,8 +120,10 @@ export function formatObjectRef(object: ObjectRef): string {
 }
 
 /**
- * `type:id` or `type:id#relation` → Subject. `type:*` is refused (the
- * module header): no line of the model admits a wildcard subject.
+ * `type:id`, `type:id#relation` or `type:*` → Subject. A wildcard parsed
+ * from text carries no condition; the caller attaches one when its source
+ * says so (the store tests carry it on the tuple, the derivation attaches
+ * the model's).
  */
 export function parseSubject(text: string): Subject {
   const hash = text.indexOf("#");
@@ -115,9 +136,7 @@ export function parseSubject(text: string): Subject {
   }
   const object = parseObjectRef(text);
   if (object.id === "*") {
-    throw new Error(
-      `wildcard subject '${text}' is not admitted: the model declares no wildcard line`,
-    );
+    return { form: "wildcard", type: object.type, condition: undefined };
   }
   return { form: "object", object };
 }
@@ -128,6 +147,10 @@ export function formatSubject(subject: Subject): string {
       return formatObjectRef(subject.object);
     case "userset":
       return `${formatObjectRef(subject.object)}#${subject.relation}`;
+    case "wildcard":
+      return subject.condition === undefined
+        ? `${subject.type}:*`
+        : `${subject.type}:* with ${subject.condition}`;
     default: {
       const exhaustive: never = subject;
       throw new Error(`unknown subject form: ${JSON.stringify(exhaustive)}`);

package/src/boot/__tests__/skill-transfer-origin.test.ts

@@ -0,0 +1,72 @@
+/**
+ * Pins the skill transfer origin verdict (boot/skill-transfer-origin.ts):
+ * loopback on the relay is fine for a single-operator install and a
+ * warning under the require-authentication posture; a public origin is
+ * reachable whatever the posture; a bucket driver makes the base URL
+ * unused; an unparseable base URL is not mistaken for loopback.
+ */
+import { describe, expect, it } from "vitest";
+
+import { assessSkillTransferOrigin } from "../skill-transfer-origin.js";
+
+describe("assessSkillTransferOrigin", () => {
+  it("the default loopback on a single-operator install is correct", () => {
+    expect(
+      assessSkillTransferOrigin({
+        baseUrl: "http://localhost:7234",
+        relaysThroughServer: true,
+        requireAuthentication: false,
+      }),
+    ).toEqual({ kind: "loopback-local" });
+  });
+
+  it.each([
+    "http://localhost:7234",
+    "http://127.0.0.1:7234",
+    "http://[::1]:7234",
+    "http://0.0.0.0:7234",
+  ])(
+    "loopback (%s) under the require-authentication posture is the warning, naming the URL",
+    (baseUrl) => {
+      expect(
+        assessSkillTransferOrigin({
+          baseUrl,
+          relaysThroughServer: true,
+          requireAuthentication: true,
+        }),
+      ).toEqual({ kind: "loopback-hosted", baseUrl });
+    },
+  );
+
+  it("a public origin is reachable under either posture", () => {
+    for (const requireAuthentication of [true, false]) {
+      expect(
+        assessSkillTransferOrigin({
+          baseUrl: "https://api.example.com",
+          relaysThroughServer: true,
+          requireAuthentication,
+        }),
+      ).toEqual({ kind: "reachable" });
+    }
+  });
+
+  it("a driver that signs its own URLs makes the base URL unused, loopback or not", () => {
+    expect(
+      assessSkillTransferOrigin({
+        baseUrl: "http://localhost:7234",
+        relaysThroughServer: false,
+        requireAuthentication: true,
+      }),
+    ).toEqual({ kind: "unused" });
+  });
+
+  it("an unparseable base URL is not loopback; its failure is loud on the first mint instead", () => {
+    expect(
+      assessSkillTransferOrigin({
+        baseUrl: "not a url",
+        relaysThroughServer: true,
+        requireAuthentication: true,
+      }),
+    ).toEqual({ kind: "reachable" });
+  });
+});

package/src/boot/compose.ts

@@ -119,14 +119,20 @@ import { registerSkillServices } from "../domain/skill/controller.js";
 import {
   DEFAULT_SLOT_TTL_MS,
   MAX_ZIP_SIZE,
+  STAGING_KEY_PREFIX,
 } from "../domain/skill/constants.js";
 import { newSkillArtifactStorage } from "../domain/skill/storage/artifact-storage.js";
 import { newContentAddressedArchiveStore } from "../archive/content-store.js";
 import {
   newSkillTransferLane,
+  transferServeUrl,
   uploadUrl as skillUploadUrl,
 } from "../domain/skill/transfer/handler.js";
 import { UploadSlots } from "../domain/skill/transfer/slots.js";
+import {
+  newArchiveStaging,
+  uploadRefOf,
+} from "../domain/skill/transfer/staging.js";
 import {
   DEFAULT_WRITE_VERSION,
   ENCRYPTION_KEY_ENV_VAR,
@@ -166,6 +172,7 @@ import { SqliteStore } from "../store/sqlite/store.js";
 import type { Store } from "../store/interface.js";
 import { resolveExtensions } from "../extensions/registry.js";
 import { resolveOAuthRedirectUri } from "./oauth-redirect-uri.js";
+import { assessSkillTransferOrigin } from "./skill-transfer-origin.js";
 import type { ServerExtension } from "../extensions/registry.js";
 import { registerWorkflowServices } from "../domain/workflow/controller.js";
 import {
@@ -926,7 +933,7 @@ export async function composeServer(
       : undefined;
   // The skill artifact store + transfer lane (Go server.go:318-340). The
   // store is content-addressed and never-GC at {storagePath}/skills/;
-  // the slots registry wipes {storagePath}/skills-staging at boot (orphans
+  // the slots registry wipes {storagePath}/skills/staging at boot (orphans
   // from a dead process are useless — the registry died with it). On OSS
   // the lane is ALWAYS configured (Go wires it unconditionally too): the
   // FailedPrecondition lane-absent arms exist for construction-order
@@ -938,16 +945,25 @@ export async function composeServer(
   // deployment changes nothing for skill artifacts until it opts in
   // explicitly, and the Go-written skills/ directory keeps serving in
   // place on the default arm.
+  //
+  // Capability URLs come from the driver through the staging port
+  // (domain/skill/transfer/staging.ts, stigmer#1219): the local driver's
+  // presignPut reserves a slot here and renders the lane URL below, a
+  // bucket driver's signs a PUT straight to the bucket, and the
+  // controllers cannot tell which. The slots are constructed on every
+  // arm so the HTTP lane always has a registry to consult; on a bucket
+  // arm nothing is ever reserved in it.
   const skillUploadSlots = new UploadSlots(
-    path.join(config.storagePath, "skills-staging"),
+    config.storagePath,
+    STAGING_KEY_PREFIX,
     DEFAULT_SLOT_TTL_MS,
     MAX_ZIP_SIZE,
   );
+  const skillType =
+    config.skillArtifactStorageType === ""
+      ? "local"
+      : config.skillArtifactStorageType;
   const skillStorageDriver = ((): ArtifactStorage => {
-    const skillType =
-      config.skillArtifactStorageType === ""
-        ? "local"
-        : config.skillArtifactStorageType;
     if (skillType === "local") {
       // Go layout invariant: {storagePath}/skills exists from boot with
       // 0755 (the retired LocalFileStorage constructor's mkdir; the
@@ -958,16 +974,23 @@ export async function composeServer(
       });
       // The local presigned-PUT arm rides the skill transfer lane's slot
       // mechanism (§6b Q1 ruling: one upload surface, no new lane). The
-      // slots stage inside THIS driver's root, so a minted stagingKey
-      // reads back through the same instance; the empty serve URL is the
-      // honest state — skill downloads ride the transfer lane, never
-      // getSignedUrl.
-      return new LocalArtifactStorage(config.storagePath, "", {
-        mint: (declaredSizeBytes) => skillUploadSlots.mint(declaredSizeBytes),
-        uploadUrl: (ref) => skillUploadUrl(config.skillTransferBaseUrl, ref),
-        stagedKey: (ref) =>
-          `skills-staging/${skillUploadSlots.stagedFileName(ref)}`,
-      });
+      // slots stage inside THIS driver's root under the domain's staging
+      // key, so download(key) reads back what the lane received; the
+      // serve URL is the lane's download route, so getSignedUrl renders
+      // the very URL the lane dispatches.
+      return new LocalArtifactStorage(
+        config.storagePath,
+        transferServeUrl(config.skillTransferBaseUrl),
+        {
+          reserve: (key, declaredSizeBytes) => {
+            const { ttlMs } = skillUploadSlots.reserve(key, declaredSizeBytes);
+            return {
+              url: skillUploadUrl(config.skillTransferBaseUrl, uploadRefOf(key)),
+              ttlMs,
+            };
+          },
+        },
+      );
     }
     // Non-local skill backends share the artifact store's R2 settings for
     // the built-in arm and the composition's registered drivers beyond it.
@@ -994,11 +1017,31 @@ export async function composeServer(
     skillStorageDriver,
     PLUGIN_ARTIFACT_KEY_PREFIX,
   );
+  // One staging port for every archive kind, over the one skill blob
+  // driver: the controllers mint, consume and sign through it and never
+  // meet the slots or the bucket.
+  const skillArchiveStaging = newArchiveStaging(skillStorageDriver, logger);
   const skillTransferLane = newSkillTransferLane(
     skillUploadSlots,
     skillArtifactStorage,
     logger,
   );
+  // A hosted server relaying bytes through itself from its loopback
+  // default mints URLs no caller can reach (stigmer#1219); nothing inside
+  // the process can observe that, so the boot says it. Never fatal: the
+  // inline push and every other RPC work, and a self-host behind a tunnel
+  // it forgot to name deserves a pointer, not an outage.
+  const transferOrigin = assessSkillTransferOrigin({
+    baseUrl: config.skillTransferBaseUrl,
+    relaysThroughServer: skillType === "local",
+    requireAuthentication,
+  });
+  if (transferOrigin.kind === "loopback-hosted") {
+    logger.warn(
+      "skill artifact transfer lane mints capability URLs on the server's own loopback while the server requires authentication; pushes above the gRPC message cap and sandbox skill downloads will fail — set SKILL_TRANSFER_BASE_URL to the origin callers reach this server on",
+      { baseUrl: transferOrigin.baseUrl },
+    );
+  }
   // The console lane (lane 4, DD-012): present only when a static export
   // is bundled (slim artifacts) or configured (STIGMER_CONSOLE_DIR) —
   // "not bundled" is a modeled state, logged once, with the router
@@ -1463,14 +1506,11 @@ export async function composeServer(
       // The agentexecution blob store (server.go:362-363) — read side of
       // pushFromExecutionArtifact.
       executionArtifactStorage: artifactStorage,
-      transferLane: {
-        slots: skillUploadSlots,
-        baseUrl: config.skillTransferBaseUrl,
-      },
+      staging: skillArchiveStaging,
     });
     // Plugins materialise their members through the in-process lane as
     // the installing caller; the lazy provider resolves the clients built
-    // from these same routes after boot. The upload slots are the skill
+    // from these same routes after boot. The staging port is the skill
     // lane's: one upload surface for every archive.
     registerPluginServices(router, {
       store,
@@ -1479,10 +1519,7 @@ export async function composeServer(
       authorizationLifecycle,
       artifactStorage: pluginArtifactStorage,
       materializerProvider: () => requireInProcess().pluginMaterializer,
-      transferLane: {
-        slots: skillUploadSlots,
-        baseUrl: config.skillTransferBaseUrl,
-      },
+      staging: skillArchiveStaging,
     });
     // Artifact CRUD shares the ONE blob store with agentexecution's
     // attachment lanes (Go server.go 347–374).

package/src/boot/config.ts

@@ -121,9 +121,10 @@ export interface ServerConfig {
   readonly oauthRedirectUri: string;
   /**
    * Skill artifact storage root (STORAGE_PATH; Go defaultStoragePath
-   * ~/.stigmer/storage). Artifacts live at {storagePath}/skills/,
-   * upload staging at {storagePath}/skills-staging/ — byte-identical to
-   * Go's layout, so a Go-written directory is served in place at cutover.
+   * ~/.stigmer/storage). Artifacts live at {storagePath}/skills/ —
+   * byte-identical to Go's layout, so a Go-written directory is served in
+   * place at cutover — and upload staging at {storagePath}/skills/staging/,
+   * the prefix the domain names (domain/skill/constants.ts).
    */
   readonly storagePath: string;
   /**

package/src/boot/skill-transfer-origin.ts

@@ -0,0 +1,76 @@
+/**
+ * Whether the skill transfer lane's origin can be reached by the callers
+ * it is minted for.
+ *
+ * On the local blob driver the server itself carries artifact bytes over
+ * HTTP, and every upload and download capability URL it mints is rendered
+ * from `SKILL_TRANSFER_BASE_URL`, which defaults to the server's own
+ * loopback. That default is right for a single-operator install reached
+ * on the machine it runs on, and silently wrong for a hosted one: the
+ * server boots, serves, and passes every in-process check while handing
+ * the CLI, the SDKs and the sandbox runner a host none of them can reach —
+ * every push above the gRPC cap fails on the PUT and every sandbox mount
+ * of a skill with supporting files loses them (stigmer#1219). No test
+ * inside the process can see it, so the process says it at boot.
+ *
+ * The hosted signal is the require-authentication posture (boot/compose.ts
+ * combines its two sources): a server that requires credentials serves
+ * callers it does not share a machine with. A bucket driver signs URLs
+ * straight to its bucket and never renders the base URL, so the verdict
+ * is moot there and says so rather than warning about a knob nothing
+ * reads.
+ *
+ * Proven by __tests__/skill-transfer-origin.test.ts.
+ */
+
+/** Hosts that name the process's own machine and nothing beyond it. */
+const LOOPBACK_HOSTS = new Set([
+  "localhost",
+  "127.0.0.1",
+  "[::1]",
+  "0.0.0.0",
+  "[::]",
+]);
+
+export type SkillTransferOriginVerdict =
+  /** The base URL names a host other than the server's own loopback. */
+  | { readonly kind: "reachable" }
+  /** Loopback on a single-operator install: the default, and correct. */
+  | { readonly kind: "loopback-local" }
+  /** Loopback on a server that requires authentication: minted URLs are dead on arrival. */
+  | { readonly kind: "loopback-hosted"; readonly baseUrl: string }
+  /** The blob driver signs its own URLs; the base URL is never rendered. */
+  | { readonly kind: "unused" };
+
+export interface SkillTransferOriginInputs {
+  /** The configured or defaulted `SKILL_TRANSFER_BASE_URL`. */
+  readonly baseUrl: string;
+  /** Whether the local driver relays artifact bytes through this server. */
+  readonly relaysThroughServer: boolean;
+  /** The composed require-authentication posture. */
+  readonly requireAuthentication: boolean;
+}
+
+export function assessSkillTransferOrigin(
+  inputs: SkillTransferOriginInputs,
+): SkillTransferOriginVerdict {
+  if (!inputs.relaysThroughServer) {
+    return { kind: "unused" };
+  }
+  if (!namesLoopback(inputs.baseUrl)) {
+    return { kind: "reachable" };
+  }
+  return inputs.requireAuthentication
+    ? { kind: "loopback-hosted", baseUrl: inputs.baseUrl }
+    : { kind: "loopback-local" };
+}
+
+function namesLoopback(baseUrl: string): boolean {
+  try {
+    return LOOPBACK_HOSTS.has(new URL(baseUrl).hostname);
+  } catch {
+    // An unparseable base URL renders into every capability URL as-is; it
+    // is not loopback, and the failure it causes is loud on the first mint.
+    return false;
+  }
+}