@crumbsdk/source-maps 0.0.1-rc.4

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Crumb contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,145 @@
+# @crumbsdk/source-maps
+
+An explicit CI command for uploading a React Native release bundle and its
+matching source map. Requires Node.js 22 or newer. It never runs inside your app
+and has no runtime dependencies.
+
+**rc.4 candidate:** confirm the exact package version is published before using
+a registry installation; source preparation alone does not establish availability. Uploads require
+a service implementing the [v1 upload contract](https://github.com/alexander126/crumb/blob/main/docs/contracts/source-map-upload.md)
+and a dedicated project-scoped upload credential. A local dry-run does not
+require either. Hosted compatibility and package publication are release gates.
+
+## Run from this checkout
+
+```sh
+cd packages/source-maps
+npm ci
+npm run build
+node dist/cli.js --help
+```
+
+After an approved package release, install its exact version as a development
+dependency and use `crumb-source-maps` from a package script. For this candidate,
+that version is `@crumbsdk/source-maps@0.0.1-rc.4`. Do not resolve an unversioned
+package on each release build.
+
+## Upload the exact release
+
+Choose a unique immutable JavaScript bundle version for each exported build,
+and supply the same value to the app's Crumb `release.bundleVersion`. Use the
+actual native app version and build number embedded in the distributed binary.
+Never use a branch name, mutable channel name, or an EAS runtime version as the
+only bundle identity.
+
+The example assumes the following variables are set by your build job:
+`CRUMB_UPLOAD_ORIGIN`, `CRUMB_PLATFORM`, `APP_VERSION`, `NATIVE_BUILD`,
+`JS_BUNDLE_VERSION`, `BUNDLE_FILE`, and `SOURCE_MAP_FILE`.
+`CRUMB_SOURCE_MAP_TOKEN` must come from your CI secret store. It is a dedicated
+upload credential; the SDK write key embedded in the app cannot upload maps.
+
+```sh
+node dist/cli.js upload \
+  --url "$CRUMB_UPLOAD_ORIGIN" \
+  --platform "$CRUMB_PLATFORM" \
+  --app-version "$APP_VERSION" \
+  --native-build "$NATIVE_BUILD" \
+  --bundle-version "$JS_BUNDLE_VERSION" \
+  --bundle "$BUNDLE_FILE" \
+  --source-map "$SOURCE_MAP_FILE"
+```
+
+Use `ios` or `android`, including for React Native. All release fields are
+required. Identity values start with a letter or digit and contain only letters,
+digits, dot, underscore, plus or hyphen. App version and native build are at most
+64 characters; bundle version is at most 128.
+
+Add `--dry-run` to validate and hash files without network access or reading a
+credential. Add `--expected-bundle-sha256` and `--expected-source-map-sha256` to
+verify checksums saved by an earlier build step. Supply lowercase hexadecimal
+SHA-256 values. The command rejects a mismatch before making any request.
+
+Alternatively, supply `--token-file /path/to/ci-secret`. A single trailing newline
+is accepted. Do not also set `CRUMB_SOURCE_MAP_TOKEN`. No command-line token flag
+is supported, no credentials are discovered automatically, and the tool never
+prints the token, input paths, bundle, map, signed URLs or server response body.
+Keep shell tracing disabled for secret-handling steps. Never put upload secrets
+in app configuration or an `EXPO_PUBLIC_*` variable.
+
+Only HTTPS is accepted. The API origin must not contain a path, query, fragment
+or credentials. Redirects are rejected, and authorization is never forwarded to
+artifact upload locations. `--allow-localhost` permits HTTP only on localhost,
+127.0.0.1 or ::1 for local fixture tests.
+
+## Results and retries
+
+Except for `--help`, stdout/stderr contain one JSON result. Success exits 0;
+failure exits 1. Success is written to stdout; failure to stderr.
+
+```json
+{"ok":true,"status":"verified","upload_id":"00000000-0000-4000-8000-000000000001","manifest_sha256":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"}
+```
+
+`verified` means the service verified and stored both artifacts. It does not
+mean any crash has been symbolicated. Dry-run returns `status: "dry_run"`, the
+manifest digest and both byte counts; it makes no storage claim.
+
+```json
+{"ok":false,"error":{"code":"release_conflict","message":"This release identity already has different artifacts. Use the matching build or a new bundle version."}}
+```
+
+Rerun the **same command with unchanged artifacts** after a timeout or interrupted
+upload. The service can refresh expired upload locations, and exact duplicates
+return the same upload ID. The CLI does not automatically retry. Each request
+has a 60-second deadline. A different artifact pair under the same release is a
+conflict; use the correct build or assign a new bundle version and rebuild.
+
+Common failure codes: `invalid_arguments`, `invalid_release`, `invalid_platform`,
+`file_unavailable`, `invalid_size`, `invalid_source_map`, `checksum_mismatch`,
+`missing_token`, `ambiguous_token`, `invalid_token`, `unauthorized`,
+`release_conflict`, `artifact_rejected`, `artifact_too_large`, `rate_limited`,
+`artifact_upload_failed`, `network_error`, and `invalid_response`.
+
+## Build artifacts and limits
+
+Supply the final bundle shipped to users and the final corresponding v3 map.
+For Hermes, this means the bytecode bundle and the map composed through Hermes,
+not only the intermediate Metro packager map. Never rebuild just to obtain a
+missing map: archive both outputs of the original build together.
+
+Both files must be nonempty regular files, at most 25 MiB each. Standard and
+inline indexed maps are supported; external section URLs are rejected. Map
+validation checks JSON structure, not whether every mapping correctly describes
+the compiled bundle. Hashes establish byte identity, not semantic correctness.
+Confirm a synthetic crash resolves to its known source location before release.
+The tool never executes a bundle or downloads source URLs.
+
+Source maps may contain original source code in `sourcesContent`. The matching
+bundle and map are deliberately uploaded as private release artifacts. Review
+your build outputs, use a narrowly scoped CI credential, and keep these files
+out of public build artifacts and the app's published assets when unnecessary.
+
+See the [Metro, bare React Native and Expo/EAS guide](https://github.com/alexander126/crumb/blob/main/docs/source-maps.md)
+for release-pipeline examples.
+
+## Package checks and publication
+
+```sh
+npm ci
+npm run typecheck
+npm test
+npm run pack:check
+```
+
+The packaging check installs the produced tarball offline, invokes its executable,
+and performs a dry-run. The allowlist contains only compiled CLI files, this
+README, the license and package metadata.
+
+The package version must match the root `VERSION`; when bumping it, update this
+package and its lockfile together. The manual `source-maps-npm-publish.yml`
+workflow requires the immutable native release tag `<version>` and the explicit
+confirmation `publish @crumbsdk/source-maps@<version>`. Prereleases use `next`;
+stable releases use `latest`. The workflow runs checks before publishing using
+npm trusted publishing. Registry ownership/trusted-publisher setup and the first
+publication require an authorized release owner; they are not performed by CI
+checks or this CLI.

package/dist/cli.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { prepareUpload, upload } from "./upload.js";
+import { readBoundedFile, UploadError } from "./validation.js";
+const HELP = `crumb-source-maps upload --platform ios|android --app-version VERSION
+  --native-build BUILD --bundle-version ID --bundle FILE --source-map FILE
+  --url HTTPS_API_ORIGIN [--token-file FILE]
+  [--expected-bundle-sha256 HASH] [--expected-source-map-sha256 HASH]
+  [--dry-run] [--allow-localhost]
+
+Credentials: CRUMB_SOURCE_MAP_TOKEN or --token-file, never a command-line token.
+--dry-run validates and hashes inputs without reading credentials or using network.
+Inputs: final matching build artifacts, at most 25 MiB each. Node.js 22 or newer.
+Successful upload means verified storage, not successful crash symbolication.
+Outputs are JSON except --help. Exit code 0 is success; 1 is a safe failure.
+`;
+async function main() {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            allowPositionals: true,
+            strict: true,
+            tokens: true,
+            options: {
+                help: { type: "boolean", short: "h" },
+                "dry-run": { type: "boolean" },
+                "allow-localhost": { type: "boolean" },
+                url: { type: "string" },
+                platform: { type: "string" },
+                "app-version": { type: "string" },
+                "native-build": { type: "string" },
+                "bundle-version": { type: "string" },
+                bundle: { type: "string" },
+                "source-map": { type: "string" },
+                "token-file": { type: "string" },
+                "expected-bundle-sha256": { type: "string" },
+                "expected-source-map-sha256": { type: "string" },
+            },
+        });
+        const seen = new Set();
+        for (const token of parsed.tokens) {
+            if (token.kind !== "option")
+                continue;
+            if (seen.has(token.name))
+                throw new Error("duplicate option");
+            seen.add(token.name);
+        }
+    }
+    catch {
+        throw new UploadError("invalid_arguments", "Invalid command options. Use --help; credentials are accepted only through environment or a secret file.");
+    }
+    const { values, positionals } = parsed;
+    if (values.help) {
+        process.stdout.write(HELP);
+        return;
+    }
+    if (positionals.length !== 1 ||
+        positionals[0] !== "upload" ||
+        !values.bundle ||
+        !values["source-map"])
+        throw new UploadError("invalid_arguments", "Use upload with release identity, --bundle and --source-map. See --help.");
+    const prepared = await prepareUpload({
+        platform: values.platform,
+        appVersion: values["app-version"],
+        nativeBuild: values["native-build"],
+        bundleVersion: values["bundle-version"],
+        bundle: values.bundle,
+        sourceMap: values["source-map"],
+        expectedBundleSha256: values["expected-bundle-sha256"],
+        expectedSourceMapSha256: values["expected-source-map-sha256"],
+    });
+    if (values["dry-run"]) {
+        process.stdout.write(`${JSON.stringify({ ok: true, status: "dry_run", manifest_sha256: prepared.manifestSha256, bundle_bytes: prepared.bundle.length, source_map_bytes: prepared.sourceMap.length })}\n`);
+        return;
+    }
+    if (!values.url)
+        throw new UploadError("invalid_arguments", "Supply the HTTPS upload API origin with --url.");
+    if (values["token-file"] && process.env.CRUMB_SOURCE_MAP_TOKEN)
+        throw new UploadError("ambiguous_token", "Choose one credential source: CRUMB_SOURCE_MAP_TOKEN or --token-file.");
+    const token = values["token-file"]
+        ? (await readBoundedFile(values["token-file"], 4098))
+            .toString("utf8")
+            .replace(/\r?\n$/, "")
+        : process.env.CRUMB_SOURCE_MAP_TOKEN;
+    if (!token)
+        throw new UploadError("missing_token", "Set CRUMB_SOURCE_MAP_TOKEN or supply --token-file with a dedicated upload credential.");
+    const result = await upload(prepared, {
+        url: values.url,
+        token,
+        allowLocalhost: values["allow-localhost"] === true,
+    });
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+}
+main().catch((error) => {
+    const safe = error instanceof UploadError
+        ? error
+        : new UploadError("upload_failed", "The upload could not complete. Check the build inputs and retry.");
+    process.stderr.write(`${JSON.stringify({ ok: false, error: { code: safe.code, message: safe.message } })}\n`);
+    process.exitCode = 1;
+});

package/dist/upload.js

@@ -0,0 +1,170 @@
+import { canonicalJson, identity, MAX_ARTIFACT_BYTES, MAX_RESPONSE_BYTES, readBoundedFile, record, safeUrl, sha256, UploadError, validateSourceMap, verifyExpectedHash, } from "./validation.js";
+export async function prepareUpload(options) {
+    if (options.platform !== "ios" && options.platform !== "android")
+        throw new UploadError("invalid_platform", "The platform must be ios or android, including for React Native.");
+    const release = {
+        platform: options.platform,
+        app_version: identity(options.appVersion, 64),
+        native_build: identity(options.nativeBuild, 64),
+        js_bundle_version: identity(options.bundleVersion, 128),
+    };
+    const bundle = await readBoundedFile(options.bundle, MAX_ARTIFACT_BYTES);
+    const sourceMap = await readBoundedFile(options.sourceMap, MAX_ARTIFACT_BYTES);
+    validateSourceMap(sourceMap);
+    const manifest = {
+        schema_version: "1.0",
+        release: { ...release, platform: options.platform },
+        bundle: {
+            byte_size: bundle.length,
+            sha256: verifyExpectedHash(bundle, options.expectedBundleSha256),
+        },
+        source_map: {
+            byte_size: sourceMap.length,
+            sha256: verifyExpectedHash(sourceMap, options.expectedSourceMapSha256),
+        },
+    };
+    return {
+        manifest,
+        manifestSha256: sha256(canonicalJson(manifest)),
+        bundle,
+        sourceMap,
+    };
+}
+const UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/i;
+export async function upload(prepared, options) {
+    const base = safeUrl(options.url, options.allowLocalhost === true, true);
+    if (!/^[\x21-\x7e]{16,4096}$/.test(options.token))
+        throw new UploadError("invalid_token", "Supply a valid source-map upload credential using the environment or a secret file.");
+    const request = options.fetch ?? fetch;
+    const timeoutMs = options.timeoutMs ?? 60_000;
+    async function send(url, init) {
+        try {
+            return await request(url, {
+                ...init,
+                redirect: "error",
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+        }
+        catch {
+            throw new UploadError("network_error", "The upload request did not complete. Check connectivity and rerun the same command to resume safely.");
+        }
+    }
+    async function api(path, body, operation) {
+        const response = await send(new URL(path, base), {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${options.token}`,
+                "content-type": "application/json",
+                "idempotency-key": `source-maps:${prepared.manifestSha256}:${operation}`,
+            },
+            body: canonicalJson(body),
+        });
+        if (!response.ok) {
+            await response.body?.cancel();
+            throw httpError(response.status);
+        }
+        const result = await readJson(response);
+        if (!record(result) ||
+            result.manifest_sha256 !== prepared.manifestSha256 ||
+            typeof result.upload_id !== "string" ||
+            !UUID.test(result.upload_id))
+            throw protocolError();
+        return result;
+    }
+    const initialized = await api("/source-maps/v1/uploads/init", { manifest: prepared.manifest }, "init");
+    if (!record(initialized) || typeof initialized.upload_id !== "string")
+        throw protocolError();
+    const uploadId = initialized.upload_id;
+    if (initialized.status === "verified")
+        return {
+            ok: true,
+            status: "verified",
+            upload_id: uploadId,
+            manifest_sha256: prepared.manifestSha256,
+        };
+    if (initialized.status !== "initialized" ||
+        !Array.isArray(initialized.artifacts) ||
+        initialized.artifacts.length !== 2)
+        throw protocolError();
+    const targets = [];
+    for (const target of initialized.artifacts) {
+        if (!record(target) ||
+            (target.kind !== "bundle" && target.kind !== "source_map") ||
+            target.method !== "PUT" ||
+            typeof target.url !== "string" ||
+            !record(target.headers) ||
+            Object.keys(target.headers).length !== 1 ||
+            target.headers["content-type"] !== "application/octet-stream")
+            throw protocolError();
+        safeUrl(target.url, options.allowLocalhost === true);
+        if (targets.some((existing) => existing.kind === target.kind))
+            throw protocolError();
+        targets.push({ kind: target.kind, url: target.url });
+    }
+    // Validate every destination before sending either private artifact. Credentials
+    // are sent only to the API, never to a signed upload target or redirect.
+    for (const target of targets) {
+        const bytes = target.kind === "bundle" ? prepared.bundle : prepared.sourceMap;
+        const response = await send(target.url, {
+            method: "PUT",
+            headers: { "content-type": "application/octet-stream" },
+            body: new Uint8Array(bytes),
+        });
+        await response.body?.cancel();
+        if (!response.ok)
+            throw new UploadError("artifact_upload_failed", "An artifact upload failed. Rerun the same command to obtain fresh upload locations and resume.");
+    }
+    const completed = await api(`/source-maps/v1/uploads/${uploadId}/complete`, {}, "complete");
+    if (!record(completed) ||
+        completed.status !== "verified" ||
+        completed.upload_id !== uploadId)
+        throw protocolError();
+    return {
+        ok: true,
+        status: "verified",
+        upload_id: uploadId,
+        manifest_sha256: prepared.manifestSha256,
+    };
+}
+async function readJson(response) {
+    const reader = response.body?.getReader();
+    if (!reader)
+        throw protocolError();
+    const chunks = [];
+    let size = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > MAX_RESPONSE_BYTES)
+                throw protocolError();
+            chunks.push(value);
+        }
+        return JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(Buffer.concat(chunks)));
+    }
+    catch {
+        throw protocolError();
+    }
+    finally {
+        await reader.cancel().catch(() => undefined);
+        reader.releaseLock();
+    }
+}
+function protocolError() {
+    return new UploadError("invalid_response", "The upload service returned an invalid response. No verification is assumed; retry with a compatible service.");
+}
+function httpError(status) {
+    if (status === 401 || status === 403)
+        return new UploadError("unauthorized", "The upload credential is invalid, expired or not permitted for this project.");
+    if (status === 409)
+        return new UploadError("release_conflict", "This release identity already has different artifacts. Use the matching build or a new bundle version.");
+    if (status === 413)
+        return new UploadError("artifact_too_large", "The release artifacts exceed the service limits.");
+    if (status === 422)
+        return new UploadError("artifact_rejected", "The release metadata or artifact verification failed. Check the build identity and checksums.");
+    if (status === 429)
+        return new UploadError("rate_limited", "Upload requests are rate limited. Wait before retrying the same command.");
+    return new UploadError("service_unavailable", "The upload service could not finish the request. Retry the same command later.");
+}

package/dist/validation.js

@@ -0,0 +1,166 @@
+import { createHash } from "node:crypto";
+import { open } from "node:fs/promises";
+import { constants } from "node:fs";
+export const MAX_ARTIFACT_BYTES = 25 * 1024 * 1024;
+export const MAX_RESPONSE_BYTES = 64 * 1024;
+export class UploadError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+export function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+export function sha256(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+export function canonicalJson(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    if (record(value))
+        return `{${Object.keys(value)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`)
+            .join(",")}}`;
+    const result = JSON.stringify(value);
+    if (result === undefined)
+        throw new UploadError("invalid_manifest", "The release manifest is invalid.");
+    return result;
+}
+export function identity(value, maximum) {
+    if (!value ||
+        value.length > maximum ||
+        !/^[A-Za-z0-9][A-Za-z0-9._+-]*$/.test(value)) {
+        throw new UploadError("invalid_release", "Supply platform, app version, native build and a unique bundle version using letters, digits, dot, underscore, plus or hyphen.");
+    }
+    return value;
+}
+/** Read only a bounded regular file, even if it changes or grows after stat. */
+export async function readBoundedFile(path, maximum) {
+    let file;
+    try {
+        file = await open(path, constants.O_RDONLY | constants.O_NONBLOCK);
+        const info = await file.stat();
+        if (!info.isFile())
+            throw new UploadError("invalid_file", "Upload inputs must be regular files.");
+        if (info.size === 0 || info.size > maximum)
+            throw new UploadError("invalid_size", "An input is empty or exceeds its size limit.");
+        const buffer = Buffer.alloc(Math.min(info.size + 1, maximum + 1));
+        let offset = 0;
+        while (offset < buffer.length) {
+            const { bytesRead } = await file.read(buffer, offset, buffer.length - offset, null);
+            if (bytesRead === 0)
+                break;
+            offset += bytesRead;
+        }
+        if (offset !== info.size)
+            throw new UploadError("file_changed", "An input changed while being read. Finish the build and retry.");
+        return buffer.subarray(0, offset);
+    }
+    catch (error) {
+        if (error instanceof UploadError)
+            throw error;
+        throw new UploadError("file_unavailable", "An input file could not be read. Check its path and permissions.");
+    }
+    finally {
+        await file?.close();
+    }
+}
+export function verifyExpectedHash(bytes, expected) {
+    const actual = sha256(bytes);
+    if (expected !== undefined &&
+        (!/^[a-f0-9]{64}$/.test(expected) || expected !== actual)) {
+        throw new UploadError("checksum_mismatch", "An input does not match its expected SHA-256. Use the artifacts from the same release build.");
+    }
+    return actual;
+}
+/** Check the v3 JSON structure without executing bundles or resolving source URLs. */
+export function validateSourceMap(bytes) {
+    let value;
+    try {
+        value = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    }
+    catch {
+        throw new UploadError("invalid_source_map", "The source map must be valid UTF-8 JSON.");
+    }
+    let count = 0;
+    function validate(map, depth) {
+        if (++count > 1024 || depth > 8 || !record(map) || map.version !== 3)
+            throw invalidMap();
+        if (map.file !== undefined && typeof map.file !== "string")
+            throw invalidMap();
+        if (map.sourceRoot !== undefined && typeof map.sourceRoot !== "string")
+            throw invalidMap();
+        if (map.sections !== undefined) {
+            if (!Array.isArray(map.sections) ||
+                map.sections.length === 0 ||
+                map.mappings !== undefined ||
+                map.sources !== undefined)
+                throw invalidMap();
+            let previousLine = -1;
+            let previousColumn = -1;
+            for (const section of map.sections) {
+                if (!record(section) ||
+                    section.url !== undefined ||
+                    !record(section.offset))
+                    throw invalidMap();
+                const { line, column } = section.offset;
+                if (typeof line !== "number" ||
+                    typeof column !== "number" ||
+                    !Number.isSafeInteger(line) ||
+                    !Number.isSafeInteger(column) ||
+                    line < 0 ||
+                    column < 0)
+                    throw invalidMap();
+                if (line < previousLine ||
+                    (line === previousLine && column <= previousColumn))
+                    throw invalidMap();
+                previousLine = line;
+                previousColumn = column;
+                validate(section.map, depth + 1);
+            }
+            return;
+        }
+        if (typeof map.mappings !== "string" ||
+            !/^[A-Za-z0-9+/;,]*$/.test(map.mappings) ||
+            !Array.isArray(map.sources) ||
+            !map.sources.every((source) => typeof source === "string"))
+            throw invalidMap();
+        if (map.names !== undefined &&
+            (!Array.isArray(map.names) ||
+                !map.names.every((name) => typeof name === "string")))
+            throw invalidMap();
+        if (map.sourcesContent !== undefined &&
+            (!Array.isArray(map.sourcesContent) ||
+                map.sourcesContent.length !== map.sources.length ||
+                !map.sourcesContent.every((source) => source === null || typeof source === "string")))
+            throw invalidMap();
+    }
+    validate(value, 0);
+}
+function invalidMap() {
+    return new UploadError("invalid_source_map", "Use a version 3 source map with inline sections only. Check its sources, mappings and offsets.");
+}
+export function safeUrl(input, allowLocal, base = false) {
+    let url;
+    try {
+        url = new URL(input);
+    }
+    catch {
+        throw invalidUrl();
+    }
+    const loopback = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+    if ((url.protocol !== "https:" &&
+        !(allowLocal && loopback && url.protocol === "http:")) ||
+        url.username ||
+        url.password ||
+        url.hash ||
+        (base && (url.search || url.pathname !== "/")))
+        throw invalidUrl();
+    return url;
+}
+function invalidUrl() {
+    return new UploadError("invalid_url", "Use an HTTPS API origin without credentials, path, query or fragment. HTTP loopback requires --allow-localhost.");
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@crumbsdk/source-maps",
+  "version": "0.0.1-rc.4",
+  "description": "Explicit, CI-safe bundle and source-map uploads for Crumb",
+  "type": "module",
+  "bin": {
+    "crumb-source-maps": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alexander126/crumb.git",
+    "directory": "packages/source-maps"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc && node -e \"require('node:fs').chmodSync('dist/cli.js', 0o755)\"",
+    "typecheck": "tsc --noEmit",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "pack:check": "npm run build && node test/pack-check.mjs",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "26.2.0",
+    "typescript": "7.0.2"
+  }
+}