The Gratitude URI Scheme

Internet-Draft D. Hakim Intended status: Experimental TYSM Expires: February 17, 2026 August 17, 2025 The Gratitude URI Scheme draft-hakim-gratitude-uri-00 Abstract This document defines the "gratitude" Uniform Resource Identifier (URI) scheme for expressing appreciation and facilitating gratitude transactions across platforms. The scheme provides a standardized method for applications to handle gratitude-related intents, analogous to the "mailto:" scheme for email. It introduces semantics for human-readable, app-agnostic gratitude expressions and specifies security and privacy considerations for safe deployment. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). This is an experimental specification developed by TYSM for community review and potential standardization. Distribution is unlimited. Table of Contents 1. Introduction 2. Scheme Definition 2.1 Syntax 2.2 Parameters 3. Semantics 3.1 Default Action 3.2 Application Behavior 4. Implementation Guidelines 4.1 Client Requirements 4.2 Fallback Handling 4.3 Error Handling 5. Security Considerations 5.1 Parameter Validation 5.2 Privacy Protection 5.3 Callback Hardening 6. IANA Considerations 7. Examples 8. References 9. Author's Address 1. Introduction Digital expressions of appreciation currently lack standardization across platforms. The "gratitude" URI scheme provides a uniform method for applications to handle appreciation intents, enabling cross-platform gratitude transactions and optional lightweight relationship mapping (e.g., who thanked whom). This document does not define transport, settlement, or ledger semantics; it defines an initiation URI only. This scheme is designed to be: * Human-readable and intuitive * Platform-agnostic and network-neutral * Privacy-preserving by default * Extensible for future gratitude applications * Interoperable across traditional and decentralized systems The key words "MUST", "MUST NOT", "SHOULD", "SHOULD NOT", and "MAY" are to be interpreted as described in RFC 2119 and RFC 8174 when, and only when, they appear in all capitals. A secondary alias scheme ("tysm:") MAY be supported for brand adoption. 2. Scheme Definition 2.1 Syntax The syntax of the gratitude URI scheme follows [RFC3986]: gratitude-uri = "gratitude:" [ action "/" ] recipient [ "?" query ] action = "send" / "tip" / "request" ; literals in lowercase recipient = handle / did / acct / address ; Handles remain ASCII for now handle = "@" 1*( ALPHA / DIGIT / "-" / "_" ) ; DID method per DID Core: letters, digits, and hyphen did = "did:" method ":" 1*( pchar ) method = 1*( ALPHA / DIGIT / "-" ) ; acct: per RFC 7565 (left as pchar envelope) acct = "acct:" 1*( pchar ) ; CAIP-10 compatible envelope (chain:account … contains colons) address = 1*( pchar ) ; Query and params query = parameter *( "&" parameter ) parameter = pname "=" pvalue pname = 1*( ALPHA / DIGIT / "-" / "_" ) pvalue = *pchar ; Core from RFC 3986 with explicit inclusions we need pchar = unreserved / pct-encoded / sub-delims / ":" / "@" unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" pct-encoded = "%" HEXDIG HEXDIG sub-delims = "!" / "$" / "&" / "'" / "(" / ")" / "*" / "+" / "," / ";" / "=" ; Parameter value hints (validation guidance, not part of pvalue) amount = 1*DIGIT [ "." 1*DIGIT ] ; dot decimal; no thousands sep currency = 3ALPHA / 1*( ALPHA / DIGIT ) ; ISO 4217 or token symbol privacy = "private" / "public" timestamp = 1*( pchar ) ; RFC 3339 in value; pct-encode as needed uri = 1*( pchar ) ; MUST be HTTPS if used as callback ALPHA = %x41-5A / %x61-7A DIGIT = %x30-39 HEXDIG = DIGIT / %x41-46 / %x61-66 Note: This specification currently defines ASCII-only handles. Future versions may incorporate Internationalized Domain Names (IDNA) per [RFC5891] for non-ASCII usernames. 2.2 Parameters Parameter registry: * amount: POSITIVE decimal (> 0); dot separator; client+server validated * currency: ISO-4217 (USD) or chain asset ID (prefer CAIP-19) * note: Human message; MUST be pct-encoded; sanitize on display * privacy: "private" (default) or "public" * network: HINT ONLY (e.g., "ethereum"); use CAIP-2/10/19 for canonical * ref: Opaque reference from initiator; not user-visible * expires: RFC 3339 timestamp; clients MUST refuse after expiry * callback: HTTPS only; use allowlists; include anti-CSRF state * account: Optional CAIP-10 account; overrides recipient mapping 2.3 Internationalization Considerations This specification restricts handle to ASCII for interoperability. Future revisions MAY enable Internationalized Resource Identifiers (IRIs) per RFC 3987 and IDNA per RFC 5891 for non-ASCII usernames. When IRIs are used, clients MUST convert to valid URIs per RFC 3987 Section 3.1 (percent-encoding as required) and ensure consistent comparison rules to avoid look-alike attacks. 2.4 URI Normalization & Comparison The "gratitude" scheme follows RFC 3986 Section 6 for comparison. Implementations SHOULD apply the following canonicalization rules before comparing two gratitude URIs for equivalence: * Scheme: case-insensitive; canonical form is "gratitude" * Action tokens ("send", "tip", "request"): case-insensitive; canonical form is lowercase * Handles: comparison is case-insensitive ASCII; clients SHOULD preserve the original case for display * Parameter names: case-insensitive; canonical form is lowercase * Parameter values: compared per-parameter semantics. The "privacy" value is case-insensitive; canonical form is lowercase. The "currency" value SHOULD be uppercase for ISO 4217 codes and left as-is for non-ISO tokens * Percent-encoding: percent-encoded triplets representing unreserved characters SHOULD be decoded for comparison; reserved characters retain their encoded form per RFC 3986 3. Semantics 3.1 Default Action If no action is specified, the default is "send". 3.2 Application Behavior Applications interpreting a "gratitude:" URI SHOULD: a) Open a gratitude transaction interface b) Pre-populate fields with provided parameters c) Require explicit user confirmation before processing d) Normalize and display resolved identity (e.g., @handle → verified profile) e) If both recipient and account are present, account MUST take precedence for funds routing; UI SHOULD still show human-readable recipient 4. Implementation Guidelines 4.1 Client Requirements Implementations MUST: * Validate all parameters before processing * Require user confirmation for financial transactions * Respect privacy settings Implementations SHOULD: * Default to private transactions unless explicitly public * Provide clear user feedback for invalid URIs * Support graceful degradation for unsupported parameters Implementations MAY: * Support additional custom parameters * Provide enhanced UI for recognized recipients 4.2 Fallback Handling If no gratitude-capable application is available, clients SHOULD redirect to a web fallback URL: gratitude:@recipient → https://tysm.to/@recipient Query parameters MUST be preserved verbatim in fallback redirects. Clients SHOULD set a no-referrer policy when opening the fallback URL to avoid leaking parameters to subsequent third-party navigations. 4.3 Error Handling Clients SHOULD ignore unknown parameters gracefully and MUST reject malformed URIs with clear error feedback to users. Common error types: invalid_amount, unsupported_currency, expired, unknown_recipient, unsafe_callback, policy_violation. Clients SHOULD show human-readable error messages for each type. 5. Security Considerations 5.1 Parameter Validation * Reject malformed amounts (e.g., "1e6", "1,000"); normalize and compare server-side * Treat note as untrusted; escape/strip HTML; no rich-text by default * Validate currency codes against known registries * Integer/precision safety: Clients and servers MUST parse amount using fixed-precision decimal logic (no binary floating point) and reject values exceeding policy-defined max or precision * Reject duplicate single-valued parameters (e.g., repeated "amount") 5.2 Privacy Protection * Default MUST be private when privacy unspecified * Do not log full URIs; redact note and PII in logs/analytics * Require explicit consent for public transactions 5.3 Callback Hardening * callback MUST be HTTPS; clients MUST maintain allowlist of trusted hosts * Include unguessable state token and verify on return (CSRF protection) * For POST callbacks, sign payloads (HMAC) and verify server-side * Callback method & headers: If callback uses POST, clients SHOULD send Content-Type: application/json and include a replay-safe id and issued_at in the body; servers MUST verify signature and freshness 5.4 Phishing & Deep-link Risks * Always display review screens; show normalized recipient identity * Consider rate-limits and maximum default amount without confirmation * Encourage servers to mint one-time ref tokens and reject replays * Open redirect avoidance: Clients MUST NOT reflect arbitrary callback values; they MUST verify scheme, host, and path against an allowlist before redirecting * Denial of service: Implementations SHOULD bound maximum note length and total URI length they process to mitigate resource exhaustion 6. IANA Considerations This document requests Provisional registration of the "gratitude" URI scheme in the "URI Schemes" registry per RFC 7595. * Scheme name: gratitude * Status: Provisional * Applications/protocols that use this scheme: Applications that initiate gratitude/tipping/payment intents and acknowledgments across platforms * Contact: TYSM <hello@tysm.to> * Change controller: TYSM (until such time as the IETF assumes change control via a Standards Track RFC) * References: This document * Interoperability considerations: Parameters are pct-encoded per RFC 3986. Where blockchain identifiers are used, CAIP-2/10/19 is RECOMMENDED * Security considerations: See Section 5 * URI scheme syntax: See Section 2.1 (ABNF) 7. Examples * Basic gratitude expression: gratitude:@alice * Gratitude with amount: gratitude:@bob?amount=10&currency=USD&note=great%20work * Private tip request: gratitude:request/@creator?amount=5&privacy=private * Timed gratitude request: gratitude:@team?amount=25&expires=2026-12-31T23:59:59Z * Cross-network gratitude: gratitude:@alice?amount=10&currency=USDC&network=polygon * Decentralized identity: gratitude:did:example:123?amount=5&currency=ETH * Multi-chain routing with callback: gratitude:@bob?amount=25&callback=https%3A%2F%2Fapp.example.com%2Fconfirm&ref=ab12 * CAIP-10 account (Ethereum mainnet) as recipient: gratitude:eip155:1:0xAbC1234567890aBcDEF1234567890abCDef12345?amount=0.02&currency=ETH * Explicit public postable note (clients must confirm visibility): gratitude:@alice?amount=3&currency=USD&privacy=public&note=Congrats%21 Parsers MUST reject inputs with multiple identical parameters where semantics would be ambiguous (e.g., two amount keys). For multi-valued, app-specific parameters, semantics are application-defined. 8. References 8.1 Normative References * [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels," BCP 14, RFC 2119, March 1997. * [RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: Timestamps," RFC 3339, July 2002. * [RFC3986] Berners-Lee, T., "Uniform Resource Identifier (URI): Generic Syntax," STD 66, RFC 3986, January 2005. * [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF," STD 68, RFC 5234, January 2008. * [RFC7565] Saint-Andre, P., "The 'acct' URI Scheme," RFC 7565, May 2015. * [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words," BCP 14, RFC 8174, May 2017. 8.2 Informative References * [RFC3987] Duerst, M. and M. Suignard, "Internationalized Resource Identifiers (IRIs)," RFC 3987, January 2005. * [RFC5891] Klensin, J., "Internationalized Domain Names in Applications (IDNA): Protocol," RFC 5891, August 2010. * [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework," RFC 6749, October 2012. * [RFC7595] Thaler, D., "Guidelines and Registration Procedures for URI Schemes," BCP 35, RFC 7595, June 2015. * [W3C-DID] W3C, "Decentralized Identifiers (DIDs) v1.0," W3C Recommendation, July 2022. * [CAIP-2] Chain Agnostic Improvement Proposals, "Blockchain ID Specification," CAIP-2, March 2020. * [CAIP-10] Chain Agnostic Improvement Proposals, "Account ID Specification," CAIP-10, March 2020. * [CAIP-19] Chain Agnostic Improvement Proposals, "Asset Type and Asset ID Specification," CAIP-19, March 2020. 9. Author's Address Daniel Hakim TYSM Development Team Email: hello@tysm.to URI: https://tysm.to Appendix A. Alternate Application Alias Some applications MAY support an unregistered alias scheme "tysm:" for brand adoption. This appendix is non-normative. The "tysm:" alias is not registered with IANA and is semantically equivalent to "gratitude:" when handled by supporting clients. Example: tysm:@alice?amount=10&note=thanks This Internet-Draft expires February 17, 2026.