@hypequery/deployment 0.0.0-canary-20260719130627

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are advised to review the applicable
+      documentation for the specific language governing permissions and
+      limitations under each license.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2024 hypequery
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License. 

package/README.md

@@ -0,0 +1,68 @@
+# @hypequery/deployment
+
+Provider-neutral verification and receiving-side intake for Hypequery deployment
+bundles.
+
+The package accepts the authenticated multipart transport emitted by
+`hypequery deploy`, reconstructs only manifest-declared files in temporary
+storage, and revalidates the release, bundle manifest, file hashes, deployment
+identity, and runtime references before handing the submission to a store. It
+does not activate or execute a release.
+
+## Intake adapters
+
+`createDeploymentIntake` is independent of an HTTP framework. Adapt an incoming
+request into a case-insensitive header record and an `AsyncIterable<Uint8Array>`
+body, then map the returned status, headers, and JSON body onto the framework's
+response.
+
+Three provider-owned adapters are required:
+
+- `DeploymentAuthenticator` validates the bearer token before request bytes are
+  consumed;
+- `DeploymentAuthorizer` authorizes the canonical project and environment once
+  the release envelope has been validated;
+- `DeploymentSubmissionStore` atomically persists or recognizes the fully
+  verified release identity.
+
+The store receives a verified bundle whose directory is temporary. It must copy
+or persist every required byte before `accept` resolves. Returning
+`already-exists` is valid only for an authorized replay of the same deterministic
+release identity.
+
+```ts
+import { createDeploymentIntake } from '@hypequery/deployment';
+
+const intake = createDeploymentIntake({
+  authenticator: {
+    async authenticate({ token }) {
+      return authenticateToken(token);
+    },
+  },
+  authorizer: {
+    async authorize({ principal, target }) {
+      return canDeploy(principal, target.project, target.environment);
+    },
+  },
+  store: {
+    async accept(submission) {
+      return persistVerifiedSubmission(submission);
+    },
+  },
+});
+```
+
+New submissions return HTTP status `202` and `status: "accepted"`; verified
+idempotent replays return HTTP status `200` and `status: "already-exists"`.
+Malformed, unauthorized, oversized, or inconsistent submissions fail closed
+with a bounded JSON error response. Temporary upload data is removed on success
+and failure.
+
+## Bundle verification
+
+`verifyDeploymentBundle(directory)` verifies a closed bundle directly from the
+filesystem. It rejects symbolic links and undeclared entries, enforces byte
+limits, recomputes every hash and identity, and returns an immutable verified
+snapshot.
+
+The package is ESM-only and requires Node.js 20 or newer.

package/dist/bundle.d.ts

@@ -0,0 +1,11 @@
+import { type ProtocolDeploymentBundleManifest, type ProtocolDeploymentContract } from '@hypequery/protocol';
+export declare const DEPLOYMENT_BUNDLE_MANIFEST = "bundle.json";
+export declare const DEPLOYMENT_BUNDLE_CONTRACT = "deployment.json";
+export interface VerifiedDeploymentBundle {
+    readonly directory: string;
+    readonly manifest: ProtocolDeploymentBundleManifest;
+    readonly identity: string;
+    readonly contract: ProtocolDeploymentContract;
+}
+export declare function verifyDeploymentBundle(bundleDirectory: string): Promise<VerifiedDeploymentBundle>;
+//# sourceMappingURL=bundle.d.ts.map

package/dist/bundle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle.d.ts","sourceRoot":"","sources":["../src/bundle.ts"],"names":[],"mappings":"AAQA,OAAO,EAKL,KAAK,gCAAgC,EACrC,KAAK,0BAA0B,EAChC,MAAM,qBAAqB,CAAC;AAE7B,eAAO,MAAM,0BAA0B,gBAAgB,CAAC;AACxD,eAAO,MAAM,0BAA0B,oBAAoB,CAAC;AAE5D,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,gCAAgC,CAAC;IACpD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,0BAA0B,CAAC;CAC/C;AAoKD,wBAAsB,sBAAsB,CAC1C,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,wBAAwB,CAAC,CA2DnC"}

package/dist/bundle.js

@@ -0,0 +1,193 @@
+import { createHash } from 'node:crypto';
+import { constants, lstat, open, readdir, } from 'node:fs/promises';
+import path from 'node:path';
+import { DEFAULT_PROTOCOL_DEPLOYMENT_BUNDLE_LIMITS, prepareProtocolDeploymentBundleManifest, prepareProtocolDeploymentContract, } from '@hypequery/protocol';
+export const DEPLOYMENT_BUNDLE_MANIFEST = 'bundle.json';
+export const DEPLOYMENT_BUNDLE_CONTRACT = 'deployment.json';
+const utf8Decoder = new TextDecoder('utf-8', { fatal: true });
+const utf8Encoder = new TextEncoder();
+function errorCode(error) {
+    return typeof error === 'object' && error !== null && 'code' in error
+        ? String(error.code)
+        : undefined;
+}
+function sha256(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+async function readBoundedRegularFile(root, relativePath, maximum) {
+    const absolutePath = path.join(root, ...relativePath.split('/'));
+    let handle;
+    try {
+        const initialStat = await lstat(absolutePath);
+        if (initialStat.isSymbolicLink()) {
+            throw new Error(`Bundle entry must not be a symbolic link: ${relativePath}`);
+        }
+        if (!initialStat.isFile()) {
+            throw new Error(`Bundle entry is not a regular file: ${relativePath}`);
+        }
+        if (initialStat.size < 1 || initialStat.size > maximum) {
+            throw new Error(`Bundle entry exceeds its byte limit: ${relativePath}`);
+        }
+        handle = await open(absolutePath, constants.O_RDONLY | constants.O_NOFOLLOW);
+        const stat = await handle.stat();
+        if (!stat.isFile())
+            throw new Error(`Bundle entry is not a regular file: ${relativePath}`);
+        if (stat.size < 1 || stat.size > maximum) {
+            throw new Error(`Bundle entry exceeds its byte limit: ${relativePath}`);
+        }
+        return await handle.readFile();
+    }
+    catch (error) {
+        if (errorCode(error) === 'ELOOP') {
+            throw new Error(`Bundle entry must not be a symbolic link: ${relativePath}`);
+        }
+        throw error;
+    }
+    finally {
+        await handle?.close();
+    }
+}
+function expectedDirectories(files) {
+    const result = new Set();
+    for (const file of files) {
+        const segments = file.split('/');
+        for (let index = 1; index < segments.length; index += 1) {
+            result.add(segments.slice(0, index).join('/'));
+        }
+    }
+    return result;
+}
+async function verifyExactEntries(root, manifest) {
+    const expectedFiles = new Set([
+        DEPLOYMENT_BUNDLE_MANIFEST,
+        manifest.deployment.path,
+        ...manifest.artifacts.map(artifact => artifact.path),
+    ]);
+    const expectedDirectoryPaths = expectedDirectories([...expectedFiles]);
+    const seenFiles = new Set();
+    const seenDirectories = new Set();
+    async function visit(relativeDirectory) {
+        const absoluteDirectory = relativeDirectory
+            ? path.join(root, ...relativeDirectory.split('/'))
+            : root;
+        const names = await readdir(absoluteDirectory);
+        names.sort();
+        for (const name of names) {
+            const relativePath = relativeDirectory ? `${relativeDirectory}/${name}` : name;
+            const stat = await lstat(path.join(absoluteDirectory, name));
+            if (stat.isSymbolicLink()) {
+                throw new Error(`Bundle entries must not be symbolic links: ${relativePath}`);
+            }
+            if (stat.isDirectory()) {
+                if (!expectedDirectoryPaths.has(relativePath)) {
+                    throw new Error(`Deployment bundle contains an undeclared directory: ${relativePath}`);
+                }
+                seenDirectories.add(relativePath);
+                await visit(relativePath);
+            }
+            else if (stat.isFile()) {
+                if (!expectedFiles.has(relativePath)) {
+                    throw new Error(`Deployment bundle contains an undeclared file: ${relativePath}`);
+                }
+                seenFiles.add(relativePath);
+            }
+            else {
+                throw new Error(`Bundle entry is not a regular file or directory: ${relativePath}`);
+            }
+        }
+    }
+    await visit('');
+    const missingFiles = [...expectedFiles].filter(file => !seenFiles.has(file)).sort();
+    if (missingFiles.length > 0) {
+        throw new Error(`Deployment bundle is missing files: ${missingFiles.join(', ')}`);
+    }
+    const missingDirectories = [...expectedDirectoryPaths]
+        .filter(directory => !seenDirectories.has(directory)).sort();
+    if (missingDirectories.length > 0) {
+        throw new Error(`Deployment bundle is missing directories: ${missingDirectories.join(', ')}`);
+    }
+}
+function verifyFile(bytes, file) {
+    if (bytes.byteLength !== file.byteLength) {
+        throw new Error(`Bundle entry byte length does not match the manifest: ${file.path}`);
+    }
+    if (sha256(bytes) !== file.sha256) {
+        throw new Error(`Bundle entry SHA-256 does not match the manifest: ${file.path}`);
+    }
+}
+function requireClosedContractArtifactSet(contract) {
+    const referenced = new Map();
+    for (const query of contract.queries) {
+        if (query.implementation.kind === 'runtime-reference') {
+            referenced.set(query.implementation.artifactSha256, query.implementation.runtime);
+        }
+    }
+    if (referenced.size !== contract.artifacts.length) {
+        throw new Error('Deployment contract contains missing or unreferenced runtime artifacts.');
+    }
+    for (const artifact of contract.artifacts) {
+        if (referenced.get(artifact.artifactSha256) !== artifact.runtime) {
+            throw new Error(`Deployment runtime artifact ${artifact.artifactSha256} is not referenced by a named query.`);
+        }
+    }
+}
+function verifyRuntimeReferences(contract, artifacts) {
+    requireClosedContractArtifactSet(contract);
+    const declared = new Map(contract.artifacts.map(artifact => [artifact.artifactSha256, artifact.runtime]));
+    if (declared.size !== artifacts.length) {
+        throw new Error('Bundle runtime artifacts do not match the deployment contract.');
+    }
+    for (const artifact of artifacts) {
+        if (declared.get(artifact.sha256) !== artifact.runtime) {
+            throw new Error(`Bundle artifact ${artifact.sha256} does not match a deployment runtime reference.`);
+        }
+    }
+}
+export async function verifyDeploymentBundle(bundleDirectory) {
+    const root = path.resolve(bundleDirectory);
+    const rootStat = await lstat(root);
+    if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) {
+        throw new Error(`Deployment bundle path must be a regular directory: ${bundleDirectory}`);
+    }
+    const manifestBytes = await readBoundedRegularFile(root, DEPLOYMENT_BUNDLE_MANIFEST, 1024 * 1024);
+    let input;
+    try {
+        input = JSON.parse(utf8Decoder.decode(manifestBytes));
+    }
+    catch (error) {
+        throw new Error(`Invalid deployment bundle manifest: ${path.join(root, DEPLOYMENT_BUNDLE_MANIFEST)}\n\n`
+            + (error instanceof Error ? error.message : String(error)));
+    }
+    const preparedManifest = prepareProtocolDeploymentBundleManifest(input);
+    const expectedManifestBytes = utf8Encoder.encode(`${preparedManifest.canonical}\n`);
+    if (!Buffer.from(manifestBytes).equals(Buffer.from(expectedManifestBytes))) {
+        throw new Error('Deployment bundle manifest must contain canonical JSON followed by one newline.');
+    }
+    await verifyExactEntries(root, preparedManifest.manifest);
+    const deployment = preparedManifest.manifest.deployment;
+    const deploymentBytes = await readBoundedRegularFile(root, deployment.path, DEFAULT_PROTOCOL_DEPLOYMENT_BUNDLE_LIMITS.maxDeploymentBytes);
+    verifyFile(deploymentBytes, deployment);
+    let contractInput;
+    try {
+        contractInput = JSON.parse(utf8Decoder.decode(deploymentBytes));
+    }
+    catch (error) {
+        throw new Error(`Invalid deployment JSON in bundle: ${deployment.path}\n\n`
+            + (error instanceof Error ? error.message : String(error)));
+    }
+    const preparedContract = prepareProtocolDeploymentContract(contractInput);
+    if (preparedContract.identity !== deployment.identity) {
+        throw new Error('Deployment identity does not match the bundle manifest.');
+    }
+    for (const artifact of preparedManifest.manifest.artifacts) {
+        const bytes = await readBoundedRegularFile(root, artifact.path, DEFAULT_PROTOCOL_DEPLOYMENT_BUNDLE_LIMITS.maxArtifactBytes);
+        verifyFile(bytes, artifact);
+    }
+    verifyRuntimeReferences(preparedContract.contract, preparedManifest.manifest.artifacts);
+    return Object.freeze({
+        directory: root,
+        manifest: preparedManifest.manifest,
+        identity: preparedManifest.identity,
+        contract: preparedContract.contract,
+    });
+}

package/dist/errors.d.ts

@@ -0,0 +1,13 @@
+export type DeploymentIntakeErrorCode = 'HQ_INTAKE_BAD_REQUEST' | 'HQ_INTAKE_UNAUTHENTICATED' | 'HQ_INTAKE_FORBIDDEN' | 'HQ_INTAKE_TOO_LARGE' | 'HQ_INTAKE_CONFLICT' | 'HQ_INTAKE_INTERNAL';
+export declare class DeploymentIntakeError extends Error {
+    readonly code: DeploymentIntakeErrorCode;
+    readonly status: number;
+    readonly expose: boolean;
+    constructor(code: DeploymentIntakeErrorCode, message: string, options?: {
+        readonly expose?: boolean;
+        readonly cause?: unknown;
+    });
+}
+export declare function badRequest(message: string, cause?: unknown): DeploymentIntakeError;
+export declare function tooLarge(message: string): DeploymentIntakeError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,yBAAyB,GACjC,uBAAuB,GACvB,2BAA2B,GAC3B,qBAAqB,GACrB,qBAAqB,GACrB,oBAAoB,GACpB,oBAAoB,CAAC;AAWzB,qBAAa,qBAAsB,SAAQ,KAAK;IAC9C,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAC;IACzC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;gBAGvB,IAAI,EAAE,yBAAyB,EAC/B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE;QAAE,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAO;CAQxE;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,qBAAqB,CAElF;AAED,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,qBAAqB,CAE/D"}

package/dist/errors.js

@@ -0,0 +1,26 @@
+const ERROR_STATUS = Object.freeze({
+    HQ_INTAKE_BAD_REQUEST: 400,
+    HQ_INTAKE_UNAUTHENTICATED: 401,
+    HQ_INTAKE_FORBIDDEN: 403,
+    HQ_INTAKE_TOO_LARGE: 413,
+    HQ_INTAKE_CONFLICT: 409,
+    HQ_INTAKE_INTERNAL: 500,
+});
+export class DeploymentIntakeError extends Error {
+    code;
+    status;
+    expose;
+    constructor(code, message, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = 'DeploymentIntakeError';
+        this.code = code;
+        this.status = ERROR_STATUS[code];
+        this.expose = options.expose ?? this.status < 500;
+    }
+}
+export function badRequest(message, cause) {
+    return new DeploymentIntakeError('HQ_INTAKE_BAD_REQUEST', message, { cause });
+}
+export function tooLarge(message) {
+    return new DeploymentIntakeError('HQ_INTAKE_TOO_LARGE', message);
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { DEPLOYMENT_BUNDLE_CONTRACT, DEPLOYMENT_BUNDLE_MANIFEST, verifyDeploymentBundle, } from './bundle.js';
+export type { VerifiedDeploymentBundle } from './bundle.js';
+export { DeploymentIntakeError, } from './errors.js';
+export type { DeploymentIntakeErrorCode } from './errors.js';
+export { createDeploymentIntake, } from './intake.js';
+export { DEFAULT_DEPLOYMENT_INTAKE_LIMITS, resolveDeploymentIntakeLimits, } from './limits.js';
+export type { DeploymentIntakeLimits } from './limits.js';
+export type { DeploymentAuthenticationInput, DeploymentAuthenticator, DeploymentAuthorizationInput, DeploymentAuthorizer, DeploymentIntake, DeploymentIntakeOptions, DeploymentIntakeRequest, DeploymentIntakeResponse, DeploymentSubmissionResponse, DeploymentSubmissionStore, VerifiedDeploymentSubmission, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,0BAA0B,EAC1B,0BAA0B,EAC1B,sBAAsB,GACvB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,EACL,qBAAqB,GACtB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,yBAAyB,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EACL,sBAAsB,GACvB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,gCAAgC,EAChC,6BAA6B,GAC9B,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAC1D,YAAY,EACV,6BAA6B,EAC7B,uBAAuB,EACvB,4BAA4B,EAC5B,oBAAoB,EACpB,gBAAgB,EAChB,uBAAuB,EACvB,uBAAuB,EACvB,wBAAwB,EACxB,4BAA4B,EAC5B,yBAAyB,EACzB,4BAA4B,GAC7B,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { DEPLOYMENT_BUNDLE_CONTRACT, DEPLOYMENT_BUNDLE_MANIFEST, verifyDeploymentBundle, } from './bundle.js';
+export { DeploymentIntakeError, } from './errors.js';
+export { createDeploymentIntake, } from './intake.js';
+export { DEFAULT_DEPLOYMENT_INTAKE_LIMITS, resolveDeploymentIntakeLimits, } from './limits.js';

package/dist/intake.d.ts

@@ -0,0 +1,3 @@
+import type { DeploymentIntake, DeploymentIntakeOptions } from './types.js';
+export declare function createDeploymentIntake<Principal>(options: DeploymentIntakeOptions<Principal>): DeploymentIntake;
+//# sourceMappingURL=intake.d.ts.map

package/dist/intake.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"intake.d.ts","sourceRoot":"","sources":["../src/intake.ts"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EACV,gBAAgB,EAChB,uBAAuB,EAIxB,MAAM,YAAY,CAAC;AAoSpB,wBAAgB,sBAAsB,CAAC,SAAS,EAC9C,OAAO,EAAE,uBAAuB,CAAC,SAAS,CAAC,GAC1C,gBAAgB,CA6HlB"}

package/dist/intake.js

@@ -0,0 +1,340 @@
+import { createHash } from 'node:crypto';
+import { mkdir, mkdtemp, open, rm, writeFile, } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { prepareProtocolDeploymentBundleManifest, prepareProtocolDeploymentReleaseEnvelope, } from '@hypequery/protocol';
+import { DEPLOYMENT_BUNDLE_MANIFEST, verifyDeploymentBundle, } from './bundle.js';
+import { badRequest, DeploymentIntakeError, tooLarge, } from './errors.js';
+import { resolveDeploymentIntakeLimits } from './limits.js';
+import { BoundedMultipartReader, } from './multipart.js';
+const BOUNDARY_PATTERN = /^[A-Za-z0-9-]{1,70}$/;
+const DIGEST_PATTERN = /^[0-9a-f]{64}$/;
+const textDecoder = new TextDecoder('utf-8', { fatal: true });
+function requestHeader(headers, expectedName) {
+    const matches = Object.entries(headers)
+        .filter(([name, value]) => value !== undefined && name.toLowerCase() === expectedName)
+        .map(([, value]) => value);
+    if (matches.length > 1)
+        throw badRequest(`Duplicate ${expectedName} request header.`);
+    return matches[0];
+}
+function requireIdentityHeader(headers, name) {
+    const value = requestHeader(headers, name);
+    if (!value || !DIGEST_PATTERN.test(value)) {
+        throw badRequest(`The ${name} request header is invalid.`);
+    }
+    return value;
+}
+function bearerToken(headers) {
+    const authorization = requestHeader(headers, 'authorization');
+    const token = authorization?.startsWith('Bearer ') ? authorization.slice(7) : '';
+    if (token.length < 1 || token.length > 4096 || token.trim() !== token
+        || [...token].some(character => {
+            const code = character.charCodeAt(0);
+            return code < 0x21 || code > 0x7e;
+        })) {
+        throw new DeploymentIntakeError('HQ_INTAKE_UNAUTHENTICATED', 'A valid bearer credential is required.');
+    }
+    return token;
+}
+function contentLength(headers, maximum) {
+    const input = requestHeader(headers, 'content-length');
+    if (!input || !/^[1-9][0-9]*$/.test(input)) {
+        throw badRequest('An exact Content-Length request header is required.');
+    }
+    const value = Number(input);
+    if (!Number.isSafeInteger(value))
+        throw tooLarge('The deployment request is too large.');
+    if (value > maximum)
+        throw tooLarge('The deployment request exceeds its byte limit.');
+    return value;
+}
+function multipartBoundary(headers) {
+    const contentType = requestHeader(headers, 'content-type');
+    const match = contentType?.match(/^multipart\/form-data; boundary=([^; ]+)$/);
+    if (!match || !BOUNDARY_PATTERN.test(match[1])) {
+        throw badRequest('Content-Type must declare a valid multipart boundary.');
+    }
+    return match[1];
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted)
+        throw badRequest('The deployment request was aborted.', signal.reason);
+}
+async function bufferedPart(reader, maximum) {
+    const chunks = [];
+    const result = await reader.readPartBody(maximum, chunk => {
+        chunks.push(Buffer.from(chunk));
+    });
+    return Object.freeze({ bytes: Buffer.concat(chunks, result.byteLength), final: result.final });
+}
+function requirePart(headers, expected) {
+    if (headers.name !== expected.name
+        || headers.filename !== expected.filename
+        || headers.contentType !== expected.contentType
+        || headers.bundlePath !== expected.bundlePath) {
+        throw badRequest('Multipart parts do not match the deployment submission contract.');
+    }
+}
+function decodeJson(bytes, description) {
+    try {
+        return JSON.parse(textDecoder.decode(bytes));
+    }
+    catch (error) {
+        throw badRequest(`${description} is not valid UTF-8 JSON.`, error);
+    }
+}
+function requireReconstructablePaths(manifest) {
+    const files = [
+        manifest.manifest.deployment.path,
+        ...manifest.manifest.artifacts.map(artifact => artifact.path),
+    ];
+    const fileSet = new Set(files);
+    if (fileSet.has(DEPLOYMENT_BUNDLE_MANIFEST)) {
+        throw badRequest('The bundle manifest path is reserved.');
+    }
+    for (const file of files) {
+        const segments = file.split('/');
+        if (file.includes('\\')
+            || segments.some(segment => segment === '' || segment === '.' || segment === '..')) {
+            throw badRequest('Bundle file paths must be safe relative paths.');
+        }
+        for (let index = 1; index < segments.length; index += 1) {
+            if (fileSet.has(segments.slice(0, index).join('/'))) {
+                throw badRequest('A bundle file path cannot also be a parent directory.');
+            }
+        }
+    }
+}
+async function readRelease(reader, maximum) {
+    requirePart(await reader.readPartHeaders(), {
+        name: 'release',
+        filename: 'release.json',
+        contentType: 'application/json',
+    });
+    const part = await bufferedPart(reader, maximum);
+    if (part.final)
+        throw badRequest('The deployment submission is missing its bundle.');
+    let prepared;
+    try {
+        prepared = prepareProtocolDeploymentReleaseEnvelope(decodeJson(part.bytes, 'The deployment release'));
+    }
+    catch (error) {
+        if (error instanceof DeploymentIntakeError)
+            throw error;
+        throw badRequest('The deployment release is invalid.', error);
+    }
+    if (!part.bytes.equals(Buffer.from(prepared.bytes))) {
+        throw badRequest('The deployment release must use canonical JSON without trailing bytes.');
+    }
+    return prepared;
+}
+async function readManifest(reader, maximum) {
+    requirePart(await reader.readPartHeaders(), {
+        name: 'bundle',
+        filename: DEPLOYMENT_BUNDLE_MANIFEST,
+        contentType: 'application/json',
+        bundlePath: DEPLOYMENT_BUNDLE_MANIFEST,
+    });
+    const part = await bufferedPart(reader, maximum);
+    if (part.final)
+        throw badRequest('The deployment submission is missing bundle files.');
+    let prepared;
+    try {
+        prepared = prepareProtocolDeploymentBundleManifest(decodeJson(part.bytes, 'The deployment bundle manifest'));
+    }
+    catch (error) {
+        if (error instanceof DeploymentIntakeError)
+            throw error;
+        throw badRequest('The deployment bundle manifest is invalid.', error);
+    }
+    const canonical = Buffer.from(`${prepared.canonical}\n`);
+    if (!part.bytes.equals(canonical)) {
+        throw badRequest('The deployment bundle manifest must use canonical JSON followed by one newline.');
+    }
+    requireReconstructablePaths(prepared);
+    return Object.freeze({ prepared, bytes: canonical });
+}
+async function writeChunk(handle, chunk) {
+    let offset = 0;
+    while (offset < chunk.byteLength) {
+        const result = await handle.write(chunk, offset, chunk.byteLength - offset);
+        if (result.bytesWritten < 1)
+            throw new Error('Could not write deployment bundle bytes.');
+        offset += result.bytesWritten;
+    }
+}
+async function receiveBundleFile(reader, root, file, contentType, expectFinal) {
+    requirePart(await reader.readPartHeaders(), {
+        name: 'bundle',
+        filename: path.basename(file.path),
+        contentType,
+        bundlePath: file.path,
+    });
+    const absolutePath = path.resolve(root, ...file.path.split('/'));
+    const relativePath = path.relative(root, absolutePath);
+    if (relativePath === '' || relativePath === '..'
+        || relativePath.startsWith(`..${path.sep}`) || path.isAbsolute(relativePath)) {
+        throw badRequest('Bundle file paths must remain within the temporary bundle directory.');
+    }
+    await mkdir(path.dirname(absolutePath), { recursive: true });
+    const handle = await open(absolutePath, 'wx');
+    const digest = createHash('sha256');
+    let result;
+    try {
+        result = await reader.readPartBody(file.byteLength, async (chunk) => {
+            digest.update(chunk);
+            await writeChunk(handle, chunk);
+        });
+    }
+    finally {
+        await handle.close();
+    }
+    if (result.byteLength !== file.byteLength || digest.digest('hex') !== file.sha256) {
+        throw badRequest(`Uploaded bundle bytes do not match the manifest: ${file.path}`);
+    }
+    if (result.final !== expectFinal) {
+        throw badRequest(expectFinal
+            ? 'The deployment submission contains undeclared bundle parts.'
+            : 'The deployment submission is missing declared bundle parts.');
+    }
+}
+function jsonResponse(status, body, additionalHeaders = {}) {
+    const encoded = `${JSON.stringify(body)}\n`;
+    return Object.freeze({
+        status,
+        headers: Object.freeze({
+            'content-type': 'application/json; charset=utf-8',
+            'content-length': String(Buffer.byteLength(encoded)),
+            'cache-control': 'no-store',
+            ...additionalHeaders,
+        }),
+        body: encoded,
+    });
+}
+function errorResponse(error) {
+    const intakeError = error instanceof DeploymentIntakeError
+        ? error
+        : new DeploymentIntakeError('HQ_INTAKE_INTERNAL', 'The deployment submission could not be processed.', { expose: false, cause: error });
+    const unsafeMessage = intakeError.expose
+        ? intakeError.message
+        : 'The deployment submission could not be processed.';
+    const message = [...unsafeMessage].map(character => {
+        const code = character.codePointAt(0) ?? 0;
+        return code < 0x20 || code === 0x7f ? ' ' : character;
+    }).join('').slice(0, 1024).trim() || 'The deployment submission was rejected.';
+    return jsonResponse(intakeError.status, {
+        error: { code: intakeError.code, message },
+    }, intakeError.status === 401 ? { 'www-authenticate': 'Bearer' } : {});
+}
+async function removeTemporaryDirectory(directory, suppressError = false) {
+    try {
+        await rm(directory, { force: true, recursive: true });
+    }
+    catch (cleanupError) {
+        if (!suppressError) {
+            throw new DeploymentIntakeError('HQ_INTAKE_INTERNAL', 'The deployment submission could not be cleaned up.', { expose: false, cause: cleanupError });
+        }
+    }
+}
+export function createDeploymentIntake(options) {
+    const limits = resolveDeploymentIntakeLimits(options.limits);
+    async function process(request) {
+        throwIfAborted(request.signal);
+        const token = bearerToken(request.headers);
+        const principal = await options.authenticator.authenticate({ token, signal: request.signal });
+        if (principal === null) {
+            throw new DeploymentIntakeError('HQ_INTAKE_UNAUTHENTICATED', 'The bearer credential was not accepted.');
+        }
+        throwIfAborted(request.signal);
+        const releaseHeader = requireIdentityHeader(request.headers, 'x-hypequery-release-identity');
+        const bundleHeader = requireIdentityHeader(request.headers, 'x-hypequery-bundle-identity');
+        const idempotencyKey = requireIdentityHeader(request.headers, 'idempotency-key');
+        const declaredLength = contentLength(request.headers, limits.maxRequestBytes);
+        const boundary = multipartBoundary(request.headers);
+        const reader = new BoundedMultipartReader(request.body, boundary, declaredLength, limits.maxRequestBytes, limits.maxPartHeaderBytes, request.signal);
+        await reader.start();
+        const release = await readRelease(reader, limits.maxReleaseBytes);
+        if (release.identity !== releaseHeader || release.identity !== idempotencyKey
+            || release.release.bundleIdentity !== bundleHeader) {
+            throw badRequest('Deployment release identities do not match the uploaded release.');
+        }
+        const authorized = await options.authorizer.authorize({
+            principal,
+            target: release.release.target,
+            releaseIdentity: release.identity,
+            bundleIdentity: release.release.bundleIdentity,
+            signal: request.signal,
+        });
+        if (!authorized) {
+            throw new DeploymentIntakeError('HQ_INTAKE_FORBIDDEN', 'The caller is not authorized for the deployment target.');
+        }
+        throwIfAborted(request.signal);
+        const manifest = await readManifest(reader, limits.maxManifestBytes);
+        if (manifest.prepared.identity !== bundleHeader
+            || manifest.prepared.identity !== release.release.bundleIdentity) {
+            throw badRequest('Deployment bundle identities do not match the uploaded manifest.');
+        }
+        const temporaryRoot = await mkdtemp(path.join(options.temporaryDirectory ?? tmpdir(), 'hypequery-intake-'));
+        let cleaned = false;
+        try {
+            const bundleRoot = path.join(temporaryRoot, 'bundle');
+            await mkdir(bundleRoot);
+            await writeFile(path.join(bundleRoot, DEPLOYMENT_BUNDLE_MANIFEST), manifest.bytes, { flag: 'wx' });
+            const files = [
+                manifest.prepared.manifest.deployment,
+                ...manifest.prepared.manifest.artifacts,
+            ];
+            for (let index = 0; index < files.length; index += 1) {
+                await receiveBundleFile(reader, bundleRoot, files[index], index === 0 ? 'application/json' : 'application/octet-stream', index === files.length - 1);
+            }
+            await reader.finish();
+            throwIfAborted(request.signal);
+            let bundle;
+            try {
+                bundle = await verifyDeploymentBundle(bundleRoot);
+            }
+            catch (error) {
+                throw badRequest('The reconstructed deployment bundle is invalid.', error);
+            }
+            if (bundle.identity !== manifest.prepared.identity
+                || bundle.identity !== release.release.bundleIdentity) {
+                throw badRequest('The reconstructed deployment bundle identity is inconsistent.');
+            }
+            const status = await options.store.accept(Object.freeze({
+                principal,
+                release: release.release,
+                releaseCanonical: release.canonical,
+                releaseIdentity: release.identity,
+                bundle,
+            }));
+            if (status !== 'accepted' && status !== 'already-exists') {
+                throw new DeploymentIntakeError('HQ_INTAKE_INTERNAL', 'The deployment store returned an invalid status.', { expose: false });
+            }
+            const response = Object.freeze({
+                kind: 'hypequery-deployment-submission',
+                version: 1,
+                status,
+                releaseIdentity: release.identity,
+                bundleIdentity: bundle.identity,
+            });
+            cleaned = true;
+            await removeTemporaryDirectory(temporaryRoot, true);
+            return jsonResponse(status === 'accepted' ? 202 : 200, response);
+        }
+        finally {
+            if (!cleaned)
+                await removeTemporaryDirectory(temporaryRoot, true);
+        }
+    }
+    return Object.freeze({
+        async handle(request) {
+            try {
+                return await process(request);
+            }
+            catch (error) {
+                return errorResponse(error);
+            }
+        },
+    });
+}

package/dist/limits.d.ts

@@ -0,0 +1,9 @@
+export interface DeploymentIntakeLimits {
+    readonly maxRequestBytes: number;
+    readonly maxReleaseBytes: number;
+    readonly maxManifestBytes: number;
+    readonly maxPartHeaderBytes: number;
+}
+export declare const DEFAULT_DEPLOYMENT_INTAKE_LIMITS: Readonly<DeploymentIntakeLimits>;
+export declare function resolveDeploymentIntakeLimits(input?: Partial<DeploymentIntakeLimits>): Readonly<DeploymentIntakeLimits>;
+//# sourceMappingURL=limits.d.ts.map

package/dist/limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"limits.d.ts","sourceRoot":"","sources":["../src/limits.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;CACrC;AAED,eAAO,MAAM,gCAAgC,EAAE,QAAQ,CAAC,sBAAsB,CAK5E,CAAC;AAEH,wBAAgB,6BAA6B,CAC3C,KAAK,GAAE,OAAO,CAAC,sBAAsB,CAAM,GAC1C,QAAQ,CAAC,sBAAsB,CAAC,CAelC"}

package/dist/limits.js

@@ -0,0 +1,22 @@
+import { DEFAULT_PROTOCOL_DEPLOYMENT_BUNDLE_LIMITS } from '@hypequery/protocol';
+export const DEFAULT_DEPLOYMENT_INTAKE_LIMITS = Object.freeze({
+    maxRequestBytes: DEFAULT_PROTOCOL_DEPLOYMENT_BUNDLE_LIMITS.maxTotalBytes + (2 * 1024 * 1024),
+    maxReleaseBytes: 16 * 1024,
+    maxManifestBytes: 1024 * 1024,
+    maxPartHeaderBytes: 8 * 1024,
+});
+export function resolveDeploymentIntakeLimits(input = {}) {
+    const result = { ...DEFAULT_DEPLOYMENT_INTAKE_LIMITS };
+    for (const key of Object.keys(result)) {
+        const value = input[key];
+        if (value === undefined)
+            continue;
+        if (!Number.isSafeInteger(value) || value < 1
+            || value > DEFAULT_DEPLOYMENT_INTAKE_LIMITS[key]) {
+            throw new RangeError(`${key} must be a positive safe integer no greater than `
+                + `${DEFAULT_DEPLOYMENT_INTAKE_LIMITS[key]} (the deployment intake v1 maximum)`);
+        }
+        result[key] = value;
+    }
+    return Object.freeze(result);
+}

package/dist/multipart.d.ts

@@ -0,0 +1,19 @@
+export interface MultipartPartHeaders {
+    readonly name: string;
+    readonly filename: string;
+    readonly contentType: string;
+    readonly bundlePath?: string;
+}
+export declare class BoundedMultipartReader {
+    #private;
+    constructor(body: AsyncIterable<Uint8Array>, boundary: string, declaredLength: number, maximumLength: number, maximumHeaderBytes: number, signal?: AbortSignal);
+    start(): Promise<void>;
+    readPartHeaders(): Promise<MultipartPartHeaders>;
+    /** Returns true when this was the final part. */
+    readPartBody(maximum: number, consume: (chunk: Uint8Array) => void | Promise<void>): Promise<{
+        readonly final: boolean;
+        readonly byteLength: number;
+    }>;
+    finish(): Promise<void>;
+}
+//# sourceMappingURL=multipart.d.ts.map

package/dist/multipart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multipart.d.ts","sourceRoot":"","sources":["../src/multipart.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,qBAAa,sBAAsB;;gBAa/B,IAAI,EAAE,aAAa,CAAC,UAAU,CAAC,EAC/B,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,MAAM,EACtB,aAAa,EAAE,MAAM,EACrB,kBAAkB,EAAE,MAAM,EAC1B,MAAM,CAAC,EAAE,WAAW;IA6EhB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAStB,eAAe,IAAI,OAAO,CAAC,oBAAoB,CAAC;IA4CtD,iDAAiD;IAC3C,YAAY,CAChB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GACnD,OAAO,CAAC;QAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAkC9D,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;CAS9B"}

package/dist/multipart.js

@@ -0,0 +1,199 @@
+import { badRequest, tooLarge } from './errors.js';
+const CRLF = Buffer.from('\r\n');
+const HEADER_NAME = /^[A-Za-z0-9-]+$/;
+const HEADER_VALUE = /^[\x20-\x7e]*$/;
+export class BoundedMultipartReader {
+    #iterator;
+    #boundary;
+    #declaredLength;
+    #maximumLength;
+    #maximumHeaderBytes;
+    #signal;
+    #buffer = Buffer.alloc(0);
+    #received = 0;
+    #finished = false;
+    #started = false;
+    constructor(body, boundary, declaredLength, maximumLength, maximumHeaderBytes, signal) {
+        this.#iterator = body[Symbol.asyncIterator]();
+        this.#boundary = Buffer.from(`--${boundary}`);
+        this.#declaredLength = declaredLength;
+        this.#maximumLength = maximumLength;
+        this.#maximumHeaderBytes = maximumHeaderBytes;
+        this.#signal = signal;
+    }
+    #throwIfAborted() {
+        if (this.#signal?.aborted) {
+            throw badRequest('The deployment request was aborted.', this.#signal.reason);
+        }
+    }
+    async #fill() {
+        while (!this.#finished) {
+            this.#throwIfAborted();
+            let item;
+            try {
+                item = await this.#iterator.next();
+            }
+            catch (error) {
+                throw badRequest('The deployment request body could not be read.', error);
+            }
+            if (item.done) {
+                this.#finished = true;
+                return false;
+            }
+            if (!(item.value instanceof Uint8Array)) {
+                throw badRequest('The deployment request body yielded a non-byte chunk.');
+            }
+            if (item.value.byteLength === 0)
+                continue;
+            this.#received += item.value.byteLength;
+            if (this.#received > this.#declaredLength) {
+                throw badRequest('The deployment request body exceeds its Content-Length.');
+            }
+            if (this.#received > this.#maximumLength) {
+                throw tooLarge('The deployment request exceeds its byte limit.');
+            }
+            const chunk = Buffer.from(item.value.buffer, item.value.byteOffset, item.value.byteLength);
+            this.#buffer = this.#buffer.length === 0 ? chunk : Buffer.concat([this.#buffer, chunk]);
+            return true;
+        }
+        return false;
+    }
+    async #readBytes(length) {
+        while (this.#buffer.length < length && await this.#fill()) {
+            // Fill until the requested framing bytes are available.
+        }
+        if (this.#buffer.length < length)
+            throw badRequest('The multipart request is truncated.');
+        const value = this.#buffer.subarray(0, length);
+        this.#buffer = this.#buffer.subarray(length);
+        return value;
+    }
+    async #readLine(maximum) {
+        for (;;) {
+            const index = this.#buffer.indexOf(CRLF);
+            if (index >= 0) {
+                if (index > maximum)
+                    throw tooLarge('Multipart part headers exceed their byte limit.');
+                const bytes = this.#buffer.subarray(0, index);
+                this.#buffer = this.#buffer.subarray(index + CRLF.length);
+                const value = bytes.toString('latin1');
+                if (!HEADER_VALUE.test(value)) {
+                    throw badRequest('Multipart headers must contain printable ASCII.');
+                }
+                return value;
+            }
+            if (this.#buffer.length > maximum) {
+                throw tooLarge('Multipart part headers exceed their byte limit.');
+            }
+            if (!await this.#fill())
+                throw badRequest('The multipart request is truncated.');
+        }
+    }
+    async start() {
+        if (this.#started)
+            throw new Error('Multipart reader has already started.');
+        this.#started = true;
+        const opening = await this.#readBytes(this.#boundary.length + CRLF.length);
+        if (!opening.equals(Buffer.concat([this.#boundary, CRLF]))) {
+            throw badRequest('The multipart body does not begin with its declared boundary.');
+        }
+    }
+    async readPartHeaders() {
+        if (!this.#started)
+            throw new Error('Multipart reader has not started.');
+        const headers = new Map();
+        let consumed = 0;
+        for (;;) {
+            const line = await this.#readLine(this.#maximumHeaderBytes - consumed);
+            consumed += Buffer.byteLength(line) + CRLF.length;
+            if (consumed > this.#maximumHeaderBytes) {
+                throw tooLarge('Multipart part headers exceed their byte limit.');
+            }
+            if (line === '')
+                break;
+            if (/^[ \t]/.test(line))
+                throw badRequest('Folded multipart headers are not supported.');
+            const separator = line.indexOf(':');
+            if (separator < 1)
+                throw badRequest('Multipart part header syntax is invalid.');
+            const name = line.slice(0, separator);
+            const value = line.slice(separator + 1).trim();
+            const normalized = name.toLowerCase();
+            if (!HEADER_NAME.test(name) || headers.has(normalized)) {
+                throw badRequest('Multipart part headers contain an invalid or duplicate field.');
+            }
+            headers.set(normalized, value);
+        }
+        const allowed = new Set([
+            'content-disposition',
+            'content-type',
+            'x-hypequery-bundle-path',
+        ]);
+        if ([...headers.keys()].some(name => !allowed.has(name))) {
+            throw badRequest('Multipart parts contain an unsupported header.');
+        }
+        const disposition = headers.get('content-disposition');
+        const match = disposition?.match(/^form-data; name="(release|bundle)"; filename="([^"\r\n]+)"$/);
+        const contentType = headers.get('content-type');
+        if (!match || !contentType)
+            throw badRequest('Multipart part headers are incomplete.');
+        return Object.freeze({
+            name: match[1],
+            filename: match[2],
+            contentType,
+            ...(headers.has('x-hypequery-bundle-path')
+                ? { bundlePath: headers.get('x-hypequery-bundle-path') }
+                : {}),
+        });
+    }
+    /** Returns true when this was the final part. */
+    async readPartBody(maximum, consume) {
+        const marker = Buffer.concat([CRLF, this.#boundary]);
+        const retained = marker.length - 1;
+        let byteLength = 0;
+        const emit = async (chunk) => {
+            if (chunk.length === 0)
+                return;
+            this.#throwIfAborted();
+            byteLength += chunk.length;
+            if (byteLength > maximum)
+                throw tooLarge('A multipart part exceeds its byte limit.');
+            await consume(chunk);
+        };
+        for (;;) {
+            const index = this.#buffer.indexOf(marker);
+            if (index >= 0) {
+                await emit(this.#buffer.subarray(0, index));
+                this.#buffer = this.#buffer.subarray(index + marker.length);
+                break;
+            }
+            if (this.#buffer.length > retained) {
+                const flushLength = this.#buffer.length - retained;
+                await emit(this.#buffer.subarray(0, flushLength));
+                this.#buffer = this.#buffer.subarray(flushLength);
+            }
+            if (!await this.#fill())
+                throw badRequest('The multipart request is truncated.');
+        }
+        const suffix = await this.#readBytes(2);
+        if (suffix.equals(CRLF))
+            return Object.freeze({ final: false, byteLength });
+        if (!suffix.equals(Buffer.from('--')))
+            throw badRequest('The multipart boundary is invalid.');
+        if (!(await this.#readBytes(2)).equals(CRLF)) {
+            throw badRequest('The final multipart boundary is invalid.');
+        }
+        return Object.freeze({ final: true, byteLength });
+    }
+    async finish() {
+        if (this.#buffer.length > 0)
+            throw badRequest('The multipart request has trailing bytes.');
+        while (await this.#fill()) {
+            if (this.#buffer.length > 0)
+                throw badRequest('The multipart request has trailing bytes.');
+        }
+        if (this.#received !== this.#declaredLength) {
+            throw badRequest('The deployment request body does not match its Content-Length.');
+        }
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,64 @@
+import type { ProtocolDeploymentReleaseEnvelope, ProtocolDeploymentReleaseTarget } from '@hypequery/protocol';
+import type { VerifiedDeploymentBundle } from './bundle.js';
+import type { DeploymentIntakeLimits } from './limits.js';
+export interface DeploymentSubmissionResponse {
+    readonly kind: 'hypequery-deployment-submission';
+    readonly version: 1;
+    readonly status: 'accepted' | 'already-exists';
+    readonly releaseIdentity: string;
+    readonly bundleIdentity: string;
+}
+export interface DeploymentIntakeRequest {
+    readonly headers: Readonly<Record<string, string | undefined>>;
+    readonly body: AsyncIterable<Uint8Array>;
+    readonly signal?: AbortSignal;
+}
+export interface DeploymentIntakeResponse {
+    readonly status: number;
+    readonly headers: Readonly<Record<string, string>>;
+    readonly body: string;
+}
+export interface DeploymentAuthenticationInput {
+    readonly token: string;
+    readonly signal?: AbortSignal;
+}
+export interface DeploymentAuthenticator<Principal> {
+    authenticate(input: DeploymentAuthenticationInput): Promise<Principal | null>;
+}
+export interface DeploymentAuthorizationInput<Principal> {
+    readonly principal: Principal;
+    readonly target: ProtocolDeploymentReleaseTarget;
+    readonly releaseIdentity: string;
+    /** Declared by the canonical release; the bundle bytes are verified after authorization. */
+    readonly bundleIdentity: string;
+    readonly signal?: AbortSignal;
+}
+export interface DeploymentAuthorizer<Principal> {
+    authorize(input: DeploymentAuthorizationInput<Principal>): Promise<boolean>;
+}
+/**
+ * A completely revalidated submission. The bundle directory is temporary and
+ * exists only for the duration of `DeploymentSubmissionStore.accept`.
+ */
+export interface VerifiedDeploymentSubmission<Principal> {
+    readonly principal: Principal;
+    readonly release: ProtocolDeploymentReleaseEnvelope;
+    readonly releaseCanonical: string;
+    readonly releaseIdentity: string;
+    readonly bundle: VerifiedDeploymentBundle;
+}
+export interface DeploymentSubmissionStore<Principal> {
+    /** Persist all required bytes before this promise resolves. */
+    accept(submission: VerifiedDeploymentSubmission<Principal>): Promise<'accepted' | 'already-exists'>;
+}
+export interface DeploymentIntakeOptions<Principal> {
+    readonly authenticator: DeploymentAuthenticator<Principal>;
+    readonly authorizer: DeploymentAuthorizer<Principal>;
+    readonly store: DeploymentSubmissionStore<Principal>;
+    readonly limits?: Partial<DeploymentIntakeLimits>;
+    readonly temporaryDirectory?: string;
+}
+export interface DeploymentIntake {
+    handle(request: DeploymentIntakeRequest): Promise<DeploymentIntakeResponse>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,iCAAiC,EACjC,+BAA+B,EAChC,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAC5D,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AAE1D,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,IAAI,EAAE,iCAAiC,CAAC;IACjD,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,gBAAgB,CAAC;IAC/C,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAC/D,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC,UAAU,CAAC,CAAC;IACzC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACnD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,uBAAuB,CAAC,SAAS;IAChD,YAAY,CAAC,KAAK,EAAE,6BAA6B,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;CAC/E;AAED,MAAM,WAAW,4BAA4B,CAAC,SAAS;IACrD,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,+BAA+B,CAAC;IACjD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,4FAA4F;IAC5F,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,oBAAoB,CAAC,SAAS;IAC7C,SAAS,CAAC,KAAK,EAAE,4BAA4B,CAAC,SAAS,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC7E;AAED;;;GAGG;AACH,MAAM,WAAW,4BAA4B,CAAC,SAAS;IACrD,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,OAAO,EAAE,iCAAiC,CAAC;IACpD,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,wBAAwB,CAAC;CAC3C;AAED,MAAM,WAAW,yBAAyB,CAAC,SAAS;IAClD,+DAA+D;IAC/D,MAAM,CACJ,UAAU,EAAE,4BAA4B,CAAC,SAAS,CAAC,GAClD,OAAO,CAAC,UAAU,GAAG,gBAAgB,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,uBAAuB,CAAC,SAAS;IAChD,QAAQ,CAAC,aAAa,EAAE,uBAAuB,CAAC,SAAS,CAAC,CAAC;IAC3D,QAAQ,CAAC,UAAU,EAAE,oBAAoB,CAAC,SAAS,CAAC,CAAC;IACrD,QAAQ,CAAC,KAAK,EAAE,yBAAyB,CAAC,SAAS,CAAC,CAAC;IACrD,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAC;IAClD,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CACtC;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAAC;CAC7E"}

package/dist/types.js

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

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@hypequery/deployment",
+  "version": "0.0.0-canary-20260719130627",
+  "description": "Provider-neutral deployment verification and intake for Hypequery",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@hypequery/protocol": "0.0.0-canary-20260719130627"
+  },
+  "devDependencies": {
+    "@types/node": "^22.5.0",
+    "typescript": "^5.7.3",
+    "vitest": "^3.2.6"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hypequery/hypequery.git",
+    "directory": "packages/deployment"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.json",
+    "dev": "tsc --project tsconfig.json --watch",
+    "lint": "eslint --ext .ts \"src/**/*.ts\"",
+    "test": "vitest run",
+    "types": "tsc --project tsconfig.json --noEmit"
+  }
+}