Add allowInsecureUri opt-out to return_uri validation

[frostevent]

Summary

Adds an explicit opt-out to the https:// requirement on return_uri, for local/dev transports (e.g. http://localhost). Prompted by the question of how to relax the check in dev mode.

The library does not read NODE_ENV — that reflects the consumer's runtime, not this library's. Instead, the caller (which owns its environment) passes an explicit ReturnUriOptions { allowInsecureUri?: boolean }. This keeps the functions pure and testable without mutating process.env, and leaves the dev/prod policy in the app that owns it.

Changes

• src/validate.ts — new ReturnUriOptions type and shared assertReturnUri(returnUri, options) helper (always requires a string; only relaxes the https:// prefix when allowInsecureUri is set). parseX401Payload now takes options and delegates to it, removing the previously duplicated inline check.
• src/agent.ts — addReturnUri uses the helper. Threaded the same option through the decode side (decodePayload, detectProofRequirement) so a dev URI actually round-trips.
• src/index.ts — exported ReturnUriOptions as a public type.
• tests/x401.test.ts — round-trip test for an http://localhost URI under { allowInsecureUri: true }, plus a test confirming a non-string return_uri is still rejected even with the flag.

Consumer usage

const dev = process.env.NODE_ENV !== "production";
const relayed = agent.addReturnUri(payload, returnUri, { allowInsecureUri: dev });
// recipient side must pass the same option to accept it:
const req = agent.detectProofRequirement({ headers, body }, { allowInsecureUri: dev });

Testing

yarn check-all and yarn test pass (35 tests). No version bump.

🤖 Generated with Claude Code