nip98-url-query-param-mismatch

NIP-98 URL Query Parameter Mismatch

Problem

NIP-98 HTTP authentication fails with 401 Unauthorized even though the token is created successfully and the signature is valid. The actual cause is a URL mismatch between the u tag in the signed event and what the server expects.

Context / Trigger Conditions

• Server returns 401 Unauthorized for NIP-98 protected endpoints
• Logs show token creation succeeded (event signed and validated)
• Error response contains "URL mismatch" with expected vs actual URLs
• The URLs differ only by query parameters

Example error response:

{"error":"Auth failed: URL mismatch: expected .../notifications, got .../notifications?limit=50"}

Root Cause

The NIP-98 spec says:

The u tag MUST be exactly the same as the absolute request URL (including query parameters).

But server implementations vary:

• Some servers follow the spec strictly (require query params in u tag)
• Some servers normalize URLs by stripping query params before validation
• You MUST match what your specific server does

Solution

Step 1: Add logging to see the actual error

} else if (response.statusCode == 401) {
  Log.error(
    'NIP-98 auth failed (401)\n'
    'URL: $url\n'
    'Response: ${response.body}',  // <-- This reveals the actual issue
    ...
  );
}

Step 2: Check the error message

• If error says "expected .../path?params, got .../path" → Include query params
• If error says "expected .../path, got .../path?params" → Strip query params

Step 3: Adjust URL normalization accordingly

For servers that STRIP query params (like Divine Relay):

final uri = Uri.parse(url);
// Server strips query params before NIP-98 validation
final normalizedUrl = '${uri.scheme}://${uri.host}${uri.path}';

For servers that REQUIRE query params (per NIP-98 spec):

final uri = Uri.parse(url);
final normalizedUrl = uri.hasQuery
    ? '${uri.scheme}://${uri.host}${uri.path}?${uri.query}'
    : '${uri.scheme}://${uri.host}${uri.path}';