@bitmagic/asset-core 0.1.2 → 0.2.0

package/dist/publish-source.d.ts

@@ -0,0 +1,270 @@
+/**
+ * What "the source of a published game" means, shared by the two sides that must agree on it.
+ *
+ * The CLI walks a creator's project to produce a fingerprint and a source archive; api-server
+ * re-derives the fingerprint from that archive's manifest to check the two describe the same
+ * tree. If the exclusion lists, the path normalisation or the fold ever differ between them, a
+ * perfectly honest publish reports a mismatch. So they live here, once.
+ *
+ * Import path matters, twice over:
+ *
+ *  - Published as the `@bitmagic/asset-core/publish-source` subpath, following `./favicon`'s
+ *    precedent, so consumers do not drag in the root barrel's zod/three/forger client. This is
+ *    not cosmetic: `api-server/src/cli/cli-routes.ts` documents that eagerly importing the
+ *    three.js graph into api-server's tests OOM-killed the CI worker. Nothing here may import
+ *    from `./index.js`.
+ *  - No zip library, no `fs`. Zip *format* handling stays in each consumer (the CLI writes an
+ *    archive, api-server streams one apart) and only the pure logic is shared, which keeps this
+ *    package dependency-clean and keeps the npm blast radius of a change small.
+ *
+ * The CLI ships to npm with this package pinned, while api-server runs from `main`, so the two
+ * routinely run DIFFERENT copies of this file. That is why the fingerprint is versioned — see
+ * `SOURCE_INDEX_ALGO`.
+ */
+/**
+ * The fingerprint algorithm's identity, sent by the CLI and dispatched on by the server.
+ *
+ * Without it, adding one entry to `EXCLUDED_FILES` — which has happened three times, each for a
+ * good reason documented below — would make every publish from an already-installed CLI report a
+ * fingerprint mismatch, because that CLI is still hashing the old file set. The server keeps every
+ * algorithm it has ever shipped and picks by this value; an unknown or absent one is reported as
+ * "cannot check", never as "mismatch". Bump it in lockstep with any change to the two sets below
+ * or to `fingerprintFromIndex`.
+ */
+export declare const SOURCE_INDEX_ALGO = "v1";
+/**
+ * Directories whose contents never change what the bundle contains: our own artifacts
+ * (`.bitmagic/`, `dist/`), the dependency tree (`node_modules/` — pinned by the lockfile the
+ * scaffold writes), vite's cache, and git's object store. Including any of them would make the
+ * fingerprint change on something other than an edit, which would make the staleness gate reject
+ * a publish of an unchanged project.
+ *
+ * `.git` is the one that bit in practice. Hashing it means an EMPTY `git commit` — no source
+ * change at all — flips the fingerprint, because the commit writes new objects, a new ref value
+ * and a new reflog entry. That turns the ordinary `bitmagic verify` → `git commit` →
+ * `bitmagic publish` sequence into exit 3 ("The project has changed since it was last verified"),
+ * and `bitmagic upgrade` actively pushes creators into git by refusing a dirty tree. The
+ * scaffolded AGENTS.md's "do not edit any tracked file between verifying and publishing" cannot
+ * prevent it either: committing is not editing. It also made every publish rebuild, since the
+ * build manifest's own recorded fingerprint could never still match by the time publish ran.
+ */
+export declare const EXCLUDED_DIRS: ReadonlySet<string>;
+/**
+ * Files that can never change what the bundle contains, excluded at basename granularity.
+ *
+ * `.DS_Store`: on macOS, Finder writes it merely for opening the project folder, and no build tool
+ * ever reads it — so it is another way to flip the fingerprint without editing anything.
+ *
+ * `mechanics-plan.md`: the agent is told to rewrite it after every slice — moving shipped items
+ * out of the backlog and re-ranking the rest is the whole point of the file. Left in, the ordinary
+ * `bitmagic verify` → update the backlog → `bitmagic publish` sequence exits 3 over prose, which
+ * teaches agents to reach for `--force`, the one flag that also waves through a genuinely stale
+ * verify.
+ *
+ * `GAME-DESIGN.md`: same "no build tool reads it" test — nothing imports it,
+ * `vite.publish.config.js` cannot put prose in the bundle, and it exists to be REWRITTEN as the
+ * game evolves (it is the input `bitmagic cover` reads).
+ *
+ * The list is deliberately not a general ignore mechanism, because a false "fresh" ships an
+ * unverified bundle while a false "stale" only costs one `bitmagic verify`.
+ *
+ * NOTE the asymmetry with `SECRET_FILE_PATTERNS` below: these files are excluded from the
+ * FINGERPRINT but still travel in the source archive, because they are exactly what a human
+ * reading the archive wants. Secrets are the other way round.
+ */
+export declare const EXCLUDED_FILES: ReadonlySet<string>;
+/**
+ * Excluded from the fingerprint, but still carried in the source archive.
+ *
+ * The two sets answer different questions. The fingerprint asks "would changing this change the
+ * bundle?" — for a design document, no, which is why editing one must not invalidate a verify. The
+ * archive asks "would a human opening this want it?" — for a design document, emphatically yes: it
+ * is the single most useful file for understanding what the game was trying to be.
+ *
+ * `.DS_Store` is in neither, so it is deliberately absent here: nobody wants it and it is not
+ * evidence of anything.
+ */
+export declare const ARCHIVED_UNFINGERPRINTED_FILES: ReadonlySet<string>;
+/**
+ * Files that must never travel inside the source archive, however the fingerprint treats them.
+ *
+ * The archive lands in the portal bucket, and that bucket carries a BUCKET-level
+ * `allUsers:objectViewer` grant (see `.github/workflows/README.md`) — every object in it is
+ * world-readable. A creator's project is their working directory, and working directories collect
+ * credentials. Shipping one to a public URL because nobody thought about it is how an incident
+ * starts.
+ *
+ * These files are still hashed and still listed in the manifest (path + hash, no content), so the
+ * server can reconcile the fingerprint without ever receiving the bytes. That is the whole reason
+ * the manifest is separate from the payload.
+ *
+ * Deliberately a deny-list of shapes rather than an allow-list of known-good paths: an allow-list
+ * would silently drop a creator's own source file the first time someone used an unusual layout,
+ * and dropping game code from the archive is a quieter failure than including a stray dotfile.
+ * The trade is accepted knowingly — this list will never be complete, which is why the archive's
+ * storage key is also unguessable rather than relying on this alone.
+ */
+export declare const SECRET_FILE_PATTERNS: readonly RegExp[];
+/** Would including this path in the archive payload risk publishing a credential? */
+export declare function isSecretPath(posixPath: string): boolean;
+/**
+ * A relative path as the fingerprint hashes it: always forward-slashed.
+ *
+ * `sep` is a parameter rather than a direct `path.sep` read so this is testable on any
+ * platform — the Windows behaviour that makes normalization necessary cannot otherwise be
+ * exercised on the POSIX runners CI uses, which is exactly how a vacuous test gets written.
+ */
+export declare function toPosixPath(relativePath: string, sep?: string): string;
+/** One file as both sides see it: the project-relative posix path and the hash of its bytes. */
+export interface SourceIndexEntry {
+    path: string;
+    sha256: string;
+    bytes: number;
+    /**
+     * For vendored engine files only: the same content hashed with line endings normalised, used
+     * exclusively to compare against the official release. See `engineComparisonHash` for why the
+     * raw `sha256` above cannot serve — in short, a Windows checkout rewrites LF to CRLF in the
+     * committed `engine/` tree and would otherwise report every engine file as modified.
+     *
+     * Computed here, by the side that actually has the bytes: the archive carries hashes rather than
+     * engine content, so the server can never normalise after the fact.
+     */
+    engineSha256?: string;
+}
+/**
+ * Every fingerprinted file in a project, plus the fingerprint they roll up to.
+ *
+ * Produced once per publish by the CLI (which owns the filesystem walk) and reconstructed by
+ * api-server from the archive's manifest. `files` is sorted by path — `fingerprintFromIndex`
+ * depends on it and sorts defensively rather than trusting the caller.
+ */
+export interface SourceIndex {
+    algo: string;
+    files: SourceIndexEntry[];
+    fingerprint: string;
+    /**
+     * Files the archive carries but the fingerprint ignores — see
+     * `ARCHIVED_UNFINGERPRINTED_FILES`. Kept apart from `files` so they can never reach
+     * `fingerprintFromIndex`, which is the whole reason they were excluded in the first place.
+     */
+    archivedOnly: SourceIndexEntry[];
+}
+/**
+ * The fingerprint: a hash of everything that determines the published bundle.
+ *
+ * This is what lets `publish` decide whether a `verify` is too stale to trust, by CONTENT
+ * rather than by clock: a timestamp policy would accept an edit made one second after
+ * verifying and reject an untouched project that merely sat overnight.
+ *
+ * The path is hashed alongside the content so that moving a file — which changes what the
+ * bundle imports — changes the fingerprint even though no byte of any file did.
+ *
+ * Kept deliberately coarse (every tracked file, not a module graph): a false "stale" costs one
+ * `bitmagic verify`, while a false "fresh" ships an unverified bundle.
+ *
+ * The exact byte sequence folded here is load-bearing across two independently-released
+ * packages. Do not "clean up" the trailing newline or the separator without bumping
+ * `SOURCE_INDEX_ALGO`.
+ */
+export declare function fingerprintFromIndex(files: readonly SourceIndexEntry[]): string;
+/** Where the archive's manifest lives inside the zip. */
+export declare const SOURCE_MANIFEST_NAME = "bitmagic-source.json";
+/**
+ * The archive's manifest: enough for the server to re-derive the fingerprint and to check the
+ * vendored engine, without the archive having to carry either the engine or any secret.
+ *
+ * `omitted` lists the paths that are in `files` but deliberately absent from the payload, so a
+ * reader (human or server) can tell "not shipped, on purpose" from "the archive is truncated".
+ *
+ * Deliberately NO `publishVersion`. The archive has to be built and hashed BEFORE `publish/begin`
+ * — that hash is what `begin` bakes into the meta block — and the version is not allocated until
+ * `begin` returns. A field that cannot be known when the file is written cannot be in the file.
+ * The version is recorded where it is actually available: in the archive's storage key and in the
+ * meta block's own `bm:publish-version`.
+ */
+export interface SourceManifest {
+    algo: string;
+    gameId: string;
+    engineVersion: string;
+    genre: string;
+    exportedAt: string;
+    fingerprint: string;
+    files: Record<string, string>;
+    omitted: string[];
+    /**
+     * Line-ending-normalised hashes for the vendored engine paths only, keyed the same way as
+     * `files`. Separate from `files` because the two answer different questions: `files` must stay
+     * byte-exact for the fingerprint, while this exists to survive a platform's checkout rules.
+     */
+    engineHashes: Record<string, string>;
+}
+/**
+ * Project-relative prefix of the vendored engine. `bitmagic init`/`upgrade` unpack the release
+ * tarball's `game/src/<root>` into `engine/<root>`, so every vendored file lives under this.
+ */
+export declare const VENDORED_ENGINE_PREFIX = "engine/";
+/**
+ * Map a path as it appears in the engine release tarball to where it lands in a scaffolded
+ * project, or null when the tarball entry is not vendored into projects at all.
+ *
+ * The tarball stores three shapes at different depths (see `cli/src/scaffold/engine-download.ts`):
+ * `game/src/<root>/…` → `engine/<root>/…`, `game/agent-docs/…` → `engine/agent-docs/…`, and
+ * `game/sw-cache-buster.js` → `sw-cache-buster.js` at the project root. `templates/` ships in the
+ * tarball for the scaffolder to read and is never vendored, so it maps to null.
+ *
+ * Lives here rather than in api-server because it is a statement about what the CLI did to the
+ * tarball, and the CLI is the other consumer that has to agree.
+ */
+export declare function tarballPathToProjectPath(tarballPath: string): string | null;
+/**
+ * Bytes every genuine published bundle carries, used to refuse a publish that is not an engine
+ * build at all.
+ *
+ * The scaffold's `index.html` emits a `<script type="importmap">` whose body Vite only RELOCATES —
+ * its import-map hook lifts the tag out and reinserts the matched text unchanged before the first
+ * module script — so these land byte for byte near the top of the single-file bundle, inside the
+ * head range `complete` already reads for the meta block.
+ *
+ * **Position is the constraint, not just survival, and it is why `id="game-container"` is not on
+ * this list.** `vite-plugin-singlefile` hoists the inlined script into `<head>`, so in a real
+ * 8.4MB bundle `</head>` sits at byte 8,471,158 and `<body>` — with the container div — begins
+ * eight megabytes past the head window. The div is present and unchanged; it is simply
+ * unreachable without reading the whole object, which is exactly what this design refuses to do.
+ * That cost a live refusal of a genuine publish in dev: a first spike validated the markers
+ * against a 1.29KB bundle, where "end of file" and "first 64KB" are the same place. Any marker
+ * added here must be checked for its OFFSET in a multi-megabyte bundle, not merely its presence.
+ *
+ * The import map is structurally safe in a way the body is not: a browser requires an import map
+ * to precede the first module script, so it cannot migrate below the inlined bundle no matter how
+ * large that bundle grows.
+ *
+ * Why a SUBSET of the alias entries rather than all of them. A creator's installed CLI is an older
+ * npm release than the running server, so the server must only require markers that both agree on.
+ * The CDN entries are disqualified outright — they embed the pinned three.js version, which moves
+ * whenever the CLI bumps it. These two are the ones that have to exist for a project to resolve
+ * its entry module at all, so requiring more would buy nothing and would turn any future alias
+ * change into a spurious refusal for every not-yet-upgraded project.
+ *
+ * What this is worth: it stops bitmagic.ai being used to host arbitrary HTML by someone who has an
+ * account and a game id. It is trivially copy-pasteable by anyone who looks, and is not claimed to
+ * be more than that.
+ */
+export declare const ENGINE_BUILD_MARKERS: readonly string[];
+/** Does this bundle's head carry every marker a genuine engine build has? */
+export declare function hasEngineBuildMarkers(head: string): boolean;
+/**
+ * Hash used ONLY when comparing a vendored engine file against the official release.
+ *
+ * Line endings are normalised first, which the fingerprint deliberately never does. The reason is
+ * Windows: `renderGitignore()` does not ignore `engine/`, so the vendored tree is committed, and
+ * AGENTS.md pushes creators into git (`bitmagic upgrade` refuses a dirty tree). A Windows checkout
+ * with the default `core.autocrlf=true` rewrites LF to CRLF in every `.ts` file it restores — so
+ * without this, every Windows creator would see 100% of their engine files reported as modified,
+ * forever, on every publish. That is a false alarm about the one check most likely to be believed.
+ *
+ * Confined to this comparison on purpose. Normalising inside the fingerprint would instead make
+ * the fingerprint disagree with itself across platforms in the staleness gate, where a false
+ * "fresh" is the dangerous direction.
+ */
+export declare function engineComparisonHash(content: Uint8Array): string;
+//# sourceMappingURL=publish-source.d.ts.map

package/dist/publish-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish-source.d.ts","sourceRoot":"","sources":["../src/publish-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAQH;;;;;;;;;GASG;AACH,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAEtC;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,aAAa,EAAE,WAAW,CAAC,MAAM,CAM5C,CAAC;AAEH;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,MAAM,CAI7C,CAAC;AAEH;;;;;;;;;;GAUG;AACH,eAAO,MAAM,8BAA8B,EAAE,WAAW,CAAC,MAAM,CAG7D,CAAC;AAEH;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,oBAAoB,EAAE,SAAS,MAAM,EASjD,CAAC;AAEF,qFAAqF;AACrF,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAEvD;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,GAAE,MAAY,GAAG,MAAM,CAE3E;AAED,gGAAgG;AAChG,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC1B,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,YAAY,EAAE,gBAAgB,EAAE,CAAC;CAClC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,SAAS,gBAAgB,EAAE,GAAG,MAAM,CAO/E;AAED,yDAAyD;AACzD,eAAO,MAAM,oBAAoB,yBAAyB,CAAC;AAE3D;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACtC;AAED;;;GAGG;AACH,eAAO,MAAM,sBAAsB,YAAY,CAAC;AAEhD;;;;;;;;;;;GAWG;AACH,wBAAgB,wBAAwB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAW3E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,oBAAoB,EAAE,SAAS,MAAM,EAGjD,CAAC;AAEF,6EAA6E;AAC7E,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE3D;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,UAAU,GAAG,MAAM,CAMhE"}

package/dist/publish-source.js

@@ -0,0 +1,267 @@
+/**
+ * What "the source of a published game" means, shared by the two sides that must agree on it.
+ *
+ * The CLI walks a creator's project to produce a fingerprint and a source archive; api-server
+ * re-derives the fingerprint from that archive's manifest to check the two describe the same
+ * tree. If the exclusion lists, the path normalisation or the fold ever differ between them, a
+ * perfectly honest publish reports a mismatch. So they live here, once.
+ *
+ * Import path matters, twice over:
+ *
+ *  - Published as the `@bitmagic/asset-core/publish-source` subpath, following `./favicon`'s
+ *    precedent, so consumers do not drag in the root barrel's zod/three/forger client. This is
+ *    not cosmetic: `api-server/src/cli/cli-routes.ts` documents that eagerly importing the
+ *    three.js graph into api-server's tests OOM-killed the CI worker. Nothing here may import
+ *    from `./index.js`.
+ *  - No zip library, no `fs`. Zip *format* handling stays in each consumer (the CLI writes an
+ *    archive, api-server streams one apart) and only the pure logic is shared, which keeps this
+ *    package dependency-clean and keeps the npm blast radius of a change small.
+ *
+ * The CLI ships to npm with this package pinned, while api-server runs from `main`, so the two
+ * routinely run DIFFERENT copies of this file. That is why the fingerprint is versioned — see
+ * `SOURCE_INDEX_ALGO`.
+ */
+import { createHash } from 'node:crypto';
+// Imported rather than taken from the ambient global, matching `node:crypto` above: this file's
+// eslint config enumerates its globals deliberately, and an explicit import says "node-only" as
+// clearly as the crypto one does.
+import { TextDecoder } from 'node:util';
+/**
+ * The fingerprint algorithm's identity, sent by the CLI and dispatched on by the server.
+ *
+ * Without it, adding one entry to `EXCLUDED_FILES` — which has happened three times, each for a
+ * good reason documented below — would make every publish from an already-installed CLI report a
+ * fingerprint mismatch, because that CLI is still hashing the old file set. The server keeps every
+ * algorithm it has ever shipped and picks by this value; an unknown or absent one is reported as
+ * "cannot check", never as "mismatch". Bump it in lockstep with any change to the two sets below
+ * or to `fingerprintFromIndex`.
+ */
+export const SOURCE_INDEX_ALGO = 'v1';
+/**
+ * Directories whose contents never change what the bundle contains: our own artifacts
+ * (`.bitmagic/`, `dist/`), the dependency tree (`node_modules/` — pinned by the lockfile the
+ * scaffold writes), vite's cache, and git's object store. Including any of them would make the
+ * fingerprint change on something other than an edit, which would make the staleness gate reject
+ * a publish of an unchanged project.
+ *
+ * `.git` is the one that bit in practice. Hashing it means an EMPTY `git commit` — no source
+ * change at all — flips the fingerprint, because the commit writes new objects, a new ref value
+ * and a new reflog entry. That turns the ordinary `bitmagic verify` → `git commit` →
+ * `bitmagic publish` sequence into exit 3 ("The project has changed since it was last verified"),
+ * and `bitmagic upgrade` actively pushes creators into git by refusing a dirty tree. The
+ * scaffolded AGENTS.md's "do not edit any tracked file between verifying and publishing" cannot
+ * prevent it either: committing is not editing. It also made every publish rebuild, since the
+ * build manifest's own recorded fingerprint could never still match by the time publish ran.
+ */
+export const EXCLUDED_DIRS = new Set([
+    '.bitmagic',
+    'node_modules',
+    'dist',
+    '.vite-cache',
+    '.git',
+]);
+/**
+ * Files that can never change what the bundle contains, excluded at basename granularity.
+ *
+ * `.DS_Store`: on macOS, Finder writes it merely for opening the project folder, and no build tool
+ * ever reads it — so it is another way to flip the fingerprint without editing anything.
+ *
+ * `mechanics-plan.md`: the agent is told to rewrite it after every slice — moving shipped items
+ * out of the backlog and re-ranking the rest is the whole point of the file. Left in, the ordinary
+ * `bitmagic verify` → update the backlog → `bitmagic publish` sequence exits 3 over prose, which
+ * teaches agents to reach for `--force`, the one flag that also waves through a genuinely stale
+ * verify.
+ *
+ * `GAME-DESIGN.md`: same "no build tool reads it" test — nothing imports it,
+ * `vite.publish.config.js` cannot put prose in the bundle, and it exists to be REWRITTEN as the
+ * game evolves (it is the input `bitmagic cover` reads).
+ *
+ * The list is deliberately not a general ignore mechanism, because a false "fresh" ships an
+ * unverified bundle while a false "stale" only costs one `bitmagic verify`.
+ *
+ * NOTE the asymmetry with `SECRET_FILE_PATTERNS` below: these files are excluded from the
+ * FINGERPRINT but still travel in the source archive, because they are exactly what a human
+ * reading the archive wants. Secrets are the other way round.
+ */
+export const EXCLUDED_FILES = new Set([
+    '.DS_Store',
+    'GAME-DESIGN.md',
+    'mechanics-plan.md',
+]);
+/**
+ * Excluded from the fingerprint, but still carried in the source archive.
+ *
+ * The two sets answer different questions. The fingerprint asks "would changing this change the
+ * bundle?" — for a design document, no, which is why editing one must not invalidate a verify. The
+ * archive asks "would a human opening this want it?" — for a design document, emphatically yes: it
+ * is the single most useful file for understanding what the game was trying to be.
+ *
+ * `.DS_Store` is in neither, so it is deliberately absent here: nobody wants it and it is not
+ * evidence of anything.
+ */
+export const ARCHIVED_UNFINGERPRINTED_FILES = new Set([
+    'GAME-DESIGN.md',
+    'mechanics-plan.md',
+]);
+/**
+ * Files that must never travel inside the source archive, however the fingerprint treats them.
+ *
+ * The archive lands in the portal bucket, and that bucket carries a BUCKET-level
+ * `allUsers:objectViewer` grant (see `.github/workflows/README.md`) — every object in it is
+ * world-readable. A creator's project is their working directory, and working directories collect
+ * credentials. Shipping one to a public URL because nobody thought about it is how an incident
+ * starts.
+ *
+ * These files are still hashed and still listed in the manifest (path + hash, no content), so the
+ * server can reconcile the fingerprint without ever receiving the bytes. That is the whole reason
+ * the manifest is separate from the payload.
+ *
+ * Deliberately a deny-list of shapes rather than an allow-list of known-good paths: an allow-list
+ * would silently drop a creator's own source file the first time someone used an unusual layout,
+ * and dropping game code from the archive is a quieter failure than including a stray dotfile.
+ * The trade is accepted knowingly — this list will never be complete, which is why the archive's
+ * storage key is also unguessable rather than relying on this alone.
+ */
+export const SECRET_FILE_PATTERNS = [
+    /(^|\/)\.env($|\.)/,
+    /\.pem$/,
+    /\.key$/,
+    /(^|\/)id_rsa/,
+    /(^|\/)\.npmrc$/,
+    /(^|\/)\.git-credentials$/,
+    /service-account[^/]*\.json$/,
+    /(^|\/)\.claude\/settings\.local\.json$/,
+];
+/** Would including this path in the archive payload risk publishing a credential? */
+export function isSecretPath(posixPath) {
+    return SECRET_FILE_PATTERNS.some((pattern) => pattern.test(posixPath));
+}
+/**
+ * A relative path as the fingerprint hashes it: always forward-slashed.
+ *
+ * `sep` is a parameter rather than a direct `path.sep` read so this is testable on any
+ * platform — the Windows behaviour that makes normalization necessary cannot otherwise be
+ * exercised on the POSIX runners CI uses, which is exactly how a vacuous test gets written.
+ */
+export function toPosixPath(relativePath, sep = '/') {
+    return relativePath.split(sep).join('/');
+}
+/**
+ * The fingerprint: a hash of everything that determines the published bundle.
+ *
+ * This is what lets `publish` decide whether a `verify` is too stale to trust, by CONTENT
+ * rather than by clock: a timestamp policy would accept an edit made one second after
+ * verifying and reject an untouched project that merely sat overnight.
+ *
+ * The path is hashed alongside the content so that moving a file — which changes what the
+ * bundle imports — changes the fingerprint even though no byte of any file did.
+ *
+ * Kept deliberately coarse (every tracked file, not a module graph): a false "stale" costs one
+ * `bitmagic verify`, while a false "fresh" ships an unverified bundle.
+ *
+ * The exact byte sequence folded here is load-bearing across two independently-released
+ * packages. Do not "clean up" the trailing newline or the separator without bumping
+ * `SOURCE_INDEX_ALGO`.
+ */
+export function fingerprintFromIndex(files) {
+    const sorted = [...files].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    const hash = createHash('sha256');
+    for (const entry of sorted) {
+        hash.update(`${entry.path}:${entry.sha256}\n`);
+    }
+    return hash.digest('hex');
+}
+/** Where the archive's manifest lives inside the zip. */
+export const SOURCE_MANIFEST_NAME = 'bitmagic-source.json';
+/**
+ * Project-relative prefix of the vendored engine. `bitmagic init`/`upgrade` unpack the release
+ * tarball's `game/src/<root>` into `engine/<root>`, so every vendored file lives under this.
+ */
+export const VENDORED_ENGINE_PREFIX = 'engine/';
+/**
+ * Map a path as it appears in the engine release tarball to where it lands in a scaffolded
+ * project, or null when the tarball entry is not vendored into projects at all.
+ *
+ * The tarball stores three shapes at different depths (see `cli/src/scaffold/engine-download.ts`):
+ * `game/src/<root>/…` → `engine/<root>/…`, `game/agent-docs/…` → `engine/agent-docs/…`, and
+ * `game/sw-cache-buster.js` → `sw-cache-buster.js` at the project root. `templates/` ships in the
+ * tarball for the scaffolder to read and is never vendored, so it maps to null.
+ *
+ * Lives here rather than in api-server because it is a statement about what the CLI did to the
+ * tarball, and the CLI is the other consumer that has to agree.
+ */
+export function tarballPathToProjectPath(tarballPath) {
+    if (tarballPath.startsWith('game/src/')) {
+        return `${VENDORED_ENGINE_PREFIX}${tarballPath.slice('game/src/'.length)}`;
+    }
+    if (tarballPath.startsWith('game/agent-docs/')) {
+        return `${VENDORED_ENGINE_PREFIX}agent-docs/${tarballPath.slice('game/agent-docs/'.length)}`;
+    }
+    if (tarballPath === 'game/sw-cache-buster.js') {
+        return 'sw-cache-buster.js';
+    }
+    return null;
+}
+/**
+ * Bytes every genuine published bundle carries, used to refuse a publish that is not an engine
+ * build at all.
+ *
+ * The scaffold's `index.html` emits a `<script type="importmap">` whose body Vite only RELOCATES —
+ * its import-map hook lifts the tag out and reinserts the matched text unchanged before the first
+ * module script — so these land byte for byte near the top of the single-file bundle, inside the
+ * head range `complete` already reads for the meta block.
+ *
+ * **Position is the constraint, not just survival, and it is why `id="game-container"` is not on
+ * this list.** `vite-plugin-singlefile` hoists the inlined script into `<head>`, so in a real
+ * 8.4MB bundle `</head>` sits at byte 8,471,158 and `<body>` — with the container div — begins
+ * eight megabytes past the head window. The div is present and unchanged; it is simply
+ * unreachable without reading the whole object, which is exactly what this design refuses to do.
+ * That cost a live refusal of a genuine publish in dev: a first spike validated the markers
+ * against a 1.29KB bundle, where "end of file" and "first 64KB" are the same place. Any marker
+ * added here must be checked for its OFFSET in a multi-megabyte bundle, not merely its presence.
+ *
+ * The import map is structurally safe in a way the body is not: a browser requires an import map
+ * to precede the first module script, so it cannot migrate below the inlined bundle no matter how
+ * large that bundle grows.
+ *
+ * Why a SUBSET of the alias entries rather than all of them. A creator's installed CLI is an older
+ * npm release than the running server, so the server must only require markers that both agree on.
+ * The CDN entries are disqualified outright — they embed the pinned three.js version, which moves
+ * whenever the CLI bumps it. These two are the ones that have to exist for a project to resolve
+ * its entry module at all, so requiring more would buy nothing and would turn any future alias
+ * change into a spurious refusal for every not-yet-upgraded project.
+ *
+ * What this is worth: it stops bitmagic.ai being used to host arbitrary HTML by someone who has an
+ * account and a game id. It is trivially copy-pasteable by anyone who looks, and is not claimed to
+ * be more than that.
+ */
+export const ENGINE_BUILD_MARKERS = [
+    '"engine/": "/dist/engine/engine/"',
+    '"types/": "/dist/engine/types/"',
+];
+/** Does this bundle's head carry every marker a genuine engine build has? */
+export function hasEngineBuildMarkers(head) {
+    return ENGINE_BUILD_MARKERS.every((marker) => head.includes(marker));
+}
+/**
+ * Hash used ONLY when comparing a vendored engine file against the official release.
+ *
+ * Line endings are normalised first, which the fingerprint deliberately never does. The reason is
+ * Windows: `renderGitignore()` does not ignore `engine/`, so the vendored tree is committed, and
+ * AGENTS.md pushes creators into git (`bitmagic upgrade` refuses a dirty tree). A Windows checkout
+ * with the default `core.autocrlf=true` rewrites LF to CRLF in every `.ts` file it restores — so
+ * without this, every Windows creator would see 100% of their engine files reported as modified,
+ * forever, on every publish. That is a false alarm about the one check most likely to be believed.
+ *
+ * Confined to this comparison on purpose. Normalising inside the fingerprint would instead make
+ * the fingerprint disagree with itself across platforms in the staleness gate, where a false
+ * "fresh" is the dangerous direction.
+ */
+export function engineComparisonHash(content) {
+    // TextDecoder rather than Buffer: this module is imported by an npm-published CLI as well as by
+    // the server, and keeping Node's Buffer out of it means the file has no ambient-global
+    // dependency beyond `node:crypto`, which it imports explicitly.
+    const text = new TextDecoder('utf-8').decode(content);
+    return createHash('sha256').update(text.replace(/\r\n/g, '\n'), 'utf8').digest('hex');
+}
+//# sourceMappingURL=publish-source.js.map

package/dist/publish-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish-source.js","sourceRoot":"","sources":["../src/publish-source.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bitmagic/asset-core",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -17,12 +17,9 @@
       "types": "./dist/favicon.d.ts",
       "default": "./dist/favicon.js"
     },
-    "./animation/*": {
-      "default": "./src/animation/*"
-    },
-    "./animation/authored.mjs": {
-      "types": "./src/animation/authored.d.mts",
-      "default": "./src/animation/authored.mjs"
+    "./publish-source": {
+      "types": "./dist/publish-source.d.ts",
+      "default": "./dist/publish-source.js"
     }
   },
   "files": [
@@ -32,8 +29,7 @@
     "access": "public"
   },
   "dependencies": {
-    "zod": "^3.25.76",
-    "three": "^0.185.1"
+    "zod": "^3.25.76"
   },
   "devDependencies": {
     "@eslint/js": "^9.38.0",