@ggui-ai/registry-core 0.1.0-rc.1

package/dist/ops/list-versions.d.ts

@@ -0,0 +1,58 @@
+/**
+ * `listArtifactVersions` — pure op for `GET /pkg/{scope}/{name}`.
+ * Mirrors {@link readArtifact}'s structure — same authn injection
+ * point, same storage seam, same discriminated-union result.
+ *
+ * Flow:
+ *   1. Point-read the metadata row via {@link RegistryStorage.getArtifactMetadata}.
+ *      Missing metadata → 404 (`not_found`).
+ *   2. Fetch all version rows via {@link RegistryStorage.listArtifactVersions}.
+ *   3. Filter out private rows for unauthenticated callers — same gate
+ *      as the read op's `visibility === 'private' && authn === undefined`
+ *      branch. We do NOT 403 on a fully-private artifact for an unauthed
+ *      caller; we 200 with `versions: []` so the wire response doesn't
+ *      leak the existence of a private artifact (cf. GitHub's 404-on-
+ *      private-repo behaviour).
+ *   4. Sort by semver DESC so the latest version is first. Yanked rows
+ *      are NOT filtered — they stay in the list with `yanked: true`
+ *      so the UI can show "this version was yanked".
+ *   5. Project the row → {@link VersionListEntry} shape (drop heavy
+ *      fields: manifest, compiledDigest, manifestSig).
+ *
+ * **Why not gate on metadata.visibility?** A private artifact might
+ * have a public version (visibility lives on every version row
+ * independently). Authn-gating at the metadata level would over-block.
+ * The version-by-version filter in step 3 is the precise gate.
+ */
+import type { ListVersionsErrorBody, ListVersionsResponse } from '../types.js';
+import type { AuthnContext } from '../interfaces/authn.js';
+import type { RegistryStorage } from '../interfaces/registry-storage.js';
+export interface ListArtifactVersionsInput {
+    /**
+     * `<scope>/<name>` — the install identifier. Scope MUST start with `@`.
+     * Cloud API Gateway path params drop the leading `@`; the cloud
+     * Lambda shell re-prepends before calling this op.
+     */
+    readonly artifactId: string;
+}
+export interface ListArtifactVersionsDeps {
+    readonly storage: RegistryStorage;
+    /**
+     * Optional — when undefined, the op filters `private` versions OUT
+     * of the response. Authenticated callers see every version they own
+     * (the storage layer's row-level visibility filter is the source of
+     * truth; this op just honours it).
+     */
+    readonly authn?: AuthnContext;
+}
+export type ListArtifactVersionsResult = {
+    readonly ok: true;
+    readonly status: 200;
+    readonly body: ListVersionsResponse;
+} | {
+    readonly ok: false;
+    readonly status: 400 | 404 | 500;
+    readonly body: ListVersionsErrorBody;
+};
+export declare function listArtifactVersions(input: ListArtifactVersionsInput, deps: ListArtifactVersionsDeps): Promise<ListArtifactVersionsResult>;
+//# sourceMappingURL=list-versions.d.ts.map

package/dist/ops/list-versions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-versions.d.ts","sourceRoot":"","sources":["../../src/ops/list-versions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,KAAK,EAEV,qBAAqB,EAErB,oBAAoB,EAErB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAGzE,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,YAAY,CAAC;CAC/B;AAED,MAAM,MAAM,0BAA0B,GAClC;IACE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;CACrC,GACD;IACE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;CACtC,CAAC;AAEN,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,yBAAyB,EAChC,IAAI,EAAE,wBAAwB,GAC7B,OAAO,CAAC,0BAA0B,CAAC,CA6DrC"}

package/dist/ops/list-versions.js

@@ -0,0 +1,60 @@
+import { compareSemver } from '../utils/semver.js';
+export async function listArtifactVersions(input, deps) {
+    if (typeof input.artifactId !== 'string' || input.artifactId.length === 0) {
+        return errorResult(400, 'invalid_request', 'missing artifactId');
+    }
+    // Step 1 — metadata existence check. A missing metadata row is the
+    // "no such artifact" signal. We rely on the publish op writing a
+    // metadata row on every successful publish (idempotent upsert).
+    let metadataExists = false;
+    try {
+        const metadata = await deps.storage.getArtifactMetadata(input.artifactId);
+        metadataExists = metadata !== null;
+    }
+    catch (err) {
+        return errorResult(500, 'server_error', `failed to read metadata: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!metadataExists) {
+        return errorResult(404, 'not_found', `no such artifact: ${input.artifactId}`);
+    }
+    // Step 2 — fetch all version rows.
+    let rows;
+    try {
+        rows = await deps.storage.listArtifactVersions(input.artifactId);
+    }
+    catch (err) {
+        return errorResult(500, 'server_error', `failed to list versions: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // Step 3 — visibility filter. Unauthed callers see only public rows;
+    // authed callers see everything (finer org-membership gating is a
+    // future concern — for now, "authed" === "can see your own private
+    // rows" is captured by the verified caller subject being non-null).
+    const visibleRows = [];
+    for (const row of rows) {
+        if (row.visibility === 'private' && deps.authn === undefined)
+            continue;
+        visibleRows.push(row);
+    }
+    // Step 4 — semver DESC sort. `compareSemver(a, b)` returns -1/0/1
+    // matching ascending order; flip the sign for DESC.
+    const sorted = [...visibleRows].sort((a, b) => -compareSemver(a.version, b.version));
+    // Step 5 — project to the lightweight wire shape.
+    const versions = sorted.map(rowToEntry);
+    return {
+        ok: true,
+        status: 200,
+        body: { artifactId: input.artifactId, versions },
+    };
+}
+function rowToEntry(row) {
+    return {
+        version: row.version,
+        publishedAt: row.publishedAt,
+        yanked: row.yanked === true,
+        kind: row.kind,
+        visibility: row.visibility,
+    };
+}
+function errorResult(status, error, message) {
+    return { ok: false, status, body: { error, message } };
+}

package/dist/ops/publish.d.ts

@@ -0,0 +1,70 @@
+import { type GadgetSignature } from '@ggui-ai/gadget-signing';
+import type { PublishErrorBody, PublishResponseBody } from '../types.js';
+import type { BlueprintProbeRunner } from './conformance.js';
+import type { AuthnContext } from '../interfaces/authn.js';
+import type { BundleStorage } from '../interfaces/bundle-storage.js';
+import type { RegistryStorage } from '../interfaces/registry-storage.js';
+/**
+ * Hard cap on the base64-DECODED bundle byte length. 5 MiB matches the
+ * apigwv2 Lambda integration payload ceiling (6 MB) minus headroom for
+ * the manifest + signature + JSON envelope. OSS server enforces the
+ * same ceiling for parity (a cloud-published bundle MUST be installable
+ * against an OSS-mirrored registry without re-bundling).
+ */
+export declare const MAX_BUNDLE_BYTES: number;
+export interface PublishArtifactInput {
+    /** Unvalidated request body — the op parses + validates. */
+    readonly manifest: unknown;
+    /** Base64-encoded gadget bundle bytes. Required if `kind === 'gadget'`. */
+    readonly bundle?: string;
+    /** Base64 SHA-384 digest of the decoded bundle bytes. Client-supplied; the op re-verifies. */
+    readonly bundleSha384?: string;
+    /**
+     * Author signature. Discriminated union over `algorithm`:
+     *   - `'ed25519'`         → private-gadget path, AuthorKeys-rooted
+     *     trust chain.
+     *   - `'sigstore-cosign'` → public-gadget path, Fulcio cert +
+     *     Rekor inclusion trust chain.
+     *
+     * The op dispatches on `algorithm` after the signature-shape guard.
+     */
+    readonly signature: GadgetSignature;
+}
+export interface PublishArtifactDeps {
+    readonly storage: RegistryStorage;
+    readonly bundleStorage: BundleStorage;
+    readonly authn: AuthnContext;
+    readonly clock: () => Date;
+    /**
+     * Hostname the install CLI talks to — embedded into the success
+     * response's `installCommand`. Cloud: API Gateway custom domain (e.g.
+     * `dev.registry.sandbox.ggui.ai`). OSS: `localhost:9001` etc.
+     *
+     * No protocol prefix — the op composes `https://` for cloud and
+     * `http://` for `localhost`/`127.0.0.1`.
+     */
+    readonly registryHostname: string;
+    /**
+     * Optional runtime probe for blueprint manifests. Static gates
+     * always run; the probe additionally compiles + renders the
+     * blueprint default export with the manifest's fixtureProps in a
+     * sandboxed Node `vm` + React server-renderer.
+     *
+     * Wire from `@ggui-ai/blueprint-probe` in OSS and cloud Lambda
+     * environments where the runtime probe is desired. Leaving it
+     * unset skips the probe — useful for the standalone conformance
+     * HTTP endpoint that should not pay for react-dom.
+     */
+    readonly blueprintProbe?: BlueprintProbeRunner;
+}
+export type PublishArtifactResult = {
+    readonly ok: true;
+    readonly status: 201;
+    readonly body: PublishResponseBody;
+} | {
+    readonly ok: false;
+    readonly status: 400 | 401 | 403 | 409 | 413 | 500;
+    readonly body: PublishErrorBody;
+};
+export declare function publishArtifact(input: PublishArtifactInput, deps: PublishArtifactDeps): Promise<PublishArtifactResult>;
+//# sourceMappingURL=publish.d.ts.map

package/dist/ops/publish.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publish.d.ts","sourceRoot":"","sources":["../../src/ops/publish.ts"],"names":[],"mappings":"AA2BA,OAAO,EAKL,KAAK,eAAe,EAErB,MAAM,yBAAyB,CAAC;AAGjC,OAAO,KAAK,EAIV,gBAAgB,EAEhB,mBAAmB,EACpB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EACV,oBAAoB,EAErB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAMzE;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,QAAkB,CAAC;AAEhD,MAAM,WAAW,oBAAoB;IACnC,4DAA4D;IAC5D,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,8FAA8F;IAC9F,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;;;;;OAQG;IACH,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;CACrC;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC;IAC3B;;;;;;;OAOG;IACH,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,oBAAoB,CAAC;CAChD;AAED,MAAM,MAAM,qBAAqB,GAC7B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAA;CAAE,GAC/E;IACE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;IACnD,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;CACjC,CAAC;AAEN,wBAAsB,eAAe,CACnC,KAAK,EAAE,oBAAoB,EAC3B,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC,qBAAqB,CAAC,CA0XhC"}

package/dist/ops/publish.js

@@ -0,0 +1,417 @@
+/**
+ * `publishArtifact` — pure op for `POST /publish`.
+ *
+ * Flow (short-circuits on first failure):
+ *
+ *   1.  Validate {@link AuthnContext} present (transport enforces auth
+ *       before calling; this is defense-in-depth).
+ *   2.  Parse + validate the manifest via `parseArtifactManifest`.
+ *   3.  Decode + size-check the bundle (gadgets only).
+ *   4.  Recompute SHA-384 of the bundle bytes; compare to client claim.
+ *   5.  Re-run the conformance gate ({@link checkConformance}).
+ *   6.  Verify the Ed25519 author signature — look up the
+ *       {@link AuthorKeyRow} by `(subject, keyId)`, base64-decode the
+ *       stored public key, call `verifyBundleEd25519`.
+ *   7.  Insert the {@link ArtifactVersionRow} via
+ *       {@link RegistryStorage.putArtifactVersionIfAbsent}. Re-publish
+ *       (collision) returns 409 `version_exists`.
+ *   8.  Upload the bundle + signature + manifest via
+ *       {@link BundleStorage}.
+ *   9.  Upsert the {@link ArtifactsMetadataRow} — only rewrites
+ *       `latestVersion` when the new version is the highest semver.
+ *   10. Return 201 with the wire-locked {@link PublishResponseBody}.
+ */
+import { parseArtifactManifest, } from '@ggui-ai/artifact-manifest';
+import { canonicalJson, isGadgetSignature, verifyBundleEd25519, verifyBundleSigstore, } from '@ggui-ai/gadget-signing';
+import { bundleHostScheme } from '@ggui-ai/protocol';
+import { ZodError } from 'zod';
+import { ARTIFACTS_METADATA_SK } from '../types.js';
+import { safeBase64Decode, sha384Base64 } from '../utils/base64.js';
+import { compareSemver } from '../utils/semver.js';
+import { compileBlueprint } from './compile.js';
+import { checkConformance } from './conformance.js';
+/**
+ * Hard cap on the base64-DECODED bundle byte length. 5 MiB matches the
+ * apigwv2 Lambda integration payload ceiling (6 MB) minus headroom for
+ * the manifest + signature + JSON envelope. OSS server enforces the
+ * same ceiling for parity (a cloud-published bundle MUST be installable
+ * against an OSS-mirrored registry without re-bundling).
+ */
+export const MAX_BUNDLE_BYTES = 5 * 1024 * 1024;
+export async function publishArtifact(input, deps) {
+    // 1. Authn — transport enforces before calling, but defensive read.
+    if (typeof deps.authn.subject !== 'string' || deps.authn.subject.length === 0) {
+        return error(401, 'unauthorized', 'request is missing a verified caller subject');
+    }
+    // 1b. Signature shape — transport pre-decoded the JSON envelope; we
+    // still validate the structured object before the cryptographic
+    // path. The discriminated guard accepts both Ed25519 (private) and
+    // sigstore-cosign (public) shapes; the verify-time dispatch on
+    // `signature.algorithm` selects the correct trust chain.
+    if (!isGadgetSignature(input.signature)) {
+        return error(400, 'signature_invalid', 'request body is missing or malformed `signature` (expected Ed25519Signature or SigstoreSignature shape)');
+    }
+    // 2. Manifest schema
+    let manifest;
+    try {
+        manifest = parseArtifactManifest(input.manifest);
+    }
+    catch (err) {
+        if (err instanceof ZodError) {
+            const first = err.issues[0];
+            const path = (first?.path ?? []).map((seg) => typeof seg === 'symbol' ? String(seg) : seg);
+            return error(400, 'manifest_invalid', first?.message ?? 'manifest failed schema validation', { path, issues: err.issues });
+        }
+        return error(400, 'manifest_invalid', `manifest failed validation: ${errorMessage(err)}`);
+    }
+    const artifactId = `${manifest.scope}/${manifest.name}`;
+    const version = manifest.version;
+    // 3. Bundle decode + size (gadgets only)
+    let bundleBytes;
+    if (manifest.kind === 'gadget') {
+        if (input.bundle === undefined || input.bundle.length === 0) {
+            return error(400, 'bundle_required', 'gadget publish requires a base64-encoded `bundle` field — blueprint manifests carry source inline, but gadgets ship compiled bytes');
+        }
+        const decoded = safeBase64Decode(input.bundle);
+        if (decoded === undefined) {
+            return error(400, 'manifest_invalid', '`bundle` field is not valid base64');
+        }
+        if (decoded.byteLength > MAX_BUNDLE_BYTES) {
+            return error(413, 'bundle_too_large', `bundle is ${decoded.byteLength} bytes; maximum is ${MAX_BUNDLE_BYTES} bytes (${MAX_BUNDLE_BYTES / (1024 * 1024)} MiB)`);
+        }
+        bundleBytes = decoded;
+        // 4. Hash check
+        if (input.bundleSha384 === undefined || input.bundleSha384.length === 0) {
+            return error(400, 'bundle_hash_mismatch', 'gadget publish requires `bundleSha384` (base64 SHA-384 digest of the decoded bundle bytes)');
+        }
+        const recomputed = sha384Base64(bundleBytes);
+        if (recomputed !== input.bundleSha384) {
+            return error(400, 'bundle_hash_mismatch', 'server-computed SHA-384 of the bundle does not match the client-supplied `bundleSha384`', { expected: recomputed, received: input.bundleSha384 });
+        }
+    }
+    // 5. Conformance gate
+    const conformanceBundleText = bundleBytes === undefined
+        ? undefined
+        : Buffer.from(bundleBytes.buffer, bundleBytes.byteOffset, bundleBytes.byteLength).toString('utf8');
+    const conformanceResult = checkConformance({
+        manifest,
+        bundle: conformanceBundleText,
+    });
+    if (!conformanceResult.ok) {
+        return conformanceFailureResponse(conformanceResult.errors);
+    }
+    // 5b. Blueprint runtime probe — opt-in via deps.blueprintProbe.
+    // Static gates already accepted the manifest above; the probe runs
+    // only for blueprints and only when the caller wired a runner.
+    // Probe failures surface through the same `conformance_failed`
+    // envelope so wire consumers don't branch on a separate error code.
+    if (manifest.kind === 'blueprint' && deps.blueprintProbe !== undefined) {
+        const probeResult = await deps.blueprintProbe.probe(manifest);
+        if (!probeResult.ok) {
+            return conformanceFailureResponse(probeResult.errors);
+        }
+    }
+    // 6. Signature verification — dispatch on the locked discriminator.
+    //
+    // `authorPublicKey` is the publisher identity persisted on the
+    // version row (`ArtifactVersionRow.authorPublicKey`). For Ed25519
+    // it's the base64 32-byte public key; for sigstore-cosign it's
+    // the leaf-cert PEM extracted from the bundle.
+    const bytesForSignature = bundleBytes ?? new TextEncoder().encode(canonicalJson(manifest));
+    let authorPublicKey;
+    if (input.signature.algorithm === 'ed25519') {
+        // Private gadgets — AuthorKeys-rooted trust chain.
+        const authorKeyRow = await deps.storage.getAuthorKey(deps.authn.subject, input.signature.publicKeyId);
+        if (authorKeyRow === null) {
+            return error(403, 'unknown_key', `no registered AuthorKeys row for publisher \`${deps.authn.subject}\` + keyId \`${input.signature.publicKeyId}\` — run \`ggui keygen\` and register the public key before publishing`);
+        }
+        const publicKeyBytes = safeBase64Decode(authorKeyRow.publicKeyBase64);
+        if (publicKeyBytes === undefined) {
+            return error(500, 'internal', 'author key row is malformed');
+        }
+        const verifyResult = await verifyBundleEd25519({
+            bundleBytes: bytesForSignature,
+            signature: input.signature,
+            publicKey: publicKeyBytes,
+        });
+        if (!verifyResult.valid) {
+            return error(400, 'signature_invalid', verifyResult.reason);
+        }
+        authorPublicKey = authorKeyRow.publicKeyBase64;
+    }
+    else {
+        // Public gadgets — sigstore (Fulcio + Rekor) trust chain.
+        // Identity claim: trust ANY valid OIDC identity at publish-time —
+        // the publisher is already authenticated by the transport layer
+        // ahead of this op. Install-time consumers CAN tighten via
+        // `--verify-identity <pattern>` (CLI install flag); that's a
+        // separate trust decision controlled by the install operator, not
+        // the publisher.
+        const verifyResult = await verifyBundleSigstore({
+            bundleBytes: bytesForSignature,
+            signature: input.signature,
+        });
+        if (!verifyResult.valid) {
+            return error(400, 'signature_invalid', verifyResult.reason);
+        }
+        // Persist the leaf cert PEM on the version row so install
+        // consumers can render the signer identity. Extracted inline from
+        // the bundle's `verificationMaterial.x509CertificateChain.certificates[0]`
+        // for now — TODO: replace with `extractSigstoreLeafCertPem(signature)`
+        // from `@ggui-ai/gadget-signing` so the parsing logic lives next to
+        // the bundle-format knowledge (single source of truth for the
+        // cosign-bundle shape).
+        const leafCertPem = extractSigstoreLeafCertPemInline(input.signature);
+        if (leafCertPem === undefined) {
+            return error(400, 'signature_invalid', 'sigstore verify succeeded but bundle is missing `verificationMaterial.x509CertificateChain.certificates[0].rawBytes` — cannot pin author identity on the version row');
+        }
+        authorPublicKey = leafCertPem;
+    }
+    // 6b. Blueprint compile boundary (TSX → JS).
+    // Blueprints compile at publish time; the canonical compiled JS bytes
+    // are stored content-addressed in {@link CompiledBlobRow} and the
+    // version row only carries the digest pointer. Two-layer storage
+    // gives dedup (byte-identical compiled output reuses one blob row)
+    // and federation-ready content-addressable identity.
+    //
+    // Compile failure surfaces through the same `conformance_failed`
+    // wire envelope as the static gates — same shape, same code
+    // (`blueprint_compile_error`). The static gate already runs a
+    // best-effort `transformSync` to catch the same class of errors;
+    // this is the load-bearing run (its output is what's persisted).
+    let compiledDigest;
+    let compiledBlobToWrite;
+    if (manifest.kind === 'blueprint') {
+        const compileResult = compileBlueprint(manifest.source);
+        if (!compileResult.ok) {
+            return conformanceFailureResponse(compileResult.errors.map((e) => ({
+                code: 'blueprint_compile_error',
+                message: e.message,
+                ...(e.location !== undefined ? { detail: { location: e.location } } : {}),
+            })));
+        }
+        compiledDigest = compileResult.compiledDigest;
+        compiledBlobToWrite = {
+            compiledDigest: compileResult.compiledDigest,
+            compiledBytes: compileResult.compiledBytes,
+            compiledSize: compileResult.compiledSize,
+            refCount: 1,
+            // Persist the publisher's signature envelope inline on the blob
+            // row so a hosted install path can re-verify without a second
+            // fetch. Stored as a JSON-encoded `GadgetSignature` discriminated
+            // union; the install path runs `JSON.parse` + `isGadgetSignature`
+            // before dispatching to verifyBundleEd25519 / verifyBundleSigstore.
+            manifestSig: JSON.stringify(input.signature),
+            // compiledSig still reserved — a registry-rooted sigstore
+            // signature over the compiled bytes is a future enhancement.
+            createdAt: deps.clock().toISOString(),
+        };
+    }
+    // 7. Atomic commit.
+    //
+    // For blueprints — version row + compiled-blob row land under one
+    // logical transaction via `commitVersionAndBlob`. The DDB impl uses
+    // `TransactWriteItems` so the all-or-nothing guarantee holds at the
+    // service level; memory + filesystem impls get atomicity from the
+    // single-threaded JS event loop.
+    //
+    // For gadgets — no compiled-blob row, so we still use the simple
+    // conditional version-row insert. (Adding a synthetic blob row for
+    // gadgets just to share the code path would widen the schema; the
+    // discriminator on `kind` is cleaner.)
+    //
+    // Either way: the version-row conditional `attribute_not_exists` is
+    // the load-bearing concurrency primitive. On conflict, return 409
+    // `version_exists` immediately — the publisher's idempotent retry path.
+    const nowIso = deps.clock().toISOString();
+    const sriHash = bundleBytes === undefined ? undefined : `sha384-${sha384Base64(bundleBytes)}`;
+    const bundleUrl = bundleBytes === undefined
+        ? undefined
+        : deps.bundleStorage.bundleUrl(manifest.scope, manifest.name, version);
+    const signatureUrl = bundleBytes === undefined
+        ? undefined
+        : deps.bundleStorage.signatureUrl(manifest.scope, manifest.name, version);
+    const versionRow = {
+        artifactId,
+        version,
+        manifest,
+        kind: manifest.kind,
+        visibility: manifest.visibility,
+        bundleUrl,
+        bundleSri: sriHash,
+        signatureUrl,
+        ...(compiledDigest !== undefined ? { compiledDigest } : {}),
+        authorPublicKey,
+        publishedAt: nowIso,
+        publishedBy: deps.authn.subject,
+    };
+    if (compiledBlobToWrite !== undefined) {
+        // Blueprint path — atomic two-row commit.
+        let commitResult;
+        try {
+            commitResult = await deps.storage.commitVersionAndBlob(versionRow, compiledBlobToWrite);
+        }
+        catch (err) {
+            return error(500, 'internal', `failed to commit version + compiled-blob rows for ${artifactId}@${version}: ${errorMessage(err)}`);
+        }
+        if (!commitResult.ok) {
+            return error(409, 'version_exists', `${artifactId}@${version} is already published — versions are immutable. Publish a new version instead.`);
+        }
+    }
+    else {
+        // Gadget path — single conditional version-row insert.
+        const insertResult = await deps.storage.putArtifactVersionIfAbsent(versionRow);
+        if (!insertResult.ok) {
+            return error(409, 'version_exists', `${artifactId}@${version} is already published — versions are immutable. Publish a new version instead.`);
+        }
+    }
+    // 8. Upload bundle + signature + manifest
+    let manifestUrl;
+    try {
+        if (bundleBytes !== undefined) {
+            await deps.bundleStorage.putBundle(manifest.scope, manifest.name, version, bundleBytes);
+            await deps.bundleStorage.putSignature(manifest.scope, manifest.name, version, input.signature);
+        }
+        manifestUrl = await deps.bundleStorage.putManifest(manifest.scope, manifest.name, version, manifest);
+    }
+    catch (err) {
+        return error(500, 'internal', `failed to upload artifact: ${errorMessage(err)}`);
+    }
+    // 9. Upsert Plugins metadata row.
+    // Only rewrite `latestVersion` when the new version is the highest
+    // semver. Race-condition note: between the get and the put, another
+    // concurrent publisher could update the row. We accept rare
+    // last-writer-wins on `latestVersion` — per-version row INSERT
+    // remains strongly conditional, which is the load-bearing invariant.
+    const existing = await deps.storage.getArtifactMetadata(artifactId);
+    const shouldUpdateLatest = existing === null || compareSemver(version, existing.latestVersion) > 0;
+    if (shouldUpdateLatest) {
+        // Denormalized search field — a gadget package's primary (first)
+        // export name. The package may export several hooks/components;
+        // the manifest's `exports[]` is the source of truth.
+        const primaryExport = manifest.kind === 'gadget' ? manifest.exports[0] : undefined;
+        const metadataRow = {
+            artifactId,
+            sk: ARTIFACTS_METADATA_SK,
+            kind: manifest.kind,
+            latestVersion: version,
+            description: manifest.description,
+            tags: manifest.tags,
+            visibility: manifest.visibility,
+            hook: primaryExport === undefined
+                ? undefined
+                : 'hook' in primaryExport
+                    ? primaryExport.hook
+                    : primaryExport.component,
+            authorName: manifest.author?.name,
+            publishedAt: nowIso,
+            publishedBy: deps.authn.subject,
+        };
+        try {
+            await deps.storage.putArtifactMetadata(metadataRow);
+        }
+        catch (err) {
+            return error(500, 'internal', `failed to write Plugins metadata row: ${errorMessage(err)}`);
+        }
+    }
+    // 10. Success
+    return {
+        ok: true,
+        status: 201,
+        body: {
+            artifactId,
+            version,
+            manifestUrl,
+            bundleUrl,
+            signatureUrl,
+            installCommand: buildInstallCommand(artifactId, version, deps.registryHostname, manifest.kind),
+        },
+    };
+}
+/** Compose the install command. Loopback hosts use http://; everything else https://. */
+function buildInstallCommand(artifactId, version, registryHostname, kind) {
+    // Loopback hosts get `http://`. Symmetric with the push-time
+    // `resolveGadgetUrls` resolver in `@ggui-ai/mcp-server-handlers` —
+    // install + render MUST agree on scheme for local-dev / sandbox
+    // workflows, otherwise the iframe blocks mixed content.
+    return `ggui ${kind} install ${artifactId}@${version} --registry=${bundleHostScheme(registryHostname)}://${registryHostname}`;
+}
+function errorMessage(err) {
+    if (err instanceof Error)
+        return err.message;
+    return String(err);
+}
+function error(status, code, message, detail) {
+    return {
+        ok: false,
+        status,
+        body: detail === undefined ? { error: code, message } : { error: code, message, detail },
+    };
+}
+/**
+ * Extract the Fulcio leaf cert's base64 raw bytes from a serialized
+ * cosign bundle (per `@sigstore/bundle` v0.3 spec). Returns `undefined`
+ * if the bundle is malformed or missing the cert chain.
+ *
+ * Inline today — TODO: pull this into `@ggui-ai/gadget-signing` as
+ * `extractSigstoreLeafCertPem` so the bundle-format knowledge sits
+ * next to the verify impl. The install CLI carries an identical
+ * helper today; both should collapse to the single canonical export.
+ */
+function extractSigstoreLeafCertPemInline(signature) {
+    let parsed;
+    try {
+        parsed = JSON.parse(signature.bundle);
+    }
+    catch {
+        return undefined;
+    }
+    if (parsed === null || typeof parsed !== 'object')
+        return undefined;
+    const verificationMaterial = parsed
+        .verificationMaterial;
+    if (verificationMaterial === null || typeof verificationMaterial !== 'object') {
+        return undefined;
+    }
+    const chain = verificationMaterial
+        .x509CertificateChain;
+    if (chain === null || typeof chain !== 'object')
+        return undefined;
+    const certificates = chain.certificates;
+    if (!Array.isArray(certificates) || certificates.length === 0)
+        return undefined;
+    const leaf = certificates[0];
+    if (leaf === null || typeof leaf !== 'object')
+        return undefined;
+    const rawBytes = leaf.rawBytes;
+    if (typeof rawBytes !== 'string' || rawBytes.length === 0)
+        return undefined;
+    return rawBytes;
+}
+/**
+ * Translate a {@link ConformanceResponseBody} error list into a 400
+ * `PublishArtifactResult`. Used by both the static-gate failure path
+ * and the runtime-probe failure path so the wire shape is identical
+ * regardless of which gate caught the issue.
+ *
+ * The first failure's sub-discriminator is hoisted to the wire body's
+ * TOP level (alongside `error: 'conformance_failed'`) so callers can
+ * branch without parsing nested JSON. The full error list stays in
+ * `detail.errors` for verbose rendering.
+ */
+function conformanceFailureResponse(errors) {
+    const conformanceFailureCode = errors[0]?.code;
+    const body = conformanceFailureCode === undefined
+        ? {
+            error: 'conformance_failed',
+            message: 'submission failed the registry conformance gate',
+            detail: { errors },
+        }
+        : {
+            error: 'conformance_failed',
+            message: 'submission failed the registry conformance gate',
+            conformanceFailureCode,
+            detail: { errors },
+        };
+    return { ok: false, status: 400, body };
+}

package/dist/ops/read.d.ts

@@ -0,0 +1,52 @@
+/**
+ * `readArtifact` — pure op for `GET /pkg/{scope}/{name}/{version}`.
+ * A shared op that both this server and the hosted registry project
+ * through their respective transport shells.
+ *
+ * Flow:
+ *   1. Point-read the version row via {@link RegistryStorage.getArtifactVersion}.
+ *   2. Enforce row `visibility`: `private` → require an {@link AuthnContext}.
+ *   3. Yanked → 410 with the manifest still in the body (audit-friendly).
+ *   4. For blueprints, resolve the {@link CompiledBlobRow} via
+ *      `row.compiledDigest` (two-layer content-addressed storage). A
+ *      missing blob when the pointer is set is a critical storage
+ *      inconsistency — the op returns 500 rather than silently
+ *      omitting `compiledBytes`.
+ *   5. Project the row + blob into the {@link ReadPkgResponse} wire shape.
+ */
+import type { ReadErrorBody, ReadPkgResponse } from '../types.js';
+import type { AuthnContext } from '../interfaces/authn.js';
+import type { RegistryStorage } from '../interfaces/registry-storage.js';
+export interface ReadArtifactInput {
+    /**
+     * `<scope>/<name>` — the install identifier. Scope MUST start with `@`.
+     * Cloud API Gateway path params drop the leading `@`; the cloud
+     * Lambda shell re-prepends before calling this op.
+     */
+    readonly artifactId: string;
+    readonly version: string;
+}
+export interface ReadArtifactDeps {
+    readonly storage: RegistryStorage;
+    /**
+     * Optional — when undefined, the op rejects `private` rows with 403.
+     * Cloud transport extracts from the JWT authorizer; OSS extracts from
+     * the bearer authn middleware.
+     */
+    readonly authn?: AuthnContext;
+}
+export type ReadArtifactResult = {
+    readonly ok: true;
+    readonly status: 200;
+    readonly body: ReadPkgResponse;
+} | {
+    readonly ok: false;
+    readonly status: 410;
+    readonly body: ReadPkgResponse;
+} | {
+    readonly ok: false;
+    readonly status: 400 | 403 | 404 | 500;
+    readonly body: ReadErrorBody;
+};
+export declare function readArtifact(input: ReadArtifactInput, deps: ReadArtifactDeps): Promise<ReadArtifactResult>;
+//# sourceMappingURL=read.d.ts.map

package/dist/ops/read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../src/ops/read.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAGV,aAAa,EAEb,eAAe,EAChB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAEzE,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,YAAY,CAAC;CAC/B;AAED,MAAM,MAAM,kBAAkB,GAC1B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;CAAE,GAC3E;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;CAAE,GAC5E;IACE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;IACvC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;CAC9B,CAAC;AAEN,wBAAsB,YAAY,CAChC,KAAK,EAAE,iBAAiB,EACxB,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC,kBAAkB,CAAC,CAkE7B"}