Agent registration operations

Chain 77 is production. Public registration creates an empty assigned wallet and a bearer token with read and transfer; it never gives faucet capability or credits funds.

Private console

Open /admin/agents on the private backend origin, through the operator network or an SSH tunnel. This path is not served by poa.net/77. The HTML shell has no operational data. Enter the existing admin API token to load data; changing settings or account access additionally requires AGENT_REGISTRATION_ADMIN_SECRET. Credentials stay in page memory, are sent only as headers to the same private origin, and are cleared on navigation. Use HTTPS, or loopback through an authenticated SSH tunnel.

The console shows durable issuance and admission counters, remaining verified keys, current quotas, the latest 50 public identities and hashed IP groups. It also shows up to 200 local API buckets for the last 60 seconds. API counters reset on restart and are per node, not cluster-wide. The current API limit is 600 requests per agent per 60 seconds per node. Registration counters exclude malformed requests and requests rejected by the edge or the local early limiter; they measure durable admission attempts, not total HTTP traffic. Paused or globally exhausted policies reject on a read-only precheck and do not increment admission counters.

Enablement

1. Deploy the backend migration and registration API with issuance disabled. Deploy the Explorer form and its Worker ingress contract before enabling issuance.
2. Set AGENT_GATEWAY_ENABLED=true, AGENT_PUBLIC_REGISTRATION_ENABLED=true, independent random secrets of at least 32 bytes in AGENT_REGISTRATION_IP_SECRET and AGENT_REGISTRATION_ADMIN_SECRET, and the existing edge host, edge shared secret and trusted proxy configuration. Do not place secrets in source control or public Worker variables. The database policy initially remains paused.
3. Set Cloudflare Pseudo IPv4 to off or add-header mode (not overwrite mode). Check that the public Worker overwrites X-2d-Registration-IP from Cloudflare’s client metadata and authenticates to the origin. Registration rejects missing, malformed, private or collapsed Worker IP assertions. Do not trust client-supplied XFF or widen the private /admin route through the tunnel. A cross-site form or fetch must fail without consuming a key.
4. Provision verified, backed-up keys. Review the daily and lifetime ceilings and reserve against the actual pool size and refill capacity. Defaults are 3 successful registrations/IP/day, 100 globally/day, lifetime 1,000, reserve 10. These are initial settings, not a production sizing recommendation.
5. Unpause with a reason in the console. Check one authorized registration, its assigned wallet, the audit entry and counters. Save its token before funding it. Keep transfer policy, amount ceilings, canary and recovery evidence checks independent of registration.

The Worker must be published before enabling the backend: older Workers do not forward the required registration headers, so issuance fails closed.

Limits and response handling

Daily windows use UTC. Durable attempt caps are 10/IP/minute and 120 globally/minute, backed by PostgreSQL; IPv6 is grouped by /64. Global issuance ceilings remain necessary because an attacker can control many IPs. Public issuers serialize on one policy row, while key claim, success counters and issuance journal commit together. Admission commits separately, so a provisioning failure cannot refund the attempt budget.

429 carries Retry-After. 503 means issuance is disabled, paused, at its lifetime ceiling, short of verified keys, or unavailable. A lost response may have committed an identity: never automatically retry registration. No token recovery or key recycling is offered. Assigned wallets can receive funds later, so apparently unused keys are not returned to the pool.

The key reserve governs public issuance only. Operator provisioning can use the same pool, including its reserve; coordinate refill and manual issuance. Alert on low verified capacity, rising rejections/failures and sustained exhaustion of daily or lifetime budgets. The console does not send alerts automatically.

Settings changes record before/after values and a reason. Account disablement is reversible and affects API authentication on subsequent requests; it neither moves funds nor cancels an already submitted transaction. This console uses shared operator credentials, so the audit does not identify an individual human. Manage credential access and incident evidence separately. A leaked bearer token requires an operator recovery plan before any re-enablement.

API contract

Private reads: GET /admin/agents/registration, header x-admin-api-token. Private mutations: POST /admin/agents/registration/settings and /identity, additionally requiring x-registration-admin-token. Unknown settings, invalid ranges and empty reasons are rejected. No admin route is exposed through the public Worker.

Public registration: POST https://poa.net/77/agent/v1/register, Content-Type: application/json, X-POA-Registration: 1, body {}. Browser registration is same-origin; server clients may omit Origin. A successful response is 201 with token, agent ID, assigned wallet, capabilities and chain ID. It must never be logged or cached.

To stop issuance immediately, pause in the console. To remove the public surface, also turn off AGENT_PUBLIC_REGISTRATION_ENABLED. Existing tokens and independent transfer policies are unchanged by a registration pause. Preserve the migration, journal and lifetime counters during rollback.