From 9a0bbb428faf11046e5623088650c07799d1b2f3 Mon Sep 17 00:00:00 2001 From: philipliu Date: Thu, 5 Dec 2024 15:25:57 -0500 Subject: [PATCH] Support SEP-45 authenticated accounts --- ecosystem/sep-0012.md | 65 ++++++++++++++++++++++--------------------- 1 file changed, 34 insertions(+), 31 deletions(-) diff --git a/ecosystem/sep-0012.md b/ecosystem/sep-0012.md index 2576afab2..5c0cd8ce3 100644 --- a/ecosystem/sep-0012.md +++ b/ecosystem/sep-0012.md @@ -7,7 +7,7 @@ Author: Interstellar Status: Active Created: 2018-09-11 Updated: 2024-07-23 -Version 1.14.0 +Version 1.15.0 ``` ## Abstract @@ -37,7 +37,8 @@ the API endpoints according to the protocol will work with any compliant wallet. - An anchor must define the location of their `KYC_SERVER` or `TRANSFER_SERVER` in their [`stellar.toml`](sep-0001.md). This is how a client app knows where to find the anchor's server. A client app will send KYC requests to the `KYC_SERVER` if it is specified, otherwise to the `TRANSFER_SERVER`. -- Anchors and clients must support [SEP-10](sep-0010.md) web authentication and use it for all SEP-12 endpoints. +- Anchors and clients must support [SEP-10](sep-0010.md) and optionally [SEP-45](sep-0045.md) web authentication and use + it for all SEP-12 endpoints. ## API Endpoints @@ -119,21 +120,21 @@ GET [KYC_SERVER]/customer?account=&type= GET [KYC_SERVER]/customer?id=&type= ``` -| Name | Type | Description | -| ---------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `id` | `string` | (optional) The ID of the customer as returned in the response of a previous `PUT` request. If the customer has not been registered, they do not yet have an `id`. | -| `account` | `G...` or `M...` string | (**deprecated**, optional) The server should infer the account from the `sub` value in the SEP-10 JWT to identify the customer. The `account` parameter is only used for backwards compatibility, and if explicitly provided in the request body it should match the `sub` value of the decoded SEP-10 JWT. | -| `memo` | string | (optional) the client-generated [memo](https://developers.stellar.org/docs/glossary/transactions/#memo) that uniquely identifies the customer. If a memo is present in the decoded SEP-10 JWT's `sub` value, it must match this parameter value. If a muxed account is used as the JWT's `sub` value, memos sent in requests must match the 64-bit integer subaccount ID of the muxed account. See the [Shared Accounts](#shared-omnibus-or-pooled-accounts) section for more information. | -| `memo_type` | string | (**deprecated**, optional) type of `memo`. One of `text`, `id` or `hash`. Deprecated because memos should always be of type `id`, although anchors should continue to support this parameter for outdated clients. If `hash`, `memo` should be base64-encoded. If a memo is present in the decoded SEP-10 JWT's `sub` value, this parameter can be ignored. See the [Shared Accounts](#shared-omnibus-or-pooled-accounts) section for more information. | -| `type` | string | (optional) the type of action the customer is being KYCd for. See the [Type Specification](#type-specification) below. | -| `transaction_id` | `string` | (optional) The transaction id with which the customer's info is associated. When information from the customer depends on the transaction (e.g., more information is required for larger amounts) | -| `lang` | string | (optional) Defaults to `en`. Language code specified using [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1). Human readable descriptions, choices, and messages should be in this language. | +| Name | Type | Description | +| ---------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `id` | `string` | (optional) The ID of the customer as returned in the response of a previous `PUT` request. If the customer has not been registered, they do not yet have an `id`. | +| `account` | `G...` or `M...` or `C...` string | (**deprecated**, optional) The server should infer the account from the `sub` value in the SEP-10/SEP-45 JWT to identify the customer. The `account` parameter is only used for backwards compatibility, and if explicitly provided in the request body it should match the `sub` value of the decoded SEP-10/SEP-45 JWT. | +| `memo` | string | (optional) the client-generated [memo](https://developers.stellar.org/docs/glossary/transactions/#memo) that uniquely identifies the customer. If a memo is present in the decoded SEP-10 JWT's `sub` value, it must match this parameter value. If a muxed account is used as the JWT's `sub` value, memos sent in requests must match the 64-bit integer subaccount ID of the muxed account. See the [Shared Accounts](#shared-omnibus-or-pooled-accounts) section for more information. | +| `memo_type` | string | (**deprecated**, optional) type of `memo`. One of `text`, `id` or `hash`. Deprecated because memos should always be of type `id`, although anchors should continue to support this parameter for outdated clients. If `hash`, `memo` should be base64-encoded. If a memo is present in the decoded SEP-10 JWT's `sub` value, this parameter can be ignored. See the [Shared Accounts](#shared-omnibus-or-pooled-accounts) section for more information. | +| `type` | string | (optional) the type of action the customer is being KYCd for. See the [Type Specification](#type-specification) below. | +| `transaction_id` | `string` | (optional) The transaction id with which the customer's info is associated. When information from the customer depends on the transaction (e.g., more information is required for larger amounts) | +| `lang` | string | (optional) Defaults to `en`. Language code specified using [ISO 639-1](https://en.wikipedia.org/wiki/ISO_639-1). Human readable descriptions, choices, and messages should be in this language. | #### ID vs. Account & Memo The client can always use the `account` and optional `memo` parameters to uniquely identify a customer, and when not explicitly passed in the request body the server can still infer this information from the decoded SEP-10 JWT's `sub` -value. If a `PUT /customer` request has already been made for the customer, the client should preferrably use the `id` +value. If a `PUT /customer` request has already been made for the customer, the client should preferably use the `id` returned in the response instead. #### Type Specification @@ -397,14 +398,14 @@ Content-Type: application/json } ``` -| Name | Type | Description | -| ---------------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `id` | string | (optional) The `id` value returned from a previous call to this endpoint. If specified, no other parameter is required. | -| `account` | `G...` or `M...` string | (**deprecated**, optional) The server should infer the account from the `sub` value in the SEP-10 JWT to identify the customer. The `account` parameter is only used for backwards compatibility, and if explicitly provided in the request body it should match the `sub` value of the decoded SEP-10 JWT. | -| `memo` | string | (optional) the client-generated [memo](https://developers.stellar.org/docs/glossary/transactions/#memo) that uniquely identifies the customer. If a memo is present in the decoded SEP-10 JWT's `sub` value, it must match this parameter value. If a muxed account is used as the JWT's `sub` value, memos sent in requests must match the 64-bit integer subaccount ID of the muxed account. See the [Shared Accounts](#shared-omnibus-or-pooled-accounts) section for more information. | -| `memo_type` | string | (**deprecated**, optional) type of `memo`. One of `text`, `id` or `hash`. Deprecated because memos should always be of type `id`, although anchors should continue to support this parameter for outdated clients. If `hash`, `memo` should be base64-encoded. If a memo is present in the decoded SEP-10 JWT's `sub` value, this parameter can be ignored. See the [Shared Accounts](#shared-omnibus-or-pooled-accounts) section for more information. | -| `type` | string | (optional) The type of the customer as defined in the [Type Specification](#type-specification). | -| `transaction_id` | `string` | (optional) The transaction id with which the customer's info is associated. When information from the customer depends on the transaction (e.g., more information is required for larger amounts) | +| Name | Type | Description | +| ---------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `id` | string | (optional) The `id` value returned from a previous call to this endpoint. If specified, no other parameter is required. | +| `account` | `G...` or `M...` or `C...` string | (**deprecated**, optional) The server should infer the account from the `sub` value in the SEP-10/SEP-45 JWT to identify the customer. The `account` parameter is only used for backwards compatibility, and if explicitly provided in the request body it should match the `sub` value of the decoded SEP-10/SEP-45 JWT. | +| `memo` | string | (optional) the client-generated [memo](https://developers.stellar.org/docs/glossary/transactions/#memo) that uniquely identifies the customer. If a memo is present in the decoded SEP-10 JWT's `sub` value, it must match this parameter value. If a muxed account is used as the JWT's `sub` value, memos sent in requests must match the 64-bit integer subaccount ID of the muxed account. See the [Shared Accounts](#shared-omnibus-or-pooled-accounts) section for more information. | +| `memo_type` | string | (**deprecated**, optional) type of `memo`. One of `text`, `id` or `hash`. Deprecated because memos should always be of type `id`, although anchors should continue to support this parameter for outdated clients. If `hash`, `memo` should be base64-encoded. If a memo is present in the decoded SEP-10 JWT's `sub` value, this parameter can be ignored. See the [Shared Accounts](#shared-omnibus-or-pooled-accounts) section for more information. | +| `type` | string | (optional) The type of the customer as defined in the [Type Specification](#type-specification). | +| `transaction_id` | `string` | (optional) The transaction id with which the customer's info is associated. When information from the customer depends on the transaction (e.g., more information is required for larger amounts) | The wallet should also transmit one or more of the fields listed in [SEP-9](./sep-0009.md), depending on what the anchor has indicated it needs. @@ -540,10 +541,11 @@ should be returned. On any other client error, use a `400` status. ## Customer DELETE -Delete all personal information that the anchor has stored about a given customer. `[account]` is the Stellar account ID -(`G...`) of the customer to delete. This request must be authenticated (via [SEP-10](sep-0010.md)) as coming from the -owner of the account that will be deleted. If `account` does not uniquely identify an individual customer (a shared -account), the client should include the `memo` and `memo_type` fields in the request body. +Delete all personal information that the anchor has stored about a given customer. `[account]` is a Stellar account ID +(`G...`) or contract account address (`C...`) of the customer to delete. This request must be authenticated (via +[SEP-10](sep-0010.md) or [SEP-45](sep-0045.md)) as coming from the owner of the account that will be deleted. If +`account` does not uniquely identify an individual customer (a shared account), the client should include the `memo` and +`memo_type` fields in the request body. ### Request @@ -580,13 +582,13 @@ it will need to set a callback again. PUT [KYC_SERVER || TRANSFER_SERVER]/customer/callback ``` -| Name | Type | Description | -| ----------- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `id` | `string` | (optional) The ID of the customer as returned in the response of a previous `PUT` request. If the customer has not been registered, they do not yet have an `id`. | -| `account` | `G...` or `M...` string | (**deprecated**, optional) The server should infer the account from the `sub` value in the SEP-10 JWT to identify the customer. The `account` parameter is only used for backwards compatibility, and if explicitly provided in the request body it should match the `sub` value of the decoded SEP-10 JWT. | -| `memo` | string | (optional) the client-generated [memo](https://developers.stellar.org/docs/glossary/transactions/#memo) that uniquely identifies the customer. If a memo is present in the decoded SEP-10 JWT's `sub` value, it must match this parameter value. If a muxed account is used as the JWT's `sub` value, memos sent in requests must match the 64-bit integer subaccount ID of the muxed account. See the [Shared Accounts](#shared-omnibus-or-pooled-accounts) section for more information. | -| `memo_type` | string | (**deprecated**, optional) type of `memo`. One of `text`, `id` or `hash`. Deprecated because memos should always be of type `id`, although anchors should continue to support this parameter for outdated clients. If `hash`, `memo` should be base64-encoded. If a memo is present in the decoded SEP-10 JWT's `sub` value, this parameter can be ignored. See the [Shared Accounts](#shared-omnibus-or-pooled-accounts) section for more information. | -| `url` | `string` | A callback URL that the SEP-12 server will POST to when the state of the account changes. | +| Name | Type | Description | +| ----------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `id` | `string` | (optional) The ID of the customer as returned in the response of a previous `PUT` request. If the customer has not been registered, they do not yet have an `id`. | +| `account` | `G...` or `M...` or `C...` string | (**deprecated**, optional) The server should infer the account from the `sub` value in the SEP-10/SEP-45 JWT to identify the customer. The `account` parameter is only used for backwards compatibility, and if explicitly provided in the request body it should match the `sub` value of the decoded SEP-10/SEP-45 JWT. | +| `memo` | string | (optional) the client-generated [memo](https://developers.stellar.org/docs/glossary/transactions/#memo) that uniquely identifies the customer. If a memo is present in the decoded SEP-10 JWT's `sub` value, it must match this parameter value. If a muxed account is used as the JWT's `sub` value, memos sent in requests must match the 64-bit integer subaccount ID of the muxed account. See the [Shared Accounts](#shared-omnibus-or-pooled-accounts) section for more information. | +| `memo_type` | string | (**deprecated**, optional) type of `memo`. One of `text`, `id` or `hash`. Deprecated because memos should always be of type `id`, although anchors should continue to support this parameter for outdated clients. If `hash`, `memo` should be base64-encoded. If a memo is present in the decoded SEP-10 JWT's `sub` value, this parameter can be ignored. See the [Shared Accounts](#shared-omnibus-or-pooled-accounts) section for more information. | +| `url` | `string` | A callback URL that the SEP-12 server will POST to when the state of the account changes. | ### PUT Responses @@ -784,6 +786,7 @@ All responses should return `200 OK`. If no files are found for the identifer us ## Changelog +- `v1.15.0`: Support SEP-45 authenticated accounts ([#1580](https://github.com/stellar/stellar-protocol/pull/1580)) - `v1.14.0`: Update SEP31 with async kyc flow ([#1502](https://github.com/stellar/stellar-protocol/pull/1502)) - `v1.13.0`: Add `transaction_id` field to `/customer` `GET` and `PUT` ([#1432](https://github.com/stellar/stellar-protocol/pull/1432))