ARC-60 Algorand Wallet Structured Data Signing API

ARCs/arc-0060.md

@@ -0,0 +1,330 @@
+---
+arc: 60
+title: Algorand Wallet Structured Data Signing API
+description: API function fot signing structured data
+author: Stefano De Angelis (@deanstef)
+discussions-to: https://github.com/algorandfoundation/ARCs/issues/284
+status: Draft
+type: Standards Track
+category: Interface
+created: 2024-02-28
+requires: 1
+---
+
+# Algorand Wallet Structured Data Signing API
+
+> This ARC is inspired by [ARC-1](./arc-0001.md).
+
+## Abstract
+
+ARC-1 defines a standard for signing Algorand transactions that are represented as structured objects. This proposal extends the signing to generic byte arrays encoded with a standardized structure.
+
+[ARC-60](./arc-0060.md) defines an API for wallets to sign structured data that are not Algorand transactions.
+
+## Motivation
+
+Signing data is a common and critical operation. Users may need to sign data for multiple reasons (e.g. delegate signatures, DIDs, signing documents, authentication).
+
+Algorand wallets need a standard approach to byte signing to unlock self-custodial services and protect users from malicious and attack-prone signing workflows.
+
+This ARC provides a standard API for bytes signing. The API encodes byte arrays into well structured JSON schemas together with additional metadata. It requires wallets to validate the signing inputs, notify users about what they are signing and warn them in case of dangerous signing requests.
+
+## Specification
+
+The key words "**MUST**", "**MUST NOT**", "**REQUIRED**", "**SHALL**", "**SHALL NOT**", "**SHOULD**", "**SHOULD NOT**", "**RECOMMENDED**", "**MAY**", and "**OPTIONAL**" in this document are to be interpreted as described in <a href="https://www.ietf.org/rfc/rfc2119.txt">RFC-2119</a>.
+
+> Comments like this are non-normative
+
+### Overview
+
+> This section is non-normative
+
+Signatures of bytes are processed with the `signData(data, metadata, signer)` function.
+
+`data` is a string representing the structured data being signed. It is the representation of a JSON Schema, provided with the `metadata`.
+
+`metadata` is a `StdSignMetadata` object that describes the signature scope and the type of data being signed, including the encoding and the JSON schema.
+
+`signer` is a byte array representing the public key to use for the signing operation.
+
+### Interfaces
+
+> Interfaces are defined in TypeScript. All the objects that are defined are valid JSON objects.
+
+ARC-60 uses interchangeably the terms "throw an error" and "reject a promise with an error".
+
+#### **Interface `SignDataFunction`**
+
+A wallet function `signData` is defined by the interface:
+
+```tsx
+export type SignDataFunction = {
+    data: StdData,
+    metadata: StdSignMetadata,
+    signer: Ed25519Pk,
+}
+    => Promise<(SignedDataStr | null)>;
+```
+
+- `data` is a `StdData` object representing the structured data being signed (defined below).
+- `metadata` is a `StdSignMetadata` objects (defined below) that provide additional information on the data being signed, such as the `data` encoding and the JSON schema.
+- `signer` is a `Ed25519Pk` object (defined below) that represents the signer public key.
+
+The `signData` function returns a `SignedDataStr` object or, in case of error, rejects the promise with an error object `SignDataError`.
+
+#### Interface `StdData`
+
+The `StdData` object is a string that comply with the `metadata` JSON schema. It **MUST** be the byte representation of a canonicalized JSON object, following the <a href="https://www.rfc-editor.org/rfc/rfc8785">RFC 8785</a>.
+
+```tsx
+export type StdData = string;
+```
+
+The `StdData` must be validated with respect the JSON schema provided with `metadata` (defined below).
+
+#### Interface `Ed25519Pk`
+
+An `Ed25519Pk` object is a 32-byte public key, point of the ed25519 elliptic curve. The key **MUST NOT** be transformed into an Algorand address.
+
+```tsx
+export type Ed25519Pk = Uint8Array;
+```
+
+> The wallet **MAY** want to operate with standard Algorand address directly. The transformation from a generic key to an Algorand address is left to the implementation. See <a href="https://developer.algorand.org/docs/get-details/accounts/#transformation-public-key-to-algorand-address">Public Key to Algorand Address</a> section of the developer portal.
+
+#### Interface `SignedDataStr`
+
+`SignedDataStr` is the produced 64-byte array, ed25519 digital signature, of the signed data.
+
+```tsx
+export type SignedDataStr = Uint8Array;
+```
+
+#### Enum `ScopeType`
+
+The `ScopeType` enumerates constant strings with the scope of a signing action.
+
+This ARC introduces two scope types.
+
+| ScopeType | Description |
+| --- | --- |
+| MSGSIG | Signature of a simple message. This is the most generic scope. |
+| LSIG | Signature of an Algorand program for delegation. |
+| ... | ... |
+
+Any extension of this ARC **SHOULD** adopt the `ScopeType` above, or introduce a new scope.
+
+#### Interface `StdSignMetadata`
+
+A `StdSignMetadata` object specifies metadata of a `StdSignData` that is being signed.
+
+```tsx
+export interface StdSignMetadata {
+    /**
+    * The scope value of the signing data request.
+    */
+    scope: ScopeType;
+
+    /**
+    * Canonical representation of the JSON schema for the signing data.
+    */
+    schema: string;
+
+    /**
+    * Optional message explaining the reason for the signature.
+    */
+    message?: string;
+
+    /**
+    * Optional encoding used to represent the signing data.
+    */
+    encoding?: string;
+}
+```
+
+If the `encoding` is not specified, the `StdData` object should be UTF-8 encoded following the <a href="https://www.rfc-editor.org/rfc/rfc8785">RFC 8785</a>.
+
+##### Simple Message Data JSON Schema
+
+The JSON schema for simple message signing. The `StdData` **MUST** be an object of this schema.
+
+> The signing data JSON schema is inspired by the schema proposed with <a href="https://eips.ethereum.org/EIPS/eip-712">EIP-712: Typed structured data hashing and signing proposal</a>.
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "ARC60Domain": {
+      "type": "string",
+      "description": "The ARC-60 domain separator"
+    },
+    "bytes": {
+      "type": "string",
+      "description": "Byte string being signed. Used with ScopeType==MSGSIG."
+    },
+  "required": ["ARC60Domain", "bytes"]
+}
+```
+
+- The `ARC60Domain` object indicates the domain separator to be used for signing. It **SHOULD** be set to `"arc60"` for simple bytes. Algorand transaction domain separators `TX` and `TG` **MUST** be forbidden.
+- The `bytes` object is the byte array of data being signed. It is a simple string in case of `ScopeType==MSGSIG`, a more complex schema **SHOULD** be used otherwise. It cannot be a valid Algorand transaction. The value of `bytes` **MUST NOT** be prepended with a known domain separator `TX` or `TG`.
+
+> Algorand domain separators can be found in the <a href="https://github.com/algorandfoundation/specs/blob/master/dev/crypto.md#domain-separation">Algorand specs</a> and in the <a href="https://github.com/algorand/go-algorand/blob/master/protocol/hash.go#L21">Go type HashID</a>.
+
+For example, a valid object that takes as bytes an extra property field is:
+
+```json
+{
+  "ARC60Domain" : "arc60",
+  "bytes" : "ARC-60 is awesome"
+}
+```
+
+#### Error interface `SignDataError`
+
+The `SignDataError` object extends the `SignTxnsError` defined in [ARC-1](./arc-0001.md).
+
+```ts
+export interface SignDataError extends Error {
+  code: number;
+  data?: any;
+  failingSignData: (StdData | null);
+}
+```
+
+`SignDataError` uses the same error codes of `SignTxnsError` as well as the following codes:
+
+| Status Code | Name | Description |
+| --- | --- | --- |
+| 4600 | Invalid scope | The scope of the signing action is not recognized by the wallet |
+| 4601 | Invalid schema | The schema does not comply with ARC-60 requirements |
+| 4602 | Invalid encoding | The canonical JSON cannot be decoded with the given encoding |
+
+### Semantic Requirements
+
+The call `signData(data, metadata, signer)` **MUST** either return the signed data `ret` or reject the call throwing an error `err`.
+
+> Following [ARC-1](./arc-0001.md) terminology, in this ARC the term **Rejecting** means throwing an error with `err.code=4300`.
+
+Upon calling `signData(data, metadata, signer)`:
+
+- the `data`, `metadata`, and `signer` **MUST NOT** be `null`, otherwise the wallet **MUST** reject the call.
+- `data` **MUST** be validated with respect to the JSON schema `metadata.schema`. If the validation fails, the call **MUST** be rejected with a `4300` error.
+- if the encoding `metadata.encoding` is present, it **MUST** be used to encode `data`.
+- the wallet **MUST** prepare the signing data as `signData=(<data.bytes>)`.
+  - if the value of `ARC6Domain` is not empty than it must used as `prefix`: `signData=(<prefix> || <data.bytes>)`.
+- the wallet **MUST** ask users for signing confirmation. It **MUST** display the `metadata.message` if present, and the `signData` being signed:
+  - if the user approves, `signData` **MUST** be signed with `signer` and `ret` **MUST** be set to the corresponding `SignedDataStr`.
+  - if the user rejects, the call **MUST** fail with error code `4001`.
+
+Note that if `signData` cannot be signed for any reason, the wallet **MUST** throw an error, such that
+
+- `err.message` **SHOULD** indicate the reason of the error (e.g. specify that `data` is not a valid JSON object according to `metadata.schema`)
+- `err.failingSignData` **SHOULD** return the `StdData` object that caused the error, otherwise `null`.
+
+#### Semantic of `data`
+
+- it **MUST** be a valid `StdData` object, otherwise the wallet **MUST** reject.
+- the encoding **MUST** be equal to the value specified with `metadata.encoding` if any, otherwise it **MUST** be UTF-8.
+- if `data` cannot be decoded into a canonicalized JSON object, the wallet **MUST** throw a `4602` error.
+- if the decoded `data` does not comply with the JSON schema in `metadata`, the wallet **MUST** reject.
+- the `ARC60Domain` filed must be validated against forbidden values:
+  - the wallet **MUST** reject if `ARC60Domain="TX"`.
+  - the wallet **MUST** reject if `ARC60Domain="TG"`.
+  - the wallet **MUST** reject if `metadata.scope=MSGSIG` and `ARC60Domain` field is not set to `"arc60"` or `""`.
+- the `bytes` must be a valid byte string:
+  - the wallet **MUST** reject if `bytes` is prepended with a forbidden domain separator `TX` or `TG`.
+
+#### Semantic of `StdSignMetadata`
+
+- `scope`:
+  - it **MUST** be a valid `ScopeType` string, otherwise the wallet **MUST** throw a `4600` error.
+
+- `schema`:
+  - it **MUST** be a canonical JSON schema with the properties `ARC60Domain` and `bytes`, otherwise the wallet **MUST** throw a `4601` error.
+  - the wallet **MAY** accept JSON schema with `bytes` with different structures (e.g. a JSON object with additional parameters). In that case, the wallet **MUST** verify that the `data.bytes` reflects the structure of the schema.
+
+- `message`:
+  - If specified, the message **SHOULD** be displayed to the user in plain text. The wallet **SHOULD** display the message `metadata.message`.
+
+- `encoding`:
+  - if specified, it **MUST** be used to encode the `data`.
+  - the wallet **MUST** throw a `4602` error if the decoding fails with the given encoding value.
+
+#### Semantic of `signer`
+
+- it **MUST** be a valid `Ed25519Pk` object, otherwise the wallet **MUST** reject.
+- the wallet **MUST** reject if `signer` is unknown.
+
+#### General Validation
+
+Every input of the `signData(data, metadata, signer)` must be validated.
+
+The validation:
+
+- **SHALL NOT** rely on TypeScript typing as this can be bypassed. Types **MUST** be manually verified.
+- **SHALL NOT** assume that the provided `data` complies with the respective `metadata.schema`. The schema **MUST** be manually verified and all the required parameters **MUST** be checked.
+- **SHALL NOT** assume that signatures are computed with the Algorand SDK `signBytes` function. There is no indirect validation on the passed `data` and `metadata` objects on that function. In general, the validation **SHALL NOT** rely on underlying SDKs to validate the inputs of an ARC-60 signing operation.
+
+#### Display warnings
+
+The wallet **MUST** display a warning message when the signing request (`ScopeType`) is related to a known Algorand action like `LSIG`, i.e. signing a logic signature for delegation.
+
+## Rationale
+
+This API was designed to enable a secure and structured signing generic data with Algorand wallets. The API:
+
+- Is generic to _pure_ ed25519 key pairs and do not require keys manipulation
+- Is easy to extend with custom JSON schema to support future signing use cases (e.g. authentication)
+- Is secure by design preventing malicious applications to trick users signing malicious messages or in worst cases approve malicious transactions.
+
+This API was not designed to sign Algorand transactions or group of transactions (see ARC-1 instead).
+
+## Backwards Compatibility
+
+This ARC is not backward compatible with [ARC-47](./arc-0047.md) Logic Signature Template.
+
+ARC-47 introduces the method `algo_templatedLsig` that takes a `LogicSignatureDescription` object and returns the signature of a logic signature program for delegation.
+
+Al alternative using the ARC-60 `signData()` is given below, where:
+
+- `data` **MUST** specify:
+  - the `LogicSignatureDescription` object as detailed in ARC-47
+  - the `values` of the templated variables and the `hash` of the expected program
+  - the `ARC60Domain` must be set to the domain separator `"Program"`, as specified in the <a href="https://github.com/algorandfoundation/specs/blob/master/dev/crypto.md#domain-separation">Algorand specs</a>.
+- `metadata` **MUST** specify:
+  - an extended ARC-60 compatible JSON schema
+  - `ScopeType` set to `LSIG`.
+
+The extended schema can be found in the `../assets/arc-0060` folder at the file [lsig-schema.json](../assets/arc-0060/lsig-schema.json).
+
+### Semantics for signing a Logic Signature
+
+- if the `metadata.scope` is set to `LSIG`:
+  - the `ARC60Domain` value **MUST** be equal to the byte array corresponding to the prefix `"Program"`.
+  - the JSON schema **MUST** define `data.bytes` as an array of objects, such as the `LogicSignatureDescription`, `values`, and `hash`.
+  - the wallet **MUST** follow the ARC-47 specification: compile the program from the received template and check the integrity.
+  - the computed `signData` beign signed **MUST** be equal to the compiled program prepended with the `"Program"` domain separator, otherwise the wallet **MUST** fail.
+
+## Test Cases
+
+N/A
+
+## Reference Implementation
+
+A reference implementation is available in the `../assets/arc-0060` folder.
+
+- [simple-schema.json](../assets/arc-0060/simple-schema.json) provides a simple ARC-60 JSON schema
+- [wallet.ts](../assets/arc-0060/wallet.ts) contains a simple TypeScript script showing how wallets can implement the `SignDataFunction` interface
+
+## Security Considerations
+
+Users signing bytes can be tricked to sign malicious messages being exposed to man-in-the-middle attacks.
+
+Users must be aware of what they are signing and for what purpose. The wallet **MUST** always show the message being signed along with the scope of the signing action and the message (if any). The requested signer **MUST** be displayed as well.
+
+> For example:"You are about to sign the bytes `ARC60 is awesome` with scope `MSGSIG` and message `Sign arbitrary bytes` with the key `1Cz6hgjfllYajnodkJ2hCi+GiYF6ndMHMstH9tJOqlg=`".
+
+## Copyright
+
+Copyright and related rights waived via <a href="https://creativecommons.org/publicdomain/zero/1.0/">CCO</a>.

assets/arc-0060/.gitignore

@@ -0,0 +1,38 @@
+# Logs
+logs/
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+# Compiled javascript
+*.js
+
+# Dependency directories
+node_modules/
+
+# Optional npm cache directory
+.npm
+
+# Optional eslint cache
+.eslintcache
+
+# Misc files and directories
+.DS_Store
+.fleet
+.idea
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+!.vscode/settings.json.example
+.idea
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+.vscode-test