import type { TSha256Digest, TImmutableContainerPlatform } from './data/immutableimage.js'; import { isSha256Digest } from './data/immutableimage.js'; export const workloadInitReleaseContract = Object.freeze({ packageName: '@serve.zone/workloadinit', sourceRepository: 'https://code.foss.global/serve.zone/workloadinit.git', imageRegistry: 'code.foss.global', imageRepository: 'serve.zone/workloadinit', imageIndexMediaType: 'application/vnd.oci.image.index.v1+json', statementType: 'https://in-toto.io/Statement/v1', predicateType: 'https://slsa.dev/provenance/v1', buildType: 'https://serve.zone/buildtypes/workloadinit-gitzone-tsdocker/v1', builderId: 'https://serve.zone/builders/workloadinit-manual-release/v1', signatureFormat: 'cosign-dsse-bundle-v0.3', signatureAlgorithm: 'ecdsa-p256-sha256', } as const); export interface IWorkloadInitBuildToolVersionsV1 { dockerBuildx: string; gitzone: string; tsdocker: string; tsrust: string; } export interface IWorkloadInitReleaseIdentityV1 { packageName: typeof workloadInitReleaseContract.packageName; version: string; sourceRepository: typeof workloadInitReleaseContract.sourceRepository; sourceRevision: string; sourceRef: string; sourceDirty: false; imageRegistry: typeof workloadInitReleaseContract.imageRegistry; imageRepository: typeof workloadInitReleaseContract.imageRepository; imageTag: string; } export interface IWorkloadInitReleaseAttestationStatementV1 { _type: typeof workloadInitReleaseContract.statementType; subject: [{ name: string; digest: { sha256: string; }; }]; predicateType: typeof workloadInitReleaseContract.predicateType; predicate: { buildDefinition: { buildType: typeof workloadInitReleaseContract.buildType; externalParameters: { artifact: { mediaType: typeof workloadInitReleaseContract.imageIndexMediaType; platforms: ['linux/amd64', 'linux/arm64']; repository: string; tag: string; }; source: { repository: typeof workloadInitReleaseContract.sourceRepository; tag: string; dirty: false; }; }; resolvedDependencies: [{ uri: string; digest: { gitCommit: string; }; }]; }; runDetails: { builder: { id: typeof workloadInitReleaseContract.builderId; version: IWorkloadInitBuildToolVersionsV1; }; }; }; } /** * Cloudly-created summary of a private DSSE verification. Shape and digest * validation do not independently prove the signature or its trust policy. */ export interface IWorkloadInitCloudlyVerificationSummaryV1 { signatureFormat: typeof workloadInitReleaseContract.signatureFormat; signatureAlgorithm: typeof workloadInitReleaseContract.signatureAlgorithm; signerKeyId: TSha256Digest; detachedBundleDigest: TSha256Digest; statementDigest: TSha256Digest; subjectImageIndexDigest: TSha256Digest; builderId: typeof workloadInitReleaseContract.builderId; policyGeneration: number; policyDigest: TSha256Digest; verifiedAt: number; } export interface IWorkloadInitApprovedArtifactV1 { platform: TImmutableContainerPlatform; workloadInitPlatformManifestDigest: TSha256Digest; workloadInitExecutableDigest: TSha256Digest; } export interface IWorkloadInitReleaseApprovalV1 { schemaVersion: 1; release: IWorkloadInitReleaseIdentityV1; imageIndexMediaType: typeof workloadInitReleaseContract.imageIndexMediaType; workloadInitImageIndexDigest: TSha256Digest; artifacts: [IWorkloadInitApprovedArtifactV1, IWorkloadInitApprovedArtifactV1]; verificationSummary: IWorkloadInitCloudlyVerificationSummaryV1; approvedAt: number; approvalDigest: TSha256Digest; } export interface IWorkloadInitApprovalAuthorityReferenceV1 { authorityVersion: 1; authorityGeneration: number; approvalDigest: TSha256Digest; } export interface IWorkloadInitActiveApprovalAuthorityV1 extends IWorkloadInitApprovalAuthorityReferenceV1 { approval: IWorkloadInitReleaseApprovalV1; } const semanticVersionRegex = /^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/; const gitRevisionRegex = /^[a-f0-9]{40}$/; const bareSha256Regex = /^[a-f0-9]{64}$/; const toolVersionRegex = /^[A-Za-z0-9][A-Za-z0-9.+_-]{0,63}$/; const isRecord = (valueArg: unknown): valueArg is Record => ( Boolean(valueArg) && typeof valueArg === 'object' && !Array.isArray(valueArg) ); const hasExactKeys = ( valueArg: Record, keysArg: string[], ): boolean => JSON.stringify(Object.keys(valueArg).sort()) === JSON.stringify([...keysArg].sort()); const isPositiveSafeInteger = (valueArg: unknown): valueArg is number => ( Number.isSafeInteger(valueArg) && (valueArg as number) > 0 ); const computeSha256 = async (inputArg: Uint8Array): Promise => { const digest = new Uint8Array(await globalThis.crypto.subtle.digest( 'SHA-256', new Uint8Array(inputArg), )); return `sha256:${[...digest] .map((byteArg) => byteArg.toString(16).padStart(2, '0')) .join('')}` as TSha256Digest; }; export const validateWorkloadInitReleaseIdentity = ( releaseArg: unknown, ): string[] => { if (!isRecord(releaseArg) || !hasExactKeys(releaseArg, [ 'packageName', 'version', 'sourceRepository', 'sourceRevision', 'sourceRef', 'sourceDirty', 'imageRegistry', 'imageRepository', 'imageTag', ])) { return ['WorkloadInit release identity must use its exact schema']; } const errors: string[] = []; if (releaseArg.packageName !== workloadInitReleaseContract.packageName || releaseArg.sourceRepository !== workloadInitReleaseContract.sourceRepository || releaseArg.imageRegistry !== workloadInitReleaseContract.imageRegistry || releaseArg.imageRepository !== workloadInitReleaseContract.imageRepository) { errors.push('WorkloadInit release identity must use the canonical package and repositories'); } if (typeof releaseArg.version !== 'string' || !semanticVersionRegex.test(releaseArg.version)) { errors.push('WorkloadInit release version must be canonical stable semver'); } else if (releaseArg.sourceRef !== `refs/tags/v${releaseArg.version}` || releaseArg.imageTag !== `v${releaseArg.version}`) { errors.push('WorkloadInit release source ref and image tag must match its version'); } if (typeof releaseArg.sourceRevision !== 'string' || !gitRevisionRegex.test(releaseArg.sourceRevision) || releaseArg.sourceDirty !== false) { errors.push('WorkloadInit release source must be an exact clean Git revision'); } return errors; }; const canonicalToolVersions = ( versionsArg: IWorkloadInitBuildToolVersionsV1, ): IWorkloadInitBuildToolVersionsV1 => ({ dockerBuildx: versionsArg.dockerBuildx, gitzone: versionsArg.gitzone, tsdocker: versionsArg.tsdocker, tsrust: versionsArg.tsrust, }); export const createWorkloadInitReleaseAttestationStatement = (inputArg: { release: IWorkloadInitReleaseIdentityV1; workloadInitImageIndexDigest: TSha256Digest; toolVersions: IWorkloadInitBuildToolVersionsV1; }): IWorkloadInitReleaseAttestationStatementV1 => ({ _type: workloadInitReleaseContract.statementType, subject: [{ name: `${inputArg.release.imageRegistry}/${inputArg.release.imageRepository}:${ inputArg.release.imageTag }`, digest: { sha256: inputArg.workloadInitImageIndexDigest.slice('sha256:'.length), }, }], predicateType: workloadInitReleaseContract.predicateType, predicate: { buildDefinition: { buildType: workloadInitReleaseContract.buildType, externalParameters: { artifact: { mediaType: workloadInitReleaseContract.imageIndexMediaType, platforms: ['linux/amd64', 'linux/arm64'], repository: `${inputArg.release.imageRegistry}/${inputArg.release.imageRepository}`, tag: inputArg.release.imageTag, }, source: { repository: inputArg.release.sourceRepository, tag: inputArg.release.sourceRef, dirty: inputArg.release.sourceDirty, }, }, resolvedDependencies: [{ uri: `git+${inputArg.release.sourceRepository}@${inputArg.release.sourceRef}`, digest: { gitCommit: inputArg.release.sourceRevision, }, }], }, runDetails: { builder: { id: workloadInitReleaseContract.builderId, version: canonicalToolVersions(inputArg.toolVersions), }, }, }, }); export const createWorkloadInitReleaseAttestationPayload = ( statementArg: IWorkloadInitReleaseAttestationStatementV1, ): Uint8Array => new TextEncoder().encode(JSON.stringify(statementArg)); export const computeWorkloadInitReleaseAttestationStatementDigest = async ( statementArg: IWorkloadInitReleaseAttestationStatementV1, ): Promise => computeSha256( createWorkloadInitReleaseAttestationPayload(statementArg), ); export const validateWorkloadInitReleaseAttestationStatement = ( statementArg: unknown, ): string[] => { try { if (!isRecord(statementArg) || !hasExactKeys(statementArg, ['_type', 'subject', 'predicateType', 'predicate'])) { return ['WorkloadInit release attestation statement must use its exact schema']; } const errors: string[] = []; if (statementArg._type !== workloadInitReleaseContract.statementType || statementArg.predicateType !== workloadInitReleaseContract.predicateType) { errors.push('WorkloadInit release attestation types must be canonical'); } if (!Array.isArray(statementArg.subject) || statementArg.subject.length !== 1 || !isRecord(statementArg.subject[0]) || !hasExactKeys(statementArg.subject[0], ['name', 'digest']) || !isRecord(statementArg.subject[0].digest) || !hasExactKeys(statementArg.subject[0].digest, ['sha256']) || typeof statementArg.subject[0].digest.sha256 !== 'string' || !bareSha256Regex.test(statementArg.subject[0].digest.sha256)) { errors.push('WorkloadInit release attestation must have one canonical root-index subject'); } if (!isRecord(statementArg.predicate) || !hasExactKeys(statementArg.predicate, ['buildDefinition', 'runDetails'])) { return [...errors, 'WorkloadInit release attestation predicate must use its exact schema']; } const buildDefinition = statementArg.predicate.buildDefinition; const runDetails = statementArg.predicate.runDetails; if (!isRecord(buildDefinition) || !hasExactKeys(buildDefinition, [ 'buildType', 'externalParameters', 'resolvedDependencies', ]) || buildDefinition.buildType !== workloadInitReleaseContract.buildType || !isRecord(buildDefinition.externalParameters) || !hasExactKeys(buildDefinition.externalParameters, ['artifact', 'source']) || !Array.isArray(buildDefinition.resolvedDependencies) || buildDefinition.resolvedDependencies.length !== 1 || !isRecord(runDetails) || !hasExactKeys(runDetails, ['builder']) || !isRecord(runDetails.builder) || !hasExactKeys(runDetails.builder, ['id', 'version']) || runDetails.builder.id !== workloadInitReleaseContract.builderId) { return [...errors, 'WorkloadInit release attestation build definition must be canonical']; } const artifact = buildDefinition.externalParameters.artifact; const source = buildDefinition.externalParameters.source; const dependency = buildDefinition.resolvedDependencies[0]; const toolVersions = runDetails.builder.version; if (!isRecord(artifact) || !hasExactKeys(artifact, ['mediaType', 'platforms', 'repository', 'tag']) || artifact.mediaType !== workloadInitReleaseContract.imageIndexMediaType || JSON.stringify(artifact.platforms) !== JSON.stringify(['linux/amd64', 'linux/arm64']) || artifact.repository !== `${workloadInitReleaseContract.imageRegistry}/${ workloadInitReleaseContract.imageRepository }` || typeof artifact.tag !== 'string' || !/^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$/.test(artifact.tag)) { errors.push('WorkloadInit release attestation artifact must be canonical and version-tagged'); } if (!isRecord(source) || !hasExactKeys(source, ['repository', 'tag', 'dirty']) || source.repository !== workloadInitReleaseContract.sourceRepository || source.dirty !== false || typeof source.tag !== 'string' || source.tag !== `refs/tags/${artifact && isRecord(artifact) ? artifact.tag : ''}`) { errors.push('WorkloadInit release attestation source must match its clean version tag'); } if (!isRecord(dependency) || !hasExactKeys(dependency, ['uri', 'digest']) || !isRecord(dependency.digest) || !hasExactKeys(dependency.digest, ['gitCommit']) || typeof dependency.digest.gitCommit !== 'string' || !gitRevisionRegex.test(dependency.digest.gitCommit) || dependency.uri !== `git+${workloadInitReleaseContract.sourceRepository}@${source && isRecord(source) ? source.tag : ''}`) { errors.push('WorkloadInit release attestation source dependency must be canonical'); } if (!isRecord(toolVersions) || !hasExactKeys(toolVersions, ['dockerBuildx', 'gitzone', 'tsdocker', 'tsrust']) || Object.values(toolVersions).some((valueArg) => ( typeof valueArg !== 'string' || !toolVersionRegex.test(valueArg) ))) { errors.push('WorkloadInit release attestation tool versions must be canonical'); } if (Array.isArray(statementArg.subject) && isRecord(statementArg.subject[0]) && isRecord(artifact) && statementArg.subject[0].name !== `${artifact.repository as string}:${artifact.tag as string}`) { errors.push('WorkloadInit release attestation subject name must match the versioned image'); } return errors; } catch { return ['WorkloadInit release attestation statement must be safely inspectable']; } }; export const validateWorkloadInitCloudlyVerificationSummary = ( summaryArg: unknown, ): string[] => { if (!isRecord(summaryArg) || !hasExactKeys(summaryArg, [ 'signatureFormat', 'signatureAlgorithm', 'signerKeyId', 'detachedBundleDigest', 'statementDigest', 'subjectImageIndexDigest', 'builderId', 'policyGeneration', 'policyDigest', 'verifiedAt', ])) { return ['WorkloadInit Cloudly verification summary must use its exact schema']; } const errors: string[] = []; if (summaryArg.signatureFormat !== workloadInitReleaseContract.signatureFormat || summaryArg.signatureAlgorithm !== workloadInitReleaseContract.signatureAlgorithm || summaryArg.builderId !== workloadInitReleaseContract.builderId) { errors.push('WorkloadInit Cloudly verification summary policy identifiers must be canonical'); } for (const field of [ 'signerKeyId', 'detachedBundleDigest', 'statementDigest', 'subjectImageIndexDigest', 'policyDigest', ] as const) { if (typeof summaryArg[field] !== 'string' || !isSha256Digest(summaryArg[field])) { errors.push(`WorkloadInit Cloudly verification summary ${field} must be canonical`); } } if (!isPositiveSafeInteger(summaryArg.policyGeneration) || !isPositiveSafeInteger(summaryArg.verifiedAt)) { errors.push('WorkloadInit Cloudly verification summary generation and time must be positive'); } return errors; }; const canonicalReleaseIdentity = ( releaseArg: IWorkloadInitReleaseIdentityV1, ): IWorkloadInitReleaseIdentityV1 => ({ packageName: releaseArg.packageName, version: releaseArg.version, sourceRepository: releaseArg.sourceRepository, sourceRevision: releaseArg.sourceRevision, sourceRef: releaseArg.sourceRef, sourceDirty: releaseArg.sourceDirty, imageRegistry: releaseArg.imageRegistry, imageRepository: releaseArg.imageRepository, imageTag: releaseArg.imageTag, }); const canonicalApprovedArtifact = ( artifactArg: IWorkloadInitApprovedArtifactV1, ): IWorkloadInitApprovedArtifactV1 => ({ platform: artifactArg.platform, workloadInitPlatformManifestDigest: artifactArg.workloadInitPlatformManifestDigest, workloadInitExecutableDigest: artifactArg.workloadInitExecutableDigest, }); const canonicalVerificationSummary = ( summaryArg: IWorkloadInitCloudlyVerificationSummaryV1, ): IWorkloadInitCloudlyVerificationSummaryV1 => ({ signatureFormat: summaryArg.signatureFormat, signatureAlgorithm: summaryArg.signatureAlgorithm, signerKeyId: summaryArg.signerKeyId, detachedBundleDigest: summaryArg.detachedBundleDigest, statementDigest: summaryArg.statementDigest, subjectImageIndexDigest: summaryArg.subjectImageIndexDigest, builderId: summaryArg.builderId, policyGeneration: summaryArg.policyGeneration, policyDigest: summaryArg.policyDigest, verifiedAt: summaryArg.verifiedAt, }); export const createWorkloadInitReleaseApprovalDigestInput = ( approvalArg: IWorkloadInitReleaseApprovalV1, ): string => JSON.stringify({ schemaVersion: approvalArg.schemaVersion, purpose: 'serve.zone/workloadinit-release-approval', release: canonicalReleaseIdentity(approvalArg.release), imageIndexMediaType: approvalArg.imageIndexMediaType, workloadInitImageIndexDigest: approvalArg.workloadInitImageIndexDigest, artifacts: approvalArg.artifacts.map(canonicalApprovedArtifact), verificationSummary: canonicalVerificationSummary(approvalArg.verificationSummary), approvedAt: approvalArg.approvedAt, }); export const computeWorkloadInitReleaseApprovalDigest = async ( approvalArg: IWorkloadInitReleaseApprovalV1, ): Promise => computeSha256( new TextEncoder().encode(createWorkloadInitReleaseApprovalDigestInput(approvalArg)), ); export const validateWorkloadInitReleaseApproval = async ( approvalArg: unknown, ): Promise => { try { if (!isRecord(approvalArg) || !hasExactKeys(approvalArg, [ 'schemaVersion', 'release', 'imageIndexMediaType', 'workloadInitImageIndexDigest', 'artifacts', 'verificationSummary', 'approvedAt', 'approvalDigest', ])) { return ['WorkloadInit release approval must use its exact schema']; } const errors = [ ...validateWorkloadInitReleaseIdentity(approvalArg.release), ...validateWorkloadInitCloudlyVerificationSummary(approvalArg.verificationSummary), ]; if (approvalArg.schemaVersion !== 1 || approvalArg.imageIndexMediaType !== workloadInitReleaseContract.imageIndexMediaType || typeof approvalArg.workloadInitImageIndexDigest !== 'string' || !isSha256Digest(approvalArg.workloadInitImageIndexDigest) || !isPositiveSafeInteger(approvalArg.approvedAt) || typeof approvalArg.approvalDigest !== 'string' || !isSha256Digest(approvalArg.approvalDigest)) { errors.push('WorkloadInit release approval authority fields must be canonical'); } if (!Array.isArray(approvalArg.artifacts) || approvalArg.artifacts.length !== 2 || approvalArg.artifacts.map((artifactArg) => ( isRecord(artifactArg) ? artifactArg.platform : undefined )).join(',') !== 'linux/amd64,linux/arm64') { errors.push('WorkloadInit release approval must contain amd64 then arm64 artifacts'); } else { const manifestDigests = new Set(); for (const [index, artifactArg] of approvalArg.artifacts.entries()) { if (!isRecord(artifactArg) || !hasExactKeys(artifactArg, [ 'platform', 'workloadInitPlatformManifestDigest', 'workloadInitExecutableDigest', ]) || typeof artifactArg.workloadInitPlatformManifestDigest !== 'string' || !isSha256Digest(artifactArg.workloadInitPlatformManifestDigest) || typeof artifactArg.workloadInitExecutableDigest !== 'string' || !isSha256Digest(artifactArg.workloadInitExecutableDigest)) { errors.push(`WorkloadInit release approval artifacts[${index}] must be canonical`); } else { manifestDigests.add(artifactArg.workloadInitPlatformManifestDigest); } } if (manifestDigests.size !== approvalArg.artifacts.length) { errors.push('WorkloadInit release approval platform manifest digests must be unique'); } } if (isRecord(approvalArg.verificationSummary)) { if (approvalArg.verificationSummary.subjectImageIndexDigest !== approvalArg.workloadInitImageIndexDigest) { errors.push('WorkloadInit release approval subject must match its image index'); } if (isPositiveSafeInteger(approvalArg.verificationSummary.verifiedAt) && isPositiveSafeInteger(approvalArg.approvedAt) && approvalArg.verificationSummary.verifiedAt > approvalArg.approvedAt) { errors.push('WorkloadInit release approval cannot predate verification'); } } if (errors.length === 0 && approvalArg.approvalDigest !== await computeWorkloadInitReleaseApprovalDigest( approvalArg as unknown as IWorkloadInitReleaseApprovalV1, )) { errors.push('WorkloadInit release approval digest does not match'); } return errors; } catch { return ['WorkloadInit release approval must be safely inspectable']; } }; export const validateWorkloadInitApprovalAuthorityReference = ( referenceArg: unknown, ): string[] => { if (!isRecord(referenceArg) || !hasExactKeys(referenceArg, [ 'authorityVersion', 'authorityGeneration', 'approvalDigest', ])) { return ['WorkloadInit approval authority reference must use its exact schema']; } const errors: string[] = []; if (referenceArg.authorityVersion !== 1 || !isPositiveSafeInteger(referenceArg.authorityGeneration) || typeof referenceArg.approvalDigest !== 'string' || !isSha256Digest(referenceArg.approvalDigest)) { errors.push('WorkloadInit approval authority reference fields must be canonical'); } return errors; }; export const validateWorkloadInitActiveApprovalAuthority = async ( authorityArg: unknown, ): Promise => { if (!isRecord(authorityArg) || !hasExactKeys(authorityArg, [ 'authorityVersion', 'authorityGeneration', 'approvalDigest', 'approval', ])) { return ['active WorkloadInit approval authority must use its exact schema']; } const reference = { authorityVersion: authorityArg.authorityVersion, authorityGeneration: authorityArg.authorityGeneration, approvalDigest: authorityArg.approvalDigest, }; const errors = [ ...validateWorkloadInitApprovalAuthorityReference(reference), ...await validateWorkloadInitReleaseApproval(authorityArg.approval), ]; if (isRecord(authorityArg.approval) && authorityArg.approvalDigest !== authorityArg.approval.approvalDigest) { errors.push('active WorkloadInit authority must reference its embedded approval'); } return errors; };