feat(api): add back action kind, reject on inbound definitions (#379)

## Summary

Adds `back` to the action `kind` enum on `step-action.yaml` so the
engine can emit it on rendered step responses for back-navigation (ADR
022). The domain validator rejects any declared action with `kind:
back`, since flow authors must never declare it themselves.

Contract + validator only — no engine behavior changes.

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: vitorbari

api/generated/oas_json_gen.go

@@ -11,7 +11,7 @@ properties:
     example: submit
   kind:
     type: string
-    enum: [submit, passkey, passkey_register, navigate]
+    enum: [submit, passkey, passkey_register, navigate, back]
     example: submit
     description: |
       Classifies how the engine handles this action:
@@ -21,7 +21,9 @@ properties:
       - `passkey_register`: issue a WebAuthn registration challenge; the matching
         transition fires once the returned attestation verifies.
       - `navigate`: route through the transition without running the input
-        pipeline. Used for back-navigation and similar pure-routing actions.
+        pipeline. Used for pure-routing actions declared in the flow definition.
+      - `back`: return the user to the previous step. Surfaced by the engine
+        when going back is available.
   primary:
     type: boolean
     default: false

api/generated/oas_schemas_gen.go

@@ -96,9 +96,14 @@ const (
 	// verifies.
 	FlowActionKindPasskeyRegister
 	// FlowActionKindNavigate routes through the transition without running
-	// the input pipeline. Used for back-navigation and similar pure-routing
-	// actions where the submitted fields are irrelevant.
+	// the input pipeline. Used for pure-routing actions declared in the flow
+	// definition where the submitted fields are irrelevant.
 	FlowActionKindNavigate
+	// FlowActionKindBack pops the previous step from runtime history and
+	// re-renders it. Injected by the engine on rendered step responses when
+	// history is non-empty and the current step is non-terminal; rejected by
+	// the validator on inbound flow definitions — flow authors never declare it.
+	FlowActionKindBack
 )
 
 // FlowDefinition is a customer-configured directed graph of authentication steps.

api/generated/oas_validators_gen.go

@@ -126,6 +126,10 @@ func validateSteps(steps []FlowDefinitionStep, userSchema *jsonschema.Schema) er
 				return ErrFlowDefinitionInvalid(fmt.Sprintf(
 					"step %q: action %q has no kind", step.Name, a.Name), nil)
 			}
+			if a.Kind == FlowActionKindBack {
+				return ErrFlowDefinitionInvalid(fmt.Sprintf(
+					"step %q: action %q has kind=back, which is engine-injected and cannot be declared", step.Name, a.Name), nil)
+			}
 			actionNames[a.Name] = struct{}{}
 		}
 

api/openapi/components/flows/step-action.yaml

@@ -1247,3 +1247,27 @@ func TestValidator_MissingActionKindRejected(t *testing.T) {
 	require.Error(t, err)
 	assert.Contains(t, errorDetails(t, err), `action "submit" has no kind`)
 }
+
+// TestValidator_DeclaredBackKindRejected guards against authors declaring
+// `kind: back` directly on a flow definition. The engine injects back on
+// rendered responses; declaring it on the definition would let an author
+// override the engine's reversibility rules and is not permitted.
+func TestValidator_DeclaredBackKindRejected(t *testing.T) {
+	schema := mustSchema(t, userSchemaIDAndPassword)
+	def := domain.FlowDefinition{
+		ProjectID: "p", Name: "f", SchemaVersion: "1",
+		UserSchema: "https://tenant.com/schemas/idpw-user.json",
+		Purposes:   map[domain.FlowDefinitionPurpose]string{domain.FlowDefinitionPurposeLogin: "step"},
+		Steps: []domain.FlowDefinitionStep{
+			{
+				Name: "step", Fields: []string{"email"},
+				Actions:     []domain.FlowStepAction{{Name: "back", Kind: domain.FlowActionKindBack}},
+				Transitions: map[string]domain.FlowStepTransition{"back": {Target: "done"}},
+			},
+			{Name: "done", Complete: gu.Ptr(domain.FlowStepCompleteShow)},
+		},
+	}
+	_, err := domain.ValidateFlowDefinition(schema, def)
+	require.Error(t, err)
+	assert.Contains(t, errorDetails(t, err), `action "back" has kind=back, which is engine-injected and cannot be declared`)
+}