@ggui-ai/registry-core 0.6.2 → 0.7.0

package/dist/ops/publish.js

@@ -6,6 +6,23 @@
  *   1.  Validate {@link AuthnContext} present (transport enforces auth
  *       before calling; this is defense-in-depth).
  *   2.  Parse + validate the manifest via `parseArtifactManifest`.
+ *   2b. Enforce the visibility ↔ signature-algorithm pairing
+ *       (`public` ⇒ `sigstore-cosign`, `private` ⇒ `ed25519`) —
+ *       cheap field comparison, before any decode or verify work.
+ *   2c. Enforce scope ownership: a scope owned by another subject
+ *       answers 403 `scope_forbidden`; an UNCLAIMED scope on the
+ *       reserved list ({@link RESERVED_SCOPES}, replaceable via
+ *       {@link PublishArtifactDeps.reservedScopes}) is never
+ *       claimable, while a reserved scope WITH an ownership row
+ *       (operator-seeded) follows the normal owner rule; any other
+ *       unclaimed scope is claimed for the caller via the atomic
+ *       {@link RegistryStorage.claimScope} (first-writer-wins; a lost
+ *       race re-reads and re-applies the owner check). NOTE — the
+ *       claim is durable even when a LATER gate fails this publish:
+ *       the caller demonstrated intent, a failed-publish claim stays
+ *       re-usable by the same caller, and an unverified claim remains
+ *       reclaimable by the registry operator. Deliberately the
+ *       simplest correct behavior.
  *   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}).
@@ -21,9 +38,9 @@
  *       `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 { manifestToRegistryEntry, parseArtifactManifest, } from '@ggui-ai/artifact-manifest';
 import { canonicalJson, extractSigstoreLeafCertPem, isGadgetSignature, verifyBundleEd25519, verifyBundleSigstore, } from '@ggui-ai/gadget-signing';
-import { bundleHostScheme } from '@ggui-ai/protocol';
+import { bundleHostScheme, strictGadgetDescriptorSchema } from '@ggui-ai/protocol';
 import { ZodError } from 'zod';
 import { ARTIFACTS_METADATA_SK } from '../types.js';
 import { safeBase64Decode, sha384Base64 } from '../utils/base64.js';
@@ -38,6 +55,36 @@ import { checkConformance } from './conformance.js';
  * against an OSS-mirrored registry without re-bundling).
  */
 export const MAX_BUNDLE_BYTES = 5 * 1024 * 1024;
+/**
+ * Scopes no publish may CLAIM — well-known names whose squatting would
+ * mislead installers about who authored an artifact. The default
+ * covers first-party names plus obvious squat-bait; a deployment
+ * REPLACES the whole list via
+ * {@link PublishArtifactDeps.reservedScopes} (spread this constant to
+ * extend it instead).
+ *
+ * Reserved scopes block first-publish CLAIMS only — not owned
+ * publishes. A registry operator who wants artifacts under a reserved
+ * name seeds its ownership row out-of-band via
+ * {@link RegistryStorage.updateScopeOwner}; once the row exists, the
+ * normal owner rule applies (the seeded owner publishes, everyone else
+ * gets `scope_forbidden`) with no change to this list.
+ */
+export const RESERVED_SCOPES = [
+    '@ggui-ai',
+    '@ggui',
+    '@guuey',
+    '@anthropic',
+    '@claude',
+    '@openai',
+    '@google',
+    '@gemini',
+    '@meta',
+    '@microsoft',
+    '@aws',
+    '@amazon',
+    '@apple',
+];
 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) {
@@ -66,6 +113,75 @@ export async function publishArtifact(input, deps) {
     }
     const artifactId = `${manifest.scope}/${manifest.name}`;
     const version = manifest.version;
+    // 2b. Visibility ↔ signature-algorithm pairing. The two algorithms
+    // carry different trust models: sigstore keyless signing records
+    // every publish in a public transparency log — the third-party
+    // auditability that makes an artifact safe to list publicly — while
+    // an Ed25519 author key leaves no public record, which is the point
+    // for private artifacts. Clients pair them at signing time, but the
+    // server cannot trust a hand-rolled request: an unenforced
+    // public+Ed25519 publish would become publicly listable with no
+    // transparency-log entry. Cheap field comparison — runs before any
+    // bundle decode, conformance, or cryptographic verify work.
+    if (manifest.visibility === 'public' && input.signature.algorithm === 'ed25519') {
+        return error(400, 'visibility_algorithm_mismatch', "`visibility: 'public'` requires a sigstore keyless signature (`algorithm: 'sigstore-cosign'`) so the publish is recorded in a public transparency log. Ed25519 author-key signatures pair with `visibility: 'private'` — re-sign with sigstore, or publish as private.");
+    }
+    if (manifest.visibility === 'private' && input.signature.algorithm === 'sigstore-cosign') {
+        return error(400, 'visibility_algorithm_mismatch', "`visibility: 'private'` requires an Ed25519 author-key signature. Sigstore keyless signing (`algorithm: 'sigstore-cosign'`) records the publish in a public transparency log and pairs with `visibility: 'public'` — re-sign with your Ed25519 author key, or publish as public.");
+    }
+    // 2c. Scope ownership. Runs after the pairing check (2b) and before
+    // any bundle decode — ownership is a cheap read and a forbidden
+    // publish must not pay for (or leak errors from) bundle work.
+    //
+    // Order within the gate: owner lookup first, then — only when the
+    // scope is UNCLAIMED — the reserved denylist, then the first-publish
+    // claim. Reserved scopes block CLAIMS, not owned publishes: a scope
+    // whose ownership row exists (seeded by the registry operator, or
+    // grandfathered) follows the normal owner rule, so the operator can
+    // publish first-party artifacts under a reserved name without
+    // touching the reserved list. A lost claim race re-reads and
+    // re-applies the owner check — the conditional create in
+    // `claimScope` is the only race-safe primitive, so `conflict` means
+    // somebody else's row is now durable and the re-read decides whose
+    // scope this is.
+    //
+    // The claim is DURABLE even when a later gate fails this publish
+    // (documented judgment call — see the flow docstring). The claim
+    // also deliberately lands BEFORE signature verification: moving it
+    // after would not stop a motivated squatter (any authenticated
+    // caller can produce a validly-signed private publish), so the real
+    // defenses against mass squatting are the operator reclaim flow, the
+    // audit trail, and (future) rate limiting — while the early claim
+    // keeps the gate order cheap-first.
+    const scopeForbiddenByOwner = () => error(403, 'scope_forbidden', `scope \`${manifest.scope}\` is owned by another publisher. Choose a scope you own — your first publish into an unclaimed scope claims it. If you hold the rights to this name (for example the matching domain or brand), the registry operator can verify that ownership and reclaim an unverified scope.`);
+    const existingOwner = await deps.storage.getScopeOwner(manifest.scope);
+    if (existingOwner !== null && existingOwner.ownerSubject !== deps.authn.subject) {
+        return scopeForbiddenByOwner();
+    }
+    if (existingOwner === null) {
+        const reservedScopes = deps.reservedScopes ?? RESERVED_SCOPES;
+        if (reservedScopes.includes(manifest.scope)) {
+            return error(403, 'scope_forbidden', `scope \`${manifest.scope}\` is reserved on this registry and cannot be claimed by publishing. Choose a scope you own — your first publish into an unclaimed scope claims it.`);
+        }
+        const claim = await deps.storage.claimScope({
+            scope: manifest.scope,
+            ownerSubject: deps.authn.subject,
+            claimedAt: deps.clock().toISOString(),
+            verification: 'unverified',
+        });
+        if ('conflict' in claim) {
+            // Lost the race — re-read and re-apply the owner check.
+            const winner = await deps.storage.getScopeOwner(manifest.scope);
+            if (winner === null) {
+                // claimScope reported an existing row but the re-read found
+                // none — storage-layer inconsistency, not a policy outcome.
+                return error(500, 'internal', `scope claim for \`${manifest.scope}\` conflicted but no ownership row exists — storage inconsistency`);
+            }
+            if (winner.ownerSubject !== deps.authn.subject) {
+                return scopeForbiddenByOwner();
+            }
+        }
+    }
     // 3. Bundle decode + size (gadgets only)
     let bundleBytes;
     if (manifest.kind === 'gadget') {
@@ -88,6 +204,31 @@ export async function publishArtifact(input, deps) {
         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 });
         }
+        // 4b. Projection viability — the install path projects this
+        // manifest into a catalog row (`manifestToRegistryEntry` →
+        // `strictGadgetDescriptorSchema`). The two schemas are separate
+        // validators (e.g. manifest `connect[]` entries are free-form
+        // strings while catalog `connect[]` entries must be full URLs),
+        // and a published version is immutable — a manifest that projects
+        // to an invalid row would be PERMANENTLY uninstallable. Reject it
+        // now, naming the offending field, while the author can still fix
+        // and republish.
+        const projected = manifestToRegistryEntry(manifest, {
+            version: manifest.version,
+            // Representative install-time computed fields: the bundle URL is
+            // stamped by storage later, so a syntactically valid placeholder
+            // stands in; the SRI is the real digest verified above.
+            bundleUrl: 'https://registry.invalid/bundle.js',
+            bundleSri: `sha384-${recomputed}`,
+        });
+        const projectionCheck = strictGadgetDescriptorSchema.safeParse(projected);
+        if (!projectionCheck.success) {
+            const first = projectionCheck.error.issues[0];
+            const path = (first?.path ?? [])
+                .map((seg) => String(seg))
+                .join('.');
+            return error(400, 'manifest_invalid', `manifest projects to an invalid gadget catalog row at \`${path}\`: ${first?.message ?? 'schema violation'} — installs would reject this artifact, and published versions are immutable. Fix the field and republish.`, { path, issues: projectionCheck.error.issues });
+        }
     }
     // 5. Conformance gate
     const conformanceBundleText = bundleBytes === undefined
@@ -150,6 +291,7 @@ export async function publishArtifact(input, deps) {
         const verifyResult = await verifyBundleSigstore({
             bundleBytes: bytesForSignature,
             signature: input.signature,
+            ...(deps.sigstoreTuf ?? {}),
         });
         if (!verifyResult.valid) {
             return error(400, 'signature_invalid', verifyResult.reason);
@@ -160,7 +302,7 @@ export async function publishArtifact(input, deps) {
         // impl (single source of truth for the bundle shape).
         const leafCertPem = extractSigstoreLeafCertPem(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');
+            return error(400, 'signature_invalid', 'sigstore verify succeeded but bundle carries no leaf certificate — expected `verificationMaterial.certificate.rawBytes` (bundle v0.3) or `verificationMaterial.x509CertificateChain.certificates[0].rawBytes` (v0.1/v0.2) — cannot pin author identity on the version row');
         }
         authorPublicKey = leafCertPem;
     }

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

@@ -3,10 +3,21 @@ import { type RegistryStorage } from '../interfaces/registry-storage.js';
 import type { RegisterAuthorKeyErrorBody, RegisterAuthorKeyRequestBody, RegisterAuthorKeyResponseBody } from '../types.js';
 export interface RegisterAuthorKeyInput {
     readonly publicKeyBase64: string;
+    /**
+     * Optional human-readable name for the key ([E] enrichment) —
+     * `ggui keys register --label …`. Trimmed; whitespace-only is
+     * treated as absent; longer than {@link MAX_LABEL_LENGTH} is a 400.
+     */
+    readonly label?: string;
 }
 export interface RegisterAuthorKeyDeps {
     readonly storage: RegistryStorage;
     readonly authn: AuthnContext;
+    /**
+     * Wall-clock provider for the row's `createdAt` stamp —
+     * overridable for deterministic tests. Defaults to `new Date()`.
+     */
+    readonly clock?: () => Date;
 }
 export type RegisterAuthorKeyResult = {
     readonly ok: true;
@@ -17,6 +28,8 @@ export type RegisterAuthorKeyResult = {
     readonly status: 400 | 409 | 500;
     readonly body: RegisterAuthorKeyErrorBody;
 };
+/** Display-name budget — a label is a short human hint, not a document. */
+export declare const MAX_LABEL_LENGTH = 100;
 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

@@ -1 +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"}
+{"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;IACjC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,IAAI,CAAC;CAC7B;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,2EAA2E;AAC3E,eAAO,MAAM,gBAAgB,MAAM,CAAC;AAEpC,wBAAsB,iBAAiB,CACrC,KAAK,EAAE,sBAAsB,EAC7B,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC,uBAAuB,CAAC,CAiLlC;AAID,YAAY,EACV,0BAA0B,EAC1B,4BAA4B,EAC5B,6BAA6B,GAC9B,CAAC"}

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

@@ -40,6 +40,8 @@ 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;
+/** Display-name budget — a label is a short human hint, not a document. */
+export const MAX_LABEL_LENGTH = 100;
 export async function registerAuthorKey(input, deps) {
     if (typeof input.publicKeyBase64 !== 'string' ||
         input.publicKeyBase64.length === 0) {
@@ -73,12 +75,42 @@ export async function registerAuthorKey(input, deps) {
             },
         };
     }
+    // Label ([E] enrichment) — defend with a typeof check even though the
+    // input type says string (transports hand over parsed JSON); trim;
+    // whitespace-only collapses to absent.
+    if (input.label !== undefined && typeof input.label !== 'string') {
+        return {
+            ok: false,
+            status: 400,
+            body: {
+                error: 'invalid_request',
+                message: '`label` must be a string',
+            },
+        };
+    }
+    const trimmedLabel = input.label?.trim();
+    const label = trimmedLabel !== undefined && trimmedLabel.length > 0
+        ? trimmedLabel
+        : undefined;
+    if (label !== undefined && label.length > MAX_LABEL_LENGTH) {
+        return {
+            ok: false,
+            status: 400,
+            body: {
+                error: 'invalid_request',
+                message: `\`label\` must be at most ${MAX_LABEL_LENGTH} characters (got ${label.length})`,
+            },
+        };
+    }
     const keyId = derivePublicKeyId(decoded);
     const subject = deps.authn.subject;
+    const clock = deps.clock ?? (() => new Date());
     const row = {
         subject,
         keyId,
         publicKeyBase64: input.publicKeyBase64,
+        createdAt: clock().toISOString(),
+        ...(label !== undefined ? { label } : {}),
     };
     // Atomic first-write attempt. The `ifNotExists` flag tells the
     // storage adapter to use a conditional put (a DDB
@@ -103,6 +135,8 @@ export async function registerAuthorKey(input, deps) {
                 subject,
                 keyId,
                 publicKeyBase64: input.publicKeyBase64,
+                ...(row.createdAt !== undefined ? { createdAt: row.createdAt } : {}),
+                ...(row.label !== undefined ? { label: row.label } : {}),
             },
         };
     }
@@ -150,6 +184,10 @@ export async function registerAuthorKey(input, deps) {
         };
     }
     if (existing.publicKeyBase64 === input.publicKeyBase64) {
+        // Idempotent re-register echoes the EXISTING row untouched — a
+        // different label on a retry does NOT rewrite the stored one
+        // (relabeling is a deliberate future op, not a register side
+        // effect).
         return {
             ok: true,
             status: 200,
@@ -157,6 +195,10 @@ export async function registerAuthorKey(input, deps) {
                 subject: existing.subject,
                 keyId: existing.keyId,
                 publicKeyBase64: existing.publicKeyBase64,
+                ...(existing.createdAt !== undefined
+                    ? { createdAt: existing.createdAt }
+                    : {}),
+                ...(existing.label !== undefined ? { label: existing.label } : {}),
             },
         };
     }

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

@@ -1,3 +1,3 @@
-import type { RegistryStorage } from '../interfaces/registry-storage.js';
+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

@@ -1 +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,CA+ZhF"}
+{"version":3,"file":"registry-storage-contract.d.ts","sourceRoot":"","sources":["../../src/testing/registry-storage-contract.ts"],"names":[],"mappings":"AAkBA,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,mCAAmC,CAAC;AAqI3C,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,MAAM,eAAe,GAAG,IAAI,CAkqBhF"}

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

@@ -16,6 +16,7 @@
  * tests rely on isolation between cases.
  */
 import { describe, expect, it } from 'vitest';
+import { AuthorKeyAlreadyExistsError, } from '../interfaces/registry-storage.js';
 import { ARTIFACTS_METADATA_SK } from '../types.js';
 function makeMetadata(overrides = {}) {
     return {
@@ -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,
     };
 }
@@ -443,6 +457,132 @@ 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');
+            });
+        });
         describe('author keys', () => {
             it('returns null on miss', async () => {
                 const storage = makeStorage();
@@ -462,6 +602,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);
+            });
         });
     });
 }