@serve.zone/interfaces 30.2.0 → 30.3.0

package/changelog.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 2026-09-09 - 30.3.0
+
+### Fixes
+
+- bump @git.zone/tstest to ^4.1.1 (deps-dev)
+  - Updated the test runner dev dependency from ^4.0.0 to ^4.1.1.
+
+### Features
+
+- add private network contracts and typed requests (private-networks)
+  - Introduce private network data models, snapshot validators, contract limits, and FQDN construction.
+  - Add Cloudly typed requests for listing, reading, mutating, and attaching service private networks.
+  - Document private network DNS, membership, retirement, and revocation semantics.
+
 ## 2026-09-09 - 30.2.0
 
 ### Features

package/dist_ts/00_commitinfo_data.js

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

package/dist_ts/data/index.d.ts

@@ -22,6 +22,7 @@ export * from './isolatedrestore.golden.js';
 export * from './mail.js';
 export * from './nodecredential.js';
 export * from './nodeenrollment.js';
+export * from './privatenetwork.js';
 export * from './registry.js';
 export * from './runtimeassignment.js';
 export * from './runtimeconfig.js';

package/dist_ts/data/index.js

@@ -22,6 +22,7 @@ export * from './isolatedrestore.golden.js';
 export * from './mail.js';
 export * from './nodecredential.js';
 export * from './nodeenrollment.js';
+export * from './privatenetwork.js';
 export * from './registry.js';
 export * from './runtimeassignment.js';
 export * from './runtimeconfig.js';
@@ -42,4 +43,4 @@ export * from './traffic.js';
 export * from './user.js';
 export * from './version.js';
 export * from './webpush.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxlQUFlLENBQUM7QUFDOUIsY0FBYyx1QkFBdUIsQ0FBQztBQUN0QyxjQUFjLGlCQUFpQixDQUFDO0FBQ2hDLGNBQWMseUJBQXlCLENBQUM7QUFDeEMsY0FBYywwQkFBMEIsQ0FBQztBQUN6QyxjQUFjLDBCQUEwQixDQUFDO0FBQ3pDLGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyxVQUFVLENBQUM7QUFDekIsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxZQUFZLENBQUM7QUFDM0IsY0FBYyx1QkFBdUIsQ0FBQztBQUN0QyxjQUFjLGNBQWMsQ0FBQztBQUM3QixjQUFjLGdCQUFnQixDQUFDO0FBQy9CLGNBQWMsWUFBWSxDQUFDO0FBQzNCLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyxzQkFBc0IsQ0FBQztBQUNyQyxjQUFjLDZCQUE2QixDQUFDO0FBQzVDLGNBQWMsV0FBVyxDQUFDO0FBQzFCLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyxxQkFBcUIsQ0FBQztBQUNwQyxjQUFjLGVBQWUsQ0FBQztBQUM5QixjQUFjLHdCQUF3QixDQUFDO0FBQ3ZDLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxxQkFBcUIsQ0FBQztBQUNwQyxjQUFjLDZCQUE2QixDQUFDO0FBQzVDLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxrQkFBa0IsQ0FBQztBQUNqQyxjQUFjLGVBQWUsQ0FBQztBQUM5QixjQUFjLGNBQWMsQ0FBQztBQUM3QixjQUFjLHdCQUF3QixDQUFDO0FBQ3ZDLGNBQWMsbUJBQW1CLENBQUM7QUFDbEMsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxvQkFBb0IsQ0FBQztBQUNuQyxjQUFjLGNBQWMsQ0FBQztBQUM3QixjQUFjLFdBQVcsQ0FBQztBQUMxQixjQUFjLGNBQWMsQ0FBQztBQUM3QixjQUFjLGNBQWMsQ0FBQyJ9
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxlQUFlLENBQUM7QUFDOUIsY0FBYyx1QkFBdUIsQ0FBQztBQUN0QyxjQUFjLGlCQUFpQixDQUFDO0FBQ2hDLGNBQWMseUJBQXlCLENBQUM7QUFDeEMsY0FBYywwQkFBMEIsQ0FBQztBQUN6QyxjQUFjLDBCQUEwQixDQUFDO0FBQ3pDLGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyxVQUFVLENBQUM7QUFDekIsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxZQUFZLENBQUM7QUFDM0IsY0FBYyx1QkFBdUIsQ0FBQztBQUN0QyxjQUFjLGNBQWMsQ0FBQztBQUM3QixjQUFjLGdCQUFnQixDQUFDO0FBQy9CLGNBQWMsWUFBWSxDQUFDO0FBQzNCLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyxzQkFBc0IsQ0FBQztBQUNyQyxjQUFjLDZCQUE2QixDQUFDO0FBQzVDLGNBQWMsV0FBVyxDQUFDO0FBQzFCLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyxxQkFBcUIsQ0FBQztBQUNwQyxjQUFjLHFCQUFxQixDQUFDO0FBQ3BDLGNBQWMsZUFBZSxDQUFDO0FBQzlCLGNBQWMsd0JBQXdCLENBQUM7QUFDdkMsY0FBYyxvQkFBb0IsQ0FBQztBQUNuQyxjQUFjLHFCQUFxQixDQUFDO0FBQ3BDLGNBQWMsNkJBQTZCLENBQUM7QUFDNUMsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxnQkFBZ0IsQ0FBQztBQUMvQixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLGtCQUFrQixDQUFDO0FBQ2pDLGNBQWMsZUFBZSxDQUFDO0FBQzlCLGNBQWMsY0FBYyxDQUFDO0FBQzdCLGNBQWMsd0JBQXdCLENBQUM7QUFDdkMsY0FBYyxtQkFBbUIsQ0FBQztBQUNsQyxjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLG9CQUFvQixDQUFDO0FBQ25DLGNBQWMsY0FBYyxDQUFDO0FBQzdCLGNBQWMsV0FBVyxDQUFDO0FBQzFCLGNBQWMsY0FBYyxDQUFDO0FBQzdCLGNBQWMsY0FBYyxDQUFDIn0=

package/dist_ts/data/privatenetwork.d.ts

@@ -0,0 +1,96 @@
+/** Cloudly owns these definitions. Membership never follows node placement. */
+export interface IPrivateNetworkPolicyV1 {
+    connectivity: 'member-full-mesh';
+    /** null denies external resolution; private names are never forwarded. */
+    externalDns: {
+        upstreams: Array<{
+            address: string;
+            port: number;
+        }>;
+        /** true requires an empty suffix list; false requires explicit suffixes. */
+        allowAnyPublicName: boolean;
+        permittedSuffixes: string[];
+    } | null;
+}
+export interface IPrivateNetworkV1 {
+    schemaVersion: 1;
+    id: string;
+    organizationId: string;
+    /** Immutable server-owned keys; display-name changes do not rename DNS. */
+    organizationDnsKey: string;
+    networkDnsKey: string;
+    name: string;
+    revision: number;
+    state: 'active' | 'retiring' | 'retired';
+    policy: IPrivateNetworkPolicyV1;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface IPrivateNetworkAttachmentV1 {
+    networkId: string;
+    /** Sorted unique single-label aliases, reserved per network for this service. */
+    aliases: string[];
+}
+/** Desired membership only. Acceptance is neither packet enforcement nor DNS readiness. */
+export interface IServicePrivateNetworksV1 {
+    schemaVersion: 1;
+    organizationId: string;
+    serviceId: string;
+    revision: number;
+    /** Sorted by networkId; every network must have the same canonical organization. */
+    attachments: IPrivateNetworkAttachmentV1[];
+    /** Exactly the sole attachment, or explicit selection/null when several exist. */
+    defaultNetworkId: string | null;
+}
+interface IPrivateNetworkMutationBaseV1 {
+    schemaVersion: 1;
+    organizationId: string;
+    /** Retain the exact body and this identifier across retries. */
+    mutationId: string;
+}
+export type TPrivateNetworkMutationV1 = IPrivateNetworkMutationBaseV1 & ({
+    operation: 'create';
+    expectedRevision: null;
+    name: string;
+    policy: IPrivateNetworkPolicyV1;
+} | {
+    operation: 'update';
+    networkId: string;
+    expectedRevision: number;
+    name: string;
+    policy: IPrivateNetworkPolicyV1;
+}
+/** Retirement completes only after outstanding grants are denied or independently fenced. */
+ | {
+    operation: 'retire';
+    networkId: string;
+    expectedRevision: number;
+});
+export interface ISetServicePrivateNetworksV1 extends IPrivateNetworkMutationBaseV1 {
+    serviceId: string;
+    /** null means the service has never had a membership document; not an empty list. */
+    expectedRevision: number | null;
+    attachments: IPrivateNetworkAttachmentV1[];
+    defaultNetworkId: string | null;
+}
+export declare const privateNetworkV1Contract: Readonly<{
+    readonly privateRoot: "internal.";
+    readonly maximumAttachments: 16;
+    readonly maximumAliasesPerAttachment: 32;
+    readonly maximumUpstreams: 4;
+    readonly maximumPermittedSuffixes: 64;
+    readonly maximumDnsLeaseMs: 900000;
+    readonly maximumPositiveTtlSeconds: 5;
+    readonly maximumNegativeTtlSeconds: 1;
+    readonly packetAuthorityLifetime: "until-applied-denial-or-independent-fence";
+    readonly omission: "no-effect";
+}>;
+/** Structural validation only; backend IP ownership/reachability and policy fences are required. */
+export declare const snapshotPrivateNetworkPolicyV1: (value: unknown) => IPrivateNetworkPolicyV1;
+export declare const snapshotPrivateNetworkV1: (value: unknown) => IPrivateNetworkV1;
+export declare const snapshotServicePrivateNetworksV1: (value: unknown) => IServicePrivateNetworksV1;
+export declare const snapshotSetServicePrivateNetworksV1: (value: unknown) => ISetServicePrivateNetworksV1;
+export declare const snapshotPrivateNetworkMutationV1: (value: unknown) => TPrivateNetworkMutationV1;
+/** Pure naming helper; it does not reserve a name or create any public DNS/ingress record. */
+export declare const buildPrivateNetworkFqdnV1: (networkValue: unknown, aliasValue: unknown) => string;
+export {};

package/dist_ts/data/privatenetwork.js

@@ -0,0 +1,168 @@
+export const privateNetworkV1Contract = Object.freeze({
+    privateRoot: 'internal.',
+    maximumAttachments: 16,
+    maximumAliasesPerAttachment: 32,
+    maximumUpstreams: 4,
+    maximumPermittedSuffixes: 64,
+    maximumDnsLeaseMs: 900_000,
+    maximumPositiveTtlSeconds: 5,
+    maximumNegativeTtlSeconds: 1,
+    packetAuthorityLifetime: 'until-applied-denial-or-independent-fence',
+    omission: 'no-effect',
+});
+const fail = () => { throw new Error('Private network contract rejected.'); };
+function requireValue(value) { if (!value)
+    fail(); }
+const safe = (operation) => { try {
+    return operation();
+}
+catch {
+    return fail();
+} };
+const object = (value, keys) => {
+    requireValue(value !== null && typeof value === 'object' && !Array.isArray(value));
+    requireValue(Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+    const actual = Reflect.ownKeys(value);
+    requireValue(actual.length === keys.length && keys.every(key => actual.includes(key)));
+    const result = Object.create(null);
+    for (const key of keys) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        requireValue(descriptor?.enumerable && Object.hasOwn(descriptor, 'value'));
+        result[key] = descriptor.value;
+    }
+    return result;
+};
+const array = (value, maximum, read) => {
+    requireValue(Array.isArray(value) && Object.getPrototypeOf(value) === Array.prototype && value.length <= maximum);
+    requireValue(Reflect.ownKeys(value).length === value.length + 1);
+    const result = [];
+    for (let index = 0; index < value.length; index++) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+        requireValue(descriptor?.enumerable && Object.hasOwn(descriptor, 'value'));
+        result.push(read(descriptor.value));
+    }
+    return result;
+};
+const identifier = (value) => {
+    requireValue(typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/.test(value));
+    return value;
+};
+const counter = (value) => {
+    requireValue(typeof value === 'number' && Number.isSafeInteger(value) && value > 0 && value < Number.MAX_SAFE_INTEGER);
+    return value;
+};
+const name = (value) => {
+    requireValue(typeof value === 'string' && value.length > 0 && value.length <= 128
+        && value === value.trim() && !/[\u0000-\u001f\u007f-\u009f\ud800-\udfff]/u.test(value));
+    return value;
+};
+const dnsKey = (value, prefix) => {
+    requireValue(typeof value === 'string' && new RegExp(`^${prefix}-[a-z2-7]{26}$`).test(value));
+    return value;
+};
+const label = (value) => {
+    requireValue(typeof value === 'string' && value.length <= 63
+        && /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(value)
+        && !['localhost', 'internal', 'resolver', 'ns', 'ns1', 'hostmaster'].includes(value));
+    return value;
+};
+const sorted = (values) => {
+    requireValue(values.every((value, index) => index === 0 || values[index - 1] < value));
+    return values;
+};
+const ipv4 = (value) => {
+    requireValue(typeof value === 'string');
+    const parts = value.split('.');
+    requireValue(parts.length === 4 && parts.every(part => /^(?:0|[1-9][0-9]{0,2})$/.test(part) && Number(part) <= 255));
+    requireValue(Number(parts[0]) > 0 && Number(parts[0]) < 224 && value !== '255.255.255.255');
+    return value;
+};
+const publicSuffix = (value) => {
+    requireValue(typeof value === 'string' && value.length <= 253 && value.endsWith('.'));
+    const labels = value.slice(0, -1).split('.');
+    requireValue(labels.length >= 2 && labels.every(part => part.length <= 63
+        && /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(part))
+        && !['internal', 'localhost', 'local', 'arpa'].includes(labels[labels.length - 1]));
+    return value;
+};
+/** Structural validation only; backend IP ownership/reachability and policy fences are required. */
+export const snapshotPrivateNetworkPolicyV1 = (value) => safe(() => {
+    const policy = object(value, ['connectivity', 'externalDns']);
+    requireValue(policy.connectivity === 'member-full-mesh');
+    if (policy.externalDns === null)
+        return { connectivity: 'member-full-mesh', externalDns: null };
+    const external = object(policy.externalDns, ['upstreams', 'allowAnyPublicName', 'permittedSuffixes']);
+    const upstreams = array(external.upstreams, privateNetworkV1Contract.maximumUpstreams, entry => {
+        const upstream = object(entry, ['address', 'port']);
+        const port = counter(upstream.port);
+        requireValue(port <= 65535);
+        return { address: ipv4(upstream.address), port };
+    });
+    requireValue(upstreams.length > 0 && new Set(upstreams.map(upstream => `${upstream.address}:${upstream.port}`)).size === upstreams.length);
+    requireValue(typeof external.allowAnyPublicName === 'boolean');
+    const permittedSuffixes = sorted(array(external.permittedSuffixes, privateNetworkV1Contract.maximumPermittedSuffixes, publicSuffix));
+    requireValue(external.allowAnyPublicName ? permittedSuffixes.length === 0 : permittedSuffixes.length > 0);
+    return { connectivity: 'member-full-mesh', externalDns: {
+            upstreams, allowAnyPublicName: external.allowAnyPublicName, permittedSuffixes,
+        } };
+});
+const membership = (attachmentsValue, defaultValue) => {
+    const attachments = array(attachmentsValue, privateNetworkV1Contract.maximumAttachments, entry => {
+        const attachment = object(entry, ['networkId', 'aliases']);
+        return { networkId: identifier(attachment.networkId),
+            aliases: sorted(array(attachment.aliases, privateNetworkV1Contract.maximumAliasesPerAttachment, label)) };
+    });
+    sorted(attachments.map(attachment => attachment.networkId));
+    const defaultNetworkId = defaultValue === null ? null : identifier(defaultValue);
+    requireValue(defaultNetworkId === null || attachments.some(attachment => attachment.networkId === defaultNetworkId));
+    requireValue(attachments.length !== 1 || defaultNetworkId === attachments[0].networkId);
+    return { attachments, defaultNetworkId };
+};
+export const snapshotPrivateNetworkV1 = (value) => safe(() => {
+    const network = object(value, ['schemaVersion', 'id', 'organizationId', 'organizationDnsKey', 'networkDnsKey',
+        'name', 'revision', 'state', 'policy', 'createdAt', 'updatedAt']);
+    requireValue(network.schemaVersion === 1 && ['active', 'retiring', 'retired'].includes(network.state));
+    const createdAt = counter(network.createdAt);
+    const updatedAt = counter(network.updatedAt);
+    requireValue(updatedAt >= createdAt);
+    return { schemaVersion: 1, id: identifier(network.id), organizationId: identifier(network.organizationId),
+        organizationDnsKey: dnsKey(network.organizationDnsKey, 'o'), networkDnsKey: dnsKey(network.networkDnsKey, 'n'),
+        name: name(network.name), revision: counter(network.revision), state: network.state,
+        policy: snapshotPrivateNetworkPolicyV1(network.policy), createdAt, updatedAt };
+});
+export const snapshotServicePrivateNetworksV1 = (value) => safe(() => {
+    const service = object(value, ['schemaVersion', 'organizationId', 'serviceId', 'revision', 'attachments', 'defaultNetworkId']);
+    requireValue(service.schemaVersion === 1);
+    return { schemaVersion: 1, organizationId: identifier(service.organizationId), serviceId: identifier(service.serviceId),
+        revision: counter(service.revision), ...membership(service.attachments, service.defaultNetworkId) };
+});
+export const snapshotSetServicePrivateNetworksV1 = (value) => safe(() => {
+    const request = object(value, ['schemaVersion', 'organizationId', 'serviceId', 'mutationId', 'expectedRevision', 'attachments', 'defaultNetworkId']);
+    requireValue(request.schemaVersion === 1);
+    return { schemaVersion: 1, organizationId: identifier(request.organizationId), serviceId: identifier(request.serviceId),
+        mutationId: identifier(request.mutationId), expectedRevision: request.expectedRevision === null ? null : counter(request.expectedRevision),
+        ...membership(request.attachments, request.defaultNetworkId) };
+});
+export const snapshotPrivateNetworkMutationV1 = (value) => safe(() => {
+    requireValue(value !== null && typeof value === 'object');
+    const operation = Object.getOwnPropertyDescriptor(value, 'operation')?.value;
+    requireValue(operation === 'create' || operation === 'update' || operation === 'retire');
+    const request = object(value, ['schemaVersion', 'organizationId', 'mutationId', 'operation', 'expectedRevision',
+        ...(operation === 'create' ? [] : ['networkId']), ...(operation === 'retire' ? [] : ['name', 'policy'])]);
+    requireValue(request.schemaVersion === 1);
+    const base = { schemaVersion: 1, organizationId: identifier(request.organizationId), mutationId: identifier(request.mutationId) };
+    if (operation === 'create') {
+        requireValue(request.expectedRevision === null);
+        return { ...base, operation, expectedRevision: null, name: name(request.name), policy: snapshotPrivateNetworkPolicyV1(request.policy) };
+    }
+    const current = { networkId: identifier(request.networkId), expectedRevision: counter(request.expectedRevision) };
+    if (operation === 'retire')
+        return { ...base, ...current, operation };
+    return { ...base, ...current, operation, name: name(request.name), policy: snapshotPrivateNetworkPolicyV1(request.policy) };
+});
+/** Pure naming helper; it does not reserve a name or create any public DNS/ingress record. */
+export const buildPrivateNetworkFqdnV1 = (networkValue, aliasValue) => safe(() => {
+    const network = snapshotPrivateNetworkV1(networkValue);
+    return `${label(aliasValue)}.${network.networkDnsKey}.${network.organizationDnsKey}.${privateNetworkV1Contract.privateRoot}`;
+});
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicHJpdmF0ZW5ldHdvcmsuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL3ByaXZhdGVuZXR3b3JrLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQW1FQSxNQUFNLENBQUMsTUFBTSx3QkFBd0IsR0FBRyxNQUFNLENBQUMsTUFBTSxDQUFDO0lBQ3BELFdBQVcsRUFBRSxXQUFXO0lBQ3hCLGtCQUFrQixFQUFFLEVBQUU7SUFDdEIsMkJBQTJCLEVBQUUsRUFBRTtJQUMvQixnQkFBZ0IsRUFBRSxDQUFDO0lBQ25CLHdCQUF3QixFQUFFLEVBQUU7SUFDNUIsaUJBQWlCLEVBQUUsT0FBTztJQUMxQix5QkFBeUIsRUFBRSxDQUFDO0lBQzVCLHlCQUF5QixFQUFFLENBQUM7SUFDNUIsdUJBQXVCLEVBQUUsMkNBQTJDO0lBQ3BFLFFBQVEsRUFBRSxXQUFXO0NBQ2IsQ0FBQyxDQUFDO0FBRVosTUFBTSxJQUFJLEdBQUcsR0FBVSxFQUFFLEdBQUcsTUFBTSxJQUFJLEtBQUssQ0FBQyxvQ0FBb0MsQ0FBQyxDQUFDLENBQUMsQ0FBQyxDQUFDO0FBQ3JGLFNBQVMsWUFBWSxDQUFDLEtBQWMsSUFBbUIsSUFBSSxDQUFDLEtBQUs7SUFBRSxJQUFJLEVBQUUsQ0FBQyxDQUFDLENBQUM7QUFDNUUsTUFBTSxJQUFJLEdBQUcsQ0FBSSxTQUFrQixFQUFLLEVBQUUsR0FBRyxJQUFJLENBQUM7SUFBQyxPQUFPLFNBQVMsRUFBRSxDQUFDO0FBQUMsQ0FBQztBQUFDLE1BQU0sQ0FBQztJQUFDLE9BQU8sSUFBSSxFQUFFLENBQUM7QUFBQyxDQUFDLENBQUMsQ0FBQyxDQUFDO0FBQ3BHLE1BQU0sTUFBTSxHQUFHLENBQUMsS0FBYyxFQUFFLElBQWMsRUFBMkIsRUFBRTtJQUN6RSxZQUFZLENBQUMsS0FBSyxLQUFLLElBQUksSUFBSSxPQUFPLEtBQUssS0FBSyxRQUFRLElBQUksQ0FBQyxLQUFLLENBQUMsT0FBTyxDQUFDLEtBQUssQ0FBQyxDQUFDLENBQUM7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

package/dist_ts/requests/network.d.ts

@@ -1,4 +1,66 @@
 import * as plugins from '../plugins.js';
+import type { IIdentityCredential } from '../data/user.js';
+import type { IPrivateNetworkV1, IServicePrivateNetworksV1, ISetServicePrivateNetworksV1, TPrivateNetworkMutationV1 } from '../data/privatenetwork.js';
+/** Every request is authorized against live canonical membership and Cloudly policy. */
+export interface IReq_Cloudly_ListPrivateNetworksV1 extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Cloudly_ListPrivateNetworksV1> {
+    method: 'listPrivateNetworksV1';
+    request: {
+        identity: IIdentityCredential;
+        organizationId: string;
+        cursor: string | null;
+        limit: number;
+    };
+    response: {
+        networks: IPrivateNetworkV1[];
+        nextCursor: string | null;
+    };
+}
+export interface IReq_Cloudly_GetPrivateNetworkV1 extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Cloudly_GetPrivateNetworkV1> {
+    method: 'getPrivateNetworkV1';
+    request: {
+        identity: IIdentityCredential;
+        organizationId: string;
+        networkId: string;
+    };
+    response: {
+        network: IPrivateNetworkV1 | null;
+    };
+}
+export interface IReq_Cloudly_MutatePrivateNetworkV1 extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Cloudly_MutatePrivateNetworkV1> {
+    method: 'mutatePrivateNetworkV1';
+    request: {
+        identity: IIdentityCredential;
+        mutation: TPrivateNetworkMutationV1;
+    };
+    /** Historical on replay; neither acceptance nor replay proves applied packet/DNS state. */
+    response: {
+        network: IPrivateNetworkV1;
+        replayed: boolean;
+    };
+}
+export interface IReq_Cloudly_GetServicePrivateNetworksV1 extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Cloudly_GetServicePrivateNetworksV1> {
+    method: 'getServicePrivateNetworksV1';
+    request: {
+        identity: IIdentityCredential;
+        organizationId: string;
+        serviceId: string;
+    };
+    response: {
+        membership: IServicePrivateNetworksV1 | null;
+    };
+}
+export interface IReq_Cloudly_SetServicePrivateNetworksV1 extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Cloudly_SetServicePrivateNetworksV1> {
+    method: 'setServicePrivateNetworksV1';
+    request: {
+        identity: IIdentityCredential;
+        mutation: ISetServicePrivateNetworksV1;
+    };
+    /** Exact desired membership; enforcement and outstanding revocations remain separately observed. */
+    response: {
+        membership: IServicePrivateNetworksV1;
+        replayed: boolean;
+    };
+}
 export interface IRequest_Any_Cloudly_GetNetworkNodes {
     method: 'getNetworkNodes';
     request: {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/interfaces",
-  "version": "30.2.0",
+  "version": "30.3.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.",
   "exports": {
@@ -30,7 +30,7 @@
     "@git.zone/tsbuild": "^4.4.2",
     "@git.zone/tsdoc": "^2.2.0",
     "@git.zone/tsrun": "^2.0.6",
-    "@git.zone/tstest": "^4.0.0",
+    "@git.zone/tstest": "^4.1.1",
     "@types/node": "26.4.1"
   },
   "files": [

package/readme.md

@@ -192,6 +192,32 @@ delivery and the replay receipt must commit in the same authorized transaction.
 The response contains only the immutable secret/version reference; no bearer or
 hash is returned. Revocation removes current delivery from the metadata.
 
+### Private Networks
+
+`requests.network` defines organization-scoped network create/update/retire and
+service attachment operations. Mutations require a retained idempotency ID and
+an exact expected revision; `null` means no prior document. Cloudly must authorize
+each request against live canonical membership and policy, reserve aliases
+transactionally, reject cross-organization attachments, and retain historical
+receipts. These contracts do not implement the backend or node enforcement.
+
+`data.buildPrivateNetworkFqdnV1` produces
+`<alias>.n-<26 lowercase base32 characters>.o-<26 lowercase base32 characters>.internal.`
+from server-owned immutable DNS keys. Aliases are lowercase ASCII labels unique
+per network. Display-name edits do not rename DNS. A sole attachment selects its
+search suffix; several attachments require an explicit default or no search
+suffix. Fully qualified names remain unambiguous across networks. Network policy
+permits member-to-member connectivity and explicitly configures or denies external
+DNS forwarding. Creating an alias does not publish public DNS, ingress or ports.
+
+The snapshot helpers validate and detach content; they do not authenticate it,
+reserve names, prove membership, or report applied state. Packet authority remains
+until an applied denial or independent fence. DNS snapshots have a separate maximum
+15-minute validity, with positive TTLs capped at five seconds and negative TTLs at
+one second. DNS expiry does not prove packet revocation or permit identity reuse.
+Retirement and attachment responses describe desired or historical metadata;
+consumers must separately track outstanding node revocations and readiness.
+
 ### Node-Bound Runtime Assignments
 
 The `data` namespace exports `IRuntimeAssignmentV1`, canonical digest helpers,

package/ts/00_commitinfo_data.ts

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

package/ts/data/index.ts

@@ -22,6 +22,7 @@ export * from './isolatedrestore.golden.js';
 export * from './mail.js';
 export * from './nodecredential.js';
 export * from './nodeenrollment.js';
+export * from './privatenetwork.js';
 export * from './registry.js';
 export * from './runtimeassignment.js';
 export * from './runtimeconfig.js';

package/ts/data/privatenetwork.ts

@@ -0,0 +1,234 @@
+/** Cloudly owns these definitions. Membership never follows node placement. */
+export interface IPrivateNetworkPolicyV1 {
+  connectivity: 'member-full-mesh';
+  /** null denies external resolution; private names are never forwarded. */
+  externalDns: {
+    upstreams: Array<{ address: string; port: number }>;
+    /** true requires an empty suffix list; false requires explicit suffixes. */
+    allowAnyPublicName: boolean;
+    permittedSuffixes: string[];
+  } | null;
+}
+
+export interface IPrivateNetworkV1 {
+  schemaVersion: 1;
+  id: string;
+  organizationId: string;
+  /** Immutable server-owned keys; display-name changes do not rename DNS. */
+  organizationDnsKey: string;
+  networkDnsKey: string;
+  name: string;
+  revision: number;
+  state: 'active' | 'retiring' | 'retired';
+  policy: IPrivateNetworkPolicyV1;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface IPrivateNetworkAttachmentV1 {
+  networkId: string;
+  /** Sorted unique single-label aliases, reserved per network for this service. */
+  aliases: string[];
+}
+
+/** Desired membership only. Acceptance is neither packet enforcement nor DNS readiness. */
+export interface IServicePrivateNetworksV1 {
+  schemaVersion: 1;
+  organizationId: string;
+  serviceId: string;
+  revision: number;
+  /** Sorted by networkId; every network must have the same canonical organization. */
+  attachments: IPrivateNetworkAttachmentV1[];
+  /** Exactly the sole attachment, or explicit selection/null when several exist. */
+  defaultNetworkId: string | null;
+}
+
+interface IPrivateNetworkMutationBaseV1 {
+  schemaVersion: 1;
+  organizationId: string;
+  /** Retain the exact body and this identifier across retries. */
+  mutationId: string;
+}
+
+export type TPrivateNetworkMutationV1 = IPrivateNetworkMutationBaseV1 & (
+  | { operation: 'create'; expectedRevision: null; name: string; policy: IPrivateNetworkPolicyV1 }
+  | { operation: 'update'; networkId: string; expectedRevision: number; name: string; policy: IPrivateNetworkPolicyV1 }
+  /** Retirement completes only after outstanding grants are denied or independently fenced. */
+  | { operation: 'retire'; networkId: string; expectedRevision: number }
+);
+
+export interface ISetServicePrivateNetworksV1 extends IPrivateNetworkMutationBaseV1 {
+  serviceId: string;
+  /** null means the service has never had a membership document; not an empty list. */
+  expectedRevision: number | null;
+  attachments: IPrivateNetworkAttachmentV1[];
+  defaultNetworkId: string | null;
+}
+
+export const privateNetworkV1Contract = Object.freeze({
+  privateRoot: 'internal.',
+  maximumAttachments: 16,
+  maximumAliasesPerAttachment: 32,
+  maximumUpstreams: 4,
+  maximumPermittedSuffixes: 64,
+  maximumDnsLeaseMs: 900_000,
+  maximumPositiveTtlSeconds: 5,
+  maximumNegativeTtlSeconds: 1,
+  packetAuthorityLifetime: 'until-applied-denial-or-independent-fence',
+  omission: 'no-effect',
+} as const);
+
+const fail = (): never => { throw new Error('Private network contract rejected.'); };
+function requireValue(value: unknown): asserts value { if (!value) fail(); }
+const safe = <T>(operation: () => T): T => { try { return operation(); } catch { return fail(); } };
+const object = (value: unknown, keys: string[]): Record<string, unknown> => {
+  requireValue(value !== null && typeof value === 'object' && !Array.isArray(value));
+  requireValue(Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null);
+  const actual = Reflect.ownKeys(value);
+  requireValue(actual.length === keys.length && keys.every(key => actual.includes(key)));
+  const result: Record<string, unknown> = Object.create(null);
+  for (const key of keys) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    requireValue(descriptor?.enumerable && Object.hasOwn(descriptor, 'value'));
+    result[key] = descriptor.value;
+  }
+  return result;
+};
+const array = <T>(value: unknown, maximum: number, read: (item: unknown) => T): T[] => {
+  requireValue(Array.isArray(value) && Object.getPrototypeOf(value) === Array.prototype && value.length <= maximum);
+  requireValue(Reflect.ownKeys(value).length === value.length + 1);
+  const result: T[] = [];
+  for (let index = 0; index < value.length; index++) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+    requireValue(descriptor?.enumerable && Object.hasOwn(descriptor, 'value'));
+    result.push(read(descriptor.value));
+  }
+  return result;
+};
+const identifier = (value: unknown): string => {
+  requireValue(typeof value === 'string' && /^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/.test(value));
+  return value;
+};
+const counter = (value: unknown): number => {
+  requireValue(typeof value === 'number' && Number.isSafeInteger(value) && value > 0 && value < Number.MAX_SAFE_INTEGER);
+  return value;
+};
+const name = (value: unknown): string => {
+  requireValue(typeof value === 'string' && value.length > 0 && value.length <= 128
+    && value === value.trim() && !/[\u0000-\u001f\u007f-\u009f\ud800-\udfff]/u.test(value));
+  return value;
+};
+const dnsKey = (value: unknown, prefix: 'o' | 'n'): string => {
+  requireValue(typeof value === 'string' && new RegExp(`^${prefix}-[a-z2-7]{26}$`).test(value));
+  return value;
+};
+const label = (value: unknown): string => {
+  requireValue(typeof value === 'string' && value.length <= 63
+    && /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(value)
+    && !['localhost', 'internal', 'resolver', 'ns', 'ns1', 'hostmaster'].includes(value));
+  return value;
+};
+const sorted = (values: string[]): string[] => {
+  requireValue(values.every((value, index) => index === 0 || values[index - 1] < value));
+  return values;
+};
+const ipv4 = (value: unknown): string => {
+  requireValue(typeof value === 'string');
+  const parts = value.split('.');
+  requireValue(parts.length === 4 && parts.every(part => /^(?:0|[1-9][0-9]{0,2})$/.test(part) && Number(part) <= 255));
+  requireValue(Number(parts[0]) > 0 && Number(parts[0]) < 224 && value !== '255.255.255.255');
+  return value;
+};
+const publicSuffix = (value: unknown): string => {
+  requireValue(typeof value === 'string' && value.length <= 253 && value.endsWith('.'));
+  const labels = value.slice(0, -1).split('.');
+  requireValue(labels.length >= 2 && labels.every(part => part.length <= 63
+    && /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(part))
+    && !['internal', 'localhost', 'local', 'arpa'].includes(labels[labels.length - 1]));
+  return value;
+};
+
+/** Structural validation only; backend IP ownership/reachability and policy fences are required. */
+export const snapshotPrivateNetworkPolicyV1 = (value: unknown): IPrivateNetworkPolicyV1 => safe(() => {
+  const policy = object(value, ['connectivity', 'externalDns']);
+  requireValue(policy.connectivity === 'member-full-mesh');
+  if (policy.externalDns === null) return { connectivity: 'member-full-mesh', externalDns: null };
+  const external = object(policy.externalDns, ['upstreams', 'allowAnyPublicName', 'permittedSuffixes']);
+  const upstreams = array(external.upstreams, privateNetworkV1Contract.maximumUpstreams, entry => {
+    const upstream = object(entry, ['address', 'port']);
+    const port = counter(upstream.port);
+    requireValue(port <= 65535);
+    return { address: ipv4(upstream.address), port };
+  });
+  requireValue(upstreams.length > 0 && new Set(upstreams.map(upstream => `${upstream.address}:${upstream.port}`)).size === upstreams.length);
+  requireValue(typeof external.allowAnyPublicName === 'boolean');
+  const permittedSuffixes = sorted(array(external.permittedSuffixes, privateNetworkV1Contract.maximumPermittedSuffixes, publicSuffix));
+  requireValue(external.allowAnyPublicName ? permittedSuffixes.length === 0 : permittedSuffixes.length > 0);
+  return { connectivity: 'member-full-mesh', externalDns: {
+    upstreams, allowAnyPublicName: external.allowAnyPublicName, permittedSuffixes,
+  } };
+});
+
+const membership = (attachmentsValue: unknown, defaultValue: unknown): Pick<IServicePrivateNetworksV1, 'attachments' | 'defaultNetworkId'> => {
+  const attachments = array(attachmentsValue, privateNetworkV1Contract.maximumAttachments, entry => {
+    const attachment = object(entry, ['networkId', 'aliases']);
+    return { networkId: identifier(attachment.networkId),
+      aliases: sorted(array(attachment.aliases, privateNetworkV1Contract.maximumAliasesPerAttachment, label)) };
+  });
+  sorted(attachments.map(attachment => attachment.networkId));
+  const defaultNetworkId = defaultValue === null ? null : identifier(defaultValue);
+  requireValue(defaultNetworkId === null || attachments.some(attachment => attachment.networkId === defaultNetworkId));
+  requireValue(attachments.length !== 1 || defaultNetworkId === attachments[0].networkId);
+  return { attachments, defaultNetworkId };
+};
+
+export const snapshotPrivateNetworkV1 = (value: unknown): IPrivateNetworkV1 => safe(() => {
+  const network = object(value, ['schemaVersion', 'id', 'organizationId', 'organizationDnsKey', 'networkDnsKey',
+    'name', 'revision', 'state', 'policy', 'createdAt', 'updatedAt']);
+  requireValue(network.schemaVersion === 1 && ['active', 'retiring', 'retired'].includes(network.state as string));
+  const createdAt = counter(network.createdAt);
+  const updatedAt = counter(network.updatedAt);
+  requireValue(updatedAt >= createdAt);
+  return { schemaVersion: 1, id: identifier(network.id), organizationId: identifier(network.organizationId),
+    organizationDnsKey: dnsKey(network.organizationDnsKey, 'o'), networkDnsKey: dnsKey(network.networkDnsKey, 'n'),
+    name: name(network.name), revision: counter(network.revision), state: network.state as IPrivateNetworkV1['state'],
+    policy: snapshotPrivateNetworkPolicyV1(network.policy), createdAt, updatedAt };
+});
+
+export const snapshotServicePrivateNetworksV1 = (value: unknown): IServicePrivateNetworksV1 => safe(() => {
+  const service = object(value, ['schemaVersion', 'organizationId', 'serviceId', 'revision', 'attachments', 'defaultNetworkId']);
+  requireValue(service.schemaVersion === 1);
+  return { schemaVersion: 1, organizationId: identifier(service.organizationId), serviceId: identifier(service.serviceId),
+    revision: counter(service.revision), ...membership(service.attachments, service.defaultNetworkId) };
+});
+
+export const snapshotSetServicePrivateNetworksV1 = (value: unknown): ISetServicePrivateNetworksV1 => safe(() => {
+  const request = object(value, ['schemaVersion', 'organizationId', 'serviceId', 'mutationId', 'expectedRevision', 'attachments', 'defaultNetworkId']);
+  requireValue(request.schemaVersion === 1);
+  return { schemaVersion: 1, organizationId: identifier(request.organizationId), serviceId: identifier(request.serviceId),
+    mutationId: identifier(request.mutationId), expectedRevision: request.expectedRevision === null ? null : counter(request.expectedRevision),
+    ...membership(request.attachments, request.defaultNetworkId) };
+});
+
+export const snapshotPrivateNetworkMutationV1 = (value: unknown): TPrivateNetworkMutationV1 => safe(() => {
+  requireValue(value !== null && typeof value === 'object');
+  const operation = Object.getOwnPropertyDescriptor(value, 'operation')?.value;
+  requireValue(operation === 'create' || operation === 'update' || operation === 'retire');
+  const request = object(value, ['schemaVersion', 'organizationId', 'mutationId', 'operation', 'expectedRevision',
+    ...(operation === 'create' ? [] : ['networkId']), ...(operation === 'retire' ? [] : ['name', 'policy'])]);
+  requireValue(request.schemaVersion === 1);
+  const base = { schemaVersion: 1 as const, organizationId: identifier(request.organizationId), mutationId: identifier(request.mutationId) };
+  if (operation === 'create') {
+    requireValue(request.expectedRevision === null);
+    return { ...base, operation, expectedRevision: null, name: name(request.name), policy: snapshotPrivateNetworkPolicyV1(request.policy) };
+  }
+  const current = { networkId: identifier(request.networkId), expectedRevision: counter(request.expectedRevision) };
+  if (operation === 'retire') return { ...base, ...current, operation };
+  return { ...base, ...current, operation, name: name(request.name), policy: snapshotPrivateNetworkPolicyV1(request.policy) };
+});
+
+/** Pure naming helper; it does not reserve a name or create any public DNS/ingress record. */
+export const buildPrivateNetworkFqdnV1 = (networkValue: unknown, aliasValue: unknown): string => safe(() => {
+  const network = snapshotPrivateNetworkV1(networkValue);
+  return `${label(aliasValue)}.${network.networkDnsKey}.${network.organizationDnsKey}.${privateNetworkV1Contract.privateRoot}`;
+});

package/ts/requests/network.ts

@@ -1,4 +1,52 @@
 import * as plugins from '../plugins.js';
+import type { IIdentityCredential } from '../data/user.js';
+import type {
+  IPrivateNetworkV1, IServicePrivateNetworksV1, ISetServicePrivateNetworksV1,
+  TPrivateNetworkMutationV1,
+} from '../data/privatenetwork.js';
+
+/** Every request is authorized against live canonical membership and Cloudly policy. */
+export interface IReq_Cloudly_ListPrivateNetworksV1 extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Cloudly_ListPrivateNetworksV1
+> {
+  method: 'listPrivateNetworksV1';
+  request: { identity: IIdentityCredential; organizationId: string; cursor: string | null; limit: number };
+  response: { networks: IPrivateNetworkV1[]; nextCursor: string | null };
+}
+
+export interface IReq_Cloudly_GetPrivateNetworkV1 extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Cloudly_GetPrivateNetworkV1
+> {
+  method: 'getPrivateNetworkV1';
+  request: { identity: IIdentityCredential; organizationId: string; networkId: string };
+  response: { network: IPrivateNetworkV1 | null };
+}
+
+export interface IReq_Cloudly_MutatePrivateNetworkV1 extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Cloudly_MutatePrivateNetworkV1
+> {
+  method: 'mutatePrivateNetworkV1';
+  request: { identity: IIdentityCredential; mutation: TPrivateNetworkMutationV1 };
+  /** Historical on replay; neither acceptance nor replay proves applied packet/DNS state. */
+  response: { network: IPrivateNetworkV1; replayed: boolean };
+}
+
+export interface IReq_Cloudly_GetServicePrivateNetworksV1 extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Cloudly_GetServicePrivateNetworksV1
+> {
+  method: 'getServicePrivateNetworksV1';
+  request: { identity: IIdentityCredential; organizationId: string; serviceId: string };
+  response: { membership: IServicePrivateNetworksV1 | null };
+}
+
+export interface IReq_Cloudly_SetServicePrivateNetworksV1 extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest, IReq_Cloudly_SetServicePrivateNetworksV1
+> {
+  method: 'setServicePrivateNetworksV1';
+  request: { identity: IIdentityCredential; mutation: ISetServicePrivateNetworksV1 };
+  /** Exact desired membership; enforcement and outstanding revocations remain separately observed. */
+  response: { membership: IServicePrivateNetworksV1; replayed: boolean };
+}
 
 export interface IRequest_Any_Cloudly_GetNetworkNodes {
   method: 'getNetworkNodes';