# Official sources

Use this reference only when grounding Contabo Object Storage API behavior, S3 compatibility, bucket operations, or access policy configuration.

## Contabo documentation

Use these as starting points, not as proof of the user's live bucket state, object inventory, or access policy configuration:

- https://api.contabo.com/#tag/Object-Storages — Object Storage API (list instances, create/manage storage instances, region codes)
- https://api.contabo.com/ — Contabo OpenAPI reference (authentication flows, request headers including x-request-id, error response schemas)
- https://docs.contabo.com/ — Contabo user documentation (Object Storage setup, S3 compatibility guide, endpoint URLs by region, access key management)
- https://github.com/contabo/cntb — cntb CLI tool (Object Storage commands; credential and access key configuration)

## Grounding rule

Official Contabo documentation describes Object Storage API endpoints, S3-compatible endpoint URLs by region, access key management patterns, and available storage instance configurations at the time of publication. It does not prove the user's current bucket inventory, object count, active retention policies, ACL configuration, or the actual data at risk in a deletion operation. Prefer live read-only API responses and S3 list commands for current-state claims. Label any bucket configuration, endpoint URL, or storage behavior claim sourced only from documentation as `documentation-based`. Always confirm the correct S3 endpoint URL for the target region from official docs — do not assume the default AWS endpoint or a URL from a prior session.

# Safety checklist

Before executing any Contabo Object Storage mutation (bucket deletion, object deletion, access policy change, retention policy change, cross-region migration), enforce every item on this checklist. Never proceed without all mandatory gates confirmed for destructive operations.

## Hard-stop gates — all required for deletion and irreversible mutations

Do not execute any bucket deletion, bulk object deletion, or irreversible mutation unless ALL of the following are confirmed in writing by the user:

1. **Target confirmed with inventory**: Bucket name AND region AND full object inventory reviewed. Do not delete a bucket based on name alone — confirm object count and verify there is nothing unexpected.
2. **Backup evidence verified**: Confirmed backup of all data to be deleted, including backup location, timestamp, and verification method (e.g., restored successfully to staging, checksum matched). "I think we have a backup" is not verification.
3. **Rollback plan documented**: A concrete data recovery path is on record. For object deletion: where the backup lives and how to restore. For bucket deletion: whether recreation is possible and what configuration is required.
4. **Named approving identity on record**: The full name or authenticated account identifier of the authorizing person. A role title, team name, ticket number, or alias alone is not sufficient.
5. **Retention audit complete**: Confirm no retention or compliance policy blocks deletion. Deleting objects under an active retention lock may be a compliance violation.

## Non-negotiables

- Do not execute bucket deletion if the object inventory has not been reviewed in this session. A prior audit is not sufficient — inventory must be confirmed fresh.
- Do not treat bucket deletion as reversible. Deleted objects in Contabo Object Storage cannot be recovered without a verified external backup.
- Do not recommend making a bucket publicly accessible without explicit user acknowledgment of the data exposure risk and the specific use case requiring public access.
- S3 access keys and secret keys for Object Storage must be stored in environment variables. Never hardcode, echo, or include them in any output, log file, or script.
- Do not log, echo, or include OAuth2 token values in any output, log file, or script.
- Include a fresh UUIDv4 `x-request-id` header in every Contabo REST API mutation call.
- For S3-compatible operations, use `aws s3` or `aws s3api` with `--endpoint-url` pointing to the Contabo Object Storage endpoint — never against the default AWS endpoint.

## Mandatory posture

- Prefer read-only inventory first. Always call `GET /v1/storage/object-storages` and list the target bucket contents before any deletion or mutation.
- Prefer the least-destructive operation. If an access policy change achieves the goal without deletion, recommend that first.
- Treat missing backup evidence as a hard blocker, not a detail to resolve after deletion.
- If any hard-stop gate is missing, stop completely and list exactly which gates remain open. Do not proceed partially.
- If public access is about to be enabled, surface the full data exposure risk explicitly before the user confirms.

## Stress checks

- Is there data in this bucket that is not captured in the confirmed backup? → Stop until resolved.
- Is any object in this bucket subject to a compliance retention policy? → Confirm legality of deletion before proceeding.
- Is the access policy change exposing sensitive data publicly? → Require explicit use-case justification.
- What is the recovery time if the backup restore is needed? Is it within the user's acceptable window?
- Is the S3 endpoint URL correct for the Contabo region, not a default AWS endpoint?
- Is the OAuth2 token fresh enough for the full sequence of API calls required?

## Evidence labels

Use `live evidence`, `user-provided sanitized evidence`, `documentation-based`, or `inference`. Never proceed with a destructive bucket operation based on inference about the object inventory or backup state.

# Workflow and output contract

Use this reference when executing Contabo Object Storage mutations: bucket creation, access policy changes, retention policy updates, object or bucket deletion, or cross-region migration. Every step is mandatory before issuing any destructive call.

## Pre-mutation sequence

1. **Confirm target and inventory**
   - Confirm the Object Storage instance ID and region.
   - List all buckets in the instance via `GET /v1/storage/object-storages` and S3-compatible list commands.
   - For deletion: confirm the full object inventory of the target bucket. Do not delete a bucket described only by name without first listing its contents.
   - Verify OAuth2 token freshness. Tokens expire in ~5 minutes. Refresh immediately before any mutation call.

2. **Review access policy and retention posture**
   - Check bucket ACLs and public access settings. Confirm whether any bucket is publicly readable or writable.
   - Review any lifecycle or retention rules. Confirm whether deletion is blocked by a retention policy.
   - Label the access policy state as `live evidence`, `user-provided sanitized evidence`, or `inference`.

3. **Enforce hard-stop gates for destructive operations**
   - All four gates (bucket ID + region + inventory, backup evidence, rollback plan, named approving identity) must be confirmed in writing before any deletion or irreversible mutation.
   - If any gate is missing, stop and request the specific missing item. Do not infer or assume.

4. **Execute with traceability**
   - Include a fresh UUIDv4 `x-request-id` in all Contabo REST API mutation calls.
   - Use environment-variable-stored S3 access keys for S3-compatible operations. Never hardcode S3 credentials.
   - Log the request ID. Do not log the OAuth2 token, S3 secret key, or access key.

5. **Post-mutation verification**
   - Confirm the bucket or object state after the operation.
   - For deletions: confirm the bucket or objects no longer exist.
   - For access policy changes: verify the new ACL or public access setting is in effect.
   - Record the operation timestamp for audit purposes.

## Output contract

Return this structure:

```markdown
# Contabo Object Storage: <operation> — <bucket name or instance ID>
## Hard-stop gate status (required for destructive operations)
- [ ] Target confirmed: bucket name + region + object inventory reviewed
- [ ] Backup evidence: <location, timestamp, and verification method or "N/A — non-destructive">
- [ ] Rollback plan documented: <recovery path>
- [ ] Named approving identity: <full name or authenticated account identifier>
- [ ] OAuth2 token freshness: confirmed fresh (refreshed at <time>)
## Pre-mutation inventory
- Object Storage instance ID:
- Bucket name:
- Object count and estimated size: <count and size or "not yet queried">
- Access policy state: <public | private | mixed | inference>
- Retention policy: <present | absent | inference>
## Proposed action
- Operation: <create | update-acl | update-retention | delete-objects | delete-bucket | migrate>
- API or S3 call: <sanitized call with x-request-id or endpoint placeholder>
## Post-mutation verification
- Bucket or object state after operation:
- Access policy confirmed:
## Open risks or refusal reason
- <risk or explicit none>
```