@hypequery/protocol 0.9.0 → 0.10.1

package/README.md

@@ -29,7 +29,7 @@ authentication or tenancy, or contain CLI, HTTP, UI, and Cloud operations.
 
 Self-hosted Serve continues to run project source directly. Deployment bundles
 are required only by Cloud deployment and may be generated ephemerally for
-Studio compatibility and security diagnostics.
+local compatibility and security diagnostics.
 
 ## Public API
 

package/dist/bundles/index.d.ts

@@ -3,5 +3,5 @@ export { PROTOCOL_DEPLOYMENT_BUNDLE_IDENTITY_DOMAIN, encodeProtocolDeploymentBun
 export type { PreparedProtocolDeploymentBundleManifest } from './codec.js';
 export { DEFAULT_PROTOCOL_DEPLOYMENT_BUNDLE_LIMITS } from './limits.js';
 export { validateProtocolDeploymentBundleManifest } from './validate.js';
-export type { ProtocolDeploymentBundleArtifact, ProtocolDeploymentBundleDeployment, ProtocolDeploymentBundleErrorCode, ProtocolDeploymentBundleFile, ProtocolDeploymentBundleLimits, ProtocolDeploymentBundleManifest, ProtocolDeploymentBundleOptions, } from './types.js';
+export type { ProtocolDeploymentBundleArtifact, ProtocolDeploymentBundleDeployment, ProtocolDeploymentBundleErrorCode, ProtocolDeploymentBundleFile, ProtocolDeploymentBundleLimits, ProtocolDeploymentBundleManifest, ProtocolDeploymentBundleOptions, ProtocolDeploymentBundleSource, ProtocolDeploymentBundleSourceRevision, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/bundles/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/bundles/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,6BAA6B,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EACL,0CAA0C,EAC1C,sCAAsC,EACtC,8CAA8C,EAC9C,oCAAoC,EACpC,uCAAuC,GACxC,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,wCAAwC,EAAE,MAAM,YAAY,CAAC;AAC3E,OAAO,EAAE,yCAAyC,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,EAAE,wCAAwC,EAAE,MAAM,eAAe,CAAC;AACzE,YAAY,EACV,gCAAgC,EAChC,kCAAkC,EAClC,iCAAiC,EACjC,4BAA4B,EAC5B,8BAA8B,EAC9B,gCAAgC,EAChC,+BAA+B,GAChC,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/bundles/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,6BAA6B,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EACL,0CAA0C,EAC1C,sCAAsC,EACtC,8CAA8C,EAC9C,oCAAoC,EACpC,uCAAuC,GACxC,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,wCAAwC,EAAE,MAAM,YAAY,CAAC;AAC3E,OAAO,EAAE,yCAAyC,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,EAAE,wCAAwC,EAAE,MAAM,eAAe,CAAC;AACzE,YAAY,EACV,gCAAgC,EAChC,kCAAkC,EAClC,iCAAiC,EACjC,4BAA4B,EAC5B,8BAA8B,EAC9B,gCAAgC,EAChC,+BAA+B,EAC/B,8BAA8B,EAC9B,sCAAsC,GACvC,MAAM,YAAY,CAAC"}

package/dist/bundles/limits.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../../src/bundles/limits.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,8BAA8B,EAC9B,+BAA+B,EAChC,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,yCAAyC,EACtD,QAAQ,CAAC,8BAA8B,CAMrC,CAAC;AAEH,wBAAgB,6BAA6B,CAC3C,OAAO,GAAE,+BAAoC,GAC5C,QAAQ,CAAC,8BAA8B,CAAC,CAe1C"}
+{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../../src/bundles/limits.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,8BAA8B,EAC9B,+BAA+B,EAChC,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,yCAAyC,EACtD,QAAQ,CAAC,8BAA8B,CASrC,CAAC;AAEH,wBAAgB,6BAA6B,CAC3C,OAAO,GAAE,+BAAoC,GAC5C,QAAQ,CAAC,8BAA8B,CAAC,CAe1C"}

package/dist/bundles/limits.js

@@ -1,8 +1,11 @@
 export const DEFAULT_PROTOCOL_DEPLOYMENT_BUNDLE_LIMITS = Object.freeze({
     maxArtifacts: 100,
+    maxSourceFiles: 1_000,
     maxPathBytes: 1_024,
     maxDeploymentBytes: 16 * 1_024 * 1_024,
     maxArtifactBytes: 128 * 1_024 * 1_024,
+    maxSourceFileBytes: 2 * 1_024 * 1_024,
+    maxSourceBytes: 32 * 1_024 * 1_024,
     maxTotalBytes: 256 * 1_024 * 1_024,
 });
 export function resolveDeploymentBundleLimits(options = {}) {

package/dist/bundles/types.d.ts

@@ -9,17 +9,36 @@ export interface ProtocolDeploymentBundleDeployment extends ProtocolDeploymentBu
 export interface ProtocolDeploymentBundleArtifact extends ProtocolDeploymentBundleFile {
     readonly runtime: 'node' | 'python';
 }
+export interface ProtocolDeploymentBundleSourceRevision {
+    readonly kind: 'git';
+    readonly commit: string;
+    readonly dirty: boolean;
+    /** Checked-out branch at build time; absent for detached HEADs. */
+    readonly branch?: string;
+}
+export interface ProtocolDeploymentBundleSource {
+    /** Directory within the closed bundle that contains project-relative source files. */
+    readonly root: string;
+    /** Project-relative API module used to build the deployment. */
+    readonly entrypoint: string;
+    readonly files: readonly ProtocolDeploymentBundleFile[];
+    readonly revision?: ProtocolDeploymentBundleSourceRevision;
+}
 export interface ProtocolDeploymentBundleManifest {
     readonly kind: 'hypequery-deployment-bundle';
     readonly version: 1;
     readonly deployment: ProtocolDeploymentBundleDeployment;
     readonly artifacts: readonly ProtocolDeploymentBundleArtifact[];
+    readonly source?: ProtocolDeploymentBundleSource;
 }
 export interface ProtocolDeploymentBundleLimits {
     readonly maxArtifacts: number;
+    readonly maxSourceFiles: number;
     readonly maxPathBytes: number;
     readonly maxDeploymentBytes: number;
     readonly maxArtifactBytes: number;
+    readonly maxSourceFileBytes: number;
+    readonly maxSourceBytes: number;
     readonly maxTotalBytes: number;
 }
 /**

package/dist/bundles/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/bundles/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,kCAAmC,SAAQ,4BAA4B;IACtF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,gCAAiC,SAAQ,4BAA4B;IACpF,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,CAAC;CACrC;AAED,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,IAAI,EAAE,6BAA6B,CAAC;IAC7C,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,QAAQ,CAAC,UAAU,EAAE,kCAAkC,CAAC;IACxD,QAAQ,CAAC,SAAS,EAAE,SAAS,gCAAgC,EAAE,CAAC;CACjE;AAED,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED;;;;;GAKG;AACH,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,8BAA8B,CAAC,CAAC;CAC3D;AAED,MAAM,MAAM,iCAAiC,GACzC,gBAAgB,GAChB,yBAAyB,GACzB,2BAA2B,GAC3B,yBAAyB,GACzB,wBAAwB,GACxB,6BAA6B,GAC7B,0BAA0B,GAC1B,qBAAqB,GACrB,yBAAyB,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/bundles/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,kCAAmC,SAAQ,4BAA4B;IACtF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,gCAAiC,SAAQ,4BAA4B;IACpF,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,CAAC;CACrC;AAED,MAAM,WAAW,sCAAsC;IACrD,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,mEAAmE;IACnE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,8BAA8B;IAC7C,sFAAsF;IACtF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gEAAgE;IAChE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,SAAS,4BAA4B,EAAE,CAAC;IACxD,QAAQ,CAAC,QAAQ,CAAC,EAAE,sCAAsC,CAAC;CAC5D;AAED,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,IAAI,EAAE,6BAA6B,CAAC;IAC7C,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,QAAQ,CAAC,UAAU,EAAE,kCAAkC,CAAC;IACxD,QAAQ,CAAC,SAAS,EAAE,SAAS,gCAAgC,EAAE,CAAC;IAChE,QAAQ,CAAC,MAAM,CAAC,EAAE,8BAA8B,CAAC;CAClD;AAED,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED;;;;;GAKG;AACH,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,8BAA8B,CAAC,CAAC;CAC3D;AAED,MAAM,MAAM,iCAAiC,GACzC,gBAAgB,GAChB,yBAAyB,GACzB,2BAA2B,GAC3B,yBAAyB,GACzB,wBAAwB,GACxB,6BAA6B,GAC7B,0BAA0B,GAC1B,qBAAqB,GACrB,yBAAyB,CAAC"}

package/dist/bundles/validate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/bundles/validate.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAIV,gCAAgC,EAChC,+BAA+B,EAChC,MAAM,YAAY,CAAC;AA4HpB,wBAAgB,wCAAwC,CACtD,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,+BAAoC,GAC5C,gCAAgC,CAwClC"}
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/bundles/validate.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAIV,gCAAgC,EAChC,+BAA+B,EAGhC,MAAM,YAAY,CAAC;AAmPpB,wBAAgB,wCAAwC,CACtD,KAAK,EAAE,OAAO,EACd,OAAO,GAAE,+BAAoC,GAC5C,gCAAgC,CA+ClC"}

package/dist/bundles/validate.js

@@ -2,6 +2,7 @@ import { bundleError } from './errors.js';
 import { resolveDeploymentBundleLimits } from './limits.js';
 const textEncoder = new TextEncoder();
 const SHA256_PATTERN = /^[0-9a-f]{64}$/;
+const GIT_COMMIT_PATTERN = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
 const PATH_SEGMENT_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
 const WINDOWS_RESERVED_NAME = /^(?:CON|PRN|AUX|NUL|COM[1-9]|LPT[1-9])(?:\.|$)/i;
 function requireRecord(input, path) {
@@ -44,8 +45,8 @@ function requireArray(input, path, maxItems) {
     }
     return input;
 }
-function exactFields(value, required, path) {
-    const allowed = new Set(required);
+function exactFields(value, required, path, optional = []) {
+    const allowed = new Set([...required, ...optional]);
     for (const key of Object.keys(value)) {
         if (!allowed.has(key))
             bundleError('HQ_BUNDLE_UNKNOWN_FIELD', `${path}.${key}`);
@@ -65,8 +66,8 @@ function digest(value, path) {
         bundleError('HQ_BUNDLE_INVALID_VALUE', path);
     return value;
 }
-function byteLength(value, path, maximum) {
-    if (!Number.isSafeInteger(value) || value < 1) {
+function byteLength(value, path, maximum, allowEmpty = false) {
+    if (!Number.isSafeInteger(value) || value < (allowEmpty ? 0 : 1)) {
         bundleError('HQ_BUNDLE_INVALID_VALUE', path);
     }
     if (value > maximum)
@@ -112,10 +113,102 @@ function validateArtifact(input, path, limits) {
         byteLength: byteLength(value.byteLength, `${path}.byteLength`, limits.maxArtifactBytes),
     });
 }
+function validateSourceRevision(input, path, limits) {
+    const value = requireRecord(input, path);
+    exactFields(value, ['kind', 'commit', 'dirty'], path, ['branch']);
+    if (value.kind !== 'git') {
+        if (typeof value.kind !== 'string')
+            bundleError('HQ_BUNDLE_TYPE', `${path}.kind`);
+        bundleError('HQ_BUNDLE_INVALID_VALUE', `${path}.kind`);
+    }
+    if (typeof value.commit !== 'string')
+        bundleError('HQ_BUNDLE_TYPE', `${path}.commit`);
+    if (!GIT_COMMIT_PATTERN.test(value.commit)) {
+        bundleError('HQ_BUNDLE_INVALID_VALUE', `${path}.commit`);
+    }
+    if (typeof value.dirty !== 'boolean')
+        bundleError('HQ_BUNDLE_TYPE', `${path}.dirty`);
+    let branch;
+    if (value.branch !== undefined) {
+        if (typeof value.branch !== 'string')
+            bundleError('HQ_BUNDLE_TYPE', `${path}.branch`);
+        if (textEncoder.encode(value.branch).byteLength > limits.maxPathBytes) {
+            bundleError('HQ_BUNDLE_TOO_LARGE', `${path}.branch`);
+        }
+        const invalidCharacter = [...value.branch].some(character => {
+            const code = character.charCodeAt(0);
+            return code <= 0x20 || code === 0x7f || '~^:?*[\\'.includes(character);
+        });
+        const segments = value.branch.split('/');
+        if (!value.branch || value.branch === '@' || value.branch.startsWith('-')
+            || value.branch.startsWith('/') || value.branch.endsWith('/')
+            || value.branch.endsWith('.') || value.branch.includes('//')
+            || value.branch.includes('..') || value.branch.includes('@{')
+            || invalidCharacter
+            || segments.some(segment => segment.startsWith('.') || segment.endsWith('.lock'))) {
+            bundleError('HQ_BUNDLE_INVALID_VALUE', `${path}.branch`);
+        }
+        branch = value.branch;
+    }
+    return freezeRecord({
+        kind: 'git',
+        commit: value.commit,
+        dirty: value.dirty,
+        ...(branch ? { branch } : {}),
+    });
+}
+function validateSource(input, path, limits) {
+    const value = requireRecord(input, path);
+    exactFields(value, ['root', 'entrypoint', 'files'], path, ['revision']);
+    const root = relativePath(value.root, `${path}.root`, limits.maxPathBytes);
+    const entrypoint = relativePath(value.entrypoint, `${path}.entrypoint`, limits.maxPathBytes);
+    const files = Object.freeze(requireArray(value.files, `${path}.files`, limits.maxSourceFiles)
+        .map((inputFile, index) => {
+        const filePath = `${path}.files[${index}]`;
+        const file = requireRecord(inputFile, filePath);
+        exactFields(file, ['path', 'sha256', 'byteLength'], filePath);
+        return freezeRecord({
+            path: relativePath(file.path, `${filePath}.path`, limits.maxPathBytes),
+            sha256: digest(file.sha256, `${filePath}.sha256`),
+            byteLength: byteLength(file.byteLength, `${filePath}.byteLength`, limits.maxSourceFileBytes, true),
+        });
+    }));
+    if (files.length < 1 || !files.some(file => file.path === entrypoint)) {
+        bundleError('HQ_BUNDLE_INVALID_REFERENCE', `${path}.entrypoint`);
+    }
+    const paths = files.map(file => file.path);
+    if (new Set(paths).size !== paths.length
+        || new Set(paths.map(filePath => filePath.toLowerCase())).size !== paths.length) {
+        bundleError('HQ_BUNDLE_INVALID_REFERENCE', `${path}.files`);
+    }
+    const sortedPaths = [...paths].sort();
+    if (paths.some((filePath, index) => filePath !== sortedPaths[index])) {
+        bundleError('HQ_BUNDLE_INVALID_VALUE', `${path}.files`);
+    }
+    const sourceBytes = files.reduce((total, file) => total + file.byteLength, 0);
+    if (!Number.isSafeInteger(sourceBytes) || sourceBytes > limits.maxSourceBytes) {
+        bundleError('HQ_BUNDLE_TOO_LARGE', path);
+    }
+    return freezeRecord({
+        root,
+        entrypoint,
+        files,
+        ...(value.revision === undefined
+            ? {}
+            : { revision: validateSourceRevision(value.revision, `${path}.revision`, limits) }),
+    });
+}
+function hasTreeCollision(paths) {
+    const normalized = new Set(paths.map(bundlePath => bundlePath.toLowerCase()));
+    return [...normalized].some((bundlePath) => {
+        const segments = bundlePath.split('/');
+        return segments.some((_, index) => index > 0 && normalized.has(segments.slice(0, index).join('/')));
+    });
+}
 export function validateProtocolDeploymentBundleManifest(input, options = {}) {
     const limits = resolveDeploymentBundleLimits(options);
     const value = requireRecord(input, '$');
-    exactFields(value, ['kind', 'version', 'deployment', 'artifacts'], '$');
+    exactFields(value, ['kind', 'version', 'deployment', 'artifacts'], '$', ['source']);
     if (value.kind !== 'hypequery-deployment-bundle') {
         if (typeof value.kind !== 'string')
             bundleError('HQ_BUNDLE_TYPE', '$.kind');
@@ -129,10 +222,15 @@ export function validateProtocolDeploymentBundleManifest(input, options = {}) {
     const deployment = validateDeployment(value.deployment, '$.deployment', limits);
     const artifacts = Object.freeze(requireArray(value.artifacts, '$.artifacts', limits.maxArtifacts)
         .map((artifact, index) => validateArtifact(artifact, `$.artifacts[${index}]`, limits)));
-    const paths = [deployment.path, ...artifacts.map(artifact => artifact.path)];
+    const source = value.source === undefined
+        ? undefined
+        : validateSource(value.source, '$.source', limits);
+    const sourcePaths = source?.files.map(file => `${source.root}/${file.path}`) ?? [];
+    const paths = [deployment.path, ...artifacts.map(artifact => artifact.path), ...sourcePaths];
     if (new Set(paths).size !== paths.length
-        || new Set(paths.map(bundlePath => bundlePath.toLowerCase())).size !== paths.length) {
-        bundleError('HQ_BUNDLE_INVALID_REFERENCE', '$.artifacts');
+        || new Set(paths.map(bundlePath => bundlePath.toLowerCase())).size !== paths.length
+        || hasTreeCollision(paths)) {
+        bundleError('HQ_BUNDLE_INVALID_REFERENCE', '$');
     }
     if (new Set(artifacts.map(artifact => artifact.sha256)).size !== artifacts.length) {
         bundleError('HQ_BUNDLE_INVALID_REFERENCE', '$.artifacts');
@@ -142,7 +240,8 @@ export function validateProtocolDeploymentBundleManifest(input, options = {}) {
         bundleError('HQ_BUNDLE_INVALID_VALUE', '$.artifacts');
     }
     const totalBytes = deployment.byteLength
-        + artifacts.reduce((total, artifact) => total + artifact.byteLength, 0);
+        + artifacts.reduce((total, artifact) => total + artifact.byteLength, 0)
+        + (source?.files.reduce((total, file) => total + file.byteLength, 0) ?? 0);
     if (!Number.isSafeInteger(totalBytes) || totalBytes > limits.maxTotalBytes) {
         bundleError('HQ_BUNDLE_TOO_LARGE', '$');
     }
@@ -151,5 +250,6 @@ export function validateProtocolDeploymentBundleManifest(input, options = {}) {
         version: 1,
         deployment,
         artifacts,
+        ...(source ? { source } : {}),
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypequery/protocol",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "description": "Public contracts and TypeScript reference implementation for portable Hypequery artifacts",
   "license": "Apache-2.0",
   "type": "module",