@serve.zone/interfaces 32.40.1 → 32.42.0

package/readme.md

@@ -395,6 +395,16 @@ the declaration is not a revocation acknowledgement. Prefix arrays are sorted
 lexically and nonoverlapping; pools and endpoints are sorted by ID; egress owners
 are ordered by canonical JSON of `[nodeId, runtimeNamespace]`.
 
+`continuesRuntimeNetworkProtection(previous, next)` states which successor of a protected authority
+only adds. It answers `true` when `next` is `previous` itself, or exactly the next step of its chain
+(the same `id` and controller, `next.previous` naming `previous`) in which every egress owner, pool,
+resolver and platform endpoint of `previous` is still present with the same content and the prefixes
+still cover every address `previous` protected, however they are split. A cluster topology change is
+such a step: a node joins the egress, or a cluster's hub joins the platform endpoints. The step keeps
+its barrier: every egress owner still reports a receipt for `next` before an allocation binds to it.
+Any removal or change, a jump over a step, another chain or another controller answers `false`. Both
+authorities and their digests are validated, and either that does not validate is rejected.
+
 `IRuntimeNetworkProtectionReceipt` reports a worker's durable, joined native
 protection journal separately from projection admission. It binds a complete
 protected-authority reference, node/controller scope, authenticated reporter,
@@ -411,9 +421,11 @@ current persisted protection receipt and durable session for every declared
 egress owner, in canonical owner order. Missing, unavailable, stale-protection
 and superseded-session evidence reject. An offline owner cannot be omitted.
 The controller must fence all those records together with lease insertion, before
-reserving any handoff or workload address. No generic independent-fence flag is
-provided; such a mechanism needs its own verified owner. Protection receipts
-neither prove workload readiness nor release packet/address/name quarantine.
+reserving any handoff or workload address. There is no generic independent-fence
+flag, quorum or expiry: the one way an owner leaves is
+[Egress Owner Retirement](#egress-owner-retirement).
+Protection receipts neither prove workload readiness nor release
+packet/address/name quarantine.
 
 `IRuntimeNetworkHandoffLease` binds an immutable node/router incarnation to its
 protected-authority reference, transit subnet and peers, protocol-qualified source
@@ -732,9 +744,12 @@ A credential names one projection, but its key pair belongs to the node's manage
 membership, which outlives it. Every workload add, removal, readiness change or policy change
 signs a new projection generation; none of them changes who the member is.
 `continuesRuntimeManagedVpnMembership(previous, next)` is that rule: `next` continues the
-membership when it is the same projection lineage (`id`) under the same protected authority and
-the same handoff lease (which names the node scope and carries the router incarnation), and is
-`previous` itself or a later generation. A protection bump, a fresh handoff (router
+membership when it is the same projection lineage (`id`), under a protected authority that
+continues the previous one (`continuesRuntimeNetworkProtection`: the same authority or its next
+step that only adds), with the same handoff lease (which names the node scope and carries the
+router incarnation), and is `previous` itself or a later generation. A node joining the egress or a
+cluster hub joining the platform endpoints therefore keeps every member's key pair and hub session.
+A protection step that removes or changes anything or skips a step, a fresh handoff (router
 reincarnation) or a new controller epoch is a new membership; an earlier generation or another
 projection of the same generation continues nothing. It validates both projections and rejects
 one that does not validate.
@@ -761,6 +776,59 @@ Noise implementation owns cryptographic validation and authentication. Credentia
 delivery does not prove a connected VPN, TUN ownership, packet enforcement or
 workload readiness, and does not replace explicit packet withdrawals.
 
+### Egress Owner Retirement
+
+An owner that is offline, revoked or gone can never acknowledge a successor, so
+while it stays declared no allocation is possible after the next protection change.
+`IRuntimeNetworkEgressRetirement` is the independent fence that lets it leave. Its
+owner is the controller, which records it from its own durable state against the
+exact protected authority the owner is about to leave, once all five hold:
+
+1. the node carries an `INodeRuntimeRetirement` row, whose `disposition` the fence
+   copies;
+2. both node credentials are revoked (`revokedCredentials`, committed at
+   `revokedAt`), so the node can no longer register, renew a DNS lease or fetch a
+   managed VPN credential;
+3. every DNS and managed VPN window the node was ever issued has ended
+   (`packetWindowExpiresAt`, or `revokedAt` when it was issued none), so no hub
+   relays for it even if it was never told to stop, and `fencedAt` is not earlier;
+4. every handoff and workload lease the node was granted is quarantined
+   (`quarantinedHandoffs`, at most 256, and `quarantinedWorkloads`, at most 512,
+   both in canonical order) and is never handed out again;
+5. every remaining owner of that authority acknowledged a projection head that
+   carries no endpoint of the node (`clearedProjections`, one per remaining owner
+   in canonical owner order, never the node itself).
+
+`lastReceipt` is the node's last accepted protection receipt. A `withdrawn` node
+took part in its own retirement, so it always has one (its null withdrawal); a
+`lost` node may have none. Neither disposition shortens the fence: a lost node
+leaves behind exactly the same controller-owned evidence as a withdrawn one.
+`snapshotRuntimeNetworkEgressRetirement` is the exact-key reader and
+`computeRuntimeNetworkEgressRetirementDigest` seals it under
+`serve.zone/runtime-network-egress-retirement`. Neither authenticates the
+evidence; the controller fences the rows it read together with the authority it
+stages.
+
+`bindRuntimeNetworkProtectedAuthorityRetirement(previous, next, fences,
+retiredOwners)` is the pure successor rule for the egress owners and the address
+space of any step. `next` must be the exact successor of `previous` under the same
+controller, with both digests verified. An owner of `previous` may be absent from
+`next` only when exactly one fence recorded against the exact `previous` reference,
+verified by its digest, names it; a fence for an owner `next` still names, or one
+`previous` never named, refuses the step, and every fence's `clearedProjections`
+must name exactly the owners the step keeps. `retiredOwners` is the complete,
+canonically ordered list of owners earlier steps fenced, which the caller's
+durable history supplies; neither side may name any of them, so a fenced owner
+never returns. Every pool of `previous` stays unchanged and the prefixes of `next`
+cover those of `previous`; a step that removes an owner also keeps every resolver.
+Owners may join in the same step, and a step without fences is the additive rule.
+One step consumes at most 16 fences (`runtimeNetworkEgressRetirementContract`).
+
+A retirement step is a new protected authority: every remaining owner reports a
+receipt citing it before anything new is allocated, while existing leases keep
+their historical eligibility. It also ends every managed VPN membership, as every
+protection change does, so each retirement costs the fleet one reconnect.
+
 ### DNS Lease Renewals
 
 A projection's `dns` window lasts at most fifteen minutes and is signed content, so a node's
@@ -1822,20 +1890,33 @@ status or assignments changed; it carries no state, so a late push never overwri
 
 ### Node Retirement
 
-`data.INodeRuntimeRetirement { id, clusterId, state, actorId, since }` records that one node leaves
-its cluster's Pallet runtime. `TNodeRuntimeRetirementState` is `retiring` while the producer still
-stops and removes the node's slots, the compiler quarantines its handoff and both node credentials
-are revoked, and `retired` once that has settled. It is stored beside the node document, because a
-node update merges caller data and no caller may retire a node with it. The producers read the row's
-presence rather than its state: a node that has one is no longer an egress member and desires no
-slots, so the row is written before anything is taken away and stays as long as the node document.
-`snapshotNodeRuntimeRetirement` checks the record.
-
-`requests.node.retireClusterNode { identity, nodeId, expectedGeneration }` answers `{ retirement }`.
-`expectedGeneration` is the cluster runtime generation the caller read with `getClusterRuntime`, so a
-cutover that moved the phase meanwhile refuses the write. Every refusal is one of
-`data.nodeRuntimeRetirementRefusals` — `node-missing`, `cluster-runtime-not-pallet`,
-`node-already-retired` or `conflict` — and takes nothing away.
+`data.INodeRuntimeRetirement { id, clusterId, state, disposition, actorId, since }` records that one
+node leaves its cluster's Pallet runtime. `TNodeRuntimeRetirementState` is `retiring` while the
+producer still stops and removes the node's slots, the compiler quarantines its handoff and leases,
+both node credentials are revoked and the node's egress fence is not yet recorded, and `retired`
+once the protected authority no longer names the node (see
+[Egress Owner Retirement](#egress-owner-retirement)). It is stored beside the node document, because
+a node update merges caller data and no caller may retire a node with it. The producers read the
+row's presence rather than its state: a node that has one is no longer an egress member and desires
+no slots, so the row is written before anything is taken away and stays as long as the node
+document. `snapshotNodeRuntimeRetirement` checks the record.
+
+`TNodeRuntimeRetirementDisposition` (`nodeRuntimeRetirementDispositions`,
+`snapshotNodeRuntimeRetirementDisposition`) says how the node leaves. `withdrawn`: the node still
+runs and takes part — its slots are removed against its own removal receipts and its Pallet
+withdraws its protection receipt before its credentials are revoked. `lost`: an administrator
+states the node will never report again, which authorizes abandoning its slots without removal
+receipts and nothing else; its egress fence is the same as a withdrawn node's.
+
+`requests.node.retireClusterNode { identity, nodeId, expectedGeneration, disposition? }` answers
+`{ retirement }`. `expectedGeneration` is the cluster runtime generation the caller read with
+`getClusterRuntime`, so a cutover that moved the phase meanwhile refuses the write. A request that
+states no disposition asks for `withdrawn`, the retirement this request always described; `lost`
+is taken only when stated, and asking again as `lost` escalates a `withdrawn` retirement that is
+still `retiring`. Every refusal is one of `data.nodeRuntimeRetirementRefusals` — `node-missing`,
+`cluster-runtime-not-pallet`, `node-already-retired`, `conflict` or `node-still-reporting` (a `lost`
+retirement of a node whose last accepted report is younger than
+`clusterNodeObservationFreshnessMs`) — and takes nothing away.
 
 ### Corestore Database Export Packaging
 
@@ -2723,8 +2804,9 @@ cluster authority every cluster-side component used before it. `IClusterRelayCre
 metadata: the cluster, a `generation` that advances by one per accepted mint or rotation, the
 machine `userId` it authenticates as, and `delivery`, the `ISecretVersionReference` of the
 immutable encrypted version the bearer was delivered as. No record, receipt, request or response
-of this contract carries a bearer, a hash or key material, and every reader is exact-keyed, so a
-peer that adds a secret-looking member is refused rather than copied.
+of this contract carries a bearer, a hash or key material, except the one answer that exists to
+hand the bearer over (see the export below), and every reader is exact-keyed, so a peer that adds
+a secret-looking member is refused rather than copied.
 
 The credential authenticates the cluster's whole control-plane session, exactly what the shared
 authority authenticated, so a relay changes one credential and keeps every call it makes. The gain
@@ -2776,7 +2858,36 @@ it names or that record's revoked successor — and to a registration whose `cre
 invalidation's `replacement`. It is a content check; dereferencing each record as current and
 requiring the live socket remain Cloudly's.
 
-All three requests read only the verified `IIdentityCredential`, never an identity member a caller
+`exportClusterRelayAuthorization { identity, clusterId, expectedGeneration }` answers the bearer
+itself, so an operator hands it to the relay without an exec into Cloudly's process. Cloudly mints
+nothing to answer it: the bearer is the encrypted version the credential's `delivery` names, read
+at exactly `expectedGeneration` (never a minimum) and proved against the hash that generation
+issued, so a rotation committing meanwhile is refused rather than answered. A new bearer is a
+`rotate` followed by an export at the new generation. It requires a freshly authenticated
+administrator, exactly as a credential mutation does. `IClusterRelayAuthorizationExport` carries
+the sealed `credential` at that generation, the `authorization` (the bearer, byte for byte what the
+relay presents: `clusterRelayToken_<credential id>_<64 hex>`, no line terminator) and the
+`receipt`. It is the only answer of this contract that carries a bearer; Cloudly never logs it, and
+its reader writes it where the relay reads it and nowhere else.
+
+Every answered export is audited: Cloudly writes `IClusterRelayAuthorizationExportReceipt`
+(`id`, `clusterId`, the exact `credential` reference, the administrator's `actorId`,
+`exportedAt`) before it answers, so no bearer leaves without a record, and a retried export is a
+second receipt rather than a replay. A receipt is value-free: no bearer, no hash.
+`getClusterRelayAuthorizationExports { identity, clusterId }` answers a cluster's receipts, oldest
+first. Refusals are `data.clusterRelayAuthorizationExportRefusals`
+(`data.TClusterRelayAuthorizationExportRefusal`): `relay-credential-absent`,
+`relay-credential-generation-mismatch`, `relay-authorization-missing` and
+`relay-authorization-ambiguous`. A reader checks an answer with
+`bindClusterRelayAuthorizationExport(answer, { clusterId, expectedGeneration })` before it writes a
+byte: the credential's digest holds, it is the requested cluster's at the requested generation, the
+bearer names that credential, and the receipt names that exact credential. Every refusal is the
+contract's one value-free message and never quotes the answer. `isClusterRelayAuthorization`
+states the bearer's shape, and `snapshotClusterRelayAuthorizationExportRequest`,
+`snapshotClusterRelayAuthorizationExportReceipt` and `snapshotClusterRelayAuthorizationExport` are
+the exact-keyed readers.
+
+All five requests read only the verified `IIdentityCredential`, never an identity member a caller
 states about itself.
 
 ### Spark Legacy Runtime Retirement
@@ -3581,6 +3692,7 @@ Request groups are exported by product area:
 - `requests.coremail`
 - `requests.coremailAdmin`
 - `requests.corestore`
+- `requests.corestorecontrol`
 - `requests.deployment`
 - `requests.dns`
 - `requests.domain`
@@ -3694,6 +3806,47 @@ bytes and digests exactly.
 payload, one-byte-larger framed snapshot-original, 128 MiB verified closure
 plaintext, and 256 MiB closure boundaries used by Corestore.
 
+### Corestore Control Token Administration
+
+The elected relay of every cluster calls its nodes' Corestore control API with one control token
+(`CORESTORE_API_TOKEN`), which Cloudly stores for both Corestore provider configs and hands to the
+relay sealed (see Corestore Runtime Credentials). `requests.corestorecontrol` lets an administrator
+store that token without an exec into Cloudly's process.
+
+`setCorestoreControlToken { identity, token, expected }` stores `token` under both provider configs
+in one transaction, so either both hold it or neither does. `token` must pass
+`isCorestoreControlToken` (32 to 4096 UTF-8 bytes, no whitespace) and is the only member of this
+contract that carries the token: it is never in an answer, a receipt, a log or a hook, and a sender
+never persists the request. `expected` is the `data.TCorestoreControlTokenState` the administrator
+last read: `{ state: 'absent' }` or `{ state: 'present', revision }`, never a minimum, so a set that
+committed in between is refused rather than overwritten. `revision` is 1 for the first token ever
+stored and advances by exactly one with every accepted set; no request removes a token. It requires
+a freshly authenticated administrator, exactly as a relay credential mutation does. The answer,
+`data.ICorestoreControlTokenSetResult`, is the state the set produced and its receipt. Refusals are
+`data.corestoreControlTokenSetRefusals` (`data.TCorestoreControlTokenSetRefusal`):
+`token-invalid`, `token-present`, `token-absent`, `token-revision-mismatch` and
+`provider-unavailable`.
+
+Every accepted set is audited: Cloudly writes `data.ICorestoreControlTokenSetReceipt` (`id`,
+`revision`, `via`, `actorId`, `setAt`) in the transaction that stores the token. `via` is
+`admin-request` with the administrator's `actorId`, or `container-cli` with
+`data.corestoreControlTokenContainerCliActorId` (`operator:secrets-cli`) when Cloudly's in-container
+`secrets set-corestore-control-token` stored it; that command advances the same revision. A receipt
+is value-free: no token, no hash. `getCorestoreControlTokenState { identity }` answers
+`data.ICorestoreControlTokenStateRead`: the state and its receipts, oldest first, contiguous and
+ending at the state's revision; no token stored means no receipt. Only a token stored before
+receipts existed, which Cloudly's migration records as revision 1, has no receipt, so the receipts
+start at revision 1 or 2. A read answers at most `data.corestoreControlTokenMaximumReceipts` (4096)
+receipts: past that many sets it answers the latest 4096, whose oldest may name any revision.
+
+A reader checks a set answer with `bindCorestoreControlTokenSet(answer, request)`: the state is
+present at revision 1 after an absent expectation and at the expected revision plus one otherwise,
+and the receipt is an `admin-request` receipt for exactly that revision.
+`snapshotCorestoreControlTokenSetRequest`, `snapshotCorestoreControlTokenSetResult`,
+`snapshotCorestoreControlTokenSetReceipt`, `snapshotCorestoreControlTokenState` and
+`snapshotCorestoreControlTokenStateRead` are the exact-keyed readers. Every refusal is the
+contract's one value-free message and never quotes the token.
+
 ### Corestore Through The Relay
 
 A serve.zone cluster is outbound-only and Corestore is node-local, so Cloudly never reaches a

package/ts/00_commitinfo_data.ts

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

package/ts/data/clusterrelaycredential.ts

@@ -128,6 +128,53 @@ export interface IClusterLegacyRelayCredentialRetirementResult {
   replayed: boolean;
 }
 
+/**
+ * What an administrator names to export one cluster's relay bearer: the cluster, at exactly the
+ * generation `getClusterRelayCredential` answered. Never a minimum: a rotation that committed
+ * after that read is refused rather than answered with a bearer the operator did not ask for.
+ */
+export interface IClusterRelayAuthorizationExportRequest {
+  clusterId: string;
+  expectedGeneration: number;
+}
+
+/**
+ * The audit record of one answered export, which Cloudly writes before it answers the bearer.
+ *
+ * Append-only and value-free: it names who received which credential's bearer and when, never
+ * the bearer or a hash of it. Every answered export writes one, so a retried export is a second
+ * receipt rather than a replay: each is a separate handover of the same bearer.
+ */
+export interface IClusterRelayAuthorizationExportReceipt {
+  id: string;
+  clusterId: string;
+  /** The exact relay credential whose bearer was answered: identity, generation and digest. */
+  credential: IRuntimeAuthorityReference;
+  /** The administrator the bearer was answered to, read from the verified credential. */
+  actorId: string;
+  exportedAt: number;
+}
+
+/**
+ * One cluster's relay bearer, answered to an administrator so it can be handed to the relay
+ * without reaching into Cloudly's process.
+ *
+ * The only member of this contract that carries a bearer. It is the delivered version the
+ * credential names, at the requested generation, proved against the hash that generation issued;
+ * Cloudly mints nothing to answer it. The reader owns the bytes: it writes them where the relay
+ * reads them and never logs, prints or persists them anywhere else.
+ */
+export interface IClusterRelayAuthorizationExport {
+  /** The relay credential the bearer authenticates as, at exactly the requested generation. */
+  credential: IClusterRelayCredential;
+  /**
+   * The bearer, byte for byte what the relay presents: `clusterRelayToken_`, the credential's
+   * 64-hex `id`, `_` and 64 hex characters, with no line terminator.
+   */
+  authorization: string;
+  receipt: IClusterRelayAuthorizationExportReceipt;
+}
+
 export const clusterRelayCredentialContract = Object.freeze({
   credentialDigestDomain: 'serve.zone/cluster-relay-credential',
   legacyCredentialDigestDomain: 'serve.zone/cluster-relay-legacy-credential',
@@ -154,6 +201,24 @@ export const clusterRelayCredentialRefusals = Object.freeze([
 
 export type TClusterRelayCredentialRefusal = typeof clusterRelayCredentialRefusals[number];
 
+/**
+ * Every reason Cloudly answers instead of a relay bearer. Its own family, because an export
+ * changes no record: it has no `conflict`, and a generation it was not asked for is a mismatch.
+ */
+export const clusterRelayAuthorizationExportRefusals = Object.freeze([
+  /** No relay credential is minted for the cluster. */
+  'relay-credential-absent',
+  /** The credential is at another generation than the one named, before the read or after it. */
+  'relay-credential-generation-mismatch',
+  /** The version the credential delivered is not stored as an active version. */
+  'relay-authorization-missing',
+  /** The secret's active version, or its bytes, are not what the credential issued. */
+  'relay-authorization-ambiguous',
+] as const);
+
+export type TClusterRelayAuthorizationExportRefusal =
+  typeof clusterRelayAuthorizationExportRefusals[number];
+
 const fail = (): never => { throw new Error('Cluster relay credential contract rejected.'); };
 const safe = <T>(operationArg: () => T): T => {
   try { return operationArg(); } catch { return fail(); }
@@ -359,3 +424,87 @@ export const bindClusterLegacyRelayCredentialInvalidation = async (
     return { invalidation, legacyCredential, acceptedRegistration };
   } catch { return fail(); }
 };
+
+const clusterRelayAuthorizationPrefix = 'clusterRelayToken_';
+const clusterRelayAuthorizationPattern = /^clusterRelayToken_[a-f0-9]{64}_[a-f0-9]{64}$/;
+
+/**
+ * Whether a value has the exact shape of a relay bearer: `clusterRelayToken_<64 hex>_<64 hex>`.
+ *
+ * Shape only: whether it authenticates is Cloudly's to decide against the hash it keeps.
+ */
+export const isClusterRelayAuthorization = (valueArg: unknown): valueArg is string =>
+  typeof valueArg === 'string' && clusterRelayAuthorizationPattern.test(valueArg);
+
+/** The credential identity a relay bearer names: the 64 hex characters after its prefix. */
+const clusterRelayAuthorizationCredentialId = (authorizationArg: string): string =>
+  authorizationArg.slice(
+    clusterRelayAuthorizationPrefix.length,
+    clusterRelayAuthorizationPrefix.length + 64,
+  );
+
+export const snapshotClusterRelayAuthorizationExportRequest = (
+  valueArg: unknown,
+): IClusterRelayAuthorizationExportRequest => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['clusterId', 'expectedGeneration']);
+  return {
+    clusterId: networkId(value.clusterId),
+    expectedGeneration: networkCounter(value.expectedGeneration),
+  };
+});
+
+export const snapshotClusterRelayAuthorizationExportReceipt = (
+  valueArg: unknown,
+): IClusterRelayAuthorizationExportReceipt => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), [
+    'id', 'clusterId', 'credential', 'actorId', 'exportedAt',
+  ]);
+  return {
+    id: networkId(value.id),
+    clusterId: networkId(value.clusterId),
+    credential: networkReference(value.credential),
+    actorId: networkId(value.actorId),
+    exportedAt: networkCounter(value.exportedAt),
+  };
+});
+
+/**
+ * Structural copy of an export answer. A refusal never quotes the answer, because it carries a
+ * bearer: every failure is the contract's one value-free message.
+ */
+export const snapshotClusterRelayAuthorizationExport = (
+  valueArg: unknown,
+): IClusterRelayAuthorizationExport => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['credential', 'authorization', 'receipt']);
+  requireNetwork(isClusterRelayAuthorization(value.authorization));
+  return {
+    credential: snapshotClusterRelayCredential(value.credential),
+    authorization: value.authorization,
+    receipt: snapshotClusterRelayAuthorizationExportReceipt(value.receipt),
+  };
+});
+
+/**
+ * Joins an export answer to the request it answers, before a reader writes a byte of the bearer.
+ *
+ * The credential is sealed with its own digest and is the requested cluster's at exactly the
+ * requested generation; the bearer names that credential; the receipt names that cluster and that
+ * exact credential. Content join only: whether the bearer authenticates is Cloudly's to prove,
+ * and Cloudly proves it before it answers.
+ */
+export const bindClusterRelayAuthorizationExport = async (
+  exportArg: unknown,
+  requestArg: unknown,
+): Promise<IClusterRelayAuthorizationExport> => {
+  try {
+    const request = snapshotClusterRelayAuthorizationExportRequest(requestArg);
+    const answer = snapshotClusterRelayAuthorizationExport(exportArg);
+    if ((await validateClusterRelayCredential(answer.credential)).length) fail();
+    requireNetwork(answer.credential.clusterId === request.clusterId
+      && answer.credential.generation === request.expectedGeneration
+      && clusterRelayAuthorizationCredentialId(answer.authorization) === answer.credential.id
+      && answer.receipt.clusterId === request.clusterId
+      && networkEqual(answer.receipt.credential, networkReferenceOf(answer.credential)));
+    return answer;
+  } catch { return fail(); }
+};

package/ts/data/corestorecontroltoken.ts

@@ -0,0 +1,195 @@
+import { isCorestoreControlToken } from '../runtime.corestore.js';
+import {
+  captureNetwork,
+  networkCounter,
+  networkId,
+  networkList,
+  networkRecord,
+  requireNetwork,
+} from '../private/networkcontract.js';
+
+/**
+ * Whether Cloudly holds the Corestore control token, and at which revision. Value-free.
+ *
+ * There is one token for both Corestore provider configs, so this is one state rather than one per
+ * provider. `revision` is 1 for the first token ever stored and advances by exactly one with every
+ * accepted set, whichever path set it. No request removes a token, so a present token never turns
+ * absent again.
+ */
+export type TCorestoreControlTokenState =
+  | { state: 'absent' }
+  | { state: 'present'; revision: number };
+
+/**
+ * What an administrator names to store the Corestore control token: the token, and the state the
+ * administrator last read. Never a minimum: a set that committed after that read is refused rather
+ * than overwritten.
+ *
+ * `token` is the secret itself, the only member of this contract that carries it. A sender never
+ * logs, hooks or persists the request; Cloudly never answers or records the token.
+ */
+export interface ICorestoreControlTokenSetRequest {
+  token: string;
+  expected: TCorestoreControlTokenState;
+}
+
+/**
+ * Which path stored a token: an administrator's typed request, or the `secrets
+ * set-corestore-control-token` command run inside Cloudly's container.
+ */
+export type TCorestoreControlTokenSetPath = 'admin-request' | 'container-cli';
+
+/**
+ * The audit record of one accepted set, which Cloudly writes in the transaction that stores the
+ * token. Append-only and value-free: it names which revision was stored, by whom, how and when,
+ * never the token or a hash of it.
+ */
+export interface ICorestoreControlTokenSetReceipt {
+  id: string;
+  /** The revision this set stored. */
+  revision: number;
+  via: TCorestoreControlTokenSetPath;
+  /** The administrator read from the verified credential, or `operator:secrets-cli`. */
+  actorId: string;
+  setAt: number;
+}
+
+/** What Cloudly answers to an accepted set: the state it produced and its receipt. Value-free. */
+export interface ICorestoreControlTokenSetResult {
+  state: { state: 'present'; revision: number };
+  receipt: ICorestoreControlTokenSetReceipt;
+}
+
+/**
+ * The token's state and its most recent receipts, oldest first: every receipt while the token has
+ * been set at most `corestoreControlTokenMaximumReceipts` times, the latest that many after. Value-free.
+ */
+export interface ICorestoreControlTokenStateRead {
+  state: TCorestoreControlTokenState;
+  receipts: ICorestoreControlTokenSetReceipt[];
+}
+
+/** Every reason Cloudly answers instead of storing a Corestore control token. */
+export const corestoreControlTokenSetRefusals = Object.freeze([
+  /** The token is outside the contract: its length, encoding or whitespace (`isCorestoreControlToken`). */
+  'token-invalid',
+  /** `expected` said absent, and a token is stored. */
+  'token-present',
+  /** `expected` named a revision, and no token is stored. */
+  'token-absent',
+  /** `expected` named a revision, and the stored token is at another one. */
+  'token-revision-mismatch',
+  /** A Corestore provider config is missing or disabled, so there is nothing to store it under. */
+  'provider-unavailable',
+] as const);
+
+export type TCorestoreControlTokenSetRefusal = typeof corestoreControlTokenSetRefusals[number];
+
+/** The actor a receipt names when the in-container command stored the token. */
+export const corestoreControlTokenContainerCliActorId = 'operator:secrets-cli' as const;
+
+/** The most receipts one state read answers: the latest ones, once a token has been set more often. */
+export const corestoreControlTokenMaximumReceipts = 4096;
+
+const fail = (): never => { throw new Error('Corestore control token contract rejected.'); };
+const safe = <T>(operationArg: () => T): T => {
+  try { return operationArg(); } catch { return fail(); }
+};
+
+const readState = (valueArg: unknown): TCorestoreControlTokenState => {
+  const value = networkRecord(valueArg, ['state'], ['revision']);
+  if (value.state === 'absent') {
+    networkRecord(value, ['state']);
+    return { state: 'absent' };
+  }
+  requireNetwork(value.state === 'present');
+  return { state: 'present', revision: networkCounter(networkRecord(value, ['state', 'revision']).revision) };
+};
+
+export const snapshotCorestoreControlTokenState = (
+  valueArg: unknown,
+): TCorestoreControlTokenState => safe(() => readState(captureNetwork(valueArg)));
+
+/**
+ * Structural copy of a set request. A refusal never quotes the request, because it carries the
+ * token: every failure is the contract's one value-free message.
+ */
+export const snapshotCorestoreControlTokenSetRequest = (
+  valueArg: unknown,
+): ICorestoreControlTokenSetRequest => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['token', 'expected']);
+  requireNetwork(isCorestoreControlToken(value.token));
+  return { token: value.token, expected: readState(value.expected) };
+});
+
+const readReceipt = (valueArg: unknown): ICorestoreControlTokenSetReceipt => {
+  const value = networkRecord(valueArg, ['id', 'revision', 'via', 'actorId', 'setAt']);
+  requireNetwork(value.via === 'admin-request' || value.via === 'container-cli');
+  const actorId = networkId(value.actorId);
+  requireNetwork(value.via === 'admin-request'
+    ? actorId !== corestoreControlTokenContainerCliActorId
+    : actorId === corestoreControlTokenContainerCliActorId);
+  return {
+    id: networkId(value.id),
+    revision: networkCounter(value.revision),
+    via: value.via,
+    actorId,
+    setAt: networkCounter(value.setAt),
+  };
+};
+
+export const snapshotCorestoreControlTokenSetReceipt = (
+  valueArg: unknown,
+): ICorestoreControlTokenSetReceipt => safe(() => readReceipt(captureNetwork(valueArg)));
+
+export const snapshotCorestoreControlTokenSetResult = (
+  valueArg: unknown,
+): ICorestoreControlTokenSetResult => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['state', 'receipt']);
+  const state = readState(value.state);
+  requireNetwork(state.state === 'present');
+  return { state, receipt: readReceipt(value.receipt) };
+});
+
+/**
+ * Structural copy of a state read. No token stored means no receipt. A stored token's receipts are
+ * contiguous and end at its revision, and they start at revision 1 -- or at 2, because only a token
+ * stored before receipts existed reaches revision 1 without one -- unless the read is a full window
+ * of `corestoreControlTokenMaximumReceipts`, whose oldest receipt may name any later revision.
+ */
+export const snapshotCorestoreControlTokenStateRead = (
+  valueArg: unknown,
+): ICorestoreControlTokenStateRead => safe(() => {
+  const value = networkRecord(captureNetwork(valueArg), ['state', 'receipts']);
+  const state = readState(value.state);
+  const receipts = networkList(value.receipts, corestoreControlTokenMaximumReceipts, readReceipt);
+  if (state.state === 'absent') {
+    requireNetwork(receipts.length === 0);
+    return { state, receipts };
+  }
+  const first = state.revision - receipts.length + 1;
+  requireNetwork(first >= 1
+    && (first <= 2 || receipts.length === corestoreControlTokenMaximumReceipts)
+    && receipts.every((receipt, index) => receipt.revision === first + index));
+  return { state, receipts };
+});
+
+/**
+ * Joins a set answer to the request it answers. The answered state is the one the request
+ * produces -- revision 1 when no token was stored, the expected revision plus one otherwise -- and
+ * the receipt is an administrator's receipt for exactly that revision. Content join only: whether
+ * the token was stored is Cloudly's to prove, and the answer never carries it.
+ */
+export const bindCorestoreControlTokenSet = (
+  resultArg: unknown,
+  requestArg: unknown,
+): ICorestoreControlTokenSetResult => safe(() => {
+  const request = snapshotCorestoreControlTokenSetRequest(requestArg);
+  const result = snapshotCorestoreControlTokenSetResult(resultArg);
+  const produced = request.expected.state === 'absent' ? 1 : request.expected.revision + 1;
+  requireNetwork(Number.isSafeInteger(produced)
+    && result.state.revision === produced
+    && result.receipt.revision === produced
+    && result.receipt.via === 'admin-request');
+  return result;
+});

package/ts/data/index.ts

@@ -7,6 +7,7 @@ export * from './clusteringressdesignation.js';
 export * from './clusterrelaycredential.js';
 export * from './config.js';
 export * from './corestore.js';
+export * from './corestorecontroltoken.js';
 export * from './corestorelegacyadoption.js';
 export * from './coremail.js';
 export * from './coremail.runtime.js';
@@ -38,6 +39,7 @@ export * from './networkaddressplan.js';
 export * from './networkauthority.js';
 export * from './networkcredential.js';
 export * from './networkdelivery.js';
+export * from './networkegressretirement.js';
 export * from './networklease.js';
 export * from './networknode.js';
 export * from './networkprojection.js';