@serve.zone/interfaces 32.20.0 → 32.21.0

package/changelog.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## 2026-09-25 - 32.21.0
+
+### Features
+
+- Add gateway-client hostname records and certificates that need no gateway route.
+  - `syncGatewayClientDnsRecord` (`IReq_SyncGatewayClientDnsRecord`) publishes, replaces or
+    withdraws the one `A` or `AAAA` record a `IGatewayClientHostnameOwnership` (`appId`,
+    `hostname`) holds, at a value the client chooses. The value must lie inside the new
+    gateway-client policy field `allowedDnsRecordAddresses`, a list of canonical CIDR prefixes on
+    `IGatewayClient`, `IGatewayClientProvisioningSpec` and `IGatewayClientContext`. An absent or
+    empty list allows no record.
+  - `getGatewayClientCertificate` (`IReq_GetGatewayClientCertificate`) answers the exact
+    certificate for the owned hostname as `ready` (`IGatewayClientCertificate` with its PEM key
+    and `renewAfter`), `pending` or `refused` (`TGatewayClientCertificateRefusal`).
+    `releaseGatewayClientCertificate` (`IReq_ReleaseGatewayClientCertificate`) removes that
+    material.
+  - The three requests accept gateway-client credentials only and reuse the existing token
+    capabilities `syncDnsRecords`, `requestCertificates` and `readCertificates`.
+  - Gateways advertise support with the optional capability flags `dns.clientRecords` and
+    `certificates.exactIssuance`.
+  - `TGatewayClientDnsRecordStatus` reuses the route DNS vocabulary, and
+    `gatewayClientHostnameContract` states the TTL, allowance and length bounds.
+  - Add the shared validators `validateGatewayClientHostnameOwnership`,
+    `validateGatewayClientDnsRecord`, `validateGatewayAllowedDnsRecordAddresses`,
+    `isGatewayClientDnsRecordAllowed`, `isGatewayAddressPrefix` and `isGatewayClientHostname`.
+    They accept only the canonical spelling of each address: the dotted quad, or RFC 5952 text
+    for IPv6.
+  - Every addition is optional or new, so no existing shape narrows.
+
+## 2026-09-24 - 32.20.1
+
+### Maintenance
+
+- Update `@push.rocks/smartlog` `^3.2.2` → `^4.0.0`. The package exports only the
+  `@push.rocks/smartlog/interfaces` types (`ILogPackage`), which are unchanged in 4.0.0, and
+  4.0.0 no longer depends on the deprecated `@push.rocks/smartclickhouse`, so that package leaves
+  the production dependency tree of every consumer.
+
 ## 2026-09-24 - 32.20.0
 
 ### Features

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@serve.zone/interfaces',
-    version: '32.20.0',
+    version: '32.21.0',
     description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSx3QkFBd0I7SUFDOUIsT0FBTyxFQUFFLFNBQVM7SUFDbEIsV0FBVyxFQUFFLHVGQUF1RjtDQUNyRyxDQUFBIn0=

package/dist_ts/data/gateway.d.ts

@@ -90,6 +90,11 @@ export interface IGatewayCapabilities {
         read: boolean;
         export: boolean;
         forceRenew: boolean;
+        /**
+         * `getGatewayClientCertificate` and `releaseGatewayClientCertificate` are served: an exact
+         * certificate for one owned hostname, with no route behind it. Absent means unsupported.
+         */
+        exactIssuance?: boolean;
     };
     email: {
         domains: boolean;
@@ -102,6 +107,11 @@ export interface IGatewayCapabilities {
     dns: {
         authoritative: boolean;
         providerManaged: boolean;
+        /**
+         * `syncGatewayClientDnsRecord` is served: an address record at a value the client chooses
+         * inside its `allowedDnsRecordAddresses`. Absent means unsupported.
+         */
+        clientRecords?: boolean;
     };
     http3: {
         enabled: boolean;
@@ -148,6 +158,11 @@ export interface IGatewayClient {
     /** `*` matches any hostname under a managed zone; `*.zone` matches exactly one label. */
     hostnamePatterns: string[];
     allowedRouteTargets: IGatewayRouteTargetAllowance[];
+    /**
+     * Canonical address prefixes the client's own address records may point into; see
+     * `validateGatewayAllowedDnsRecordAddresses`. Absent or empty allows no address record.
+     */
+    allowedDnsRecordAddresses?: string[];
     capabilities: IGatewayTokenCapabilities;
     enabled: boolean;
     tokenCount?: number;
@@ -166,6 +181,11 @@ export interface IGatewayClientProvisioningSpec {
     /** `*` matches any hostname under a managed zone; `*.zone` matches exactly one label. */
     hostnamePatterns: string[];
     allowedRouteTargets: IGatewayRouteTargetAllowance[];
+    /**
+     * Canonical address prefixes the client's own address records may point into; see
+     * `validateGatewayAllowedDnsRecordAddresses`. Absent or empty allows no address record.
+     */
+    allowedDnsRecordAddresses?: string[];
     capabilities: IGatewayTokenCapabilities;
     enabled?: boolean;
 }
@@ -194,6 +214,8 @@ interface IGatewayClientContextBase {
     /** `*` matches any hostname under a managed zone; `*.zone` matches exactly one label. */
     hostnamePatterns: string[];
     allowedRouteTargets: IGatewayRouteTargetAllowance[];
+    /** Absent on gateways that predate address records; read it as an empty allowance. */
+    allowedDnsRecordAddresses?: string[];
     capabilities: IGatewayTokenCapabilities;
 }
 /** Server-authoritative lifecycle of an authenticated gateway-client credential. */
@@ -410,4 +432,151 @@ export interface IGatewayRouteSyncResult {
     dns?: IGatewayRouteDnsResult;
     message?: string;
 }
+/**
+ * Bounds of the gateway-client address record and certificate contracts.
+ *
+ * A gateway applies `defaultTtl` to a record that names none, and refuses a TTL outside
+ * `minTtl`..`maxTtl` as it refuses an allowance list longer than `maxAllowedDnsRecordAddresses`.
+ */
+export declare const gatewayClientHostnameContract: Readonly<{
+    minTtl: 60;
+    maxTtl: 86400;
+    defaultTtl: 300;
+    maxAllowedDnsRecordAddresses: 64;
+    maxAppIdLength: 128;
+    maxHostnameLength: 253;
+}>;
+/**
+ * What one gateway client owns a hostname for: its app and the exact hostname.
+ *
+ * The gateway client itself is never named here. The gateway resolves it from the authenticating
+ * gateway-client credential, so a client cannot act for another one. One ownership holds at most
+ * one address record and one certificate for its hostname, and a hostname is held by at most one
+ * ownership: a second client or app, a gateway route claim, or a record the gateway does not
+ * manage makes the hostname a conflict rather than a shared name.
+ */
+export interface IGatewayClientHostnameOwnership {
+    /** 1 to 128 characters of letters, digits, `.`, `_`, `:` or `-`, starting with a letter or digit. */
+    appId: string;
+    /** Lowercase fully qualified hostname without a trailing dot and without a wildcard. */
+    hostname: string;
+}
+/** Address record types a gateway client may publish at a value it chooses. */
+export type TGatewayClientDnsRecordType = 'A' | 'AAAA';
+/**
+ * One address record a gateway client asks the gateway to publish for its hostname.
+ *
+ * The value is the canonical literal of the record's family (a dotted quad for `A`, RFC 5952 text
+ * for `AAAA`) and must lie inside the client's `allowedDnsRecordAddresses`. The record is never
+ * proxied: a client that chooses its own address asks for exactly that address to be served.
+ */
+export interface IGatewayClientDnsRecord {
+    type: TGatewayClientDnsRecordType;
+    value: string;
+    /** Seconds, `minTtl`..`maxTtl`; `defaultTtl` when omitted. */
+    ttl?: number;
+}
+/**
+ * Outcome of one address record synchronization, in the gateway route DNS vocabulary.
+ *
+ * - `managed-created` / `managed-updated` / `managed-unchanged` / `managed-deleted`: done.
+ * - `target-invalid`: the value is outside the client's address allowance.
+ * - `zone-unmanaged`: no zone the gateway manages holds the hostname.
+ * - `zone-unavailable`: the zone's DNS provider or authority cannot be reached; retryable.
+ * - `record-conflict`: another ownership, a gateway route claim, or an unmanaged record holds
+ *   the hostname. The gateway never overwrites or adopts it.
+ * - `mutation-failed`: writing the record failed; retryable.
+ */
+export type TGatewayClientDnsRecordStatus = Extract<TGatewayRouteDnsStatus, 'managed-created' | 'managed-updated' | 'managed-unchanged' | 'managed-deleted' | 'target-invalid' | 'zone-unmanaged' | 'zone-unavailable' | 'record-conflict' | 'mutation-failed'>;
+/** Result of `syncGatewayClientDnsRecord`. */
+export interface IGatewayClientDnsRecordSyncResult {
+    success: boolean;
+    /** True when the same request may succeed later without any change on the client's side. */
+    retryable: boolean;
+    status: TGatewayClientDnsRecordStatus;
+    hostname: string;
+    zoneName?: string;
+    /** The record this ownership holds after the call; absent after a deletion or a refusal. */
+    record?: IGatewayRouteDnsRecord;
+    /** The records that hold the hostname, as evidence for `record-conflict`. */
+    conflictingRecords?: IGatewayRouteDnsRecord[];
+    /** Unix epoch milliseconds at which the gateway checked the DNS state. */
+    checkedAt: number;
+    /** Unix epoch milliseconds at which authoritative DNS confirmed the desired state. */
+    authoritativeVerifiedAt?: number;
+    message?: string;
+}
+/**
+ * The certificate a gateway issued for one owned hostname, with its private key.
+ *
+ * Secret-bearing: a receiver keeps the key sealed and never logs or caches the response as is.
+ */
+export interface IGatewayClientCertificate {
+    hostname: string;
+    /** PEM leaf certificate followed by its chain. */
+    certificatePem: string;
+    /** PEM private key of the leaf certificate. */
+    privateKeyPem: string;
+    /** Unix epoch milliseconds. */
+    validFrom: number;
+    /** Unix epoch milliseconds. */
+    validUntil: number;
+    /** Unix epoch milliseconds after which asking again yields a renewed certificate. */
+    renewAfter: number;
+}
+/**
+ * Why a gateway does not issue a certificate for an ownership.
+ *
+ * - `zone-unmanaged`: no zone the gateway manages with verified authority holds the hostname.
+ * - `hostname-conflict`: another ownership or a gateway route claim holds the hostname.
+ * - `issuance-failed`: the certificate authority refused the order; `retryAfter` says when a new
+ *   order is placed.
+ * - `issuance-unavailable`: the gateway's ACME configuration or DNS authority is not ready.
+ */
+export type TGatewayClientCertificateRefusal = 'zone-unmanaged' | 'hostname-conflict' | 'issuance-failed' | 'issuance-unavailable';
+/** Result of `getGatewayClientCertificate`. */
+export type TGatewayClientCertificateResult = {
+    status: 'ready';
+    certificate: IGatewayClientCertificate;
+} | {
+    /** An issuance runs; ask again after `retryAfterMs`. */
+    status: 'pending';
+    hostname: string;
+    retryAfterMs: number;
+} | {
+    status: 'refused';
+    hostname: string;
+    code: TGatewayClientCertificateRefusal;
+    retryable: boolean;
+    /** Unix epoch milliseconds before which asking again cannot change the answer. */
+    retryAfter?: number;
+    message?: string;
+};
+/** Result of `releaseGatewayClientCertificate`. */
+export type TGatewayClientCertificateReleaseResult = {
+    success: true;
+    /** `released` when material or an issuance was held; `unchanged` when nothing was. */
+    action: 'released' | 'unchanged';
+} | {
+    success: false;
+    retryable: boolean;
+    message: string;
+};
+/** True for a lowercase fully qualified hostname of two or more labels, without wildcard or dot. */
+export declare const isGatewayClientHostname: (valueArg: unknown) => valueArg is string;
+/** Validates one hostname ownership and names every reason it is refused. */
+export declare const validateGatewayClientHostnameOwnership: (valueArg: unknown, pathArg?: string) => string[];
+/** True for one canonical address prefix of either family whose host bits are zero. */
+export declare const isGatewayAddressPrefix: (valueArg: unknown) => valueArg is string;
+/** Validates a client's address allowance and names every reason it is refused. */
+export declare const validateGatewayAllowedDnsRecordAddresses: (valueArg: unknown, pathArg?: string) => string[];
+/** Validates one requested address record and names every reason it is refused. */
+export declare const validateGatewayClientDnsRecord: (valueArg: unknown, pathArg?: string) => string[];
+/**
+ * True when a valid record's value lies inside one of the allowance's prefixes of its family.
+ *
+ * A prefix that is not canonical allows nothing, so an allowance a gateway would refuse never
+ * widens what a record may point at.
+ */
+export declare const isGatewayClientDnsRecordAllowed: (recordArg: IGatewayClientDnsRecord, allowedDnsRecordAddressesArg: readonly string[] | undefined) => boolean;
 export {};

package/dist_ts/data/gateway.js

@@ -1,2 +1,115 @@
-export {};
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZ2F0ZXdheS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL2RhdGEvZ2F0ZXdheS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiIn0=
+import { hasExactKeys, readDataElements, readDataProperties } from '../private/dataproperties.js';
+import { isPlausibleUnicastIpv4 } from '../private/ipv4.js';
+import { ipPrefixContains, parseCanonicalIpAddress, parseCanonicalIpPrefix, } from '../private/ipaddress.js';
+/**
+ * Bounds of the gateway-client address record and certificate contracts.
+ *
+ * A gateway applies `defaultTtl` to a record that names none, and refuses a TTL outside
+ * `minTtl`..`maxTtl` as it refuses an allowance list longer than `maxAllowedDnsRecordAddresses`.
+ */
+export const gatewayClientHostnameContract = Object.freeze({
+    minTtl: 60,
+    maxTtl: 86_400,
+    defaultTtl: 300,
+    maxAllowedDnsRecordAddresses: 64,
+    maxAppIdLength: 128,
+    maxHostnameLength: 253,
+});
+const gatewayHostnameLabel = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+const gatewayAppId = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
+/** True for a lowercase fully qualified hostname of two or more labels, without wildcard or dot. */
+export const isGatewayClientHostname = (valueArg) => (typeof valueArg === 'string'
+    && valueArg.length <= gatewayClientHostnameContract.maxHostnameLength
+    && valueArg.split('.').length >= 2
+    && valueArg.split('.').every((labelArg) => gatewayHostnameLabel.test(labelArg)));
+/** Validates one hostname ownership and names every reason it is refused. */
+export const validateGatewayClientHostnameOwnership = (valueArg, pathArg = 'ownership') => {
+    const ownership = readDataProperties(valueArg);
+    if (ownership === null || !hasExactKeys(ownership, ['appId', 'hostname'])) {
+        return [`${pathArg} must use its exact schema`];
+    }
+    const errors = [];
+    const appId = ownership.appId;
+    if (typeof appId !== 'string' || appId.length > gatewayClientHostnameContract.maxAppIdLength
+        || !gatewayAppId.test(appId)) {
+        errors.push(`${pathArg} appId must be 1 to ${gatewayClientHostnameContract.maxAppIdLength} `
+            + 'characters of letters, digits, dot, underscore, colon or hyphen, starting with a letter or digit');
+    }
+    if (!isGatewayClientHostname(ownership.hostname)) {
+        errors.push(`${pathArg} hostname must be a lowercase fully qualified hostname `
+            + 'without a trailing dot or wildcard');
+    }
+    return errors;
+};
+/** True for one canonical address prefix of either family whose host bits are zero. */
+export const isGatewayAddressPrefix = (valueArg) => parseCanonicalIpPrefix(valueArg) !== null;
+/** Validates a client's address allowance and names every reason it is refused. */
+export const validateGatewayAllowedDnsRecordAddresses = (valueArg, pathArg = 'allowedDnsRecordAddresses') => {
+    const maximum = gatewayClientHostnameContract.maxAllowedDnsRecordAddresses;
+    const prefixes = readDataElements(valueArg, maximum);
+    if (prefixes === null) {
+        return [`${pathArg} must be a list of at most ${maximum} address prefixes`];
+    }
+    const errors = [];
+    prefixes.forEach((prefixArg, indexArg) => {
+        if (!isGatewayAddressPrefix(prefixArg)) {
+            errors.push(`${pathArg}[${indexArg}] must be a canonical address prefix whose host bits are zero`);
+        }
+        else if (prefixes.indexOf(prefixArg) !== indexArg) {
+            errors.push(`${pathArg}[${indexArg}] repeats ${prefixArg}`);
+        }
+    });
+    return errors;
+};
+/** True when the value is a canonical literal of the record type that can address one host. */
+const isGatewayClientDnsRecordAddress = (typeArg, valueArg) => {
+    if (typeArg === 'A') {
+        return isPlausibleUnicastIpv4(valueArg);
+    }
+    const address = parseCanonicalIpAddress(valueArg);
+    // `::` is unspecified and `ff00::/8` is multicast; neither addresses one host.
+    return address?.family === 6 && address.value !== 0n && address.value >> 120n !== 0xffn;
+};
+/** Validates one requested address record and names every reason it is refused. */
+export const validateGatewayClientDnsRecord = (valueArg, pathArg = 'record') => {
+    const record = readDataProperties(valueArg);
+    if (record === null || !hasExactKeys(record, ['type', 'value'], ['ttl'])) {
+        return [`${pathArg} must use its exact schema`];
+    }
+    const type = record.type;
+    if (type !== 'A' && type !== 'AAAA') {
+        return [`${pathArg} type must be A or AAAA`];
+    }
+    const errors = [];
+    if (!isGatewayClientDnsRecordAddress(type, record.value)) {
+        errors.push(type === 'A'
+            ? `${pathArg} value must be a canonical IPv4 host address (not 0.0.0.0/8, multicast or reserved)`
+            : `${pathArg} value must be a canonical RFC 5952 IPv6 host address (not unspecified or multicast)`);
+    }
+    const { minTtl, maxTtl } = gatewayClientHostnameContract;
+    if (Object.hasOwn(record, 'ttl') && !(typeof record.ttl === 'number'
+        && Number.isSafeInteger(record.ttl) && record.ttl >= minTtl && record.ttl <= maxTtl)) {
+        errors.push(`${pathArg} ttl must be an integer from ${minTtl} to ${maxTtl} seconds`);
+    }
+    return errors;
+};
+/**
+ * True when a valid record's value lies inside one of the allowance's prefixes of its family.
+ *
+ * A prefix that is not canonical allows nothing, so an allowance a gateway would refuse never
+ * widens what a record may point at.
+ */
+export const isGatewayClientDnsRecordAllowed = (recordArg, allowedDnsRecordAddressesArg) => {
+    if (validateGatewayClientDnsRecord(recordArg).length > 0) {
+        return false;
+    }
+    const address = parseCanonicalIpAddress(recordArg.value);
+    const allowance = allowedDnsRecordAddressesArg === undefined
+        ? []
+        : readDataElements(allowedDnsRecordAddressesArg, gatewayClientHostnameContract.maxAllowedDnsRecordAddresses);
+    return address !== null && allowance !== null && allowance.some((prefixArg) => {
+        const prefix = parseCanonicalIpPrefix(prefixArg);
+        return prefix !== null && ipPrefixContains(prefix, address);
+    });
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZ2F0ZXdheS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL2RhdGEvZ2F0ZXdheS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFDQSxPQUFPLEVBQUUsWUFBWSxFQUFFLGdCQUFnQixFQUFFLGtCQUFrQixFQUFFLE1BQU0sOEJBQThCLENBQUM7QUFDbEcsT0FBTyxFQUFFLHNCQUFzQixFQUFFLE1BQU0sb0JBQW9CLENBQUM7QUFDNUQsT0FBTyxFQUNMLGdCQUFnQixFQUNoQix1QkFBdUIsRUFDdkIsc0JBQXNCLEdBQ3ZCLE1BQU0seUJBQXlCLENBQUM7QUFvZWpDOzs7OztHQUtHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sNkJBQTZCLEdBQUcsTUFBTSxDQUFDLE1BQU0sQ0FBQztJQUN6RCxNQUFNLEVBQUUsRUFBRTtJQUNWLE1BQU0sRUFBRSxNQUFNO0lBQ2QsVUFBVSxFQUFFLEdBQUc7SUFDZiw0QkFBNEIsRUFBRSxFQUFFO0lBQ2hDLGNBQWMsRUFBRSxHQUFHO0lBQ25CLGlCQUFpQixFQUFFLEdBQUc7Q0FDdkIsQ0FBQyxDQUFDO0FBbUpILE1BQU0sb0JBQW9CLEdBQUcsd0NBQXdDLENBQUM7QUFDdEUsTUFBTSxZQUFZLEdBQUcsK0JBQStCLENBQUM7QUFFckQsb0dBQW9HO0FBQ3BHLE1BQU0sQ0FBQyxNQUFNLHVCQUF1QixHQUFHLENBQUMsUUFBaUIsRUFBc0IsRUFBRSxDQUFDLENBQ2hGLE9BQU8sUUFBUSxLQUFLLFFBQVE7T0FDekIsUUFBUSxDQUFDLE1BQU0sSUFBSSw2QkFBNkIsQ0FBQyxpQkFBaUI7T0FDbEUsUUFBUSxDQUFDLEtBQUssQ0FBQyxHQUFHLENBQUMsQ0FBQyxNQUFNLElBQUksQ0FBQztPQUMvQixRQUFRLENBQUMsS0FBSyxDQUFDLEdBQUcsQ0FBQyxDQUFDLEtBQUssQ0FBQyxDQUFDLFFBQVEsRUFBRSxFQUFFLENBQUMsb0JBQW9CLENBQUMsSUFBSSxDQUFDLFFBQVEsQ0FBQyxDQUFDLENBQ2hGLENBQUM7QUFF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

package/dist_ts/private/ipaddress.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Canonical IP address and prefix text, read into numbers a prefix test can compare.
+ *
+ * Only the one canonical spelling of each value is accepted: a dotted quad without leading zeros
+ * for IPv4, and the RFC 5952 form for IPv6 (lowercase, no leading zeros, the longest run of two or
+ * more zero groups compressed, the first run on a tie). A value two peers could spell differently
+ * would let the same address pass one comparison and fail another, so a non-canonical spelling is
+ * refused rather than normalized. IPv6 text with an embedded dotted quad or a zone index is refused
+ * for the same reason.
+ */
+export type TIpAddressFamily = 4 | 6;
+export interface IIpAddressValue {
+    family: TIpAddressFamily;
+    value: bigint;
+}
+export interface IIpPrefixValue {
+    family: TIpAddressFamily;
+    network: bigint;
+    length: number;
+}
+/** One canonical address literal of either family, or `null` for anything else. */
+export declare const parseCanonicalIpAddress: (valueArg: unknown) => IIpAddressValue | null;
+/**
+ * One canonical prefix `<address>/<length>` of either family whose host bits are all zero, or
+ * `null` for anything else. The length is written without leading zeros.
+ */
+export declare const parseCanonicalIpPrefix: (valueArg: unknown) => IIpPrefixValue | null;
+/** True when the address lies inside the prefix; families never contain each other. */
+export declare const ipPrefixContains: (prefixArg: IIpPrefixValue, addressArg: IIpAddressValue) => boolean;

package/dist_ts/private/ipaddress.js

@@ -0,0 +1,120 @@
+/**
+ * Canonical IP address and prefix text, read into numbers a prefix test can compare.
+ *
+ * Only the one canonical spelling of each value is accepted: a dotted quad without leading zeros
+ * for IPv4, and the RFC 5952 form for IPv6 (lowercase, no leading zeros, the longest run of two or
+ * more zero groups compressed, the first run on a tie). A value two peers could spell differently
+ * would let the same address pass one comparison and fail another, so a non-canonical spelling is
+ * refused rather than normalized. IPv6 text with an embedded dotted quad or a zone index is refused
+ * for the same reason.
+ */
+const familyBits = (familyArg) => (familyArg === 4 ? 32 : 128);
+const parseIpv4 = (valueArg) => {
+    if (valueArg.length > 15) {
+        return null;
+    }
+    const octets = valueArg.split('.');
+    if (octets.length !== 4
+        || !octets.every((octetArg) => /^(?:0|[1-9][0-9]{0,2})$/.test(octetArg) && Number(octetArg) <= 255)) {
+        return null;
+    }
+    return octets.reduce((sumArg, octetArg) => (sumArg << 8n) | BigInt(Number(octetArg)), 0n);
+};
+const parseIpv6Groups = (valueArg) => {
+    if (valueArg.length > 39 || !/^[0-9a-f:]+$/.test(valueArg)) {
+        return null;
+    }
+    const halves = valueArg.split('::');
+    if (halves.length > 2) {
+        return null;
+    }
+    const head = halves[0] === '' ? [] : halves[0].split(':');
+    if (halves.length === 1) {
+        return head;
+    }
+    const tail = halves[1] === '' ? [] : halves[1].split(':');
+    if (head.length + tail.length > 7) {
+        return null;
+    }
+    return [...head, ...new Array(8 - head.length - tail.length).fill('0'), ...tail];
+};
+const parseIpv6 = (valueArg) => {
+    const groups = parseIpv6Groups(valueArg);
+    if (groups === null || groups.length !== 8
+        || !groups.every((groupArg) => /^[0-9a-f]{1,4}$/.test(groupArg))) {
+        return null;
+    }
+    return groups.reduce((sumArg, groupArg) => (sumArg << 16n) | BigInt(parseInt(groupArg, 16)), 0n);
+};
+/** The RFC 5952 text of one IPv6 address. */
+const formatIpv6 = (valueArg) => {
+    const groups = [];
+    for (let index = 7; index >= 0; index--) {
+        groups.push(Number((valueArg >> BigInt(index * 16)) & 0xffffn));
+    }
+    let bestStart = -1;
+    let bestLength = 0;
+    for (let start = 0; start < 8;) {
+        if (groups[start] !== 0) {
+            start++;
+            continue;
+        }
+        let end = start;
+        while (end < 8 && groups[end] === 0) {
+            end++;
+        }
+        if (end - start > bestLength) {
+            bestStart = start;
+            bestLength = end - start;
+        }
+        start = end;
+    }
+    const text = groups.map((groupArg) => groupArg.toString(16));
+    if (bestLength < 2) {
+        return text.join(':');
+    }
+    return `${text.slice(0, bestStart).join(':')}::${text.slice(bestStart + bestLength).join(':')}`;
+};
+/** One canonical address literal of either family, or `null` for anything else. */
+export const parseCanonicalIpAddress = (valueArg) => {
+    if (typeof valueArg !== 'string') {
+        return null;
+    }
+    const ipv4 = parseIpv4(valueArg);
+    if (ipv4 !== null) {
+        return { family: 4, value: ipv4 };
+    }
+    const ipv6 = parseIpv6(valueArg);
+    return ipv6 !== null && formatIpv6(ipv6) === valueArg ? { family: 6, value: ipv6 } : null;
+};
+/**
+ * One canonical prefix `<address>/<length>` of either family whose host bits are all zero, or
+ * `null` for anything else. The length is written without leading zeros.
+ */
+export const parseCanonicalIpPrefix = (valueArg) => {
+    if (typeof valueArg !== 'string') {
+        return null;
+    }
+    const parts = valueArg.split('/');
+    if (parts.length !== 2 || !/^(?:0|[1-9][0-9]{0,2})$/.test(parts[1])) {
+        return null;
+    }
+    const address = parseCanonicalIpAddress(parts[0]);
+    const length = Number(parts[1]);
+    if (address === null || length > familyBits(address.family)) {
+        return null;
+    }
+    const hostBits = BigInt(familyBits(address.family) - length);
+    return address.value % (1n << hostBits) === 0n
+        ? { family: address.family, network: address.value, length }
+        : null;
+};
+/** True when the address lies inside the prefix; families never contain each other. */
+export const ipPrefixContains = (prefixArg, addressArg) => {
+    if (prefixArg.family !== addressArg.family) {
+        return false;
+    }
+    const hostBits = BigInt(familyBits(prefixArg.family) - prefixArg.length);
+    return addressArg.value >> hostBits === prefixArg.network >> hostBits;
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaXBhZGRyZXNzLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vdHMvcHJpdmF0ZS9pcGFkZHJlc3MudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUE7Ozs7Ozs7OztHQVNHO0FBZUgsTUFBTSxVQUFVLEdBQUcsQ0FBQyxTQUEyQixFQUFVLEVBQUUsQ0FBQyxDQUFDLFNBQVMsS0FBSyxDQUFDLENBQUMsQ0FBQyxDQUFDLEVBQUUsQ0FBQyxDQUFDLENBQUMsR0FBRyxDQUFDLENBQUM7QUFFekYsTUFBTSxTQUFTLEdBQUcsQ0FBQyxRQUFnQixFQUFpQixFQUFFO0lBQ3BELElBQUksUUFBUSxDQUFDLE1BQU0sR0FBRyxFQUFFLEVBQUUsQ0FBQztRQUN6QixPQUFPLElBQUksQ0FBQztJQUNkLENBQUM7SUFDRCxNQUFNLE1BQU0sR0FBRyxRQUFRLENBQUMsS0FBSyxDQUFDLEdBQUcsQ0FBQyxDQUFDO0lBQ25DLElBQUksTUFBTSxDQUFDLE1BQU0sS0FBSyxDQUFDO1dBQ2xCLENBQUMsTUFBTSxDQUFDLEtBQUssQ0FBQyxDQUFDLFFBQVEsRUFBRSxFQUFFLENBQUMseUJBQXlCLENBQUMsSUFBSSxDQUFDLFFBQVEsQ0FBQyxJQUFJLE1BQU0sQ0FBQyxRQUFRLENBQUMsSUFBSSxHQUFHLENBQUMsRUFBRSxDQUFDO1FBQ3RHLE9BQU8sSUFBSSxDQUFDO0lBQ2QsQ0FBQztJQUNELE9BQU8sTUFBTSxDQUFDLE1BQU0sQ0FBQyxDQUFDLE1BQU0sRUFBRSxRQUFRLEVBQUUsRUFBRSxDQUFDLENBQUMsTUFBTSxJQUFJLEVBQUUsQ0FBQyxHQUFHLE1BQU0sQ0FBQyxNQUFNLENBQUMsUUFBUSxDQUFDLENBQUMsRUFBRSxFQUFFLENBQUMsQ0FBQztBQUM1RixDQUFDLENBQUM7QUFFRixNQUFNLGVBQWUsR0FBRyxDQUFDLFFBQWdCLEVBQW1CLEVBQUU7SUFDNUQsSUFBSSxRQUFRLENBQUMsTUFBTSxHQUFHLEVBQUUsSUFBSSxDQUFDLGNBQWMsQ0FBQyxJQUFJ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

package/dist_ts/requests/gateway.d.ts

@@ -1,5 +1,5 @@
 import * as plugins from '../plugins.js';
-import type { IGatewayCapabilities, IGatewayClient, IGatewayClientCredential, IGatewayClientProvisioningSpec, IGatewayClientContext, IGatewayClientOwnership, IGatewayClientRoute, IGatewayDnsRecord, IGatewayDomain, IGatewayIdentity, IGatewayRouteConfig, IGatewayRouteSyncResult, TGatewayRouteDnsMode, TGatewayClientProvisioningAction } from '../data/gateway.js';
+import type { IGatewayCapabilities, IGatewayClient, IGatewayClientCredential, IGatewayClientProvisioningSpec, IGatewayClientContext, IGatewayClientDnsRecord, IGatewayClientDnsRecordSyncResult, IGatewayClientHostnameOwnership, IGatewayClientOwnership, IGatewayClientRoute, IGatewayDnsRecord, IGatewayDomain, IGatewayIdentity, IGatewayRouteConfig, IGatewayRouteSyncResult, TGatewayRouteDnsMode, TGatewayClientCertificateReleaseResult, TGatewayClientCertificateResult, TGatewayClientProvisioningAction } from '../data/gateway.js';
 import type { IMailOverviewDomain, IMailOverviewEmail } from './mail.js';
 /**
  * Gateway client contracts: the machine-facing API a gateway (dcrouter)
@@ -172,6 +172,63 @@ export interface IReq_SyncGatewayClientRoute extends plugins.typedrequestInterfa
     };
     response: IGatewayRouteSyncResult;
 }
+/**
+ * Publishes, replaces or withdraws the one address record a gateway-client ownership holds.
+ *
+ * Gateway-client credentials only, with the `syncDnsRecords` capability; the hostname must match
+ * the client's `hostnamePatterns`. Idempotent: the same record again answers `managed-unchanged`,
+ * and deleting a record the ownership does not hold answers `managed-deleted`. The value must lie
+ * inside the client's `allowedDnsRecordAddresses` (`target-invalid` otherwise). A hostname held by
+ * anything else is `record-conflict` and stays untouched. Requires `dns.clientRecords`.
+ */
+export interface IReq_SyncGatewayClientDnsRecord extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_SyncGatewayClientDnsRecord> {
+    method: 'syncGatewayClientDnsRecord';
+    request: {
+        apiToken: string;
+        identity?: never;
+        ownership: IGatewayClientHostnameOwnership;
+    } & ({
+        record: IGatewayClientDnsRecord;
+        delete?: never;
+    } | {
+        delete: true;
+        record?: never;
+    });
+    response: IGatewayClientDnsRecordSyncResult;
+}
+/**
+ * Answers the exact certificate for one owned hostname, starting its issuance when none is valid.
+ *
+ * Gateway-client credentials only, with `requestCertificates` and `readCertificates`; the hostname
+ * must match the client's `hostnamePatterns`. No gateway route is needed. The certificate is issued
+ * for exactly this one identifier in the client's own namespace, and asking again after
+ * `renewAfter` answers a renewed one. The `ready` answer carries the private key. Requires
+ * `certificates.exactIssuance`.
+ */
+export interface IReq_GetGatewayClientCertificate extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_GetGatewayClientCertificate> {
+    method: 'getGatewayClientCertificate';
+    request: {
+        apiToken: string;
+        identity?: never;
+        ownership: IGatewayClientHostnameOwnership;
+    };
+    response: TGatewayClientCertificateResult;
+}
+/**
+ * Removes the certificate material and any issuance an ownership holds, releasing its certificate claim; an address record under the same ownership is unaffected.
+ *
+ * Gateway-client credentials only, with `requestCertificates`. Idempotent: an ownership that holds
+ * nothing answers `unchanged`. Requires `certificates.exactIssuance`.
+ */
+export interface IReq_ReleaseGatewayClientCertificate extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_ReleaseGatewayClientCertificate> {
+    method: 'releaseGatewayClientCertificate';
+    request: {
+        apiToken: string;
+        identity?: never;
+        ownership: IGatewayClientHostnameOwnership;
+    };
+    response: TGatewayClientCertificateReleaseResult;
+}
 export interface IReq_ReprovisionCertificateDomain extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_ReprovisionCertificateDomain> {
     method: 'reprovisionCertificateDomain';
     request: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/interfaces",
-  "version": "32.20.0",
+  "version": "32.21.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.",
   "exports": {
@@ -23,7 +23,7 @@
   "dependencies": {
     "@api.global/typedrequest-interfaces": "^7.1.0",
     "@push.rocks/smartcrypto": "^2.2.0",
-    "@push.rocks/smartlog": "^3.2.2",
+    "@push.rocks/smartlog": "^4.0.0",
     "@tsclass/tsclass": "^9.5.1"
   },
   "devDependencies": {

package/readme.md

@@ -2684,6 +2684,38 @@ const provisioning: requests.gateway.IReq_ProvisionGatewayClientCredential['requ
 
 `getGatewayClientContext` returns effective live policy. A `gatewayClient` role necessarily includes the credential ID, bound client ID/type, and `policyGeneration`; consumers should reject admin/operator or mismatched contexts rather than falling back to a caller-supplied owner ID. `getGatewayClientMailOverview` provides an owner-scoped domain and recent-message summary. `getGatewayClientMailDomainCount` derives ownership exclusively from the authenticating gateway credential and returns `{ count: number }` for its distinct configured mail domains. Cloudly therefore uses only `dcrouterGatewayApiToken`; the former `dcrouterOpsApiToken` setting is not part of `data.ICloudlySettings`.
 
+### Gateway Client Hostname Records and Certificates
+
+A gateway client can hold an exact hostname without a gateway route: an address record at a value it chooses, and an exact certificate for that one name. Cloudly uses this for its cluster relay names, whose A record must carry the relay node's own address and whose certificate the relay serves itself. All three requests accept only a gateway-client credential (`identity` is `never`). The gateway resolves the client from that credential, and the hostname must match the client's `hostnamePatterns`. `data.IGatewayClientHostnameOwnership` names only `{ appId, hostname }`. One ownership holds at most one address record and one certificate. A hostname held by another ownership, by a gateway route claim, or by a record the gateway does not manage is a conflict. The gateway never overwrites or adopts it.
+
+- `syncGatewayClientDnsRecord` (`requests.gateway.IReq_SyncGatewayClientDnsRecord`) publishes, replaces or withdraws the ownership's `A` or `AAAA` record. It needs the token capability `syncDnsRecords`, and the gateway advertises it as `capabilities.dns.clientRecords`. The value must be a canonical unicast literal inside the client's policy field `allowedDnsRecordAddresses`, a list of canonical CIDR prefixes. An absent or empty list allows no record. The result reuses the route DNS vocabulary (`data.TGatewayClientDnsRecordStatus`): `target-invalid` for an address outside the allowance, `record-conflict` with `conflictingRecords` as evidence, and `zone-unavailable` or `mutation-failed` when retryable. Records are never proxied.
+- `getGatewayClientCertificate` (`requests.gateway.IReq_GetGatewayClientCertificate`) answers `ready` with `data.IGatewayClientCertificate` (PEM chain, PEM private key, `validFrom`, `validUntil`, `renewAfter`), `pending` with `retryAfterMs` while an issuance runs, or `refused` with a `data.TGatewayClientCertificateRefusal`. Asking again after `renewAfter` yields a renewed certificate. It needs `requestCertificates` and `readCertificates`, and the gateway advertises it as `capabilities.certificates.exactIssuance`. The `ready` answer carries a private key; keep it sealed and never log it.
+- `releaseGatewayClientCertificate` (`requests.gateway.IReq_ReleaseGatewayClientCertificate`) removes the ownership's certificate material and any issuance in flight. It is idempotent and answers `released` or `unchanged`.
+
+Both sides judge values with the same helpers:
+
+- `data.validateGatewayClientHostnameOwnership`
+- `data.validateGatewayClientDnsRecord`
+- `data.validateGatewayAllowedDnsRecordAddresses`
+- `data.isGatewayClientDnsRecordAllowed`
+- `data.isGatewayAddressPrefix`
+- `data.isGatewayClientHostname`
+
+Only one spelling of each address is accepted: the dotted quad, or RFC 5952 text for IPv6. `data.gatewayClientHostnameContract` states the bounds: TTL 60 to 86400 seconds with a default of 300, at most 64 allowance prefixes, an `appId` of at most 128 characters, and a hostname of at most 253 characters.
+
+```typescript
+import { data, requests } from '@serve.zone/interfaces';
+
+const record: data.IGatewayClientDnsRecord = { type: 'A', value: '198.51.100.85', ttl: 60 };
+data.isGatewayClientDnsRecordAllowed(record, ['198.51.100.0/24']); // true
+
+const request: requests.gateway.IReq_SyncGatewayClientDnsRecord['request'] = {
+  apiToken: gatewayClientToken,
+  ownership: { appId: 'cluster-relay:clusterexample', hostname: 'relay.clusterexample.example.com' },
+  record,
+};
+```
+
 ### CoreMail contracts
 
 `requests.coremail` is the shared contract boundary for authenticated workload

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/interfaces',
-  version: '32.20.0',
+  version: '32.21.0',
   description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 }

package/ts/data/gateway.ts

@@ -1,4 +1,11 @@
 import type { TDnsRecordType } from './dns.js';
+import { hasExactKeys, readDataElements, readDataProperties } from '../private/dataproperties.js';
+import { isPlausibleUnicastIpv4 } from '../private/ipv4.js';
+import {
+  ipPrefixContains,
+  parseCanonicalIpAddress,
+  parseCanonicalIpPrefix,
+} from '../private/ipaddress.js';
 
 /**
  * Type of platform acting as a gateway client against a gateway (dcrouter).
@@ -115,6 +122,11 @@ export interface IGatewayCapabilities {
     read: boolean;
     export: boolean;
     forceRenew: boolean;
+    /**
+     * `getGatewayClientCertificate` and `releaseGatewayClientCertificate` are served: an exact
+     * certificate for one owned hostname, with no route behind it. Absent means unsupported.
+     */
+    exactIssuance?: boolean;
   };
   email: {
     domains: boolean;
@@ -127,6 +139,11 @@ export interface IGatewayCapabilities {
   dns: {
     authoritative: boolean;
     providerManaged: boolean;
+    /**
+     * `syncGatewayClientDnsRecord` is served: an address record at a value the client chooses
+     * inside its `allowedDnsRecordAddresses`. Absent means unsupported.
+     */
+    clientRecords?: boolean;
   };
   http3: {
     enabled: boolean;
@@ -176,6 +193,11 @@ export interface IGatewayClient {
   /** `*` matches any hostname under a managed zone; `*.zone` matches exactly one label. */
   hostnamePatterns: string[];
   allowedRouteTargets: IGatewayRouteTargetAllowance[];
+  /**
+   * Canonical address prefixes the client's own address records may point into; see
+   * `validateGatewayAllowedDnsRecordAddresses`. Absent or empty allows no address record.
+   */
+  allowedDnsRecordAddresses?: string[];
   capabilities: IGatewayTokenCapabilities;
   enabled: boolean;
   tokenCount?: number;
@@ -195,6 +217,11 @@ export interface IGatewayClientProvisioningSpec {
   /** `*` matches any hostname under a managed zone; `*.zone` matches exactly one label. */
   hostnamePatterns: string[];
   allowedRouteTargets: IGatewayRouteTargetAllowance[];
+  /**
+   * Canonical address prefixes the client's own address records may point into; see
+   * `validateGatewayAllowedDnsRecordAddresses`. Absent or empty allows no address record.
+   */
+  allowedDnsRecordAddresses?: string[];
   capabilities: IGatewayTokenCapabilities;
   enabled?: boolean;
 }
@@ -226,6 +253,8 @@ interface IGatewayClientContextBase {
   /** `*` matches any hostname under a managed zone; `*.zone` matches exactly one label. */
   hostnamePatterns: string[];
   allowedRouteTargets: IGatewayRouteTargetAllowance[];
+  /** Absent on gateways that predate address records; read it as an empty allowance. */
+  allowedDnsRecordAddresses?: string[];
   capabilities: IGatewayTokenCapabilities;
 }
 
@@ -459,3 +488,282 @@ export interface IGatewayRouteSyncResult {
   dns?: IGatewayRouteDnsResult;
   message?: string;
 }
+
+/**
+ * Bounds of the gateway-client address record and certificate contracts.
+ *
+ * A gateway applies `defaultTtl` to a record that names none, and refuses a TTL outside
+ * `minTtl`..`maxTtl` as it refuses an allowance list longer than `maxAllowedDnsRecordAddresses`.
+ */
+export const gatewayClientHostnameContract = Object.freeze({
+  minTtl: 60,
+  maxTtl: 86_400,
+  defaultTtl: 300,
+  maxAllowedDnsRecordAddresses: 64,
+  maxAppIdLength: 128,
+  maxHostnameLength: 253,
+});
+
+/**
+ * What one gateway client owns a hostname for: its app and the exact hostname.
+ *
+ * The gateway client itself is never named here. The gateway resolves it from the authenticating
+ * gateway-client credential, so a client cannot act for another one. One ownership holds at most
+ * one address record and one certificate for its hostname, and a hostname is held by at most one
+ * ownership: a second client or app, a gateway route claim, or a record the gateway does not
+ * manage makes the hostname a conflict rather than a shared name.
+ */
+export interface IGatewayClientHostnameOwnership {
+  /** 1 to 128 characters of letters, digits, `.`, `_`, `:` or `-`, starting with a letter or digit. */
+  appId: string;
+  /** Lowercase fully qualified hostname without a trailing dot and without a wildcard. */
+  hostname: string;
+}
+
+/** Address record types a gateway client may publish at a value it chooses. */
+export type TGatewayClientDnsRecordType = 'A' | 'AAAA';
+
+/**
+ * One address record a gateway client asks the gateway to publish for its hostname.
+ *
+ * The value is the canonical literal of the record's family (a dotted quad for `A`, RFC 5952 text
+ * for `AAAA`) and must lie inside the client's `allowedDnsRecordAddresses`. The record is never
+ * proxied: a client that chooses its own address asks for exactly that address to be served.
+ */
+export interface IGatewayClientDnsRecord {
+  type: TGatewayClientDnsRecordType;
+  value: string;
+  /** Seconds, `minTtl`..`maxTtl`; `defaultTtl` when omitted. */
+  ttl?: number;
+}
+
+/**
+ * Outcome of one address record synchronization, in the gateway route DNS vocabulary.
+ *
+ * - `managed-created` / `managed-updated` / `managed-unchanged` / `managed-deleted`: done.
+ * - `target-invalid`: the value is outside the client's address allowance.
+ * - `zone-unmanaged`: no zone the gateway manages holds the hostname.
+ * - `zone-unavailable`: the zone's DNS provider or authority cannot be reached; retryable.
+ * - `record-conflict`: another ownership, a gateway route claim, or an unmanaged record holds
+ *   the hostname. The gateway never overwrites or adopts it.
+ * - `mutation-failed`: writing the record failed; retryable.
+ */
+export type TGatewayClientDnsRecordStatus = Extract<
+  TGatewayRouteDnsStatus,
+  | 'managed-created'
+  | 'managed-updated'
+  | 'managed-unchanged'
+  | 'managed-deleted'
+  | 'target-invalid'
+  | 'zone-unmanaged'
+  | 'zone-unavailable'
+  | 'record-conflict'
+  | 'mutation-failed'
+>;
+
+/** Result of `syncGatewayClientDnsRecord`. */
+export interface IGatewayClientDnsRecordSyncResult {
+  success: boolean;
+  /** True when the same request may succeed later without any change on the client's side. */
+  retryable: boolean;
+  status: TGatewayClientDnsRecordStatus;
+  hostname: string;
+  zoneName?: string;
+  /** The record this ownership holds after the call; absent after a deletion or a refusal. */
+  record?: IGatewayRouteDnsRecord;
+  /** The records that hold the hostname, as evidence for `record-conflict`. */
+  conflictingRecords?: IGatewayRouteDnsRecord[];
+  /** Unix epoch milliseconds at which the gateway checked the DNS state. */
+  checkedAt: number;
+  /** Unix epoch milliseconds at which authoritative DNS confirmed the desired state. */
+  authoritativeVerifiedAt?: number;
+  message?: string;
+}
+
+/**
+ * The certificate a gateway issued for one owned hostname, with its private key.
+ *
+ * Secret-bearing: a receiver keeps the key sealed and never logs or caches the response as is.
+ */
+export interface IGatewayClientCertificate {
+  hostname: string;
+  /** PEM leaf certificate followed by its chain. */
+  certificatePem: string;
+  /** PEM private key of the leaf certificate. */
+  privateKeyPem: string;
+  /** Unix epoch milliseconds. */
+  validFrom: number;
+  /** Unix epoch milliseconds. */
+  validUntil: number;
+  /** Unix epoch milliseconds after which asking again yields a renewed certificate. */
+  renewAfter: number;
+}
+
+/**
+ * Why a gateway does not issue a certificate for an ownership.
+ *
+ * - `zone-unmanaged`: no zone the gateway manages with verified authority holds the hostname.
+ * - `hostname-conflict`: another ownership or a gateway route claim holds the hostname.
+ * - `issuance-failed`: the certificate authority refused the order; `retryAfter` says when a new
+ *   order is placed.
+ * - `issuance-unavailable`: the gateway's ACME configuration or DNS authority is not ready.
+ */
+export type TGatewayClientCertificateRefusal =
+  | 'zone-unmanaged'
+  | 'hostname-conflict'
+  | 'issuance-failed'
+  | 'issuance-unavailable';
+
+/** Result of `getGatewayClientCertificate`. */
+export type TGatewayClientCertificateResult =
+  | {
+      status: 'ready';
+      certificate: IGatewayClientCertificate;
+    }
+  | {
+      /** An issuance runs; ask again after `retryAfterMs`. */
+      status: 'pending';
+      hostname: string;
+      retryAfterMs: number;
+    }
+  | {
+      status: 'refused';
+      hostname: string;
+      code: TGatewayClientCertificateRefusal;
+      retryable: boolean;
+      /** Unix epoch milliseconds before which asking again cannot change the answer. */
+      retryAfter?: number;
+      message?: string;
+    };
+
+/** Result of `releaseGatewayClientCertificate`. */
+export type TGatewayClientCertificateReleaseResult =
+  | {
+      success: true;
+      /** `released` when material or an issuance was held; `unchanged` when nothing was. */
+      action: 'released' | 'unchanged';
+    }
+  | {
+      success: false;
+      retryable: boolean;
+      message: string;
+    };
+
+const gatewayHostnameLabel = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
+const gatewayAppId = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/;
+
+/** True for a lowercase fully qualified hostname of two or more labels, without wildcard or dot. */
+export const isGatewayClientHostname = (valueArg: unknown): valueArg is string => (
+  typeof valueArg === 'string'
+  && valueArg.length <= gatewayClientHostnameContract.maxHostnameLength
+  && valueArg.split('.').length >= 2
+  && valueArg.split('.').every((labelArg) => gatewayHostnameLabel.test(labelArg))
+);
+
+/** Validates one hostname ownership and names every reason it is refused. */
+export const validateGatewayClientHostnameOwnership = (
+  valueArg: unknown,
+  pathArg = 'ownership',
+): string[] => {
+  const ownership = readDataProperties(valueArg);
+  if (ownership === null || !hasExactKeys(ownership, ['appId', 'hostname'])) {
+    return [`${pathArg} must use its exact schema`];
+  }
+  const errors: string[] = [];
+  const appId = ownership.appId;
+  if (typeof appId !== 'string' || appId.length > gatewayClientHostnameContract.maxAppIdLength
+    || !gatewayAppId.test(appId)) {
+    errors.push(`${pathArg} appId must be 1 to ${gatewayClientHostnameContract.maxAppIdLength} `
+      + 'characters of letters, digits, dot, underscore, colon or hyphen, starting with a letter or digit');
+  }
+  if (!isGatewayClientHostname(ownership.hostname)) {
+    errors.push(`${pathArg} hostname must be a lowercase fully qualified hostname `
+      + 'without a trailing dot or wildcard');
+  }
+  return errors;
+};
+
+/** True for one canonical address prefix of either family whose host bits are zero. */
+export const isGatewayAddressPrefix = (valueArg: unknown): valueArg is string =>
+  parseCanonicalIpPrefix(valueArg) !== null;
+
+/** Validates a client's address allowance and names every reason it is refused. */
+export const validateGatewayAllowedDnsRecordAddresses = (
+  valueArg: unknown,
+  pathArg = 'allowedDnsRecordAddresses',
+): string[] => {
+  const maximum = gatewayClientHostnameContract.maxAllowedDnsRecordAddresses;
+  const prefixes = readDataElements(valueArg, maximum);
+  if (prefixes === null) {
+    return [`${pathArg} must be a list of at most ${maximum} address prefixes`];
+  }
+  const errors: string[] = [];
+  prefixes.forEach((prefixArg, indexArg) => {
+    if (!isGatewayAddressPrefix(prefixArg)) {
+      errors.push(`${pathArg}[${indexArg}] must be a canonical address prefix whose host bits are zero`);
+    } else if (prefixes.indexOf(prefixArg) !== indexArg) {
+      errors.push(`${pathArg}[${indexArg}] repeats ${prefixArg}`);
+    }
+  });
+  return errors;
+};
+
+/** True when the value is a canonical literal of the record type that can address one host. */
+const isGatewayClientDnsRecordAddress = (
+  typeArg: TGatewayClientDnsRecordType,
+  valueArg: unknown,
+): valueArg is string => {
+  if (typeArg === 'A') {
+    return isPlausibleUnicastIpv4(valueArg);
+  }
+  const address = parseCanonicalIpAddress(valueArg);
+  // `::` is unspecified and `ff00::/8` is multicast; neither addresses one host.
+  return address?.family === 6 && address.value !== 0n && address.value >> 120n !== 0xffn;
+};
+
+/** Validates one requested address record and names every reason it is refused. */
+export const validateGatewayClientDnsRecord = (valueArg: unknown, pathArg = 'record'): string[] => {
+  const record = readDataProperties(valueArg);
+  if (record === null || !hasExactKeys(record, ['type', 'value'], ['ttl'])) {
+    return [`${pathArg} must use its exact schema`];
+  }
+  const type = record.type;
+  if (type !== 'A' && type !== 'AAAA') {
+    return [`${pathArg} type must be A or AAAA`];
+  }
+  const errors: string[] = [];
+  if (!isGatewayClientDnsRecordAddress(type, record.value)) {
+    errors.push(type === 'A'
+      ? `${pathArg} value must be a canonical IPv4 host address (not 0.0.0.0/8, multicast or reserved)`
+      : `${pathArg} value must be a canonical RFC 5952 IPv6 host address (not unspecified or multicast)`);
+  }
+  const { minTtl, maxTtl } = gatewayClientHostnameContract;
+  if (Object.hasOwn(record, 'ttl') && !(typeof record.ttl === 'number'
+    && Number.isSafeInteger(record.ttl) && record.ttl >= minTtl && record.ttl <= maxTtl)) {
+    errors.push(`${pathArg} ttl must be an integer from ${minTtl} to ${maxTtl} seconds`);
+  }
+  return errors;
+};
+
+/**
+ * True when a valid record's value lies inside one of the allowance's prefixes of its family.
+ *
+ * A prefix that is not canonical allows nothing, so an allowance a gateway would refuse never
+ * widens what a record may point at.
+ */
+export const isGatewayClientDnsRecordAllowed = (
+  recordArg: IGatewayClientDnsRecord,
+  allowedDnsRecordAddressesArg: readonly string[] | undefined,
+): boolean => {
+  if (validateGatewayClientDnsRecord(recordArg).length > 0) {
+    return false;
+  }
+  const address = parseCanonicalIpAddress(recordArg.value);
+  const allowance = allowedDnsRecordAddressesArg === undefined
+    ? []
+    : readDataElements(allowedDnsRecordAddressesArg, gatewayClientHostnameContract.maxAllowedDnsRecordAddresses);
+  return address !== null && allowance !== null && allowance.some((prefixArg) => {
+    const prefix = parseCanonicalIpPrefix(prefixArg);
+    return prefix !== null && ipPrefixContains(prefix, address);
+  });
+};

package/ts/private/ipaddress.ts

@@ -0,0 +1,140 @@
+/**
+ * Canonical IP address and prefix text, read into numbers a prefix test can compare.
+ *
+ * Only the one canonical spelling of each value is accepted: a dotted quad without leading zeros
+ * for IPv4, and the RFC 5952 form for IPv6 (lowercase, no leading zeros, the longest run of two or
+ * more zero groups compressed, the first run on a tie). A value two peers could spell differently
+ * would let the same address pass one comparison and fail another, so a non-canonical spelling is
+ * refused rather than normalized. IPv6 text with an embedded dotted quad or a zone index is refused
+ * for the same reason.
+ */
+
+export type TIpAddressFamily = 4 | 6;
+
+export interface IIpAddressValue {
+  family: TIpAddressFamily;
+  value: bigint;
+}
+
+export interface IIpPrefixValue {
+  family: TIpAddressFamily;
+  network: bigint;
+  length: number;
+}
+
+const familyBits = (familyArg: TIpAddressFamily): number => (familyArg === 4 ? 32 : 128);
+
+const parseIpv4 = (valueArg: string): bigint | null => {
+  if (valueArg.length > 15) {
+    return null;
+  }
+  const octets = valueArg.split('.');
+  if (octets.length !== 4
+    || !octets.every((octetArg) => /^(?:0|[1-9][0-9]{0,2})$/.test(octetArg) && Number(octetArg) <= 255)) {
+    return null;
+  }
+  return octets.reduce((sumArg, octetArg) => (sumArg << 8n) | BigInt(Number(octetArg)), 0n);
+};
+
+const parseIpv6Groups = (valueArg: string): string[] | null => {
+  if (valueArg.length > 39 || !/^[0-9a-f:]+$/.test(valueArg)) {
+    return null;
+  }
+  const halves = valueArg.split('::');
+  if (halves.length > 2) {
+    return null;
+  }
+  const head = halves[0] === '' ? [] : halves[0].split(':');
+  if (halves.length === 1) {
+    return head;
+  }
+  const tail = halves[1] === '' ? [] : halves[1].split(':');
+  if (head.length + tail.length > 7) {
+    return null;
+  }
+  return [...head, ...new Array<string>(8 - head.length - tail.length).fill('0'), ...tail];
+};
+
+const parseIpv6 = (valueArg: string): bigint | null => {
+  const groups = parseIpv6Groups(valueArg);
+  if (groups === null || groups.length !== 8
+    || !groups.every((groupArg) => /^[0-9a-f]{1,4}$/.test(groupArg))) {
+    return null;
+  }
+  return groups.reduce((sumArg, groupArg) => (sumArg << 16n) | BigInt(parseInt(groupArg, 16)), 0n);
+};
+
+/** The RFC 5952 text of one IPv6 address. */
+const formatIpv6 = (valueArg: bigint): string => {
+  const groups: number[] = [];
+  for (let index = 7; index >= 0; index--) {
+    groups.push(Number((valueArg >> BigInt(index * 16)) & 0xffffn));
+  }
+  let bestStart = -1;
+  let bestLength = 0;
+  for (let start = 0; start < 8;) {
+    if (groups[start] !== 0) {
+      start++;
+      continue;
+    }
+    let end = start;
+    while (end < 8 && groups[end] === 0) {
+      end++;
+    }
+    if (end - start > bestLength) {
+      bestStart = start;
+      bestLength = end - start;
+    }
+    start = end;
+  }
+  const text = groups.map((groupArg) => groupArg.toString(16));
+  if (bestLength < 2) {
+    return text.join(':');
+  }
+  return `${text.slice(0, bestStart).join(':')}::${text.slice(bestStart + bestLength).join(':')}`;
+};
+
+/** One canonical address literal of either family, or `null` for anything else. */
+export const parseCanonicalIpAddress = (valueArg: unknown): IIpAddressValue | null => {
+  if (typeof valueArg !== 'string') {
+    return null;
+  }
+  const ipv4 = parseIpv4(valueArg);
+  if (ipv4 !== null) {
+    return { family: 4, value: ipv4 };
+  }
+  const ipv6 = parseIpv6(valueArg);
+  return ipv6 !== null && formatIpv6(ipv6) === valueArg ? { family: 6, value: ipv6 } : null;
+};
+
+/**
+ * One canonical prefix `<address>/<length>` of either family whose host bits are all zero, or
+ * `null` for anything else. The length is written without leading zeros.
+ */
+export const parseCanonicalIpPrefix = (valueArg: unknown): IIpPrefixValue | null => {
+  if (typeof valueArg !== 'string') {
+    return null;
+  }
+  const parts = valueArg.split('/');
+  if (parts.length !== 2 || !/^(?:0|[1-9][0-9]{0,2})$/.test(parts[1])) {
+    return null;
+  }
+  const address = parseCanonicalIpAddress(parts[0]);
+  const length = Number(parts[1]);
+  if (address === null || length > familyBits(address.family)) {
+    return null;
+  }
+  const hostBits = BigInt(familyBits(address.family) - length);
+  return address.value % (1n << hostBits) === 0n
+    ? { family: address.family, network: address.value, length }
+    : null;
+};
+
+/** True when the address lies inside the prefix; families never contain each other. */
+export const ipPrefixContains = (prefixArg: IIpPrefixValue, addressArg: IIpAddressValue): boolean => {
+  if (prefixArg.family !== addressArg.family) {
+    return false;
+  }
+  const hostBits = BigInt(familyBits(prefixArg.family) - prefixArg.length);
+  return addressArg.value >> hostBits === prefixArg.network >> hostBits;
+};

package/ts/requests/gateway.ts

@@ -5,6 +5,9 @@ import type {
   IGatewayClientCredential,
   IGatewayClientProvisioningSpec,
   IGatewayClientContext,
+  IGatewayClientDnsRecord,
+  IGatewayClientDnsRecordSyncResult,
+  IGatewayClientHostnameOwnership,
   IGatewayClientOwnership,
   IGatewayClientRoute,
   IGatewayDnsRecord,
@@ -13,6 +16,8 @@ import type {
   IGatewayRouteConfig,
   IGatewayRouteSyncResult,
   TGatewayRouteDnsMode,
+  TGatewayClientCertificateReleaseResult,
+  TGatewayClientCertificateResult,
   TGatewayClientProvisioningAction,
 } from '../data/gateway.js';
 import type { IMailOverviewDomain, IMailOverviewEmail } from './mail.js';
@@ -233,6 +238,72 @@ export interface IReq_SyncGatewayClientRoute extends plugins.typedrequestInterfa
   response: IGatewayRouteSyncResult;
 }
 
+/**
+ * Publishes, replaces or withdraws the one address record a gateway-client ownership holds.
+ *
+ * Gateway-client credentials only, with the `syncDnsRecords` capability; the hostname must match
+ * the client's `hostnamePatterns`. Idempotent: the same record again answers `managed-unchanged`,
+ * and deleting a record the ownership does not hold answers `managed-deleted`. The value must lie
+ * inside the client's `allowedDnsRecordAddresses` (`target-invalid` otherwise). A hostname held by
+ * anything else is `record-conflict` and stays untouched. Requires `dns.clientRecords`.
+ */
+export interface IReq_SyncGatewayClientDnsRecord extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_SyncGatewayClientDnsRecord
+> {
+  method: 'syncGatewayClientDnsRecord';
+  request: {
+    apiToken: string;
+    identity?: never;
+    ownership: IGatewayClientHostnameOwnership;
+  } & (
+    | { record: IGatewayClientDnsRecord; delete?: never }
+    | { delete: true; record?: never }
+  );
+  response: IGatewayClientDnsRecordSyncResult;
+}
+
+/**
+ * Answers the exact certificate for one owned hostname, starting its issuance when none is valid.
+ *
+ * Gateway-client credentials only, with `requestCertificates` and `readCertificates`; the hostname
+ * must match the client's `hostnamePatterns`. No gateway route is needed. The certificate is issued
+ * for exactly this one identifier in the client's own namespace, and asking again after
+ * `renewAfter` answers a renewed one. The `ready` answer carries the private key. Requires
+ * `certificates.exactIssuance`.
+ */
+export interface IReq_GetGatewayClientCertificate extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_GetGatewayClientCertificate
+> {
+  method: 'getGatewayClientCertificate';
+  request: {
+    apiToken: string;
+    identity?: never;
+    ownership: IGatewayClientHostnameOwnership;
+  };
+  response: TGatewayClientCertificateResult;
+}
+
+/**
+ * Removes the certificate material and any issuance an ownership holds, releasing its certificate claim; an address record under the same ownership is unaffected.
+ *
+ * Gateway-client credentials only, with `requestCertificates`. Idempotent: an ownership that holds
+ * nothing answers `unchanged`. Requires `certificates.exactIssuance`.
+ */
+export interface IReq_ReleaseGatewayClientCertificate extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_ReleaseGatewayClientCertificate
+> {
+  method: 'releaseGatewayClientCertificate';
+  request: {
+    apiToken: string;
+    identity?: never;
+    ownership: IGatewayClientHostnameOwnership;
+  };
+  response: TGatewayClientCertificateReleaseResult;
+}
+
 export interface IReq_ReprovisionCertificateDomain extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,
   IReq_ReprovisionCertificateDomain