fix(browser-transfer): allow maxClockSkewMs on session and capability lifetime ceilings (01-06)

A server lifetime equal to the client ceiling was refused as soon as the
device clock ran slightly behind, and the error did not read as a clock
problem. Both ceilings now allow maxClockSkewMs (default 60 s), as image-cdn
already does; the doc states the server-side lifetime conditions.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-25 22:25:44 +09:00
co-authored by Claude Opus 5.5
parent 426b6b8eec
commit c0b7ff1576
8 changed files with 124 additions and 2 deletions
@@ -164,6 +164,14 @@ URL을 발급하면 안 된다.
- capability를 async 대기하는 동안 caller 입력과 dependency method를 snapshot한다.
- 사용 전에 만료뿐 아니라 최소 잔여 lifetime도 검사한다.
- 기기 시계가 서버보다 `maxClockSkewMs`(기본 60초)까지 늦어도 수명 상한 검사는
거절하지 않는다. 서버는 session 수명을 `maxSessionLifetimeMs` 이하, capability
수명을 `maxCapabilityTtlMs` 이하로 주면 된다(`upload-response-validation.ts`
`validateSession`, `presigned-capability-http-provider.ts` `maxClockSkewMs`).
하한은 느슨하게 하지 않는다. 기기 시계가 빠르면 수명이 그만큼 짧아 보이므로
서버 capability 수명은 `minimumRemainingLifetimeMs + maxClockSkewMs`와
`capabilityRefreshSkewMs + maxClockSkewMs`보다 길어야 한다. 기기 시계가 이보다
더 빠르면 그 기기에서는 capability가 만료로 보인다.
- 만료/403은 임의 retry가 아니라 control plane의 새 capability 발급으로 복구한다.
- ambiguous network failure 뒤 upload part를 새 bytes로 덮어쓰지 않는다.
- client-side single-use map은 UX 최적화일 뿐이다. cross-tab/replay authority는
@@ -87,6 +87,14 @@ export type PresignedCapabilityHttpProviderOptions = Readonly<{
* with a token that is predictably going to expire in flight.
*/
minimumRemainingLifetimeMs: number;
/**
* 01-06. How far the device clock may trail the server's. A capability is
* refused as too long-lived only past `maxCapabilityTtlMs` plus this.
* Default 60 s. The lower bound is not relaxed: a server lifetime must be at
* least `minimumRemainingLifetimeMs + maxClockSkewMs` to survive a device
* clock running that far ahead.
*/
maxClockSkewMs?: number;
timeoutMs: number;
maxCapabilityResponseBytes?: number;
fetcher?: typeof fetch;
@@ -143,6 +151,10 @@ export function createPresignedCapabilityHttpProvider(
options.minimumRemainingLifetimeMs,
"Presigned capability minimum remaining lifetime",
);
const maxClockSkewMs = options.maxClockSkewMs ?? 60_000;
if (!Number.isSafeInteger(maxClockSkewMs) || maxClockSkewMs < 0) {
throw new TypeError("Presigned capability clock skew is invalid.");
}
if (minimumRemainingLifetimeMs > maxCapabilityTtlMs) {
throw new TypeError(
"Presigned capability minimum remaining lifetime exceeds its TTL.",
@@ -267,7 +279,7 @@ export function createPresignedCapabilityHttpProvider(
expected,
hardMaxTransferBytes,
hardMaxUploadResponseBytes,
maxCapabilityTtlMs,
maxCapabilityTtlMs: maxCapabilityTtlMs + maxClockSkewMs,
minimumRemainingLifetimeMs,
nowEpochMs: now(),
allowedDataOrigins,
@@ -17,6 +17,11 @@ export type ResumableUploadRuntimePolicy = Readonly<{
maxRetryAfterMs: number;
capabilityRefreshSkewMs: number;
maxSessionLifetimeMs: number;
/**
* 01-06. How far the device clock may trail the server's. A session is
* refused only when it outlives `maxSessionLifetimeMs` by more than this.
*/
maxClockSkewMs: number;
providerAttemptTimeoutMs: number;
/**
* 01-03. The slowest uplink a part PUT must survive. Its attempt deadline is
@@ -48,6 +53,7 @@ const ABSOLUTE_LIMITS = Object.freeze({
maxRetryAfterMs: 60_000,
maxCapabilityRefreshSkewMs: 5 * 60_000,
maxSessionLifetimeMs: 7 * 24 * 60 * 60_000,
maxClockSkewMs: 5 * 60_000,
maxProviderAttemptTimeoutMs: 2 * 60_000,
});
@@ -67,6 +73,7 @@ const DEFAULT_POLICY: ResumableUploadRuntimePolicy = Object.freeze({
maxRetryAfterMs: 30_000,
capabilityRefreshSkewMs: 5_000,
maxSessionLifetimeMs: 24 * 60 * 60_000,
maxClockSkewMs: 60_000,
providerAttemptTimeoutMs: 30_000,
// 64 KiB/s (about 0.5 Mbit/s): a 5 MiB part gets 30 s + 80 s.
minTransferBytesPerSecond: 64 * 1024,
@@ -116,6 +123,8 @@ export function resolveResumableUploadRuntimePolicy(
!positiveSafeInteger(policy.maxSessionLifetimeMs) ||
policy.maxSessionLifetimeMs >
ABSOLUTE_LIMITS.maxSessionLifetimeMs ||
!nonNegativeSafeInteger(policy.maxClockSkewMs) ||
policy.maxClockSkewMs > ABSOLUTE_LIMITS.maxClockSkewMs ||
!positiveSafeInteger(policy.providerAttemptTimeoutMs) ||
policy.providerAttemptTimeoutMs >
ABSOLUTE_LIMITS.maxProviderAttemptTimeoutMs ||
@@ -232,7 +232,8 @@ export function validateSession<Capability>(
if (
requireActiveExpiry &&
value.expiresAtEpochMs - now.value >
dependencies.policy.maxSessionLifetimeMs
dependencies.policy.maxSessionLifetimeMs +
dependencies.policy.maxClockSkewMs
) {
return browserDataFailure("POLICY_REJECTED", "UPLOAD_SESSION");
}
+4
View File
@@ -160,6 +160,7 @@ export function createHarness(input: Readonly<{
scheduler?: PresignedTransferExecutorOptions["scheduler"];
minTransferBytesPerSecond?: number;
idleTimeoutMs?: number;
maxClockSkewMs?: number;
observer?: Readonly<{
record(observation: BrowserDataObservation): void;
}>;
@@ -195,6 +196,9 @@ export function createHarness(input: Readonly<{
now,
scheduler: input.scheduler,
observer: input.observer,
...(input.maxClockSkewMs === undefined
? {}
: { maxClockSkewMs: input.maxClockSkewMs }),
});
const executor = createPresignedTransferExecutor({
vault,
+28
View File
@@ -69,6 +69,34 @@ describe("presigned transfer capability issuance and admission", () => {
}
});
it.each([
[500, true],
[501, false],
] as const)(
"accepts a max-TTL capability from a server %i ms ahead: %s (01-06)",
async (skewMs, accepted) => {
const bytes = new Uint8Array([1, 2, 3]);
const payload = downloadCapabilityPayload(bytes, {
// The harness allows 60 s; the server clock runs `skewMs` ahead.
expiresAtEpochMs: NOW + skewMs + 60_000,
});
const fetcher = vi.fn(async () =>
jsonResponse(payload),
) as unknown as typeof fetch;
const { provider } = createHarness({ fetcher, maxClockSkewMs: 500 });
const issued = await provider.issueDownload({
resourceId: "resource-1",
signal: new AbortController().signal,
});
expect(issued.ok).toBe(accepted);
if (!accepted) {
expect(issued).toMatchObject({ error: { code: "POLICY_REJECTED" } });
}
},
);
it("answers a refused capability envelope with a re-issuable recovery", async () => {
// BT-PRE-04. A capability document the adapter will not accept is closed as
// `POLICY_REJECTED`, and the caller's only way forward is a new capability.
@@ -209,6 +209,7 @@ export function runtimePolicy(
maxRetryAfterMs: 100,
capabilityRefreshSkewMs: 5,
maxSessionLifetimeMs: 10_000,
maxClockSkewMs: 0,
providerAttemptTimeoutMs: 100,
...overrides,
};
@@ -865,3 +865,62 @@ describe("upload() failure recovery maps to one caller action (01-05)", () => {
if (!result.ok) expect(UPLOAD_ACTIONS.has(result.error.recovery)).toBe(true);
});
});
describe("device clock skew on server lifetimes (01-06)", () => {
/** A server whose clock runs `skewMs` ahead and gives full-length sessions. */
function skewedServer(skewMs: number, lifetimeMs: number) {
const harness = createControlHarness();
const expiresAtEpochMs = 1_000 + skewMs + lifetimeMs;
const create = harness.control.createSession.bind(harness.control);
const status = harness.control.getStatus.bind(harness.control);
harness.control.createSession = async (input) => {
const created = await create(input);
return created.ok
? browserDataSuccess({ ...created.value, expiresAtEpochMs })
: created;
};
harness.control.getStatus = async (input) => {
const read = await status(input);
return read.ok && read.value.state === "ACTIVE"
? browserDataSuccess({
...read.value,
session: { ...read.value.session, expiresAtEpochMs },
})
: read;
};
return harness;
}
it.each([
[500, true],
[501, false],
] as const)(
"accepts a max-length session from a server %i ms ahead: %s",
async (skewMs, accepted) => {
const harness = skewedServer(skewMs, 10_000);
const runtime = createResumableUploadRuntime({
controlPlane: harness.control,
partExecutor: executorFor(harness),
checkpoints: new MemoryCheckpointStore(),
mutationLock: noContentionLock,
crypto,
policy: runtimePolicy({
maxRetries: 0,
maxSessionLifetimeMs: 10_000,
maxClockSkewMs: 500,
}),
now: () => 1_000,
sleep: async () => {},
});
const result = await runtime.upload(request(`upload_key_skew_${skewMs}`));
expect(result.ok).toBe(accepted);
if (!accepted) {
expect(result).toMatchObject({
error: { code: "POLICY_REJECTED", operation: "UPLOAD_SESSION" },
});
}
},
);
});