> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bijection.com/llms.txt
> Use this file to discover all available pages before exploring further.

# S3 bucket

> Resources, examples, configuration and evidence for S3 bucket.

Use the `@bijectionhq/connectors/s3` entrypoint to declare S3 bucket resources.

## Availability

This page describes the pinned source package. Published availability is unestablished for this artifact. [Source build and package availability](https://docs.bijection.com/client/sdk-distribution.md).

## Resources and modes

| Resource | Mode | Description |
| - | - | - |
| S3 bucket | `poll` | Paged metadata and independent content |
| S3 bucket | `writable` | Paged files with conditional writes |
| S3 bucket | `references` | Metadata only |

Declare a resource in application code, then bind deployment-specific settings and credentials. See [typed resources](https://docs.bijection.com/integrations/resources.md), [connections](https://docs.bijection.com/integrations/connections.md) and [source inspection](https://docs.bijection.com/integrations/cli.md).

## S3 bucket

### poll: Paged metadata and independent content

The following example matches configuration `standard`.

```ts theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import { s3 } from "@bijectionhq/connectors/s3";
export const files = s3.bucket.poll();
```

> **Inferred record types**
>
> ```ts theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> items: {
>   "id": string;
>   "kind": "file";
>   "downloadable": boolean;
>   "content_version": string;
>   "size": string;
>   "last_modified": string | undefined;
> }
>
> contents: {
>   "id": string;
>   "file": Id<"_storage">;
>   "size": string;
>   "sha256": string;
>   "content_version": string | undefined;
> }
> ```

#### Configuration: standard

Case: `s3/bucket/poll/standard`.

Connection and resource configuration are declared by this exact case.

Credential kind: `s3`. Keep credential material in the private credential inventory.

| Setting | Type | Required | Owner |
| - | - | - | - |
| `bucketUrl` | string | Yes | Shared connection |
| `prefix` | string | Yes | Resource binding |

> **Complete configuration contract**
>
> ```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> {
>   "setup": [],
>   "resource": {
>     "access": {},
>     "defaults": {},
>     "connector": "s3",
>     "output": {
>       "kind": "bundle",
>       "collections": [
>         "contents",
>         "items"
>       ]
>     },
>     "credential_kind": "s3",
>     "connection_fields": [
>       "bucketUrl"
>     ],
>     "address": {
>       "kind": "setup",
>       "field": "bucketUrl"
>     }
>   },
>   "connection_setup": {
>     "type": "object",
>     "value": {
>       "bucketUrl": {
>         "fieldType": {
>           "type": "string"
>         },
>         "optional": false
>       },
>       "prefix": {
>         "fieldType": {
>           "type": "string"
>         },
>         "optional": false
>       }
>     }
>   },
>   "execution": null
> }
> ```

Native admission analysis has not been recorded for this artifact. Declared configuration does not establish native guarantees or provider behavior.

**Recorded checks**

| Requirement | Scope | Evidence | Result |
| - | - | - | - |
| page-publication-recovery | \{"kind":"collection","name":"contents"} | Provider behavior and native admission require exact-source remote receipts; no live provider account has been reached. | Execution result unavailable |
| page-publication-recovery | \{"kind":"collection","name":"items"} | Provider behavior and native admission require exact-source remote receipts; no live provider account has been reached. | Execution result unavailable |
| identity-account | \{"kind":"connection"} | Provider behavior and native admission require exact-source remote receipts; no live provider account has been reached. | Execution result unavailable |

Hosted qualification: **unestablished for this catalog configuration**. Installed connections report their own identity, authority and current status.

### writable: Paged files with conditional writes

The following example matches configuration `standard`.

```ts theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import { makeFunctionReference } from "bijection/server";
import { s3 } from "@bijectionhq/connectors/s3";
export const files = s3.bucket.writable({
  governingRule: makeFunctionReference<"query", any, [null]>("policies:write"),
});
```

> **Inferred record types**
>
> ```ts theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> items: {
>   "id": string;
>   "kind": "file";
>   "downloadable": boolean;
>   "content_version": string;
>   "size": string;
>   "last_modified": string | undefined;
> }
>
> contents: {
>   "id": string;
>   "file": Id<"_storage">;
>   "size": string;
>   "sha256": string;
>   "content_version": string | undefined;
> }
> ```

The function references identify application policy queries. Implement those policies in your application; the references alone grant no authority.

#### Configuration: standard

Case: `s3/bucket/writable/standard`.

Connection and resource configuration are declared by this exact case.

Credential kind: `s3`. Keep credential material in the private credential inventory.

| Setting | Type | Required | Owner |
| - | - | - | - |
| `bucketUrl` | string | Yes | Shared connection |
| `prefix` | string | Yes | Resource binding |

> **Complete configuration contract**
>
> ```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> {
>   "setup": [],
>   "resource": {
>     "access": {},
>     "defaults": {},
>     "connector": "s3",
>     "output": {
>       "kind": "bundle",
>       "collections": [
>         "contents",
>         "items"
>       ]
>     },
>     "credential_kind": "s3",
>     "connection_fields": [
>       "bucketUrl"
>     ],
>     "address": {
>       "kind": "setup",
>       "field": "bucketUrl"
>     }
>   },
>   "connection_setup": {
>     "type": "object",
>     "value": {
>       "bucketUrl": {
>         "fieldType": {
>           "type": "string"
>         },
>         "optional": false
>       },
>       "prefix": {
>         "fieldType": {
>           "type": "string"
>         },
>         "optional": false
>       }
>     }
>   },
>   "execution": null
> }
> ```

Native admission analysis has not been recorded for this artifact. Declared configuration does not establish native guarantees or provider behavior.

**Recorded checks**

| Requirement | Scope | Evidence | Result |
| - | - | - | - |
| page-publication-recovery | \{"kind":"collection","name":"contents"} | Conditional writes have portable contract evidence; remote admission and real-provider execution remain separate. | Execution result unavailable |
| page-publication-recovery | \{"kind":"collection","name":"items"} | Conditional writes have portable contract evidence; remote admission and real-provider execution remain separate. | Execution result unavailable |
| command-response-lost | \{"kind":"command","name":"create"} | Conditional writes have portable contract evidence; remote admission and real-provider execution remain separate. | Execution result unavailable |
| command-response-lost | \{"kind":"command","name":"delete"} | Conditional writes have portable contract evidence; remote admission and real-provider execution remain separate. | Execution result unavailable |
| command-response-lost | \{"kind":"command","name":"replace"} | Conditional writes have portable contract evidence; remote admission and real-provider execution remain separate. | Execution result unavailable |
| identity-account | \{"kind":"connection"} | Conditional writes have portable contract evidence; remote admission and real-provider execution remain separate. | Execution result unavailable |

Hosted qualification: **unestablished for this catalog configuration**. Installed connections report their own identity, authority and current status.

### references: Metadata only

The following example matches configuration `standard`.

```ts theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import { s3 } from "@bijectionhq/connectors/s3";
export const files = s3.bucket.references();
```

> **Inferred record types**
>
> ```ts theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> items: {
>   "id": string;
>   "kind": "file";
>   "downloadable": boolean;
>   "content_version": string;
>   "size": string;
>   "last_modified": string | undefined;
> }
> ```

#### Configuration: standard

Case: `s3/bucket/references/standard`.

Connection and resource configuration are declared by this exact case.

Credential kind: `s3`. Keep credential material in the private credential inventory.

| Setting | Type | Required | Owner |
| - | - | - | - |
| `bucketUrl` | string | Yes | Shared connection |
| `prefix` | string | Yes | Resource binding |

> **Complete configuration contract**
>
> ```json theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> {
>   "setup": [],
>   "resource": {
>     "access": {},
>     "defaults": {},
>     "connector": "s3",
>     "output": {
>       "kind": "bundle",
>       "collections": [
>         "items"
>       ]
>     },
>     "credential_kind": "s3",
>     "connection_fields": [
>       "bucketUrl"
>     ],
>     "address": {
>       "kind": "setup",
>       "field": "bucketUrl"
>     }
>   },
>   "connection_setup": {
>     "type": "object",
>     "value": {
>       "bucketUrl": {
>         "fieldType": {
>           "type": "string"
>         },
>         "optional": false
>       },
>       "prefix": {
>         "fieldType": {
>           "type": "string"
>         },
>         "optional": false
>       }
>     }
>   },
>   "execution": null
> }
> ```

Native admission analysis has not been recorded for this artifact. Declared configuration does not establish native guarantees or provider behavior.

**Recorded checks**

| Requirement | Scope | Evidence | Result |
| - | - | - | - |
| page-publication-recovery | \{"kind":"collection","name":"items"} | Reference mode declares no content downloads; hosted behavior remains unestablished. | Execution result unavailable |
| identity-account | \{"kind":"connection"} | Reference mode declares no content downloads; hosted behavior remains unestablished. | Execution result unavailable |

Hosted qualification: **unestablished for this catalog configuration**. Installed connections report their own identity, authority and current status.

## Provider guidance

```ts theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
import { s3 } from "@bijectionhq/connectors/s3";
export const files = s3.bucket.poll({
  maxContentBytes: 256 * 1024 * 1024,
});
```

Bind a bucket URL (`bucketUrl`, including the bucket in a path-style endpoint or
using its virtual host) and an explicit `prefix`, which may be empty. The
connection's private `s3` credential is a SigV4 envelope with the correct region
and service `s3`; neither access keys nor secrets belong in source code.
Native request resolution checks point keys against the installed prefix before
I/O. Native evidence extraction checks listing keys after their one declared
percent decode, so guest code cannot publish keys outside that prefix. An empty
prefix selects the whole bucket.

`items` publishes each ListObjectsV2 page immediately. Keys use
encoding-type=url and are decoded exactly once, preserving plus signs. Sizes
remain exact decimal text. The listing's ETag is an opaque content version,
including multipart and encrypted objects; it is never labeled SHA-256. Terminal
pages establish no multi-page snapshot. The next scheduled pass starts from the
beginning. A daily HEAD reconciliation withdraws a published key only on 404;
403 is unresolved. This mode targets general-purpose S3 buckets and compatible
APIs, not directory buckets or an object-version history.

`contents` drains separate durable per-key obligations. A metadata change and
its obligation commit together; a failed download does not hold the listing. The
native host streams bytes into protected storage, computes SHA-256 and publishes
the file reference and exact size atomically. `s3.bucket.references()` publishes
metadata without automatically acquiring bytes. The current maximum is 1 GiB per
file; the default is 256 MiB. Larger or interrupted bodies remain unresolved and
never publish truncated content. There are no writes in this mode.

Application authorization governs published data. Provider object ACLs are not
imported as application permissions. No live S3 qualification is implied by a
portable fixture or an exported declaration.

## Conditional writes

`s3.bucket.writable({ governingRule })` adds `create`, `replace` and `delete`
while preserving independent metadata and content acquisition. `create` prefixes
its relative `key` with the bound selection and sends `If-None-Match: *`.
`replace` and `delete` target an acquired `contents` row and send its host-owned
response ETag as `If-Match`. Freeze the reviewed token with
`ctx.sources.commandTarget(row._id, { version: "content" })` and pass its
`expectedVersion` when admitting the command. Metadata version and content
version remain separate.

Uploads stream a protected file, bounded by `maxContentBytes` (at most 1 GiB).
Each command has one delivery attempt; lost responses and ambiguous provider
errors stay unknown. A later matching object or absence does not attribute an
operation's effect. Readback uses HEAD, and confirmed writes are acquired through
the ordinary source owner. This mode does not provide multipart upload sessions.
The governing rule and current source scope are rechecked by the native command
owner. The selected credential must have the corresponding provider authority.

These preconditions are documented for general-purpose AWS S3 buckets;
compatible services must implement the same semantics:
[conditional writes](https://docs.aws.amazon.com/AmazonS3/latest/userguide/conditional-writes.html)
and [conditional deletes](https://docs.aws.amazon.com/AmazonS3/latest/userguide/conditional-deletes.html).

## Provider references

Provider references and prerequisites are maintained in the connector guidance above. No separate provider-documentation review date is recorded.

## Source and evidence

[Canonical connector source](https://github.com/bijectionhq/component-support/blob/80d6b8b52265070a1008a58e4a99df086f94771a/packages/connectors/src/connectors/s3/README.md), [native analysis](https://github.com/bijectionhq/component-support/blob/80d6b8b52265070a1008a58e4a99df086f94771a/packages/connectors/contract-analysis.json) and [check receipts](https://github.com/bijectionhq/component-support/blob/80d6b8b52265070a1008a58e4a99df086f94771a/packages/connectors/evidence.json).

Connector artifact: `4f299f628dc463dd516cd6941e78813d3b2e27f88a9a37a14af7837a20805b62`.

The resource declaration examples above are compiled and compared with exact catalog declarations. Recorded checks apply only to their source, declaration and runtime identities. Configure a connection and inspect its status to establish deployment-specific readiness.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.