@ggui-ai/gadget-signing 0.1.0-rc.1

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 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 Support. 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 support.
+
+   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 Loqu, Inc. (Guuey)
+
+   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,86 @@
+# @ggui-ai/gadget-signing
+
+> Gadget bundle signing + verification for the ggui gadget marketplace.
+
+Signs and verifies the `bundle.js` files that authors publish to a ggui
+gadget registry. The Ed25519 path is pure-TS via `@noble/ed25519` +
+`@noble/hashes` — no `node:crypto` dependency, so that path is safe to
+import from browser contexts (e.g. client-side signature verification in
+the iframe runtime).
+
+## Two signing paths
+
+| Path                          | Audience        | Trust root                                                |
+| ----------------------------- | --------------- | --------------------------------------------------------- |
+| **Ed25519 author key**        | private gadgets | Author's local private key; public key stored by registry |
+| **sigstore (cosign + Rekor)** | public gadgets  | Keyless Fulcio cert via OIDC + Rekor transparency log     |
+
+The sigstore path is a full implementation built on the upstream
+`sigstore` package. The publisher acquires an OIDC token out-of-band and
+passes it in; signing walks the keyless Fulcio + Rekor flow, and
+verification resolves trust material via TUF and enforces an optional
+caller-supplied identity policy.
+
+## Wire format
+
+```ts
+type GadgetSignature = Ed25519Signature | SigstoreSignature;
+
+interface Ed25519Signature {
+  readonly algorithm: "ed25519";
+  readonly bundleSha384: string; // base64(sha384(bundleBytes))
+  readonly signature: string; // base64(ed25519.sign(digest, privateKey))
+  readonly publicKeyId: string; // stable id derived from the public key
+  readonly signedAt: string; // ISO 8601
+}
+```
+
+SHA-384 (not 512) matches the SRI hash the iframe runtime enforces on
+`<script>` tags, so the signature attests to the exact digest the browser
+recomputes at load time.
+
+## Usage
+
+### Ed25519 author-key path
+
+```ts
+import {
+  generateEd25519Keypair,
+  signBundleEd25519,
+  verifyBundleEd25519,
+} from "@ggui-ai/gadget-signing";
+
+// Author (keygen)
+const { publicKey, privateKey, publicKeyId } = await generateEd25519Keypair();
+// publicKey + publicKeyId go to the registry; privateKey stays local.
+
+// Publisher
+const signature = await signBundleEd25519({
+  bundleBytes,
+  privateKey,
+  publicKeyId,
+});
+
+// Install / runtime
+const result = await verifyBundleEd25519({ bundleBytes, signature, publicKey });
+if (!result.valid) throw new Error(`signature invalid: ${result.reason}`);
+```
+
+### Sigstore keyless path
+
+```ts
+import { signBundleSigstore, verifyBundleSigstore } from "@ggui-ai/gadget-signing";
+
+// Publisher — identityToken is a pre-acquired OIDC JWT.
+const signature = await signBundleSigstore({ bundleBytes, identityToken });
+
+// Install — optionally pin the expected signer identity.
+const result = await verifyBundleSigstore({
+  bundleBytes,
+  signature,
+  expectedIdentity: { subject: /^https:\/\/github\.com\/my-org\// },
+});
+```
+
+The sigstore code path uses `node:crypto` transitively and is therefore
+Node-only. The Ed25519 path stays browser-safe.

package/dist/index.d.ts

@@ -0,0 +1,283 @@
+/**
+ * `@ggui-ai/gadget-signing` — gadget bundle signing + verification for the
+ * ggui gadget marketplace.
+ *
+ * Two signing schemes:
+ * 1. **Ed25519 author keys** (private gadgets) — full implementation. The
+ *    author manages a 32-byte Ed25519 private key locally; the registry
+ *    stores the public key per author identity. The publisher hashes the
+ *    bundle with SHA-384, signs the hash with their private key, and
+ *    uploads `bundle.js` + `bundle.js.sig`. The install CLI downloads
+ *    both, looks up the author's public key, and verifies. The SRI hash
+ *    on the `<script>` tag closes the loop end-to-end.
+ *
+ * 2. **sigstore (cosign + Rekor)** (public gadgets) — full implementation
+ *    via the upstream `sigstore` package (which composes
+ *    `@sigstore/sign` + `@sigstore/verify` + `@sigstore/tuf`). The
+ *    publisher acquires an OIDC token out-of-band (env var or browser
+ *    flow at the CLI seam), passes it in, and the `sign` call walks the
+ *    keyless Fulcio + Rekor flow. The serialized cosign Bundle (per
+ *    `@sigstore/bundle` v0.3 spec) becomes `SigstoreSignature.bundle`.
+ *    Verification calls `sigstore.verify` which uses TUF to resolve the
+ *    trust material at runtime, then enforces an optional caller-supplied
+ *    identity policy.
+ *
+ * Cryptography for the Ed25519 path uses `@noble/ed25519` +
+ * `@noble/hashes` — pure-TS, audited, browser-safe; no `node:crypto`.
+ * The sigstore path uses `node:crypto` transitively through the
+ * `sigstore` package, so the sigstore code path is Node-only. Ed25519
+ * remains browser-safe.
+ */
+/** Ed25519 signature over the SHA-384 hash of a gadget bundle. */
+export interface Ed25519Signature {
+    readonly algorithm: "ed25519";
+    /** Base64 SHA-384 digest of the bundle bytes. */
+    readonly bundleSha384: string;
+    /** Base64 Ed25519 signature over `bundleSha384` decoded bytes. */
+    readonly signature: string;
+    /** Public-key identifier — the registry's stable handle for the key. */
+    readonly publicKeyId: string;
+    /** ISO 8601 timestamp at signing time. */
+    readonly signedAt: string;
+}
+/**
+ * Sigstore/cosign signature.
+ *
+ * Carries a full serialized Sigstore bundle (per
+ * `@sigstore/bundle` v0.3 spec) — including the cert chain, the
+ * Rekor inclusion proof, and the messageSignature payload. Verify
+ * reconstitutes via `@sigstore/verify` and runs the canonical
+ * Sigstore verification flow (Fulcio cert chain + Rekor inclusion +
+ * signature over the digest).
+ *
+ * `bundleSha384` is intentionally retained alongside the cosign
+ * bundle (redundant with `messageSignature.messageDigest` inside the
+ * bundle) so the server can run a fast tamper-detection pass before
+ * paying for the full Sigstore-verify path.
+ */
+export interface SigstoreSignature {
+    readonly algorithm: "sigstore-cosign";
+    /** Base64 SHA-384 digest of the bundle bytes — fast tamper check. */
+    readonly bundleSha384: string;
+    /**
+     * Serialized cosign bundle (JSON-encoded per `@sigstore/bundle`'s
+     * `Bundle` schema, v0.3 mediaType
+     * `application/vnd.dev.sigstore.bundle+json;version=0.3`). Opaque
+     * at the wire layer; deserialized by `verifyBundleSigstore` via
+     * `@sigstore/bundle`'s parser.
+     */
+    readonly bundle: string;
+    /** ISO 8601 timestamp at signing time. */
+    readonly signedAt: string;
+}
+/** Discriminated union of all signature shapes. */
+export type GadgetSignature = Ed25519Signature | SigstoreSignature;
+/**
+ * Runtime check that `value` is a well-formed {@link Ed25519Signature}.
+ * Structural shape only — does NOT cryptographically verify.
+ */
+export declare function isEd25519Signature(value: unknown): value is Ed25519Signature;
+/**
+ * Runtime check that `value` is a well-formed {@link SigstoreSignature}.
+ * Structural shape only — does NOT cryptographically verify the embedded
+ * bundle. Use {@link verifyBundleSigstore} for the full trust-chain check.
+ */
+export declare function isSigstoreSignature(value: unknown): value is SigstoreSignature;
+/**
+ * Discriminated guard over the {@link GadgetSignature} union. Use this
+ * at request boundaries — switching on `value.algorithm` after the
+ * guard passes narrows to the correct variant for downstream dispatch.
+ */
+export declare function isGadgetSignature(value: unknown): value is GadgetSignature;
+/**
+ * Canonical-JSON serialization for blueprint signatures. Recursive
+ * lexicographic key-sort at every nesting depth, then `JSON.stringify`.
+ *
+ * Lives here (not in publish/install/server) because all three sites
+ * sign or verify against the same byte sequence. Any drift between
+ * server-side canonicalization and CLI-side canonicalization breaks
+ * blueprint signatures silently — pulling the impl into one place
+ * eliminates that drift class.
+ *
+ * NOT RFC-8785 compliant: the v1 manifest schema doesn't carry
+ * non-ASCII strings, exotic numbers, or unicode normalization
+ * surfaces, so the simpler shape suffices. If a future blueprint
+ * manifest grows nested objects with order-sensitive content that
+ * RFC-8785 would canonicalize differently, both this function and
+ * the publish + install sites need to swap to a real RFC-8785 impl
+ * in lock-step.
+ */
+export declare function canonicalJson(value: unknown): string;
+/**
+ * Derive a stable public-key identifier from a 32-byte Ed25519 public key.
+ * `base64(sha256(publicKey))[:16]`. Used as the registry's stable handle
+ * for a stored author public key.
+ */
+export declare function derivePublicKeyId(publicKey: Uint8Array): string;
+/**
+ * Derive the Ed25519 public key from a 32-byte private key. Deterministic
+ * (Ed25519 public keys are functions of the private key). Used by the
+ * publish CLI when re-reading a stored private key from disk between
+ * sessions — recompute the public half rather than store both halves.
+ */
+export declare function publicKeyFromPrivate(privateKey: Uint8Array): Promise<Uint8Array>;
+/**
+ * Generate a fresh 32-byte Ed25519 keypair plus its derived `publicKeyId`.
+ *
+ * Use only in CLI flows (`ggui gadget keygen`) — the private key MUST be
+ * stored by the author locally and NEVER uploaded to the registry.
+ */
+export declare function generateEd25519Keypair(): Promise<{
+    publicKey: Uint8Array;
+    privateKey: Uint8Array;
+    publicKeyId: string;
+}>;
+/**
+ * Sign a gadget bundle with an Ed25519 author key.
+ *
+ * Hashes the bundle with SHA-384 and signs the digest. SHA-384 (not 512)
+ * matches the SRI hash that the iframe-runtime enforces on `<script>` tags,
+ * so the signature attests to the exact same digest the browser will
+ * recompute at install/load time.
+ */
+export declare function signBundleEd25519(input: {
+    bundleBytes: Uint8Array;
+    privateKey: Uint8Array;
+    publicKeyId: string;
+}): Promise<Ed25519Signature>;
+/** Result of a verification call. Discriminated by `valid`. */
+export type VerifyResult = {
+    valid: true;
+} | {
+    valid: false;
+    reason: string;
+};
+/**
+ * Verify a gadget bundle against an Ed25519 author key.
+ *
+ * Checks (in order):
+ * 1. Recompute SHA-384 of `bundleBytes` and confirm it matches
+ *    `signature.bundleSha384`. Catches bundle tampering.
+ * 2. Confirm `signature.publicKeyId === derivePublicKeyId(publicKey)`.
+ *    Catches `publicKeyId` substitution (e.g., the registry returning a
+ *    different author's public key alongside the original sig).
+ * 3. Run the Ed25519 verify over the digest. Catches signature tampering
+ *    and wrong-key cases.
+ */
+export declare function verifyBundleEd25519(input: {
+    bundleBytes: Uint8Array;
+    signature: Ed25519Signature;
+    publicKey: Uint8Array;
+}): Promise<VerifyResult>;
+/** Discriminated error codes thrown by {@link signBundleSigstore}. */
+export type SigstoreSigningErrorCode = "oidc_invalid" | "fulcio_error" | "rekor_error" | "unknown";
+/**
+ * Error class thrown by {@link signBundleSigstore} on signing failure.
+ * The `code` field is enumerated so callers can route to recovery paths
+ * (re-acquire OIDC token, retry against a different Rekor instance, …).
+ *
+ * Verification failures DO NOT throw — they project to
+ * `{ valid: false, reason }` instead. Only the signing seam exposes
+ * structured errors, since signing failure modes (network down, OIDC
+ * expired, Rekor 5xx) drive caller retry behavior and the verification
+ * seam wants the `VerifyResult` discriminator at every callsite.
+ */
+export declare class SigstoreSigningError extends Error {
+    readonly code: SigstoreSigningErrorCode;
+    readonly cause?: unknown;
+    constructor(code: SigstoreSigningErrorCode, message: string, cause?: unknown);
+}
+/** Input to {@link signBundleSigstore}. */
+export interface SignBundleSigstoreInput {
+    /** Raw gadget bundle bytes — the signature attests to these bytes. */
+    readonly bundleBytes: Uint8Array;
+    /**
+     * Pre-acquired OIDC JWT. Caller is responsible for obtaining it
+     * (env var, `--identity-token` flag, interactive browser flow) — all
+     * resolved at the CLI seam, not here. Keeping the token at the call
+     * site (rather than reading env in this package) keeps the signing
+     * function pure + testable.
+     */
+    readonly identityToken: string;
+    /**
+     * Optional override of the Sigstore endpoint set. Defaults to the
+     * production Fulcio + Rekor URLs (`sigstore.dev`). Tests pass mock
+     * URLs via `@sigstore/mock`; staging traffic points at the
+     * sigstaging.dev instances.
+     */
+    readonly endpoints?: {
+        readonly fulcioURL?: string;
+        readonly rekorURL?: string;
+    };
+}
+/**
+ * Sign a gadget bundle via the Sigstore keyless flow.
+ *
+ * 1. SHA-384 the bundle bytes (matches the Ed25519 path and the SRI hash
+ *    the iframe-runtime enforces). The digest becomes the fast
+ *    tamper-check payload stored in `bundleSha384`.
+ * 2. Hand the bundle bytes + OIDC token to `sigstore.sign()`. Under the
+ *    hood: ephemeral keypair → Fulcio short-lived signing cert tied to
+ *    the OIDC identity → Rekor inclusion entry → bundle assembled.
+ * 3. Serialize the bundle to JSON (per `@sigstore/bundle` v0.3 schema)
+ *    and pack into `SigstoreSignature`.
+ */
+export declare function signBundleSigstore(input: SignBundleSigstoreInput): Promise<SigstoreSignature>;
+/** Input to {@link verifyBundleSigstore}. */
+export interface VerifyBundleSigstoreInput {
+    /** Raw bundle bytes — must match the bytes that were signed. */
+    readonly bundleBytes: Uint8Array;
+    /** The signature returned by {@link signBundleSigstore}. */
+    readonly signature: SigstoreSignature;
+    /**
+     * Optional identity-claim assertion. When present, the verifier rejects
+     * bundles whose embedded Fulcio cert doesn't claim the expected OIDC
+     * identity — `subject` is matched against the cert's
+     * `subjectAlternativeName`. Use this to encode "publisher X is the
+     * only legitimate signer" trust models at install time.
+     *
+     * The `subject` may be a string (literal equality, per Sigstore's
+     * `certificateIdentityURI` / `certificateIdentityEmail` semantics) or
+     * a RegExp (the verifier pre-validates against the deserialized
+     * bundle SAN before delegating to upstream, since the upstream API
+     * supports only string equality).
+     */
+    readonly expectedIdentity?: {
+        readonly subject: string | RegExp;
+        /** OIDC issuer URL (e.g. `https://token.actions.githubusercontent.com`). */
+        readonly issuer?: string;
+    };
+    /**
+     * Optional endpoint overrides — only meaningful when paired with a
+     * non-prod TUF mirror. Production gadgets verify against the prod
+     * Sigstore TUF root.
+     */
+    readonly endpoints?: {
+        readonly fulcioURL?: string;
+        readonly rekorURL?: string;
+    };
+}
+/**
+ * Verify a sigstore-signed gadget bundle.
+ *
+ * 1. **Fast tamper check** — recompute SHA-384 of `bundleBytes` and
+ *    compare to `signature.bundleSha384`. Mismatch short-circuits the
+ *    full Sigstore-verify path. (Redundant with `messageDigest` inside
+ *    the bundle, but cheap.)
+ * 2. **Deserialize** the embedded bundle via `bundleFromJSON`.
+ * 3. **RegExp identity pre-check** — when `expectedIdentity.subject` is
+ *    a RegExp, walk the bundle's verification material to extract the
+ *    SAN URI and assert the match here (upstream `sigstore.verify` only
+ *    accepts literal strings).
+ * 4. **Upstream verify** — `sigstore.verify(bundle, data, opts)` runs
+ *    the full Sigstore flow: TUF trust material, Fulcio cert-chain
+ *    validation, Rekor inclusion proof, signature over the digest, and
+ *    (if `expectedIdentity` was provided as a string) the identity
+ *    policy. Throws on any failure.
+ *
+ * Returns a {@link VerifyResult} discriminated by `valid` — never
+ * throws on policy failure (only on programmer error like a malformed
+ * `signature.bundle` JSON).
+ */
+export declare function verifyBundleSigstore(input: VerifyBundleSigstoreInput): Promise<VerifyResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,536 @@
+/**
+ * `@ggui-ai/gadget-signing` — gadget bundle signing + verification for the
+ * ggui gadget marketplace.
+ *
+ * Two signing schemes:
+ * 1. **Ed25519 author keys** (private gadgets) — full implementation. The
+ *    author manages a 32-byte Ed25519 private key locally; the registry
+ *    stores the public key per author identity. The publisher hashes the
+ *    bundle with SHA-384, signs the hash with their private key, and
+ *    uploads `bundle.js` + `bundle.js.sig`. The install CLI downloads
+ *    both, looks up the author's public key, and verifies. The SRI hash
+ *    on the `<script>` tag closes the loop end-to-end.
+ *
+ * 2. **sigstore (cosign + Rekor)** (public gadgets) — full implementation
+ *    via the upstream `sigstore` package (which composes
+ *    `@sigstore/sign` + `@sigstore/verify` + `@sigstore/tuf`). The
+ *    publisher acquires an OIDC token out-of-band (env var or browser
+ *    flow at the CLI seam), passes it in, and the `sign` call walks the
+ *    keyless Fulcio + Rekor flow. The serialized cosign Bundle (per
+ *    `@sigstore/bundle` v0.3 spec) becomes `SigstoreSignature.bundle`.
+ *    Verification calls `sigstore.verify` which uses TUF to resolve the
+ *    trust material at runtime, then enforces an optional caller-supplied
+ *    identity policy.
+ *
+ * Cryptography for the Ed25519 path uses `@noble/ed25519` +
+ * `@noble/hashes` — pure-TS, audited, browser-safe; no `node:crypto`.
+ * The sigstore path uses `node:crypto` transitively through the
+ * `sigstore` package, so the sigstore code path is Node-only. Ed25519
+ * remains browser-safe.
+ */
+import { signAsync, verifyAsync, getPublicKeyAsync, utils } from "@noble/ed25519";
+import { sha384, sha256 } from "@noble/hashes/sha2";
+import { bundleFromJSON, bundleToJSON, } from "@sigstore/bundle";
+import * as sigstoreClient from "sigstore";
+// ---------------------------------------------------------------------------
+// Canonical type guards.
+//
+// The signature guards live in one canonical home so wire-shape
+// changes flow uniformly to every consumer (registry publish op,
+// install path). `isGadgetSignature` is the discriminated guard
+// callers use at the request boundary.
+// ---------------------------------------------------------------------------
+/**
+ * Runtime check that `value` is a well-formed {@link Ed25519Signature}.
+ * Structural shape only — does NOT cryptographically verify.
+ */
+export function isEd25519Signature(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    // `as Partial<Ed25519Signature>` (not `Record<string, unknown>`) is
+    // the honest narrow: it makes each field optional with the correct
+    // declared type, so the typeof checks below catch shape mismatches
+    // without lying about what the input MAY be.
+    const v = value;
+    return (v.algorithm === "ed25519" &&
+        typeof v.bundleSha384 === "string" &&
+        typeof v.signature === "string" &&
+        typeof v.publicKeyId === "string" &&
+        typeof v.signedAt === "string");
+}
+/**
+ * Runtime check that `value` is a well-formed {@link SigstoreSignature}.
+ * Structural shape only — does NOT cryptographically verify the embedded
+ * bundle. Use {@link verifyBundleSigstore} for the full trust-chain check.
+ */
+export function isSigstoreSignature(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const v = value;
+    return (v.algorithm === "sigstore-cosign" &&
+        typeof v.bundleSha384 === "string" &&
+        typeof v.bundle === "string" &&
+        typeof v.signedAt === "string");
+}
+/**
+ * Discriminated guard over the {@link GadgetSignature} union. Use this
+ * at request boundaries — switching on `value.algorithm` after the
+ * guard passes narrows to the correct variant for downstream dispatch.
+ */
+export function isGadgetSignature(value) {
+    return isEd25519Signature(value) || isSigstoreSignature(value);
+}
+// ---------------------------------------------------------------------------
+// Base64 helpers — browser-safe, no `node:buffer` dependency.
+// ---------------------------------------------------------------------------
+function bytesToBase64(bytes) {
+    let binary = "";
+    for (let i = 0; i < bytes.length; i++) {
+        binary += String.fromCharCode(bytes[i]);
+    }
+    // `btoa` exists in browsers and modern Node (>=16) globals.
+    return btoa(binary);
+}
+function base64ToBytes(b64) {
+    const binary = atob(b64);
+    const out = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        out[i] = binary.charCodeAt(i);
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Canonical JSON — the bit-stable form blueprint signatures cover.
+// ---------------------------------------------------------------------------
+/**
+ * Canonical-JSON serialization for blueprint signatures. Recursive
+ * lexicographic key-sort at every nesting depth, then `JSON.stringify`.
+ *
+ * Lives here (not in publish/install/server) because all three sites
+ * sign or verify against the same byte sequence. Any drift between
+ * server-side canonicalization and CLI-side canonicalization breaks
+ * blueprint signatures silently — pulling the impl into one place
+ * eliminates that drift class.
+ *
+ * NOT RFC-8785 compliant: the v1 manifest schema doesn't carry
+ * non-ASCII strings, exotic numbers, or unicode normalization
+ * surfaces, so the simpler shape suffices. If a future blueprint
+ * manifest grows nested objects with order-sensitive content that
+ * RFC-8785 would canonicalize differently, both this function and
+ * the publish + install sites need to swap to a real RFC-8785 impl
+ * in lock-step.
+ */
+export function canonicalJson(value) {
+    return JSON.stringify(canonicalSort(value));
+}
+function canonicalSort(value) {
+    if (Array.isArray(value)) {
+        return value.map(canonicalSort);
+    }
+    if (value !== null && typeof value === "object") {
+        const entries = Object.entries(value).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        const out = {};
+        for (const [k, v] of entries)
+            out[k] = canonicalSort(v);
+        return out;
+    }
+    return value;
+}
+// ---------------------------------------------------------------------------
+// Public-key ID derivation — stable, deterministic.
+// ---------------------------------------------------------------------------
+/**
+ * Derive a stable public-key identifier from a 32-byte Ed25519 public key.
+ * `base64(sha256(publicKey))[:16]`. Used as the registry's stable handle
+ * for a stored author public key.
+ */
+export function derivePublicKeyId(publicKey) {
+    if (publicKey.length !== 32) {
+        throw new Error(`derivePublicKeyId: expected 32-byte Ed25519 public key, got ${publicKey.length}`);
+    }
+    const digest = sha256(publicKey);
+    return bytesToBase64(digest).slice(0, 16);
+}
+/**
+ * Derive the Ed25519 public key from a 32-byte private key. Deterministic
+ * (Ed25519 public keys are functions of the private key). Used by the
+ * publish CLI when re-reading a stored private key from disk between
+ * sessions — recompute the public half rather than store both halves.
+ */
+export async function publicKeyFromPrivate(privateKey) {
+    if (privateKey.length !== 32) {
+        throw new Error(`publicKeyFromPrivate: expected 32-byte Ed25519 private key, got ${privateKey.length}`);
+    }
+    return getPublicKeyAsync(privateKey);
+}
+// ---------------------------------------------------------------------------
+// Ed25519 path — full implementation.
+// ---------------------------------------------------------------------------
+/**
+ * Generate a fresh 32-byte Ed25519 keypair plus its derived `publicKeyId`.
+ *
+ * Use only in CLI flows (`ggui gadget keygen`) — the private key MUST be
+ * stored by the author locally and NEVER uploaded to the registry.
+ */
+export async function generateEd25519Keypair() {
+    const privateKey = utils.randomPrivateKey();
+    const publicKey = await getPublicKeyAsync(privateKey);
+    return {
+        publicKey,
+        privateKey,
+        publicKeyId: derivePublicKeyId(publicKey),
+    };
+}
+/**
+ * Sign a gadget bundle with an Ed25519 author key.
+ *
+ * Hashes the bundle with SHA-384 and signs the digest. SHA-384 (not 512)
+ * matches the SRI hash that the iframe-runtime enforces on `<script>` tags,
+ * so the signature attests to the exact same digest the browser will
+ * recompute at install/load time.
+ */
+export async function signBundleEd25519(input) {
+    const { bundleBytes, privateKey, publicKeyId } = input;
+    if (privateKey.length !== 32) {
+        throw new Error(`signBundleEd25519: expected 32-byte Ed25519 private key, got ${privateKey.length}`);
+    }
+    const digest = sha384(bundleBytes);
+    const sigBytes = await signAsync(digest, privateKey);
+    return {
+        algorithm: "ed25519",
+        bundleSha384: bytesToBase64(digest),
+        signature: bytesToBase64(sigBytes),
+        publicKeyId,
+        signedAt: new Date().toISOString(),
+    };
+}
+/**
+ * Verify a gadget bundle against an Ed25519 author key.
+ *
+ * Checks (in order):
+ * 1. Recompute SHA-384 of `bundleBytes` and confirm it matches
+ *    `signature.bundleSha384`. Catches bundle tampering.
+ * 2. Confirm `signature.publicKeyId === derivePublicKeyId(publicKey)`.
+ *    Catches `publicKeyId` substitution (e.g., the registry returning a
+ *    different author's public key alongside the original sig).
+ * 3. Run the Ed25519 verify over the digest. Catches signature tampering
+ *    and wrong-key cases.
+ */
+export async function verifyBundleEd25519(input) {
+    const { bundleBytes, signature, publicKey } = input;
+    if (publicKey.length !== 32) {
+        return {
+            valid: false,
+            reason: `expected 32-byte Ed25519 public key, got ${publicKey.length}`,
+        };
+    }
+    const recomputed = sha384(bundleBytes);
+    const recomputedB64 = bytesToBase64(recomputed);
+    if (recomputedB64 !== signature.bundleSha384) {
+        return {
+            valid: false,
+            reason: "bundle hash mismatch (bundleBytes tampered or wrong bundle)",
+        };
+    }
+    const expectedKeyId = derivePublicKeyId(publicKey);
+    if (expectedKeyId !== signature.publicKeyId) {
+        return {
+            valid: false,
+            reason: `publicKeyId mismatch: signature claims '${signature.publicKeyId}', provided key derives '${expectedKeyId}'`,
+        };
+    }
+    let sigBytes;
+    try {
+        sigBytes = base64ToBytes(signature.signature);
+    }
+    catch (err) {
+        return {
+            valid: false,
+            reason: `malformed signature base64: ${err.message}`,
+        };
+    }
+    let ok;
+    try {
+        ok = await verifyAsync(sigBytes, recomputed, publicKey);
+    }
+    catch (err) {
+        return {
+            valid: false,
+            reason: `signature verification threw: ${err.message}`,
+        };
+    }
+    if (!ok) {
+        return { valid: false, reason: "Ed25519 signature does not verify" };
+    }
+    return { valid: true };
+}
+/**
+ * Error class thrown by {@link signBundleSigstore} on signing failure.
+ * The `code` field is enumerated so callers can route to recovery paths
+ * (re-acquire OIDC token, retry against a different Rekor instance, …).
+ *
+ * Verification failures DO NOT throw — they project to
+ * `{ valid: false, reason }` instead. Only the signing seam exposes
+ * structured errors, since signing failure modes (network down, OIDC
+ * expired, Rekor 5xx) drive caller retry behavior and the verification
+ * seam wants the `VerifyResult` discriminator at every callsite.
+ */
+export class SigstoreSigningError extends Error {
+    code;
+    cause;
+    constructor(code, message, cause) {
+        super(message);
+        this.name = "SigstoreSigningError";
+        this.code = code;
+        if (cause !== undefined)
+            this.cause = cause;
+    }
+}
+/**
+ * Sign a gadget bundle via the Sigstore keyless flow.
+ *
+ * 1. SHA-384 the bundle bytes (matches the Ed25519 path and the SRI hash
+ *    the iframe-runtime enforces). The digest becomes the fast
+ *    tamper-check payload stored in `bundleSha384`.
+ * 2. Hand the bundle bytes + OIDC token to `sigstore.sign()`. Under the
+ *    hood: ephemeral keypair → Fulcio short-lived signing cert tied to
+ *    the OIDC identity → Rekor inclusion entry → bundle assembled.
+ * 3. Serialize the bundle to JSON (per `@sigstore/bundle` v0.3 schema)
+ *    and pack into `SigstoreSignature`.
+ */
+export async function signBundleSigstore(input) {
+    const { bundleBytes, identityToken, endpoints } = input;
+    const digest = sha384(bundleBytes);
+    const bundleSha384 = bytesToBase64(digest);
+    let serialized;
+    try {
+        serialized = await sigstoreClient.sign(Buffer.from(bundleBytes), {
+            identityToken,
+            ...(endpoints?.fulcioURL ? { fulcioURL: endpoints.fulcioURL } : {}),
+            ...(endpoints?.rekorURL ? { rekorURL: endpoints.rekorURL } : {}),
+            tlogUpload: true,
+        });
+    }
+    catch (err) {
+        throw classifySigstoreSigningError(err);
+    }
+    return {
+        algorithm: "sigstore-cosign",
+        bundleSha384,
+        bundle: JSON.stringify(serialized),
+        signedAt: new Date().toISOString(),
+    };
+}
+/**
+ * Heuristic classifier mapping upstream sigstore errors onto our
+ * enumerated `SigstoreSigningErrorCode`. The upstream library throws a
+ * mix of `InternalError` (network-level) and `Error` subclasses; the
+ * codes attached to `InternalError` (`CA_*`, `TLOG_*`, …) are stable
+ * enough to map onto our coarser categories.
+ */
+function classifySigstoreSigningError(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    // `InternalError` from `@sigstore/sign` carries a string `code` field
+    // like `'CA_CREATE_SIGNING_CERTIFICATE_ERROR'` or `'TLOG_CREATE_ENTRY_ERROR'`.
+    const upstreamCode = err !== null &&
+        typeof err === "object" &&
+        "code" in err &&
+        typeof err.code === "string"
+        ? err.code
+        : undefined;
+    if (upstreamCode?.includes("IDENTITY") || /identity|oidc|jwt/i.test(message)) {
+        return new SigstoreSigningError("oidc_invalid", `OIDC identity token rejected: ${message}`, err);
+    }
+    if (upstreamCode?.includes("CA_") || /fulcio/i.test(message)) {
+        return new SigstoreSigningError("fulcio_error", `Fulcio signing-cert issuance failed: ${message}`, err);
+    }
+    if (upstreamCode?.includes("TLOG") || /rekor|tlog/i.test(message)) {
+        return new SigstoreSigningError("rekor_error", `Rekor transparency-log write failed: ${message}`, err);
+    }
+    return new SigstoreSigningError("unknown", `sigstore signing failed: ${message}`, err);
+}
+/**
+ * Verify a sigstore-signed gadget bundle.
+ *
+ * 1. **Fast tamper check** — recompute SHA-384 of `bundleBytes` and
+ *    compare to `signature.bundleSha384`. Mismatch short-circuits the
+ *    full Sigstore-verify path. (Redundant with `messageDigest` inside
+ *    the bundle, but cheap.)
+ * 2. **Deserialize** the embedded bundle via `bundleFromJSON`.
+ * 3. **RegExp identity pre-check** — when `expectedIdentity.subject` is
+ *    a RegExp, walk the bundle's verification material to extract the
+ *    SAN URI and assert the match here (upstream `sigstore.verify` only
+ *    accepts literal strings).
+ * 4. **Upstream verify** — `sigstore.verify(bundle, data, opts)` runs
+ *    the full Sigstore flow: TUF trust material, Fulcio cert-chain
+ *    validation, Rekor inclusion proof, signature over the digest, and
+ *    (if `expectedIdentity` was provided as a string) the identity
+ *    policy. Throws on any failure.
+ *
+ * Returns a {@link VerifyResult} discriminated by `valid` — never
+ * throws on policy failure (only on programmer error like a malformed
+ * `signature.bundle` JSON).
+ */
+export async function verifyBundleSigstore(input) {
+    const { bundleBytes, signature, expectedIdentity } = input;
+    // 1. Fast tamper check.
+    const recomputed = sha384(bundleBytes);
+    const recomputedB64 = bytesToBase64(recomputed);
+    if (recomputedB64 !== signature.bundleSha384) {
+        return {
+            valid: false,
+            reason: "bundle hash mismatch (bundleBytes tampered or wrong bundle)",
+        };
+    }
+    // 2. Deserialize cosign bundle. The wire shape stores the JSON-encoded
+    // bundle as a string; `bundleFromJSON` takes the parsed object.
+    let parsedBundle;
+    try {
+        parsedBundle = JSON.parse(signature.bundle);
+    }
+    catch (err) {
+        return {
+            valid: false,
+            reason: `malformed bundle JSON: ${err.message}`,
+        };
+    }
+    try {
+        // Validate-only round-trip — throws ValidationError on bad shape.
+        bundleToJSON(bundleFromJSON(parsedBundle));
+    }
+    catch (err) {
+        return {
+            valid: false,
+            reason: `invalid sigstore bundle shape: ${err.message}`,
+        };
+    }
+    // 3. RegExp identity pre-check. Upstream `sigstore.verify` accepts
+    // only literal-equality identity strings, so a RegExp expectation
+    // must be enforced here against the bundle's embedded SAN.
+    if (expectedIdentity && expectedIdentity.subject instanceof RegExp) {
+        const san = extractSANFromBundle(parsedBundle);
+        if (san === undefined) {
+            return {
+                valid: false,
+                reason: "expectedIdentity.subject is RegExp but bundle has no subjectAlternativeName to match against",
+            };
+        }
+        if (!expectedIdentity.subject.test(san)) {
+            return {
+                valid: false,
+                reason: `identity mismatch: bundle SAN '${san}' does not match expected pattern ${expectedIdentity.subject}`,
+            };
+        }
+    }
+    // 4. Run the full upstream verify.
+    try {
+        const verifyOpts = {};
+        if (expectedIdentity) {
+            if (typeof expectedIdentity.subject === "string") {
+                // Use email-shaped vs URI-shaped routing per upstream's two
+                // policy fields. Both enforce a SAN match.
+                if (expectedIdentity.subject.includes("@")) {
+                    verifyOpts.certificateIdentityEmail =
+                        expectedIdentity.subject;
+                }
+                else {
+                    verifyOpts.certificateIdentityURI =
+                        expectedIdentity.subject;
+                }
+            }
+            if (expectedIdentity.issuer) {
+                verifyOpts.certificateIssuer =
+                    expectedIdentity.issuer;
+            }
+        }
+        await sigstoreClient.verify(parsedBundle, Buffer.from(bundleBytes), verifyOpts);
+        return { valid: true };
+    }
+    catch (err) {
+        return {
+            valid: false,
+            reason: `sigstore verification failed: ${err.message}`,
+        };
+    }
+}
+/**
+ * Reach into a serialized sigstore Bundle and pull the
+ * `subjectAlternativeName` from the embedded X.509 cert (if any). Used
+ * by the RegExp-identity pre-check; production verification still goes
+ * through the upstream verifier for the actual cryptographic check.
+ *
+ * Returns `undefined` if the bundle has no cert (e.g. publicKey-only
+ * bundle) or no extractable SAN. Uses lightweight base64-DER scanning —
+ * defers to the upstream verifier for the trust-chain semantics.
+ */
+function extractSANFromBundle(bundle) {
+    const material = bundle.verificationMaterial;
+    if (!material)
+        return undefined;
+    let certB64;
+    if ("certificate" in material && material.certificate) {
+        certB64 = material.certificate.rawBytes;
+    }
+    else if ("x509CertificateChain" in material &&
+        material.x509CertificateChain &&
+        material.x509CertificateChain.certificates.length > 0) {
+        certB64 = material.x509CertificateChain.certificates[0]?.rawBytes;
+    }
+    if (!certB64)
+        return undefined;
+    // Very lightweight SAN extraction: decode DER, locate the SAN
+    // extension OID (2.5.29.17), and pull the first URI/email-shaped
+    // ASCII run. This is intentionally tolerant — exact parsing happens
+    // in `@sigstore/verify` downstream.
+    let der;
+    try {
+        der = base64ToBytes(certB64);
+    }
+    catch {
+        return undefined;
+    }
+    // OID 2.5.29.17 (subjectAltName) DER prefix: 06 03 55 1d 11.
+    const sanOid = [0x06, 0x03, 0x55, 0x1d, 0x11];
+    let idx = -1;
+    for (let i = 0; i < der.length - sanOid.length; i++) {
+        let match = true;
+        for (let j = 0; j < sanOid.length; j++) {
+            if (der[i + j] !== sanOid[j]) {
+                match = false;
+                break;
+            }
+        }
+        if (match) {
+            idx = i;
+            break;
+        }
+    }
+    if (idx === -1)
+        return undefined;
+    // After the OID DER there's a BOOLEAN (critical, optional) then an
+    // OCTET STRING wrapping a SEQUENCE of GeneralName. Scan forward for
+    // the first printable ASCII run containing a URI or email shape.
+    const tail = der.subarray(idx + sanOid.length);
+    let buf = "";
+    const uriPattern = /[a-zA-Z][a-zA-Z0-9+.-]*:[^\s]+|[\w.+-]+@[\w.-]+/;
+    for (let i = 0; i < tail.length; i++) {
+        const b = tail[i];
+        if (b >= 0x20 && b <= 0x7e) {
+            buf += String.fromCharCode(b);
+        }
+        else {
+            if (buf.length >= 3) {
+                const m = buf.match(uriPattern);
+                if (m)
+                    return m[0];
+            }
+            buf = "";
+        }
+    }
+    if (buf.length >= 3) {
+        const m = buf.match(uriPattern);
+        if (m)
+            return m[0];
+    }
+    return undefined;
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@ggui-ai/gadget-signing",
+  "version": "0.1.0-rc.1",
+  "description": "Gadget bundle signing + verification for the ggui gadget marketplace. Ed25519 author-key path + sigstore/cosign keyless path. Pure-TS @noble crypto for Ed25519 — browser-safe.",
+  "license": "Apache-2.0",
+  "keywords": [
+    "ggui",
+    "gadgets",
+    "code-signing",
+    "ed25519",
+    "sigstore",
+    "cosign",
+    "supply-chain"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@noble/ed25519": "^2.2.0",
+    "@noble/hashes": "^1.6.0",
+    "@sigstore/bundle": "^4.0.0",
+    "sigstore": "^4.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^3.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ggui-ai/ggui.git",
+    "directory": "packages/gadget-signing"
+  },
+  "homepage": "https://github.com/ggui-ai/ggui/tree/main/packages/gadget-signing",
+  "bugs": {
+    "url": "https://github.com/ggui-ai/ggui/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "author": "ggui contributors <hello@ggui.ai>",
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src --ext .ts --max-warnings 0",
+    "clean": "rm -rf dist"
+  }
+}