@chrona-city/ugc-kit 1.5.9 → 1.5.11
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/README.md +95 -5
- package/contracts/ugc/public-runtime/v1/README.md +82 -5
- package/contracts/ugc/public-runtime/v1/archive.mjs +4 -3
- package/contracts/ugc/public-runtime/v1/manifest.mjs +56 -14
- package/contracts/ugc/public-runtime/v1/runtime-manifest.schema.json +186 -39
- package/contracts/ugc/public-runtime/v1/static-room-runtime.test.mjs +225 -0
- package/contracts/ugc/public-runtime/v1/target-compatibility.test.mjs +98 -0
- package/docs/harness-onboarding.md +55 -12
- package/docs/npm-creator.md +95 -12
- package/docs/runtime-download.md +87 -2
- package/lib/creator-cli.mjs +6 -4
- package/lib/creator-platform.mjs +2 -1
- package/lib/creator-toolchain-compat.mjs +9 -0
- package/lib/host-ipc/distribution-static-room-semantic-contract/contracts/ugc/public-runtime/v1/manifest.mjs +209 -0
- package/lib/host-ipc/distribution-static-room-semantic-contract/contracts/ugc/public-runtime/v1/runtime-manifest.schema.json +898 -0
- package/lib/host-ipc/distribution-static-room-semantic-contract/contracts/ugc/registry/v1/conformance/js/capability-resolver.mjs +191 -0
- package/lib/host-ipc/host-ipc.schema.json +18 -27
- package/lib/host-ipc/runtime-contract.mjs +7 -3
- package/lib/host-ipc/source-lock.json +16 -4
- package/lib/local-development.mjs +5 -2
- package/lib/runtime-host-client.mjs +11 -4
- package/lib/runtime-host.mjs +12 -3
- package/lib/runtime-install.mjs +12 -3
- package/node_modules/@esbuild/darwin-x64/README.md +3 -0
- package/node_modules/@esbuild/darwin-x64/bin/esbuild +0 -0
- package/node_modules/@esbuild/darwin-x64/package.json +20 -0
- package/node_modules/@esbuild/linux-x64/README.md +3 -0
- package/node_modules/@esbuild/linux-x64/bin/esbuild +0 -0
- package/node_modules/@esbuild/linux-x64/package.json +20 -0
- package/package.json +1 -1
- package/public-runtime.snapshot.lock.json +13 -5
- package/runtime-catalog.json +16 -16
- /package/lib/host-ipc/{distribution-document-tool-package-contract → distribution-static-room-semantic-contract}/contracts/ugc/creator-source/v1/tool-package.schema.json +0 -0
package/docs/runtime-download.md
CHANGED
|
@@ -48,6 +48,91 @@ finalization or bypass the final version/source/archive checks. Release tooling,
|
|
|
48
48
|
portable integrity, target installation and ordinary gameplay remain separate
|
|
49
49
|
verification stages; an engineering source/package fixture is not an issued Kit.
|
|
50
50
|
|
|
51
|
+
## Release-only WorldScene and Document catalog composition
|
|
52
|
+
|
|
53
|
+
The catalog prepare CLI accepts its original `producerFile`,
|
|
54
|
+
`clientsDeliveryFile`, `runtimeOrigin` and `outputDirectory` input. A Document
|
|
55
|
+
release may also supply `legacy: {producerFile, clientsDeliveryFile}` for the
|
|
56
|
+
existing WorldScene1.0 content family. Each pair goes through the original
|
|
57
|
+
Producer/delivery/manifest/target checks before the catalog is combined. Both
|
|
58
|
+
must bind the same release source, version, environment and complete toolchain;
|
|
59
|
+
the additional delivery is a normal Producer delivery, not a borrowed Document
|
|
60
|
+
companion or payload-reuse proof. No snapshot or content identity is converted.
|
|
61
|
+
The shared release binding describes the two internal Kit packages, not a
|
|
62
|
+
requirement for historical projects to adopt a new identity. Every historical
|
|
63
|
+
content tuple still needs genuine compatibility and execution evidence; a new
|
|
64
|
+
reference built by the current Kit cannot stand in for that historical input.
|
|
65
|
+
|
|
66
|
+
The release package and the content under test have separate identities. The
|
|
67
|
+
Producer's package, metadata, evidence, source and toolchain bind the new release
|
|
68
|
+
exactly. A retained content input keeps its original `expected` tuple and pinned
|
|
69
|
+
snapshot; when it differs from the carrier, the constructor reenters the existing
|
|
70
|
+
snapshot Reader rather than changing its tool fields. Each target report's `tool`
|
|
71
|
+
must equal that actual content's `expected.tool`, not the carrier version. The two
|
|
72
|
+
content families may therefore have different tool identities while sharing the
|
|
73
|
+
same release package/toolchain/source. This is not a version-range waiver: the
|
|
74
|
+
Runtime must declare and verify the exact content tuple, and the installed
|
|
75
|
+
package, execution target, original reports and cleanup remain independently
|
|
76
|
+
checked. A successful Producer or catalog check is not proof of historical Host
|
|
77
|
+
execution or of an unobserved project's compatibility.
|
|
78
|
+
|
|
79
|
+
The pairing keeps the Document `producer`, `clients` and `targets` unchanged,
|
|
80
|
+
and pins the WorldScene pair under `legacy: {producer, clients, targets}`.
|
|
81
|
+
Final verification reproduces both catalogs, checks the entire selected catalog,
|
|
82
|
+
and returns `legacyTargets` alongside the original `targets`. Catalog CAS and
|
|
83
|
+
source checks apply to both Producers. Removing either pair, changing its inputs
|
|
84
|
+
or manually adding a catalog entry cannot produce a matching final pairing.
|
|
85
|
+
|
|
86
|
+
Portable export/import transports the additional Producer, package, metadata,
|
|
87
|
+
evidence, content, complete snapshot, optional source lock and both target
|
|
88
|
+
manifests/archives/reports as closed `legacy-*` roles. Original logical JSON and
|
|
89
|
+
pins remain byte-identical, with no original-host fallback. The Document
|
|
90
|
+
companion proof and its existing roles are not extended to certify WorldScene.
|
|
91
|
+
This tooling support alone does not supply a playable static Room Runtime: its
|
|
92
|
+
trusted source contract, installed inspection, IPC, actual execution and public
|
|
93
|
+
immutable download must be verified separately before a release is recommended.
|
|
94
|
+
|
|
95
|
+
## Local selection failures
|
|
96
|
+
|
|
97
|
+
`dev` and `test` read the trusted catalog bundled with the CLI actually invoked,
|
|
98
|
+
including the executable saved in an existing MCP registration. Installing a new
|
|
99
|
+
package does not switch an already running MCP connection. The state directory is
|
|
100
|
+
a verified download/installation cache, not a search path for arbitrary runtimes.
|
|
101
|
+
|
|
102
|
+
The issued city 1.5.9 catalog declares **Node 22.16.0 exactly** for its Linux arm64
|
|
103
|
+
and macOS arm64 runtimes. It does not supply a Linux x64 runtime. In WSL, the
|
|
104
|
+
Linux process architecture is the target, not the Windows host. Node 24.1.0 is
|
|
105
|
+
outside these declared targets; changing only Node still cannot supply a missing
|
|
106
|
+
x64 runtime. These are facts about this issued catalog, not a new compatibility
|
|
107
|
+
rule or a promise about future releases. The pinned manifest `targets` remain
|
|
108
|
+
authoritative.
|
|
109
|
+
|
|
110
|
+
For a no-rebuild local path, use an already available supported arm64 environment,
|
|
111
|
+
its existing verified Kit installation and its Node 22.16.0 executable to run the
|
|
112
|
+
same snapshot through `test`. Call that Node executable and Kit binary explicitly:
|
|
113
|
+
a saved wrapper or MCP entry may still invoke a different Node even after a shell
|
|
114
|
+
version switch. No source reupload or identity/hash change is required. Passing
|
|
115
|
+
the target check still leaves the snapshot's full content tuple to be checked;
|
|
116
|
+
without that tuple, content compatibility remains unknown. This is not a command
|
|
117
|
+
to install Node, alter a user's registration or switch their environment.
|
|
118
|
+
|
|
119
|
+
- `RUNTIME_TARGET_UNSUPPORTED`: no catalog runtime supports the current OS,
|
|
120
|
+
architecture and Node version. Check `node --version` and the pinned manifest
|
|
121
|
+
targets. CLI installation support is not a promise that every Runtime supports
|
|
122
|
+
every newer Node version.
|
|
123
|
+
- `RUNTIME_CONTENT_INCOMPATIBLE`: a target is supported, but no declared row
|
|
124
|
+
matches the snapshot's builder, tool and contracts. Check the selected CLI and
|
|
125
|
+
actual snapshot; do not rewrite its identity, force a runtime ID or reupload to
|
|
126
|
+
bypass the refusal. A version difference alone does not establish semantic
|
|
127
|
+
incompatibility or authorize adding a compatibility row.
|
|
128
|
+
|
|
129
|
+
Both are local selection failures before creator execution, not cloud candidate
|
|
130
|
+
check results. An unknown error, unavailable/corrupt manifest or cancellation
|
|
131
|
+
retains its original failure; no automatic retry or alternate source is selected.
|
|
132
|
+
Existing platform/session Origins are independent of Runtime transport. Preserve
|
|
133
|
+
old registrations and unresolved requests; `--replace-from` below is not an
|
|
134
|
+
automatic cross-Origin migration or permission to edit a saved session.
|
|
135
|
+
|
|
51
136
|
## Explicit local distribution (same pinned runtime bytes)
|
|
52
137
|
|
|
53
138
|
Runtime distribution and the creator API are separate. `--platform` never chooses a CDN.
|
|
@@ -103,7 +188,7 @@ The caller supplies a canonical, private cache directory outside creator project
|
|
|
103
188
|
|
|
104
189
|
## Verified installation
|
|
105
190
|
|
|
106
|
-
|
|
191
|
+
The selected installed package's `/runtime-install` export provides `installPinnedRuntime`, `inspectInstalledRuntime` and `verifyPublicRuntimeSnapshot`. Read its package name from actual installed `package.json`; do not hardcode a legacy scope or change a historical project's identity. The authoritative distribution contract is mirrored verbatim from Services in `contracts/ugc/public-runtime/v1`, bound by `public-runtime.snapshot.lock.json`; no second archive schema is maintained here. This separate installer snapshot does not change the content compiler's snapshot identity.
|
|
107
192
|
|
|
108
193
|
Trusted platform code calls `installPinnedRuntime({cacheDirectory, installationsDirectory, lock, trustedLock, expected, offline?, signal?})`. `lock` is the project selection; `trustedLock` must come from an independently platform-managed catalog, never the same creator-controlled input used as both arguments. Exact supported targets and content toolchains come from the fixed release catalog and verified runtime manifests, not historical examples in this guide. An engineering candidate may still await its matching runtime catalog and is not thereby playable. Older installed archives retain their original catalogs; a matching version label alone is insufficient. The export is an installation primitive for the platform CLI, not a creator permission to add code URLs. Source entitlement, backend runtime installation and formal approval are separate.
|
|
109
194
|
|
|
@@ -153,7 +238,7 @@ their separate formal consumers.
|
|
|
153
238
|
|
|
154
239
|
## Installed host management
|
|
155
240
|
|
|
156
|
-
|
|
241
|
+
The same installed package's `/runtime-host` export provides `openInstalledRuntimeHost({installationDirectory,lock,trustedLock,content,signal?,onStatus?})`. This platform-facing operation **executes the selected trusted native host**, unlike installation. Never pass a creator-controlled catalog or executable as its trusted selection. Only the exact catalog release and its supported content identities may execute. The Clients-owned IPC validator and Schema are mirrored without changes under `lib/host-ipc`, with their source commit and hashes; the distribution contract above remains the only manifest/archive authority.
|
|
157
242
|
|
|
158
243
|
`content` contains the canonical absolute `snapshotRoot`, raw `snapshotManifestSha256` and complete original `expected` LocalContentSnapshot identity. The original snapshot's builder/tool version is not replaced by the calling CLI version. Before spawning, management rechecks the entire installed release, actual platform, content compatibility and request shape. The child must still verify all snapshot files, policies and sandbox eligibility; an IPC-valid request is not a content approval.
|
|
159
244
|
|
package/lib/creator-cli.mjs
CHANGED
|
@@ -109,7 +109,7 @@ const messages = {
|
|
|
109
109
|
UPGRADE_BUSY: 'Another upgrade or recovery is active. Do not remove its transaction.',
|
|
110
110
|
UPGRADE_RECOVERY_REQUIRED: 'An unfinished upgrade exists. Stop editing, inspect its owner and use explicit recovery after the owner exits.',
|
|
111
111
|
UPGRADE_RECOVERY_CONFLICT: 'Recovery conflicts with the committed source or current files. Preserve the transaction for operator inspection.',
|
|
112
|
-
CREATOR_SESSION_ORIGIN_MISMATCH: 'The saved session
|
|
112
|
+
CREATOR_SESSION_ORIGIN_MISMATCH: 'The saved session belongs to another platform. Preserve it and inspect auth-status for its Origin. Authorize the intended platform explicitly before further writes; installing or upgrading a Kit does not migrate authorization.',
|
|
113
113
|
CREATOR_SESSION_SCOPE_REQUIRED: 'Uploading requires source:read, submissions:write and projects:read for live platform preflight. Preserve this session and explicitly start a new authorization in a separate private session directory with these scopes for the selected project; approve it in the browser and exchange it before retrying. No permission was added or revoked.',
|
|
114
114
|
CREATOR_SESSION_PROJECT_MISMATCH: 'This authorization is restricted to another project. Select its authorized project or explicitly create a new authorization for the intended project; do not edit the saved scope or project binding.',
|
|
115
115
|
CREATOR_SESSION_RENEWAL_REQUIRED: 'The existing authorization is expired, revoked or uncertain. Preserve it and explicitly configure a new authorization session.',
|
|
@@ -132,7 +132,7 @@ const messages = {
|
|
|
132
132
|
INSTALL_RELEASE_CHANGED: 'The official current release and immutable metadata differ. No connection was written; retry after the release is consistent.',
|
|
133
133
|
INVALID_HARNESS_CONFIG: 'The selected Harness configuration is not a supported regular file.',
|
|
134
134
|
HARNESS_CONFIG_BUSY: 'Another initialization owns this configuration. Retry after it finishes.',
|
|
135
|
-
HARNESS_CONFIG_CONFLICT: 'The existing
|
|
135
|
+
HARNESS_CONFIG_CONFLICT: 'The existing AI registration was preserved. Inspect its executable, workspace, platform and session. Use --replace-from only for the same binding; a different platform requires an explicit registration and its own authorization, not an edited session.',
|
|
136
136
|
HARNESS_CONFIG_CHANGED: 'The configuration changed during initialization. Inspect it before retrying.',
|
|
137
137
|
RUNTIME_NOT_AVAILABLE: 'Isolated tests and dev require a compatible public runtime. No creator code was executed.',
|
|
138
138
|
INVALID_RUNTIME_SOURCE: 'Use the packaged catalog or an explicitly selected literal loopback runtime origin with --runtime-source local --runtime-origin ORIGIN --allow-local-http true. Upload origins and project catalogs cannot supply runtime trust.',
|
|
@@ -185,6 +185,8 @@ for (const code of ['INVALID_INSTALL_RELEASE', 'INSTALL_DOWNLOAD_FAILED', 'INSTA
|
|
|
185
185
|
'INSTALL_INVENTORY_INVALID', 'INSTALL_PLATFORM_UNSUPPORTED', 'INSTALL_NODE_UNSUPPORTED', 'INSTALL_PREREQUISITE_MISSING',
|
|
186
186
|
'INSTALL_CALLER_MISMATCH', 'INSTALL_BUSY', 'INSTALL_CONFLICT', 'INSTALL_NPM_FAILED']) messages[code] = code;
|
|
187
187
|
Object.assign(messages, {
|
|
188
|
+
RUNTIME_TARGET_UNSUPPORTED: 'The selected runtime or catalog does not support this OS, architecture and Node version. Check node --version and the selected Kit runtime targets. Preserve the project and runtime pins; do not rewrite versions. This local refusal does not describe cloud candidate checks.',
|
|
189
|
+
RUNTIME_CONTENT_INCOMPATIBLE: 'No selected runtime declares a matching builder, tool and contracts row for this snapshot. Check the selected CLI, snapshot and trusted runtime catalog. Preserve the source identity; do not rewrite hashes or reupload to bypass this local refusal. Cloud candidate checks are separate.',
|
|
188
190
|
INVALID_RESOURCE: 'A resource declaration is missing, malformed or no longer bound to verified content. Review the indicated provenance entry before submitting; explicit author or third-party terms are not rewritten.',
|
|
189
191
|
SOURCE_PROVENANCE_UPDATED: 'Testing creator declarations were updated from verified asset bytes before source freeze. Review and commit the intended content changes with your normal Git harness, then retry submit. Nothing was uploaded; no extra source questionnaire is required.',
|
|
190
192
|
SOURCE_PROVENANCE_CONTROLLED_UNKNOWN: 'This imported project lacks explicit controlled scene provenance. Restore its original source-package declarations with the supported preparation path; do not relabel controlled assets as AI-generated.',
|
|
@@ -198,8 +200,8 @@ Object.assign(messages, {
|
|
|
198
200
|
INSTALL_BUSY: 'Another initialization owns this exact installation. Wait for that process; do not delete its lock.',
|
|
199
201
|
INSTALL_NPM_FAILED: 'Dependency installation failed. Check access to the public npm registry and retry the official entry; no partial program was registered.',
|
|
200
202
|
INSTALL_CALLER_MISMATCH: 'The initializer and selected release package/version do not match. Preserve the installed tool and verify the explicit platform and matching release metadata. Do not downgrade to an older webpage recommendation, rename the package or rewrite hashes.',
|
|
201
|
-
INSTALL_PLATFORM_UNSUPPORTED: 'This release has no verified installation for this
|
|
202
|
-
INSTALL_NODE_UNSUPPORTED: '
|
|
203
|
+
INSTALL_PLATFORM_UNSUPPORTED: 'This release metadata has no verified installation for this OS and architecture. Bundled native tools alone do not prove installation or Runtime support. Preserve the project; obtain a release verified for this target, without editing its metadata.',
|
|
204
|
+
INSTALL_NODE_UNSUPPORTED: 'The initializer requires Node.js 22.16.0 or newer; this is not a requirement to match its build Node patch. Runtime execution has its own declared support. The initializer does not change your Node installation.',
|
|
203
205
|
INSTALL_PREREQUISITE_MISSING: 'Install the documented Node.js/npm and Git prerequisites, then retry. The initializer does not install system tools.',
|
|
204
206
|
SOURCE_UPDATE_BASE_UNAVAILABLE: 'No verified old base is available for this project or candidate. Preserve the original project and pending key; update cannot safely infer the old main.',
|
|
205
207
|
SOURCE_UPDATE_CONFLICT: 'The same files changed locally and on the new main. Review the listed paths in your original project; no file or candidate was overwritten.',
|
package/lib/creator-platform.mjs
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { parseReleaseVersion } from './release-version.mjs';
|
|
2
|
+
import { isCreatorPackageName } from './creator-package-identity.mjs';
|
|
2
3
|
|
|
3
4
|
const fail = code => { throw Object.assign(new Error(code), { code }); };
|
|
4
5
|
const exact = (v, keys) => v && typeof v === 'object' && !Array.isArray(v)
|
|
@@ -50,7 +51,7 @@ export function readPlatformPreflight(data, projectId, now = Date.now()) {
|
|
|
50
51
|
|| hashes.some(k => !hash(data[k])) || typeof data.policyId !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(data.policyId)
|
|
51
52
|
|| !positive(data.validUntilMs) || !positive(data.observedAtMs)) fail('INVALID_CREATOR_RESPONSE');
|
|
52
53
|
const t = data.toolchain;
|
|
53
|
-
if (!exact(t, ['package', 'schemaVersion', 'version', 'snapshotHash', 'sdk']) || t.package
|
|
54
|
+
if (!exact(t, ['package', 'schemaVersion', 'version', 'snapshotHash', 'sdk']) || !isCreatorPackageName(t.package)
|
|
54
55
|
|| t.schemaVersion !== '1.0.0' || !parseReleaseVersion(t.version) || !hash(t.snapshotHash)
|
|
55
56
|
|| !exact(t.sdk, ['client', 'shared']) || t.sdk.client !== '#chrona/client' || t.sdk.shared !== '#chrona/shared') fail('INVALID_CREATOR_RESPONSE');
|
|
56
57
|
if (!Array.isArray(data.capabilities) || data.capabilities.length > 128) fail('INVALID_CREATOR_RESPONSE');
|
|
@@ -59,6 +59,15 @@ export const registeredUpgradeSources = [{ schemaVersion: '1.0.0', package: '@ch
|
|
|
59
59
|
sdk: { shared: '#chrona/shared', client: '#chrona/client' } },
|
|
60
60
|
{ schemaVersion: '1.0.0', package: '@chrona/ugc-kit', version: '1.5.8',
|
|
61
61
|
snapshotHash: 'sha256:2a150f290a642e1c72c9ac887cf787a916e4a1ee6f5e25b47f1d87467198285f',
|
|
62
|
+
sdk: { shared: '#chrona/shared', client: '#chrona/client' } },
|
|
63
|
+
{ schemaVersion: '1.0.0', package: '@chrona-city/ugc-kit', version: '1.5.9',
|
|
64
|
+
snapshotHash: 'sha256:1bc56acdc3fdac6999115526f804068c101dcc73ef5054eb2c2c3dc29e381af8',
|
|
65
|
+
sdk: { shared: '#chrona/shared', client: '#chrona/client' } },
|
|
66
|
+
{ schemaVersion: '1.0.0', package: '@chrona-city/ugc-kit', version: '1.5.10',
|
|
67
|
+
snapshotHash: 'sha256:1bc56acdc3fdac6999115526f804068c101dcc73ef5054eb2c2c3dc29e381af8',
|
|
68
|
+
sdk: { shared: '#chrona/shared', client: '#chrona/client' } },
|
|
69
|
+
{ schemaVersion: '1.0.0', package: '@chrona-city/ugc-kit', version: '1.5.11',
|
|
70
|
+
snapshotHash: 'sha256:1bc56acdc3fdac6999115526f804068c101dcc73ef5054eb2c2c3dc29e381af8',
|
|
62
71
|
sdk: { shared: '#chrona/shared', client: '#chrona/client' } }];
|
|
63
72
|
|
|
64
73
|
const fail = code => { throw Object.assign(new Error(code), { code }); };
|
|
@@ -0,0 +1,209 @@
|
|
|
1
|
+
import toolPackageSchema from '../../creator-source/v1/tool-package.schema.json' with { type: 'json' };
|
|
2
|
+
import { createHash } from 'node:crypto';
|
|
3
|
+
import { canonicalJson } from '../../registry/v1/conformance/js/capability-resolver.mjs';
|
|
4
|
+
|
|
5
|
+
export const runtimeHash = bytes => `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
|
|
6
|
+
export const runtimeCanonical = canonicalJson;
|
|
7
|
+
export const RUNTIME_LIMITS = Object.freeze({ files: 4096, fileBytes: 33554432, totalBytes: 134217728, archiveBytes: 268435456, manifestBytes: 2097152 });
|
|
8
|
+
const fail = code => { throw Object.assign(new Error(code), { code }); };
|
|
9
|
+
const exact = (v, keys) => v && typeof v === 'object' && !Array.isArray(v) && Object.keys(v).sort().join(',') === [...keys].sort().join(',');
|
|
10
|
+
const digest = v => typeof v === 'string' && /^sha256:[a-f0-9]{64}$/.test(v);
|
|
11
|
+
const commit = v => typeof v === 'string' && /^[a-f0-9]{40}$/.test(v);
|
|
12
|
+
const version = v => typeof v === 'string' && /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.test(v);
|
|
13
|
+
const toolVersion = v => typeof v === 'string' && /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(?:-alpha\.[1-9][0-9]*(?:\.[1-9][0-9]*)?)?$(?![\s\S])/.test(v);
|
|
14
|
+
const bounded = (v, min, max) => Number.isSafeInteger(v) && v >= min && v <= max;
|
|
15
|
+
const roles = ['node', 'browser', 'sandbox', 'wasm', 'data', 'license'];
|
|
16
|
+
|
|
17
|
+
export function validRuntimePath(v, { document = false, staticRoom = false } = {}) {
|
|
18
|
+
const roomImplementation = typeof v === 'string' && (document
|
|
19
|
+
? /^node\/content-room-document-authority\/services\/game-worker\/src\/runtime\/content\/[A-Za-z0-9_-][A-Za-z0-9_.-]*\.js$/.test(v)
|
|
20
|
+
: staticRoom && /^node\/content-room-authority\/services\/game-worker\/src\/runtime\/content\/[A-Za-z0-9_-][A-Za-z0-9_.-]*\.js$/.test(v));
|
|
21
|
+
const localExecutionImplementation = document && typeof v === 'string'
|
|
22
|
+
&& /^node\/document-local-execution\/services\/ugc-pipeline\/src\/(?:document-local-execution|private-state-model|private-event-model|private-ecs-model|registry-release)\.mjs$/.test(v);
|
|
23
|
+
return typeof v === 'string' && v.length <= 512 && /^[A-Za-z0-9_@-][A-Za-z0-9_@.-]*(?:\/[A-Za-z0-9_@-][A-Za-z0-9_@.-]*)*$/.test(v)
|
|
24
|
+
&& !v.split('/').some(p => ['credentials', 'secrets', 'private'].includes(p.toLowerCase())
|
|
25
|
+
|| p.toLowerCase() === 'ugc-pipeline' && !localExecutionImplementation
|
|
26
|
+
|| p.toLowerCase() === 'content' && !roomImplementation)
|
|
27
|
+
&& !v.split('/').some(p => p.endsWith('.') || /^(con|prn|aux|nul|com[0-9]|lpt[0-9])(\.|$)/i.test(p))
|
|
28
|
+
&& !/\.(?:pem|key|p12|pfx|glb|gltf)$/i.test(v) && !['runtime.zip', 'runtime-manifest.json'].includes(v.toLowerCase());
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
export function validateRuntimeFiles(files, { document = false, staticRoom = false } = {}) {
|
|
32
|
+
if (!Array.isArray(files) || !files.length || files.length > RUNTIME_LIMITS.files) fail('INVALID_RUNTIME_FILES');
|
|
33
|
+
let previous = '', total = 0;
|
|
34
|
+
const folded = new Set(), directories = new Set();
|
|
35
|
+
for (const f of files) {
|
|
36
|
+
if (!exact(f, ['path', 'bytes', 'sha256', 'role']) || !validRuntimePath(f.path, { document, staticRoom }) || f.path <= previous
|
|
37
|
+
|| !digest(f.sha256) || !bounded(f.bytes, 0, RUNTIME_LIMITS.fileBytes) || !roles.includes(f.role)) fail('INVALID_RUNTIME_FILES');
|
|
38
|
+
const parts = f.path.toLowerCase().split('/');
|
|
39
|
+
if (folded.has(parts.join('/')) || directories.has(parts.join('/')) || parts.some((_, i) => folded.has(parts.slice(0, i).join('/')))) fail('INVALID_RUNTIME_FILES');
|
|
40
|
+
for (let i = 1; i < parts.length; i++) directories.add(parts.slice(0, i).join('/'));
|
|
41
|
+
folded.add(parts.join('/')); previous = f.path; total += f.bytes;
|
|
42
|
+
}
|
|
43
|
+
if (total > RUNTIME_LIMITS.totalBytes) fail('RUNTIME_PACKAGE_BUDGET_EXCEEDED');
|
|
44
|
+
return total;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
export function computeRuntimeHash(value) {
|
|
48
|
+
const { runtimeId, runtimeHash: ignoredHash, archive, ...body } = value;
|
|
49
|
+
return runtimeHash(`chrona.public-runtime.v1\n${canonicalJson(body)}`);
|
|
50
|
+
}
|
|
51
|
+
export const runtimeIdentity = value => `runtime_${computeRuntimeHash(value).slice(7)}`;
|
|
52
|
+
export const runtimeHashFromId = value => {
|
|
53
|
+
if (typeof value !== 'string' || !/^runtime_[a-f0-9]{64}$/.test(value)) fail('INVALID_RUNTIME_MANIFEST');
|
|
54
|
+
return `sha256:${value.slice(8)}`;
|
|
55
|
+
};
|
|
56
|
+
// Actual execution observations are exact versions. A support declaration is a
|
|
57
|
+
// separate, versioned manifest value; neither package engines nor a report
|
|
58
|
+
// silently widens it. Old string targets keep their original exact semantics.
|
|
59
|
+
const nodeVersion = v => {
|
|
60
|
+
if (typeof v !== 'string' || v.length > 48 || !/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$(?![\s\S])/.test(v)) return null;
|
|
61
|
+
const parts = v.split('.').map(Number);
|
|
62
|
+
return parts.every(Number.isSafeInteger) && parts[0] > 0 ? parts : null;
|
|
63
|
+
};
|
|
64
|
+
const targetPlatform = v => ['darwin', 'linux'].includes(v.os) && ['arm64', 'x64'].includes(v.arch);
|
|
65
|
+
export const validateRuntimeTarget = v => Boolean(exact(v, ['os', 'arch', 'nodeVersion']) && targetPlatform(v) && nodeVersion(v.nodeVersion));
|
|
66
|
+
const validTarget = v => {
|
|
67
|
+
if (exact(v, ['os', 'arch', 'nodeVersion'])) return validateRuntimeTarget(v) && v.nodeVersion === '22.16.0';
|
|
68
|
+
if (!exact(v, ['os', 'arch', 'nodeSupport']) || !targetPlatform(v)
|
|
69
|
+
|| !exact(v.nodeSupport, ['schemaVersion', 'lines']) || v.nodeSupport.schemaVersion !== '1.0.0'
|
|
70
|
+
|| !Array.isArray(v.nodeSupport.lines) || !v.nodeSupport.lines.length || v.nodeSupport.lines.length > 4) return false;
|
|
71
|
+
return v.nodeSupport.lines.every((line, i, lines) => exact(line, ['major', 'minimum'])
|
|
72
|
+
&& Number.isSafeInteger(line.major) && line.major > 0 && nodeVersion(line.minimum)?.[0] === line.major
|
|
73
|
+
&& (!i || line.major > lines[i - 1].major));
|
|
74
|
+
};
|
|
75
|
+
const targetMatches = (declared, actual) => {
|
|
76
|
+
if (Object.hasOwn(declared, 'nodeVersion')) return canonicalJson(declared) === canonicalJson(actual);
|
|
77
|
+
const observed = nodeVersion(actual.nodeVersion);
|
|
78
|
+
return declared.os === actual.os && declared.arch === actual.arch && declared.nodeSupport.lines.some(line => {
|
|
79
|
+
if (observed[0] !== line.major) return false;
|
|
80
|
+
const minimum = nodeVersion(line.minimum);
|
|
81
|
+
return observed[1] > minimum[1] || observed[1] === minimum[1] && observed[2] >= minimum[2];
|
|
82
|
+
});
|
|
83
|
+
};
|
|
84
|
+
// The Host IPC and Runtime compatibility use the same exact tuple definition.
|
|
85
|
+
// `document` is selected from the verified snapshot/runtime variant, not a
|
|
86
|
+
// claim made by the child. This validates format, not source approval or access.
|
|
87
|
+
export function validateRuntimeContentContracts(c, { document = false } = {}) {
|
|
88
|
+
return exact(c, ['registryVersion', 'registryHash', 'resolutionPolicyHash', 'contractSetHashes']) && version(c.registryVersion)
|
|
89
|
+
&& digest(c.registryHash) && digest(c.resolutionPolicyHash)
|
|
90
|
+
&& exact(c.contractSetHashes, document ? ['localContent', 'worldScene', 'documentPresentation'] : ['localContent', 'worldScene'])
|
|
91
|
+
&& Object.values(c.contractSetHashes).every(digest);
|
|
92
|
+
}
|
|
93
|
+
function validContentRow(row, document = false) {
|
|
94
|
+
if (!exact(row, ['builderVersion', 'tool', 'contracts']) || row.builderVersion !== (document ? 'local-content@1.1.0' : 'local-content@1.0.0')) return false;
|
|
95
|
+
const t = row.tool, c = row.contracts;
|
|
96
|
+
return exact(t, ['packageName', 'packageVersion', 'kitVersion', 'kitSnapshotHash']) && toolPackageSchema.enum.includes(t.packageName)
|
|
97
|
+
&& toolVersion(t.packageVersion) && toolVersion(t.kitVersion) && digest(t.kitSnapshotHash)
|
|
98
|
+
&& validateRuntimeContentContracts(c, { document });
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
export function validateRuntimeManifest(v) {
|
|
102
|
+
if (!exact(v, ['schemaVersion', 'kind', 'apiVersion', 'runtimeId', 'runtimeHash', 'executionTier', 'source', 'targets', 'compatibility', 'entrypoints', 'files', 'archive'])
|
|
103
|
+
|| !['1.0.0', '1.1.0'].includes(v.schemaVersion) || v.kind !== 'public-local-runtime' || v.apiVersion !== '1.0.0'
|
|
104
|
+
|| v.executionTier !== 'public-untrusted' || !/^runtime_[a-f0-9]{64}$/.test(v.runtimeId ?? '') || !digest(v.runtimeHash)) fail('INVALID_RUNTIME_MANIFEST');
|
|
105
|
+
const document = v.schemaVersion === '1.1.0';
|
|
106
|
+
// Static Room is a distinct source closure, not Document or historical Flight.
|
|
107
|
+
// The exact source shape selects only its fixed implementation namespace.
|
|
108
|
+
const staticRoom = !document && exact(v.source, ['clientsCommitSha', 'publicNode', 'contentRoom']);
|
|
109
|
+
const sourceKeys = document ? ['publicNode', 'contentRoom', 'documentAuthority']
|
|
110
|
+
: staticRoom ? ['publicNode', 'contentRoom'] : ['publicNode', 'publicFlight'];
|
|
111
|
+
if (!exact(v.source, ['clientsCommitSha', ...sourceKeys]) || !commit(v.source.clientsCommitSha)) fail('INVALID_RUNTIME_SOURCE');
|
|
112
|
+
validateRuntimeFiles(v.files, { document, staticRoom });
|
|
113
|
+
const files = new Map(v.files.map(f => [f.path, f]));
|
|
114
|
+
const reference = (p, role) => validRuntimePath(p, { document, staticRoom }) && files.get(p)?.role === role;
|
|
115
|
+
for (const key of sourceKeys) {
|
|
116
|
+
const source = v.source[key];
|
|
117
|
+
if (!exact(source, ['commitSha', 'sourceHash', 'lockPath']) || !commit(source.commitSha) || !digest(source.sourceHash)
|
|
118
|
+
|| !reference(source.lockPath, 'data')) fail('INVALID_RUNTIME_SOURCE');
|
|
119
|
+
}
|
|
120
|
+
if (new Set(sourceKeys.map(key => v.source[key].lockPath)).size !== sourceKeys.length) fail('INVALID_RUNTIME_SOURCE');
|
|
121
|
+
const c = v.compatibility;
|
|
122
|
+
if (!Array.isArray(v.targets) || !v.targets.length || v.targets.length > 4 || v.targets.some(t => !validTarget(t))
|
|
123
|
+
|| v.targets.some((t, i) => i && canonicalJson(t) <= canonicalJson(v.targets[i - 1]))) fail('INVALID_RUNTIME_COMPATIBILITY');
|
|
124
|
+
if (!exact(c, ['protocol', 'content', 'policyFiles', 'localContentContract'])
|
|
125
|
+
|| !exact(c.protocol, ['major', 'schemaRevision']) || c.protocol.major !== 1
|
|
126
|
+
|| !(c.protocol.schemaRevision === 2 || document && c.protocol.schemaRevision === 3)
|
|
127
|
+
|| !Array.isArray(c.content) || !c.content.length || c.content.length > 8
|
|
128
|
+
|| !(document ? exact(c.policyFiles, ['documentPresentation']) && reference(c.policyFiles.documentPresentation, 'data')
|
|
129
|
+
: exact(c.policyFiles, ['worldScene', 'sceneRender']) && reference(c.policyFiles.worldScene, 'data')
|
|
130
|
+
&& reference(c.policyFiles.sceneRender, 'data') && c.policyFiles.worldScene !== c.policyFiles.sceneRender)
|
|
131
|
+
|| !reference(c.localContentContract, 'node')) fail('INVALID_RUNTIME_COMPATIBILITY');
|
|
132
|
+
let previous = '';
|
|
133
|
+
for (const row of c.content) {
|
|
134
|
+
if (!validContentRow(row, document) || canonicalJson(row) <= previous) fail('INVALID_RUNTIME_COMPATIBILITY');
|
|
135
|
+
previous = canonicalJson(row);
|
|
136
|
+
}
|
|
137
|
+
if (!exact(v.entrypoints, ['api', 'browser', 'sandbox'])
|
|
138
|
+
|| v.entrypoints.api !== 'node/host.mjs' || !reference(v.entrypoints.api, 'node')
|
|
139
|
+
|| v.entrypoints.browser !== 'web/index.html' || !reference(v.entrypoints.browser, 'browser')
|
|
140
|
+
|| !reference('web/app.js', 'browser')
|
|
141
|
+
|| v.entrypoints.sandbox !== (document ? 'sandbox/document-view.html' : 'sandbox/public-content-bridge.html')
|
|
142
|
+
|| !reference(v.entrypoints.sandbox, 'sandbox')
|
|
143
|
+
|| !document && !reference('sandbox/public-content-worker.js', 'sandbox')
|
|
144
|
+
|| !v.files.some(f => f.role === 'wasm' && f.path.endsWith('.wasm')) || !v.files.some(f => f.role === 'license' && f.path.startsWith('licenses/'))) fail('INVALID_RUNTIME_ENTRYPOINT');
|
|
145
|
+
if (!exact(v.archive, ['path', 'format', 'bytes', 'sha256']) || v.archive.path !== 'runtime.zip' || v.archive.format !== 'zip-store-v1'
|
|
146
|
+
|| !bounded(v.archive.bytes, 22, RUNTIME_LIMITS.archiveBytes) || !digest(v.archive.sha256)) fail('INVALID_RUNTIME_ARCHIVE');
|
|
147
|
+
const expectedBytes = 22 + v.files.reduce((n, f) => n + f.bytes + 76 + 2 * Buffer.byteLength(f.path), 0);
|
|
148
|
+
if (v.archive.bytes !== expectedBytes || runtimeIdentity(v) !== v.runtimeId || computeRuntimeHash(v) !== v.runtimeHash) fail('RUNTIME_PACKAGE_IDENTITY_MISMATCH');
|
|
149
|
+
return v;
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
export function verifyRuntimeManifest(bytes, expectedHash) {
|
|
153
|
+
if (!(bytes instanceof Uint8Array) || bytes.byteLength > RUNTIME_LIMITS.manifestBytes || !digest(expectedHash)
|
|
154
|
+
|| runtimeHash(bytes) !== expectedHash) fail('RUNTIME_MANIFEST_HASH_MISMATCH');
|
|
155
|
+
let value;
|
|
156
|
+
try { value = JSON.parse(Buffer.from(bytes)); } catch { fail('INVALID_RUNTIME_MANIFEST'); }
|
|
157
|
+
validateRuntimeManifest(value);
|
|
158
|
+
if (!Buffer.from(`${canonicalJson(value)}\n`).equals(Buffer.from(bytes))) fail('INVALID_RUNTIME_MANIFEST');
|
|
159
|
+
return value;
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
function artifactPin(v, maximum, allowLocalHttp) {
|
|
163
|
+
if (!exact(v, ['url', 'bytes', 'sha256']) || !bounded(v.bytes, 1, maximum) || !digest(v.sha256) || typeof v.url !== 'string' || v.url.length > 2048) fail('INVALID_RUNTIME_LOCK');
|
|
164
|
+
let url;
|
|
165
|
+
try { url = new URL(v.url); } catch { fail('INVALID_RUNTIME_LOCK'); }
|
|
166
|
+
if (url.href !== v.url || url.username || url.password || url.search || url.hash
|
|
167
|
+
|| !(url.protocol === 'https:' || allowLocalHttp && url.protocol === 'http:' && ['127.0.0.1', '[::1]'].includes(url.hostname))) fail('INVALID_RUNTIME_LOCK');
|
|
168
|
+
}
|
|
169
|
+
|
|
170
|
+
function validateLockShape(lock, allowLocalHttp) {
|
|
171
|
+
if (typeof allowLocalHttp !== 'boolean' || !exact(lock, ['schemaVersion', 'kind', 'runtimeId', 'runtimeHash', 'manifest', 'archive'])
|
|
172
|
+
|| lock.schemaVersion !== '1.0.0' || lock.kind !== 'public-runtime-lock' || !/^runtime_[a-f0-9]{64}$/.test(lock.runtimeId ?? '')) fail('INVALID_RUNTIME_LOCK');
|
|
173
|
+
if (runtimeHashFromId(lock.runtimeId) !== lock.runtimeHash) fail('INVALID_RUNTIME_LOCK');
|
|
174
|
+
artifactPin(lock.manifest, RUNTIME_LIMITS.manifestBytes, allowLocalHttp); artifactPin(lock.archive, RUNTIME_LIMITS.archiveBytes, allowLocalHttp);
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
export function validateRuntimeLock(lock, trustedLock, { allowLocalHttp = false } = {}) {
|
|
178
|
+
validateLockShape(lock, allowLocalHttp);
|
|
179
|
+
if (!trustedLock || canonicalJson(lock) !== canonicalJson(trustedLock)) fail('UNTRUSTED_RUNTIME_LOCK');
|
|
180
|
+
return lock;
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
export function assertRuntimeTargetCompatibility(manifest, { target = { os: process.platform, arch: process.arch, nodeVersion: process.versions.node } } = {}) {
|
|
184
|
+
validateRuntimeManifest(manifest);
|
|
185
|
+
if (!validateRuntimeTarget(target) || !manifest.targets.some(t => targetMatches(t, target))) fail('RUNTIME_TARGET_UNSUPPORTED');
|
|
186
|
+
return true;
|
|
187
|
+
}
|
|
188
|
+
|
|
189
|
+
export function assertRuntimeCompatibility(manifest, { target, expected } = {}) {
|
|
190
|
+
assertRuntimeTargetCompatibility(manifest, { target });
|
|
191
|
+
const row = { builderVersion: expected?.builderVersion, tool: expected?.tool, contracts: expected?.contracts };
|
|
192
|
+
const staticRoom = manifest.schemaVersion === '1.0.0' && exact(manifest.source, ['clientsCommitSha', 'publicNode', 'contentRoom']);
|
|
193
|
+
// Tool versions retain snapshot/report provenance. Only this validated static
|
|
194
|
+
// Room family matches the actual Builder/contracts/SDK interface instead.
|
|
195
|
+
if (!validContentRow(row, manifest.schemaVersion === '1.1.0') || !manifest.compatibility.content.some(r => staticRoom
|
|
196
|
+
? r.builderVersion === row.builderVersion && canonicalJson(r.contracts) === canonicalJson(row.contracts)
|
|
197
|
+
&& r.tool.packageName === row.tool.packageName && r.tool.kitSnapshotHash === row.tool.kitSnapshotHash
|
|
198
|
+
: canonicalJson(r) === canonicalJson(row))) fail('RUNTIME_CONTENT_INCOMPATIBLE');
|
|
199
|
+
return true;
|
|
200
|
+
}
|
|
201
|
+
|
|
202
|
+
export function verifyRuntimePair(manifest, lock, expected, { target, allowLocalHttp = false } = {}) {
|
|
203
|
+
validateLockShape(lock, allowLocalHttp);
|
|
204
|
+
assertRuntimeCompatibility(manifest, { target, expected });
|
|
205
|
+
const bytes = Buffer.from(`${canonicalJson(manifest)}\n`);
|
|
206
|
+
if (manifest.runtimeId !== lock.runtimeId || manifest.runtimeHash !== lock.runtimeHash || manifest.archive.sha256 !== lock.archive.sha256
|
|
207
|
+
|| manifest.archive.bytes !== lock.archive.bytes || bytes.length !== lock.manifest.bytes || runtimeHash(bytes) !== lock.manifest.sha256) fail('RUNTIME_PAIR_MISMATCH');
|
|
208
|
+
return { runtimeId: manifest.runtimeId, runtimeHash: manifest.runtimeHash, manifestSha256: lock.manifest.sha256, apiVersion: manifest.apiVersion, ready: false };
|
|
209
|
+
}
|