@stigmer/server 3.22.1 → 3.23.0

package/dist/pipeline/steps/resolve-artifact-source.js

@@ -1,7 +1,8 @@
+import { SlotUnknownError } from "../../domain/skill/transfer/slots.js";
 import { failedPreconditionError, invalidArgumentError } from "../errors.js";
 /** Where the resolved bytes ride for every downstream step. */
 export const ARTIFACT_BYTES_KEY = "pushArtifactBytes";
-export function newResolveArtifactSourceStep(slots, binding) {
+export function newResolveArtifactSourceStep(staging, binding) {
     return {
         name: "ResolveArtifactSource",
         async execute(ctx) {
@@ -10,15 +11,18 @@ export function newResolveArtifactSourceStep(slots, binding) {
                 ctx.set(ARTIFACT_BYTES_KEY, artifact);
                 return;
             }
-            if (slots === undefined) {
+            if (staging === undefined) {
                 throw failedPreconditionError(binding.laneNotConfigured);
             }
             let data;
             try {
-                data = await slots.consume(artifactUploadRef);
+                data = await staging.consume(artifactUploadRef);
             }
             catch (error) {
-                throw invalidArgumentError(`artifact_upload_ref not usable: ${error instanceof Error ? error.message : String(error)} — request a new upload URL via createArtifactUploadUrl`);
+                if (error instanceof SlotUnknownError) {
+                    throw invalidArgumentError(`artifact_upload_ref not usable: ${error.message} — request a new upload URL via createArtifactUploadUrl`);
+                }
+                throw error;
             }
             ctx.set(ARTIFACT_BYTES_KEY, data);
         },

package/dist/pipeline/steps/resolve-artifact-source.js.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-artifact-source.js","sourceRoot":"","sources":["../../../src/pipeline/steps/resolve-artifact-source.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAI7E,+DAA+D;AAC/D,MAAM,CAAC,MAAM,kBAAkB,GAAG,mBAAmB,CAAC;AAYtD,MAAM,UAAU,4BAA4B,CAC1C,KAA8B,EAC9B,OAAoC;IAEpC,OAAO;QACL,IAAI,EAAE,uBAAuB;QAC7B,KAAK,CAAC,OAAO,CAAC,GAAyB;YACrC,MAAM,EAAE,QAAQ,EAAE,iBAAiB,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YAClE,IAAI,iBAAiB,KAAK,EAAE,EAAE,CAAC;gBAC7B,GAAG,CAAC,GAAG,CAAC,kBAAkB,EAAE,QAAQ,CAAC,CAAC;gBACtC,OAAO;YACT,CAAC;YACD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACxB,MAAM,uBAAuB,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC;YAC3D,CAAC;YACD,IAAI,IAAgB,CAAC;YACrB,IAAI,CAAC;gBACH,IAAI,GAAG,MAAM,KAAK,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC;YAChD,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,oBAAoB,CACxB,mCAAmC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,yDAAyD,CACnJ,CAAC;YACJ,CAAC;YACD,GAAG,CAAC,GAAG,CAAC,kBAAkB,EAAE,IAAI,CAAC,CAAC;QACpC,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"resolve-artifact-source.js","sourceRoot":"","sources":["../../../src/pipeline/steps/resolve-artifact-source.ts"],"names":[],"mappings":"AAwBA,OAAO,EAAE,gBAAgB,EAAE,MAAM,sCAAsC,CAAC;AAExE,OAAO,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAI7E,+DAA+D;AAC/D,MAAM,CAAC,MAAM,kBAAkB,GAAG,mBAAmB,CAAC;AAYtD,MAAM,UAAU,4BAA4B,CAC1C,OAAmC,EACnC,OAAoC;IAEpC,OAAO;QACL,IAAI,EAAE,uBAAuB;QAC7B,KAAK,CAAC,OAAO,CAAC,GAAyB;YACrC,MAAM,EAAE,QAAQ,EAAE,iBAAiB,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;YAClE,IAAI,iBAAiB,KAAK,EAAE,EAAE,CAAC;gBAC7B,GAAG,CAAC,GAAG,CAAC,kBAAkB,EAAE,QAAQ,CAAC,CAAC;gBACtC,OAAO;YACT,CAAC;YACD,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC1B,MAAM,uBAAuB,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC;YAC3D,CAAC;YACD,IAAI,IAAgB,CAAC;YACrB,IAAI,CAAC;gBACH,IAAI,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC;YAClD,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IAAI,KAAK,YAAY,gBAAgB,EAAE,CAAC;oBACtC,MAAM,oBAAoB,CACxB,mCAAmC,KAAK,CAAC,OAAO,yDAAyD,CAC1G,CAAC;gBACJ,CAAC;gBACD,MAAM,KAAK,CAAC;YACd,CAAC;YACD,GAAG,CAAC,GAAG,CAAC,kBAAkB,EAAE,IAAI,CAAC,CAAC;QACpC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stigmer/server",
-  "version": "3.22.1",
+  "version": "3.23.0",
   "description": "The Stigmer OSS control plane as a composable library: composeServer, the extension registry and the driver seams a composition builds on. The self-contained deployable of the same server is @stigmer/server-slim.",
   "license": "Apache-2.0",
   "type": "module",
@@ -62,11 +62,11 @@
     "@connectrpc/connect-node": "^2.0.0",
     "@kubernetes/client-node": "2.0.0",
     "@opentelemetry/api": "^1.9.0",
-    "@stigmer/outbound": "3.22.1",
-    "@stigmer/plugin-package": "3.22.1",
-    "@stigmer/protos": "3.22.1",
-    "@stigmer/temporal-codecs": "3.22.1",
-    "@stigmer/zip-structure": "3.22.1",
+    "@stigmer/outbound": "3.23.0",
+    "@stigmer/plugin-package": "3.23.0",
+    "@stigmer/protos": "3.23.0",
+    "@stigmer/temporal-codecs": "3.23.0",
+    "@stigmer/zip-structure": "3.23.0",
     "@temporalio/activity": "1.16.2",
     "@temporalio/client": "1.16.2",
     "@temporalio/common": "1.16.2",

package/src/artifactstorage/__tests__/artifact-storage.test.ts

@@ -14,9 +14,13 @@ import path from "node:path";
 import { Readable } from "node:stream";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 
-import { UPLOADS_SEGMENT } from "../../domain/skill/constants.js";
+import {
+  STAGING_KEY_PREFIX,
+  UPLOADS_SEGMENT,
+} from "../../domain/skill/constants.js";
 import { UploadSlots } from "../../domain/skill/transfer/slots.js";
 import { uploadUrl } from "../../domain/skill/transfer/handler.js";
+import { uploadRefOf } from "../../domain/skill/transfer/staging.js";
 import { SKILL_ARTIFACTS_PATH_PREFIX } from "../../transport/constants.js";
 import {
   ArtifactStorageNotFoundError,
@@ -184,33 +188,32 @@ describe("LocalArtifactStorage", () => {
     });
 
     it("presignPut without a wired lane is the explicit not-configured throw, never a silent no-op", async () => {
-      await expect(storage.presignPut(16, 60_000)).rejects.toThrow(
-        "local presigned uploads not configured",
-      );
+      await expect(
+        storage.presignPut("skills/staging/deadbeef.zip", 16, 60_000),
+      ).rejects.toThrow("local presigned uploads not configured");
     });
   });
 });
 
 // The local presigned-PUT arm over the REAL skill-transfer-lane slot
 // mechanism (§6b, the Q1 ruling: one upload surface, no new lane) — the
-// adapter below mirrors boot/compose.ts's wiring exactly.
+// adapter below mirrors boot/compose.ts's wiring exactly. The caller names
+// the key; the lane stages under it inside this driver's root.
 describe("LocalArtifactStorage presignPut over the transfer-lane slots", () => {
   const BASE_URL = "http://localhost:8080";
+  const KEY = `${STAGING_KEY_PREFIX}${"ab".repeat(16)}.zip`;
   let root: string;
   let slots: UploadSlots;
   let driver: ArtifactStorage;
 
   beforeEach(() => {
     root = mkdtempSync(path.join(tmpdir(), "artifact-presign-"));
-    slots = new UploadSlots(
-      path.join(root, "skills-staging"),
-      60_000,
-      1024 * 1024,
-    );
+    slots = new UploadSlots(root, STAGING_KEY_PREFIX, 60_000, 1024 * 1024);
     driver = new LocalArtifactStorage(root, "", {
-      mint: (declaredSizeBytes) => slots.mint(declaredSizeBytes),
-      uploadUrl: (ref) => uploadUrl(BASE_URL, ref),
-      stagedKey: (ref) => `skills-staging/${slots.stagedFileName(ref)}`,
+      reserve: (key, declaredSizeBytes) => {
+        const { ttlMs } = slots.reserve(key, declaredSizeBytes);
+        return { url: uploadUrl(BASE_URL, uploadRefOf(key)), ttlMs };
+      },
     });
   });
 
@@ -218,36 +221,36 @@ describe("LocalArtifactStorage presignPut over the transfer-lane slots", () => {
     rmSync(root, { recursive: true, force: true });
   });
 
-  it("mint → PUT (lane receive) → download(stagingKey) round-trips the bytes", async () => {
+  it("presignPut(key) → PUT (lane receive) → download(key) round-trips the bytes", async () => {
     const bytes = Buffer.from("staged artifact bytes");
-    const upload = await driver.presignPut(bytes.length, 999_999_999);
+    const upload = await driver.presignPut(KEY, bytes.length, 999_999_999);
 
     // The URL is the lane's wire shape and the ref is its last segment —
     // exactly how the lane handler dispatches a PUT.
-    expect(
-      upload.url.startsWith(
-        `${BASE_URL}${SKILL_ARTIFACTS_PATH_PREFIX}${UPLOADS_SEGMENT}`,
-      ),
-    ).toBe(true);
+    expect(upload.url).toBe(
+      `${BASE_URL}${SKILL_ARTIFACTS_PATH_PREFIX}${UPLOADS_SEGMENT}${uploadRefOf(KEY)}`,
+    );
     // The lane's slot TTL governs, not the caller's larger ask.
     expect(upload.ttlMs).toBe(60_000);
 
-    const ref = upload.url.slice(upload.url.lastIndexOf("/") + 1);
-    await slots.receive(ref, Readable.from(bytes));
+    await slots.receive(KEY, Readable.from(bytes));
 
-    expect(Buffer.from(await driver.download(upload.stagingKey))).toEqual(
-      bytes,
-    );
-    expect(await driver.size(upload.stagingKey)).toBe(bytes.length);
+    expect(Buffer.from(await driver.download(KEY))).toEqual(bytes);
+    expect(await driver.size(KEY)).toBe(bytes.length);
+    // The driver's own delete retires the staged bytes — the consume path.
+    await driver.delete(KEY);
+    await expect(driver.download(KEY)).rejects.toThrow(ArtifactStorageNotFoundError);
   });
 
-  it("the staged key never resolves outside the driver root", async () => {
-    const upload = await driver.presignPut(4, 60_000);
-    expect(upload.stagingKey.startsWith("skills-staging/")).toBe(true);
-    // Unreceived slot: the key is honest about absence.
-    await expect(driver.download(upload.stagingKey)).rejects.toThrow(
-      ArtifactStorageNotFoundError,
-    );
+  it("an unreceived key is honest about absence", async () => {
+    await driver.presignPut(KEY, 4, 60_000);
+    await expect(driver.download(KEY)).rejects.toThrow(ArtifactStorageNotFoundError);
+  });
+
+  it("refuses a key that would stage outside the driver root before the lane sees it", async () => {
+    await expect(
+      driver.presignPut("../outside.zip", 4, 60_000),
+    ).rejects.toThrow("resolves outside the artifact storage root");
   });
 });
 

package/src/artifactstorage/__tests__/r2-storage.test.ts

@@ -4,8 +4,8 @@
  * ships r2_storage.go untested; these pins are what the port adds:
  * required-config copy, the 7-day presign clamp, the signed
  * Content-Disposition, the not-found mapping, and the O5 widened surface
- * (typed not-found on download/size, presigned-PUT under the pinned
- * staging prefix with the signed Content-Length).
+ * (typed not-found on download/size, presigned-PUT under the caller's key
+ * with the signed Content-Length).
  */
 import { describe, expect, it } from "vitest";
 
@@ -13,7 +13,6 @@ import { ArtifactStorageNotFoundError } from "../artifact-storage.js";
 import {
   R2ArtifactStorage,
   R2_MAX_EXPIRATION_MS,
-  R2_STAGING_PREFIX,
   isNotFoundError,
 } from "../r2-storage.js";
 
@@ -64,16 +63,14 @@ describe("R2ArtifactStorage presigned URLs", () => {
 });
 
 describe("R2ArtifactStorage O5 widened surface", () => {
-  it("presignPut mints under the pinned staging prefix, clamps the TTL, and signs the declared size", async () => {
+  it("presignPut signs a PUT under the caller's key, clamps the TTL, and signs the declared size", async () => {
     const storage = new R2ArtifactStorage(VALID);
-    const upload = await storage.presignPut(1234, R2_MAX_EXPIRATION_MS * 5);
+    const key = "skills/staging/0123456789abcdef0123456789abcdef.zip";
+    const upload = await storage.presignPut(key, 1234, R2_MAX_EXPIRATION_MS * 5);
 
-    expect(upload.stagingKey.startsWith(R2_STAGING_PREFIX)).toBe(true);
     expect(upload.ttlMs).toBe(R2_MAX_EXPIRATION_MS);
     expect(
-      upload.url.startsWith(
-        `${VALID.endpoint}/${VALID.bucket}/${upload.stagingKey}?`,
-      ),
+      upload.url.startsWith(`${VALID.endpoint}/${VALID.bucket}/${key}?`),
     ).toBe(true);
     expect(upload.url).toContain("X-Amz-Expires=604800");
     // Content-Length rides the signature: a body of a different size
@@ -81,11 +78,12 @@ describe("R2ArtifactStorage O5 widened surface", () => {
     expect(upload.url.toLowerCase()).toContain("content-length");
   });
 
-  it("two mints never share a staging key (the URL is the credential)", async () => {
+  it("the key is the caller's verbatim — the driver invents none of its own", async () => {
     const storage = new R2ArtifactStorage(VALID);
-    const a = await storage.presignPut(1, 60_000);
-    const b = await storage.presignPut(1, 60_000);
-    expect(a.stagingKey).not.toBe(b.stagingKey);
+    const a = await storage.presignPut("staging/a.zip", 1, 60_000);
+    const b = await storage.presignPut("staging/b.zip", 1, 60_000);
+    expect(a.url).toContain(`/${VALID.bucket}/staging/a.zip?`);
+    expect(b.url).toContain(`/${VALID.bucket}/staging/b.zip?`);
   });
 
   it("download and size map the SDK's not-found onto the typed class; real faults stay wrapped", async () => {

package/src/artifactstorage/artifact-storage.ts

@@ -58,17 +58,15 @@ export class ArtifactStorageNotFoundError extends Error {
 }
 
 /**
- * A staged upload minted by presignPut: the URL receives the bytes, the
- * stagingKey reads them back through the same driver. Staged blobs are
- * short-lived by contract — the local lane sweeps them on TTL expiry and
- * boot; R2 deployments configure a bucket lifecycle rule on the staging
- * prefix (the §6b driver-side sweep expectation).
+ * A staged upload minted by presignPut: the URL receives the bytes, which
+ * the caller reads back through download() under the key IT named. Staged
+ * blobs are short-lived by contract — the local lane sweeps them on TTL
+ * expiry and boot; a bucket deployment configures a lifecycle rule on the
+ * domain's staging prefix (the §6b driver-side sweep expectation).
  */
 export interface PresignedUpload {
-  /** Accepts one HTTP PUT of exactly the declared byte count. */
+  /** Accepts an HTTP PUT of exactly the declared byte count. */
   readonly url: string;
-  /** Driver key where the staged bytes land, readable via download(). */
-  readonly stagingKey: string;
   /** The TTL actually granted, after per-driver clamping. */
   readonly ttlMs: number;
 }
@@ -98,18 +96,25 @@ export interface ArtifactStorage {
     downloadFilename: string,
   ): Promise<string>;
   /**
-   * A time-limited upload URL for a staging-prefixed blob of exactly
-   * declaredSizeBytes (§6b). Per-driver semantics differ DELIBERATELY and
-   * are contract, not accident: the local backend rides the skill transfer
-   * lane's URL-as-credential slot mechanism (single-use, exact-size
-   * enforced by the lane, TTL clamped to the lane's slot TTL) and answers
-   * only on instances with a staged-upload lane wired — unwired instances
-   * throw the explicit not-configured error, never a silent no-op. The R2
-   * backend presigns a PUT (repeatable within its TTL, size enforced by
-   * the signed Content-Length header, TTL clamped to the 7-day R2
-   * maximum).
+   * A time-limited upload URL for a blob of exactly declaredSizeBytes at
+   * the key the CALLER names (§6b). The key is the domain's: it chooses
+   * the staging prefix its sweep targets and the mapping from its wire
+   * reference, and reads the bytes back through download(key) — the
+   * driver never invents a key of its own. Per-driver semantics differ
+   * DELIBERATELY and are contract, not accident: the local backend rides
+   * the skill transfer lane's URL-as-credential slot mechanism
+   * (single-use, exact-size enforced by the lane, TTL clamped to the
+   * lane's slot TTL) and answers only on instances with a staged-upload
+   * lane wired — unwired instances throw the explicit not-configured
+   * error, never a silent no-op. The R2 backend presigns a PUT
+   * (repeatable within its TTL, size enforced by the signed
+   * Content-Length header, TTL clamped to the 7-day R2 maximum).
    */
-  presignPut(declaredSizeBytes: number, ttlMs: number): Promise<PresignedUpload>;
+  presignPut(
+    key: string,
+    declaredSizeBytes: number,
+    ttlMs: number,
+  ): Promise<PresignedUpload>;
   /** Removes the artifact; missing is not an error. */
   delete(key: string): Promise<void>;
   /** Whether an artifact with the key exists. */
@@ -136,16 +141,16 @@ export type ArtifactStorageDriverFactory = () => ArtifactStorage;
  * the shape it needs and stays ignorant of who provides it.
  */
 export interface StagedUploadLane {
-  /** Reserves a single-use upload slot; returns its reference + TTL. */
-  mint(declaredSizeBytes: number): { ref: string; ttlMs: number };
-  /** The externally-reachable PUT URL for a minted reference. */
-  uploadUrl(ref: string): string;
   /**
-   * The driver key where the reference's staged bytes land — MUST resolve
-   * inside the driver instance's root, or download(stagingKey) could
-   * never read what the lane received.
+   * Reserves a single-use upload slot whose bytes land at `key` under this
+   * driver instance's root — the lane stages into the driver's own tree,
+   * so download(key) reads exactly what the lane received. Returns the
+   * externally-reachable PUT URL and the TTL the lane grants.
    */
-  stagedKey(ref: string): string;
+  reserve(
+    key: string,
+    declaredSizeBytes: number,
+  ): { url: string; ttlMs: number };
 }
 
 export interface ArtifactStorageConfig {
@@ -259,6 +264,7 @@ export class LocalArtifactStorage implements ArtifactStorage {
   }
 
   async presignPut(
+    key: string,
     declaredSizeBytes: number,
     _ttlMs: number,
   ): Promise<PresignedUpload> {
@@ -267,15 +273,13 @@ export class LocalArtifactStorage implements ArtifactStorage {
         "local presigned uploads not configured - no staged-upload lane is wired to this store instance",
       );
     }
+    // The key must be one this instance can read back, or the lane would
+    // stage bytes download(key) can never reach.
+    this.resolveWithinRoot(key);
     // The lane's slot TTL governs, not the caller's ask — the slot
     // registry sweeps on ITS clock, and a URL outliving its slot would be
     // a credential for nothing.
-    const { ref, ttlMs } = this.stagedUploadLane.mint(declaredSizeBytes);
-    return {
-      url: this.stagedUploadLane.uploadUrl(ref),
-      stagingKey: this.stagedUploadLane.stagedKey(ref),
-      ttlMs,
-    };
+    return this.stagedUploadLane.reserve(key, declaredSizeBytes);
   }
 
   async getSignedUrl(

package/src/artifactstorage/r2-storage.ts

@@ -9,8 +9,6 @@
  * that have logic: config validation copy, the 7-day presign clamp, the
  * signed Content-Disposition, and the not-found mapping.
  */
-import { randomBytes } from "node:crypto";
-
 import {
   DeleteObjectCommand,
   GetObjectCommand,
@@ -30,13 +28,6 @@ import {
 /** Go: "R2 has a maximum expiration of 7 days" — presigns clamp here. */
 export const R2_MAX_EXPIRATION_MS = 7 * 24 * 60 * 60 * 1000;
 
-/**
- * Key prefix for presignPut staging blobs (§6b). Pinned as the surface a
- * deployment's bucket lifecycle rule targets: the driver mints under it,
- * operations sweeps it — changing it orphans staged blobs from the sweep.
- */
-export const R2_STAGING_PREFIX = "staging/";
-
 /**
  * Go get_content/get_download_url wrap their storage calls in a 30s
  * context timeout. The TS ArtifactStorage interface carries no signal, so
@@ -167,17 +158,17 @@ export class R2ArtifactStorage implements ArtifactStorage {
   }
 
   async presignPut(
+    key: string,
     declaredSizeBytes: number,
     ttlMs: number,
   ): Promise<PresignedUpload> {
     const clampedMs = Math.min(ttlMs, R2_MAX_EXPIRATION_MS);
-    // Random staging key: the URL is the credential (unguessable), and the
-    // prefix is the contract surface a bucket lifecycle rule sweeps (§6b —
-    // staged uploads the domain never committed must not accrete forever).
-    const stagingKey = `${R2_STAGING_PREFIX}${randomBytes(16).toString("hex")}`;
+    // The key is the caller's: the domain names its staging prefix (the
+    // surface a bucket lifecycle rule sweeps) and keeps the unguessable
+    // part of the URL-as-credential in the reference it hands the client.
     const command = new PutObjectCommand({
       Bucket: this.bucket,
-      Key: stagingKey,
+      Key: key,
       // Signed into the URL: a PUT whose body disagrees with the declared
       // size fails the signature check — R2's arm of the exact-size
       // contract the local lane enforces by counting bytes.
@@ -187,7 +178,7 @@ export class R2ArtifactStorage implements ArtifactStorage {
       const url = await this.presign(this.client, command, {
         expiresIn: Math.floor(clampedMs / 1000),
       });
-      return { url, stagingKey, ttlMs: clampedMs };
+      return { url, ttlMs: clampedMs };
     } catch (error) {
       throw new Error(`r2 presign failed: ${errorText(error)}`, { cause: error });
     }

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).