@rathnasgala2/schemas 3.13.0 → 3.14.1

package/openapi/openapi.yaml

@@ -1441,6 +1441,27 @@ components:
         - GOOGLE
         - DESCRIPTION_CODE
       type: string
+    CreatorClaimProof:
+      additionalProperties: false
+      description: What a claimant must show before accepting. `YOUTUBE_CHANNEL` needs the claimant to prove they control the channel (`channelId`, and `handle` when it is known); `LINK_ONLY` needs nothing beyond the link itself, so anyone who holds a `LINK_ONLY` link and signs in can claim the site.
+      properties:
+        channelId:
+          $ref: "#/components/schemas/YoutubeChannelId"
+        handle:
+          maxLength: 31
+          minLength: 4
+          pattern: ^@[A-Za-z0-9._-]{3,30}$
+          type: string
+        kind:
+          $ref: "#/components/schemas/CreatorClaimProofKind"
+      required:
+        - kind
+      type: object
+    CreatorClaimProofKind:
+      enum:
+        - YOUTUBE_CHANNEL
+        - LINK_ONLY
+      type: string
     CreatorClaimState:
       enum:
         - OPEN
@@ -2146,6 +2167,7 @@ components:
       properties:
         channel:
           additionalProperties: false
+          description: Present only when `proof.kind` is `YOUTUBE_CHANNEL`.
           properties:
             handle:
               maxLength: 31
@@ -2165,19 +2187,22 @@ components:
           pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
           type: string
         methods:
+          description: The ways to prove the channel is the caller's; empty when `proof.kind` is `LINK_ONLY`, which has nothing to prove.
           items:
             $ref: "#/components/schemas/CreatorClaimMethod"
           maxItems: 2
-          minItems: 1
+          minItems: 0
           type: array
           uniqueItems: true
         organizationId:
-          description: Present only when `state` is `CLAIMED` and the caller is the person who claimed it.
+          description: Present only when `state` is `CLAIMED` and the caller is the person who claimed it, or when the caller already owns the site (the owner who issued the link, reading it).
           format: uuid
           pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
           type: string
+        proof:
+          $ref: "#/components/schemas/CreatorClaimProof"
         publicationId:
-          description: Present only when `state` is `CLAIMED` and the caller is the person who claimed it.
+          description: Present only when `state` is `CLAIMED` and the caller is the person who claimed it, or when the caller already owns the site (the owner who issued the link, reading it).
           format: uuid
           pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
           type: string
@@ -2202,7 +2227,6 @@ components:
       required:
         - claimId
         - state
-        - channel
         - site
         - methods
       type: object
@@ -3128,6 +3152,18 @@ components:
         - periodEndsAt
         - editionKinds
       type: object
+    GetOrganizationsByOrganizationIdPublicationsByPublicationIdHandoverClaimsResponse:
+      additionalProperties: false
+      properties:
+        items:
+          description: Newest first, every state; at most the 50 most recent.
+          items:
+            $ref: "#/components/schemas/HandoverClaim"
+          maxItems: 50
+          type: array
+      required:
+        - items
+      type: object
     GetOrganizationsByOrganizationIdPublicationsByPublicationIdHandoverResponse:
       additionalProperties: false
       properties:
@@ -4818,6 +4854,59 @@ components:
         - PRIVATE
         - PUBLIC
       type: string
+    HandoverClaim:
+      additionalProperties: false
+      description: One claim link that hands a site to whoever accepts it. Demo-site claims appear here too, with proof `YOUTUBE_CHANNEL`.
+      properties:
+        claimId:
+          format: uuid
+          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+          type: string
+        claimUrl:
+          description: Present only while `state` is `OPEN`, so the owner can copy the link again; absent in every other state. It is also absent on an `OPEN` claim issued before 3.14.0 whose token the API does not hold sealed, until the owner re-issues the claim with `replace`. The link is a bearer secret, so anyone who holds it can open the claim page.
+          format: uri
+          maxLength: 2048
+          pattern: ^https://[^\s]+$
+          type: string
+        claimedAt:
+          $ref: "#/components/schemas/PortableProblemRfc3339"
+        claimedBy:
+          additionalProperties: false
+          description: Present only when `state` is `CLAIMED`.
+          properties:
+            displayName:
+              maxLength: 200
+              minLength: 1
+              type: string
+            login:
+              description: "GitHub login grammar: letters, digits and single hyphens, not starting or ending with a hyphen. Absent when the claimant has no linked GitHub login."
+              maxLength: 39
+              minLength: 1
+              pattern: ^[A-Za-z0-9](?:-?[A-Za-z0-9]){0,38}$
+              type: string
+          required:
+            - displayName
+          type: object
+        createdAt:
+          $ref: "#/components/schemas/PortableProblemRfc3339"
+        expiresAt:
+          $ref: "#/components/schemas/PortableProblemRfc3339"
+        proof:
+          $ref: "#/components/schemas/CreatorClaimProof"
+        state:
+          $ref: "#/components/schemas/CreatorClaimState"
+        version:
+          format: int64
+          minimum: 0
+          type: integer
+      required:
+        - claimId
+        - state
+        - createdAt
+        - expiresAt
+        - proof
+        - version
+      type: object
     HandoverState:
       enum:
         - NOT_STARTED
@@ -14672,6 +14761,30 @@ components:
         - $ref: "#/components/schemas/DomainBinding"
     PostOrganizationsByOrganizationIdPublicationsByPublicationIdHandoverCancelResponse:
       $ref: "#/components/schemas/GetOrganizationsByOrganizationIdPublicationsByPublicationIdHandoverResponse"
+    PostOrganizationsByOrganizationIdPublicationsByPublicationIdHandoverClaimsByClaimIdRevokeResponse:
+      $ref: "#/components/schemas/HandoverClaim"
+    PostOrganizationsByOrganizationIdPublicationsByPublicationIdHandoverClaimsRequest:
+      additionalProperties: false
+      properties:
+        channelId:
+          $ref: "#/components/schemas/YoutubeChannelId"
+        expiresInDays:
+          default: 30
+          description: Days until the link expires; at most 365.
+          maximum: 365
+          minimum: 1
+          type: integer
+        proof:
+          $ref: "#/components/schemas/CreatorClaimProofKind"
+        replace:
+          default: false
+          description: Set to revoke the site's OPEN claim and issue this one in its place. Without it, an OPEN claim answers `409 INVALID_SOURCE_STATE`.
+          type: boolean
+      required:
+        - proof
+      type: object
+    PostOrganizationsByOrganizationIdPublicationsByPublicationIdHandoverClaimsResponse:
+      $ref: "#/components/schemas/HandoverClaim"
     PostOrganizationsByOrganizationIdPublicationsByPublicationIdHandoverRequest:
       additionalProperties: false
       properties:
@@ -15645,7 +15758,7 @@ components:
       additionalProperties: false
       properties:
         claimUrl:
-          description: "Present only in the response that issued the claim link, or re-issued it while the claim is still OPEN. Save it then: it is never shown again."
+          description: Present only in the response that issued the claim link, or re-issued it while the claim is still OPEN. While the claim is OPEN the site owner can read the link again from `GET .../handover-claims`; once it is VERIFIED or CLAIMED it is gone.
           format: uri
           maxLength: 2048
           pattern: ^https://[^\s]+$
@@ -20006,7 +20119,7 @@ paths:
   /v2/claims/{token}:
     get:
       description: |
-        Needs a signed-in session; signed out is `401 AUTHENTICATION_REQUIRED` and reveals nothing. Returns the channel and site the link offers and the ways to prove the channel is the caller's. `404 CLAIM_NOT_FOUND` for an unknown or revoked link, `410 CLAIM_EXPIRED` once the demo is past its archive date. Rate limited per caller (`429 RATE_LIMITED`).
+        Needs a signed-in session; signed out is `401 AUTHENTICATION_REQUIRED` and reveals nothing. Returns the site the link offers, what the claimant must show (`proof`) and the ways to show it. For `proof.kind` `YOUTUBE_CHANNEL` the response carries the `channel` and the `methods` that prove it is the caller's. For `LINK_ONLY` there is no channel and `methods` is empty: the caller goes straight to `POST /v2/claims/{token}:accept` after signing in. A response without `proof` is a `YOUTUBE_CHANNEL` claim. `organizationId` and `publicationId` are also returned to the person who issued the link (the site owner reading their own link), who owns the site; accepting it is refused with `409 INVALID_SOURCE_STATE`. `404 CLAIM_NOT_FOUND` for an unknown or revoked link, `410 CLAIM_EXPIRED` once the claim is past its expiry (a demo site's archive date, or the `expiresAt` the site owner chose). Rate limited per caller (`429 RATE_LIMITED`).
       operationId: getClaimsByToken
       parameters:
         - $ref: "#/components/parameters/XCorrelationId"
@@ -20035,6 +20148,10 @@ paths:
                     methods:
                       - GOOGLE
                       - DESCRIPTION_CODE
+                    proof:
+                      channelId: UCabcdefghijklmnopqrstuv
+                      handle: "@mayacooks"
+                      kind: YOUTUBE_CHANNEL
                     site:
                       name: Maya Cooks
                       url: https://rathnasdemo.github.io/maya-cooks/
@@ -20242,7 +20359,7 @@ paths:
   /v2/claims/{token}/description-code:
     post:
       description: |
-        Needs a signed-in session. Issues a one-time code to put in the YouTube channel description, valid 24 hours; a new request replaces an unexpired code issued to the same person. `404 CLAIM_NOT_FOUND`, `410 CLAIM_EXPIRED`, `409 CLAIM_ALREADY_CLAIMED`, and `409 CLAIM_CODE_PENDING` when a description code issued to another person for this claim is still pending: it expires at the time in the problem detail, so verify with Google instead, or try again after it expires. Rate limited (`429 RATE_LIMITED`).
+        Needs a signed-in session. Issues a one-time code to put in the YouTube channel description, valid 24 hours; a new request replaces an unexpired code issued to the same person. `404 CLAIM_NOT_FOUND`, `410 CLAIM_EXPIRED`, `409 CLAIM_ALREADY_CLAIMED`, and `409 CLAIM_CODE_PENDING` when a description code issued to another person for this claim is still pending: it expires at the time in the problem detail, so verify with Google instead, or try again after it expires. A `LINK_ONLY` claim has no channel to prove, so this answers `400 VALIDATION_FAILED` for one. Rate limited (`429 RATE_LIMITED`). The first person to complete acceptance owns the site. Until a claim is `CLAIMED`, anyone who proves the channel may verify it, and a later proof replaces an earlier one.
       operationId: postClaimsByTokenDescriptionCode
       parameters:
         - $ref: "#/components/parameters/XCorrelationId"
@@ -20513,7 +20630,7 @@ paths:
   /v2/claims/{token}/description-code:check:
     post:
       description: |
-        Needs a signed-in session. Reads the channel description through the YouTube Data API and, when it contains the issued code, marks the claim verified for this person and spends the code. A code that is not there yet is `200` with `verified: false` and a `reason`, not a problem. `503 DEPENDENCY_UNAVAILABLE` when YouTube cannot be reached. Rate limited (`429 RATE_LIMITED`).
+        Needs a signed-in session. Reads the channel description through the YouTube Data API and, when it contains the issued code, marks the claim verified for this person and spends the code. A code that is not there yet is `200` with `verified: false` and a `reason`, not a problem. `503 DEPENDENCY_UNAVAILABLE` when YouTube cannot be reached. A `LINK_ONLY` claim has no channel to prove, so this answers `400 VALIDATION_FAILED` for one. Rate limited (`429 RATE_LIMITED`). The first person to complete acceptance owns the site. Until a claim is `CLAIMED`, anyone who proves the channel may verify it, and a later proof replaces an earlier one.
       operationId: postClaimsByTokenDescriptionCodeCheck
       parameters:
         - $ref: "#/components/parameters/XCorrelationId"
@@ -20797,7 +20914,7 @@ paths:
   /v2/claims/{token}/google:start:
     post:
       description: |
-        Needs a signed-in session. Returns the Google authorize URL for one single-use, PKCE-protected transaction bound to this session; the callback is `GET /v2/callbacks/google/claim`. `404 CLAIM_NOT_FOUND`, `410 CLAIM_EXPIRED`, `409 CLAIM_ALREADY_CLAIMED` when the site was taken. Rate limited (`429 RATE_LIMITED`).
+        Needs a signed-in session. Returns the Google authorize URL for one single-use, PKCE-protected transaction bound to this session; the callback is `GET /v2/callbacks/google/claim`. `404 CLAIM_NOT_FOUND`, `410 CLAIM_EXPIRED`, `409 CLAIM_ALREADY_CLAIMED` when the site was taken. A `LINK_ONLY` claim has no channel to prove, so this answers `400 VALIDATION_FAILED` for one. Rate limited (`429 RATE_LIMITED`). The first person to complete acceptance owns the site. Until a claim is `CLAIMED`, anyone who proves the channel may verify it, and a later proof replaces an earlier one.
       operationId: postClaimsByTokenGoogleStart
       parameters:
         - $ref: "#/components/parameters/XCorrelationId"
@@ -21052,7 +21169,7 @@ paths:
   /v2/claims/{token}:accept:
     post:
       description: |
-        Needs recent authentication. Requires the claim to be verified by this same person (`409 CLAIM_NOT_VERIFIED` otherwise), then makes the caller the owner of the demo organisation. Repeating the call after success returns the same organisation. `409 CLAIM_ALREADY_CLAIMED` when another person claimed it; `410 CLAIM_EXPIRED`. An API key is always refused.
+        Needs recent authentication. For a `YOUTUBE_CHANNEL` claim it requires the claim to be verified by this same person (`409 CLAIM_NOT_VERIFIED` otherwise); a `LINK_ONLY` claim has nothing to verify and is accepted from `OPEN`. Then it makes the caller the owner of the site's organisation, which hands the site over. Repeating the call after success returns the same organisation. `409 INVALID_SOURCE_STATE` when the caller is the person who issued the claim or already owns the site: nobody can claim their own site. `409 CLAIM_ALREADY_CLAIMED` when another person claimed it; `410 CLAIM_EXPIRED`. An API key is always refused. The first person to complete acceptance owns the site. Until a claim is `CLAIMED`, anyone who proves the channel may verify it, and a later proof replaces an earlier one.
       operationId: postClaimsByTokenAccept
       parameters:
         - $ref: "#/components/parameters/XCorrelationId"
@@ -21237,9 +21354,22 @@ paths:
                     status: 409
                     title: CLAIM_NOT_VERIFIED
                     type: urn:gala:problem:claim-not-verified
+                INVALID_SOURCE_STATE:
+                  summary: INVALID_SOURCE_STATE
+                  value:
+                    code: INVALID_SOURCE_STATE
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 409
+                    title: INVALID_SOURCE_STATE
+                    type: urn:gala:problem:invalid-source-state
               schema:
                 $ref: "#/components/schemas/Problem"
-          description: CLAIM_ALREADY_CLAIMED, CLAIM_NOT_VERIFIED
+          description: CLAIM_ALREADY_CLAIMED, CLAIM_NOT_VERIFIED, INVALID_SOURCE_STATE
           headers:
             Cache-Control:
               $ref: "#/components/headers/CacheControlNoStore"
@@ -21248,6 +21378,7 @@ paths:
           x-gala-problem-codes:
             - CLAIM_ALREADY_CLAIMED
             - CLAIM_NOT_VERIFIED
+            - INVALID_SOURCE_STATE
         "410":
           content:
             application/problem+json:
@@ -21327,12 +21458,14 @@ paths:
         - CLAIM_EXPIRED
         - CLAIM_NOT_FOUND
         - CLAIM_NOT_VERIFIED
+        - INVALID_SOURCE_STATE
         - RATE_LIMITED
         - REAUTH_REQUIRED
         - VALIDATION_FAILED
       x-gala-replay-identity: natural-idempotent-state
       x-gala-state-guards:
-        - NONE
+        - CreatorClaim:OPEN -> CLAIMED
+        - CreatorClaim:VERIFIED -> CLAIMED
       x-gala-success-category: protocol
       x-gala-tenant-scope: NONE
   /v2/github/app:
@@ -38402,21 +38535,747 @@ paths:
             - RESOURCE_NOT_FOUND
       security:
         - browserSession: []
-      summary: read the Prism generation policy
+      summary: read the Prism generation policy
+      tags:
+        - prism
+      x-gala-activation-gate: MVP
+      x-gala-activation-guards:
+        - NONE
+      x-gala-capability-key: publication.source.write
+      x-gala-concurrency: authorization-and-publication-epochs
+      x-gala-conditional-capabilities: []
+      x-gala-example-profile: NOMINAL_SUCCESS_AND_EACH_REACHABLE_PROBLEM
+      x-gala-nullability: required-and-nullable-are-explicit
+      x-gala-purpose: read the Prism generation policy
+      x-gala-reachable-problems:
+        - AUTHENTICATION_REQUIRED
+        - AUTHORIZATION_DENIED
+        - RESOURCE_NOT_FOUND
+        - VALIDATION_FAILED
+      x-gala-replay-identity: safe-query
+      x-gala-state-guards:
+        - NONE
+      x-gala-success-category: query
+      x-gala-tenant-scope: ORGANIZATION_AND_PUBLICATION_PATH
+  /v2/organizations/{organizationId}/publications/{publicationId}/handover:
+    get:
+      description: |
+        The organisation owner, signed in (a read needs no fresh sign-in); an API key is always refused. Reports the handover of a demo site into the creator's own GitHub account: its state, the target, whether the Galascribe App is installed on the target, each step and the address the site will have. `200` with `state: NOT_STARTED` (empty `steps`, `version` 0, no `target`, `appInstalledOnTarget` or `siteUrlAfter`) for a demo publication (one with a demo-site record) that has no handover yet; `200` with the latest handover otherwise, including `DONE`, `FAILED` and `CANCELLED`; `404 RESOURCE_NOT_FOUND` only for a publication that is not a demo publication.
+      operationId: getOrganizationsByOrganizationIdPublicationsByPublicationIdHandover
+      parameters:
+        - $ref: "#/components/parameters/XCorrelationId"
+        - example: 018f0000-0000-7000-8000-000000000001
+          in: path
+          name: organizationId
+          required: true
+          schema:
+            format: uuid
+            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+            type: string
+        - example: 018f0000-0000-7000-8000-000000000001
+          in: path
+          name: publicationId
+          required: true
+          schema:
+            format: uuid
+            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+            type: string
+      responses:
+        "200":
+          content:
+            application/json:
+              examples:
+                nominal:
+                  summary: Nominal successful response
+                  value:
+                    appInstalledOnTarget: true
+                    siteUrlAfter: https://creator-org.github.io/maya-cooks/
+                    state: TRANSFER_STARTED
+                    steps:
+                      - name: FINALIZE_CHANGE
+                        state: DONE
+                      - name: TRANSFER
+                        state: RUNNING
+                      - name: RELINK
+                        state: PENDING
+                      - name: PAGES
+                        state: PENDING
+                      - name: PUBLISH
+                        state: PENDING
+                    target:
+                      kind: ORGANIZATION
+                      ownerLogin: creator-org
+                    version: 1
+                notStarted:
+                  summary: Demo publication with no handover yet
+                  value:
+                    state: NOT_STARTED
+                    steps: []
+                    version: 0
+              schema:
+                $ref: "#/components/schemas/GetOrganizationsByOrganizationIdPublicationsByPublicationIdHandoverResponse"
+          description: read publication handover succeeded
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+        "400":
+          content:
+            application/problem+json:
+              examples:
+                VALIDATION_FAILED:
+                  summary: VALIDATION_FAILED
+                  value:
+                    code: VALIDATION_FAILED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 400
+                    title: VALIDATION_FAILED
+                    type: urn:gala:problem:validation-failed
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: VALIDATION_FAILED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - VALIDATION_FAILED
+        "401":
+          content:
+            application/problem+json:
+              examples:
+                AUTHENTICATION_REQUIRED:
+                  summary: AUTHENTICATION_REQUIRED
+                  value:
+                    code: AUTHENTICATION_REQUIRED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 401
+                    title: AUTHENTICATION_REQUIRED
+                    type: urn:gala:problem:authentication-required
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: AUTHENTICATION_REQUIRED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - AUTHENTICATION_REQUIRED
+        "403":
+          content:
+            application/problem+json:
+              examples:
+                AUTHORIZATION_DENIED:
+                  summary: AUTHORIZATION_DENIED
+                  value:
+                    code: AUTHORIZATION_DENIED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 403
+                    title: AUTHORIZATION_DENIED
+                    type: urn:gala:problem:authorization-denied
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: AUTHORIZATION_DENIED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - AUTHORIZATION_DENIED
+        "404":
+          content:
+            application/problem+json:
+              examples:
+                RESOURCE_NOT_FOUND:
+                  summary: RESOURCE_NOT_FOUND
+                  value:
+                    code: RESOURCE_NOT_FOUND
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 404
+                    title: RESOURCE_NOT_FOUND
+                    type: urn:gala:problem:resource-not-found
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: RESOURCE_NOT_FOUND
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - RESOURCE_NOT_FOUND
+      security:
+        - browserSession: []
+      summary: read publication handover
+      tags:
+        - organizations
+      x-gala-action-grant: none
+      x-gala-activation-gate: MVP
+      x-gala-activation-guards:
+        - NONE
+      x-gala-assurance-class: SESSION
+      x-gala-capability-key: publication.handover.view
+      x-gala-concurrency: none
+      x-gala-conditional-capabilities: []
+      x-gala-example-profile: NOMINAL_SUCCESS_AND_EACH_REACHABLE_PROBLEM
+      x-gala-nullability: required-and-nullable-are-explicit
+      x-gala-purpose: read publication handover
+      x-gala-reachable-problems:
+        - AUTHENTICATION_REQUIRED
+        - AUTHORIZATION_DENIED
+        - RESOURCE_NOT_FOUND
+        - VALIDATION_FAILED
+      x-gala-replay-identity: safe-query
+      x-gala-state-guards:
+        - NONE
+      x-gala-success-category: query
+      x-gala-tenant-scope: ORGANIZATION_AND_PUBLICATION_PATH
+    post:
+      description: |
+        The organisation owner, with recent authentication; an API key is always refused. Moves a demo site's repository into `targetOwnerLogin` (a person or an organisation where the Galascribe App is installed): plans and confirms the finalize change in the caller's session, then starts the GitHub transfer. `202` accepts; `GET` reports progress. `409 HANDOVER_EXISTS` while one is live, `409 HANDOVER_TARGET_NOT_INSTALLED` when the App is not installed on the target, `503 DEPENDENCY_UNAVAILABLE` when GitHub cannot be reached. `404 RESOURCE_NOT_FOUND` when the publication is not a demo site. The response never carries `state: NOT_STARTED`.
+      operationId: postOrganizationsByOrganizationIdPublicationsByPublicationIdHandover
+      parameters:
+        - $ref: "#/components/parameters/XCorrelationId"
+        - example: 018f0000-0000-7000-8000-000000000001
+          in: path
+          name: organizationId
+          required: true
+          schema:
+            format: uuid
+            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+            type: string
+        - example: 018f0000-0000-7000-8000-000000000001
+          in: path
+          name: publicationId
+          required: true
+          schema:
+            format: uuid
+            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+            type: string
+        - $ref: "#/components/parameters/IdempotencyKey"
+        - $ref: "#/components/parameters/XCsrfToken"
+      requestBody:
+        content:
+          application/json:
+            examples:
+              nominal:
+                summary: Nominal valid request
+                value:
+                  targetOwnerLogin: creator-org
+            schema:
+              $ref: "#/components/schemas/PostOrganizationsByOrganizationIdPublicationsByPublicationIdHandoverRequest"
+        required: true
+      responses:
+        "202":
+          content:
+            application/json:
+              examples:
+                nominal:
+                  summary: Nominal successful response
+                  value:
+                    appInstalledOnTarget: true
+                    siteUrlAfter: https://creator-org.github.io/maya-cooks/
+                    state: REQUESTED
+                    steps:
+                      - name: FINALIZE_CHANGE
+                        state: DONE
+                      - name: TRANSFER
+                        state: RUNNING
+                      - name: RELINK
+                        state: PENDING
+                      - name: PAGES
+                        state: PENDING
+                      - name: PUBLISH
+                        state: PENDING
+                    target:
+                      kind: ORGANIZATION
+                      ownerLogin: creator-org
+                    version: 1
+              schema:
+                $ref: "#/components/schemas/PostOrganizationsByOrganizationIdPublicationsByPublicationIdHandoverResponse"
+          description: start publication handover succeeded
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+        "400":
+          content:
+            application/problem+json:
+              examples:
+                REQUEST_FIELD_UNKNOWN:
+                  summary: REQUEST_FIELD_UNKNOWN
+                  value:
+                    code: REQUEST_FIELD_UNKNOWN
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 400
+                    title: REQUEST_FIELD_UNKNOWN
+                    type: urn:gala:problem:request-field-unknown
+                VALIDATION_FAILED:
+                  summary: VALIDATION_FAILED
+                  value:
+                    code: VALIDATION_FAILED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 400
+                    title: VALIDATION_FAILED
+                    type: urn:gala:problem:validation-failed
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: REQUEST_FIELD_UNKNOWN, VALIDATION_FAILED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - REQUEST_FIELD_UNKNOWN
+            - VALIDATION_FAILED
+        "401":
+          content:
+            application/problem+json:
+              examples:
+                AUTHENTICATION_REQUIRED:
+                  summary: AUTHENTICATION_REQUIRED
+                  value:
+                    code: AUTHENTICATION_REQUIRED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 401
+                    title: AUTHENTICATION_REQUIRED
+                    type: urn:gala:problem:authentication-required
+                REAUTH_REQUIRED:
+                  summary: REAUTH_REQUIRED
+                  value:
+                    code: REAUTH_REQUIRED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 401
+                    title: REAUTH_REQUIRED
+                    type: urn:gala:problem:reauth-required
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: AUTHENTICATION_REQUIRED, REAUTH_REQUIRED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - AUTHENTICATION_REQUIRED
+            - REAUTH_REQUIRED
+        "403":
+          content:
+            application/problem+json:
+              examples:
+                AUTHORIZATION_DENIED:
+                  summary: AUTHORIZATION_DENIED
+                  value:
+                    code: AUTHORIZATION_DENIED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 403
+                    title: AUTHORIZATION_DENIED
+                    type: urn:gala:problem:authorization-denied
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: AUTHORIZATION_DENIED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - AUTHORIZATION_DENIED
+        "404":
+          content:
+            application/problem+json:
+              examples:
+                RESOURCE_NOT_FOUND:
+                  summary: RESOURCE_NOT_FOUND
+                  value:
+                    code: RESOURCE_NOT_FOUND
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 404
+                    title: RESOURCE_NOT_FOUND
+                    type: urn:gala:problem:resource-not-found
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: RESOURCE_NOT_FOUND
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - RESOURCE_NOT_FOUND
+        "409":
+          content:
+            application/problem+json:
+              examples:
+                COMMAND_REPLAY_CONFLICT:
+                  summary: COMMAND_REPLAY_CONFLICT
+                  value:
+                    code: COMMAND_REPLAY_CONFLICT
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 409
+                    title: COMMAND_REPLAY_CONFLICT
+                    type: urn:gala:problem:command-replay-conflict
+                HANDOVER_EXISTS:
+                  summary: HANDOVER_EXISTS
+                  value:
+                    code: HANDOVER_EXISTS
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 409
+                    title: HANDOVER_EXISTS
+                    type: urn:gala:problem:handover-exists
+                HANDOVER_TARGET_NOT_INSTALLED:
+                  summary: HANDOVER_TARGET_NOT_INSTALLED
+                  value:
+                    code: HANDOVER_TARGET_NOT_INSTALLED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 409
+                    title: HANDOVER_TARGET_NOT_INSTALLED
+                    type: urn:gala:problem:handover-target-not-installed
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: COMMAND_REPLAY_CONFLICT, HANDOVER_EXISTS, HANDOVER_TARGET_NOT_INSTALLED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - COMMAND_REPLAY_CONFLICT
+            - HANDOVER_EXISTS
+            - HANDOVER_TARGET_NOT_INSTALLED
+        "503":
+          content:
+            application/problem+json:
+              examples:
+                DEPENDENCY_UNAVAILABLE:
+                  summary: DEPENDENCY_UNAVAILABLE
+                  value:
+                    code: DEPENDENCY_UNAVAILABLE
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: true
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 503
+                    title: DEPENDENCY_UNAVAILABLE
+                    type: urn:gala:problem:dependency-unavailable
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: DEPENDENCY_UNAVAILABLE
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - DEPENDENCY_UNAVAILABLE
+      security:
+        - browserSession: []
+      summary: start publication handover
+      tags:
+        - organizations
+      x-gala-action-grant: none
+      x-gala-activation-gate: MVP
+      x-gala-activation-guards:
+        - NONE
+      x-gala-assurance-class: RECENT_AUTHENTICATION
+      x-gala-capability-key: publication.handover.manage
+      x-gala-concurrency: none
+      x-gala-conditional-capabilities: []
+      x-gala-example-profile: NOMINAL_SUCCESS_AND_EACH_REACHABLE_PROBLEM
+      x-gala-nullability: required-and-nullable-are-explicit
+      x-gala-purpose: start publication handover
+      x-gala-reachable-problems:
+        - AUTHENTICATION_REQUIRED
+        - AUTHORIZATION_DENIED
+        - COMMAND_REPLAY_CONFLICT
+        - DEPENDENCY_UNAVAILABLE
+        - HANDOVER_EXISTS
+        - HANDOVER_TARGET_NOT_INSTALLED
+        - REAUTH_REQUIRED
+        - REQUEST_FIELD_UNKNOWN
+        - RESOURCE_NOT_FOUND
+        - VALIDATION_FAILED
+      x-gala-replay-identity: idempotency-key
+      x-gala-state-guards:
+        - NONE
+      x-gala-success-category: async
+      x-gala-tenant-scope: ORGANIZATION_AND_PUBLICATION_PATH
+  /v2/organizations/{organizationId}/publications/{publicationId}/handover-claims:
+    get:
+      description: |
+        The organisation owner, with recent authentication; an API key is always refused. Lists the claim links that hand this site to whoever accepts them, newest first and in every state (`OPEN`, `VERIFIED`, `CLAIMED`, `EXPIRED`, `REVOKED`), at most the 50 most recent. `claimUrl` is present only on an `OPEN` claim whose token the API holds sealed, so the owner can copy it again; it is a bearer secret and is never returned for any other state. A claim issued before 3.14.0 may have no `claimUrl` until the owner re-issues it with `replace`. `claimedBy` is present only on a `CLAIMED` claim. A claim past `expiresAt` reads `EXPIRED`. Demo sites are owned by the operator's organisation until claimed, so the operator finds a demo site's claim link here, in that site's Settings. `404 RESOURCE_NOT_FOUND` for a publication that is not in the organisation.
+      operationId: getOrganizationsByOrganizationIdPublicationsByPublicationIdHandoverClaims
+      parameters:
+        - $ref: "#/components/parameters/XCorrelationId"
+        - example: 018f0000-0000-7000-8000-000000000001
+          in: path
+          name: organizationId
+          required: true
+          schema:
+            format: uuid
+            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+            type: string
+        - example: 018f0000-0000-7000-8000-000000000001
+          in: path
+          name: publicationId
+          required: true
+          schema:
+            format: uuid
+            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+            type: string
+      responses:
+        "200":
+          content:
+            application/json:
+              examples:
+                nominal:
+                  summary: Nominal successful response
+                  value:
+                    items:
+                      - claimId: 018f0000-0000-7000-8000-000000000001
+                        claimUrl: https://app.galascribe.com/claim/abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQ
+                        createdAt: "2026-10-17T12:00:00.000Z"
+                        expiresAt: "2026-11-16T12:00:00.000Z"
+                        proof:
+                          kind: LINK_ONLY
+                        state: OPEN
+                        version: 0
+                      - claimId: 018f0000-0000-7000-8000-000000000002
+                        claimedAt: "2026-10-20T09:30:00.000Z"
+                        claimedBy:
+                          displayName: Maya Cooks
+                          login: mayacooks
+                        createdAt: "2026-10-15T12:00:00.000Z"
+                        expiresAt: "2026-11-14T12:00:00.000Z"
+                        proof:
+                          channelId: UCabcdefghijklmnopqrstuv
+                          handle: "@mayacooks"
+                          kind: YOUTUBE_CHANNEL
+                        state: CLAIMED
+                        version: 2
+              schema:
+                $ref: "#/components/schemas/GetOrganizationsByOrganizationIdPublicationsByPublicationIdHandoverClaimsResponse"
+          description: list site handover claims succeeded
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+        "400":
+          content:
+            application/problem+json:
+              examples:
+                VALIDATION_FAILED:
+                  summary: VALIDATION_FAILED
+                  value:
+                    code: VALIDATION_FAILED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 400
+                    title: VALIDATION_FAILED
+                    type: urn:gala:problem:validation-failed
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: VALIDATION_FAILED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - VALIDATION_FAILED
+        "401":
+          content:
+            application/problem+json:
+              examples:
+                AUTHENTICATION_REQUIRED:
+                  summary: AUTHENTICATION_REQUIRED
+                  value:
+                    code: AUTHENTICATION_REQUIRED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 401
+                    title: AUTHENTICATION_REQUIRED
+                    type: urn:gala:problem:authentication-required
+                REAUTH_REQUIRED:
+                  summary: REAUTH_REQUIRED
+                  value:
+                    code: REAUTH_REQUIRED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 401
+                    title: REAUTH_REQUIRED
+                    type: urn:gala:problem:reauth-required
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: AUTHENTICATION_REQUIRED, REAUTH_REQUIRED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - AUTHENTICATION_REQUIRED
+            - REAUTH_REQUIRED
+        "403":
+          content:
+            application/problem+json:
+              examples:
+                AUTHORIZATION_DENIED:
+                  summary: AUTHORIZATION_DENIED
+                  value:
+                    code: AUTHORIZATION_DENIED
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 403
+                    title: AUTHORIZATION_DENIED
+                    type: urn:gala:problem:authorization-denied
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: AUTHORIZATION_DENIED
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - AUTHORIZATION_DENIED
+        "404":
+          content:
+            application/problem+json:
+              examples:
+                RESOURCE_NOT_FOUND:
+                  summary: RESOURCE_NOT_FOUND
+                  value:
+                    code: RESOURCE_NOT_FOUND
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 404
+                    title: RESOURCE_NOT_FOUND
+                    type: urn:gala:problem:resource-not-found
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: RESOURCE_NOT_FOUND
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - RESOURCE_NOT_FOUND
+      security:
+        - browserSession: []
+      summary: list site handover claims
       tags:
-        - prism
+        - organizations
+      x-gala-action-grant: none
       x-gala-activation-gate: MVP
       x-gala-activation-guards:
         - NONE
-      x-gala-capability-key: publication.source.write
-      x-gala-concurrency: authorization-and-publication-epochs
+      x-gala-assurance-class: RECENT_AUTHENTICATION
+      x-gala-capability-key: publication.handover.manage
+      x-gala-concurrency: none
       x-gala-conditional-capabilities: []
       x-gala-example-profile: NOMINAL_SUCCESS_AND_EACH_REACHABLE_PROBLEM
       x-gala-nullability: required-and-nullable-are-explicit
-      x-gala-purpose: read the Prism generation policy
+      x-gala-purpose: list site handover claims
       x-gala-reachable-problems:
         - AUTHENTICATION_REQUIRED
         - AUTHORIZATION_DENIED
+        - REAUTH_REQUIRED
         - RESOURCE_NOT_FOUND
         - VALIDATION_FAILED
       x-gala-replay-identity: safe-query
@@ -38424,11 +39283,10 @@ paths:
         - NONE
       x-gala-success-category: query
       x-gala-tenant-scope: ORGANIZATION_AND_PUBLICATION_PATH
-  /v2/organizations/{organizationId}/publications/{publicationId}/handover:
-    get:
+    post:
       description: |
-        The organisation owner, with recent authentication; an API key is always refused. Reports the handover of a demo site into the creator's own GitHub account: its state, the target, whether the Galascribe App is installed on the target, each step and the address the site will have. `200` with `state: NOT_STARTED` (empty `steps`, `version` 0, no `target`, `appInstalledOnTarget` or `siteUrlAfter`) for a demo publication (one with a demo-site record) that has no handover yet; `200` with the latest handover otherwise, including `DONE`, `FAILED` and `CANCELLED`; `404 RESOURCE_NOT_FOUND` only for a publication that is not a demo publication.
-      operationId: getOrganizationsByOrganizationIdPublicationsByPublicationIdHandover
+        The organisation owner, with recent authentication; an API key is always refused. Issues a claim link that hands this site to whoever signs in and accepts it, and returns the claim with its `claimUrl`. `proof` is `LINK_ONLY` (anyone who holds the link and signs in can claim the site, so share it only with the person you mean; it expires and can be revoked) or `YOUTUBE_CHANNEL` (the claimant must also prove they control the channel in `channelId`, which is required for that proof and refused with `LINK_ONLY`: `400 VALIDATION_FAILED`). `expiresInDays` defaults to 30 and is at most 365. A site holds one `OPEN` claim at a time: while one exists the call answers `409 INVALID_SOURCE_STATE` unless `replace` is `true`, which revokes the `OPEN` claim and issues this one in the same transaction, so the old link stops working. A `VERIFIED` claim is never replaced (`409 INVALID_SOURCE_STATE`); revoke it first. A `CLAIMED` claim never blocks a new one, because ownership can chain. `409 INVALID_SOURCE_STATE` also for a site whose organisation is not a single-person organisation, since only a single-person organisation can be handed over. `409 HANDOVER_EXISTS` while a repository move (`/handover`) is live. `404 RESOURCE_NOT_FOUND` for a publication that is not in the organisation. `Idempotency-Key` is the issue identity: repeating it returns the same claim and `claimUrl`.
+      operationId: postOrganizationsByOrganizationIdPublicationsByPublicationIdHandoverClaims
       parameters:
         - $ref: "#/components/parameters/XCorrelationId"
         - example: 018f0000-0000-7000-8000-000000000001
@@ -38447,50 +39305,68 @@ paths:
             format: uuid
             pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
             type: string
+        - $ref: "#/components/parameters/IdempotencyKey"
+        - $ref: "#/components/parameters/XCsrfToken"
+      requestBody:
+        content:
+          application/json:
+            examples:
+              nominal:
+                summary: Nominal valid request
+                value:
+                  expiresInDays: 30
+                  proof: LINK_ONLY
+              youtubeChannel:
+                summary: Proof that the claimant controls a YouTube channel
+                value:
+                  channelId: UCabcdefghijklmnopqrstuv
+                  proof: YOUTUBE_CHANNEL
+            schema:
+              $ref: "#/components/schemas/PostOrganizationsByOrganizationIdPublicationsByPublicationIdHandoverClaimsRequest"
+        required: true
       responses:
-        "200":
+        "201":
           content:
             application/json:
               examples:
                 nominal:
                   summary: Nominal successful response
                   value:
-                    appInstalledOnTarget: true
-                    siteUrlAfter: https://creator-org.github.io/maya-cooks/
-                    state: TRANSFER_STARTED
-                    steps:
-                      - name: FINALIZE_CHANGE
-                        state: DONE
-                      - name: TRANSFER
-                        state: RUNNING
-                      - name: RELINK
-                        state: PENDING
-                      - name: PAGES
-                        state: PENDING
-                      - name: PUBLISH
-                        state: PENDING
-                    target:
-                      kind: ORGANIZATION
-                      ownerLogin: creator-org
-                    version: 1
-                notStarted:
-                  summary: Demo publication with no handover yet
-                  value:
-                    state: NOT_STARTED
-                    steps: []
+                    claimId: 018f0000-0000-7000-8000-000000000001
+                    claimUrl: https://app.galascribe.com/claim/abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQ
+                    createdAt: "2026-10-17T12:00:00.000Z"
+                    expiresAt: "2026-11-16T12:00:00.000Z"
+                    proof:
+                      kind: LINK_ONLY
+                    state: OPEN
                     version: 0
               schema:
-                $ref: "#/components/schemas/GetOrganizationsByOrganizationIdPublicationsByPublicationIdHandoverResponse"
-          description: read publication handover succeeded
+                $ref: "#/components/schemas/PostOrganizationsByOrganizationIdPublicationsByPublicationIdHandoverClaimsResponse"
+          description: issue site handover claim succeeded
           headers:
             Cache-Control:
               $ref: "#/components/headers/CacheControlNoStore"
+            Location:
+              $ref: "#/components/headers/Location"
             X-Correlation-Id:
               $ref: "#/components/headers/XCorrelationId"
         "400":
           content:
             application/problem+json:
               examples:
+                REQUEST_FIELD_UNKNOWN:
+                  summary: REQUEST_FIELD_UNKNOWN
+                  value:
+                    code: REQUEST_FIELD_UNKNOWN
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 400
+                    title: REQUEST_FIELD_UNKNOWN
+                    type: urn:gala:problem:request-field-unknown
                 VALIDATION_FAILED:
                   summary: VALIDATION_FAILED
                   value:
@@ -38506,13 +39382,14 @@ paths:
                     type: urn:gala:problem:validation-failed
               schema:
                 $ref: "#/components/schemas/Problem"
-          description: VALIDATION_FAILED
+          description: REQUEST_FIELD_UNKNOWN, VALIDATION_FAILED
           headers:
             Cache-Control:
               $ref: "#/components/headers/CacheControlNoStore"
             X-Correlation-Id:
               $ref: "#/components/headers/XCorrelationId"
           x-gala-problem-codes:
+            - REQUEST_FIELD_UNKNOWN
             - VALIDATION_FAILED
         "401":
           content:
@@ -38609,9 +39486,64 @@ paths:
               $ref: "#/components/headers/XCorrelationId"
           x-gala-problem-codes:
             - RESOURCE_NOT_FOUND
+        "409":
+          content:
+            application/problem+json:
+              examples:
+                COMMAND_REPLAY_CONFLICT:
+                  summary: COMMAND_REPLAY_CONFLICT
+                  value:
+                    code: COMMAND_REPLAY_CONFLICT
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 409
+                    title: COMMAND_REPLAY_CONFLICT
+                    type: urn:gala:problem:command-replay-conflict
+                HANDOVER_EXISTS:
+                  summary: HANDOVER_EXISTS
+                  value:
+                    code: HANDOVER_EXISTS
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 409
+                    title: HANDOVER_EXISTS
+                    type: urn:gala:problem:handover-exists
+                INVALID_SOURCE_STATE:
+                  summary: INVALID_SOURCE_STATE
+                  value:
+                    code: INVALID_SOURCE_STATE
+                    correlationId: 018f0000-0000-7000-8000-000000000001
+                    detail: See the operation contract.
+                    errors: []
+                    retryable: false
+                    schemaId: urn:gala:schema:problem:2.0.0
+                    schemaVersion: 2.0.0
+                    status: 409
+                    title: INVALID_SOURCE_STATE
+                    type: urn:gala:problem:invalid-source-state
+              schema:
+                $ref: "#/components/schemas/Problem"
+          description: COMMAND_REPLAY_CONFLICT, HANDOVER_EXISTS, INVALID_SOURCE_STATE
+          headers:
+            Cache-Control:
+              $ref: "#/components/headers/CacheControlNoStore"
+            X-Correlation-Id:
+              $ref: "#/components/headers/XCorrelationId"
+          x-gala-problem-codes:
+            - COMMAND_REPLAY_CONFLICT
+            - HANDOVER_EXISTS
+            - INVALID_SOURCE_STATE
       security:
         - browserSession: []
-      summary: read publication handover
+      summary: issue site handover claim
       tags:
         - organizations
       x-gala-action-grant: none
@@ -38624,22 +39556,30 @@ paths:
       x-gala-conditional-capabilities: []
       x-gala-example-profile: NOMINAL_SUCCESS_AND_EACH_REACHABLE_PROBLEM
       x-gala-nullability: required-and-nullable-are-explicit
-      x-gala-purpose: read publication handover
+      x-gala-purpose: issue site handover claim
       x-gala-reachable-problems:
         - AUTHENTICATION_REQUIRED
         - AUTHORIZATION_DENIED
+        - COMMAND_REPLAY_CONFLICT
+        - HANDOVER_EXISTS
+        - INVALID_SOURCE_STATE
         - REAUTH_REQUIRED
+        - REQUEST_FIELD_UNKNOWN
         - RESOURCE_NOT_FOUND
         - VALIDATION_FAILED
-      x-gala-replay-identity: safe-query
+      x-gala-replay-identity: idempotency-key
       x-gala-state-guards:
-        - NONE
-      x-gala-success-category: query
+        - Publication:ACTIVE
+        - Organization:SINGLE
+        - CreatorClaim:no VERIFIED claim
+        - CreatorClaim:OPEN -> REVOKED when replace is true, otherwise no OPEN claim
+      x-gala-success-category: create
       x-gala-tenant-scope: ORGANIZATION_AND_PUBLICATION_PATH
+  /v2/organizations/{organizationId}/publications/{publicationId}/handover-claims/{claimId}:revoke:
     post:
       description: |
-        The organisation owner, with recent authentication; an API key is always refused. Moves a demo site's repository into `targetOwnerLogin` (a person or an organisation where the Galascribe App is installed): plans and confirms the finalize change in the caller's session, then starts the GitHub transfer. `202` accepts; `GET` reports progress. `409 HANDOVER_EXISTS` while one is live, `409 HANDOVER_TARGET_NOT_INSTALLED` when the App is not installed on the target, `503 DEPENDENCY_UNAVAILABLE` when GitHub cannot be reached. `404 RESOURCE_NOT_FOUND` when the publication is not a demo site. The response never carries `state: NOT_STARTED`.
-      operationId: postOrganizationsByOrganizationIdPublicationsByPublicationIdHandover
+        The organisation owner, with recent authentication; an API key is always refused. Revokes an `OPEN` or `VERIFIED` claim: its link stops working at once (`GET /v2/claims/{token}` answers `404 CLAIM_NOT_FOUND`) and any verification a claimant completed is discarded. Revoking a `REVOKED` claim returns it unchanged. `409 CLAIM_ALREADY_CLAIMED` once the site has been claimed, `410 CLAIM_EXPIRED` once the claim has expired, `404 RESOURCE_NOT_FOUND` for a claim that is not this site's.
+      operationId: postOrganizationsByOrganizationIdPublicationsByPublicationIdHandoverClaimsByClaimIdRevoke
       parameters:
         - $ref: "#/components/parameters/XCorrelationId"
         - example: 018f0000-0000-7000-8000-000000000001
@@ -38658,70 +39598,45 @@ paths:
             format: uuid
             pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
             type: string
+        - example: 018f0000-0000-7000-8000-000000000001
+          in: path
+          name: claimId
+          required: true
+          schema:
+            format: uuid
+            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
+            type: string
         - $ref: "#/components/parameters/IdempotencyKey"
         - $ref: "#/components/parameters/XCsrfToken"
-      requestBody:
-        content:
-          application/json:
-            examples:
-              nominal:
-                summary: Nominal valid request
-                value:
-                  targetOwnerLogin: creator-org
-            schema:
-              $ref: "#/components/schemas/PostOrganizationsByOrganizationIdPublicationsByPublicationIdHandoverRequest"
-        required: true
       responses:
-        "202":
+        "200":
           content:
             application/json:
               examples:
                 nominal:
                   summary: Nominal successful response
                   value:
-                    appInstalledOnTarget: true
-                    siteUrlAfter: https://creator-org.github.io/maya-cooks/
-                    state: REQUESTED
-                    steps:
-                      - name: FINALIZE_CHANGE
-                        state: DONE
-                      - name: TRANSFER
-                        state: RUNNING
-                      - name: RELINK
-                        state: PENDING
-                      - name: PAGES
-                        state: PENDING
-                      - name: PUBLISH
-                        state: PENDING
-                    target:
-                      kind: ORGANIZATION
-                      ownerLogin: creator-org
+                    claimId: 018f0000-0000-7000-8000-000000000001
+                    createdAt: "2026-10-17T12:00:00.000Z"
+                    expiresAt: "2026-11-16T12:00:00.000Z"
+                    proof:
+                      kind: LINK_ONLY
+                    state: REVOKED
                     version: 1
               schema:
-                $ref: "#/components/schemas/PostOrganizationsByOrganizationIdPublicationsByPublicationIdHandoverResponse"
-          description: start publication handover succeeded
+                $ref: "#/components/schemas/PostOrganizationsByOrganizationIdPublicationsByPublicationIdHandoverClaimsByClaimIdRevokeResponse"
+          description: revoke site handover claim succeeded
           headers:
             Cache-Control:
               $ref: "#/components/headers/CacheControlNoStore"
+            ETag:
+              $ref: "#/components/headers/ETag"
             X-Correlation-Id:
               $ref: "#/components/headers/XCorrelationId"
         "400":
           content:
             application/problem+json:
               examples:
-                REQUEST_FIELD_UNKNOWN:
-                  summary: REQUEST_FIELD_UNKNOWN
-                  value:
-                    code: REQUEST_FIELD_UNKNOWN
-                    correlationId: 018f0000-0000-7000-8000-000000000001
-                    detail: See the operation contract.
-                    errors: []
-                    retryable: false
-                    schemaId: urn:gala:schema:problem:2.0.0
-                    schemaVersion: 2.0.0
-                    status: 400
-                    title: REQUEST_FIELD_UNKNOWN
-                    type: urn:gala:problem:request-field-unknown
                 VALIDATION_FAILED:
                   summary: VALIDATION_FAILED
                   value:
@@ -38737,14 +39652,13 @@ paths:
                     type: urn:gala:problem:validation-failed
               schema:
                 $ref: "#/components/schemas/Problem"
-          description: REQUEST_FIELD_UNKNOWN, VALIDATION_FAILED
+          description: VALIDATION_FAILED
           headers:
             Cache-Control:
               $ref: "#/components/headers/CacheControlNoStore"
             X-Correlation-Id:
               $ref: "#/components/headers/XCorrelationId"
           x-gala-problem-codes:
-            - REQUEST_FIELD_UNKNOWN
             - VALIDATION_FAILED
         "401":
           content:
@@ -38845,23 +39759,10 @@ paths:
           content:
             application/problem+json:
               examples:
-                COMMAND_REPLAY_CONFLICT:
-                  summary: COMMAND_REPLAY_CONFLICT
-                  value:
-                    code: COMMAND_REPLAY_CONFLICT
-                    correlationId: 018f0000-0000-7000-8000-000000000001
-                    detail: See the operation contract.
-                    errors: []
-                    retryable: false
-                    schemaId: urn:gala:schema:problem:2.0.0
-                    schemaVersion: 2.0.0
-                    status: 409
-                    title: COMMAND_REPLAY_CONFLICT
-                    type: urn:gala:problem:command-replay-conflict
-                HANDOVER_EXISTS:
-                  summary: HANDOVER_EXISTS
+                CLAIM_ALREADY_CLAIMED:
+                  summary: CLAIM_ALREADY_CLAIMED
                   value:
-                    code: HANDOVER_EXISTS
+                    code: CLAIM_ALREADY_CLAIMED
                     correlationId: 018f0000-0000-7000-8000-000000000001
                     detail: See the operation contract.
                     errors: []
@@ -38869,12 +39770,12 @@ paths:
                     schemaId: urn:gala:schema:problem:2.0.0
                     schemaVersion: 2.0.0
                     status: 409
-                    title: HANDOVER_EXISTS
-                    type: urn:gala:problem:handover-exists
-                HANDOVER_TARGET_NOT_INSTALLED:
-                  summary: HANDOVER_TARGET_NOT_INSTALLED
+                    title: CLAIM_ALREADY_CLAIMED
+                    type: urn:gala:problem:claim-already-claimed
+                COMMAND_REPLAY_CONFLICT:
+                  summary: COMMAND_REPLAY_CONFLICT
                   value:
-                    code: HANDOVER_TARGET_NOT_INSTALLED
+                    code: COMMAND_REPLAY_CONFLICT
                     correlationId: 018f0000-0000-7000-8000-000000000001
                     detail: See the operation contract.
                     errors: []
@@ -38882,50 +39783,49 @@ paths:
                     schemaId: urn:gala:schema:problem:2.0.0
                     schemaVersion: 2.0.0
                     status: 409
-                    title: HANDOVER_TARGET_NOT_INSTALLED
-                    type: urn:gala:problem:handover-target-not-installed
+                    title: COMMAND_REPLAY_CONFLICT
+                    type: urn:gala:problem:command-replay-conflict
               schema:
                 $ref: "#/components/schemas/Problem"
-          description: COMMAND_REPLAY_CONFLICT, HANDOVER_EXISTS, HANDOVER_TARGET_NOT_INSTALLED
+          description: CLAIM_ALREADY_CLAIMED, COMMAND_REPLAY_CONFLICT
           headers:
             Cache-Control:
               $ref: "#/components/headers/CacheControlNoStore"
             X-Correlation-Id:
               $ref: "#/components/headers/XCorrelationId"
           x-gala-problem-codes:
+            - CLAIM_ALREADY_CLAIMED
             - COMMAND_REPLAY_CONFLICT
-            - HANDOVER_EXISTS
-            - HANDOVER_TARGET_NOT_INSTALLED
-        "503":
+        "410":
           content:
             application/problem+json:
               examples:
-                DEPENDENCY_UNAVAILABLE:
-                  summary: DEPENDENCY_UNAVAILABLE
+                CLAIM_EXPIRED:
+                  summary: CLAIM_EXPIRED
                   value:
-                    code: DEPENDENCY_UNAVAILABLE
+                    code: CLAIM_EXPIRED
                     correlationId: 018f0000-0000-7000-8000-000000000001
                     detail: See the operation contract.
                     errors: []
-                    retryable: true
+                    retryable: false
                     schemaId: urn:gala:schema:problem:2.0.0
                     schemaVersion: 2.0.0
-                    status: 503
-                    title: DEPENDENCY_UNAVAILABLE
-                    type: urn:gala:problem:dependency-unavailable
+                    status: 410
+                    title: CLAIM_EXPIRED
+                    type: urn:gala:problem:claim-expired
               schema:
                 $ref: "#/components/schemas/Problem"
-          description: DEPENDENCY_UNAVAILABLE
+          description: CLAIM_EXPIRED
           headers:
             Cache-Control:
               $ref: "#/components/headers/CacheControlNoStore"
             X-Correlation-Id:
               $ref: "#/components/headers/XCorrelationId"
           x-gala-problem-codes:
-            - DEPENDENCY_UNAVAILABLE
+            - CLAIM_EXPIRED
       security:
         - browserSession: []
-      summary: start publication handover
+      summary: revoke site handover claim
       tags:
         - organizations
       x-gala-action-grant: none
@@ -38938,22 +39838,20 @@ paths:
       x-gala-conditional-capabilities: []
       x-gala-example-profile: NOMINAL_SUCCESS_AND_EACH_REACHABLE_PROBLEM
       x-gala-nullability: required-and-nullable-are-explicit
-      x-gala-purpose: start publication handover
+      x-gala-purpose: revoke site handover claim
       x-gala-reachable-problems:
         - AUTHENTICATION_REQUIRED
         - AUTHORIZATION_DENIED
+        - CLAIM_ALREADY_CLAIMED
+        - CLAIM_EXPIRED
         - COMMAND_REPLAY_CONFLICT
-        - DEPENDENCY_UNAVAILABLE
-        - HANDOVER_EXISTS
-        - HANDOVER_TARGET_NOT_INSTALLED
         - REAUTH_REQUIRED
-        - REQUEST_FIELD_UNKNOWN
         - RESOURCE_NOT_FOUND
         - VALIDATION_FAILED
       x-gala-replay-identity: idempotency-key
       x-gala-state-guards:
         - NONE
-      x-gala-success-category: async
+      x-gala-success-category: update
       x-gala-tenant-scope: ORGANIZATION_AND_PUBLICATION_PATH
   /v2/organizations/{organizationId}/publications/{publicationId}/handover:cancel:
     post: