@serve.zone/interfaces 7.2.0 → 7.3.0

package/changelog.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 2026-06-09 - 7.3.0
+
+### Features
+
+- add gateway client data models and request contracts (gateway)
+  - Add gateway capability, domain, DNS record, route, and token context interfaces
+  - Add TypedRequest contracts for gateway capabilities, client context, domains, DNS records, route sync, and certificate import/export
+  - Export gateway data and request modules through existing barrels
+
 ## 2026-06-09 - 7.2.0
 
 ### Features

package/dist_ts/00_commitinfo_data.js

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

package/dist_ts/data/gateway.d.ts

@@ -0,0 +1,219 @@
+import type { TDnsRecordType } from './dns.js';
+/**
+ * Type of platform acting as a gateway client against a gateway (dcrouter).
+ */
+export type TGatewayClientType = 'onebox' | 'cloudly' | 'custom';
+/**
+ * Role resolved for a gateway API token or identity.
+ */
+export type TGatewayTokenRole = 'admin' | 'gatewayClient' | 'operator';
+/**
+ * Feature surface a gateway exposes to connected gateway clients.
+ */
+export interface IGatewayCapabilities {
+    routes: {
+        read: boolean;
+        write: boolean;
+        idempotentSync: boolean;
+    };
+    domains: {
+        read: boolean;
+        write: boolean;
+    };
+    certificates: {
+        read: boolean;
+        export: boolean;
+        forceRenew: boolean;
+    };
+    email: {
+        domains: boolean;
+        inbound: boolean;
+        outbound: boolean;
+    };
+    remoteIngress: {
+        enabled: boolean;
+    };
+    dns: {
+        authoritative: boolean;
+        providerManaged: boolean;
+    };
+    http3: {
+        enabled: boolean;
+    };
+}
+/**
+ * Capability flags granted to a gateway client token.
+ */
+export interface IGatewayTokenCapabilities {
+    readDomains?: boolean;
+    readDnsRecords?: boolean;
+    syncRoutes?: boolean;
+    syncDnsRecords?: boolean;
+    requestCertificates?: boolean;
+}
+/**
+ * A host/ports combination a gateway client is allowed to route traffic to.
+ */
+export interface IGatewayRouteTargetAllowance {
+    host: string;
+    ports: number[];
+}
+/**
+ * Resolved auth context for a gateway client token, as reported by the gateway.
+ * Scopes are gateway-defined strings; the closed scope list lives in the gateway.
+ */
+export interface IGatewayClientContext {
+    role: TGatewayTokenRole;
+    scopes: string[];
+    gatewayClient?: {
+        type: TGatewayClientType;
+        id: string;
+    };
+    hostnamePatterns: string[];
+    allowedRouteTargets: IGatewayRouteTargetAllowance[];
+    capabilities: IGatewayTokenCapabilities;
+}
+/**
+ * Where a gateway-managed domain is sourced from.
+ *
+ * - 'dcrouter' → the gateway itself is the authoritative DNS server.
+ * - 'provider' → the domain is managed through an external DNS provider.
+ */
+export type TGatewayDomainSource = 'dcrouter' | 'provider';
+/**
+ * What a gateway client may do with a gateway-exposed domain.
+ */
+export interface IGatewayDomainCapabilities {
+    canCreateSubdomains: boolean;
+    canManageDnsRecords: boolean;
+    canIssueCertificates: boolean;
+    canHostEmail: boolean;
+}
+/**
+ * A domain a gateway exposes to gateway clients for app hosting.
+ */
+export interface IGatewayDomain {
+    id: string;
+    /** Fully qualified domain name (e.g. 'example.com'). */
+    name: string;
+    source: TGatewayDomainSource;
+    /** Gateway-internal DNS provider id — only set when source === 'provider'. */
+    providerId?: string;
+    /** True when the gateway is the authoritative DNS server for this domain. */
+    authoritative: boolean;
+    nameservers?: string[];
+    /** Provider's internal zone identifier — only set when source === 'provider'. */
+    externalZoneId?: string;
+    /** Last time records were synced from the provider — only set when source === 'provider'. */
+    lastSyncedAt?: number;
+    description?: string;
+    createdAt: number;
+    updatedAt: number;
+    createdBy: string;
+    capabilities: IGatewayDomainCapabilities;
+    /** Number of gateway-client services currently using this domain. */
+    serviceCount?: number;
+    /** Gateway UI path for managing this domain. */
+    managePath?: string;
+}
+/**
+ * DNS record view for gateway-client app hostnames.
+ * Records with status 'missing' describe expected-but-absent records and
+ * use type 'MISSING' placeholders where applicable.
+ */
+export interface IGatewayDnsRecord {
+    id: string;
+    /** Id of the parent gateway domain. */
+    domainId: string;
+    domainName?: string;
+    /** Fully qualified record name (e.g. 'www.example.com'). */
+    name: string;
+    type: TDnsRecordType | 'MISSING';
+    value: string;
+    /** TTL in seconds. */
+    ttl: number;
+    /** Provider-specific: whether the record is proxied (e.g. Cloudflare). */
+    proxied?: boolean;
+    source: 'local' | 'synced';
+    /** Provider's internal record id — only set for provider records. */
+    providerRecordId?: string;
+    createdAt: number;
+    updatedAt: number;
+    createdBy: string;
+    status: 'active' | 'missing';
+    gatewayClientType: TGatewayClientType;
+    gatewayClientId: string;
+    /** App identifier within the owning gateway client platform. */
+    appId: string;
+    hostname: string;
+    routeId?: string;
+    serviceName?: string;
+    /** Gateway UI path for managing this record. */
+    managePath?: string;
+}
+/**
+ * Ownership of a gateway-client-synced route: which platform, which platform
+ * instance, and which app/hostname the route belongs to.
+ */
+export interface IGatewayClientOwnership {
+    gatewayClientType?: TGatewayClientType;
+    gatewayClientId?: string;
+    /** App identifier within the owning gateway client platform. */
+    appId: string;
+    hostname: string;
+}
+/**
+ * A single forward target of a gateway route.
+ */
+export interface IGatewayRouteTarget {
+    host: string;
+    port: number;
+}
+/**
+ * Match condition for a gateway route.
+ */
+export interface IGatewayRouteMatch {
+    ports: number[];
+    domains: string[];
+    path?: string;
+}
+/**
+ * TLS handling for a gateway route. 'terminate' with certificate 'auto'
+ * requests gateway-managed ACME certificates.
+ */
+export interface IGatewayRouteTls {
+    mode: 'terminate' | 'passthrough' | 'terminate-and-reencrypt';
+    certificate?: 'auto';
+}
+/**
+ * Forward action of a gateway route.
+ */
+export interface IGatewayRouteAction {
+    type: 'forward';
+    targets: IGatewayRouteTarget[];
+    tls?: IGatewayRouteTls;
+    websocket?: {
+        enabled: boolean;
+    };
+}
+/**
+ * Platform-neutral desired state for one gateway route.
+ *
+ * This is deliberately narrower than the gateway's internal route config:
+ * control planes express route intent with this shape and the gateway maps
+ * it onto its own proxy configuration.
+ */
+export interface IGatewayRouteConfig {
+    name: string;
+    match: IGatewayRouteMatch;
+    action: IGatewayRouteAction;
+}
+/**
+ * Result of an idempotent gateway route sync.
+ */
+export interface IGatewayRouteSyncResult {
+    success: boolean;
+    action?: 'created' | 'updated' | 'deleted' | 'unchanged';
+    routeId?: string;
+    message?: string;
+}

package/dist_ts/data/gateway.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZ2F0ZXdheS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL2RhdGEvZ2F0ZXdheS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiIn0=

package/dist_ts/data/index.d.ts

@@ -7,6 +7,7 @@ export * from './docker.js';
 export * from './domain.js';
 export * from './event.js';
 export * from './externalregistry.js';
+export * from './gateway.js';
 export * from './hostedapp.js';
 export * from './image.js';
 export * from './mail.js';

package/dist_ts/data/index.js

@@ -7,6 +7,7 @@ export * from './docker.js';
 export * from './domain.js';
 export * from './event.js';
 export * from './externalregistry.js';
+export * from './gateway.js';
 export * from './hostedapp.js';
 export * from './image.js';
 export * from './mail.js';
@@ -24,4 +25,4 @@ export * from './taskexecution.js';
 export * from './traffic.js';
 export * from './user.js';
 export * from './version.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxpQkFBaUIsQ0FBQztBQUNoQyxjQUFjLFVBQVUsQ0FBQztBQUN6QixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLFlBQVksQ0FBQztBQUMzQixjQUFjLHVCQUF1QixDQUFDO0FBQ3RDLGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyxZQUFZLENBQUM7QUFDM0IsY0FBYyxXQUFXLENBQUM7QUFDMUIsY0FBYyxlQUFlLENBQUM7QUFDOUIsY0FBYyxtQkFBbUIsQ0FBQztBQUNsQyxjQUFjLGtCQUFrQixDQUFDO0FBQ2pDLGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxrQkFBa0IsQ0FBQztBQUNqQyxjQUFjLGVBQWUsQ0FBQztBQUM5QixjQUFjLGNBQWMsQ0FBQztBQUM3QixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLG9CQUFvQixDQUFDO0FBQ25DLGNBQWMsY0FBYyxDQUFDO0FBQzdCLGNBQWMsV0FBVyxDQUFDO0FBQzFCLGNBQWMsY0FBYyxDQUFDIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxpQkFBaUIsQ0FBQztBQUNoQyxjQUFjLFVBQVUsQ0FBQztBQUN6QixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLFlBQVksQ0FBQztBQUMzQixjQUFjLHVCQUF1QixDQUFDO0FBQ3RDLGNBQWMsY0FBYyxDQUFDO0FBQzdCLGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyxZQUFZLENBQUM7QUFDM0IsY0FBYyxXQUFXLENBQUM7QUFDMUIsY0FBYyxlQUFlLENBQUM7QUFDOUIsY0FBYyxtQkFBbUIsQ0FBQztBQUNsQyxjQUFjLGtCQUFrQixDQUFDO0FBQ2pDLGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxrQkFBa0IsQ0FBQztBQUNqQyxjQUFjLGVBQWUsQ0FBQztBQUM5QixjQUFjLGNBQWMsQ0FBQztBQUM3QixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLG9CQUFvQixDQUFDO0FBQ25DLGNBQWMsY0FBYyxDQUFDO0FBQzdCLGNBQWMsV0FBVyxDQUFDO0FBQzFCLGNBQWMsY0FBYyxDQUFDIn0=

package/dist_ts/requests/gateway.d.ts

@@ -0,0 +1,93 @@
+import * as plugins from '../plugins.js';
+import type { IIdentity } from '../data/user.js';
+import type { IGatewayCapabilities, IGatewayClientContext, IGatewayClientOwnership, IGatewayDnsRecord, IGatewayDomain, IGatewayRouteConfig, IGatewayRouteSyncResult } from '../data/gateway.js';
+/**
+ * Gateway client contracts: the machine-facing API a gateway (dcrouter)
+ * serves to gateway clients (Onebox, Cloudly/Coreflow).
+ *
+ * Wire note: these methods are already deployed; auth fields stay top-level
+ * (identity?/apiToken?) for wire compatibility, unlike the nested auth
+ * envelope used by the newer mail contracts. The method strings
+ * 'exportCertificate' and 'importCertificate' likewise keep their deployed
+ * names and deliberately lack a gateway prefix.
+ */
+export interface IReq_GetGatewayCapabilities extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_GetGatewayCapabilities> {
+    method: 'getGatewayCapabilities';
+    request: {
+        identity?: IIdentity;
+        apiToken?: string;
+    };
+    response: {
+        capabilities: IGatewayCapabilities;
+    };
+}
+export interface IReq_GetGatewayClientContext extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_GetGatewayClientContext> {
+    method: 'getGatewayClientContext';
+    request: {
+        identity?: IIdentity;
+        apiToken?: string;
+    };
+    response: {
+        context: IGatewayClientContext;
+        capabilities: IGatewayCapabilities;
+    };
+}
+export interface IReq_GetGatewayClientDomains extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_GetGatewayClientDomains> {
+    method: 'getGatewayClientDomains';
+    request: {
+        identity?: IIdentity;
+        apiToken?: string;
+        gatewayClientId?: string;
+    };
+    response: {
+        domains: IGatewayDomain[];
+    };
+}
+export interface IReq_GetGatewayClientDnsRecords extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_GetGatewayClientDnsRecords> {
+    method: 'getGatewayClientDnsRecords';
+    request: {
+        identity?: IIdentity;
+        apiToken?: string;
+        gatewayClientId?: string;
+    };
+    response: {
+        records: IGatewayDnsRecord[];
+    };
+}
+export interface IReq_SyncGatewayClientRoute extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_SyncGatewayClientRoute> {
+    method: 'syncGatewayClientRoute';
+    request: {
+        identity?: IIdentity;
+        apiToken?: string;
+        ownership: IGatewayClientOwnership;
+        route?: IGatewayRouteConfig;
+        enabled?: boolean;
+        delete?: boolean;
+    };
+    response: IGatewayRouteSyncResult;
+}
+export interface IReq_ExportCertificate extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_ExportCertificate> {
+    method: 'exportCertificate';
+    request: {
+        identity?: IIdentity;
+        apiToken?: string;
+        domain: string;
+    };
+    response: {
+        success: boolean;
+        cert?: plugins.tsclass.network.ICert;
+        message?: string;
+    };
+}
+export interface IReq_ImportCertificate extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_ImportCertificate> {
+    method: 'importCertificate';
+    request: {
+        identity?: IIdentity;
+        apiToken?: string;
+        cert: plugins.tsclass.network.ICert;
+    };
+    response: {
+        success: boolean;
+        message?: string;
+    };
+}

package/dist_ts/requests/gateway.js

@@ -0,0 +1,2 @@
+import * as plugins from '../plugins.js';
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZ2F0ZXdheS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL3JlcXVlc3RzL2dhdGV3YXkudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLE9BQU8sTUFBTSxlQUFlLENBQUMifQ==

package/dist_ts/requests/index.d.ts

@@ -10,6 +10,7 @@ import * as deploymentRequests from './deployment.js';
 import * as dnsRequests from './dns.js';
 import * as domainRequests from './domain.js';
 import * as externalRegistryRequests from './externalregistry.js';
+import * as gatewayRequests from './gateway.js';
 import * as hostedAppRequests from './hostedapp.js';
 import * as identityRequests from './identity.js';
 import * as imageRequests from './image.js';
@@ -28,7 +29,7 @@ import * as settingsRequests from './settings.js';
 import * as statusRequests from './status.js';
 import * as taskRequests from './task.js';
 import * as versionRequests from './version.js';
-export { adminRequests as admin, appStoreRequests as appstore, baremetalRequests as baremetal, baseOsRequests as baseos, backupRequests as backup, certificateRequests as certificate, clusterRequests as cluster, configRequests as config, deploymentRequests as deployment, dnsRequests as dns, domainRequests as domain, externalRegistryRequests as externalRegistry, hostedAppRequests as hostedapp, identityRequests as identity, imageRequests as image, informRequests as inform, logRequests as log, mailRequests as mail, networkRequests as network, nodeRequests as node, platformRequests as platform, routingRequests as routing, secretBundleRequests as secretbundle, secretGroupRequests as secretgroup, serverRequests as server, serviceRequests as service, settingsRequests as settings, statusRequests as status, taskRequests as task, versionRequests as version, };
+export { adminRequests as admin, appStoreRequests as appstore, baremetalRequests as baremetal, baseOsRequests as baseos, backupRequests as backup, certificateRequests as certificate, clusterRequests as cluster, configRequests as config, deploymentRequests as deployment, dnsRequests as dns, domainRequests as domain, externalRegistryRequests as externalRegistry, gatewayRequests as gateway, hostedAppRequests as hostedapp, identityRequests as identity, imageRequests as image, informRequests as inform, logRequests as log, mailRequests as mail, networkRequests as network, nodeRequests as node, platformRequests as platform, routingRequests as routing, secretBundleRequests as secretbundle, secretGroupRequests as secretgroup, serverRequests as server, serviceRequests as service, settingsRequests as settings, statusRequests as status, taskRequests as task, versionRequests as version, };
 export * from './inform.js';
 export * from './hostedapp.js';
 export * from './mail.js';

package/dist_ts/requests/index.js

@@ -11,6 +11,7 @@ import * as deploymentRequests from './deployment.js';
 import * as dnsRequests from './dns.js';
 import * as domainRequests from './domain.js';
 import * as externalRegistryRequests from './externalregistry.js';
+import * as gatewayRequests from './gateway.js';
 import * as hostedAppRequests from './hostedapp.js';
 import * as identityRequests from './identity.js';
 import * as imageRequests from './image.js';
@@ -29,8 +30,8 @@ import * as settingsRequests from './settings.js';
 import * as statusRequests from './status.js';
 import * as taskRequests from './task.js';
 import * as versionRequests from './version.js';
-export { adminRequests as admin, appStoreRequests as appstore, baremetalRequests as baremetal, baseOsRequests as baseos, backupRequests as backup, certificateRequests as certificate, clusterRequests as cluster, configRequests as config, deploymentRequests as deployment, dnsRequests as dns, domainRequests as domain, externalRegistryRequests as externalRegistry, hostedAppRequests as hostedapp, identityRequests as identity, imageRequests as image, informRequests as inform, logRequests as log, mailRequests as mail, networkRequests as network, nodeRequests as node, platformRequests as platform, routingRequests as routing, secretBundleRequests as secretbundle, secretGroupRequests as secretgroup, serverRequests as server, serviceRequests as service, settingsRequests as settings, statusRequests as status, taskRequests as task, versionRequests as version, };
+export { adminRequests as admin, appStoreRequests as appstore, baremetalRequests as baremetal, baseOsRequests as baseos, backupRequests as backup, certificateRequests as certificate, clusterRequests as cluster, configRequests as config, deploymentRequests as deployment, dnsRequests as dns, domainRequests as domain, externalRegistryRequests as externalRegistry, gatewayRequests as gateway, hostedAppRequests as hostedapp, identityRequests as identity, imageRequests as image, informRequests as inform, logRequests as log, mailRequests as mail, networkRequests as network, nodeRequests as node, platformRequests as platform, routingRequests as routing, secretBundleRequests as secretbundle, secretGroupRequests as secretgroup, serverRequests as server, serviceRequests as service, settingsRequests as settings, statusRequests as status, taskRequests as task, versionRequests as version, };
 export * from './inform.js';
 export * from './hostedapp.js';
 export * from './mail.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9yZXF1ZXN0cy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLGVBQWUsQ0FBQztBQUV6QyxPQUFPLEtBQUssYUFBYSxNQUFNLFlBQVksQ0FBQztBQUM1QyxPQUFPLEtBQUssZ0JBQWdCLE1BQU0sZUFBZSxDQUFDO0FBQ2xELE9BQU8sS0FBSyxpQkFBaUIsTUFBTSxnQkFBZ0IsQ0FBQztBQUNwRCxPQUFPLEtBQUssY0FBYyxNQUFNLGFBQWEsQ0FBQztBQUM5QyxPQUFPLEtBQUssY0FBYyxNQUFNLGFBQWEsQ0FBQztBQUM5QyxPQUFPLEtBQUssbUJBQW1CLE1BQU0sa0JBQWtCLENBQUM7QUFDeEQsT0FBTyxLQUFLLGVBQWUsTUFBTSxjQUFjLENBQUM7QUFDaEQsT0FBTyxLQUFLLGNBQWMsTUFBTSxhQUFhLENBQUM7QUFDOUMsT0FBTyxLQUFLLGtCQUFrQixNQUFNLGlCQUFpQixDQUFDO0FBQ3RELE9BQU8sS0FBSyxXQUFXLE1BQU0sVUFBVSxDQUFDO0FBQ3hDLE9BQU8sS0FBSyxjQUFjLE1BQU0sYUFBYSxDQUFDO0FBQzlDLE9BQU8sS0FBSyx3QkFBd0IsTUFBTSx1QkFBdUIsQ0FBQztBQUNsRSxPQUFPLEtBQUssaUJBQWlCLE1BQU0sZ0JBQWdCLENBQUM7QUFDcEQsT0FBTyxLQUFLLGdCQUFnQixNQUFNLGVBQWUsQ0FBQztBQUNsRCxPQUFPLEtBQUssYUFBYSxNQUFNLFlBQVksQ0FBQztBQUM1QyxPQUFPLEtBQUssY0FBYyxNQUFNLGFBQWEsQ0FBQztBQUM5QyxPQUFPLEtBQUssV0FBVyxNQUFNLFVBQVUsQ0FBQztBQUN4QyxPQUFPLEtBQUssWUFBWSxNQUFNLFdBQVcsQ0FBQztBQUMxQyxPQUFPLEtBQUssZUFBZSxNQUFNLGNBQWMsQ0FBQztBQUNoRCxPQUFPLEtBQUssWUFBWSxNQUFNLFdBQVcsQ0FBQztBQUMxQyxPQUFPLEtBQUssZ0JBQWdCLE1BQU0sZUFBZSxDQUFDO0FBQ2xELE9BQU8sS0FBSyxlQUFlLE1BQU0sY0FBYyxDQUFDO0FBQ2hELE9BQU8sS0FBSyxvQkFBb0IsTUFBTSxtQkFBbUIsQ0FBQztBQUMxRCxPQUFPLEtBQUssbUJBQW1CLE1BQU0sa0JBQWtCLENBQUM7QUFDeEQsT0FBTyxLQUFLLGNBQWMsTUFBTSxhQUFhLENBQUM7QUFDOUMsT0FBTyxLQUFLLGVBQWUsTUFBTSxjQUFjLENBQUM7QUFDaEQsT0FBTyxLQUFLLGdCQUFnQixNQUFNLGVBQWUsQ0FBQztBQUNsRCxPQUFPLEtBQUssY0FBYyxNQUFNLGFBQWEsQ0FBQztBQUM5QyxPQUFPLEtBQUssWUFBWSxNQUFNLFdBQVcsQ0FBQztBQUMxQyxPQUFPLEtBQUssZUFBZSxNQUFNLGNBQWMsQ0FBQztBQUVoRCxPQUFPLEVBQ0wsYUFBYSxJQUFJLEtBQUssRUFDdEIsZ0JBQWdCLElBQUksUUFBUSxFQUM1QixpQkFBaUIsSUFBSSxTQUFTLEVBQzlCLGNBQWMsSUFBSSxNQUFNLEVBQ3hCLGNBQWMsSUFBSSxNQUFNLEVBQ3hCLG1CQUFtQixJQUFJLFdBQVcsRUFDbEMsZUFBZSxJQUFJLE9BQU8sRUFDMUIsY0FBYyxJQUFJLE1BQU0sRUFDeEIsa0JBQWtCLElBQUksVUFBVSxFQUNoQyxXQUFXLElBQUksR0FBRyxFQUNsQixjQUFjLElBQUksTUFBTSxFQUN4Qix3QkFBd0IsSUFBSSxnQkFBZ0IsRUFDNUMsaUJBQWlCLElBQUksU0FBUyxFQUM5QixnQkFBZ0IsSUFBSSxRQUFRLEVBQzVCLGFBQWEsSUFBSSxLQUFLLEVBQ3RCLGNBQWMsSUFBSSxNQUFNLEVBQ3hCLFdBQVcsSUFBSSxHQUFHLEVBQ2xCLFlBQVksSUFBSSxJQUFJLEVBQ3BCLGVBQWUsSUFBSSxPQUFPLEVBQzFCLFlBQVksSUFBSSxJQUFJLEVBQ3BCLGdCQUFnQixJQUFJLFFBQVEsRUFDNUIsZUFBZSxJQUFJLE9BQU8sRUFDMUIsb0JBQW9CLElBQUksWUFBWSxFQUNwQyxtQkFBbUIsSUFBSSxXQUFXLEVBQ2xDLGNBQWMsSUFBSSxNQUFNLEVBQ3hCLGVBQWUsSUFBSSxPQUFPLEVBQzFCLGdCQUFnQixJQUFJLFFBQVEsRUFDNUIsY0FBYyxJQUFJLE1BQU0sRUFDeEIsWUFBWSxJQUFJLElBQUksRUFDcEIsZUFBZSxJQUFJLE9BQU8sR0FDM0IsQ0FBQztBQUVGLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyxXQUFXLENBQUMifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9yZXF1ZXN0cy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLGVBQWUsQ0FBQztBQUV6QyxPQUFPLEtBQUssYUFBYSxNQUFNLFlBQVksQ0FBQztBQUM1QyxPQUFPLEtBQUssZ0JBQWdCLE1BQU0sZUFBZSxDQUFDO0FBQ2xELE9BQU8sS0FBSyxpQkFBaUIsTUFBTSxnQkFBZ0IsQ0FBQztBQUNwRCxPQUFPLEtBQUssY0FBYyxNQUFNLGFBQWEsQ0FBQztBQUM5QyxPQUFPLEtBQUssY0FBYyxNQUFNLGFBQWEsQ0FBQztBQUM5QyxPQUFPLEtBQUssbUJBQW1CLE1BQU0sa0JBQWtCLENBQUM7QUFDeEQsT0FBTyxLQUFLLGVBQWUsTUFBTSxjQUFjLENBQUM7QUFDaEQsT0FBTyxLQUFLLGNBQWMsTUFBTSxhQUFhLENBQUM7QUFDOUMsT0FBTyxLQUFLLGtCQUFrQixNQUFNLGlCQUFpQixDQUFDO0FBQ3RELE9BQU8sS0FBSyxXQUFXLE1BQU0sVUFBVSxDQUFDO0FBQ3hDLE9BQU8sS0FBSyxjQUFjLE1BQU0sYUFBYSxDQUFDO0FBQzlDLE9BQU8sS0FBSyx3QkFBd0IsTUFBTSx1QkFBdUIsQ0FBQztBQUNsRSxPQUFPLEtBQUssZUFBZSxNQUFNLGNBQWMsQ0FBQztBQUNoRCxPQUFPLEtBQUssaUJBQWlCLE1BQU0sZ0JBQWdCLENBQUM7QUFDcEQsT0FBTyxLQUFLLGdCQUFnQixNQUFNLGVBQWUsQ0FBQztBQUNsRCxPQUFPLEtBQUssYUFBYSxNQUFNLFlBQVksQ0FBQztBQUM1QyxPQUFPLEtBQUssY0FBYyxNQUFNLGFBQWEsQ0FBQztBQUM5QyxPQUFPLEtBQUssV0FBVyxNQUFNLFVBQVUsQ0FBQztBQUN4QyxPQUFPLEtBQUssWUFBWSxNQUFNLFdBQVcsQ0FBQztBQUMxQyxPQUFPLEtBQUssZUFBZSxNQUFNLGNBQWMsQ0FBQztBQUNoRCxPQUFPLEtBQUssWUFBWSxNQUFNLFdBQVcsQ0FBQztBQUMxQyxPQUFPLEtBQUssZ0JBQWdCLE1BQU0sZUFBZSxDQUFDO0FBQ2xELE9BQU8sS0FBSyxlQUFlLE1BQU0sY0FBYyxDQUFDO0FBQ2hELE9BQU8sS0FBSyxvQkFBb0IsTUFBTSxtQkFBbUIsQ0FBQztBQUMxRCxPQUFPLEtBQUssbUJBQW1CLE1BQU0sa0JBQWtCLENBQUM7QUFDeEQsT0FBTyxLQUFLLGNBQWMsTUFBTSxhQUFhLENBQUM7QUFDOUMsT0FBTyxLQUFLLGVBQWUsTUFBTSxjQUFjLENBQUM7QUFDaEQsT0FBTyxLQUFLLGdCQUFnQixNQUFNLGVBQWUsQ0FBQztBQUNsRCxPQUFPLEtBQUssY0FBYyxNQUFNLGFBQWEsQ0FBQztBQUM5QyxPQUFPLEtBQUssWUFBWSxNQUFNLFdBQVcsQ0FBQztBQUMxQyxPQUFPLEtBQUssZUFBZSxNQUFNLGNBQWMsQ0FBQztBQUVoRCxPQUFPLEVBQ0wsYUFBYSxJQUFJLEtBQUssRUFDdEIsZ0JBQWdCLElBQUksUUFBUSxFQUM1QixpQkFBaUIsSUFBSSxTQUFTLEVBQzlCLGNBQWMsSUFBSSxNQUFNLEVBQ3hCLGNBQWMsSUFBSSxNQUFNLEVBQ3hCLG1CQUFtQixJQUFJLFdBQVcsRUFDbEMsZUFBZSxJQUFJLE9BQU8sRUFDMUIsY0FBYyxJQUFJLE1BQU0sRUFDeEIsa0JBQWtCLElBQUksVUFBVSxFQUNoQyxXQUFXLElBQUksR0FBRyxFQUNsQixjQUFjLElBQUksTUFBTSxFQUN4Qix3QkFBd0IsSUFBSSxnQkFBZ0IsRUFDNUMsZUFBZSxJQUFJLE9BQU8sRUFDMUIsaUJBQWlCLElBQUksU0FBUyxFQUM5QixnQkFBZ0IsSUFBSSxRQUFRLEVBQzVCLGFBQWEsSUFBSSxLQUFLLEVBQ3RCLGNBQWMsSUFBSSxNQUFNLEVBQ3hCLFdBQVcsSUFBSSxHQUFHLEVBQ2xCLFlBQVksSUFBSSxJQUFJLEVBQ3BCLGVBQWUsSUFBSSxPQUFPLEVBQzFCLFlBQVksSUFBSSxJQUFJLEVBQ3BCLGdCQUFnQixJQUFJLFFBQVEsRUFDNUIsZUFBZSxJQUFJLE9BQU8sRUFDMUIsb0JBQW9CLElBQUksWUFBWSxFQUNwQyxtQkFBbUIsSUFBSSxXQUFXLEVBQ2xDLGNBQWMsSUFBSSxNQUFNLEVBQ3hCLGVBQWUsSUFBSSxPQUFPLEVBQzFCLGdCQUFnQixJQUFJLFFBQVEsRUFDNUIsY0FBYyxJQUFJLE1BQU0sRUFDeEIsWUFBWSxJQUFJLElBQUksRUFDcEIsZUFBZSxJQUFJLE9BQU8sR0FDM0IsQ0FBQztBQUVGLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyxXQUFXLENBQUMifQ==

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/interfaces",
-  "version": "7.2.0",
+  "version": "7.3.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.",
   "exports": {

package/ts/00_commitinfo_data.ts

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

package/ts/data/gateway.ts

@@ -0,0 +1,236 @@
+import type { TDnsRecordType } from './dns.js';
+
+/**
+ * Type of platform acting as a gateway client against a gateway (dcrouter).
+ */
+export type TGatewayClientType = 'onebox' | 'cloudly' | 'custom';
+
+/**
+ * Role resolved for a gateway API token or identity.
+ */
+export type TGatewayTokenRole = 'admin' | 'gatewayClient' | 'operator';
+
+/**
+ * Feature surface a gateway exposes to connected gateway clients.
+ */
+export interface IGatewayCapabilities {
+  routes: {
+    read: boolean;
+    write: boolean;
+    idempotentSync: boolean;
+  };
+  domains: {
+    read: boolean;
+    write: boolean;
+  };
+  certificates: {
+    read: boolean;
+    export: boolean;
+    forceRenew: boolean;
+  };
+  email: {
+    domains: boolean;
+    inbound: boolean;
+    outbound: boolean;
+  };
+  remoteIngress: {
+    enabled: boolean;
+  };
+  dns: {
+    authoritative: boolean;
+    providerManaged: boolean;
+  };
+  http3: {
+    enabled: boolean;
+  };
+}
+
+/**
+ * Capability flags granted to a gateway client token.
+ */
+export interface IGatewayTokenCapabilities {
+  readDomains?: boolean;
+  readDnsRecords?: boolean;
+  syncRoutes?: boolean;
+  syncDnsRecords?: boolean;
+  requestCertificates?: boolean;
+}
+
+/**
+ * A host/ports combination a gateway client is allowed to route traffic to.
+ */
+export interface IGatewayRouteTargetAllowance {
+  host: string;
+  ports: number[];
+}
+
+/**
+ * Resolved auth context for a gateway client token, as reported by the gateway.
+ * Scopes are gateway-defined strings; the closed scope list lives in the gateway.
+ */
+export interface IGatewayClientContext {
+  role: TGatewayTokenRole;
+  scopes: string[];
+  gatewayClient?: {
+    type: TGatewayClientType;
+    id: string;
+  };
+  hostnamePatterns: string[];
+  allowedRouteTargets: IGatewayRouteTargetAllowance[];
+  capabilities: IGatewayTokenCapabilities;
+}
+
+/**
+ * Where a gateway-managed domain is sourced from.
+ *
+ * - 'dcrouter' → the gateway itself is the authoritative DNS server.
+ * - 'provider' → the domain is managed through an external DNS provider.
+ */
+export type TGatewayDomainSource = 'dcrouter' | 'provider';
+
+/**
+ * What a gateway client may do with a gateway-exposed domain.
+ */
+export interface IGatewayDomainCapabilities {
+  canCreateSubdomains: boolean;
+  canManageDnsRecords: boolean;
+  canIssueCertificates: boolean;
+  canHostEmail: boolean;
+}
+
+/**
+ * A domain a gateway exposes to gateway clients for app hosting.
+ */
+export interface IGatewayDomain {
+  id: string;
+  /** Fully qualified domain name (e.g. 'example.com'). */
+  name: string;
+  source: TGatewayDomainSource;
+  /** Gateway-internal DNS provider id — only set when source === 'provider'. */
+  providerId?: string;
+  /** True when the gateway is the authoritative DNS server for this domain. */
+  authoritative: boolean;
+  nameservers?: string[];
+  /** Provider's internal zone identifier — only set when source === 'provider'. */
+  externalZoneId?: string;
+  /** Last time records were synced from the provider — only set when source === 'provider'. */
+  lastSyncedAt?: number;
+  description?: string;
+  createdAt: number;
+  updatedAt: number;
+  createdBy: string;
+  capabilities: IGatewayDomainCapabilities;
+  /** Number of gateway-client services currently using this domain. */
+  serviceCount?: number;
+  /** Gateway UI path for managing this domain. */
+  managePath?: string;
+}
+
+/**
+ * DNS record view for gateway-client app hostnames.
+ * Records with status 'missing' describe expected-but-absent records and
+ * use type 'MISSING' placeholders where applicable.
+ */
+export interface IGatewayDnsRecord {
+  id: string;
+  /** Id of the parent gateway domain. */
+  domainId: string;
+  domainName?: string;
+  /** Fully qualified record name (e.g. 'www.example.com'). */
+  name: string;
+  type: TDnsRecordType | 'MISSING';
+  value: string;
+  /** TTL in seconds. */
+  ttl: number;
+  /** Provider-specific: whether the record is proxied (e.g. Cloudflare). */
+  proxied?: boolean;
+  source: 'local' | 'synced';
+  /** Provider's internal record id — only set for provider records. */
+  providerRecordId?: string;
+  createdAt: number;
+  updatedAt: number;
+  createdBy: string;
+  status: 'active' | 'missing';
+  gatewayClientType: TGatewayClientType;
+  gatewayClientId: string;
+  /** App identifier within the owning gateway client platform. */
+  appId: string;
+  hostname: string;
+  routeId?: string;
+  serviceName?: string;
+  /** Gateway UI path for managing this record. */
+  managePath?: string;
+}
+
+/**
+ * Ownership of a gateway-client-synced route: which platform, which platform
+ * instance, and which app/hostname the route belongs to.
+ */
+export interface IGatewayClientOwnership {
+  gatewayClientType?: TGatewayClientType;
+  gatewayClientId?: string;
+  /** App identifier within the owning gateway client platform. */
+  appId: string;
+  hostname: string;
+}
+
+/**
+ * A single forward target of a gateway route.
+ */
+export interface IGatewayRouteTarget {
+  host: string;
+  port: number;
+}
+
+/**
+ * Match condition for a gateway route.
+ */
+export interface IGatewayRouteMatch {
+  ports: number[];
+  domains: string[];
+  path?: string;
+}
+
+/**
+ * TLS handling for a gateway route. 'terminate' with certificate 'auto'
+ * requests gateway-managed ACME certificates.
+ */
+export interface IGatewayRouteTls {
+  mode: 'terminate' | 'passthrough' | 'terminate-and-reencrypt';
+  certificate?: 'auto';
+}
+
+/**
+ * Forward action of a gateway route.
+ */
+export interface IGatewayRouteAction {
+  type: 'forward';
+  targets: IGatewayRouteTarget[];
+  tls?: IGatewayRouteTls;
+  websocket?: {
+    enabled: boolean;
+  };
+}
+
+/**
+ * Platform-neutral desired state for one gateway route.
+ *
+ * This is deliberately narrower than the gateway's internal route config:
+ * control planes express route intent with this shape and the gateway maps
+ * it onto its own proxy configuration.
+ */
+export interface IGatewayRouteConfig {
+  name: string;
+  match: IGatewayRouteMatch;
+  action: IGatewayRouteAction;
+}
+
+/**
+ * Result of an idempotent gateway route sync.
+ */
+export interface IGatewayRouteSyncResult {
+  success: boolean;
+  action?: 'created' | 'updated' | 'deleted' | 'unchanged';
+  routeId?: string;
+  message?: string;
+}

package/ts/data/index.ts

@@ -7,6 +7,7 @@ export * from './docker.js';
 export * from './domain.js';
 export * from './event.js';
 export * from './externalregistry.js';
+export * from './gateway.js';
 export * from './hostedapp.js';
 export * from './image.js';
 export * from './mail.js';

package/ts/requests/gateway.ts

@@ -0,0 +1,130 @@
+import * as plugins from '../plugins.js';
+import type { IIdentity } from '../data/user.js';
+import type {
+  IGatewayCapabilities,
+  IGatewayClientContext,
+  IGatewayClientOwnership,
+  IGatewayDnsRecord,
+  IGatewayDomain,
+  IGatewayRouteConfig,
+  IGatewayRouteSyncResult,
+} from '../data/gateway.js';
+
+/**
+ * Gateway client contracts: the machine-facing API a gateway (dcrouter)
+ * serves to gateway clients (Onebox, Cloudly/Coreflow).
+ *
+ * Wire note: these methods are already deployed; auth fields stay top-level
+ * (identity?/apiToken?) for wire compatibility, unlike the nested auth
+ * envelope used by the newer mail contracts. The method strings
+ * 'exportCertificate' and 'importCertificate' likewise keep their deployed
+ * names and deliberately lack a gateway prefix.
+ */
+
+export interface IReq_GetGatewayCapabilities extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_GetGatewayCapabilities
+> {
+  method: 'getGatewayCapabilities';
+  request: {
+    identity?: IIdentity;
+    apiToken?: string;
+  };
+  response: {
+    capabilities: IGatewayCapabilities;
+  };
+}
+
+export interface IReq_GetGatewayClientContext extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_GetGatewayClientContext
+> {
+  method: 'getGatewayClientContext';
+  request: {
+    identity?: IIdentity;
+    apiToken?: string;
+  };
+  response: {
+    context: IGatewayClientContext;
+    capabilities: IGatewayCapabilities;
+  };
+}
+
+export interface IReq_GetGatewayClientDomains extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_GetGatewayClientDomains
+> {
+  method: 'getGatewayClientDomains';
+  request: {
+    identity?: IIdentity;
+    apiToken?: string;
+    gatewayClientId?: string;
+  };
+  response: {
+    domains: IGatewayDomain[];
+  };
+}
+
+export interface IReq_GetGatewayClientDnsRecords extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_GetGatewayClientDnsRecords
+> {
+  method: 'getGatewayClientDnsRecords';
+  request: {
+    identity?: IIdentity;
+    apiToken?: string;
+    gatewayClientId?: string;
+  };
+  response: {
+    records: IGatewayDnsRecord[];
+  };
+}
+
+export interface IReq_SyncGatewayClientRoute extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_SyncGatewayClientRoute
+> {
+  method: 'syncGatewayClientRoute';
+  request: {
+    identity?: IIdentity;
+    apiToken?: string;
+    ownership: IGatewayClientOwnership;
+    route?: IGatewayRouteConfig;
+    enabled?: boolean;
+    delete?: boolean;
+  };
+  response: IGatewayRouteSyncResult;
+}
+
+export interface IReq_ExportCertificate extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_ExportCertificate
+> {
+  method: 'exportCertificate';
+  request: {
+    identity?: IIdentity;
+    apiToken?: string;
+    domain: string;
+  };
+  response: {
+    success: boolean;
+    cert?: plugins.tsclass.network.ICert;
+    message?: string;
+  };
+}
+
+export interface IReq_ImportCertificate extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_ImportCertificate
+> {
+  method: 'importCertificate';
+  request: {
+    identity?: IIdentity;
+    apiToken?: string;
+    cert: plugins.tsclass.network.ICert;
+  };
+  response: {
+    success: boolean;
+    message?: string;
+  };
+}

package/ts/requests/index.ts

@@ -12,6 +12,7 @@ import * as deploymentRequests from './deployment.js';
 import * as dnsRequests from './dns.js';
 import * as domainRequests from './domain.js';
 import * as externalRegistryRequests from './externalregistry.js';
+import * as gatewayRequests from './gateway.js';
 import * as hostedAppRequests from './hostedapp.js';
 import * as identityRequests from './identity.js';
 import * as imageRequests from './image.js';
@@ -44,6 +45,7 @@ export {
   dnsRequests as dns,
   domainRequests as domain,
   externalRegistryRequests as externalRegistry,
+  gatewayRequests as gateway,
   hostedAppRequests as hostedapp,
   identityRequests as identity,
   imageRequests as image,