web/backend/secretapi/README.md

Secret API Backend (secretapi)

Deterministic backend for wallet-first designation, EDUT ID activation metadata, and governance install authorization.

Run

cd <home>/Documents/VSG\ Codex/web/backend/secretapi
go run .

Default listen address is :8080.

Test

cd <home>/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)
• GET /secret/setup/health (deterministic setup readiness checks for wallet/session/membership/assurance/principal state)
• POST /secret/id/mint-payload (direct wallet mint payload, no quote dependency)

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

Member channel feed includes deterministic anti-noise throttling:

1. when event volume exceeds configured burst limits in a window, direct events are suppressed
2. a single channel_digest card is inserted per window with grouped context and aggregated suppressed_count
3. throttling is fail-closed deterministic and does not require external services

GET /member/channel/events now also returns digest summary fields:

1. digest_active
2. digest_suppressed_count

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>
3. Optional stronger replay binding: X-Edut-Device-Binding: <stable-device-secret>

If a session was issued with a device binding (or user-agent fallback binding), requests from a different binding context are rejected with wallet_session_context_mismatch.

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 active membership and org-root-owner role.
3. Governance admin controls (install token issuance, lease heartbeat/offline renew, owner support tickets) require org_root_owner role and additionally require onramp_attested identity assurance (identity_assurance_insufficient when unmet).

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.

Quote endpoints accept optional payment_path:

1. crypto_direct (default)
2. fiat_onramp

When the on-ramp dependency edge is degraded, fiat_onramp fails closed with dependency.onramp_unavailable while crypto_direct remains available.

Financial approval thresholds:

1. when SECRET_API_FINANCIAL_APPROVAL_THRESHOLD_ATOMIC > 0, quote responses include approval_required=true and deterministic approval_reason when total_amount_atomic exceeds the threshold.
2. threshold-gated confirms fail closed with approval_required unless both approval_token and approval_actor are supplied.
3. confirm responses persist only approval_token_ref (hash reference), never raw approval token material.

Chain-settlement confirmations (/secret/membership/confirm, /marketplace/checkout/confirm) also fail closed when chain-adjacent dependency edges are degraded:

1. dependency.dns_unavailable
2. dependency.tls_unavailable
3. dependency.chain_unavailable

Error envelope contract:

1. all non-2xx responses return deterministic code + error + correlation_id.
2. responses now also include deterministic next_step guidance for remediation/retry.
3. /marketplace/checkout/confirm now enforces setup readiness before high-impact entitlement activation:
   • if membership is not active and the quote is not a bundled membership activation quote, confirm fails closed with setup_incomplete.
   • recovery path is deterministic via GET /secret/setup/health?wallet=....

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_DEPENDENCY_RECOVERY_STABILITY_SECONDS (default 60; hold window before degraded-edge recovery)
• SECRET_API_DEPENDENCY_CHAIN_STATE (auto|healthy|degraded; default auto)
• SECRET_API_DEPENDENCY_TLS_STATE (auto|healthy|degraded; default auto)
• SECRET_API_DEPENDENCY_DNS_STATE (auto|healthy|degraded; default auto)
• SECRET_API_DEPENDENCY_ONRAMP_STATE (auto|healthy|degraded; default auto)
• SECRET_API_DEPENDENCY_CLOUD_STATE (auto|healthy|degraded; default auto)
• SECRET_API_DEPENDENCY_MODEL_STATE (auto|healthy|degraded; default auto)
• SECRET_API_MEMBER_POLL_INTERVAL_SECONDS (default 30)
• SECRET_API_MEMBER_CHANNEL_EVENT_BURST_LIMIT (default 25; set 0 to disable channel event throttling)
• SECRET_API_MEMBER_CHANNEL_EVENT_BURST_WINDOW_SECONDS (default 3600; required positive when burst limit is enabled)
• 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 (ETH default for gas-only EDUT ID; USDC optional)
• SECRET_API_MINT_AMOUNT_ATOMIC (default 0 for gas-only EDUT ID mint)
• SECRET_API_MINT_DECIMALS (must be 6 for USDC, 18 for ETH)
• SECRET_API_FINANCIAL_APPROVAL_THRESHOLD_ATOMIC (default 0; when greater than 0, marketplace checkout confirmations above threshold require explicit approval_token and approval_actor)

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)