@adcp/sdk 15.0.0 → 15.2.0

package/dist/lib/reporting/gcs/io.mjs

@@ -0,0 +1,69 @@
+import { isReportingObjectWriteConflictError, isReportingObjectWriteNotRevokedError } from "../ledger/object-writes.mjs";
+import { ReportingGcsFenceError, isReportingGcsFenceError } from "./errors.mjs";
+function activeGcsSignal(signal) {
+  if (signal.aborted) throw signal.reason;
+}
+const active = activeGcsSignal;
+async function withGcsDeadline(work, context = {}) {
+  const signal = context.signal;
+  const deadline = context.milliseconds ?? 6e4;
+  if (!Number.isSafeInteger(deadline) || deadline < 1 || deadline > 6e4)
+    throw new ReportingGcsFenceError("INVALID_INPUT");
+  if (signal !== void 0 && !(signal instanceof AbortSignal)) throw new ReportingGcsFenceError("INVALID_INPUT");
+  const controller = new AbortController();
+  const onAbort = () => controller.abort(new ReportingGcsFenceError("ABORTED"));
+  signal?.addEventListener("abort", onAbort, { once: true });
+  if (signal?.aborted) onAbort();
+  const timer = setTimeout(() => controller.abort(new ReportingGcsFenceError("DEADLINE_EXCEEDED")), deadline);
+  let rejectAbort;
+  try {
+    active(controller.signal);
+    return await Promise.race([
+      work(controller.signal),
+      new Promise((_, reject) => {
+        rejectAbort = () => reject(controller.signal.reason);
+        controller.signal.addEventListener("abort", rejectAbort, { once: true });
+        if (controller.signal.aborted) rejectAbort();
+      })
+    ]);
+  } catch (error) {
+    if (controller.signal.aborted) throw controller.signal.reason;
+    if (isReportingGcsFenceError(error)) throw error;
+    if (isReportingObjectWriteConflictError(error) || error instanceof Error && isReportingObjectWriteConflictError(error.cause))
+      throw new ReportingGcsFenceError("CONTENT_CONFLICT");
+    if (isReportingObjectWriteNotRevokedError(error) || error instanceof Error && isReportingObjectWriteNotRevokedError(error.cause))
+      throw new ReportingGcsFenceError("NOT_REVOKED");
+    throw new ReportingGcsFenceError("STATE_UNAVAILABLE");
+  } finally {
+    clearTimeout(timer);
+    signal?.removeEventListener("abort", onAbort);
+    if (rejectAbort) controller.signal.removeEventListener("abort", rejectAbort);
+  }
+}
+async function readGcsBytes(file, maxBytes, signal) {
+  active(signal);
+  const stream = file.createReadStream();
+  const abort = () => stream.destroy(new ReportingGcsFenceError("ABORTED"));
+  signal.addEventListener("abort", abort, { once: true });
+  if (signal.aborted) abort();
+  const chunks = [];
+  let count = 0;
+  try {
+    for await (const chunk of stream) {
+      active(signal);
+      count += chunk.length;
+      if (count > maxBytes) throw new ReportingGcsFenceError("CONTENT_CONFLICT");
+      chunks.push(Buffer.from(chunk));
+    }
+    active(signal);
+    return Buffer.concat(chunks);
+  } finally {
+    signal.removeEventListener("abort", abort);
+    stream.destroy();
+  }
+}
+export {
+  activeGcsSignal,
+  readGcsBytes,
+  withGcsDeadline
+};

package/dist/lib/reporting/gcs/reader.d.mts

@@ -0,0 +1,43 @@
+import type { Storage } from '@google-cloud/storage';
+import { type CanonicalReferenceResolver } from '../../canonical-references/index.mjs';
+import type { ReportingResourceReader } from '../inspection.mjs';
+import { type ReportingObjectWriteScopeV1 } from '../ledger/object-writes.mjs';
+export interface GcsReportingReadScopeV1 extends ReportingObjectWriteScopeV1 {
+    /** Non-secret identity from the host's authenticated principal registry. Never a bearer. */
+    principal_id: string;
+}
+export interface GcsReportingReadAuthorizationV1 {
+    scope: Readonly<GcsReportingReadScopeV1>;
+    bucket: string;
+    objectPrefix: string;
+    objectName: string;
+}
+export interface GcsReportingReaderOptionsV1 {
+    scope: GcsReportingReadScopeV1;
+    bucket: string;
+    /** Exact saved destination prefix, including the trailing slash. */
+    objectPrefix: string;
+    /** Resolve an official client with keyless credentials for this operation. */
+    getStorage(scope: Readonly<GcsReportingReadScopeV1>, context: {
+        signal: AbortSignal;
+    }): Promise<Storage>;
+    /** Host verifies principal/account/destination ownership and the current grant generation. */
+    authorize(request: Readonly<GcsReportingReadAuthorizationV1>, context: {
+        signal: AbortSignal;
+    }): Promise<boolean>;
+    /** Optional operation lifetime, composed with each read deadline/caller signal. */
+    signal?: AbortSignal;
+    operationDeadlineMilliseconds?: number;
+    maxBytes?: number;
+}
+/** Restrictive provider-native URL grammar: no credentials, queries, encoding or traversal. */
+export declare function gcsReportingObjectFromUriV1(uri: string, bucket: string, prefix: string): string;
+export declare function createGcsScopedObjectReadV1(options: GcsReportingReaderOptionsV1): (uri: string, maxBytes: number, signal?: AbortSignal, nativeVersion?: string) => Promise<{
+    body: Buffer<ArrayBufferLike>;
+    contentType: string | undefined;
+    generation: string;
+}>;
+/** Destination-bound manifest/object reader. The caller never supplies bucket or credential scope. */
+export declare function createGcsReportingResourceReaderV1(options: GcsReportingReaderOptionsV1): ReportingResourceReader;
+/** Digest-pinned private contract resolver; all resolutions re-authorize and bypass caches. */
+export declare function createGcsReportingReferenceResolverV1(options: GcsReportingReaderOptionsV1): CanonicalReferenceResolver;

package/dist/lib/reporting/gcs/reader.d.ts

@@ -0,0 +1,43 @@
+import type { Storage } from '@google-cloud/storage';
+import { type CanonicalReferenceResolver } from '../../canonical-references';
+import type { ReportingResourceReader } from '../inspection';
+import { type ReportingObjectWriteScopeV1 } from '../ledger/object-writes';
+export interface GcsReportingReadScopeV1 extends ReportingObjectWriteScopeV1 {
+    /** Non-secret identity from the host's authenticated principal registry. Never a bearer. */
+    principal_id: string;
+}
+export interface GcsReportingReadAuthorizationV1 {
+    scope: Readonly<GcsReportingReadScopeV1>;
+    bucket: string;
+    objectPrefix: string;
+    objectName: string;
+}
+export interface GcsReportingReaderOptionsV1 {
+    scope: GcsReportingReadScopeV1;
+    bucket: string;
+    /** Exact saved destination prefix, including the trailing slash. */
+    objectPrefix: string;
+    /** Resolve an official client with keyless credentials for this operation. */
+    getStorage(scope: Readonly<GcsReportingReadScopeV1>, context: {
+        signal: AbortSignal;
+    }): Promise<Storage>;
+    /** Host verifies principal/account/destination ownership and the current grant generation. */
+    authorize(request: Readonly<GcsReportingReadAuthorizationV1>, context: {
+        signal: AbortSignal;
+    }): Promise<boolean>;
+    /** Optional operation lifetime, composed with each read deadline/caller signal. */
+    signal?: AbortSignal;
+    operationDeadlineMilliseconds?: number;
+    maxBytes?: number;
+}
+/** Restrictive provider-native URL grammar: no credentials, queries, encoding or traversal. */
+export declare function gcsReportingObjectFromUriV1(uri: string, bucket: string, prefix: string): string;
+export declare function createGcsScopedObjectReadV1(options: GcsReportingReaderOptionsV1): (uri: string, maxBytes: number, signal?: AbortSignal, nativeVersion?: string) => Promise<{
+    body: Buffer<ArrayBufferLike>;
+    contentType: string | undefined;
+    generation: string;
+}>;
+/** Destination-bound manifest/object reader. The caller never supplies bucket or credential scope. */
+export declare function createGcsReportingResourceReaderV1(options: GcsReportingReaderOptionsV1): ReportingResourceReader;
+/** Digest-pinned private contract resolver; all resolutions re-authorize and bypass caches. */
+export declare function createGcsReportingReferenceResolverV1(options: GcsReportingReaderOptionsV1): CanonicalReferenceResolver;

package/dist/lib/reporting/gcs/reader.js

@@ -0,0 +1,193 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var reader_exports = {};
+__export(reader_exports, {
+  createGcsReportingReferenceResolverV1: () => createGcsReportingReferenceResolverV1,
+  createGcsReportingResourceReaderV1: () => createGcsReportingResourceReaderV1,
+  createGcsScopedObjectReadV1: () => createGcsScopedObjectReadV1,
+  gcsReportingObjectFromUriV1: () => gcsReportingObjectFromUriV1
+});
+module.exports = __toCommonJS(reader_exports);
+var import_canonical_references = require('../../canonical-references/index.js');
+var import_object_writes = require('../ledger/object-writes.js');
+var import_errors = require('./errors.js');
+var import_io = require('./io.js');
+function gcsReportingObjectFromUriV1(uri, bucket, prefix) {
+  if (typeof uri !== "string" || uri.length > 2048) throw new import_errors.ReportingGcsFenceError("INVALID_INPUT");
+  const expectedBase = `https://storage.googleapis.com/${bucket}/`;
+  let parsed;
+  try {
+    parsed = new URL(uri);
+  } catch {
+    throw new import_errors.ReportingGcsFenceError("INVALID_INPUT");
+  }
+  const name = uri.startsWith(expectedBase) ? uri.slice(expectedBase.length) : "";
+  if (parsed.href !== uri || parsed.username || parsed.password || parsed.search || parsed.hash || !name.startsWith(prefix) || name.length <= prefix.length || name.length > 1024 || !/^[A-Za-z0-9/_.-]+$/.test(name) || name.split("/").some((part) => !part || part === "." || part === ".."))
+    throw new import_errors.ReportingGcsFenceError("INVALID_INPUT");
+  return name;
+}
+function createGcsScopedObjectReadV1(options) {
+  let scope;
+  try {
+    scope = structuredClone(options.scope);
+    (0, import_object_writes.assertReportingObjectWriteScope)(scope);
+  } catch {
+    throw new import_errors.ReportingGcsFenceError("INVALID_INPUT");
+  }
+  if (typeof scope.principal_id !== "string" || scope.principal_id.length < 1 || scope.principal_id.length > 255 || typeof options.bucket !== "string" || !/^[a-z0-9][a-z0-9.-]{1,220}[a-z0-9]$/.test(options.bucket) || typeof options.objectPrefix !== "string" || !/^[A-Za-z0-9/_.-]+\/$/.test(options.objectPrefix) || options.objectPrefix.length > 1e3 || options.objectPrefix.split("/").slice(0, -1).some((p) => !p || p === "." || p === "..") || typeof options.authorize !== "function" || typeof options.getStorage !== "function")
+    throw new import_errors.ReportingGcsFenceError("INVALID_INPUT");
+  Object.freeze(scope);
+  const { bucket, objectPrefix, authorize, getStorage, signal: parentSignal } = options;
+  if (parentSignal !== void 0 && !(parentSignal instanceof AbortSignal))
+    throw new import_errors.ReportingGcsFenceError("INVALID_INPUT");
+  const maximum = options.maxBytes ?? 64 * 1024 * 1024;
+  const milliseconds = options.operationDeadlineMilliseconds ?? 6e4;
+  if (!Number.isSafeInteger(maximum) || maximum < 1 || maximum > 64 * 1024 * 1024 || !Number.isSafeInteger(milliseconds) || milliseconds < 1 || milliseconds > 6e4)
+    throw new import_errors.ReportingGcsFenceError("INVALID_INPUT");
+  async function authorized(signal, objectName) {
+    (0, import_io.activeGcsSignal)(signal);
+    const allowed = await authorize({ scope, bucket, objectPrefix, objectName }, { signal });
+    (0, import_io.activeGcsSignal)(signal);
+    if (allowed !== true) throw new import_errors.ReportingGcsFenceError("REVOKED");
+  }
+  return async (uri, maxBytes, signal, nativeVersion) => (0, import_io.withGcsDeadline)(
+    async (active) => {
+      const name = gcsReportingObjectFromUriV1(uri, bucket, objectPrefix);
+      if (!Number.isSafeInteger(maxBytes) || maxBytes < 1 || nativeVersion !== void 0 && !/^[1-9][0-9]{0,39}$/.test(nativeVersion))
+        throw new import_errors.ReportingGcsFenceError("INVALID_INPUT");
+      await authorized(active, name);
+      const storage = await getStorage(scope, { signal: active });
+      (0, import_io.activeGcsSignal)(active);
+      try {
+        const file = storage.bucket(bucket).file(name, nativeVersion ? { generation: nativeVersion } : void 0);
+        const [metadata] = await file.getMetadata();
+        (0, import_io.activeGcsSignal)(active);
+        if (metadata.metadata?.adcp_reporting_tombstone !== void 0) throw new import_errors.ReportingGcsFenceError("REVOKED");
+        const generation = String(metadata.generation);
+        if (nativeVersion !== void 0 && generation !== nativeVersion)
+          throw new import_errors.ReportingGcsFenceError("CONTENT_CONFLICT");
+        if (!/^[1-9][0-9]{0,39}$/.test(generation) || !/^(?:0|[1-9][0-9]{0,19})$/.test(String(metadata.size)) || BigInt(String(metadata.size)) > BigInt(Math.min(maxBytes, maximum)))
+          throw new import_errors.ReportingGcsFenceError("CONTENT_CONFLICT");
+        const body = await (0, import_io.readGcsBytes)(
+          storage.bucket(bucket).file(name, { generation }),
+          Math.min(maxBytes, maximum),
+          active
+        );
+        (0, import_io.activeGcsSignal)(active);
+        await authorized(active, name);
+        return { body, contentType: metadata.contentType, generation };
+      } catch (error) {
+        (0, import_io.activeGcsSignal)(active);
+        if ((0, import_errors.isReportingGcsFenceError)(error)) throw error;
+        await authorized(active, name);
+        throw new import_errors.ReportingGcsFenceError("PROVIDER_UNAVAILABLE");
+      }
+    },
+    {
+      signal: parentSignal && signal ? AbortSignal.any([parentSignal, signal]) : parentSignal ?? signal,
+      milliseconds
+    }
+  );
+}
+function createGcsReportingResourceReaderV1(options) {
+  const read = createGcsScopedObjectReadV1(options);
+  const scope = structuredClone(options.scope);
+  const { bucket, objectPrefix } = options;
+  return {
+    async read(request) {
+      if (!request?.context?.materialization?.resource || !["manifest", "object"].includes(request.role) || request.context.obligation?.account_id !== scope.account_id || request.location !== request.context.materialization.resource.location || request.context.materialization.destination_ref !== scope.destination_ref)
+        throw new import_errors.ReportingGcsFenceError("INVALID_INPUT");
+      let uri = request.location;
+      if (request.role === "object") {
+        if (typeof request.objectRef !== "string" || !/^[A-Za-z0-9_.-]+$/.test(request.objectRef) || request.objectRef === "." || request.objectRef === "..")
+          throw new import_errors.ReportingGcsFenceError("INVALID_INPUT");
+        const name = gcsReportingObjectFromUriV1(request.location, bucket, objectPrefix);
+        uri = `https://storage.googleapis.com/${bucket}/${name.slice(0, name.lastIndexOf("/") + 1)}${request.objectRef}`;
+      }
+      return read(
+        uri,
+        request.maxBytes,
+        request.signal,
+        request.role === "manifest" ? request.context.materialization.resource?.native_version_ref : void 0
+      );
+    }
+  };
+}
+function createGcsReportingReferenceResolverV1(options) {
+  const read = createGcsScopedObjectReadV1(options);
+  const documentReader = {
+    async read(request) {
+      try {
+        return await read(request.uri, request.maxBytes, request.signal);
+      } catch (error) {
+        if ((0, import_errors.isReportingGcsFenceError)(error)) {
+          if (error.code === "ABORTED") throw new import_canonical_references.CanonicalDocumentReadError("aborted");
+          if (error.code === "INVALID_INPUT") throw new import_canonical_references.CanonicalDocumentReadError("unsafe_url");
+          if (error.code === "REVOKED") throw new import_canonical_references.CanonicalDocumentReadError("access_denied");
+          if (error.code === "CONTENT_CONFLICT") throw new import_canonical_references.CanonicalDocumentReadError("body_too_large");
+        }
+        throw new import_canonical_references.CanonicalDocumentReadError("network_error");
+      }
+    }
+  };
+  const parentSignal = options.signal;
+  const resolver = (0, import_canonical_references.createCanonicalReferenceResolver)({ documentReader, signal: parentSignal });
+  const routing = { bucket: options.bucket, objectPrefix: options.objectPrefix };
+  const forced = (input) => ({
+    ...input,
+    documentReader,
+    signal: parentSignal && input?.signal ? AbortSignal.any([parentSignal, input.signal]) : parentSignal ?? input?.signal
+  });
+  function blocked(ref, kind) {
+    try {
+      gcsReportingObjectFromUriV1(ref.uri, routing.bucket, routing.objectPrefix);
+      return void 0;
+    } catch {
+      return {
+        ok: false,
+        status: "blocked_unsafe_url",
+        kind,
+        ref: {
+          uri: "https://storage.googleapis.com/redacted-invalid-reference",
+          digest: /^sha256:[a-f0-9]{64}$/.test(ref?.digest) ? ref.digest : "invalid"
+        },
+        cacheKey: "private-reference-refused",
+        fromCache: false,
+        error: {
+          code: "unsafe_url",
+          message: "Private reference is outside the saved destination scope",
+          retryable: false
+        }
+      };
+    }
+  }
+  return {
+    cache: resolver.cache,
+    resolve: async (ref, context) => blocked(ref, "generic") ?? resolver.resolve(ref, forced(context)),
+    resolveFormatSchema: async (ref, context) => blocked(ref, "format_schema") ?? resolver.resolveFormatSchema(ref, forced(context)),
+    resolvePlatformExtensions: async (ref, context) => blocked(ref, "platform_extensions") ?? resolver.resolvePlatformExtensions(ref, forced(context))
+  };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  createGcsReportingReferenceResolverV1,
+  createGcsReportingResourceReaderV1,
+  createGcsScopedObjectReadV1,
+  gcsReportingObjectFromUriV1
+});

package/dist/lib/reporting/gcs/reader.mjs

@@ -0,0 +1,169 @@
+import {
+  CanonicalDocumentReadError,
+  createCanonicalReferenceResolver
+} from "../../canonical-references/index.mjs";
+import { assertReportingObjectWriteScope } from "../ledger/object-writes.mjs";
+import { ReportingGcsFenceError, isReportingGcsFenceError } from "./errors.mjs";
+import { activeGcsSignal, readGcsBytes, withGcsDeadline } from "./io.mjs";
+function gcsReportingObjectFromUriV1(uri, bucket, prefix) {
+  if (typeof uri !== "string" || uri.length > 2048) throw new ReportingGcsFenceError("INVALID_INPUT");
+  const expectedBase = `https://storage.googleapis.com/${bucket}/`;
+  let parsed;
+  try {
+    parsed = new URL(uri);
+  } catch {
+    throw new ReportingGcsFenceError("INVALID_INPUT");
+  }
+  const name = uri.startsWith(expectedBase) ? uri.slice(expectedBase.length) : "";
+  if (parsed.href !== uri || parsed.username || parsed.password || parsed.search || parsed.hash || !name.startsWith(prefix) || name.length <= prefix.length || name.length > 1024 || !/^[A-Za-z0-9/_.-]+$/.test(name) || name.split("/").some((part) => !part || part === "." || part === ".."))
+    throw new ReportingGcsFenceError("INVALID_INPUT");
+  return name;
+}
+function createGcsScopedObjectReadV1(options) {
+  let scope;
+  try {
+    scope = structuredClone(options.scope);
+    assertReportingObjectWriteScope(scope);
+  } catch {
+    throw new ReportingGcsFenceError("INVALID_INPUT");
+  }
+  if (typeof scope.principal_id !== "string" || scope.principal_id.length < 1 || scope.principal_id.length > 255 || typeof options.bucket !== "string" || !/^[a-z0-9][a-z0-9.-]{1,220}[a-z0-9]$/.test(options.bucket) || typeof options.objectPrefix !== "string" || !/^[A-Za-z0-9/_.-]+\/$/.test(options.objectPrefix) || options.objectPrefix.length > 1e3 || options.objectPrefix.split("/").slice(0, -1).some((p) => !p || p === "." || p === "..") || typeof options.authorize !== "function" || typeof options.getStorage !== "function")
+    throw new ReportingGcsFenceError("INVALID_INPUT");
+  Object.freeze(scope);
+  const { bucket, objectPrefix, authorize, getStorage, signal: parentSignal } = options;
+  if (parentSignal !== void 0 && !(parentSignal instanceof AbortSignal))
+    throw new ReportingGcsFenceError("INVALID_INPUT");
+  const maximum = options.maxBytes ?? 64 * 1024 * 1024;
+  const milliseconds = options.operationDeadlineMilliseconds ?? 6e4;
+  if (!Number.isSafeInteger(maximum) || maximum < 1 || maximum > 64 * 1024 * 1024 || !Number.isSafeInteger(milliseconds) || milliseconds < 1 || milliseconds > 6e4)
+    throw new ReportingGcsFenceError("INVALID_INPUT");
+  async function authorized(signal, objectName) {
+    activeGcsSignal(signal);
+    const allowed = await authorize({ scope, bucket, objectPrefix, objectName }, { signal });
+    activeGcsSignal(signal);
+    if (allowed !== true) throw new ReportingGcsFenceError("REVOKED");
+  }
+  return async (uri, maxBytes, signal, nativeVersion) => withGcsDeadline(
+    async (active) => {
+      const name = gcsReportingObjectFromUriV1(uri, bucket, objectPrefix);
+      if (!Number.isSafeInteger(maxBytes) || maxBytes < 1 || nativeVersion !== void 0 && !/^[1-9][0-9]{0,39}$/.test(nativeVersion))
+        throw new ReportingGcsFenceError("INVALID_INPUT");
+      await authorized(active, name);
+      const storage = await getStorage(scope, { signal: active });
+      activeGcsSignal(active);
+      try {
+        const file = storage.bucket(bucket).file(name, nativeVersion ? { generation: nativeVersion } : void 0);
+        const [metadata] = await file.getMetadata();
+        activeGcsSignal(active);
+        if (metadata.metadata?.adcp_reporting_tombstone !== void 0) throw new ReportingGcsFenceError("REVOKED");
+        const generation = String(metadata.generation);
+        if (nativeVersion !== void 0 && generation !== nativeVersion)
+          throw new ReportingGcsFenceError("CONTENT_CONFLICT");
+        if (!/^[1-9][0-9]{0,39}$/.test(generation) || !/^(?:0|[1-9][0-9]{0,19})$/.test(String(metadata.size)) || BigInt(String(metadata.size)) > BigInt(Math.min(maxBytes, maximum)))
+          throw new ReportingGcsFenceError("CONTENT_CONFLICT");
+        const body = await readGcsBytes(
+          storage.bucket(bucket).file(name, { generation }),
+          Math.min(maxBytes, maximum),
+          active
+        );
+        activeGcsSignal(active);
+        await authorized(active, name);
+        return { body, contentType: metadata.contentType, generation };
+      } catch (error) {
+        activeGcsSignal(active);
+        if (isReportingGcsFenceError(error)) throw error;
+        await authorized(active, name);
+        throw new ReportingGcsFenceError("PROVIDER_UNAVAILABLE");
+      }
+    },
+    {
+      signal: parentSignal && signal ? AbortSignal.any([parentSignal, signal]) : parentSignal ?? signal,
+      milliseconds
+    }
+  );
+}
+function createGcsReportingResourceReaderV1(options) {
+  const read = createGcsScopedObjectReadV1(options);
+  const scope = structuredClone(options.scope);
+  const { bucket, objectPrefix } = options;
+  return {
+    async read(request) {
+      if (!request?.context?.materialization?.resource || !["manifest", "object"].includes(request.role) || request.context.obligation?.account_id !== scope.account_id || request.location !== request.context.materialization.resource.location || request.context.materialization.destination_ref !== scope.destination_ref)
+        throw new ReportingGcsFenceError("INVALID_INPUT");
+      let uri = request.location;
+      if (request.role === "object") {
+        if (typeof request.objectRef !== "string" || !/^[A-Za-z0-9_.-]+$/.test(request.objectRef) || request.objectRef === "." || request.objectRef === "..")
+          throw new ReportingGcsFenceError("INVALID_INPUT");
+        const name = gcsReportingObjectFromUriV1(request.location, bucket, objectPrefix);
+        uri = `https://storage.googleapis.com/${bucket}/${name.slice(0, name.lastIndexOf("/") + 1)}${request.objectRef}`;
+      }
+      return read(
+        uri,
+        request.maxBytes,
+        request.signal,
+        request.role === "manifest" ? request.context.materialization.resource?.native_version_ref : void 0
+      );
+    }
+  };
+}
+function createGcsReportingReferenceResolverV1(options) {
+  const read = createGcsScopedObjectReadV1(options);
+  const documentReader = {
+    async read(request) {
+      try {
+        return await read(request.uri, request.maxBytes, request.signal);
+      } catch (error) {
+        if (isReportingGcsFenceError(error)) {
+          if (error.code === "ABORTED") throw new CanonicalDocumentReadError("aborted");
+          if (error.code === "INVALID_INPUT") throw new CanonicalDocumentReadError("unsafe_url");
+          if (error.code === "REVOKED") throw new CanonicalDocumentReadError("access_denied");
+          if (error.code === "CONTENT_CONFLICT") throw new CanonicalDocumentReadError("body_too_large");
+        }
+        throw new CanonicalDocumentReadError("network_error");
+      }
+    }
+  };
+  const parentSignal = options.signal;
+  const resolver = createCanonicalReferenceResolver({ documentReader, signal: parentSignal });
+  const routing = { bucket: options.bucket, objectPrefix: options.objectPrefix };
+  const forced = (input) => ({
+    ...input,
+    documentReader,
+    signal: parentSignal && input?.signal ? AbortSignal.any([parentSignal, input.signal]) : parentSignal ?? input?.signal
+  });
+  function blocked(ref, kind) {
+    try {
+      gcsReportingObjectFromUriV1(ref.uri, routing.bucket, routing.objectPrefix);
+      return void 0;
+    } catch {
+      return {
+        ok: false,
+        status: "blocked_unsafe_url",
+        kind,
+        ref: {
+          uri: "https://storage.googleapis.com/redacted-invalid-reference",
+          digest: /^sha256:[a-f0-9]{64}$/.test(ref?.digest) ? ref.digest : "invalid"
+        },
+        cacheKey: "private-reference-refused",
+        fromCache: false,
+        error: {
+          code: "unsafe_url",
+          message: "Private reference is outside the saved destination scope",
+          retryable: false
+        }
+      };
+    }
+  }
+  return {
+    cache: resolver.cache,
+    resolve: async (ref, context) => blocked(ref, "generic") ?? resolver.resolve(ref, forced(context)),
+    resolveFormatSchema: async (ref, context) => blocked(ref, "format_schema") ?? resolver.resolveFormatSchema(ref, forced(context)),
+    resolvePlatformExtensions: async (ref, context) => blocked(ref, "platform_extensions") ?? resolver.resolvePlatformExtensions(ref, forced(context))
+  };
+}
+export {
+  createGcsReportingReferenceResolverV1,
+  createGcsReportingResourceReaderV1,
+  createGcsScopedObjectReadV1,
+  gcsReportingObjectFromUriV1
+};

package/dist/lib/reporting/gcs/validation.d.mts

@@ -0,0 +1,5 @@
+import type { ReportingManagedDeliveryAdapterV1 } from '../ledger/managed.mjs';
+import type { ExpectedReportingPeriod } from '../reconciliation.mjs';
+type DeliveryInput = Parameters<ReportingManagedDeliveryAdapterV1['deliver']>[0];
+export declare function assertExpectedBinding(input: DeliveryInput, expected: ExpectedReportingPeriod): void;
+export {};

package/dist/lib/reporting/gcs/validation.d.ts

@@ -0,0 +1,5 @@
+import type { ReportingManagedDeliveryAdapterV1 } from '../ledger/managed';
+import type { ExpectedReportingPeriod } from '../reconciliation';
+type DeliveryInput = Parameters<ReportingManagedDeliveryAdapterV1['deliver']>[0];
+export declare function assertExpectedBinding(input: DeliveryInput, expected: ExpectedReportingPeriod): void;
+export {};

package/dist/lib/reporting/gcs/validation.js

@@ -0,0 +1,49 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var validation_exports = {};
+__export(validation_exports, {
+  assertExpectedBinding: () => assertExpectedBinding
+});
+module.exports = __toCommonJS(validation_exports);
+var import_jcs = require('../../utils/jcs.js');
+var import_errors = require('./errors.js');
+function assertExpectedBinding(input, expected) {
+  const {
+    binding,
+    revision: { wireRevision: r },
+    obligation
+  } = input;
+  const shaMatches = (a, b) => typeof a === "string" && /^[a-fA-F0-9]{64}$/.test(a) && /^[a-fA-F0-9]{64}$/.test(b) && a.toLowerCase() === b.toLowerCase();
+  if (expected.verificationProfile !== binding.verification_profile || expected.destinationRef !== binding.destination_ref || expected.deliveryMethod !== binding.method || expected.deliveryConfigId !== binding.delivery_config_id || expected.deliveryConfigVersion !== binding.delivery_config_version || expected.reportDefinitionId !== r.report_definition_id || expected.feedPurpose !== binding.feed_purpose || expected.reportingProfile !== r.reporting_profile || expected.reconciliationMode !== binding.reconciliation_mode || expected.requiredFinality !== obligation.requiredFinality || expected.periodStart !== r.period.start || expected.periodEnd !== r.period.end || (0, import_jcs.canonicalize)([...expected.mediaBuyIds].sort()) !== (0, import_jcs.canonicalize)([...r.media_buy_ids].sort()) || expected.reportDefinitionUri !== r.report_definition_uri || !shaMatches(r.report_definition_sha256, expected.reportDefinitionSha256) || expected.schemaUri !== r.schema_uri || !shaMatches(r.schema_sha256, expected.schemaSha256) || expected.schemaVersion !== r.schema_version || expected.schemaDialect !== r.schema_dialect || expected.schemaRefPolicy !== r.schema_ref_policy || r.finality === "official" && (!expected.officialFinality || expected.officialFinality.policyId !== r.finality_policy_id || expected.officialFinality.basis !== r.finality_basis))
+    throw new import_errors.ReportingGcsFenceError("CONTENT_CONFLICT");
+  const coverage = (value) => Object.fromEntries(
+    Object.entries(value).filter(([key]) => !["evaluated_at", "limitations"].includes(key)).map(([key, item]) => [key, Array.isArray(item) ? [...item].sort() : item])
+  );
+  if ((0, import_jcs.canonicalize)(coverage(expected.coverage)) !== (0, import_jcs.canonicalize)(coverage(r.coverage)))
+    throw new import_errors.ReportingGcsFenceError("CONTENT_CONFLICT");
+  if (expected.verificationProfile === "canonical_digest") {
+    const pin = expected.canonicalization, digest = r.canonical_content_digest;
+    if (!digest || digest.canonicalization_id !== pin.id || digest.canonicalization_uri !== pin.uri || !shaMatches(digest.canonicalization_sha256, pin.sha256))
+      throw new import_errors.ReportingGcsFenceError("CONTENT_CONFLICT");
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  assertExpectedBinding
+});

package/dist/lib/reporting/gcs/validation.mjs

@@ -0,0 +1,25 @@
+import { canonicalize } from "../../utils/jcs.mjs";
+import { ReportingGcsFenceError } from "./errors.mjs";
+function assertExpectedBinding(input, expected) {
+  const {
+    binding,
+    revision: { wireRevision: r },
+    obligation
+  } = input;
+  const shaMatches = (a, b) => typeof a === "string" && /^[a-fA-F0-9]{64}$/.test(a) && /^[a-fA-F0-9]{64}$/.test(b) && a.toLowerCase() === b.toLowerCase();
+  if (expected.verificationProfile !== binding.verification_profile || expected.destinationRef !== binding.destination_ref || expected.deliveryMethod !== binding.method || expected.deliveryConfigId !== binding.delivery_config_id || expected.deliveryConfigVersion !== binding.delivery_config_version || expected.reportDefinitionId !== r.report_definition_id || expected.feedPurpose !== binding.feed_purpose || expected.reportingProfile !== r.reporting_profile || expected.reconciliationMode !== binding.reconciliation_mode || expected.requiredFinality !== obligation.requiredFinality || expected.periodStart !== r.period.start || expected.periodEnd !== r.period.end || canonicalize([...expected.mediaBuyIds].sort()) !== canonicalize([...r.media_buy_ids].sort()) || expected.reportDefinitionUri !== r.report_definition_uri || !shaMatches(r.report_definition_sha256, expected.reportDefinitionSha256) || expected.schemaUri !== r.schema_uri || !shaMatches(r.schema_sha256, expected.schemaSha256) || expected.schemaVersion !== r.schema_version || expected.schemaDialect !== r.schema_dialect || expected.schemaRefPolicy !== r.schema_ref_policy || r.finality === "official" && (!expected.officialFinality || expected.officialFinality.policyId !== r.finality_policy_id || expected.officialFinality.basis !== r.finality_basis))
+    throw new ReportingGcsFenceError("CONTENT_CONFLICT");
+  const coverage = (value) => Object.fromEntries(
+    Object.entries(value).filter(([key]) => !["evaluated_at", "limitations"].includes(key)).map(([key, item]) => [key, Array.isArray(item) ? [...item].sort() : item])
+  );
+  if (canonicalize(coverage(expected.coverage)) !== canonicalize(coverage(r.coverage)))
+    throw new ReportingGcsFenceError("CONTENT_CONFLICT");
+  if (expected.verificationProfile === "canonical_digest") {
+    const pin = expected.canonicalization, digest = r.canonical_content_digest;
+    if (!digest || digest.canonicalization_id !== pin.id || digest.canonicalization_uri !== pin.uri || !shaMatches(digest.canonicalization_sha256, pin.sha256))
+      throw new ReportingGcsFenceError("CONTENT_CONFLICT");
+  }
+}
+export {
+  assertExpectedBinding
+};

package/dist/lib/reporting/ledger/handler.d.mts

@@ -13,6 +13,7 @@ export interface ReportingStatusConsumerScopeOptionsV1<TContext = unknown> {
      */
     consumerMismatchEscalation?: ReportingConsumerMismatchEscalationV1;
 }
+export declare function createReportingStatusHandler(store: ReportingLedgerStore): (request: Parameters<ReportingStatusHandlerV1>[0], context: Pick<Parameters<ReportingStatusHandlerV1>[1], 'account' | 'signal'>) => ReturnType<ReportingStatusHandlerV1>;
 export declare function createReportingStatusHandler<TContext = unknown>(store: ReportingLedgerStore, options?: ReportingStatusConsumerScopeOptionsV1<TContext>): ReportingStatusHandlerV1;
 /** Exact revision reader for createAdcpServer's getMediaBuyDelivery slot. */
 export declare function createReportingDeliveryHandler(store: ReportingLedgerStore): ReportingDeliveryHandlerV1;

package/dist/lib/reporting/ledger/handler.d.ts

@@ -13,6 +13,7 @@ export interface ReportingStatusConsumerScopeOptionsV1<TContext = unknown> {
      */
     consumerMismatchEscalation?: ReportingConsumerMismatchEscalationV1;
 }
+export declare function createReportingStatusHandler(store: ReportingLedgerStore): (request: Parameters<ReportingStatusHandlerV1>[0], context: Pick<Parameters<ReportingStatusHandlerV1>[1], 'account' | 'signal'>) => ReturnType<ReportingStatusHandlerV1>;
 export declare function createReportingStatusHandler<TContext = unknown>(store: ReportingLedgerStore, options?: ReportingStatusConsumerScopeOptionsV1<TContext>): ReportingStatusHandlerV1;
 /** Exact revision reader for createAdcpServer's getMediaBuyDelivery slot. */
 export declare function createReportingDeliveryHandler(store: ReportingLedgerStore): ReportingDeliveryHandlerV1;

package/dist/lib/reporting/ledger/index.d.mts

@@ -9,4 +9,5 @@ export * from './status-ingest.mjs';
 export * from './consumer-status-identity.mjs';
 export * from './managed.mjs';
 export * from './managed-postgres.mjs';
+export * from './object-writes.mjs';
 export * from './notification-activity.mjs';

package/dist/lib/reporting/ledger/index.d.ts

@@ -9,4 +9,5 @@ export * from './status-ingest';
 export * from './consumer-status-identity';
 export * from './managed';
 export * from './managed-postgres';
+export * from './object-writes';
 export * from './notification-activity';