@ggui-ai/registry-core 0.6.3 → 0.8.0

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

@@ -16,7 +16,8 @@
  * tests rely on isolation between cases.
  */
 import { describe, expect, it } from 'vitest';
-import { ARTIFACTS_METADATA_SK } from '../types.js';
+import { AuthorKeyAlreadyExistsError, } from '../interfaces/registry-storage.js';
+import { ARTIFACTS_METADATA_SK, SAN_ALLOWLIST_INVALID } from '../types.js';
 function makeMetadata(overrides = {}) {
     return {
         artifactId: '@test/foo',
@@ -97,6 +98,19 @@ function makeAuthorKey(overrides = {}) {
         subject: 'user-1',
         keyId: 'key-1',
         publicKeyBase64: 'BBBB',
+        // Row enrichment ([E], 2026-08-10) — the round-trip case carries
+        // BOTH optional fields so every impl proves it persists them.
+        createdAt: '2026-08-10T00:00:00.000Z',
+        label: 'ci laptop',
+        ...overrides,
+    };
+}
+function makeScopeOwner(overrides = {}) {
+    return {
+        scope: '@test',
+        ownerSubject: 'user-1',
+        claimedAt: '2026-08-10T00:00:00.000Z',
+        verification: 'unverified',
         ...overrides,
     };
 }
@@ -251,6 +265,68 @@ export function registryStorageContract(makeStorage) {
                 const byTag = await storage.scanArtifacts({ q: 'geo' });
                 expect(byTag.rows.map((r) => r.artifactId)).toEqual(['@a/leaflet']);
             });
+            // #259 delta-2 — MCP tool-binding filters share `matchesMcpToolFilters`
+            // semantics with the search op; every impl must honor them identically
+            // (the byMcpTool GSI path in the DDB adapter is the load-bearing case).
+            it('filters by tool (matches any entry with that tool name, with or without a server)', async () => {
+                const storage = makeStorage();
+                await storage.putArtifactMetadata(makeMetadata({
+                    artifactId: '@a/stripe-ui',
+                    mcpTools: [{ server: 'stripe-mcp', tool: 'create_payment' }],
+                    mcpToolsSource: 'declared',
+                }));
+                await storage.putArtifactMetadata(makeMetadata({
+                    artifactId: '@a/bare-ui',
+                    mcpTools: [{ tool: 'refund_payment' }],
+                    mcpToolsSource: 'derived',
+                }));
+                await storage.putArtifactMetadata(makeMetadata({ artifactId: '@a/unbound', mcpTools: undefined }));
+                const byServerBound = await storage.scanArtifacts({ tool: 'create_payment' });
+                expect(byServerBound.rows.map((r) => r.artifactId)).toEqual(['@a/stripe-ui']);
+                const byBare = await storage.scanArtifacts({ tool: 'refund_payment' });
+                expect(byBare.rows.map((r) => r.artifactId)).toEqual(['@a/bare-ui']);
+                const byMiss = await storage.scanArtifacts({ tool: 'unknown_tool' });
+                expect(byMiss.rows).toEqual([]);
+            });
+            it('filters by server; bare-tool entries never match', async () => {
+                const storage = makeStorage();
+                await storage.putArtifactMetadata(makeMetadata({
+                    artifactId: '@a/bound',
+                    mcpTools: [{ server: 'stripe-mcp', tool: 'create_payment' }],
+                    mcpToolsSource: 'declared',
+                }));
+                await storage.putArtifactMetadata(makeMetadata({
+                    artifactId: '@a/bare',
+                    mcpTools: [{ tool: 'create_payment' }],
+                    mcpToolsSource: 'derived',
+                }));
+                const page = await storage.scanArtifacts({ server: 'stripe-mcp' });
+                expect(page.rows.map((r) => r.artifactId)).toEqual(['@a/bound']);
+            });
+            it('tool + server composes into the exact-pair filter — cross-product is not enough', async () => {
+                const storage = makeStorage();
+                // A single artifact declaring TWO bindings — `stripe-mcp` and
+                // `refund_payment` each independently exist on this row, but
+                // never paired on the same binding entry.
+                await storage.putArtifactMetadata(makeMetadata({
+                    artifactId: '@a/multi-bound',
+                    mcpTools: [
+                        { server: 'stripe-mcp', tool: 'create_payment' },
+                        { server: 'other-mcp', tool: 'refund_payment' },
+                    ],
+                    mcpToolsSource: 'declared',
+                }));
+                const exactPair = await storage.scanArtifacts({
+                    server: 'stripe-mcp',
+                    tool: 'create_payment',
+                });
+                expect(exactPair.rows.map((r) => r.artifactId)).toEqual(['@a/multi-bound']);
+                const crossProduct = await storage.scanArtifacts({
+                    server: 'stripe-mcp',
+                    tool: 'refund_payment',
+                });
+                expect(crossProduct.rows).toEqual([]);
+            });
         });
         describe('plugin versions', () => {
             it('returns null for missing version', async () => {
@@ -443,6 +519,191 @@ export function registryStorageContract(makeStorage) {
                 expect(existingBlobFetched?.refCount).toBe(1);
             });
         });
+        describe('scope owners', () => {
+            it('returns null for an unclaimed scope', async () => {
+                const storage = makeStorage();
+                expect(await storage.getScopeOwner('@nobody-claimed-this')).toBe(null);
+            });
+            it('claims an unclaimed scope and round-trips the full row', async () => {
+                const storage = makeStorage();
+                const row = makeScopeOwner();
+                const result = await storage.claimScope(row);
+                expect(result).toEqual({ ok: true });
+                expect(await storage.getScopeOwner(row.scope)).toEqual(row);
+            });
+            it('rejects a second claim on an already-claimed scope (first row untouched)', async () => {
+                const storage = makeStorage();
+                const first = makeScopeOwner({ ownerSubject: 'user-1' });
+                await storage.claimScope(first);
+                const second = await storage.claimScope(makeScopeOwner({ ownerSubject: 'user-2', claimedAt: '2026-08-11T00:00:00.000Z' }));
+                expect(second).toEqual({ conflict: true });
+                // First-writer-wins: the persisted row is the FIRST claimant's.
+                expect(await storage.getScopeOwner('@test')).toEqual(first);
+            });
+            it('a simulated race between two claims yields exactly one winner', async () => {
+                // Both claims run concurrently against the same fresh storage.
+                // The atomicity obligation (conditional create — DDB
+                // `attribute_not_exists(scope)`, filesystem O_EXCL, memory
+                // check-and-set without an interleaving await) means EXACTLY
+                // one may win; the loser MUST see `{ conflict: true }` and the
+                // persisted row MUST be the winner's.
+                const storage = makeStorage();
+                const claimA = makeScopeOwner({ ownerSubject: 'racer-a' });
+                const claimB = makeScopeOwner({ ownerSubject: 'racer-b' });
+                const [a, b] = await Promise.all([
+                    storage.claimScope(claimA),
+                    storage.claimScope(claimB),
+                ]);
+                const results = [
+                    { claim: claimA, result: a },
+                    { claim: claimB, result: b },
+                ];
+                const winners = results.filter((r) => 'ok' in r.result);
+                const losers = results.filter((r) => 'conflict' in r.result);
+                expect(winners).toHaveLength(1);
+                expect(losers).toHaveLength(1);
+                expect(await storage.getScopeOwner('@test')).toEqual(winners[0].claim);
+            });
+            it('claims are scoped — sibling scopes claim independently', async () => {
+                const storage = makeStorage();
+                const a = await storage.claimScope(makeScopeOwner({ scope: '@alpha' }));
+                const b = await storage.claimScope(makeScopeOwner({ scope: '@beta', ownerSubject: 'user-2' }));
+                expect(a).toEqual({ ok: true });
+                expect(b).toEqual({ ok: true });
+                expect((await storage.getScopeOwner('@alpha'))?.ownerSubject).toBe('user-1');
+                expect((await storage.getScopeOwner('@beta'))?.ownerSubject).toBe('user-2');
+            });
+            it('updateScopeOwner rewrites the full row when the expectation matches the stored snapshot', async () => {
+                const storage = makeStorage();
+                await storage.claimScope(makeScopeOwner());
+                const verified = {
+                    ...makeScopeOwner(),
+                    verification: 'verified',
+                    verifiedDomain: 'test.example',
+                    verifiedAt: '2026-08-12T00:00:00.000Z',
+                };
+                const result = await storage.updateScopeOwner(verified, {
+                    ownerSubject: 'user-1',
+                    verification: 'unverified',
+                });
+                expect(result).toEqual({ ok: true });
+                expect(await storage.getScopeOwner('@test')).toEqual(verified);
+            });
+            it('updateScopeOwner seeds a row when the caller expects absence (operator seed path)', async () => {
+                const storage = makeStorage();
+                const seeded = makeScopeOwner({ scope: '@seeded', ownerSubject: 'operator-chosen' });
+                const result = await storage.updateScopeOwner(seeded, { absent: true });
+                expect(result).toEqual({ ok: true });
+                expect(await storage.getScopeOwner('@seeded')).toEqual(seeded);
+                // A first-publish claim against the seeded scope now conflicts.
+                expect(await storage.claimScope(makeScopeOwner({ scope: '@seeded', ownerSubject: 'squatter' }))).toEqual({ conflict: true });
+            });
+            it('updateScopeOwner refuses a stale snapshot — RMW race loses, row untouched', async () => {
+                const storage = makeStorage();
+                const current = makeScopeOwner({ ownerSubject: 'current-owner' });
+                await storage.claimScope(current);
+                // Operator read an OLD snapshot (different owner) — e.g. a
+                // concurrent transfer landed between their read and this write.
+                const result = await storage.updateScopeOwner(makeScopeOwner({ ownerSubject: 'operator-target' }), { ownerSubject: 'stale-previous-owner', verification: 'unverified' });
+                expect(result).toEqual({ conflict: true });
+                expect(await storage.getScopeOwner('@test')).toEqual(current);
+            });
+            it('updateScopeOwner refuses a verification-stale snapshot', async () => {
+                const storage = makeStorage();
+                await storage.claimScope(makeScopeOwner());
+                // Verification flipped concurrently — the (owner, verification)
+                // pair is the snapshot identity, so a matching owner alone is
+                // not enough.
+                const result = await storage.updateScopeOwner(makeScopeOwner({ ownerSubject: 'new-owner' }), { ownerSubject: 'user-1', verification: 'verified' });
+                expect(result).toEqual({ conflict: true });
+                expect(await storage.getScopeOwner('@test')).toEqual(makeScopeOwner());
+            });
+            it('updateScopeOwner expect-absent refuses when a claim landed first', async () => {
+                const storage = makeStorage();
+                const claimed = makeScopeOwner({ ownerSubject: 'racing-claimant' });
+                await storage.claimScope(claimed);
+                const result = await storage.updateScopeOwner(makeScopeOwner({ ownerSubject: 'operator-target' }), { absent: true });
+                expect(result).toEqual({ conflict: true });
+                expect(await storage.getScopeOwner('@test')).toEqual(claimed);
+            });
+            it('updateScopeOwner expect-match refuses when the row is missing', async () => {
+                const storage = makeStorage();
+                const result = await storage.updateScopeOwner(makeScopeOwner(), {
+                    ownerSubject: 'user-1',
+                    verification: 'unverified',
+                });
+                expect(result).toEqual({ conflict: true });
+                expect(await storage.getScopeOwner('@test')).toBeNull();
+            });
+            it('getScopeOwner observes a completed claim immediately (conflict re-read obligation)', async () => {
+                // The publish gate's claim-conflict path re-reads to learn the
+                // winner. A read that can miss a completed claim would turn the
+                // losing racer's publish into a spurious storage-inconsistency
+                // failure — reads MUST be read-your-writes strong here.
+                const storage = makeStorage();
+                await storage.claimScope(makeScopeOwner({ ownerSubject: 'winner' }));
+                expect((await storage.getScopeOwner('@test'))?.ownerSubject).toBe('winner');
+            });
+            // F4 — `sanAllowlist` is the per-scope publisher-identity
+            // allowlist the publish gate enforces on sigstore-signed
+            // publishes. It's an OPTIONAL array column: a row without it
+            // falls back to the deployment's default identity rule, so a
+            // storage impl that silently drops (or fabricates) the field
+            // would flip a scope's identity policy without any write.
+            it('claimScope round-trips a sanAllowlist (F4 identity binding)', async () => {
+                const storage = makeStorage();
+                const row = makeScopeOwner({
+                    sanAllowlist: [
+                        'ci@test.example',
+                        'https://ci.example.com/workflows/publish.yml@refs/heads/main',
+                    ],
+                });
+                await storage.claimScope(row);
+                expect(await storage.getScopeOwner(row.scope)).toEqual(row);
+            });
+            it('updateScopeOwner sets a sanAllowlist on an existing row (operator path)', async () => {
+                const storage = makeStorage();
+                await storage.claimScope(makeScopeOwner());
+                const withAllowlist = makeScopeOwner({ sanAllowlist: ['ops@test.example'] });
+                const result = await storage.updateScopeOwner(withAllowlist, {
+                    ownerSubject: 'user-1',
+                    verification: 'unverified',
+                });
+                expect(result).toEqual({ ok: true });
+                expect(await storage.getScopeOwner('@test')).toEqual(withAllowlist);
+            });
+            it('the SAN_ALLOWLIST_INVALID marker round-trips as invalid — corruption never launders into a valid policy', async () => {
+                // Fail-closed obligation: an adapter that reads malformed
+                // allowlist data projects SAN_ALLOWLIST_INVALID (see
+                // ScopeOwnerRow.sanAllowlist). Writing the marker itself back
+                // (e.g. a verification flip preserving a corrupt column) MUST
+                // read back as invalid in every impl — the marker is a bare
+                // string, itself a malformed column value, so the round-trip
+                // cannot turn corruption into "no allowlist" or a real list.
+                const storage = makeStorage();
+                const row = makeScopeOwner({ sanAllowlist: SAN_ALLOWLIST_INVALID });
+                await storage.claimScope(row);
+                expect((await storage.getScopeOwner('@test'))?.sanAllowlist).toBe(SAN_ALLOWLIST_INVALID);
+            });
+            it('updateScopeOwner clears a sanAllowlist — the field is ABSENT after, not empty', async () => {
+                // Absent vs empty is load-bearing: the publish gate treats a
+                // missing allowlist as "no per-scope rule" (default identity
+                // rule applies). A cleared row that came back `[]` instead of
+                // absent would be indistinguishable in JS truthiness tests but
+                // MUST round-trip as absent so every impl agrees on the shape.
+                const storage = makeStorage();
+                await storage.claimScope(makeScopeOwner({ sanAllowlist: ['ops@test.example'] }));
+                const cleared = makeScopeOwner();
+                const result = await storage.updateScopeOwner(cleared, {
+                    ownerSubject: 'user-1',
+                    verification: 'unverified',
+                });
+                expect(result).toEqual({ ok: true });
+                const fetched = await storage.getScopeOwner('@test');
+                expect(fetched).toEqual(cleared);
+                expect(fetched?.sanAllowlist).toBeUndefined();
+            });
+        });
         describe('author keys', () => {
             it('returns null on miss', async () => {
                 const storage = makeStorage();
@@ -462,6 +723,95 @@ export function registryStorageContract(makeStorage) {
                 const aliceKeys = await storage.listAuthorKeys('alice');
                 expect(aliceKeys.map((k) => k.keyId).sort()).toEqual(['k1', 'k2']);
             });
+            it('round-trips a legacy row without enrichment fields', async () => {
+                // Rows written before the [E] enrichment carry neither
+                // createdAt nor label — impls MUST NOT fabricate either.
+                const storage = makeStorage();
+                const row = {
+                    subject: 'legacy-subject',
+                    keyId: 'legacy-key',
+                    publicKeyBase64: 'CCCC',
+                };
+                await storage.putAuthorKey(row);
+                const fetched = await storage.getAuthorKey('legacy-subject', 'legacy-key');
+                expect(fetched).toEqual(row);
+                expect(fetched?.createdAt).toBeUndefined();
+                expect(fetched?.label).toBeUndefined();
+            });
+            it('round-trips base64url-alphabet keyIds (- and _)', async () => {
+                // derivePublicKeyId emits RFC 4648 §5 base64url — the '-'/'_'
+                // characters are representative of the real id alphabet and
+                // MUST survive every impl's row-key encoding.
+                const storage = makeStorage();
+                const row = makeAuthorKey({ keyId: 'aB-cD_eF-gH_iJ-k' });
+                await storage.putAuthorKey(row);
+                expect(await storage.getAuthorKey(row.subject, row.keyId)).toEqual(row);
+                const listed = await storage.listAuthorKeys(row.subject);
+                expect(listed.map((k) => k.keyId)).toContain('aB-cD_eF-gH_iJ-k');
+                expect(await storage.deleteAuthorKey(row.subject, row.keyId)).toBe(true);
+                expect(await storage.getAuthorKey(row.subject, row.keyId)).toBe(null);
+            });
+            it("isolates subjects containing '/' — composite-key encodings must be unambiguous", async () => {
+                // Subjects are operator-defined free text; a naive
+                // `${subject}/${keyId}` composite (or a raw path component)
+                // makes 'team' and 'team/alice' collide or leak.
+                const storage = makeStorage();
+                await storage.putAuthorKey(makeAuthorKey({ subject: 'team/alice', keyId: 'k1' }));
+                await storage.putAuthorKey(makeAuthorKey({ subject: 'team', keyId: 'k2' }));
+                const teamKeys = await storage.listAuthorKeys('team');
+                expect(teamKeys.map((k) => k.keyId)).toEqual(['k2']);
+                const nestedKeys = await storage.listAuthorKeys('team/alice');
+                expect(nestedKeys.map((k) => k.keyId)).toEqual(['k1']);
+                // Delete under 'team' must not touch team/alice's row.
+                expect(await storage.deleteAuthorKey('team', 'k1')).toBe(false);
+                expect(await storage.getAuthorKey('team/alice', 'k1')).not.toBe(null);
+            });
+            it('putAuthorKey with ifNotExists rejects an existing row with AuthorKeyAlreadyExistsError', async () => {
+                // The register op's TOCTOU close relies on this conditional
+                // rejecting — an impl that silently upserts turns idempotent
+                // re-registers into false 201s.
+                const storage = makeStorage();
+                const row = makeAuthorKey();
+                await storage.putAuthorKey(row, { ifNotExists: true });
+                await expect(storage.putAuthorKey(makeAuthorKey({ publicKeyBase64: 'ZZZZ' }), { ifNotExists: true })).rejects.toThrow(AuthorKeyAlreadyExistsError);
+                // The stored row is untouched by the rejected write.
+                expect(await storage.getAuthorKey(row.subject, row.keyId)).toEqual(row);
+            });
+            it('putAuthorKey without options is an unconditional upsert', async () => {
+                const storage = makeStorage();
+                await storage.putAuthorKey(makeAuthorKey({ label: 'first' }));
+                await storage.putAuthorKey(makeAuthorKey({ label: 'second' }));
+                const row = await storage.getAuthorKey('user-1', 'key-1');
+                expect(row?.label).toBe('second');
+            });
+            it('deletes an existing author key and reports deleted: true', async () => {
+                const storage = makeStorage();
+                const row = makeAuthorKey();
+                await storage.putAuthorKey(row);
+                expect(await storage.deleteAuthorKey(row.subject, row.keyId)).toBe(true);
+                expect(await storage.getAuthorKey(row.subject, row.keyId)).toBe(null);
+                expect(await storage.listAuthorKeys(row.subject)).toEqual([]);
+            });
+            it('delete of an absent key reports deleted: false (idempotent)', async () => {
+                const storage = makeStorage();
+                expect(await storage.deleteAuthorKey('nobody', 'nope')).toBe(false);
+                // Second delete of a just-deleted row is the same absent case.
+                const row = makeAuthorKey();
+                await storage.putAuthorKey(row);
+                await storage.deleteAuthorKey(row.subject, row.keyId);
+                expect(await storage.deleteAuthorKey(row.subject, row.keyId)).toBe(false);
+            });
+            it('delete is isolated per subject — another subject\'s same keyId survives', async () => {
+                const storage = makeStorage();
+                await storage.putAuthorKey(makeAuthorKey({ subject: 'alice', keyId: 'k1' }));
+                await storage.putAuthorKey(makeAuthorKey({ subject: 'bob', keyId: 'k1' }));
+                // Deleting under a subject that has no such key touches nothing.
+                expect(await storage.deleteAuthorKey('charlie', 'k1')).toBe(false);
+                // Alice's delete removes ONLY alice's row.
+                expect(await storage.deleteAuthorKey('alice', 'k1')).toBe(true);
+                expect(await storage.getAuthorKey('alice', 'k1')).toBe(null);
+                expect(await storage.getAuthorKey('bob', 'k1')).not.toBe(null);
+            });
         });
     });
 }