@substrat-run/vertical-host 0.148.0 → 0.149.0

package/dist/outbound-calls.d.ts

@@ -0,0 +1,94 @@
+/**
+ * The outbound calls a request made, on its invocation line (#2192).
+ *
+ * A request that failed BECAUSE of an upstream answer — an OAuth callback whose token
+ * exchange was refused — used to show a single `request` span: the call that actually
+ * failed was nowhere on the timeline. So the platform's entry records every `fetch` the
+ * request makes, the way it records its store calls (#2245): the request runs in an
+ * `AsyncLocalStorage` holding its record, and a wrapped `globalThis.fetch` adds each call to
+ * whichever record is current. Module code cannot fetch (boundary-lint R3); what is recorded
+ * is the vertical's host code — its connectors and harness routes.
+ *
+ * ## What is written, and what never is
+ *
+ * The host, the method, the status, the time to the response headers, when in the request
+ * the call started, and how it ended. Never a header, a body, a query string, a fragment or
+ * userinfo, and the path only after {@link redactOutboundPath}: a path segment can be a
+ * credential (an API key, a bot token), and a log line is read by a wider audience, for
+ * longer, than the call ever had.
+ *
+ * A refusal by the PLATFORM — the egress worker answering a host the vertical never declared —
+ * is recorded as `refused`, read off `x-substrat-egress: refused`. To the vertical's code it is
+ * a bare 403, the same as the destination's own; on the line the two read differently.
+ *
+ * ## What it does not see
+ *
+ * - A `fetch` made inside a Durable Object (a consumer, a schedule, the drain): no request's
+ *   record is current there.
+ * - A `fetch` still running after the line was written (`waitUntil` work).
+ * - A reference to `fetch` a bundle captured while its modules were evaluated: the entry
+ *   installs the wrapper after that, because the vertical's import is evaluated first.
+ *
+ * And one property to know: a call is attributed to the request whose `AsyncLocalStorage`
+ * context it runs in, as a store call is. A call a promise shared across requests makes lands on
+ * the line of the request it runs under.
+ *
+ * ## It cannot fail the call
+ *
+ * Outside a request the wrapper hands the call straight to the runtime's `fetch`, and inside
+ * one it passes the arguments on untouched — the body is never read, the signal never
+ * replaced — and hands back the runtime's own response or rejection. Recording is advisory: a
+ * throw from it is swallowed, never the call's.
+ */
+import { type OutboundCallTally } from '@substrat-run/kernel/invocation-line';
+/**
+ * The response header the egress worker marks its own refusals with — its `EGRESS_HEADER`
+ * (`apps/vertical-egress/src/worker.ts`). Spelled twice, because the worker is not a package
+ * this one can import; `outbound-calls.test.ts` holds the two equal.
+ */
+export declare const EGRESS_REFUSAL_HEADER = "x-substrat-egress";
+/**
+ * Whether one path segment is kept as it is. Default-deny: a segment of at most 40 characters
+ * is kept ONLY when it is lowercase words (at most 4, each at most 16 letters, joined by `-` or
+ * `_`), optionally with a short file extension, an integer of at most 10 digits, or a version token (`v1`, `v2.1`). Everything else
+ * is redacted — every UUID and ULID, any segment mixing letters and digits (`oauth2`, `abc1234`),
+ * anything with an uppercase letter (an owner or a repository named `Acme`), and any longer
+ * number. An id in a path is not needed to diagnose a failed call: the host, the method, the
+ * status, the outcome and the path's shape are.
+ *
+ * What still survives, stated: a lowercase-letter word of up to 16 letters (per part) and an
+ * integer of up to 10 digits are written as they are, whatever they mean to the destination.
+ */
+export declare function keepsSegment(segment: string): boolean;
+/**
+ * The path of an outbound URL as the line writes it: each segment that {@link keepsSegment}
+ * does not keep is `[redacted]`, and the result is cut at {@link PATH_MAX} characters. The
+ * query string and fragment are not part of a pathname and so never reach it.
+ */
+export declare function redactOutboundPath(pathname: string): string;
+/** The tally a request's calls go on: the invocation record, or anything shaped like it. */
+export type OutboundRecording = OutboundCallTally;
+/** Note when the request a recording belongs to started. Never throws. */
+export declare function markRequestStart(recording: OutboundRecording, started: number): void;
+/** What the wrapper needs from the platform: the recording of the request now running. */
+export type CurrentRecording = () => OutboundRecording | undefined;
+type FetchFn = (input: unknown, init?: unknown) => Promise<{
+    status: number;
+    headers?: {
+        get?(name: string): string | null;
+    };
+}>;
+/**
+ * Wrap `fetch` so each call made while a request's recording is current is added to it.
+ * Exported for the tests; the platform installs it with {@link installOutboundRecorder}.
+ */
+export declare function recordingFetch<F extends FetchFn>(original: F, current: CurrentRecording): F;
+/**
+ * Put the recorder in front of the isolate's `fetch`, once. A `fetch` that already carries the
+ * mark — installed by this request's entry, a previous one, or another copy of this module — is
+ * left as it is, so evaluating the entry again never wraps twice. Something that replaced
+ * `globalThis.fetch` since (a test's mock) is wrapped in turn. Never throws.
+ */
+export declare function installOutboundRecorder(current: CurrentRecording): void;
+export {};
+//# sourceMappingURL=outbound-calls.d.ts.map

package/dist/outbound-calls.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbound-calls.d.ts","sourceRoot":"","sources":["../src/outbound-calls.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,OAAO,EAIL,KAAK,iBAAiB,EACvB,MAAM,sCAAsC,CAAC;AAE9C;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,sBAAsB,CAAC;AAyBzD;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CASrD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAM3D;AAiCD,4FAA4F;AAC5F,MAAM,MAAM,iBAAiB,GAAG,iBAAiB,CAAC;AAelD,0EAA0E;AAC1E,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAMpF;AAED,0FAA0F;AAC1F,MAAM,MAAM,gBAAgB,GAAG,MAAM,iBAAiB,GAAG,SAAS,CAAC;AA0CnE,KAAK,OAAO,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE;QAAE,GAAG,CAAC,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAA;KAAE,CAAA;CAAE,CAAC,CAAC;AAiBhI;;;GAGG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,OAAO,EAAE,gBAAgB,GAAG,CAAC,CAsD3F;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI,CASvE"}

package/dist/outbound-calls.js

@@ -0,0 +1,282 @@
+/**
+ * The outbound calls a request made, on its invocation line (#2192).
+ *
+ * A request that failed BECAUSE of an upstream answer — an OAuth callback whose token
+ * exchange was refused — used to show a single `request` span: the call that actually
+ * failed was nowhere on the timeline. So the platform's entry records every `fetch` the
+ * request makes, the way it records its store calls (#2245): the request runs in an
+ * `AsyncLocalStorage` holding its record, and a wrapped `globalThis.fetch` adds each call to
+ * whichever record is current. Module code cannot fetch (boundary-lint R3); what is recorded
+ * is the vertical's host code — its connectors and harness routes.
+ *
+ * ## What is written, and what never is
+ *
+ * The host, the method, the status, the time to the response headers, when in the request
+ * the call started, and how it ended. Never a header, a body, a query string, a fragment or
+ * userinfo, and the path only after {@link redactOutboundPath}: a path segment can be a
+ * credential (an API key, a bot token), and a log line is read by a wider audience, for
+ * longer, than the call ever had.
+ *
+ * A refusal by the PLATFORM — the egress worker answering a host the vertical never declared —
+ * is recorded as `refused`, read off `x-substrat-egress: refused`. To the vertical's code it is
+ * a bare 403, the same as the destination's own; on the line the two read differently.
+ *
+ * ## What it does not see
+ *
+ * - A `fetch` made inside a Durable Object (a consumer, a schedule, the drain): no request's
+ *   record is current there.
+ * - A `fetch` still running after the line was written (`waitUntil` work).
+ * - A reference to `fetch` a bundle captured while its modules were evaluated: the entry
+ *   installs the wrapper after that, because the vertical's import is evaluated first.
+ *
+ * And one property to know: a call is attributed to the request whose `AsyncLocalStorage`
+ * context it runs in, as a store call is. A call a promise shared across requests makes lands on
+ * the line of the request it runs under.
+ *
+ * ## It cannot fail the call
+ *
+ * Outside a request the wrapper hands the call straight to the runtime's `fetch`, and inside
+ * one it passes the arguments on untouched — the body is never read, the signal never
+ * replaced — and hands back the runtime's own response or rejection. Recording is advisory: a
+ * throw from it is swallowed, never the call's.
+ */
+import { tallyOutboundCall, } from '@substrat-run/kernel/invocation-line';
+/**
+ * The response header the egress worker marks its own refusals with — its `EGRESS_HEADER`
+ * (`apps/vertical-egress/src/worker.ts`). Spelled twice, because the worker is not a package
+ * this one can import; `outbound-calls.test.ts` holds the two equal.
+ */
+export const EGRESS_REFUSAL_HEADER = 'x-substrat-egress';
+/** The scope-store transport's host: those calls are already named, as `storeCalls` (#2245). */
+const STORE_CALL_HOST = 'store.substrat.internal';
+/** What a redacted segment is written as. */
+const REDACTED = '[redacted]';
+/** A path longer than this is cut, after redaction. */
+const PATH_MAX = 200;
+/**
+ * Lowercase words, at most 4 of them joined by `-` or `_`, each at most 16 letters:
+ * `messages`, `oauth_token`, `access-token`. Past four parts a segment is a token chunked by
+ * dashes, not a name.
+ */
+const WORDS = /^[a-z]{1,16}(?:[-_][a-z]{1,16}){0,3}$/;
+/** The same words with a short file extension: `me.json`, `token.json`, `clip.mp4`. */
+const WORDS_WITH_EXTENSION = /^[a-z]{1,16}(?:[-_][a-z]{1,16}){0,3}\.[a-z][a-z0-9]{0,4}$/;
+/** No kept segment is longer than this, whatever it is made of. */
+const SEGMENT_MAX = 40;
+/** An integer of at most 10 digits: a page number, a small numeric id. */
+const SMALL_INTEGER = /^[0-9]{1,10}$/;
+/** A version: `v1`, `v2.1`, `v10.0.3`. */
+const VERSION = /^v[0-9]{1,3}(?:\.[0-9]{1,3}){0,2}$/;
+/**
+ * Whether one path segment is kept as it is. Default-deny: a segment of at most 40 characters
+ * is kept ONLY when it is lowercase words (at most 4, each at most 16 letters, joined by `-` or
+ * `_`), optionally with a short file extension, an integer of at most 10 digits, or a version token (`v1`, `v2.1`). Everything else
+ * is redacted — every UUID and ULID, any segment mixing letters and digits (`oauth2`, `abc1234`),
+ * anything with an uppercase letter (an owner or a repository named `Acme`), and any longer
+ * number. An id in a path is not needed to diagnose a failed call: the host, the method, the
+ * status, the outcome and the path's shape are.
+ *
+ * What still survives, stated: a lowercase-letter word of up to 16 letters (per part) and an
+ * integer of up to 10 digits are written as they are, whatever they mean to the destination.
+ */
+export function keepsSegment(segment) {
+    if (segment.length > SEGMENT_MAX)
+        return false;
+    return (segment === '' ||
+        WORDS.test(segment) ||
+        WORDS_WITH_EXTENSION.test(segment) ||
+        SMALL_INTEGER.test(segment) ||
+        VERSION.test(segment));
+}
+/**
+ * The path of an outbound URL as the line writes it: each segment that {@link keepsSegment}
+ * does not keep is `[redacted]`, and the result is cut at {@link PATH_MAX} characters. The
+ * query string and fragment are not part of a pathname and so never reach it.
+ */
+export function redactOutboundPath(pathname) {
+    const path = pathname
+        .split('/')
+        .map((segment) => (keepsSegment(segment) ? segment : REDACTED))
+        .join('/');
+    return path.length > PATH_MAX ? `${path.slice(0, PATH_MAX)}…` : path;
+}
+/**
+ * A thrown value's class, when it reads as one — a capitalised name of letters only, ending in
+ * `Error` or `Exception` (`TypeError`, `TimeoutError`, `DOMException`) — and `Error` otherwise.
+ * Never its message. The name comes from whatever threw, a wrapper library included, so anything
+ * else it holds is not written.
+ */
+const ERROR_CLASS = /^[A-Z][A-Za-z]{0,30}(?:Error|Exception)$/;
+function errorName(e) {
+    const name = e?.name;
+    return typeof name === 'string' && ERROR_CLASS.test(name) ? name : 'Error';
+}
+/**
+ * How a call that answered ended. `refused` only for the platform's own refusal: a 403 carrying
+ * exactly `x-substrat-egress: refused`. The egress worker strips the mark from every answer it
+ * passes through, and the status is required too, so a destination cannot make its own answer
+ * read as the platform's.
+ */
+function answeredOutcome(response) {
+    if (response.status === 403 && response.headers?.get?.(EGRESS_REFUSAL_HEADER) === 'refused')
+        return 'refused';
+    return response.status >= 400 ? 'http-error' : 'ok';
+}
+/** How a call that rejected ended, and the class to name when it is `failed`. */
+function rejectedOutcome(e) {
+    const name = errorName(e);
+    if (name === 'TimeoutError')
+        return { outcome: 'timeout' };
+    if (name === 'AbortError')
+        return { outcome: 'aborted' };
+    return { outcome: 'failed', reason: name };
+}
+/**
+ * When each recording's request started — what a call's `atMs` is measured from. Kept beside
+ * the record rather than on it, since the record is handed to the vertical's handler chain, and
+ * under a GLOBAL symbol, since the copy that starts a request and the copy that recorded the
+ * call may be different module instances (the stamp registry's reason).
+ */
+const SINCE = Symbol.for('substrat.outbound-since');
+function sinceMap() {
+    const g = globalThis;
+    return (g[SINCE] ??= new WeakMap());
+}
+/** Note when the request a recording belongs to started. Never throws. */
+export function markRequestStart(recording, started) {
+    try {
+        sinceMap().set(recording, started);
+    }
+    catch {
+        /* calls then sit at the request's start */
+    }
+}
+/** The destination of a `fetch`'s arguments, read without touching a body. `null` when unreadable. */
+function destinationOf(input, init) {
+    const fromRequest = typeof input === 'object' && input !== null && !(input instanceof URL);
+    const raw = fromRequest ? input.url : input;
+    let url;
+    try {
+        url = new URL(String(raw));
+    }
+    catch {
+        return null;
+    }
+    const initMethod = init?.method;
+    const requestMethod = fromRequest ? input.method : undefined;
+    const method = typeof initMethod === 'string' ? initMethod : typeof requestMethod === 'string' ? requestMethod : 'GET';
+    return { url, method: method.toUpperCase().slice(0, 16) };
+}
+/** Add one finished call to the recording. Never throws. */
+function record(recording, destination, startedAt, end) {
+    try {
+        const call = {
+            host: destination.url.host.toLowerCase(),
+            path: redactOutboundPath(destination.url.pathname),
+            method: destination.method,
+            status: end.status,
+            outcome: end.outcome,
+            durationMs: Math.max(0, Date.now() - startedAt),
+            atMs: Math.max(0, startedAt - (sinceMap().get(recording) ?? startedAt)),
+            ...(end.reason !== undefined ? { reason: end.reason } : {}),
+        };
+        tallyOutboundCall(recording, call);
+    }
+    catch {
+        // Recording is advisory: a call that cannot be recorded is one missing entry.
+    }
+}
+/** The mark a wrapped `fetch` carries, shared by every copy of this module in the isolate. */
+const WRAPPED = Symbol.for('substrat.outbound-fetch');
+/**
+ * Set while a recorder is handing a call on, synchronously, and cleared before it returns.
+ *
+ * Something that patches `globalThis.fetch` after the recorder is installed (instrumentation
+ * that installs lazily) is wrapped again by the next request's install, so one call can pass
+ * through two recorders: recorder → patch → recorder → runtime. The inner one sees this set and
+ * hands the call straight on, so the call is recorded once, by the outermost recorder. It spans
+ * only the synchronous part of the call, so concurrent calls never see each other's: a patch that
+ * reaches the inner recorder only after an `await` is still recorded twice.
+ */
+const IN_CALL = Symbol.for('substrat.outbound-fetch.in-call');
+/**
+ * Wrap `fetch` so each call made while a request's recording is current is added to it.
+ * Exported for the tests; the platform installs it with {@link installOutboundRecorder}.
+ */
+export function recordingFetch(original, current) {
+    const wrapped = function fetch(input, init) {
+        const g = globalThis;
+        // An outer recorder is already recording this call: hand it on, unrecorded.
+        if (g[IN_CALL] === true)
+            return original.call(globalThis, input, init);
+        let recording;
+        let destination = null;
+        try {
+            recording = current();
+            if (recording)
+                destination = destinationOf(input, init);
+        }
+        catch {
+            recording = undefined;
+        }
+        // The runtime's `fetch` is called on `globalThis` — workerd refuses any other receiver.
+        if (!recording || !destination || destination.url.hostname.toLowerCase() === STORE_CALL_HOST) {
+            return original.call(globalThis, input, init);
+        }
+        const rec = recording;
+        const dest = destination;
+        const startedAt = Date.now();
+        let pending;
+        g[IN_CALL] = true;
+        try {
+            pending = original.call(globalThis, input, init);
+        }
+        finally {
+            g[IN_CALL] = false;
+        }
+        return pending.then((response) => {
+            let status = null;
+            let outcome = 'failed';
+            try {
+                status = response.status;
+                outcome = answeredOutcome(response);
+            }
+            catch {
+                /* recorded as far as it was read */
+            }
+            record(rec, dest, startedAt, { status, outcome });
+            return response;
+        }, (e) => {
+            let end = { outcome: 'failed', reason: 'Error' };
+            try {
+                end = rejectedOutcome(e);
+            }
+            catch {
+                /* recorded as a plain failure */
+            }
+            record(rec, dest, startedAt, { status: null, ...end });
+            throw e;
+        });
+    };
+    Object.defineProperty(wrapped, WRAPPED, { value: true });
+    return wrapped;
+}
+/**
+ * Put the recorder in front of the isolate's `fetch`, once. A `fetch` that already carries the
+ * mark — installed by this request's entry, a previous one, or another copy of this module — is
+ * left as it is, so evaluating the entry again never wraps twice. Something that replaced
+ * `globalThis.fetch` since (a test's mock) is wrapped in turn. Never throws.
+ */
+export function installOutboundRecorder(current) {
+    try {
+        const g = globalThis;
+        const existing = g.fetch;
+        if (typeof existing !== 'function' || existing[WRAPPED])
+            return;
+        g.fetch = recordingFetch(existing, current);
+    }
+    catch {
+        // A runtime whose `fetch` cannot be replaced simply has no outbound calls on the line.
+    }
+}
+//# sourceMappingURL=outbound-calls.js.map

package/dist/outbound-calls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outbound-calls.js","sourceRoot":"","sources":["../src/outbound-calls.ts"],"names":[],"mappings":"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"}

package/dist/peer-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"peer-client.d.ts","sourceRoot":"","sources":["../src/peer-client.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,WAAW,UAAU;IACzB,uEAAuE;IACvE,MAAM,CAAC,CAAC,GAAG,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAC5G;AAED,MAAM,WAAW,iBAAiB;IAChC,iFAAiF;IACjF,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAaD,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,UAAU,CAkCxF"}
+{"version":3,"file":"peer-client.d.ts","sourceRoot":"","sources":["../src/peer-client.ts"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,WAAW,UAAU;IACzB,uEAAuE;IACvE,MAAM,CAAC,CAAC,GAAG,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CAC5G;AAED,MAAM,WAAW,iBAAiB;IAChC,iFAAiF;IACjF,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;CACtB;AAaD,wBAAgB,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,UAAU,CAqCxF"}

package/dist/peer-client.js

@@ -1,5 +1,6 @@
 import { globalFetch } from '@substrat-run/kernel';
-import { PEER_CALL_URL, peerCallResponse, substratError } from '@substrat-run/contracts';
+import { currentInvocationId } from '@substrat-run/kernel/invocation-line';
+import { PARENT_REQUEST_ID_HEADER, parentRequestIdOf, PEER_CALL_URL, peerCallResponse, substratError, } from '@substrat-run/contracts';
 /** What a refused peer call throws: the platform's code and the reason, not a bare status. */
 const REFUSAL_BY_STATUS = {
     400: 'validation_failed',
@@ -14,9 +15,12 @@ export function peerClient(vertical, options = {}) {
     const call = options.fetch ?? globalFetch;
     return {
         async invoke(operation, input, invokeOptions) {
+            // #2192: the request this call is made from, so the target's line can name it as its
+            // parent. Absent outside a stamped request, and on a platform entry that predates it.
+            const parent = parentRequestIdOf(currentInvocationId());
             const response = await call(PEER_CALL_URL, {
                 method: 'POST',
-                headers: { 'content-type': 'application/json' },
+                headers: { 'content-type': 'application/json', ...(parent ? { [PARENT_REQUEST_ID_HEADER]: parent } : {}) },
                 body: JSON.stringify({
                     vertical,
                     operation,

package/dist/peer-client.js.map

@@ -1 +1 @@
-{"version":3,"file":"peer-client.js","sourceRoot":"","sources":["../src/peer-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,aAAa,EAAkB,MAAM,yBAAyB,CAAC;AAqCzG,8FAA8F;AAC9F,MAAM,iBAAiB,GAA8B;IACnD,GAAG,EAAE,mBAAmB;IACxB,GAAG,EAAE,WAAW;IAChB,GAAG,EAAE,WAAW;IAChB,GAAG,EAAE,UAAU;IACf,GAAG,EAAE,cAAc;IACnB,GAAG,EAAE,aAAa;IAClB,GAAG,EAAE,aAAa;CACnB,CAAC;AAEF,MAAM,UAAU,UAAU,CAAC,QAAgB,EAAE,OAAO,GAAsB,EAAE;IAC1E,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,IAAI,WAAW,CAAC;IAC1C,OAAO;QACL,KAAK,CAAC,MAAM,CAAI,SAAiB,EAAE,KAAe,EAAE,aAA2C;YAC7F,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,aAAa,EAAE;gBACzC,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;gBAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;oBACnB,QAAQ;oBACR,SAAS;oBACT,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC;oBACzC,GAAG,CAAC,aAAa,EAAE,cAAc,KAAK,SAAS;wBAC7C,CAAC,CAAC,EAAE;wBACJ,CAAC,CAAC,EAAE,cAAc,EAAE,aAAa,CAAC,cAAc,EAAE,CAAC;iBACtD,CAAC;aACH,CAAC,CAAC;YACH,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAiD,CAAC;YACvG,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,+EAA+E;gBAC/E,oFAAoF;gBACpF,+EAA+E;gBAC/E,4BAA4B;gBAC5B,MAAM,aAAa,CACjB,iBAAiB,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,UAAU,EAChD,OAAO,IAAI,EAAE,KAAK,KAAK,QAAQ;oBAC7B,CAAC,CAAC,IAAI,CAAC,KAAK;oBACZ,CAAC,CAAC,gBAAgB,QAAQ,kBAAkB,QAAQ,CAAC,MAAM,GAAG,CACjE,CAAC;YACJ,CAAC;YACD,MAAM,MAAM,GAAG,gBAAgB,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;YAChD,IAAI,CAAC,MAAM,CAAC,OAAO;gBAAE,MAAM,aAAa,CAAC,aAAa,EAAE,+BAA+B,QAAQ,GAAG,CAAC,CAAC;YACpG,OAAO,MAAM,CAAC,IAAI,CAAC,MAAW,CAAC;QACjC,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"peer-client.js","sourceRoot":"","sources":["../src/peer-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAC3E,OAAO,EACL,wBAAwB,EACxB,iBAAiB,EACjB,aAAa,EACb,gBAAgB,EAChB,aAAa,GAEd,MAAM,yBAAyB,CAAC;AAqCjC,8FAA8F;AAC9F,MAAM,iBAAiB,GAA8B;IACnD,GAAG,EAAE,mBAAmB;IACxB,GAAG,EAAE,WAAW;IAChB,GAAG,EAAE,WAAW;IAChB,GAAG,EAAE,UAAU;IACf,GAAG,EAAE,cAAc;IACnB,GAAG,EAAE,aAAa;IAClB,GAAG,EAAE,aAAa;CACnB,CAAC;AAEF,MAAM,UAAU,UAAU,CAAC,QAAgB,EAAE,OAAO,GAAsB,EAAE;IAC1E,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,IAAI,WAAW,CAAC;IAC1C,OAAO;QACL,KAAK,CAAC,MAAM,CAAI,SAAiB,EAAE,KAAe,EAAE,aAA2C;YAC7F,qFAAqF;YACrF,sFAAsF;YACtF,MAAM,MAAM,GAAG,iBAAiB,CAAC,mBAAmB,EAAE,CAAC,CAAC;YACxD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,aAAa,EAAE;gBACzC,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,wBAAwB,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE;gBAC1G,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;oBACnB,QAAQ;oBACR,SAAS;oBACT,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC;oBACzC,GAAG,CAAC,aAAa,EAAE,cAAc,KAAK,SAAS;wBAC7C,CAAC,CAAC,EAAE;wBACJ,CAAC,CAAC,EAAE,cAAc,EAAE,aAAa,CAAC,cAAc,EAAE,CAAC;iBACtD,CAAC;aACH,CAAC,CAAC;YACH,MAAM,IAAI,GAAG,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAiD,CAAC;YACvG,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;gBACjB,+EAA+E;gBAC/E,oFAAoF;gBACpF,+EAA+E;gBAC/E,4BAA4B;gBAC5B,MAAM,aAAa,CACjB,iBAAiB,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,UAAU,EAChD,OAAO,IAAI,EAAE,KAAK,KAAK,QAAQ;oBAC7B,CAAC,CAAC,IAAI,CAAC,KAAK;oBACZ,CAAC,CAAC,gBAAgB,QAAQ,kBAAkB,QAAQ,CAAC,MAAM,GAAG,CACjE,CAAC;YACJ,CAAC;YACD,MAAM,MAAM,GAAG,gBAAgB,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;YAChD,IAAI,CAAC,MAAM,CAAC,OAAO;gBAAE,MAAM,aAAa,CAAC,aAAa,EAAE,+BAA+B,QAAQ,GAAG,CAAC,CAAC;YACpG,OAAO,MAAM,CAAC,IAAI,CAAC,MAAW,CAAC;QACjC,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/upload-link.d.ts

@@ -25,10 +25,22 @@
  * target's `writePermission` as them, now. The link is spent in that transaction, so every
  * failure leaves it unspent.
  *
- * Answers: **201** `{ id, filename, contentType, size, sha256 }`; **404** for a secret that
- * names nothing and for a path naming another target than the link's (nothing is spent);
- * **410** for a link already used, expired or revoked; **413** over the link's size;
- * **415** for a type the link refuses; **403** when the minter no longer holds the key.
+ * Answers: **201** `{ id, filename, contentType, size, sha256 }`; **200** with the same body for
+ * a replay (below); **404** for a secret that
+ * names nothing — a malformed one answered here, without asking the scope — and for a path
+ * naming another target than the link's, whatever the link's state (nothing is spent);
+ * **410** for a link already used, expired or revoked at its own path; **413** over the link's size;
+ * **415** for a type the link refuses; **403** when the minter no longer holds the key; **422**
+ * for a replay whose bytes are not the stored file; **400** for an empty body or a malformed
+ * `Idempotency-Key`.
+ *
+ * **A lost reply is retryable (#2315).** A request may name itself with `Idempotency-Key` (16 to
+ * 255 visible ASCII characters other than `"` and `\`, such as a UUID; a quoted structured-field
+ * string is read without its quotes). The spend records the key's hash. A later request for the
+ * SAME link with the same key and the same bytes, before the link's expiry plus
+ * `UPLOAD_LINK_REPLAY_GRACE_SECONDS`, gets the stored record with **200** and writes nothing. Every other request for a spent link (no
+ * key, another key, past the window, or a file removed or swept since) gets the same 410, so a
+ * holder of the secret without the key learns nothing about the redemption.
  *
  * **Response hygiene, set before anything can fail.** `Cache-Control: no-store`,
  * `Referrer-Policy: no-referrer`, `X-Content-Type-Options: nosniff`. There is no `ETag`,
@@ -44,15 +56,16 @@ import type { Context, Env, Hono } from 'hono';
 import { type ScopeHost } from '@substrat-run/kernel';
 import type { CapabilityNode } from './capability-exchange.js';
 type Awaitable<T> = T | Promise<T>;
-/** Where `mountUploadLinkRedeem` listens unless told otherwise. */
+/**
+ * Where `mountUploadLinkRedeem` listens — the one path, not an option: `uploadLinkPath` mints
+ * URLs under it, and `invocationLog` redacts the secret segment under it.
+ */
 export declare const UPLOAD_LINK_REDEEM_PATH = "/api/attachment-uploads/:entityType/:entityId/:secret";
 export interface UploadLinkRedeemOptions<E extends Env = Env> {
     /** The host serving the scope. Taken structurally — any host with the two link verbs. */
     host: (c: Context<E>) => Awaitable<Pick<ScopeHost, 'inspectUploadLink' | 'redeemUploadLink'>>;
     /** Which scope this request is for — the router-asserted (tenant, scope) the vertical already resolves. */
     node: (c: Context<E>) => Awaitable<CapabilityNode>;
-    /** Defaults to `UPLOAD_LINK_REDEEM_PATH`; must carry `:entityType`, `:entityId` and `:secret`. */
-    path?: string;
 }
 /** The few types whose first bytes say what they are. Anything else is `null`: not sniffable, not suspect. */
 export declare function sniffMediaType(bytes: Uint8Array): string | null;
@@ -65,8 +78,8 @@ export declare function sniffMediaType(bytes: Uint8Array): string | null;
  */
 export declare function resolveUploadMediaType(header: string | undefined, filename: string, bytes: Uint8Array): string | null;
 /**
- * Mount `PUT <path>` and `POST <path>`: redeem one upload link. See the module header for the
- * answers and the hygiene.
+ * Mount `PUT` and `POST` on `UPLOAD_LINK_REDEEM_PATH`: redeem one upload link. See the module
+ * header for the answers and the hygiene.
  */
 export declare function mountUploadLinkRedeem<E extends Env>(app: Hono<E>, options: UploadLinkRedeemOptions<E>): void;
 export {};

package/dist/upload-link.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"upload-link.d.ts","sourceRoot":"","sources":["../src/upload-link.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAS/C,OAAO,EAML,KAAK,SAAS,EACf,MAAM,sBAAsB,CAAC;AAG9B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE/D,KAAK,SAAS,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAEnC,mEAAmE;AACnE,eAAO,MAAM,uBAAuB,0DAA6D,CAAC;AAElG,MAAM,WAAW,uBAAuB,CAAC,CAAC,SAAS,GAAG,GAAG,GAAG;IAC1D,yFAAyF;IACzF,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,IAAI,CAAC,SAAS,EAAE,mBAAmB,GAAG,kBAAkB,CAAC,CAAC,CAAC;IAC9F,2GAA2G;IAC3G,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,cAAc,CAAC,CAAC;IACnD,kGAAkG;IAClG,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AA4BD,8GAA8G;AAC9G,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAM/D;AAQD;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,UAAU,GAChB,MAAM,GAAG,IAAI,CAQf;AAyHD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,uBAAuB,CAAC,CAAC,CAAC,GAAG,IAAI,CAwE5G"}
+{"version":3,"file":"upload-link.d.ts","sourceRoot":"","sources":["../src/upload-link.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAY/C,OAAO,EAQL,KAAK,SAAS,EACf,MAAM,sBAAsB,CAAC;AAG9B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAE/D,KAAK,SAAS,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAEnC;;;GAGG;AACH,eAAO,MAAM,uBAAuB,0DAA6D,CAAC;AAElG,MAAM,WAAW,uBAAuB,CAAC,CAAC,SAAS,GAAG,GAAG,GAAG;IAC1D,yFAAyF;IACzF,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,IAAI,CAAC,SAAS,EAAE,mBAAmB,GAAG,kBAAkB,CAAC,CAAC,CAAC;IAC9F,2GAA2G;IAC3G,IAAI,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,SAAS,CAAC,cAAc,CAAC,CAAC;CACpD;AA4BD,8GAA8G;AAC9G,wBAAgB,cAAc,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,GAAG,IAAI,CAM/D;AAID;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,UAAU,GAChB,MAAM,GAAG,IAAI,CAQf;AA8ID;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,uBAAuB,CAAC,CAAC,CAAC,GAAG,IAAI,CAgF5G"}

package/dist/upload-link.js

@@ -1,7 +1,10 @@
-import { PROBLEM_CONTENT_TYPE, UPLOAD_LINK_PATH_PREFIX, substratError, uploadLinkFilename, } from '@substrat-run/contracts';
-import { UPLOAD_LINK_GONE, UPLOAD_LINK_TOO_LARGE, UPLOAD_LINK_TYPE_REFUSED, UPLOAD_LINK_WRONG_TARGET, uploadContentTypeAllowed, } from '@substrat-run/kernel';
+import { PROBLEM_CONTENT_TYPE, UPLOAD_LINK_IDEMPOTENCY_HEADER, UPLOAD_LINK_PATH_PREFIX, isUploadLinkIdempotencyKey, isUploadLinkSecretShape, substratError, uploadLinkFilename, } from '@substrat-run/contracts';
+import { UPLOAD_LINK_GONE, UPLOAD_LINK_REPLAY_MISMATCH, UPLOAD_LINK_TOO_LARGE, UPLOAD_LINK_TYPE_REFUSED, UPLOAD_LINK_WRONG_TARGET, normalizeUploadMediaType, uploadContentTypeAllowed, } from '@substrat-run/kernel';
 import { problemOf, messageOf } from './errors.js';
-/** Where `mountUploadLinkRedeem` listens unless told otherwise. */
+/**
+ * Where `mountUploadLinkRedeem` listens — the one path, not an option: `uploadLinkPath` mints
+ * URLs under it, and `invocationLog` redacts the secret segment under it.
+ */
 export const UPLOAD_LINK_REDEEM_PATH = `${UPLOAD_LINK_PATH_PREFIX}/:entityType/:entityId/:secret`;
 // ---------------------------------------------------------------------------
 // The media type. A client's `Content-Type` is a claim; the bytes get a say where they can.
@@ -37,10 +40,6 @@ export function sniffMediaType(bytes) {
     return null;
 }
 const SNIFFABLE = new Set(['application/pdf', 'image/png', 'image/jpeg', 'image/gif']);
-const normalizeType = (raw) => {
-    const t = raw.split(';')[0].trim().toLowerCase();
-    return t === 'image/jpg' ? 'image/jpeg' : t;
-};
 /**
  * The type the platform will record. Order: the request's own `Content-Type` unless it is
  * generic (`curl --upload-file` sends none), else the file name's extension, else what the
@@ -49,7 +48,7 @@ const normalizeType = (raw) => {
  * another claim: a `.pdf` that is a PNG is not what the link's allowlist was written for.
  */
 export function resolveUploadMediaType(header, filename, bytes) {
-    const fromHeader = header ? normalizeType(header) : '';
+    const fromHeader = header ? normalizeUploadMediaType(header) : '';
     const ext = filename.includes('.') ? filename.slice(filename.lastIndexOf('.') + 1).toLowerCase() : '';
     const claimed = fromHeader && !GENERIC_TYPES.has(fromHeader) ? fromHeader : (EXTENSION_TYPES[ext] ?? null);
     const sniffed = sniffMediaType(bytes);
@@ -132,6 +131,7 @@ const STATUS_BY_REASON = {
     [UPLOAD_LINK_TOO_LARGE]: 413,
     [UPLOAD_LINK_TYPE_REFUSED]: 415,
     [UPLOAD_LINK_WRONG_TARGET]: 404,
+    [UPLOAD_LINK_REPLAY_MISMATCH]: 422,
 };
 const CORS_HEADERS = [
     'access-control-allow-origin',
@@ -170,11 +170,26 @@ function errorStatus(err) {
     return (code && STATUS_BY_CODE[code]) || 500;
 }
 /**
- * Mount `PUT <path>` and `POST <path>`: redeem one upload link. See the module header for the
- * answers and the hygiene.
+ * The `Idempotency-Key` a request carries, or `undefined` for none: the bare token, or one
+ * structured-field string (`"…"`, the IETF draft's spelling) with its quotes taken off. Anything
+ * else is a 400 — never a key matched loosely.
+ */
+function idempotencyKeyOf(header) {
+    if (header === undefined)
+        return undefined;
+    const key = header.length >= 2 && header.startsWith('"') && header.endsWith('"') ? header.slice(1, -1) : header;
+    if (!isUploadLinkIdempotencyKey(key)) {
+        throw substratError('validation_failed', 'An Idempotency-Key is 16 to 255 visible ASCII characters, with no space, quote or backslash, such as a UUID.');
+    }
+    return key;
+}
+/** The 404 every secret that names nothing gets — the scope's answer, and this route's for a malformed one. */
+const unknownLink = () => substratError('not_found', 'This upload link is not valid.');
+/**
+ * Mount `PUT` and `POST` on `UPLOAD_LINK_REDEEM_PATH`: redeem one upload link. See the module
+ * header for the answers and the hygiene.
  */
 export function mountUploadLinkRedeem(app, options) {
-    const path = options.path ?? UPLOAD_LINK_REDEEM_PATH;
     const handler = async (c) => {
         // Before anything can fail: nothing here may be cached or handed onwards, and an outer
         // blanket CORS layer must not make the answer readable by a page that learned the link.
@@ -187,20 +202,21 @@ export function mountUploadLinkRedeem(app, options) {
             const entityType = c.req.param('entityType');
             const entityId = c.req.param('entityId');
             const secret = c.req.param('secret');
-            if (!entityType || !entityId || !secret)
-                throw substratError('not_found', 'This upload link is not valid.');
+            // A secret that cannot be one the kernel minted costs the scope nothing: the same 404 an
+            // unknown one gets, before the host, the scope or its Durable Object is touched.
+            if (!entityType || !entityId || !isUploadLinkSecretShape(secret))
+                throw unknownLink();
+            // #2315: the redeemer's own id for this redemption, judged before the scope is asked, so a
+            // malformed one is the same 400 whatever the link's state.
+            const idempotencyKey = idempotencyKeyOf(c.req.header(UPLOAD_LINK_IDEMPOTENCY_HEADER));
             const [host, node] = await Promise.all([options.host(c), options.node(c)]);
             if (!host.inspectUploadLink || !host.redeemUploadLink) {
                 throw substratError('unavailable', 'this scope host serves no upload links');
             }
-            // The link first, so a refusal costs no body: unknown (404), used / expired / revoked (410),
-            // and what the body will be judged against.
-            const view = await host.inspectUploadLink(node.tenantId, node.scopeId, secret);
-            if (view.entity.entityType !== entityType || view.entity.entityId !== entityId) {
-                throw substratError('not_found', 'This upload link is not valid for that target.', {
-                    reason: UPLOAD_LINK_WRONG_TARGET,
-                });
-            }
+            // The link first, so a refusal costs no body: unknown or minted for another target (404,
+            // judged before its state), used / expired / revoked (410), and what the body will be
+            // judged against.
+            const view = await host.inspectUploadLink(node.tenantId, node.scopeId, secret, { entityType, entityId }, idempotencyKey);
             const filename = view.filename ??
                 cleanFilename(c.req.query('filename')) ??
                 cleanFilename(dispositionFilename(c.req.header('content-disposition'))) ??
@@ -230,20 +246,22 @@ export function mountUploadLinkRedeem(app, options) {
                 filename,
                 contentType,
                 body,
+                ...(idempotencyKey !== undefined ? { idempotencyKey } : {}),
             });
+            // 200 for a replay of the redemption that spent the link, 201 for a file stored now.
             return c.body(JSON.stringify({
                 id: record.id,
                 filename: record.filename,
                 contentType: record.contentType,
                 size: record.size,
                 sha256: record.sha256,
-            }), 201, { 'content-type': 'application/json' });
+            }), record.replayed ? 200 : 201, { 'content-type': 'application/json' });
         }
         catch (err) {
             return refuse(c, err);
         }
     };
-    app.put(path, handler);
-    app.post(path, handler);
+    app.put(UPLOAD_LINK_REDEEM_PATH, handler);
+    app.post(UPLOAD_LINK_REDEEM_PATH, handler);
 }
 //# sourceMappingURL=upload-link.js.map