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

package/dist/invocation/response.js

@@ -0,0 +1,38 @@
+import { errorPayload, exactFields, invalid, invocation, portableObject, requestId, required, } from './admission.js';
+import { decodeMiss } from './miss.js';
+import { decodeRedirectResponse } from './redirect.js';
+import { decodeStale } from './stale-route.js';
+const SUCCESS_FIELDS = new Set(['result', 'requestId', 'invocation']);
+const ERROR_FIELDS = new Set(['error', 'requestId', 'invocation']);
+export function decodeResponse(input) {
+    const object = portableObject(input, 'response');
+    const hasResult = Object.hasOwn(object, 'result');
+    const hasError = Object.hasOwn(object, 'error');
+    if (hasResult || hasError) {
+        if (hasResult === hasError)
+            invalid('response must contain exactly one of result or error');
+        if (hasResult) {
+            exactFields(object, SUCCESS_FIELDS, 'response');
+            required(object, ['requestId', 'invocation'], 'response');
+            return Object.freeze({
+                result: object.result,
+                requestId: requestId(object.requestId, 'response.requestId'),
+                invocation: invocation(object.invocation, 'response.invocation'),
+            });
+        }
+        exactFields(object, ERROR_FIELDS, 'response');
+        required(object, ['requestId', 'error', 'invocation'], 'response');
+        return Object.freeze({
+            error: errorPayload(object.error, 'response.error'),
+            requestId: requestId(object.requestId, 'response.requestId'),
+            invocation: invocation(object.invocation, 'response.invocation'),
+        });
+    }
+    if (object.kind === 'redirect')
+        return decodeRedirectResponse(object);
+    if (object.kind === 'stale')
+        return decodeStale(object);
+    if (object.kind === 'miss')
+        return decodeMiss(object);
+    return invalid('response must contain a result, error, redirect, stale, or miss control');
+}

package/dist/invocation/routing.d.ts

@@ -0,0 +1,14 @@
+import type { IssuerId } from '@astrale-os/kernel-core/auth/issuer';
+import type { Etag } from '../publication/etag.js';
+import type { PublicationRef } from '../publication/reference.js';
+export interface Via {
+    readonly kind: 'via';
+    readonly publication: PublicationRef;
+    readonly issuer: IssuerId;
+}
+export interface Refresh {
+    readonly kind: 'refresh';
+    readonly stale: Etag;
+}
+export type Routing = Via | Refresh;
+export declare function acceptRouting(input: unknown): Routing;

package/dist/invocation/routing.js

@@ -0,0 +1,34 @@
+import { PublicationError } from '../publication/error.js';
+import { acceptReference } from '../publication/reference.js';
+import { digest, exactFields, invalid, issuerId, portableObject, required } from './admission.js';
+const VIA_FIELDS = new Set(['kind', 'publication', 'issuer']);
+const REFRESH_FIELDS = new Set(['kind', 'stale']);
+export function acceptRouting(input) {
+    const object = portableObject(input, 'routing');
+    if (object.kind === 'via') {
+        exactFields(object, VIA_FIELDS, 'via routing');
+        required(object, ['kind', 'publication', 'issuer'], 'via routing');
+        try {
+            return Object.freeze({
+                kind: 'via',
+                publication: acceptReference(object.publication),
+                issuer: issuerId(object.issuer, 'via routing.issuer'),
+            });
+        }
+        catch (cause) {
+            if (cause instanceof PublicationError) {
+                return invalid(`via routing.publication is invalid: ${cause.message}`);
+            }
+            throw cause;
+        }
+    }
+    if (object.kind === 'refresh') {
+        exactFields(object, REFRESH_FIELDS, 'refresh routing');
+        required(object, ['kind', 'stale'], 'refresh routing');
+        return Object.freeze({
+            kind: 'refresh',
+            stale: digest(object.stale, 'refresh routing.stale'),
+        });
+    }
+    return invalid('routing.kind must be "via" or "refresh"');
+}

package/dist/invocation/schema.d.ts

@@ -0,0 +1,9 @@
+import type { Revision } from '@astrale-os/kernel-dsl/v1/addressing';
+import type { Sha256Digest } from '../publication/index.js';
+/** Source-Kernel precondition for the active Schema Registration selected by one invocation. */
+export type SchemaTarget = {
+    readonly target: Sha256Digest;
+} | {
+    readonly revision: Revision;
+};
+export declare function acceptSchemaTarget(input: unknown): SchemaTarget;

package/dist/invocation/schema.js

@@ -0,0 +1,19 @@
+import { patterns } from '@astrale-os/kernel-dsl/v1/addressing';
+import { digest, exactFields, invalid, portableObject } from './admission.js';
+const FIELDS = new Set(['target', 'revision']);
+export function acceptSchemaTarget(input) {
+    const object = portableObject(input, 'schema target');
+    exactFields(object, FIELDS, 'schema target');
+    const hasTarget = Object.hasOwn(object, 'target');
+    const hasRevision = Object.hasOwn(object, 'revision');
+    if (hasTarget === hasRevision) {
+        invalid('schema target must contain exactly one of target or revision');
+    }
+    if (hasTarget) {
+        return Object.freeze({ target: digest(object.target, 'schema target.target') });
+    }
+    if (typeof object.revision !== 'string' || !patterns.revision.test(object.revision)) {
+        invalid('schema target.revision must be a Schema revision');
+    }
+    return Object.freeze({ revision: object.revision });
+}

package/dist/invocation/service-reason.d.ts

@@ -0,0 +1,48 @@
+import type { IssuerId } from '@astrale-os/kernel-core/auth/issuer';
+import type { Revision } from '@astrale-os/kernel-dsl/v1/addressing';
+import type { Object as ValueObject } from '@astrale-os/kernel-dsl/value';
+import { type Key } from '@astrale-os/kernel-dsl/v1/addressing';
+import type { ErrorPayload, ErrorReason } from '../errors/index.js';
+import { CODES } from '../errors/index.js';
+export declare const SCHEMA_UPGRADE_REQUIRED: 'SCHEMA_UPGRADE_REQUIRED';
+export declare const SCHEMA_REVISION_MISMATCH: 'SCHEMA_REVISION_MISMATCH';
+export declare const SERVICE_TRUST_REQUIRED: 'SERVICE_TRUST_REQUIRED';
+export declare const SERVICE_UNAVAILABLE: 'SERVICE_UNAVAILABLE';
+export declare const SERVICE_CANDIDATE_INVALID: 'SERVICE_CANDIDATE_INVALID';
+export type SchemaUpgradeRequiredDetails = ValueObject & {
+    readonly origin: Key.Origin;
+    readonly installedRevision: Revision;
+    readonly candidateRevision: Revision;
+};
+export type SchemaRevisionMismatchDetails = ValueObject & {
+    readonly origin: Key.Origin;
+    readonly expectedRevision: Revision;
+    readonly installedRevision: Revision;
+};
+export type ServiceTrustRequiredDetails = ValueObject & {
+    readonly origin: Key.Origin;
+    readonly installedIssuer: IssuerId;
+    readonly candidateIssuer: IssuerId;
+};
+export type ServiceUnavailableDetails = ValueObject & {
+    readonly origin: Key.Origin;
+    readonly revision: Revision;
+};
+export type ServiceCandidateInvalidDetails = ValueObject & {
+    readonly origin: Key.Origin;
+};
+export type SchemaUpgradeRequiredReason = ErrorReason<typeof SCHEMA_UPGRADE_REQUIRED, SchemaUpgradeRequiredDetails>;
+export type SchemaRevisionMismatchReason = ErrorReason<typeof SCHEMA_REVISION_MISMATCH, SchemaRevisionMismatchDetails>;
+export type ServiceTrustRequiredReason = ErrorReason<typeof SERVICE_TRUST_REQUIRED, ServiceTrustRequiredDetails>;
+export type ServiceUnavailableReason = ErrorReason<typeof SERVICE_UNAVAILABLE, ServiceUnavailableDetails>;
+export type ServiceCandidateInvalidReason = ErrorReason<typeof SERVICE_CANDIDATE_INVALID, ServiceCandidateInvalidDetails>;
+export type ServiceReason = SchemaRevisionMismatchReason | SchemaUpgradeRequiredReason | ServiceTrustRequiredReason | ServiceUnavailableReason | ServiceCandidateInvalidReason;
+export type ServiceErrorPayload = (Omit<ErrorPayload, 'code' | 'data'> & {
+    readonly code: typeof CODES.CONFLICT;
+    readonly data: SchemaRevisionMismatchReason | SchemaUpgradeRequiredReason | ServiceTrustRequiredReason;
+}) | (Omit<ErrorPayload, 'code' | 'data'> & {
+    readonly code: typeof CODES.BACKEND_UNAVAILABLE;
+    readonly data: ServiceUnavailableReason | ServiceCandidateInvalidReason;
+});
+/** Recognize only exact outer-code, reason-code, and detail-shape combinations. */
+export declare function serviceErrorOf(input: ErrorPayload): ServiceErrorPayload | undefined;

package/dist/invocation/service-reason.js

@@ -0,0 +1,85 @@
+import { AuthValueError } from '@astrale-os/kernel-core/auth/error';
+import { accept as acceptIssuer } from '@astrale-os/kernel-core/auth/issuer';
+import { patterns } from '@astrale-os/kernel-dsl/v1/addressing';
+import { CODES, reasonOf } from '../errors/index.js';
+export const SCHEMA_UPGRADE_REQUIRED = 'SCHEMA_UPGRADE_REQUIRED';
+export const SCHEMA_REVISION_MISMATCH = 'SCHEMA_REVISION_MISMATCH';
+export const SERVICE_TRUST_REQUIRED = 'SERVICE_TRUST_REQUIRED';
+export const SERVICE_UNAVAILABLE = 'SERVICE_UNAVAILABLE';
+export const SERVICE_CANDIDATE_INVALID = 'SERVICE_CANDIDATE_INVALID';
+/** Recognize only exact outer-code, reason-code, and detail-shape combinations. */
+export function serviceErrorOf(input) {
+    const reason = reasonOf(input.data);
+    if (reason === undefined)
+        return undefined;
+    switch (reason.code) {
+        case SCHEMA_REVISION_MISMATCH:
+            return input.code === CODES.CONFLICT && schemaRevisionMismatchDetails(reason.details)
+                ? input
+                : undefined;
+        case SCHEMA_UPGRADE_REQUIRED:
+            return input.code === CODES.CONFLICT && schemaUpgradeDetails(reason.details)
+                ? input
+                : undefined;
+        case SERVICE_TRUST_REQUIRED:
+            return input.code === CODES.CONFLICT && serviceTrustDetails(reason.details)
+                ? input
+                : undefined;
+        case SERVICE_UNAVAILABLE:
+            return input.code === CODES.BACKEND_UNAVAILABLE && serviceUnavailableDetails(reason.details)
+                ? input
+                : undefined;
+        case SERVICE_CANDIDATE_INVALID:
+            return input.code === CODES.BACKEND_UNAVAILABLE && candidateInvalidDetails(reason.details)
+                ? input
+                : undefined;
+        default:
+            return undefined;
+    }
+}
+function schemaRevisionMismatchDetails(input) {
+    return (exact(input, ['origin', 'expectedRevision', 'installedRevision']) &&
+        isOrigin(input.origin) &&
+        isRevision(input.expectedRevision) &&
+        isRevision(input.installedRevision));
+}
+function schemaUpgradeDetails(input) {
+    return (exact(input, ['origin', 'installedRevision', 'candidateRevision']) &&
+        isOrigin(input.origin) &&
+        isRevision(input.installedRevision) &&
+        isRevision(input.candidateRevision));
+}
+function serviceTrustDetails(input) {
+    return (exact(input, ['origin', 'installedIssuer', 'candidateIssuer']) &&
+        isOrigin(input.origin) &&
+        isIssuer(input.installedIssuer) &&
+        isIssuer(input.candidateIssuer));
+}
+function serviceUnavailableDetails(input) {
+    return (exact(input, ['origin', 'revision']) && isOrigin(input.origin) && isRevision(input.revision));
+}
+function candidateInvalidDetails(input) {
+    return exact(input, ['origin']) && isOrigin(input.origin);
+}
+function exact(input, fields) {
+    return (Object.keys(input).length === fields.length &&
+        fields.every((field) => Object.hasOwn(input, field)));
+}
+function isOrigin(input) {
+    return typeof input === 'string' && patterns.origin.test(input);
+}
+function isRevision(input) {
+    return typeof input === 'string' && patterns.revision.test(input);
+}
+function isIssuer(input) {
+    if (typeof input !== 'string')
+        return false;
+    try {
+        return acceptIssuer(input) === input;
+    }
+    catch (cause) {
+        if (cause instanceof AuthValueError)
+            return false;
+        throw cause;
+    }
+}

package/dist/invocation/stale-route.d.ts

@@ -0,0 +1,12 @@
+import type { Etag } from '../publication/index.js';
+import type { RequestId } from './correlation.js';
+import type { InvocationId } from './identity.js';
+/** Reserved pre-handler routing control; never an application ErrorResponse. */
+export interface Stale {
+    readonly kind: 'stale';
+    readonly requestId: RequestId;
+    readonly invocation: InvocationId;
+    readonly current: Etag;
+}
+export declare function decodeStale(input: unknown): Stale;
+export declare function stale(requestId: RequestId, assigned: InvocationId, current: Etag): Stale;

package/dist/invocation/stale-route.js

@@ -0,0 +1,19 @@
+import { digest, exactFields, invalid, invocation, portableObject, requestId, required, } from './admission.js';
+const FIELDS = new Set(['kind', 'requestId', 'invocation', 'current']);
+export function decodeStale(input) {
+    const object = portableObject(input, 'stale control');
+    exactFields(object, FIELDS, 'stale control');
+    required(object, ['kind', 'requestId', 'invocation', 'current'], 'stale control');
+    if (object.kind !== 'stale') {
+        invalid('stale control.kind must be "stale"');
+    }
+    return Object.freeze({
+        kind: 'stale',
+        requestId: requestId(object.requestId, 'stale control.requestId'),
+        invocation: invocation(object.invocation, 'stale control.invocation'),
+        current: digest(object.current, 'stale control.current'),
+    });
+}
+export function stale(requestId, assigned, current) {
+    return decodeStale({ kind: 'stale', requestId, invocation: assigned, current });
+}

package/dist/invocation/stream.d.ts

@@ -0,0 +1,27 @@
+import type { Value } from '@astrale-os/kernel-dsl/value';
+import type { ErrorPayload } from '../errors/index.js';
+import type { RequestId } from './correlation.js';
+import type { InvocationId } from './identity.js';
+export interface StreamStartFrame {
+    readonly kind: 'stream.start';
+    readonly requestId: RequestId;
+    readonly invocation: InvocationId;
+}
+export interface StreamItemFrame {
+    readonly kind: 'stream.item';
+    readonly requestId: RequestId;
+    readonly index: number;
+    readonly value: Value;
+}
+export interface StreamEndFrame {
+    readonly kind: 'stream.end';
+    readonly requestId: RequestId;
+    readonly count: number;
+}
+export interface StreamErrorFrame {
+    readonly kind: 'stream.error';
+    readonly requestId: RequestId;
+    readonly error: ErrorPayload;
+}
+export type StreamFrame = StreamStartFrame | StreamItemFrame | StreamEndFrame | StreamErrorFrame;
+export declare function decodeStreamFrame(input: unknown): StreamFrame;

package/dist/invocation/stream.js

@@ -0,0 +1,44 @@
+import { count, errorPayload, exactFields, invalid, invocation, portableObject, requestId, required, } from './admission.js';
+export function decodeStreamFrame(input) {
+    const object = portableObject(input, 'stream frame');
+    const kind = object.kind;
+    if (typeof kind !== 'string')
+        invalid('stream frame.kind must be a string');
+    switch (kind) {
+        case 'stream.start':
+            exactFields(object, new Set(['kind', 'requestId', 'invocation']), 'stream.start');
+            required(object, ['requestId', 'invocation'], 'stream.start');
+            return Object.freeze({
+                kind,
+                requestId: requestId(object.requestId, 'stream.start.requestId'),
+                invocation: invocation(object.invocation, 'stream.start.invocation'),
+            });
+        case 'stream.item':
+            exactFields(object, new Set(['kind', 'requestId', 'index', 'value']), 'stream.item');
+            required(object, ['requestId', 'index', 'value'], 'stream.item');
+            return Object.freeze({
+                kind,
+                requestId: requestId(object.requestId, 'stream.item.requestId'),
+                index: count(object.index, 'stream.item.index'),
+                value: object.value,
+            });
+        case 'stream.end':
+            exactFields(object, new Set(['kind', 'requestId', 'count']), 'stream.end');
+            required(object, ['requestId', 'count'], 'stream.end');
+            return Object.freeze({
+                kind,
+                requestId: requestId(object.requestId, 'stream.end.requestId'),
+                count: count(object.count, 'stream.end.count'),
+            });
+        case 'stream.error':
+            exactFields(object, new Set(['kind', 'requestId', 'error']), 'stream.error');
+            required(object, ['requestId', 'error'], 'stream.error');
+            return Object.freeze({
+                kind,
+                requestId: requestId(object.requestId, 'stream.error.requestId'),
+                error: errorPayload(object.error, 'stream.error.error'),
+            });
+        default:
+            return invalid(`unsupported stream frame kind ${JSON.stringify(kind)}`);
+    }
+}

package/dist/invocation/target.d.ts

@@ -0,0 +1,3 @@
+import type { Call } from '@astrale-os/kernel-core/callable';
+export type { Call } from '@astrale-os/kernel-core/callable';
+export declare function acceptCall(input: unknown): Call;

package/dist/invocation/target.js

@@ -0,0 +1,11 @@
+import { exactFields, nodePath, portableObject, required } from './admission.js';
+const CALL_FIELDS = new Set(['target', 'input']);
+export function acceptCall(input) {
+    const object = portableObject(input, 'call');
+    exactFields(object, CALL_FIELDS, 'call');
+    required(object, ['target', 'input'], 'call');
+    return Object.freeze({
+        target: nodePath(object.target, 'call.target'),
+        input: object.input,
+    });
+}

package/dist/invocation/trace.d.ts

@@ -0,0 +1,9 @@
+export declare const MAXIMUM_TRACEPARENT_BYTES = 512;
+export declare const MAXIMUM_TRACESTATE_BYTES = 512;
+export declare const MAXIMUM_TRACESTATE_MEMBERS = 32;
+export interface Trace {
+    readonly traceparent: string;
+    readonly tracestate?: string;
+}
+/** Admit portable correlation syntax without making it an invocation validity condition. */
+export declare function admitTrace(input: unknown): Trace | undefined;

package/dist/invocation/trace.js

@@ -0,0 +1,86 @@
+export const MAXIMUM_TRACEPARENT_BYTES = 512;
+export const MAXIMUM_TRACESTATE_BYTES = 512;
+export const MAXIMUM_TRACESTATE_MEMBERS = 32;
+const TRACEPARENT_PREFIX = /^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})/u;
+const FUTURE_SUFFIX = /^-[\x21-\x7e]+$/u;
+const SIMPLE_KEY = /^[a-z][a-z0-9_*/-]{0,255}$/u;
+const TENANT_ID = /^[a-z0-9][a-z0-9_*/-]{0,240}$/u;
+const SYSTEM_ID = /^[a-z][a-z0-9_*/-]{0,13}$/u;
+const STATE_VALUE = /^[\x20-\x2b\x2d-\x3c\x3e-\x7e]{0,255}[\x21-\x2b\x2d-\x3c\x3e-\x7e]$/u;
+/** Admit portable correlation syntax without making it an invocation validity condition. */
+export function admitTrace(input) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input))
+        return undefined;
+    const keys = Reflect.ownKeys(input);
+    if (!keys.includes('traceparent') ||
+        keys.some((key) => key !== 'traceparent' && key !== 'tracestate')) {
+        return undefined;
+    }
+    let traceparent;
+    let tracestate;
+    try {
+        const value = input;
+        traceparent = value.traceparent;
+        tracestate = value.tracestate;
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof traceparent !== 'string' || !validTraceparent(traceparent))
+        return undefined;
+    const state = typeof tracestate === 'string' && validTracestate(tracestate) ? tracestate : undefined;
+    return Object.freeze({
+        traceparent,
+        ...(state === undefined || state.trim() === '' ? {} : { tracestate: state }),
+    });
+}
+function validTraceparent(input) {
+    if (input.length < 55 || input.length > MAXIMUM_TRACEPARENT_BYTES)
+        return false;
+    const match = TRACEPARENT_PREFIX.exec(input);
+    if (match === null || match.index !== 0)
+        return false;
+    const [, version, traceId, parentId, flags] = match;
+    if (version === undefined ||
+        traceId === undefined ||
+        parentId === undefined ||
+        flags === undefined ||
+        version === 'ff' ||
+        /^0+$/u.test(traceId) ||
+        /^0+$/u.test(parentId)) {
+        return false;
+    }
+    if (version === '00')
+        return input.length === 55 && (flags === '00' || flags === '01');
+    return input.length === 55 || FUTURE_SUFFIX.test(input.slice(55));
+}
+function validTracestate(input) {
+    if (input.length > MAXIMUM_TRACESTATE_BYTES)
+        return false;
+    const members = input.split(',');
+    if (members.length > MAXIMUM_TRACESTATE_MEMBERS)
+        return false;
+    const keys = new Set();
+    for (const inputMember of members) {
+        const member = inputMember.replace(/^[ \t]+|[ \t]+$/gu, '');
+        if (member === '')
+            continue;
+        const separator = member.indexOf('=');
+        if (separator < 1 || separator !== member.lastIndexOf('='))
+            return false;
+        const key = member.slice(0, separator);
+        const value = member.slice(separator + 1);
+        if (!validStateKey(key) || !STATE_VALUE.test(value) || keys.has(key))
+            return false;
+        keys.add(key);
+    }
+    return true;
+}
+function validStateKey(input) {
+    const separator = input.indexOf('@');
+    if (separator === -1)
+        return SIMPLE_KEY.test(input);
+    if (separator !== input.lastIndexOf('@'))
+        return false;
+    return TENANT_ID.test(input.slice(0, separator)) && SYSTEM_ID.test(input.slice(separator + 1));
+}

package/dist/invocation/version.d.ts

@@ -0,0 +1,2 @@
+export declare const VERSION: 2;
+export type Version = typeof VERSION;

package/dist/invocation/version.js

@@ -0,0 +1 @@
+export const VERSION = 2;

package/dist/invocation/websocket/binary.d.ts

@@ -0,0 +1,3 @@
+import type { BinaryResponse } from '../binary.js';
+export declare function encodeBinary(response: BinaryResponse): Uint8Array;
+export declare function decodeBinary(input: Uint8Array): BinaryResponse | undefined;

package/dist/invocation/websocket/binary.js

@@ -0,0 +1,71 @@
+import { CODES, ProtocolError } from '../../errors/index.js';
+import { decodeBinaryResponse } from '../binary.js';
+const MAGIC = new Uint8Array([0x41, 0x53, 0x54, 0x42, 0x01]);
+const LENGTH_BYTES = 4;
+const MAXIMUM_METADATA_BYTES = 65_536;
+const encoder = new TextEncoder();
+const decoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: false });
+export function encodeBinary(response) {
+    const headers = response.headers === undefined
+        ? undefined
+        : Object.fromEntries(Object.entries(response.headers).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0));
+    const metadata = encoder.encode(JSON.stringify({
+        kind: response.kind,
+        requestId: response.requestId,
+        invocation: response.invocation,
+        mediaType: response.mediaType,
+        ...(headers === undefined ? {} : { headers }),
+    }));
+    if (metadata.byteLength > MAXIMUM_METADATA_BYTES)
+        invalid();
+    const output = new Uint8Array(MAGIC.byteLength + LENGTH_BYTES + metadata.byteLength + response.body.byteLength);
+    output.set(MAGIC, 0);
+    new DataView(output.buffer).setUint32(MAGIC.byteLength, metadata.byteLength);
+    output.set(metadata, MAGIC.byteLength + LENGTH_BYTES);
+    output.set(response.body, MAGIC.byteLength + LENGTH_BYTES + metadata.byteLength);
+    return output;
+}
+export function decodeBinary(input) {
+    if (!hasMagic(input))
+        return undefined;
+    const headerBytes = MAGIC.byteLength + LENGTH_BYTES;
+    if (input.byteLength < headerBytes)
+        invalid();
+    const metadataLength = new DataView(input.buffer, input.byteOffset + MAGIC.byteLength, LENGTH_BYTES).getUint32(0);
+    const bodyOffset = headerBytes + metadataLength;
+    if (metadataLength === 0 ||
+        metadataLength > MAXIMUM_METADATA_BYTES ||
+        bodyOffset > input.byteLength) {
+        invalid();
+    }
+    let metadata;
+    try {
+        metadata = JSON.parse(decoder.decode(input.subarray(headerBytes, bodyOffset)));
+    }
+    catch (cause) {
+        if (cause instanceof SyntaxError || cause instanceof TypeError)
+            return invalid();
+        throw cause;
+    }
+    if (typeof metadata !== 'object' || metadata === null || Array.isArray(metadata))
+        invalid();
+    return decodeBinaryResponse({
+        ...metadata,
+        body: input.slice(bodyOffset),
+    });
+}
+function hasMagic(input) {
+    if (input.byteLength < MAGIC.byteLength)
+        return false;
+    for (let index = 0; index < MAGIC.byteLength; index += 1) {
+        if (input[index] !== MAGIC[index])
+            return false;
+    }
+    return true;
+}
+function invalid() {
+    throw new ProtocolError({
+        code: CODES.INVALID_REQUEST,
+        message: 'WebSocket binary response is invalid.',
+    });
+}

package/dist/invocation/websocket/index.d.ts

@@ -0,0 +1,2 @@
+export { decodeBinary, encodeBinary } from './binary.js';
+export { JSON_SUBPROTOCOL, MSGPACK_SUBPROTOCOL, selectSubprotocol, subprotocolFor, type Subprotocol, type SubprotocolSelection, } from './subprotocol.js';

package/dist/invocation/websocket/index.js

@@ -0,0 +1,2 @@
+export { decodeBinary, encodeBinary } from './binary.js';
+export { JSON_SUBPROTOCOL, MSGPACK_SUBPROTOCOL, selectSubprotocol, subprotocolFor, } from './subprotocol.js';

package/dist/invocation/websocket/subprotocol.d.ts

@@ -0,0 +1,10 @@
+import type { Codec } from '../../codecs/index.js';
+export declare const JSON_SUBPROTOCOL: 'astrale.invocation.v2.json';
+export declare const MSGPACK_SUBPROTOCOL: 'astrale.invocation.v2.msgpack';
+export type Subprotocol = typeof JSON_SUBPROTOCOL | typeof MSGPACK_SUBPROTOCOL;
+export interface SubprotocolSelection {
+    readonly subprotocol: Subprotocol;
+    readonly codec: Codec;
+}
+export declare function subprotocolFor(codec: Codec): Subprotocol;
+export declare function selectSubprotocol(offered: string | null, supported: readonly Codec[]): SubprotocolSelection | undefined;

package/dist/invocation/websocket/subprotocol.js

@@ -0,0 +1,29 @@
+import { admitSupportedCodecs, codecProfile } from '../binding-codecs.js';
+export const JSON_SUBPROTOCOL = 'astrale.invocation.v2.json';
+export const MSGPACK_SUBPROTOCOL = 'astrale.invocation.v2.msgpack';
+const TOKEN = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/u;
+export function subprotocolFor(codec) {
+    const profile = codecProfile(codec);
+    if (profile === undefined)
+        throw new TypeError('codec is not a canonical Invocation codec.');
+    return profile === 'json' ? JSON_SUBPROTOCOL : MSGPACK_SUBPROTOCOL;
+}
+export function selectSubprotocol(offered, supported) {
+    const admitted = admitSupportedCodecs(supported);
+    if (offered === null || offered.trim() === '')
+        return undefined;
+    const tokens = offered.split(',').map((token) => token.trim());
+    const seen = new Set();
+    for (const token of tokens) {
+        if (!TOKEN.test(token) || seen.has(token))
+            return undefined;
+        seen.add(token);
+    }
+    for (const token of tokens) {
+        const entry = admitted.find((candidate) => subprotocolFor(candidate.codec) === token);
+        if (entry !== undefined) {
+            return Object.freeze({ subprotocol: token, codec: entry.codec });
+        }
+    }
+    return undefined;
+}

package/dist/issuer/configuration.d.ts

@@ -0,0 +1,14 @@
+import type { IssuerId } from '@astrale-os/kernel-core/auth/issuer';
+export interface Configuration {
+    readonly issuer: IssuerId;
+    readonly jwks_uri: string;
+    readonly subject_types_supported: readonly ['public'];
+    readonly id_token_signing_alg_values_supported: readonly [string, ...string[]];
+    readonly token_exchange_endpoint?: string;
+}
+export interface ConfigurationOptions {
+    readonly tokenExchange?: boolean;
+}
+export declare function configuration(issuer: string, algorithms: readonly [string, ...string[]], options?: ConfigurationOptions): Configuration;
+export declare function acceptConfiguration(input: unknown, expectedIssuer?: string): Configuration;
+export declare function acceptAlgorithms(input: unknown): readonly [string, ...string[]];