Refactor README and enhance ENS/receipt validation

[GsCommand]

Summary

This PR significantly improves the documentation and adds stricter validation to core signing and ENS resolution functions. The README is rewritten to focus on the canonical implementation role of runtime-core, with clearer examples and protocol documentation. Input validation is strengthened across receipt signing, ENS resolution, and legacy compat functions.

Key Changes

Documentation & Examples

• Completely rewritten README to emphasize runtime-core as the single canonical implementation of signing, verification, and canonicalization
• Reorganized examples to show common workflows first (canonicalization, signing/verification, ENS resolution)
• Added protocol constants reference section
• Added environment variables documentation with .env.example
• Clarified signing protocol: signatures are over raw UTF-8 bytes of canonical JSON, not hashed
• Removed outdated contract family (Commons/Commercial) references

ENS Resolution (src/ens.ts)

• Added support for both positional arguments and options object calling conventions:
  • resolveSignerFromENS('name.eth', provider) (positional)
  • resolveSignerFromENS({ ensName: 'name.eth', provider }) (options)
• Added ResolveSignerFromENSOptions interface for options object form
• Enhanced input validation: checks for non-empty ensName string and required provider
• Improved error messages with clearer guidance
• Re-exported ENS_KEY_SIGNER constant from crypto module for convenience

Receipt Signing & Verification (src/receipt.ts)

• Strengthened validation in signReceipt(): now validates all four required fields (verb, version, agent, timestamp) are non-empty strings
• Added validation for signing options (privateKeyPem, kid, signerEns)
• Enhanced verifyReceipt() structure checks: validates signature is a non-empty string
• Improved isSignedLayeredReceipt(): now checks that signature string is non-empty (length > 0)
• Better type safety with explicit string type checks before use

Legacy Compat (src/compat.ts)

• Added input validation to signReceiptEd25519Sha256(): validates privateKeyPem, signer_id, kid
• Added input validation to verifyReceiptEd25519Sha256(): validates publicKeyPemOrDer
• Improved signature field handling: accepts either signature or signature_b64 field with non-empty string check

Tests (test/ens.test.ts, test/receipt.test.ts)

• Added comprehensive ENS resolution test suite covering both calling conventions
• Added tests for input validation edge cases (empty strings, missing fields)
• Added tests for error conditions (no resolver, network errors, malformed keys)
• Enhanced receipt tests: added validation for version, agent, timestamp fields
• Added test for empty signature string detection

Notable Implementation Details

• ENS resolution now uses a single overloaded function signature that detects calling convention at runtime
• All validation errors include specific field names and requirements for better debugging
• Signature validation now explicitly checks for non-empty strings to prevent false positives on empty signatures
• Error messages use template literals with + concatenation for consistency with existing codebase style

https://claude.ai/code/session_01GQcff5HnFcrTbyuwuvsNEv