@serve.zone/interfaces 32.9.0 → 32.10.1

package/ts/data/runtimesession.ts

@@ -23,6 +23,8 @@ import { isClusterNodeId } from '../private/nodeidentifier.js';
 export interface IRuntimeSessionBinding {
   reporterSessionId: string;
   nodeId: string;
+  /** Cluster read from the controller's owned node record when this session is admitted. */
+  clusterId: string;
   credentialGeneration: number;
   sessionEpoch: number;
   controllerInstanceId: string;
@@ -254,12 +256,13 @@ const reference = (valueArg: unknown): IRuntimeAssignmentReference => {
   return { assignmentId: identifier(value.assignmentId), generation: positive(value.generation), digest: value.digest };
 };
 const session = (valueArg: unknown): IRuntimeSessionBinding => {
-  const value = record(valueArg, ['reporterSessionId', 'nodeId', 'credentialGeneration',
+  const value = record(valueArg, ['reporterSessionId', 'nodeId', 'clusterId', 'credentialGeneration',
     'sessionEpoch', 'controllerInstanceId', 'controller', 'runtimeNamespace']);
   const controller = record(value.controller, ['kind', 'id', 'epoch']);
   requireValue(controller.kind === 'cloudly' || controller.kind === 'onebox');
   return {
     reporterSessionId: identifier(value.reporterSessionId), nodeId: nodeId(value.nodeId),
+    clusterId: identifier(value.clusterId),
     credentialGeneration: positive(value.credentialGeneration), sessionEpoch: positive(value.sessionEpoch),
     controllerInstanceId: identifier(value.controllerInstanceId),
     controller: { kind: controller.kind, id: identifier(controller.id), epoch: identifier(controller.epoch) },
@@ -269,7 +272,8 @@ const session = (valueArg: unknown): IRuntimeSessionBinding => {
 const sameSession = (leftArg: IRuntimeSessionBinding, rightArg: IRuntimeSessionBinding): boolean =>
   canonical(leftArg) === canonical(rightArg);
 const sameOwner = (leftArg: IRuntimeSessionBinding, rightArg: IRuntimeSessionBinding): boolean =>
-  leftArg.nodeId === rightArg.nodeId && leftArg.runtimeNamespace === rightArg.runtimeNamespace
+  leftArg.nodeId === rightArg.nodeId && leftArg.clusterId === rightArg.clusterId
+  && leftArg.runtimeNamespace === rightArg.runtimeNamespace
   && canonical(leftArg.controller) === canonical(rightArg.controller);
 const matchesAssignment = (sessionArg: IRuntimeSessionBinding, assignmentArg: IRuntimeAssignment): boolean =>
   sessionArg.nodeId === assignmentArg.nodeId && sessionArg.runtimeNamespace === assignmentArg.runtimeNamespace

package/ts/data/runtimestorageclaim.ts

@@ -0,0 +1,162 @@
+import type { TSha256Digest } from './immutableimage.js';
+import type { IRuntimeAssignment, IRuntimeAuthorityReference, IRuntimeController } from './runtimeassignment.js';
+import { snapshotRuntimeAssignment, validateRuntimeAssignment } from './runtimeassignment.js';
+import { normalizeServiceAbsolutePath } from './service.js';
+import type { IResolvedFilesystemStorageBinding } from '../platform/storage.js';
+import { canonicalizeStrictJson, createCanonicalJsonSha256Hex } from '../private/canonicaljson.js';
+import { isClusterNodeId } from '../private/nodeidentifier.js';
+
+/** Only immutable, portable fields of a ready Corestore filesystem binding. */
+export interface IRuntimeStorageClaimBinding extends Pick<IResolvedFilesystemStorageBinding,
+  'id' | 'serviceId' | 'requestId' | 'requestDigest' | 'generation' | 'observedGeneration'
+  | 'policy' | 'resourceRef' | 'mountPath'> {
+  kind: 'filesystem';
+  status: 'ready';
+  accessMode: 'ReadWriteOnce';
+  capabilities: { durability: 'persistent'; topology: 'singleNode' };
+}
+
+/** Cloudly authority for one retained, node-local volume; no host path or attachment attempt. */
+export interface IRuntimeStorageClaim {
+  id: string;
+  generation: number;
+  previous: IRuntimeAuthorityReference | null;
+  controller: IRuntimeController & { kind: 'cloudly' };
+  organizationId: string;
+  clusterId: string;
+  nodeId: string;
+  runtimeNamespace: string;
+  serviceId: string;
+  binding: IRuntimeStorageClaimBinding;
+  reclaimPolicy: 'retain';
+  digest: TSha256Digest;
+}
+
+export const runtimeStorageClaimContract = Object.freeze({
+  digestDomain: 'serve.zone/runtime-storage-claim',
+  accessMode: 'ReadWriteOnce',
+  reclaimPolicy: 'retain',
+} as const);
+
+const fail = (): never => { throw new Error('Runtime storage claim contract rejected.'); };
+function requireValue(conditionArg: unknown): asserts conditionArg { if (!conditionArg) fail(); }
+const record = (valueArg: unknown, keysArg: readonly string[]): Record<string, unknown> => {
+  requireValue(valueArg !== null && typeof valueArg === 'object' && !Array.isArray(valueArg));
+  const prototype = Object.getPrototypeOf(valueArg);
+  requireValue(prototype === Object.prototype || prototype === null);
+  const keys = Reflect.ownKeys(valueArg);
+  requireValue(keys.length === keysArg.length && keysArg.every((keyArg) => keys.includes(keyArg)));
+  const result: Record<string, unknown> = Object.create(null);
+  for (const key of keysArg) {
+    const descriptor = Object.getOwnPropertyDescriptor(valueArg, key);
+    requireValue(descriptor?.enumerable && Object.hasOwn(descriptor, 'value'));
+    result[key] = descriptor.value;
+  }
+  return result;
+};
+const id = (valueArg: unknown): string => {
+  requireValue(typeof valueArg === 'string' && /^[A-Za-z0-9][A-Za-z0-9:._@-]{0,191}$/.test(valueArg));
+  return valueArg as string;
+};
+const assignmentId = (valueArg: unknown): string => {
+  requireValue(typeof valueArg === 'string' && /^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/.test(valueArg));
+  return valueArg as string;
+};
+const generation = (valueArg: unknown): number => {
+  requireValue(typeof valueArg === 'number' && Number.isSafeInteger(valueArg)
+    && valueArg > 0 && valueArg < Number.MAX_SAFE_INTEGER);
+  return valueArg as number;
+};
+const digest = (valueArg: unknown): TSha256Digest => {
+  requireValue(typeof valueArg === 'string' && /^sha256:[a-f0-9]{64}$/.test(valueArg));
+  return valueArg as TSha256Digest;
+};
+const reference = (valueArg: unknown): IRuntimeAuthorityReference => {
+  const value = record(valueArg, ['id', 'generation', 'digest']);
+  return { id: assignmentId(value.id), generation: generation(value.generation), digest: digest(value.digest) };
+};
+const controller = (valueArg: unknown): IRuntimeStorageClaim['controller'] => {
+  const value = record(valueArg, ['kind', 'id', 'epoch']);
+  requireValue(value.kind === 'cloudly');
+  return { kind: 'cloudly', id: assignmentId(value.id), epoch: assignmentId(value.epoch) };
+};
+const mountPath = (valueArg: unknown): string => {
+  requireValue(typeof valueArg === 'string' && normalizeServiceAbsolutePath(valueArg) === valueArg
+    && valueArg !== '/' && valueArg !== '/run' && valueArg !== '/run/secrets'
+    && !valueArg.startsWith('/run/secrets/') && !'/run/secrets'.startsWith(`${valueArg}/`));
+  return valueArg as string;
+};
+const binding = (valueArg: unknown): IRuntimeStorageClaimBinding => {
+  const value = record(valueArg, ['id', 'serviceId', 'requestId', 'requestDigest', 'kind',
+    'generation', 'observedGeneration', 'status', 'policy', 'resourceRef', 'mountPath',
+    'accessMode', 'capabilities']);
+  requireValue(value.kind === 'filesystem' && value.status === 'ready'
+    && value.accessMode === 'ReadWriteOnce'
+    && typeof value.requestDigest === 'string' && /^[a-f0-9]{64}$/.test(value.requestDigest));
+  const policy = record(value.policy, ['classId', 'revision']);
+  const capabilities = record(value.capabilities, ['durability', 'topology']);
+  requireValue(capabilities.durability === 'persistent' && capabilities.topology === 'singleNode');
+  const bindingGeneration = generation(value.generation);
+  requireValue(generation(value.observedGeneration) === bindingGeneration);
+  return { id: id(value.id), serviceId: assignmentId(value.serviceId), requestId: id(value.requestId),
+    requestDigest: value.requestDigest as string, kind: 'filesystem', generation: bindingGeneration,
+    observedGeneration: bindingGeneration, status: 'ready',
+    policy: { classId: id(policy.classId), revision: id(policy.revision) },
+    resourceRef: id(value.resourceRef), mountPath: mountPath(value.mountPath),
+    accessMode: 'ReadWriteOnce', capabilities: { durability: 'persistent', topology: 'singleNode' } };
+};
+
+/** Detached exact-schema snapshot. Digest and authoritative provider readiness are separate checks. */
+export const snapshotRuntimeStorageClaim = (valueArg: unknown): IRuntimeStorageClaim => {
+  const value = record(valueArg, ['id', 'generation', 'previous', 'controller', 'organizationId',
+    'clusterId', 'nodeId', 'runtimeNamespace', 'serviceId', 'binding', 'reclaimPolicy', 'digest']);
+  const claimId = assignmentId(value.id), claimGeneration = generation(value.generation);
+  const previous = value.previous === null ? null : reference(value.previous);
+  requireValue(claimGeneration === 1 ? previous === null
+    : previous?.id === claimId && previous.generation === claimGeneration - 1);
+  requireValue(isClusterNodeId(value.nodeId) && value.reclaimPolicy === 'retain');
+  const claimBinding = binding(value.binding), serviceId = assignmentId(value.serviceId);
+  requireValue(claimBinding.serviceId === serviceId);
+  return { id: claimId, generation: claimGeneration, previous, controller: controller(value.controller),
+    organizationId: assignmentId(value.organizationId), clusterId: id(value.clusterId),
+    nodeId: value.nodeId as string, runtimeNamespace: assignmentId(value.runtimeNamespace), serviceId,
+    binding: claimBinding, reclaimPolicy: 'retain', digest: digest(value.digest) };
+};
+
+export const computeRuntimeStorageClaimDigest = async (valueArg: unknown): Promise<TSha256Digest> => {
+  const { digest: _digest, ...payload } = snapshotRuntimeStorageClaim(valueArg);
+  return `sha256:${await createCanonicalJsonSha256Hex(canonicalizeStrictJson({
+    domain: runtimeStorageClaimContract.digestDomain, payload,
+  }, fail), fail)}`;
+};
+
+export const validateRuntimeStorageClaim = async (valueArg: unknown): Promise<string[]> => {
+  try {
+    const claim = snapshotRuntimeStorageClaim(valueArg);
+    return claim.digest === await computeRuntimeStorageClaimDigest(claim)
+      ? [] : ['runtime storage claim digest does not match'];
+  } catch {
+    return ['runtime storage claim must use its exact canonical schema'];
+  }
+};
+
+/** Content binding only; controller authentication, provider checks and attachment fencing remain owner-owned. */
+export const bindRuntimeStorageClaimToAssignment = async (
+  claimArg: unknown, assignmentArg: unknown, expectedClusterIdArg: unknown,
+): Promise<{ claim: IRuntimeStorageClaim; assignment: IRuntimeAssignment }> => {
+  const claim = snapshotRuntimeStorageClaim(claimArg);
+  const assignment = snapshotRuntimeAssignment(assignmentArg);
+  if ((await validateRuntimeStorageClaim(claim)).length || (await validateRuntimeAssignment(assignment)).length) fail();
+  const expectedClusterId = id(expectedClusterIdArg);
+  const reference = assignment.workload.storage.find((itemArg) => itemArg.id === claim.id);
+  requireValue(reference?.generation === claim.generation && reference.digest === claim.digest
+    && claim.clusterId === expectedClusterId
+    && assignment.controller.kind === 'cloudly'
+    && assignment.controller.id === claim.controller.id
+    && assignment.controller.epoch === claim.controller.epoch
+    && assignment.organizationId === claim.organizationId
+    && assignment.nodeId === claim.nodeId
+    && assignment.runtimeNamespace === claim.runtimeNamespace
+    && assignment.serviceId === claim.serviceId);
+  return { claim, assignment };
+};

package/ts/data/secret.ts

@@ -84,15 +84,27 @@ export type TSecretVersionRetentionReferenceKind =
   | 'applied-manifest'
   | 'previous-accepted-manifest'
   | 'rollback-manifest'
+  | 'runtime-assignment'
   | 'backup'
   | 'retention-window';
 
-export interface ISecretVersionRetentionReference {
-  kind: TSecretVersionRetentionReferenceKind;
+export interface IRuntimeAssignmentSecretVersionRetentionReference {
+  kind: 'runtime-assignment';
+  resourceId: string;
+  expiresAt?: never;
+}
+
+export interface IExpiringSecretVersionRetentionReference {
+  kind: Exclude<TSecretVersionRetentionReferenceKind, 'runtime-assignment'>;
   resourceId: string;
   expiresAt?: number;
 }
 
+/** Retains the existing public name while discriminating indefinite assignment holds. */
+export type ISecretVersionRetentionReference =
+  | IRuntimeAssignmentSecretVersionRetentionReference
+  | IExpiringSecretVersionRetentionReference;
+
 export const secretVersionRetentionReferenceLimits = Object.freeze({
   pageSizeMaximum: 256,
 });
@@ -435,6 +447,7 @@ export const validateSecretVersionRetentionReferences = (
     'applied-manifest',
     'previous-accepted-manifest',
     'rollback-manifest',
+    'runtime-assignment',
     'backup',
     'retention-window',
   ]);
@@ -444,6 +457,7 @@ export const validateSecretVersionRetentionReferences = (
       || !hasOnlyKeys(referenceArg, ['kind', 'resourceId', 'expiresAt'])
       || !kinds.has(referenceArg.kind as TSecretVersionRetentionReferenceKind)
       || !isSecretIdentifier(referenceArg.resourceId)
+      || (referenceArg.kind === 'runtime-assignment' && Object.hasOwn(referenceArg, 'expiresAt'))
       || (referenceArg.expiresAt !== undefined
         && !isNonNegativeSafeInteger(referenceArg.expiresAt))) {
       errors.push(`secret version retention references[${index}] must be canonical`);

package/ts/runtime.assignmentsecret.ts

@@ -501,28 +501,30 @@ export const bindGetRuntimeAssignmentSecretMaterialRequest = async (
 
 /**
  * Verify one complete response without opening a private key. The caller must
- * supply its authenticated current session, current assignment, pinned config,
- * enrolled cluster and active recipient from their respective trusted owners.
+ * supply its authenticated current session, current assignment, pinned config
+ * and active recipient from their respective trusted owners. The controller-issued
+ * session binding supplies the enrolled cluster.
  */
 export const bindGetRuntimeAssignmentSecretMaterialResponse = async (
   valueArg: unknown, requestArg: unknown, assignmentArg: unknown, configArg: unknown,
-  trustedSessionArg: unknown, trustedClusterIdArg: string, activeRecipientArg: unknown,
+  trustedSessionArg: unknown, activeRecipientArg: unknown,
 ): Promise<IGetRuntimeAssignmentSecretMaterialResponse> => {
   try {
     const value = exact(capture(valueArg, runtimeAssignmentSecretContract.maximumMaterialBytes), ['material']);
+    const trustedSession = session(capture(trustedSessionArg));
     const material = exact(value.material, [
       'assignment', 'nodeId', 'secrets', 'recipientKeyId', 'recipientGeneration',
       'authority', 'manifest', 'workloadInit', 'entries',
     ]);
     const request = await bindGetRuntimeAssignmentSecretMaterialRequest(
-      requestArg, assignmentArg, trustedSessionArg, activeRecipientArg,
+      requestArg, assignmentArg, trustedSession, activeRecipientArg,
     );
     const assignment = snapshotRuntimeAssignment(assignmentArg);
     const authority = await bindRuntimeAssignmentSecretAuthority(
-      material.authority, material.manifest, assignment, configArg, trustedClusterIdArg,
+      material.authority, material.manifest, assignment, configArg, trustedSession.clusterId,
     );
     const manifest = material.manifest as IResolvedSecretManifest;
-    requireValue(identifier(trustedClusterIdArg) === manifest.clusterId
+    requireValue(trustedSession.clusterId === manifest.clusterId
       && material.nodeId === assignment.nodeId
       && same(assignmentReference(material.assignment), request.assignment)
       && same(authorityReference(material.secrets), request.secrets)