From bd32c3cad45484cd5fb3d6fef2fa7581f6c1a0b6 Mon Sep 17 00:00:00 2001 From: Joshua Date: Wed, 18 Feb 2026 20:57:08 -0800 Subject: [PATCH] Sync membership docs with wallet session lifecycle endpoints --- .../membership-platform-interfaces.md | 8 +++-- docs/deployment/secretapi-deploy.md | 20 +++++++------ docs/handoff/membership-backend-checklist.md | 30 +++++++++++++++++-- docs/roadmap-membership-platform.md | 2 ++ docs/secret-system-spec.md | 13 ++++++-- 5 files changed, 56 insertions(+), 17 deletions(-) diff --git a/docs/contracts/membership-platform-interfaces.md b/docs/contracts/membership-platform-interfaces.md index d2626d8..8b40885 100644 --- a/docs/contracts/membership-platform-interfaces.md +++ b/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` -4. `POST /secret/membership/confirm` -5. `GET /secret/membership/status?designation_code=...` +3. `POST /secret/wallet/session/refresh` +4. `POST /secret/wallet/session/revoke` +5. `POST /secret/membership/quote` +6. `POST /secret/membership/confirm` +7. `GET /secret/membership/status?designation_code=...` ## Marketplace diff --git a/docs/deployment/secretapi-deploy.md b/docs/deployment/secretapi-deploy.md index 3447502..795f498 100644 --- a/docs/deployment/secretapi-deploy.md +++ b/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. -3. `POST /secret/membership/quote` returns tx payload. -4. `POST /secret/membership/confirm` marks membership active. -5. `POST /governance/install/token` enforces owner role and active membership. -6. `POST /governance/install/confirm` enforces package/runtime/policy match. -7. `GET /governance/install/status` resolves deterministic activation state. -8. `POST /member/channel/device/register` returns active channel binding. -9. `GET /member/channel/events` returns deterministic inbox page. -10. `POST /member/channel/events/{event_id}/ack` is idempotent per event+device. +2. `POST /secret/wallet/verify` accepts valid EIP-712 signature and returns `session_token`. +3. `POST /secret/wallet/session/refresh` rotates wallet session token. +4. `POST /secret/wallet/session/revoke` revokes wallet session token. +5. `POST /secret/membership/quote` returns tx payload. +6. `POST /secret/membership/confirm` marks membership active. +7. `POST /governance/install/token` enforces owner role and active membership. +8. `POST /governance/install/confirm` enforces package/runtime/policy match. +9. `GET /governance/install/status` resolves deterministic activation state. +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. diff --git a/docs/handoff/membership-backend-checklist.md b/docs/handoff/membership-backend-checklist.md index 5e736bc..2336d94 100644 --- a/docs/handoff/membership-backend-checklist.md +++ b/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` -4. `POST /secret/membership/confirm` -5. `GET /secret/membership/status` +3. `POST /secret/wallet/session/refresh` +4. `POST /secret/wallet/session/revoke` +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 diff --git a/docs/roadmap-membership-platform.md b/docs/roadmap-membership-platform.md index a126a79..838c9a3 100644 --- a/docs/roadmap-membership-platform.md +++ b/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 diff --git a/docs/secret-system-spec.md b/docs/secret-system-spec.md index 2524e8b..ec59e5f 100644 --- a/docs/secret-system-spec.md +++ b/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, -3. membership gates all future marketplace purchases. +2. verify issues wallet session for fail-closed control-plane access, +3. paid mint proves intent, +4. membership gates all future marketplace purchases.