@takosjp/yurucommu-core 4.1.0 → 4.1.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takosjp/yurucommu-core",
-  "version": "4.1.0",
+  "version": "4.1.2",
   "license": "AGPL-3.0-only",
   "type": "module",
   "workspaces": [
@@ -59,8 +59,9 @@
     "start": "bun src/backend/server.ts",
     "dev": "bun src/backend/server.ts",
     "dev:server": "bun src/backend/server.ts",
-    "check": "bun run fmt:check && tsc --noEmit && bun run check:no-opentofu-artifacts && bun run test",
+    "check": "bun run fmt:check && tsc --noEmit && bun run check:no-opentofu-artifacts && bun run check:worker-bundle && bun run test",
     "check:no-opentofu-artifacts": "bun scripts/check-no-opentofu-artifacts.mjs",
+    "check:worker-bundle": "bun scripts/check-worker-bundle-portable.mjs",
     "test": "bun run build:api && bun test test/ src/backend/ packages/api/src/ scripts/check-publish-version-discipline.test.ts scripts/publish-package-resumable.test.ts && bun run check:release-contents",
     "test:backend": "bun test src/backend/",
     "build": "bun run build:api",

package/packages/api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takosjp/yurucommu-api",
-  "version": "4.1.0",
+  "version": "4.1.2",
   "description": "Typed client SDK and public API contract for yurucommu-server clients.",
   "license": "AGPL-3.0-only",
   "type": "module",

package/src/backend/index.ts

@@ -1,4 +1,4 @@
-import { Hono, type Context } from "hono";
+import { Hono, type Context, type Next } from "hono";
 import { MOBILE_PUSH_REGISTRATION_PATH } from "./lib/mobile-contract.ts";
 import { NOTIFICATION_PUSHER_REGISTRATION_PATH } from "./lib/notification-pusher-contract.ts";
 import type { Env, EnvVars, Variables } from "./types.ts";
@@ -9,7 +9,13 @@ import {
   wrapRuntimeBindings,
   wrapRuntimeMessageBatch,
   type PortableWorkerBindings,
+  type RuntimeLane,
 } from "./runtime/lane.ts";
+import {
+  configuredAppUrl,
+  establishRequestPublicOrigin,
+  withRequiredBackgroundPublicOrigin,
+} from "./runtime/public-origin.ts";
 import type { EdgeQueueBatch } from "./runtime/edge-facades.ts";
 import {
   getMobileOidcAudience,
@@ -925,6 +931,65 @@ function mountStaticFallback(app: YurucommuApp): void {
   });
 }
 
+/**
+ * Give this request an `APP_URL` when the Host, not the deployer, chose it.
+ *
+ * Registered BEFORE every other route so `/readyz` and the `.well-known`
+ * discovery documents see the same origin the rest of the app mints ids from —
+ * a readiness probe that reported `APP_URL` missing on a Worker whose origin
+ * only its own traffic can reveal would never go ready.
+ *
+ * It runs on the `portable` lane alone. There, a wrapper host routes by
+ * hostname and delivers the request it received on the Worker's public
+ * endpoint, so the request URL IS the assigned origin (see
+ * runtime/public-origin.ts). A Worker deployed straight to Cloudflare answers
+ * on workers.dev, on every custom domain, and on every route pattern its
+ * account holds, so the same inference there would let whichever hostname
+ * happened to arrive first name the instance for good; that lane keeps
+ * requiring an explicit `APP_URL` exactly as before.
+ *
+ * It never fails a request. When no origin can be established — the request is
+ * plain http, KV is unbound, an operator hand-wrote the pin — `APP_URL` simply
+ * stays unset, which `/readyz` already reports as a hard missing binding.
+ * Turning that into a 500 would take the readiness probe down with it and
+ * replace a precise answer with a generic one.
+ */
+function publicOriginMiddleware() {
+  let warned = false;
+  return async (
+    c: Context<{ Bindings: Env; Variables: Variables }>,
+    next: Next,
+  ) => {
+    if (configuredAppUrl(c.env) !== null) return next();
+    // An unrecognised lane declaration is refused at the binding boundary by
+    // wrapRuntimeBindings. Reaching here with one means the app was composed
+    // directly, and the safe reading of "not a lane I know" is "do not infer".
+    let lane: RuntimeLane;
+    try {
+      lane = resolveRuntimeLane(c.env.YURUCOMMU_RUNTIME_LANE);
+    } catch {
+      return next();
+    }
+    if (lane !== "portable") return next();
+    try {
+      const origin = await establishRequestPublicOrigin(c.env, c.req.raw);
+      c.env = { ...c.env, APP_URL: origin };
+      warned = false;
+    } catch (error) {
+      // Once per isolate: this condition is a property of the deployment, not
+      // of the request, so it would otherwise repeat on every single one.
+      if (!warned) {
+        warned = true;
+        log.warn("Could not establish this instance's public origin", {
+          event: "runtime.public_origin.unestablished",
+          error,
+        });
+      }
+    }
+    return next();
+  };
+}
+
 export function createYurucommuBackendApp(
   options: CreateYurucommuBackendAppOptionsV1 = {},
 ): YurucommuApp {
@@ -941,6 +1006,10 @@ export function createYurucommuBackendApp(
     }
   }
 
+  // Before the readiness probes, because they report on APP_URL and the
+  // `.well-known` discovery documents publish it. Reads no body and consults no
+  // route, so it does not weaken the body-cap ordering below.
+  app.use("*", publicOriginMiddleware());
   mountReadinessRoutes(app, options.discovery);
   // Body-size cap must run BEFORE any handler reads the body or executes
   // expensive auth / rate-limit logic. Mounted after readiness probes so
@@ -1056,9 +1125,15 @@ export default {
     bindings: WorkerBindings,
   ): Promise<void> {
     const lane = resolveRuntimeLane(bindings.YURUCOMMU_RUNTIME_LANE);
+    // Federation delivery signs and addresses from this instance's own actor
+    // ids, and a queue invocation has no request to learn the origin from. When
+    // `APP_URL` is unset and no request has pinned one yet, this THROWS: the
+    // batch is retried later, after traffic has established the origin, instead
+    // of being delivered under `undefined/ap/users/…` to peers that would cache
+    // it. See runtime/public-origin.ts.
     return handleYurucommuQueueBatch(
       wrapRuntimeMessageBatch(batch, lane),
-      wrapRuntimeBindings(bindings),
+      await withRequiredBackgroundPublicOrigin(wrapRuntimeBindings(bindings)),
     );
   },
 

package/src/backend/public.ts

@@ -53,6 +53,21 @@ export {
   wrapRuntimeBindings,
   wrapRuntimeMessageBatch,
 } from "./runtime/lane.ts";
+// The public origin: `APP_URL` when the deployment could carry one, and the
+// origin one request established when only the Host knew it. A product that
+// composes its own Worker entry uses these for the handlers the core default
+// export does not own.
+export {
+  CANONICAL_ORIGIN_KV_KEY,
+  PublicOriginError,
+  canonicalPublicOrigin,
+  configuredAppUrl,
+  establishRequestPublicOrigin,
+  peekObservedPublicOrigin,
+  requireBackgroundPublicOrigin,
+  resetObservedPublicOrigin,
+  withRequiredBackgroundPublicOrigin,
+} from "./runtime/public-origin.ts";
 export {
   EDGE_KV_MAX_EXPIRATION_TTL_SECONDS,
   EDGE_KV_MIN_EXPIRATION_TTL_SECONDS,

package/src/backend/runtime/bun.ts

@@ -24,7 +24,7 @@ import {
   assertPathChainWithinBasePath,
   isPathWithinBasePath,
   resolvePathWithinBasePath,
-} from "./shared.ts";
+} from "./node-paths.ts";
 import { MemoryKV } from "./memory-kv.ts";
 import { isBackendPath } from "../lib/backend-paths.ts";
 import { loadBunSqlite } from "./compat-bun/types.ts";

package/src/backend/runtime/edge-facades.ts

@@ -9,7 +9,7 @@
  * The managed Cloudflare backend and the self-host backend project the SAME
  * facade: same methods, same option keys, same error names. Takoserver's
  * ADR 0005 states this explicitly for object storage, and its self-host wrapper
- * repeats it for KV and SQL.
+ * repeats it for all four.
  *
  * This module is a TYPE MIRROR of that contract plus the structural probes the
  * lane selector uses. It deliberately contains no behaviour: the adapters that
@@ -21,7 +21,8 @@
  *     — `projectEnv`, `createKvAdapter`, `createSqlAdapter`,
  *       `createQueueAdapter`, `createEdgeObjectsR2Adapter`
  *   takoserver `src/providers/selfhost-worker-wrapper.ts`
- *     — `projectEnv`, `createKvAdapter`, `createSqlAdapter`
+ *     — `projectEnv`, `createKvAdapter`, `createSqlAdapter`,
+ *       `createQueueAdapter`, `createObjectsAdapter`
  *
  * Every method rejects with an `Error` whose `name` is the portable error code
  * (`invalid_key`, `invalid_value`, `value_too_large`, `metadata_too_large`,
@@ -235,22 +236,24 @@ function hasMethods(value: unknown, names: readonly string[]): boolean {
 /**
  * Structural probes.
  *
- * Only SOME bindings can be told apart by shape, and the difference matters:
+ * Only ONE binding can be told apart by shape, and the difference matters:
  *
  *   decisive   `DB`     — `execute`/`query`/`transaction` (facade) against
  *                         `prepare`/`batch` (D1). Disjoint method sets.
- *   decisive   `MEDIA`  — R2 carries the multipart helpers the facade omits.
  *   decisive   a queue *batch* — `acknowledgeAll` (facade) against `ackAll`
  *                         (Cloudflare `MessageBatch`).
  *   AMBIGUOUS  `KV`     — `edge.kv` and `KVNamespace` expose the same five
  *                         method names.
  *   AMBIGUOUS  a queue *producer* — both are `send`/`sendBatch`.
+ *   AMBIGUOUS  `MEDIA`  — `edge.objects@1.0.0` is R2's method set by design,
+ *                         multipart helpers included. See below.
  *
  * That is why the lane is a DECLARED variable rather than something sniffed:
- * two of the five bindings cannot be identified at all. The declaration is then
- * cross-checked against the decisive bindings, so a Worker whose var and whose
- * bindings disagree refuses to start instead of calling `kv.get(key, {type})`
- * on a facade that would silently treat the options object as nothing.
+ * three of the five bindings cannot be identified at all. The declaration is
+ * then cross-checked against the decisive bindings, so a Worker whose var and
+ * whose bindings disagree refuses to start instead of calling
+ * `kv.get(key, {type})` on a facade that would silently treat the options
+ * object as nothing.
  */
 export function isEdgeSqlBinding(value: unknown): value is EdgeSqlBinding {
   return (
@@ -274,24 +277,38 @@ export function isEdgeQueueBatch(value: unknown): value is EdgeQueueBatch {
   );
 }
 
+/**
+ * A bucket-shaped binding with `edge.objects@1.0.0`'s call signatures.
+ *
+ * NOT DECISIVE, and never a lane test. The facade is R2's method set on
+ * purpose — `head`, `get`, `put`, `delete`, `list`, and the four multipart
+ * calls — so that an app written against R2 ports over unchanged. A real
+ * `R2Bucket` therefore answers `true` here too. Use it to check that SOMETHING
+ * bucket-shaped arrived, never to decide which host projected it: that is what
+ * `YURUCOMMU_RUNTIME_LANE` is for.
+ *
+ * The arity check is the facade's own contract rather than a discriminator:
+ * the Host counts `arguments.length`, so `get` takes its options slot even when
+ * that slot is `undefined`.
+ */
 export function isEdgeObjectsBinding(
   value: unknown,
 ): value is EdgeObjectsBinding {
   return (
     hasMethods(value, ["head", "get", "put", "delete", "list"]) &&
-    // R2 exposes multipart helpers on the binding itself; the facade does not
-    // give a bucket-shaped object those names.
-    typeof (value as Record<string, unknown>).createMultipartUpload !==
-      "function" &&
-    // Arity is part of the facade's contract and is asserted rather than
-    // assumed: the Host checks `arguments.length`, so `get` and `list` take
-    // their options slot even when it is `undefined`. Anything bucket-shaped
-    // whose `get` takes one argument is some other adapter, not this facade.
     (value as { get: (...args: unknown[]) => unknown }).get.length === 2
   );
 }
 
-/** Cloudflare's `R2Bucket`. */
+/**
+ * Cloudflare's `R2Bucket` — and, unavoidably, the `edge.objects` facade.
+ *
+ * A method-name test cannot separate the two, because Takoserver's facade
+ * carries `createMultipartUpload` as well (`selfhost-worker-wrapper.ts`
+ * `createObjectsAdapter`). 4.1.0 used this function to refuse the portable
+ * lane and so refused every self-hosted deployment. Keep it for describing a
+ * binding; do not let it decide a lane.
+ */
 export function isNativeR2Bucket(value: unknown): boolean {
   return hasMethods(value, [
     "head",

package/src/backend/runtime/edge-objects.ts

@@ -21,10 +21,14 @@
  *  - NO ENUMERATION OR HEAD. The port does not carry them, so neither does the
  *    adapter, even though the Host projects both.
  *
- * AVAILABILITY: `edge.objects` is projected by the managed Cloudflare backend
- * (`createEdgeObjectsR2Adapter`). The self-host backend projects only
- * `edge.kv` and `edge.sql`, so a self-hosted Worker has no object binding and
- * the core's existing "object storage unavailable" behaviour applies.
+ * AVAILABILITY: BOTH wrapper backends project `edge.objects`. The managed
+ * Cloudflare backend does it over provider-private R2
+ * (`createEdgeObjectsR2Adapter`); the self-host backend realizes its own object
+ * store for a Version's `bucketBindings` and projects the same facade, byte for
+ * byte. A Worker on the `portable` lane therefore receives `env.MEDIA` on
+ * either host. What still leaves `MEDIA` unbound is a Version that declared no
+ * bucket at all, and the core's existing "object storage unavailable" (503)
+ * behaviour is what applies then.
  */
 
 import type {

package/src/backend/runtime/edge-queue.ts

@@ -14,12 +14,12 @@
  *    and the body arrives as `{encoding:"base64", data}`. `retry` also refuses
  *    `delaySeconds: 0`, which Cloudflare accepts as "no delay".
  *
- * AVAILABILITY: the managed Cloudflare backend projects queue bindings; the
- * self-host backend projects only `edge.kv` and `edge.sql` today (see
- * takoserver `selfhost-worker-wrapper.ts` `projectEnv`). A self-hosted Worker
- * therefore has no queue binding at all, and the core's existing behaviour for
- * an unbound `DELIVERY_QUEUE` — synchronous fallback delivery, reported by the
- * readiness surface — is what applies there.
+ * AVAILABILITY: both wrapper backends project queue bindings (see takoserver
+ * `selfhost-worker-wrapper.ts` `projectEnv`, whose data-binding kinds are
+ * `edge.kv`, `edge.objects`, `edge.queue` and `edge.sql`). What leaves
+ * `DELIVERY_QUEUE` unbound is a Version that declared no queue, and the core's
+ * existing behaviour for that — synchronous fallback delivery, reported by the
+ * readiness surface — is what applies then.
  */
 
 import {

package/src/backend/runtime/lane.ts

@@ -28,8 +28,18 @@
  * So the lane comes from `YURUCOMMU_RUNTIME_LANE`, which a self-host or managed
  * Workers-for-Platforms deployment sets to `portable` and every raw-binding
  * deployment leaves unset (or `cloudflare`). The declaration is then
- * cross-checked against the bindings that ARE decisive — `DB` always, `MEDIA`
- * when it is bound. A disagreement refuses to start.
+ * cross-checked against the ONE binding that is decisive — `DB`. A
+ * disagreement refuses to start.
+ *
+ * `MEDIA` is NOT decisive and must never be cross-checked. Takoserver's
+ * `edge.objects@1.0.0` facade is method-for-method a bucket: `head`, `get`,
+ * `put`, `delete`, `list`, `createMultipartUpload`, `uploadPart`,
+ * `completeMultipartUpload`, `abortMultipartUpload` — the same names, the same
+ * option keys, deliberately, so that an app written against R2 ports over
+ * unchanged (ADR 0005/0007). 4.1.0 read that identity backwards and refused the
+ * portable lane whenever `MEDIA` looked R2-shaped, which is to say always: a
+ * self-hosted Yurucommu Worker could not boot on the lane its own README
+ * documents. The declaration decides `MEDIA`.
  */
 
 import type {
@@ -47,7 +57,6 @@ import {
   isEdgeQueueBatch,
   isEdgeSqlBinding,
   isNativeD1Database,
-  isNativeR2Bucket,
   type EdgeKvBinding,
   type EdgeObjectsBinding,
   type EdgeQueueBatch,
@@ -114,23 +123,35 @@ export function resolveRuntimeLane(declared: unknown): RuntimeLane {
 
 interface LaneBindings {
   readonly DB?: unknown;
+  /**
+   * Accepted so a caller can pass the whole `env`, and deliberately not read:
+   * the bucket binding carries no evidence about the lane. See
+   * {@link assertRuntimeLaneBindings}.
+   */
   readonly MEDIA?: unknown;
 }
 
 /**
- * Prove the declared lane against the bindings that can actually be identified.
+ * Prove the declared lane against the ONE binding that can be identified.
+ *
+ * `DB` is decisive in both directions: `execute`/`query`/`transaction` and
+ * `prepare`/`batch` are disjoint method sets, so a Worker that was handed the
+ * wrong one would fail at its first query anyway and is better stopped here
+ * with a message that names the variable to fix.
  *
- * `DB` is always decisive: `execute`/`query`/`transaction` and
- * `prepare`/`batch` are disjoint. `MEDIA` is decisive only in one direction —
- * an `R2Bucket` is recognisable by its multipart helpers, whereas a plain
- * five-method object could be the facade or an adapter a host repository
- * supplied — so only the direction that can be proven is checked.
+ * `MEDIA` is checked against NOTHING. The portable `edge.objects@1.0.0` facade
+ * is intentionally indistinguishable from an `R2Bucket` — that identity is the
+ * point of the Interface — so a shape test on it can only produce false
+ * refusals. On `portable` the bucket is wrapped as the facade, on `cloudflare`
+ * as native R2, and the declaration is the whole of the evidence. Getting it
+ * wrong is loud and immediate (the first `MEDIA` call throws), not the silent
+ * misread that `KV`'s ambiguity would cause.
  */
 export function assertRuntimeLaneBindings(
   lane: RuntimeLane,
   bindings: LaneBindings,
 ): void {
-  const { DB, MEDIA } = bindings;
+  const { DB } = bindings;
   if (lane === "portable") {
     if (isNativeD1Database(DB)) {
       throw new RuntimeLaneError(
@@ -148,13 +169,6 @@ export function assertRuntimeLaneBindings(
           `neither that nor D1's prepare/batch.`,
       );
     }
-    if (MEDIA !== undefined && isNativeR2Bucket(MEDIA)) {
-      throw new RuntimeLaneError(
-        `${RUNTIME_LANE_VAR}="portable" declares the portable-facade lane, ` +
-          `but env.MEDIA is a native R2Bucket. A portable bucket binding ` +
-          `arrives as the edge.objects@1.0.0 facade.`,
-      );
-    }
     return;
   }
   if (isEdgeSqlBinding(DB)) {
@@ -287,5 +301,9 @@ export function wrapRuntimeMessageBatch<T>(
   return wrapCloudflareMessageBatch(batch as MessageBatch<T>);
 }
 
-/** Re-exported so a Worker entry can probe MEDIA without importing internals. */
+/**
+ * Re-exported so a Worker entry can assert that SOMETHING bucket-shaped
+ * arrived without importing internals. It does not identify the lane — a
+ * native `R2Bucket` satisfies it too — so never branch on it.
+ */
 export { isEdgeObjectsBinding };

package/src/backend/runtime/node-paths.ts

@@ -0,0 +1,79 @@
+/**
+ * Filesystem path containment for the Bun/Node runtime ONLY.
+ *
+ * These helpers need `node:path`, so they live apart from `shared.ts`. That
+ * separation is load-bearing rather than tidy: `shared.ts` is reached from
+ * `edge-kv.ts` and `edge-objects.ts`, which are on the portable Worker's
+ * import path. A `node:` specifier anywhere in that graph survives bundling as
+ * a real static import, and a wrapper host (self-hosted Takoserver, managed
+ * Workers-for-Platforms) runs the Worker with no `nodejs_compat` flag — the
+ * portable `WorkerVersion` form has nowhere to ask for one — so the module
+ * fails to load with `No such module "node:path"` before a single request is
+ * served. Nothing in this file may be imported from a module the Worker
+ * bundle reaches; `scripts/check-worker-bundle-portable.mjs` enforces that.
+ */
+
+import path from "node:path";
+
+import { hasNulByte } from "./shared.ts";
+
+export function isPathWithinBasePath(
+  basePath: string,
+  candidatePath: string,
+): boolean {
+  const relative = path.relative(basePath, candidatePath);
+  return (
+    relative === "" ||
+    (!relative.startsWith("..") && !path.isAbsolute(relative))
+  );
+}
+
+export function resolvePathWithinBasePath(
+  basePath: string,
+  key: string,
+): string {
+  if (hasNulByte(key)) {
+    throw new Error("Invalid path");
+  }
+  const resolvedPath = path.resolve(basePath, key);
+  if (!isPathWithinBasePath(basePath, resolvedPath)) {
+    throw new Error("Path escapes base directory");
+  }
+  return resolvedPath;
+}
+
+function isNotFoundError(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    (error as { code?: unknown }).code === "ENOENT"
+  );
+}
+
+export async function assertPathChainWithinBasePath(
+  basePath: string,
+  targetPath: string,
+  realpath: (path: string) => Promise<string>,
+): Promise<void> {
+  let currentPath = targetPath;
+
+  while (true) {
+    try {
+      const realCurrentPath = await realpath(currentPath);
+      if (!isPathWithinBasePath(basePath, realCurrentPath)) {
+        throw new Error("Path escapes base directory");
+      }
+      return;
+    } catch (error) {
+      if (!isNotFoundError(error)) {
+        throw error;
+      }
+      const parentPath = path.dirname(currentPath);
+      if (parentPath === currentPath) {
+        throw error;
+      }
+      currentPath = parentPath;
+    }
+  }
+}

package/src/backend/runtime/public-origin.ts

@@ -0,0 +1,263 @@
+/**
+ * The one absolute origin this instance is: `APP_URL`, or the one a request
+ * established when the Host — not the deployer — chose it.
+ *
+ * Every federated identity this app mints is absolute. Actor ids, activity and
+ * object ids, `inbox` / `outbox` / `followers` collections, the OIDC
+ * `redirect_uri`, notification links, and the `.well-known` discovery documents
+ * are all `${APP_URL}/…`, and a wrong one is not a broken page — it is a
+ * permanent, federated wrong answer that remote servers have already cached.
+ *
+ * `APP_URL` is a plain variable, and on a wrapper host it cannot always be one.
+ * A Takoform `WorkerEndpoint` allocates the Worker's public origin AFTER the
+ * `WorkerVersion` that would have carried the variable is already immutable, so
+ * the deployer does not know the value at apply time and there is no second
+ * apply that could inject it. The origin exists, but only the Host knows it,
+ * and the only place it is ever spoken is on the requests the Host routes here.
+ *
+ * So on the `portable` lane an unset `APP_URL` is answered by OBSERVING one
+ * request and PINNING what it observed:
+ *
+ *   1. `APP_URL` is authoritative whenever it is set. It is used exactly as the
+ *      operator wrote it and is never validated, cached, or persisted here —
+ *      an operator who sets it has already decided, and this module has no
+ *      standing to refuse a value the previous release accepted.
+ *   2. Otherwise the origin PINNED IN KV wins, for every request and for
+ *      background work alike. First writer wins: once a value is stored, no
+ *      later request replaces it, whatever `Host` that request carried.
+ *   3. Otherwise a request may establish it, from the request URL's own origin
+ *      and from nothing else.
+ *   4. Otherwise there is no origin, and background work refuses rather than
+ *      minting `undefined/ap/users/alice`.
+ *
+ * WHAT IS TRUSTED. The request URL as the runtime delivers it, and only that.
+ * Not `X-Forwarded-Host`, not `X-Forwarded-Proto`, not `Host` read out of the
+ * headers — nothing a client can write. Both wrapper hosts route by hostname
+ * and deliver the request they received on the Worker's own public endpoint:
+ * Takoserver's managed Workers-for-Platforms gateway looks up a host route for
+ * `new URL(request.url).hostname` and dispatches the SAME `Request` object, and
+ * the self-host workerd router picks a service from a table keyed by hostname
+ * and forwards unchanged. A hostname nobody published for this Worker is a 404
+ * before any of this code runs, so the origin on the request is one the Host
+ * assigned — which is exactly the value that could not be delivered as a var.
+ *
+ * WHY HTTPS. A public fediverse origin is https, and Takoserver's own
+ * `WorkerEndpoint` can only ever assign an https origin. Requiring it here
+ * means an http request cannot pin an origin that would then sign deliveries
+ * and mint actor ids. Loopback http is the one exception, because `localhost`
+ * is not routable and is the origin a developer actually serves on.
+ *
+ * A wrapper host that terminates TLS in FRONT of workerd and speaks plain http
+ * to it therefore establishes nothing: `request.url` is `http://…` and the
+ * derivation refuses. That deployment must set `APP_URL`, which it can, because
+ * an operator who terminates TLS chose the hostname themselves. Refusing is the
+ * point — the alternative is trusting a forwarded-proto header that the same
+ * proxy may or may not be the only writer of.
+ */
+
+import type { Env, EnvVars } from "../types.ts";
+import type { IKeyValueStore } from "./types.ts";
+
+/**
+ * Where the observed origin is pinned.
+ *
+ * The key is shared with the origin pin Yurucommu's own generated Worker entry
+ * writes, so a deployment that pinned an origin under the product's
+ * implementation keeps it when the product delegates to this one.
+ */
+export const CANONICAL_ORIGIN_KV_KEY =
+  "__yurucommu/runtime/canonical-origin/v1";
+
+/** No usable public origin, or a candidate that may not become one. */
+export class PublicOriginError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "PublicOriginError";
+  }
+}
+
+/**
+ * Hostnames whose http origin is still trustworthy, because they are not
+ * routable off the machine. `*.localhost` is included: RFC 6761 reserves the
+ * whole tree for loopback, and a self-host Worker endpoint on a local Takoserver
+ * is `<script>.localhost`.
+ */
+function isLoopbackHostname(hostname: string): boolean {
+  return (
+    hostname === "localhost" ||
+    hostname === "127.0.0.1" ||
+    hostname === "[::1]" ||
+    hostname.endsWith(".localhost")
+  );
+}
+
+/**
+ * Reduce a candidate to a bare origin, or refuse it.
+ *
+ * Refuses anything that is not just an origin — a path, a query, a fragment,
+ * embedded credentials — because the value is concatenated with `/ap/users/…`
+ * at hundreds of call sites and a stray path would silently produce a second,
+ * parallel set of actor ids.
+ */
+export function canonicalPublicOrigin(value: string): string {
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new PublicOriginError(
+      `"${value}" is not a URL and cannot be this instance's public origin.`,
+    );
+  }
+  if (
+    url.username !== "" ||
+    url.password !== "" ||
+    url.search !== "" ||
+    url.hash !== "" ||
+    url.pathname !== "/"
+  ) {
+    throw new PublicOriginError(
+      `"${value}" is not a bare origin; this instance's public origin must ` +
+        `carry no path, query, fragment, or credentials.`,
+    );
+  }
+  if (
+    url.protocol !== "https:" &&
+    !(url.protocol === "http:" && isLoopbackHostname(url.hostname))
+  ) {
+    throw new PublicOriginError(
+      `"${value}" is not an https origin. A public origin observed from a ` +
+        `request must be https (loopback http is the only exception); set ` +
+        `APP_URL explicitly when this Worker is served over plain http.`,
+    );
+  }
+  return url.origin;
+}
+
+/** `APP_URL` exactly as the operator set it, or null when it is not set. */
+export function configuredAppUrl(env: Partial<EnvVars>): string | null {
+  const raw = typeof env.APP_URL === "string" ? env.APP_URL.trim() : "";
+  return raw.length > 0 ? raw : null;
+}
+
+/**
+ * The origin this isolate has already established.
+ *
+ * Cached because the alternative is a KV read on the hot path of every single
+ * request, and because the value cannot legitimately change: first writer wins,
+ * so a second read can only ever return what the first one did. An operator who
+ * deliberately re-pins a different origin (see {@link resetObservedPublicOrigin})
+ * is served the new value by isolates started after the change.
+ */
+let observedPublicOrigin: string | null = null;
+
+/** Forget this isolate's observation. Tests, and an operator-driven re-pin. */
+export function resetObservedPublicOrigin(): void {
+  observedPublicOrigin = null;
+}
+
+/** What this isolate has observed so far, without touching KV. */
+export function peekObservedPublicOrigin(): string | null {
+  return observedPublicOrigin;
+}
+
+type PublicOriginEnv = Partial<EnvVars> & { KV?: IKeyValueStore };
+
+function requireKv(env: PublicOriginEnv): IKeyValueStore {
+  if (!env.KV) {
+    throw new PublicOriginError(
+      "KV is not bound, so this instance's public origin can be neither read " +
+        "nor pinned. Bind KV, or set APP_URL.",
+    );
+  }
+  return env.KV;
+}
+
+async function readPinnedOrigin(kv: IKeyValueStore): Promise<string | null> {
+  const stored = await kv.get(CANONICAL_ORIGIN_KV_KEY);
+  if (stored === null) return null;
+  // A stored value that no longer canonicalizes is a refusal, never a silent
+  // fallback to the current request: it means somebody wrote the key by hand.
+  return canonicalPublicOrigin(stored);
+}
+
+/**
+ * Establish this instance's public origin from one request, once.
+ *
+ * CONSISTENCY. The pin lives in KV, the one store both lanes always have (`DB`
+ * is equally present, but the origin is needed by the readiness probe and by
+ * queue work that must not open a transaction to learn its own name). KV is
+ * eventually consistent and has no compare-and-swap, so "first writer wins" is
+ * enforced by reading before writing and then READING BACK: an isolate that
+ * finds a different origin on the read-back lost the race and refuses this
+ * request rather than serving two identities. The next request reads the
+ * winner's value through the ordinary stored-value path. A read-back that has
+ * not converged yet (null) is treated as our own write, because we wrote it.
+ */
+export async function establishRequestPublicOrigin(
+  env: PublicOriginEnv,
+  request: Request,
+): Promise<string> {
+  if (observedPublicOrigin !== null) return observedPublicOrigin;
+
+  const kv = requireKv(env);
+  const pinned = await readPinnedOrigin(kv);
+  if (pinned !== null) {
+    observedPublicOrigin = pinned;
+    return pinned;
+  }
+
+  const requestOrigin = canonicalPublicOrigin(new URL(request.url).origin);
+  await kv.put(CANONICAL_ORIGIN_KV_KEY, requestOrigin);
+  const readback = await kv.get(CANONICAL_ORIGIN_KV_KEY);
+  if (readback !== null && canonicalPublicOrigin(readback) !== requestOrigin) {
+    throw new PublicOriginError(
+      `this instance's public origin was concurrently pinned to ` +
+        `"${readback}" while this request was establishing ` +
+        `"${requestOrigin}". The pinned origin stands; retry.`,
+    );
+  }
+  observedPublicOrigin = requestOrigin;
+  return requestOrigin;
+}
+
+/**
+ * The public origin for work that has no request to read it from.
+ *
+ * Queue consumers sign federation deliveries and address them from this
+ * instance's actor ids; there is no request in scope and nothing to derive one
+ * from. `APP_URL` first, then the pinned origin, then a refusal — never a
+ * guess, and never `undefined` concatenated into an actor id.
+ */
+export async function requireBackgroundPublicOrigin(
+  env: PublicOriginEnv,
+): Promise<string> {
+  const configured = configuredAppUrl(env);
+  if (configured !== null) return configured;
+  if (observedPublicOrigin !== null) return observedPublicOrigin;
+
+  const pinned = await readPinnedOrigin(requireKv(env));
+  if (pinned === null) {
+    throw new PublicOriginError(
+      "this instance's public origin has not been observed yet: APP_URL is " +
+        "unset and no request has pinned an origin. Serve one request on the " +
+        "Worker's public endpoint before background delivery can address " +
+        "anything.",
+    );
+  }
+  observedPublicOrigin = pinned;
+  return pinned;
+}
+
+/**
+ * The env background work should run with: `APP_URL` present, or a refusal.
+ *
+ * Returned as a copy rather than by mutating the caller's bindings, so the same
+ * `env` may be handed to several handlers without one of them rewriting what
+ * the others read.
+ */
+export async function withRequiredBackgroundPublicOrigin(
+  env: Env,
+): Promise<Env> {
+  if (configuredAppUrl(env) !== null) return env;
+  return { ...env, APP_URL: await requireBackgroundPublicOrigin(env) };
+}

package/src/backend/runtime/shared.ts

@@ -1,4 +1,12 @@
-import path from "node:path";
+/**
+ * Runtime helpers shared by EVERY lane, including the portable Worker.
+ *
+ * `edge-kv.ts` and `edge-objects.ts` import this module, so it is part of the
+ * bundle a wrapper host loads with no `nodejs_compat` flag. It must therefore
+ * stay free of `node:` specifiers; the filesystem path helpers that need
+ * `node:path` live in `node-paths.ts`, which only the Bun/Node runtime
+ * imports.
+ */
 
 export const DEFAULT_LIST_LIMIT = 1000;
 
@@ -35,67 +43,6 @@ export function hasNulByte(value: string): boolean {
   return value.includes("\0");
 }
 
-export function isPathWithinBasePath(
-  basePath: string,
-  candidatePath: string,
-): boolean {
-  const relative = path.relative(basePath, candidatePath);
-  return (
-    relative === "" ||
-    (!relative.startsWith("..") && !path.isAbsolute(relative))
-  );
-}
-
-export function resolvePathWithinBasePath(
-  basePath: string,
-  key: string,
-): string {
-  if (hasNulByte(key)) {
-    throw new Error("Invalid path");
-  }
-  const resolvedPath = path.resolve(basePath, key);
-  if (!isPathWithinBasePath(basePath, resolvedPath)) {
-    throw new Error("Path escapes base directory");
-  }
-  return resolvedPath;
-}
-
-function isNotFoundError(error: unknown): boolean {
-  return (
-    typeof error === "object" &&
-    error !== null &&
-    "code" in error &&
-    (error as { code?: unknown }).code === "ENOENT"
-  );
-}
-
-export async function assertPathChainWithinBasePath(
-  basePath: string,
-  targetPath: string,
-  realpath: (path: string) => Promise<string>,
-): Promise<void> {
-  let currentPath = targetPath;
-
-  while (true) {
-    try {
-      const realCurrentPath = await realpath(currentPath);
-      if (!isPathWithinBasePath(basePath, realCurrentPath)) {
-        throw new Error("Path escapes base directory");
-      }
-      return;
-    } catch (error) {
-      if (!isNotFoundError(error)) {
-        throw error;
-      }
-      const parentPath = path.dirname(currentPath);
-      if (parentPath === currentPath) {
-        throw error;
-      }
-      currentPath = parentPath;
-    }
-  }
-}
-
 export async function readStream(
   stream: ReadableStream<Uint8Array>,
 ): Promise<Uint8Array> {