@leaflow/sdk 0.1.3 → 0.3.0

package/openapi/iam.yaml

@@ -1,6 +1,18 @@
 components:
   schemas:
-    AcceptInvitationByTokenInputBody:
+    AcceptConsentsRequestBody:
+      additionalProperties: false
+      properties:
+        consents:
+          items:
+            $ref: "#/components/schemas/ConsentBody"
+          type:
+            - array
+            - "null"
+      required:
+        - consents
+      type: object
+    AcceptInvitationByTokenRequestBody:
       additionalProperties: false
       properties:
         token:
@@ -10,15 +22,15 @@ components:
       required:
         - token
       type: object
-    AcceptInvitationOutputBody:
+    AcceptedInvitationResponseBody:
       additionalProperties: false
       properties:
         project:
-          $ref: "#/components/schemas/ProjectView"
+          $ref: "#/components/schemas/ProjectResource"
       required:
         - project
       type: object
-    AccountView:
+    AccountResource:
       additionalProperties: false
       properties:
         created_at:
@@ -40,6 +52,12 @@ components:
         last_name:
           description: 来自登录信息，可能为空
           type: string
+        pending_agreements:
+          items:
+            $ref: "#/components/schemas/AgreementResource"
+          type:
+            - array
+            - "null"
         status:
           enum:
             - ACTIVE
@@ -47,11 +65,6 @@ components:
             - BANNED
             - DELETING
           type: string
-        terms_accepted_at:
-          format: date-time
-          type:
-            - string
-            - "null"
       required:
         - id
         - email
@@ -59,36 +72,114 @@ components:
         - last_name
         - status
         - email_verified_at
-        - terms_accepted_at
         - created_at
+        - pending_agreements
       type: object
-    CreateProjectInputBody:
+    AgreementListResponseBody:
       additionalProperties: false
       properties:
-        description:
-          maxLength: 2000
+        items:
+          items:
+            $ref: "#/components/schemas/AgreementResource"
+          type:
+            - array
+            - "null"
+      required:
+        - items
+      type: object
+    AgreementResource:
+      additionalProperties: false
+      properties:
+        effective_at:
+          description: 从这一刻起注册必须同意这一版
+          format: date-time
           type: string
-        name:
-          maxLength: 128
-          minLength: 1
+        type:
+          enum:
+            - TERMS
+            - PRIVACY
+            - DPA
+          type: string
+        url:
+          description: 正文发布在哪
+          type: string
+        version:
+          description: 同意时原样回传这个值
           type: string
       required:
-        - name
+        - type
+        - version
+        - url
+        - effective_at
+      type: object
+    ConsentBody:
+      additionalProperties: false
+      properties:
+        type:
+          enum:
+            - TERMS
+            - PRIVACY
+            - DPA
+          type: string
+        version:
+          maxLength: 32
+          type: string
+      required:
+        - type
+        - version
       type: object
-    CreateProjectSSHKeyInputBody:
+    ConsentListResponseBody:
       additionalProperties: false
       properties:
+        items:
+          items:
+            $ref: "#/components/schemas/ConsentResource"
+          type:
+            - array
+            - "null"
+      required:
+        - items
+      type: object
+    ConsentResource:
+      additionalProperties: false
+      properties:
+        consented_at:
+          format: date-time
+          type: string
+        method:
+          description: OFFLINE 是线下签的，由运营录入
+          enum:
+            - CLICKWRAP
+            - OFFLINE
+          type: string
+        type:
+          enum:
+            - TERMS
+            - PRIVACY
+            - DPA
+          type: string
+        version:
+          type: string
+      required:
+        - type
+        - version
+        - consented_at
+        - method
+      type: object
+    CreateProjectRequestBody:
+      additionalProperties: false
+      properties:
+        description:
+          maxLength: 2000
+          type: string
         name:
           maxLength: 128
-          type: string
-        public_key:
-          maxLength: 16384
+          minLength: 1
           type: string
       required:
         - name
-        - public_key
       type: object
-    CreateRoleInputBody:
+    CreateRoleRequestBody:
       additionalProperties: false
       properties:
         code:
@@ -112,16 +203,31 @@ components:
         - code
         - name
       type: object
-    CreateUserSSHKeyInputBody:
+    CreateSSHKeyRequestBody:
       additionalProperties: false
       properties:
         name:
           maxLength: 128
           type: string
+        owner:
+          default: me
+          description: 这把钥匙归谁
+          enum:
+            - me
+            - project
+          type: string
         public_key:
           description: OpenSSH 格式的公钥。类型和指纹从它算出来，都不可改
           maxLength: 16384
           type: string
+        purposes:
+          description: 用途标签，比如 ci、bastion
+          items:
+            type: string
+          maxItems: 16
+          type:
+            - array
+            - "null"
       required:
         - name
         - public_key
@@ -143,38 +249,7 @@ components:
         - status
         - message
       type: object
-    ExchangeTokenOutputBody:
-      additionalProperties: false
-      properties:
-        expires_at:
-          description: 过期时刻。到点之前拿用户身份再换一张，别等第一个 401
-          format: date-time
-          type: string
-        expires_in:
-          description: 还能活多少秒
-          format: int64
-          type: integer
-        grant:
-          $ref: "#/components/schemas/GrantView"
-          description: "**这一份是此刻的快照，不在令牌里，也不要缓存它。** 它只用来决定界面上画什么；真正的判定每次都要重新问"
-        project:
-          $ref: "#/components/schemas/ProjectView"
-          description: 顺带带上项目本身，省掉换完之后立刻再查一次
-        token:
-          description: "项目令牌，放进 Authorization: Bearer 里用"
-          type: string
-        token_type:
-          description: 固定是 Bearer
-          type: string
-      required:
-        - token
-        - token_type
-        - expires_at
-        - expires_in
-        - project
-        - grant
-      type: object
-    GrantView:
+    GrantResource:
       additionalProperties: false
       properties:
         admin:
@@ -201,7 +276,7 @@ components:
         - permissions
         - roles
       type: object
-    IdentityVerificationView:
+    IdentityVerificationResource:
       additionalProperties: false
       properties:
         reject_reason:
@@ -231,7 +306,7 @@ components:
         - verified_at
         - reject_reason
       type: object
-    InvitationView:
+    InvitationResource:
       additionalProperties: false
       properties:
         created_at:
@@ -266,7 +341,7 @@ components:
         - expires_at
         - created_at
       type: object
-    IssueInvitationInputBody:
+    IssueInvitationRequestBody:
       additionalProperties: false
       properties:
         email:
@@ -285,11 +360,11 @@ components:
         - email
         - roles
       type: object
-    IssueInvitationOutputBody:
+    IssuedInvitationResponseBody:
       additionalProperties: false
       properties:
         invitation:
-          $ref: "#/components/schemas/InvitationView"
+          $ref: "#/components/schemas/InvitationResource"
         token:
           description: 兑现用的明文，**只在这一次响应里出现**。库里只有它的哈希，丢了只能撤销重发
           type: string
@@ -297,95 +372,111 @@ components:
         - invitation
         - token
       type: object
-    ListInvitationsOutputBody:
+    LengthAwarePageInvitationResource:
       additionalProperties: false
       properties:
         items:
+          description: 这一页的内容
           items:
-            $ref: "#/components/schemas/InvitationView"
-          type:
-            - array
-            - "null"
+            $ref: "#/components/schemas/InvitationResource"
+          type: array
+        limit:
+          description: 这一页最多几条，回显请求里的值
+          format: int64
+          type: integer
+        offset:
+          description: 跳过了多少条，回显请求里的值
+          format: int64
+          type: integer
         total:
+          description: 命中的总条数，不只是这一页
           format: int64
           type: integer
       required:
         - items
         - total
+        - limit
+        - offset
       type: object
-    ListMembersOutputBody:
+    LengthAwarePageMemberResource:
       additionalProperties: false
       properties:
         items:
+          description: 这一页的内容
           items:
-            $ref: "#/components/schemas/MemberView"
-          type:
-            - array
-            - "null"
+            $ref: "#/components/schemas/MemberResource"
+          type: array
+        limit:
+          description: 这一页最多几条，回显请求里的值
+          format: int64
+          type: integer
+        offset:
+          description: 跳过了多少条，回显请求里的值
+          format: int64
+          type: integer
         total:
+          description: 命中的总条数，不只是这一页
           format: int64
           type: integer
       required:
         - items
         - total
+        - limit
+        - offset
       type: object
-    ListPermissionsOutputBody:
-      additionalProperties: false
-      properties:
-        items:
-          items:
-            $ref: "#/components/schemas/PermissionView"
-          type:
-            - array
-            - "null"
-      required:
-        - items
-      type: object
-    ListProjectsOutputBody:
+    LengthAwarePageProjectAccessResource:
       additionalProperties: false
       properties:
         items:
+          description: 这一页的内容
           items:
-            $ref: "#/components/schemas/ProjectListItem"
-          type:
-            - array
-            - "null"
+            $ref: "#/components/schemas/ProjectAccessResource"
+          type: array
+        limit:
+          description: 这一页最多几条，回显请求里的值
+          format: int64
+          type: integer
+        offset:
+          description: 跳过了多少条，回显请求里的值
+          format: int64
+          type: integer
         total:
+          description: 命中的总条数，不只是这一页
           format: int64
           type: integer
       required:
         - items
         - total
+        - limit
+        - offset
       type: object
-    ListRolesOutputBody:
-      additionalProperties: false
-      properties:
-        items:
-          items:
-            $ref: "#/components/schemas/RoleView"
-          type:
-            - array
-            - "null"
-      required:
-        - items
-      type: object
-    ListSSHKeysOutputBody:
+    LengthAwarePageSSHKeyResource:
       additionalProperties: false
       properties:
         items:
+          description: 这一页的内容
           items:
-            $ref: "#/components/schemas/SSHKeyView"
-          type:
-            - array
-            - "null"
+            $ref: "#/components/schemas/SSHKeyResource"
+          type: array
+        limit:
+          description: 这一页最多几条，回显请求里的值
+          format: int64
+          type: integer
+        offset:
+          description: 跳过了多少条，回显请求里的值
+          format: int64
+          type: integer
         total:
+          description: 命中的总条数，不只是这一页
           format: int64
           type: integer
       required:
         - items
         - total
+        - limit
+        - offset
       type: object
-    MemberView:
+    MemberResource:
       additionalProperties: false
       properties:
         created_at:
@@ -398,7 +489,7 @@ components:
         first_name:
           type: string
         grant:
-          $ref: "#/components/schemas/GrantView"
+          $ref: "#/components/schemas/GrantResource"
         last_name:
           type: string
         user_id:
@@ -412,11 +503,11 @@ components:
         - created_by
         - created_at
       type: object
-    MembershipView:
+    MembershipResource:
       additionalProperties: false
       properties:
         grant:
-          $ref: "#/components/schemas/GrantView"
+          $ref: "#/components/schemas/GrantResource"
         member:
           type: boolean
         project_status:
@@ -429,7 +520,31 @@ components:
         - user_status
         - project_status
       type: object
-    PermissionView:
+    OwnershipTransferResponseBody:
+      additionalProperties: false
+      properties:
+        from:
+          $ref: "#/components/schemas/MemberResource"
+          description: 原所有者。他保留其余的角色——转让的是所有权，不是把人踢出去
+        to:
+          $ref: "#/components/schemas/MemberResource"
+      required:
+        - from
+        - to
+      type: object
+    PermissionListResponseBody:
+      additionalProperties: false
+      properties:
+        items:
+          items:
+            $ref: "#/components/schemas/PermissionResource"
+          type:
+            - array
+            - "null"
+      required:
+        - items
+      type: object
+    PermissionResource:
       additionalProperties: false
       properties:
         description:
@@ -444,18 +559,18 @@ components:
         - description
         - owner_only
       type: object
-    ProjectListItem:
+    ProjectAccessResource:
       additionalProperties: false
       properties:
         grant:
-          $ref: "#/components/schemas/GrantView"
+          $ref: "#/components/schemas/GrantResource"
         project:
-          $ref: "#/components/schemas/ProjectView"
+          $ref: "#/components/schemas/ProjectResource"
       required:
         - project
         - grant
       type: object
-    ProjectView:
+    ProjectResource:
       additionalProperties: false
       properties:
         ban_reason:
@@ -511,16 +626,51 @@ components:
         - created_at
         - updated_at
       type: object
-    RenameProjectSSHKeyInputBody:
+    ProjectTokenResponseBody:
       additionalProperties: false
       properties:
-        name:
-          maxLength: 128
+        expires_at:
+          description: 过期时刻。到点之前拿用户身份再换一张，别等第一个 401
+          format: date-time
+          type: string
+        expires_in:
+          description: 还能活多少秒
+          format: int64
+          type: integer
+        grant:
+          $ref: "#/components/schemas/GrantResource"
+          description: "**这一份是此刻的快照，不在令牌里，也不要缓存它。** 它只用来决定界面上画什么；真正的判定每次都要重新问"
+        project:
+          $ref: "#/components/schemas/ProjectResource"
+          description: 顺带带上项目本身，省掉换完之后立刻再查一次
+        token:
+          description: "项目令牌，放进 Authorization: Bearer 里用"
+          type: string
+        token_type:
+          description: 固定是 Bearer
           type: string
       required:
-        - name
+        - token
+        - token_type
+        - expires_at
+        - expires_in
+        - project
+        - grant
       type: object
-    RenameUserSSHKeyInputBody:
+    RegisterRequestBody:
+      additionalProperties: false
+      properties:
+        consents:
+          description: 当前生效的必签文件全部要在里面，版本号要和 GET /api/v1/agreements 给的一致
+          items:
+            $ref: "#/components/schemas/ConsentBody"
+          type:
+            - array
+            - "null"
+      required:
+        - consents
+      type: object
+    RenameSSHKeyRequestBody:
       additionalProperties: false
       properties:
         name:
@@ -529,7 +679,19 @@ components:
       required:
         - name
       type: object
-    RoleView:
+    RoleListResponseBody:
+      additionalProperties: false
+      properties:
+        items:
+          items:
+            $ref: "#/components/schemas/RoleResource"
+          type:
+            - array
+            - "null"
+      required:
+        - items
+      type: object
+    RoleResource:
       additionalProperties: false
       properties:
         builtin:
@@ -562,7 +724,7 @@ components:
         - created_at
         - updated_at
       type: object
-    SSHKeyView:
+    SSHKeyResource:
       additionalProperties: false
       properties:
         created_at:
@@ -570,6 +732,9 @@ components:
           type: string
         fingerprint:
           type: string
+        has_private_key:
+          description: 平台生成并保管的那把。它的私钥不对外提供
+          type: boolean
         id:
           format: uuid
           type: string
@@ -577,8 +742,18 @@ components:
           type: string
         name:
           type: string
+        owner_user_id:
+          description: 归属人；不给表示这把钥匙归项目本身
+          type: string
         public_key:
           type: string
+        purposes:
+          description: 用途标签。平台自己生成的那把是 platform
+          items:
+            type: string
+          type:
+            - array
+            - "null"
         status:
           enum:
             - ACTIVE
@@ -592,8 +767,10 @@ components:
         - key_type
         - status
         - created_at
+        - purposes
+        - has_private_key
       type: object
-    SetMemberRolesInputBody:
+    SetMemberRolesRequestBody:
       additionalProperties: false
       properties:
         roles:
@@ -606,7 +783,7 @@ components:
       required:
         - roles
       type: object
-    SubmitIdentityVerificationInputBody:
+    SubmitIdentityVerificationRequestBody:
       additionalProperties: false
       properties:
         id_number:
@@ -622,7 +799,7 @@ components:
         - real_name
         - id_number
       type: object
-    TransferOwnershipInputBody:
+    TransferOwnershipRequestBody:
       additionalProperties: false
       properties:
         to_user_id:
@@ -632,19 +809,7 @@ components:
       required:
         - to_user_id
       type: object
-    TransferOwnershipOutputBody:
-      additionalProperties: false
-      properties:
-        from:
-          $ref: "#/components/schemas/MemberView"
-          description: 原所有者。他保留其余的角色——转让的是所有权，不是把人踢出去
-        to:
-          $ref: "#/components/schemas/MemberView"
-      required:
-        - from
-        - to
-      type: object
-    UpdateProjectInputBody:
+    UpdateProjectRequestBody:
       additionalProperties: false
       properties:
         description:
@@ -654,7 +819,7 @@ components:
           maxLength: 128
           type: string
       type: object
-    UpdateRoleInputBody:
+    UpdateRoleRequestBody:
       additionalProperties: false
       properties:
         description:
@@ -672,6 +837,12 @@ components:
       required:
         - name
       type: object
+  securitySchemes:
+    bearerAuth:
+      bearerFormat: JWT
+      description: 项目令牌。先在 auth.leaflow.net 登录拿到账号令牌，再用它向 IAM 换取项目令牌（POST /api/v1/projects/{projectId}/token）——一张项目令牌同时说明当前用户和当前项目。
+      scheme: bearer
+      type: http
 info:
   description: |-
     用户和项目自己用的接口：账号、项目、成员、角色、邀请、SSH 公钥。
@@ -693,8 +864,32 @@ info:
   version: 1.0.0
 openapi: 3.1.0
 paths:
+  /api/v1/agreements:
+    get:
+      description: |-
+        注册页显示它，用户同意之后把每一项的 `type` 和 `version` 原样回传给 `POST /api/v1/register`。
+
+        不需要令牌。还没有任何文件生效时返回空数组，那时注册不需要提交 `consents`。
+      operationId: list-agreements
+      responses:
+        "200":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AgreementListResponseBody"
+          description: OK
+        default:
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+          description: Error
+      summary: 列出注册必须同意的文件
+      tags:
+        - Agreement
   /api/v1/me:
     get:
+      description: "`pending_agreements` 是还没同意的文件，非空就要先引导用户同意，再调 `POST /api/v1/me/consents`。"
       operationId: get-account
       parameters:
         - description: Bearer 令牌。选定项目之前用 auth.leaflow.net 签发的账号令牌，选定之后用项目令牌
@@ -709,7 +904,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/AccountView"
+                $ref: "#/components/schemas/AccountResource"
           description: OK
         default:
           content:
@@ -720,10 +915,10 @@ paths:
       summary: 查看当前账号
       tags:
         - Account
-  /api/v1/me/identity-verification:
+  /api/v1/me/consents:
     get:
-      description: 没交过材料时答 UNVERIFIED，不是 404。姓名和证件号不会出现在任何响应里。
-      operationId: get-identity-verification
+      description: 全部记录，最新的在前，包括已经不是当前版本的那些。
+      operationId: list-consents
       parameters:
         - description: Bearer 令牌。选定项目之前用 auth.leaflow.net 签发的账号令牌，选定之后用项目令牌
           in: header
@@ -737,7 +932,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/IdentityVerificationView"
+                $ref: "#/components/schemas/ConsentListResponseBody"
           description: OK
         default:
           content:
@@ -745,12 +940,15 @@ paths:
               schema:
                 $ref: "#/components/schemas/Error"
           description: Error
-      summary: 查看实名核验状态
+      summary: 列出我同意过的文件
       tags:
-        - Account
+        - Agreement
     post:
-      description: 已经在等人审的和已经核过的都会被拒。被驳回之后可以改了再交。
-      operationId: submit-identity-verification
+      description: |-
+        条款改版之后用它重新同意，`GET /api/v1/me` 的 `pending_agreements` 非空时就该调。
+
+        只收当前生效的版本，签旧版答 409。重复提交同一版不报错，第一次那条记录会留着。
+      operationId: accept-agreements
       parameters:
         - description: Bearer 令牌。选定项目之前用 auth.leaflow.net 签发的账号令牌，选定之后用项目令牌
           in: header
@@ -763,28 +961,28 @@ paths:
         content:
           application/json:
             schema:
-              $ref: "#/components/schemas/SubmitIdentityVerificationInputBody"
+              $ref: "#/components/schemas/AcceptConsentsRequestBody"
         required: true
       responses:
-        "202":
+        "200":
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/IdentityVerificationView"
-          description: Accepted
+                $ref: "#/components/schemas/AccountResource"
+          description: OK
         default:
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
           description: Error
-      summary: 提交实名核验材料
+      summary: 同意条款
       tags:
-        - Account
-  /api/v1/me/invitations:
+        - Agreement
+  /api/v1/me/identity-verification:
     get:
-      description: 按当前账号的邮箱查，因为要约是寄给一个地址的——被邀请的人当时可能还没注册。
-      operationId: list-my-invitations
+      description: 没交过材料时答 UNVERIFIED，不是 404。姓名和证件号不会出现在任何响应里。
+      operationId: get-identity-verification
       parameters:
         - description: Bearer 令牌。选定项目之前用 auth.leaflow.net 签发的账号令牌，选定之后用项目令牌
           in: header
@@ -793,32 +991,12 @@ paths:
           schema:
             description: Bearer 令牌。选定项目之前用 auth.leaflow.net 签发的账号令牌，选定之后用项目令牌
             type: string
-        - description: 这一页最多返回多少条，0 表示用默认值
-          explode: false
-          in: query
-          name: limit
-          schema:
-            default: 50
-            description: 这一页最多返回多少条，0 表示用默认值
-            format: int64
-            maximum: 100
-            minimum: 0
-            type: integer
-        - description: 跳过多少条
-          explode: false
-          in: query
-          name: offset
-          schema:
-            description: 跳过多少条
-            format: int64
-            minimum: 0
-            type: integer
       responses:
         "200":
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ListInvitationsOutputBody"
+                $ref: "#/components/schemas/IdentityVerificationResource"
           description: OK
         default:
           content:
@@ -826,13 +1004,12 @@ paths:
               schema:
                 $ref: "#/components/schemas/Error"
           description: Error
-      summary: 列出寄给我的要约
+      summary: 查看实名核验状态
       tags:
-        - Invitation
-  /api/v1/me/invitations/accept:
+        - Account
     post:
-      description: token 对不上和这份要约已经不作数了是同一个回答：持有者对这两种情况能做的事完全一样，分开报会把这个接口变成一个可以拿来试 token 的探针。
-      operationId: accept-invitation-by-token
+      description: 已经在等人审的和已经核过的都会被拒。被驳回之后可以改了再交。
+      operationId: submit-identity-verification
       parameters:
         - description: Bearer 令牌。选定项目之前用 auth.leaflow.net 签发的账号令牌，选定之后用项目令牌
           in: header
@@ -845,61 +1022,28 @@ paths:
         content:
           application/json:
             schema:
-              $ref: "#/components/schemas/AcceptInvitationByTokenInputBody"
+              $ref: "#/components/schemas/SubmitIdentityVerificationRequestBody"
         required: true
       responses:
-        "200":
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/AcceptInvitationOutputBody"
-          description: OK
-        default:
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/Error"
-          description: Error
-      summary: 顺着邀请链接接受
-      tags:
-        - Invitation
-  /api/v1/me/invitations/{invitationId}/accept:
-    post:
-      description: 不需要 token：token 证明的是「你就是这份要约寄给的那个人」，而当前账号的邮箱对得上这份要约，证明的是同一件事。
-      operationId: accept-invitation
-      parameters:
-        - description: Bearer 令牌。选定项目之前用 auth.leaflow.net 签发的账号令牌，选定之后用项目令牌
-          in: header
-          name: Authorization
-          required: true
-          schema:
-            description: Bearer 令牌。选定项目之前用 auth.leaflow.net 签发的账号令牌，选定之后用项目令牌
-            type: string
-        - in: path
-          name: invitationId
-          required: true
-          schema:
-            format: uuid
-            type: string
-      responses:
-        "200":
+        "202":
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/AcceptInvitationOutputBody"
-          description: OK
+                $ref: "#/components/schemas/IdentityVerificationResource"
+          description: Accepted
         default:
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
           description: Error
-      summary: 接受一份列在我名下的要约
+      summary: 提交实名核验材料
       tags:
-        - Invitation
-  /api/v1/me/ssh-keys:
+        - Account
+  /api/v1/me/invitations:
     get:
-      operationId: list-my-ssh-keys
+      description: 按当前账号的邮箱查，因为要约是寄给一个地址的——被邀请的人当时可能还没注册。
+      operationId: list-my-invitations
       parameters:
         - description: Bearer 令牌。选定项目之前用 auth.leaflow.net 签发的账号令牌，选定之后用项目令牌
           in: header
@@ -908,42 +1052,33 @@ paths:
           schema:
             description: Bearer 令牌。选定项目之前用 auth.leaflow.net 签发的账号令牌，选定之后用项目令牌
             type: string
-        - description: 这一页最多返回多少条，0 表示用默认值
+        - description: 这一页最多返回多少条
           explode: false
           in: query
           name: limit
           schema:
             default: 50
-            description: 这一页最多返回多少条，0 表示用默认值
+            description: 这一页最多返回多少条
             format: int64
-            maximum: 100
-            minimum: 0
+            maximum: 200
+            minimum: 1
             type: integer
-        - description: 跳过多少条
+        - description: 跳过多少条。要翻得更深请改用游标翻页的接口
           explode: false
           in: query
           name: offset
           schema:
-            description: 跳过多少条
+            description: 跳过多少条。要翻得更深请改用游标翻页的接口
             format: int64
+            maximum: 10000
             minimum: 0
             type: integer
-        - description: 不传时两种都返回
-          explode: false
-          in: query
-          name: status
-          schema:
-            description: 不传时两种都返回
-            enum:
-              - ACTIVE
-              - REVOKED
-            type: string
       responses:
         "200":
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ListSSHKeysOutputBody"
+                $ref: "#/components/schemas/LengthAwarePageInvitationResource"
           description: OK
         default:
           content:
@@ -951,11 +1086,13 @@ paths:
               schema:
                 $ref: "#/components/schemas/Error"
           description: Error
-      summary: 列出我的公钥
+      summary: 列出寄给我的要约
       tags:
-        - SSHKey
+        - Invitation
+  /api/v1/me/invitations/accept:
     post:
-      operationId: create-my-ssh-key
+      description: token 对不上和这份要约已经不作数了是同一个回答：持有者对这两种情况能做的事完全一样，分开报会把这个接口变成一个可以拿来试 token 的探针。
+      operationId: accept-invitation-by-token
       parameters:
         - description: Bearer 令牌。选定项目之前用 auth.leaflow.net 签发的账号令牌，选定之后用项目令牌
           in: header
@@ -968,48 +1105,14 @@ paths:
         content:
           application/json:
             schema:
-              $ref: "#/components/schemas/CreateUserSSHKeyInputBody"
+              $ref: "#/components/schemas/AcceptInvitationByTokenRequestBody"
         required: true
-      responses:
-        "201":
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/SSHKeyView"
-          description: Created
-        default:
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/Error"
-          description: Error
-      summary: 添加一把我的公钥
-      tags:
-        - SSHKey
-  /api/v1/me/ssh-keys/{keyId}:
-    delete:
-      description: 行留着，状态变成 REVOKED。事故之后要问的是当时信任的是哪把钥匙。
-      operationId: revoke-my-ssh-key
-      parameters:
-        - description: Bearer 令牌。选定项目之前用 auth.leaflow.net 签发的账号令牌，选定之后用项目令牌
-          in: header
-          name: Authorization
-          required: true
-          schema:
-            description: Bearer 令牌。选定项目之前用 auth.leaflow.net 签发的账号令牌，选定之后用项目令牌
-            type: string
-        - in: path
-          name: keyId
-          required: true
-          schema:
-            format: uuid
-            type: string
       responses:
         "200":
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/SSHKeyView"
+                $ref: "#/components/schemas/AcceptedInvitationResponseBody"
           description: OK
         default:
           content:
@@ -1017,44 +1120,13 @@ paths:
               schema:
                 $ref: "#/components/schemas/Error"
           description: Error
-      summary: 吊销我的一把公钥
-      tags:
-        - SSHKey
-    get:
-      operationId: get-my-ssh-key
-      parameters:
-        - description: Bearer 令牌。选定项目之前用 auth.leaflow.net 签发的账号令牌，选定之后用项目令牌
-          in: header
-          name: Authorization
-          required: true
-          schema:
-            description: Bearer 令牌。选定项目之前用 auth.leaflow.net 签发的账号令牌，选定之后用项目令牌
-            type: string
-        - in: path
-          name: keyId
-          required: true
-          schema:
-            format: uuid
-            type: string
-      responses:
-        "200":
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/SSHKeyView"
-          description: OK
-        default:
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/Error"
-          description: Error
-      summary: 查看我的一把公钥
+      summary: 顺着邀请链接接受
       tags:
-        - SSHKey
-    patch:
-      description: 只有名字能改：公钥、类型、指纹是同一样东西的三种说法，改其中一个会让这一行描述一把并不存在的钥匙。
-      operationId: rename-my-ssh-key
+        - Invitation
+  /api/v1/me/invitations/{invitationId}/accept:
+    post:
+      description: 不需要 token：token 证明的是「你就是这份要约寄给的那个人」，而当前账号的邮箱对得上这份要约，证明的是同一件事。
+      operationId: accept-invitation
       parameters:
         - description: Bearer 令牌。选定项目之前用 auth.leaflow.net 签发的账号令牌，选定之后用项目令牌
           in: header
@@ -1064,23 +1136,17 @@ paths:
             description: Bearer 令牌。选定项目之前用 auth.leaflow.net 签发的账号令牌，选定之后用项目令牌
             type: string
         - in: path
-          name: keyId
+          name: invitationId
           required: true
           schema:
             format: uuid
             type: string
-      requestBody:
-        content:
-          application/json:
-            schema:
-              $ref: "#/components/schemas/RenameUserSSHKeyInputBody"
-        required: true
       responses:
         "200":
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/SSHKeyView"
+                $ref: "#/components/schemas/AcceptedInvitationResponseBody"
           description: OK
         default:
           content:
@@ -1088,37 +1154,9 @@ paths:
               schema:
                 $ref: "#/components/schemas/Error"
           description: Error
-      summary: 给我的公钥改名
-      tags:
-        - SSHKey
-  /api/v1/me/terms:
-    post:
-      description: 幂等：已经同意过的不会被推到今天——那一列是法务要的证据，说的是他哪一次同意的。
-      operationId: accept-terms
-      parameters:
-        - description: Bearer 令牌。选定项目之前用 auth.leaflow.net 签发的账号令牌，选定之后用项目令牌
-          in: header
-          name: Authorization
-          required: true
-          schema:
-            description: Bearer 令牌。选定项目之前用 auth.leaflow.net 签发的账号令牌，选定之后用项目令牌
-            type: string
-      responses:
-        "200":
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/AccountView"
-          description: OK
-        default:
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/Error"
-          description: Error
-      summary: 同意服务条款
+      summary: 接受一份列在我名下的要约
       tags:
-        - Account
+        - Invitation
   /api/v1/permissions:
     get:
       description: "**只有 IAM 这一份。** 别的服务的操作不在这里——权限目录是各服务各自声明、由 各个服务自己声明的，IAM 认识它们就等于要跟着每个下游一起发版。"
@@ -1128,7 +1166,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ListPermissionsOutputBody"
+                $ref: "#/components/schemas/PermissionListResponseBody"
           description: OK
         default:
           content:
@@ -1151,24 +1189,25 @@ paths:
           schema:
             description: Bearer 令牌。选定项目之前用 auth.leaflow.net 签发的账号令牌，选定之后用项目令牌
             type: string
-        - description: 这一页最多返回多少条，0 表示用默认值
+        - description: 这一页最多返回多少条
           explode: false
           in: query
           name: limit
           schema:
             default: 50
-            description: 这一页最多返回多少条，0 表示用默认值
+            description: 这一页最多返回多少条
             format: int64
-            maximum: 100
-            minimum: 0
+            maximum: 200
+            minimum: 1
             type: integer
-        - description: 跳过多少条
+        - description: 跳过多少条。要翻得更深请改用游标翻页的接口
           explode: false
           in: query
           name: offset
           schema:
-            description: 跳过多少条
+            description: 跳过多少条。要翻得更深请改用游标翻页的接口
             format: int64
+            maximum: 10000
             minimum: 0
             type: integer
         - description: 按名称或描述模糊匹配
@@ -1197,7 +1236,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ListProjectsOutputBody"
+                $ref: "#/components/schemas/LengthAwarePageProjectAccessResource"
           description: OK
         default:
           content:
@@ -1223,14 +1262,14 @@ paths:
         content:
           application/json:
             schema:
-              $ref: "#/components/schemas/CreateProjectInputBody"
+              $ref: "#/components/schemas/CreateProjectRequestBody"
         required: true
       responses:
         "201":
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ProjectListItem"
+                $ref: "#/components/schemas/ProjectAccessResource"
           description: Created
         default:
           content:
@@ -1264,7 +1303,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ProjectListItem"
+                $ref: "#/components/schemas/ProjectAccessResource"
           description: OK
         default:
           content:
@@ -1297,7 +1336,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ProjectListItem"
+                $ref: "#/components/schemas/ProjectAccessResource"
           description: OK
         default:
           content:
@@ -1328,14 +1367,14 @@ paths:
         content:
           application/json:
             schema:
-              $ref: "#/components/schemas/UpdateProjectInputBody"
+              $ref: "#/components/schemas/UpdateProjectRequestBody"
         required: true
       responses:
         "200":
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ProjectListItem"
+                $ref: "#/components/schemas/ProjectAccessResource"
           description: OK
         default:
           content:
@@ -1358,24 +1397,25 @@ paths:
           schema:
             description: Bearer 令牌。选定项目之前用 auth.leaflow.net 签发的账号令牌，选定之后用项目令牌
             type: string
-        - description: 这一页最多返回多少条，0 表示用默认值
+        - description: 这一页最多返回多少条
           explode: false
           in: query
           name: limit
           schema:
             default: 50
-            description: 这一页最多返回多少条，0 表示用默认值
+            description: 这一页最多返回多少条
             format: int64
-            maximum: 100
-            minimum: 0
+            maximum: 200
+            minimum: 1
             type: integer
-        - description: 跳过多少条
+        - description: 跳过多少条。要翻得更深请改用游标翻页的接口
           explode: false
           in: query
           name: offset
           schema:
-            description: 跳过多少条
+            description: 跳过多少条。要翻得更深请改用游标翻页的接口
             format: int64
+            maximum: 10000
             minimum: 0
             type: integer
         - in: path
@@ -1389,7 +1429,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ListInvitationsOutputBody"
+                $ref: "#/components/schemas/LengthAwarePageInvitationResource"
           description: OK
         default:
           content:
@@ -1421,14 +1461,14 @@ paths:
         content:
           application/json:
             schema:
-              $ref: "#/components/schemas/IssueInvitationInputBody"
+              $ref: "#/components/schemas/IssueInvitationRequestBody"
         required: true
       responses:
         "201":
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/IssueInvitationOutputBody"
+                $ref: "#/components/schemas/IssuedInvitationResponseBody"
           description: Created
         default:
           content:
@@ -1485,24 +1525,25 @@ paths:
           schema:
             description: Bearer 令牌。选定项目之前用 auth.leaflow.net 签发的账号令牌，选定之后用项目令牌
             type: string
-        - description: 这一页最多返回多少条，0 表示用默认值
+        - description: 这一页最多返回多少条
           explode: false
           in: query
           name: limit
           schema:
             default: 50
-            description: 这一页最多返回多少条，0 表示用默认值
+            description: 这一页最多返回多少条
             format: int64
-            maximum: 100
-            minimum: 0
+            maximum: 200
+            minimum: 1
             type: integer
-        - description: 跳过多少条
+        - description: 跳过多少条。要翻得更深请改用游标翻页的接口
           explode: false
           in: query
           name: offset
           schema:
-            description: 跳过多少条
+            description: 跳过多少条。要翻得更深请改用游标翻页的接口
             format: int64
+            maximum: 10000
             minimum: 0
             type: integer
         - in: path
@@ -1524,7 +1565,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ListMembersOutputBody"
+                $ref: "#/components/schemas/LengthAwarePageMemberResource"
           description: OK
         default:
           content:
@@ -1599,14 +1640,14 @@ paths:
         content:
           application/json:
             schema:
-              $ref: "#/components/schemas/SetMemberRolesInputBody"
+              $ref: "#/components/schemas/SetMemberRolesRequestBody"
         required: true
       responses:
         "200":
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/MemberView"
+                $ref: "#/components/schemas/MemberResource"
           description: OK
         default:
           content:
@@ -1640,7 +1681,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/MembershipView"
+                $ref: "#/components/schemas/MembershipResource"
           description: OK
         default:
           content:
@@ -1673,7 +1714,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ListRolesOutputBody"
+                $ref: "#/components/schemas/RoleListResponseBody"
           description: OK
         default:
           content:
@@ -1704,14 +1745,14 @@ paths:
         content:
           application/json:
             schema:
-              $ref: "#/components/schemas/CreateRoleInputBody"
+              $ref: "#/components/schemas/CreateRoleRequestBody"
         required: true
       responses:
         "201":
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/RoleView"
+                $ref: "#/components/schemas/RoleResource"
           description: Created
         default:
           content:
@@ -1785,7 +1826,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/RoleView"
+                $ref: "#/components/schemas/RoleResource"
           description: OK
         default:
           content:
@@ -1823,14 +1864,14 @@ paths:
         content:
           application/json:
             schema:
-              $ref: "#/components/schemas/UpdateRoleInputBody"
+              $ref: "#/components/schemas/UpdateRoleRequestBody"
         required: true
       responses:
         "200":
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/RoleView"
+                $ref: "#/components/schemas/RoleResource"
           description: OK
         default:
           content:
@@ -1843,7 +1884,8 @@ paths:
         - Role
   /api/v1/projects/{projectId}/ssh-keys:
     get:
-      operationId: list-project-ssh-keys
+      description: 归成员的和归项目的都在里面，靠每一条上的 owner_user_id 区分。
+      operationId: list-ssh-keys
       parameters:
         - description: Bearer 令牌。选定项目之前用 auth.leaflow.net 签发的账号令牌，选定之后用项目令牌
           in: header
@@ -1852,24 +1894,25 @@ paths:
           schema:
             description: Bearer 令牌。选定项目之前用 auth.leaflow.net 签发的账号令牌，选定之后用项目令牌
             type: string
-        - description: 这一页最多返回多少条，0 表示用默认值
+        - description: 这一页最多返回多少条
           explode: false
           in: query
           name: limit
           schema:
             default: 50
-            description: 这一页最多返回多少条，0 表示用默认值
+            description: 这一页最多返回多少条
             format: int64
-            maximum: 100
-            minimum: 0
+            maximum: 200
+            minimum: 1
             type: integer
-        - description: 跳过多少条
+        - description: 跳过多少条。要翻得更深请改用游标翻页的接口
           explode: false
           in: query
           name: offset
           schema:
-            description: 跳过多少条
+            description: 跳过多少条。要翻得更深请改用游标翻页的接口
             format: int64
+            maximum: 10000
             minimum: 0
             type: integer
         - in: path
@@ -1878,20 +1921,30 @@ paths:
           schema:
             format: uuid
             type: string
-        - explode: false
+        - description: 不传时两种都返回
+          explode: false
           in: query
           name: status
           schema:
+            description: 不传时两种都返回
             enum:
               - ACTIVE
               - REVOKED
             type: string
+        - description: 只列挂着这个用途的钥匙。平台自己生成的那把是 platform
+          explode: false
+          in: query
+          name: purpose
+          schema:
+            description: 只列挂着这个用途的钥匙。平台自己生成的那把是 platform
+            maxLength: 64
+            type: string
       responses:
         "200":
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ListSSHKeysOutputBody"
+                $ref: "#/components/schemas/LengthAwarePageSSHKeyResource"
           description: OK
         default:
           content:
@@ -1899,11 +1952,12 @@ paths:
               schema:
                 $ref: "#/components/schemas/Error"
           description: Error
-      summary: 列出项目的公钥
+      summary: 列出这个项目的公钥
       tags:
         - SSHKey
     post:
-      operationId: create-project-ssh-key
+      description: owner=me 是自己的，是成员就能加；owner=project 是项目公用的，要 iam:ssh_keys.manage —— 它会进这个项目之后开出来的每一台机器。
+      operationId: create-ssh-key
       parameters:
         - description: Bearer 令牌。选定项目之前用 auth.leaflow.net 签发的账号令牌，选定之后用项目令牌
           in: header
@@ -1922,14 +1976,14 @@ paths:
         content:
           application/json:
             schema:
-              $ref: "#/components/schemas/CreateProjectSSHKeyInputBody"
+              $ref: "#/components/schemas/CreateSSHKeyRequestBody"
         required: true
       responses:
         "201":
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/SSHKeyView"
+                $ref: "#/components/schemas/SSHKeyResource"
           description: Created
         default:
           content:
@@ -1937,12 +1991,13 @@ paths:
               schema:
                 $ref: "#/components/schemas/Error"
           description: Error
-      summary: 给项目添加一把公钥
+      summary: 添加一把公钥
       tags:
         - SSHKey
   /api/v1/projects/{projectId}/ssh-keys/{keyId}:
     delete:
-      operationId: revoke-project-ssh-key
+      description: 行留着，状态变成 REVOKED。事故之后要问的是当时信任的是哪把钥匙。
+      operationId: revoke-ssh-key
       parameters:
         - description: Bearer 令牌。选定项目之前用 auth.leaflow.net 签发的账号令牌，选定之后用项目令牌
           in: header
@@ -1968,7 +2023,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/SSHKeyView"
+                $ref: "#/components/schemas/SSHKeyResource"
           description: OK
         default:
           content:
@@ -1976,11 +2031,11 @@ paths:
               schema:
                 $ref: "#/components/schemas/Error"
           description: Error
-      summary: 吊销项目的一把公钥
+      summary: 吊销一把公钥
       tags:
         - SSHKey
     get:
-      operationId: get-project-ssh-key
+      operationId: get-ssh-key
       parameters:
         - description: Bearer 令牌。选定项目之前用 auth.leaflow.net 签发的账号令牌，选定之后用项目令牌
           in: header
@@ -2006,7 +2061,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/SSHKeyView"
+                $ref: "#/components/schemas/SSHKeyResource"
           description: OK
         default:
           content:
@@ -2014,11 +2069,12 @@ paths:
               schema:
                 $ref: "#/components/schemas/Error"
           description: Error
-      summary: 查看项目的一把公钥
+      summary: 查看一把公钥
       tags:
         - SSHKey
     patch:
-      operationId: rename-project-ssh-key
+      description: 只有名字能改：公钥、类型、指纹是同一样东西的三种说法，改其中一个会让这一行描述一把并不存在的钥匙。
+      operationId: rename-ssh-key
       parameters:
         - description: Bearer 令牌。选定项目之前用 auth.leaflow.net 签发的账号令牌，选定之后用项目令牌
           in: header
@@ -2043,14 +2099,14 @@ paths:
         content:
           application/json:
             schema:
-              $ref: "#/components/schemas/RenameProjectSSHKeyInputBody"
+              $ref: "#/components/schemas/RenameSSHKeyRequestBody"
         required: true
       responses:
         "200":
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/SSHKeyView"
+                $ref: "#/components/schemas/SSHKeyResource"
           description: OK
         default:
           content:
@@ -2058,7 +2114,7 @@ paths:
               schema:
                 $ref: "#/components/schemas/Error"
           description: Error
-      summary: 给项目的公钥改名
+      summary: 给公钥改名
       tags:
         - SSHKey
   /api/v1/projects/{projectId}/token:
@@ -2093,7 +2149,7 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/ExchangeTokenOutputBody"
+                $ref: "#/components/schemas/ProjectTokenResponseBody"
           description: Created
         default:
           content:
@@ -2126,14 +2182,14 @@ paths:
         content:
           application/json:
             schema:
-              $ref: "#/components/schemas/TransferOwnershipInputBody"
+              $ref: "#/components/schemas/TransferOwnershipRequestBody"
         required: true
       responses:
         "200":
           content:
             application/json:
               schema:
-                $ref: "#/components/schemas/TransferOwnershipOutputBody"
+                $ref: "#/components/schemas/OwnershipTransferResponseBody"
           description: OK
         default:
           content:
@@ -2144,4 +2200,43 @@ paths:
       summary: 转移项目所有权
       tags:
         - Member
+  /api/v1/register:
+    post:
+      description: |-
+        在 auth.leaflow.net 登录之后调它，带上账号令牌。姓名和邮箱取自登录信息，不从请求体收。
+
+        `consents` 要覆盖 `GET /api/v1/agreements` 返回的每一份，版本号也要一致；漏一份答 400，版本对不上答 409（多半是页面开着的时候条款改版了，重新拉一次清单即可）。已经注册过的答 409。
+      operationId: register
+      parameters:
+        - description: auth.leaflow.net 签发的账号令牌，形如 Bearer <token>
+          in: header
+          name: Authorization
+          required: true
+          schema:
+            description: auth.leaflow.net 签发的账号令牌，形如 Bearer <token>
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/RegisterRequestBody"
+        required: true
+      responses:
+        "201":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AccountResource"
+          description: Created
+        default:
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+          description: Error
+      summary: 注册账号
+      tags:
+        - Account
+security:
+  - bearerAuth: []