180 lines
6.2 KiB
Markdown
180 lines
6.2 KiB
Markdown
# Secret API Backend (`secretapi`)
|
|
|
|
Deterministic backend for wallet-first designation, EDUT ID activation, and governance install authorization.
|
|
|
|
## Run
|
|
|
|
```bash
|
|
cd /Users/vsg/Documents/VSG\ Codex/web/backend/secretapi
|
|
go run .
|
|
```
|
|
|
|
Default listen address is `:8080`.
|
|
|
|
## Test
|
|
|
|
```bash
|
|
cd /Users/vsg/Documents/VSG\ Codex/web/backend/secretapi
|
|
go test ./...
|
|
```
|
|
|
|
## Environment Template
|
|
|
|
Copy `.env.example` in this folder and set contract/runtime values before deploy.
|
|
`secretapi` validates config at startup and fails closed if strict chain verification is enabled without RPC.
|
|
|
|
## Endpoint Surface
|
|
|
|
### Membership
|
|
|
|
- `POST /secret/wallet/intent`
|
|
- `POST /secret/wallet/verify`
|
|
- `POST /secret/wallet/session/refresh`
|
|
- `POST /secret/wallet/session/revoke`
|
|
- `POST /secret/membership/quote`
|
|
- `POST /secret/membership/confirm`
|
|
- `GET /secret/membership/status`
|
|
- `POST /secret/id/quote` (alias to membership quote)
|
|
- `POST /secret/id/confirm` (alias to membership confirm)
|
|
- `GET /secret/id/status` (alias to membership status)
|
|
|
|
### Marketplace
|
|
|
|
- `GET /marketplace/offers`
|
|
- `GET /marketplace/offers/{offer_id}`
|
|
- `POST /marketplace/checkout/quote`
|
|
- `POST /marketplace/checkout/confirm`
|
|
- `GET /marketplace/entitlements`
|
|
|
|
### Governance install + availability
|
|
|
|
- `POST /governance/install/token`
|
|
- `POST /governance/install/confirm`
|
|
- `GET /governance/install/status`
|
|
- `POST /governance/lease/heartbeat`
|
|
- `POST /governance/lease/offline-renew`
|
|
|
|
### Member app channel
|
|
|
|
- `POST /member/channel/device/register`
|
|
- `POST /member/channel/device/unregister`
|
|
- `GET /member/channel/events`
|
|
- `POST /member/channel/events/{event_id}/ack`
|
|
- `POST /member/channel/support/ticket`
|
|
|
|
## Wallet Session Hardening
|
|
|
|
`POST /secret/wallet/verify` now issues a wallet session token:
|
|
|
|
1. Response fields: `session_token`, `session_expires_at`
|
|
2. Response headers: `X-Edut-Session`, `X-Edut-Session-Expires-At`
|
|
|
|
When `SECRET_API_REQUIRE_WALLET_SESSION=true`, wallet-scoped control-plane endpoints fail closed unless a valid session token is provided via:
|
|
|
|
1. `Authorization: Bearer <session_token>`
|
|
2. `X-Edut-Session: <session_token>`
|
|
|
|
Covered endpoints include marketplace checkout/entitlements, governance install/lease actions, and member-channel calls.
|
|
|
|
Session lifecycle endpoints:
|
|
|
|
1. `POST /secret/wallet/session/refresh`: rotates the current session token and revokes the prior token.
|
|
2. `POST /secret/wallet/session/revoke`: revokes the current token immediately.
|
|
|
|
## Sponsorship Behavior
|
|
|
|
Membership quote supports ownership wallet and distinct payer wallet:
|
|
|
|
- `address`: ownership wallet (required)
|
|
- `payer_wallet`: optional payer wallet
|
|
- `payer_proof`: required when payer differs from owner
|
|
|
|
Distinct payer proof uses owner-signed personal message:
|
|
|
|
`EDUT-PAYER-AUTH:{designation_code}:{owner_wallet}:{payer_wallet}:{chain_id}`
|
|
|
|
This enables company-sponsored mint flows while preserving deterministic owner authorization.
|
|
|
|
Company-first sponsor path is also supported:
|
|
|
|
- If `sponsor_org_root_id` is provided and the `payer_wallet` is a stored `org_root_owner` principal for that org root with active entitlement status, quote issuance is allowed without `payer_proof`.
|
|
|
|
## Identity Assurance Model
|
|
|
|
Membership activation and identity assurance are stored as separate facts:
|
|
|
|
1. `membership_status`
|
|
2. `identity_assurance_level`
|
|
|
|
Assurance levels:
|
|
|
|
1. `none`
|
|
2. `crypto_direct_unattested`
|
|
3. `sponsored_unattested`
|
|
4. `onramp_attested`
|
|
|
|
`onramp_attested` can be set during membership confirm only on self-paid quotes and requires `identity_attested_by`.
|
|
|
|
Policy gates:
|
|
|
|
1. Store checkout requires active membership.
|
|
2. Workspace admin install/support actions require `onramp_attested` assurance.
|
|
|
|
## Quote Cost Envelope
|
|
|
|
`POST /secret/membership/quote` and `POST /marketplace/checkout/quote` return a deterministic `cost_envelope` object.
|
|
|
|
The envelope is pre-execution pricing metadata and is authoritative for checkout presentation:
|
|
|
|
1. `checkout_total_atomic` and `checkout_total` are the user checkout totals.
|
|
2. `provider_fee_policy=edut_absorbed` means on-ramp processing fees are absorbed by EDUT.
|
|
3. `network_fee_policy=payer_wallet_pays_chain_gas` means chain gas remains wallet-dependent and separate from checkout total.
|
|
|
|
## Key Environment Variables
|
|
|
|
### Core
|
|
|
|
- `SECRET_API_LISTEN_ADDR` (default `:8080`)
|
|
- `SECRET_API_DB_PATH` (default `./secret.db`)
|
|
- `SECRET_API_ALLOWED_ORIGIN` (default `https://edut.ai`)
|
|
- `SECRET_API_DEPLOYMENT_CLASS` (`development|staging|production`; default `development`)
|
|
- `SECRET_API_MEMBER_POLL_INTERVAL_SECONDS` (default `30`)
|
|
- `SECRET_API_CHAIN_ID` (default `84532`)
|
|
- `SECRET_API_CHAIN_RPC_URL` (optional, enables on-chain tx receipt verification)
|
|
- `SECRET_API_REQUIRE_ONCHAIN_TX_VERIFICATION`:
|
|
- if explicitly set, value is honored.
|
|
- if unset, defaults to `true` when `SECRET_API_DEPLOYMENT_CLASS=production`, else `false`.
|
|
- when enabled, membership confirm and marketplace checkout confirm fail closed without chain receipt verification.
|
|
- `SECRET_API_ENTITLEMENT_CONTRACT` (optional; when set, marketplace quote emits purchase calldata for entitlement settlement contract)
|
|
|
|
### Membership
|
|
|
|
- `SECRET_API_INTENT_TTL_SECONDS` (default `900`)
|
|
- `SECRET_API_QUOTE_TTL_SECONDS` (default `900`)
|
|
- `SECRET_API_WALLET_SESSION_TTL_SECONDS` (default `2592000`)
|
|
- `SECRET_API_REQUIRE_WALLET_SESSION` (default `true`; set `false` only for controlled local harness/debug usage)
|
|
- `SECRET_API_DOMAIN_NAME`
|
|
- `SECRET_API_VERIFYING_CONTRACT`
|
|
- `SECRET_API_MEMBERSHIP_CONTRACT`
|
|
- `SECRET_API_MINT_CURRENCY` (`USDC` for launch; `ETH` allowed for Sepolia/test harness)
|
|
- `SECRET_API_MINT_AMOUNT_ATOMIC` (default `100000000`)
|
|
- `SECRET_API_MINT_DECIMALS` (must be `6` for `USDC`, `18` for `ETH`)
|
|
|
|
### Marketplace
|
|
|
|
- `SECRET_API_ENTITLEMENT_CONTRACT` must be configured to issue checkout quotes.
|
|
- Marketplace quote fails closed with `entitlement_contract_unconfigured` when unset/zero.
|
|
|
|
### Governance install
|
|
|
|
- `SECRET_API_INSTALL_TOKEN_TTL_SECONDS` (default `900`)
|
|
- `SECRET_API_LEASE_TTL_SECONDS` (default `3600`)
|
|
- `SECRET_API_OFFLINE_RENEW_TTL_SECONDS` (default `2592000`)
|
|
- `SECRET_API_GOV_RUNTIME_VERSION`
|
|
- `SECRET_API_GOV_PACKAGE_URL`
|
|
- `SECRET_API_GOV_PACKAGE_HASH`
|
|
- `SECRET_API_GOV_PACKAGE_SIGNATURE`
|
|
- `SECRET_API_GOV_SIGNER_KEY_ID`
|
|
- `SECRET_API_GOV_POLICY_HASH`
|
|
- `SECRET_API_GOV_ROLLOUT_CHANNEL` (default `stable`)
|