feat: implement account recovery skeleton (#294)

This patch implements the account recovery request skeleton with endpoints such as "Init Account Recovery", a new config value `urls�.recovery_ui` and so on.

Additionally, some refactoring was made to DRY code and make naming consistent.

See #37

BREAKING CHANGEs: The field `identity.addresses` has moved to `identity.verifiable_addresses`. A new field has been added
`identity.recovery_addresses`. Configuration key `selfservice.verify` was renamed to `selfservice.verification`. Configuration key `selfservice.verification.link_lifespan`
has been merged with  `selfservice.verification.request_lifespan`.

.bin/.lock

@@ -0,0 +1 @@
+v0

.schema/api.swagger.json

@@ -402,6 +402,31 @@
         }
       }
     },
+    "/self-service/browser/flows/recovery": {
+      "get": {
+        "description": "This endpoint initializes a browser-based account recovery flow. Once initialized, the browser will be redirected to\n`urls.recovery_ui` with the request ID set as a query parameter. If a valid user session exists, the request\nis aborted.\n\n\u003e This endpoint is NOT INTENDED for API clients and only works\nwith browsers (Chrome, Firefox, ...).\n\nMore information can be found at [ORY Kratos Account Recovery Documentation](../self-service/flows/password-reset-account-recovery).",
+        "schemes": [
+          "http",
+          "https"
+        ],
+        "tags": [
+          "public"
+        ],
+        "summary": "Initialize browser-based account recovery flow",
+        "operationId": "initializeSelfServiceRecoveryFlow",
+        "responses": {
+          "302": {
+            "description": "Empty responses are sent when, for example, resources are deleted. The HTTP status code for empty responses is\ntypically 201."
+          },
+          "500": {
+            "description": "genericError",
+            "schema": {
+              "$ref": "#/definitions/genericError"
+            }
+          }
+        }
+      }
+    },
     "/self-service/browser/flows/registration": {
       "get": {
         "description": "This endpoint initializes a browser-based user registration flow. Once initialized, the browser will be redirected to\n`urls.registration_ui` with the request ID set as a query parameter. If a valid user session exists already, the browser will be\nredirected to `urls.default_redirect_url`.\n\n\u003e This endpoint is NOT INTENDED for API clients and only works\nwith browsers (Chrome, Firefox, ...).\n\nMore information can be found at [ORY Kratos User Login and User Registration Documentation](https://www.ory.sh/docs/next/kratos/self-service/flows/user-login-user-registration).",
@@ -516,6 +541,66 @@
         }
       }
     },
+    "/self-service/browser/flows/requests/recovery": {
+      "get": {
+        "description": "When accessing this endpoint through ORY Kratos' Public API, ensure that cookies are set as they are required\nfor checking the auth session. To prevent scanning attacks, the public endpoint does not return 404 status codes\nbut instead 403 or 500.\n\nMore information can be found at [ORY Kratos Account Recovery Documentation](../self-service/flows/password-reset-account-recovery).",
+        "produces": [
+          "application/json"
+        ],
+        "schemes": [
+          "http",
+          "https"
+        ],
+        "tags": [
+          "common",
+          "public",
+          "admin"
+        ],
+        "summary": "Get the request context of browser-based recovery flows",
+        "operationId": "getSelfServiceBrowserRecoveryRequest",
+        "parameters": [
+          {
+            "type": "string",
+            "description": "Request is the Login Request ID\n\nThe value for this parameter comes from `request` URL Query parameter sent to your\napplication (e.g. `/recover?request=abcde`).",
+            "name": "request",
+            "in": "query",
+            "required": true
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "recoveryRequest",
+            "schema": {
+              "$ref": "#/definitions/recoveryRequest"
+            }
+          },
+          "403": {
+            "description": "genericError",
+            "schema": {
+              "$ref": "#/definitions/genericError"
+            }
+          },
+          "404": {
+            "description": "genericError",
+            "schema": {
+              "$ref": "#/definitions/genericError"
+            }
+          },
+          "410": {
+            "description": "genericError",
+            "schema": {
+              "$ref": "#/definitions/genericError"
+            }
+          },
+          "500": {
+            "description": "genericError",
+            "schema": {
+              "$ref": "#/definitions/genericError"
+            }
+          }
+        }
+      }
+    },
     "/self-service/browser/flows/requests/registration": {
       "get": {
         "description": "This endpoint returns a registration request's context with, for example, error details and\nother information.\n\nWhen accessing this endpoint through ORY Kratos' Public API, ensure that cookies are set as they are required for CSRF to work. To prevent\ntoken scanning attacks, the public endpoint does not return 404 status codes to prevent scanning attacks.\n\nMore information can be found at [ORY Kratos User Login and User Registration Documentation](https://www.ory.sh/docs/next/kratos/self-service/flows/user-login-user-registration).",
@@ -596,7 +681,7 @@
         "parameters": [
           {
             "type": "string",
-            "description": "Request is the Login Request ID\n\nThe value for this parameter comes from `request` URL Query parameter sent to your\napplication (e.g. `/login?request=abcde`).",
+            "description": "Request is the Login Request ID\n\nThe value for this parameter comes from `request` URL Query parameter sent to your\napplication (e.g. `/settingss?request=abcde`).",
             "name": "request",
             "in": "query",
             "required": true
@@ -1053,15 +1138,15 @@
         "traits"
       ],
       "properties": {
-        "addresses": {
+        "id": {
+          "$ref": "#/definitions/UUID"
+        },
+        "recovery_addresses": {
           "type": "array",
           "items": {
-            "$ref": "#/definitions/VerifiableAddress"
+            "$ref": "#/definitions/RecoveryAddress"
           }
         },
-        "id": {
-          "$ref": "#/definitions/UUID"
-        },
         "traits": {
           "$ref": "#/definitions/Traits"
         },
@@ -1072,6 +1157,12 @@
         "traits_schema_url": {
           "description": "TraitsSchemaURL is the URL of the endpoint where the identity's traits schema can be fetched from.\n\nformat: url",
           "type": "string"
+        },
+        "verifiable_addresses": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/VerifiableAddress"
+          }
         }
       }
     },
@@ -1086,6 +1177,41 @@
         }
       }
     },
+    "RecoveryAddress": {
+      "type": "object",
+      "required": [
+        "id",
+        "value",
+        "via",
+        "recovered",
+        "expires_at"
+      ],
+      "properties": {
+        "expires_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "id": {
+          "$ref": "#/definitions/UUID"
+        },
+        "recovered": {
+          "type": "boolean"
+        },
+        "recovered_at": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "value": {
+          "type": "string"
+        },
+        "via": {
+          "$ref": "#/definitions/RecoveryAddressType"
+        }
+      }
+    },
+    "RecoveryAddressType": {
+      "type": "string"
+    },
     "RequestMethodConfig": {
       "type": "object",
       "required": [
@@ -1114,6 +1240,9 @@
         }
       }
     },
+    "State": {
+      "type": "string"
+    },
     "Traits": {
       "type": "object"
     },
@@ -1412,6 +1541,64 @@
         }
       }
     },
+    "recoveryRequest": {
+      "description": "This request is used when an identity wants to recover their account.\n\nWe recommend reading the [Account Recovery Documentation](../self-service/flows/password-reset-account-recovery)",
+      "type": "object",
+      "title": "Request presents a recovery request",
+      "required": [
+        "id",
+        "expires_at",
+        "issued_at",
+        "request_url",
+        "methods",
+        "state"
+      ],
+      "properties": {
+        "active": {
+          "description": "Active, if set, contains the registration method that is being used. It is initially\nnot set.",
+          "type": "string"
+        },
+        "expires_at": {
+          "description": "ExpiresAt is the time (UTC) when the request expires. If the user still wishes to update the setting,\na new request has to be initiated.",
+          "type": "string",
+          "format": "date-time"
+        },
+        "id": {
+          "$ref": "#/definitions/UUID"
+        },
+        "issued_at": {
+          "description": "IssuedAt is the time (UTC) when the request occurred.",
+          "type": "string",
+          "format": "date-time"
+        },
+        "methods": {
+          "description": "Methods contains context for all account recovery methods. If a registration request has been\nprocessed, but for example the password is incorrect, this will contain error messages.",
+          "type": "object",
+          "additionalProperties": {
+            "$ref": "#/definitions/recoveryRequestMethod"
+          }
+        },
+        "request_url": {
+          "description": "RequestURL is the initial URL that was requested from ORY Kratos. It can be used\nto forward information contained in the URL's path or query for example.",
+          "type": "string"
+        },
+        "state": {
+          "$ref": "#/definitions/State"
+        }
+      }
+    },
+    "recoveryRequestMethod": {
+      "type": "object",
+      "properties": {
+        "config": {
+          "$ref": "#/definitions/RequestMethodConfig"
+        },
+        "method": {
+          "description": "Method contains the request credentials type.",
+          "type": "string"
+        }
+      }
+    },
     "registrationRequest": {
       "type": "object",
       "required": [
@@ -1573,7 +1760,7 @@
           "type": "string"
         },
         "update_successful": {
-          "description": "UpdateSuccessful, if true, indicates that the settings request has been updated successfully with the provided data.\nDone will stay true when repeatedly checking. If set to true, done will revert back to false only\nwhen a request with invalid (e.g. \"please use a valid phone number\") data was sent.",
+          "description": "Success, if true, indicates that the settings request has been updated successfully with the provided data.\nDone will stay true when repeatedly checking. If set to true, done will revert back to false only\nwhen a request with invalid (e.g. \"please use a valid phone number\") data was sent.",
           "type": "boolean"
         }
       }

.schema/config.schema.json

@@ -387,7 +387,7 @@
           "properties": {
             "request_lifespan": {
               "title": "Self-Service Verification Request Lifespan",
-              "description": "Sets how long the verification request (for the UI interaction) is valid.",
+              "description": "Sets how long the verification request (both for the UI interaction as well as the verification code) is valid.",
               "type": "string",
               "pattern": "^[0-9]+(ns|us|ms|s|m|h)$",
               "default": "1h",
@@ -396,18 +396,6 @@
                 "1m",
                 "1s"
               ]
-            },
-            "link_lifespan": {
-              "title": "Self-Service Verification Link Lifespan",
-              "description": "Sets how long the verification link (e.g. the one sent via email) is valid for.",
-              "type": "string",
-              "pattern": "^[0-9]+(ns|us|ms|s|m|h)$",
-              "default": "24h",
-              "examples": [
-                "1h",
-                "1m",
-                "1s"
-              ]
             }
           }
         },

UPGRADE.md

@@ -10,6 +10,17 @@ before finalizing the upgrade process.
 These changes have not yet been released and this area's purpose is to keep
 track of future changes.
 
+### Identity
+
+
+### Account verification
+
+The field `identity.addresses` has moved to `identity.verifiable_addresses`. A new field has been added
+`identity.recovery_addresses`.
+
+Configuration key `selfservice.verify` was renamed to `selfservice.verification`. Configuration key `selfservice.verification.link_lifespan`
+has been merged with  `selfservice.verification.request_lifespan`.
+
 ## v0.3.0-alpha.1
 
 This release finalizes the OpenID Connect and OAuth2 login, registration, and settings strategy with JsonNet data transformation! From now on, "Sign in with Google, Github, ..." is officially supported! It's also possible to link and unlink these connections using the Self-Service Settings Flow! The documentation has been updated to reflect those changes and includes guides to setting up "Sign in with GitHub" in under 5 Minutes! Please be aware that existing OpenID Connect connections will stop working. Check out the "Breaking Changes" section for more info! Want to learn more? Check [out the docs](https://www.ory.sh/kratos/docs/concepts/credentials/openid-connect-oidc-oauth2)!

courier/template/recover_invalid.go

@@ -0,0 +1,33 @@
+package template
+
+import (
+	"path/filepath"
+
+	"github.com/ory/kratos/driver/configuration"
+)
+
+type (
+	RecoverInvalid struct {
+		c configuration.Provider
+		m *RecoverInvalidModel
+	}
+	RecoverInvalidModel struct {
+		To string
+	}
+)
+
+func NewRecoverInvalid(c configuration.Provider, m *RecoverInvalidModel) *RecoverInvalid {
+	return &RecoverInvalid{c: c, m: m}
+}
+
+func (t *RecoverInvalid) EmailRecipient() (string, error) {
+	return t.m.To, nil
+}
+
+func (t *RecoverInvalid) EmailSubject() (string, error) {
+	return loadTextTemplate(filepath.Join(t.c.CourierTemplatesRoot(), "recover/invalid/email.subject.gotmpl"), t.m)
+}
+
+func (t *RecoverInvalid) EmailBody() (string, error) {
+	return loadTextTemplate(filepath.Join(t.c.CourierTemplatesRoot(), "recover/invalid/email.body.gotmpl"), t.m)
+}

courier/template/recover_invalid_test.go

@@ -0,0 +1,24 @@
+package template_test
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/ory/kratos/courier/template"
+	"github.com/ory/kratos/internal"
+)
+
+func TestRecoverInvalid(t *testing.T) {
+	conf, _ := internal.NewFastRegistryWithMocks(t)
+	tpl := template.NewRecoverInvalid(conf, &template.RecoverInvalidModel{})
+
+	rendered, err := tpl.EmailBody()
+	require.NoError(t, err)
+	assert.NotEmpty(t, rendered)
+
+	rendered, err = tpl.EmailSubject()
+	require.NoError(t, err)
+	assert.NotEmpty(t, rendered)
+}