# 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_REGULATORY_PROFILE_ID` (`us_general_2026` default, `eu_ai_act_2026_baseline` supported)
- `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`)