wayid-nginx

Verify the WayID of inbound AI agents at the NGINX edge, before traffic reaches your application. Part of the WayID verification SDK (#373).

How it works (v1 — passive)

An agent declares its identity with a request header:

WayID: wayid:agent:{24-char-base58}      # full DID or the bare 24-char tail

An njs handler (njs/wayid.js), wired with js_content, reads the header, resolves it against {issuer}/api/v1/agent/{did}, and:

• forwards X-WayID-Decision / X-WayID-Verified / X-WayID-DID / X-WayID-Identity-Level / X-WayID-Status to your upstream (via js_vars), then internalRedirects to it;
• returns 403 instead when $wayid_enforce is on and the decision is deny.

Passive v1 needs no crypto, so the lightweight njs handler is sufficient — no sidecar process. It fails open: a missing/unknown/malformed header or an issuer outage never blocks traffic unless you explicitly enforce. Resolutions are cached in a shared dict (js_shared_dict_zone) for the zone TTL, so the edge doesn't hit the issuer on every request.

Identification, not authentication. The WayID header is self-asserted. Cryptographic proof-of-possession is a planned v2 layer (Web Bot Auth / RFC 9421).

Why js_content, not auth_request? njs's ngx.fetch does not run inside an auth_request subrequest (the subrequest never fires), so the natural-looking auth_request design does not work for a handler that calls the issuer. The working pattern is js_content → resolve → internalRedirect to the upstream.

Install

1. Build/run NGINX with the njs module (ngx_http_js_module). On Debian/Ubuntu: apt-get install nginx-module-njs, then load_module modules/ngx_http_js_module.so;. The official nginx Docker image already ships the module under /etc/nginx/modules/.
2. Copy njs/wayid.js to /etc/nginx/njs/.
3. In http {}:

   js_path   "/etc/nginx/njs/";
   js_import wayid from wayid.js;
   js_var    $wayid_decision;
   js_var    $wayid_verified;
   js_var    $wayid_did;
   js_var    $wayid_level;
   js_var    $wayid_status;
   resolver  1.1.1.1 ipv6=off;                    # ngx.fetch needs a resolver
   js_shared_dict_zone zone=wayid:1m timeout=60s; # optional resolution cache

4. Use conf/wayid.conf as a template for the server {} block (a location / with js_content wayid.gate; and an internal location @wayid_upstream that proxy_passes to your app).

Configuration

nginx variable	default	meaning
$wayid_issuer	https://way.je	issuer origin that minted the DIDs
$wayid_enforce	off	on ⇒ return 403 on a deny decision
$wayid_require_verified	off	on ⇒ require owner identityLevel == "verified"

Test

test/run.sh runs the handler in real NGINX + njs (Docker) against a mock issuer and asserts allow / deny / flag behaviour:

bash test/run.sh    # requires docker

Alternative: auth_request sidecar (no njs)

If your NGINX build lacks njs, run the JS package (@lineagelabs/wayid-verify, withWayId worker adapter) as a small HTTP service and point auth_request at it via proxy_pass; read the X-WayID-* response headers with auth_request_set $v $upstream_http_*. (This works because the sidecar — not njs — makes the issuer call.)

Distribution

This is a single njs handler plus a sample config — there's no package registry artifact. Get it one of two ways:

• Tagged GitHub release (recommended). Each v* tag publishes a release with njs/wayid.js and conf/wayid.conf attached (see .github/workflows/release.yml). Download wayid.js, drop it in /etc/nginx/njs/, and wire up your config.
• Clone / vendor. Copy njs/wayid.js into your repo or config-management (Ansible, Docker build, etc.). Pin to a tag for reproducibility.

To cut a release: bump CHANGELOG.md, then git tag v0.1.0 && git push origin v0.1.0. The release workflow runs the integration test before publishing.

License

MIT © Lineage Labs — see LICENSE.