integration.provider-storage

@lssm-tech/integration.provider-storage

Website: https://contractspec.io

Object storage provider implementations for ContractSpec.

Usage

Import the root entrypoint for the domain surface, or import a concrete implementation from the ./impls/* subpaths.

Compatibility

This package owns the storage implementation slice split out of @lssm-tech/integration.providers-impls. The legacy package continues to re-export these subpaths for existing consumers.

Approved S3 reads

S3ObjectReader from @lssm-tech/integration.provider-storage/impls/s3-object-reader implements the narrow ObjectStorageReadProvider capability. It accepts an existing AWS SDK S3 client with host-resolved scoped credentials; it creates no client and reads no environment variables. Configure exact bucket/key approvals with a byte limit and expected SHA-256, optionally an S3 version ID. No write, delete, listing or signed-URL methods are exposed. Keep IAM grants restricted to the same objects.

const reader = new S3ObjectReader(client, [{
  bucket: 'private-knowledge', key: 'approved/source.txt',
  maxBytes: 1048576, expectedSha256: approvedSourceDigest,
}], 10000);
const object = await reader.getObject({
  bucket: 'private-knowledge', key: 'approved/source.txt', signal,
});

The reader forwards cancellation to the SDK, bounds response/body waits, and requests stream teardown when interrupted. Only fully buffered, digest-verified bytes are returned. Missing keys return null; permission and provider failures remain redacted errors. Cancellation does not independently prove remote IO stopped. This server-only reader is not a full S3 lifecycle provider.

Transport behavior follows the AWS SDK v3 S3 examples and SDK AbortController support.

Qualification: the initial reader completed an actual Railway S3 read of the approved 176-byte synthetic pilot object with its exact SHA-256. Unapproved-key and pre-aborted requests made no provider calls. This is scoped read evidence; full S3 lifecycle, live interrupted-network cleanup and broader cloud qualification remain separate acceptance requirements.

Supabase Storage (S3 protocol)

supabaseStorageS3ClientConfig({ endpoint, region, accessKeyId, secretAccessKey }) from @lssm-tech/integration.provider-storage/impls/supabase-storage-s3 returns an AWS SDK client configuration for https://<ref>.storage.supabase.co/storage/v1/s3: path-style addressing, no SDK retries, and checksums only when an operation requires them. Supabase's PutObject ignores If-None-Match and checksum headers, so pair it with new S3ObjectWriter(client, { ..., conditionalWrite: 'head-verify' }): the writer heads the (content-addressed) key, writes only when it is absent and verifies the stored object afterwards (SHA-256 metadata, or size plus MD5 ETag), refusing any conflicting object. Keep the bucket private.