@serve.zone/interfaces 32.40.0 → 32.41.0

package/changelog.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 2026-10-02 - 32.41.0
+
+### Features
+
+- An administrator can export a cluster relay's bearer without an exec into Cloudly's process.
+  `exportClusterRelayAuthorization { identity, clusterId, expectedGeneration }` answers
+  `IClusterRelayAuthorizationExport`: the sealed relay credential at exactly that generation, the
+  bearer it delivered (`authorization`) and the audit `receipt` Cloudly writes before it answers.
+  Cloudly mints nothing to answer it; a new bearer is a `rotate` followed by an export.
+  `getClusterRelayAuthorizationExports { identity, clusterId }` answers the value-free receipts.
+  `data.clusterRelayAuthorizationExportRefusals` names the refusals, and
+  `bindClusterRelayAuthorizationExport`, `isClusterRelayAuthorization` and the exact-keyed
+  snapshots let a reader check an answer before it writes the bearer, without ever quoting it.
+
+## 2026-10-02 - 32.40.1
+
+### Fixes
+
+- Depend on `@push.rocks/smartcrypto` 3, which no longer ships node-forge, so consumers' production trees are free of node-forge advisory GHSA-86w9-cpqp-85rv (lenient RSA PKCS#1 v1.5 verification, no patched release). The contracts use only smartcrypto's X25519 envelope API, which is unchanged.
+
 ## 2026-10-02 - 32.40.0
 
 ### Features

package/dist_ts/00_commitinfo_data.js

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

package/dist_ts/data/clusterrelaycredential.d.ts

@@ -106,6 +106,50 @@ export interface IClusterLegacyRelayCredentialRetirementResult {
     /** A replay returns the recorded invalidation; nothing is revoked twice. */
     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 declare const clusterRelayCredentialContract: Readonly<{
     readonly credentialDigestDomain: "serve.zone/cluster-relay-credential";
     readonly legacyCredentialDigestDomain: "serve.zone/cluster-relay-legacy-credential";
@@ -114,6 +158,12 @@ export declare const clusterRelayCredentialContract: Readonly<{
 /** Every reason Cloudly answers instead of mutating or retiring a cluster relay authority. */
 export declare const clusterRelayCredentialRefusals: readonly ["relay-credential-absent", "legacy-credential-absent", "legacy-credential-already-retired", "legacy-retirement-replacement-not-current", "legacy-retirement-registration-not-current", "legacy-retirement-relay-not-live", "conflict"];
 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 declare const clusterRelayAuthorizationExportRefusals: readonly ["relay-credential-absent", "relay-credential-generation-mismatch", "relay-authorization-missing", "relay-authorization-ambiguous"];
+export type TClusterRelayAuthorizationExportRefusal = typeof clusterRelayAuthorizationExportRefusals[number];
 /** Structural copy only; whether the record is the cluster's current one is Cloudly's to decide. */
 export declare const snapshotClusterRelayCredential: (valueArg: unknown) => IClusterRelayCredential;
 export declare const computeClusterRelayCredentialDigest: (valueArg: unknown) => Promise<TSha256Digest>;
@@ -138,4 +188,26 @@ export declare const bindClusterLegacyRelayCredentialInvalidation: (invalidation
     legacyCredential: IClusterLegacyRelayCredential;
     acceptedRegistration: IClusterRelayAcceptedRegistration;
 }>;
+/**
+ * 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 declare const isClusterRelayAuthorization: (valueArg: unknown) => valueArg is string;
+export declare const snapshotClusterRelayAuthorizationExportRequest: (valueArg: unknown) => IClusterRelayAuthorizationExportRequest;
+export declare const snapshotClusterRelayAuthorizationExportReceipt: (valueArg: unknown) => IClusterRelayAuthorizationExportReceipt;
+/**
+ * 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 declare const snapshotClusterRelayAuthorizationExport: (valueArg: unknown) => IClusterRelayAuthorizationExport;
+/**
+ * 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 declare const bindClusterRelayAuthorizationExport: (exportArg: unknown, requestArg: unknown) => Promise<IClusterRelayAuthorizationExport>;
 export {};

package/dist_ts/data/clusterrelaycredential.js

@@ -22,6 +22,20 @@ export const clusterRelayCredentialRefusals = Object.freeze([
     /** An expected generation was not the exact current one, or a mutation ID met a changed body. */
     'conflict',
 ]);
+/**
+ * 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',
+]);
 const fail = () => { throw new Error('Cluster relay credential contract rejected.'); };
 const safe = (operationArg) => {
     try {
@@ -189,4 +203,71 @@ export const bindClusterLegacyRelayCredentialInvalidation = async (invalidationA
         return fail();
     }
 };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2x1c3RlcnJlbGF5Y3JlZGVudGlhbC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL2RhdGEvY2x1c3RlcnJlbGF5Y3JlZGVudGlhbC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFDQSxPQUFPLEVBQ0wsd0NBQXdDLEVBQ3hDLHdDQUF3QyxHQUN6QyxNQUFNLGNBQWMsQ0FBQztBQUt0QixPQUFPLEVBQ0wsY0FBYyxFQUNkLGNBQWMsRUFDZCxhQUFhLEVBQ2IsWUFBWSxFQUNaLFdBQVcsRUFDWCxTQUFTLEVBQ1QsYUFBYSxFQUNiLGdCQUFnQixFQUNoQixrQkFBa0IsRUFDbEIsY0FBYyxHQUNmLE1BQU0sK0JBQStCLENBQUM7QUE4R3ZDLE1BQU0sQ0FBQyxNQUFNLDhCQUE4QixHQUFHLE1BQU0sQ0FBQyxNQUFNLENBQUM7SUFDMUQsc0JBQXNCLEVBQUUscUNBQXFDO0lBQzdELDRCQUE0QixFQUFFLDRDQUE0QztJQUMxRSw4QkFBOEIsRUFBRSx5REFBeUQ7Q0FDakYsQ0FBQyxDQUFDO0FBRVosOEZBQThGO0FBQzlGLE1BQU0sQ0FBQyxNQUFNLDhCQUE4QixHQUFHLE1BQU0sQ0FBQyxNQUFNLENBQUM7SUFDMUQsbUVBQW1FO0lBQ25FLHlCQUF5QjtJQUN6QiwyRUFBMkU7SUFDM0UsMEJBQTBCO0lBQzFCLGlGQUFpRjtJQUNqRixtQ0FBbUM7SUFDbkMsNkZBQTZGO0lBQzdGLDJDQUEyQztJQUMzQyxpR0FBaUc7SUFDakcsNENBQTRDO0lBQzVDLHNGQUFzRjtJQUN0RixrQ0FBa0M7SUFDbEMsaUdBQWlHO0lBQ2pHLFVBQVU7Q0FDRixDQUFDLENBQUM7QUFJWixNQUFNLElBQUksR0FBRyxHQUFVLEVBQUUsR0FBRyxNQUFNLElBQUksS0FBSyxDQUFDLDZDQUE2QyxDQUFDLENBQUMsQ0FBQyxDQUFDLENBQUM7QUFDOUYsTUFBTSxJQUFJLEdBQUcsQ0FBSSxZQUFxQixFQUFLLEVBQUU7SUFDM0MsSUFBSSxDQUFDO1FBQUMsT0FBTyxZQUFZ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
+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) => typeof valueArg === 'string' && clusterRelayAuthorizationPattern.test(valueArg);
+/** The credential identity a relay bearer names: the 64 hex characters after its prefix. */
+const clusterRelayAuthorizationCredentialId = (authorizationArg) => authorizationArg.slice(clusterRelayAuthorizationPrefix.length, clusterRelayAuthorizationPrefix.length + 64);
+export const snapshotClusterRelayAuthorizationExportRequest = (valueArg) => safe(() => {
+    const value = networkRecord(captureNetwork(valueArg), ['clusterId', 'expectedGeneration']);
+    return {
+        clusterId: networkId(value.clusterId),
+        expectedGeneration: networkCounter(value.expectedGeneration),
+    };
+});
+export const snapshotClusterRelayAuthorizationExportReceipt = (valueArg) => 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) => 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, requestArg) => {
+    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();
+    }
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2x1c3RlcnJlbGF5Y3JlZGVudGlhbC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzL2RhdGEvY2x1c3RlcnJlbGF5Y3JlZGVudGlhbC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFDQSxPQUFPLEVBQ0wsd0NBQXdDLEVBQ3hDLHdDQUF3QyxHQUN6QyxNQUFNLGNBQWMsQ0FBQztBQUt0QixPQUFPLEVBQ0wsY0FBYyxFQUNkLGNBQWMsRUFDZCxhQUFhLEVBQ2IsWUFBWSxFQUNaLFdBQVcsRUFDWCxTQUFTLEVBQ1QsYUFBYSxFQUNiLGdCQUFnQixFQUNoQixrQkFBa0IsRUFDbEIsY0FBYyxHQUNmLE1BQU0sK0JBQStCLENBQUM7QUE2SnZDLE1BQU0sQ0FBQyxNQUFNLDhCQUE4QixHQUFHLE1BQU0sQ0FBQyxNQUFNLENBQUM7SUFDMUQsc0JBQXNCLEVBQUUscUNBQXFDO0lBQzdELDRCQUE0QixFQUFFLDRDQUE0QztJQUMxRSw4QkFBOEIsRUFBRSx5REFBeUQ7Q0FDakYsQ0FBQyxDQUFDO0FBRVosOEZBQThGO0FBQzlGLE1BQU0sQ0FBQyxNQUFNLDhCQUE4QixHQUFHLE1BQU0sQ0FBQyxNQUFNLENBQUM7SUFDMUQsbUVBQW1FO0lBQ25FLHlCQUF5QjtJQUN6QiwyRUFBMkU7SUFDM0UsMEJBQTBCO0lBQzFCLGlGQUFpRjtJQUNqRixtQ0FBbUM7SUFDbkMsNkZBQTZGO0lBQzdGLDJDQUEyQztJQUMzQyxpR0FBaUc7SUFDakcsNENBQTRDO0lBQzVDLHNGQUFzRjtJQUN0RixrQ0FBa0M7SUFDbEMsaUdBQWlHO0lBQ2pHLFVBQVU7Q0FDRixDQUFDLENBQUM7QUFJWjs7O0dBR0c7QUFDSCxNQUFNLENBQUMsTUFBTSx1Q0FBdUMsR0FBRyxNQUFNLENBQUMsTUFBTSxDQUFDO0lBQ25FLHFEQUFxRDtJQUNyRCx5QkFBeUI7SUFDekIsK0ZBQStGO0lBQy9GLHNDQUFzQztJQUN0QywrRUFBK0U7SUFDL0UsNkJBQTZCO0lBQzdCLHFGQUFxRjtJQUNy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

package/dist_ts/requests/cluster.d.ts

@@ -170,6 +170,40 @@ export interface IReq_Admin_Cloudly_RetireLegacyClusterRelayCredential extends p
     };
     response: relayCredentialInterfaces.IClusterLegacyRelayCredentialRetirementResult;
 }
+/**
+ * Answers one cluster's relay bearer to an administrator, so it reaches the relay without an exec
+ * into Cloudly's process.
+ *
+ * Cloudly mints nothing here: a bearer is issued by `mutateClusterRelayCredential` and delivered as
+ * the encrypted version the credential names, and this reads exactly that version at exactly
+ * `expectedGeneration`, proved against the hash that generation issued. A new bearer is a
+ * rotation followed by an export at the new generation. Only the verified credential of a freshly
+ * authenticated administrator is read, as for a credential mutation, and Cloudly writes the
+ * `receipt` before it answers, so no bearer leaves without an audit record. The bearer is in this
+ * answer and nowhere else: never in a log, a receipt or another request. Cloudly refuses with one
+ * of `data.clusterRelayAuthorizationExportRefusals`.
+ */
+export interface IReq_Admin_Cloudly_ExportClusterRelayAuthorization extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Admin_Cloudly_ExportClusterRelayAuthorization> {
+    method: 'exportClusterRelayAuthorization';
+    request: relayCredentialInterfaces.IClusterRelayAuthorizationExportRequest & {
+        identity: userInterfaces.IIdentityCredential;
+    };
+    response: relayCredentialInterfaces.IClusterRelayAuthorizationExport;
+}
+/**
+ * The audit trail of one cluster's relay bearer exports: every receipt, oldest first. Value-free,
+ * like the receipts themselves; empty while no bearer was ever exported.
+ */
+export interface IReq_Admin_Cloudly_GetClusterRelayAuthorizationExports extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Admin_Cloudly_GetClusterRelayAuthorizationExports> {
+    method: 'getClusterRelayAuthorizationExports';
+    request: {
+        identity: userInterfaces.IIdentityCredential;
+        clusterId: string;
+    };
+    response: {
+        receipts: relayCredentialInterfaces.IClusterRelayAuthorizationExportReceipt[];
+    };
+}
 /**
  * Cloudly hands the cluster relay the DNS lease renewals it has signed ahead of time for one node.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/interfaces",
-  "version": "32.40.0",
+  "version": "32.41.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.",
   "exports": {
@@ -22,7 +22,7 @@
   "license": "MIT",
   "dependencies": {
     "@api.global/typedrequest-interfaces": "^7.1.0",
-    "@push.rocks/smartcrypto": "^2.2.0",
+    "@push.rocks/smartcrypto": "^3.0.0",
     "@push.rocks/smartlog": "^4.0.0",
     "@tsclass/tsclass": "^9.5.1"
   },

package/readme.md

@@ -2723,8 +2723,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 +2777,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

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/interfaces',
-  version: '32.40.0',
+  version: '32.41.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/requests/cluster.ts

@@ -219,6 +219,50 @@ extends plugins.typedrequestInterfaces.implementsTR<
   response: relayCredentialInterfaces.IClusterLegacyRelayCredentialRetirementResult;
 }
 
+/**
+ * Answers one cluster's relay bearer to an administrator, so it reaches the relay without an exec
+ * into Cloudly's process.
+ *
+ * Cloudly mints nothing here: a bearer is issued by `mutateClusterRelayCredential` and delivered as
+ * the encrypted version the credential names, and this reads exactly that version at exactly
+ * `expectedGeneration`, proved against the hash that generation issued. A new bearer is a
+ * rotation followed by an export at the new generation. Only the verified credential of a freshly
+ * authenticated administrator is read, as for a credential mutation, and Cloudly writes the
+ * `receipt` before it answers, so no bearer leaves without an audit record. The bearer is in this
+ * answer and nowhere else: never in a log, a receipt or another request. Cloudly refuses with one
+ * of `data.clusterRelayAuthorizationExportRefusals`.
+ */
+export interface IReq_Admin_Cloudly_ExportClusterRelayAuthorization
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Admin_Cloudly_ExportClusterRelayAuthorization
+> {
+  method: 'exportClusterRelayAuthorization';
+  request: relayCredentialInterfaces.IClusterRelayAuthorizationExportRequest & {
+    identity: userInterfaces.IIdentityCredential;
+  };
+  response: relayCredentialInterfaces.IClusterRelayAuthorizationExport;
+}
+
+/**
+ * The audit trail of one cluster's relay bearer exports: every receipt, oldest first. Value-free,
+ * like the receipts themselves; empty while no bearer was ever exported.
+ */
+export interface IReq_Admin_Cloudly_GetClusterRelayAuthorizationExports
+extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Admin_Cloudly_GetClusterRelayAuthorizationExports
+> {
+  method: 'getClusterRelayAuthorizationExports';
+  request: {
+    identity: userInterfaces.IIdentityCredential;
+    clusterId: string;
+  };
+  response: {
+    receipts: relayCredentialInterfaces.IClusterRelayAuthorizationExportReceipt[];
+  };
+}
+
 /**
  * Cloudly hands the cluster relay the DNS lease renewals it has signed ahead of time for one node.
  *