@serve.zone/interfaces 32.20.1 → 32.22.0

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/data/index.d.ts

@@ -3,6 +3,7 @@ export * from './cluster.js';
 export * from './clusterruntime.js';
 export * from './clustervpn.js';
 export * from './clusteringress.js';
+export * from './clusteringressdesignation.js';
 export * from './clusterrelaycredential.js';
 export * from './config.js';
 export * from './corestore.js';
@@ -40,6 +41,8 @@ export * from './networkprojection.js';
 export type { IRuntimeNetworkRouterPacketGrant, IRuntimeNetworkRouterProjection } from './networkrouter.js';
 export type { IRuntimeNetworkHostIngress, IRuntimeNetworkHostPacketGrant, IRuntimeNetworkHostProjection } from './networkhost.js';
 export { runtimeNetworkHostContract } from './networkhost.js';
+export type { IRuntimeNetworkWorkloadIngress, IRuntimeNetworkWorkloadIngressPacketGrant, IRuntimeNetworkWorkloadIngressProjection } from './networkworkloadingress.js';
+export { runtimeNetworkWorkloadIngressContract } from './networkworkloadingress.js';
 export * from './networkprotection.js';
 export * from './networksigning.js';
 export * from './privatenetwork.js';
@@ -48,6 +51,7 @@ export * from './releaseversion.js';
 export * from './runtimeassignment.js';
 export * from './runtimeconfig.js';
 export * from './runtimestorageclaim.js';
+export * from './runtimelocalstorageclaim.js';
 export * from './runtimesession.js';
 export * from './runtimeterminalreceipt.js';
 export * from './secret.js';

package/dist_ts/data/index.js

@@ -3,6 +3,7 @@ export * from './cluster.js';
 export * from './clusterruntime.js';
 export * from './clustervpn.js';
 export * from './clusteringress.js';
+export * from './clusteringressdesignation.js';
 export * from './clusterrelaycredential.js';
 export * from './config.js';
 export * from './corestore.js';
@@ -38,6 +39,7 @@ export * from './networklease.js';
 export * from './networknode.js';
 export * from './networkprojection.js';
 export { runtimeNetworkHostContract } from './networkhost.js';
+export { runtimeNetworkWorkloadIngressContract } from './networkworkloadingress.js';
 export * from './networkprotection.js';
 export * from './networksigning.js';
 export * from './privatenetwork.js';
@@ -46,6 +48,7 @@ export * from './releaseversion.js';
 export * from './runtimeassignment.js';
 export * from './runtimeconfig.js';
 export * from './runtimestorageclaim.js';
+export * from './runtimelocalstorageclaim.js';
 export * from './runtimesession.js';
 export * from './runtimeterminalreceipt.js';
 export * from './secret.js';
@@ -66,4 +69,4 @@ export * from './traffic.js';
 export * from './user.js';
 export * from './version.js';
 export * from './webpush.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxxQkFBcUIsQ0FBQztBQUNwQyxjQUFjLGlCQUFpQixDQUFDO0FBQ2hDLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyw2QkFBNkIsQ0FBQztBQUM1QyxjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLGdCQUFnQixDQUFDO0FBQy9CLGNBQWMsZUFBZSxDQUFDO0FBQzlCLGNBQWMsdUJBQXVCLENBQUM7QUFDdEMsY0FBYyxpQkFBaUIsQ0FBQztBQUNoQyxjQUFjLHlCQUF5QixDQUFDO0FBQ3hDLGNBQWMsMEJBQTBCLENBQUM7QUFDekMsY0FBYywwQkFBMEIsQ0FBQztBQUN6QyxjQUFjLGdCQUFnQixDQUFDO0FBQy9CLGNBQWMsVUFBVSxDQUFDO0FBQ3pCLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsWUFBWSxDQUFDO0FBQzNCLGNBQWMsdUJBQXVCLENBQUM7QUFDdEMsY0FBYyxtQkFBbUIsQ0FBQztBQUNsQyxjQUFjLGNBQWMsQ0FBQztBQUM3QixjQUFjLGdCQUFnQixDQUFDO0FBQy9CLGNBQWMsWUFBWSxDQUFDO0FBQzNCLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyxzQkFBc0IsQ0FBQztBQUNyQyxjQUFjLDZCQUE2QixDQUFDO0FBQzVDLGNBQWMsV0FBVyxDQUFDO0FBQzFCLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyxxQkFBcUIsQ0FBQztBQUNwQyxjQUFjLHlCQUF5QixDQUFDO0FBQ3hDLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyx5QkFBeUIsQ0FBQztBQUN4QyxjQUFjLHVCQUF1QixDQUFDO0FBQ3RDLGNBQWMsd0JBQXdCLENBQUM7QUFDdkMsY0FBYyxzQkFBc0IsQ0FBQztBQUNyQyxjQUFjLG1CQUFtQixDQUFDO0FBQ2xDLGNBQWMsa0JBQWtCLENBQUM7QUFDakMsY0FBYyx3QkFBd0IsQ0FBQztBQUd2QyxPQUFPLEVBQUUsMEJBQTBCLEVBQUUsTUFBTSxrQkFBa0IsQ0FBQztBQUM5RCxjQUFjLHdCQUF3QixDQUFDO0FBQ3ZDLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyxxQkFBcUIsQ0FBQztBQUNwQyxjQUFjLGVBQWUsQ0FBQztBQUM5QixjQUFjLHFCQUFxQixDQUFDO0FBQ3BDLGNBQWMsd0JBQXdCLENBQUM7QUFDdkMsY0FBYyxvQkFBb0IsQ0FBQztBQUNuQyxjQUFjLDBCQUEwQixDQUFDO0FBQ3pDLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyw2QkFBNkIsQ0FBQztBQUM1QyxjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLGdCQUFnQixDQUFDO0FBQy9CLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsa0JBQWtCLENBQUM7QUFDakMsY0FBYyxlQUFlLENBQUM7QUFDOUIsY0FBYyw0QkFBNEIsQ0FBQztBQUMzQyxjQUFjLHNCQUFzQixDQUFDO0FBQ3JDLGNBQWMsY0FBYyxDQUFDO0FBQzdCLGNBQWMsd0JBQXdCLENBQUM7QUFDdkMsY0FBYyxtQkFBbUIsQ0FBQztBQUNsQyxjQUFjLHFCQUFxQixDQUFDO0FBQ3BDLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxXQUFXLENBQUM7QUFDMUIsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxjQUFjLENBQUMifQ==
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxxQkFBcUIsQ0FBQztBQUNwQyxjQUFjLGlCQUFpQixDQUFDO0FBQ2hDLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyxnQ0FBZ0MsQ0FBQztBQUMvQyxjQUFjLDZCQUE2QixDQUFDO0FBQzVDLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyxlQUFlLENBQUM7QUFDOUIsY0FBYyx1QkFBdUIsQ0FBQztBQUN0QyxjQUFjLGlCQUFpQixDQUFDO0FBQ2hDLGNBQWMseUJBQXlCLENBQUM7QUFDeEMsY0FBYywwQkFBMEIsQ0FBQztBQUN6QyxjQUFjLDBCQUEwQixDQUFDO0FBQ3pDLGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyxVQUFVLENBQUM7QUFDekIsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxZQUFZLENBQUM7QUFDM0IsY0FBYyx1QkFBdUIsQ0FBQztBQUN0QyxjQUFjLG1CQUFtQixDQUFDO0FBQ2xDLGNBQWMsY0FBYyxDQUFDO0FBQzdCLGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyxZQUFZLENBQUM7QUFDM0IsY0FBYyxxQkFBcUIsQ0FBQztBQUNwQyxjQUFjLHNCQUFzQixDQUFDO0FBQ3JDLGNBQWMsNkJBQTZCLENBQUM7QUFDNUMsY0FBYyxXQUFXLENBQUM7QUFDMUIsY0FBYyxxQkFBcUIsQ0FBQztBQUNwQyxjQUFjLHFCQUFxQixDQUFDO0FBQ3BDLGNBQWMseUJBQXlCLENBQUM7QUFDeEMsY0FBYyxxQkFBcUIsQ0FBQztBQUNwQyxjQUFjLHlCQUF5QixDQUFDO0FBQ3hDLGNBQWMsdUJBQXVCLENBQUM7QUFDdEMsY0FBYyx3QkFBd0IsQ0FBQztBQUN2QyxjQUFjLHNCQUFzQixDQUFDO0FBQ3JDLGNBQWMsbUJBQW1CLENBQUM7QUFDbEMsY0FBYyxrQkFBa0IsQ0FBQztBQUNqQyxjQUFjLHdCQUF3QixDQUFDO0FBR3ZDLE9BQU8sRUFBRSwwQkFBMEIsRUFBRSxNQUFNLGtCQUFrQixDQUFDO0FBRzlELE9BQU8sRUFBRSxxQ0FBcUMsRUFBRSxNQUFNLDZCQUE2QixDQUFDO0FBQ3BGLGNBQWMsd0JBQXdCLENBQUM7QUFDdkMsY0FBYyxxQkFBcUIsQ0FBQztBQUNwQyxjQUFjLHFCQUFxQixDQUFDO0FBQ3BDLGNBQWMsZUFBZSxDQUFDO0FBQzlCLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyx3QkFBd0IsQ0FBQztBQUN2QyxjQUFjLG9CQUFvQixDQUFDO0FBQ25DLGNBQWMsMEJBQTBCLENBQUM7QUFDekMsY0FBYywrQkFBK0IsQ0FBQztBQUM5QyxjQUFjLHFCQUFxQixDQUFDO0FBQ3BDLGNBQWMsNkJBQTZCLENBQUM7QUFDNUMsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxnQkFBZ0IsQ0FBQztBQUMvQixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLGtCQUFrQixDQUFDO0FBQ2pDLGNBQWMsZUFBZSxDQUFDO0FBQzlCLGNBQWMsNEJBQTRCLENBQUM7QUFDM0MsY0FBYyxzQkFBc0IsQ0FBQztBQUNyQyxjQUFjLGNBQWMsQ0FBQztBQUM3QixjQUFjLHdCQUF3QixDQUFDO0FBQ3ZDLGNBQWMsbUJBQW1CLENBQUM7QUFDbEMsY0FBYyxxQkFBcUIsQ0FBQztBQUNwQyxjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLG9CQUFvQixDQUFDO0FBQ25DLGNBQWMsY0FBYyxDQUFDO0FBQzdCLGNBQWMsV0FBVyxDQUFDO0FBQzFCLGNBQWMsY0FBYyxDQUFDO0FBQzdCLGNBQWMsY0FBYyxDQUFDIn0=

package/dist_ts/data/networkprojection.d.ts

@@ -4,6 +4,7 @@ import type { IRuntimeNetworkHandoffLease, IRuntimeNetworkProtectedAuthority } f
 import type { IPrivateNetwork, IServicePrivateNetworks, IServicePrivateNetworkDnsPolicy } from './privatenetwork.js';
 import { type IRuntimeNetworkRouterPacketGrant, type IRuntimeNetworkRouterProjection } from './networkrouter.js';
 import { type IRuntimeNetworkHostPacketGrant, type IRuntimeNetworkHostProjection } from './networkhost.js';
+import { type IRuntimeNetworkWorkloadIngressPacketGrant, type IRuntimeNetworkWorkloadIngressProjection } from './networkworkloadingress.js';
 export interface IRuntimeNetworkNodeScope {
     controller: IRuntimeController;
     nodeId: string;
@@ -154,6 +155,21 @@ export interface IRuntimeNetworkProjection extends IRuntimeNetworkNodeScope {
      * host-origin flow; any other controller kind carrying it is refused.
      */
     host?: IRuntimeNetworkHostProjection;
+    /**
+     * One-way workload ingress selections of a `cloudly` projection: the cluster ingress workload dials
+     * exact target workload ports across organizations (`IRuntimeNetworkWorkloadIngressPacketGrant`).
+     * Omitted, it keeps the canonical bytes and grants no such flow; any other controller kind
+     * carrying it is refused.
+     */
+    workloadIngress?: IRuntimeNetworkWorkloadIngressProjection;
+    /**
+     * Ids of the protected authority's platform endpoints whose address this projection's node's own
+     * host carries, such as a relay listener or a Corestore beside the node on one machine. The node
+     * delivers workload flows to them locally instead of forwarding them. Sorted, unique and never
+     * empty when present; omitted, it keeps the canonical bytes and states that no endpoint is local.
+     * It grants nothing: a workload still reaches only the endpoints it selects.
+     */
+    hostPlatformEndpointIds?: string[];
     digest: TSha256Digest;
 }
 export interface IRuntimeNetworkDnsView {
@@ -203,6 +219,8 @@ export declare const getRuntimeNetworkProjectionPacketGrants: (value: unknown) =
 export declare const getRuntimeNetworkProjectionRouterPacketGrants: (value: unknown) => Promise<IRuntimeNetworkRouterPacketGrant[]>;
 /** Host-origin authority comes only from explicit signed `onebox` selections of local workload ports. */
 export declare const getRuntimeNetworkProjectionHostPacketGrants: (value: unknown) => Promise<IRuntimeNetworkHostPacketGrant[]>;
+/** One-way workload ingress authority comes only from explicit signed `cloudly` selections of exact target ports. */
+export declare const getRuntimeNetworkProjectionWorkloadIngressPacketGrants: (value: unknown) => Promise<IRuntimeNetworkWorkloadIngressPacketGrant[]>;
 /** Complete offline DNS material, including authorized names never previously queried. */
 /** Select exact local receivers before expansion; all targets still come from
  * the complete validated projection. Selection supplies no attachment authority. */