@serve.zone/interfaces 32.28.0 → 32.30.0

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;
+};