@pulse-compute/s3 1.0.0-beta.4 → 1.0.0-beta.6

package/README.md

@@ -5,11 +5,11 @@
 > **Audience:** Applications using bounded exact-key object reads and writes through Pulse effects.<br>
 > **Install directly:** Yes, when an application uses S3 object operations.<br>
 > **Supported entry points:** `@pulse-compute/s3`<br>
-> **Stability:** The package root supports head, getText and putText on Node Native, Node JavaScript and Fastly Native. Fastly JavaScript is ineligible. Provider and lowering subpaths are toolchain-only; live origin acceptance is separate.<br>
+> **Stability:** The package root supports head, getText, getBody and putText on Node Native, Node JavaScript and Fastly Native. getBody returns bounded opaque binary responses with the documented HTTP subset. Fastly JavaScript is ineligible. Provider and lowering subpaths are toolchain-only; live origin acceptance is separate.<br>
 > **npm:** [`@pulse-compute/s3`](https://www.npmjs.com/package/@pulse-compute/s3)<br>
-> **Canonical documentation:** [Package guide](https://pulsecompute.io/v1.0.0-beta.4/packages/s3/)
+> **Canonical documentation:** [Package guide](https://pulsecompute.io/v1.0.0-beta.6/packages/s3/)
 >
-> This release-status block is generated from the synchronized `Pulse 1.0.0-beta.4` package policy.
+> This release-status block is generated from the synchronized `Pulse 1.0.0-beta.6` package policy.
 <!-- pulse-package-status:end -->
 
 This package provides bounded, exact-key `head`, `getText` and `putText` effects for
@@ -31,7 +31,7 @@ Put mappings under `<profile>.node.bindings.s3` or
 | `bucket`, `region` | Explicit bucket and signing region |
 | `accessKeyIdSecret`, `secretAccessKeySecret` | Named provider secret references |
 | `sessionTokenSecret` | Optional named session-token reference |
-| `maxTextBytes` | 1–32768; default 32768 |
+| `maxTextBytes` | 1–2097152; default 32768 |
 | `timeoutMs` | 1–30000; default 10000 |
 | `backend` | Fastly-only named static backend |
 
@@ -65,19 +65,23 @@ Native targets compose Crypto's AssemblyScript primitives. Fastly JavaScript S3
 is ineligible because its SDK projects raw headers and loses required metadata
 information. This target exclusion does not gate supported targets.
 
-For a JSON request carrying the maximum text consisting of escaped control
-characters, configure the existing `schemas.maxBytes` request envelope to
-262144; the object itself remains bounded to 32768 UTF-8 bytes. The acceptance
+Select `maxTextBytes: 2097152` per binding for 2 MiB objects; the default remains
+32768. Request/schema limits are independent. Use `schemas.maxBytes: 2097152`
+for a 2 MiB encoded object, and explicitly size larger transport envelopes when
+JSON escaping requires it. The S3/text effect envelope is 12,648,448 bytes.
+Local HTTP ingress also uses `dev.maxBodyBytes`, default 65536. Primary-memory
+Native digest/S3 modules enforce a 256 MiB Wasm maximum; fixed-memory linked
+guests retain their separate ABI. KV values, HMAC and JWT do not grow with S3. The acceptance
 consumer uses generic JSON responses (`strict: false`) to compare the complete
 result unions. Applications using strict JSON must declare response schemas.
 
 The package root is the supported application API in the synchronized
-`1.0.0-beta.4` release candidate. Provider, manifest, compiler and Native
+`1.0.0-beta.6` release candidate. Provider, manifest, compiler and Native
 subpaths are trusted toolchain integration, not application imports. Install
 S3 with the exact compatible Pulse, CLI and provider candidate set; candidate
 preparation does not imply npm publication.
 
-See the [S3 guide](https://pulsecompute.io/v1.0.0-beta.4/packages/s3/) for the
+See the [S3 guide](https://pulsecompute.io/v1.0.0-beta.6/packages/s3/) for the
 lowering contract, support matrix and acceptance boundaries. Local acceptance
 executes Node Native, Node JavaScript and compiled Fastly Native Wasm against
 controlled origins. Live Object Storage evidence follows infrastructure setup.

package/as/read.as.ts

@@ -83,11 +83,11 @@ function __pulse_s3_date(seconds: i64): string {
 class __PulseS3Signature {
   date: string = ''; digest: string = ''; authorization: string = '';
 }
-function __pulse_s3_sign(method: string, path: string, host: string, region: string, id: string, secret: string, token: string, seconds: i64, body: Uint8Array, contentType: string): __PulseS3Signature {
+function __pulse_s3_sign(method: string, path: string, host: string, region: string, id: string, secret: string, token: string, seconds: i64, body: Uint8Array, contentType: string, range: string = '', ifNoneMatch: string = ''): __PulseS3Signature {
   const result = new __PulseS3Signature(); result.date = __pulse_s3_date(seconds);
   result.digest = __pulse_s3_hex(__pulse_s3_sha(body));
-  const names = (contentType.length ? 'content-type;' : '') + 'host;x-amz-content-sha256;x-amz-date' + (token.length ? ';x-amz-security-token' : '');
-  const headers = (contentType.length ? 'content-type:' + __pulse_s3_header_spaces(contentType) + '\n' : '') + 'host:' + host + '\nx-amz-content-sha256:' + result.digest + '\nx-amz-date:' + result.date + '\n'
+  const names = (contentType.length ? 'content-type;' : '') + 'host;' + (ifNoneMatch.length ? 'if-none-match;' : '') + (range.length ? 'range;' : '') + 'x-amz-content-sha256;x-amz-date' + (token.length ? ';x-amz-security-token' : '');
+  const headers = (contentType.length ? 'content-type:' + __pulse_s3_header_spaces(contentType) + '\n' : '') + 'host:' + host + '\n' + (ifNoneMatch.length ? 'if-none-match:' + ifNoneMatch + '\n' : '') + (range.length ? 'range:' + range + '\n' : '') + 'x-amz-content-sha256:' + result.digest + '\nx-amz-date:' + result.date + '\n'
     + (token.length ? 'x-amz-security-token:' + token + '\n' : '');
   const canonical = method + '\n' + path + '\n\n' + headers + '\n' + names + '\n' + result.digest;
   const day = result.date.slice(0, 8), scope = day + '/' + region + '/s3/aws4_request';
@@ -113,3 +113,34 @@ function __pulse_s3_header_spaces(text: string): string {
   }
   return output;
 }
+
+// Canonical decimal/range validation shared by Native body transports.
+function __pulse_s3_decimal(value: string): f64 {
+  if (!value.length || (value.length > 1 && value.charCodeAt(0) == 48)) return -1;
+  let result: f64 = 0;
+  for (let i = 0; i < value.length; i++) {
+    const digit = value.charCodeAt(i) - 48;
+    if (digit < 0 || digit > 9) return -1;
+    result = result * 10 + digit;
+    if (result > 9007199254740991) return -1;
+  }
+  return result;
+}
+function __pulse_s3_body_range(status: i32, length: f64, contentRange: string, range: string, conditional: bool): bool {
+  if (status == 304 && !conditional) return false;
+  if (status == 206) {
+    if (!range.length || !contentRange.startsWith('bytes ')) return false;
+    const parts = contentRange.slice(6).split('/'), request = range.slice(6).split('-');
+    if (parts.length != 2 || request.length != 2) return false;
+    const interval = parts[0].split('-'); if (interval.length != 2) return false;
+    const start = __pulse_s3_decimal(interval[0]), end = __pulse_s3_decimal(interval[1]), total = __pulse_s3_decimal(parts[1]);
+    return start >= 0 && total >= 0 && start == __pulse_s3_decimal(request[0])
+      && end == Math.min(__pulse_s3_decimal(request[1]), total - 1) && end >= start && length == end - start + 1;
+  }
+  if (status == 416) {
+    if (!range.length || !contentRange.startsWith('bytes */')) return false;
+    const total = __pulse_s3_decimal(contentRange.slice(8));
+    return total >= 0 && __pulse_s3_decimal(range.slice(6).split('-')[0]) >= total;
+  }
+  return !contentRange.length && (status == 200 || status == 304 || status == 404 || status == 412);
+}

package/conformance/README.md

@@ -10,4 +10,4 @@ metadata limits, truncation, deadlines, write uncertainty and secret redaction.
 Fastly Native executes compiled Wasm against host ABI fixtures. These checks
 do not establish live origin behavior; that evidence follows infrastructure
 setup. Fastly JavaScript is ineligible for S3 because its SDK loses raw header
-metadata. See the [S3 guide](https://pulsecompute.io/v1.0.0-beta.4/packages/s3/).
+metadata. See the [S3 guide](https://pulsecompute.io/v1.0.0-beta.6/packages/s3/).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pulse-compute/s3",
-  "version": "1.0.0-beta.4",
+  "version": "1.0.0-beta.6",
   "license": "Apache-2.0",
   "engines": {
     "node": "^22.14.0 || ^24.0.0"
@@ -18,7 +18,12 @@
     "./provider": "./src/provider.js",
     "./pulsewasm/manifest": "./pulsewasm.manifest.cjs",
     "./pulsewasm/compiler": "./pulsewasm.compiler.cjs",
-    "./pulsewasm-native": "./pulsewasm.native.cjs"
+    "./pulsewasm-native": "./pulsewasm.native.cjs",
+    "./signing": {
+      "types": "./src/signing.d.ts",
+      "require": "./src/signing.js",
+      "default": "./src/signing.js"
+    }
   },
   "files": [
     "src",
@@ -39,8 +44,8 @@
     "manifest": "./pulsewasm.manifest.cjs"
   },
   "dependencies": {
-    "@pulse-compute/runtime": "1.0.0-beta.4",
-    "@pulse-compute/wasm-contracts": "1.0.0-beta.4"
+    "@pulse-compute/runtime": "1.0.0-beta.6",
+    "@pulse-compute/wasm-contracts": "1.0.0-beta.6"
   },
   "publishConfig": {
     "access": "public"
@@ -50,7 +55,7 @@
     "url": "git+https://github.com/pulse-compute/pulse.git",
     "directory": "packages/s3"
   },
-  "homepage": "https://pulsecompute.io/v1.0.0-beta.4/packages/s3/",
+  "homepage": "https://pulsecompute.io/v1.0.0-beta.6/packages/s3/",
   "bugs": {
     "url": "https://github.com/pulse-compute/pulse/issues"
   }

package/pulse.package.json

@@ -10,7 +10,8 @@
     "symbols": [
       "head",
       "getText",
-      "putText"
+      "putText",
+      "getBody"
     ]
   },
   "ownership": {
@@ -66,7 +67,8 @@
     "semanticCases": [
       "s3.head",
       "s3.getText",
-      "s3.putText"
+      "s3.putText",
+      "s3.getBody"
     ]
   },
   "docs": {

package/pulsewasm.compiler.cjs

@@ -3,7 +3,7 @@ const { normalizeDiagnostic, sourceLoc } = require('@pulse-compute/wasm-contract
 const { CANONICAL_PACKAGE_EFFECT_VERSION } = require('@pulse-compute/wasm-contracts/handler/canonical-runtime');
 const { PACKAGE_CRYPTO_REQUIREMENT_VERSION } = require('@pulse-compute/wasm-contracts/package/package-contract');
 const { S3_PACKAGE, S3_CONTRACT_ID, S3_OPERATIONS, S3_LOWERING_PLAN_VERSION, S3_CRYPTO_ALGORITHMS } = require('@pulse-compute/wasm-contracts/s3/contracts');
-const { normalizePutOptions } = require('./src/provider.js');
+const { normalizePutOptions, normalizeBodyOptions } = require('./src/provider.js');
 
 function buildS3LoweringPlan(input = {}) {
   const ts = input.typescript || require('typescript');
@@ -35,12 +35,13 @@ function buildS3LoweringPlan(input = {}) {
       && ts.isIdentifier(node.expression.expression) && namespaces.has(node.expression.expression.text)) {
       const method = node.expression.name.text;
       const op = S3_OPERATIONS[method];
-      if (!op) { error(node, 'OPERATION_UNSUPPORTED', 'S3 supports head, getText and putText.'); return; }
+      if (!op) { error(node, 'OPERATION_UNSUPPORTED', 'S3 supports head, getText, getBody and putText.'); return; }
       const put = method === 'putText';
+      const body = method === 'getBody';
       let fn = node.parent;
       while (fn && !ts.isArrowFunction(fn) && !ts.isFunctionExpression(fn)) fn = fn.parent;
       const ctx = fn && fn.parameters[0] && fn.parameters[0].name;
-      if (!(put ? [4, 5].includes(node.arguments.length) : node.arguments.length === 3) || !ctx || !ts.isIdentifier(ctx)
+      if (!(put ? [4, 5].includes(node.arguments.length) : body ? [3, 4].includes(node.arguments.length) : node.arguments.length === 3) || !ctx || !ts.isIdentifier(ctx)
         || !ts.isIdentifier(node.arguments[0]) || node.arguments[0].text !== ctx.text) {
         error(node, 'ARGUMENTS_UNSUPPORTED', 'S3 requires current handler context, literal binding, runtime key and, for PUT, text with optional literal options.'); return;
       }
@@ -63,6 +64,21 @@ function buildS3LoweringPlan(input = {}) {
           options = normalizePutOptions(options);
         } catch { error(nodeOptions || node, 'OPTIONS_UNSUPPORTED', 'PUT options must be a literal object containing only a valid literal contentType.'); return; }
       }
+      if (body) {
+        const nodeOptions = node.arguments[3];
+        try {
+          if (nodeOptions) {
+            if (!ts.isObjectLiteralExpression(nodeOptions) || nodeOptions.properties.length > 3) throw new TypeError();
+            for (const property of nodeOptions.properties) {
+              if (!ts.isPropertyAssignment(property) || !ts.isIdentifier(property.name) && !ts.isStringLiteralLike(property.name)
+                || !['method', 'range', 'ifNoneMatch'].includes(property.name.text) || Object.hasOwn(options, property.name.text)
+                || !ts.isStringLiteralLike(property.initializer)) throw new TypeError();
+              options[property.name.text] = property.initializer.text;
+            }
+          }
+          options = normalizeBodyOptions(options);
+        } catch { error(nodeOptions || node, 'OPTIONS_UNSUPPORTED', 'Body options require literal method, closed byte range and/or one If-None-Match validator.'); return; }
+      }
       let placement = '';
       const parent = node.parent;
       if (ts.isAwaitExpression(parent) && ts.isVariableDeclaration(parent.parent)) placement = 'variable';

package/pulsewasm.manifest.cjs

@@ -3,7 +3,7 @@ const { S3_PACKAGE, S3_CONTRACT_ID, S3_OPERATIONS } = require('@pulse-compute/wa
 module.exports = Object.freeze({
   version: 'pulsewasm.lowerable-library-manifest.v2', kind: 'pulsewasm.lowerable-library-manifest',
   contractId: S3_CONTRACT_ID, npmPackage: S3_PACKAGE, lowerableSubpath: S3_PACKAGE,
-  facade: { namespace: 's3', import: S3_PACKAGE, symbols: ['head', 'getText', 'putText'] },
+  facade: { namespace: 's3', import: S3_PACKAGE, symbols: ['head', 'getText', 'putText', 'getBody'] },
   publicApi: { package: S3_PACKAGE, symbols: ['s3'], compatibilitySubpaths: [], loweringIntentionallyNarrow: true },
   compiler: { version: 'pulsewasm.lowerable-compiler-builder.v1', entry: './pulsewasm.compiler.cjs', export: 'buildS3LoweringPlan', artifact: 's3-lowering-plan.json', builderOwner: S3_PACKAGE, trust: 'first-party', inputs: ['typescript.SourceFile'] },
   modes: {

package/src/body.js

@@ -0,0 +1,55 @@
+'use strict';
+
+// Protocol-only helpers. The provider owns transport, deadlines and body handles.
+function normalizeBodyOptions(input = {}) {
+  if (!input || typeof input !== 'object' || ![Object.prototype, null].includes(Object.getPrototypeOf(input))) throw new TypeError('Invalid S3 body options.');
+  for (const key of Reflect.ownKeys(input)) {
+    const field = Object.getOwnPropertyDescriptor(input, key);
+    if (!['method', 'range', 'ifNoneMatch'].includes(key) || !field.enumerable || !Object.hasOwn(field, 'value')) throw new TypeError('Invalid S3 body option.');
+  }
+  const method = input.method ?? 'GET';
+  if (!['GET', 'HEAD'].includes(method)) throw new TypeError('S3 body method must be GET or HEAD.');
+  if (input.range !== undefined) {
+    const match = typeof input.range === 'string' && /^bytes=(0|[1-9][0-9]*)-(0|[1-9][0-9]*)$/.exec(input.range);
+    if (method !== 'GET' || !match || !Number.isSafeInteger(Number(match[2])) || Number(match[1]) > Number(match[2])) throw new TypeError('S3 body requires one closed byte range.');
+  }
+  if (input.ifNoneMatch !== undefined && (typeof input.ifNoneMatch !== 'string' || input.ifNoneMatch.length > 1024
+    || !/^(?:\*|(?:W\/)?"[\x21\x23-\x7e]*")$/.test(input.ifNoneMatch))) throw new TypeError('S3 body requires one entity tag or *.');
+  return Object.freeze({ method, ...(input.range === undefined ? {} : { range: input.range }), ...(input.ifNoneMatch === undefined ? {} : { ifNoneMatch: input.ifNoneMatch }) });
+}
+function bodyRequestHeaders(input) {
+  const options = normalizeBodyOptions(input);
+  return { ...(options.range === undefined ? {} : { range: options.range }), ...(options.ifNoneMatch === undefined ? {} : { 'if-none-match': options.ifNoneMatch }) };
+}
+function bodyResponseMetadata(status, headers, options, maximum) {
+  const { metadataFromHeaders } = require('./provider.js');
+  const metadata = metadataFromHeaders(headers, status === 200 || status === 206);
+  if (!metadata) throw new Error('protocol');
+  let contentRange;
+  for (const [name, value] of headers) if (name.toLowerCase() === 'content-range') {
+    if (contentRange !== undefined || value.length > 128) throw new Error('protocol');
+    contentRange = value;
+  }
+  if (status === 304 && options.ifNoneMatch === undefined) throw new Error('protocol');
+  if (status === 206) {
+    const match = contentRange && /^bytes (0|[1-9][0-9]*)-(0|[1-9][0-9]*)\/(0|[1-9][0-9]*)$/.exec(contentRange);
+    const range = options.range && /^bytes=(\d+)-(\d+)$/.exec(options.range);
+    if (!match || !range) throw new Error('protocol');
+    const [start, end, total] = match.slice(1).map(Number);
+    if (!Number.isSafeInteger(total) || start !== Number(range[1]) || end !== Math.min(Number(range[2]), total - 1)
+      || start > end || metadata.byteLength !== end - start + 1) throw new Error('protocol');
+  } else if (status === 416) {
+    const match = contentRange && /^bytes \*\/(0|[1-9][0-9]*)$/.exec(contentRange);
+    if (!options.range || !match || !Number.isSafeInteger(Number(match[1])) || Number(options.range.slice(6).split('-')[0]) < Number(match[1])) throw new Error('protocol');
+  } else if (contentRange !== undefined) throw new Error('protocol');
+  if (options.method !== 'HEAD' && [200, 206].includes(status) && metadata.byteLength > maximum) throw new Error('too-large');
+  if (![200, 206, 304, 404, 412, 416].includes(status)) throw new Error('protocol');
+  const selected = new Headers();
+  if (metadata.byteLength !== undefined && [200, 206].includes(status)) selected.set('content-length', String(metadata.byteLength));
+  if (metadata.contentType !== undefined) selected.set('content-type', metadata.contentType);
+  if (metadata.etag !== undefined) selected.set('etag', metadata.etag);
+  if (contentRange !== undefined) selected.set('content-range', contentRange);
+  // No response digest is asserted, including for partial representations.
+  return { headers: selected, byteLength: metadata.byteLength, body: options.method !== 'HEAD' && [200, 206].includes(status) };
+}
+module.exports = { normalizeBodyOptions, bodyRequestHeaders, bodyResponseMetadata };

package/src/index.d.ts

@@ -43,7 +43,17 @@ export interface S3PutTextOptions {
 
 // Binding and options must be compiler-proven literals. Key and text may be
 // runtime strings. TypeScript alone cannot enforce that lowering restriction.
+export interface S3GetBodyOptions {
+  readonly method?: 'GET' | 'HEAD';
+  /** One closed byte range, for example bytes=0-1023; GET only. */
+  readonly range?: string;
+  /** One entity tag or *, without a comma-separated list. */
+  readonly ifNoneMatch?: string;
+}
+
 export declare const s3: {
+  /** Opaque binary response; capped by maxTextBytes. Return without decoding. */
+  getBody(ctx: PulseContext, binding: string, key: string, options?: S3GetBodyOptions): PulseParallelEffect<Response>;
   head(ctx: PulseContext, binding: string, key: string): PulseParallelEffect<S3HeadResult>;
   getText(ctx: PulseContext, binding: string, key: string): PulseParallelEffect<S3GetTextResult>;
   putText(ctx: PulseContext, binding: string, key: string, text: string,

package/src/index.js

@@ -1,10 +1,22 @@
 'use strict';
 const { createPackageRuntime } = require('@pulse-compute/runtime/package');
-const { S3_PACKAGE, S3_CONTRACT_ID, S3_OPERATIONS } = require('@pulse-compute/wasm-contracts/s3/contracts');
+const { S3_PACKAGE, S3_CONTRACT_ID, S3_OPERATIONS, S3_LIMITS } = require('@pulse-compute/wasm-contracts/s3/contracts');
 const { normalizeResult, normalizePutOptions } = require('./provider.js');
+const { normalizeBodyOptions } = require('./body.js');
 const runtime = createPackageRuntime({ package: S3_PACKAGE, contractId: S3_CONTRACT_ID, providerKind: 's3', operations: S3_OPERATIONS });
 exports.s3 = Object.freeze({
+  getBody(ctx, binding, key, options) {
+    return runtime.effect(ctx, 'getBody', { binding, key, ...normalizeBodyOptions(options) }, result => {
+      if (!(result instanceof Response)) throw new TypeError('S3 getBody requires an opaque provider Response.');
+      return result;
+    });
+  },
   head(ctx, binding, key) { return runtime.effect(ctx, 'head', { binding, key }, (result) => normalizeResult('head', result)); },
   getText(ctx, binding, key) { return runtime.effect(ctx, 'getText', { binding, key }, (result) => normalizeResult('getText', result)); },
-  putText(ctx, binding, key, text, options) { return runtime.effect(ctx, 'putText', { binding, key, text, ...normalizePutOptions(options) }, (result) => normalizeResult('putText', result)); }
+  putText(ctx, binding, key, text, options) {
+    // Retain an over-limit sentinel without copying an unbounded string into
+    // the effect envelope. Providers reject it before encoding or dispatch.
+    const boundedText = typeof text === 'string' ? text.slice(0, S3_LIMITS.textBytes + 1) : null;
+    return runtime.effect(ctx, 'putText', { binding, key, text: boundedText, ...normalizePutOptions(options) }, (result) => normalizeResult('putText', result));
+  }
 });

package/src/provider.js

@@ -3,6 +3,7 @@
 // Trusted provider surface; never an application lowering escape. Protocol
 // composition is S3-owned, while crypto, secrets and I/O are supplied by hosts.
 const { S3_LIMITS } = require('@pulse-compute/wasm-contracts/s3/contracts');
+const { encodeS3Key, createAuthorization } = require('./signing.js');
 const encoder = new TextEncoder();
 const namePattern = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
 const bytes = (text) => encoder.encode(text);
@@ -26,7 +27,7 @@ function normalizeBinding(value) {
     if (field === 'sessionTokenSecret' && input[field] === undefined) continue;
     if (typeof input[field] !== 'string' || !namePattern.test(input[field])) throw new TypeError('S3 credentials must be valid named secret references.');
   }
-  const maxTextBytes = input.maxTextBytes === undefined ? S3_LIMITS.textBytes : input.maxTextBytes;
+  const maxTextBytes = input.maxTextBytes === undefined ? S3_LIMITS.defaultTextBytes : input.maxTextBytes;
   const timeoutMs = input.timeoutMs === undefined ? 10000 : input.timeoutMs;
   if (!Number.isInteger(maxTextBytes) || maxTextBytes < 1 || maxTextBytes > S3_LIMITS.textBytes || !Number.isInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30000) throw new TypeError('S3 limits are outside the bounded subset.');
   return Object.freeze({ ...input, endpoint: url.origin, maxTextBytes, timeoutMs });
@@ -34,9 +35,7 @@ function normalizeBinding(value) {
 function encodeKey(key) {
   if (typeof key !== 'string' || !key.isWellFormed() || !key.length || bytes(key).length > S3_LIMITS.keyBytes
     || /[\u0000-\u001f\u007f-\u009f]/u.test(key) || key.split('/').some((p) => p === '.' || p === '..')) return null;
-  // One-time adaptation of Assets' RFC3986 segment encoder. Deliberately no
-  // AssetBucket normalization, path joining, middleware or cache policy.
-  return key.split('/').map((part) => encodeURIComponent(part).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`)).join('/');
+  return encodeS3Key(key);
 }
 function credentialsValid(accessId, secret, token) {
   return typeof accessId === 'string' && /^[\x21-\x7e]{1,256}$/.test(accessId)
@@ -59,22 +58,12 @@ async function signRequest(input, crypto) {
   const digest = hex(await crypto.sha256(body));
   const host = new URL(binding.endpoint).host;
   const headers = { ...(contentType === undefined ? {} : { 'content-type': contentType }), host, 'x-amz-content-sha256': digest, 'x-amz-date': date, ...(token === undefined ? {} : { 'x-amz-security-token': token }) };
-  const names = Object.keys(headers).sort();
+  if (input.readOptions) Object.assign(headers, require('./body.js').bodyRequestHeaders(input.readOptions));
   const uri = `/${binding.bucket}/${encodedKey}`;
-  const canonical = `${method}\n${uri}\n\n${names.map((name) => `${name}:${headers[name].replace(/ +/g, ' ')}\n`).join('')}\n${names.join(';')}\n${digest}`;
-  const scope = `${date.slice(0, 8)}/${binding.region}/s3/aws4_request`;
-  const toSign = `AWS4-HMAC-SHA256\n${date}\n${scope}\n${hex(await crypto.sha256(bytes(canonical)))}`;
-  let key = bytes(`AWS4${secret}`);
-  try {
-    for (const part of [date.slice(0, 8), binding.region, 's3', 'aws4_request']) {
-      const next = await crypto.hmacSha256(key, bytes(part)); key.fill(0); key = next;
-    }
-    const signature = await crypto.hmacSha256(key, bytes(toSign));
-    headers.authorization = `AWS4-HMAC-SHA256 Credential=${accessId}/${scope}, SignedHeaders=${names.join(';')}, Signature=${hex(signature)}`;
-    signature.fill(0);
-    headers['accept-encoding'] = 'identity';
-    return { method, url: binding.endpoint + uri, headers, ...(method === 'PUT' ? { body } : {}) };
-  } finally { key.fill(0); }
+  headers.authorization = await createAuthorization({ method, uri, query: '', headers, date,
+    region: binding.region, service: 's3', accessId, secret, payloadHash: digest }, crypto);
+  headers['accept-encoding'] = 'identity';
+  return { method, url: binding.endpoint + uri, headers, ...(method === 'PUT' ? { body } : {}) };
 }
 function failure(reason, httpStatus) { return Object.freeze({ status: 'failed', reason, ...(httpStatus === undefined ? {} : { httpStatus }) }); }
 function putFailure(reason, dispatched, httpStatus) {
@@ -133,4 +122,4 @@ function normalizeResult(operation, result) {
   if (bytes(JSON.stringify(result)).length > S3_LIMITS.envelopeBytes) throw new TypeError('S3 result envelope exceeds its bound.');
   return Object.freeze({ ...result });
 }
-module.exports = Object.freeze({ normalizeBinding, namePattern, encodeKey, credentialsValid, normalizePutOptions, signRequest, signRead: signRequest, failure, putFailure, putStatusResult, statusResult, metadataFromHeaders, normalizeResult, hex, bytes });
+module.exports = Object.freeze({ ...require('./body.js'), normalizeBinding, namePattern, encodeKey, credentialsValid, normalizePutOptions, signRequest, signRead: signRequest, failure, putFailure, putStatusResult, statusResult, metadataFromHeaders, normalizeResult, hex, bytes });

package/src/signing.d.ts

@@ -0,0 +1,23 @@
+/** Trusted first-party host integration, not application lowering authority. */
+export interface SigV4Crypto {
+  sha256(bytes: Uint8Array): Promise<Uint8Array>;
+  hmacSha256(key: Uint8Array, bytes: Uint8Array): Promise<Uint8Array>;
+}
+export interface HttpSigningInput {
+  method: string;
+  url: URL | string;
+  accessId: string;
+  secret: string;
+  token?: string | undefined;
+  region?: string | undefined;
+  service?: string | undefined;
+  headers?: HeadersInit | undefined;
+  now?: Date | undefined;
+  payloadHash?: string | undefined;
+}
+export declare function encodeS3Key(key: string): string;
+export declare function signHttpRequest(input: HttpSigningInput, crypto: SigV4Crypto): Promise<Request>;
+export declare function createAuthorization(input: {
+  method: string; uri: string; query: string; headers: Readonly<Record<string, string>>;
+  date: string; region: string; service: string; accessId: string; secret: string; payloadHash: string;
+}, crypto: SigV4Crypto): Promise<string>;

package/src/signing.js

@@ -0,0 +1,63 @@
+'use strict';
+
+// First-party host integration only. S3 owns protocol composition; callers
+// supply resolved credentials and an explicitly selected SHA/HMAC realization.
+const encoder = new TextEncoder();
+const bytes = value => encoder.encode(value);
+const hex = value => Array.from(value, byte => byte.toString(16).padStart(2, '0')).join('');
+const encodeRfc3986 = value => encodeURIComponent(value).replace(/[!'()*]/g, char => `%${char.charCodeAt(0).toString(16).toUpperCase()}`);
+
+function encodeS3Key(key) {
+  // Encoding only: portable key admission and legacy Assets path policy remain
+  // separate. In particular, this preserves empty and repeated segments.
+  return key.split('/').map(encodeRfc3986).join('/');
+}
+
+function canonicalQuery(url) {
+  const pairs = [];
+  url.searchParams.forEach((value, key) => pairs.push([encodeRfc3986(key), encodeRfc3986(value)]));
+  pairs.sort(([ak, av], [bk, bv]) => ak === bk ? (av < bv ? -1 : av > bv ? 1 : 0) : ak < bk ? -1 : 1);
+  return pairs.map(([key, value]) => `${key}=${value}`).join('&');
+}
+
+async function createAuthorization(input, crypto) {
+  const { method, uri, query, headers, date, region, service, accessId, secret, payloadHash } = input;
+  const names = Object.keys(headers).sort();
+  const canonicalHeaders = names.map(name => `${name}:${headers[name].trim().replace(/\s+/g, ' ')}\n`).join('');
+  const canonical = [method, uri, query, canonicalHeaders, names.join(';'), payloadHash].join('\n');
+  const stamp = date.slice(0, 8);
+  const scope = `${stamp}/${region}/${service}/aws4_request`;
+  const toSign = `AWS4-HMAC-SHA256\n${date}\n${scope}\n${hex(await crypto.sha256(bytes(canonical)))}`;
+  let key = bytes(`AWS4${secret}`);
+  try {
+    for (const part of [stamp, region, service, 'aws4_request']) {
+      const next = await crypto.hmacSha256(key, bytes(part)); key.fill(0); key = next;
+    }
+    const signature = await crypto.hmacSha256(key, bytes(toSign));
+    try { return `AWS4-HMAC-SHA256 Credential=${accessId}/${scope}, SignedHeaders=${names.join(';')}, Signature=${hex(signature)}`; }
+    finally { signature.fill(0); }
+  } finally { key.fill(0); }
+}
+
+async function signHttpRequest(input, crypto) {
+  const url = new URL(input.url.toString());
+  const method = input.method.toUpperCase();
+  const date = (input.now ?? new Date()).toISOString().replace(/[:-]|\.\d{3}/g, '');
+  const payloadHash = input.payloadHash ?? 'UNSIGNED-PAYLOAD';
+  const headers = new Headers(input.headers);
+  headers.set('x-amz-date', date);
+  headers.set('x-amz-content-sha256', payloadHash);
+  if (input.token) headers.set('x-amz-security-token', input.token);
+  const signingHeaders = Object.create(null);
+  headers.forEach((value, name) => { if (name !== 'authorization') signingHeaders[name] = value; });
+  signingHeaders.host = url.host;
+  headers.set('authorization', await createAuthorization({ method, uri: url.pathname || '/', query: canonicalQuery(url),
+    headers: signingHeaders, date, region: input.region ?? 'us-east-1', service: input.service ?? 's3',
+    accessId: input.accessId, secret: input.secret, payloadHash }, crypto));
+  return new Request(url, { method, headers });
+}
+
+exports.encodeS3Key = encodeS3Key;
+exports.createAuthorization = createAuthorization;
+exports.signHttpRequest = signHttpRequest;
+Object.freeze(module.exports);