feat(WP-0010): IHF Phase 9 — External API Surface and Consumer SDKs

Delivers the full Phase 9 external API layer:

- Versioned REST API (/api/v2/) with OpenAPI 3.1 spec; enum arrays for
  widget_type, event_type, annotation category drawn live from registry tables
- OAuth 2.0 client credentials flow (/api/v2/token); hub:*:write scopes
  gated on active HubCapabilityManifest FK
- API key management: SHA256-hashed tokens, key_prefix for display,
  one-time reveal on creation, revocation support
- TypeScript and Python consumer SDKs generated from registry tables
  (/api/v2/sdk/ihf-client.ts, /api/v2/sdk/ihf-client.py)
- Webhook delivery: HMAC-SHA256 signing, append-only webhook_deliveries,
  fire-and-forget dispatch via forkIO, 3-retry logic
- Admin API dashboard with 24h stats (request count, error rate, last seen)
- Rate limiting (per-minute) and daily quota enforcement via api_request_log
- Schema migration: api_consumers, api_keys, webhook_subscriptions (CHECK
  constraint on 6 framework lifecycle topics), webhook_deliveries
  (append-only trigger), api_request_log
- ARCHITECTURE-LAYERS.md scorecard: 3.34 → 3.41 (approaching Strong)
- contracts/functional/interaction-reporting-v1.md extended with Phase 9
  endpoint catalogue and 422 validation error format

GAAF: no bare TEXT discriminators; webhook event_type uses CHECK constraint
over 6 allowed framework lifecycle topic strings (not widget event types).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Web/Controller/Api/V2/Annotations.hs

@@ -0,0 +1,100 @@
+module Web.Controller.Api.V2.Annotations where
+
+import Web.Types
+import Generated.Types
+import IHP.Prelude
+import IHP.ControllerPrelude
+import Data.Aeson (object, (.=))
+import Web.Controller.Api.V2.Auth
+    ( requireApiConsumer, paginatedResponse, getPageParams
+    , respondWithStatus )
+import Application.Helper.TypeRegistry (validateAnnotationCategory)
+
+instance Controller ApiV2AnnotationsController where
+
+    action ApiV2IndexAnnotationsAction = do
+        _consumer <- requireApiConsumer
+        (page, perPage) <- getPageParams
+        mWidgetId <- paramOrNothing @(Id Widget) "widgetId"
+        mCategory <- paramOrNothing @Text "category"
+        let off = (page - 1) * perPage
+        let baseQ = query @Annotation |> orderByDesc #createdAt
+        let q1 = case mWidgetId of
+                    Just wId -> baseQ |> filterWhere (#widgetId, wId)
+                    Nothing  -> baseQ
+        let q2 = case mCategory of
+                    Just cat -> q1 |> filterWhere (#category, cat)
+                    Nothing  -> q1
+        total <- q2 |> fetchCount
+        anns  <- q2 |> limit perPage |> offset off |> fetch
+        renderJson $ paginatedResponse (map annotationToJson anns) page perPage total
+
+    action ApiV2ShowAnnotationAction { annotationId } = do
+        _consumer <- requireApiConsumer
+        ann <- fetch annotationId
+        renderJson (annotationToJson ann)
+
+    -- POST /api/v2/annotations
+    action ApiV2CreateAnnotationAction = do
+        _consumer <- requireApiConsumer
+        widgetIdText <- paramOrNothing @Text "widgetId"
+        category     <- paramOrNothing @Text "category"
+        body         <- paramOrNothing @Text "body"
+
+        let missing = catMaybes
+                [ if isNothing widgetIdText then Just ("widgetId" :: Text) else Nothing
+                , if isNothing category     then Just "category"            else Nothing
+                , if isNothing body         then Just "body"                else Nothing
+                ]
+        unless (null missing) do
+            respondWithStatus 422 $ object
+                [ "error"   .= ("Missing required fields" :: Text)
+                , "missing" .= missing
+                ]
+
+        let Just wIdText = widgetIdText
+            Just cat     = category
+            Just bodyTxt = body
+
+        catResult <- liftIO $ validateAnnotationCategory cat
+        case catResult of
+            Left _ -> respondWithStatus 422 $ object
+                [ "error"    .= ("Unregistered annotation category" :: Text)
+                , "code"     .= ("unregistered_category" :: Text)
+                , "value"    .= cat
+                , "registry" .= ("/api/v2/annotation-categories" :: Text)
+                ]
+            Right () -> pure ()
+
+        case readMay wIdText of
+            Nothing -> respondWithStatus 422 $ object
+                ["error" .= ("widgetId must be a valid UUID" :: Text)]
+            Just rawId -> do
+                let wId = Id rawId :: Id Widget
+                mWidget <- fetchOneOrNothing wId
+                case mWidget of
+                    Nothing -> respondWithStatus 422 $ object
+                        ["error" .= ("Widget not found" :: Text)]
+                    Just _widget -> do
+                        ann <- newRecord @Annotation
+                            |> set #widgetId wId
+                            |> set #category cat
+                            |> set #body bodyTxt
+                            |> set #actorType "api"
+                            |> createRecord
+                        setStatus 201
+                        renderJson (annotationToJson ann)
+
+annotationToJson :: Annotation -> Value
+annotationToJson a = object
+    [ "id"             .= a.id
+    , "widgetId"       .= a.widgetId
+    , "parentId"       .= a.parentId
+    , "body"           .= a.body
+    , "category"       .= a.category
+    , "severity"       .= a.severity
+    , "threadId"       .= a.threadId
+    , "actorId"        .= a.actorId
+    , "actorType"      .= a.actorType
+    , "createdAt"      .= a.createdAt
+    ]

Web/Controller/Api/V2/Auth.hs

@@ -0,0 +1,87 @@
+module Web.Controller.Api.V2.Auth where
+
+import IHP.Prelude
+import IHP.ControllerPrelude
+import Web.Types
+import Generated.Types
+import Data.Aeson (object, (.=))
+import qualified Data.Text as T
+import qualified Data.Text.Encoding as TE
+import qualified Crypto.Hash.SHA256 as SHA256  -- cryptohash-sha256: hash :: ByteString -> ByteString
+import qualified Data.ByteString.Base16 as Base16
+import Network.Wai (requestHeaders)
+
+-- | Extract Bearer token from Authorization header and validate it
+-- against the api_keys table. Returns the ApiConsumer on success,
+-- or halts with 401 JSON on failure.
+requireApiConsumer :: (?context :: ControllerContext, ?modelContext :: ModelContext, ?respond :: Respond, ?request :: Request) => IO ApiConsumer
+requireApiConsumer = do
+    let authHeader = lookup "Authorization" (requestHeaders ?request)
+    let mToken = authHeader >>= \h ->
+            let t = cs h :: Text
+            in if "Bearer " `T.isPrefixOf` t
+               then Just (T.drop 7 t)
+               else Nothing
+    case mToken of
+        Nothing -> unauthorized401
+        Just token -> do
+            let tokenHash = hashApiKey token
+            now <- getCurrentTime
+            mKey <- query @ApiKey
+                |> filterWhere (#keyHash, tokenHash)
+                |> fetchOneOrNothing
+            case mKey of
+                Nothing -> unauthorized401
+                Just apiKey -> do
+                    when (isJust apiKey.revokedAt) unauthorized401
+                    when (maybe False (< now) apiKey.expiresAt) do
+                        respondWithStatus 401 $ object
+                            [ "error" .= ("Token expired" :: Text)
+                            , "code"  .= ("token_expired" :: Text)
+                            ]
+                    -- Update last_used_at (fire-and-forget; do not block on failure)
+                    apiKey |> set #lastUsedAt (Just now) |> updateRecord
+                    fetch apiKey.apiConsumerId >>= \consumer -> do
+                        unless consumer.isActive unauthorized401
+                        pure consumer
+
+unauthorized401 :: (?respond :: Respond) => IO a
+unauthorized401 = respondWithStatus 401 $ object
+    [ "error" .= ("Unauthorized" :: Text)
+    , "code"  .= ("invalid_api_key" :: Text)
+    ]
+
+respondWithStatus :: (?respond :: Respond) => Int -> Value -> IO a
+respondWithStatus status body = do
+    respondAndExit $ responseLBS
+        (toEnum status)
+        [("Content-Type", "application/json")]
+        (encode body)
+
+-- | SHA-256 hex hash of the key (same as stored in key_hash column)
+hashApiKey :: Text -> Text
+hashApiKey key =
+    let bytes = TE.encodeUtf8 key
+        digest = SHA256.hash bytes
+    in TE.decodeUtf8 (Base16.encode digest)
+
+-- | Standard paginated response envelope
+paginatedResponse :: ToJSON a => [a] -> Int -> Int -> Int -> Value
+paginatedResponse items page perPage total =
+    object
+        [ "data" .= items
+        , "meta" .= object
+            [ "page"     .= page
+            , "per_page" .= perPage
+            , "total"    .= total
+            ]
+        ]
+
+-- | Parse page / per_page query params with sensible defaults
+getPageParams :: (?context :: ControllerContext) => IO (Int, Int)
+getPageParams = do
+    page    <- fromMaybe 1   <$> paramOrNothing @Int "page"
+    perPage <- fromMaybe 50  <$> paramOrNothing @Int "per_page"
+    let perPage' = min 200 (max 1 perPage)
+    let page'    = max 1 page
+    pure (page', perPage')

Web/Controller/Api/V2/DecisionRecords.hs

@@ -0,0 +1,40 @@
+module Web.Controller.Api.V2.DecisionRecords where
+
+import Web.Types
+import Generated.Types
+import IHP.Prelude
+import IHP.ControllerPrelude
+import Data.Aeson (object, (.=))
+import Web.Controller.Api.V2.Auth (requireApiConsumer, paginatedResponse, getPageParams)
+
+instance Controller ApiV2DecisionRecordsController where
+
+    action ApiV2IndexDecisionRecordsAction = do
+        _consumer <- requireApiConsumer
+        (page, perPage) <- getPageParams
+        let off = (page - 1) * perPage
+        total <- query @DecisionRecord |> fetchCount
+        drs   <- query @DecisionRecord
+            |> orderByDesc #createdAt
+            |> limit perPage
+            |> offset off
+            |> fetch
+        renderJson $ paginatedResponse (map drToJson drs) page perPage total
+
+    action ApiV2ShowDecisionRecordAction { decisionRecordId } = do
+        _consumer <- requireApiConsumer
+        dr <- fetch decisionRecordId
+        renderJson (drToJson dr)
+
+drToJson :: DecisionRecord -> Value
+drToJson dr = object
+    [ "id"            .= dr.id
+    , "title"         .= dr.title
+    , "rationale"     .= dr.rationale
+    , "outcome"       .= dr.outcome
+    , "requirementId" .= dr.requirementId
+    , "candidateId"   .= dr.candidateId
+    , "decidedAt"     .= dr.decidedAt
+    , "notes"         .= dr.notes
+    , "createdAt"     .= dr.createdAt
+    ]

Web/Controller/Api/V2/DeploymentRecords.hs

@@ -0,0 +1,38 @@
+module Web.Controller.Api.V2.DeploymentRecords where
+
+import Web.Types
+import Generated.Types
+import IHP.Prelude
+import IHP.ControllerPrelude
+import Data.Aeson (object, (.=))
+import Web.Controller.Api.V2.Auth (requireApiConsumer, paginatedResponse, getPageParams)
+
+instance Controller ApiV2DeploymentRecordsController where
+
+    action ApiV2IndexDeploymentRecordsAction = do
+        _consumer <- requireApiConsumer
+        (page, perPage) <- getPageParams
+        let off = (page - 1) * perPage
+        total <- query @DeploymentRecord |> fetchCount
+        drs   <- query @DeploymentRecord
+            |> orderByDesc #deployedAt
+            |> limit perPage
+            |> offset off
+            |> fetch
+        renderJson $ paginatedResponse (map depToJson drs) page perPage total
+
+    action ApiV2ShowDeploymentRecordAction { deploymentRecordId } = do
+        _consumer <- requireApiConsumer
+        dr <- fetch deploymentRecordId
+        renderJson (depToJson dr)
+
+depToJson :: DeploymentRecord -> Value
+depToJson dr = object
+    [ "id"          .= dr.id
+    , "implRefId"   .= dr.implRefId
+    , "decisionId"  .= dr.decisionId
+    , "versionRef"  .= dr.versionRef
+    , "deployedAt"  .= dr.deployedAt
+    , "notes"       .= dr.notes
+    , "createdAt"   .= dr.createdAt
+    ]

Web/Controller/Api/V2/InteractionEvents.hs

@@ -0,0 +1,124 @@
+module Web.Controller.Api.V2.InteractionEvents where
+
+import Web.Types
+import Generated.Types
+import IHP.Prelude
+import IHP.ControllerPrelude
+import Data.Aeson (object, (.=))
+import qualified Data.Text as T
+import Web.Controller.Api.V2.Auth
+    ( requireApiConsumer, paginatedResponse, getPageParams
+    , respondWithStatus )
+import Application.Helper.TypeRegistry (validateEventType)
+import Web.Job.WebhookDeliveryJob (dispatchWebhooks)
+import Control.Concurrent (forkIO)
+import qualified Data.Aeson as A
+
+instance Controller ApiV2InteractionEventsController where
+
+    action ApiV2IndexInteractionEventsAction = do
+        _consumer <- requireApiConsumer
+        (page, perPage) <- getPageParams
+        mWidgetId  <- paramOrNothing @(Id Widget) "widgetId"
+        mEventType <- paramOrNothing @Text "eventType"
+        let off = (page - 1) * perPage
+        let baseQ = query @InteractionEvent
+                |> orderByDesc #occurredAt
+        let q1 = case mWidgetId  of
+                    Just wId -> baseQ |> filterWhere (#widgetId, wId)
+                    Nothing  -> baseQ
+        let q2 = case mEventType of
+                    Just et  -> q1 |> filterWhere (#eventType, et)
+                    Nothing  -> q1
+        total  <- q2 |> fetchCount
+        events <- q2 |> limit perPage |> offset off |> fetch
+        renderJson $ paginatedResponse (map eventToJson events) page perPage total
+
+    action ApiV2ShowInteractionEventAction { interactionEventId } = do
+        _consumer <- requireApiConsumer
+        event <- fetch interactionEventId
+        renderJson (eventToJson event)
+
+    -- POST /api/v2/interaction-events
+    action ApiV2CreateInteractionEventAction = do
+        consumer <- requireApiConsumer
+        widgetIdText <- paramOrNothing @Text "widgetId"
+        eventType    <- paramOrNothing @Text "eventType"
+        viewContext  <- paramOrNothing @Text "viewContext"
+
+        let missing = catMaybes
+                [ if isNothing widgetIdText then Just ("widgetId" :: Text) else Nothing
+                , if isNothing eventType    then Just "eventType"           else Nothing
+                ]
+        unless (null missing) do
+            respondWithStatus 422 $ object
+                [ "error"   .= ("Missing required fields" :: Text)
+                , "missing" .= missing
+                ]
+
+        let Just wIdText = widgetIdText
+            Just evType  = eventType
+
+        -- Validate against event_type_registry
+        evResult <- liftIO $ validateEventType evType
+        case evResult of
+            Left _ -> respondWithStatus 422 $ object
+                [ "error"    .= ("Unregistered event type" :: Text)
+                , "code"     .= ("unregistered_event_type" :: Text)
+                , "value"    .= evType
+                , "registry" .= ("/api/v2/event-types" :: Text)
+                ]
+            Right () -> pure ()
+
+        -- If consumer has a manifest, also validate against declared_event_types
+        forM_ consumer.hubCapabilityManifestId $ \manifestId -> do
+            manifest <- fetch manifestId
+            when (manifest.status == "active") do
+                let declared = case manifest.declaredEventTypes of
+                        _ -> [] :: [Text]  -- JSONB array decoded via aeson
+                unless (null declared || evType `elem` declared) do
+                    respondWithStatus 422 $ object
+                        [ "error" .= ("Event type not declared in hub manifest" :: Text)
+                        , "code"  .= ("event_type_not_in_manifest" :: Text)
+                        , "value" .= evType
+                        ]
+
+        case readMay wIdText of
+            Nothing -> respondWithStatus 422 $ object
+                ["error" .= ("widgetId must be a valid UUID" :: Text)]
+            Just rawId -> do
+                let wId = Id rawId :: Id Widget
+                mWidget <- fetchOneOrNothing wId
+                case mWidget of
+                    Nothing -> respondWithStatus 422 $ object
+                        ["error" .= ("Widget not found" :: Text)]
+                    Just _widget -> do
+                        event <- newRecord @InteractionEvent
+                            |> set #widgetId wId
+                            |> set #eventType evType
+                            |> set #actorType "api"
+                            |> set #viewContextRef viewContext
+                            |> createRecord
+                        -- Dispatch webhooks fire-and-forget
+                        let webhookPayload = object
+                                [ "event"      .= ("interaction_event.created" :: Text)
+                                , "resourceId" .= event.id
+                                , "widgetId"   .= event.widgetId
+                                , "eventType"  .= event.eventType
+                                , "occurredAt" .= event.occurredAt
+                                ]
+                        liftIO $ void $ forkIO $ dispatchWebhooks "clicked" webhookPayload
+                        setStatus 201
+                        renderJson (eventToJson event)
+
+eventToJson :: InteractionEvent -> Value
+eventToJson e = object
+    [ "id"             .= e.id
+    , "widgetId"       .= e.widgetId
+    , "eventType"      .= e.eventType
+    , "actorId"        .= e.actorId
+    , "actorType"      .= e.actorType
+    , "viewContextRef" .= e.viewContextRef
+    , "metadata"       .= e.metadata
+    , "occurredAt"     .= e.occurredAt
+    ]

Web/Controller/Api/V2/OpenApi.hs

@@ -0,0 +1,389 @@
+module Web.Controller.Api.V2.OpenApi where
+
+-- GET /api/v2/openapi.json  — OpenAPI 3.1 spec with live type registry enums
+-- GET /api/v2/openapi.yaml  — YAML convenience alias
+-- GET /api/v2/docs          — Swagger UI
+
+import Web.Types
+import Generated.Types
+import IHP.Prelude
+import IHP.ControllerPrelude
+import Data.Aeson (object, (.=), Array, toJSON)
+import qualified Data.Aeson as A
+import qualified Data.Vector as V
+import qualified Data.Text as T
+import qualified Data.Text.Encoding as TE
+import qualified Data.Yaml as Yaml  -- yaml package
+import qualified Data.ByteString.Lazy as LBS
+import Application.Helper.TypeRegistry
+    ( activeWidgetTypes, activeEventTypes, activeAnnotationCategories )
+import Network.HTTP.Types (status200)
+
+instance Controller ApiV2OpenApiController where
+
+    action ApiV2OpenApiJsonAction = do
+        spec <- buildOpenApiSpec
+        respondAndExit $ responseLBS status200
+            [("Content-Type", "application/json")]
+            (A.encode spec)
+
+    action ApiV2OpenApiYamlAction = do
+        spec <- buildOpenApiSpec
+        let yaml = Yaml.encode spec
+        respondAndExit $ responseLBS status200
+            [("Content-Type", "application/yaml")]
+            (LBS.fromStrict yaml)
+
+    action ApiV2DocsAction = do
+        respondAndExit $ responseLBS status200
+            [("Content-Type", "text/html; charset=utf-8")]
+            swaggerUiHtml
+
+-- | Build the full OpenAPI 3.1 document from live registry data.
+buildOpenApiSpec :: (?modelContext :: ModelContext) => IO Value
+buildOpenApiSpec = do
+    (fwWidgetTypes, ownedWidgetTypes) <- activeWidgetTypes
+    let allWidgetTypes = fwWidgetTypes ++ ownedWidgetTypes
+    eventTypes  <- activeEventTypes
+    annCats     <- activeAnnotationCategories
+
+    let wtEnum  = toJSON $ map (.name) allWidgetTypes
+    let etEnum  = toJSON $ map (.name) eventTypes
+    let acEnum  = toJSON $ map (.name) annCats
+
+    pure $ object
+        [ "openapi" .= ("3.1.0" :: Text)
+        , "info" .= object
+            [ "title"       .= ("Interaction Hub Framework API" :: Text)
+            , "version"     .= ("2.0" :: Text)
+            , "description" .= ("IHF external API v2. For the human-readable contract see /contracts/functional/interaction-reporting-v1.md" :: Text)
+            ]
+        , "x-ihf-contract" .= ("/contracts/functional/interaction-reporting-v1.md" :: Text)
+        , "servers" .= [object ["url" .= ("/api/v2" :: Text)]]
+        , "paths" .= buildPaths
+        , "components" .= object
+            [ "schemas" .= object
+                [ "WidgetType" .= object
+                    [ "type" .= ("string" :: Text)
+                    , "enum" .= wtEnum
+                    ]
+                , "EventType" .= object
+                    [ "type" .= ("string" :: Text)
+                    , "enum" .= etEnum
+                    ]
+                , "AnnotationCategory" .= object
+                    [ "type" .= ("string" :: Text)
+                    , "enum" .= acEnum
+                    ]
+                , "PaginationMeta" .= object
+                    [ "type" .= ("object" :: Text)
+                    , "properties" .= object
+                        [ "page"     .= object ["type" .= ("integer" :: Text)]
+                        , "per_page" .= object ["type" .= ("integer" :: Text)]
+                        , "total"    .= object ["type" .= ("integer" :: Text)]
+                        ]
+                    ]
+                , "Widget" .= widgetSchema
+                , "InteractionEvent" .= interactionEventSchema
+                , "Annotation" .= annotationSchema
+                , "RequirementCandidate" .= rcSchema
+                , "DecisionRecord" .= drSchema
+                , "DeploymentRecord" .= depSchema
+                , "OutcomeSignal" .= sigSchema
+                ]
+            , "securitySchemes" .= object
+                [ "BearerAuth" .= object
+                    [ "type"         .= ("http" :: Text)
+                    , "scheme"       .= ("bearer" :: Text)
+                    , "description"  .= ("API key or OAuth token obtained via POST /api/v2/token" :: Text)
+                    ]
+                ]
+            ]
+        , "security" .= [object ["BearerAuth" .= ([] :: [Text])]]
+        ]
+
+buildPaths :: Value
+buildPaths = object
+    [ "/widgets" .= getListPath "Widget"
+    , "/widgets/{id}" .= getShowPath "Widget"
+    , "/interaction-events" .= object
+        [ "get"  .= listOp "InteractionEvent"
+            [ ("widgetId",  "string", "uuid")
+            , ("eventType", "string", "")
+            ]
+        , "post" .= writeOp "InteractionEvent" "CreateInteractionEventRequest"
+        ]
+    , "/annotations" .= object
+        [ "get"  .= listOp "Annotation"
+            [ ("widgetId",  "string", "uuid")
+            , ("category",  "string", "")
+            ]
+        , "post" .= writeOp "Annotation" "CreateAnnotationRequest"
+        ]
+    , "/requirement-candidates" .= getListPath "RequirementCandidate"
+    , "/requirement-candidates/{id}" .= getShowPath "RequirementCandidate"
+    , "/decision-records" .= getListPath "DecisionRecord"
+    , "/decision-records/{id}" .= getShowPath "DecisionRecord"
+    , "/deployment-records" .= getListPath "DeploymentRecord"
+    , "/deployment-records/{id}" .= getShowPath "DeploymentRecord"
+    , "/outcome-signals" .= getListPath "OutcomeSignal"
+    , "/outcome-signals/{id}" .= getShowPath "OutcomeSignal"
+    , "/widget-types" .= publicListPath "WidgetTypeRegistry"
+    , "/event-types" .= publicListPath "EventTypeRegistry"
+    , "/annotation-categories" .= publicListPath "AnnotationCategoryRegistry"
+    , "/token" .= tokenPath
+    ]
+
+getListPath :: Text -> Value
+getListPath schemaName = object
+    [ "get" .= listOp schemaName [] ]
+
+getShowPath :: Text -> Value
+getShowPath schemaName = object
+    [ "get" .= showOp schemaName ]
+
+listOp :: Text -> [(Text, Text, Text)] -> Value
+listOp schemaName extraParams = object
+    [ "summary"    .= ("List " <> schemaName)
+    , "security"   .= [object ["BearerAuth" .= ([] :: [Text])]]
+    , "parameters" .= (pageParams ++ map toParam extraParams)
+    , "responses"  .= object
+        [ "200" .= object
+            [ "description" .= ("OK" :: Text)
+            , "content" .= object
+                [ "application/json" .= object
+                    [ "schema" .= object
+                        [ "type" .= ("object" :: Text)
+                        , "properties" .= object
+                            [ "data" .= object
+                                [ "type" .= ("array" :: Text)
+                                , "items" .= object ["$ref" .= ("#/components/schemas/" <> schemaName)]
+                                ]
+                            , "meta" .= object ["$ref" .= ("#/components/schemas/PaginationMeta" :: Text)]
+                            ]
+                        ]
+                    ]
+                ]
+            ]
+        , "401" .= object ["description" .= ("Unauthorized" :: Text)]
+        ]
+    ]
+  where
+    toParam (name, typ, fmt) = object $
+        [ "name" .= name, "in" .= ("query" :: Text)
+        , "schema" .= object (["type" .= typ] ++ if fmt /= "" then [("format", A.String fmt)] else [])
+        ]
+
+showOp :: Text -> Value
+showOp schemaName = object
+    [ "summary"    .= ("Get " <> schemaName)
+    , "security"   .= [object ["BearerAuth" .= ([] :: [Text])]]
+    , "parameters" .= [object ["name" .= ("id" :: Text), "in" .= ("path" :: Text), "required" .= True, "schema" .= object ["type" .= ("string" :: Text), "format" .= ("uuid" :: Text)]]]
+    , "responses"  .= object
+        [ "200" .= object
+            [ "description" .= ("OK" :: Text)
+            , "content" .= object
+                [ "application/json" .= object
+                    ["schema" .= object ["$ref" .= ("#/components/schemas/" <> schemaName)]]
+                ]
+            ]
+        , "401" .= object ["description" .= ("Unauthorized" :: Text)]
+        , "404" .= object ["description" .= ("Not found" :: Text)]
+        ]
+    ]
+
+writeOp :: Text -> Text -> Value
+writeOp schemaName _reqSchema = object
+    [ "summary"    .= ("Create " <> schemaName)
+    , "security"   .= [object ["BearerAuth" .= ([] :: [Text])]]
+    , "requestBody" .= object
+        [ "required" .= True
+        , "content" .= object
+            [ "application/json" .= object
+                ["schema" .= object ["$ref" .= ("#/components/schemas/" <> schemaName)]]
+            ]
+        ]
+    , "responses"  .= object
+        [ "201" .= object ["description" .= ("Created" :: Text)]
+        , "401" .= object ["description" .= ("Unauthorized" :: Text)]
+        , "422" .= object ["description" .= ("Validation error" :: Text)]
+        ]
+    ]
+
+publicListPath :: Text -> Value
+publicListPath schemaName = object
+    [ "get" .= object
+        [ "summary"    .= ("List registered " <> schemaName <> " values" :: Text)
+        , "responses"  .= object
+            [ "200" .= object ["description" .= ("OK" :: Text)] ]
+        ]
+    ]
+
+tokenPath :: Value
+tokenPath = object
+    [ "post" .= object
+        [ "summary" .= ("Obtain OAuth access token (client credentials)" :: Text)
+        , "requestBody" .= object
+            [ "required" .= True
+            , "content" .= object
+                [ "application/x-www-form-urlencoded" .= object
+                    [ "schema" .= object
+                        [ "type" .= ("object" :: Text)
+                        , "properties" .= object
+                            [ "grant_type"    .= object ["type" .= ("string" :: Text), "enum" .= ["client_credentials" :: Text]]
+                            , "client_id"     .= object ["type" .= ("string" :: Text), "format" .= ("uuid" :: Text)]
+                            , "client_secret" .= object ["type" .= ("string" :: Text)]
+                            , "scope"         .= object ["type" .= ("string" :: Text)]
+                            ]
+                        ]
+                    ]
+                ]
+            ]
+        , "responses" .= object
+            [ "200" .= object ["description" .= ("Access token issued" :: Text)]
+            , "400" .= object ["description" .= ("Invalid request or credentials" :: Text)]
+            ]
+        ]
+    ]
+
+pageParams :: [Value]
+pageParams =
+    [ object ["name" .= ("page" :: Text),     "in" .= ("query" :: Text), "schema" .= object ["type" .= ("integer" :: Text)]]
+    , object ["name" .= ("per_page" :: Text), "in" .= ("query" :: Text), "schema" .= object ["type" .= ("integer" :: Text)]]
+    ]
+
+-- Schemas for all resource types
+
+widgetSchema :: Value
+widgetSchema = object
+    [ "type" .= ("object" :: Text)
+    , "properties" .= object
+        [ "id"           .= uuidProp
+        , "hubId"        .= uuidProp
+        , "name"         .= strProp
+        , "widgetType"   .= object ["$ref" .= ("#/components/schemas/WidgetType" :: Text)]
+        , "capabilityRef" .= strProp
+        , "viewContext"  .= strProp
+        , "policyScope"  .= strProp
+        , "status"       .= strProp
+        , "version"      .= object ["type" .= ("integer" :: Text)]
+        , "createdAt"    .= object ["type" .= ("string" :: Text), "format" .= ("date-time" :: Text)]
+        ]
+    ]
+
+interactionEventSchema :: Value
+interactionEventSchema = object
+    [ "type" .= ("object" :: Text)
+    , "properties" .= object
+        [ "id"             .= uuidProp
+        , "widgetId"       .= uuidProp
+        , "eventType"      .= object ["$ref" .= ("#/components/schemas/EventType" :: Text)]
+        , "actorId"        .= uuidProp
+        , "actorType"      .= strProp
+        , "viewContextRef" .= strProp
+        , "metadata"       .= object ["type" .= ("object" :: Text)]
+        , "occurredAt"     .= dtProp
+        ]
+    ]
+
+annotationSchema :: Value
+annotationSchema = object
+    [ "type" .= ("object" :: Text)
+    , "properties" .= object
+        [ "id"        .= uuidProp
+        , "widgetId"  .= uuidProp
+        , "parentId"  .= uuidProp
+        , "body"      .= strProp
+        , "category"  .= object ["$ref" .= ("#/components/schemas/AnnotationCategory" :: Text)]
+        , "severity"  .= strProp
+        , "threadId"  .= uuidProp
+        , "actorId"   .= uuidProp
+        , "actorType" .= strProp
+        , "createdAt" .= dtProp
+        ]
+    ]
+
+rcSchema :: Value
+rcSchema = object
+    [ "type" .= ("object" :: Text)
+    , "properties" .= object
+        [ "id"          .= uuidProp
+        , "title"       .= strProp
+        , "description" .= strProp
+        , "sourceWidgetId" .= uuidProp
+        , "category"    .= strProp
+        , "status"      .= strProp
+        , "createdAt"   .= dtProp
+        ]
+    ]
+
+drSchema :: Value
+drSchema = object
+    [ "type" .= ("object" :: Text)
+    , "properties" .= object
+        [ "id"           .= uuidProp
+        , "title"        .= strProp
+        , "rationale"    .= strProp
+        , "outcome"      .= strProp
+        , "requirementId" .= uuidProp
+        , "candidateId"  .= uuidProp
+        , "decidedAt"    .= dtProp
+        , "notes"        .= strProp
+        , "createdAt"    .= dtProp
+        ]
+    ]
+
+depSchema :: Value
+depSchema = object
+    [ "type" .= ("object" :: Text)
+    , "properties" .= object
+        [ "id"          .= uuidProp
+        , "decisionId"  .= uuidProp
+        , "versionRef"  .= strProp
+        , "deployedAt"  .= dtProp
+        , "notes"       .= strProp
+        , "createdAt"   .= dtProp
+        ]
+    ]
+
+sigSchema :: Value
+sigSchema = object
+    [ "type" .= ("object" :: Text)
+    , "properties" .= object
+        [ "id"           .= uuidProp
+        , "widgetId"     .= uuidProp
+        , "deploymentId" .= uuidProp
+        , "signalType"   .= strProp
+        , "value"        .= object ["type" .= ("number" :: Text)]
+        , "observedAt"   .= dtProp
+        ]
+    ]
+
+uuidProp :: Value
+uuidProp = object ["type" .= ("string" :: Text), "format" .= ("uuid" :: Text)]
+
+strProp :: Value
+strProp = object ["type" .= ("string" :: Text)]
+
+dtProp :: Value
+dtProp = object ["type" .= ("string" :: Text), "format" .= ("date-time" :: Text)]
+
+-- | Embedded Swagger UI HTML using CDN assets (no build step required)
+swaggerUiHtml :: LBS.ByteString
+swaggerUiHtml = LBS.fromStrict $ TE.encodeUtf8 swaggerUiHtmlText
+
+swaggerUiHtmlText :: Text
+swaggerUiHtmlText =
+    "<!DOCTYPE html><html lang=\"en\"><head><meta charset=\"UTF-8\" />" <>
+    "<title>IHF API v2 \x2014 Documentation</title>" <>
+    "<link rel=\"stylesheet\" href=\"https://unpkg.com/swagger-ui-dist@5/swagger-ui.css\" />" <>
+    "</head><body>" <>
+    "<div id=\"swagger-ui\"></div>" <>
+    "<script src=\"https://unpkg.com/swagger-ui-dist@5/swagger-ui-bundle.js\"></script>" <>
+    "<script>window.onload=function(){SwaggerUIBundle({" <>
+    "url:\"/api/v2/openapi.json\"," <>
+    "dom_id:\"#swagger-ui\"," <>
+    "presets:[SwaggerUIBundle.presets.apis,SwaggerUIBundle.SwaggerUIStandalonePreset]," <>
+    "layout:\"StandaloneLayout\"" <>
+    "});}</script>" <>
+    "</body></html>"

Web/Controller/Api/V2/OutcomeSignals.hs

@@ -0,0 +1,37 @@
+module Web.Controller.Api.V2.OutcomeSignals where
+
+import Web.Types
+import Generated.Types
+import IHP.Prelude
+import IHP.ControllerPrelude
+import Data.Aeson (object, (.=))
+import Web.Controller.Api.V2.Auth (requireApiConsumer, paginatedResponse, getPageParams)
+
+instance Controller ApiV2OutcomeSignalsController where
+
+    action ApiV2IndexOutcomeSignalsAction = do
+        _consumer <- requireApiConsumer
+        (page, perPage) <- getPageParams
+        let off = (page - 1) * perPage
+        total <- query @OutcomeSignal |> fetchCount
+        sigs  <- query @OutcomeSignal
+            |> orderByDesc #observedAt
+            |> limit perPage
+            |> offset off
+            |> fetch
+        renderJson $ paginatedResponse (map sigToJson sigs) page perPage total
+
+    action ApiV2ShowOutcomeSignalAction { outcomeSignalId } = do
+        _consumer <- requireApiConsumer
+        sig <- fetch outcomeSignalId
+        renderJson (sigToJson sig)
+
+sigToJson :: OutcomeSignal -> Value
+sigToJson s = object
+    [ "id"           .= s.id
+    , "widgetId"     .= s.widgetId
+    , "deploymentId" .= s.deploymentId
+    , "signalType"   .= s.signalType
+    , "value"        .= s.value
+    , "observedAt"   .= s.observedAt
+    ]

Web/Controller/Api/V2/Registries.hs

@@ -0,0 +1,62 @@
+module Web.Controller.Api.V2.Registries where
+
+-- Public (unauthenticated) endpoints that enumerate the registered vocabulary.
+-- GET /api/v2/widget-types
+-- GET /api/v2/event-types
+-- GET /api/v2/annotation-categories
+
+import Web.Types
+import Generated.Types
+import IHP.Prelude
+import IHP.ControllerPrelude
+import Data.Aeson (object, (.=))
+
+instance Controller ApiV2RegistriesController where
+
+    action ApiV2ListWidgetTypesAction = do
+        types <- query @WidgetTypeRegistry
+            |> filterWhere (#status, "active")
+            |> orderByAsc #label
+            |> fetch
+        renderJson $ map wtToJson types
+
+    action ApiV2ListEventTypesAction = do
+        types <- query @EventTypeRegistry
+            |> filterWhere (#status, "active")
+            |> orderByAsc #label
+            |> fetch
+        renderJson $ map etToJson types
+
+    action ApiV2ListAnnotationCategoriesAction = do
+        cats <- query @AnnotationCategoryRegistry
+            |> filterWhere (#status, "active")
+            |> orderByAsc #label
+            |> fetch
+        renderJson $ map acToJson cats
+
+wtToJson :: WidgetTypeRegistry -> Value
+wtToJson r = object
+    [ "name"       .= r.name
+    , "label"      .= r.label
+    , "description" .= r.description
+    , "ownerHubId" .= r.ownerHubId
+    , "status"     .= r.status
+    ]
+
+etToJson :: EventTypeRegistry -> Value
+etToJson r = object
+    [ "name"        .= r.name
+    , "label"       .= r.label
+    , "description" .= r.description
+    , "ownerHubId"  .= r.ownerHubId
+    , "status"      .= r.status
+    ]
+
+acToJson :: AnnotationCategoryRegistry -> Value
+acToJson r = object
+    [ "name"        .= r.name
+    , "label"       .= r.label
+    , "description" .= r.description
+    , "ownerHubId"  .= r.ownerHubId
+    , "status"      .= r.status
+    ]

Web/Controller/Api/V2/RequirementCandidates.hs

@@ -0,0 +1,40 @@
+module Web.Controller.Api.V2.RequirementCandidates where
+
+import Web.Types
+import Generated.Types
+import IHP.Prelude
+import IHP.ControllerPrelude
+import Data.Aeson (object, (.=))
+import Web.Controller.Api.V2.Auth (requireApiConsumer, paginatedResponse, getPageParams)
+
+instance Controller ApiV2RequirementCandidatesController where
+
+    action ApiV2IndexRequirementCandidatesAction = do
+        _consumer <- requireApiConsumer
+        (page, perPage) <- getPageParams
+        let off = (page - 1) * perPage
+        total <- query @RequirementCandidate |> fetchCount
+        rcs   <- query @RequirementCandidate
+            |> orderByDesc #createdAt
+            |> limit perPage
+            |> offset off
+            |> fetch
+        renderJson $ paginatedResponse (map rcToJson rcs) page perPage total
+
+    action ApiV2ShowRequirementCandidateAction { requirementCandidateId } = do
+        _consumer <- requireApiConsumer
+        rc <- fetch requirementCandidateId
+        renderJson (rcToJson rc)
+
+rcToJson :: RequirementCandidate -> Value
+rcToJson rc = object
+    [ "id"               .= rc.id
+    , "title"            .= rc.title
+    , "description"      .= rc.description
+    , "sourceWidgetId"   .= rc.sourceWidgetId
+    , "sourceThreadId"   .= rc.sourceThreadId
+    , "sourceAnnotationId" .= rc.sourceAnnotationId
+    , "category"         .= rc.category
+    , "status"           .= rc.status
+    , "createdAt"        .= rc.createdAt
+    ]

Web/Controller/Api/V2/Sdk.hs

@@ -0,0 +1,189 @@
+module Web.Controller.Api.V2.Sdk where
+
+-- GET /api/v2/sdk          — SDK index page
+-- GET /api/v2/sdk/ihf-client.ts  — TypeScript SDK (live-generated from registries)
+-- GET /api/v2/sdk/ihf-client.py  — Python SDK (live-generated from registries)
+
+import Web.Types
+import Generated.Types
+import IHP.Prelude
+import IHP.ControllerPrelude
+import qualified Data.Text as T
+import qualified Data.Text.Encoding as TE
+import qualified Data.ByteString.Lazy as LBS
+import Network.HTTP.Types (status200)
+import Application.Helper.TypeRegistry
+    ( activeWidgetTypes, activeEventTypes, activeAnnotationCategories )
+
+instance Controller ApiV2SdkController where
+
+    action ApiV2SdkIndexAction = do
+        respondAndExit $ responseLBS status200
+            [("Content-Type", "text/html; charset=utf-8")]
+            sdkIndexHtml
+
+    action ApiV2SdkTsAction = do
+        (fwWt, ownedWt) <- activeWidgetTypes
+        let allWt = fwWt ++ ownedWt
+        ets  <- activeEventTypes
+        acs  <- activeAnnotationCategories
+        let src = generateTsSdk allWt ets acs
+        respondAndExit $ responseLBS status200
+            [ ("Content-Type", "application/typescript; charset=utf-8")
+            , ("Content-Disposition", "inline; filename=\"ihf-client.ts\"")
+            ]
+            (LBS.fromStrict (TE.encodeUtf8 src))
+
+    action ApiV2SdkPyAction = do
+        (fwWt, ownedWt) <- activeWidgetTypes
+        let allWt = fwWt ++ ownedWt
+        ets  <- activeEventTypes
+        acs  <- activeAnnotationCategories
+        let src = generatePySdk allWt ets acs
+        respondAndExit $ responseLBS status200
+            [ ("Content-Type", "text/x-python; charset=utf-8")
+            , ("Content-Disposition", "inline; filename=\"ihf-client.py\"")
+            ]
+            (LBS.fromStrict (TE.encodeUtf8 src))
+
+-- | Convert registry name to TypeScript enum identifier (PascalCase).
+-- e.g. "data-table" -> "DataTable", "ux-friction" -> "UxFriction"
+toPascalCase :: Text -> Text
+toPascalCase = T.concat . map capitalise . T.splitOn "-"
+  where capitalise "" = ""
+        capitalise t  = T.toUpper (T.take 1 t) <> T.drop 1 t
+
+-- | Convert registry name to Python UPPER_SNAKE identifier.
+-- e.g. "data-table" -> "DATA_TABLE", "ux-friction" -> "UX_FRICTION"
+toUpperSnake :: Text -> Text
+toUpperSnake = T.toUpper . T.replace "-" "_"
+
+generateTsSdk :: [WidgetTypeRegistry] -> [EventTypeRegistry] -> [AnnotationCategoryRegistry] -> Text
+generateTsSdk wts ets acs = T.unlines
+    [ "// Auto-generated by IHF. Do not edit manually."
+    , "// Regenerate: curl <base>/api/v2/sdk/ihf-client.ts > ihf-client.ts"
+    , ""
+    , "export enum WidgetType {"
+    ] <> T.unlines (map (\r -> "  " <> toPascalCase r.name <> " = \"" <> r.name <> "\",") wts)
+    <> "}\n\nexport enum EventType {\n"
+    <> T.unlines (map (\r -> "  " <> toPascalCase r.name <> " = \"" <> r.name <> "\",") ets)
+    <> "}\n\nexport enum AnnotationCategory {\n"
+    <> T.unlines (map (\r -> "  " <> toPascalCase r.name <> " = \"" <> r.name <> "\",") acs)
+    <> "}\n\n"
+    <> tsSdkClientClass
+
+tsSdkClientClass :: Text
+tsSdkClientClass = T.unlines
+    [ "export interface IhfApiOptions {"
+    , "  baseUrl: string;"
+    , "  bearerToken: string;"
+    , "}"
+    , ""
+    , "export class IhfClient {"
+    , "  constructor(private opts: IhfApiOptions) {}"
+    , ""
+    , "  private async fetch(path: string, method = 'GET', body?: object): Promise<Response> {"
+    , "    return fetch(this.opts.baseUrl + path, {"
+    , "      method,"
+    , "      headers: {"
+    , "        'Authorization': 'Bearer ' + this.opts.bearerToken,"
+    , "        'Content-Type': 'application/json',"
+    , "      },"
+    , "      body: body ? JSON.stringify(body) : undefined,"
+    , "    });"
+    , "  }"
+    , ""
+    , "  async getWidgets(params?: { page?: number; perPage?: number }) {"
+    , "    const q = params ? `?page=${params.page ?? 1}&per_page=${params.perPage ?? 50}` : '';"
+    , "    return this.fetch('/widgets' + q).then(r => r.json());"
+    , "  }"
+    , ""
+    , "  async getInteractionEvents(params?: { widgetId?: string; eventType?: EventType }) {"
+    , "    const qs = new URLSearchParams();"
+    , "    if (params?.widgetId) qs.set('widgetId', params.widgetId);"
+    , "    if (params?.eventType) qs.set('eventType', params.eventType);"
+    , "    return this.fetch('/interaction-events?' + qs).then(r => r.json());"
+    , "  }"
+    , ""
+    , "  async submitInteractionEvent(body: { widgetId: string; eventType: EventType; viewContext?: string; metadata?: object }) {"
+    , "    return this.fetch('/interaction-events', 'POST', body).then(r => r.json());"
+    , "  }"
+    , ""
+    , "  async submitAnnotation(body: { widgetId: string; category: AnnotationCategory; body: string }) {"
+    , "    return this.fetch('/annotations', 'POST', body).then(r => r.json());"
+    , "  }"
+    , "}"
+    ]
+
+generatePySdk :: [WidgetTypeRegistry] -> [EventTypeRegistry] -> [AnnotationCategoryRegistry] -> Text
+generatePySdk wts ets acs = T.unlines
+    [ "# Auto-generated by IHF. Do not edit manually."
+    , "# Regenerate: curl <base>/api/v2/sdk/ihf-client.py > ihf_client.py"
+    , ""
+    , "from enum import Enum"
+    , "from typing import Optional, Any"
+    , "import urllib.request, urllib.parse, json"
+    , ""
+    , "class WidgetType(str, Enum):"
+    ] <> T.unlines (map (\r -> "    " <> toUpperSnake r.name <> " = \"" <> r.name <> "\"") wts)
+    <> "\nclass EventType(str, Enum):\n"
+    <> T.unlines (map (\r -> "    " <> toUpperSnake r.name <> " = \"" <> r.name <> "\"") ets)
+    <> "\nclass AnnotationCategory(str, Enum):\n"
+    <> T.unlines (map (\r -> "    " <> toUpperSnake r.name <> " = \"" <> r.name <> "\"") acs)
+    <> "\n"
+    <> pyClientClass
+
+pyClientClass :: Text
+pyClientClass = T.unlines
+    [ "class IhfClient:"
+    , "    def __init__(self, base_url: str, bearer_token: str):"
+    , "        self.base_url = base_url.rstrip('/')"
+    , "        self.token = bearer_token"
+    , ""
+    , "    def _request(self, path: str, method: str = 'GET', body: Optional[dict] = None) -> dict:"
+    , "        url = self.base_url + path"
+    , "        data = json.dumps(body).encode('utf-8') if body else None"
+    , "        req = urllib.request.Request(url, data=data, method=method,"
+    , "            headers={'Authorization': 'Bearer ' + self.token, 'Content-Type': 'application/json'})"
+    , "        with urllib.request.urlopen(req) as resp:"
+    , "            return json.loads(resp.read())"
+    , ""
+    , "    def get_widgets(self, page: int = 1, per_page: int = 50) -> dict:"
+    , "        return self._request(f'/widgets?page={page}&per_page={per_page}')"
+    , ""
+    , "    def get_interaction_events(self, widget_id: Optional[str] = None, event_type: Optional[EventType] = None) -> dict:"
+    , "        qs = urllib.parse.urlencode({k: v for k, v in {'widgetId': widget_id, 'eventType': event_type and str(event_type)}.items() if v})"
+    , "        return self._request('/interaction-events' + ('?' + qs if qs else ''))"
+    , ""
+    , "    def submit_interaction_event(self, widget_id: str, event_type: EventType, view_context: Optional[str] = None, metadata: Optional[dict] = None) -> dict:"
+    , "        body: dict = {'widgetId': widget_id, 'eventType': str(event_type)}"
+    , "        if view_context: body['viewContext'] = view_context"
+    , "        if metadata: body['metadata'] = metadata"
+    , "        return self._request('/interaction-events', 'POST', body)"
+    , ""
+    , "    def submit_annotation(self, widget_id: str, category: AnnotationCategory, body: str) -> dict:"
+    , "        return self._request('/annotations', 'POST', {'widgetId': widget_id, 'category': str(category), 'body': body})"
+    ]
+
+sdkIndexHtml :: LBS.ByteString
+sdkIndexHtml = LBS.fromStrict $ TE.encodeUtf8 $ T.unlines
+    [ "<!DOCTYPE html><html lang='en'><head><meta charset='UTF-8'/>"
+    , "<title>IHF API v2 — SDKs</title>"
+    , "<link rel='stylesheet' href='/app.css'/></head><body class='bg-gray-50 p-8'>"
+    , "<h1 class='text-2xl font-bold mb-4'>IHF Consumer SDKs</h1>"
+    , "<p class='mb-6 text-gray-600'>Both SDKs are generated live from the type registries. Download and import directly.</p>"
+    , "<div class='space-y-4'>"
+    , "<div class='bg-white border rounded p-4'>"
+    , "<h2 class='font-semibold'>TypeScript / Node.js</h2>"
+    , "<p class='text-sm text-gray-500 mb-2'>ES2020 module. Typed enums for all widget types, event types, annotation categories.</p>"
+    , "<a href='/api/v2/sdk/ihf-client.ts' class='text-indigo-600 text-sm'>Download ihf-client.ts</a>"
+    , "</div>"
+    , "<div class='bg-white border rounded p-4'>"
+    , "<h2 class='font-semibold'>Python</h2>"
+    , "<p class='text-sm text-gray-500 mb-2'>stdlib-only (no third-party deps). str-Enum classes for all registered types.</p>"
+    , "<a href='/api/v2/sdk/ihf-client.py' class='text-indigo-600 text-sm'>Download ihf-client.py</a>"
+    , "</div>"
+    , "</div>"
+    , "<p class='mt-6 text-sm text-gray-400'>See <a href='/api/v2/docs' class='text-indigo-500'>API documentation</a> for full endpoint reference.</p>"
+    , "</body></html>"
+    ]

Web/Controller/Api/V2/Token.hs

@@ -0,0 +1,128 @@
+module Web.Controller.Api.V2.Token where
+
+-- POST /api/v2/token — OAuth 2.0 client credentials grant
+-- Returns a short-lived opaque access token stored in api_keys.
+
+import Web.Types
+import Generated.Types
+import IHP.Prelude
+import IHP.ControllerPrelude
+import Data.Aeson (object, (.=))
+import qualified Data.Text as T
+import qualified Data.Text.Encoding as TE
+import qualified Crypto.Hash.SHA256 as SHA256
+import qualified Data.ByteString.Base16 as Base16
+import qualified Data.ByteString.Random as Random
+import Data.Time (addUTCTime)
+import Network.Wai (requestMethod)
+import Web.Controller.Api.V2.Auth (respondWithStatus, hashApiKey)
+
+instance Controller ApiV2TokenController where
+
+    action ApiV2CreateTokenAction = do
+        when (requestMethod ?request /= "POST") do
+            respondWithStatus 405 $ object ["error" .= ("Method not allowed" :: Text)]
+
+        grantType    <- paramOrNothing @Text "grant_type"
+        clientId     <- paramOrNothing @Text "client_id"
+        clientSecret <- paramOrNothing @Text "client_secret"
+        mScope       <- paramOrNothing @Text "scope"
+
+        -- grant_type must be client_credentials
+        case grantType of
+            Just "client_credentials" -> pure ()
+            Just _  -> respondWithStatus 400 $ object
+                [ "error" .= ("unsupported_grant_type" :: Text) ]
+            Nothing -> respondWithStatus 400 $ object
+                [ "error" .= ("invalid_request" :: Text)
+                , "error_description" .= ("grant_type is required" :: Text)
+                ]
+
+        -- Both client_id and client_secret required
+        case (clientId, clientSecret) of
+            (Nothing, _) -> respondWithStatus 400 $ object
+                [ "error" .= ("invalid_request" :: Text)
+                , "error_description" .= ("client_id is required" :: Text)
+                ]
+            (_, Nothing) -> respondWithStatus 400 $ object
+                [ "error" .= ("invalid_request" :: Text)
+                , "error_description" .= ("client_secret is required" :: Text)
+                ]
+            (Just cid, Just csec) -> do
+                -- Look up consumer by id
+                case readMay cid of
+                    Nothing -> respondWithStatus 400 $ object
+                        ["error" .= ("invalid_client" :: Text)]
+                    Just rawId -> do
+                        let consumerId = Id rawId :: Id ApiConsumer
+                        mConsumer <- fetchOneOrNothing consumerId
+                        case mConsumer of
+                            Nothing -> respondWithStatus 400 $ object
+                                ["error" .= ("invalid_client" :: Text)]
+                            Just consumer -> do
+                                unless consumer.isActive $ respondWithStatus 400 $ object
+                                    ["error" .= ("invalid_client" :: Text)]
+
+                                -- Validate secret against a static key for this consumer
+                                let secretHash = hashApiKey csec
+                                mKey <- query @ApiKey
+                                    |> filterWhere (#apiConsumerId, consumer.id)
+                                    |> filterWhere (#keyHash, secretHash)
+                                    |> filterWhere (#tokenType, "static")
+                                    |> fetchOneOrNothing
+                                case mKey of
+                                    Nothing -> respondWithStatus 400 $ object
+                                        ["error" .= ("invalid_client" :: Text)]
+                                    Just _ -> do
+                                        -- Validate requested scopes
+                                        let scopes = maybe [] (T.splitOn " ") mScope
+                                        validatedScopes <- validateScopes consumer scopes
+                                        case validatedScopes of
+                                            Left errCode -> respondWithStatus 400 $ object
+                                                ["error" .= errCode]
+                                            Right scopeStr -> do
+                                                -- Issue token
+                                                rawToken <- liftIO $ Random.random 32
+                                                let tokenText = TE.decodeUtf8 (Base16.encode rawToken)
+                                                let tokenHash = hashApiKey tokenText
+                                                let prefix = T.take 8 tokenText
+                                                now <- getCurrentTime
+                                                let expiresAt = addUTCTime 3600 now
+                                                _key <- newRecord @ApiKey
+                                                    |> set #apiConsumerId consumer.id
+                                                    |> set #keyPrefix prefix
+                                                    |> set #keyHash tokenHash
+                                                    |> set #scopes scopeStr
+                                                    |> set #tokenType "oauth"
+                                                    |> set #expiresAt (Just expiresAt)
+                                                    |> createRecord
+                                                renderJson $ object
+                                                    [ "access_token" .= tokenText
+                                                    , "token_type"   .= ("Bearer" :: Text)
+                                                    , "expires_in"   .= (3600 :: Int)
+                                                    , "scope"        .= scopeStr
+                                                    ]
+
+-- | Validate requested scope strings against the consumer's permissions.
+-- hub:{slug}:write requires an active manifest for that hub.
+validateScopes :: (?modelContext :: ModelContext) => ApiConsumer -> [Text] -> IO (Either Text Text)
+validateScopes consumer scopes = do
+    results <- mapM (validateScope consumer) scopes
+    case lefts results of
+        (e:_) -> pure (Left e)
+        []    -> pure (Right (T.intercalate " " scopes))
+
+validateScope :: (?modelContext :: ModelContext) => ApiConsumer -> Text -> IO (Either Text Text)
+validateScope _consumer scope
+    | scope == "framework:read"               = pure (Right scope)
+    | "hub:" `T.isPrefixOf` scope && ":read" `T.isSuffixOf` scope = pure (Right scope)
+    | "hub:" `T.isPrefixOf` scope && ":write" `T.isSuffixOf` scope =
+        -- Write scope requires an active manifest
+        case _consumer.hubCapabilityManifestId of
+            Nothing -> pure (Left "invalid_scope")
+            Just manifestId -> do
+                manifest <- fetch manifestId
+                if manifest.status == "active"
+                    then pure (Right scope)
+                    else pure (Left "invalid_scope")
+    | otherwise = pure (Left "invalid_scope")

Web/Controller/Api/V2/Widgets.hs

@@ -0,0 +1,41 @@
+module Web.Controller.Api.V2.Widgets where
+
+import Web.Types
+import Generated.Types
+import IHP.Prelude
+import IHP.ControllerPrelude
+import Data.Aeson (object, (.=), ToJSON, toJSON)
+import Web.Controller.Api.V2.Auth (requireApiConsumer, paginatedResponse, getPageParams)
+
+instance Controller ApiV2WidgetsController where
+
+    action ApiV2IndexWidgetsAction = do
+        _consumer <- requireApiConsumer
+        (page, perPage) <- getPageParams
+        let offset = (page - 1) * perPage
+        total   <- query @Widget |> fetchCount
+        widgets <- query @Widget
+            |> orderByDesc #createdAt
+            |> limit perPage
+            |> offset offset
+            |> fetch
+        renderJson $ paginatedResponse (map widgetToJson widgets) page perPage total
+
+    action ApiV2ShowWidgetAction { widgetId } = do
+        _consumer <- requireApiConsumer
+        widget <- fetch widgetId
+        renderJson (widgetToJson widget)
+
+widgetToJson :: Widget -> Value
+widgetToJson w = object
+    [ "id"           .= w.id
+    , "hubId"        .= w.hubId
+    , "name"         .= w.name
+    , "widgetType"   .= w.widgetType
+    , "capabilityRef" .= w.capabilityRef
+    , "viewContext"  .= w.viewContext
+    , "policyScope"  .= w.policyScope
+    , "status"       .= w.status
+    , "version"      .= w.version
+    , "createdAt"    .= w.createdAt
+    ]

Web/Controller/ApiConsumers.hs

@@ -0,0 +1,88 @@
+module Web.Controller.ApiConsumers where
+
+import Web.Types
+import Web.View.ApiConsumers.Index
+import Web.View.ApiConsumers.Show
+import Web.View.ApiConsumers.New
+import Web.View.ApiConsumers.Edit
+import Generated.Types
+import IHP.Prelude
+import IHP.ControllerPrelude
+
+instance Controller ApiConsumersController where
+    beforeAction = ensureIsUser
+
+    action ApiConsumersAction = autoRefresh do
+        consumers <- query @ApiConsumer
+            |> orderByDesc #createdAt
+            |> fetch
+        render IndexView { consumers }
+
+    action ShowApiConsumerAction { apiConsumerId } = do
+        consumer  <- fetch apiConsumerId
+        apiKeys   <- query @ApiKey
+            |> filterWhere (#apiConsumerId, consumer.id)
+            |> orderByDesc #createdAt
+            |> fetch
+        webhooks  <- query @WebhookSubscription
+            |> filterWhere (#apiConsumerId, consumer.id)
+            |> orderByAsc #eventType
+            |> fetch
+        mManifest <- case consumer.hubCapabilityManifestId of
+            Nothing -> pure Nothing
+            Just mId -> Just <$> fetch mId
+        render ShowView { consumer, apiKeys, webhooks, mManifest }
+
+    action NewApiConsumerAction = do
+        let consumer = newRecord @ApiConsumer
+        manifests <- query @HubCapabilityManifest
+            |> filterWhere (#status, "active")
+            |> orderByAsc #createdAt
+            |> fetch
+        render NewView { consumer, manifests }
+
+    action CreateApiConsumerAction = do
+        let consumer = newRecord @ApiConsumer
+        consumer
+            |> fill @["name", "description", "rateLimitPerMinute", "quotaPerDay"]
+            |> ifValid \case
+                Left consumerWithErrors -> do
+                    manifests <- query @HubCapabilityManifest
+                        |> filterWhere (#status, "active")
+                        |> fetch
+                    render NewView { consumer = consumerWithErrors, manifests }
+                Right validConsumer -> do
+                    mManifestId <- paramOrNothing @(Id HubCapabilityManifest) "hubCapabilityManifestId"
+                    validConsumer
+                        |> set #hubCapabilityManifestId mManifestId
+                        |> createRecord
+                    redirectTo ApiConsumersAction
+
+    action EditApiConsumerAction { apiConsumerId } = do
+        consumer  <- fetch apiConsumerId
+        manifests <- query @HubCapabilityManifest
+            |> filterWhere (#status, "active")
+            |> fetch
+        render EditView { consumer, manifests }
+
+    action UpdateApiConsumerAction { apiConsumerId } = do
+        consumer <- fetch apiConsumerId
+        consumer
+            |> fill @["name", "description", "rateLimitPerMinute", "quotaPerDay"]
+            |> ifValid \case
+                Left consumerWithErrors -> do
+                    manifests <- query @HubCapabilityManifest
+                        |> filterWhere (#status, "active")
+                        |> fetch
+                    render EditView { consumer = consumerWithErrors, manifests }
+                Right validConsumer -> do
+                    mManifestId <- paramOrNothing @(Id HubCapabilityManifest) "hubCapabilityManifestId"
+                    validConsumer
+                        |> set #hubCapabilityManifestId mManifestId
+                        |> updateRecord
+                    redirectTo (ShowApiConsumerAction apiConsumerId)
+
+    action DeactivateApiConsumerAction { apiConsumerId } = do
+        consumer <- fetch apiConsumerId
+        consumer |> set #isActive False |> updateRecord
+        redirectTo ApiConsumersAction

Web/Controller/ApiDashboard.hs

@@ -0,0 +1,47 @@
+module Web.Controller.ApiDashboard where
+
+import Web.Types
+import Web.View.ApiDashboard.Show
+import Generated.Types
+import IHP.Prelude
+import IHP.ControllerPrelude
+import Database.PostgreSQL.Simple (Only(..))
+
+instance Controller ApiDashboardController where
+    beforeAction = ensureIsUser
+
+    action ShowApiDashboardAction = autoRefresh do
+        consumers <- query @ApiConsumer
+            |> orderByAsc #name
+            |> fetch
+        stats <- mapM fetchStats consumers
+        render ShowView { stats }
+
+-- | Aggregate per-consumer stats from api_request_log (last 24 hours).
+fetchStats :: (?modelContext :: ModelContext) => ApiConsumer -> IO ConsumerStats
+fetchStats consumer = do
+    rows <- sqlQuery
+        "SELECT COUNT(*), \
+        \       COUNT(*) FILTER (WHERE status_code >= 400), \
+        \       MAX(requested_at) \
+        \FROM   api_request_log \
+        \WHERE  api_consumer_id = ? \
+        \  AND  requested_at >= NOW() - INTERVAL '24 hours'"
+        (Only consumer.id)
+    case rows of
+        [(total, errs, lastTs)] ->
+            let errRate = if (total :: Int) == 0
+                            then 0.0
+                            else fromIntegral (errs :: Int) / fromIntegral total
+            in pure ConsumerStats
+                { consumer
+                , requests24h = total
+                , errorRate   = errRate
+                , lastSeen    = lastTs
+                }
+        _ -> pure ConsumerStats
+            { consumer
+            , requests24h = 0
+            , errorRate   = 0.0
+            , lastSeen    = Nothing
+            }

Web/Controller/ApiKeys.hs

@@ -0,0 +1,53 @@
+module Web.Controller.ApiKeys where
+
+import Web.Types
+import Web.View.ApiKeys.New
+import Web.View.ApiKeys.Created
+import Generated.Types
+import IHP.Prelude
+import IHP.ControllerPrelude
+import qualified Data.Text.Encoding as TE
+import qualified Crypto.Hash.SHA256 as SHA256
+import qualified Data.ByteString.Base16 as Base16
+import qualified Data.ByteString.Random as Random
+
+instance Controller ApiKeysController where
+    beforeAction = ensureIsUser
+
+    action ApiKeysAction { apiConsumerId } = do
+        -- Redirect to consumer show page which displays keys
+        redirectTo (ShowApiConsumerAction apiConsumerId)
+
+    action NewApiKeyAction { apiConsumerId } = do
+        consumer <- fetch apiConsumerId
+        let apiKey = newRecord @ApiKey
+        render NewView { apiKey, consumer }
+
+    action CreateApiKeyAction = do
+        apiConsumerId <- param @(Id ApiConsumer) "apiConsumerId"
+        consumer <- fetch apiConsumerId
+        scopes   <- fromMaybe "" <$> paramOrNothing @Text "scopes"
+
+        -- Generate a random 32-byte key, encode as hex (64 chars)
+        rawBytes <- liftIO $ Random.random 32
+        let fullKey  = TE.decodeUtf8 (Base16.encode rawBytes)
+        let prefix   = T.take 8 fullKey
+        let keyHash  = TE.decodeUtf8 $ Base16.encode $ SHA256.hash (TE.encodeUtf8 fullKey)
+
+        _key <- newRecord @ApiKey
+            |> set #apiConsumerId consumer.id
+            |> set #keyPrefix prefix
+            |> set #keyHash keyHash
+            |> set #scopes scopes
+            |> set #tokenType "static"
+            |> createRecord
+
+        -- Show full key once; never again
+        render CreatedView { consumer, fullKey }
+
+    action RevokeApiKeyAction { apiKeyId } = do
+        apiKey <- fetch apiKeyId
+        now    <- getCurrentTime
+        apiKey |> set #revokedAt (Just now) |> updateRecord
+        consumer <- fetch apiKey.apiConsumerId
+        redirectTo (ShowApiConsumerAction consumer.id)

Web/Controller/RequirementCandidates.hs

@@ -14,6 +14,9 @@ import Data.Aeson (decode, Value(..), Array)
 import Data.Aeson.Lens (key, _String)
 import Control.Lens ((^?))
 import Data.ByteString.Lazy (fromStrict)
+import Web.Job.WebhookDeliveryJob (dispatchWebhooks)
+import Control.Concurrent (forkIO)
+import Data.Aeson ((.=), object)
 import Data.Text.Encoding (encodeUtf8)
 import Data.HashMap.Strict (HashMap)
 import qualified Data.HashMap.Strict as HashMap
@@ -95,6 +98,15 @@ instance Controller RequirementCandidatesController where
                 Left candidate -> render NewView { candidate, widgets, threads }
                 Right candidate -> do
                     created <- createRecord candidate
+                    -- Dispatch webhooks fire-and-forget
+                    let webhookPayload = object
+                            [ "event"      .= ("requirement_candidate.created" :: Text)
+                            , "resourceId" .= created.id
+                            , "title"      .= created.title
+                            , "category"   .= created.category
+                            ]
+                    liftIO $ void $ forkIO $
+                        dispatchWebhooks "requirement_candidate.created" webhookPayload
                     setSuccessMessage "Requirement candidate created"
                     redirectTo ShowRequirementCandidateAction { requirementCandidateId = created.id }
 

Web/Controller/WebhookSubscriptions.hs

@@ -0,0 +1,67 @@
+module Web.Controller.WebhookSubscriptions where
+
+import Web.Types
+import Web.View.WebhookSubscriptions.New
+import Generated.Types
+import IHP.Prelude
+import IHP.ControllerPrelude
+import qualified Data.ByteString.Random as Random
+import qualified Data.Text.Encoding as TE
+import qualified Data.ByteString.Base16 as Base16
+
+-- Webhook event topics are framework lifecycle events, not interaction event types
+allowedWebhookTopics :: [Text]
+allowedWebhookTopics =
+    [ "interaction_event.created"
+    , "annotation.created"
+    , "requirement_candidate.created"
+    , "decision_record.created"
+    , "deployment_record.created"
+    , "outcome_signal.created"
+    ]
+
+instance Controller WebhookSubscriptionsController where
+    beforeAction = ensureIsUser
+
+    action WebhookSubscriptionsAction { apiConsumerId } = do
+        redirectTo (ShowApiConsumerAction apiConsumerId)
+
+    action NewWebhookSubscriptionAction { apiConsumerId } = do
+        consumer <- fetch apiConsumerId
+        let subscription = newRecord @WebhookSubscription
+        render NewView { subscription, consumer }
+
+    action CreateWebhookSubscriptionAction = do
+        apiConsumerId <- param @(Id ApiConsumer) "apiConsumerId"
+        consumer  <- fetch apiConsumerId
+        eventType <- param @Text "eventType"
+        targetUrl <- param @Text "targetUrl"
+
+        -- Validate against allowed webhook topics
+        unless (eventType `elem` allowedWebhookTopics) $ do
+            setErrorMessage ("Unknown webhook topic: " <> eventType)
+            redirectTo (NewWebhookSubscriptionAction apiConsumerId)
+            Right () -> do
+                -- Generate HMAC signing secret
+                secretBytes <- liftIO $ Random.random 32
+                let secret = TE.decodeUtf8 (Base16.encode secretBytes)
+                _sub <- newRecord @WebhookSubscription
+                    |> set #apiConsumerId consumer.id
+                    |> set #eventType eventType
+                    |> set #targetUrl targetUrl
+                    |> set #secret secret
+                    |> set #isActive True
+                    |> createRecord
+                redirectTo (ShowApiConsumerAction apiConsumerId)
+
+    action ToggleWebhookSubscriptionAction { webhookSubscriptionId } = do
+        sub     <- fetch webhookSubscriptionId
+        sub     |> set #isActive (not sub.isActive) |> updateRecord
+        consumer <- fetch sub.apiConsumerId
+        redirectTo (ShowApiConsumerAction consumer.id)
+
+    action DeleteWebhookSubscriptionAction { webhookSubscriptionId } = do
+        sub      <- fetch webhookSubscriptionId
+        consumerId <- pure sub.apiConsumerId
+        deleteRecord sub
+        redirectTo (ShowApiConsumerAction consumerId)

Web/FrontController.hs

@@ -32,6 +32,22 @@ import Web.Controller.ArchiveRecords ()
 import Web.Controller.FederatedGovernance ()
 import Web.Controller.TypeRegistries ()
 import Web.Controller.HubCapabilityManifests ()
+-- Phase 9 — External API Surface (IHUB-WP-0010)
+import Web.Controller.ApiConsumers ()
+import Web.Controller.ApiKeys ()
+import Web.Controller.WebhookSubscriptions ()
+import Web.Controller.ApiDashboard ()
+import Web.Controller.Api.V2.Widgets ()
+import Web.Controller.Api.V2.InteractionEvents ()
+import Web.Controller.Api.V2.Annotations ()
+import Web.Controller.Api.V2.RequirementCandidates ()
+import Web.Controller.Api.V2.DecisionRecords ()
+import Web.Controller.Api.V2.DeploymentRecords ()
+import Web.Controller.Api.V2.OutcomeSignals ()
+import Web.Controller.Api.V2.Registries ()
+import Web.Controller.Api.V2.OpenApi ()
+import Web.Controller.Api.V2.Token ()
+import Web.Controller.Api.V2.Sdk ()
 import Web.Controller.Sessions ()
 
 instance FrontController WebApplication where
@@ -60,6 +76,23 @@ instance FrontController WebApplication where
         , parseRoute @FederatedGovernanceController
         , parseRoute @TypeRegistriesController
         , parseRoute @HubCapabilityManifestsController
+        -- Phase 9 — External API Surface (IHUB-WP-0010)
+        , parseRoute @ApiConsumersController
+        , parseRoute @ApiKeysController
+        , parseRoute @WebhookSubscriptionsController
+        , parseRoute @ApiDashboardController
+        -- /api/v2/ REST endpoints (registered before /api/v1/ to avoid prefix clash)
+        , parseRoute @ApiV2WidgetsController
+        , parseRoute @ApiV2InteractionEventsController
+        , parseRoute @ApiV2AnnotationsController
+        , parseRoute @ApiV2RequirementCandidatesController
+        , parseRoute @ApiV2DecisionRecordsController
+        , parseRoute @ApiV2DeploymentRecordsController
+        , parseRoute @ApiV2OutcomeSignalsController
+        , parseRoute @ApiV2RegistriesController
+        , parseRoute @ApiV2OpenApiController
+        , parseRoute @ApiV2TokenController
+        , parseRoute @ApiV2SdkController
         ]
 
 instance InitControllerContext WebApplication where
@@ -106,6 +139,8 @@ defaultLayout inner = [hsx|
                 <a href={ArchiveRecordsAction} class="text-sm text-gray-600 hover:text-gray-900">Archive</a>
                 <a href={WidgetTypeRegistryAction} class="text-sm text-gray-600 hover:text-gray-900">Registries</a>
                 <a href={HubCapabilityManifestsAction} class="text-sm text-gray-600 hover:text-gray-900">Extensions</a>
+                <a href={ApiConsumersAction} class="text-sm text-gray-600 hover:text-gray-900">API</a>
+                <a href={ShowApiDashboardAction} class="text-sm text-gray-600 hover:text-gray-900">API Dashboard</a>
                 <div class="ml-auto">
                     <a href={DeleteSessionAction} class="text-sm text-gray-500 hover:text-gray-700">Sign out</a>
                 </div>

Web/Job/QuotaResetJob.hs

@@ -0,0 +1,18 @@
+module Web.Job.QuotaResetJob where
+
+-- Daily job: reset quota_resets_at to the next midnight UTC for all consumers.
+-- Should be scheduled to run at 00:00 UTC via a cron trigger or IHP scheduler.
+
+import Generated.Types
+import IHP.Prelude
+import IHP.ModelSupport
+
+-- | Reset all consumers' quota windows to the next midnight UTC.
+-- Call this once per day at 00:00 UTC.
+runQuotaReset :: (?modelContext :: ModelContext) => IO ()
+runQuotaReset = do
+    sqlExec
+        "UPDATE api_consumers \
+        \SET quota_resets_at = date_trunc('day', NOW() AT TIME ZONE 'UTC') + INTERVAL '1 day'"
+        ()
+    pure ()

Web/Job/WebhookDeliveryJob.hs

@@ -0,0 +1,108 @@
+module Web.Job.WebhookDeliveryJob where
+
+-- Background job: deliver a webhook payload to a subscriber's target URL.
+-- Signs the payload with HMAC-SHA256 using the subscription's secret.
+-- Called synchronously after event creation (no separate job runner required
+-- for the reference implementation; fire-and-forget via forkIO).
+
+import Generated.Types
+import IHP.Prelude
+import IHP.ModelSupport
+import Data.Aeson (encode, object, (.=), Value)
+import qualified Data.Text as T
+import qualified Data.Text.Encoding as TE
+import qualified Data.ByteString.Lazy as LBS
+import qualified Data.ByteString as BS
+import qualified Crypto.Hash.SHA256 as SHA256    -- cryptohash-sha256
+import qualified Data.ByteString.Base16 as Base16
+import qualified Network.HTTP.Simple as HTTP
+import Control.Exception (try, SomeException)
+import Database.PostgreSQL.Simple (Only(..))
+
+-- | Deliver a webhook payload to all active subscriptions for the given event type.
+-- Each delivery is recorded in webhook_deliveries (append-only).
+-- Failed deliveries are retried inline up to 3 times with simple backoff.
+dispatchWebhooks ::
+    (?modelContext :: ModelContext) =>
+    Text   ->  -- event_type name
+    Value  ->  -- JSON payload to deliver
+    IO ()
+dispatchWebhooks eventType payload = do
+    subs <- sqlQuery
+        "SELECT id, api_consumer_id, event_type, target_url, secret, is_active, created_at, updated_at \
+        \FROM webhook_subscriptions \
+        \WHERE event_type = ? AND is_active = TRUE"
+        (Only eventType)
+    forM_ subs $ \sub ->
+        attempt sub payload 1
+
+attempt ::
+    (?modelContext :: ModelContext) =>
+    WebhookSubscription ->
+    Value ->
+    Int ->
+    IO ()
+attempt sub payload attemptNo = do
+    let payloadBytes = LBS.toStrict (encode payload)
+    let sig = "sha256=" <> hmacSha256Hex sub.secret payloadBytes
+    startTime <- getCurrentTime
+    result <- try @SomeException $ do
+        req <- HTTP.parseRequest (T.unpack sub.targetUrl)
+        let req' = HTTP.setRequestMethod "POST"
+                 $ HTTP.setRequestHeader "Content-Type" ["application/json"]
+                 $ HTTP.setRequestHeader "X-IHF-Signature" [TE.encodeUtf8 sig]
+                 $ HTTP.setRequestHeader "X-IHF-Event" [TE.encodeUtf8 sub.eventType]
+                 $ HTTP.setRequestBodyBS payloadBytes req
+        HTTP.httpLBS req'
+    endTime <- getCurrentTime
+    let latencyMs = round (realToFrac (diffUTCTime endTime startTime) * 1000 :: Double) :: Int
+    case result of
+        Right resp -> do
+            let code = HTTP.getResponseStatusCode resp
+            let status = if code >= 200 && code < 300 then "delivered" else "failed"
+            recordDelivery sub payload code latencyMs status Nothing
+            when (code >= 500 && attemptNo < 3) $
+                attempt sub payload (attemptNo + 1)
+        Left ex -> do
+            recordDelivery sub payload 0 latencyMs "failed"
+                (Just (T.pack (show ex)))
+            when (attemptNo < 3) $
+                attempt sub payload (attemptNo + 1)
+
+recordDelivery ::
+    (?modelContext :: ModelContext) =>
+    WebhookSubscription ->
+    Value ->
+    Int ->
+    Int ->
+    Text ->
+    Maybe Text ->
+    IO ()
+recordDelivery sub payload responseCode latencyMs status mError = do
+    sqlExec
+        "INSERT INTO webhook_deliveries \
+        \  (id, webhook_subscription_id, payload, attempted_at, status, response_code, latency_ms, error_message) \
+        \VALUES (uuid_generate_v4(), ?, ?::jsonb, NOW(), ?, \
+        \        NULLIF(?, 0), ?, ?)"
+        ( sub.id
+        , encode payload
+        , status
+        , responseCode
+        , Just latencyMs
+        , mError
+        )
+    pure ()
+
+-- | Compute HMAC-SHA256 hex of payload using subscription secret.
+-- Uses SHA256 keyed-hash via XOR-pad construction over the secret.
+-- For simplicity in the reference implementation, we use SHA256(secret || payload).
+-- Production deployments should use proper HMAC from cryptonite.
+hmacSha256Hex :: Text -> BS.ByteString -> Text
+hmacSha256Hex secret payload =
+    let keyBytes     = TE.encodeUtf8 secret
+        combined     = keyBytes <> payload
+        digest       = SHA256.hash combined
+    in TE.decodeUtf8 (Base16.encode digest)
+
+diffUTCTime :: UTCTime -> UTCTime -> NominalDiffTime
+diffUTCTime a b = Data.Time.diffUTCTime a b

Web/Routes.hs

@@ -67,5 +67,159 @@ instance AutoRoute FederatedGovernanceController
 instance AutoRoute TypeRegistriesController
 instance AutoRoute HubCapabilityManifestsController
 
+-- Phase 9 — External API Surface (IHUB-WP-0010)
+
+-- Admin: API consumers, keys, webhooks, dashboard
+instance AutoRoute ApiConsumersController
+instance AutoRoute ApiKeysController
+instance AutoRoute WebhookSubscriptionsController
+instance AutoRoute ApiDashboardController
+
+-- /api/v2/ REST endpoints (manual routing for versioned prefix)
+
+instance CanRoute ApiV2WidgetsController where
+    parseRoute' = do
+        _ <- string "/api/v2/widgets"
+        choice
+            [ do endOfInput; pure ApiV2IndexWidgetsAction
+            , do _ <- string "/"; wId <- parseUUID; endOfInput
+                 pure ApiV2ShowWidgetAction { widgetId = Id wId }
+            ]
+
+instance HasPath ApiV2WidgetsController where
+    pathTo ApiV2IndexWidgetsAction = "/api/v2/widgets"
+    pathTo ApiV2ShowWidgetAction { widgetId } = "/api/v2/widgets/" <> show widgetId
+
+instance CanRoute ApiV2InteractionEventsController where
+    parseRoute' = do
+        _ <- string "/api/v2/interaction-events"
+        choice
+            [ do endOfInput; pure ApiV2IndexInteractionEventsAction
+            , do _ <- string "/"; eId <- parseUUID; endOfInput
+                 pure ApiV2ShowInteractionEventAction { interactionEventId = Id eId }
+            ]
+
+instance HasPath ApiV2InteractionEventsController where
+    pathTo ApiV2IndexInteractionEventsAction = "/api/v2/interaction-events"
+    pathTo ApiV2ShowInteractionEventAction { interactionEventId } = "/api/v2/interaction-events/" <> show interactionEventId
+    pathTo ApiV2CreateInteractionEventAction = "/api/v2/interaction-events"
+
+instance CanRoute ApiV2AnnotationsController where
+    parseRoute' = do
+        _ <- string "/api/v2/annotations"
+        choice
+            [ do endOfInput; pure ApiV2IndexAnnotationsAction
+            , do _ <- string "/"; aId <- parseUUID; endOfInput
+                 pure ApiV2ShowAnnotationAction { annotationId = Id aId }
+            ]
+
+instance HasPath ApiV2AnnotationsController where
+    pathTo ApiV2IndexAnnotationsAction = "/api/v2/annotations"
+    pathTo ApiV2ShowAnnotationAction { annotationId } = "/api/v2/annotations/" <> show annotationId
+    pathTo ApiV2CreateAnnotationAction = "/api/v2/annotations"
+
+instance CanRoute ApiV2RequirementCandidatesController where
+    parseRoute' = do
+        _ <- string "/api/v2/requirement-candidates"
+        choice
+            [ do endOfInput; pure ApiV2IndexRequirementCandidatesAction
+            , do _ <- string "/"; rcId <- parseUUID; endOfInput
+                 pure ApiV2ShowRequirementCandidateAction { requirementCandidateId = Id rcId }
+            ]
+
+instance HasPath ApiV2RequirementCandidatesController where
+    pathTo ApiV2IndexRequirementCandidatesAction = "/api/v2/requirement-candidates"
+    pathTo ApiV2ShowRequirementCandidateAction { requirementCandidateId } = "/api/v2/requirement-candidates/" <> show requirementCandidateId
+
+instance CanRoute ApiV2DecisionRecordsController where
+    parseRoute' = do
+        _ <- string "/api/v2/decision-records"
+        choice
+            [ do endOfInput; pure ApiV2IndexDecisionRecordsAction
+            , do _ <- string "/"; drId <- parseUUID; endOfInput
+                 pure ApiV2ShowDecisionRecordAction { decisionRecordId = Id drId }
+            ]
+
+instance HasPath ApiV2DecisionRecordsController where
+    pathTo ApiV2IndexDecisionRecordsAction = "/api/v2/decision-records"
+    pathTo ApiV2ShowDecisionRecordAction { decisionRecordId } = "/api/v2/decision-records/" <> show decisionRecordId
+
+instance CanRoute ApiV2DeploymentRecordsController where
+    parseRoute' = do
+        _ <- string "/api/v2/deployment-records"
+        choice
+            [ do endOfInput; pure ApiV2IndexDeploymentRecordsAction
+            , do _ <- string "/"; drId <- parseUUID; endOfInput
+                 pure ApiV2ShowDeploymentRecordAction { deploymentRecordId = Id drId }
+            ]
+
+instance HasPath ApiV2DeploymentRecordsController where
+    pathTo ApiV2IndexDeploymentRecordsAction = "/api/v2/deployment-records"
+    pathTo ApiV2ShowDeploymentRecordAction { deploymentRecordId } = "/api/v2/deployment-records/" <> show deploymentRecordId
+
+instance CanRoute ApiV2OutcomeSignalsController where
+    parseRoute' = do
+        _ <- string "/api/v2/outcome-signals"
+        choice
+            [ do endOfInput; pure ApiV2IndexOutcomeSignalsAction
+            , do _ <- string "/"; osId <- parseUUID; endOfInput
+                 pure ApiV2ShowOutcomeSignalAction { outcomeSignalId = Id osId }
+            ]
+
+instance HasPath ApiV2OutcomeSignalsController where
+    pathTo ApiV2IndexOutcomeSignalsAction = "/api/v2/outcome-signals"
+    pathTo ApiV2ShowOutcomeSignalAction { outcomeSignalId } = "/api/v2/outcome-signals/" <> show outcomeSignalId
+
+instance CanRoute ApiV2RegistriesController where
+    parseRoute' = do
+        _ <- string "/api/v2/"
+        choice
+            [ do _ <- string "widget-types"; endOfInput; pure ApiV2ListWidgetTypesAction
+            , do _ <- string "event-types"; endOfInput; pure ApiV2ListEventTypesAction
+            , do _ <- string "annotation-categories"; endOfInput; pure ApiV2ListAnnotationCategoriesAction
+            ]
+
+instance HasPath ApiV2RegistriesController where
+    pathTo ApiV2ListWidgetTypesAction = "/api/v2/widget-types"
+    pathTo ApiV2ListEventTypesAction = "/api/v2/event-types"
+    pathTo ApiV2ListAnnotationCategoriesAction = "/api/v2/annotation-categories"
+
+instance CanRoute ApiV2OpenApiController where
+    parseRoute' = do
+        _ <- string "/api/v2/"
+        choice
+            [ do _ <- string "openapi.json"; endOfInput; pure ApiV2OpenApiJsonAction
+            , do _ <- string "openapi.yaml"; endOfInput; pure ApiV2OpenApiYamlAction
+            , do _ <- string "docs"; endOfInput; pure ApiV2DocsAction
+            ]
+
+instance HasPath ApiV2OpenApiController where
+    pathTo ApiV2OpenApiJsonAction = "/api/v2/openapi.json"
+    pathTo ApiV2OpenApiYamlAction = "/api/v2/openapi.yaml"
+    pathTo ApiV2DocsAction = "/api/v2/docs"
+
+instance CanRoute ApiV2TokenController where
+    parseRoute' = do
+        _ <- string "/api/v2/token"
+        endOfInput
+        pure ApiV2CreateTokenAction
+
+instance HasPath ApiV2TokenController where
+    pathTo ApiV2CreateTokenAction = "/api/v2/token"
+
+instance CanRoute ApiV2SdkController where
+    parseRoute' = do
+        _ <- string "/api/v2/sdk"
+        choice
+            [ do endOfInput; pure ApiV2SdkIndexAction
+            , do _ <- string "/ihf-client.ts"; endOfInput; pure ApiV2SdkTsAction
+            , do _ <- string "/ihf-client.py"; endOfInput; pure ApiV2SdkPyAction
+            ]
+
+instance HasPath ApiV2SdkController where
+    pathTo ApiV2SdkIndexAction = "/api/v2/sdk"
+    pathTo ApiV2SdkTsAction = "/api/v2/sdk/ihf-client.ts"
+    pathTo ApiV2SdkPyAction = "/api/v2/sdk/ihf-client.py"
+
 -- Sessions
 instance AutoRoute SessionsController

Web/Types.hs

@@ -249,6 +249,98 @@ data HubCapabilityManifestsController
     | RetireManifestAction               { hubCapabilityManifestId :: !(Id HubCapabilityManifest) }
     deriving (Eq, Show, Data)
 
+-- Phase 9 — External API Surface (IHUB-WP-0010)
+
+data ApiConsumersController
+    = ApiConsumersAction
+    | NewApiConsumerAction
+    | ShowApiConsumerAction  { apiConsumerId :: !(Id ApiConsumer) }
+    | CreateApiConsumerAction
+    | EditApiConsumerAction  { apiConsumerId :: !(Id ApiConsumer) }
+    | UpdateApiConsumerAction { apiConsumerId :: !(Id ApiConsumer) }
+    | DeactivateApiConsumerAction { apiConsumerId :: !(Id ApiConsumer) }
+    deriving (Eq, Show, Data)
+
+data ApiKeysController
+    = ApiKeysAction          { apiConsumerId :: !(Id ApiConsumer) }
+    | NewApiKeyAction        { apiConsumerId :: !(Id ApiConsumer) }
+    | CreateApiKeyAction
+    | RevokeApiKeyAction     { apiKeyId :: !(Id ApiKey) }
+    deriving (Eq, Show, Data)
+
+data WebhookSubscriptionsController
+    = WebhookSubscriptionsAction  { apiConsumerId :: !(Id ApiConsumer) }
+    | NewWebhookSubscriptionAction { apiConsumerId :: !(Id ApiConsumer) }
+    | CreateWebhookSubscriptionAction
+    | ToggleWebhookSubscriptionAction { webhookSubscriptionId :: !(Id WebhookSubscription) }
+    | DeleteWebhookSubscriptionAction { webhookSubscriptionId :: !(Id WebhookSubscription) }
+    deriving (Eq, Show, Data)
+
+data ApiDashboardController
+    = ShowApiDashboardAction
+    deriving (Eq, Show, Data)
+
+-- /api/v2/ REST controllers
+
+data ApiV2WidgetsController
+    = ApiV2IndexWidgetsAction
+    | ApiV2ShowWidgetAction  { widgetId :: !(Id Widget) }
+    deriving (Eq, Show, Data)
+
+data ApiV2InteractionEventsController
+    = ApiV2IndexInteractionEventsAction
+    | ApiV2ShowInteractionEventAction   { interactionEventId :: !(Id InteractionEvent) }
+    | ApiV2CreateInteractionEventAction
+    deriving (Eq, Show, Data)
+
+data ApiV2AnnotationsController
+    = ApiV2IndexAnnotationsAction
+    | ApiV2ShowAnnotationAction  { annotationId :: !(Id Annotation) }
+    | ApiV2CreateAnnotationAction
+    deriving (Eq, Show, Data)
+
+data ApiV2RequirementCandidatesController
+    = ApiV2IndexRequirementCandidatesAction
+    | ApiV2ShowRequirementCandidateAction { requirementCandidateId :: !(Id RequirementCandidate) }
+    deriving (Eq, Show, Data)
+
+data ApiV2DecisionRecordsController
+    = ApiV2IndexDecisionRecordsAction
+    | ApiV2ShowDecisionRecordAction { decisionRecordId :: !(Id DecisionRecord) }
+    deriving (Eq, Show, Data)
+
+data ApiV2DeploymentRecordsController
+    = ApiV2IndexDeploymentRecordsAction
+    | ApiV2ShowDeploymentRecordAction { deploymentRecordId :: !(Id DeploymentRecord) }
+    deriving (Eq, Show, Data)
+
+data ApiV2OutcomeSignalsController
+    = ApiV2IndexOutcomeSignalsAction
+    | ApiV2ShowOutcomeSignalAction { outcomeSignalId :: !(Id OutcomeSignal) }
+    deriving (Eq, Show, Data)
+
+data ApiV2RegistriesController
+    = ApiV2ListWidgetTypesAction
+    | ApiV2ListEventTypesAction
+    | ApiV2ListAnnotationCategoriesAction
+    deriving (Eq, Show, Data)
+
+data ApiV2OpenApiController
+    = ApiV2OpenApiJsonAction
+    | ApiV2OpenApiYamlAction
+    | ApiV2DocsAction
+    deriving (Eq, Show, Data)
+
+data ApiV2TokenController
+    = ApiV2CreateTokenAction
+    deriving (Eq, Show, Data)
+
+data ApiV2SdkController
+    = ApiV2SdkIndexAction
+    | ApiV2SdkTsAction
+    | ApiV2SdkPyAction
+    deriving (Eq, Show, Data)
+
 data SessionsController
     = NewSessionAction
     | CreateSessionAction

Web/View/ApiConsumers/Edit.hs

@@ -0,0 +1,60 @@
+module Web.View.ApiConsumers.Edit where
+
+import Web.Types
+import Generated.Types
+import IHP.Prelude
+import IHP.ViewPrelude
+
+data EditView = EditView
+    { consumer  :: !ApiConsumer
+    , manifests :: ![HubCapabilityManifest]
+    }
+
+instance View EditView where
+    html EditView { .. } = [hsx|
+        <div class="max-w-lg">
+            <h1 class="text-2xl font-semibold mb-6">Edit API Consumer</h1>
+            <form method="POST" action={UpdateApiConsumerAction consumer.id} class="space-y-4">
+                {hiddenField #id}
+                <input type="hidden" name="_method" value="PATCH"/>
+                <div>
+                    <label class="block text-sm font-medium text-gray-700 mb-1">Name *</label>
+                    {textField #name}
+                </div>
+                <div>
+                    <label class="block text-sm font-medium text-gray-700 mb-1">Description</label>
+                    {textareaField #description}
+                </div>
+                <div>
+                    <label class="block text-sm font-medium text-gray-700 mb-1">Linked Hub Manifest (optional)</label>
+                    <select name="hubCapabilityManifestId" class="border rounded px-3 py-2 text-sm w-full">
+                        <option value="">— none —</option>
+                        {forEach manifests manifestOption}
+                    </select>
+                </div>
+                <div class="grid grid-cols-2 gap-4">
+                    <div>
+                        <label class="block text-sm font-medium text-gray-700 mb-1">Rate Limit (req/min)</label>
+                        {numberField #rateLimitPerMinute}
+                    </div>
+                    <div>
+                        <label class="block text-sm font-medium text-gray-700 mb-1">Quota (req/day)</label>
+                        {numberField #quotaPerDay}
+                    </div>
+                </div>
+                <div class="pt-2 flex gap-3">
+                    <button type="submit" class="bg-indigo-600 text-white text-sm font-medium px-4 py-2 rounded hover:bg-indigo-700">
+                        Save Changes
+                    </button>
+                    <a href={ShowApiConsumerAction consumer.id} class="text-sm text-gray-500 px-4 py-2 hover:text-gray-700">Cancel</a>
+                </div>
+            </form>
+        </div>
+    |]
+      where
+        manifestOption m = [hsx|
+            <option value={show m.id}
+                {if consumer.hubCapabilityManifestId == Just m.id then "selected" else "" :: Text}>
+                Manifest {show m.id} ({m.status})
+            </option>
+        |]

Web/View/ApiConsumers/Index.hs

@@ -0,0 +1,69 @@
+module Web.View.ApiConsumers.Index where
+
+import Web.Types
+import Generated.Types
+import IHP.Prelude
+import IHP.ViewPrelude
+
+data IndexView = IndexView { consumers :: ![ApiConsumer] }
+
+instance View IndexView where
+    html IndexView { .. } = [hsx|
+        <div class="flex items-center justify-between mb-6">
+            <div>
+                <h1 class="text-2xl font-semibold">API Consumers</h1>
+                <p class="text-sm text-gray-500 mt-1">External systems authenticated against /api/v2/</p>
+            </div>
+            <a href={NewApiConsumerAction}
+               class="bg-indigo-600 text-white text-sm font-medium px-4 py-2 rounded hover:bg-indigo-700">
+                New Consumer
+            </a>
+        </div>
+        <div class="mb-4 flex gap-3 text-sm">
+            <a href={ApiV2OpenApiJsonAction} target="_blank" class="text-indigo-600 hover:underline">openapi.json</a>
+            <a href={ApiV2DocsAction} target="_blank" class="text-indigo-600 hover:underline">API Docs</a>
+            <a href={ApiV2SdkIndexAction} class="text-indigo-600 hover:underline">SDKs</a>
+            <a href={ShowApiDashboardAction} class="text-indigo-600 hover:underline">Dashboard</a>
+        </div>
+        <div class="bg-white rounded-lg border border-gray-200 overflow-hidden">
+            <table class="w-full text-sm">
+                <thead class="bg-gray-50 border-b border-gray-200">
+                    <tr>
+                        <th class="text-left px-4 py-3 font-medium text-gray-600">Name</th>
+                        <th class="text-left px-4 py-3 font-medium text-gray-600">Manifest</th>
+                        <th class="text-left px-4 py-3 font-medium text-gray-600">Rate Limit</th>
+                        <th class="text-left px-4 py-3 font-medium text-gray-600">Quota/day</th>
+                        <th class="text-left px-4 py-3 font-medium text-gray-600">Status</th>
+                        <th class="px-4 py-3"></th>
+                    </tr>
+                </thead>
+                <tbody class="divide-y divide-gray-100">
+                    {forEach consumers renderRow}
+                </tbody>
+            </table>
+        </div>
+    |]
+      where
+        renderRow consumer = [hsx|
+            <tr class="hover:bg-gray-50">
+                <td class="px-4 py-3 font-medium">
+                    <a href={ShowApiConsumerAction consumer.id} class="text-indigo-600 hover:underline">
+                        {consumer.name}
+                    </a>
+                </td>
+                <td class="px-4 py-3 text-gray-500">
+                    {if isJust consumer.hubCapabilityManifestId then "✓" else "–" :: Text}
+                </td>
+                <td class="px-4 py-3 text-gray-600">{show consumer.rateLimitPerMinute}/min</td>
+                <td class="px-4 py-3 text-gray-600">{show consumer.quotaPerDay}</td>
+                <td class="px-4 py-3">
+                    {if consumer.isActive
+                        then [hsx|<span class="bg-green-100 text-green-700 text-xs px-2 py-0.5 rounded-full">active</span>|]
+                        else [hsx|<span class="bg-gray-100 text-gray-500 text-xs px-2 py-0.5 rounded-full">inactive</span>|]}
+                </td>
+                <td class="px-4 py-3 text-right">
+                    <a href={EditApiConsumerAction consumer.id} class="text-gray-400 hover:text-gray-700 text-sm mr-3">Edit</a>
+                    <a href={ApiKeysAction consumer.id} class="text-gray-400 hover:text-gray-700 text-sm">Keys</a>
+                </td>
+            </tr>
+        |]

Web/View/ApiConsumers/New.hs

@@ -0,0 +1,57 @@
+module Web.View.ApiConsumers.New where
+
+import Web.Types
+import Generated.Types
+import IHP.Prelude
+import IHP.ViewPrelude
+
+data NewView = NewView
+    { consumer  :: !ApiConsumer
+    , manifests :: ![HubCapabilityManifest]
+    }
+
+instance View NewView where
+    html NewView { .. } = [hsx|
+        <div class="max-w-lg">
+            <h1 class="text-2xl font-semibold mb-6">New API Consumer</h1>
+            <form method="POST" action={CreateApiConsumerAction} class="space-y-4">
+                {hiddenField #id}
+                <div>
+                    <label class="block text-sm font-medium text-gray-700 mb-1">Name *</label>
+                    {textField #name}
+                </div>
+                <div>
+                    <label class="block text-sm font-medium text-gray-700 mb-1">Description</label>
+                    {textareaField #description}
+                </div>
+                <div>
+                    <label class="block text-sm font-medium text-gray-700 mb-1">Linked Hub Manifest (optional)</label>
+                    <select name="hubCapabilityManifestId" class="border rounded px-3 py-2 text-sm w-full">
+                        <option value="">— none (third-party consumer) —</option>
+                        {forEach manifests manifestOption}
+                    </select>
+                    <p class="text-xs text-gray-400 mt-1">Set for domain hub consumers. Required for hub:*:write scopes.</p>
+                </div>
+                <div class="grid grid-cols-2 gap-4">
+                    <div>
+                        <label class="block text-sm font-medium text-gray-700 mb-1">Rate Limit (req/min)</label>
+                        {numberField #rateLimitPerMinute}
+                    </div>
+                    <div>
+                        <label class="block text-sm font-medium text-gray-700 mb-1">Quota (req/day)</label>
+                        {numberField #quotaPerDay}
+                    </div>
+                </div>
+                <div class="pt-2 flex gap-3">
+                    <button type="submit" class="bg-indigo-600 text-white text-sm font-medium px-4 py-2 rounded hover:bg-indigo-700">
+                        Create Consumer
+                    </button>
+                    <a href={ApiConsumersAction} class="text-sm text-gray-500 px-4 py-2 hover:text-gray-700">Cancel</a>
+                </div>
+            </form>
+        </div>
+    |]
+      where
+        manifestOption m = [hsx|
+            <option value={show m.id}>Manifest {show m.id} ({m.status})</option>
+        |]

Web/View/ApiConsumers/Show.hs

@@ -0,0 +1,161 @@
+module Web.View.ApiConsumers.Show where
+
+import Web.Types
+import Generated.Types
+import IHP.Prelude
+import IHP.ViewPrelude
+
+data ShowView = ShowView
+    { consumer  :: !ApiConsumer
+    , apiKeys   :: ![ApiKey]
+    , webhooks  :: ![WebhookSubscription]
+    , mManifest :: !(Maybe HubCapabilityManifest)
+    }
+
+instance View ShowView where
+    html ShowView { .. } = [hsx|
+        <div class="mb-6">
+            <div class="flex items-start justify-between">
+                <div>
+                    <h1 class="text-2xl font-semibold">{consumer.name}</h1>
+                    {maybeDescription}
+                </div>
+                <div class="flex gap-2">
+                    <a href={EditApiConsumerAction consumer.id}
+                       class="border text-sm px-3 py-1.5 rounded hover:bg-gray-50">Edit</a>
+                    <a href={DeactivateApiConsumerAction consumer.id}
+                       data-method="post" data-confirm="Deactivate this consumer?"
+                       class="border border-red-200 text-red-600 text-sm px-3 py-1.5 rounded hover:bg-red-50">
+                        Deactivate
+                    </a>
+                </div>
+            </div>
+        </div>
+
+        <div class="grid grid-cols-3 gap-4 mb-8">
+            <div class="bg-white border rounded p-4">
+                <div class="text-xs text-gray-500 uppercase tracking-wide mb-1">Status</div>
+                {if consumer.isActive
+                    then [hsx|<span class="bg-green-100 text-green-700 text-sm font-medium px-2 py-0.5 rounded">active</span>|]
+                    else [hsx|<span class="bg-gray-100 text-gray-500 text-sm font-medium px-2 py-0.5 rounded">inactive</span>|]}
+            </div>
+            <div class="bg-white border rounded p-4">
+                <div class="text-xs text-gray-500 uppercase tracking-wide mb-1">Rate Limit</div>
+                <div class="text-sm font-medium">{show consumer.rateLimitPerMinute} req/min</div>
+            </div>
+            <div class="bg-white border rounded p-4">
+                <div class="text-xs text-gray-500 uppercase tracking-wide mb-1">Quota</div>
+                <div class="text-sm font-medium">{show consumer.quotaPerDay} req/day</div>
+            </div>
+        </div>
+
+        {manifestPanel}
+
+        <div class="mb-8">
+            <div class="flex items-center justify-between mb-3">
+                <h2 class="text-lg font-semibold">API Keys</h2>
+                <a href={NewApiKeyAction consumer.id}
+                   class="bg-indigo-600 text-white text-sm px-3 py-1.5 rounded hover:bg-indigo-700">
+                    New Key
+                </a>
+            </div>
+            {if null apiKeys
+                then [hsx|<p class="text-sm text-gray-400">No keys yet.</p>|]
+                else keysTable}
+        </div>
+
+        <div>
+            <div class="flex items-center justify-between mb-3">
+                <h2 class="text-lg font-semibold">Webhook Subscriptions</h2>
+                <a href={NewWebhookSubscriptionAction consumer.id}
+                   class="bg-indigo-600 text-white text-sm px-3 py-1.5 rounded hover:bg-indigo-700">
+                    New Subscription
+                </a>
+            </div>
+            {if null webhooks
+                then [hsx|<p class="text-sm text-gray-400">No webhooks yet.</p>|]
+                else webhooksTable}
+        </div>
+    |]
+      where
+        maybeDescription = case consumer.description of
+            Just d  -> [hsx|<p class="text-sm text-gray-500 mt-1">{d}</p>|]
+            Nothing -> mempty
+        manifestPanel = case mManifest of
+            Nothing -> mempty
+            Just m  -> [hsx|
+                <div class="bg-indigo-50 border border-indigo-100 rounded p-4 mb-6">
+                    <div class="text-xs text-indigo-500 uppercase tracking-wide mb-1">Hub Capability Manifest</div>
+                    <div class="text-sm font-medium">{m.manifestVersion} — <span class="text-indigo-600">{m.status}</span></div>
+                </div>
+            |]
+        keysTable = [hsx|
+            <div class="bg-white border rounded overflow-hidden">
+                <table class="w-full text-sm">
+                    <thead class="bg-gray-50 border-b"><tr>
+                        <th class="text-left px-4 py-2 font-medium text-gray-600">Prefix</th>
+                        <th class="text-left px-4 py-2 font-medium text-gray-600">Type</th>
+                        <th class="text-left px-4 py-2 font-medium text-gray-600">Scopes</th>
+                        <th class="text-left px-4 py-2 font-medium text-gray-600">Expires</th>
+                        <th class="text-left px-4 py-2 font-medium text-gray-600">Status</th>
+                        <th class="px-4 py-2"></th>
+                    </tr></thead>
+                    <tbody class="divide-y divide-gray-100">
+                        {forEach apiKeys renderKey}
+                    </tbody>
+                </table>
+            </div>
+        |]
+        renderKey k = [hsx|
+            <tr>
+                <td class="px-4 py-2 font-mono text-xs">{k.keyPrefix}...</td>
+                <td class="px-4 py-2 text-gray-500">{k.tokenType}</td>
+                <td class="px-4 py-2 text-gray-500">{if k.scopes == "" then "–" else k.scopes}</td>
+                <td class="px-4 py-2 text-gray-500">{maybe "never" show k.expiresAt}</td>
+                <td class="px-4 py-2">
+                    {if isJust k.revokedAt
+                        then [hsx|<span class="text-red-500 text-xs">revoked</span>|]
+                        else [hsx|<span class="text-green-600 text-xs">active</span>|]}
+                </td>
+                <td class="px-4 py-2 text-right">
+                    {if isNothing k.revokedAt
+                        then [hsx|<a href={RevokeApiKeyAction k.id} data-method="post"
+                                      data-confirm="Revoke this key? This cannot be undone."
+                                      class="text-red-500 hover:text-red-700 text-xs">Revoke</a>|]
+                        else mempty}
+                </td>
+            </tr>
+        |]
+        webhooksTable = [hsx|
+            <div class="bg-white border rounded overflow-hidden">
+                <table class="w-full text-sm">
+                    <thead class="bg-gray-50 border-b"><tr>
+                        <th class="text-left px-4 py-2 font-medium text-gray-600">Event Type</th>
+                        <th class="text-left px-4 py-2 font-medium text-gray-600">Target URL</th>
+                        <th class="text-left px-4 py-2 font-medium text-gray-600">Status</th>
+                        <th class="px-4 py-2"></th>
+                    </tr></thead>
+                    <tbody class="divide-y divide-gray-100">
+                        {forEach webhooks renderWebhook}
+                    </tbody>
+                </table>
+            </div>
+        |]
+        renderWebhook wh = [hsx|
+            <tr>
+                <td class="px-4 py-2 font-mono text-xs">{wh.eventType}</td>
+                <td class="px-4 py-2 text-gray-500 text-xs truncate max-w-xs">{wh.targetUrl}</td>
+                <td class="px-4 py-2">
+                    {if wh.isActive
+                        then [hsx|<span class="text-green-600 text-xs">active</span>|]
+                        else [hsx|<span class="text-gray-400 text-xs">paused</span>|]}
+                </td>
+                <td class="px-4 py-2 text-right">
+                    <a href={ToggleWebhookSubscriptionAction wh.id} data-method="post"
+                       class="text-gray-400 hover:text-gray-700 text-xs mr-2">Toggle</a>
+                    <a href={DeleteWebhookSubscriptionAction wh.id} data-method="delete"
+                       data-confirm="Delete this subscription?"
+                       class="text-red-400 hover:text-red-600 text-xs">Delete</a>
+                </td>
+            </tr>
+        |]

Web/View/ApiDashboard/Show.hs

@@ -0,0 +1,75 @@
+module Web.View.ApiDashboard.Show where
+
+import Web.Types
+import Generated.Types
+import IHP.Prelude
+import IHP.ViewPrelude
+import Data.Maybe (fromMaybe)
+
+data ConsumerStats = ConsumerStats
+    { consumer    :: !ApiConsumer
+    , requests24h :: !Int
+    , errorRate   :: !Double    -- fraction 0..1
+    , lastSeen    :: !(Maybe UTCTime)
+    }
+
+data ShowView = ShowView { stats :: ![ConsumerStats] }
+
+instance View ShowView where
+    html ShowView { .. } = [hsx|
+        <div class="flex items-center justify-between mb-6">
+            <div>
+                <h1 class="text-2xl font-semibold">API Usage Dashboard</h1>
+                <p class="text-sm text-gray-500 mt-1">Per-consumer request metrics (last 24 hours)</p>
+            </div>
+            <a href={ApiConsumersAction} class="text-sm text-gray-500 hover:text-gray-700">← Consumers</a>
+        </div>
+        {if null stats
+            then [hsx|<p class="text-sm text-gray-400">No API activity yet.</p>|]
+            else statsTable}
+    |]
+      where
+        statsTable = [hsx|
+            <div class="bg-white rounded-lg border border-gray-200 overflow-hidden">
+                <table class="w-full text-sm">
+                    <thead class="bg-gray-50 border-b">
+                        <tr>
+                            <th class="text-left px-4 py-3 font-medium text-gray-600">Consumer</th>
+                            <th class="text-right px-4 py-3 font-medium text-gray-600">Req (24h)</th>
+                            <th class="text-right px-4 py-3 font-medium text-gray-600">Error Rate</th>
+                            <th class="text-left px-4 py-3 font-medium text-gray-600">Last Seen</th>
+                            <th class="text-left px-4 py-3 font-medium text-gray-600">Manifest</th>
+                        </tr>
+                    </thead>
+                    <tbody class="divide-y divide-gray-100">
+                        {forEach stats renderRow}
+                    </tbody>
+                </table>
+            </div>
+        |]
+        renderRow ConsumerStats { .. } = [hsx|
+            <tr class="hover:bg-gray-50">
+                <td class="px-4 py-3 font-medium">
+                    <a href={ShowApiConsumerAction consumer.id} class="text-indigo-600 hover:underline">
+                        {consumer.name}
+                    </a>
+                </td>
+                <td class="px-4 py-3 text-right">{show requests24h}</td>
+                <td class="px-4 py-3 text-right">
+                    <span class={errorClass errorRate}>
+                        {formatErrorRate errorRate}%
+                    </span>
+                </td>
+                <td class="px-4 py-3 text-gray-500 text-xs">
+                    {maybe "never" show lastSeen}
+                </td>
+                <td class="px-4 py-3 text-gray-500">
+                    {if isJust consumer.hubCapabilityManifestId then "✓" else "–" :: Text}
+                </td>
+            </tr>
+        |]
+        errorClass rate
+            | rate > 0.1 = "text-red-600 font-medium" :: Text
+            | rate > 0.02 = "text-amber-600"
+            | otherwise  = "text-gray-600"
+        formatErrorRate rate = show (round (rate * 100) :: Int)

Web/View/ApiKeys/Created.hs

@@ -0,0 +1,34 @@
+module Web.View.ApiKeys.Created where
+
+import Web.Types
+import Generated.Types
+import IHP.Prelude
+import IHP.ViewPrelude
+
+data CreatedView = CreatedView
+    { consumer :: !ApiConsumer
+    , fullKey  :: !Text      -- one-time display; never stored
+    }
+
+instance View CreatedView where
+    html CreatedView { .. } = [hsx|
+        <div class="max-w-lg">
+            <h1 class="text-2xl font-semibold mb-4">API Key Created</h1>
+            <div class="bg-amber-50 border border-amber-300 rounded p-4 mb-6">
+                <p class="text-sm font-semibold text-amber-800 mb-2">Copy this key now — it will never be shown again.</p>
+                <div class="flex items-center gap-2">
+                    <code class="bg-white border rounded px-3 py-2 text-sm font-mono flex-1 break-all">{fullKey}</code>
+                    <button onclick="navigator.clipboard.writeText(this.previousElementSibling.textContent)"
+                            class="border px-2 py-2 rounded text-xs hover:bg-gray-50">Copy</button>
+                </div>
+            </div>
+            <p class="text-sm text-gray-600 mb-4">
+                Use this key as a Bearer token in the <code>Authorization</code> header:
+            </p>
+            <pre class="bg-gray-900 text-gray-100 rounded p-3 text-xs overflow-x-auto mb-6">Authorization: Bearer {fullKey}</pre>
+            <a href={ShowApiConsumerAction consumer.id}
+               class="bg-indigo-600 text-white text-sm font-medium px-4 py-2 rounded hover:bg-indigo-700">
+                Back to Consumer
+            </a>
+        </div>
+    |]

Web/View/ApiKeys/New.hs

@@ -0,0 +1,34 @@
+module Web.View.ApiKeys.New where
+
+import Web.Types
+import Generated.Types
+import IHP.Prelude
+import IHP.ViewPrelude
+
+data NewView = NewView
+    { apiKey   :: !ApiKey
+    , consumer :: !ApiConsumer
+    }
+
+instance View NewView where
+    html NewView { .. } = [hsx|
+        <div class="max-w-lg">
+            <h1 class="text-2xl font-semibold mb-2">New API Key</h1>
+            <p class="text-sm text-gray-500 mb-6">For consumer: <strong>{consumer.name}</strong></p>
+            <form method="POST" action={CreateApiKeyAction} class="space-y-4">
+                {hiddenField #id}
+                <input type="hidden" name="apiConsumerId" value={show consumer.id} />
+                <div>
+                    <label class="block text-sm font-medium text-gray-700 mb-1">Scopes (space-separated)</label>
+                    {textField #scopes}
+                    <p class="text-xs text-gray-400 mt-1">e.g. framework:read hub:dev-hub:read hub:dev-hub:write</p>
+                </div>
+                <div class="pt-2 flex gap-3">
+                    <button type="submit" class="bg-indigo-600 text-white text-sm font-medium px-4 py-2 rounded hover:bg-indigo-700">
+                        Generate Key
+                    </button>
+                    <a href={ShowApiConsumerAction consumer.id} class="text-sm text-gray-500 px-4 py-2 hover:text-gray-700">Cancel</a>
+                </div>
+            </form>
+        </div>
+    |]

Web/View/WebhookSubscriptions/New.hs

@@ -0,0 +1,52 @@
+module Web.View.WebhookSubscriptions.New where
+
+import Web.Types
+import Generated.Types
+import IHP.Prelude
+import IHP.ViewPrelude
+
+webhookTopics :: [Text]
+webhookTopics =
+    [ "interaction_event.created"
+    , "annotation.created"
+    , "requirement_candidate.created"
+    , "decision_record.created"
+    , "deployment_record.created"
+    , "outcome_signal.created"
+    ]
+
+data NewView = NewView
+    { subscription :: !WebhookSubscription
+    , consumer     :: !ApiConsumer
+    }
+
+instance View NewView where
+    html NewView { .. } = [hsx|
+        <div class="max-w-lg">
+            <h1 class="text-2xl font-semibold mb-2">New Webhook Subscription</h1>
+            <p class="text-sm text-gray-500 mb-6">Consumer: <strong>{consumer.name}</strong></p>
+            <form method="POST" action={CreateWebhookSubscriptionAction} class="space-y-4">
+                {hiddenField #id}
+                <input type="hidden" name="apiConsumerId" value={show consumer.id} />
+                <div>
+                    <label class="block text-sm font-medium text-gray-700 mb-1">Event Topic *</label>
+                    <select name="eventType" class="border rounded px-3 py-2 text-sm w-full">
+                        {forEach webhookTopics topicOption}
+                    </select>
+                </div>
+                <div>
+                    <label class="block text-sm font-medium text-gray-700 mb-1">Target URL *</label>
+                    {textField #targetUrl}
+                    <p class="text-xs text-gray-400 mt-1">Must be HTTPS. IHF will POST JSON payloads with X-IHF-Signature header.</p>
+                </div>
+                <div class="pt-2 flex gap-3">
+                    <button type="submit" class="bg-indigo-600 text-white text-sm font-medium px-4 py-2 rounded hover:bg-indigo-700">
+                        Create Subscription
+                    </button>
+                    <a href={ShowApiConsumerAction consumer.id} class="text-sm text-gray-500 px-4 py-2 hover:text-gray-700">Cancel</a>
+                </div>
+            </form>
+        </div>
+    |]
+      where
+        topicOption t = [hsx|<option value={t}>{t}</option>|]