@astrale-os/kernel-protocol 0.5.0-beta.10

package/dist/schema/installation/introspection/codec.js

@@ -0,0 +1,272 @@
+import * as bundle from '@astrale-os/kernel-dsl/v1/bundle/transport';
+import * as artifact from '../../../artifact/index.js';
+import { json } from '../../../codecs/index.js';
+import * as publication from '../../../publication/index.js';
+import * as runtime from '../../../runtime/index.js';
+export const MEDIA_TYPE = 'application/vnd.astrale.schema-introspection.v1+msgpack';
+export async function encode(input, result) {
+    const fields = selected(input);
+    const wire = result === null ? null : encodeResult(fields, result);
+    const { pack } = await import('msgpackr/pack');
+    return new Uint8Array(pack(wire));
+}
+export async function decode(input, bytes, limits) {
+    if (!(bytes instanceof Uint8Array))
+        invalid('Schema introspection evidence must be binary.');
+    admitLimit(limits.maximumPublicationBytes, 'Publication');
+    admitLimit(limits.maximumBundleBytes, 'Bundle');
+    if (bytes.byteLength > limits.maximumPublicationBytes + limits.maximumBundleBytes + 2_048) {
+        invalid('Schema introspection evidence exceeds its declared bounds.');
+    }
+    const { unpack } = await import('msgpackr/unpack');
+    let decoded;
+    try {
+        decoded = unpack(bytes);
+    }
+    catch (cause) {
+        throw new TypeError('Schema introspection evidence is malformed.', { cause });
+    }
+    if (decoded === null)
+        return null;
+    if (!isRecord(decoded))
+        invalid('Schema introspection result must be an object or null.');
+    const fields = selected(input);
+    exact(decoded, fields, 'Schema introspection result');
+    return decodeResult(fields, decoded, limits);
+}
+function encodeResult(fields, result) {
+    exact(result, fields, 'Schema introspection result');
+    const source = fields.includes('source') ? encodeSource(result.source) : undefined;
+    const output = {};
+    for (const field of fields) {
+        switch (field) {
+            case 'state':
+                output.state = state(result.state);
+                break;
+            case 'target':
+                output.target = digest(result.target, 'Installation target');
+                break;
+            case 'source':
+                output.source = source;
+                break;
+            case 'bundle':
+                output.bundle = encodeBundle(result.bundle, result.source);
+                break;
+            case 'readiness':
+                output.readiness =
+                    result.readiness === null ? null : digest(result.readiness, 'Installation readiness');
+                break;
+            case 'capabilities':
+                output.capabilities = capabilities(result.capabilities);
+                break;
+        }
+    }
+    return Object.freeze(output);
+}
+function decodeResult(fields, input, limits) {
+    const source = fields.includes('source') ? decodeSource(input.source, limits) : undefined;
+    const output = {};
+    for (const field of fields) {
+        switch (field) {
+            case 'state':
+                output.state = state(input.state);
+                break;
+            case 'target':
+                output.target = digest(input.target, 'Installation target');
+                break;
+            case 'source':
+                output.source = source;
+                break;
+            case 'bundle':
+                output.bundle = decodeBundle(input.bundle, source, limits.maximumBundleBytes);
+                break;
+            case 'readiness':
+                output.readiness =
+                    input.readiness === null ? null : digest(input.readiness, 'Installation readiness');
+                break;
+            case 'capabilities':
+                output.capabilities = capabilities(input.capabilities);
+                break;
+        }
+    }
+    if (output.state === 'ready' && Object.hasOwn(output, 'readiness') && output.readiness === null) {
+        invalid('A ready Installation requires readiness evidence.');
+    }
+    return Object.freeze(output);
+}
+function encodeSource(input) {
+    if (input?.kind === 'builtin') {
+        return Object.freeze({
+            kind: 'builtin',
+            bundle: ref(input.bundle, publication.BUNDLE_MEDIA_TYPE, 'Builtin schema Bundle'),
+        });
+    }
+    if (input?.kind === 'local') {
+        return Object.freeze({
+            kind: 'local',
+            artifact: ref(input.artifact, runtime.MEDIA_TYPE, 'Local Runtime Artifact'),
+            bundle: ref(input.bundle, publication.BUNDLE_MEDIA_TYPE, 'Local schema Bundle'),
+        });
+    }
+    if (input?.kind === 'remote') {
+        return Object.freeze({
+            kind: 'remote',
+            publication: publication.encode(publication.accept(input.publication)),
+        });
+    }
+    return invalid('Installation source is invalid.');
+}
+function decodeSource(input, limits) {
+    if (!isRecord(input))
+        invalid('Installation source is invalid.');
+    if (input.kind === 'builtin') {
+        exact(input, ['bundle', 'kind'], 'Builtin installation source');
+        return Object.freeze({
+            kind: 'builtin',
+            bundle: ref(input.bundle, publication.BUNDLE_MEDIA_TYPE, 'Builtin schema Bundle'),
+        });
+    }
+    if (input.kind === 'local') {
+        exact(input, ['artifact', 'bundle', 'kind'], 'Local installation source');
+        return Object.freeze({
+            kind: 'local',
+            artifact: ref(input.artifact, runtime.MEDIA_TYPE, 'Local Runtime Artifact'),
+            bundle: ref(input.bundle, publication.BUNDLE_MEDIA_TYPE, 'Local schema Bundle'),
+        });
+    }
+    if (input.kind === 'remote') {
+        exact(input, ['kind', 'publication'], 'Remote installation source');
+        const encoded = boundedBytes(input.publication, limits.maximumPublicationBytes, 'Publication');
+        let admitted;
+        try {
+            admitted = publication.accept(json.decode(encoded));
+        }
+        catch (cause) {
+            throw new TypeError('Remote installed Publication is invalid.', { cause });
+        }
+        if (!equal(encoded, publication.encode(admitted))) {
+            invalid('Remote installed Publication is not canonical.');
+        }
+        return Object.freeze({ kind: 'remote', publication: admitted });
+    }
+    return invalid('Installation source kind is invalid.');
+}
+function encodeBundle(input, source) {
+    if (source === undefined || input === undefined)
+        invalid('Bundle source evidence is missing.');
+    const admitted = source.kind === 'remote'
+        ? publication.acceptBundle(source.publication, input)
+        : bundle.accept(input);
+    const encoded = bundle.encode(admitted);
+    if (source.kind !== 'remote' &&
+        !same(artifact.identify(encoded, publication.BUNDLE_MEDIA_TYPE), source.bundle)) {
+        invalid('Local schema Bundle does not match its source Ref.');
+    }
+    return encoded;
+}
+function decodeBundle(input, source, maximum) {
+    const encoded = boundedBytes(input, maximum, 'Bundle');
+    let admitted;
+    try {
+        admitted =
+            source.kind === 'remote'
+                ? publication.decodeBundle(source.publication, encoded)
+                : bundle.decode(encoded);
+    }
+    catch (cause) {
+        throw new TypeError('Installed schema Bundle is invalid.', { cause });
+    }
+    if (!equal(encoded, bundle.encode(admitted)))
+        invalid('Installed schema Bundle is not canonical.');
+    if (source.kind !== 'remote' &&
+        !same(artifact.identify(encoded, publication.BUNDLE_MEDIA_TYPE), source.bundle)) {
+        invalid('Local schema Bundle does not match its source Ref.');
+    }
+    return admitted;
+}
+function selected(input) {
+    if (input === null ||
+        typeof input !== 'object' ||
+        input.from?.kind !== 'installation' ||
+        input.select === null ||
+        typeof input.select !== 'object') {
+        invalid('Schema introspection request is invalid.');
+    }
+    const allowed = ['state', 'target', 'source', 'bundle', 'readiness', 'capabilities'];
+    const fields = Object.keys(input.select);
+    if (fields.length === 0 ||
+        fields.some((field) => !allowed.includes(field) ||
+            input.select[field] !== true) ||
+        (input.select.bundle === true && input.select.source !== true)) {
+        invalid('Schema introspection selection is invalid.');
+    }
+    return Object.freeze(allowed.filter((field) => input.select[field] === true));
+}
+function capabilities(input) {
+    if (!isRecord(input))
+        invalid('Installation capabilities are invalid.');
+    exact(input, ['materialized', 'requested'], 'Installation capabilities');
+    try {
+        const requested = publication.admitRequirements({ capabilities: input.requested }).capabilities;
+        const materialized = publication.admitRequirements({
+            capabilities: input.materialized,
+        }).capabilities;
+        return Object.freeze({ requested, materialized });
+    }
+    catch (cause) {
+        throw new TypeError('Installation capabilities are invalid.', { cause });
+    }
+}
+function state(input) {
+    if (input !== 'installed' && input !== 'ready' && input !== 'removing') {
+        invalid('Installation state is invalid.');
+    }
+    return input;
+}
+function digest(input, label) {
+    if (typeof input !== 'string' || !/^sha256:[0-9a-f]{64}$/u.test(input)) {
+        invalid(`${label} digest is invalid.`);
+    }
+    return input;
+}
+function ref(input, mediaType, label) {
+    let admitted;
+    try {
+        admitted = artifact.accept(input);
+    }
+    catch (cause) {
+        throw new TypeError(`${label} Ref is invalid.`, { cause });
+    }
+    if (admitted.mediaType !== mediaType)
+        invalid(`${label} media type is invalid.`);
+    return admitted;
+}
+function same(left, right) {
+    return (left.digest === right.digest && left.mediaType === right.mediaType && left.size === right.size);
+}
+function boundedBytes(input, maximum, label) {
+    if (!(input instanceof Uint8Array) || input.byteLength === 0 || input.byteLength > maximum) {
+        invalid(`${label} evidence is invalid or exceeds its bound.`);
+    }
+    return Uint8Array.from(input);
+}
+function admitLimit(input, label) {
+    if (!Number.isSafeInteger(input) || input < 1)
+        invalid(`${label} evidence bound is invalid.`);
+}
+function exact(input, expected, label) {
+    const keys = Object.keys(input).sort();
+    const wanted = [...expected].sort();
+    if (keys.length !== wanted.length || keys.some((key, index) => key !== wanted[index])) {
+        invalid(`${label} fields are invalid.`);
+    }
+}
+function equal(left, right) {
+    return left.byteLength === right.byteLength && left.every((byte, index) => byte === right[index]);
+}
+function isRecord(input) {
+    return input !== null && typeof input === 'object' && !Array.isArray(input);
+}
+function invalid(message) {
+    throw new TypeError(message);
+}

package/dist/schema/installation/introspection/index.d.ts

@@ -0,0 +1,2 @@
+export { MEDIA_TYPE, decode, encode } from './codec.js';
+export type { Digest, Installation, Limits, ResultFor, Source } from './result.js';

package/dist/schema/installation/introspection/index.js

@@ -0,0 +1 @@
+export { MEDIA_TYPE, decode, encode } from './codec.js';

package/dist/schema/installation/introspection/result.d.ts

@@ -0,0 +1,33 @@
+import type { introspection } from '@astrale-os/kernel-core/schema';
+import type { bundle } from '@astrale-os/kernel-dsl/v1';
+import type { Ref } from '../../../artifact/index.js';
+import type { Publication } from '../../../publication/index.js';
+import type { PublicationRequirements } from '../../../publication/index.js';
+export type Digest = `sha256:${string}`;
+export type Source = {
+    readonly kind: 'builtin';
+    readonly bundle: Ref;
+} | {
+    readonly kind: 'local';
+    readonly artifact: Ref;
+    readonly bundle: Ref;
+} | {
+    readonly kind: 'remote';
+    readonly publication: Publication;
+};
+export interface Installation {
+    readonly state: 'installed' | 'ready' | 'removing';
+    readonly target: Digest;
+    readonly source: Source;
+    readonly bundle: bundle.Bundle;
+    readonly readiness: Digest | null;
+    readonly capabilities: {
+        readonly requested: PublicationRequirements['capabilities'];
+        readonly materialized: PublicationRequirements['capabilities'];
+    };
+}
+export type ResultFor<Input extends introspection.Introspection> = Pick<Installation, Extract<keyof Input['select'], keyof Installation>> | null;
+export interface Limits {
+    readonly maximumPublicationBytes: number;
+    readonly maximumBundleBytes: number;
+}

package/dist/schema/installation/introspection/result.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,163 @@
+{
+  "name": "@astrale-os/kernel-protocol",
+  "version": "0.5.0-beta.10",
+  "description": "Portable Astrale invocation, publication, installation, routing, and issuer protocols",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/astrale-os/kernel.git",
+    "directory": "protocol"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./codecs": {
+      "types": "./dist/codecs/index.d.ts",
+      "import": "./dist/codecs/index.js"
+    },
+    "./errors": {
+      "types": "./dist/errors/index.d.ts",
+      "import": "./dist/errors/index.js"
+    },
+    "./issuer/configuration": {
+      "types": "./dist/issuer/configuration.d.ts",
+      "import": "./dist/issuer/configuration.js"
+    },
+    "./issuer/exchange": {
+      "types": "./dist/issuer/exchange.d.ts",
+      "import": "./dist/issuer/exchange.js"
+    },
+    "./issuer/hosted": {
+      "types": "./dist/issuer/hosted.d.ts",
+      "import": "./dist/issuer/hosted.js"
+    },
+    "./issuer/key-set": {
+      "types": "./dist/issuer/key-set.d.ts",
+      "import": "./dist/issuer/key-set.js"
+    },
+    "./issuer/paths": {
+      "types": "./dist/issuer/paths.d.ts",
+      "import": "./dist/issuer/paths.js"
+    },
+    "./invocation": {
+      "types": "./dist/invocation/index.d.ts",
+      "import": "./dist/invocation/index.js"
+    },
+    "./invocation/service-reason": {
+      "types": "./dist/invocation/service-reason.d.ts",
+      "import": "./dist/invocation/service-reason.js"
+    },
+    "./artifact": {
+      "types": "./dist/artifact/index.d.ts",
+      "import": "./dist/artifact/index.js"
+    },
+    "./publication": {
+      "types": "./dist/publication/index.d.ts",
+      "import": "./dist/publication/index.js"
+    },
+    "./publication/publication": {
+      "types": "./dist/publication/publication.d.ts",
+      "import": "./dist/publication/publication.js"
+    },
+    "./publication/reference": {
+      "types": "./dist/publication/reference.d.ts",
+      "import": "./dist/publication/reference.js"
+    },
+    "./publication/requirements": {
+      "types": "./dist/publication/requirements.d.ts",
+      "import": "./dist/publication/requirements.js"
+    },
+    "./publication/delivery": {
+      "types": "./dist/publication/delivery/index.d.ts",
+      "import": "./dist/publication/delivery/index.js"
+    },
+    "./publication/bundle": {
+      "types": "./dist/publication/bundle.d.ts",
+      "import": "./dist/publication/bundle.js"
+    },
+    "./publication/bundle-evidence": {
+      "types": "./dist/publication/bundle-evidence.d.ts",
+      "import": "./dist/publication/bundle-evidence.js"
+    },
+    "./publication/delivery-declaration": {
+      "types": "./dist/publication/delivery-declaration.d.ts",
+      "import": "./dist/publication/delivery-declaration.js"
+    },
+    "./routes": {
+      "types": "./dist/routes/index.d.ts",
+      "import": "./dist/routes/index.js"
+    },
+    "./schema": {
+      "types": "./dist/schema/index.d.ts",
+      "import": "./dist/schema/index.js"
+    },
+    "./routes/admission": {
+      "types": "./dist/routes/admission.d.ts",
+      "import": "./dist/routes/admission.js"
+    },
+    "./routes/binding": {
+      "types": "./dist/routes/binding.d.ts",
+      "import": "./dist/routes/binding.js"
+    },
+    "./routes/evidence": {
+      "types": "./dist/routes/evidence.d.ts",
+      "import": "./dist/routes/evidence.js"
+    },
+    "./routes/placement": {
+      "types": "./dist/routes/placement.d.ts",
+      "import": "./dist/routes/placement.js"
+    },
+    "./routes/release-unavailable": {
+      "types": "./dist/routes/release-unavailable.d.ts",
+      "import": "./dist/routes/release-unavailable.js"
+    },
+    "./routes/routing": {
+      "types": "./dist/routes/routing.d.ts",
+      "import": "./dist/routes/routing.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime/index.d.ts",
+      "import": "./dist/runtime/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@astrale-os/kernel-core": ">=0.9.0-beta.9 <1.0.0",
+    "@astrale-os/kernel-dsl": ">=0.2.0-beta.7 <1.0.0",
+    "@noble/hashes": "2.3.0"
+  },
+  "devDependencies": {
+    "@astrale/typescript-config": "npm:@jsr/astrale__typescript-config@~1.1.0",
+    "msgpackr": "^2.0.5",
+    "typescript": "7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "peerDependencies": {
+    "msgpackr": "^2.0.5"
+  },
+  "peerDependenciesMeta": {
+    "msgpackr": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:file": "vitest run",
+    "test:watch": "vitest",
+    "preinstall": "node -e \"try{require('./.check-workspace.cjs')}catch{}\""
+  }
+}