Gateway

Public hostnames, TLS certificates, and IP history for agent-hosted services. The gateway schema holds the ledger; the agent-gateway Cloud Function drives ACME and cert rotation.

Tables

Table	Purpose
gateway.hosts	(agent_id, host) unique records.
gateway.certs	Issued certificate chain, expiry, serial.
gateway.ip_history	Historical A/AAAA records per host.

Issuance flow

1. Agent calls /host/claim with a proposed hostname.
2. The function verifies agent_id owns it (via DNS CNAME or TXT check).
3. ACME order is triggered; certs are stored in gateway.certs.
4. gateway.cert_days_remaining(host) drives a renewal cron.

Routes

Method	Path	Purpose
POST	/host/claim	Start a new hostname.
POST	/host/release	Give it up.
POST	/cert/issue	Force an ACME issuance.
POST	/cert/renew	Renew before expiry.
POST	/ip/report	Report current IPs for a host.
POST	/list	List hosts + cert state for an agent.

Custom domains vs. DuckDNS

DuckDNS is the push-button path: the owner uploads a DuckDNS token once (setDuckDnsToken, KMS-wrapped), then issue({fqdn: 'alice.duckdns.org'}) runs the full DNS-01 exchange on the control plane using acme-client's auto flow. TXT propagation is confirmed in-band and cleared after the cert issues.

Custom domains cannot be automated the same way — AgentPack does not hold DNS credentials for arbitrary zones. Instead the flow is split:

1. claimHostname({fqdn, mode:'custom'}) — records intent.
2. acmeStart({fqdn}) — creates an ACME order, persists the intermediate state (account key, CSR, challenge URL) KMS-wrapped under owners/{uid}/acmeOrders/{id}, and returns {recordName, recordValue} for the owner to publish as a TXT at _acme-challenge.<fqdn>.
3. Owner publishes the TXT at their DNS provider.
4. acmeFinish({orderId}) — completes the challenge, finalizes the order, and writes the cert into owners/{uid}/certificates/{id}.

Renewal for DuckDNS runs automatically via the renewCerts schedule; custom-domain renewals surface a prompt in the dashboard 30 days before expiry (no TXT rotation is possible without the owner again).

Cert monitoring

A histogram of cert_days_remaining on the operations dashboard makes expiring certs visible long before an outage.