@serve.zone/interfaces 32.27.0 → 32.29.0

package/ts/data/runtimelocalstorageclaim.ts

@@ -3,8 +3,10 @@ import type { IRuntimeAssignment, IRuntimeAuthorityReference, IRuntimeController
 import { snapshotRuntimeAssignment, validateRuntimeAssignment } from './runtimeassignment.js';
 import type { IRuntimeSessionBinding } from './runtimesession.js';
 import { snapshotRuntimeSessionBinding } from './runtimesession.js';
-import { captureNetwork, networkController, networkDigest, networkEqual, networkHash, networkId,
-  networkNodeId, networkRecord, networkReference, networkReferenceOf, networkRevision, requireNetwork,
+import type { IIdentityCredential } from './user.js';
+import { captureNetwork, networkController, networkCounter, networkDigest, networkEqual, networkHash, networkId,
+  networkList, networkNodeId, networkRecord, networkReference, networkReferenceOf, networkRevision, networkSorted,
+  requireNetwork,
 } from '../private/networkcontract.js';
 import { parseCanonicalIpAddress } from '../private/ipaddress.js';
 import { isRuntimeIdentityNumber } from '../private/runtimepolicy.js';
@@ -161,6 +163,60 @@ export interface IApplyRuntimeLocalStorageClaimResponse {
   claim: IRuntimeAuthorityReference;
 }
 
+/**
+ * What an administrator reads about one local storage claim a controller issued: where the volume
+ * is, whose it is, how it starts and what its node last answered.
+ *
+ * It is a projection of the controller's current generation, never the claim itself: it carries no
+ * digest, no controller epoch and no source beyond its kind, so an SMB claim's credential reference
+ * is not in it. `claimId` is the claim's `id`, the name the node keys the volume by, including the
+ * `import/<claimId>` directory an operator places an `import` volume's bytes in; a reader takes it
+ * from here and never derives it.
+ *
+ * `state` is what the node answered about exactly `generation`, or `null` while the node has not
+ * acknowledged that generation. It follows the rule `bindApplyRuntimeLocalStorageClaimResponse`
+ * holds an answer to: a bound claim is `ready`, `import-required` (an `import` claim only) or
+ * `uncertain`; a purge is `purged` or `uncertain`.
+ */
+export interface IRuntimeLocalStorageClaimSummary {
+  claimId: string;
+  generation: number;
+  clusterId: string;
+  nodeId: string;
+  serviceId: string;
+  volumeId: string;
+  mountPath: string;
+  sourceKind: TRuntimeLocalStorageSource['kind'];
+  initialization: IRuntimeLocalStorageClaim['initialization'];
+  lifecycle: TRuntimeLocalStorageLifecycle;
+  state: TRuntimeLocalStorageClaimState | null;
+}
+
+/**
+ * An administrator's read of the local storage claims of one cluster, optionally of one node.
+ *
+ * Paged: `cursor` is the opaque `nextCursor` of the previous page, and `limit` asks for at most that
+ * many summaries, which the controller may lower but never exceed; both absent read the first page
+ * at the controller's own size.
+ */
+export interface IGetRuntimeLocalStorageClaimsRequest {
+  /** The controller verifies this credential and derives every actor claim itself. */
+  identity: IIdentityCredential;
+  clusterId: string;
+  nodeId?: string;
+  cursor?: string;
+  limit?: number;
+}
+
+/**
+ * One page of summaries in strictly ascending `claimId` order. `nextCursor` is omitted on the final
+ * page; a page that carries it carries at least one summary.
+ */
+export interface IGetRuntimeLocalStorageClaimsResponse {
+  claims: IRuntimeLocalStorageClaimSummary[];
+  nextCursor?: string;
+}
+
 export const runtimeLocalStorageClaimContract = Object.freeze({
   digestDomain: 'serve.zone/runtime-local-storage-claim',
   error: 'Runtime local storage claim contract rejected.',
@@ -178,6 +234,11 @@ export const runtimeLocalStorageClaimContract = Object.freeze({
   maximumSegmentLength: 255,
   /** The longest SMB share name. */
   maximumShareLength: 80,
+  /**
+   * The most claim summaries one `getRuntimeLocalStorageClaims` page carries. A page of summaries
+   * with every field at its bound stays inside the network contract's one-mebibyte capture.
+   */
+  maximumSummaryPageSize: 200,
 } as const);
 
 const fail = (): never => { throw new Error(runtimeLocalStorageClaimContract.error); };
@@ -241,6 +302,14 @@ const shareOf = (valueArg: unknown): string => {
   return valueArg;
 };
 
+/** The states a node may answer about one generation, whatever the answer's status. */
+const isClaimStateOf = (
+  claimArg: Pick<IRuntimeLocalStorageClaim, 'lifecycle' | 'initialization'>, stateArg: TRuntimeLocalStorageClaimState,
+): boolean => claimArg.lifecycle === 'purge'
+  ? stateArg === 'purged' || stateArg === 'uncertain'
+  : stateArg === 'ready' || stateArg === 'uncertain'
+    || (stateArg === 'import-required' && claimArg.initialization === 'import');
+
 const literalOf = <TLiteral extends string>(valueArg: unknown, allowedArg: readonly TLiteral[]): TLiteral => {
   requireNetwork((allowedArg as readonly unknown[]).includes(valueArg));
   return valueArg as TLiteral;
@@ -424,11 +493,107 @@ export const bindApplyRuntimeLocalStorageClaimResponse = (
   const response = snapshotApplyRuntimeLocalStorageClaimResponse(valueArg);
   const { claim } = snapshotApplyRuntimeLocalStorageClaimRequest(requestArg);
   requireNetwork(networkEqual(response.claim, getRuntimeLocalStorageClaimReference(claim)));
-  if (response.status !== 'historical') {
-    requireNetwork(claim.lifecycle === 'purge'
-      ? response.state === 'purged' || response.state === 'uncertain'
-      : response.state === 'ready' || response.state === 'uncertain'
-        || (response.state === 'import-required' && claim.initialization === 'import'));
-  }
+  if (response.status !== 'historical') requireNetwork(isClaimStateOf(claim, response.state));
+  return response;
+});
+
+const sourceKinds = ['directory', 'nfs', 'smb'] as const;
+const initializations = ['empty', 'import'] as const;
+const lifecycles = ['bound', 'purge'] as const;
+
+/** Detached exact-schema snapshot of one summary, its state judged against its lifecycle. */
+export const snapshotRuntimeLocalStorageClaimSummary = (
+  valueArg: unknown,
+): IRuntimeLocalStorageClaimSummary => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['claimId', 'generation', 'clusterId', 'nodeId',
+    'serviceId', 'volumeId', 'mountPath', 'sourceKind', 'initialization', 'lifecycle', 'state']);
+  const summary: IRuntimeLocalStorageClaimSummary = {
+    claimId: networkId(value.claimId),
+    generation: networkCounter(value.generation),
+    clusterId: networkId(value.clusterId),
+    nodeId: networkNodeId(value.nodeId),
+    serviceId: networkId(value.serviceId),
+    volumeId: networkId(value.volumeId),
+    mountPath: readMountPath(value.mountPath, 'mountPath'),
+    sourceKind: literalOf(value.sourceKind, sourceKinds),
+    initialization: literalOf(value.initialization, initializations),
+    lifecycle: literalOf(value.lifecycle, lifecycles),
+    state: value.state === null ? null : literalOf(value.state, claimStates),
+  };
+  // A purge always follows a bound generation, and an SMB volume always starts empty.
+  requireNetwork((summary.lifecycle === 'bound' || summary.generation > 1)
+    && (summary.sourceKind !== 'smb' || summary.initialization === 'empty')
+    && (summary.state === null || isClaimStateOf(summary, summary.state)));
+  return summary;
+});
+
+/**
+ * The one projection of a claim and its node's last answer into a summary. `stateArg` is what the
+ * node answered about exactly this generation, or `null` while it has not acknowledged it.
+ */
+export const summarizeRuntimeLocalStorageClaim = (
+  claimArg: unknown, stateArg: TRuntimeLocalStorageClaimState | null,
+): IRuntimeLocalStorageClaimSummary => {
+  const claim = snapshotRuntimeLocalStorageClaim(claimArg);
+  return snapshotRuntimeLocalStorageClaimSummary({
+    claimId: claim.id,
+    generation: claim.generation,
+    clusterId: claim.clusterId,
+    nodeId: claim.nodeId,
+    serviceId: claim.serviceId,
+    volumeId: claim.volumeId,
+    mountPath: claim.mount.mountPath,
+    sourceKind: claim.source.kind,
+    initialization: claim.initialization,
+    lifecycle: claim.lifecycle,
+    state: stateArg,
+  });
+};
+
+/**
+ * Detached exact-schema snapshot of a read request. It checks the identity's shape only: the
+ * controller authenticates it.
+ */
+export const snapshotGetRuntimeLocalStorageClaimsRequest = (
+  valueArg: unknown,
+): IGetRuntimeLocalStorageClaimsRequest => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['identity', 'clusterId'], ['nodeId', 'cursor', 'limit']);
+  const identity = networkRecord(value.identity, ['jwt']);
+  requireNetwork(typeof identity.jwt === 'string' && identity.jwt.length > 0);
+  return {
+    identity: { jwt: identity.jwt as string },
+    clusterId: networkId(value.clusterId),
+    ...(Object.hasOwn(value, 'nodeId') ? { nodeId: networkNodeId(value.nodeId) } : {}),
+    ...(Object.hasOwn(value, 'cursor') ? { cursor: networkId(value.cursor) } : {}),
+    ...(Object.hasOwn(value, 'limit')
+      ? { limit: networkCounter(value.limit, runtimeLocalStorageClaimContract.maximumSummaryPageSize) } : {}),
+  };
+});
+
+/** Detached exact-schema snapshot of one page: bounded, strictly ascending and never empty with a cursor. */
+export const snapshotGetRuntimeLocalStorageClaimsResponse = (
+  valueArg: unknown,
+): IGetRuntimeLocalStorageClaimsResponse => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['claims'], ['nextCursor']);
+  const claims = networkList(value.claims, runtimeLocalStorageClaimContract.maximumSummaryPageSize,
+    snapshotRuntimeLocalStorageClaimSummary);
+  networkSorted(claims, (claimArg) => claimArg.claimId);
+  if (!Object.hasOwn(value, 'nextCursor')) return { claims };
+  requireNetwork(claims.length > 0);
+  return { claims, nextCursor: networkId(value.nextCursor) };
+});
+
+/**
+ * Matches a page to the read that asked for it: every summary names the requested cluster and, when
+ * the request named one, the requested node, and the page holds no more than the requested `limit`.
+ */
+export const bindGetRuntimeLocalStorageClaimsResponse = (
+  valueArg: unknown, requestArg: unknown,
+): IGetRuntimeLocalStorageClaimsResponse => safe(() => {
+  const response = snapshotGetRuntimeLocalStorageClaimsResponse(valueArg);
+  const request = snapshotGetRuntimeLocalStorageClaimsRequest(requestArg);
+  requireNetwork(response.claims.length <= (request.limit ?? runtimeLocalStorageClaimContract.maximumSummaryPageSize)
+    && response.claims.every((claimArg) => claimArg.clusterId === request.clusterId
+      && (request.nodeId === undefined || claimArg.nodeId === request.nodeId)));
   return response;
 });

package/ts/data/secret.ts

@@ -1893,6 +1893,22 @@ export const createAppStoreInstallSecretEnvelopeContext = (contextArg: {
     : null,
 });
 
+/**
+ * The context a dcrouter admin bootstrap token is sealed under for `bootstrapExternalGatewayCredential`.
+ *
+ * It binds the envelope to the dcrouter URL and the gateway client id the administrator named, so a
+ * sealed token opens only for a request that states the same target, and Cloudly hands it only to
+ * a gateway its own settings name.
+ */
+export const createGatewayBootstrapEnvelopeContext = (contextArg: {
+  gatewayUrl: string;
+  gatewayClientId: string;
+}): Uint8Array => contextBytes({
+  purpose: 'serve.zone/gateway-bootstrap',
+  gatewayUrl: contextArg.gatewayUrl,
+  gatewayClientId: contextArg.gatewayClientId,
+});
+
 export const createResolvedSecretMaterialEnvelopeContext = (contextArg: {
   recipientKeyId: string;
   organizationId: string;

package/ts/data/settings.ts

@@ -1,5 +1,6 @@
 import type { TServiceMailSubmissionTlsMode } from './mail.js';
 import type { ISystemSecretOwner, TSecretManagementScope } from './secret.js';
+import { hasExactKeys, readDataProperties } from '../private/dataproperties.js';
 
 export interface ICloudlyS3BackupTargetDescriptor {
   type: 's3';
@@ -109,3 +110,129 @@ export const cloudlySystemSecretKeys = Object.freeze({
   coreMailSmtpTlsCertificatePem: 'COREMAIL_SMTP_TLS_CERTIFICATE_PEM',
   coreMailSmtpTlsPrivateKeyPem: 'COREMAIL_SMTP_TLS_PRIVATE_KEY_PEM',
 } as const);
+
+/**
+ * How far Cloudly's enrollment as a dcrouter gateway client has come.
+ *
+ * - `unconfigured` — no `dcrouterGatewayUrl` is set, so there is nothing to enroll with.
+ * - `checking` — Cloudly is validating or provisioning its credential right now.
+ * - `ready` — Cloudly holds a validated gateway-client credential whose policy matches its settings.
+ * - `degraded` — dcrouter could not be reached; Cloudly retries on its own.
+ * - `admin-bootstrap-required` — the held credential is missing, rejected or stale (its policy no
+ *   longer matches Cloudly's settings or the runtime network address plan's DNS record allowance),
+ *   and only a dcrouter admin token handed in with `bootstrapExternalGatewayCredential` moves it on.
+ */
+export type TExternalGatewayEnrollmentStatus =
+  | 'unconfigured'
+  | 'checking'
+  | 'ready'
+  | 'degraded'
+  | 'admin-bootstrap-required';
+
+/** Cloudly's gateway-client enrollment as an administrator reads it; it never carries a credential. */
+export interface IExternalGatewayEnrollmentState {
+  status: TExternalGatewayEnrollmentStatus;
+  /** Why the state is what it is, in Cloudly's words; absent when there is nothing to say. */
+  reason?: string;
+  /** When Cloudly last finished a check, in milliseconds since the epoch. */
+  lastCheckedAt?: number;
+  /** When Cloudly retries on its own, for a `degraded` state. */
+  nextRetryAt?: number;
+  /** Whether Cloudly still holds a validated runtime credential it can serve gateway calls with. */
+  cachedValidationProof: boolean;
+  /** Whether a provisioned candidate credential still awaits finalization at dcrouter. */
+  finalizationPending: boolean;
+}
+
+export const externalGatewayEnrollmentStatuses = Object.freeze([
+  'unconfigured',
+  'checking',
+  'ready',
+  'degraded',
+  'admin-bootstrap-required',
+] as const satisfies readonly TExternalGatewayEnrollmentStatus[]);
+
+export const externalGatewayBootstrapContract = Object.freeze({
+  /**
+   * The longest admin bootstrap token Cloudly accepts, in bytes. A dcrouter API token is far
+   * shorter; the bound only keeps an unopened envelope from carrying an arbitrary payload.
+   */
+  maximumTokenBytes: 1_024,
+  /** The longest `reason` an enrollment state carries, in characters. */
+  maximumReasonLength: 4_096,
+  /** The longest `expectedGatewayUrl` a bootstrap request states, in characters. */
+  maximumGatewayUrlLength: 2_048,
+  /** The longest `expectedGatewayClientId` a bootstrap request states, in characters. */
+  maximumGatewayClientIdLength: 253,
+} as const);
+
+/** Every reason Cloudly answers instead of bootstrapping its gateway-client credential. */
+export const externalGatewayBootstrapRefusals = Object.freeze([
+  /** Cloudly has no `dcrouterGatewayUrl` or no `dcrouterGatewayClientId` to enroll under. */
+  'gateway-unconfigured',
+  /**
+   * The request's `expectedGatewayUrl` or `expectedGatewayClientId` is not what Cloudly's settings
+   * state, so the token would reach a dcrouter or a client the administrator did not name.
+   */
+  'gateway-target-mismatch',
+  /** The sealed token does not open, or what it opens to breaks the bootstrap token rule. */
+  'bootstrap-token-invalid',
+  /** dcrouter did not accept the token at all: unknown, revoked, disabled or expired. */
+  'bootstrap-token-rejected',
+  /** dcrouter accepted the token, but its role is not `admin`, so it cannot provision a client. */
+  'bootstrap-token-not-admin',
+  /** A candidate credential from an earlier provisioning is still being finalized; retry later. */
+  'bootstrap-candidate-pending',
+  /** dcrouter could not be reached; the held credential is unchanged and the call may be repeated. */
+  'gateway-unreachable',
+  /** dcrouter refused provisioning, or the credential it issued failed Cloudly's validation. */
+  'bootstrap-provisioning-refused',
+] as const);
+
+export type TExternalGatewayBootstrapRefusal = typeof externalGatewayBootstrapRefusals[number];
+
+/**
+ * The bootstrap token rule, judged on the opened bytes: 1 to `maximumTokenBytes` bytes of visible
+ * ASCII, with no whitespace or control character. The token is dcrouter's; this only refuses what
+ * could never be one, so a pasted line break or an empty pipe never reaches dcrouter.
+ */
+export const isExternalGatewayBootstrapToken = (valueArg: unknown): valueArg is Uint8Array => (
+  valueArg instanceof Uint8Array
+  && valueArg.length > 0
+  && valueArg.length <= externalGatewayBootstrapContract.maximumTokenBytes
+  && valueArg.every((byteArg) => byteArg >= 0x21 && byteArg <= 0x7e)
+);
+
+const isEpochMilliseconds = (valueArg: unknown): boolean => (
+  Number.isSafeInteger(valueArg) && (valueArg as number) >= 0
+);
+
+/** Structural check of an enrollment state as a client receives it; every problem is named. */
+export const validateExternalGatewayEnrollmentState = (valueArg: unknown): string[] => {
+  const state = readDataProperties(valueArg);
+  if (state === null) return ['external gateway enrollment state must be a plain record'];
+  const errors: string[] = [];
+  if (!hasExactKeys(state, ['status', 'cachedValidationProof', 'finalizationPending'],
+    ['reason', 'lastCheckedAt', 'nextRetryAt'])) {
+    errors.push('external gateway enrollment state contains fields outside its schema');
+  }
+  if (!externalGatewayEnrollmentStatuses.some((statusArg) => statusArg === state.status)) {
+    errors.push('external gateway enrollment status is unknown');
+  }
+  if (state.reason !== undefined && (typeof state.reason !== 'string'
+    || state.reason.length === 0
+    || state.reason.length > externalGatewayBootstrapContract.maximumReasonLength)) {
+    errors.push('external gateway enrollment reason must be a bounded non-empty string');
+  }
+  for (const key of ['lastCheckedAt', 'nextRetryAt'] as const) {
+    if (state[key] !== undefined && !isEpochMilliseconds(state[key])) {
+      errors.push(`external gateway enrollment ${key} must be epoch milliseconds`);
+    }
+  }
+  for (const key of ['cachedValidationProof', 'finalizationPending'] as const) {
+    if (typeof state[key] !== 'boolean') {
+      errors.push(`external gateway enrollment ${key} must be a boolean`);
+    }
+  }
+  return errors;
+};

package/ts/private/networkcontract.ts

@@ -9,7 +9,42 @@ export const failNetwork = (): never => { throw new Error('Runtime network proje
 export function requireNetwork(value: unknown): asserts value { if (!value) failNetwork(); }
 export const networkCanonical = (value: unknown): string => canonicalizeStrictJson(value, failNetwork);
 export const networkEqual = (left: unknown, right: unknown): boolean => networkCanonical(left) === networkCanonical(right);
-export const networkSafe = <T>(operation: () => T): T => { try { return operation(); } catch { return failNetwork(); } };
+
+/** The runtime network address plan's lists that must be stated in their one canonical order. */
+export type TRuntimeNetworkAddressPlanOrderedField = 'prefixes' | 'pools' | 'resolvers' | 'platformEndpoints';
+
+/** The structure rules an address plan refusal names; `order` is the only one named so far. */
+export type TRuntimeNetworkAddressPlanStructureRule = 'order';
+
+/** Which list of a plan broke which structure rule; never a value from the plan. */
+export interface IRuntimeNetworkAddressPlanStructureViolation {
+  field: TRuntimeNetworkAddressPlanOrderedField;
+  rule: TRuntimeNetworkAddressPlanStructureRule;
+}
+
+/**
+ * A plan refused for a structure rule the contract names, rather than with the contract's generic
+ * rejection. It is the one error `networkSafe` lets through, so a caller can tell an administrator
+ * which list to fix; its message names the field and the rule and quotes nothing from the plan.
+ */
+export class RuntimeNetworkAddressPlanStructureError extends Error {
+  public readonly violation: IRuntimeNetworkAddressPlanStructureViolation;
+
+  public constructor(violationArg: IRuntimeNetworkAddressPlanStructureViolation) {
+    super(`Runtime network address plan rejected: ${violationArg.field} breaks the ${violationArg.rule} rule.`);
+    this.name = 'RuntimeNetworkAddressPlanStructureError';
+    this.violation = { field: violationArg.field, rule: violationArg.rule };
+  }
+}
+
+export const networkSafe = <T>(operation: () => T): T => {
+  try {
+    return operation();
+  } catch (error) {
+    if (error instanceof RuntimeNetworkAddressPlanStructureError) throw error;
+    return failNetwork();
+  }
+};
 
 /** Bound decoded transport input before canonicalization; never execute getters/toJSON. */
 export const captureNetwork = (value: unknown): unknown => networkSafe(() => {

package/ts/requests/network.ts

@@ -108,7 +108,8 @@ export interface IRequest_Any_Cloudly_GetNetworkNodes {
  * validates the plan with `snapshotRuntimeNetworkAddressPlan`, decides the change with
  * `admitRuntimeNetworkAddressPlanChange`, refuses the change while a resolver or platform endpoint
  * it removes or changes is still referenced, and answers with the stored plan: at its new revision,
- * or unchanged.
+ * or unchanged. A list stated out of its canonical order (see `IRuntimeNetworkAddressPlan`) is
+ * refused `plan-unsorted`, naming the list as the refusal's reference; the plan is never reordered.
  */
 export interface IReq_Any_Cloudly_SetRuntimeNetworkAddressPlan extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_Cloudly_SetRuntimeNetworkAddressPlan

package/ts/requests/runtimesession.ts

@@ -179,6 +179,22 @@ export interface IReq_Controller_Pallet_ApplyRuntimeLocalStorageClaim extends pl
   response: localStorage.IApplyRuntimeLocalStorageClaimResponse;
 }
 
+/**
+ * An administrator reads the local storage claims Cloudly issued in one cluster, optionally on one
+ * node, one page at a time: each claim's id, volume, mount path, initialization, lifecycle and what
+ * its node last answered. `snapshotGetRuntimeLocalStorageClaimsRequest` and
+ * `bindGetRuntimeLocalStorageClaimsResponse` judge both sides; a summary never carries the claim's
+ * source beyond its kind, so no credential reference leaves Cloudly through it.
+ */
+export interface IReq_Any_Cloudly_GetRuntimeLocalStorageClaims extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_GetRuntimeLocalStorageClaims
+> {
+  method: 'getRuntimeLocalStorageClaims';
+  request: localStorage.IGetRuntimeLocalStorageClaimsRequest;
+  response: localStorage.IGetRuntimeLocalStorageClaimsResponse;
+}
+
 /** Current-peer report, including exact historical outbox recovery after reconnect. */
 export interface IReq_Pallet_Controller_ReportRuntimeAssignmentObservation extends plugins.typedrequestInterfaces.implementsTR<
   plugins.typedrequestInterfaces.ITypedRequest,

package/ts/requests/settings.ts

@@ -1,6 +1,10 @@
 import * as plugins from '../plugins.js';
-import type { ICloudlySettings } from '../data/settings.js';
-import type { IIdentity } from '../data/user.js';
+import * as secretData from '../data/secret.js';
+import * as settingsData from '../data/settings.js';
+import type { IActiveSecretRecipientMetadata } from '../data/secret.js';
+import type { ICloudlySettings, IExternalGatewayEnrollmentState } from '../data/settings.js';
+import type { IIdentity, IIdentityCredential } from '../data/user.js';
+import { readDataProperties, hasExactKeys } from '../private/dataproperties.js';
 
 // Get Settings
 export interface IRequest_GetSettings extends plugins.typedrequestInterfaces.ITypedRequest {
@@ -64,3 +68,159 @@ export interface IRequest_GetSetting extends plugins.typedrequestInterfaces.ITyp
     value: ICloudlySettings[keyof ICloudlySettings] | undefined;
   };
 }
+
+/** A dcrouter admin bootstrap token, sealed to Cloudly's active secret ingress recipient. */
+export interface IExternalGatewayBootstrapTokenInput {
+  mode: 'sealed';
+  /** Sealed under `data.createGatewayBootstrapEnvelopeContext` for the request's expected target. */
+  envelope: plugins.smartcrypto.IX25519EnvelopeV1;
+}
+
+/**
+ * Enrolls Cloudly as its dcrouter gateway client with a dcrouter admin token an administrator
+ * hands in once.
+ *
+ * Cloudly opens the token, checks the target the request names against its own settings, asks
+ * dcrouter whether the token is an admin token, and provisions, finalizes and stores its own
+ * least-privilege gateway-client credential with it — under the policy its settings and the runtime
+ * network address plan state now. The admin token is used for this one call and never stored; the
+ * administrator revokes it at dcrouter afterwards. A refusal leaves the credential Cloudly already
+ * holds unchanged and is answered with one of `data.externalGatewayBootstrapRefusals`.
+ *
+ * This is the one way a gateway credential enters Cloudly, for a first enrollment and for the
+ * re-bootstrap a changed address plan or gateway setting asks for (`admin-bootstrap-required`).
+ */
+export interface IReq_Any_Cloudly_BootstrapExternalGatewayCredential
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_BootstrapExternalGatewayCredential
+> {
+  method: 'bootstrapExternalGatewayCredential';
+  request: {
+    identity: IIdentityCredential;
+    /** The `dcrouterGatewayUrl` the administrator read from Cloudly's settings. */
+    expectedGatewayUrl: string;
+    /** The `dcrouterGatewayClientId` the administrator read from Cloudly's settings. */
+    expectedGatewayClientId: string;
+    bootstrapToken: IExternalGatewayBootstrapTokenInput;
+  };
+  response: {
+    /** The enrollment after the bootstrap: `ready` when the new credential is Cloudly's runtime authority. */
+    state: IExternalGatewayEnrollmentState;
+  };
+}
+
+/** Cloudly's gateway-client enrollment state, for an administrator; it never carries a credential. */
+export interface IReq_Any_Cloudly_GetExternalGatewayEnrollmentState
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_GetExternalGatewayEnrollmentState
+> {
+  method: 'getExternalGatewayEnrollmentState';
+  request: {
+    identity: IIdentityCredential;
+  };
+  response: {
+    state: IExternalGatewayEnrollmentState;
+  };
+}
+
+const hasJwtIdentity = (valueArg: unknown): boolean => {
+  const identity = readDataProperties(valueArg);
+  return identity !== null && typeof identity.jwt === 'string' && identity.jwt.length > 0;
+};
+
+/** Structural check of the target a bootstrap request names; empty when both are well formed. */
+const validateExpectedGatewayTarget = (urlArg: unknown, clientIdArg: unknown): string[] => {
+  const errors: string[] = [];
+  let url: URL | undefined;
+  if (typeof urlArg === 'string'
+    && urlArg.length > 0
+    && urlArg.length <= settingsData.externalGatewayBootstrapContract.maximumGatewayUrlLength) {
+    try {
+      url = new URL(urlArg);
+    } catch {
+      url = undefined;
+    }
+  }
+  if (!url
+    || url.protocol !== 'https:'
+    || url.username !== ''
+    || url.password !== ''
+    || url.search !== ''
+    || url.hash !== '') {
+    errors.push('bootstrap expectedGatewayUrl must be an HTTPS URL without credentials, query or fragment');
+  }
+  if (typeof clientIdArg !== 'string'
+    || clientIdArg.length === 0
+    || clientIdArg.length > settingsData.externalGatewayBootstrapContract.maximumGatewayClientIdLength
+    || !/^[\x21-\x7e]+$/.test(clientIdArg)) {
+    errors.push('bootstrap expectedGatewayClientId must be a bounded identifier without whitespace');
+  }
+  return errors;
+};
+
+/**
+ * Checks a bootstrap request against its schema and the active ingress recipient, without opening
+ * the envelope: the recipient, the context digest of the named target and the ciphertext bound of
+ * `data.externalGatewayBootstrapContract.maximumTokenBytes`. Every problem is named.
+ */
+export const validateBootstrapExternalGatewayCredentialRequest = async (
+  requestArg: unknown,
+  activeIngressRecipientArg: IActiveSecretRecipientMetadata,
+): Promise<string[]> => {
+  const request = readDataProperties(requestArg);
+  if (request === null) return ['bootstrap request must be a plain record'];
+  const errors: string[] = [];
+  if (!hasExactKeys(request, ['identity', 'expectedGatewayUrl', 'expectedGatewayClientId', 'bootstrapToken'])) {
+    errors.push('bootstrap request contains fields outside its schema');
+  }
+  if (!hasJwtIdentity(request.identity)) {
+    errors.push('bootstrap identity must be a JWT credential');
+  }
+  const targetErrors = validateExpectedGatewayTarget(
+    request.expectedGatewayUrl,
+    request.expectedGatewayClientId,
+  );
+  errors.push(...targetErrors);
+  const tokenInput = readDataProperties(request.bootstrapToken);
+  if (tokenInput === null || tokenInput.mode !== 'sealed') {
+    errors.push('bootstrap token must be a sealed input');
+    return errors;
+  }
+  const expectedContext = targetErrors.length === 0
+    ? secretData.createGatewayBootstrapEnvelopeContext({
+        gatewayUrl: request.expectedGatewayUrl as string,
+        gatewayClientId: request.expectedGatewayClientId as string,
+      })
+    : new Uint8Array();
+  errors.push(...await secretData.validateSecretValueInputForRecipient(
+    tokenInput,
+    activeIngressRecipientArg,
+    expectedContext,
+  ));
+  const envelope = readDataProperties(tokenInput.envelope);
+  if (envelope !== null
+    && typeof envelope.ciphertext === 'string'
+    && envelope.ciphertext.length
+      > Math.ceil(settingsData.externalGatewayBootstrapContract.maximumTokenBytes * 4 / 3)) {
+    errors.push(
+      `bootstrap token must not exceed ${settingsData.externalGatewayBootstrapContract.maximumTokenBytes} bytes`,
+    );
+  }
+  return errors;
+};
+
+/** Checks an enrollment state read; every problem is named. */
+export const validateGetExternalGatewayEnrollmentStateRequest = (requestArg: unknown): string[] => {
+  const request = readDataProperties(requestArg);
+  if (request === null) return ['enrollment state request must be a plain record'];
+  const errors: string[] = [];
+  if (!hasExactKeys(request, ['identity'])) {
+    errors.push('enrollment state request contains fields outside its schema');
+  }
+  if (!hasJwtIdentity(request.identity)) {
+    errors.push('enrollment state identity must be a JWT credential');
+  }
+  return errors;
+};