Sync membership docs with wallet session lifecycle endpoints

docs/contracts/membership-platform-interfaces.md

@@ -88,9 +88,11 @@ PrincipalRole:
 
 1. `POST /secret/wallet/intent`
 2. `POST /secret/wallet/verify`
-3. `POST /secret/membership/quote`
+3. `POST /secret/wallet/session/refresh`
-4. `POST /secret/membership/confirm`
+4. `POST /secret/wallet/session/revoke`
-5. `GET /secret/membership/status?designation_code=...`
+5. `POST /secret/membership/quote`
+6. `POST /secret/membership/confirm`
+7. `GET /secret/membership/status?designation_code=...`
 
 ## Marketplace
 

docs/deployment/secretapi-deploy.md

@@ -66,12 +66,14 @@ Expected:
 ## Post-Deploy Verification
 
 1. `POST /secret/wallet/intent` returns `intent_id` and `designation_code`.
-2. `POST /secret/wallet/verify` accepts valid EIP-712 signature.
+2. `POST /secret/wallet/verify` accepts valid EIP-712 signature and returns `session_token`.
-3. `POST /secret/membership/quote` returns tx payload.
+3. `POST /secret/wallet/session/refresh` rotates wallet session token.
-4. `POST /secret/membership/confirm` marks membership active.
+4. `POST /secret/wallet/session/revoke` revokes wallet session token.
-5. `POST /governance/install/token` enforces owner role and active membership.
+5. `POST /secret/membership/quote` returns tx payload.
-6. `POST /governance/install/confirm` enforces package/runtime/policy match.
+6. `POST /secret/membership/confirm` marks membership active.
-7. `GET /governance/install/status` resolves deterministic activation state.
+7. `POST /governance/install/token` enforces owner role and active membership.
-8. `POST /member/channel/device/register` returns active channel binding.
+8. `POST /governance/install/confirm` enforces package/runtime/policy match.
-9. `GET /member/channel/events` returns deterministic inbox page.
+9. `GET /governance/install/status` resolves deterministic activation state.
-10. `POST /member/channel/events/{event_id}/ack` is idempotent per event+device.
+10. `POST /member/channel/device/register` returns active channel binding.
+11. `GET /member/channel/events` returns deterministic inbox page.
+12. `POST /member/channel/events/{event_id}/ack` is idempotent per event+device.

docs/handoff/membership-backend-checklist.md

@@ -10,9 +10,11 @@ Current implementation target in this repo:
 
 1. `POST /secret/wallet/intent`
 2. `POST /secret/wallet/verify`
-3. `POST /secret/membership/quote`
+3. `POST /secret/wallet/session/refresh`
-4. `POST /secret/membership/confirm`
+4. `POST /secret/wallet/session/revoke`
-5. `GET /secret/membership/status`
+5. `POST /secret/membership/quote`
+6. `POST /secret/membership/confirm`
+7. `GET /secret/membership/status`
 
 ## Web Behavior Dependency
 
@@ -50,6 +52,25 @@ Must return:
 1. `status = signature_verified`
 2. `designation_code`
 3. `display_token`
+4. `session_token`
+5. `session_expires_at`
+
+## Wallet Session Refresh
+
+Must return:
+
+1. `status = session_refreshed`
+2. `wallet`
+3. `session_token`
+4. `session_expires_at`
+
+## Wallet Session Revoke
+
+Must return:
+
+1. `status = session_revoked`
+2. `wallet`
+3. `revoked_at`
 
 ## Membership Quote
 
@@ -102,6 +123,9 @@ Must return:
 10. Optional strict chain verification mode:
    - when `SECRET_API_REQUIRE_ONCHAIN_TX_VERIFICATION=true`,
    - membership confirm must fail closed if chain RPC verification is unavailable.
+11. Wallet-session fail-closed mode:
+   - when `SECRET_API_REQUIRE_WALLET_SESSION=true`,
+   - wallet-scoped APIs must reject missing/invalid/revoked/expired sessions.
 
 ## Data Persistence Requirements
 

docs/roadmap-membership-platform.md

@@ -29,6 +29,8 @@ This roadmap is intentionally step-based and dependency-ordered. No timeline com
 2. EIP-712 signature proves wallet possession.
 3. Server verify endpoint enforces replay protection and origin checks.
 4. Intent payload includes price/currency/deadline for explicit consent.
+5. Verify response issues wallet session token with deterministic expiry.
+6. Session lifecycle includes rotate (`/secret/wallet/session/refresh`) and revoke (`/secret/wallet/session/revoke`) controls.
 
 ## Step 5: Add Membership Mint Transaction Stage
 

docs/secret-system-spec.md

@@ -367,6 +367,14 @@ location /secret/wallet/verify {
     proxy_pass http://127.0.0.1:9091;
 }
 
+location /secret/wallet/session/refresh {
+    proxy_pass http://127.0.0.1:9091;
+}
+
+location /secret/wallet/session/revoke {
+    proxy_pass http://127.0.0.1:9091;
+}
+
 location /secret/membership/quote {
     proxy_pass http://127.0.0.1:9091;
 }
@@ -382,5 +390,6 @@ location /secret/membership/confirm {
 The wallet-first designation plus paid membership flow creates a deterministic two-factor identity and commitment chain:
 
 1. signature proves wallet control,
-2. paid mint proves intent,
+2. verify issues wallet session for fail-closed control-plane access,
-3. membership gates all future marketplace purchases.
+3. paid mint proves intent,
+4. membership gates all future marketplace purchases.