@adcp/sdk 14.4.0 → 15.2.0

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

@@ -0,0 +1,230 @@
+import { createHash } from "node:crypto";
+import {
+  assertReportingObjectWriteScope,
+  reportingObjectWritePlanFingerprint,
+  reportingObjectWriteName,
+  reportingObjectWriteScopeKey
+} from "../ledger/object-writes.mjs";
+import { ReportingGcsFenceError, isReportingGcsFenceError } from "./errors.mjs";
+import { activeGcsSignal as active, withGcsDeadline, readGcsBytes } from "./io.mjs";
+import { assertGcsReportingBucketPolicy } from "./bucket-policy.mjs";
+const hash = (bytes) => createHash("sha256").update(bytes).digest("hex");
+const TOMBSTONE = "adcp_reporting_tombstone";
+import { ReportingGcsFenceError as ReportingGcsFenceError2 } from "./errors.mjs";
+function createGcsReportingObjectFenceV1(options) {
+  if (!options || typeof options.bucket !== "string" || !/^[a-z0-9][a-z0-9.-]{1,220}[a-z0-9]$/.test(options.bucket) || typeof options.namespace !== "string" || options.namespace.length < 1 || options.namespace.length > 255 || !options.storage || typeof options.storage.bucket !== "function" || !options.store)
+    throw new ReportingGcsFenceError("INVALID_INPUT");
+  const { storage, store, bucket: bucketName, namespace } = options;
+  const deadline = options.operationDeadlineMilliseconds ?? 6e4;
+  if (!Number.isSafeInteger(deadline) || deadline < 1 || deadline > 6e4)
+    throw new ReportingGcsFenceError("INVALID_INPUT");
+  const provider = { bucket: bucketName, namespace_key: hash(namespace) };
+  const status = (error, code) => !!error && typeof error === "object" && "code" in error && Number(error.code) === code;
+  const bounded = (work, signal) => withGcsDeadline(work, { signal, milliseconds: deadline });
+  async function probe(bucket, signal) {
+    active(signal);
+    try {
+      const [metadata] = await bucket.getMetadata();
+      active(signal);
+      try {
+        assertGcsReportingBucketPolicy(metadata);
+      } catch {
+        throw new ReportingGcsFenceError("UNSAFE_BUCKET");
+      }
+    } catch (error) {
+      active(signal);
+      if (isReportingGcsFenceError(error)) throw error;
+      throw new ReportingGcsFenceError("PROVIDER_UNAVAILABLE");
+    }
+  }
+  function assertScope(scope) {
+    try {
+      assertReportingObjectWriteScope(scope);
+    } catch {
+      throw new ReportingGcsFenceError("INVALID_INPUT");
+    }
+  }
+  function assertPlan(plan) {
+    try {
+      reportingObjectWritePlanFingerprint(plan);
+    } catch {
+      throw new ReportingGcsFenceError("INVALID_INPUT");
+    }
+    if (plan.provider.bucket !== bucketName || plan.provider.namespace_key !== provider.namespace_key)
+      throw new ReportingGcsFenceError("INVALID_INPUT");
+  }
+  async function register(scope, deliveryId, bodies, signal) {
+    assertScope(scope);
+    if (typeof deliveryId !== "string" || deliveryId.length < 1 || deliveryId.length > 255 || !Array.isArray(bodies) || bodies.length < 1 || bodies.length > 128 || bodies.some((b) => !(b instanceof Uint8Array) || b.byteLength > 64 * 1024 * 1024) || bodies.reduce((total, b) => total + b.byteLength, 0) > 64 * 1024 * 1024)
+      throw new ReportingGcsFenceError("INVALID_INPUT");
+    const scopeCopy = {
+      account_id: scope.account_id,
+      destination_ref: scope.destination_ref,
+      generation: scope.generation
+    };
+    const planId = hash(deliveryId);
+    const plan = {
+      ...scopeCopy,
+      provider: { ...provider },
+      plan_id: planId,
+      objects: bodies.map((b, i) => ({
+        bucket: bucketName,
+        object_name: reportingObjectWriteName(scopeCopy, provider, planId, i),
+        sha256: hash(b),
+        size_bytes: b.byteLength
+      }))
+    };
+    await probe(storage.bucket(bucketName), signal);
+    active(signal);
+    const registered = await store.registerObjectWritePlan(plan, { signal });
+    active(signal);
+    if (registered === "revoked") throw new ReportingGcsFenceError("REVOKED");
+    return plan;
+  }
+  async function write(input, index, inputBytes, signal) {
+    const plan = structuredClone(input);
+    assertPlan(plan);
+    const expected = plan.objects[index];
+    if (!Number.isInteger(index) || !expected || !(inputBytes instanceof Uint8Array))
+      throw new ReportingGcsFenceError("INVALID_INPUT");
+    if (inputBytes.byteLength !== expected.size_bytes) throw new ReportingGcsFenceError("CONTENT_CONFLICT");
+    const bytes = Buffer.from(inputBytes);
+    if (hash(bytes) !== expected.sha256) throw new ReportingGcsFenceError("CONTENT_CONFLICT");
+    active(signal);
+    const bucket = storage.bucket(bucketName);
+    await probe(bucket, signal);
+    active(signal);
+    const registered = await store.registerObjectWritePlan(plan, { signal });
+    active(signal);
+    if (registered === "revoked") throw new ReportingGcsFenceError("REVOKED");
+    const file = bucket.file(expected.object_name);
+    try {
+      await file.save(bytes, {
+        resumable: false,
+        preconditionOpts: { ifGenerationMatch: 0 },
+        metadata: { cacheControl: "no-store" }
+      });
+      active(signal);
+    } catch (error) {
+      active(signal);
+      if (!status(error, 412)) throw new ReportingGcsFenceError("PROVIDER_UNAVAILABLE");
+      try {
+        const [metadata] = await file.getMetadata();
+        active(signal);
+        if (metadata.metadata?.[TOMBSTONE] !== void 0) throw new ReportingGcsFenceError("REVOKED");
+        const existing = await readGcsBytes(
+          bucket.file(expected.object_name, { generation: metadata.generation }),
+          bytes.length,
+          signal
+        );
+        if (existing.length !== bytes.length || hash(existing) !== expected.sha256)
+          throw new ReportingGcsFenceError("CONTENT_CONFLICT");
+      } catch (error2) {
+        active(signal);
+        if (status(error2, 404)) {
+          const current = await store.registerObjectWritePlan(plan, { signal });
+          active(signal);
+          if (current === "revoked") throw new ReportingGcsFenceError("REVOKED");
+        }
+        if (isReportingGcsFenceError(error2)) throw error2;
+        throw new ReportingGcsFenceError("PROVIDER_UNAVAILABLE");
+      }
+    }
+    active(signal);
+    if (await store.registerObjectWritePlan(plan, { signal }) === "revoked")
+      throw new ReportingGcsFenceError("REVOKED");
+    active(signal);
+  }
+  async function revoke(scopeInput, maxObjects, signal) {
+    assertScope(scopeInput);
+    const scope = {
+      account_id: scopeInput.account_id,
+      destination_ref: scopeInput.destination_ref,
+      generation: scopeInput.generation
+    };
+    const limit = maxObjects ?? 10;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 1e3) throw new ReportingGcsFenceError("INVALID_INPUT");
+    active(signal);
+    const binding = await store.getObjectWriteBinding(scope, { signal });
+    active(signal);
+    const objects = await store.listRevokedObjectWrites(scope, { limit }, { signal });
+    active(signal);
+    if (!binding) {
+      if (objects.length) throw new ReportingGcsFenceError("STATE_UNAVAILABLE");
+      return { fenced: 0, complete: true };
+    }
+    const bucket = storage.bucket(binding.bucket);
+    await probe(bucket, signal);
+    const scopeKey = reportingObjectWriteScopeKey(scope);
+    for (const object of objects) {
+      active(signal);
+      if (object.bucket !== binding.bucket || object.object_name !== reportingObjectWriteName(scope, binding, object.plan_id, object.object_index))
+        throw new ReportingGcsFenceError("STATE_UNAVAILABLE");
+      const file = bucket.file(object.object_name);
+      let fencedGeneration;
+      for (let attempt = 0; attempt < 4 && !fencedGeneration; attempt++) {
+        active(signal);
+        let generation = 0;
+        try {
+          const [metadata] = await file.getMetadata();
+          active(signal);
+          generation = String(metadata.generation);
+          if (metadata.metadata?.[TOMBSTONE] === scopeKey && String(metadata.size) === "0") {
+            fencedGeneration = String(metadata.generation);
+            break;
+          }
+        } catch (error) {
+          active(signal);
+          if (!status(error, 404)) throw new ReportingGcsFenceError("PROVIDER_UNAVAILABLE");
+        }
+        active(signal);
+        try {
+          await file.save(Buffer.alloc(0), {
+            resumable: false,
+            preconditionOpts: { ifGenerationMatch: generation },
+            metadata: { cacheControl: "no-store", metadata: { [TOMBSTONE]: scopeKey } }
+          });
+          active(signal);
+          const [verified] = await file.getMetadata();
+          active(signal);
+          if (verified.metadata?.[TOMBSTONE] !== scopeKey || String(verified.size) !== "0")
+            throw new ReportingGcsFenceError("PROVIDER_UNAVAILABLE");
+          fencedGeneration = String(verified.generation);
+        } catch (error) {
+          active(signal);
+          if (isReportingGcsFenceError(error)) throw error;
+          if (!status(error, 412)) throw new ReportingGcsFenceError("PROVIDER_UNAVAILABLE");
+        }
+      }
+      if (!fencedGeneration) throw new ReportingGcsFenceError("PROVIDER_UNAVAILABLE");
+      active(signal);
+      await store.markObjectWriteFenced(
+        {
+          ...scope,
+          plan_id: object.plan_id,
+          object_index: object.object_index,
+          tombstone_generation: fencedGeneration
+        },
+        { signal }
+      );
+      active(signal);
+    }
+    const remaining = await store.listRevokedObjectWrites(scope, { limit: 1 }, { signal });
+    active(signal);
+    return { fenced: objects.length, complete: remaining.length === 0 };
+  }
+  function requireSignal(context) {
+    if (!(context?.signal instanceof AbortSignal)) throw new ReportingGcsFenceError("INVALID_INPUT");
+    return context.signal;
+  }
+  return {
+    probe: async (context) => bounded((signal) => probe(storage.bucket(bucketName), signal), context?.signal),
+    register: async (scope, deliveryId, bodies, context) => bounded((signal) => register(scope, deliveryId, bodies, signal), context?.signal),
+    write: async (plan, index, bytes, context) => bounded((signal) => write(plan, index, bytes, signal), requireSignal(context)),
+    revoke: async (scope, context) => bounded((signal) => revoke(scope, context.maxObjects, signal), requireSignal(context))
+  };
+}
+export {
+  ReportingGcsFenceError2 as ReportingGcsFenceError,
+  createGcsReportingObjectFenceV1
+};

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

@@ -0,0 +1,7 @@
+export { createGcsReportingObjectFenceV1 } from './fence.mjs';
+export type { GcsReportingObjectFenceV1 } from './fence.mjs';
+export { ReportingGcsFenceError, isReportingGcsFenceError } from './errors.mjs';
+export { createGcsReportingResourceReaderV1, createGcsReportingReferenceResolverV1 } from './reader.mjs';
+export type { GcsReportingReadScopeV1, GcsReportingReadAuthorizationV1, GcsReportingReaderOptionsV1 } from './reader.mjs';
+export { createGcsReportingManagedDeliveryAdapterV1 } from './adapter.mjs';
+export type { CreateGcsReportingManagedDeliveryAdapterOptionsV1 } from './adapter.mjs';

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

@@ -0,0 +1,7 @@
+export { createGcsReportingObjectFenceV1 } from './fence';
+export type { GcsReportingObjectFenceV1 } from './fence';
+export { ReportingGcsFenceError, isReportingGcsFenceError } from './errors';
+export { createGcsReportingResourceReaderV1, createGcsReportingReferenceResolverV1 } from './reader';
+export type { GcsReportingReadScopeV1, GcsReportingReadAuthorizationV1, GcsReportingReaderOptionsV1 } from './reader';
+export { createGcsReportingManagedDeliveryAdapterV1 } from './adapter';
+export type { CreateGcsReportingManagedDeliveryAdapterOptionsV1 } from './adapter';

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

@@ -0,0 +1,41 @@
+"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 gcs_exports = {};
+__export(gcs_exports, {
+  ReportingGcsFenceError: () => import_errors.ReportingGcsFenceError,
+  createGcsReportingManagedDeliveryAdapterV1: () => import_adapter.createGcsReportingManagedDeliveryAdapterV1,
+  createGcsReportingObjectFenceV1: () => import_fence.createGcsReportingObjectFenceV1,
+  createGcsReportingReferenceResolverV1: () => import_reader.createGcsReportingReferenceResolverV1,
+  createGcsReportingResourceReaderV1: () => import_reader.createGcsReportingResourceReaderV1,
+  isReportingGcsFenceError: () => import_errors.isReportingGcsFenceError
+});
+module.exports = __toCommonJS(gcs_exports);
+var import_fence = require('./fence.js');
+var import_errors = require('./errors.js');
+var import_reader = require('./reader.js');
+var import_adapter = require('./adapter.js');
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ReportingGcsFenceError,
+  createGcsReportingManagedDeliveryAdapterV1,
+  createGcsReportingObjectFenceV1,
+  createGcsReportingReferenceResolverV1,
+  createGcsReportingResourceReaderV1,
+  isReportingGcsFenceError
+});

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

@@ -0,0 +1,12 @@
+import { createGcsReportingObjectFenceV1 } from "./fence.mjs";
+import { ReportingGcsFenceError, isReportingGcsFenceError } from "./errors.mjs";
+import { createGcsReportingResourceReaderV1, createGcsReportingReferenceResolverV1 } from "./reader.mjs";
+import { createGcsReportingManagedDeliveryAdapterV1 } from "./adapter.mjs";
+export {
+  ReportingGcsFenceError,
+  createGcsReportingManagedDeliveryAdapterV1,
+  createGcsReportingObjectFenceV1,
+  createGcsReportingReferenceResolverV1,
+  createGcsReportingResourceReaderV1,
+  isReportingGcsFenceError
+};

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

@@ -0,0 +1,7 @@
+import type { File } from '@google-cloud/storage';
+export declare function activeGcsSignal(signal: AbortSignal): void;
+export declare function withGcsDeadline<T>(work: (signal: AbortSignal) => Promise<T>, context?: {
+    signal?: AbortSignal;
+    milliseconds?: number;
+}): Promise<T>;
+export declare function readGcsBytes(file: File, maxBytes: number, signal: AbortSignal): Promise<Buffer>;

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

@@ -0,0 +1,7 @@
+import type { File } from '@google-cloud/storage';
+export declare function activeGcsSignal(signal: AbortSignal): void;
+export declare function withGcsDeadline<T>(work: (signal: AbortSignal) => Promise<T>, context?: {
+    signal?: AbortSignal;
+    milliseconds?: number;
+}): Promise<T>;
+export declare function readGcsBytes(file: File, maxBytes: number, signal: AbortSignal): Promise<Buffer>;

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

@@ -0,0 +1,95 @@
+"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 io_exports = {};
+__export(io_exports, {
+  activeGcsSignal: () => activeGcsSignal,
+  readGcsBytes: () => readGcsBytes,
+  withGcsDeadline: () => withGcsDeadline
+});
+module.exports = __toCommonJS(io_exports);
+var import_object_writes = require('../ledger/object-writes.js');
+var import_errors = require('./errors.js');
+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 import_errors.ReportingGcsFenceError("INVALID_INPUT");
+  if (signal !== void 0 && !(signal instanceof AbortSignal)) throw new import_errors.ReportingGcsFenceError("INVALID_INPUT");
+  const controller = new AbortController();
+  const onAbort = () => controller.abort(new import_errors.ReportingGcsFenceError("ABORTED"));
+  signal?.addEventListener("abort", onAbort, { once: true });
+  if (signal?.aborted) onAbort();
+  const timer = setTimeout(() => controller.abort(new import_errors.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 ((0, import_errors.isReportingGcsFenceError)(error)) throw error;
+    if ((0, import_object_writes.isReportingObjectWriteConflictError)(error) || error instanceof Error && (0, import_object_writes.isReportingObjectWriteConflictError)(error.cause))
+      throw new import_errors.ReportingGcsFenceError("CONTENT_CONFLICT");
+    if ((0, import_object_writes.isReportingObjectWriteNotRevokedError)(error) || error instanceof Error && (0, import_object_writes.isReportingObjectWriteNotRevokedError)(error.cause))
+      throw new import_errors.ReportingGcsFenceError("NOT_REVOKED");
+    throw new import_errors.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 import_errors.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 import_errors.ReportingGcsFenceError("CONTENT_CONFLICT");
+      chunks.push(Buffer.from(chunk));
+    }
+    active(signal);
+    return Buffer.concat(chunks);
+  } finally {
+    signal.removeEventListener("abort", abort);
+    stream.destroy();
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  activeGcsSignal,
+  readGcsBytes,
+  withGcsDeadline
+});

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;