docs(verifier): how to run a nym_auth verifier, and what each refusal means

.github/workflows/test.yaml

@@ -112,6 +112,16 @@ jobs:
           # targets, and both are cached on the resolved revision, so both
           # need resolving the same way. One step rather than two so the
           # ls-remote handling below exists once.
+          # The Makefile's own default, not a second copy of it. These
+          # refs are pinned there (ZK_CRED_LONGFELLOW_REF is a commit of
+          # the crate's nym_auth branch), and a cache key resolved from a
+          # hardcoded "main" would track a ref the build does not use:
+          # bumping the pin would leave the key unchanged and restore a
+          # stage built from the OLD pin. Same resolver as
+          # .github/workflows/docker-build-push.yml.
+          read_ref() {
+            sed -n "s/^$1[[:space:]]*?=[[:space:]]*//p" Makefile | head -n1
+          }
           resolve() {
             local name="$1" repo="$2" ref="$3" sha refs
             if printf '%s' "$ref" | grep -Eiq '^[0-9a-f]{40}$'; then
@@ -134,8 +144,13 @@ jobs:
             fi
             echo "$sha"
           }
-          echo "sha=$(resolve zk-cred-longfellow https://github.com/sirosfoundation/zk-cred-longfellow.git "${ZK_CRED_LONGFELLOW_REF:-main}")" >> "$GITHUB_OUTPUT"
-          echo "vega_sha=$(resolve zk-cred-vega https://github.com/sirosfoundation/zk-cred-vega.git "${ZK_CRED_VEGA_REF:-main}")" >> "$GITHUB_OUTPUT"
+          LONGFELLOW_REF=$(read_ref ZK_CRED_LONGFELLOW_REF)
+          VEGA_REF=$(read_ref ZK_CRED_VEGA_REF)
+          for pair in "ZK_CRED_LONGFELLOW_REF=$LONGFELLOW_REF" "ZK_CRED_VEGA_REF=$VEGA_REF"; do
+            case "$pair" in *=) echo "::error::could not read ${pair%=} default from Makefile"; exit 1 ;; esac
+          done
+          echo "sha=$(resolve zk-cred-longfellow https://github.com/sirosfoundation/zk-cred-longfellow.git "$LONGFELLOW_REF")" >> "$GITHUB_OUTPUT"
+          echo "vega_sha=$(resolve zk-cred-vega https://github.com/sirosfoundation/zk-cred-vega.git "$VEGA_REF")" >> "$GITHUB_OUTPUT"
 
       - name: Cache the built C ABI library
         uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0

README.md

@@ -372,6 +372,19 @@ gated by the `zk_verifier` config block.
   wire protocol and `docs/ZK_VEGA_DIGESTID_WIRE_EXTENSION.md` for a real
   wire-format addition Vega's verification needed (flagged there, not yet
   raised with multipaz upstream).
+- **nym_auth** - the pseudonym circuits, a *second* C ABI of the same
+  zk-cred-longfellow build (`include/zk_cred_longfellow_nymauth.h`,
+  bound in `pkg/nymauth/verifier/zknative`). `make zk-native-lib` stages
+  both headers and requires both: a stage carrying only the mdoc header
+  is refused rather than silently building without pseudonym support.
+  The request a proof is checked against - and the rule that none of it
+  may come from the holder's response - lives in
+  `pkg/nymauth/verifier`, which builds without cgo; only the proof check
+  itself is behind the tag.
+
+  `ZK_CRED_LONGFELLOW_REF` is pinned to a commit of that crate's
+  `feat/nymauth-prove` branch, because the nym_auth C ABI is not on its
+  `main` yet. Move the pin to a `main` SHA once that branch lands.
 
 Setup:
 
@@ -400,9 +413,9 @@ LD_LIBRARY_PATH=$(pwd)/third_party/zk-cred-longfellow/lib:$(pwd)/third_party/zk-
   PATH=$(pwd)/bin:$PATH \
   ./bin/vc_verifier-zknative
 
-# ...or run pkg/mdoc's zknative-tagged tests directly (covers both
-# systems; make test-zknative sets the loader path for both libraries
-# itself):
+# ...or run the zknative-tagged tests directly (pkg/mdoc for both ZK
+# systems, pkg/nymauth for the pseudonym circuits; make test-zknative
+# sets the loader path for both libraries itself):
 make test-zknative
 ```
 

developer_tools/scripts/seed_recover/main.go

@@ -47,7 +47,7 @@ func run() error {
 		subjects        subjectList
 		derivContext    = flag.String("context", "", "the derivation context, if the credential configuration sets one")
 		pseudonymConfig = flag.String("pseudonym-config", "", "nym_auth pseudonym configuration to compute, e.g. known-offender-matching-ssc")
-		verifierID      = flag.String("verifier-id", "", "the verifier_id EXACTLY as the Verifier publishes it: bare (verifier.example) for an x509_san_dns Verifier, or semantic_id:<identifier> for a semantic one - never the prefixed client_id")
+		verifierID      = flag.String("verifier-id", "", "the verifier_id EXACTLY as the Verifier publishes it, prefix included: x509_san_dns:<dns> or semantic_id:<identifier>. Never strip the prefix - the whole string is hashed")
 		verifierContext = flag.String("verifier-context", "", "verifier_context, required for account-recovery-ssc")
 		userValue       = flag.String("user-value", "", "the user-supplied linking value, for user-managed-pseudonym-xsite-ssc")
 		expect          = flag.String("expect", "", "a pseudonym in hex to compare against; exit 0 on a match, 2 on a mismatch")

dockerfiles/worker

@@ -51,9 +51,13 @@ RUN make proto-${SERVICE_NAME}
 # Every worker links libzk_cred_bbs.so via pkg/openid4vci → pkg/bbs.
 RUN make bbs-native-lib ${ZK_CRED_BBS_REF:+ZK_CRED_BBS_REF="$ZK_CRED_BBS_REF"}
 
-# Only the verifier links libzk_cred_longfellow.so (native ZK/PPID via the
-# zknative build tag) and only the verifier's separate zkvegaverifyworker
-# links libzk_cred_vega.so.
+# Only the verifier links the ZK libraries (zknative build tag). It links
+# BOTH: libzk_cred_longfellow.so, and libzk_cred_vega.so for the in-process
+# Vega nym_auth verifier - the latter through
+# pkg/nymauth/verifier/zknative_vega's own cgo directives against
+# third_party/zk-cred-vega, which is why the build step below sets explicit
+# flags for Longfellow only. The separate zkvegaverifyworker links Vega too,
+# for the subprocess-isolated mdoc path.
 RUN if [ "$SERVICE_NAME" = "verifier" ]; then \
         make zk-native-lib ${ZK_CRED_LONGFELLOW_REF:+ZK_CRED_LONGFELLOW_REF="$ZK_CRED_LONGFELLOW_REF"} && \
         make zk-native-lib-vega ${ZK_CRED_VEGA_REF:+ZK_CRED_VEGA_REF="$ZK_CRED_VEGA_REF"} ; \