@kubohiroya/sb3-toolchain 0.20.0 → 0.21.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/CHANGELOG.md +4 -0
- package/README.ja.md +14 -1
- package/README.md +14 -1
- package/dist/cli.d.ts +7 -1
- package/dist/cli.js +41 -1
- package/dist/cli.js.map +1 -1
- package/dist/constants.d.ts +1 -1
- package/dist/constants.js +1 -1
- package/dist/constants.js.map +1 -1
- package/dist/extension-digest-inventory.d.ts +104 -0
- package/dist/extension-digest-inventory.js +319 -0
- package/dist/extension-digest-inventory.js.map +1 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.js +2 -1
- package/docs/extension-digests.md +83 -0
- package/docs/index.html +10 -2
- package/docs/ja/extension-digests.md +81 -0
- package/docs/ja/workflows.md +2 -0
- package/docs/workflows.md +3 -0
- package/package.json +1 -1
|
@@ -0,0 +1,319 @@
|
|
|
1
|
+
import { assert } from "./assert.js";
|
|
2
|
+
import { validateArchiveEntryName } from "./archive.js";
|
|
3
|
+
import { decodeExtensionDataUrl } from "./import.js";
|
|
4
|
+
import path from "node:path";
|
|
5
|
+
import { createHash } from "node:crypto";
|
|
6
|
+
import { lstat, readFile } from "node:fs/promises";
|
|
7
|
+
import { strFromU8, unzipSync } from "fflate";
|
|
8
|
+
//#region src/extension-digest-inventory.ts
|
|
9
|
+
/**
|
|
10
|
+
* Reads what an SB3 itself says about the extensions it carries: the pinned SHA-256, which of the
|
|
11
|
+
* four forms the author kept each extension in, how many bytes the archive holds for it, and the
|
|
12
|
+
* project URI that names the work.
|
|
13
|
+
*
|
|
14
|
+
* Nothing here looks at a browser's stored state. An extension cache lives in IndexedDB, which
|
|
15
|
+
* belongs to an origin *and* to a browser profile, so a command line cannot reach the cache the
|
|
16
|
+
* person running it actually has. This side produces the list to compare against; the screen in
|
|
17
|
+
* the browser owns the listing and the deleting.
|
|
18
|
+
*
|
|
19
|
+
* Nothing here is fetched either. A project URI says nothing until its author publishes there, and
|
|
20
|
+
* a work saved but never published looks exactly like a published work whose address rotted. So no
|
|
21
|
+
* URL in an SB3 is contacted, and no absence is ever concluded from a response.
|
|
22
|
+
*
|
|
23
|
+
* The manifest rules below are read, not imported. `@kubohiroya/turbowarp-extension-loader` owns
|
|
24
|
+
* them, but it is a browser runtime this command never needs, and taking a dependency on it would
|
|
25
|
+
* add nothing an inventory uses: no bytes are resolved, no dependency graph is ordered, nothing is
|
|
26
|
+
* executed. What is reproduced here is only what the report prints — the four source names, the
|
|
27
|
+
* digest form, the embedded path rule, the HTTPS address rule, and the refusal of the retired
|
|
28
|
+
* spellings. A change to any of those on the loader's side is a change to make here too.
|
|
29
|
+
*/
|
|
30
|
+
/** The project.json member the loader family keeps its manifest under. */
|
|
31
|
+
var projectManifestKey = "turboWarpPlus";
|
|
32
|
+
/**
|
|
33
|
+
* The four forms an author can keep one extension in, spelled as the manifest spells them.
|
|
34
|
+
*
|
|
35
|
+
* Two hold a reference and two hold the bytes. Only `remote-cacheable` can ever leave a copy in a
|
|
36
|
+
* browser, which is what makes the distinction worth reporting at all.
|
|
37
|
+
*/
|
|
38
|
+
var extensionSourceTypes = Object.freeze([
|
|
39
|
+
"remote-non-cacheable",
|
|
40
|
+
"remote-cacheable",
|
|
41
|
+
"embedded-file",
|
|
42
|
+
"embedded-data"
|
|
43
|
+
]);
|
|
44
|
+
var archiveSizeLimit = 67108864;
|
|
45
|
+
var expandedSizeLimit = 268435456;
|
|
46
|
+
var archiveEntryLimit = 4096;
|
|
47
|
+
var manifestExtensionLimit = 64;
|
|
48
|
+
var sha256Pattern = /^[a-f0-9]{64}$/u;
|
|
49
|
+
var extensionIdPattern = /^[a-zA-Z][a-zA-Z0-9]{0,63}$/u;
|
|
50
|
+
var embeddedPathPattern = /^extensions\/[a-zA-Z0-9][a-zA-Z0-9._/-]*\.js$/u;
|
|
51
|
+
function isObject(value) {
|
|
52
|
+
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
53
|
+
}
|
|
54
|
+
function sha256(contents) {
|
|
55
|
+
return createHash("sha256").update(contents).digest("hex");
|
|
56
|
+
}
|
|
57
|
+
function assertKnownMembers(value, allowed, label) {
|
|
58
|
+
assert(isObject(value), `${label} must be a JSON object.`);
|
|
59
|
+
const unknownMembers = Object.keys(value).filter((key) => !allowed.includes(key));
|
|
60
|
+
assert(unknownMembers.length === 0, `${label} has unknown members: ${unknownMembers.join(", ")}`);
|
|
61
|
+
return value;
|
|
62
|
+
}
|
|
63
|
+
/** One rule for every address the manifest records, applied without contacting anything. */
|
|
64
|
+
function manifestAddress(value, what) {
|
|
65
|
+
assert(typeof value === "string" && value.length > 0 && value.length <= 4096, `${what} must be an absolute HTTPS URL.`);
|
|
66
|
+
let url;
|
|
67
|
+
try {
|
|
68
|
+
url = new URL(value);
|
|
69
|
+
} catch {
|
|
70
|
+
throw new Error(`${what} must be an absolute HTTPS URL.`);
|
|
71
|
+
}
|
|
72
|
+
assert(url.protocol === "https:" && !url.username && !url.password && !url.hash, `${what} requires HTTPS without credentials or a fragment.`);
|
|
73
|
+
return url.href;
|
|
74
|
+
}
|
|
75
|
+
function readManifestSource(value, id) {
|
|
76
|
+
assert(isObject(value), `Extension ${id} is missing its source.`);
|
|
77
|
+
const { type } = value;
|
|
78
|
+
if (type === "remote-non-cacheable" || type === "remote-cacheable") {
|
|
79
|
+
assertKnownMembers(value, ["type", "url"], `Extension ${id} source`);
|
|
80
|
+
return {
|
|
81
|
+
type,
|
|
82
|
+
path: null,
|
|
83
|
+
url: manifestAddress(value.url, `Extension ${id} source URL`)
|
|
84
|
+
};
|
|
85
|
+
}
|
|
86
|
+
if (type === "embedded-file") {
|
|
87
|
+
assertKnownMembers(value, [
|
|
88
|
+
"type",
|
|
89
|
+
"path",
|
|
90
|
+
"url"
|
|
91
|
+
], `Extension ${id} source`);
|
|
92
|
+
const sourcePath = value.path;
|
|
93
|
+
assert(typeof sourcePath === "string" && sourcePath.length <= 256 && embeddedPathPattern.test(sourcePath) && !sourcePath.split("/").some((part) => !part || part === "." || part === ".."), `Extension ${id} has an unsafe embedded path: ${JSON.stringify(sourcePath)}`);
|
|
94
|
+
return {
|
|
95
|
+
type,
|
|
96
|
+
path: sourcePath,
|
|
97
|
+
url: value.url === void 0 ? null : manifestAddress(value.url, `Extension ${id} source URL`)
|
|
98
|
+
};
|
|
99
|
+
}
|
|
100
|
+
if (type === "embedded-data") {
|
|
101
|
+
assertKnownMembers(value, ["type", "url"], `Extension ${id} source`);
|
|
102
|
+
return {
|
|
103
|
+
type,
|
|
104
|
+
path: null,
|
|
105
|
+
url: value.url === void 0 ? null : manifestAddress(value.url, `Extension ${id} source URL`)
|
|
106
|
+
};
|
|
107
|
+
}
|
|
108
|
+
assert(type !== "remote", `Extension ${id}: a remote source is now remote-cacheable or remote-non-cacheable.`);
|
|
109
|
+
assert(type !== "cached", `Extension ${id}: a cached source is now embedded-file with a url.`);
|
|
110
|
+
assert(type !== "embedded", `Extension ${id}: an embedded source is now embedded-file or embedded-data.`);
|
|
111
|
+
throw new Error(`Extension ${id} has an unsupported source type: ${JSON.stringify(type)}`);
|
|
112
|
+
}
|
|
113
|
+
/**
|
|
114
|
+
* Validates only what this inventory reports, without resolving dependencies or granting anything.
|
|
115
|
+
*
|
|
116
|
+
* The manifest is the author's claim about their own project, so it is read as untrusted data: the
|
|
117
|
+
* members are checked, and nothing in it is contacted or executed.
|
|
118
|
+
*/
|
|
119
|
+
function readProjectManifest(project) {
|
|
120
|
+
assert(isObject(project), "SB3 project.json must contain a JSON object.");
|
|
121
|
+
if (!Object.hasOwn(project, "turboWarpPlus")) return null;
|
|
122
|
+
const manifest = assertKnownMembers(project[projectManifestKey], [
|
|
123
|
+
"schemaVersion",
|
|
124
|
+
"uri",
|
|
125
|
+
"extensions"
|
|
126
|
+
], "Project manifest");
|
|
127
|
+
assert(manifest.schemaVersion === 1, "Only project manifest schemaVersion 1 is supported.");
|
|
128
|
+
const uri = manifest.uri === void 0 ? null : manifestAddress(manifest.uri, "A project URI");
|
|
129
|
+
assert(Array.isArray(manifest.extensions) && manifest.extensions.length <= manifestExtensionLimit, `Project manifest extensions must be an array of at most ${manifestExtensionLimit} entries.`);
|
|
130
|
+
const seenIds = /* @__PURE__ */ new Set();
|
|
131
|
+
return {
|
|
132
|
+
uri,
|
|
133
|
+
extensions: manifest.extensions.map((entry) => {
|
|
134
|
+
const extension = assertKnownMembers(entry, [
|
|
135
|
+
"id",
|
|
136
|
+
"source",
|
|
137
|
+
"execution",
|
|
138
|
+
"sha256",
|
|
139
|
+
"version",
|
|
140
|
+
"publisher",
|
|
141
|
+
"capabilities",
|
|
142
|
+
"dependencies"
|
|
143
|
+
], "Project manifest extension");
|
|
144
|
+
const { id } = extension;
|
|
145
|
+
assert(typeof id === "string" && extensionIdPattern.test(id) && !seenIds.has(id), `Invalid or duplicate manifest extension ID: ${JSON.stringify(id)}`);
|
|
146
|
+
seenIds.add(id);
|
|
147
|
+
assert(extension.execution === "sandboxed" || extension.execution === "unsandboxed", `Extension ${id} requires an explicit sandboxed or unsandboxed execution request.`);
|
|
148
|
+
assert(typeof extension.sha256 === "string" && sha256Pattern.test(extension.sha256), `Extension ${id} requires a lowercase SHA-256 pin.`);
|
|
149
|
+
return {
|
|
150
|
+
id,
|
|
151
|
+
sha256: extension.sha256,
|
|
152
|
+
execution: extension.execution,
|
|
153
|
+
source: readManifestSource(extension.source, id)
|
|
154
|
+
};
|
|
155
|
+
})
|
|
156
|
+
};
|
|
157
|
+
}
|
|
158
|
+
function parseArchive(contents) {
|
|
159
|
+
const names = /* @__PURE__ */ new Set();
|
|
160
|
+
let expandedSize = 0;
|
|
161
|
+
const entries = unzipSync(contents, { filter: (entry) => {
|
|
162
|
+
validateArchiveEntryName(entry.name);
|
|
163
|
+
assert(!names.has(entry.name), `Duplicate SB3 archive entry: ${entry.name}`);
|
|
164
|
+
names.add(entry.name);
|
|
165
|
+
expandedSize += entry.originalSize;
|
|
166
|
+
assert(names.size <= archiveEntryLimit && expandedSize <= expandedSizeLimit, "SB3 expansion limit exceeded.");
|
|
167
|
+
return true;
|
|
168
|
+
} });
|
|
169
|
+
assert(Object.hasOwn(entries, "project.json"), "SB3 archive does not contain project.json.");
|
|
170
|
+
let project;
|
|
171
|
+
try {
|
|
172
|
+
project = JSON.parse(strFromU8(entries["project.json"]));
|
|
173
|
+
} catch (error) {
|
|
174
|
+
throw new Error("SB3 project.json is not valid JSON.", { cause: error });
|
|
175
|
+
}
|
|
176
|
+
assert(isObject(project), "SB3 project.json must contain a JSON object.");
|
|
177
|
+
return {
|
|
178
|
+
entries,
|
|
179
|
+
project
|
|
180
|
+
};
|
|
181
|
+
}
|
|
182
|
+
async function readArchive(filePath) {
|
|
183
|
+
assert(path.extname(filePath).toLowerCase() === ".sb3", `Expected an .sb3 file: ${filePath}`);
|
|
184
|
+
const stats = await lstat(filePath);
|
|
185
|
+
assert(stats.isFile() && !stats.isSymbolicLink(), `Expected a regular SB3 file: ${filePath}`);
|
|
186
|
+
assert(stats.size <= archiveSizeLimit, `SB3 exceeds the 64 MiB limit: ${filePath}`);
|
|
187
|
+
return readFile(filePath);
|
|
188
|
+
}
|
|
189
|
+
function heldBytes(extension, archive) {
|
|
190
|
+
if (extension.source.type === "embedded-file") {
|
|
191
|
+
const entryPath = extension.source.path;
|
|
192
|
+
const entry = archive.entries[entryPath];
|
|
193
|
+
assert(entry !== void 0, `Extension ${extension.id} names a missing archive entry: ${entryPath}`);
|
|
194
|
+
return entry;
|
|
195
|
+
}
|
|
196
|
+
if (extension.source.type === "embedded-data") {
|
|
197
|
+
const urls = archive.project.extensionURLs;
|
|
198
|
+
assert(isObject(urls) && typeof urls[extension.id] === "string", `Extension ${extension.id} is missing its embedded data carrier in extensionURLs.`);
|
|
199
|
+
return decodeExtensionDataUrl(urls[extension.id]).source;
|
|
200
|
+
}
|
|
201
|
+
return null;
|
|
202
|
+
}
|
|
203
|
+
/** Reads one SB3's manifest digests; `embedded-data` sizes come from the decoded carrier. */
|
|
204
|
+
function inspectSb3ExtensionDigests(inputPath, contents) {
|
|
205
|
+
const archive = parseArchive(contents);
|
|
206
|
+
const manifest = readProjectManifest(archive.project);
|
|
207
|
+
if (!manifest) return {
|
|
208
|
+
inputPath,
|
|
209
|
+
uri: null,
|
|
210
|
+
manifestPresent: false,
|
|
211
|
+
extensions: []
|
|
212
|
+
};
|
|
213
|
+
const extensions = manifest.extensions.map((extension) => {
|
|
214
|
+
const bytes = heldBytes(extension, archive);
|
|
215
|
+
return {
|
|
216
|
+
id: extension.id,
|
|
217
|
+
sha256: extension.sha256,
|
|
218
|
+
sourceType: extension.source.type,
|
|
219
|
+
size: bytes ? bytes.byteLength : null,
|
|
220
|
+
heldSha256: bytes ? sha256(bytes) : null,
|
|
221
|
+
url: extension.source.url,
|
|
222
|
+
path: extension.source.path,
|
|
223
|
+
execution: extension.execution,
|
|
224
|
+
cacheable: extension.source.type === "remote-cacheable"
|
|
225
|
+
};
|
|
226
|
+
});
|
|
227
|
+
return {
|
|
228
|
+
inputPath,
|
|
229
|
+
uri: manifest.uri,
|
|
230
|
+
manifestPresent: true,
|
|
231
|
+
extensions
|
|
232
|
+
};
|
|
233
|
+
}
|
|
234
|
+
/**
|
|
235
|
+
* Builds the list to compare a browser's extension cache against.
|
|
236
|
+
*
|
|
237
|
+
* Whether a digest is shared is decided by how many of the given SB3s name it, and by nothing
|
|
238
|
+
* else: an input that was not given is simply unknown, never absent. The same goes for
|
|
239
|
+
* `cacheable` — it says that some input given here keeps those bytes as `remote-cacheable`, which
|
|
240
|
+
* is the only form a cache may hold, so a digest left over from a project since converted to
|
|
241
|
+
* `remote-non-cacheable` shows up with `cacheable` false.
|
|
242
|
+
*/
|
|
243
|
+
async function inventoryExtensionDigests(inputPaths) {
|
|
244
|
+
assert(inputPaths.length > 0, "At least one INPUT.sb3 is required.");
|
|
245
|
+
const resolvedPaths = inputPaths.map((inputPath) => path.resolve(inputPath));
|
|
246
|
+
const seenPaths = /* @__PURE__ */ new Set();
|
|
247
|
+
for (const resolvedPath of resolvedPaths) {
|
|
248
|
+
assert(!seenPaths.has(resolvedPath), `Duplicate SB3 input: ${resolvedPath}`);
|
|
249
|
+
seenPaths.add(resolvedPath);
|
|
250
|
+
}
|
|
251
|
+
const projects = [];
|
|
252
|
+
for (const resolvedPath of resolvedPaths) projects.push(inspectSb3ExtensionDigests(resolvedPath, await readArchive(resolvedPath)));
|
|
253
|
+
const usages = /* @__PURE__ */ new Map();
|
|
254
|
+
for (const project of projects) for (const extension of project.extensions) {
|
|
255
|
+
let usage = usages.get(extension.sha256);
|
|
256
|
+
if (!usage) {
|
|
257
|
+
usage = {
|
|
258
|
+
sha256: extension.sha256,
|
|
259
|
+
ids: [],
|
|
260
|
+
sourceTypes: [],
|
|
261
|
+
cacheable: false,
|
|
262
|
+
size: null,
|
|
263
|
+
projects: [],
|
|
264
|
+
shared: false
|
|
265
|
+
};
|
|
266
|
+
usages.set(extension.sha256, usage);
|
|
267
|
+
}
|
|
268
|
+
if (!usage.ids.includes(extension.id)) usage.ids.push(extension.id);
|
|
269
|
+
if (!usage.sourceTypes.includes(extension.sourceType)) usage.sourceTypes.push(extension.sourceType);
|
|
270
|
+
usage.cacheable = usage.cacheable || extension.cacheable;
|
|
271
|
+
if (usage.size === null) usage.size = extension.size;
|
|
272
|
+
if (!usage.projects.some((entry) => entry.inputPath === project.inputPath)) usage.projects.push({
|
|
273
|
+
inputPath: project.inputPath,
|
|
274
|
+
uri: project.uri
|
|
275
|
+
});
|
|
276
|
+
}
|
|
277
|
+
const digests = [...usages.values()].sort((left, right) => left.sha256 < right.sha256 ? -1 : 1);
|
|
278
|
+
for (const usage of digests) {
|
|
279
|
+
usage.ids.sort();
|
|
280
|
+
usage.shared = usage.projects.length > 1;
|
|
281
|
+
}
|
|
282
|
+
return {
|
|
283
|
+
projects,
|
|
284
|
+
digests
|
|
285
|
+
};
|
|
286
|
+
}
|
|
287
|
+
/** Formats the inventory as the lines the CLI prints, one fact per `key=value` pair. */
|
|
288
|
+
function formatExtensionDigestInventory(inventory) {
|
|
289
|
+
const extensionCount = inventory.projects.reduce((total, project) => total + project.extensions.length, 0);
|
|
290
|
+
const sharedCount = inventory.digests.filter((usage) => usage.shared).length;
|
|
291
|
+
const lines = [`Inventory: ${inventory.projects.length} SB3 inputs; ${extensionCount} manifest extensions; ${inventory.digests.length} distinct digests (${sharedCount} shared, ${inventory.digests.length - sharedCount} in one project).`];
|
|
292
|
+
for (const project of inventory.projects) {
|
|
293
|
+
if (!project.manifestPresent) {
|
|
294
|
+
lines.push(`${project.inputPath}: manifest=absent`);
|
|
295
|
+
continue;
|
|
296
|
+
}
|
|
297
|
+
lines.push(`${project.inputPath}: uri=${project.uri ?? "absent"}; extensions=${project.extensions.length}`);
|
|
298
|
+
for (const extension of project.extensions) {
|
|
299
|
+
const details = [
|
|
300
|
+
`sha256=${extension.sha256}`,
|
|
301
|
+
`source=${extension.sourceType}`,
|
|
302
|
+
`size=${extension.size === null ? "not-held" : extension.size}`,
|
|
303
|
+
`cacheable=${extension.cacheable ? "yes" : "no"}`,
|
|
304
|
+
`execution=${extension.execution}`
|
|
305
|
+
];
|
|
306
|
+
if (extension.path) details.push(`path=${extension.path}`);
|
|
307
|
+
if (extension.url) details.push(`url=${extension.url}`);
|
|
308
|
+
if (extension.heldSha256 && extension.heldSha256 !== extension.sha256) details.push(`held-sha256=${extension.heldSha256}`);
|
|
309
|
+
lines.push(` ${extension.id}: ${details.join("; ")}`);
|
|
310
|
+
}
|
|
311
|
+
}
|
|
312
|
+
for (const usage of inventory.digests) lines.push(`${usage.shared ? "Shared" : "Single"}: ${usage.sha256}; projects=${usage.projects.length}; ids=${usage.ids.join(",")}; sources=${usage.sourceTypes.join(",")}; cacheable=${usage.cacheable ? "yes" : "no"}; size=${usage.size === null ? "not-held" : usage.size}`);
|
|
313
|
+
lines.push("Browser caches are not read: IndexedDB belongs to an origin and a browser profile. No URI above was contacted, and an unresolved URI never means an absent project.");
|
|
314
|
+
return lines;
|
|
315
|
+
}
|
|
316
|
+
//#endregion
|
|
317
|
+
export { extensionSourceTypes, formatExtensionDigestInventory, inspectSb3ExtensionDigests, inventoryExtensionDigests, projectManifestKey, readProjectManifest };
|
|
318
|
+
|
|
319
|
+
//# sourceMappingURL=extension-digest-inventory.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"extension-digest-inventory.js","names":[],"sources":["../src/extension-digest-inventory.ts"],"sourcesContent":["// SPDX-License-Identifier: MPL-2.0\n\n/**\n * Reads what an SB3 itself says about the extensions it carries: the pinned SHA-256, which of the\n * four forms the author kept each extension in, how many bytes the archive holds for it, and the\n * project URI that names the work.\n *\n * Nothing here looks at a browser's stored state. An extension cache lives in IndexedDB, which\n * belongs to an origin *and* to a browser profile, so a command line cannot reach the cache the\n * person running it actually has. This side produces the list to compare against; the screen in\n * the browser owns the listing and the deleting.\n *\n * Nothing here is fetched either. A project URI says nothing until its author publishes there, and\n * a work saved but never published looks exactly like a published work whose address rotted. So no\n * URL in an SB3 is contacted, and no absence is ever concluded from a response.\n *\n * The manifest rules below are read, not imported. `@kubohiroya/turbowarp-extension-loader` owns\n * them, but it is a browser runtime this command never needs, and taking a dependency on it would\n * add nothing an inventory uses: no bytes are resolved, no dependency graph is ordered, nothing is\n * executed. What is reproduced here is only what the report prints — the four source names, the\n * digest form, the embedded path rule, the HTTPS address rule, and the refusal of the retired\n * spellings. A change to any of those on the loader's side is a change to make here too.\n */\n\nimport {createHash} from 'node:crypto';\nimport {lstat, readFile} from 'node:fs/promises';\nimport path from 'node:path';\n\nimport {strFromU8, unzipSync} from 'fflate';\n\nimport {validateArchiveEntryName} from './archive';\nimport {assert} from './assert';\nimport {decodeExtensionDataUrl} from './import';\nimport type {UnknownRecord} from './types';\n\n/** The project.json member the loader family keeps its manifest under. */\nexport const projectManifestKey = 'turboWarpPlus';\n\n/**\n * The four forms an author can keep one extension in, spelled as the manifest spells them.\n *\n * Two hold a reference and two hold the bytes. Only `remote-cacheable` can ever leave a copy in a\n * browser, which is what makes the distinction worth reporting at all.\n */\nexport const extensionSourceTypes = Object.freeze([\n 'remote-non-cacheable',\n 'remote-cacheable',\n 'embedded-file',\n 'embedded-data',\n] as const);\n\nexport type ExtensionSourceType = (typeof extensionSourceTypes)[number];\n\nexport type ExtensionExecutionMode = 'sandboxed' | 'unsandboxed';\n\nexport interface ExtensionDigestEntry {\n /** The extension ID, which is also how an `embedded-data` carrier is addressed. */\n id: string;\n /** The SHA-256 the manifest pins, lowercase hexadecimal. */\n sha256: string;\n sourceType: ExtensionSourceType;\n /** Bytes the SB3 itself holds for this extension; null when it holds only a reference. */\n size: number | null;\n /** The digest of the bytes the SB3 holds; null when it holds only a reference. */\n heldSha256: string | null;\n /** The recorded address, for either reference form or an embedded source that kept its origin. */\n url: string | null;\n /** The archive entry that carries the bytes, for `embedded-file` only. */\n path: string | null;\n execution: ExtensionExecutionMode;\n /** Whether this form can leave a copy in a browser's cache. */\n cacheable: boolean;\n}\n\nexport interface Sb3ExtensionDigests {\n inputPath: string;\n /** The project's own claim of its address, which is the cache bucket name. Never fetched. */\n uri: string | null;\n manifestPresent: boolean;\n extensions: ExtensionDigestEntry[];\n}\n\nexport interface ExtensionDigestUsage {\n sha256: string;\n /** Every extension ID that names these bytes, across the inputs, sorted. */\n ids: string[];\n /** Every form these bytes are kept in, across the inputs, in manifest order. */\n sourceTypes: ExtensionSourceType[];\n /** True when at least one input keeps these bytes as `remote-cacheable`. */\n cacheable: boolean;\n /** Byte length when some input holds the bytes; null when every input holds a reference. */\n size: number | null;\n projects: {inputPath: string; uri: string | null}[];\n /** True when more than one input names these bytes. */\n shared: boolean;\n}\n\nexport interface ExtensionDigestInventory {\n projects: Sb3ExtensionDigests[];\n /** One record per distinct digest, ordered by digest so two runs read the same way. */\n digests: ExtensionDigestUsage[];\n}\n\nconst archiveSizeLimit = 64 * 1024 * 1024;\nconst expandedSizeLimit = 256 * 1024 * 1024;\nconst archiveEntryLimit = 4096;\nconst manifestExtensionLimit = 64;\nconst sha256Pattern = /^[a-f0-9]{64}$/u;\nconst extensionIdPattern = /^[a-zA-Z][a-zA-Z0-9]{0,63}$/u;\nconst embeddedPathPattern = /^extensions\\/[a-zA-Z0-9][a-zA-Z0-9._/-]*\\.js$/u;\n\nfunction isObject(value: unknown): value is UnknownRecord {\n return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\nfunction sha256(contents: Uint8Array): string {\n return createHash('sha256').update(contents).digest('hex');\n}\n\nfunction assertKnownMembers(value: unknown, allowed: string[], label: string): UnknownRecord {\n assert(isObject(value), `${label} must be a JSON object.`);\n const unknownMembers = Object.keys(value).filter((key) => !allowed.includes(key));\n assert(unknownMembers.length === 0, `${label} has unknown members: ${unknownMembers.join(', ')}`);\n return value;\n}\n\n/** One rule for every address the manifest records, applied without contacting anything. */\nfunction manifestAddress(value: unknown, what: string): string {\n assert(\n typeof value === 'string' && value.length > 0 && value.length <= 4096,\n `${what} must be an absolute HTTPS URL.`,\n );\n let url: URL;\n try {\n url = new URL(value);\n } catch {\n throw new Error(`${what} must be an absolute HTTPS URL.`);\n }\n assert(\n url.protocol === 'https:' && !url.username && !url.password && !url.hash,\n `${what} requires HTTPS without credentials or a fragment.`,\n );\n return url.href;\n}\n\n/** Split by carrier, so only `embedded-file` carries an archive path to look up. */\ntype ManifestSource =\n | {type: 'remote-non-cacheable' | 'remote-cacheable'; path: null; url: string}\n | {type: 'embedded-file'; path: string; url: string | null}\n | {type: 'embedded-data'; path: null; url: string | null};\n\nfunction readManifestSource(value: unknown, id: string): ManifestSource {\n assert(isObject(value), `Extension ${id} is missing its source.`);\n const {type} = value;\n if (type === 'remote-non-cacheable' || type === 'remote-cacheable') {\n assertKnownMembers(value, ['type', 'url'], `Extension ${id} source`);\n return {type, path: null, url: manifestAddress(value.url, `Extension ${id} source URL`)};\n }\n if (type === 'embedded-file') {\n assertKnownMembers(value, ['type', 'path', 'url'], `Extension ${id} source`);\n const sourcePath = value.path;\n assert(\n typeof sourcePath === 'string' &&\n sourcePath.length <= 256 &&\n embeddedPathPattern.test(sourcePath) &&\n !sourcePath.split('/').some((part) => !part || part === '.' || part === '..'),\n `Extension ${id} has an unsafe embedded path: ${JSON.stringify(sourcePath)}`,\n );\n return {\n type,\n path: sourcePath,\n url:\n value.url === undefined ? null : manifestAddress(value.url, `Extension ${id} source URL`),\n };\n }\n if (type === 'embedded-data') {\n assertKnownMembers(value, ['type', 'url'], `Extension ${id} source`);\n return {\n type,\n path: null,\n url:\n value.url === undefined ? null : manifestAddress(value.url, `Extension ${id} source URL`),\n };\n }\n // Name each retired spelling and what replaces it, so a project written by an older version\n // reports something a reader can act on instead of \"unsupported\".\n assert(\n type !== 'remote',\n `Extension ${id}: a remote source is now remote-cacheable or remote-non-cacheable.`,\n );\n assert(type !== 'cached', `Extension ${id}: a cached source is now embedded-file with a url.`);\n assert(\n type !== 'embedded',\n `Extension ${id}: an embedded source is now embedded-file or embedded-data.`,\n );\n throw new Error(`Extension ${id} has an unsupported source type: ${JSON.stringify(type)}`);\n}\n\ninterface ManifestExtension {\n id: string;\n sha256: string;\n execution: ExtensionExecutionMode;\n source: ManifestSource;\n}\n\ninterface ProjectManifest {\n uri: string | null;\n extensions: ManifestExtension[];\n}\n\n/**\n * Validates only what this inventory reports, without resolving dependencies or granting anything.\n *\n * The manifest is the author's claim about their own project, so it is read as untrusted data: the\n * members are checked, and nothing in it is contacted or executed.\n */\nexport function readProjectManifest(project: unknown): ProjectManifest | null {\n assert(isObject(project), 'SB3 project.json must contain a JSON object.');\n if (!Object.hasOwn(project, projectManifestKey)) return null;\n const manifest = assertKnownMembers(\n project[projectManifestKey],\n ['schemaVersion', 'uri', 'extensions'],\n 'Project manifest',\n );\n assert(manifest.schemaVersion === 1, 'Only project manifest schemaVersion 1 is supported.');\n const uri = manifest.uri === undefined ? null : manifestAddress(manifest.uri, 'A project URI');\n assert(\n Array.isArray(manifest.extensions) && manifest.extensions.length <= manifestExtensionLimit,\n `Project manifest extensions must be an array of at most ${manifestExtensionLimit} entries.`,\n );\n\n const seenIds = new Set<string>();\n const extensions = manifest.extensions.map((entry: unknown): ManifestExtension => {\n const extension = assertKnownMembers(\n entry,\n [\n 'id',\n 'source',\n 'execution',\n 'sha256',\n 'version',\n 'publisher',\n 'capabilities',\n 'dependencies',\n ],\n 'Project manifest extension',\n );\n const {id} = extension;\n assert(\n typeof id === 'string' && extensionIdPattern.test(id) && !seenIds.has(id),\n `Invalid or duplicate manifest extension ID: ${JSON.stringify(id)}`,\n );\n seenIds.add(id);\n assert(\n extension.execution === 'sandboxed' || extension.execution === 'unsandboxed',\n `Extension ${id} requires an explicit sandboxed or unsandboxed execution request.`,\n );\n assert(\n typeof extension.sha256 === 'string' && sha256Pattern.test(extension.sha256),\n `Extension ${id} requires a lowercase SHA-256 pin.`,\n );\n return {\n id,\n sha256: extension.sha256,\n execution: extension.execution,\n source: readManifestSource(extension.source, id),\n };\n });\n return {uri, extensions};\n}\n\ninterface ReadArchiveResult {\n entries: Record<string, Uint8Array>;\n project: UnknownRecord;\n}\n\nfunction parseArchive(contents: Uint8Array): ReadArchiveResult {\n const names = new Set<string>();\n let expandedSize = 0;\n const entries = unzipSync(contents, {\n filter: (entry) => {\n validateArchiveEntryName(entry.name);\n assert(!names.has(entry.name), `Duplicate SB3 archive entry: ${entry.name}`);\n names.add(entry.name);\n expandedSize += entry.originalSize;\n assert(\n names.size <= archiveEntryLimit && expandedSize <= expandedSizeLimit,\n 'SB3 expansion limit exceeded.',\n );\n return true;\n },\n });\n assert(Object.hasOwn(entries, 'project.json'), 'SB3 archive does not contain project.json.');\n let project: unknown;\n try {\n project = JSON.parse(strFromU8(entries['project.json']));\n } catch (error) {\n throw new Error('SB3 project.json is not valid JSON.', {cause: error});\n }\n assert(isObject(project), 'SB3 project.json must contain a JSON object.');\n return {entries, project};\n}\n\nasync function readArchive(filePath: string): Promise<Buffer> {\n assert(path.extname(filePath).toLowerCase() === '.sb3', `Expected an .sb3 file: ${filePath}`);\n const stats = await lstat(filePath);\n assert(stats.isFile() && !stats.isSymbolicLink(), `Expected a regular SB3 file: ${filePath}`);\n assert(stats.size <= archiveSizeLimit, `SB3 exceeds the 64 MiB limit: ${filePath}`);\n return readFile(filePath);\n}\n\nfunction heldBytes(extension: ManifestExtension, archive: ReadArchiveResult): Uint8Array | null {\n if (extension.source.type === 'embedded-file') {\n const entryPath = extension.source.path;\n const entry = archive.entries[entryPath];\n assert(\n entry !== undefined,\n `Extension ${extension.id} names a missing archive entry: ${entryPath}`,\n );\n return entry;\n }\n if (extension.source.type === 'embedded-data') {\n const urls: unknown = archive.project.extensionURLs;\n assert(\n isObject(urls) && typeof urls[extension.id] === 'string',\n `Extension ${extension.id} is missing its embedded data carrier in extensionURLs.`,\n );\n return decodeExtensionDataUrl(urls[extension.id]).source;\n }\n return null;\n}\n\n/** Reads one SB3's manifest digests; `embedded-data` sizes come from the decoded carrier. */\nexport function inspectSb3ExtensionDigests(\n inputPath: string,\n contents: Uint8Array,\n): Sb3ExtensionDigests {\n const archive = parseArchive(contents);\n const manifest = readProjectManifest(archive.project);\n if (!manifest) {\n return {inputPath, uri: null, manifestPresent: false, extensions: []};\n }\n const extensions = manifest.extensions.map((extension): ExtensionDigestEntry => {\n const bytes = heldBytes(extension, archive);\n return {\n id: extension.id,\n sha256: extension.sha256,\n sourceType: extension.source.type,\n size: bytes ? bytes.byteLength : null,\n heldSha256: bytes ? sha256(bytes) : null,\n url: extension.source.url,\n path: extension.source.path,\n execution: extension.execution,\n cacheable: extension.source.type === 'remote-cacheable',\n };\n });\n return {inputPath, uri: manifest.uri, manifestPresent: true, extensions};\n}\n\n/**\n * Builds the list to compare a browser's extension cache against.\n *\n * Whether a digest is shared is decided by how many of the given SB3s name it, and by nothing\n * else: an input that was not given is simply unknown, never absent. The same goes for\n * `cacheable` — it says that some input given here keeps those bytes as `remote-cacheable`, which\n * is the only form a cache may hold, so a digest left over from a project since converted to\n * `remote-non-cacheable` shows up with `cacheable` false.\n */\nexport async function inventoryExtensionDigests(\n inputPaths: string[],\n): Promise<ExtensionDigestInventory> {\n assert(inputPaths.length > 0, 'At least one INPUT.sb3 is required.');\n const resolvedPaths = inputPaths.map((inputPath) => path.resolve(inputPath));\n const seenPaths = new Set<string>();\n for (const resolvedPath of resolvedPaths) {\n assert(!seenPaths.has(resolvedPath), `Duplicate SB3 input: ${resolvedPath}`);\n seenPaths.add(resolvedPath);\n }\n\n const projects: Sb3ExtensionDigests[] = [];\n for (const resolvedPath of resolvedPaths) {\n projects.push(inspectSb3ExtensionDigests(resolvedPath, await readArchive(resolvedPath)));\n }\n\n const usages = new Map<string, ExtensionDigestUsage>();\n for (const project of projects) {\n for (const extension of project.extensions) {\n let usage = usages.get(extension.sha256);\n if (!usage) {\n usage = {\n sha256: extension.sha256,\n ids: [],\n sourceTypes: [],\n cacheable: false,\n size: null,\n projects: [],\n shared: false,\n };\n usages.set(extension.sha256, usage);\n }\n if (!usage.ids.includes(extension.id)) usage.ids.push(extension.id);\n if (!usage.sourceTypes.includes(extension.sourceType)) {\n usage.sourceTypes.push(extension.sourceType);\n }\n usage.cacheable = usage.cacheable || extension.cacheable;\n if (usage.size === null) usage.size = extension.size;\n if (!usage.projects.some((entry) => entry.inputPath === project.inputPath)) {\n usage.projects.push({inputPath: project.inputPath, uri: project.uri});\n }\n }\n }\n\n const digests = [...usages.values()].sort((left, right) => (left.sha256 < right.sha256 ? -1 : 1));\n for (const usage of digests) {\n usage.ids.sort();\n usage.shared = usage.projects.length > 1;\n }\n return {projects, digests};\n}\n\n/** Formats the inventory as the lines the CLI prints, one fact per `key=value` pair. */\nexport function formatExtensionDigestInventory(inventory: ExtensionDigestInventory): string[] {\n const extensionCount = inventory.projects.reduce(\n (total, project) => total + project.extensions.length,\n 0,\n );\n const sharedCount = inventory.digests.filter((usage) => usage.shared).length;\n const lines = [\n `Inventory: ${inventory.projects.length} SB3 inputs; ${extensionCount} manifest extensions; ` +\n `${inventory.digests.length} distinct digests (${sharedCount} shared, ` +\n `${inventory.digests.length - sharedCount} in one project).`,\n ];\n for (const project of inventory.projects) {\n if (!project.manifestPresent) {\n lines.push(`${project.inputPath}: manifest=absent`);\n continue;\n }\n lines.push(\n `${project.inputPath}: uri=${project.uri ?? 'absent'}; ` +\n `extensions=${project.extensions.length}`,\n );\n for (const extension of project.extensions) {\n const details = [\n `sha256=${extension.sha256}`,\n `source=${extension.sourceType}`,\n `size=${extension.size === null ? 'not-held' : extension.size}`,\n `cacheable=${extension.cacheable ? 'yes' : 'no'}`,\n `execution=${extension.execution}`,\n ];\n if (extension.path) details.push(`path=${extension.path}`);\n if (extension.url) details.push(`url=${extension.url}`);\n if (extension.heldSha256 && extension.heldSha256 !== extension.sha256) {\n details.push(`held-sha256=${extension.heldSha256}`);\n }\n lines.push(` ${extension.id}: ${details.join('; ')}`);\n }\n }\n for (const usage of inventory.digests) {\n lines.push(\n `${usage.shared ? 'Shared' : 'Single'}: ${usage.sha256}; ` +\n `projects=${usage.projects.length}; ids=${usage.ids.join(',')}; ` +\n `sources=${usage.sourceTypes.join(',')}; cacheable=${usage.cacheable ? 'yes' : 'no'}; ` +\n `size=${usage.size === null ? 'not-held' : usage.size}`,\n );\n }\n lines.push(\n 'Browser caches are not read: IndexedDB belongs to an origin and a browser profile. ' +\n 'No URI above was contacted, and an unresolved URI never means an absent project.',\n );\n return lines;\n}\n"],"mappings":"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"}
|
package/dist/index.d.ts
CHANGED
|
@@ -7,6 +7,8 @@ export { extensionHeaderId, extensionHeaderMetadata, extensionIntegrity, unsandb
|
|
|
7
7
|
export { compareExtensionApiManifests, defaultExtensionApiManifestSizeLimit, extensionApiManifestEffects, extensionApiManifestFormatVersion, extensionApiManifestFormatVersions, extensionApiManifestIntegrity, extensionApiManifestLocalPath, extensionApiManifestResultTypes, formatExtensionApiCompatibilityChanges, parseExtensionApiManifest, tryParseExtensionApiManifest, validateExtensionApiManifestSourceMetadata, validateManagedExtensionApiManifest, } from './extension-api-manifest';
|
|
8
8
|
export { bundleExtensions, planExtensionBundle, planExtensionUnbundle, unbundleExtensions, } from './extension-bundle-configuration';
|
|
9
9
|
export { planBundledSb3Unbundle, unbundleSb3 } from './extension-bundle-archive';
|
|
10
|
+
export { extensionSourceTypes, formatExtensionDigestInventory, inspectSb3ExtensionDigests, inventoryExtensionDigests, projectManifestKey, readProjectManifest, } from './extension-digest-inventory';
|
|
11
|
+
export type { ExtensionDigestEntry, ExtensionDigestInventory, ExtensionDigestUsage, ExtensionExecutionMode, ExtensionSourceType, Sb3ExtensionDigests, } from './extension-digest-inventory';
|
|
10
12
|
export { buildExtensionBundles, createStaticExtensionBundle, bundleUnsandboxedRequirement, defaultSandboxedNotices, extensionBundleRecoveryMarker, validateExtensionBundleConfigurations, } from './extension-bundle';
|
|
11
13
|
export { buildExtensionBundlesWithModules } from './extension-module-bundle';
|
|
12
14
|
export type { ExtensionModuleBuildReport } from './extension-module-bundle';
|
package/dist/index.js
CHANGED
|
@@ -13,8 +13,9 @@ import { packageName, packageVersion } from "./constants.js";
|
|
|
13
13
|
import { decodeExtensionDataUrl, importSb3 } from "./import.js";
|
|
14
14
|
import { planBundledSb3Unbundle, unbundleSb3 } from "./extension-bundle-archive.js";
|
|
15
15
|
import { bundleExtensions, planExtensionBundle, planExtensionUnbundle, unbundleExtensions } from "./extension-bundle-configuration.js";
|
|
16
|
+
import { extensionSourceTypes, formatExtensionDigestInventory, inspectSb3ExtensionDigests, inventoryExtensionDigests, projectManifestKey, readProjectManifest } from "./extension-digest-inventory.js";
|
|
16
17
|
import { migrateExtensionId, planExtensionIdMigration, validateNewExtensionId } from "./extension-id-migration.js";
|
|
17
18
|
import { defaultKamishibaiManifestUrl, kamishibaiReplacementIds, replaceSb3Extensions } from "./extension-sb3-replacement.js";
|
|
18
19
|
import { defaultExtensionArtifactSizeLimit, extensionStatus, syncExtensions, updateExtensions } from "./extension-sync.js";
|
|
19
20
|
import { assertSb3ReleaseSnapshotMetadata, computeReleaseSourceIdentity, createSb3ReleaseSnapshot, createSb3ReleaseSnapshotMetadata, freezeSb3ReleaseSnapshot, readSb3ReleaseSnapshotMetadata, recordPublishedSb3ReleaseSnapshot, verifySb3ReleaseSnapshot, writeSb3ReleaseCandidate } from "./release-snapshot.js";
|
|
20
|
-
export { applyProjectAssetAdditions, assert, assertSb3ReleaseSnapshotMetadata, buildExtensionBundles, buildExtensionBundlesWithModules, buildSb3, bundleExtensions, bundleUnsandboxedRequirement, cleanUpTurboWarpBlocks, compareDirectories, compareExtensionApiManifests, computeReleaseSourceIdentity, createDeterministicSb3, createSb3ReleaseSnapshot, createSb3ReleaseSnapshotMetadata, createStaticExtensionBundle, decodeExtensionDataUrl, defaultExtensionApiManifestSizeLimit, defaultExtensionArtifactSizeLimit, defaultKamishibaiManifestUrl, defaultSandboxedNotices, extensionApiManifestEffects, extensionApiManifestFormatVersion, extensionApiManifestFormatVersions, extensionApiManifestIntegrity, extensionApiManifestLocalPath, extensionApiManifestResultTypes, extensionBundleRecoveryMarker, extensionHeaderId, extensionHeaderMetadata, extensionIntegrity, extensionStatus, fixedZipTimestamp, formatExtensionApiCompatibilityChanges, freezeSb3ReleaseSnapshot, importSb3, inspectGitOutputState, kamishibaiReplacementIds, migrateExtensionId, packageName, packageVersion, parseExtensionApiManifest, planBundledSb3Unbundle, planExtensionBundle, planExtensionIdMigration, planExtensionUnbundle, projectAssetAdditionsFormatVersion, readSb3ReleaseSnapshotMetadata, recordPublishedSb3ReleaseSnapshot, replaceSb3Extensions, sourceFormatVersion, syncExtensions, tryParseExtensionApiManifest, turboWarpCleanUpLayout, unbundleExtensions, unbundleSb3, unsandboxedRequirement, unsandboxedRequirements, updateExtensions, validateArchiveEntryName, validateExtensionApiManifestSourceMetadata, validateExtensionBundleConfigurations, validateExtensionSourceMetadata, validateManagedExtensionApiManifest, validateManagedExtensionContents, validateNewExtensionId, validateOutputDirectoryPath, validateSb3Source, verifySb3ReleaseSnapshot, writeSb3ReleaseCandidate };
|
|
21
|
+
export { applyProjectAssetAdditions, assert, assertSb3ReleaseSnapshotMetadata, buildExtensionBundles, buildExtensionBundlesWithModules, buildSb3, bundleExtensions, bundleUnsandboxedRequirement, cleanUpTurboWarpBlocks, compareDirectories, compareExtensionApiManifests, computeReleaseSourceIdentity, createDeterministicSb3, createSb3ReleaseSnapshot, createSb3ReleaseSnapshotMetadata, createStaticExtensionBundle, decodeExtensionDataUrl, defaultExtensionApiManifestSizeLimit, defaultExtensionArtifactSizeLimit, defaultKamishibaiManifestUrl, defaultSandboxedNotices, extensionApiManifestEffects, extensionApiManifestFormatVersion, extensionApiManifestFormatVersions, extensionApiManifestIntegrity, extensionApiManifestLocalPath, extensionApiManifestResultTypes, extensionBundleRecoveryMarker, extensionHeaderId, extensionHeaderMetadata, extensionIntegrity, extensionSourceTypes, extensionStatus, fixedZipTimestamp, formatExtensionApiCompatibilityChanges, formatExtensionDigestInventory, freezeSb3ReleaseSnapshot, importSb3, inspectGitOutputState, inspectSb3ExtensionDigests, inventoryExtensionDigests, kamishibaiReplacementIds, migrateExtensionId, packageName, packageVersion, parseExtensionApiManifest, planBundledSb3Unbundle, planExtensionBundle, planExtensionIdMigration, planExtensionUnbundle, projectAssetAdditionsFormatVersion, projectManifestKey, readProjectManifest, readSb3ReleaseSnapshotMetadata, recordPublishedSb3ReleaseSnapshot, replaceSb3Extensions, sourceFormatVersion, syncExtensions, tryParseExtensionApiManifest, turboWarpCleanUpLayout, unbundleExtensions, unbundleSb3, unsandboxedRequirement, unsandboxedRequirements, updateExtensions, validateArchiveEntryName, validateExtensionApiManifestSourceMetadata, validateExtensionBundleConfigurations, validateExtensionSourceMetadata, validateManagedExtensionApiManifest, validateManagedExtensionContents, validateNewExtensionId, validateOutputDirectoryPath, validateSb3Source, verifySb3ReleaseSnapshot, writeSb3ReleaseCandidate };
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
# Extension digests and retention forms
|
|
2
|
+
|
|
3
|
+
```bash
|
|
4
|
+
sb3-toolchain extensions digests project.sb3 [another.sb3 ...] [--json]
|
|
5
|
+
```
|
|
6
|
+
|
|
7
|
+
Reads what each SB3 says about itself and reports, for every extension its manifest names:
|
|
8
|
+
|
|
9
|
+
- the extension ID,
|
|
10
|
+
- the pinned `sha256`,
|
|
11
|
+
- which of the four retention forms the author chose — `remote-non-cacheable`, `remote-cacheable`,
|
|
12
|
+
`embedded-file`, or `embedded-data`,
|
|
13
|
+
- the number of bytes the archive actually holds for it,
|
|
14
|
+
- the digest of those held bytes, when it differs from the pinned one,
|
|
15
|
+
- the recorded URL and, for `embedded-file`, the archive entry path,
|
|
16
|
+
- the requested execution mode.
|
|
17
|
+
|
|
18
|
+
It also reports the project's own `uri`, which is the name a browser's caches and the opener's
|
|
19
|
+
recorded decisions are filed under, and, given more than one SB3, which digests several of those
|
|
20
|
+
projects name and which belong to a single project.
|
|
21
|
+
|
|
22
|
+
## What this command cannot do
|
|
23
|
+
|
|
24
|
+
**It does not read browser storage.** An extension cache lives in IndexedDB, which belongs to an
|
|
25
|
+
origin _and_ to a browser profile, so no command line can reach the cache the person running it
|
|
26
|
+
actually has — driving a fresh automated browser would only show a profile nobody uses. Only the
|
|
27
|
+
browser knows which projects it has cached, so listing and deleting belong to the screen in
|
|
28
|
+
[`kubohiroya/turbowarp-title-menu#23`](https://github.com/kubohiroya/turbowarp-title-menu/issues/23).
|
|
29
|
+
This command produces the list to compare that state against.
|
|
30
|
+
|
|
31
|
+
**It never decides anything by reachability.** A project URI returns nothing until its author
|
|
32
|
+
publishes there, so a work saved but never published and a published work whose address rotted look
|
|
33
|
+
exactly alike. No URL in an SB3 is contacted, and nothing is ever treated as absent because a
|
|
34
|
+
request failed. An input that was not given is unknown, not absent.
|
|
35
|
+
|
|
36
|
+
## What the report is for
|
|
37
|
+
|
|
38
|
+
1. Deciding what belongs in the shared bucket: a digest several projects name is a copy worth
|
|
39
|
+
keeping once rather than per project.
|
|
40
|
+
2. Feeding the title-menu screen's "remove caches no project still names" mode with the set of
|
|
41
|
+
digests the projects on hand actually name.
|
|
42
|
+
3. Finding entries left behind after a project was converted from `remote-cacheable` to
|
|
43
|
+
`remote-non-cacheable`. Only `remote-cacheable` can ever leave a copy in a browser, so a digest
|
|
44
|
+
whose `cacheable` is false across every input is one no project still asks to be retained. An
|
|
45
|
+
author who decided those bytes should not be kept has had that decision undone if a browser
|
|
46
|
+
keeps them anyway.
|
|
47
|
+
|
|
48
|
+
## Reading the output
|
|
49
|
+
|
|
50
|
+
The text report prints one `key=value; ...` line per extension, then one line per distinct digest
|
|
51
|
+
labelled `Shared` (named by more than one input) or `Single`. `size=not-held` means the SB3 carries
|
|
52
|
+
only a reference, so the bytes are not there to measure — not that they are missing. `--json` emits
|
|
53
|
+
the same inventory as JSON, with `projects` in input order and `digests` sorted by digest.
|
|
54
|
+
|
|
55
|
+
## JavaScript API
|
|
56
|
+
|
|
57
|
+
```js
|
|
58
|
+
import {inventoryExtensionDigests} from '@kubohiroya/sb3-toolchain';
|
|
59
|
+
|
|
60
|
+
const inventory = await inventoryExtensionDigests(['one.sb3', 'two.sb3']);
|
|
61
|
+
|
|
62
|
+
for (const usage of inventory.digests) {
|
|
63
|
+
if (!usage.cacheable) {
|
|
64
|
+
// No input keeps these bytes in the one form a browser may retain.
|
|
65
|
+
console.log(
|
|
66
|
+
usage.sha256,
|
|
67
|
+
usage.ids,
|
|
68
|
+
usage.projects.map((project) => project.uri),
|
|
69
|
+
);
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
`inspectSb3ExtensionDigests(inputPath, contents)` reports one already-read archive, and
|
|
75
|
+
`readProjectManifest(project)` validates just the `turboWarpPlus` member of a parsed `project.json`,
|
|
76
|
+
returning `null` when a project carries no manifest. A manifest written before the four names
|
|
77
|
+
existed is refused by naming what replaces each retired spelling, rather than translated into a
|
|
78
|
+
choice its author never made.
|
|
79
|
+
|
|
80
|
+
## Limits
|
|
81
|
+
|
|
82
|
+
Inputs are accepted up to 64 MiB compressed, 256 MiB expanded, and 4096 ZIP entries, with at most
|
|
83
|
+
64 extensions per manifest. Duplicate inputs, symbolic links, and non-`.sb3` paths are refused.
|
package/docs/index.html
CHANGED
|
@@ -69,7 +69,7 @@
|
|
|
69
69
|
<body>
|
|
70
70
|
<header>
|
|
71
71
|
<h1>SB3 Toolchain</h1>
|
|
72
|
-
<p><code>@kubohiroya/sb3-toolchain@0.
|
|
72
|
+
<p><code>@kubohiroya/sb3-toolchain@0.21.0</code></p>
|
|
73
73
|
<nav aria-label="Documentation">
|
|
74
74
|
<a href="#scope">責務</a><a href="#usage">使い方</a><a href="#api">API</a
|
|
75
75
|
><a href="#schemas">Schema</a><a href="#guides">関連文書</a>
|
|
@@ -90,7 +90,7 @@
|
|
|
90
90
|
<section id="usage">
|
|
91
91
|
<h2>使い方</h2>
|
|
92
92
|
<p>公開済みの完全固定versionを使います。</p>
|
|
93
|
-
<pre><code>npm install --save-exact @kubohiroya/sb3-toolchain@0.
|
|
93
|
+
<pre><code>npm install --save-exact @kubohiroya/sb3-toolchain@0.21.0</code></pre>
|
|
94
94
|
<pre><code>sb3-toolchain import tmp/project.sb3 --output app
|
|
95
95
|
sb3-toolchain check app
|
|
96
96
|
sb3-toolchain build app --output dist/project.sb3</code></pre>
|
|
@@ -121,6 +121,12 @@ sb3-toolchain build app --output dist/project.sb3</code></pre>
|
|
|
121
121
|
<th><code>bundleExtensions</code></th>
|
|
122
122
|
<td>管理対象の埋込拡張を一つの権限単位へ静的bundleします。</td>
|
|
123
123
|
</tr>
|
|
124
|
+
<tr>
|
|
125
|
+
<th><code>inventoryExtensionDigests</code></th>
|
|
126
|
+
<td>
|
|
127
|
+
SB3が述べる各拡張のdigest・保持形式・サイズと作品のURIを読み、複数の作品が共有するdigestを示します。取得もブラウザー保存状態の読み取りも行いません。
|
|
128
|
+
</td>
|
|
129
|
+
</tr>
|
|
124
130
|
</tbody>
|
|
125
131
|
</table>
|
|
126
132
|
<p>
|
|
@@ -143,9 +149,11 @@ sb3-toolchain build app --output dist/project.sb3</code></pre>
|
|
|
143
149
|
<ul>
|
|
144
150
|
<li><a href="extension-api-compatibility.md">extension-api-compatibility.md</a></li>
|
|
145
151
|
<li><a href="extension-bundles.md">extension-bundles.md</a></li>
|
|
152
|
+
<li><a href="extension-digests.md">extension-digests.md</a></li>
|
|
146
153
|
<li><a href="extension-id-migration.md">extension-id-migration.md</a></li>
|
|
147
154
|
<li><a href="ja/extension-api-compatibility.md">ja/extension-api-compatibility.md</a></li>
|
|
148
155
|
<li><a href="ja/extension-bundles.md">ja/extension-bundles.md</a></li>
|
|
156
|
+
<li><a href="ja/extension-digests.md">ja/extension-digests.md</a></li>
|
|
149
157
|
<li><a href="ja/extension-id-migration.md">ja/extension-id-migration.md</a></li>
|
|
150
158
|
<li><a href="ja/project-asset-additions.md">ja/project-asset-additions.md</a></li>
|
|
151
159
|
<li><a href="ja/source-format-v1.md">ja/source-format-v1.md</a></li>
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
# 機能拡張のdigestと保持形式を出す
|
|
2
|
+
|
|
3
|
+
```bash
|
|
4
|
+
sb3-toolchain extensions digests project.sb3 [another.sb3 ...] [--json]
|
|
5
|
+
```
|
|
6
|
+
|
|
7
|
+
SB3が自分自身について述べていることを読み、マニフェストが挙げる各機能拡張について次を出力します。
|
|
8
|
+
|
|
9
|
+
- 機能拡張のID
|
|
10
|
+
- 固定された`sha256`
|
|
11
|
+
- 作者が選んだ4つの保持形式のどれか(`remote-non-cacheable` / `remote-cacheable` /
|
|
12
|
+
`embedded-file` / `embedded-data`)
|
|
13
|
+
- そのSB3が実際に保持しているバイト数
|
|
14
|
+
- 保持しているバイト列のdigest(固定値と異なる場合のみ表示)
|
|
15
|
+
- 記録されたURL、`embedded-file`の場合はアーカイブ内のパス
|
|
16
|
+
- 要求された実行モード
|
|
17
|
+
|
|
18
|
+
あわせて作品自身の`uri`を出力します。これはブラウザーのキャッシュと、開いた人の記録済みの判断が
|
|
19
|
+
ひも付けられる名前です。SB3を複数与えた場合は、どのdigestが複数の作品から名指され、どれが1作品だけの
|
|
20
|
+
ものかも出力します。
|
|
21
|
+
|
|
22
|
+
## このコマンドができないこと
|
|
23
|
+
|
|
24
|
+
**ブラウザーの保存状態は読みません。** 機能拡張のキャッシュはIndexedDBにあり、これはオリジンに属すると
|
|
25
|
+
同時に**ブラウザーのプロファイル**にも属します。コマンドラインからは、実行する人が実際に持っている
|
|
26
|
+
キャッシュには原理的に届きません。自動化されたブラウザーを新たに起動しても、誰も使っていない
|
|
27
|
+
プロファイルが見えるだけです。どの作品がキャッシュされているかを知っているのはブラウザーだけなので、
|
|
28
|
+
一覧と削除は[`kubohiroya/turbowarp-title-menu#23`](https://github.com/kubohiroya/turbowarp-title-menu/issues/23)
|
|
29
|
+
の画面が担います。このコマンドは、その状態と照合するための一覧を作る側です。
|
|
30
|
+
|
|
31
|
+
**到達性で何も判断しません。** 作品のURIは作者がそこに公開するまで何も返しません。保存したが未公開の
|
|
32
|
+
作品と、公開済みだが住所が腐った作品は見分けがつきません。SB3の中のURLには一切アクセスせず、
|
|
33
|
+
リクエストが失敗したことを根拠に何かを「無い」と扱うことはありません。与えなかった入力は「不明」で
|
|
34
|
+
あって「無い」ではありません。
|
|
35
|
+
|
|
36
|
+
## 何に使うか
|
|
37
|
+
|
|
38
|
+
1. 共通バケットに何を置くべきかの判断材料。複数の作品が名指すdigestは、作品ごとに持つのではなく
|
|
39
|
+
一度だけ持つ価値のあるバイト列です。
|
|
40
|
+
2. title-menuの画面の「どの作品からも名指されなくなったキャッシュを消す」モードへの入力。手元の
|
|
41
|
+
作品群が実際に名指すdigestの集合を渡します。
|
|
42
|
+
3. 作品を`remote-cacheable`から`remote-non-cacheable`に変換したあと、取り残された古いエントリーを
|
|
43
|
+
見つける材料。キャッシュを持ちうるのは`remote-cacheable`だけなので、すべての入力で`cacheable`が
|
|
44
|
+
falseのdigestは、もうどの作品も保持を求めていないバイト列です。作者が「残すな」と決めたのに
|
|
45
|
+
ブラウザーに残り続けるなら、その判断は反故になっています。
|
|
46
|
+
|
|
47
|
+
## 出力の読み方
|
|
48
|
+
|
|
49
|
+
テキスト出力は機能拡張ごとに`key=value; ...`の1行を、続いてdistinctなdigestごとに1行を出します。
|
|
50
|
+
後者は複数の入力から名指されていれば`Shared`、1つだけなら`Single`と表示します。`size=not-held`は
|
|
51
|
+
そのSB3が参照だけを持っていて、測るべきバイト列がそこに無いという意味で、失われているのではありません。
|
|
52
|
+
`--json`は同じ内容をJSONで出力します。`projects`は入力順、`digests`はdigest順です。
|
|
53
|
+
|
|
54
|
+
## JavaScript API
|
|
55
|
+
|
|
56
|
+
```js
|
|
57
|
+
import {inventoryExtensionDigests} from '@kubohiroya/sb3-toolchain';
|
|
58
|
+
|
|
59
|
+
const inventory = await inventoryExtensionDigests(['one.sb3', 'two.sb3']);
|
|
60
|
+
|
|
61
|
+
for (const usage of inventory.digests) {
|
|
62
|
+
if (!usage.cacheable) {
|
|
63
|
+
// どの入力も、ブラウザーが保持しうる唯一の形式では持っていないバイト列。
|
|
64
|
+
console.log(
|
|
65
|
+
usage.sha256,
|
|
66
|
+
usage.ids,
|
|
67
|
+
usage.projects.map((project) => project.uri),
|
|
68
|
+
);
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
`inspectSb3ExtensionDigests(inputPath, contents)`は既に読み込んだアーカイブ1件を対象にします。
|
|
74
|
+
`readProjectManifest(project)`は、解析済み`project.json`の`turboWarpPlus`メンバーだけを検証し、
|
|
75
|
+
マニフェストを持たない作品では`null`を返します。4つの名前が存在する前に書かれたマニフェストは、
|
|
76
|
+
作者がしていない選択を勝手に補う代わりに、廃止された綴りごとに何がそれを置き換えるかを示して拒否します。
|
|
77
|
+
|
|
78
|
+
## 制限
|
|
79
|
+
|
|
80
|
+
入力は圧縮サイズ64 MiB、展開サイズ256 MiB、ZIPエントリー数4096まで、マニフェスト1件あたりの機能拡張は
|
|
81
|
+
64件までです。入力の重複、シンボリックリンク、`.sb3`以外のパスは拒否します。
|
package/docs/ja/workflows.md
CHANGED
|
@@ -2,6 +2,8 @@
|
|
|
2
2
|
|
|
3
3
|
Kamishibai作品SB3に埋め込まれた実装を一括更新する場合は、[SB3の機能拡張更新](sb3-extension-replacement.md)を参照してください。
|
|
4
4
|
|
|
5
|
+
ブラウザーの機能拡張キャッシュと照合する一覧を作る場合は、[機能拡張のdigestと保持形式](extension-digests.md)を参照してください。
|
|
6
|
+
|
|
5
7
|
[English](../workflows.md)
|
|
6
8
|
|
|
7
9
|
この文書では、Scratch 3またはTurboWarpのSB3をGit内の展開ソースとして管理し、検証済みSB3を再ビルドする
|
package/docs/workflows.md
CHANGED
|
@@ -1,5 +1,8 @@
|
|
|
1
1
|
# SB3 source-management workflows
|
|
2
2
|
|
|
3
|
+
To build the list to compare a browser's extension cache against, see
|
|
4
|
+
[extension digests and retention forms](extension-digests.md).
|
|
5
|
+
|
|
3
6
|
[日本語版](ja/workflows.md)
|
|
4
7
|
|
|
5
8
|
This document describes the common workflow for managing a Scratch 3 or TurboWarp SB3 as expanded
|
package/package.json
CHANGED