feat(instance): public profile endpoint GET /api/instance (hub-app M1)

spec.yaml

@@ -2,7 +2,7 @@ openapi: 3.0.3
 info:
   title: Dcntrlized Maestro API
   version: 1.0.0
-  description: The API of the Maestro orchestration router. Maestro manages the lifecycle of Dcntrlized service containers and routes inter-service action calls to them. Every /api/* route except /api/auth/* requires an instance-owner session (cookies issued by the auth endpoints); in setup mode gated routes answer 428 ERR_SETUP_REQUIRED, otherwise 401 ERR_UNAUTHENTICATED. Mutating requests from browser origins are additionally checked against the request host (CSRF).
+  description: The API of the Maestro orchestration router. Maestro manages the lifecycle of Dcntrlized service containers and routes inter-service action calls to them. Every /api/* route except /api/auth/* and the deliberately public GET /api/instance (hub-app theme) requires an instance-owner session (cookies issued by the auth endpoints); in setup mode gated routes answer 428 ERR_SETUP_REQUIRED, otherwise 401 ERR_UNAUTHENTICATED. Mutating requests from browser origins are additionally checked against the request host (CSRF).
 
 components:
   schemas:
@@ -144,6 +144,90 @@ components:
         issued_at:
           type: string
 
+    InstanceIdentity:
+      type: object
+      description: The instance's public self-description (hub-app M1).
+      required: [name]
+      properties:
+        name:
+          type: string
+          example: "home-node"
+        title:
+          type: string
+        description:
+          type: string
+        fingerprint:
+          type: string
+          description: Instance CA public-key SHA256 (lib/pki); omitted when no CA is provisioned.
+          example: "sha256:…"
+
+    PublicService:
+      type: object
+      description: |
+        Deliberately reduced view of a running service — no container id,
+        docker name, private IP, or port mapping leaves the instance (hub-app D3).
+      required: [service_name, status, image]
+      properties:
+        service_name:
+          type: string
+        title:
+          type: string
+        description:
+          type: string
+        status:
+          type: string
+        version:
+          type: string
+        capabilities:
+          type: array
+          items:
+            type: string
+        has_auth:
+          type: boolean
+        image:
+          type: string
+
+    TrustedInstance:
+      type: object
+      description: A remote instance this instance trusts (federation store row).
+      required: [name, url, fingerprint, status]
+      properties:
+        name:
+          type: string
+        url:
+          type: string
+        fingerprint:
+          type: string
+          example: "sha256:…"
+        status:
+          type: string
+          example: "authorized"
+        scopes:
+          type: array
+          items:
+            type: string
+
+    InstancePublicProfile:
+      type: object
+      description: |
+        The unauthenticated GET /api/instance response (hub-app theme). With
+        DCNTRLIZED_PUBLIC_PROFILE=false only `instance` is returned. Absent
+        federation store → trusted_instances:null; present-but-empty → [].
+      required: [instance]
+      properties:
+        instance:
+          $ref: '#/components/schemas/InstanceIdentity'
+        services:
+          type: array
+          nullable: true
+          items:
+            $ref: '#/components/schemas/PublicService'
+        trusted_instances:
+          type: array
+          nullable: true
+          items:
+            $ref: '#/components/schemas/TrustedInstance'
+
     RegistryContainer:
       type: object
       required: [name, image]
@@ -506,6 +590,24 @@ paths:
         '502':
           description: Failed to connect to upstream registry
 
+  /api/instance:
+    get:
+      summary: Public instance profile (unauthenticated)
+      tags: ["instance"]
+      security: []
+      description: >-
+        The one read surface the owner gate deliberately allows through
+        (hub-app theme M1/D2): what this instance is, which non-hidden services
+        it runs (public fields only), and which remote instances it trusts.
+        DCNTRLIZED_PUBLIC_PROFILE=false omits services + trusted_instances.
+      responses:
+        '200':
+          description: The instance public profile
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/InstancePublicProfile'
+
   /api/auth/status:
     get:
       summary: Instance-owner gate state (public)