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

package/dist/ops/read.js

@@ -0,0 +1,60 @@
+export async function readArtifact(input, deps) {
+    if (typeof input.artifactId !== 'string' || input.artifactId.length === 0) {
+        return errorResult(400, 'invalid_request', 'missing artifactId');
+    }
+    if (typeof input.version !== 'string' || input.version.length === 0) {
+        return errorResult(400, 'invalid_request', 'missing version');
+    }
+    let row;
+    try {
+        row = await deps.storage.getArtifactVersion(input.artifactId, input.version);
+    }
+    catch (err) {
+        return errorResult(500, 'server_error', `failed to read package: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (row === null) {
+        return errorResult(404, 'not_found', `package ${input.artifactId}@${input.version} not found`);
+    }
+    if (row.visibility === 'private' && deps.authn === undefined) {
+        return errorResult(403, 'forbidden', 'private package requires authentication');
+    }
+    // Two-layer resolution — blueprint rows carry a pointer into the
+    // compiled-blob table. Yanked rows still resolve so the 410
+    // response keeps the manifest body informative; install paths
+    // gate on yanked status independently.
+    let compiledBlob = null;
+    if (typeof row.compiledDigest === 'string' && row.compiledDigest.length > 0) {
+        try {
+            compiledBlob = await deps.storage.getCompiledBlob(row.compiledDigest);
+        }
+        catch (err) {
+            return errorResult(500, 'server_error', `failed to read compiled blob for compiledDigest=${row.compiledDigest}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        if (compiledBlob === null) {
+            // CRITICAL — version row points at a digest with no blob.
+            // Should never happen if publish succeeded; surface loudly.
+            return errorResult(500, 'server_error', `version row points at compiledDigest=${row.compiledDigest} but no compiled-blob row exists`);
+        }
+    }
+    const body = rowToResponse(row, compiledBlob);
+    if (row.yanked === true) {
+        return { ok: false, status: 410, body };
+    }
+    return { ok: true, status: 200, body };
+}
+function rowToResponse(row, compiledBlob) {
+    return {
+        manifest: row.manifest,
+        bundleUrl: row.bundleUrl,
+        bundleSri: row.bundleSri,
+        signatureUrl: row.signatureUrl,
+        compiledDigest: row.compiledDigest,
+        compiledBytes: compiledBlob?.compiledBytes,
+        authorPublicKey: row.authorPublicKey,
+        publishedAt: row.publishedAt,
+        publishedBy: row.publishedBy,
+    };
+}
+function errorResult(status, error, message) {
+    return { ok: false, status, body: { error, message } };
+}

package/dist/ops/register-author-key.d.ts

@@ -0,0 +1,22 @@
+import type { AuthnContext } from '../interfaces/authn.js';
+import { type RegistryStorage } from '../interfaces/registry-storage.js';
+import type { RegisterAuthorKeyErrorBody, RegisterAuthorKeyRequestBody, RegisterAuthorKeyResponseBody } from '../types.js';
+export interface RegisterAuthorKeyInput {
+    readonly publicKeyBase64: string;
+}
+export interface RegisterAuthorKeyDeps {
+    readonly storage: RegistryStorage;
+    readonly authn: AuthnContext;
+}
+export type RegisterAuthorKeyResult = {
+    readonly ok: true;
+    readonly status: 200 | 201;
+    readonly body: RegisterAuthorKeyResponseBody;
+} | {
+    readonly ok: false;
+    readonly status: 400 | 409 | 500;
+    readonly body: RegisterAuthorKeyErrorBody;
+};
+export declare function registerAuthorKey(input: RegisterAuthorKeyInput, deps: RegisterAuthorKeyDeps): Promise<RegisterAuthorKeyResult>;
+export type { RegisterAuthorKeyErrorBody, RegisterAuthorKeyRequestBody, RegisterAuthorKeyResponseBody, };
+//# sourceMappingURL=register-author-key.d.ts.map

package/dist/ops/register-author-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register-author-key.d.ts","sourceRoot":"","sources":["../../src/ops/register-author-key.ts"],"names":[],"mappings":"AAuCA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,mCAAmC,CAAC;AAE3C,OAAO,KAAK,EAEV,0BAA0B,EAC1B,4BAA4B,EAC5B,6BAA6B,EAC9B,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;CAC9B;AAED,MAAM,MAAM,uBAAuB,GAC/B;IACE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,MAAM,EAAE,GAAG,GAAG,GAAG,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,6BAA6B,CAAC;CAC9C,GACD;IACE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,0BAA0B,CAAC;CAC3C,CAAC;AAIN,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,sBAAsB,EAC7B,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC,uBAAuB,CAAC,CAuIlC;AAID,YAAY,EACV,0BAA0B,EAC1B,4BAA4B,EAC5B,6BAA6B,GAC9B,CAAC"}

package/dist/ops/register-author-key.js

@@ -0,0 +1,171 @@
+/**
+ * `POST /author-keys` — register an Ed25519 public key for the
+ * authenticated publisher's identity.
+ *
+ * Trust shape:
+ *
+ *   - `subject` is the verified caller identity (carried in
+ *     `deps.authn`, never trusted from the request body). The publisher
+ *     can only register keys under their own identity.
+ *   - `keyId` is derived deterministically from the public-key bytes
+ *     via {@link derivePublicKeyId} — NOT caller-supplied. Two clients
+ *     registering the same key produce the same row.
+ *   - `publicKeyBase64` is base64-encoded raw 32-byte Ed25519 public-
+ *     key bytes. The op decodes + validates length, then writes via
+ *     {@link RegistryStorage.putAuthorKey}.
+ *
+ * Idempotency:
+ *
+ *   - First write for `(subject, keyId)` → 201.
+ *   - Re-register of the same row contents → 200.
+ *   - Re-register with a DIFFERENT publicKey for the same keyId →
+ *     409 `key_conflict`. (Hash collision is the only realistic path;
+ *     SHA-256 truncation collisions on 64 bits are vanishingly rare
+ *     but the failure mode is closed-form.)
+ *
+ * Concurrency: the op uses a conditional put via
+ * {@link RegistryStorage.putAuthorKey}'s `ifNotExists: true` flag and
+ * falls back to a read-then-dispatch only when the conditional put
+ * rejects. This closes the TOCTOU race that an earlier
+ * read-then-write flow had — two concurrent first-register requests
+ * for the same `(subject, keyId)` are now serialized at the storage
+ * layer, so the 409 branch is deterministically reachable on the
+ * SHA-256 truncation-collision race.
+ *
+ * Why a server-side op rather than a client writing storage directly:
+ * keeps the publisher's verified credentials the only auth surface —
+ * the storage backend does not need to grant write access to end users.
+ */
+import { derivePublicKeyId } from '@ggui-ai/gadget-signing';
+import { AuthorKeyAlreadyExistsError, } from '../interfaces/registry-storage.js';
+import { safeBase64Decode } from '../utils/base64.js';
+const ED25519_PUBLIC_KEY_BYTES = 32;
+export async function registerAuthorKey(input, deps) {
+    if (typeof input.publicKeyBase64 !== 'string' ||
+        input.publicKeyBase64.length === 0) {
+        return {
+            ok: false,
+            status: 400,
+            body: {
+                error: 'invalid_request',
+                message: '`publicKeyBase64` is required',
+            },
+        };
+    }
+    const decoded = safeBase64Decode(input.publicKeyBase64);
+    if (decoded === undefined) {
+        return {
+            ok: false,
+            status: 400,
+            body: {
+                error: 'invalid_request',
+                message: '`publicKeyBase64` is not valid base64',
+            },
+        };
+    }
+    if (decoded.length !== ED25519_PUBLIC_KEY_BYTES) {
+        return {
+            ok: false,
+            status: 400,
+            body: {
+                error: 'invalid_request',
+                message: `\`publicKeyBase64\` must decode to ${ED25519_PUBLIC_KEY_BYTES} raw bytes (got ${decoded.length})`,
+            },
+        };
+    }
+    const keyId = derivePublicKeyId(decoded);
+    const subject = deps.authn.subject;
+    const row = {
+        subject,
+        keyId,
+        publicKeyBase64: input.publicKeyBase64,
+    };
+    // Atomic first-write attempt. The `ifNotExists` flag tells the
+    // storage adapter to use a conditional put (a DDB
+    // `attribute_not_exists(...)` condition on a hosted backend, an
+    // in-memory map-key check for the OSS impl). On success → 201. On
+    // conflict → storage throws {@link AuthorKeyAlreadyExistsError};
+    // re-read and dispatch same-publicKey → 200 vs different-publicKey
+    // → 409.
+    //
+    // This closes the TOCTOU race the prior read-then-write flow had:
+    // two concurrent first-register requests both saw `null` on
+    // `getAuthorKey` and both unconditionally put → last-writer-wins.
+    // Same-publicKey races are still harmless idempotent re-writes; the
+    // ≈2^-64 SHA-256-first-16-chars-collision race hits the 409 branch
+    // deterministically rather than silently overwriting the first row.
+    try {
+        await deps.storage.putAuthorKey(row, { ifNotExists: true });
+        return {
+            ok: true,
+            status: 201,
+            body: {
+                subject,
+                keyId,
+                publicKeyBase64: input.publicKeyBase64,
+            },
+        };
+    }
+    catch (err) {
+        if (!(err instanceof AuthorKeyAlreadyExistsError)) {
+            return {
+                ok: false,
+                status: 500,
+                body: {
+                    error: 'server_error',
+                    message: 'failed to write AuthorKey row',
+                },
+            };
+        }
+        // Conditional-put rejected — a row already exists for
+        // `(subject, keyId)`. Read it back and dispatch.
+    }
+    let existing;
+    try {
+        existing = await deps.storage.getAuthorKey(subject, keyId);
+    }
+    catch {
+        return {
+            ok: false,
+            status: 500,
+            body: {
+                error: 'server_error',
+                message: 'failed to read existing AuthorKey row',
+            },
+        };
+    }
+    if (existing === null) {
+        // The conditional put failed but no row is visible on read-back.
+        // This means a concurrent writer landed AND then a concurrent
+        // deleter removed the row, OR a non-atomic storage backend has
+        // diverged. Either way the safest answer is 500 — caller should
+        // retry.
+        return {
+            ok: false,
+            status: 500,
+            body: {
+                error: 'server_error',
+                message: 'AuthorKey row vanished between conditional put and idempotency read-back',
+            },
+        };
+    }
+    if (existing.publicKeyBase64 === input.publicKeyBase64) {
+        return {
+            ok: true,
+            status: 200,
+            body: {
+                subject: existing.subject,
+                keyId: existing.keyId,
+                publicKeyBase64: existing.publicKeyBase64,
+            },
+        };
+    }
+    return {
+        ok: false,
+        status: 409,
+        body: {
+            error: 'key_conflict',
+            message: `an AuthorKey for (subject=${subject}, keyId=${keyId}) already exists with a different publicKey — derivePublicKeyId collision or stale row?`,
+        },
+    };
+}

package/dist/ops/search.d.ts

@@ -0,0 +1,50 @@
+/**
+ * `searchArtifacts` — pure op for `GET /search?…`. Delegates the
+ * post-fetch filter + cursor to {@link RegistryStorage.scanArtifacts} so
+ * every storage impl shares the single semantic — AND-composition over
+ * q/kind/hook/tag/author.
+ *
+ * Visibility: only `visibility: "public"` rows are exposed. Without that
+ * filter the public `/search` route would leak private artifact IDs.
+ * Impls SHOULD apply the visibility filter inside `scanArtifacts`; the
+ * op verifies defensively after the page returns.
+ */
+import type { SearchErrorBody, SearchResponse } from '../types.js';
+import type { RegistryStorage } from '../interfaces/registry-storage.js';
+export interface SearchArtifactsInput {
+    readonly q?: string;
+    readonly kind?: string;
+    readonly hook?: string;
+    readonly tag?: string;
+    readonly author?: string;
+    readonly limit?: string | number;
+    readonly cursor?: string;
+    /**
+     * Optional sort. `'recent'` orders results by `publishedAt` DESC; any
+     * other string is a 400. Default (omitted) is impl-defined ordering —
+     * memory insertion order, filesystem directory order, or DDB Scan
+     * order. See {@link SearchSort} for the full enum.
+     *
+     * **Scale ceiling.** Implemented as an in-memory pass on the page
+     * returned by {@link RegistryStorage.scanArtifacts}. For small row
+     * counts (< ~1k artifacts, single-page scans) the order is globally
+     * correct. Past one Scan page (~1 MiB of items), the order is only
+     * page-local. A DDB GSI on `publishedAt` is the proper fix and is
+     * planned as a follow-up.
+     */
+    readonly sort?: string;
+}
+export interface SearchArtifactsDeps {
+    readonly storage: RegistryStorage;
+}
+export type SearchArtifactsResult = {
+    readonly ok: true;
+    readonly status: 200;
+    readonly body: SearchResponse;
+} | {
+    readonly ok: false;
+    readonly status: 400 | 500;
+    readonly body: SearchErrorBody;
+};
+export declare function searchArtifacts(input: SearchArtifactsInput, deps: SearchArtifactsDeps): Promise<SearchArtifactsResult>;
+//# sourceMappingURL=search.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"search.d.ts","sourceRoot":"","sources":["../../src/ops/search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAIV,eAAe,EACf,cAAc,EAGf,MAAM,aAAa,CAAC;AAErB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAKzE,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;CACnC;AAED,MAAM,MAAM,qBAAqB,GAC7B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAA;CAAE,GAC1E;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,GAAG,GAAG,GAAG,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAA;CAAE,CAAC;AAEvF,wBAAsB,eAAe,CACnC,KAAK,EAAE,oBAAoB,EAC3B,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC,qBAAqB,CAAC,CA6FhC"}

package/dist/ops/search.js

@@ -0,0 +1,106 @@
+import { SEARCH_SORT_OPTIONS } from '../types.js';
+const DEFAULT_LIMIT = 50;
+const MAX_LIMIT = 200;
+export async function searchArtifacts(input, deps) {
+    let kind;
+    if (input.kind !== undefined) {
+        if (input.kind !== 'gadget' && input.kind !== 'blueprint') {
+            return {
+                ok: false,
+                status: 400,
+                body: {
+                    error: 'invalid_request',
+                    message: '`kind` must be one of: gadget, blueprint',
+                },
+            };
+        }
+        kind = input.kind;
+    }
+    let limit = DEFAULT_LIMIT;
+    if (input.limit !== undefined) {
+        const raw = typeof input.limit === 'number' ? input.limit : Number.parseInt(input.limit, 10);
+        if (!Number.isInteger(raw) || raw < 1 || raw > MAX_LIMIT) {
+            return {
+                ok: false,
+                status: 400,
+                body: {
+                    error: 'invalid_request',
+                    message: `\`limit\` must be an integer in [1, ${MAX_LIMIT}]`,
+                },
+            };
+        }
+        limit = raw;
+    }
+    let sort;
+    if (input.sort !== undefined) {
+        if (!isSearchSort(input.sort)) {
+            return {
+                ok: false,
+                status: 400,
+                body: {
+                    error: 'invalid_request',
+                    message: `\`sort\` must be one of: ${SEARCH_SORT_OPTIONS.join(', ')}`,
+                },
+            };
+        }
+        sort = input.sort;
+    }
+    const filter = {
+        q: nonEmpty(input.q),
+        kind,
+        hook: nonEmpty(input.hook),
+        tag: nonEmpty(input.tag),
+        author: nonEmpty(input.author),
+        limit,
+        cursor: nonEmpty(input.cursor),
+    };
+    let page;
+    try {
+        page = await deps.storage.scanArtifacts(filter);
+    }
+    catch {
+        return {
+            ok: false,
+            status: 500,
+            body: { error: 'server_error', message: 'failed to search registry' },
+        };
+    }
+    const visibleRows = [];
+    for (const row of page.rows) {
+        if (row.visibility !== 'public')
+            continue;
+        visibleRows.push(row);
+    }
+    // `sort=recent`: in-memory ORDER BY publishedAt DESC over the page.
+    // Pre-launch posture (see SearchArtifactsInput.sort docstring) —
+    // global order holds for single-page scans; multi-page scans get
+    // per-page recency. A DDB GSI on publishedAt is the proper fix.
+    const sortedRows = sort === 'recent'
+        ? [...visibleRows].sort((a, b) => 
+        // ISO-8601 strings compare lexicographically === chronologically.
+        // DESC: later (greater) publishedAt comes first.
+        b.publishedAt.localeCompare(a.publishedAt))
+        : visibleRows;
+    const results = sortedRows.map(rowToEntry);
+    return {
+        ok: true,
+        status: 200,
+        body: { results, nextCursor: page.nextCursor },
+    };
+}
+function isSearchSort(value) {
+    return SEARCH_SORT_OPTIONS.includes(value);
+}
+function rowToEntry(row) {
+    return {
+        artifactId: row.artifactId,
+        latestVersion: row.latestVersion,
+        kind: row.kind,
+        description: row.description,
+        tags: row.tags,
+        publishedAt: row.publishedAt,
+    };
+}
+function nonEmpty(s) {
+    return typeof s === 'string' && s.length > 0 ? s : undefined;
+}

package/dist/testing/bundle-storage-contract.d.ts

@@ -0,0 +1,3 @@
+import type { BundleStorage } from '../interfaces/bundle-storage.js';
+export declare function bundleStorageContract(makeStorage: () => BundleStorage): void;
+//# sourceMappingURL=bundle-storage-contract.d.ts.map

package/dist/testing/bundle-storage-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle-storage-contract.d.ts","sourceRoot":"","sources":["../../src/testing/bundle-storage-contract.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AA0DrE,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,aAAa,GAAG,IAAI,CA6H5E"}

package/dist/testing/bundle-storage-contract.js

@@ -0,0 +1,176 @@
+/**
+ * Contract test for {@link BundleStorage} — every impl runs these.
+ *
+ * Consumed via the package's `./testing` subpath:
+ *
+ * ```ts
+ * import { bundleStorageContract } from '@ggui-ai/registry-core/testing';
+ * import { inMemoryBundleStorage } from '@ggui-ai/registry-core';
+ *
+ * describe('memory bundle impl', () => {
+ *   bundleStorageContract(() => inMemoryBundleStorage({ bundleHost: 'https://test.invalid' }));
+ * });
+ * ```
+ */
+import { describe, expect, it } from 'vitest';
+function stubManifest() {
+    return {
+        kind: 'gadget',
+        scope: '@test',
+        name: 'foo',
+        version: '0.1.0',
+        description: 'a test gadget',
+        visibility: 'public',
+        bundle: './dist/index.js',
+        exports: [
+            {
+                hook: 'useFoo',
+                description: 'the test gadget export',
+                usage: 'A test gadget for registry-core contract tests',
+                example: { props: {} },
+            },
+        ],
+    };
+}
+function stubSignature() {
+    return {
+        algorithm: 'ed25519',
+        bundleSha384: 'AAAA',
+        signature: 'BBBB',
+        publicKeyId: 'kid-1',
+        signedAt: '2026-05-17T00:00:00.000Z',
+    };
+}
+function stubSigstoreSignature() {
+    // Minimal valid cosign-bundle JSON. Shape-checked by
+    // `isSigstoreSignature`; actual cryptographic content is irrelevant
+    // for the storage round-trip pin.
+    return {
+        algorithm: 'sigstore-cosign',
+        bundleSha384: 'AAAA',
+        bundle: JSON.stringify({
+            mediaType: 'application/vnd.dev.sigstore.bundle+json;version=0.3',
+            verificationMaterial: {
+                x509CertificateChain: {
+                    certificates: [{ rawBytes: 'STUB-CERT-PEM-BASE64' }],
+                },
+                tlogEntries: [],
+            },
+            messageSignature: {
+                messageDigest: { algorithm: 'SHA2_256', digest: 'AAAA' },
+                signature: 'BBBB',
+            },
+        }),
+        signedAt: '2026-05-21T00:00:00.000Z',
+    };
+}
+export function bundleStorageContract(makeStorage) {
+    describe('BundleStorage contract', () => {
+        describe('bundle', () => {
+            it('returns null on miss', async () => {
+                const s = makeStorage();
+                expect(await s.getBundle('@test', 'foo', '0.1.0')).toBe(null);
+            });
+            it('round-trips bundle bytes', async () => {
+                const s = makeStorage();
+                const bytes = new Uint8Array([0xff, 0x00, 0x10, 0x20]);
+                await s.putBundle('@test', 'foo', '0.1.0', bytes);
+                const fetched = await s.getBundle('@test', 'foo', '0.1.0');
+                expect(fetched).toEqual(bytes);
+            });
+            it('isolates bundles by (scope, name, version)', async () => {
+                const s = makeStorage();
+                await s.putBundle('@a', 'pkg', '0.1.0', new Uint8Array([1]));
+                await s.putBundle('@a', 'pkg', '0.2.0', new Uint8Array([2]));
+                await s.putBundle('@b', 'pkg', '0.1.0', new Uint8Array([3]));
+                expect((await s.getBundle('@a', 'pkg', '0.1.0'))?.[0]).toBe(1);
+                expect((await s.getBundle('@a', 'pkg', '0.2.0'))?.[0]).toBe(2);
+                expect((await s.getBundle('@b', 'pkg', '0.1.0'))?.[0]).toBe(3);
+            });
+        });
+        describe('signature', () => {
+            it('returns null on miss', async () => {
+                const s = makeStorage();
+                expect(await s.getSignature('@test', 'foo', '0.1.0')).toBe(null);
+            });
+            it('round-trips an Ed25519 signature envelope', async () => {
+                const s = makeStorage();
+                const sig = stubSignature();
+                await s.putSignature('@test', 'foo', '0.1.0', sig);
+                const fetched = await s.getSignature('@test', 'foo', '0.1.0');
+                expect(fetched).toEqual(sig);
+            });
+            // Pin the sigstore round-trip through the storage layer. Guards
+            // against a narrow-cast on read (`JSON.parse(text) as
+            // Ed25519Signature`) that would mangle a sigstore signature,
+            // returning a shape with undefined `signature` + undefined
+            // `publicKeyId` + an unexpected `bundle` field at runtime. The
+            // defensive guard (`isGadgetSignature` on read) keeps the
+            // cosign bundle JSON intact across the round-trip.
+            it('round-trips a sigstore signature envelope including the embedded cosign bundle', async () => {
+                const s = makeStorage();
+                const sig = stubSigstoreSignature();
+                await s.putSignature('@test', 'foo', '0.1.0', sig);
+                const fetched = await s.getSignature('@test', 'foo', '0.1.0');
+                expect(fetched).toEqual(sig);
+                // Specifically pin the `algorithm` discriminator + the
+                // `bundle` field — these are sigstore-only fields the prior
+                // narrow-cast would have lost.
+                expect(fetched?.algorithm).toBe('sigstore-cosign');
+                if (fetched?.algorithm === 'sigstore-cosign') {
+                    expect(fetched.bundle).toBe(sig.bundle);
+                    // Confirm the bundle JSON is parseable (catches accidental
+                    // double-encoding / base64-wrapping regressions).
+                    expect(() => JSON.parse(fetched.bundle)).not.toThrow();
+                }
+            });
+            it('returns null when the stored signature is structurally malformed', async () => {
+                // Defensive: a corrupted on-disk signature blob must NOT be
+                // force-cast through. Storage impls bypassing the
+                // `isGadgetSignature` guard would surface the malformed shape
+                // to install-side consumers.
+                const s = makeStorage();
+                // Write a structurally-valid Ed25519 signature first, then
+                // attempt to retrieve a non-existent one. The well-formed
+                // case is covered by the round-trip tests; this test pins the
+                // null-on-miss contract specifically — without it, a regression
+                // that silently returns a stub object would slip through.
+                const fetched = await s.getSignature('@no-such-scope', 'no-such-name', '0.0.0');
+                expect(fetched).toBe(null);
+            });
+        });
+        describe('manifest', () => {
+            it('returns null on miss', async () => {
+                const s = makeStorage();
+                expect(await s.getManifest('@test', 'foo', '0.1.0')).toBe(null);
+            });
+            it('round-trips the manifest', async () => {
+                const s = makeStorage();
+                const m = stubManifest();
+                await s.putManifest('@test', 'foo', '0.1.0', m);
+                const fetched = await s.getManifest('@test', 'foo', '0.1.0');
+                expect(fetched).toEqual(m);
+            });
+        });
+        describe('URL composition', () => {
+            it('produces distinct URLs for bundle / sig / manifest', async () => {
+                const s = makeStorage();
+                const b = s.bundleUrl('@test', 'foo', '0.1.0');
+                const sig = s.signatureUrl('@test', 'foo', '0.1.0');
+                const man = s.manifestUrl('@test', 'foo', '0.1.0');
+                expect(b).not.toBe(sig);
+                expect(b).not.toBe(man);
+                expect(sig).not.toBe(man);
+            });
+            it('matches the URL returned from put*', async () => {
+                const s = makeStorage();
+                const putBundleUrl = await s.putBundle('@test', 'foo', '0.1.0', new Uint8Array([1]));
+                expect(putBundleUrl).toBe(s.bundleUrl('@test', 'foo', '0.1.0'));
+                const putSigUrl = await s.putSignature('@test', 'foo', '0.1.0', stubSignature());
+                expect(putSigUrl).toBe(s.signatureUrl('@test', 'foo', '0.1.0'));
+                const putManUrl = await s.putManifest('@test', 'foo', '0.1.0', stubManifest());
+                expect(putManUrl).toBe(s.manifestUrl('@test', 'foo', '0.1.0'));
+            });
+        });
+    });
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Contract test helpers for {@link RegistryStorage} + {@link BundleStorage}.
+ *
+ * Subpath export — consumers `import { registryStorageContract } from
+ * '@ggui-ai/registry-core/testing'`. Requires `vitest` at test-runtime
+ * (declared as an optional peerDep).
+ */
+export { registryStorageContract } from './registry-storage-contract.js';
+export { bundleStorageContract } from './bundle-storage-contract.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,uBAAuB,EAAE,MAAM,gCAAgC,CAAC;AACzE,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC"}

package/dist/testing/index.js

@@ -0,0 +1,9 @@
+/**
+ * Contract test helpers for {@link RegistryStorage} + {@link BundleStorage}.
+ *
+ * Subpath export — consumers `import { registryStorageContract } from
+ * '@ggui-ai/registry-core/testing'`. Requires `vitest` at test-runtime
+ * (declared as an optional peerDep).
+ */
+export { registryStorageContract } from './registry-storage-contract.js';
+export { bundleStorageContract } from './bundle-storage-contract.js';

package/dist/testing/registry-storage-contract.d.ts

@@ -0,0 +1,3 @@
+import type { RegistryStorage } from '../interfaces/registry-storage.js';
+export declare function registryStorageContract(makeStorage: () => RegistryStorage): void;
+//# sourceMappingURL=registry-storage-contract.d.ts.map

package/dist/testing/registry-storage-contract.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry-storage-contract.d.ts","sourceRoot":"","sources":["../../src/testing/registry-storage-contract.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAsHzE,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,eAAe,GAAG,IAAI,CAkUhF"}