@uploadfilm/sdk 0.0.0-stage → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +4 -0
- package/README.md +529 -2
- package/dist/ai/embed.d.ts +58 -0
- package/dist/ai/fake.d.ts +41 -0
- package/dist/ai/http.d.ts +17 -0
- package/dist/ai/index.d.ts +27 -0
- package/dist/ai/languages.d.ts +2 -0
- package/dist/ai/ollama.d.ts +23 -0
- package/dist/ai/openaiCompatible.d.ts +54 -0
- package/dist/ai/passages.d.ts +28 -0
- package/dist/ai/transcribe.d.ts +84 -0
- package/dist/ai/types.d.ts +141 -0
- package/dist/ai/usage.d.ts +66 -0
- package/dist/ai/whisperJson.d.ts +15 -0
- package/dist/ai/workersAi.d.ts +56 -0
- package/dist/ai.js +1 -0
- package/dist/ai.mjs +1 -0
- package/dist/cards/files.d.ts +91 -0
- package/dist/cards/index.d.ts +15 -0
- package/dist/cards/layouts.d.ts +121 -0
- package/dist/cards/probe.d.ts +69 -0
- package/dist/cards/proxies.d.ts +70 -0
- package/dist/cards/select.d.ts +68 -0
- package/dist/cards/volumes.d.ts +170 -0
- package/dist/cards/xml.d.ts +80 -0
- package/dist/cards.js +1 -0
- package/dist/cards.mjs +1 -0
- package/dist/copy/checksums.d.ts +66 -0
- package/dist/copy/engine.d.ts +24 -0
- package/dist/copy/errors.d.ts +109 -0
- package/dist/copy/index.d.ts +15 -0
- package/dist/copy/steps.d.ts +28 -0
- package/dist/copy/sweep.d.ts +24 -0
- package/dist/copy/types.d.ts +363 -0
- package/dist/embed/player.js +2 -0
- package/dist/host/adapters.d.ts +107 -0
- package/dist/host/detect.d.ts +68 -0
- package/dist/host/encoders.d.ts +34 -0
- package/dist/host/environment.d.ts +53 -0
- package/dist/host/index.d.ts +20 -0
- package/dist/host/linux.d.ts +94 -0
- package/dist/host/mac.d.ts +47 -0
- package/dist/host/network.d.ts +54 -0
- package/dist/host/node.d.ts +13 -0
- package/dist/host/policy.d.ts +101 -0
- package/dist/host/tuner.d.ts +48 -0
- package/dist/host/types.d.ts +118 -0
- package/dist/host-node.js +1 -0
- package/dist/host-node.mjs +1 -0
- package/dist/host.js +1 -0
- package/dist/host.mjs +1 -0
- package/dist/images/index.d.ts +11 -0
- package/dist/images/settings.d.ts +43 -0
- package/dist/images/types.d.ts +83 -0
- package/dist/images/url.d.ts +65 -0
- package/dist/index.d.ts +16 -0
- package/dist/index.js +1 -0
- package/dist/index.mjs +1 -0
- package/dist/player/adapters/hlsjs.d.ts +28 -0
- package/dist/player/bandwidthMemory.d.ts +28 -0
- package/dist/player/captions/index.d.ts +55 -0
- package/dist/player/embed/code.d.ts +195 -0
- package/dist/player/embed/constants.d.ts +4 -0
- package/dist/player/embed/controller.d.ts +62 -0
- package/dist/player/embed/element.d.ts +32 -0
- package/dist/player/embed/frame.d.ts +65 -0
- package/dist/player/embed/global.d.ts +14 -0
- package/dist/player/embed/index.d.ts +15 -0
- package/dist/player/embed/loader.d.ts +1 -0
- package/dist/player/embed/oembed.d.ts +74 -0
- package/dist/player/embed/protocol.d.ts +64 -0
- package/dist/player/engine.d.ts +215 -0
- package/dist/player/index.d.ts +18 -0
- package/dist/player/start.d.ts +62 -0
- package/dist/player/store.d.ts +10 -0
- package/dist/player/storyboard/index.d.ts +161 -0
- package/dist/player/stream.d.ts +206 -0
- package/dist/player/tracks.d.ts +41 -0
- package/dist/player.js +1 -0
- package/dist/player.mjs +1 -0
- package/dist/proxies/args.d.ts +19 -0
- package/dist/proxies/budget.d.ts +57 -0
- package/dist/proxies/camera.d.ts +104 -0
- package/dist/proxies/formats.d.ts +36 -0
- package/dist/proxies/index.d.ts +18 -0
- package/dist/proxies/jobs.d.ts +98 -0
- package/dist/proxies/node.d.ts +32 -0
- package/dist/proxies/plan.d.ts +89 -0
- package/dist/proxies/probe.d.ts +39 -0
- package/dist/proxies/render.d.ts +104 -0
- package/dist/proxies/safety.d.ts +45 -0
- package/dist/proxies/types.d.ts +83 -0
- package/dist/proxies/upload.d.ts +14 -0
- package/dist/react/BigPlay.d.ts +26 -0
- package/dist/react/Player.d.ts +58 -0
- package/dist/react/embed/index.d.ts +45 -0
- package/dist/react/examples/CustomControls.d.ts +8 -0
- package/dist/react/images/Image.d.ts +16 -0
- package/dist/react/images/index.d.ts +4 -0
- package/dist/react/images/useImage.d.ts +47 -0
- package/dist/react/index.d.ts +17 -0
- package/dist/react/storyboard/index.d.ts +58 -0
- package/dist/react/theme.d.ts +37 -0
- package/dist/react/useAdapterErrors.d.ts +8 -0
- package/dist/react/usePlaybackStart.d.ts +18 -0
- package/dist/react/usePlayer.d.ts +28 -0
- package/dist/react/useReducedMotion.d.ts +2 -0
- package/dist/react/useTimedTrack.d.ts +22 -0
- package/dist/react.js +1 -0
- package/dist/react.mjs +1 -0
- package/dist/server/auth/apiKeys.d.ts +30 -0
- package/dist/server/auth/cache.d.ts +21 -0
- package/dist/server/auth/deviceTokens.d.ts +38 -0
- package/dist/server/auth/envelope.d.ts +15 -0
- package/dist/server/auth/grants.d.ts +76 -0
- package/dist/server/auth/index.d.ts +19 -0
- package/dist/server/auth/jwt.d.ts +65 -0
- package/dist/server/auth/keyring.d.ts +31 -0
- package/dist/server/auth/kv.d.ts +12 -0
- package/dist/server/auth/repository.d.ts +45 -0
- package/dist/server/auth/revocations.d.ts +21 -0
- package/dist/server/auth/scope.d.ts +4 -0
- package/dist/server/auth/serviceAuth.d.ts +24 -0
- package/dist/server/auth/signedUrls.d.ts +28 -0
- package/dist/server/embed/index.d.ts +36 -0
- package/dist/server/embed/lifecycle.d.ts +53 -0
- package/dist/server/embed/playerScript.d.ts +4 -0
- package/dist/server/images/index.d.ts +15 -0
- package/dist/server/images/job.d.ts +80 -0
- package/dist/server/images/layout.d.ts +24 -0
- package/dist/server/images/params.d.ts +90 -0
- package/dist/server/images/route.d.ts +101 -0
- package/dist/server/images/sign.d.ts +55 -0
- package/dist/server/index.d.ts +42 -0
- package/dist/server/media/client.d.ts +99 -0
- package/dist/server/media/frameCheck.d.ts +62 -0
- package/dist/server/media/index.d.ts +10 -0
- package/dist/server/media/protocol.d.ts +556 -0
- package/dist/server/media/storyboard.d.ts +144 -0
- package/dist/server/media/transcript.d.ts +143 -0
- package/dist/server/pipeline/index.d.ts +12 -0
- package/dist/server/pipeline/match.d.ts +10 -0
- package/dist/server/pipeline/pipeline.d.ts +182 -0
- package/dist/server/pipeline/queues.d.ts +108 -0
- package/dist/server/pipeline/sources.d.ts +54 -0
- package/dist/server/r2/client.d.ts +164 -0
- package/dist/server/r2/crc32.d.ts +24 -0
- package/dist/server/r2/encoding.d.ts +35 -0
- package/dist/server/r2/errors.d.ts +9 -0
- package/dist/server/r2/integrity.d.ts +25 -0
- package/dist/server/r2/parts.d.ts +46 -0
- package/dist/server/r2/sign.d.ts +47 -0
- package/dist/server/redis/index.d.ts +39 -0
- package/dist/server/state/memory.d.ts +18 -0
- package/dist/server/state/r2.d.ts +73 -0
- package/dist/server/state/types.d.ts +57 -0
- package/dist/server/storage/chunked.d.ts +25 -0
- package/dist/server/storage/index.d.ts +12 -0
- package/dist/server/storage/r2.d.ts +96 -0
- package/dist/server/storage/s3.d.ts +144 -0
- package/dist/server/testing/fake-r2.d.ts +410 -0
- package/dist/server/testing/index.d.ts +10 -0
- package/dist/server/testing/kv-contract.d.ts +14 -0
- package/dist/server/transfer/handler.d.ts +217 -0
- package/dist/server/transfer/keys.d.ts +45 -0
- package/dist/server/transfer/protocol.d.ts +190 -0
- package/dist/server/zip/client.d.ts +32 -0
- package/dist/server/zip/generations.d.ts +83 -0
- package/dist/server/zip/index.d.ts +12 -0
- package/dist/server/zip/planner.d.ts +94 -0
- package/dist/server/zip/sign.d.ts +22 -0
- package/dist/server-media.js +1 -0
- package/dist/server-media.mjs +1 -0
- package/dist/server-redis.js +1 -0
- package/dist/server-redis.mjs +1 -0
- package/dist/server-testing.js +1 -0
- package/dist/server-testing.mjs +1 -0
- package/dist/server.js +1 -0
- package/dist/server.mjs +1 -0
- package/dist/storage/browserFile.d.ts +19 -0
- package/dist/storage/index.d.ts +12 -0
- package/dist/storage/local.d.ts +9 -0
- package/dist/storage/presigned.d.ts +22 -0
- package/dist/sync/ffmpeg.d.ts +44 -0
- package/dist/sync/index.d.ts +17 -0
- package/dist/sync/match.d.ts +28 -0
- package/dist/sync/probe.d.ts +30 -0
- package/dist/sync/timecode.d.ts +50 -0
- package/dist/sync/transcript.d.ts +35 -0
- package/dist/sync/types.d.ts +172 -0
- package/dist/sync/waveform.d.ts +89 -0
- package/dist/sync.js +1 -0
- package/dist/sync.mjs +1 -0
- package/dist/transfer/claims.d.ts +41 -0
- package/dist/transfer/client.d.ts +267 -0
- package/dist/transfer/download.d.ts +192 -0
- package/dist/transfer/engine.d.ts +402 -0
- package/dist/transfer/errors.d.ts +50 -0
- package/dist/transfer/growing/bytes.d.ts +17 -0
- package/dist/transfer/growing/index.d.ts +12 -0
- package/dist/transfer/growing/parts.d.ts +157 -0
- package/dist/transfer/growing/retry.d.ts +38 -0
- package/dist/transfer/growing/store.d.ts +66 -0
- package/dist/transfer/growing/upload.d.ts +126 -0
- package/dist/transfer/index.d.ts +40 -0
- package/dist/transfer/integrity.d.ts +93 -0
- package/dist/transfer/limits.d.ts +34 -0
- package/dist/transfer/node.d.ts +63 -0
- package/dist/transfer/pool.d.ts +83 -0
- package/dist/transfer/protocol.d.ts +172 -0
- package/dist/transfer/signer.d.ts +29 -0
- package/dist/transfer/storage.d.ts +135 -0
- package/dist/transfer/timing.d.ts +132 -0
- package/dist/transfer/transports/electronNet.d.ts +62 -0
- package/dist/transfer/transports/fetch.d.ts +15 -0
- package/dist/transfer/transports/retryAfter.d.ts +12 -0
- package/dist/transfer/transports/undici.d.ts +72 -0
- package/dist/transfer/tuner.d.ts +56 -0
- package/dist/workers/cli.mjs +115 -0
- package/dist/workers/media/config.mjs +53 -0
- package/dist/workers/media/container/Dockerfile +19 -0
- package/dist/workers/media/container/FFMPEG.md +129 -0
- package/dist/workers/media/container/runner.mjs +2690 -0
- package/dist/workers/media/index.mjs +1011 -0
- package/dist/workers/media/init/config.ts +52 -0
- package/dist/workers/media/init/worker.ts +8 -0
- package/dist/workers/media/init/wrangler.toml +44 -0
- package/dist/workers/media/runner.mjs +2656 -0
- package/dist/workers/media/types/build/entry/config.d.mts +6 -0
- package/dist/workers/media/types/build/entry/index.d.mts +43 -0
- package/dist/workers/media/types/build/entry/program.d.mts +13 -0
- package/dist/workers/media/types/build/entry/runner.d.mts +12 -0
- package/dist/workers/media/types/build/entry/settings.d.mts +40 -0
- package/dist/workers/media/types/src/config.d.mts +135 -0
- package/dist/workers/media/types/src/jobs.d.mts +73 -0
- package/dist/workers/media/types/src/runner/container.d.mts +32 -0
- package/dist/workers/media/types/src/runner/ffmpeg.d.mts +227 -0
- package/dist/workers/media/types/src/runner/job.d.mts +107 -0
- package/dist/workers/media/types/src/runner/node.d.mts +71 -0
- package/dist/workers/media/types/src/runner/plugins.d.mts +45 -0
- package/dist/workers/media/types/src/serve.d.mts +107 -0
- package/dist/workers/media/types/src/steps/audio.d.mts +33 -0
- package/dist/workers/media/types/src/steps/edit.d.mts +62 -0
- package/dist/workers/media/types/src/steps/frameCheck.d.mts +44 -0
- package/dist/workers/media/types/src/steps/gate.d.mts +18 -0
- package/dist/workers/media/types/src/steps/paths.d.mts +1 -0
- package/dist/workers/media/types/src/steps/prep.d.mts +60 -0
- package/dist/workers/media/types/src/steps/render.d.mts +40 -0
- package/dist/workers/media/types/src/steps/runner.d.mts +30 -0
- package/dist/workers/media/types/src/steps/transcribe.d.mts +89 -0
- package/dist/workers/media/types/src/storyboard/index.d.mts +61 -0
- package/dist/workers/media/types/src/transcoder.d.mts +30 -0
- package/dist/workers/media/types/src/worker.d.mts +30 -0
- package/dist/workers/zip/index.mjs +589 -0
- package/dist/workers/zip/init/config.ts +22 -0
- package/dist/workers/zip/init/worker.ts +5 -0
- package/dist/workers/zip/init/wrangler.toml +25 -0
- package/dist/workers/zip/types/build/entry/index.d.mts +5 -0
- package/dist/workers/zip/types/src/config.d.mts +35 -0
- package/dist/workers/zip/types/src/serve.d.mts +86 -0
- package/dist/workers/zip/types/src/worker.d.mts +12 -0
- package/dist/zip/index.d.ts +13 -0
- package/dist/zip/layout.d.ts +129 -0
- package/dist/zip/names.d.ts +34 -0
- package/dist/zip/plan.d.ts +115 -0
- package/dist/zip/sw.d.ts +7 -0
- package/package.json +313 -4
|
@@ -0,0 +1,65 @@
|
|
|
1
|
+
import { type Keyring } from "./keyring";
|
|
2
|
+
import type { RevocationList } from "./revocations";
|
|
3
|
+
import type { TokenCache } from "./cache";
|
|
4
|
+
export interface TokenClaims {
|
|
5
|
+
sub: string;
|
|
6
|
+
aud: string;
|
|
7
|
+
scope: string[];
|
|
8
|
+
iat: number;
|
|
9
|
+
exp: number;
|
|
10
|
+
jti: string;
|
|
11
|
+
nbf?: number;
|
|
12
|
+
iss?: string;
|
|
13
|
+
}
|
|
14
|
+
export interface IssueOptions {
|
|
15
|
+
sub: string;
|
|
16
|
+
aud: string;
|
|
17
|
+
scope?: readonly string[];
|
|
18
|
+
/** Lifetime: seconds, or "15m" / "6h" / "1d". */
|
|
19
|
+
ttl: number | string;
|
|
20
|
+
iss?: string;
|
|
21
|
+
/** Not valid before (unix seconds). */
|
|
22
|
+
nbf?: number;
|
|
23
|
+
/** Token id; random when omitted. Must be [A-Za-z0-9._~-]{1,128}. */
|
|
24
|
+
jti?: string;
|
|
25
|
+
/** Milliseconds clock. */
|
|
26
|
+
now?: number;
|
|
27
|
+
/** A product hook: record the issue (onTokenIssued). Awaited; a failing hook fails the issue. */
|
|
28
|
+
onIssued?: (e: {
|
|
29
|
+
kid: string;
|
|
30
|
+
claims: TokenClaims;
|
|
31
|
+
}) => void | Promise<void>;
|
|
32
|
+
}
|
|
33
|
+
export type VerifyFailure = "malformed" | "header" | "kid" | "signature" | "claims" | "expired" | "not-yet-valid" | "issued-in-future" | "ttl" | "audience" | "issuer" | "scope" | "revoked";
|
|
34
|
+
export type VerifyResult = {
|
|
35
|
+
ok: true;
|
|
36
|
+
kid: string;
|
|
37
|
+
claims: TokenClaims;
|
|
38
|
+
} | {
|
|
39
|
+
ok: false;
|
|
40
|
+
reason: VerifyFailure;
|
|
41
|
+
};
|
|
42
|
+
export interface VerifyOptions {
|
|
43
|
+
/** Required audience: exact match. */
|
|
44
|
+
aud: string;
|
|
45
|
+
/** Every wanted scope must be covered by the token's scopes. */
|
|
46
|
+
scope?: string | string[];
|
|
47
|
+
iss?: string;
|
|
48
|
+
/** Milliseconds clock. */
|
|
49
|
+
now?: number;
|
|
50
|
+
/** Tolerated clock skew for exp/nbf/iat, seconds. Default 0. */
|
|
51
|
+
skewSeconds?: number;
|
|
52
|
+
/** Refuse tokens whose exp − iat exceeds this, seconds (a product's maximum lifetime). */
|
|
53
|
+
maxTtlSeconds?: number;
|
|
54
|
+
revocations?: RevocationList;
|
|
55
|
+
/**
|
|
56
|
+
* @deprecated No longer consulted: the MAC is always checked (a cache hit that skipped it let a forged token verify
|
|
57
|
+
* through a store an attacker could observe and write: O-2 in docs/platform/SECURITY.md). Verdicts are still written
|
|
58
|
+
* (the option's existing contract) but never read back here; drop the option. Revocation goes through `revocations`.
|
|
59
|
+
*/
|
|
60
|
+
cache?: TokenCache<TokenClaims>;
|
|
61
|
+
}
|
|
62
|
+
export declare const MAX_TOKEN_LENGTH = 8192;
|
|
63
|
+
export declare function issueToken(keys: Keyring, o: IssueOptions): Promise<string>;
|
|
64
|
+
/** Verifies a token. Never throws for a bad token; throws only for bad options (a programming error). */
|
|
65
|
+
export declare function verifyToken(keys: Keyring, token: unknown, o: VerifyOptions): Promise<VerifyResult>;
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
export interface KeyringKey {
|
|
2
|
+
/** Public key id carried by tokens: [A-Za-z0-9_-]{1,64} (no dots: several wire formats use them as separators). */
|
|
3
|
+
kid: string;
|
|
4
|
+
/** At least 32 bytes of secret (a string of ≥ 32 characters, or bytes). */
|
|
5
|
+
secret: string | Uint8Array;
|
|
6
|
+
}
|
|
7
|
+
export interface Keyring {
|
|
8
|
+
readonly current: KeyringKey;
|
|
9
|
+
readonly previous: readonly KeyringKey[];
|
|
10
|
+
/** Every kid accepted when verifying (current first). */
|
|
11
|
+
readonly kids: readonly string[];
|
|
12
|
+
/** The key for a kid, or undefined when the kid isn't on the ring (an allowlist lookup, not a pattern). */
|
|
13
|
+
byKid(kid: string): KeyringKey | undefined;
|
|
14
|
+
}
|
|
15
|
+
export declare const KID: RegExp;
|
|
16
|
+
export declare function keyring(opts: {
|
|
17
|
+
current: KeyringKey;
|
|
18
|
+
previous?: readonly KeyringKey[];
|
|
19
|
+
}): Keyring;
|
|
20
|
+
/** Token kinds; each gets its own HKDF subkey. */
|
|
21
|
+
export type KeyPurpose = "jwt-hs256" | "signed-url" | "service-hmac" | "envelope-kek";
|
|
22
|
+
/** The 32-byte subkey for one purpose (HKDF-SHA256, salt "uploadfilm-sdk/auth/v1", info = purpose). Cached per key. */
|
|
23
|
+
export declare function subkey(k: KeyringKey, purpose: KeyPurpose): Promise<Uint8Array<ArrayBuffer>>;
|
|
24
|
+
/** The purpose's subkey imported for HMAC-SHA256 sign/verify. Cached per key. */
|
|
25
|
+
export declare function hmacKey(k: KeyringKey, purpose: KeyPurpose): Promise<CryptoKey>;
|
|
26
|
+
export declare function macWith(k: KeyringKey, purpose: KeyPurpose, message: string): Promise<Uint8Array<ArrayBuffer>>;
|
|
27
|
+
/**
|
|
28
|
+
* A public fingerprint of one purpose's key material (HMAC of a fixed label under the subkey, 128 bits, hex): equal
|
|
29
|
+
* only for the same secret and purpose. Used to bind cached verdicts to the key that produced them.
|
|
30
|
+
*/
|
|
31
|
+
export declare function keyFingerprint(k: KeyringKey, purpose: KeyPurpose): Promise<string>;
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The state the auth kit keeps (revocations, the token cache, replay guards) lives in a product's KeyValueStore
|
|
3
|
+
* (docs/platform/RFC.md §3.3). The shape is structural, so any adapter with these methods fits: the SDK's in-memory
|
|
4
|
+
* and Redis adapters, or a product's own.
|
|
5
|
+
*/
|
|
6
|
+
export type { KeyValueStore } from "../state/types";
|
|
7
|
+
/** Ids that go into KV keys: no separators, no whitespace, bounded. */
|
|
8
|
+
export declare const KV_ID: RegExp;
|
|
9
|
+
/** Unix seconds from a millisecond clock. */
|
|
10
|
+
export declare const seconds: (ms: number) => number;
|
|
11
|
+
/** "90" / 90 → 90 s; "15m", "6h", "7d", "30s". Positive whole seconds only. */
|
|
12
|
+
export declare function parseTtl(ttl: number | string): number;
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* What a product implements to persist keys and tokens in its own database. The SDK never owns tables: it hashes,
|
|
3
|
+
* generates and checks; the product stores and looks up. UploadFilm keeps its SQL in web/lib/keys.ts.
|
|
4
|
+
*/
|
|
5
|
+
export interface ApiKeyRecord {
|
|
6
|
+
id: string;
|
|
7
|
+
/** Whoever the key acts for (UploadFilm: a device id). */
|
|
8
|
+
ownerId: string;
|
|
9
|
+
name: string;
|
|
10
|
+
/** Display prefix (generateApiKey().prefix). */
|
|
11
|
+
prefix: string;
|
|
12
|
+
last4?: string;
|
|
13
|
+
/** SHA-256 hex of the key. */
|
|
14
|
+
hash: string;
|
|
15
|
+
createdAt: string;
|
|
16
|
+
lastUsedAt?: string;
|
|
17
|
+
revokedAt?: string;
|
|
18
|
+
}
|
|
19
|
+
export interface ApiKeyRepository {
|
|
20
|
+
insert(record: ApiKeyRecord): Promise<void>;
|
|
21
|
+
/** The record with this hash that isn't revoked (touching its last-used time is up to the product), or null. */
|
|
22
|
+
findActiveByHash(hash: string): Promise<ApiKeyRecord | null>;
|
|
23
|
+
listActive(ownerId: string): Promise<ApiKeyRecord[]>;
|
|
24
|
+
/** False when there was nothing active to revoke. */
|
|
25
|
+
revoke(ownerId: string, id: string): Promise<boolean>;
|
|
26
|
+
}
|
|
27
|
+
/** A record of an issued short-lived token, for products that keep an audit trail (issueToken's onIssued hook). */
|
|
28
|
+
export interface IssuedTokenRecord {
|
|
29
|
+
jti: string;
|
|
30
|
+
kid: string;
|
|
31
|
+
sub: string;
|
|
32
|
+
aud: string;
|
|
33
|
+
scope: string[];
|
|
34
|
+
iat: number;
|
|
35
|
+
exp: number;
|
|
36
|
+
}
|
|
37
|
+
export interface TokenRepository {
|
|
38
|
+
recordIssued(t: IssuedTokenRecord): Promise<void>;
|
|
39
|
+
/** Marks a token revoked in the product's records (the KV revocation list is what verification reads). */
|
|
40
|
+
recordRevoked(jti: string, at: string): Promise<void>;
|
|
41
|
+
}
|
|
42
|
+
/** An in-memory ApiKeyRepository, for tests and local development. */
|
|
43
|
+
export declare function memoryApiKeyRepository(now?: () => number): ApiKeyRepository & {
|
|
44
|
+
all(): ApiKeyRecord[];
|
|
45
|
+
};
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* A revocation list on a KeyValueStore: a revoked token id (jti) stays listed until the token would have expired
|
|
3
|
+
* anyway, then KV drops it. Checks fail closed: a store that errors reads as "revoked".
|
|
4
|
+
*/
|
|
5
|
+
import { type KeyValueStore } from "./kv";
|
|
6
|
+
export interface RevocationList {
|
|
7
|
+
/**
|
|
8
|
+
* The most clock skew a verifier using this list may allow, and the most two hosts' clocks may differ. Entries are
|
|
9
|
+
* kept until exp + 2 × skewSeconds.
|
|
10
|
+
*/
|
|
11
|
+
readonly skewSeconds: number;
|
|
12
|
+
/** Lists `jti` until `untilUnixSeconds` (the token's exp), plus 2 × skewSeconds. A time already past still lists it for 1 s. */
|
|
13
|
+
revoke(jti: string, untilUnixSeconds: number): Promise<void>;
|
|
14
|
+
/** True when listed, and when the store can't answer (fail closed). */
|
|
15
|
+
isRevoked(jti: string): Promise<boolean>;
|
|
16
|
+
}
|
|
17
|
+
export declare function revocationList(kv: KeyValueStore, opts?: {
|
|
18
|
+
namespace?: string;
|
|
19
|
+
now?: () => number;
|
|
20
|
+
skewSeconds?: number;
|
|
21
|
+
}): RevocationList;
|
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
export declare function isWantedScope(s: unknown): s is string;
|
|
2
|
+
export declare function isGrantedScope(s: unknown): s is string;
|
|
3
|
+
/** Does any granted scope cover `wanted`? Malformed entries never match. */
|
|
4
|
+
export declare function scopeAllows(granted: readonly unknown[], wanted: string): boolean;
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
import { type Keyring } from "./keyring";
|
|
2
|
+
import { type KeyValueStore } from "./kv";
|
|
3
|
+
export interface ServiceVerifyOptions {
|
|
4
|
+
/** How old a signature may be, seconds (required: the product picks its window). */
|
|
5
|
+
maxAgeSeconds: number;
|
|
6
|
+
/** Tolerated clock skew into the future, seconds. Default 0. */
|
|
7
|
+
skewSeconds?: number;
|
|
8
|
+
/** When given, a signature is accepted once (kept for maxAge + skew). */
|
|
9
|
+
replay?: KeyValueStore;
|
|
10
|
+
replayNamespace?: string;
|
|
11
|
+
now?: number;
|
|
12
|
+
}
|
|
13
|
+
export type ServiceVerifyResult = {
|
|
14
|
+
ok: true;
|
|
15
|
+
kid: string;
|
|
16
|
+
ts: number;
|
|
17
|
+
} | {
|
|
18
|
+
ok: false;
|
|
19
|
+
reason: "malformed" | "kid" | "signature" | "stale" | "future" | "replayed" | "replay-unavailable";
|
|
20
|
+
};
|
|
21
|
+
export declare function signServiceRequest(keys: Keyring, domain: string, body: string, o?: {
|
|
22
|
+
now?: number;
|
|
23
|
+
}): Promise<string>;
|
|
24
|
+
export declare function verifyServiceRequest(keys: Keyring, domain: string, body: string, header: unknown, o: ServiceVerifyOptions): Promise<ServiceVerifyResult>;
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
import { type Keyring } from "./keyring";
|
|
2
|
+
export interface SignUrlOptions {
|
|
3
|
+
/** Expiry: unix seconds (`expiresAt`) or a lifetime from now (`ttl`). One is required. */
|
|
4
|
+
expiresAt?: number;
|
|
5
|
+
ttl?: number | string;
|
|
6
|
+
/** Default "GET". */
|
|
7
|
+
method?: string;
|
|
8
|
+
/** Request values the URL is only good for, by lowercase name (e.g. { range: "bytes=0-1023" }). */
|
|
9
|
+
bind?: Record<string, string>;
|
|
10
|
+
now?: number;
|
|
11
|
+
}
|
|
12
|
+
export interface VerifyUrlOptions {
|
|
13
|
+
method?: string;
|
|
14
|
+
/** The request's values for the names the URL binds; a bound name missing here fails. */
|
|
15
|
+
bind?: Record<string, string | null | undefined>;
|
|
16
|
+
now?: number;
|
|
17
|
+
skewSeconds?: number;
|
|
18
|
+
}
|
|
19
|
+
export type VerifyUrlResult = {
|
|
20
|
+
ok: true;
|
|
21
|
+
exp: number;
|
|
22
|
+
kid: string;
|
|
23
|
+
} | {
|
|
24
|
+
ok: false;
|
|
25
|
+
reason: "malformed" | "kid" | "expired" | "signature" | "bind";
|
|
26
|
+
};
|
|
27
|
+
export declare function signUrl(keys: Keyring, url: string | URL, o: SignUrlOptions): Promise<string>;
|
|
28
|
+
export declare function verifySignedUrl(keys: Keyring, url: string | URL, o?: VerifyUrlOptions): Promise<VerifyUrlResult>;
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* servePlayerScript(): the embed control API script (`UploadFilm.Player`, built from src/player/embed) as a route
|
|
3
|
+
* handler, on Node or Cloudflare Workers (Web Request/Response only). Mount it at PLAYER_SCRIPT_PATH:
|
|
4
|
+
*
|
|
5
|
+
* // Next.js: app/embeds/v1/player.js/route.ts
|
|
6
|
+
* const serve = servePlayerScript();
|
|
7
|
+
* export const GET = serve, HEAD = serve;
|
|
8
|
+
*
|
|
9
|
+
* Caching, as UploadFilm serves its /player.js: an hour in the browser (no request on repeat views), then checked again
|
|
10
|
+
* with the ETag (a cheap 304), so a fix reaches a page at most an hour later. No stale-while-revalidate: Vercel drops it
|
|
11
|
+
* when Cache-Control is the only cache header, and where it's honoured a visitor back days later would run the old
|
|
12
|
+
* script once.
|
|
13
|
+
*/
|
|
14
|
+
import { PLAYER_SCRIPT, PLAYER_SCRIPT_SHA256 } from "./playerScript";
|
|
15
|
+
export { PLAYER_SCRIPT, PLAYER_SCRIPT_SHA256 };
|
|
16
|
+
/** Where products mount the script (the major version is the protocol's). */
|
|
17
|
+
export declare const PLAYER_SCRIPT_PATH = "/embeds/v1/player.js";
|
|
18
|
+
/** Cache-Control of the script: an hour, then revalidated. */
|
|
19
|
+
export declare const PLAYER_SCRIPT_CACHE_CONTROL = "public, max-age=3600";
|
|
20
|
+
export declare const PLAYER_SCRIPT_CONTENT_TYPE = "application/javascript; charset=utf-8";
|
|
21
|
+
export interface ServePlayerScriptOptions {
|
|
22
|
+
/** Cache-Control header. Default PLAYER_SCRIPT_CACHE_CONTROL. */
|
|
23
|
+
cacheControl?: string;
|
|
24
|
+
/** Serve another build of the script (tests, a patched copy). Its ETag is computed once, with WebCrypto. */
|
|
25
|
+
script?: string;
|
|
26
|
+
}
|
|
27
|
+
/** The strong ETag of the script: its sha256, quoted. */
|
|
28
|
+
export declare const playerScriptEtag: (sha256Hex: string) => string;
|
|
29
|
+
/**
|
|
30
|
+
* Whether an If-None-Match header matches `etag` (RFC 9110 §13.1.2: weak comparison, a list, or "*"). Malformed
|
|
31
|
+
* entries never match.
|
|
32
|
+
*/
|
|
33
|
+
export declare function ifNoneMatchHits(header: string | null, etag: string): boolean;
|
|
34
|
+
/** A handler for GET and HEAD of the embed script: 200 with the script, 304 when the browser's copy is current. */
|
|
35
|
+
export declare function servePlayerScript(options?: ServePlayerScriptOptions): (req: Request) => Promise<Response>;
|
|
36
|
+
export { EMBED_EDGE_REDIRECT_S, EMBED_ORPHAN_AFTER_MS, EMBED_RETIRE_SLACK_S, EMBED_SIGNED_URL_TTL_S, copiesToDelete, embedRedirect, retireGraceMs, type EmbedCopy, type RetireTiming, } from "./lifecycle";
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* An embed's own copy of a video: how it's handed out and when it may be deleted (REALITY-CHECK.md RC-S6; UploadFilm
|
|
3
|
+
* 5996513 and 0a600b3).
|
|
4
|
+
*
|
|
5
|
+
* A player gets the copy through a redirect to a signed storage URL. The redirect is cached at the edge (a CDN) for a
|
|
6
|
+
* minute, never in browsers, so one signature serves a burst of viewers; a fresh query (`r=<now>`, the player's
|
|
7
|
+
* refreshSource) skips a cached one. The signed URL itself lives for hours (a viewer mid-play keeps using it, ranges
|
|
8
|
+
* included). So a copy that's replaced or turned off must outlive every URL already out: it is RETIRED (no new
|
|
9
|
+
* redirect names it) and deleted only after the retirement grace, the signed URL's life plus the edge's plus some slack.
|
|
10
|
+
* Deleting it at once 404s every viewer mid-play and every edge-cached redirect.
|
|
11
|
+
*
|
|
12
|
+
* The SDK does the mechanics; where the records live (a table, a KeyValueStore) is the product's. Web Request/Response
|
|
13
|
+
* only (Node, Workers, Next.js).
|
|
14
|
+
*/
|
|
15
|
+
/** The signed URL's life a redirect hands out (UploadFilm: 6 h). */
|
|
16
|
+
export declare const EMBED_SIGNED_URL_TTL_S: number;
|
|
17
|
+
/** How long the edge keeps a redirect (UploadFilm: 60 s; turning an embed off reaches new requests in about 90 s). */
|
|
18
|
+
export declare const EMBED_EDGE_REDIRECT_S = 60;
|
|
19
|
+
/** Extra time on top of both before a retired copy goes (clock skew, a slow sweep). With the defaults: 7 h in all. */
|
|
20
|
+
export declare const EMBED_RETIRE_SLACK_S: number;
|
|
21
|
+
export interface RetireTiming {
|
|
22
|
+
/** The signed URLs' life (seconds). Default EMBED_SIGNED_URL_TTL_S. */
|
|
23
|
+
signedUrlTtlS?: number;
|
|
24
|
+
/** The edge's cache of a redirect (seconds). Default EMBED_EDGE_REDIRECT_S. */
|
|
25
|
+
edgeMaxAgeS?: number;
|
|
26
|
+
/** Extra (seconds, ≥ 0). Default EMBED_RETIRE_SLACK_S. */
|
|
27
|
+
slackS?: number;
|
|
28
|
+
}
|
|
29
|
+
/** How long after it's retired a copy may be deleted (ms): never before every URL and cached redirect naming it is dead. */
|
|
30
|
+
export declare function retireGraceMs(o?: RetireTiming): number;
|
|
31
|
+
/**
|
|
32
|
+
* The 302 to a copy's signed URL: cached `edgeMaxAgeS` at the edge only (`s-maxage`; browsers revalidate every time,
|
|
33
|
+
* so turning an embed off reaches a returning viewer at once), never indexed.
|
|
34
|
+
*/
|
|
35
|
+
export declare function embedRedirect(signedUrl: string, o?: {
|
|
36
|
+
edgeMaxAgeS?: number;
|
|
37
|
+
}): Response;
|
|
38
|
+
/** One copy, as the product records it. Times in ms since the epoch. */
|
|
39
|
+
export interface EmbedCopy {
|
|
40
|
+
key: string;
|
|
41
|
+
createdAt: number;
|
|
42
|
+
/** Set when a newer copy replaced it, or its embed was turned off: no new redirect names it. */
|
|
43
|
+
retiredAt?: number | null;
|
|
44
|
+
/** Is it what the embed hands out now (the product's current pointer)? */
|
|
45
|
+
current: boolean;
|
|
46
|
+
}
|
|
47
|
+
/** A copy never published (a crash between the copy and the swap) goes after this long, if nothing points at it. */
|
|
48
|
+
export declare const EMBED_ORPHAN_AFTER_MS: number;
|
|
49
|
+
/**
|
|
50
|
+
* Which copies may be deleted now: retired at least the retirement grace ago, or never published (not current, not
|
|
51
|
+
* retired, older than EMBED_ORPHAN_AFTER_MS). A current copy never is, whatever its other fields say.
|
|
52
|
+
*/
|
|
53
|
+
export declare function copiesToDelete<C extends EmbedCopy>(copies: Iterable<C>, now: number, o?: RetireTiming): C[];
|
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
/** The embed control API script (an ES5 IIFE defining `UploadFilm.Player`). */
|
|
2
|
+
export declare const PLAYER_SCRIPT: string;
|
|
3
|
+
/** sha256 (hex) of PLAYER_SCRIPT's UTF-8 bytes: its ETag. */
|
|
4
|
+
export declare const PLAYER_SCRIPT_SHA256 = "096f4c55453f6178cc440328d3355a42e7b8cf14a4b1df4b93cdebe07dc48986";
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Server images (Node or Cloudflare Workers, no dependencies beyond the auth kit): signed on-the-fly URLs and the
|
|
3
|
+
* route that serves them, the key layout, and the variants-at-upload job + runner client. The codecs live in the
|
|
4
|
+
* deploy template, sdks/image-worker (sharp in Node/containers; jSquash wasm or the Images binding in Workers).
|
|
5
|
+
*/
|
|
6
|
+
export { formatParams, negotiateFormat, outputBox, parseParams, policyProblem, resolvePolicy } from "./params";
|
|
7
|
+
export type { ConcreteFormat, Fit, PolicyProblem, ResolvedPolicy, TransformFormat, TransformParams, TransformPolicy, TransformPreset, } from "./params";
|
|
8
|
+
export { imageSigner, isSafeImageKey } from "./sign";
|
|
9
|
+
export type { ImagePresetArg, ImageSigner, ImageSignerOptions, ImageUrlVerdict } from "./sign";
|
|
10
|
+
export { imageLayout, imageVersion, sourceRevision, variantSetId } from "./layout";
|
|
11
|
+
export type { ImageLayout } from "./layout";
|
|
12
|
+
export { createImageRoute, masterMetadata, parseMasterMetadata } from "./route";
|
|
13
|
+
export type { EdgeCache, ImageBucket, ImageRouteEvent, ImageRouteOptions, ImageTransformer, MasterInfo, TransformJob, } from "./route";
|
|
14
|
+
export { imageRunnerClient, imageVariantsJob, SIGNATURE_HEADER, VARIANTS_PATH } from "./job";
|
|
15
|
+
export type { ImageInput, ImageRefusal, ImageRunnerClientOptions, ImageVariantsJobOptions, UploadEvent, VariantsRequest, VariantsResponse, } from "./job";
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
import type { Keyring } from "../auth/keyring";
|
|
2
|
+
import type { ImageManifest } from "../../images/types";
|
|
3
|
+
import type { VariantSettings } from "../../images/settings";
|
|
4
|
+
/** Where the source bytes are: an object in the product's bucket, a local file (runner's root), or a remote URL. */
|
|
5
|
+
export type ImageInput = {
|
|
6
|
+
r2Key: string;
|
|
7
|
+
} | {
|
|
8
|
+
file: string;
|
|
9
|
+
} | {
|
|
10
|
+
url: string;
|
|
11
|
+
};
|
|
12
|
+
export interface VariantsRequest {
|
|
13
|
+
v: 1;
|
|
14
|
+
input: ImageInput;
|
|
15
|
+
/** The key renditions are filed under (the R2 key for R2 inputs; the product names file/URL inputs). */
|
|
16
|
+
key: string;
|
|
17
|
+
/** Layout prefix (see imageLayout). */
|
|
18
|
+
prefix: string;
|
|
19
|
+
settings?: Partial<VariantSettings>;
|
|
20
|
+
/** Make them again even when a manifest for this set and source ETag exists. */
|
|
21
|
+
force?: boolean;
|
|
22
|
+
/**
|
|
23
|
+
* Set by imageRunnerClient: makes every request's signature unique, so the runner's replay guard never mistakes a
|
|
24
|
+
* legitimate repeat (a queue retry within the same second) for a replay.
|
|
25
|
+
*/
|
|
26
|
+
nonce?: string;
|
|
27
|
+
}
|
|
28
|
+
/** Refusals: the input itself is the problem (never retried). */
|
|
29
|
+
export type ImageRefusal = "unsupported" | "corrupt" | "too-large" | "too-many-pixels" | "too-many-frames" | "svg-unsafe" | "fetch-refused" | "not-found";
|
|
30
|
+
export type VariantsResponse = {
|
|
31
|
+
ok: true;
|
|
32
|
+
manifest: ImageManifest;
|
|
33
|
+
reused: boolean;
|
|
34
|
+
} | {
|
|
35
|
+
ok: false;
|
|
36
|
+
refused: ImageRefusal;
|
|
37
|
+
message: string;
|
|
38
|
+
};
|
|
39
|
+
export declare const VARIANTS_PATH = "/v1/variants";
|
|
40
|
+
export declare const SIGNATURE_HEADER = "x-image-signature";
|
|
41
|
+
export interface ImageRunnerClientOptions {
|
|
42
|
+
/** The runner's base URL (container or self-hosted). */
|
|
43
|
+
url: string;
|
|
44
|
+
keys: Keyring;
|
|
45
|
+
/** Service-HMAC domain tag the runner checks (the product's own, e.g. "acme-image-job-1"). */
|
|
46
|
+
domain: string;
|
|
47
|
+
fetch?: typeof fetch;
|
|
48
|
+
/** Per call, ms (default 120 000: a 48 MP HEIC with every format takes tens of seconds on one core). */
|
|
49
|
+
timeoutMs?: number;
|
|
50
|
+
}
|
|
51
|
+
export declare function imageRunnerClient(o: ImageRunnerClientOptions): {
|
|
52
|
+
variants(req: VariantsRequest): Promise<VariantsResponse>;
|
|
53
|
+
};
|
|
54
|
+
export interface UploadEvent {
|
|
55
|
+
key: string;
|
|
56
|
+
size?: number;
|
|
57
|
+
etag?: string;
|
|
58
|
+
}
|
|
59
|
+
export interface ImageVariantsJobOptions {
|
|
60
|
+
name?: string;
|
|
61
|
+
/** Key filter, passed to the pipeline as is (a glob over the product's key shapes). */
|
|
62
|
+
match: string;
|
|
63
|
+
prefix: string;
|
|
64
|
+
settings?: Partial<VariantSettings>;
|
|
65
|
+
variants: (req: VariantsRequest) => Promise<VariantsResponse>;
|
|
66
|
+
onManifest?: (m: ImageManifest, e: UploadEvent & {
|
|
67
|
+
reused: boolean;
|
|
68
|
+
}) => unknown;
|
|
69
|
+
onRefused?: (r: Extract<VariantsResponse, {
|
|
70
|
+
ok: false;
|
|
71
|
+
}>, e: UploadEvent) => unknown;
|
|
72
|
+
}
|
|
73
|
+
export declare function imageVariantsJob(o: ImageVariantsJobOptions): {
|
|
74
|
+
name: string;
|
|
75
|
+
match: string;
|
|
76
|
+
run(e: UploadEvent): Promise<VariantsResponse | {
|
|
77
|
+
ok: true;
|
|
78
|
+
skipped: "derived";
|
|
79
|
+
}>;
|
|
80
|
+
};
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
import { type ImageFormat } from "../../images/types";
|
|
2
|
+
import { type VariantSettings } from "../../images/settings";
|
|
3
|
+
export interface ImageLayout {
|
|
4
|
+
readonly prefix: string;
|
|
5
|
+
variantKey(sourceKey: string, set: string, rev: string, width: number, format: ImageFormat): string;
|
|
6
|
+
manifestKey(sourceKey: string, set: string): string;
|
|
7
|
+
masterKey(sourceKey: string): string;
|
|
8
|
+
cacheKey(hash: string, format: ImageFormat): string;
|
|
9
|
+
/** Whether a key is one of ours (a pipeline must not make variants of its own variants). */
|
|
10
|
+
isDerived(key: string): boolean;
|
|
11
|
+
}
|
|
12
|
+
export declare function imageLayout(prefix: string): ImageLayout;
|
|
13
|
+
/**
|
|
14
|
+
* The variant-set id: `s` + 12 hex of SHA-256 over the canonical settings and the runner's version (its codecs and
|
|
15
|
+
* pipeline). Same settings + same runner = same id = the job's idempotency key.
|
|
16
|
+
*/
|
|
17
|
+
export declare function variantSetId(settings: VariantSettings, runnerVersion: string): Promise<string>;
|
|
18
|
+
/**
|
|
19
|
+
* A source revision: 12 hex of SHA-256 over its ETag (or content hash). In rendition keys, in the master's metadata
|
|
20
|
+
* and, as `v`, in versioned on-the-fly URLs, so a re-upload never reuses an old key or an old cached answer.
|
|
21
|
+
*/
|
|
22
|
+
export declare function sourceRevision(etag: string): Promise<string>;
|
|
23
|
+
/** The image version: 12 hex over the source revision and the variant set (what the master was made from). */
|
|
24
|
+
export declare function imageVersion(rev: string, set: string): Promise<string>;
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* On-the-fly transform parameters, their one canonical spelling, and the allowlist (policy) every request is held to.
|
|
3
|
+
*
|
|
4
|
+
* p=card,f=auto,dpr=2 a named preset (its width/height/fit/quality come from the policy)
|
|
5
|
+
* w=640,f=webp,q=75 a free width from the policy's `widths`
|
|
6
|
+
*
|
|
7
|
+
* Canonical means: keys in a fixed order (p w h fit f q dpr v e), each once, integers without leading zeros, nothing
|
|
8
|
+
* else. One transform has exactly one spelling, so neither the signature nor the R2/edge cache can be fanned out by
|
|
9
|
+
* re-spelling a URL. Parsing refuses anything that isn't canonical.
|
|
10
|
+
*/
|
|
11
|
+
import type { ImageFormat } from "../../images/types";
|
|
12
|
+
export type Fit = "cover" | "contain" | "inside";
|
|
13
|
+
export type TransformFormat = "auto" | "avif" | "webp" | "jpeg" | "png";
|
|
14
|
+
export interface TransformParams {
|
|
15
|
+
/** A named preset from the policy (exclusive with width/height/fit/quality). */
|
|
16
|
+
preset?: string;
|
|
17
|
+
width?: number;
|
|
18
|
+
height?: number;
|
|
19
|
+
fit?: Fit;
|
|
20
|
+
/** "auto" picks from the request's Accept header (AVIF, then WebP, then JPEG/PNG). */
|
|
21
|
+
format: TransformFormat;
|
|
22
|
+
quality?: number;
|
|
23
|
+
dpr?: number;
|
|
24
|
+
/**
|
|
25
|
+
* The image version (manifest.version: the source revision and the variant set). Versioned URLs are cached for a
|
|
26
|
+
* year (immutable) and answer 404 once the source is replaced or the master remade with other settings;
|
|
27
|
+
* unversioned ones are cached for an hour.
|
|
28
|
+
*/
|
|
29
|
+
version?: string;
|
|
30
|
+
/** Optional expiry, unix seconds (for private images; public images usually don't expire). */
|
|
31
|
+
expires?: number;
|
|
32
|
+
}
|
|
33
|
+
export interface TransformPreset {
|
|
34
|
+
width: number;
|
|
35
|
+
height?: number;
|
|
36
|
+
fit?: Fit;
|
|
37
|
+
quality?: number;
|
|
38
|
+
}
|
|
39
|
+
export interface TransformPolicy {
|
|
40
|
+
/** Named presets: `p=<name>`. */
|
|
41
|
+
presets?: Record<string, TransformPreset>;
|
|
42
|
+
/** Free widths allowed with `w=` (default 320, 640, 1280, 2048). Empty = presets only. */
|
|
43
|
+
widths?: readonly number[];
|
|
44
|
+
/** Heights allowed with `h=` (default none: free heights only through presets). */
|
|
45
|
+
heights?: readonly number[];
|
|
46
|
+
/** Qualities allowed with `q=` (default none: the format's default quality). */
|
|
47
|
+
qualities?: readonly number[];
|
|
48
|
+
/** Device pixel ratios allowed with `dpr=` (default 1, 2). */
|
|
49
|
+
dprs?: readonly number[];
|
|
50
|
+
/** Output formats allowed (default all: auto, avif, webp, jpeg, png). */
|
|
51
|
+
formats?: readonly TransformFormat[];
|
|
52
|
+
/** Largest output edge after dpr (default 4096; never above the master either). */
|
|
53
|
+
maxEdge?: number;
|
|
54
|
+
}
|
|
55
|
+
export interface ResolvedPolicy {
|
|
56
|
+
presets: Record<string, TransformPreset>;
|
|
57
|
+
widths: ReadonlySet<number>;
|
|
58
|
+
heights: ReadonlySet<number>;
|
|
59
|
+
qualities: ReadonlySet<number>;
|
|
60
|
+
dprs: ReadonlySet<number>;
|
|
61
|
+
formats: ReadonlySet<TransformFormat>;
|
|
62
|
+
maxEdge: number;
|
|
63
|
+
}
|
|
64
|
+
export declare function resolvePolicy(p?: TransformPolicy): ResolvedPolicy;
|
|
65
|
+
export type PolicyProblem = "preset" | "width" | "height" | "fit" | "quality" | "dpr" | "format" | "size" | "shape";
|
|
66
|
+
/** Why params fall outside the policy, or null when they're allowed. */
|
|
67
|
+
export declare function policyProblem(t: TransformParams, pol: ResolvedPolicy): PolicyProblem | null;
|
|
68
|
+
/** The output box a request asks for, in device pixels (preset expanded, dpr applied). */
|
|
69
|
+
export declare function outputBox(t: TransformParams, pol: ResolvedPolicy): {
|
|
70
|
+
width: number;
|
|
71
|
+
height?: number;
|
|
72
|
+
fit: Fit;
|
|
73
|
+
quality?: number;
|
|
74
|
+
};
|
|
75
|
+
/** Canonical spelling, e.g. `w=640,f=auto`. Throws on params that can't be spelled (bad types, missing format). */
|
|
76
|
+
export declare function formatParams(t: TransformParams): string;
|
|
77
|
+
/** Parses a canonical params string (without the kid/signature). null for anything not in canonical form. */
|
|
78
|
+
export declare function parseParams(s: string): TransformParams | null;
|
|
79
|
+
export type ConcreteFormat = Exclude<TransformFormat, "auto">;
|
|
80
|
+
/**
|
|
81
|
+
* The output format for a request: an explicit format as asked; "auto" from the Accept header (AVIF, then WebP),
|
|
82
|
+
* else the universal fallback (JPEG, or PNG when the master has alpha). Accept entries with q=0 count as refused.
|
|
83
|
+
* With `allowed`, only allowed formats are ever chosen; null when none fits (the route answers 406).
|
|
84
|
+
*/
|
|
85
|
+
export declare function negotiateFormat(asked: TransformFormat, accept: string | null | undefined, o: {
|
|
86
|
+
hasAlpha: boolean;
|
|
87
|
+
allowed?: ReadonlySet<TransformFormat>;
|
|
88
|
+
}): ConcreteFormat | null;
|
|
89
|
+
/** For a type check against the shared ImageFormat union. */
|
|
90
|
+
export declare const asImageFormat: (f: ConcreteFormat) => ImageFormat;
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
import { type ImageFormat } from "../../images/types";
|
|
2
|
+
import type { ImageLayout } from "./layout";
|
|
3
|
+
import { type ConcreteFormat, type Fit } from "./params";
|
|
4
|
+
import type { ImageSigner } from "./sign";
|
|
5
|
+
/** The master's description, kept as R2 customMetadata on the master object. */
|
|
6
|
+
export interface MasterInfo {
|
|
7
|
+
width: number;
|
|
8
|
+
height: number;
|
|
9
|
+
hasAlpha: boolean;
|
|
10
|
+
format: ImageFormat;
|
|
11
|
+
set: string;
|
|
12
|
+
/** Source revision the master was made from ("" when unknown). */
|
|
13
|
+
rev?: string;
|
|
14
|
+
/** The image version (manifest.version: source revision + variant set); "" when unknown. */
|
|
15
|
+
version?: string;
|
|
16
|
+
}
|
|
17
|
+
export declare const masterMetadata: (m: MasterInfo) => Record<string, string>;
|
|
18
|
+
export declare function parseMasterMetadata(md: Record<string, string> | undefined): MasterInfo | null;
|
|
19
|
+
/** What a transformer is asked to do: fit the master into a box and encode it. */
|
|
20
|
+
export interface TransformJob {
|
|
21
|
+
source: MasterInfo;
|
|
22
|
+
width: number;
|
|
23
|
+
height?: number;
|
|
24
|
+
fit: Fit;
|
|
25
|
+
format: ConcreteFormat;
|
|
26
|
+
quality: number;
|
|
27
|
+
}
|
|
28
|
+
/** A codec back end: wasm (jSquash), the Cloudflare Images binding, or sharp (Node). See sdks/image-worker. */
|
|
29
|
+
export interface ImageTransformer {
|
|
30
|
+
readonly id: string;
|
|
31
|
+
transform(input: Uint8Array, job: TransformJob): Promise<Uint8Array>;
|
|
32
|
+
}
|
|
33
|
+
/** The R2 binding subset the route uses (an R2Bucket fits; so does the SDK's fake R2 for tests). */
|
|
34
|
+
export interface ImageBucket {
|
|
35
|
+
head(key: string): Promise<{
|
|
36
|
+
etag: string;
|
|
37
|
+
size: number;
|
|
38
|
+
customMetadata?: Record<string, string>;
|
|
39
|
+
} | null>;
|
|
40
|
+
get(key: string): Promise<{
|
|
41
|
+
etag: string;
|
|
42
|
+
size: number;
|
|
43
|
+
customMetadata?: Record<string, string>;
|
|
44
|
+
arrayBuffer(): Promise<ArrayBuffer>;
|
|
45
|
+
} | null>;
|
|
46
|
+
put(key: string, value: Uint8Array, o?: {
|
|
47
|
+
httpMetadata?: {
|
|
48
|
+
contentType?: string;
|
|
49
|
+
};
|
|
50
|
+
customMetadata?: Record<string, string>;
|
|
51
|
+
}): Promise<unknown>;
|
|
52
|
+
}
|
|
53
|
+
/** The Cache API subset (caches.default in a Worker). */
|
|
54
|
+
export interface EdgeCache {
|
|
55
|
+
match(req: Request): Promise<Response | undefined>;
|
|
56
|
+
put(req: Request, res: Response): Promise<void>;
|
|
57
|
+
}
|
|
58
|
+
export type ImageRouteEvent = {
|
|
59
|
+
type: "refused";
|
|
60
|
+
reason: string;
|
|
61
|
+
problem?: string;
|
|
62
|
+
} | {
|
|
63
|
+
type: "edge-hit";
|
|
64
|
+
key: string;
|
|
65
|
+
} | {
|
|
66
|
+
type: "r2-hit";
|
|
67
|
+
key: string;
|
|
68
|
+
cacheKey: string;
|
|
69
|
+
} | {
|
|
70
|
+
type: "transformed";
|
|
71
|
+
key: string;
|
|
72
|
+
cacheKey: string;
|
|
73
|
+
ms: number;
|
|
74
|
+
bytes: number;
|
|
75
|
+
format: ConcreteFormat;
|
|
76
|
+
transformer: string;
|
|
77
|
+
} | {
|
|
78
|
+
type: "no-master";
|
|
79
|
+
key: string;
|
|
80
|
+
} | {
|
|
81
|
+
type: "error";
|
|
82
|
+
key: string;
|
|
83
|
+
message: string;
|
|
84
|
+
};
|
|
85
|
+
export interface ImageRouteOptions {
|
|
86
|
+
signer: ImageSigner;
|
|
87
|
+
bucket: ImageBucket;
|
|
88
|
+
layout: ImageLayout;
|
|
89
|
+
transformer: ImageTransformer;
|
|
90
|
+
edgeCache?: EdgeCache;
|
|
91
|
+
/** Default quality per output format when the URL doesn't set one. */
|
|
92
|
+
quality?: Partial<Record<ConcreteFormat, number>>;
|
|
93
|
+
/** Largest master the route will decode, bytes (default 64 MiB) and pixels (default 40 MP). */
|
|
94
|
+
maxMasterBytes?: number;
|
|
95
|
+
maxMasterPixels?: number;
|
|
96
|
+
onEvent?: (e: ImageRouteEvent) => void;
|
|
97
|
+
/** Schedules work after the response (ctx.waitUntil in a Worker). */
|
|
98
|
+
waitUntil?: (p: Promise<unknown>) => void;
|
|
99
|
+
now?: () => number;
|
|
100
|
+
}
|
|
101
|
+
export declare function createImageRoute(o: ImageRouteOptions): (req: Request) => Promise<Response>;
|