@tide-ota/protocol 0.0.1 → 0.1.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.
@@ -0,0 +1,46 @@
1
+ /**
2
+ * A ready-to-serve `/manifest` reply: the exact signed multipart body and what the server sends beside it. The
3
+ * publisher derives every field from the parts it built and signed (docs/design.md, Stored replies).
4
+ */
5
+ export type StoredReply = {
6
+ readonly kind: "manifest";
7
+ readonly updateId: string;
8
+ readonly boundary: string;
9
+ readonly manifestFilters: string;
10
+ readonly body: Uint8Array<ArrayBuffer>;
11
+ } | {
12
+ readonly kind: "rollBackToEmbedded" | "noUpdateAvailable";
13
+ readonly boundary: string;
14
+ readonly body: Uint8Array<ArrayBuffer>;
15
+ };
16
+ /** The key of the signed noUpdateAvailable reply served when no pointer applies. */
17
+ export declare const NO_UPDATE_KEY = "reply/no-update";
18
+ /** The content keys that URLs published by earlier servers name, written by the legacy import. */
19
+ export declare const LEGACY_MAP_KEY = "legacy/map.json";
20
+ /** The largest record the server reads; encode refuses a larger one. */
21
+ export declare const MAX_REPLY_BYTES: number;
22
+ /** The longest `expo-manifest-filters` value, well under the smallest client header budget. */
23
+ export declare const MAX_FILTERS_BYTES = 4096;
24
+ /** A content-addressed bundle or asset key; lowercase, so it is safe on case-insensitive disks. */
25
+ export declare const CONTENT_KEY: RegExp;
26
+ /** Returns the record bytes for `reply`: one JSON object, keys in a fixed order, the body as a string. */
27
+ export declare function encodeStoredReply(reply: StoredReply): Uint8Array<ArrayBuffer>;
28
+ /** Returns the reply a record holds, with the body's exact bytes; a record encode would refuse is rejected. */
29
+ export declare function decodeStoredReply(bytes: Uint8Array): StoredReply;
30
+ /** Returns the pointer key for a channel, runtime version and platform; names outside the grammar are rejected. */
31
+ export declare function replyKey(channel: string, runtimeVersion: string, platform: string): string;
32
+ /** Returns the base record key for `updateId`, which must be a lowercase UUID. */
33
+ export declare function baseKey(updateId: string): string;
34
+ /** Returns the key of the patch from bundle `fromHex` to bundle `toHex`, each 64 lowercase hex. */
35
+ export declare function patchKey(fromHex: string, toHex: string): string;
36
+ /**
37
+ * Returns the relative file path that holds `key` on disk. Names are hex-escaped to lowercase without `.` or `-`, so
38
+ * no two keys share a path on a case-insensitive filesystem and no name collides with `reply/no-update`.
39
+ */
40
+ export declare function diskPath(key: string): string;
41
+ /** Returns the key whose `diskPath` is `path`, or undefined when no key maps there. */
42
+ export declare function diskKey(path: string): string | undefined;
43
+ /** Reverses `diskPath`'s escaping; for a directory `diskPath` creates, this is the key prefix it holds. */
44
+ export declare function unescapeDiskPath(path: string): string;
45
+ export declare function checkName(value: string, field: string): void;
46
+ export declare function checkUpdateId(value: unknown): string;
package/dist/reply.js ADDED
@@ -0,0 +1,215 @@
1
+ import { ProtocolError } from "./hash.js";
2
+ import { UUID } from "./manifest.js";
3
+ import { BOUNDARY } from "./multipart.js";
4
+ import { encodeSfvDictionary, parseSfvDictionary } from "./sfv.js";
5
+ /** The key of the signed noUpdateAvailable reply served when no pointer applies. */
6
+ export const NO_UPDATE_KEY = "reply/no-update";
7
+ /** The content keys that URLs published by earlier servers name, written by the legacy import. */
8
+ export const LEGACY_MAP_KEY = "legacy/map.json";
9
+ /** The largest record the server reads; encode refuses a larger one. */
10
+ export const MAX_REPLY_BYTES = 2 * 1024 * 1024;
11
+ /** The longest `expo-manifest-filters` value, well under the smallest client header budget. */
12
+ export const MAX_FILTERS_BYTES = 4096;
13
+ const VERSION = 1;
14
+ // Fields each kind's record may hold; a directive has no update ID or filters.
15
+ const RECORD_FIELDS = {
16
+ manifest: ["version", "kind", "updateId", "contentType", "manifestFilters", "body"],
17
+ rollBackToEmbedded: ["version", "kind", "contentType", "body"],
18
+ noUpdateAvailable: ["version", "kind", "contentType", "body"],
19
+ };
20
+ /** A content-addressed bundle or asset key; lowercase, so it is safe on case-insensitive disks. */
21
+ export const CONTENT_KEY = /^(?:assets|bundles)\/[0-9a-f]{64}$/;
22
+ // Release record, base record and patch keys, lowercase for the same reason.
23
+ const RECORD_KEY = new RegExp(`^updates/${UUID.source.slice(1, -1)}\\.json$`);
24
+ const BASE_KEY = new RegExp(`^bases/${UUID.source.slice(1, -1)}$`);
25
+ const PATCH_KEY = /^patches\/[0-9a-f]{64}\/[0-9a-f]{64}$/;
26
+ const CONTENT_TYPE = /^multipart\/mixed; boundary=(.*)$/s;
27
+ // Covers every Expo runtime policy: appVersion `2.6.2`, nativeVersion `1.0.0(1)`, sdkVersion `exposdk:57.0.0`.
28
+ const NAME = /^[A-Za-z0-9._+():-]{1,64}$/;
29
+ const encoder = new TextEncoder();
30
+ const utf8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
31
+ /** Returns the record bytes for `reply`: one JSON object, keys in a fixed order, the body as a string. */
32
+ export function encodeStoredReply(reply) {
33
+ let body;
34
+ try {
35
+ body = utf8.decode(reply.body);
36
+ }
37
+ catch {
38
+ throw new ProtocolError("body", "is not UTF-8");
39
+ }
40
+ const contentType = `multipart/mixed; boundary=${reply.boundary}`;
41
+ const record = reply.kind === "manifest"
42
+ ? {
43
+ version: VERSION,
44
+ kind: reply.kind,
45
+ updateId: reply.updateId,
46
+ contentType,
47
+ manifestFilters: reply.manifestFilters,
48
+ body,
49
+ }
50
+ : { version: VERSION, kind: reply.kind, contentType, body };
51
+ const bytes = new Uint8Array(encoder.encode(JSON.stringify(record)));
52
+ decodeStoredReply(bytes); // Encode never writes what decode refuses.
53
+ return bytes;
54
+ }
55
+ /** Returns the reply a record holds, with the body's exact bytes; a record encode would refuse is rejected. */
56
+ export function decodeStoredReply(bytes) {
57
+ if (bytes.length > MAX_REPLY_BYTES) {
58
+ throw new ProtocolError("record", `is too large: over ${MAX_REPLY_BYTES} bytes`);
59
+ }
60
+ let text;
61
+ try {
62
+ text = utf8.decode(bytes);
63
+ }
64
+ catch {
65
+ throw new ProtocolError("record", "is not UTF-8");
66
+ }
67
+ let parsed;
68
+ try {
69
+ parsed = JSON.parse(text);
70
+ }
71
+ catch {
72
+ throw new ProtocolError("record", "is not JSON");
73
+ }
74
+ if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
75
+ throw new ProtocolError("record", "must be a JSON object");
76
+ }
77
+ const r = parsed;
78
+ // Version first, so a later layout is reported as unsupported rather than as malformed.
79
+ const version = present(r, "version");
80
+ if (!Number.isInteger(version))
81
+ throw new ProtocolError("version", "must be an integer");
82
+ if (version !== VERSION)
83
+ throw new ProtocolError("version", "is not supported");
84
+ const kind = checkKind(present(r, "kind"));
85
+ for (const key of Object.keys(r)) {
86
+ if (!RECORD_FIELDS[kind].includes(key)) {
87
+ throw new ProtocolError(key, `is not a field of a ${kind} reply`);
88
+ }
89
+ }
90
+ const contentType = present(r, "contentType");
91
+ const boundary = typeof contentType === "string" ? CONTENT_TYPE.exec(contentType)?.[1] : undefined;
92
+ if (boundary === undefined || !BOUNDARY.test(boundary)) {
93
+ throw new ProtocolError("contentType", "must be multipart/mixed; boundary=<boundary>");
94
+ }
95
+ const body = present(r, "body");
96
+ if (typeof body !== "string" || body === "") {
97
+ throw new ProtocolError("body", "must be a non-empty string");
98
+ }
99
+ // JSON.parse accepts an escaped lone surrogate, which TextEncoder would replace with U+FFFD.
100
+ if (!body.isWellFormed())
101
+ throw new ProtocolError("body", "is not well-formed Unicode");
102
+ const bodyBytes = new Uint8Array(encoder.encode(body));
103
+ if (kind !== "manifest")
104
+ return { kind, boundary, body: bodyBytes };
105
+ return {
106
+ kind,
107
+ updateId: checkUpdateId(present(r, "updateId")),
108
+ boundary,
109
+ manifestFilters: checkFilters(present(r, "manifestFilters")),
110
+ body: bodyBytes,
111
+ };
112
+ }
113
+ /** Returns the pointer key for a channel, runtime version and platform; names outside the grammar are rejected. */
114
+ export function replyKey(channel, runtimeVersion, platform) {
115
+ checkName(channel, "channel");
116
+ checkName(runtimeVersion, "runtimeVersion");
117
+ if (platform !== "ios" && platform !== "android") {
118
+ throw new ProtocolError("platform", "must be ios or android");
119
+ }
120
+ return `reply/${channel}/${runtimeVersion}/${platform}`;
121
+ }
122
+ /** Returns the base record key for `updateId`, which must be a lowercase UUID. */
123
+ export function baseKey(updateId) {
124
+ return `bases/${checkUpdateId(updateId)}`;
125
+ }
126
+ /** Returns the key of the patch from bundle `fromHex` to bundle `toHex`, each 64 lowercase hex. */
127
+ export function patchKey(fromHex, toHex) {
128
+ const key = `patches/${fromHex}/${toHex}`;
129
+ if (!PATCH_KEY.test(key))
130
+ throw new ProtocolError("key", "must name two 64-hex bundle keys");
131
+ return key;
132
+ }
133
+ /**
134
+ * Returns the relative file path that holds `key` on disk. Names are hex-escaped to lowercase without `.` or `-`, so
135
+ * no two keys share a path on a case-insensitive filesystem and no name collides with `reply/no-update`.
136
+ */
137
+ export function diskPath(key) {
138
+ if (key === NO_UPDATE_KEY ||
139
+ key === LEGACY_MAP_KEY ||
140
+ CONTENT_KEY.test(key) ||
141
+ RECORD_KEY.test(key) ||
142
+ BASE_KEY.test(key) ||
143
+ PATCH_KEY.test(key)) {
144
+ return key;
145
+ }
146
+ const [prefix, channel = "", runtime = "", platform = "", ...rest] = key.split("/");
147
+ if (prefix !== "reply" || rest.length > 0)
148
+ throw new ProtocolError("key", "is not a store key");
149
+ try {
150
+ replyKey(channel, runtime, platform);
151
+ }
152
+ catch {
153
+ throw new ProtocolError("key", "is not a store key");
154
+ }
155
+ return `reply/${escapeName(channel)}/${escapeName(runtime)}/${platform}`;
156
+ }
157
+ /** Returns the key whose `diskPath` is `path`, or undefined when no key maps there. */
158
+ export function diskKey(path) {
159
+ const key = unescapeDiskPath(path);
160
+ try {
161
+ return diskPath(key) === path ? key : undefined;
162
+ }
163
+ catch {
164
+ return undefined;
165
+ }
166
+ }
167
+ /** Reverses `diskPath`'s escaping; for a directory `diskPath` creates, this is the key prefix it holds. */
168
+ export function unescapeDiskPath(path) {
169
+ return path.replace(/_([0-9a-f]{2})/g, (_, h) => String.fromCharCode(parseInt(h, 16)));
170
+ }
171
+ function escapeName(name) {
172
+ return name.replace(/[^a-z0-9]/g, (c) => `_${c.charCodeAt(0).toString(16).padStart(2, "0")}`);
173
+ }
174
+ export function checkName(value, field) {
175
+ // Dot segments would resolve in an S3 URL or a path join.
176
+ if (!NAME.test(value) || value === "." || value === "..") {
177
+ throw new ProtocolError(field, "must be 1 to 64 of A-Z, a-z, 0-9, ., _, +, -, (, ) and :, and not . or ..");
178
+ }
179
+ }
180
+ function checkKind(kind) {
181
+ if (typeof kind !== "string" || !Object.hasOwn(RECORD_FIELDS, kind)) {
182
+ throw new ProtocolError("kind", "must be manifest, rollBackToEmbedded or noUpdateAvailable");
183
+ }
184
+ return kind;
185
+ }
186
+ export function checkUpdateId(value) {
187
+ if (typeof value !== "string" || !UUID.test(value)) {
188
+ throw new ProtocolError("updateId", "must be a lowercase UUID");
189
+ }
190
+ return value;
191
+ }
192
+ /** Empty, or a canonical dictionary of strings: exactly what `encodeSfvDictionary` writes. */
193
+ function checkFilters(value) {
194
+ if (typeof value !== "string")
195
+ throw new ProtocolError("manifestFilters", "must be a string");
196
+ if (value.length > MAX_FILTERS_BYTES) {
197
+ throw new ProtocolError("manifestFilters", `is longer than ${MAX_FILTERS_BYTES} bytes`);
198
+ }
199
+ const members = new Map();
200
+ for (const [key, member] of parseSfvDictionary(value, "manifestFilters")) {
201
+ if (member.kind !== "string") {
202
+ throw new ProtocolError("manifestFilters", `${key} must be a string`);
203
+ }
204
+ members.set(key, member.text);
205
+ }
206
+ if (encodeSfvDictionary(Object.fromEntries(members)) !== value) {
207
+ throw new ProtocolError("manifestFilters", "must be written by encodeSfvDictionary");
208
+ }
209
+ return value;
210
+ }
211
+ function present(r, field) {
212
+ if (!Object.hasOwn(r, field))
213
+ throw new ProtocolError(field, "is missing");
214
+ return r[field];
215
+ }
package/dist/s3.d.ts ADDED
@@ -0,0 +1,117 @@
1
+ /** An S3-compatible bucket, addressed path-style. */
2
+ export interface S3Config {
3
+ readonly endpoint: string;
4
+ readonly region: string;
5
+ readonly bucket: string;
6
+ readonly accessKeyId: string;
7
+ readonly secretAccessKey: string;
8
+ }
9
+ /** A validated `S3Config`, ready for `s3Fetch`. */
10
+ export interface S3Target {
11
+ readonly endpoint: URL;
12
+ readonly bucket: string;
13
+ readonly credentials: SigV4Credentials;
14
+ }
15
+ export interface SigV4Credentials {
16
+ readonly accessKeyId: string;
17
+ readonly secretAccessKey: string;
18
+ readonly region: string;
19
+ readonly service: string;
20
+ }
21
+ export interface S3Request {
22
+ readonly method: "GET" | "PUT" | "DELETE";
23
+ readonly key?: string;
24
+ readonly query?: Readonly<Record<string, string>>;
25
+ readonly headers?: Readonly<Record<string, string>>;
26
+ readonly body?: Uint8Array<ArrayBuffer>;
27
+ }
28
+ export type S3Operation = "GetObject" | "PutObject" | "DeleteObject" | "ListObjectsV2";
29
+ /** What can be wrong with a 200; each is reported in these fixed words, never with the value received. */
30
+ declare const PROBLEMS: {
31
+ readonly encoding: "an unsupported content-encoding";
32
+ readonly length: "a missing or invalid content-length";
33
+ readonly body: "a body that differs from its content-length";
34
+ readonly over: "a content-length over the caller's limit";
35
+ readonly etag: "a missing or invalid ETag";
36
+ readonly date: "a missing or invalid Date";
37
+ readonly listing: "an invalid listing page";
38
+ };
39
+ export type S3Problem = keyof typeof PROBLEMS;
40
+ type S3Failure = {
41
+ readonly status: number;
42
+ readonly code: string | undefined;
43
+ } | {
44
+ readonly problem: S3Problem;
45
+ } | {
46
+ readonly timeoutMs: number;
47
+ } | "network";
48
+ /**
49
+ * An S3 failure. Its message holds only fixed words, the operation, the HTTP status and an allowlisted error code,
50
+ * so no provider text, key or credential can reach a log.
51
+ */
52
+ export declare class S3Error extends Error {
53
+ readonly status: number | undefined;
54
+ constructor(operation: S3Operation, failure: S3Failure);
55
+ /** The error for a request that got no response: a timeout when the deadline aborted it, else a network failure. */
56
+ static unanswered(operation: S3Operation, aborted: boolean, timeoutMs: number): S3Error;
57
+ }
58
+ export declare const EMPTY_SHA256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
59
+ /** Returns the validated target; no message echoes a value, since a rejected one may carry a credential. */
60
+ export declare function s3Target(config: S3Config): S3Target;
61
+ /** Returns validated credentials for `service`; a rejected one throws a `ProtocolError` naming the field, never the value. */
62
+ export declare function sigV4Credentials(config: Pick<S3Config, "region" | "accessKeyId" | "secretAccessKey">, service: string): SigV4Credentials;
63
+ /** Signs and sends one S3 request through `awsFetch`. */
64
+ export declare function s3Fetch(target: S3Target, request: S3Request, signal: AbortSignal): Promise<Response>;
65
+ /**
66
+ * Signs and sends one request with every header given. A 3xx is returned, never followed. Network failures reject
67
+ * with fetch's own error, which the caller replaces with its own.
68
+ */
69
+ export declare function awsFetch(request: {
70
+ readonly method: string;
71
+ readonly url: URL;
72
+ readonly headers?: Readonly<Record<string, string>>;
73
+ readonly body?: Uint8Array<ArrayBuffer>;
74
+ }, credentials: SigV4Credentials, signal: AbortSignal): Promise<Response>;
75
+ /** Returns the SigV4 `Authorization` value for a request, signing its query and every header given. */
76
+ export declare function signV4(request: {
77
+ method: string;
78
+ url: URL;
79
+ headers: Readonly<Record<string, string>>;
80
+ }, credentials: SigV4Credentials): Promise<string>;
81
+ /** Returns what makes a 200 unusable as one whole unencoded object, or undefined. */
82
+ export declare function s3BodyProblem(res: Response): S3Problem | undefined;
83
+ /**
84
+ * Returns the `Code` of a complete S3 error document of at most 4 KiB: root `Error` with exactly one direct,
85
+ * text-only `Code` child. Anything else is undefined; a body that fails mid-read rejects.
86
+ */
87
+ export declare function s3ErrorCode(res: Response): Promise<string | undefined>;
88
+ /** Returns undefined for a 404 `NoSuchKey`, the one non-200 that means absence; any other response throws. */
89
+ export declare function s3Absent(operation: S3Operation, res: Response): Promise<undefined>;
90
+ /**
91
+ * Returns a body of at most `limit` bytes as text, or undefined when it is absent, longer, or not valid UTF-8; the
92
+ * read stops at the limit. A body that fails mid-read rejects.
93
+ */
94
+ export declare function readS3Text(res: Response, limit: number): Promise<string | undefined>;
95
+ /** Returns the body's bytes, empty when absent, or undefined once it passes `limit`, cancelling the rest. */
96
+ export declare function readLimited(res: Response, limit: number): Promise<Uint8Array<ArrayBuffer> | undefined>;
97
+ export interface XmlElement {
98
+ readonly name: string;
99
+ readonly children: readonly (XmlElement | string)[];
100
+ }
101
+ /**
102
+ * Returns the element tree of one S3 response document, or undefined. Strict: an optional XML declaration, elements
103
+ * and text with the predefined entities and character references; no comments, CDATA, DOCTYPE, processing
104
+ * instructions, prefixed names, or attributes other than the S3 namespace on the root.
105
+ */
106
+ export declare function parseS3Xml(text: string): XmlElement | undefined;
107
+ /** Returns the direct children of `element` named `name`. */
108
+ export declare function childElements(element: XmlElement, name: string): XmlElement[];
109
+ /** Returns the text of an element holding only text ("" when empty), or undefined. */
110
+ export declare function textOf(element: XmlElement): string | undefined;
111
+ /** Returns the store the environment configures: TIDE_DISK_DIR, or every TIDE_S3_* variable. Empty means unset. */
112
+ export declare function storageFromEnv(env: Readonly<Record<string, string | undefined>>): {
113
+ readonly disk: string;
114
+ } | {
115
+ readonly s3: S3Config;
116
+ };
117
+ export {};