@ggui-ai/registry-core 0.7.0 → 0.8.0

package/dist/ops/private-read-authz.js

@@ -0,0 +1,58 @@
+/**
+ * Decide whether `authn` may read a private row.
+ *
+ * @param authn verified caller context; `undefined` for anonymous.
+ * @param row the private row under decision (only `publishedBy` is
+ *   consulted — pass the full row or a narrowed projection).
+ * @param getScopeOwner lazy scope-owner lookup for the artifact's
+ *   scope. Called at most once, only when the publisher fast path
+ *   misses. Build it with {@link createScopeOwnerResolver} for
+ *   memoization + fail-closed semantics.
+ */
+export async function canReadPrivateArtifact(authn, row, getScopeOwner) {
+    if (authn === undefined)
+        return false;
+    if (authn.subject === row.publishedBy)
+        return true;
+    const owner = await getScopeOwner();
+    return owner !== null && owner.ownerSubject === authn.subject;
+}
+/**
+ * Build the memoized, fail-closed `getScopeOwner` thunk for
+ * {@link canReadPrivateArtifact}.
+ *
+ *   - **Lazy** — no storage read happens until the owner arm is
+ *     actually needed (public rows, anonymous callers, and publisher
+ *     matches never trigger one).
+ *   - **Memoized** — a caller checking many rows of one artifact
+ *     (the list op) pays for at most one lookup.
+ *   - **Fail-closed** — a storage failure resolves to `null`
+ *     (unclaimed ⇒ deny) and is logged server-side with structure;
+ *     the raw error never reaches a wire body. See the failure-mode
+ *     section above for why neither fail-open nor fail-loud is
+ *     acceptable here.
+ */
+export function createScopeOwnerResolver(storage, artifactId) {
+    let lookup;
+    return () => {
+        lookup ??= storage.getScopeOwner(artifactScope(artifactId)).catch((err) => {
+            // eslint-disable-next-line no-console -- server-side operator signal; the wire stays opaque
+            console.error('registry: scope-owner lookup failed; treating scope as unclaimed (fail closed)', {
+                artifactId,
+                scope: artifactScope(artifactId),
+                error: err instanceof Error ? err.message : String(err),
+            });
+            return null;
+        });
+        return lookup;
+    };
+}
+/**
+ * Extract the scope segment (leading `@` included) from a canonical
+ * `<@scope>/<name>` artifactId — the key for
+ * {@link RegistryStorage.getScopeOwner}.
+ */
+export function artifactScope(artifactId) {
+    const slash = artifactId.indexOf('/');
+    return slash === -1 ? artifactId : artifactId.slice(0, slash);
+}

package/dist/ops/publish.d.ts

@@ -93,7 +93,37 @@ export interface PublishArtifactDeps {
      * consults any of these.
      */
     readonly sigstoreTuf?: Pick<VerifyBundleSigstoreInput, 'tufCachePath' | 'tufForceCache' | 'tufMirrorURL' | 'tufRootPath'>;
+    /**
+     * F4 identity binding — resolve the VERIFIED email address of the
+     * publishing account identified by `subject` (the same value as
+     * {@link AuthnContext.subject}). Return `undefined` when the account
+     * has no verified email; the resolver MUST NOT return an address the
+     * deployment's identity layer has not verified, because the publish
+     * gate authorizes signer identities against it.
+     *
+     * Consumed only on sigstore-signed publishes into a scope whose
+     * ownership row carries NO `sanAllowlist`: the bundle's certificate
+     * SAN must then equal the resolved email (compared
+     * case-insensitively). Scopes WITH an allowlist never consult the
+     * resolver — the allowlist is the stricter, operator-managed rule.
+     *
+     * OPTIONAL, and honestly so: a deployment that does not wire a
+     * resolver enforces publisher identity ONLY through per-scope
+     * allowlists ({@link ScopeOwnerRow.sanAllowlist}); scopes without
+     * one accept any identity a valid sigstore bundle proves. Wire a
+     * resolver backed by your identity provider to bind default
+     * publishes to account emails.
+     */
+    readonly verifiedEmailResolver?: VerifiedEmailResolver;
 }
+/**
+ * Deployment-provided lookup from an authenticated caller subject to
+ * that account's VERIFIED email address. See
+ * {@link PublishArtifactDeps.verifiedEmailResolver} for the contract
+ * (parties, obligations, and the fail-closed posture the publish gate
+ * layers on top).
+ */
+export type VerifiedEmailResolver = (subject: string) => Promise<string | undefined>;
 export type PublishArtifactResult = {
     readonly ok: true;
     readonly status: 201;

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

@@ -1 +1 @@
-{"version":3,"file":"publish.d.ts","sourceRoot":"","sources":["../../src/ops/publish.ts"],"names":[],"mappings":"AA6CA,OAAO,EAML,KAAK,eAAe,EACpB,KAAK,yBAAyB,EAC/B,MAAM,yBAAyB,CAAC;AAGjC,OAAO,KAAK,EAIV,gBAAgB,EAEhB,mBAAmB,EACpB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EACV,oBAAoB,EAErB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAMzE;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,QAAkB,CAAC;AAEhD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,eAAe,EAAE,SAAS,MAAM,EAc5C,CAAC;AAEF,MAAM,WAAW,oBAAoB;IACnC,4DAA4D;IAC5D,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,8FAA8F;IAC9F,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;;;;;OAQG;IACH,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;CACrC;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC;IAC3B;;;;;;;OAOG;IACH,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,oBAAoB,CAAC;IAC/C;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,IAAI,CACzB,yBAAyB,EACzB,cAAc,GAAG,eAAe,GAAG,cAAc,GAAG,aAAa,CAClE,CAAC;CACH;AAED,MAAM,MAAM,qBAAqB,GAC7B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAA;CAAE,GAC/E;IACE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;IACnD,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;CACjC,CAAC;AAEN,wBAAsB,eAAe,CACnC,KAAK,EAAE,oBAAoB,EAC3B,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC,qBAAqB,CAAC,CAqfhC"}
+{"version":3,"file":"publish.d.ts","sourceRoot":"","sources":["../../src/ops/publish.ts"],"names":[],"mappings":"AAwDA,OAAO,EAOL,KAAK,eAAe,EACpB,KAAK,yBAAyB,EAC/B,MAAM,yBAAyB,CAAC;AAGjC,OAAO,KAAK,EAIV,gBAAgB,EAEhB,mBAAmB,EAEpB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EACV,oBAAoB,EAErB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AACrE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAMzE;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,QAAkB,CAAC;AAEhD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,eAAe,EAAE,SAAS,MAAM,EAc5C,CAAC;AAEF,MAAM,WAAW,oBAAoB;IACnC,4DAA4D;IAC5D,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,8FAA8F;IAC9F,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;;;;;OAQG;IACH,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;CACrC;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,IAAI,CAAC;IAC3B;;;;;;;OAOG;IACH,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,oBAAoB,CAAC;IAC/C;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,IAAI,CACzB,yBAAyB,EACzB,cAAc,GAAG,eAAe,GAAG,cAAc,GAAG,aAAa,CAClE,CAAC;IACF;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,QAAQ,CAAC,qBAAqB,CAAC,EAAE,qBAAqB,CAAC;CACxD;AAED;;;;;;GAMG;AACH,MAAM,MAAM,qBAAqB,GAAG,CAClC,OAAO,EAAE,MAAM,KACZ,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;AAEjC,MAAM,MAAM,qBAAqB,GAC7B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,GAAG,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAA;CAAE,GAC/E;IACE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,MAAM,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;IACnD,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;CACjC,CAAC;AAEN,wBAAsB,eAAe,CACnC,KAAK,EAAE,oBAAoB,EAC3B,IAAI,EAAE,mBAAmB,GACxB,OAAO,CAAC,qBAAqB,CAAC,CAupBhC"}

package/dist/ops/publish.js

@@ -18,11 +18,21 @@
  *       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.
+ *       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}).
@@ -38,11 +48,11 @@
  *       `latestVersion` when the new version is the highest semver.
  *   10. Return 201 with the wire-locked {@link PublishResponseBody}.
  */
-import { manifestToRegistryEntry, parseArtifactManifest, } from '@ggui-ai/artifact-manifest';
-import { canonicalJson, extractSigstoreLeafCertPem, isGadgetSignature, verifyBundleEd25519, verifyBundleSigstore, } from '@ggui-ai/gadget-signing';
+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';
@@ -145,24 +155,127 @@ export async function publishArtifact(input, deps) {
     // 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.
+    // 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) {
+    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,
@@ -180,6 +293,12 @@ export async function publishArtifact(input, deps) {
             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)
@@ -282,12 +401,15 @@ 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,
@@ -364,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,
@@ -408,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)}`);
@@ -429,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,
@@ -442,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/search.d.ts

@@ -2,7 +2,7 @@
  * `searchArtifacts` — pure op for `GET /search?…`. Delegates the
  * post-fetch filter + cursor to {@link RegistryStorage.scanArtifacts} so
  * every storage impl shares the single semantic — AND-composition over
- * q/kind/hook/tag/author.
+ * q/kind/hook/tag/author/tool/server.
  *
  * Visibility: only `visibility: "public"` rows are exposed. Without that
  * filter the public `/search` route would leak private artifact IDs.
@@ -31,6 +31,18 @@ export interface SearchArtifactsInput {
      * globally-correct newest-first order across the full cursor chain.
      */
     readonly sort?: string;
+    /**
+     * Exact MCP tool-name filter — matches artifacts whose bindings
+     * include this tool (declared under any server, or none). Must match
+     * `^[A-Za-z0-9_.-]{1,128}$`; anything else is a 400.
+     */
+    readonly tool?: string;
+    /**
+     * Exact MCP server-name filter — matches artifacts whose bindings
+     * declare this server; bindings without a server never match. Same
+     * charset rule as `tool`.
+     */
+    readonly server?: string;
 }
 export interface SearchArtifactsDeps {
     readonly storage: RegistryStorage;

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

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