@whooshbang/contracts 1.0.0-rc.20 → 1.0.0-rc.21

package/schemas/whooshbang-v1.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://whooshbang.flowxo.com/schemas/whooshbang-v1.schema.json",
-  "x-contract-version": "1.0.0-rc.20",
+  "x-contract-version": "1.0.0-rc.21",
   "title": "WhooshBangV1ContractDocument",
   "description": "Public request, resource, summary, and Problem Details models for the WhooshBang V1 REST API.",
   "anyOf": [
@@ -41,6 +41,24 @@
     {
       "$ref": "#/$defs/ApiCredentialRotation"
     },
+    {
+      "$ref": "#/$defs/CreateAccountCredentialRequest"
+    },
+    {
+      "$ref": "#/$defs/RotateAccountCredentialRequest"
+    },
+    {
+      "$ref": "#/$defs/AccountCredential"
+    },
+    {
+      "$ref": "#/$defs/AccountCredentialCollection"
+    },
+    {
+      "$ref": "#/$defs/AccountCredentialSecretReveal"
+    },
+    {
+      "$ref": "#/$defs/AccountCredentialRotation"
+    },
     {
       "$ref": "#/$defs/CreateCustomerEndpointRequest"
     },
@@ -104,6 +122,18 @@
     {
       "$ref": "#/$defs/AttachNotifierConnectionRequest"
     },
+    {
+      "$ref": "#/$defs/ConnectionTest"
+    },
+    {
+      "$ref": "#/$defs/ConnectionTestCollection"
+    },
+    {
+      "$ref": "#/$defs/CreateConnectionTestRequest"
+    },
+    {
+      "$ref": "#/$defs/CustomerOwnedSlackAppManifest"
+    },
     {
       "$ref": "#/$defs/ProjectRecipientExperience"
     },
@@ -916,6 +946,210 @@
       },
       "additionalProperties": false
     },
+    "AccountCredentialId": {
+      "type": "string",
+      "pattern": "^acred_[A-Za-z0-9_-]{21}[AQgw]$",
+      "description": "acred_ followed by the canonical unpadded base64url encoding of exactly 16 random bytes."
+    },
+    "AccountCredentialPrefix": {
+      "type": "string",
+      "pattern": "^wb_ac1\\.acred_[A-Za-z0-9_-]{8}$",
+      "description": "A safe display prefix containing the account-credential format marker and first eight base64url identity characters, never secret bytes."
+    },
+    "AccountCredentialSecret": {
+      "type": "string",
+      "pattern": "^wb_ac1\\.acred_[A-Za-z0-9_-]{21}[AQgw]\\.[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$",
+      "description": "The exact one-time runtime bearer syntax. The final segment is canonical unpadded base64url for exactly 32 random secret bytes."
+    },
+    "AccountCredentialScope": {
+      "type": "string",
+      "enum": [
+        "account:read",
+        "projects:write",
+        "projects:read",
+        "messages:write",
+        "messages:read",
+        "subscriptions:write",
+        "subscriptions:read",
+        "machine-clients:write",
+        "machine-clients:read",
+        "capabilities:read",
+        "connections:write",
+        "connections:read"
+      ],
+      "description": "One account-credential capability. `account:read` is the account's project directory — listing the account's projects and reading one — and is the only scope here a project credential can never carry; it authorizes nothing below the account. Every other name is the project-credential vocabulary unchanged, and is exercised only on the environment-scoped routes, where the project and environment come from the path and the credential's authority is the intersection of these scopes with the project-credential vocabulary. An account credential is therefore never wider than a project credential would have been for the same project environment."
+    },
+    "AccountCredentialScopeSet": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 12,
+      "uniqueItems": true,
+      "items": {
+        "$ref": "#/$defs/AccountCredentialScope"
+      }
+    },
+    "CreateAccountCredentialRequest": {
+      "type": "object",
+      "description": "Creates one credential against the whole account rather than one project environment.",
+      "required": ["label", "scopes"],
+      "properties": {
+        "label": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100
+        },
+        "scopes": {
+          "$ref": "#/$defs/AccountCredentialScopeSet"
+        }
+      },
+      "additionalProperties": false
+    },
+    "RotateAccountCredentialRequest": {
+      "type": "object",
+      "description": "Creates a replacement with the same label and scopes and schedules terminal revocation of the replaced credential after the declared overlap.",
+      "required": ["overlap_seconds"],
+      "properties": {
+        "overlap_seconds": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 86400
+        }
+      },
+      "additionalProperties": false
+    },
+    "AccountCredential": {
+      "type": "object",
+      "description": "Safe account-scoped API credential metadata. It carries no project or environment, because it names neither: a request does, in its path. It never contains a bearer secret, digest, Clerk identifier, or digest-key reference.",
+      "required": [
+        "id",
+        "prefix",
+        "label",
+        "scopes",
+        "created_by",
+        "created_at",
+        "status"
+      ],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/AccountCredentialId"
+        },
+        "prefix": {
+          "$ref": "#/$defs/AccountCredentialPrefix"
+        },
+        "label": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100
+        },
+        "scopes": {
+          "$ref": "#/$defs/AccountCredentialScopeSet"
+        },
+        "created_by": {
+          "$ref": "#/$defs/OpaqueIdentifier",
+          "description": "An opaque WhooshBang member identifier. It is never a Clerk user identifier."
+        },
+        "created_at": {
+          "$ref": "#/$defs/Timestamp"
+        },
+        "last_used_at": {
+          "$ref": "#/$defs/Timestamp"
+        },
+        "scheduled_revocation_at": {
+          "$ref": "#/$defs/Timestamp",
+          "description": "When an active credential in a rotation overlap becomes terminally revoked."
+        },
+        "status": {
+          "type": "string",
+          "enum": ["active", "revoked"]
+        },
+        "revoked_at": {
+          "$ref": "#/$defs/Timestamp"
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "status": {
+                "const": "revoked"
+              }
+            },
+            "required": ["status"]
+          },
+          "then": {
+            "required": ["revoked_at"],
+            "properties": {
+              "revoked_at": {},
+              "scheduled_revocation_at": false
+            }
+          },
+          "else": {
+            "properties": {
+              "revoked_at": false
+            }
+          }
+        }
+      ],
+      "additionalProperties": false
+    },
+    "AccountCredentialCollection": {
+      "type": "object",
+      "description": "A stable page of safe account-credential metadata for one account.",
+      "required": ["items"],
+      "properties": {
+        "items": {
+          "type": "array",
+          "maxItems": 100,
+          "items": {
+            "$ref": "#/$defs/AccountCredential"
+          }
+        },
+        "next_cursor": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256,
+          "pattern": "^[A-Za-z0-9_-]+$"
+        },
+        "page": {
+          "$ref": "#/$defs/ListPageNumber"
+        },
+        "page_size": {
+          "$ref": "#/$defs/ListPageSize"
+        },
+        "total": {
+          "$ref": "#/$defs/ListTotal"
+        }
+      },
+      "additionalProperties": false
+    },
+    "AccountCredentialSecretReveal": {
+      "type": "object",
+      "description": "The creation-only response. The secret is emitted in this response exactly once and is never available from list, rotate-target, revoke, or later read responses.",
+      "required": ["credential", "secret"],
+      "properties": {
+        "credential": {
+          "$ref": "#/$defs/AccountCredential"
+        },
+        "secret": {
+          "$ref": "#/$defs/AccountCredentialSecret"
+        }
+      },
+      "additionalProperties": false
+    },
+    "AccountCredentialRotation": {
+      "type": "object",
+      "description": "A creation-only replacement secret plus safe metadata for the credential it replaces.",
+      "required": ["credential", "replaced_credential"],
+      "properties": {
+        "credential": {
+          "$ref": "#/$defs/AccountCredentialSecretReveal"
+        },
+        "replaced_credential": {
+          "$ref": "#/$defs/AccountCredential"
+        }
+      },
+      "additionalProperties": false
+    },
     "BindingSummary": {
       "type": "object",
       "description": "A safe channel binding identity. Raw Telegram chat and user identifiers are never exposed. Legacy bindings may omit connection_id because no exact connection was recorded when they were authorized.",
@@ -3611,6 +3845,7 @@
         "resource_not_found",
         "resource_expired",
         "cancellation_too_late",
+        "credential_account_mismatch",
         "endpoint_rotation_conflict",
         "rate_limited",
         "provider_retryable",
@@ -4318,6 +4553,26 @@
             }
           }
         },
+        {
+          "type": "object",
+          "properties": {
+            "type": {
+              "const": "https://whooshbang.flowxo.com/problems/credential_account_mismatch"
+            },
+            "title": {
+              "const": "Credential account mismatch"
+            },
+            "status": {
+              "const": 403
+            },
+            "code": {
+              "const": "credential_account_mismatch"
+            },
+            "retryable": {
+              "const": false
+            }
+          }
+        },
         {
           "type": "object",
           "properties": {
@@ -4564,7 +4819,12 @@
             },
             "setup_modes": {
               "type": "array",
-              "const": ["whooshbang_hosted"]
+              "minItems": 1,
+              "maxItems": 2,
+              "uniqueItems": true,
+              "items": {
+                "enum": ["whooshbang_hosted", "customer_managed"]
+              }
             },
             "lifecycle_operations": {
               "type": "array",
@@ -4685,35 +4945,112 @@
         }
       ]
     },
-    "ProviderInstallationStatus": {
+    "CustomerOwnedSlackSetupStatus": {
       "type": "string",
       "enum": [
-        "pending",
-        "active",
-        "reauthorization_required",
-        "revoked",
-        "invalid"
+        "awaiting_app_creation",
+        "awaiting_authorities",
+        "awaiting_authorization",
+        "awaiting_ingress_proof",
+        "provisioning",
+        "failed",
+        "expired"
       ],
-      "description": "The safe customer-facing lifecycle of a provider installation. Credential and provider-native state stay private."
+      "description": "How far a customer-owned Slack setup has reached, which is the only thing a caller can act on while the connection is still `pending`. Each verification state names a different authority, because Slack hands the app's secrets over together but exercises them at different moments: `awaiting_authorization` has the three values and is waiting for the install, `awaiting_ingress_proof` has a bot grant Slack confirmed and is waiting for the first request Slack itself signs. Collapsing them would let a connection report a verified ingress it has never verified."
     },
-    "ProviderInstallationSummary": {
+    "CustomerOwnedSlackAppAuthority": {
+      "type": "string",
+      "enum": ["client_identity", "client_secret", "signing_secret"],
+      "description": "One app-specific authority the owner hands over. Product vocabulary for what each value is for, never the value: `client_identity` is safe metadata, and the other two are write-only."
+    },
+    "CustomerOwnedSlackConnectionSetup": {
       "type": "object",
-      "description": "A safe summary projected only through an exact authorized connection. Internal installation ids, provider-native workspace ids, scope arrays, grant metadata and credentials are absent.",
-      "required": ["display_name", "status", "health"],
+      "description": "The unfinished half of a customer-owned Slack connection: what the owner still has to do in Slack, and by when.\n\nIt is deliberately incapable of carrying a secret. The creation link contains configuration and nothing else, the two secrets the owner supplies are write-only and have no field here or on the connection, and the bot grant never travels through a browser at all — WhooshBang obtains it from Slack's own installation exchange. Everything here is therefore safe to poll, render, and hand to whoever is doing the setup.",
+      "required": [
+        "status",
+        "creation_url",
+        "expires_at",
+        "app_name",
+        "bot_display_name",
+        "outstanding_authorities"
+      ],
       "properties": {
-        "display_name": {
+        "status": { "$ref": "#/$defs/CustomerOwnedSlackSetupStatus" },
+        "creation_url": {
+          "type": "string",
+          "format": "uri",
+          "pattern": "^https://api\\.slack\\.com/apps\\?[^\\s]+$",
+          "maxLength": 8192,
+          "description": "Slack's own app-creation flow, opened with this app's manifest already filled in, so the owner reviews and presses Create rather than writing or pasting YAML. The URL carries configuration only: it names no account, project, or environment and contains no credential. The opaque handle it does carry selects candidate setup state and authorizes nothing."
+        },
+        "expires_at": {
+          "$ref": "#/$defs/Timestamp",
+          "description": "When an unfinished setup stops being usable. A setup that already produced a Slack app stays recoverable past this, because the app exists whether or not the browser came back."
+        },
+        "authorization_url": {
+          "type": "string",
+          "format": "uri",
+          "pattern": "^https://[^\\s]+$",
+          "maxLength": 2048,
+          "description": "The short-lived handoff that installs the owner's app into their workspace, present once the three authorities have arrived and an installation has been started. It carries opaque state, never a provider credential or a raw authorization code, and the bot grant it produces is returned to WhooshBang by Slack rather than to the browser."
+        },
+        "app_name": {
           "type": "string",
           "minLength": 1,
-          "maxLength": 100
+          "maxLength": 35,
+          "description": "The name the owner chose, echoed so a resumed session shows the same app it started with. Slack's own limit."
         },
-        "status": {
-          "$ref": "#/$defs/ProviderInstallationStatus"
+        "bot_display_name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 80,
+          "description": "The bot display name the owner chose, echoed for the same reason. Slack's own limit."
         },
-        "health": {
-          "$ref": "#/$defs/ProviderHealthState"
-        }
-      },
-      "additionalProperties": false
+        "outstanding_authorities": {
+          "type": "array",
+          "maxItems": 3,
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/CustomerOwnedSlackAppAuthority" },
+          "description": "Which of the three app-specific values this setup is still waiting for. Empty once they have all arrived; it never says what any of them are."
+        },
+        "failure_reason": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200,
+          "description": "Why this attempt ended, in terms the owner can act on. It never echoes a submitted secret, whole or in part, and never names another customer: a Slack app already connected elsewhere says only that."
+        }
+      },
+      "additionalProperties": false
+    },
+    "ProviderInstallationStatus": {
+      "type": "string",
+      "enum": [
+        "pending",
+        "active",
+        "reauthorization_required",
+        "revoked",
+        "invalid"
+      ],
+      "description": "The safe customer-facing lifecycle of a provider installation. Credential and provider-native state stay private."
+    },
+    "ProviderInstallationSummary": {
+      "type": "object",
+      "description": "A safe summary projected only through an exact authorized connection. Internal installation ids, provider-native workspace ids, scope arrays, grant metadata and credentials are absent.",
+      "required": ["display_name", "status", "health"],
+      "properties": {
+        "display_name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100
+        },
+        "status": {
+          "$ref": "#/$defs/ProviderInstallationStatus"
+        },
+        "health": {
+          "$ref": "#/$defs/ProviderHealthState"
+        }
+      },
+      "additionalProperties": false
     },
     "HostedConnectionCapability": {
       "type": "string",
@@ -4800,6 +5137,7 @@
         "identity": { "$ref": "#/$defs/TelegramConnectionIdentity" },
         "setup": { "$ref": "#/$defs/ChannelConnectionSetup" },
         "authorization_setup": false,
+        "app_setup": false,
         "installation": false,
         "row_version": {
           "type": "integer",
@@ -4862,6 +5200,7 @@
         },
         "identity": { "$ref": "#/$defs/SlackConnectionIdentity" },
         "setup": false,
+        "app_setup": false,
         "authorization_setup": {
           "$ref": "#/$defs/HostedChannelConnectionSetup",
           "description": "The additive hosted authorization state. Older tolerant readers discard this unknown field rather than interpreting it as Telegram setup."
@@ -4905,11 +5244,94 @@
       },
       "additionalProperties": false
     },
+    "CustomerOwnedSlackChannelConnection": {
+      "type": "object",
+      "description": "A Slack app the customer created and owns, referenced by one exact environment connection.\n\nIt differs from the hosted arm in who owns the app and its lifecycle, not in what a notification can do. WhooshBang custodies the three app-specific authorities Slack makes unavoidable and none of them appears here or in any other read: absence, not redaction, is the mechanism.",
+      "required": [
+        "id",
+        "project_id",
+        "environment_id",
+        "environment",
+        "provider",
+        "mode",
+        "display_name",
+        "status",
+        "health",
+        "capabilities",
+        "recovery_action",
+        "row_version",
+        "created_at",
+        "updated_at",
+        "diagnostic_id"
+      ],
+      "properties": {
+        "id": { "$ref": "#/$defs/OpaqueIdentifier" },
+        "project_id": { "$ref": "#/$defs/OpaqueIdentifier" },
+        "environment_id": { "$ref": "#/$defs/OpaqueIdentifier" },
+        "environment": { "$ref": "#/$defs/Environment" },
+        "provider": { "const": "slack" },
+        "mode": { "const": "customer_managed" },
+        "display_name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100
+        },
+        "status": { "$ref": "#/$defs/ChannelConnectionStatus" },
+        "health": { "$ref": "#/$defs/ProviderHealthState" },
+        "capabilities": {
+          "type": "array",
+          "maxItems": 1,
+          "uniqueItems": true,
+          "items": { "$ref": "#/$defs/HostedConnectionCapability" }
+        },
+        "identity": { "$ref": "#/$defs/SlackConnectionIdentity" },
+        "setup": false,
+        "authorization_setup": false,
+        "app_setup": {
+          "$ref": "#/$defs/CustomerOwnedSlackConnectionSetup",
+          "description": "The guided customer-owned setup state. A distinct field from Telegram's `setup` and the hosted arm's `authorization_setup` so a tolerant reader can never mistake one journey's progress for another's."
+        },
+        "installation": {
+          "$ref": "#/$defs/ProviderInstallationSummary",
+          "description": "The safe installation this exact connection owns. It exposes no provider-native identifier and no credential reference."
+        },
+        "management_url": {
+          "type": "string",
+          "format": "uri",
+          "pattern": "^slack://app\\?[^\\s]+$",
+          "maxLength": 2048,
+          "description": "A provider-owned App Home deep link for the customer's own workspace and their own app. It is not a caller-supplied return URL."
+        },
+        "recovery_action": {
+          "$ref": "#/$defs/HostedConnectionRecoveryAction"
+        },
+        "last_successful_verification_at": { "$ref": "#/$defs/Timestamp" },
+        "last_successful_delivery_at": { "$ref": "#/$defs/Timestamp" },
+        "row_version": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Send this back on an update. A stale value is refused rather than silently overwriting a change made in between."
+        },
+        "created_at": { "$ref": "#/$defs/Timestamp" },
+        "updated_at": { "$ref": "#/$defs/Timestamp" },
+        "archived_at": { "$ref": "#/$defs/Timestamp" },
+        "health_checked_at": { "$ref": "#/$defs/Timestamp" },
+        "last_transition_at": { "$ref": "#/$defs/Timestamp" },
+        "last_transition_reason": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200
+        },
+        "diagnostic_id": { "$ref": "#/$defs/DiagnosticId" }
+      },
+      "additionalProperties": false
+    },
     "ChannelConnection": {
       "description": "One environment's provider-discriminated connection. Credentials and provider-native authority identifiers are structurally absent.",
       "oneOf": [
         { "$ref": "#/$defs/TelegramChannelConnection" },
-        { "$ref": "#/$defs/HostedChannelConnection" }
+        { "$ref": "#/$defs/HostedChannelConnection" },
+        { "$ref": "#/$defs/CustomerOwnedSlackChannelConnection" }
       ]
     },
     "ChannelConnectionCollection": {
@@ -5036,6 +5458,53 @@
           },
           "additionalProperties": false
         },
+        {
+          "type": "object",
+          "description": "Starts a guided setup in which the customer creates and owns their own Slack app. The connection comes back `pending` with an `app_setup` carrying Slack's own creation link, already filled in with this app's manifest.\n\nThis arm carries no credential field, because at this point no credential exists: Slack issues the app's secrets when the owner presses Create. They arrive later through the write-only rotation boundary, and the bot grant never arrives from the caller at all — WhooshBang obtains it from Slack's installation exchange. The three names here are what the owner's whole workspace will see, which is why the caller chooses them rather than WhooshBang: a generated name would permanently brand a customer's own app with ours, and that is the one thing customer-owned modes exist to prevent.",
+          "required": [
+            "mode",
+            "provider",
+            "display_name",
+            "app_name",
+            "bot_display_name",
+            "app_description"
+          ],
+          "properties": {
+            "mode": {
+              "type": "string",
+              "const": "customer_managed"
+            },
+            "provider": {
+              "type": "string",
+              "const": "slack"
+            },
+            "display_name": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 100,
+              "description": "What this connection is called inside WhooshBang. Unrelated to what Slack shows the workspace."
+            },
+            "app_name": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 35,
+              "description": "The app name Slack's creation dialog is prefilled with, constrained to Slack's own 35-character limit. The owner can still change it in Slack; this is a suggestion, not a reservation."
+            },
+            "bot_display_name": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 80,
+              "description": "The bot display name in the same dialog — what a recipient reads at the top of the conversation. Slack's own 80-character limit."
+            },
+            "app_description": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 140,
+              "description": "The short description Slack shows beside the app, within Slack's own 140-character limit."
+            }
+          },
+          "additionalProperties": false
+        },
         {
           "type": "object",
           "description": "Starts the hosted authorization for a WhooshBang-owned distributed app installed independently at the provider authority Slack derives during OAuth. The caller supplies neither installation identity nor credential material.",
@@ -5060,8 +5529,46 @@
       ]
     },
     "RotateChannelConnectionCredentialRequest": {
-      "description": "Replaces the secret behind a connection, discriminated by where a replacement can come from at all. A customer-owned bot has one only its owner can produce and therefore sends it; a managed bot has one only Telegram can issue and therefore sends nothing. Either way the connection keeps its provider identity, so a subscriber stays bound to the identity it consented to and only the secret changes.",
+      "description": "Replaces the secret behind a connection, discriminated by where a replacement can come from at all. A customer-owned bot has one only its owner can produce and therefore sends it; a managed bot has one only Telegram can issue and therefore sends nothing. A customer-owned Slack app has three separate authorities and names which of them it is replacing. Either way the connection keeps its provider identity, so a subscriber stays bound to the identity it consented to and only the secret changes.\n\nThe first submission during setup uses this same boundary. Handing a secret over and replacing it are the same operation — a write that never reads the old value back — and giving initial setup its own endpoint would have meant two ways to do one thing, differing only in what the connection's status happened to be.",
       "oneOf": [
+        {
+          "type": "object",
+          "description": "Supplies or replaces the app-specific authorities of a Slack app the customer owns. All three are sent together, both for the first submission during setup and for every later replacement.\n\nSending only the one that changed would read as the kinder API, and it is the wrong shape: the three are sealed as one versioned set, so replacing one alone would mean decrypting the other two and writing them back — reading secrets at a boundary whose whole purpose is that nothing reads them. Slack shows all three on one screen, so re-entering them costs the owner a copy each and costs the system no read at all.\n\n`client_identity` is safe metadata and is echoed back; the other two are write-only and are never readable afterwards by any surface.\n\nThere is no bot-token field here, and the absence is the point: WhooshBang obtains the bot grant from Slack's installation exchange, so it never passes through a browser, a clipboard, this request, or any response.",
+          "required": [
+            "provider",
+            "client_identity",
+            "client_secret",
+            "signing_secret"
+          ],
+          "properties": {
+            "provider": {
+              "type": "string",
+              "const": "slack"
+            },
+            "client_identity": {
+              "type": "string",
+              "minLength": 7,
+              "maxLength": 66,
+              "pattern": "^[0-9]{3,32}\\.[0-9]{3,32}$",
+              "description": "The app's Client ID, in Slack's own `<digits>.<digits>` shape. Safe app metadata rather than an authority: it identifies the app in an OAuth redirect the workspace can already see, so unlike the other two it is echoed back."
+            },
+            "client_secret": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 512,
+              "writeOnly": true,
+              "description": "The app's Client Secret. Write-only: sealed on arrival, never echoed here or by any later read, and reachable only by the installation and identity exchanges — delivery cannot obtain it, and holding it sends no message."
+            },
+            "signing_secret": {
+              "type": "string",
+              "minLength": 1,
+              "maxLength": 512,
+              "writeOnly": true,
+              "description": "The app's Signing Secret, which verifies that an inbound request really came from Slack. Write-only on the same terms, and reachable only by ingress verification."
+            }
+          },
+          "additionalProperties": false
+        },
         {
           "type": "object",
           "description": "Replaces the customer-owned credential behind a connection. The connection keeps its provider identity, so a subscriber stays bound to the identity it consented to and only the secret changes; a credential for a different identity is refused.",
@@ -5113,6 +5620,287 @@
       },
       "additionalProperties": false
     },
+    "ConnectionTestKind": {
+      "type": "string",
+      "enum": ["outbound_notification", "signed_interaction"],
+      "description": "Which half of a connection a test exercises. `outbound_notification` proves this exact identity can put a message in front of the person who set it up. `signed_interaction` proves the opposite direction: that the provider can reach this deployment's interactivity URL and that the request it signs verifies against the secret we hold. The two fail for entirely different reasons, so they are never collapsed into one result.",
+      "$comment": "Provider-neutral vocabulary. Slack is the only provider that implements either today; a provider that cannot run one refuses it rather than reporting a pass it never proved."
+    },
+    "ConnectionTestStatus": {
+      "type": "string",
+      "enum": ["pending", "succeeded", "failed", "expired"],
+      "description": "`pending` means the test is placed and its answer has not arrived; a signed-interaction test stays there until somebody presses the button it sent. `expired` is the honest reading of a pending test whose window closed: nothing failed, nobody answered."
+    },
+    "ConnectionTestFailureCode": {
+      "type": "string",
+      "enum": [
+        "setup_incomplete",
+        "verification_target_unknown",
+        "credential_unavailable",
+        "provider_rejected",
+        "provider_unavailable",
+        "provider_rate_limited",
+        "unverified_request_received"
+      ],
+      "description": "Why a test did not pass, in a vocabulary the owner can act on rather than the provider's wire error.\n\n`verification_target_unknown` means nobody has installed the app from this deployment yet, so there is no owner to send a test to. `unverified_request_received` is a statement of fact and not a diagnosis: a request carrying this test's own challenge reached the interactivity URL and its signature did not verify against the secret this connection holds.\n\nA window that closed with nothing arriving is not in this list, because it is not a failure: it reads as `expired`, which says nobody answered rather than that anything broke."
+    },
+    "ConnectionTestRecoveryAction": {
+      "type": "string",
+      "enum": [
+        "none",
+        "complete_setup",
+        "replace_credentials",
+        "reinstall",
+        "retry_later",
+        "check_request_url",
+        "contact_support"
+      ],
+      "description": "The exact safe next action for one test result, in product vocabulary.\n\nIt is a different vocabulary from a connection's own recovery action because the actions genuinely differ: a test that nothing answered is fixed by checking the request URL the provider was given, and a request that arrived and did not verify is fixed by re-entering the app's secrets — neither of which is a lifecycle transition on the connection.\n\n`check_request_url` is also the honest answer when nobody simply pressed the button: the window closed with nothing arriving, and that has exactly two causes."
+    },
+    "ConnectionTestEvidence": {
+      "type": "object",
+      "description": "What a finished test actually observed. Every field is safe to render, log, and paste into an issue: no credential, no provider-native app, workspace, channel, or user identifier, and no message content.",
+      "properties": {
+        "identity_handle": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 128,
+          "description": "The visible handle the test went out as — the same identity a subscriber would see."
+        },
+        "workspace_display_name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 100,
+          "description": "The provider workspace the test ran in, as its own members see it named."
+        },
+        "accepted_at": {
+          "$ref": "#/$defs/Timestamp",
+          "description": "When the provider accepted the outbound message. Acceptance is the provider's own answer, not our belief."
+        },
+        "observed_at": {
+          "$ref": "#/$defs/Timestamp",
+          "description": "When the signed request the test was waiting for arrived and verified."
+        },
+        "round_trip_ms": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 86400000,
+          "description": "Milliseconds from placing the test to observing its answer."
+        },
+        "signature_verified": {
+          "type": "boolean",
+          "description": "Whether the provider's signature over the untouched request body verified against the secret this connection custodies. Present only once a request has arrived."
+        },
+        "ingress_host": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 253,
+          "description": "The public host the provider actually called, which is what a misconfigured or stale request URL gets wrong. It is this deployment's own hostname and names no tenant."
+        }
+      },
+      "additionalProperties": false
+    },
+    "ConnectionTest": {
+      "type": "object",
+      "description": "One owner-triggered proof that an exact connection still works, run on demand and answered with evidence rather than with a claim.\n\nIt is deliberately incapable of carrying a secret: nothing here is a credential, a provider-native identifier, or message content, and a test that failed says why in a closed vocabulary rather than by quoting a provider.",
+      "required": [
+        "id",
+        "connection_id",
+        "kind",
+        "status",
+        "requested_at",
+        "expires_at",
+        "recovery_action",
+        "diagnostic_id"
+      ],
+      "properties": {
+        "id": {
+          "$ref": "#/$defs/OpaqueIdentifier"
+        },
+        "connection_id": {
+          "$ref": "#/$defs/OpaqueIdentifier"
+        },
+        "kind": {
+          "$ref": "#/$defs/ConnectionTestKind"
+        },
+        "status": {
+          "$ref": "#/$defs/ConnectionTestStatus"
+        },
+        "requested_at": {
+          "$ref": "#/$defs/Timestamp"
+        },
+        "completed_at": {
+          "$ref": "#/$defs/Timestamp",
+          "description": "When the test settled. Absent while it is still pending."
+        },
+        "expires_at": {
+          "$ref": "#/$defs/Timestamp",
+          "description": "When a pending test stops waiting. A test that reaches this without an answer becomes `expired`, which is not a failure of the connection."
+        },
+        "evidence": {
+          "$ref": "#/$defs/ConnectionTestEvidence"
+        },
+        "failure_code": {
+          "$ref": "#/$defs/ConnectionTestFailureCode"
+        },
+        "recovery_action": {
+          "$ref": "#/$defs/ConnectionTestRecoveryAction",
+          "description": "The exact safe next action for this result. `none` on a pass."
+        },
+        "diagnostic_id": {
+          "$ref": "#/$defs/DiagnosticId"
+        }
+      },
+      "additionalProperties": false
+    },
+    "ConnectionTestCollection": {
+      "type": "object",
+      "description": "This connection's recent tests, newest first. It is the audit-safe failure history for a connection: what was tried, when, and what came back.",
+      "required": ["items"],
+      "properties": {
+        "items": {
+          "type": "array",
+          "maxItems": 100,
+          "items": {
+            "$ref": "#/$defs/ConnectionTest"
+          }
+        },
+        "next_cursor": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 256,
+          "pattern": "^[A-Za-z0-9_-]+$"
+        },
+        "page": {
+          "$ref": "#/$defs/ListPageNumber"
+        },
+        "page_size": {
+          "$ref": "#/$defs/ListPageSize"
+        },
+        "total": {
+          "$ref": "#/$defs/ListTotal"
+        }
+      },
+      "additionalProperties": false
+    },
+    "CreateConnectionTestRequest": {
+      "type": "object",
+      "description": "Places one test against an exact connection. It carries nothing but which test to run: a test needs no target, because the only person it may address is the one who installed the app.",
+      "required": ["kind"],
+      "properties": {
+        "kind": {
+          "$ref": "#/$defs/ConnectionTestKind"
+        }
+      },
+      "additionalProperties": false
+    },
+    "CustomerOwnedSlackAppManifest": {
+      "type": "object",
+      "description": "The exact configuration a customer-owned Slack app is created from, as data rather than as a URL-encoded blob.\n\nIt exists so the owner can read what they are about to approve, and so a reviewer can check it, without opening Slack. It carries configuration only: no account, project, or environment, no credential, and no provider-native identifier. The opaque handle inside the request URLs selects candidate setup state and authorizes nothing — a request still has to carry Slack's signature over the untouched body before anything inside it is believed.",
+      "required": [
+        "creation_url",
+        "app_name",
+        "bot_display_name",
+        "description",
+        "bot_scopes",
+        "user_scopes",
+        "request_urls",
+        "manifest",
+        "diagnostic_id"
+      ],
+      "properties": {
+        "creation_url": {
+          "type": "string",
+          "format": "uri",
+          "pattern": "^https://api\\.slack\\.com/apps\\?[^\\s]+$",
+          "maxLength": 8192,
+          "description": "The same prefilled creation link the setup carries, repeated here so one read answers both questions."
+        },
+        "app_name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 35
+        },
+        "bot_display_name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 80
+        },
+        "description": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 140
+        },
+        "bot_scopes": {
+          "type": "array",
+          "maxItems": 20,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 64
+          },
+          "description": "Every provider scope the bot will ask for, exactly as Slack will show them. Raw provider vocabulary on purpose: this is the screen the owner is about to approve, and translating it would make it unverifiable."
+        },
+        "user_scopes": {
+          "type": "array",
+          "maxItems": 20,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 64
+          },
+          "description": "Every provider scope a recipient will be asked for when they sign in. Separate from the bot scopes because they are approved by different people at different moments."
+        },
+        "request_urls": {
+          "type": "object",
+          "description": "Where this deployment answers the app. A stale or edited value here is the failure a signed-interaction test detects.",
+          "required": [
+            "events",
+            "interactions",
+            "installation_redirect",
+            "recipient_redirect"
+          ],
+          "properties": {
+            "events": {
+              "type": "string",
+              "format": "uri",
+              "pattern": "^https://[^\\s]+$",
+              "maxLength": 2048
+            },
+            "interactions": {
+              "type": "string",
+              "format": "uri",
+              "pattern": "^https://[^\\s]+$",
+              "maxLength": 2048
+            },
+            "installation_redirect": {
+              "type": "string",
+              "format": "uri",
+              "pattern": "^https://[^\\s]+$",
+              "maxLength": 2048
+            },
+            "recipient_redirect": {
+              "type": "string",
+              "format": "uri",
+              "pattern": "^https://[^\\s]+$",
+              "maxLength": 2048
+            }
+          },
+          "additionalProperties": false
+        },
+        "manifest": {
+          "type": "object",
+          "description": "The literal manifest document Slack is handed. Reproduced whole so what the owner reviews and what Slack receives cannot drift apart.",
+          "additionalProperties": true
+        },
+        "diagnostic_id": {
+          "$ref": "#/$defs/DiagnosticId"
+        }
+      },
+      "additionalProperties": false
+    },
     "NotifierConnectionRoute": {
       "type": "object",
       "description": "One notifier's use of one connection in the same environment. This is the record that decides which identity a send actually leaves through: a connection nothing routes to is configured and inert, and a subscriber cannot authorize against it either. Routing is deliberately separate from creating the connection so that adding a second identity never moves traffic on its own.",