Source: parse-siwe.js

  1. /**
  2.  * @file src/parse-siwe.js
  3.  * @author Lowell D. Thomas <ldt@sabnf.com>
  4.  */
  5. import { Parser } from './parser.js';
  6. import { default as Grammar } from './grammar.js';
  7. import { cb } from './callbacks.js';
  8. import { isERC55, toERC55 } from './keccak256.js';
  9. export { parseSiweMessage, isUri, siweObjectToString };
  11. /**
  12.  * Parses an [ERC-4361: Sign-In with Ethereum](https://eips.ethereum.org/EIPS/eip-4361) 
  13.  * message to an object with the message components.
  14.  *
  15.  * @param {string} msg the ERC-4361 message
  16.  * @param {string} erc55 controls [ERC-55](https://eips.ethereum.org/EIPS/eip-55) processing of the message address<br>
  17.  *   - 'validate' - (default) parser fails if address is not in ERC-55 encoding
  18.  *   - 'convert'  - parser will convert the address to ERC-55 encoding
  19.  *   - 'other'    - (actually, any value other than 'validate', 'convert' or undefined) parser ignores ERC-55 encoding
  20.  * @returns An siwe message object or throws exception with instructive message on format error.<br>
  21.  * e.g. message
  22.  * ````
  23. example.com:80 wants you to sign in with your Ethereum account:
  24. 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2
  26. Valid statement
  28. URI: https://example.com/login
  29. Version: 1
  30. Chain ID: 123456789
  31. Nonce: 32891756
  32. Issued At: 2021-09-30T16:25:24Z
  33. Request ID: someRequestId
  34. Resources:
  35. - ftp://myftpsite.com/
  36. - https://example.com/my-web2-claim.json
  37.  * ````
  38. * returns object, obj:
  39.  * ````
  40.   obj.scheme = undefined
  41.   obj.domain = 'example.com:80'
  42.   obj.address = '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2'
  43.   obj.statement = 'Valid statement'
  44.   obj.uri = 'https://example.com/login'
  45.   obj.version = 1
  46.   obj.chainId = 123456789
  47.   obj.nonce = '32891756'
  48.   obj.issuedAt = '2021-09-30T16:25:24Z'
  49.   obj.expirationTime = undefined
  50.   obj.notBefore = undefined
  51.   obj.requestId = 'someRequestId'
  52.   obj.resources = [ 'ftp://myftpsite.com/', 'https://example.com/my-web2-claim.json' ]
  53. * ````
  54.  */
  55. function parseSiweMessage(msg, erc55 = 'validate') {
  56.   const fname = 'parseSiweMessage: ';
  57.   if (typeof msg !== 'string') {
  58.     throw new Error(`${fname} invalid input msg: message must be of type string`);
  59.   }
  60.   const p = new Parser();
  61.   const g = new Grammar();
  63.   // set the parser's callback functions
  64.   p.callbacks['ffscheme'] = cb.ffscheme;
  65.   p.callbacks['fdomain'] = cb.fdomain;
  66.   p.callbacks['faddress'] = cb.faddress;
  67.   p.callbacks['fstatement'] = cb.fstatement;
  68.   p.callbacks['furi'] = cb.furi;
  69.   p.callbacks['fnonce'] = cb.fnonce;
  70.   p.callbacks['fversion'] = cb.fversion;
  71.   p.callbacks['fchain-id'] = cb.fchainId;
  72.   p.callbacks['fissued-at'] = cb.fissuedAt;
  73.   p.callbacks['fexpiration-time'] = cb.fexpirationTime;
  74.   p.callbacks['fnot-before'] = cb.fnotBefore;
  75.   p.callbacks['frequest-id'] = cb.frequestId;
  76.   p.callbacks['fresources'] = cb.fresources;
  77.   p.callbacks['fresource'] = cb.fresource;
  78.   p.callbacks['empty-statement'] = cb.emptyStatement;
  79.   p.callbacks['no-statement'] = cb.noStatement;
  80.   p.callbacks['actual-statement'] = cb.actualStatment;
  81.   p.callbacks['pre-uri'] = cb.preUri;
  82.   p.callbacks['pre-version'] = cb.preVersion;
  83.   p.callbacks['pre-chain-id'] = cb.preChainId;
  84.   p.callbacks['pre-nonce'] = cb.preNonce;
  85.   p.callbacks['pre-issued-at'] = cb.preIssuedAt;
  86.   // URI callbacks
  87.   p.callbacks['uri'] = cb.URI;
  88.   p.callbacks['scheme'] = cb.scheme;
  89.   p.callbacks['userinfo-at'] = cb.userinfo;
  90.   p.callbacks['host'] = cb.host;
  91.   p.callbacks['IP-literal'] = cb.ipLiteral;
  92.   p.callbacks['port'] = cb.port;
  93.   p.callbacks['path-abempty'] = cb.pathAbempty;
  94.   p.callbacks['path-absolute'] = cb.pathAbsolute;
  95.   p.callbacks['path-rootless'] = cb.pathRootless;
  96.   p.callbacks['path-empty'] = cb.pathEmpty;
  97.   p.callbacks['query'] = cb.query;
  98.   p.callbacks['fragment'] = cb.fragment;
  99.   p.callbacks['IPv4address'] = cb.ipv4;
  100.   p.callbacks['nodcolon'] = cb.nodcolon;
  101.   p.callbacks['dcolon'] = cb.dcolon;
  102.   p.callbacks['h16'] = cb.h16;
  103.   p.callbacks['h16c'] = cb.h16;
  104.   p.callbacks['h16n'] = cb.h16;
  105.   p.callbacks['h16cn'] = cb.h16;
  106.   p.callbacks['dec-octet'] = cb.decOctet;
  107.   p.callbacks['dec-digit'] = cb.decDigit;
  109.   // BEGIN: some parser helper functions
  110.   function validateDateTime(time, name = 'unknown') {
  111.     const ret = p.parse(g, 'date-time', time);
  112.     if (!ret.success || isNaN(Date.parse(time))) {
  113.       throw new Error(`${fname}invalid date time: ${name} not date time string format: ${time}`);
  114.     }
  115.   }
  116.   function validInt(i) {
  117.     const valid = parseInt(i, 10);
  118.     if (isNaN(valid)) {
  119.       throw new Error(`${fname}invalid integer: not a number: ${i}`);
  120.     } else if (valid === Infinity) {
  121.       throw new Error(`${fname}invalid integer: Infinity: ${i}`);
  122.     }
  123.     return valid;
  124.   }
  126.   // Validates an RFC 3986 URI.
  127.   // returns true if the URI is valid, false otherwise
  128.   function isUri(URI) {
  129.     ret = p.parse(g, 'uri', URI, {});
  130.     return ret.success;
  131.   }
  132.   // END: some parser helper functions
  134.   // first pass parse of the message
  135.   // capture all the message parts, then validate them one-by-one later
  136.   let data = { error: false };
  137.   let ret;
  138.   ret = p.parse(g, 'siwe-first-pass', msg, data);
  139.   if (data.error) {
  140.     throw new Error(`${fname}invalid siwe message: ${data.error}`);
  141.   }
  142.   if (!ret.success) {
  143.     throw new Error(
  144.       `${fname}invalid siwe message: carefully check message syntax, especially after required "Issued At: "\n${JSON.stringify(
  145.         ret
  146.       )}`
  147.     );
  148.   }
  150.   if (data.fscheme) {
  151.     // validate the scheme
  152.     ret = p.parse(g, 'scheme', data.fscheme, {});
  153.     if (!ret.success) {
  154.       throw new Error(`${fname}invalid scheme: ${data.fscheme}`);
  155.     }
  156.   }
  158.   // validate the domain
  159.   ret = p.parse(g, 'authority', data.fdomain, {});
  160.   if (!ret.success) {
  161.     throw new Error(`${fname}invalid domain: ${data.fdomain}`);
  162.   }
  164.   // validate the address
  165.   ret = p.parse(g, 'address', data.faddress);
  166.   if (!ret.success) {
  167.     throw new Error(`${fname}invalid address: ${data.faddress}`);
  168.   }
  169.   if (erc55 == 'validate') {
  170.     // address must be ERC55 format
  171.     if (!isERC55(data.faddress)) {
  172.       throw new Error(
  173.         `${fname}invalid ERC-55 format address: 'validate' specified, MUST be ERC55-conformant: ${data.faddress}`
  174.       );
  175.     }
  176.   } else if (erc55 === 'convert') {
  177.     // convert address to ERC55 format
  178.     data.faddress = toERC55(data.faddress);
  179.   }
  180.   // else for any other value of erc55 no further action on the address is taken
  182.   // validate the statement
  183.   if (data.fstatement !== undefined && data.fstatement !== '') {
  184.     ret = p.parse(g, 'statement', data.fstatement);
  185.     if (!ret.success) {
  186.       throw new Error(`${fname}invalid statement: ${data.fstatement}`);
  187.     }
  188.   }
  190.   // validate the URI
  191.   if (!isUri(data.furi)) {
  192.     throw new Error(`${fname}invalid URI: ${data.furi}`);
  193.   }
  195.   // validate the version
  196.   ret = p.parse(g, 'version', data.fversion);
  197.   if (!ret.success) {
  198.     throw new Error(`${fname}invalid Version: ${data.fversion}`);
  199.   }
  200.   data.fversion = validInt(data.fversion);
  202.   // validate the chain-id
  203.   ret = p.parse(g, 'chain-id', data.fchainId);
  204.   if (!ret.success) {
  205.     throw new Error(`${fname}invalid Chain ID: ${data.fchainId}`);
  206.   }
  207.   data.fchainId = validInt(data.fchainId);
  209.   // validate nonce
  210.   ret = p.parse(g, 'nonce', data.fnonce);
  211.   if (!ret.success) {
  212.     throw new Error(`${fname}invalid Nonce: ${data.fnonce}`);
  213.   }
  215.   // validate the date times
  216.   validateDateTime(data.fissuedAt, 'Issued At');
  217.   if (data.fexpirationTime) {
  218.     validateDateTime(data.fexpirationTime, 'Expiration Time');
  219.   }
  220.   if (data.fnotBefore) {
  221.     validateDateTime(data.fnotBefore, 'Not Before');
  222.   }
  224.   // validate request-id
  225.   if (data.frequestId !== undefined && data.frequestId !== '') {
  226.     ret = p.parse(g, 'request-id', data.frequestId);
  227.     if (!ret.success) {
  228.       throw new Error(`${fname}invalid Request ID: i${data.frequestId}`);
  229.     }
  230.   }
  232.   // validate all resource URIs, if any
  233.   if (data.fresources && data.fresources.length) {
  234.     for (let i = 0; i < data.fresources.length; i++) {
  235.       if (!isUri(data.fresources[i])) {
  236.         throw new Error(`${fname}invalid resource URI [${i}]: ${data.fresources[i]}`);
  237.       }
  238.     }
  239.   }
  241.   // by now all first-pass values (e.g. fscheme) have been validated
  242.   const o = {};
  243.   o.scheme = data.fscheme;
  244.   o.domain = data.fdomain;
  245.   o.address = data.faddress;
  246.   o.statement = data.fstatement;
  247.   o.uri = data.furi;
  248.   o.version = data.fversion;
  249.   o.chainId = data.fchainId;
  250.   o.nonce = data.fnonce;
  251.   o.issuedAt = data.fissuedAt;
  252.   o.expirationTime = data.fexpirationTime;
  253.   o.notBefore = data.fnotBefore;
  254.   o.requestId = data.frequestId;
  255.   o.resources = undefined;
  256.   if (data.fresources) {
  257.     o.resources = [];
  258.     for (let i = 0; i < data.fresources.length; i++) {
  259.       o.resources.push(data.fresources[i]);
  260.     }
  261.   }
  262.   return o;
  263. }
  265. /**
  266.  * Parses a Uniform Resource Identifier (URI) defined in [RFC 3986](https://www.rfc-editor.org/rfc/rfc3986).
  267.  *
  268.  * @param {string} URI the URI to parse
  269.  * @returns `false` if the URI is invalid, otherwise a URI object. e.g.<br>
  270.  * ````
  271.  * const obj = isUri('uri://user:pass@example.com:123/one/two.three?q1=a1&q2=a2#body');
  272.  * ````
  273.  * returns:
  274.  * ````
  275.  * obj.scheme = 'uri'
  276.  * obj.userinfo = 'user:pass'
  277.  * obj.host = 'example.com',
  278.  * obj.port = 123,
  279.  * obj.path = '/one/two.three',
  280.  * obj.query = 'q1=a1&q2=a2',
  281.  * obj.fragment = 'body'
  282.  * ````
  283.  */
  284. function isUri(URI) {
  285.   const p = new Parser();
  286.   const g = new Grammar();
  287.   const uriData = {};
  288.   p.callbacks['uri'] = cb.URI;
  289.   p.callbacks['scheme'] = cb.scheme;
  290.   p.callbacks['userinfo-at'] = cb.userinfo;
  291.   p.callbacks['host'] = cb.host;
  292.   p.callbacks['IP-literal'] = cb.ipLiteral;
  293.   p.callbacks['port'] = cb.port;
  294.   p.callbacks['path-abempty'] = cb.pathAbempty;
  295.   p.callbacks['path-absolute'] = cb.pathAbsolute;
  296.   p.callbacks['path-rootless'] = cb.pathRootless;
  297.   p.callbacks['path-empty'] = cb.pathEmpty;
  298.   p.callbacks['query'] = cb.query;
  299.   p.callbacks['fragment'] = cb.fragment;
  300.   p.callbacks['IPv4address'] = cb.ipv4;
  301.   p.callbacks['nodcolon'] = cb.nodcolon;
  302.   p.callbacks['dcolon'] = cb.dcolon;
  303.   p.callbacks['h16'] = cb.h16;
  304.   p.callbacks['h16c'] = cb.h16;
  305.   p.callbacks['h16n'] = cb.h16;
  306.   p.callbacks['h16cn'] = cb.h16;
  307.   p.callbacks['dec-octet'] = cb.decOctet;
  308.   p.callbacks['dec-digit'] = cb.decDigit;
  309.   const ret = p.parse(g, 'uri', URI, uriData);
  310.   if (!ret.success) {
  311.     return false;
  312.   }
  313.   const uriObject = {
  314.     uri: uriData['uri'],
  315.     scheme: uriData['scheme'],
  316.     userinfo: uriData['userinfo'],
  317.     host: uriData['host'],
  318.     port: uriData['port'],
  319.     path: uriData['path'],
  320.     query: uriData['query'],
  321.     fragment: uriData['fragment'],
  322.   };
  323.   return uriObject;
  324. }
  326. /**
  327.  * Stringify an [ERC-4361: Sign-In with Ethereum](https://eips.ethereum.org/EIPS/eip-4361) (siwe) object.
  328.  * Note that this function does no validation of the input object.
  329.  * It simply returns a string that includes the valid parts of the object, if any.
  330.  * For validation, use {@link parseSiweMessage}.
  331.  *
  332.  * @param {object} o an siwe message object (see {@link parseSiweMessage} )
  333.  * @returns A stringified version of the object suitable as input to {@link parseSiweMessage}.
  334.  *
  335.  * For example, to validate an siwe object <br>*(ignore backslash, JSDoc can't handle closed bracket character without it)*:
  336.  * ````
  337.  * try{
  338.  *  parseSiweMessage(siweObjectToString(siweObject));
  339.  *  console.log('siweObject is valid');
  340.  * \}catch(e){
  341.  *  console.log('siweObject is not valid: ' + e.message);
  342.  * \}
  343.  * ````
  344.  */
  345. function siweObjectToString(o) {
  346.   let str = '';
  347.   if (typeof o !== 'object') {
  348.     return str;
  349.   }
  350.   if (o.scheme && o.scheme !== '') {
  351.     str += `${o.scheme}://`;
  352.   }
  353.   if (o.domain && o.domain !== '') {
  354.     str += o.domain;
  355.   }
  356.   str += ' wants you to sign in with your Ethereum account:\n';
  357.   if (o.address && o.address !== '') {
  358.     str += `${o.address}\n`;
  359.   }
  360.   str += '\n';
  361.   if (o.statement !== undefined) {
  362.     str += `${o.statement}\n`;
  363.   }
  364.   str += '\n';
  365.   if (o.uri && o.uri !== '') {
  366.     str += `URI: ${o.uri}\n`;
  367.   }
  368.   if (o['version'] && o['version'] !== '') {
  369.     str += `Version: ${o['version']}\n`;
  370.   }
  371.   if (o['chainId'] && o['chainId'] !== '') {
  372.     str += `Chain ID: ${o['chainId']}\n`;
  373.   }
  374.   if (o['nonce'] && o['nonce'] !== '') {
  375.     str += `Nonce: ${o['nonce']}\n`;
  376.   }
  377.   if (o['issuedAt'] && o['issuedAt'] !== '') {
  378.     str += `Issued At: ${o['issuedAt']}`;
  379.   }
  380.   if (o['expirationTime'] && o['expirationTime'] !== '') {
  381.     str += `\nExpiration Time: ${o['expirationTime']}`;
  382.   }
  383.   if (o['notBefore'] && o['notBefore'] !== '') {
  384.     str += `\nNot Before: ${o['notBefore']}`;
  385.   }
  386.   if (o['requestId'] !== undefined) {
  387.     str += `\nRequest ID: ${o['requestId']}`;
  388.   }
  389.   if (o['resources']) {
  390.     str += `\nResources:`;
  391.     if (Array.isArray(o.resources)) {
  392.       for (let i = 0; i < o.resources.length; i++) {
  393.         str += `\n- ${o.resources[i]}`;
  394.       }
  395.     }
  396.   }
  397.   return str;
  398. }