# Secret API Backend (`secretapi`)

Deterministic backend for wallet-first designation, membership 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.

## Endpoint Surface

### Membership

- `POST /secret/wallet/intent`
- `POST /secret/wallet/verify`
- `POST /secret/membership/quote`
- `POST /secret/membership/confirm`
- `GET /secret/membership/status`

### 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`

## 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`.

## 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_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` (default `false`; when `true`, membership confirm fails closed without chain receipt verification)

### Membership

- `SECRET_API_INTENT_TTL_SECONDS` (default `900`)
- `SECRET_API_QUOTE_TTL_SECONDS` (default `900`)
- `SECRET_API_DOMAIN_NAME`
- `SECRET_API_VERIFYING_CONTRACT`
- `SECRET_API_MEMBERSHIP_CONTRACT`
- `SECRET_API_MINT_CURRENCY` (default `ETH`)
- `SECRET_API_MINT_AMOUNT_ATOMIC` (default `5000000000000000`)
- `SECRET_API_MINT_DECIMALS` (default `18`)

### 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`)