@serve.zone/interfaces 27.5.0 → 28.0.0

package/changelog.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 2026-09-05 - 28.0.0
+
+### Breaking Changes
+
+- require identity for node config and add credential administration contracts (node-credentials)
+  - Add node credential metadata, mutation precondition, and mutation result interfaces for spark and pallet purposes.
+  - Add getNodeCredential, rotateNodeCredential, and revokeNodeCredential typed request contracts with infrastructure-admin identity requirements.
+  - Require identity on getNodeConfig requests, changing the existing request shape.
+  - Document node credential administration semantics and add type-level contract tests.
+
 ## 2026-09-05 - 27.5.0
 
 ### Features

package/dist_ts/00_commitinfo_data.js

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

package/dist_ts/data/index.d.ts

@@ -20,6 +20,7 @@ export * from './immutableimage.js';
 export * from './isolatedrestore.js';
 export * from './isolatedrestore.golden.js';
 export * from './mail.js';
+export * from './nodecredential.js';
 export * from './registry.js';
 export * from './runtimeassignment.js';
 export * from './secret.js';

package/dist_ts/data/index.js

@@ -20,6 +20,7 @@ export * from './immutableimage.js';
 export * from './isolatedrestore.js';
 export * from './isolatedrestore.golden.js';
 export * from './mail.js';
+export * from './nodecredential.js';
 export * from './registry.js';
 export * from './runtimeassignment.js';
 export * from './secret.js';
@@ -36,4 +37,4 @@ export * from './traffic.js';
 export * from './user.js';
 export * from './version.js';
 export * from './webpush.js';
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxlQUFlLENBQUM7QUFDOUIsY0FBYyx1QkFBdUIsQ0FBQztBQUN0QyxjQUFjLGlCQUFpQixDQUFDO0FBQ2hDLGNBQWMseUJBQXlCLENBQUM7QUFDeEMsY0FBYywwQkFBMEIsQ0FBQztBQUN6QyxjQUFjLDBCQUEwQixDQUFDO0FBQ3pDLGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyxVQUFVLENBQUM7QUFDekIsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxZQUFZLENBQUM7QUFDM0IsY0FBYyx1QkFBdUIsQ0FBQztBQUN0QyxjQUFjLGNBQWMsQ0FBQztBQUM3QixjQUFjLGdCQUFnQixDQUFDO0FBQy9CLGNBQWMsWUFBWSxDQUFDO0FBQzNCLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyxzQkFBc0IsQ0FBQztBQUNyQyxjQUFjLDZCQUE2QixDQUFDO0FBQzVDLGNBQWMsV0FBVyxDQUFDO0FBQzFCLGNBQWMsZUFBZSxDQUFDO0FBQzlCLGNBQWMsd0JBQXdCLENBQUM7QUFDdkMsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxnQkFBZ0IsQ0FBQztBQUMvQixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLGtCQUFrQixDQUFDO0FBQ2pDLGNBQWMsZUFBZSxDQUFDO0FBQzlCLGNBQWMsY0FBYyxDQUFDO0FBQzdCLGNBQWMsbUJBQW1CLENBQUM7QUFDbEMsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxvQkFBb0IsQ0FBQztBQUNuQyxjQUFjLGNBQWMsQ0FBQztBQUM3QixjQUFjLFdBQVcsQ0FBQztBQUMxQixjQUFjLGNBQWMsQ0FBQztBQUM3QixjQUFjLGNBQWMsQ0FBQyJ9
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL2luZGV4LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLGNBQWMsb0JBQW9CLENBQUM7QUFDbkMsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxlQUFlLENBQUM7QUFDOUIsY0FBYyx1QkFBdUIsQ0FBQztBQUN0QyxjQUFjLGlCQUFpQixDQUFDO0FBQ2hDLGNBQWMseUJBQXlCLENBQUM7QUFDeEMsY0FBYywwQkFBMEIsQ0FBQztBQUN6QyxjQUFjLDBCQUEwQixDQUFDO0FBQ3pDLGNBQWMsZ0JBQWdCLENBQUM7QUFDL0IsY0FBYyxVQUFVLENBQUM7QUFDekIsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxhQUFhLENBQUM7QUFDNUIsY0FBYyxZQUFZLENBQUM7QUFDM0IsY0FBYyx1QkFBdUIsQ0FBQztBQUN0QyxjQUFjLGNBQWMsQ0FBQztBQUM3QixjQUFjLGdCQUFnQixDQUFDO0FBQy9CLGNBQWMsWUFBWSxDQUFDO0FBQzNCLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyxzQkFBc0IsQ0FBQztBQUNyQyxjQUFjLDZCQUE2QixDQUFDO0FBQzVDLGNBQWMsV0FBVyxDQUFDO0FBQzFCLGNBQWMscUJBQXFCLENBQUM7QUFDcEMsY0FBYyxlQUFlLENBQUM7QUFDOUIsY0FBYyx3QkFBd0IsQ0FBQztBQUN2QyxjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLGdCQUFnQixDQUFDO0FBQy9CLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsYUFBYSxDQUFDO0FBQzVCLGNBQWMsa0JBQWtCLENBQUM7QUFDakMsY0FBYyxlQUFlLENBQUM7QUFDOUIsY0FBYyxjQUFjLENBQUM7QUFDN0IsY0FBYyxtQkFBbUIsQ0FBQztBQUNsQyxjQUFjLGFBQWEsQ0FBQztBQUM1QixjQUFjLG9CQUFvQixDQUFDO0FBQ25DLGNBQWMsY0FBYyxDQUFDO0FBQzdCLGNBQWMsV0FBVyxDQUFDO0FBQzFCLGNBQWMsY0FBYyxDQUFDO0FBQzdCLGNBQWMsY0FBYyxDQUFDIn0=

package/dist_ts/data/nodecredential.d.ts

@@ -0,0 +1,38 @@
+/** Independent infrastructure credentials; neither purpose grants workload RBAC. */
+export type TNodeCredentialPurpose = 'spark' | 'pallet';
+/**
+ * Public inspection and mutation-result metadata. Never includes bearer material,
+ * hashes, socket peer IDs or controller process IDs. On replay this is historical
+ * evidence, not an assertion that a credential or reporter session is still live.
+ */
+export interface INodeCredentialMetadataV1 {
+    schemaVersion: 1;
+    nodeId: string;
+    purpose: TNodeCredentialPurpose;
+    state: 'active' | 'revoked';
+    generation: number;
+    /** Migrated Spark credentials remain usable only until their staged rotation. */
+    requiresRotation: boolean;
+    sessionEpoch: number;
+    sessionId: string | null;
+    createdAt: number;
+    updatedAt: number;
+}
+/**
+ * Infrastructure-admin mutation preconditions. Both counters are exact CAS
+ * preconditions, not minimums. Retrying must retain this complete input and the
+ * original mutationId; a changed request with the same ID must fail closed.
+ */
+export interface INodeCredentialMutationPreconditionsV1 {
+    schemaVersion: 1;
+    nodeId: string;
+    purpose: TNodeCredentialPurpose;
+    mutationId: string;
+    expectedGeneration: number;
+    expectedSessionEpoch: number;
+}
+export interface INodeCredentialMutationResultV1 {
+    metadata: INodeCredentialMetadataV1;
+    /** A replay returns the original result without restoring its authority. */
+    replayed: boolean;
+}

package/dist_ts/data/nodecredential.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoibm9kZWNyZWRlbnRpYWwuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90cy9kYXRhL25vZGVjcmVkZW50aWFsLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiIifQ==

package/dist_ts/requests/node.d.ts

@@ -4,15 +4,54 @@ import type { ICluster } from '../data/cluster.js';
 import type { IClusterNode, IClusterNodeMetrics, INodeAction, INodeMetricsSample, ISparkNodeRuntimeInfo, TNodeActionName } from '../data/clusternode.js';
 import type { IDeployment } from '../data/deployment.js';
 import type { IIdentity } from '../data/user.js';
-export interface IRequest_Any_Cloudly_GetNodeConfig {
+import type { INodeCredentialMetadataV1, INodeCredentialMutationPreconditionsV1, INodeCredentialMutationResultV1, TNodeCredentialPurpose } from '../data/nodecredential.js';
+/** Requires verified platform-infrastructure admin authority; returns public data only. */
+export interface IRequest_Any_Cloudly_GetNodeConfig extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IRequest_Any_Cloudly_GetNodeConfig> {
     method: 'getNodeConfig';
     request: {
+        identity: IIdentity;
         nodeId: string;
     };
     response: {
         configData: IClusterNode;
     };
 }
+/** These credential methods require verified infrastructure-admin authority. */
+export interface IReq_Any_Cloudly_GetNodeCredential extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_Cloudly_GetNodeCredential> {
+    method: 'getNodeCredential';
+    request: {
+        identity: IIdentity;
+        nodeId: string;
+        purpose: TNodeCredentialPurpose;
+    };
+    response: {
+        metadata: INodeCredentialMetadataV1 | null;
+    };
+}
+export interface IReq_Any_Cloudly_RotateNodeCredential extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_Cloudly_RotateNodeCredential> {
+    method: 'rotateNodeCredential';
+    request: {
+        identity: IIdentity;
+        mutation: INodeCredentialMutationPreconditionsV1 & {
+            /**
+             * SHA-256(token UTF-8 bytes), exactly 64 lowercase hexadecimal characters.
+             * The node must durably retain its pending CSPRNG credential and mutation
+             * identity before this request. A metadata-only retry never issues plaintext.
+             * Treat this request field as sensitive; never include it in hooks or logs.
+             */
+            newTokenHash: string;
+        };
+    };
+    response: INodeCredentialMutationResultV1;
+}
+export interface IReq_Any_Cloudly_RevokeNodeCredential extends plugins.typedrequestInterfaces.implementsTR<plugins.typedrequestInterfaces.ITypedRequest, IReq_Any_Cloudly_RevokeNodeCredential> {
+    method: 'revokeNodeCredential';
+    request: {
+        identity: IIdentity;
+        mutation: INodeCredentialMutationPreconditionsV1;
+    };
+    response: INodeCredentialMutationResultV1;
+}
 export interface IRequest_Any_Cloudly_GetNodesByCluster {
     method: 'getNodesByCluster';
     request: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/interfaces",
-  "version": "27.5.0",
+  "version": "28.0.0",
   "private": false,
   "description": "Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.",
   "exports": {

package/readme.md

@@ -47,6 +47,33 @@ validator; unlike `@serve.zone/interfaces/runtime`, it does not load the general
 runtime graph, `plugins.js`, SmartCrypto, TypedRequest, Corestore, or settlement
 runtime modules.
 
+### Node Credential Administration
+
+`requests.node` defines `getNodeCredential`, `rotateNodeCredential` and
+`revokeNodeCredential` for verified platform-infrastructure administrators.
+`getNodeConfig` now also requires `identity`; callers using the previous
+unauthenticated request shape must update. Its response remains the public
+`IClusterNode`, never a persisted backend document.
+
+`data.INodeCredentialMetadataV1` separates `spark` and `pallet` purposes and
+exposes lifecycle state, generation, rotation-required status and session epoch,
+but no bearer, hash, socket peer or controller process identity. Infrastructure
+credentials do not grant organization or workload permissions.
+
+Mutations require the exact generation and session epoch plus a stable mutation
+ID. Rotation takes the SHA-256 hash of a node-generated CSPRNG credential that the
+node has already durably retained with that mutation ID. Lost-response retries
+repeat the complete request and receive the original metadata, never newly minted
+plaintext. A replay result is historical and cannot authorize a current session.
+Treat rotation request hashes as sensitive in transport hooks and logs.
+
+These types do not implement authentication, storage, enrollment or endpoints.
+Cloudly must verify current administrator authority, validate complete inputs,
+atomically persist the credential transition and immutable actor-bound receipt,
+and fence subsequent control effects against current durable credential/session
+authority. Node identity storage and transport integration must be qualified
+before enabling rotation or Pallet enrollment.
+
 ### Node-Bound Runtime Assignments
 
 The `data` namespace exports `IRuntimeAssignmentV1`, canonical digest helpers,

package/ts/00_commitinfo_data.ts

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

package/ts/data/index.ts

@@ -20,6 +20,7 @@ export * from './immutableimage.js';
 export * from './isolatedrestore.js';
 export * from './isolatedrestore.golden.js';
 export * from './mail.js';
+export * from './nodecredential.js';
 export * from './registry.js';
 export * from './runtimeassignment.js';
 export * from './secret.js';

package/ts/data/nodecredential.ts

@@ -0,0 +1,41 @@
+/** Independent infrastructure credentials; neither purpose grants workload RBAC. */
+export type TNodeCredentialPurpose = 'spark' | 'pallet';
+
+/**
+ * Public inspection and mutation-result metadata. Never includes bearer material,
+ * hashes, socket peer IDs or controller process IDs. On replay this is historical
+ * evidence, not an assertion that a credential or reporter session is still live.
+ */
+export interface INodeCredentialMetadataV1 {
+  schemaVersion: 1;
+  nodeId: string;
+  purpose: TNodeCredentialPurpose;
+  state: 'active' | 'revoked';
+  generation: number;
+  /** Migrated Spark credentials remain usable only until their staged rotation. */
+  requiresRotation: boolean;
+  sessionEpoch: number;
+  sessionId: string | null;
+  createdAt: number;
+  updatedAt: number;
+}
+
+/**
+ * Infrastructure-admin mutation preconditions. Both counters are exact CAS
+ * preconditions, not minimums. Retrying must retain this complete input and the
+ * original mutationId; a changed request with the same ID must fail closed.
+ */
+export interface INodeCredentialMutationPreconditionsV1 {
+  schemaVersion: 1;
+  nodeId: string;
+  purpose: TNodeCredentialPurpose;
+  mutationId: string;
+  expectedGeneration: number;
+  expectedSessionEpoch: number;
+}
+
+export interface INodeCredentialMutationResultV1 {
+  metadata: INodeCredentialMetadataV1;
+  /** A replay returns the original result without restoring its authority. */
+  replayed: boolean;
+}

package/ts/requests/node.ts

@@ -4,10 +4,21 @@ import type { ICluster } from '../data/cluster.js';
 import type { IClusterNode, IClusterNodeMetrics, INodeAction, INodeMetricsSample, ISparkNodeRuntimeInfo, TNodeActionName } from '../data/clusternode.js';
 import type { IDeployment } from '../data/deployment.js';
 import type { IIdentity } from '../data/user.js';
+import type {
+  INodeCredentialMetadataV1,
+  INodeCredentialMutationPreconditionsV1,
+  INodeCredentialMutationResultV1,
+  TNodeCredentialPurpose,
+} from '../data/nodecredential.js';
 
-export interface IRequest_Any_Cloudly_GetNodeConfig {
+/** Requires verified platform-infrastructure admin authority; returns public data only. */
+export interface IRequest_Any_Cloudly_GetNodeConfig extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IRequest_Any_Cloudly_GetNodeConfig
+> {
   method: 'getNodeConfig';
   request: {
+    identity: IIdentity;
     nodeId: string;
   };
   response: {
@@ -15,6 +26,54 @@ export interface IRequest_Any_Cloudly_GetNodeConfig {
   };
 }
 
+/** These credential methods require verified infrastructure-admin authority. */
+export interface IReq_Any_Cloudly_GetNodeCredential extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_GetNodeCredential
+> {
+  method: 'getNodeCredential';
+  request: {
+    identity: IIdentity;
+    nodeId: string;
+    purpose: TNodeCredentialPurpose;
+  };
+  response: {
+    metadata: INodeCredentialMetadataV1 | null;
+  };
+}
+
+export interface IReq_Any_Cloudly_RotateNodeCredential extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_RotateNodeCredential
+> {
+  method: 'rotateNodeCredential';
+  request: {
+    identity: IIdentity;
+    mutation: INodeCredentialMutationPreconditionsV1 & {
+      /**
+       * SHA-256(token UTF-8 bytes), exactly 64 lowercase hexadecimal characters.
+       * The node must durably retain its pending CSPRNG credential and mutation
+       * identity before this request. A metadata-only retry never issues plaintext.
+       * Treat this request field as sensitive; never include it in hooks or logs.
+       */
+      newTokenHash: string;
+    };
+  };
+  response: INodeCredentialMutationResultV1;
+}
+
+export interface IReq_Any_Cloudly_RevokeNodeCredential extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_Any_Cloudly_RevokeNodeCredential
+> {
+  method: 'revokeNodeCredential';
+  request: {
+    identity: IIdentity;
+    mutation: INodeCredentialMutationPreconditionsV1;
+  };
+  response: INodeCredentialMutationResultV1;
+}
+
 export interface IRequest_Any_Cloudly_GetNodesByCluster {
   method: 'getNodesByCluster';
   request: {