@alneas/eaos-server 0.0.0-stage → 0.1.0

package/docs/lifecycle/docs/baseline.md

@@ -0,0 +1,50 @@
+---
+title: "Data Contract baselines"
+description: "Keep portable declarations separate from trusted host execution, current access checks and durable effects."
+sidebar:
+  order: 20
+archetype: "explanation"
+project: "eaos-workspace"
+tags: ["eaos", "explanation"]
+---
+
+# Data Contract baselines
+
+## Motivation
+
+Keep portable declarations separate from trusted host execution, current access checks and durable effects.
+
+## Architectural Diagram
+
+```mermaid
+flowchart LR
+  Contract[Public contract] --> Host[Verified host scope]
+  Host --> Operation[Explicit runtime operation]
+  Operation --> Validation[Result and permission verification]
+```
+
+## Public import
+
+Install the package; the subpath below is an import target, not a separate package. Registry installation requires a published EAOS release; before publication use the owning workspace's checksum-verified build artifact.
+
+```bash
+bun add @alneas/eaos-server
+```
+
+```typescript
+import { createDataContractBaseline } from '@alneas/eaos-server/lifecycle-engine/baseline'
+
+export const describeBaseline = createDataContractBaseline
+```
+
+Server tooling only. Descriptor creation does not verify SQL equivalence or rebase an installed ledger; those are separate reviewed operations.
+
+## Trade-offs & Decisions
+
+`createDataContractBaseline(source, version, finalSql)` creates an immutable descriptor with source and target contracts, source migration IDs/positions/checksums and an integrity hash. The new contract version must increase, every original SQL dialect must remain represented and all replaced migrations must be database-scoped. The supplied SQL must describe the final schema, rather than a concatenated history. Provider tooling owns SQL equivalence review.
+
+`rebaseDataContractBaseline(store, databaseId, descriptor, { expectedRevision, quiesce })` runs under the existing exclusive Lifecycle writer lock. It checks the complete installed source contract and every applied checksum, scope and position. Partial, dirty, modified or stale history is rejected. Installed consumers must accept the target contract version. Active consumers require an all-instance drain callback and are disabled before the ledger changes.
+
+No DDL runs during rebase. Old records and the exact source contract remain in `LifecycleState.baselineHistory`. The current migration ledger advances to the baseline; the installed Data Contract advances to the target. New hosts execute the target's final DDL normally. Existing hosts rebased against matching history skip it. A second unrelated apply still uses ordinary plan/review/revision rules. Preserve the baseline descriptor and archived source with the release.
+
+The CLI's `db:baseline` automatically compiles SQLite, PostgreSQL and Oracle schema histories in fresh local databases and verifies an independent rebuild. It retains the archived contract, complete replaced-history checksums and compiler evidence. PostgreSQL/Oracle require checksum-pinned local Docker images; no production DSN is accepted. Generation is separate from ledger rebase. Unsupported object classes are rejected rather than silently omitted. See the CLI baseline guide for compiler boundaries.

package/docs/lifecycle/docs/guide.md

@@ -0,0 +1,47 @@
+---
+title: "Lifecycle ownership and host boundaries"
+description: "Installation, upgrades, activation, migration history, placement and completion evidence. This capability belongs to @alneas/eaos-server; it is not a separate npm package."
+sidebar:
+  order: 20
+archetype: "explanation"
+project: "eaos-workspace"
+tags: ["eaos", "explanation"]
+---
+
+# Lifecycle ownership and host boundaries
+
+## Motivation
+
+Installation, upgrades, activation, migration history, placement and completion evidence. This capability belongs to `@alneas/eaos-server`; it is not a separate npm package.
+
+## Architectural Diagram
+
+```mermaid
+flowchart LR
+  Host[Trusted host] --> Adapter[Scoped Server adapter]
+  Adapter --> Store[Host-owned durable provider]
+```
+
+## Public import
+
+Install the package; the subpath below is an import target, not a separate package. Registry installation requires a published EAOS release; before publication use the owning workspace's checksum-verified build artifact.
+
+```bash
+bun add @alneas/eaos-server
+```
+
+```typescript
+import { resolveDataContracts } from '@alneas/eaos-server/lifecycle-engine'
+
+export const resolveHostContracts = resolveDataContracts
+```
+
+Server runtime only. Supply durable lifecycle state, exclusive writer locking and reviewed host executors before applying a plan.
+
+## Trade-offs & Decisions
+
+Apply only a reviewed current plan under an exclusive writer lock. Active upgrades require all-instance drain. Shared hosts use one transactional control store. Disable/uninstall retain data and history. Dirty DDL requires reconciliation rather than blind retry or automatic lock expiry.
+
+See [baseline descriptors](baseline.md) for integrity-pinned, non-DDL ledger rebase with retained source history.
+
+The host owns verified identity, tenant boundaries, credentials and real provider adoption. Package builds and tests never apply production changes or activate tenants. Review the [API reference](api.md) before binding the host.

package/docs/storage/README.md

@@ -0,0 +1,49 @@
+---
+title: "Storage capability"
+description: "Host developers use @alneas/eaos-server/storage for tenant/plugin-scoped storage."
+sidebar:
+  order: 20
+archetype: "explanation"
+project: "eaos-workspace"
+tags: ["eaos", "explanation"]
+---
+
+# Storage capability
+
+## Elevator Pitch
+
+Host developers use `@alneas/eaos-server/storage` for tenant/plugin-scoped storage.
+
+## Why & Value
+
+This topic belongs to `@alneas/eaos-server` and is not an independently installed package. Shared contracts keep capability ownership clear while host identity, provider configuration and acceptance remain explicit.
+
+## Key Highlights
+
+- Canonical package subpath
+- Explicit host boundaries
+- Typed declarations and local verification
+
+## Quickstart
+
+Install the owning package, using a verified tarball before registry publication.
+
+### Public import
+
+Install the owning package and use the exact import in the example below. The subpath is not a separate npm package. Check the selected entry's runtime and peer requirements in the linked architecture guide.
+
+```bash
+bun add @alneas/eaos-server
+```
+
+```typescript
+import * as capability from '@alneas/eaos-server/storage'
+
+console.log(Object.keys(capability))
+```
+
+## Next Steps
+
+- [Architecture and host boundaries](docs/guide.md)
+- [API reference](docs/api.md)
+- [Owning package](../index.md)

package/docs/storage/docs/api.md

@@ -0,0 +1,470 @@
+---
+title: "@alneas/eaos-server API"
+description: "@alneas/eaos-server API: source-derived declarations, parameter tables, return types and public import examples."
+sidebar:
+  order: 30
+archetype: "reference"
+project: "eaos-workspace"
+tags: ["api", "generated"]
+---
+
+<!-- Generated by scripts/generate-public-api.ts from built source declarations. Edit source JSDoc/types and regenerate; do not edit these cards. -->
+
+# @alneas/eaos-server API
+
+## Public entrypoints
+
+| Import | Contract |
+| --- | --- |
+| `@alneas/eaos-server/storage` | Typed public export |
+| `@alneas/eaos-server/storage/s3-compatible` | Typed public export |
+
+<a id="api-createS3CompatibleStorage"></a>
+
+## [FUNCTION] `createS3CompatibleStorage`
+
+Creates an unscoped private-upload, signed-URL storage adapter for R2 or S3.
+
+Imports: `@alneas/eaos-server/storage`, `@alneas/eaos-server/storage/s3-compatible`.
+
+### Signature
+
+```typescript
+declare function createS3CompatibleStorage(config: S3CompatibleStorageConfig): Promise<StorageAdapter>;
+```
+
+### Parameters
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `config` | `S3CompatibleStorageConfig` | Yes | Provider configuration, credentials, and URL ceiling; see {@link S3CompatibleStorageConfig}. |
+
+### Returns
+
+`Promise<StorageAdapter>`
+
+A frozen app-core adapter whose uploads reject public=true and whose URLs always use signatures within the configured ceiling.
+
+### Remarks
+
+Server-only: transport/signing stay in app-core and the host supplies secrets. Credentials are resolved once at construction. Signed access also works during a public-bucket migration but cannot close existing public URLs. Keep this unscoped adapter host-owned; give plugins createTenantS3CompatibleStorage. Constructing an adapter does not verify remote credentials or create a bucket.
+
+### Errors and rejections
+
+Rejects invalid provider, lifetime, bucket, account/region, endpoint, or empty credentials, and propagates credential callback/import/adapter construction errors. Subsequent operations propagate transport errors.
+
+### Example
+
+```typescript
+import { createS3CompatibleStorage, readS3CompatibleStorageConfig } from "@alneas/eaos-server/storage/s3-compatible";
+// The host provisions a private bucket and supplies the documented storage environment.
+const config = readS3CompatibleStorageConfig();
+if (!config) throw new Error("Storage is not configured");
+const storage = await createS3CompatibleStorage(config);
+// Retain storage in trusted server code; authorize requests before performing operations.
+```
+
+
+<a id="api-createTenantS3CompatibleStorage"></a>
+
+## [FUNCTION] `createTenantS3CompatibleStorage`
+
+Creates provider-backed storage isolated to a verified tenant/plugin scope.
+
+Imports: `@alneas/eaos-server/storage`, `@alneas/eaos-server/storage/s3-compatible`.
+
+### Signature
+
+```typescript
+declare function createTenantS3CompatibleStorage(config: S3CompatibleStorageConfig, options: TenantStorageOptions): Promise<StorageAdapter>;
+```
+
+### Parameters
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `config` | `S3CompatibleStorageConfig` | Yes | Host provider configuration and credentials. |
+| `options` | `TenantStorageOptions` | Yes | Trusted scope and live authorization; an omitted scope URL ceiling inherits config.maxUrlLifetimeSeconds, then 300. |
+
+### Returns
+
+`Promise<StorageAdapter>`
+
+A frozen scoped adapter; see {@link createTenantStorage} for relative key and operation policy.
+
+### Remarks
+
+The provider ceiling also applies, so a larger scope ceiling cannot increase it. The host owns bucket provisioning and verified identity resolution.
+
+### Errors and rejections
+
+Rejects provider construction failures and invalid scope settings; operations propagate authorization, policy, and transport errors.
+
+### Example
+
+```typescript
+import { createTenantS3CompatibleStorage, type S3CompatibleStorageConfig } from "@alneas/eaos-server/storage/s3-compatible";
+import type { TenantStorageOptions } from "@alneas/eaos-server/storage";
+export async function scopedStorage(config: S3CompatibleStorageConfig, trustedOptions: TenantStorageOptions) {
+  return createTenantS3CompatibleStorage(config, trustedOptions);
+}
+```
+
+
+<a id="api-createTenantStorage"></a>
+
+## [FUNCTION] `createTenantStorage`
+
+Wraps a storage adapter with tenant/plugin key isolation and per-operation authorization.
+
+Imports: `@alneas/eaos-server/storage`.
+
+### Signature
+
+```typescript
+declare function createTenantStorage(adapter: StorageAdapter, options: TenantStorageOptions): StorageAdapter;
+```
+
+### Parameters
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `adapter` | `StorageAdapter` | Yes | Host-owned transport/signing adapter; optional copy and move are exposed only when supported. |
+| `options` | `TenantStorageOptions` | Yes | Trusted scope, authorization callback, and signed URL ceiling; see {@link TenantStorageOptions}. |
+
+### Returns
+
+`StorageAdapter`
+
+A frozen adapter using relative keys while storing under tenants/{tenantId}/plugins/{pluginId}/; returned object keys and list cursors are scope-relative.
+
+### Remarks
+
+Keys cannot be absolute or contain traversal, empty segments, backslashes, percent escapes, control characters, query strings, or fragments. List permits an empty prefix and slash delimiter only. URLs default to a 300-second ceiling and remain usable until expiry after authorization changes. This wrapper supplies no persistence, locking, revocation, or transaction mechanism beyond the underlying adapter. The host must retain ownership of the unscoped adapter.
+
+### Errors and rejections
+
+Throws synchronously for invalid scope IDs or URL lifetime. Operations reject for invalid relative keys, denied access, public uploads, unsigned or overlong URLs, invalid cursors/delimiters, out-of-scope provider results, or propagated adapter/authorization errors.
+
+### Example
+
+```typescript
+import { createTenantStorage, type StorageAdapter, type TenantStorageOptions } from "@alneas/eaos-server/storage";
+export function pluginStorage(adapter: StorageAdapter, trustedOptions: TenantStorageOptions) {
+  // Resolve scope and authorization from verified host identity, never request body IDs.
+  return createTenantStorage(adapter, trustedOptions);
+}
+```
+
+
+<a id="api-readS3CompatibleStorageConfig"></a>
+
+## [FUNCTION] `readS3CompatibleStorageConfig`
+
+Reads trimmed S3 or R2 configuration from a host environment map.
+
+Imports: `@alneas/eaos-server/storage`, `@alneas/eaos-server/storage/s3-compatible`.
+
+### Signature
+
+```typescript
+declare function readS3CompatibleStorageConfig(env?: Record<string, string | undefined>): S3CompatibleStorageConfig | null;
+```
+
+### Parameters
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `env` | `Record<string, string \| undefined>` | No | Environment values; defaults to process.env. EAOS_STORAGE_PROVIDER selects s3/r2 case-insensitively. R2 uses R2_ACCOUNT_ID, R2_BUCKET, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY, and optional R2_ENDPOINT. S3 uses S3_BUCKET, S3_REGION, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, optional S3_ENDPOINT, and S3_FORCE_PATH_STYLE (true or 1). EAOS_STORAGE_MAX_URL_SECONDS is converted with Number. |
+
+### Returns
+
+`S3CompatibleStorageConfig \| null`
+
+Configuration, or null when the provider is absent/blank. This read does not fully validate values; creation validates provider settings.
+
+### Remarks
+
+Returned configuration contains secrets and belongs exclusively in trusted server code.
+
+### Errors and rejections
+
+If a selected provider lacks required nonblank values, or the provider is unsupported.
+
+### Example
+
+```typescript
+import { readS3CompatibleStorageConfig } from "@alneas/eaos-server/storage/s3-compatible";
+const config = readS3CompatibleStorageConfig();
+console.log(config ? "Storage configured" : "Storage disabled");
+```
+
+
+<a id="api-S3CompatibleStorageConfig"></a>
+
+## [TYPE] `S3CompatibleStorageConfig`
+
+Selects R2 or S3 transport settings with host-held credentials and a signed URL ceiling.
+
+Imports: `@alneas/eaos-server/storage`, `@alneas/eaos-server/storage/s3-compatible`.
+
+### Signature
+
+```typescript
+type S3CompatibleStorageConfig = Common & (({
+    provider: 'r2';
+} & Omit<R2StorageConfig, 'accessKeyId' | 'secretAccessKey' | 'publicUrl' | 'defaultExpiresIn'>) | ({
+    provider: 's3';
+} & Omit<S3StorageConfig, 'accessKeyId' | 'secretAccessKey' | 'defaultExpiresIn'>));
+```
+
+### Parameters
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| — | — | — | No call parameters. |
+
+### Returns
+
+Type declaration; no runtime value.
+
+### Remarks
+
+R2 requires a 32-hex-character accountId; S3 requires region. Both require a valid bucket name. Optional endpoints must be HTTPS URLs without credentials, query, or fragment. Provider-specific fields follow app-core storage configuration; public URLs are not configured by this factory.
+
+### See also
+
+createS3CompatibleStorage for a complete setup example.
+
+### Public members
+
+#### `provider`
+
+Select Cloudflare R2 transport; accountId must be 32 hexadecimal characters and bucket/credentials must be configured.
+
+
+#### `provider`
+
+Select S3-compatible transport; a nonempty region and valid bucket/credentials are required, with optional HTTPS endpoint.
+
+
+
+### Example
+
+See the owning declaration and linked feature guide for usage; no standalone example is documented in source.
+
+<a id="api-StorageAdapter"></a>
+
+## [INTERFACE] `StorageAdapter`
+
+Compatibility re-export; its implementation and documentation are owned by the owning package `@alneas/appkit-core`.
+
+Imports: `@alneas/eaos-server/storage`.
+
+### Signature
+
+```typescript
+export interface StorageAdapter {
+    upload(key: string, data: Uint8Array | Blob | ReadableStream | string, options?: StorageUploadOptions): Promise<StorageObject>;
+    download(key: string): Promise<Uint8Array | null>;
+    getUrl(key: string, options?: StorageURLOptions): Promise<string>;
+    getUploadUrl?(key: string, options?: Pick<StorageURLOptions, 'expiresIn'>): Promise<string>;
+    getDownloadUrl?(key: string, options?: StorageURLOptions): Promise<string>;
+    delete(key: string): Promise<boolean>;
+    exists(key: string): Promise<boolean>;
+    head(key: string): Promise<StorageObject | null>;
+    list(options?: StorageListOptions): Promise<StorageListResult>;
+    copy?(sourceKey: string, destinationKey: string): Promise<StorageObject>;
+    move?(sourceKey: string, destinationKey: string): Promise<StorageObject>;
+}
+```
+
+### Parameters
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `upload` | `Promise<StorageObject>` | Yes | See the upstream owning declaration. |
+| `download` | `Promise<Uint8Array \| null>` | Yes | See the upstream owning declaration. |
+| `getUrl` | `Promise<string>` | Yes | See the upstream owning declaration. |
+| `getUploadUrl` | `Promise<string>` | No | See the upstream owning declaration. |
+| `getDownloadUrl` | `Promise<string>` | No | See the upstream owning declaration. |
+| `delete` | `Promise<boolean>` | Yes | See the upstream owning declaration. |
+| `exists` | `Promise<boolean>` | Yes | See the upstream owning declaration. |
+| `head` | `Promise<StorageObject \| null>` | Yes | See the upstream owning declaration. |
+| `list` | `Promise<StorageListResult>` | Yes | See the upstream owning declaration. |
+| `copy` | `Promise<StorageObject>` | No | See the upstream owning declaration. |
+| `move` | `Promise<StorageObject>` | No | See the upstream owning declaration. |
+
+### Returns
+
+Type declaration; no runtime value.
+
+### Example
+
+See the owning declaration and linked feature guide for usage; no standalone example is documented in source.
+
+<a id="api-StorageCredentials"></a>
+
+## [INTERFACE] `StorageCredentials`
+
+Server-held signing credentials; never expose these through browser configuration.
+
+Imports: `@alneas/eaos-server/storage`, `@alneas/eaos-server/storage/s3-compatible`.
+
+### Signature
+
+```typescript
+interface StorageCredentials {
+    accessKeyId: string;
+    secretAccessKey: string;
+}
+```
+
+### Parameters
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `accessKeyId` | `string` | Yes | Nonempty access key identifier for the selected provider. |
+| `secretAccessKey` | `string` | Yes | Nonempty secret used for request signing. |
+
+### Returns
+
+Type declaration; no runtime value.
+
+### See also
+
+createS3CompatibleStorage for host setup.
+
+### Public members
+
+#### `accessKeyId`
+
+Nonempty access key identifier for the selected provider.
+
+
+#### `secretAccessKey`
+
+Nonempty secret used for request signing.
+
+
+
+### Example
+
+See the owning declaration and linked feature guide for usage; no standalone example is documented in source.
+
+<a id="api-StorageOperation"></a>
+
+## [TYPE] `StorageOperation`
+
+Operation names passed to the host authorization callback before scoped storage access.
+
+Imports: `@alneas/eaos-server/storage`.
+
+### Signature
+
+```typescript
+type StorageOperation = 'upload' | 'download' | 'delete' | 'exists' | 'head' | 'list' | 'getUrl' | 'copy' | 'move';
+```
+
+### Parameters
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| — | — | — | No call parameters. |
+
+### Returns
+
+Type declaration; no runtime value.
+
+### See also
+
+createTenantStorage for a complete usage example.
+
+### Example
+
+See the owning declaration and linked feature guide for usage; no standalone example is documented in source.
+
+<a id="api-TenantStorageOptions"></a>
+
+## [INTERFACE] `TenantStorageOptions`
+
+Trusted tenant/plugin scope and per-operation authorization for [createTenantStorage](#api-createTenantStorage).
+
+Imports: `@alneas/eaos-server/storage`.
+
+### Signature
+
+```typescript
+interface TenantStorageOptions {
+    tenantId: string;
+    pluginId: string;
+    authorize: (request: {
+        tenantId: string;
+        pluginId: string;
+        operation: StorageOperation;
+        keys: readonly string[];
+    }) => boolean | Promise<boolean>;
+    maxUrlLifetimeSeconds?: number;
+}
+```
+
+### Parameters
+
+| Name | Type | Required | Description |
+| --- | --- | --- | --- |
+| `tenantId` | `string` | Yes | Trusted tenant ID: 1–128 ASCII letters, digits, underscores, or hyphens, starting alphanumeric. It must come from verified server identity/configuration, never request body keys. |
+| `pluginId` | `string` | Yes | Trusted plugin ID: 1–128 ASCII letters, digits, underscores, or hyphens, starting with a letter or digit. |
+| `authorize` | `(request: {     tenantId: string;     pluginId: string;     operation: StorageOperation;     keys: readonly string[]; }) => boolean \| Promise<boolean>` | Yes | Invoked before each operation with trusted scope, operation, and frozen relative keys (list receives its prefix); only exactly true allows access. Errors propagate. |
+| `maxUrlLifetimeSeconds` | `number` | No | Signed URLs remain usable until expiry; default ceiling 300 seconds. |
+
+### Returns
+
+Type declaration; no runtime value.
+
+### Public members
+
+#### `tenantId`
+
+Trusted tenant ID: 1–128 ASCII letters, digits, underscores, or hyphens, starting alphanumeric. It must come from verified server identity/configuration, never request body keys.
+
+
+#### `pluginId`
+
+Trusted plugin ID: 1–128 ASCII letters, digits, underscores, or hyphens, starting with a letter or digit.
+
+
+#### `authorize`
+
+Invoked before each operation with trusted scope, operation, and frozen relative keys (list receives its prefix); only exactly true allows access. Errors propagate.
+
+
+#### `authorize.request.tenantId`
+
+Trusted tenant scope captured at adapter construction, independent of caller object keys.
+
+
+#### `authorize.request.pluginId`
+
+Trusted plugin scope captured at adapter construction.
+
+
+#### `authorize.request.operation`
+
+Storage operation about to be delegated to the provider.
+
+
+#### `authorize.request.keys`
+
+Frozen relative-key array; copy/move supplies source then destination, and list supplies its requested prefix.
+
+
+#### `maxUrlLifetimeSeconds`
+
+Signed URLs remain usable until expiry; default ceiling 300 seconds.
+
+
+
+### Example
+
+See the owning declaration and linked feature guide for usage; no standalone example is documented in source.
+

package/docs/storage/docs/guide.md

@@ -0,0 +1,47 @@
+---
+title: "Storage ownership and host boundaries"
+description: "Tenant/plugin-scoped storage and signed-URL authorization. This capability belongs to @alneas/eaos-server; it is not a separate npm package."
+sidebar:
+  order: 20
+archetype: "explanation"
+project: "eaos-workspace"
+tags: ["eaos", "explanation"]
+---
+
+# Storage ownership and host boundaries
+
+## Motivation
+
+Tenant/plugin-scoped storage and signed-URL authorization. This capability belongs to `@alneas/eaos-server`; it is not a separate npm package.
+
+## Architectural Diagram
+
+```mermaid
+flowchart LR
+  Host[Trusted host] --> Adapter[Scoped Server adapter]
+  Adapter --> Store[Host-owned durable provider]
+```
+
+## Public import
+
+Install the package; the subpath below is an import target, not a separate package. Registry installation requires a published EAOS release; before publication use the owning workspace's checksum-verified build artifact.
+
+```bash
+bun add @alneas/eaos-server
+```
+
+```typescript
+import { createTenantStorage } from '@alneas/eaos-server/storage'
+
+export function bindStorage(...args: Parameters<typeof createTenantStorage>) {
+  return createTenantStorage(...args)
+}
+```
+
+Server runtime only. Supply the external storage adapter and verified tenant/plugin scope with live authorization; provider credentials stay on the server.
+
+## Trade-offs & Decisions
+
+Reuse the app-core storage adapter. Verified scopes, private provider settings and live per-operation permission are mandatory. A signed URL can remain usable until expiry; downloaded bytes cannot be remotely revoked. Validate real bucket protection separately from a configuration flag.
+
+The host owns verified identity, tenant boundaries, credentials and real provider adoption. Package builds and tests never apply production changes or activate tenants. Review the [API reference](api.md) before binding the host.