@ggui-ai/registry-core 0.6.3 → 0.8.0

package/dist/ops/publish.js

@@ -6,6 +6,33 @@
  *   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 when a LATER gate (bundle, conformance,
+ *       crypto verify) fails this publish: by then the caller passed
+ *       every policy gate, so the claim records legitimate 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.
+ *   2d. Bind the publisher identity (F4, sigstore-signed publishes
+ *       only): the bundle certificate's SAN must be on the scope's
+ *       `sanAllowlist` when the ownership row carries one, else must
+ *       equal the account's verified email when the deployment wires
+ *       {@link PublishArtifactDeps.verifiedEmailResolver}. Neither
+ *       configured ⇒ no identity rule (allowlist-only posture).
+ *       Violations answer 403 `identity_mismatch`. On the UNCLAIMED
+ *       path this gate runs BEFORE the claim — a rejected signer
+ *       must not walk away owning the scope.
  *   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,11 +48,11 @@
  *       `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, extractSigstoreLeafCertPem, isGadgetSignature, verifyBundleEd25519, verifyBundleSigstore, } from '@ggui-ai/gadget-signing';
-import { bundleHostScheme } from '@ggui-ai/protocol';
+import { manifestToRegistryEntry, parseArtifactManifest, resolveMcpToolBindings, } from '@ggui-ai/artifact-manifest';
+import { canonicalJson, extractSigstoreLeafCertPem, extractSigstoreSANs, isGadgetSignature, verifyBundleEd25519, verifyBundleSigstore, } from '@ggui-ai/gadget-signing';
+import { bundleHostScheme, strictGadgetDescriptorSchema } from '@ggui-ai/protocol';
 import { ZodError } from 'zod';
-import { ARTIFACTS_METADATA_SK } from '../types.js';
+import { ARTIFACTS_METADATA_SK, SAN_ALLOWLIST_INVALID } from '../types.js';
 import { safeBase64Decode, sha384Base64 } from '../utils/base64.js';
 import { compareSemver } from '../utils/semver.js';
 import { compileBlueprint } from './compile.js';
@@ -38,6 +65,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 +123,184 @@ 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 when a LATER gate (bundle, conformance,
+    // crypto verify) fails this publish (documented judgment call — see
+    // the flow docstring): by then the caller has already passed every
+    // policy gate, so the claim records legitimate intent. The identity
+    // gate (2d) is different — it runs BEFORE the claim on the unclaimed
+    // path, because a signer the scope's identity rule rejects must not
+    // walk away owning the scope. That ordering costs nothing: a fresh
+    // claim can never carry a `sanAllowlist`, so only the deployment's
+    // default email rule can apply pre-claim. The claim still lands
+    // before cryptographic 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.
+    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.`);
+    // 2d. Publisher-identity binding (F4) — sigstore-signed publishes
+    // only (returns `undefined` = pass for Ed25519). Binds the bundle's
+    // certificate identity (the Fulcio cert's SAN) to the ggui account
+    // that owns (or is claiming) the scope, so a valid-but-unrelated
+    // OIDC identity can no longer sign publishes into it. Two rules,
+    // strictly ordered:
+    //
+    //   1. ALLOWLIST — the ownership row carries a non-empty
+    //      `sanAllowlist`: the SAN must be one of its literal entries
+    //      (operator-managed; org/CI flexibility).
+    //   2. VERIFIED EMAIL (default) — no allowlist, and the deployment
+    //      wires {@link PublishArtifactDeps.verifiedEmailResolver}: the
+    //      SAN must equal the account's verified email
+    //      (case-insensitive). An account without a verified email
+    //      fails closed.
+    //
+    // No allowlist AND no resolver ⇒ no identity rule — the deployment
+    // enforces identity only through allowlists (see the resolver
+    // docstring for why that posture is documented rather than papered
+    // over).
+    //
+    // Invocation points (all before bundle decode or cryptographic
+    // verify — the SAN is a cheap local projection, so a forbidden
+    // identity never pays for, or leaks errors from, bundle work):
+    //   - claimed scope: with the stored ownership row;
+    //   - unclaimed scope: with `null` BEFORE the claim (fresh claims
+    //     never carry an allowlist — email rule only);
+    //   - lost claim race won by the same subject: re-run with the
+    //     winner row, which MAY be operator-seeded with an allowlist.
+    // The projection is trustworthy in the reject direction
+    // unconditionally; in the accept direction it is paired with the
+    // REAL `verifyBundleSigstore` at step 6, which proves the same
+    // SAN-bearing cert is genuinely CA-issued and bound to the signed
+    // bytes (same parser both places — the projection cannot drift from
+    // what verification enforces).
+    //
+    // Error hygiene: messages name the rule that failed and MAY echo the
+    // caller's OWN certificate identity (they supplied it), but NEVER
+    // other identities — not allowlist entries, not the account email.
+    const checkPublisherIdentity = async (ownerRow) => {
+        if (input.signature.algorithm !== 'sigstore-cosign')
+            return undefined;
+        // Fail closed on corrupt policy data: a storage adapter projects a
+        // malformed allowlist column as SAN_ALLOWLIST_INVALID (see the
+        // ScopeOwnerRow docstring). Falling through to the email rule (or
+        // no rule) would let corruption silently WIDEN who may publish.
+        const rawAllowlist = ownerRow?.sanAllowlist;
+        if (rawAllowlist === SAN_ALLOWLIST_INVALID) {
+            return error(500, 'internal', `scope \`${manifest.scope}\` has a malformed publisher-identity allowlist in storage — refusing to fall back to a weaker identity rule. A registry operator must rewrite the scope's allowlist (set or clear it) before sigstore publishes into this scope can proceed.`);
+        }
+        // An empty allowlist behaves like an absent one — the allowlist
+        // rule applies only when at least one entry names a signer.
+        const sanAllowlist = rawAllowlist ?? [];
+        const resolver = deps.verifiedEmailResolver;
+        if (sanAllowlist.length === 0 && resolver === undefined)
+            return undefined;
+        // EVERY SAN on the certificate (a Fulcio cert can carry both a
+        // URI and an email SAN) — the rules below accept on ANY hit, so a
+        // both-SAN cert matches whichever identity the policy names.
+        const sans = extractSigstoreSANs(input.signature).map((san) => san.toLowerCase());
+        if (sans.length === 0) {
+            return error(403, 'identity_mismatch', `scope \`${manifest.scope}\` requires a bound publisher identity, but the sigstore bundle's certificate carries no subject identity (SAN) to check`);
+        }
+        const echoedSans = sans.map((san) => `\`${san}\``).join(', ');
+        if (sanAllowlist.length > 0) {
+            // ONE case rule for every identity comparison (mirrors the email
+            // rule below): operator tooling lowercase-normalizes entries at
+            // write, and the comparison is case-insensitive regardless so
+            // rows seeded by other paths behave identically.
+            const allowlistLower = sanAllowlist.map((entry) => entry.toLowerCase());
+            if (!sans.some((san) => allowlistLower.includes(san))) {
+                return error(403, 'identity_mismatch', `no certificate identity (${echoedSans}) is on the publisher-identity allowlist for scope \`${manifest.scope}\`. Sign with an allowlisted identity, or ask the registry operator to update the scope's allowlist.`);
+            }
+            return undefined;
+        }
+        if (resolver !== undefined) {
+            const verifiedEmail = await resolver(deps.authn.subject);
+            if (verifiedEmail === undefined) {
+                return error(403, 'identity_mismatch', `scope \`${manifest.scope}\` binds publishes to the account's verified email, but the publishing account has none. Verify your account email, or ask the registry operator to set a publisher-identity allowlist for the scope. If you verified your email just now, it can take a minute to propagate — retry shortly.`);
+            }
+            if (!sans.includes(verifiedEmail.toLowerCase())) {
+                return error(403, 'identity_mismatch', `no certificate identity (${echoedSans}) matches the publishing account's verified email. Sign with the OIDC identity of your account email, or ask the registry operator to add this identity to the scope's publisher allowlist.`);
+            }
+        }
+        return undefined;
+    };
+    const existingOwner = await deps.storage.getScopeOwner(manifest.scope);
+    if (existingOwner !== null && existingOwner.ownerSubject !== deps.authn.subject) {
+        return scopeForbiddenByOwner();
+    }
+    if (existingOwner !== null) {
+        const identityFailure = await checkPublisherIdentity(existingOwner);
+        if (identityFailure !== undefined)
+            return identityFailure;
+    }
+    else {
+        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.`);
+        }
+        // Identity BEFORE the claim (review r1 finding 2): a rejected
+        // signer must not walk away owning the scope. Fresh claims carry
+        // no allowlist, so this pre-claim run applies the email rule only.
+        const identityFailure = await checkPublisherIdentity(null);
+        if (identityFailure !== undefined)
+            return identityFailure;
+        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();
+            }
+            // The winner row may be operator-seeded WITH an allowlist the
+            // pre-claim run (against `null`) never saw — re-apply the gate
+            // against the durable row.
+            const raceIdentityFailure = await checkPublisherIdentity(winner);
+            if (raceIdentityFailure !== undefined)
+                return raceIdentityFailure;
+        }
+    }
     // 3. Bundle decode + size (gadgets only)
     let bundleBytes;
     if (manifest.kind === 'gadget') {
@@ -88,6 +323,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
@@ -141,15 +401,19 @@ export async function publishArtifact(input, deps) {
     }
     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.
+        // Identity claim: gate 2d already bound the certificate's SAN to
+        // the scope's allowlist / the account's verified email (where
+        // configured — see the gate for the honest no-rule posture). This
+        // verify is the cryptographic half of that pairing: it proves the
+        // SAN-bearing cert is genuinely CA-issued, transparency-logged,
+        // and bound to the signed bytes. Install-time consumers can layer
+        // their own policy via `--verify-identity <pattern>` (CLI install
+        // flag) — a separate trust decision controlled by the install
+        // operator, not the publisher.
         const verifyResult = await verifyBundleSigstore({
             bundleBytes: bytesForSignature,
             signature: input.signature,
+            ...(deps.sigstoreTuf ?? {}),
         });
         if (!verifyResult.valid) {
             return error(400, 'signature_invalid', verifyResult.reason);
@@ -160,7 +424,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;
     }
@@ -222,12 +486,17 @@ export async function publishArtifact(input, deps) {
     // `version_exists` immediately — the publisher's idempotent retry path.
     const nowIso = deps.clock().toISOString();
     const sriHash = bundleBytes === undefined ? undefined : `sha384-${sha384Base64(bundleBytes)}`;
+    // H1 prefix split — the manifest's visibility selects the blob
+    // placement (`bundles/public/…` vs `bundles/private/…`), and the
+    // persisted row URLs reflect that real location: public URLs stay
+    // CDN/static-servable, private URLs resolve only through the
+    // authenticated private-bundle route.
     const bundleUrl = bundleBytes === undefined
         ? undefined
-        : deps.bundleStorage.bundleUrl(manifest.scope, manifest.name, version);
+        : deps.bundleStorage.bundleUrl(manifest.scope, manifest.name, version, manifest.visibility);
     const signatureUrl = bundleBytes === undefined
         ? undefined
-        : deps.bundleStorage.signatureUrl(manifest.scope, manifest.name, version);
+        : deps.bundleStorage.signatureUrl(manifest.scope, manifest.name, version, manifest.visibility);
     const versionRow = {
         artifactId,
         version,
@@ -266,10 +535,10 @@ export async function publishArtifact(input, deps) {
     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);
+            await deps.bundleStorage.putBundle(manifest.scope, manifest.name, version, manifest.visibility, bundleBytes);
+            await deps.bundleStorage.putSignature(manifest.scope, manifest.name, version, manifest.visibility, input.signature);
         }
-        manifestUrl = await deps.bundleStorage.putManifest(manifest.scope, manifest.name, version, manifest);
+        manifestUrl = await deps.bundleStorage.putManifest(manifest.scope, manifest.name, version, manifest.visibility, manifest);
     }
     catch (err) {
         return error(500, 'internal', `failed to upload artifact: ${errorMessage(err)}`);
@@ -287,6 +556,11 @@ export async function publishArtifact(input, deps) {
         // 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;
+        // Denormalized search field — the effective MCP tool bindings
+        // (declared wins entirely; blueprints derive from their contract).
+        // Search metadata ONLY: never part of contract canonicalization,
+        // blueprintKey, or any cache identity.
+        const bindingResolution = resolveMcpToolBindings(manifest);
         const metadataRow = {
             artifactId,
             sk: ARTIFACTS_METADATA_SK,
@@ -300,6 +574,8 @@ export async function publishArtifact(input, deps) {
                 : 'hook' in primaryExport
                     ? primaryExport.hook
                     : primaryExport.component,
+            mcpTools: bindingResolution?.bindings,
+            mcpToolsSource: bindingResolution?.source,
             authorName: manifest.author?.name,
             publishedAt: nowIso,
             publishedBy: deps.authn.subject,

package/dist/ops/read.d.ts

@@ -5,14 +5,34 @@
  *
  * Flow:
  *   1. Point-read the version row via {@link RegistryStorage.getArtifactVersion}.
- *   2. Enforce row `visibility`: `private` → require an {@link AuthnContext}.
+ *   2. Enforce row `visibility`: `private` → the caller must satisfy
+ *      {@link canReadPrivateArtifact} (publisher or scope owner).
+ *      Anyone else receives a response byte-identical to a true
+ *      not-found — no status, code, or message distinguishes "exists
+ *      but you may not read it" from "does not exist".
  *   3. Yanked → 410 with the manifest still in the body (audit-friendly).
+ *      The private gate fires FIRST — an unauthorized caller never sees
+ *      the 410 body.
  *   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.
+ *   5. Project the row + blob into the {@link ReadPkgResponse} wire shape,
+ *      including `scopeVerification`/`verifiedDomain`.
+ *
+ * Scope-owner reads (2026-08-10, MCP discovery §2): every read — public
+ * or private — now costs exactly ONE memoized {@link RegistryStorage.getScopeOwner}
+ * point-read via {@link createScopeOwnerResolver}, shared between the
+ * private-read gate (when applicable) and the `scopeVerification` /
+ * `verifiedDomain` wire projection. This deliberately SUPERSEDES the
+ * prior "public reads cost zero extra storage reads" guarantee from
+ * the private-read-ownership work ({@link ./private-read-authz.js}) —
+ * verification surfacing needs the scope row on every read, public
+ * included, so the old zero-reads pin was retired in favor of a
+ * one-read invariant instead. A failed or missing scope-owner read
+ * degrades to absent `scopeVerification`/`verifiedDomain` (never
+ * defaulted to `'unverified'`) and never fails the read itself.
  */
 import type { ReadErrorBody, ReadPkgResponse } from '../types.js';
 import type { AuthnContext } from '../interfaces/authn.js';
@@ -29,9 +49,11 @@ export interface ReadArtifactInput {
 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.
+     * Optional — the verified caller context, produced by the
+     * transport's own credential verification. When the requested row
+     * is `private`, the op admits only the row's publisher or the
+     * artifact's scope owner ({@link canReadPrivateArtifact}); every
+     * other caller — anonymous included — gets the not-found shape.
      */
     readonly authn?: AuthnContext;
 }
@@ -45,7 +67,7 @@ export type ReadArtifactResult = {
     readonly body: ReadPkgResponse;
 } | {
     readonly ok: false;
-    readonly status: 400 | 403 | 404 | 500;
+    readonly status: 400 | 404 | 500;
     readonly body: ReadErrorBody;
 };
 export declare function readArtifact(input: ReadArtifactInput, deps: ReadArtifactDeps): Promise<ReadArtifactResult>;

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

@@ -1 +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"}
+{"version":3,"file":"read.d.ts","sourceRoot":"","sources":["../../src/ops/read.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,OAAO,KAAK,EAGV,aAAa,EAEb,eAAe,EAEhB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAMzE,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;;;;;;OAMG;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,CAAC;IACjC,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;CAC9B,CAAC;AAEN,wBAAsB,YAAY,CAChC,KAAK,EAAE,iBAAiB,EACxB,IAAI,EAAE,gBAAgB,GACrB,OAAO,CAAC,kBAAkB,CAAC,CA0E7B"}

package/dist/ops/read.js

@@ -1,3 +1,4 @@
+import { canReadPrivateArtifact, createScopeOwnerResolver, } from './private-read-authz.js';
 export async function readArtifact(input, deps) {
     if (typeof input.artifactId !== 'string' || input.artifactId.length === 0) {
         return errorResult(400, 'invalid_request', 'missing artifactId');
@@ -5,18 +6,33 @@ export async function readArtifact(input, deps) {
     if (typeof input.version !== 'string' || input.version.length === 0) {
         return errorResult(400, 'invalid_request', 'missing version');
     }
+    // Scope-owner resolver — memoized, so the private-read gate and the
+    // verification surfacing share at most ONE storage read. Fail-closed:
+    // a storage fault resolves null, which denies on the private gate and
+    // omits the verification fields (state unknown is not 'unverified').
+    const resolveScopeOwner = createScopeOwnerResolver(deps.storage, input.artifactId);
     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)}`);
+        logStorageFailure('read version row', input.artifactId, err);
+        return errorResult(500, 'server_error', 'failed to read package');
     }
     if (row === null) {
-        return errorResult(404, 'not_found', `package ${input.artifactId}@${input.version} not found`);
+        return notFoundResult(input);
     }
-    if (row.visibility === 'private' && deps.authn === undefined) {
-        return errorResult(403, 'forbidden', 'private package requires authentication');
+    if (row.visibility === 'private') {
+        // Ownership gate — publisher or scope owner only. The
+        // unauthorized response is produced by the SAME function as a
+        // true miss so the two are structurally indistinguishable. The
+        // resolver is fail-closed: a storage fault during the owner
+        // lookup denies (logged server-side) rather than erroring — a
+        // 500 only private rows could trigger would leak existence.
+        const allowed = await canReadPrivateArtifact(deps.authn, row, resolveScopeOwner);
+        if (!allowed) {
+            return notFoundResult(input);
+        }
     }
     // Two-layer resolution — blueprint rows carry a pointer into the
     // compiled-blob table. Yanked rows still resolve so the 410
@@ -28,7 +44,8 @@ export async function readArtifact(input, deps) {
             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)}`);
+            logStorageFailure('read compiled blob', input.artifactId, err);
+            return errorResult(500, 'server_error', `failed to read compiled blob for compiledDigest=${row.compiledDigest}`);
         }
         if (compiledBlob === null) {
             // CRITICAL — version row points at a digest with no blob.
@@ -36,13 +53,14 @@ export async function readArtifact(input, deps) {
             return errorResult(500, 'server_error', `version row points at compiledDigest=${row.compiledDigest} but no compiled-blob row exists`);
         }
     }
-    const body = rowToResponse(row, compiledBlob);
+    const scopeOwner = await resolveScopeOwner();
+    const body = rowToResponse(row, compiledBlob, scopeOwner);
     if (row.yanked === true) {
         return { ok: false, status: 410, body };
     }
     return { ok: true, status: 200, body };
 }
-function rowToResponse(row, compiledBlob) {
+function rowToResponse(row, compiledBlob, scopeOwner) {
     return {
         manifest: row.manifest,
         bundleUrl: row.bundleUrl,
@@ -53,8 +71,30 @@ function rowToResponse(row, compiledBlob) {
         authorPublicKey: row.authorPublicKey,
         publishedAt: row.publishedAt,
         publishedBy: row.publishedBy,
+        scopeVerification: scopeOwner?.verification,
+        verifiedDomain: scopeOwner?.verification === 'verified' ? scopeOwner.verifiedDomain : undefined,
     };
 }
+/**
+ * Structured server-side failure log. Raw storage error text stays
+ * OUT of wire bodies (it can carry backend identifiers a caller has
+ * no business seeing); this log line is the operator's copy.
+ */
+function logStorageFailure(operation, artifactId, err) {
+    // eslint-disable-next-line no-console -- server-side operator signal; the wire stays generic
+    console.error(`registry read: failed to ${operation}`, {
+        artifactId,
+        error: err instanceof Error ? err.message : String(err),
+    });
+}
+/**
+ * The one not-found projection — used for BOTH a true miss and an
+ * unauthorized private read, so the two responses cannot drift apart
+ * (drift would reintroduce the existence signal).
+ */
+function notFoundResult(input) {
+    return errorResult(404, 'not_found', `package ${input.artifactId}@${input.version} not found`);
+}
 function errorResult(status, error, message) {
     return { ok: false, status, body: { error, message } };
 }

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"}