Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
114 changes: 114 additions & 0 deletions .github/workflows/prism-code-update.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,114 @@
# Keeps the shell on the newest prism-code, without giving up the pin. Each hour it asks npm which
# release of prism-code is `latest`. When that is newer than the version the shell carries byte for
# byte, it re-pins (studio/tools/prism_code_update.mjs), runs the gates a re-pin must keep, and opens
# the result as a pull request. Nothing is merged here: a pull request the workflow token opens
# starts no CI, so a person, or the acceptance gate dispatched on it, decides.
#
# The proposal is made with read permission only, as template-update.yml makes its own: the job that
# installs a package published minutes ago holds no token that can write. The job that can write
# applies the patch that came out and runs nothing from it.
name: prism-code update

on:
schedule:
- cron: '41 * * * *'
workflow_dispatch:

permissions: {}

concurrency:
group: prism-code-update
cancel-in-progress: false

jobs:
proposal:
name: re-pin prism-code to npm's latest and hold it to the journey gates
runs-on: ubuntu-24.04
timeout-minutes: 15
permissions:
contents: read
outputs:
changed: ${{ steps.repin.outputs.changed }}
version: ${{ steps.repin.outputs.version }}
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
with:
persist-credentials: false
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
with:
node-version: "24"
- id: repin
name: Re-pin, copy the files, and check every import resolves inside the shell
working-directory: studio
run: |
set -euo pipefail
node tools/prism_code_update.mjs
if git diff --quiet; then
echo "changed=false" >> "$GITHUB_OUTPUT"
exit 0
fi
echo "changed=true" >> "$GITHUB_OUTPUT"
echo "version=$(sed -n 's/^const PRISM_CODE = "\(.*\)";$/\1/p' tools/prism_journey.mjs)" >> "$GITHUB_OUTPUT"
- name: The commit Forge makes on a template instance is still prism-code's, byte for byte
if: steps.repin.outputs.changed == 'true'
working-directory: studio
run: node tools/prism_template.mjs --check
- name: Every app the studio publishes is still a full Prism model
if: steps.repin.outputs.changed == 'true'
working-directory: studio
run: |
node tools/builder/pack.mjs --check
node --test tools/builder_commit.test.mjs
- name: Keep the re-pin as an inert patch
if: steps.repin.outputs.changed == 'true'
run: |
git add --intent-to-add studio
git diff --binary > .prism-code-update.patch
- if: steps.repin.outputs.changed == 'true'
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9
with:
name: prism-code-update-proposal
path: .prism-code-update.patch
if-no-files-found: error
include-hidden-files: true

open:
name: open the re-pin as a pull request
needs: proposal
if: needs.proposal.outputs.changed == 'true'
runs-on: ubuntu-24.04
timeout-minutes: 10
permissions:
contents: write
pull-requests: write
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
with:
persist-credentials: false
ref: ${{ github.event.repository.default_branch }}
- uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333
with:
name: prism-code-update-proposal
- name: Apply the patch without executing anything from it
run: |
git apply --check .prism-code-update.patch
git apply .prism-code-update.patch
rm .prism-code-update.patch
- uses: peter-evans/create-pull-request@15733dbdfeedb4f7fdb73d13c6f5ac83b710fab8
with:
branch: automation/prism-code-update
commit-message: "chore: re-pin prism-code to ${{ needs.proposal.outputs.version }}"
delete-branch: true
title: "chore: re-pin prism-code to ${{ needs.proposal.outputs.version }}"
body: |
npm's `latest` release of prism-code is ${{ needs.proposal.outputs.version }}, newer than the
version the shell carried. This re-pins the three tools that name it and copies its
journey and browser files byte for byte (`studio/tools/prism_code_update.mjs`).

Held before this was opened: every copied file is that version's, every import the
copied files make resolves inside the shell, the template commit is still prism-code's
byte for byte, and the builder gates pass.

Not run here: the rest of the studio gates. A pull request the workflow token opens
starts no CI, so dispatch them on this branch, and read the prism-code changelog for
anything the shell should start to call, before merging.
149 changes: 145 additions & 4 deletions studio/shell/prism-code/src/archive.mjs
Original file line number Diff line number Diff line change
@@ -1,6 +1,9 @@
/**
* Reader for the Hologram v4 `.holo` application archive that PrismPM
* composes (`SPEC.md` §3, `crates/prismpm/src/holo/archive.rs`, encoded through
* Reader for the `.holo` application archive. PrismPM writes holo v5, a UORC
* archive of ordered objects named by κ (ADR-017, `src/uorc.mjs`); the
* Hologram physical-v4 archive below stays readable and is never written.
*
* Legacy v4 is the archive PrismPM composed before v5 (`SPEC.md` §3, `crates/prismpm/src/holo/archive.rs`, encoded through
* `Foundation.Holo.V1.Wire`).
*
* Layout, little-endian:
Expand All @@ -17,10 +20,16 @@
* blob. A content blob starts with its 71-byte `blake3:<hex>` label.
*/
import { DigestMismatchError, fail } from './errors.mjs';
import { blake3Hex, kappa } from './blake3.mjs';
import { blake3Hex, kappa as v4Label } from './blake3.mjs';
import { isUorc, kappa, layout } from './uorc.mjs';

export const MAGIC = 'HOLO';
export const VERSION = 4;
/** Holo v5 (ADR-017): schema of the manifest object and the roles of the ordered objects. */
export const MANIFEST_SCHEMA_V5 = 'prism/holo/5';
export const PROVENANCE_SCHEMA_V5 = 'prismpm/model-provenance/2';
export const ROLES_V5 = Object.freeze(['manifest', 'source-manifest', 'provenance', 'capabilities', 'guest', 'view', 'model']);
export const ROLE_ATTESTATIONS = 'attestations';
export const KIND = Object.freeze({ APP_MANIFEST: 15, METADATA: 8, EXTENSION: 14, CONTENT_BLOB: 16 });
export const LABEL_LENGTH = 71;
export const FOOTER_LENGTH = 32;
Expand Down Expand Up @@ -68,6 +77,7 @@ function isLabel(bytes) {
*/
export function parseArchive(source) {
const bytes = asBytes(source);
if (isUorc(bytes)) return parseArchiveV5(bytes);
if (bytes.length < HEADER_LENGTH + FOOTER_LENGTH) fail('archive.bounds', 'archive shorter than header and footer');
const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
const magic = String.fromCharCode(bytes[0], bytes[1], bytes[2], bytes[3]);
Expand Down Expand Up @@ -163,7 +173,7 @@ export function parseArchive(source) {
if (!isLabel(labelBytes)) fail('archive.blob', `content blob ${blobs.length} has no blake3 label`);
const label = decoder.decode(labelBytes);
const content = b.subarray(LABEL_LENGTH);
const actual = kappa(content);
const actual = v4Label(content);
if (actual !== label) labelMismatches.push({ section: section.index, label, actual });
blobs.push({ label, content, section: section.index });
break;
Expand Down Expand Up @@ -202,13 +212,92 @@ export function parseArchive(source) {
};
}

const hexOf = (bytes) => Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');

/**
* Parse a holo v5. The result has the v4 reader's shape (sections, blobs,
* extensions, manifest labels, verification) so every consumer reads both:
* each object is a section whose `kind` is its role, the provenance object is
* the model extension and the attestation object the attestation extension.
*/
function parseArchiveV5(bytes) {
const { objects, sealed, seal, preimage } = layout(bytes);
if (objects.length !== ROLES_V5.length && objects.length !== ROLES_V5.length + 1) {
fail('archive.bounds', `a v5 application holo holds ${ROLES_V5.length} objects, or ${ROLES_V5.length + 1} when signed; this one holds ${objects.length}`);
}
const roles = [...ROLES_V5, ROLE_ATTESTATIONS];
const sections = objects.map((object, index) => ({ index, kind: roles[index], offset: object.offset, length: object.length, body: object.bytes }));
const text = (slice, what) => {
try {
return decoder.decode(slice);
} catch {
if (!sealed) throw new DigestMismatchError(`integrity failure: the holo was altered: its seal does not match, and ${what} is not UTF-8`, { check: 'holo.integrity' });
return fail('archive.manifest', `${what} is not UTF-8`);
}
};
const manifestText = text(objects[0].bytes, 'the manifest');
let holoManifest;
try {
holoManifest = JSON.parse(manifestText);
} catch (error) {
if (!sealed) throw new DigestMismatchError('integrity failure: the holo was altered: its seal does not match', { check: 'holo.integrity', cause: error });
fail('archive.manifest', `the manifest is not JSON: ${error.message}`);
}
if (holoManifest?.schema !== MANIFEST_SCHEMA_V5) fail('archive.manifest', `the manifest schema is ${JSON.stringify(holoManifest?.schema)}, expected ${MANIFEST_SCHEMA_V5}`);
const layer = (kind) => (Array.isArray(holoManifest.layers) ? holoManifest.layers.find((l) => l.kind === kind) : undefined);
const labels = [holoManifest.requires, layer('wasm')?.kappa, layer('view')?.kappa];
const blobs = [3, 4, 5, 6].map((index) => ({ label: kappa(objects[index].bytes), content: objects[index].bytes, section: index }));
const extensions = [
{ name: MODEL_EXTENSION, payload: objects[2].bytes, text: text(objects[2].bytes, 'the provenance object'), section: 2 },
];
if (objects.length > ROLES_V5.length) {
const payload = objects[ROLES_V5.length].bytes;
extensions.push({ name: 'https://uor.foundation/extension/attestation-bundle/v1', payload, text: text(payload, 'the attestation object'), section: ROLES_V5.length });
}
const listed = Array.isArray(holoManifest.objects) ? holoManifest.objects : [];
const expected = [1, 3, 4, 5, 6].map((index) => ({ role: ROLES_V5[index], kappa: kappa(objects[index].bytes), length: objects[index].length }));
const labelMismatches = expected
.filter((row, i) => listed[i]?.role !== row.role || listed[i]?.kappa !== row.kappa || listed[i]?.length !== row.length)
.map((row) => ({ section: ROLES_V5.indexOf(row.role), label: listed.find((l) => l.role === row.role)?.kappa ?? null, actual: row.kappa }));
if (listed.length !== expected.length) labelMismatches.push({ section: null, label: null, actual: null });
const fingerprint = hexOf(seal);
return {
format: 5,
bytes,
body: preimage,
version: 5,
flags: 0,
sections,
manifest: { uri: MANIFEST_SCHEMA_V5, labels, section: 0 },
holoManifest,
metadata: { text: text(objects[1].bytes, 'the source manifest'), section: 1 },
extensions,
blobs,
footer: fingerprint,
fingerprint: sealed ? fingerprint : null,
kappa: kappa(bytes),
verification: {
footer: sealed,
seal: sealed,
labels: labelMismatches.length === 0,
labelMismatches,
},
};
}

function blake3HexOf(bytes) {
let s = '';
for (const b of bytes) s += b.toString(16).padStart(2, '0');
return s;
}

/** JSON with sorted keys and no whitespace, the SDK's canonical encoding (`holo/canonical.rs`). */
/**
* The identity of a holo: for a holo v5 its κ, the `sha256:` of the file, which is also its OCI layer digest
* (ADR-017); for a legacy v4 holo the `blake3:` of its body, which its footer claims.
*/
export const holoDigest = (parsed) => (parsed.format === 5 ? parsed.kappa : `blake3:${parsed.fingerprint}`);

export function canonicalJson(value) {
if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
if (value && typeof value === 'object') {
Expand All @@ -225,6 +314,7 @@ export function canonicalJson(value) {
* directory and model extensions against the manifest and the blobs.
*/
export function resolveArchive(parsed) {
if (parsed.format === 5) return resolveArchiveV5(parsed);
const extension = (name) => parsed.extensions.find((e) => e.name === name);
const directoryExtension = extension(DIRECTORY_EXTENSION);
const modelExtension = extension(MODEL_EXTENSION);
Expand Down Expand Up @@ -287,3 +377,54 @@ export function resolveArchive(parsed) {
},
};
}

function resolveArchiveV5(parsed) {
const manifest = parsed.holoManifest;
const provenance = JSON.parse(parsed.extensions.find((e) => e.name === MODEL_EXTENSION).text);
const [capabilities, guest, view, model] = parsed.blobs;
const wasmLayer = manifest.layers?.find((l) => l.kind === 'wasm');
const viewLayer = manifest.layers?.find((l) => l.kind === 'view');
if (!wasmLayer || wasmLayer.entry !== 'holo_run') fail('archive.directory', 'the manifest has no wasm layer entered at holo_run');
if (!viewLayer) fail('archive.directory', 'the manifest has no view layer');
const applicationKappa = kappa(parsed.sections[0].body);
const consistent =
canonicalJson(manifest) === decoder.decode(parsed.sections[0].body) &&
manifest.requires === capabilities.label &&
wasmLayer.kappa === guest.label &&
viewLayer.kappa === view.label &&
provenance.schema === PROVENANCE_SCHEMA_V5 &&
provenance.guest_content_kappa === guest.label &&
provenance.model_content_kappa === model.label &&
provenance.view_binding?.view_content_kappa === view.label &&
provenance.application_kappa === applicationKappa &&
canonicalJson(provenance) === parsed.extensions.find((e) => e.name === MODEL_EXTENSION).text;
let modelDocument;
try {
modelDocument = JSON.parse(decoder.decode(model.content));
} catch (error) {
fail('archive.model', `model document is not JSON: ${error.message}`);
}
return {
directory: { schema_version: 5, primary_layer: 0, requires_kappa: manifest.requires, layers: manifest.layers.map((l) => ({ ...l, content_kappa: l.kappa })) },
manifest,
provenance,
modelDocument,
guest,
view,
model,
capabilities,
identities: {
archiveFingerprint: parsed.fingerprint,
footer: parsed.footer,
archiveKappa: parsed.kappa,
basis: manifest.basis ?? null,
guestKappa: guest.label,
viewKappa: view.label,
modelKappa: model.label,
capabilitiesKappa: capabilities.label,
applicationKappa,
verified: parsed.verification.seal && parsed.verification.labels && consistent,
consistent,
},
};
}
23 changes: 17 additions & 6 deletions studio/shell/prism-code/src/attestations.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@
* that is `prism verify` (#272) and `@prism-code/verify` (#273).
*/
import { fail } from './errors.mjs';
import { writeObjects } from './uorc.mjs';
import { asBytes, parseArchive, KIND, MAGIC, VERSION, HEADER_LENGTH, TABLE_ENTRY_LENGTH, FOOTER_LENGTH } from './archive.mjs';
import { blake3 } from './blake3.mjs';

Expand Down Expand Up @@ -81,9 +82,17 @@ function splitLines(payload) {
return lines;
}

function digestSet(digest, where) {
function digestSet(digest, where, legacy) {
if (!isObject(digest)) fail('attestation.subject', `${where} has no digest set`);
const keys = Object.keys(digest).sort();
if (!legacy) {
// A holo v5 names its objects by κ (sha256), so a subject is sha256 alone (ADR-017).
if (keys.length !== 1 || keys[0] !== 'sha256') {
fail('attestation.subject', `${where} must carry exactly sha256, the κ of the object it names (ADR-017), found ${keys.join(', ') || 'none'}`);
}
if (typeof digest.sha256 !== 'string' || !HEX64.test(digest.sha256)) fail('attestation.subject', `${where} sha256 is not 64 lowercase hex characters`);
return { sha256: digest.sha256 };
}
if (keys.length !== 2 || keys[0] !== 'blake3' || keys[1] !== 'sha256') {
fail('attestation.subject', `${where} must carry exactly blake3 and sha256 (ADR-015), found ${keys.join(', ') || 'none'}`);
}
Expand Down Expand Up @@ -134,8 +143,9 @@ export function decodeBundle(line, labels = new Set()) {
if (subject.name === OCI_MANIFEST_SUBJECT) {
fail('attestation.subject', 'a statement inside the holo cannot name the OCI manifest; that statement is signed at push');
}
const digest = digestSet(subject.digest, where);
const label = `blake3:${digest.blake3}`;
const legacy = [...labels].some((label) => label.startsWith('blake3:'));
const digest = digestSet(subject.digest, where, legacy);
const label = legacy ? `blake3:${digest.blake3}` : `sha256:${digest.sha256}`;
return { name: subject.name, digest, blob: labels.has(label) ? label : null };
});
return {
Expand Down Expand Up @@ -225,6 +235,7 @@ function hex(bytes) {
*/
export function appendAttestations(source, bundles) {
const parsed = parsedOf(source);
if (parsed.format !== 5) fail('attestation.format', 'a physical-v4 holo is read-only; rebuild it as a holo v5 before signing (ADR-017)');
if (!parsed.verification.footer) fail('attestation.footer', 'the archive footer does not verify; refusing to append');
if (!Array.isArray(bundles) || bundles.length === 0) fail('attestation.input', 'appendAttestations takes a non-empty array of bundles');
const existing = attestationSection(parsed);
Expand All @@ -246,9 +257,8 @@ export function appendAttestations(source, bundles) {
payload[line.length + at] = LF;
at += line.length + 1;
}
const kept = parsed.sections.filter((s) => !existing || s.index !== existing.section).map(({ kind, body }) => ({ kind, body }));
kept.push({ kind: KIND.EXTENSION, body: extensionBody(ATTESTATION_EXTENSION, payload) });
return encodeArchive(kept, { version: parsed.version, flags: parsed.flags });
const kept = parsed.sections.filter((s) => !existing || s.index !== existing.section).map((s) => s.body);
return writeObjects([...kept, payload]);
}

/**
Expand All @@ -261,6 +271,7 @@ export function stripAttestations(source) {
const parsed = parsedOf(source);
const existing = attestationSection(parsed);
if (!existing) return parsed.bytes.slice();
if (parsed.format === 5) return writeObjects(parsed.sections.filter((s) => s.index !== existing.section).map((s) => s.body));
const kept = parsed.sections.filter((s) => s.index !== existing.section).map(({ kind, body }) => ({ kind, body }));
return encodeArchive(kept, { version: parsed.version, flags: parsed.flags });
}
Loading
Loading