@serve.zone/interfaces 32.8.0 → 32.9.0

package/ts/runtime.assignmentsecret.ts

@@ -0,0 +1,581 @@
+import * as plugins from './plugins.js';
+import type {
+  IActiveSecretRecipientMetadata, IResolvedSecretManifest, IResolvedSecretManifestReference,
+  IRuntimeAssignment, IRuntimeAssignmentReference, IRuntimeAuthorityReference, IRuntimeConfig,
+  IRuntimeSessionBinding, TImmutableContainerPlatform, TSecretRecipientMetadata, TSha256Digest,
+} from './data/index.js';
+import {
+  bindRuntimeConfigToAssignment, getRuntimeAssignmentReference, isSha256Digest,
+  snapshotRuntimeAssignment, snapshotRuntimeSessionBinding, validateRuntimeAssignment,
+  validateResolvedSecretManifest, validateResolvedSecretManifestReference,
+  validateSecretRecipientMetadata, validateSecretRecipientSet, verifyResolvedSecretManifestDigest,
+  verifySecretEnvelopeContext,
+} from './data/index.js';
+import { secretValueLimits } from './data/secret.js';
+import {
+  validateWorkloadInitActiveApprovalAuthority, validateWorkloadInitApprovalAuthorityReference,
+  type IWorkloadInitActiveApprovalAuthority, type IWorkloadInitApprovalAuthorityReference,
+  type IWorkloadInitApprovedArtifact,
+} from './runtime.workloadinit.js';
+import { canonicalizeStrictJson, createCanonicalJsonSha256Hex } from './private/canonicaljson.js';
+import { isClusterNodeId } from './private/nodeidentifier.js';
+
+/**
+ * Content contracts only. Authentication of the physical peer, current session,
+ * node credential and slot, recipient-generation CAS, accepted manifest/version
+ * retention, challenge consumption and material issuance are Cloudly-owned.
+ */
+export const runtimeAssignmentSecretContract = Object.freeze({
+  descriptorDomain: 'serve.zone/runtime-assignment-secret-authority',
+  maximumRequestBytes: 327_680,
+  maximumMaterialBytes: 192 * 1024 * 1024,
+  error: 'Runtime assignment secret contract rejected.',
+} as const);
+
+const fail = (): never => { throw new Error(runtimeAssignmentSecretContract.error); };
+function requireValue(conditionArg: unknown): asserts conditionArg {
+  if (!conditionArg) fail();
+}
+const exact = (valueArg: unknown, keysArg: readonly string[]): Record<string, unknown> => {
+  requireValue(valueArg !== null && typeof valueArg === 'object' && !Array.isArray(valueArg));
+  const keys = Object.keys(valueArg);
+  requireValue(keys.length === keysArg.length && keysArg.every((keyArg) => keys.includes(keyArg)));
+  return valueArg as Record<string, unknown>;
+};
+const positive = (valueArg: unknown): number => {
+  requireValue(Number.isSafeInteger(valueArg) && (valueArg as number) > 0);
+  return valueArg as number;
+};
+const nonnegative = (valueArg: unknown): number => {
+  requireValue(Number.isSafeInteger(valueArg) && (valueArg as number) >= 0);
+  return valueArg as number;
+};
+const identifier = (valueArg: unknown): string => {
+  requireValue(typeof valueArg === 'string' && /^[A-Za-z0-9][A-Za-z0-9:._-]{0,199}$/.test(valueArg));
+  return valueArg;
+};
+const digest = (valueArg: unknown): TSha256Digest => {
+  requireValue(typeof valueArg === 'string' && isSha256Digest(valueArg));
+  return valueArg;
+};
+const canonical = (valueArg: unknown): string => canonicalizeStrictJson(valueArg, fail);
+const capture = (valueArg: unknown, maximumArg: number = runtimeAssignmentSecretContract.maximumRequestBytes): unknown => {
+  const serialized = canonical(valueArg);
+  requireValue(new TextEncoder().encode(serialized).byteLength <= maximumArg);
+  return JSON.parse(serialized) as unknown;
+};
+const same = (leftArg: unknown, rightArg: unknown): boolean => canonical(leftArg) === canonical(rightArg);
+const snapshot = <T>(callbackArg: () => T): T => {
+  try { return callbackArg(); } catch { return fail(); }
+};
+const session = (valueArg: unknown): IRuntimeSessionBinding =>
+  snapshotRuntimeSessionBinding(valueArg);
+const assignmentReference = (valueArg: unknown): IRuntimeAssignmentReference => {
+  const value = exact(valueArg, ['assignmentId', 'generation', 'digest']);
+  return { assignmentId: identifier(value.assignmentId), generation: positive(value.generation), digest: digest(value.digest) };
+};
+const authorityReference = (valueArg: unknown): IRuntimeAuthorityReference => {
+  const value = exact(valueArg, ['id', 'generation', 'digest']);
+  return { id: identifier(value.id), generation: positive(value.generation), digest: digest(value.digest) };
+};
+const manifestReference = (manifestArg: IResolvedSecretManifest): IResolvedSecretManifestReference => ({
+  manifestId: manifestArg.id, manifestDigest: manifestArg.digest, clusterId: manifestArg.clusterId,
+  imageRolloutId: manifestArg.imageRolloutId, imageRolloutGeneration: manifestArg.imageRolloutGeneration,
+  requestedImageDigest: manifestArg.requestedImageDigest, invocationDigest: manifestArg.invocationDigest,
+  secretRolloutId: manifestArg.secretRolloutId, secretRolloutGeneration: manifestArg.secretRolloutGeneration,
+});
+
+export interface IRuntimeAssignmentSecretLauncher {
+  approval: IWorkloadInitApprovalAuthorityReference;
+  artifact: IWorkloadInitApprovedArtifact;
+}
+
+/**
+ * Value-free descriptor hashed BEFORE the assignment is sealed. Its manifest is
+ * already independently hashed; neither digest contains the assignment digest.
+ */
+export interface IRuntimeAssignmentSecretAuthority extends IRuntimeAuthorityReference {
+  organizationId: string;
+  serviceId: string;
+  platform: TImmutableContainerPlatform;
+  manifest: IResolvedSecretManifestReference;
+  workloadInit: IRuntimeAssignmentSecretLauncher | null;
+}
+
+const launcher = (valueArg: unknown, platformArg: TImmutableContainerPlatform): IRuntimeAssignmentSecretLauncher => {
+  const value = exact(valueArg, ['approval', 'artifact']);
+  requireValue(validateWorkloadInitApprovalAuthorityReference(value.approval).length === 0);
+  const artifact = exact(value.artifact, [
+    'platform', 'workloadInitPlatformManifestDigest', 'workloadInitExecutableDigest',
+  ]);
+  requireValue(artifact.platform === platformArg);
+  digest(artifact.workloadInitPlatformManifestDigest);
+  digest(artifact.workloadInitExecutableDigest);
+  return valueArg as IRuntimeAssignmentSecretLauncher;
+};
+
+export const snapshotRuntimeAssignmentSecretAuthority = (valueArg: unknown): IRuntimeAssignmentSecretAuthority =>
+  snapshot(() => {
+    const value = exact(capture(valueArg), [
+      'id', 'generation', 'digest', 'organizationId', 'serviceId', 'platform', 'manifest', 'workloadInit',
+    ]);
+    const reference = authorityReference({
+      id: value.id, generation: value.generation, digest: value.digest,
+    });
+    requireValue(value.platform === 'linux/amd64' || value.platform === 'linux/arm64');
+    const manifest = value.manifest;
+    requireValue(validateResolvedSecretManifestReference(manifest, (manifest as IResolvedSecretManifestReference)?.clusterId).length === 0);
+    requireValue(reference.id === (manifest as IResolvedSecretManifestReference).manifestId
+      && reference.generation === (manifest as IResolvedSecretManifestReference).secretRolloutGeneration);
+    if (value.workloadInit !== null) launcher(value.workloadInit, value.platform);
+    return value as unknown as IRuntimeAssignmentSecretAuthority;
+  });
+
+export const computeRuntimeAssignmentSecretAuthorityDigest = async (
+  authorityArg: IRuntimeAssignmentSecretAuthority,
+): Promise<TSha256Digest> => {
+  const authority = snapshotRuntimeAssignmentSecretAuthority(authorityArg);
+  const { digest: _digest, ...payload } = authority;
+  return `sha256:${await createCanonicalJsonSha256Hex(canonical({
+    domain: runtimeAssignmentSecretContract.descriptorDomain, payload,
+  }), fail)}`;
+};
+
+export const validateRuntimeAssignmentSecretAuthority = async (valueArg: unknown): Promise<string[]> => {
+  try {
+    const value = snapshotRuntimeAssignmentSecretAuthority(valueArg);
+    return value.digest === await computeRuntimeAssignmentSecretAuthorityDigest(value)
+      ? [] : [runtimeAssignmentSecretContract.error];
+  } catch { return [runtimeAssignmentSecretContract.error]; }
+};
+
+/** Producer creates this before assignment digest computation. */
+export const createRuntimeAssignmentSecretAuthority = async (
+  manifestArg: unknown, platformArg: TImmutableContainerPlatform,
+  workloadInitArg: IRuntimeAssignmentSecretLauncher | null,
+): Promise<IRuntimeAssignmentSecretAuthority> => {
+  try {
+    const manifest = capture(manifestArg) as IResolvedSecretManifest;
+    requireValue(validateResolvedSecretManifest(manifest).length === 0
+      && await verifyResolvedSecretManifestDigest(manifest)
+      && (platformArg === 'linux/amd64' || platformArg === 'linux/arm64')
+      && (manifest.entries.some((entryArg) => entryArg.delivery.type === 'launcher-environment')
+        ? workloadInitArg !== null : workloadInitArg === null));
+    const workloadInit = workloadInitArg === null
+      ? null : launcher(capture(workloadInitArg), platformArg);
+    const authority: IRuntimeAssignmentSecretAuthority = {
+      id: manifest.id, generation: manifest.secretRolloutGeneration,
+      digest: 'sha256:0000000000000000000000000000000000000000000000000000000000000000',
+      organizationId: manifest.organizationId, serviceId: manifest.serviceId,
+      platform: platformArg, manifest: manifestReference(manifest), workloadInit,
+    };
+    authority.digest = await computeRuntimeAssignmentSecretAuthorityDigest(authority);
+    return authority;
+  } catch { return fail(); }
+};
+
+/** Trusted manifest/config are required: the reference alone is no authorization. */
+export const bindRuntimeAssignmentSecretAuthority = async (
+  authorityArg: unknown, manifestArg: unknown, assignmentArg: unknown, configArg: unknown,
+  trustedClusterIdArg: string,
+): Promise<IRuntimeAssignmentSecretAuthority> => {
+  try {
+    const authority = snapshotRuntimeAssignmentSecretAuthority(authorityArg);
+    const assignment = snapshotRuntimeAssignment(assignmentArg);
+    const manifest = capture(manifestArg) as IResolvedSecretManifest;
+    requireValue((await validateRuntimeAssignmentSecretAuthority(authority)).length === 0
+      && (await validateRuntimeAssignment(assignment)).length === 0
+      && validateResolvedSecretManifest(manifest).length === 0
+      && await verifyResolvedSecretManifestDigest(manifest));
+    const { config } = await bindRuntimeConfigToAssignment(configArg, assignment);
+    requireValue(assignment.disposition === 'run' && assignment.generation === 1
+      && assignment.previous === null && assignment.workload.secrets !== null
+      && same(assignment.workload.secrets, {
+        id: authority.id, generation: authority.generation, digest: authority.digest,
+      })
+      && same(authority.manifest, manifestReference(manifest))
+      && authority.organizationId === assignment.organizationId
+      && authority.serviceId === assignment.serviceId
+      && authority.platform === assignment.workload.platform
+      && identifier(trustedClusterIdArg) === manifest.clusterId
+      && manifest.organizationId === assignment.organizationId
+      && manifest.serviceId === assignment.serviceId
+      && manifest.requestedImageDigest === assignment.workload.imageDigest
+      && manifest.invocationDigest === config.image.invocation.digest
+      && (manifest.entries.some((entryArg) => entryArg.delivery.type === 'launcher-environment')
+        ? authority.workloadInit !== null : authority.workloadInit === null));
+    return authority;
+  } catch { return fail(); }
+};
+
+export interface IRuntimeSecretRecipientState {
+  nodeId: string;
+  generation: number;
+  recipients: TSecretRecipientMetadata[];
+}
+
+export interface IGetRuntimeSecretRecipientStateRequest { session: IRuntimeSessionBinding }
+export interface IGetRuntimeSecretRecipientStateResponse { state: IRuntimeSecretRecipientState }
+export interface IBeginRuntimeSecretRecipientEnrollmentRequest {
+  session: IRuntimeSessionBinding;
+  proposedRecipientKeyId: string;
+  proposedPublicKey: string;
+  expectedGeneration: number;
+}
+export interface IRuntimeSecretRecipientEnrollmentChallenge {
+  session: IRuntimeSessionBinding;
+  enrollmentId: string;
+  recipientKeyId: string;
+  publicKey: string;
+  generation: number;
+  expiresAt: number;
+  envelope: plugins.smartcrypto.IX25519EnvelopeV1;
+}
+export interface IBeginRuntimeSecretRecipientEnrollmentResponse {
+  challenge: IRuntimeSecretRecipientEnrollmentChallenge;
+}
+export interface ICompleteRuntimeSecretRecipientEnrollmentRequest {
+  session: IRuntimeSessionBinding;
+  enrollmentId: string;
+  expectedGeneration: number;
+  /** Canonical unpadded base64url encoding of the opened 32-byte challenge. */
+  response: string;
+}
+export interface ICompleteRuntimeSecretRecipientEnrollmentResponse {
+  recipient: IActiveSecretRecipientMetadata;
+}
+
+const raw32ByteBase64Url = /^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$/;
+export const snapshotRuntimeSecretRecipientState = (valueArg: unknown): IRuntimeSecretRecipientState =>
+  snapshot(() => {
+    const state = exact(capture(valueArg), ['nodeId', 'generation', 'recipients']);
+    requireValue(isClusterNodeId(state.nodeId));
+    const generation = nonnegative(state.generation);
+    requireValue(Array.isArray(state.recipients));
+    requireValue(generation === 0
+      ? state.recipients.length === 0
+      : validateSecretRecipientSet(state.recipients).length === 0
+        && state.recipients.some((recipientArg: TSecretRecipientMetadata) =>
+          recipientArg.lifecycleState === 'active' && recipientArg.generation === generation));
+    return state as unknown as IRuntimeSecretRecipientState;
+  });
+
+export const bindGetRuntimeSecretRecipientStateRequest = (
+  valueArg: unknown, trustedSessionArg: unknown,
+): IGetRuntimeSecretRecipientStateRequest => snapshot(() => {
+  const value = exact(capture(valueArg), ['session']);
+  const trusted = session(trustedSessionArg);
+  requireValue(same(session(value.session), trusted));
+  return { session: trusted };
+});
+
+export const bindGetRuntimeSecretRecipientStateResponse = (
+  valueArg: unknown, requestArg: unknown,
+): IGetRuntimeSecretRecipientStateResponse => snapshot(() => {
+  const request = exact(capture(requestArg), ['session']);
+  const value = exact(capture(valueArg), ['state']);
+  const state = snapshotRuntimeSecretRecipientState(value.state);
+  requireValue(state.nodeId === session(request.session).nodeId);
+  return { state };
+});
+
+export const bindBeginRuntimeSecretRecipientEnrollmentRequest = (
+  valueArg: unknown, trustedSessionArg: unknown, currentStateArg: unknown,
+): IBeginRuntimeSecretRecipientEnrollmentRequest => snapshot(() => {
+  const value = exact(capture(valueArg), [
+    'session', 'proposedRecipientKeyId', 'proposedPublicKey', 'expectedGeneration',
+  ]);
+  const trusted = session(trustedSessionArg);
+  const state = snapshotRuntimeSecretRecipientState(currentStateArg);
+  requireValue(same(session(value.session), trusted) && state.nodeId === trusted.nodeId
+    && nonnegative(value.expectedGeneration) === state.generation
+    && raw32ByteBase64Url.test(value.proposedPublicKey as string));
+  return {
+    session: trusted, proposedRecipientKeyId: identifier(value.proposedRecipientKeyId),
+    proposedPublicKey: value.proposedPublicKey as string, expectedGeneration: state.generation,
+  };
+});
+
+/** Use the existing SmartCrypto X25519 envelope and one-time challenge proof. */
+export const createRuntimeSecretRecipientEnrollmentChallengeContext = (
+  challengeArg: Omit<IRuntimeSecretRecipientEnrollmentChallenge, 'envelope'>,
+): Uint8Array => new TextEncoder().encode(canonical({
+  purpose: 'serve.zone/runtime-secret-recipient-enrollment-challenge',
+  session: challengeArg.session,
+  enrollmentId: challengeArg.enrollmentId,
+  recipientKeyId: challengeArg.recipientKeyId,
+  publicKey: challengeArg.publicKey,
+  generation: challengeArg.generation,
+  expiresAt: challengeArg.expiresAt,
+}));
+
+export const bindBeginRuntimeSecretRecipientEnrollmentResponse = async (
+  valueArg: unknown, requestArg: unknown, trustedSessionArg: unknown, nowArg: number,
+): Promise<IBeginRuntimeSecretRecipientEnrollmentResponse> => {
+  try {
+    const value = exact(capture(valueArg), ['challenge']);
+    const challenge = exact(value.challenge, [
+      'session', 'enrollmentId', 'recipientKeyId', 'publicKey', 'generation', 'expiresAt', 'envelope',
+    ]);
+    const request = exact(capture(requestArg), [
+      'session', 'proposedRecipientKeyId', 'proposedPublicKey', 'expectedGeneration',
+    ]);
+    const trusted = session(trustedSessionArg);
+    requireValue(same(session(request.session), trusted) && same(session(challenge.session), trusted)
+      && identifier(challenge.enrollmentId).length > 0
+      && challenge.recipientKeyId === identifier(request.proposedRecipientKeyId)
+      && challenge.publicKey === request.proposedPublicKey
+      && typeof challenge.publicKey === 'string' && raw32ByteBase64Url.test(challenge.publicKey)
+      && positive(challenge.generation) === nonnegative(request.expectedGeneration) + 1
+      && positive(challenge.expiresAt) > positive(nowArg));
+    const envelope = plugins.smartcrypto.parseX25519Envelope(challenge.envelope);
+    requireValue(envelope.recipientKeyId === challenge.recipientKeyId
+      && raw32ByteBase64Url.test(envelope.ciphertext));
+    const captured = { ...challenge, session: trusted, envelope } as IRuntimeSecretRecipientEnrollmentChallenge;
+    requireValue(await verifySecretEnvelopeContext(
+      envelope, createRuntimeSecretRecipientEnrollmentChallengeContext(captured),
+    ));
+    return { challenge: captured };
+  } catch { return fail(); }
+};
+
+export const bindCompleteRuntimeSecretRecipientEnrollmentRequest = async (
+  valueArg: unknown, challengeArg: unknown, trustedSessionArg: unknown, nowArg: number,
+): Promise<ICompleteRuntimeSecretRecipientEnrollmentRequest> => {
+  try {
+    const value = exact(capture(valueArg), ['session', 'enrollmentId', 'expectedGeneration', 'response']);
+    const challenge = exact(capture(challengeArg), [
+      'session', 'enrollmentId', 'recipientKeyId', 'publicKey', 'generation', 'expiresAt', 'envelope',
+    ]);
+    const trusted = session(trustedSessionArg);
+    requireValue(same(session(value.session), trusted) && same(session(challenge.session), trusted)
+      && identifier(value.enrollmentId) === identifier(challenge.enrollmentId)
+      && identifier(challenge.recipientKeyId).length > 0
+      && nonnegative(value.expectedGeneration) + 1 === positive(challenge.generation)
+      && positive(challenge.expiresAt) > positive(nowArg)
+      && typeof value.response === 'string' && raw32ByteBase64Url.test(value.response));
+    const envelope = plugins.smartcrypto.parseX25519Envelope(challenge.envelope);
+    requireValue(envelope.recipientKeyId === challenge.recipientKeyId
+      && typeof challenge.publicKey === 'string' && raw32ByteBase64Url.test(challenge.publicKey)
+      && raw32ByteBase64Url.test(envelope.ciphertext)
+      && await verifySecretEnvelopeContext(
+        envelope,
+        createRuntimeSecretRecipientEnrollmentChallengeContext(
+          challenge as unknown as IRuntimeSecretRecipientEnrollmentChallenge),
+      ));
+    return value as unknown as ICompleteRuntimeSecretRecipientEnrollmentRequest;
+  } catch { return fail(); }
+};
+
+export const bindCompleteRuntimeSecretRecipientEnrollmentResponse = (
+  valueArg: unknown, challengeArg: unknown,
+): ICompleteRuntimeSecretRecipientEnrollmentResponse => snapshot(() => {
+  const value = exact(capture(valueArg), ['recipient']);
+  const challenge = exact(capture(challengeArg), [
+    'session', 'enrollmentId', 'recipientKeyId', 'publicKey', 'generation', 'expiresAt', 'envelope',
+  ]);
+  requireValue(validateSecretRecipientMetadata(value.recipient).length === 0);
+  const recipient = value.recipient as IActiveSecretRecipientMetadata;
+  requireValue(recipient.lifecycleState === 'active' && recipient.recipientKeyId === challenge.recipientKeyId
+    && recipient.publicKey === challenge.publicKey && recipient.generation === challenge.generation);
+  return { recipient };
+});
+
+export interface IGetRuntimeAssignmentSecretMaterialRequest {
+  session: IRuntimeSessionBinding;
+  /** Exact current generation-one run assignment, never a historical receipt. */
+  assignment: IRuntimeAssignmentReference;
+  secrets: IRuntimeAuthorityReference;
+  expectedRecipientKeyId: string;
+  expectedRecipientGeneration: number;
+}
+
+export interface ISealedRuntimeAssignmentSecretMaterialEntry {
+  secretVersionId: string;
+  envelope: plugins.smartcrypto.IX25519EnvelopeV1;
+}
+
+/** Sensitive ephemeral sealed material; exclude the complete body from hooks and logs. */
+export interface ISealedRuntimeAssignmentSecretMaterial {
+  assignment: IRuntimeAssignmentReference;
+  nodeId: string;
+  secrets: IRuntimeAuthorityReference;
+  recipientKeyId: string;
+  recipientGeneration: number;
+  authority: IRuntimeAssignmentSecretAuthority;
+  manifest: IResolvedSecretManifest;
+  /** Full approved immutable launcher authority, exactly when an entry needs it. */
+  workloadInit: IWorkloadInitActiveApprovalAuthority | null;
+  /** Sorted exact one-to-one coverage of the pinned manifest's versions. */
+  entries: ISealedRuntimeAssignmentSecretMaterialEntry[];
+}
+
+export interface IGetRuntimeAssignmentSecretMaterialResponse {
+  material: ISealedRuntimeAssignmentSecretMaterial;
+}
+
+/**
+ * The descriptor was hashed before assignment seal. This context binds each
+ * envelope to the final run digest, node and recipient generation afterwards.
+ * Use SmartCrypto sealX25519Envelope with these exact bytes.
+ */
+export const createRuntimeAssignmentSecretMaterialEnvelopeContext = (contextArg: {
+  recipientKeyId: string;
+  recipientGeneration: number;
+  organizationId: string;
+  clusterId: string;
+  serviceId: string;
+  nodeId: string;
+  assignment: IRuntimeAssignmentReference;
+  authorityDigest: TSha256Digest;
+  manifestId: string;
+  manifestDigest: TSha256Digest;
+  imageRolloutId: string;
+  imageRolloutGeneration: number;
+  requestedImageDigest: TSha256Digest;
+  invocationDigest: TSha256Digest;
+  secretRolloutId: string;
+  secretRolloutGeneration: number;
+  secretId: string;
+  secretVersionId: string;
+}): Uint8Array => new TextEncoder().encode(canonical({
+  purpose: 'serve.zone/runtime-assignment-secret-material',
+  recipientKeyId: contextArg.recipientKeyId,
+  recipientGeneration: contextArg.recipientGeneration,
+  organizationId: contextArg.organizationId,
+  clusterId: contextArg.clusterId,
+  serviceId: contextArg.serviceId,
+  nodeId: contextArg.nodeId,
+  assignment: contextArg.assignment,
+  authorityDigest: contextArg.authorityDigest,
+  manifestId: contextArg.manifestId,
+  manifestDigest: contextArg.manifestDigest,
+  imageRolloutId: contextArg.imageRolloutId,
+  imageRolloutGeneration: contextArg.imageRolloutGeneration,
+  requestedImageDigest: contextArg.requestedImageDigest,
+  invocationDigest: contextArg.invocationDigest,
+  secretRolloutId: contextArg.secretRolloutId,
+  secretRolloutGeneration: contextArg.secretRolloutGeneration,
+  secretId: contextArg.secretId,
+  secretVersionId: contextArg.secretVersionId,
+}));
+
+/**
+ * trustedSessionArg MUST be the current authenticated connection's server-owned
+ * binding; assignmentArg MUST be its current durable run. Content checks here
+ * do not prove either source, recipient possession, version issuance policy or
+ * the native workload's mount ownership.
+ */
+export const bindGetRuntimeAssignmentSecretMaterialRequest = async (
+  valueArg: unknown, assignmentArg: unknown, trustedSessionArg: unknown,
+  activeRecipientArg: unknown,
+): Promise<IGetRuntimeAssignmentSecretMaterialRequest> => {
+  try {
+    const value = exact(capture(valueArg), [
+      'session', 'assignment', 'secrets', 'expectedRecipientKeyId', 'expectedRecipientGeneration',
+    ]);
+    const assignment = snapshotRuntimeAssignment(assignmentArg);
+    const trusted = session(trustedSessionArg);
+    const recipient = activeRecipientArg as IActiveSecretRecipientMetadata;
+    requireValue((await validateRuntimeAssignment(assignment)).length === 0
+      && validateSecretRecipientMetadata(recipient).length === 0
+      && recipient.lifecycleState === 'active'
+      && same(session(value.session), trusted)
+      && trusted.nodeId === assignment.nodeId
+      && trusted.runtimeNamespace === assignment.runtimeNamespace
+      && same(trusted.controller, assignment.controller)
+      && assignment.generation === 1 && assignment.previous === null
+      && assignment.disposition === 'run' && assignment.workload.secrets !== null
+      && same(assignmentReference(value.assignment), getRuntimeAssignmentReference(assignment))
+      && same(authorityReference(value.secrets), assignment.workload.secrets)
+      && identifier(value.expectedRecipientKeyId) === recipient.recipientKeyId
+      && positive(value.expectedRecipientGeneration) === recipient.generation);
+    return {
+      session: trusted, assignment: getRuntimeAssignmentReference(assignment),
+      secrets: assignment.workload.secrets,
+      expectedRecipientKeyId: recipient.recipientKeyId,
+      expectedRecipientGeneration: recipient.generation,
+    };
+  } catch { return fail(); }
+};
+
+/**
+ * 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.
+ */
+export const bindGetRuntimeAssignmentSecretMaterialResponse = async (
+  valueArg: unknown, requestArg: unknown, assignmentArg: unknown, configArg: unknown,
+  trustedSessionArg: unknown, trustedClusterIdArg: string, activeRecipientArg: unknown,
+): Promise<IGetRuntimeAssignmentSecretMaterialResponse> => {
+  try {
+    const value = exact(capture(valueArg, runtimeAssignmentSecretContract.maximumMaterialBytes), ['material']);
+    const material = exact(value.material, [
+      'assignment', 'nodeId', 'secrets', 'recipientKeyId', 'recipientGeneration',
+      'authority', 'manifest', 'workloadInit', 'entries',
+    ]);
+    const request = await bindGetRuntimeAssignmentSecretMaterialRequest(
+      requestArg, assignmentArg, trustedSessionArg, activeRecipientArg,
+    );
+    const assignment = snapshotRuntimeAssignment(assignmentArg);
+    const authority = await bindRuntimeAssignmentSecretAuthority(
+      material.authority, material.manifest, assignment, configArg, trustedClusterIdArg,
+    );
+    const manifest = material.manifest as IResolvedSecretManifest;
+    requireValue(identifier(trustedClusterIdArg) === manifest.clusterId
+      && material.nodeId === assignment.nodeId
+      && same(assignmentReference(material.assignment), request.assignment)
+      && same(authorityReference(material.secrets), request.secrets)
+      && material.recipientKeyId === request.expectedRecipientKeyId
+      && material.recipientGeneration === request.expectedRecipientGeneration
+      && Array.isArray(material.entries)
+      && material.entries.length === manifest.entries.length);
+    if (authority.workloadInit === null) {
+      requireValue(material.workloadInit === null);
+    } else {
+      requireValue((await validateWorkloadInitActiveApprovalAuthority(material.workloadInit)).length === 0);
+      const approval = material.workloadInit as IWorkloadInitActiveApprovalAuthority;
+      requireValue(same({
+        authorityGeneration: approval.authorityGeneration, approvalDigest: approval.approvalDigest,
+      }, authority.workloadInit.approval)
+        && approval.approval.artifacts.some((artifactArg) =>
+          same(artifactArg, authority.workloadInit!.artifact)));
+    }
+    const expectedIds = manifest.entries.map((entryArg) => entryArg.secretVersionId).sort();
+    const actualIds = material.entries.map((entryArg: unknown) =>
+      exact(entryArg, ['secretVersionId', 'envelope']).secretVersionId);
+    requireValue(actualIds.every((idArg: unknown) => typeof idArg === 'string')
+      && same(actualIds, expectedIds));
+    const byVersion = new Map(manifest.entries.map((entryArg) => [entryArg.secretVersionId, entryArg]));
+    for (const entryValue of material.entries) {
+      const entry = exact(entryValue, ['secretVersionId', 'envelope']);
+      const manifestEntry = byVersion.get(entry.secretVersionId as string);
+      requireValue(manifestEntry);
+      const envelope = plugins.smartcrypto.parseX25519Envelope(entry.envelope);
+      requireValue(envelope.recipientKeyId === request.expectedRecipientKeyId
+        && envelope.ciphertext.length <= Math.ceil(secretValueLimits.maximumBytes * 4 / 3));
+      const context = createRuntimeAssignmentSecretMaterialEnvelopeContext({
+        recipientKeyId: request.expectedRecipientKeyId,
+        recipientGeneration: request.expectedRecipientGeneration,
+        organizationId: manifest.organizationId,
+        clusterId: manifest.clusterId,
+        serviceId: manifest.serviceId,
+        nodeId: assignment.nodeId,
+        assignment: request.assignment,
+        authorityDigest: authority.digest,
+        manifestId: manifest.id,
+        manifestDigest: manifest.digest,
+        imageRolloutId: manifest.imageRolloutId,
+        imageRolloutGeneration: manifest.imageRolloutGeneration,
+        requestedImageDigest: manifest.requestedImageDigest,
+        invocationDigest: manifest.invocationDigest,
+        secretRolloutId: manifest.secretRolloutId,
+        secretRolloutGeneration: manifest.secretRolloutGeneration,
+        secretId: manifestEntry.secretId,
+        secretVersionId: manifestEntry.secretVersionId,
+      });
+      requireValue(await verifySecretEnvelopeContext(envelope, context));
+    }
+    return { material: material as unknown as ISealedRuntimeAssignmentSecretMaterial };
+  } catch { return fail(); }
+};

package/ts/runtime.ts

@@ -45,6 +45,7 @@ export * from './runtime.networkprojection.js';
 export * from './runtime.corestore.js';
 export * from './runtime.corestore.databaseexportpackage.js';
 export * from './runtime.corestore.relay.js';
+export * from './runtime.assignmentsecret.js';
 
 export interface ISealedResolvedSecretMaterialEntry {
   secretVersionId: string;