Add anonymous OOBE gateway grants

Provide App Attest-bound, one-time onboarding AI access without creating accounts, with durable replay protection and production deployment safeguards.

docs/DEPLOYMENT.md

@@ -97,6 +97,10 @@ Apple 配置使用所属开发者账号的 Team ID、Key ID、bundle ID 和 `.p8
 v3 WSS endpoint、资源 ID 和 API Key；DeepSeek 使用 HTTPS endpoint、已开通模型名和 API Key。
 三方凭据分别创建、分别轮换，不得复用。
 
+生产默认仅接受 TestFlight 与 App Store 构建的 production App Attest。确需让已登记真机上的
+Xcode Development 构建连接生产服务时，可临时设置
+`ALLOW_DEVELOPMENT_APP_ATTEST=true`；完成测试后应立即恢复为 `false` 并重启服务。
+
 ## 5. 构建与启动
 
 GitHub CI 在测试通过后发布私有镜像

docs/mysql-minimum-privileges.sql

@@ -31,6 +31,11 @@ GRANT SELECT ON osg_account.gateway_grants TO 'osg_account_runtime'@'10.20.%';
 GRANT SELECT ON osg_account.gateway_grant_scopes TO 'osg_account_runtime'@'10.20.%';
 GRANT SELECT ON osg_account.gateway_refresh_tokens TO 'osg_account_runtime'@'10.20.%';
 GRANT SELECT ON osg_account.gateway_complimentary_requests TO 'osg_account_runtime'@'10.20.%';
+GRANT SELECT ON osg_account.oobe_subjects TO 'osg_account_runtime'@'10.20.%';
+GRANT SELECT ON osg_account.oobe_gateway_grants TO 'osg_account_runtime'@'10.20.%';
+GRANT SELECT ON osg_account.oobe_gateway_refresh_tokens TO 'osg_account_runtime'@'10.20.%';
+GRANT SELECT ON osg_account.oobe_gateway_claims TO 'osg_account_runtime'@'10.20.%';
+GRANT SELECT ON osg_account.oobe_provider_requests TO 'osg_account_runtime'@'10.20.%';
 GRANT SELECT ON osg_account.devicecheck_trial_claims TO 'osg_account_runtime'@'10.20.%';
 GRANT SELECT ON osg_account.app_attest_challenges TO 'osg_account_runtime'@'10.20.%';
 GRANT SELECT ON osg_account.app_attest_keys TO 'osg_account_runtime'@'10.20.%';
@@ -72,6 +77,11 @@ GRANT INSERT ON osg_account.gateway_grant_scopes TO 'osg_account_runtime'@'10.20
 GRANT INSERT, UPDATE ON osg_account.gateway_refresh_tokens TO 'osg_account_runtime'@'10.20.%';
 GRANT INSERT, UPDATE, DELETE ON osg_account.gateway_complimentary_requests
     TO 'osg_account_runtime'@'10.20.%';
+GRANT INSERT ON osg_account.oobe_subjects TO 'osg_account_runtime'@'10.20.%';
+GRANT INSERT, UPDATE ON osg_account.oobe_gateway_grants TO 'osg_account_runtime'@'10.20.%';
+GRANT INSERT, UPDATE ON osg_account.oobe_gateway_refresh_tokens TO 'osg_account_runtime'@'10.20.%';
+GRANT INSERT, UPDATE, DELETE ON osg_account.oobe_gateway_claims TO 'osg_account_runtime'@'10.20.%';
+GRANT INSERT, UPDATE ON osg_account.oobe_provider_requests TO 'osg_account_runtime'@'10.20.%';
 GRANT INSERT, UPDATE ON osg_account.devicecheck_trial_claims TO 'osg_account_runtime'@'10.20.%';
 GRANT INSERT, UPDATE ON osg_account.app_attest_challenges TO 'osg_account_runtime'@'10.20.%';
 GRANT INSERT, UPDATE ON osg_account.app_attest_keys TO 'osg_account_runtime'@'10.20.%';

docs/openapi.yaml

@@ -381,6 +381,43 @@ paths:
       responses:
         "200": { description: Assertion counter advanced }
         default: { $ref: "#/components/responses/Error" }
+  /v1/oobe/grants:
+    post:
+      security: []
+      summary: Create a short-lived anonymous OOBE gateway grant
+      description: |
+        Verifies an App Attest assertion bound to the installation and returns
+        credentials limited to the four one-time onboarding AI features.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/CreateOobeGrantRequest" }
+      responses:
+        "201":
+          description: OOBE gateway credentials
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/OobeGrantTokens" }
+        default: { $ref: "#/components/responses/GatewayError" }
+  /v1/oobe/grants/refresh:
+    post:
+      security: []
+      summary: Rotate an anonymous OOBE refresh token
+      parameters:
+        - $ref: "#/components/parameters/IdempotencyKey"
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: "#/components/schemas/RefreshOobeGrantRequest" }
+      responses:
+        "200":
+          description: Rotated OOBE gateway credentials
+          content:
+            application/json:
+              schema: { $ref: "#/components/schemas/OobeGrantTokens" }
+        default: { $ref: "#/components/responses/GatewayError" }
   /v1/gateway/catalog:
     get:
       summary: Return configured managed-provider capabilities
@@ -441,9 +478,10 @@ paths:
         and output-budget policy from `capability` plus optional `taskKind`. It
         never infers task type from `input` or `context`, and clients cannot
         supply provider parameters. Search and tools are currently disabled.
-        An authenticated `oobe` purpose is accepted only for dictation polish.
-        The first successful request per account is complimentary; later attempts
-        fail without falling through to paid billing.
+        For account grants, `oobe` is accepted only for dictation polish and the
+        first successful request per account is complimentary. Anonymous OOBE
+        grants require a matching `oobeFeature` and allow one successful request
+        per feature. Later attempts fail without falling through to paid billing.
       parameters:
         - $ref: "#/components/parameters/RequestId"
         - name: capability
@@ -2629,8 +2667,51 @@ components:
           type: ["string", "null"]
           enum: [oobe, null]
           description: |
-            Optional server-audited billing purpose. `oobe` is valid only with
-            `polish` and `dictation_polish`, and is complimentary once per account.
+            Optional server-audited billing purpose. Account grants accept `oobe`
+            only for complimentary dictation polish. Anonymous OOBE grants require
+            `oobe` together with an `oobeFeature`.
+        oobeFeature:
+          type: ["string", "null"]
+          enum: [voice_input, clipboard_translate, clipboard_reply, ask_ai, null]
+          description: |
+            Required for anonymous OOBE grants. The server validates that the
+            feature matches the requested capability and task kind, and allows
+            each feature to succeed only once per installation-bound subject.
+    CreateOobeGrantRequest:
+      type: object
+      additionalProperties: false
+      required: [challengeId, challenge, keyId, installationId, assertion]
+      properties:
+        challengeId: { type: string, format: uuid }
+        challenge: { type: string, description: Base64URL challenge returned by the integrity API }
+        keyId: { type: string, minLength: 1, maxLength: 256 }
+        installationId: { type: string, format: uuid }
+        assertion: { type: string, contentEncoding: base64 }
+    RefreshOobeGrantRequest:
+      type: object
+      additionalProperties: false
+      required: [refreshToken]
+      properties:
+        refreshToken: { type: string, minLength: 32, maxLength: 512 }
+    OobeGrantTokens:
+      type: object
+      additionalProperties: false
+      required:
+        [grantId, scopes, features, accessToken, accessExpiresAt, refreshToken, refreshExpiresAt]
+      properties:
+        grantId: { type: string, format: uuid }
+        scopes:
+          type: array
+          uniqueItems: true
+          items: { type: string, enum: [polish, ai] }
+        features:
+          type: array
+          uniqueItems: true
+          items: { type: string, enum: [voice_input, clipboard_translate, clipboard_reply, ask_ai] }
+        accessToken: { type: string }
+        accessExpiresAt: { type: string, format: date-time }
+        refreshToken: { type: string }
+        refreshExpiresAt: { type: string, format: date-time }
     CreateGatewayGrantRequest:
       type: object
       additionalProperties: false