@k2b/cloud 0.42.0 → 0.44.0

package/src/services/image-metadata.ts

@@ -366,12 +366,76 @@ const stripWebp = (bytes: Uint8Array): Uint8Array => {
   return out.subarray(0, written);
 };
 
+const stripGif = (bytes: Uint8Array): Uint8Array => {
+  const bad = () => new ImageMetadataError("GIF");
+  if (bytes.length < 13) throw bad();
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (!view.getUint16(6, true) || !view.getUint16(8, true)) throw bad();
+  let offset = 13 + (bytes[10]! & 0x80 ? 3 * (1 << ((bytes[10]! & 7) + 1)) : 0);
+  if (offset > bytes.length) throw bad();
+  const out = new Uint8Array(bytes.length);
+  let written = copy(out, 0, bytes, 0, offset);
+  let image = false;
+  const blocksEnd = (start: number) => {
+    let next = start;
+    while (next < bytes.length) {
+      const size = bytes[next++]!;
+      if (!size) return next;
+      if (next + size > bytes.length) throw bad();
+      next += size;
+    }
+    throw bad();
+  };
+  while (offset < bytes.length) {
+    const start = offset;
+    const type = bytes[offset++]!;
+    if (type === 0x3b) {
+      if (!image) throw bad();
+      out[written++] = type;
+      return out.subarray(0, written);
+    }
+    if (type === 0x2c) {
+      if (offset + 9 > bytes.length || !view.getUint16(offset + 4, true) || !view.getUint16(offset + 6, true)) throw bad();
+      const packed = bytes[offset + 8]!;
+      offset += 9 + (packed & 0x80 ? 3 * (1 << ((packed & 7) + 1)) : 0);
+      if (offset >= bytes.length || bytes[offset]! < 2 || bytes[offset]! > 8) throw bad();
+      offset = blocksEnd(offset + 1);
+      written = copy(out, written, bytes, start, offset);
+      image = true;
+    } else if (type === 0x21) {
+      if (offset >= bytes.length) throw bad();
+      const label = bytes[offset++]!;
+      const payload = offset;
+      offset = blocksEnd(offset);
+      if (label === 0xf9) {
+        if (bytes[payload] !== 4 || offset !== payload + 6) throw bad();
+        written = copy(out, written, bytes, start, offset);
+      } else if (label === 0x01) {
+        // Plain text extensions contribute visible content, unlike comments and private application blocks.
+        if (bytes[payload] !== 12) throw bad();
+        written = copy(out, written, bytes, start, offset);
+      } else if (
+        label === 0xff &&
+        bytes[payload] === 11 &&
+        offset === start + 19 &&
+        (startsWith(bytes, "NETSCAPE2.0", payload + 1) || startsWith(bytes, "ANIMEXTS1.0", payload + 1)) &&
+        bytes[payload + 12] === 3 &&
+        bytes[payload + 13] === 1
+      ) {
+        written = copy(out, written, bytes, start, offset);
+      }
+    } else throw bad();
+  }
+  throw bad();
+};
+
 /**
- * Losslessly removes non-rendering metadata from JPEG, PNG and WebP, selected
+ * Losslessly removes non-rendering metadata from JPEG, PNG, WebP and GIF, selected
  * by magic bytes. Call only for uploads the application classifies as images.
  * Other formats are returned unchanged. No decoding; linear time and space.
  */
 export const stripImageMetadata = (bytes: Uint8Array): Uint8Array => {
+  if (startsWith(bytes, "GIF87a") || startsWith(bytes, "GIF89a")) return stripGif(bytes);
   if (bytes[0] === 0xff && bytes[1] === 0xd8) return stripJpeg(bytes);
   if (startsWith(bytes, "\x89PNG")) return stripPng(bytes);
   if (startsWith(bytes, "RIFF") && startsWith(bytes, "WEBP", 8)) return stripWebp(bytes);

package/src/services/index.ts

@@ -104,7 +104,7 @@ export type {
   ServiceAccountCredentialOwner,
   ServiceAccountCredentialStatus,
 } from "./service-account-credentials";
-export { oauthTokens } from "./oauth-tokens";
+export { isServiceAccountOAuthAuthorityCurrent, oauthTokens } from "./oauth-tokens";
 export type { AuthenticatedOAuthToken } from "./oauth-tokens";
 export { webauthn } from "./webauthn";
 export type { WebAuthnRp } from "./webauthn";
@@ -251,6 +251,7 @@ export {
 export type { NetworkLookup, PublicNetworkAddress } from "./network-security";
 
 export { geoip } from "./geoip";
+export { appDetails } from "./app-details";
 export {
   knownBrowsers,
   KNOWN_BROWSER_LIMITS,
@@ -268,3 +269,25 @@ export { coreGeo, createGeoService } from "./geo/service";
 export { migrate as migrateGeo } from "./geo/migrate";
 
 export { coreGeoMap, createGeoMapService } from "./geo/map";
+
+export {
+  AppAccessManagementError,
+  appAccessGrantCounts,
+  canManageAppAccess,
+  readAppAccess,
+  changeAppAccess,
+  canRepairAppAccess,
+  requireAppAccessManager,
+  type AppAccessSnapshot,
+} from "./app-access-management";
+
+export { storage } from "./object-store";
+export type {
+  ObjectStoreFile,
+  ObjectVisibility,
+  ObjectWriteData,
+  ObjectWriteOptions,
+  ObjectPresignOptions,
+  ObjectListOptions,
+  ObjectListResult,
+} from "./object-store";

package/src/services/ipa/sync.ts

@@ -1,4 +1,5 @@
 import { sql } from "bun";
+import { coreUserEventPublisher } from "../../events/core-user-created";
 import { freeipa } from "../../server/services";
 import { writeDeletedAccountAudit } from "../account-lifecycle/audit";
 import { calculateIpaProfileFromGroupNames, parseIpaAccountTransitionPolicy, parseIpaMatchMode } from "../account-model";
@@ -461,8 +462,11 @@ export const syncFromIpa = async (runtime: IpaSyncRuntime = {}): Promise<void> =
         RETURNING id, (xmax = 0) AS inserted`;
       await upsertUserIpaData(tx, { userId: upserted[0]!.id as string, ...u });
       upsertedUsersByUid += 1;
-      if (Boolean(upserted[0]?.inserted)) insertedUsersByUid += 1;
-      else updatedUsersByUid += 1;
+      if (Boolean(upserted[0]?.inserted)) {
+        insertedUsersByUid += 1;
+        const userId = upserted[0]!.id as string;
+        await coreUserEventPublisher().publish(tx, "user.created", { subject: userId, data: { userId, provider: "ipa" } });
+      } else updatedUsersByUid += 1;
     }
 
     for (let staleIndex = 0; staleIndex < staleLocalUsers.length; staleIndex += 1) {

package/src/services/ipa/users.ts

@@ -1,6 +1,7 @@
 import { password } from "@k2b/stdlib";
 import { sql } from "bun";
 import type { MutationResult, UserProfile } from "../../contracts/shared";
+import { coreUserEventPublisher } from "../../events/core-user-created";
 import { freeipa } from "../../server/services";
 import { writeDeletedAccountAudit } from "../account-lifecycle/audit";
 import { resolveProviderProfile } from "../accounts/base-user";
@@ -366,7 +367,7 @@ export const addIpa = async (params: {
           display_name = EXCLUDED.display_name,
           mail = EXCLUDED.mail,
           account_expires = EXCLUDED.account_expires
-        RETURNING id
+        RETURNING id, (xmax = 0) AS inserted
       `;
         id = insertRows[0]!.id as string;
         await upsertUserIpaData(
@@ -381,6 +382,8 @@ export const addIpa = async (params: {
           },
           tx,
         );
+        if (insertRows[0]?.inserted)
+          await coreUserEventPublisher().publish(tx, "user.created", { subject: id, data: { userId: id, provider: "ipa" } });
       }
     } catch (dbError) {
       log.error("CRITICAL: FreeIPA user created but local DB update failed. Manual reconciliation needed.", {

package/src/services/mandates/policy.ts

@@ -194,6 +194,11 @@ export const isMandatePolicyNarrowing = (current: MandatePolicyV1, next: Mandate
         }),
       ));
 
+/**
+ * True when a background mandate permits one operation. Unattended Actions must fit the live
+ * capability policy whenever the mandate has grants or preapproves Actions; a `require_approval`
+ * mandate without grants runs an Action only after its separate approval completed through Cloud.
+ */
 export const mandatePolicyAllows = (
   policy: MandatePolicyV1,
   input: {
@@ -224,14 +229,14 @@ export const mandatePolicyAllows = (
       )
     );
   }
+  const [operation, capabilityId] = input.operation.split(":");
+  const kind =
+    operation === "capability.query"
+      ? "query"
+      : operation === "capability.action.run" || operation === "capability.action.review"
+        ? "action"
+        : null;
   if (policy.grants !== undefined) {
-    const [operation, capabilityId] = input.operation.split(":");
-    const kind =
-      operation === "capability.query"
-        ? "query"
-        : operation === "capability.action.run" || operation === "capability.action.review"
-          ? "action"
-          : null;
     if (
       !kind ||
       !capabilityId ||
@@ -240,11 +245,13 @@ export const mandatePolicyAllows = (
       )
     )
       return false;
-    if (kind === "action") {
-      if (input.capabilityPolicy) {
-        if (!("silent" in input.capabilityPolicy) || input.capabilityPolicy.routines === false) return false;
-      } else if (input.capabilityApproval !== "none" && input.capabilityApproval !== "rememberable") return false;
-    }
+  }
+  // Routine grants and unattended preapproval must both fit the live capability policy.
+  // A no-grants require_approval mandate keeps its separately approved execution path.
+  if (kind === "action" && (policy.grants !== undefined || policy.actions === "preapproved")) {
+    if (input.capabilityPolicy) {
+      if (!("silent" in input.capabilityPolicy) || input.capabilityPolicy.routines === false) return false;
+    } else if (input.capabilityApproval !== "none" && input.capabilityApproval !== "rememberable") return false;
   }
   if (!input.operation.startsWith("capability.action.run:")) return true;
   if (policy.actions === "deny") return false;

package/src/services/notifications/browser.ts

@@ -29,6 +29,7 @@ type BrowserDeliveryPayload = {
   group?: string;
   badge?: number;
   createdAt?: number;
+  alert?: false;
 };
 
 // RFC 8030 section 7.2 guarantees 4,096 bytes; aes128gcm adds a header, tag, and padding delimiter.
@@ -44,6 +45,7 @@ const browserPushMessage = (payload: BrowserDeliveryPayload): string =>
     ...(payload.group !== undefined ? { group: payload.group } : {}),
     ...(payload.badge !== undefined ? { badge: payload.badge } : {}),
     ...(payload.createdAt !== undefined ? { createdAt: payload.createdAt } : {}),
+    ...(payload.alert === false ? { alert: false } : {}),
   });
 
 const BrowserDeliveryPayloadSchema = z.object({
@@ -59,6 +61,7 @@ const BrowserDeliveryPayloadSchema = z.object({
     .optional(),
   badge: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER).optional(),
   createdAt: z.number().int().min(0).max(Number.MAX_SAFE_INTEGER).optional(),
+  alert: z.literal(false).optional(),
 });
 
 const BrowserDestinationContextSchema = z.object({
@@ -192,6 +195,7 @@ const browserDriver = {
       ...(group !== undefined ? { group } : {}),
       ...(presentation.badge !== undefined ? { badge: presentation.badge } : {}),
       ...(presentation.group !== undefined || presentation.badge !== undefined ? { createdAt: Date.now() } : {}),
+      ...(presentation.alert === false ? { alert: false } : {}),
     });
     if (payload.preview !== undefined && Buffer.byteLength(browserPushMessage(payload), "utf8") > WEB_PUSH_PLAINTEXT_BUDGET) {
       const { preview: _preview, ...titleOnlyPayload } = payload;

package/src/services/notifications/catalog.ts

@@ -17,15 +17,16 @@ const isSchemaUnavailable = (error: unknown): boolean => {
 const upsertDefinition = async (definition: AnyBoundNotificationDefinition, db: typeof sql = sql): Promise<void> => {
   const recommended = toPgTextArray([...(definition.delivery?.recommended ?? [])]);
   const required = toPgTextArray([...(definition.delivery?.required ?? [])]);
+  const excluded = toPgTextArray([...(definition.delivery?.excluded ?? [])]);
   await db`
     INSERT INTO notifications.definitions (
       id, app_id, kind, label, description, presentation, recipient_kind,
-      recommended_channels, required_channels, active, last_seen_at, updated_at
+      recommended_channels, required_channels, excluded_channels, excluded_reason, active, last_seen_at, updated_at
     ) VALUES (
       ${definition.id}, ${definition.appId}, ${definition.key}, ${definition.label},
       ${definition.description}, (${definition.presentation ? JSON.stringify(definition.presentation) : null}::text)::jsonb,
       ${definition.recipient}, ${recommended}::text[],
-      ${required}::text[], true, now(), now()
+      ${required}::text[], ${excluded}::text[], ${definition.excludedReason ?? null}, true, now(), now()
     )
     ON CONFLICT (id) DO UPDATE SET
       app_id = EXCLUDED.app_id,
@@ -36,6 +37,8 @@ const upsertDefinition = async (definition: AnyBoundNotificationDefinition, db:
       recipient_kind = EXCLUDED.recipient_kind,
       recommended_channels = EXCLUDED.recommended_channels,
       required_channels = EXCLUDED.required_channels,
+      excluded_channels = EXCLUDED.excluded_channels,
+      excluded_reason = EXCLUDED.excluded_reason,
       active = true,
       last_seen_at = now(),
       updated_at = now()

package/src/services/notifications/platform.ts

@@ -95,6 +95,9 @@ const validatePresentation = (presentation: NotificationPresentation, appId: str
   if (presentation.badge !== undefined && (!Number.isSafeInteger(presentation.badge) || presentation.badge < 0)) {
     throw new Error("Notification badge must be a non-negative safe integer");
   }
+  if (presentation.alert !== undefined && typeof presentation.alert !== "boolean") {
+    throw new Error("Notification alert must be a boolean");
+  }
   return {
     title,
     ...(body ? { body } : {}),
@@ -102,6 +105,7 @@ const validatePresentation = (presentation: NotificationPresentation, appId: str
     ...(targetHref ? { targetHref } : {}),
     ...(presentation.group !== undefined ? { group: presentation.group } : {}),
     ...(presentation.badge !== undefined ? { badge: presentation.badge } : {}),
+    ...(presentation.alert === false ? { alert: false } : {}),
   };
 };
 
@@ -274,10 +278,11 @@ export const sendTypedNotification = async <
   const candidateEventId = crypto.randomUUID();
   await ensureNotificationDefinition(definition);
 
-  const requiredChannels = unique([...(definition.delivery?.required ?? [])]);
+  const excluded = new Set<string>(definition.delivery?.excluded ?? []);
+  const requiredChannels = unique([...(definition.delivery?.required ?? [])]).filter((channel) => !excluded.has(channel));
   const requiredChannelSet = new Set<string>(requiredChannels);
   const preference = await preferredChannels(definition.id, resolved.recipient, definition.delivery?.recommended ?? []);
-  const preferred = preference.channels.filter((channel) => !requiredChannelSet.has(channel));
+  const preferred = preference.channels.filter((channel) => !requiredChannelSet.has(channel) && !excluded.has(channel));
 
   const identity = await sql.begin(async (tx) => {
     const eventRows = await tx<{ id: string }[]>`

package/src/services/notifications/user.ts

@@ -25,6 +25,8 @@ type PreferenceRow = {
   presentation: NotificationDefinitionPresentationCatalog | null;
   recommended_channels: string[];
   required_channels: string[];
+  excluded_channels: string[];
+  excluded_reason: string | null;
   channels: string[] | null;
   customized: boolean;
 };
@@ -57,12 +59,14 @@ const definitionPresentation = (
 ): { label: string; description: string } => resolveNotificationDefinitionPresentation(row, locale);
 
 const mapPreference = (row: PreferenceRow, locale?: string): UserNotificationPreference => {
-  const requiredChannels = unique(row.required_channels);
+  const excludedChannels = unique(row.excluded_channels);
+  const excluded = new Set(excludedChannels);
+  const requiredChannels = unique(row.required_channels).filter((channel) => !excluded.has(channel));
   const required = new Set(requiredChannels);
   const selectedChannels = unique(row.customized ? (row.channels ?? []) : row.recommended_channels).filter(
-    (channel) => !required.has(channel),
+    (channel) => !required.has(channel) && !excluded.has(channel),
   );
-  const presentation = definitionPresentation(row, locale);
+  const presentation = resolveNotificationDefinitionPresentation({ ...row, excludedReason: row.excluded_reason ?? undefined }, locale);
   return {
     id: row.id,
     appId: row.app_id,
@@ -71,6 +75,8 @@ const mapPreference = (row: PreferenceRow, locale?: string): UserNotificationPre
     description: presentation.description,
     recommendedChannels: unique(row.recommended_channels),
     requiredChannels,
+    excludedChannels,
+    excludedReason: presentation.excludedReason ?? null,
     selectedChannels,
     effectiveChannels: unique([...requiredChannels, ...selectedChannels]),
     customized: row.customized,
@@ -80,7 +86,7 @@ const mapPreference = (row: PreferenceRow, locale?: string): UserNotificationPre
 const listPreferences = async (userId: string, locale?: string): Promise<UserNotificationPreferencesResponse> => {
   const rows = await sql<PreferenceRow[]>`
     SELECT d.id, d.app_id, d.kind, d.label, d.description, d.presentation,
-           d.recommended_channels, d.required_channels, p.channels,
+           d.recommended_channels, d.required_channels, d.excluded_channels, d.excluded_reason, p.channels,
            (p.user_id IS NOT NULL) AS customized
     FROM notifications.definitions d
     LEFT JOIN notifications.preferences p
@@ -110,8 +116,8 @@ const setPreference = async (config: {
   channels: string[];
   locale?: string;
 }): Promise<MutationResult<UserNotificationPreference>> => {
-  const rows = await sql<{ required_channels: string[] }[]>`
-    SELECT required_channels
+  const rows = await sql<{ required_channels: string[]; excluded_channels: string[] }[]>`
+    SELECT required_channels, excluded_channels
     FROM notifications.definitions
     WHERE id = ${config.definitionId} AND active = true AND recipient_kind = 'user'
     LIMIT 1
@@ -119,8 +125,13 @@ const setPreference = async (config: {
   const definition = rows[0];
   if (!definition) return { ok: false, error: "Notification preference not found", status: 404 };
 
+  const requested = unique(config.channels.map((channel) => channel.trim()).filter(Boolean));
+  const excluded = requested.filter((channel) => definition.excluded_channels.includes(channel));
+  if (excluded.length > 0) {
+    return { ok: false, error: `Excluded notification channel: ${excluded.join(", ")}`, status: 400 };
+  }
   const required = new Set(definition.required_channels);
-  const channels = unique(config.channels.map((channel) => channel.trim()).filter(Boolean)).filter((channel) => !required.has(channel));
+  const channels = requested.filter((channel) => !required.has(channel));
   const available = new Set(listNotificationChannels());
   const unavailable = channels.filter((channel) => !available.has(channel));
   if (unavailable.length > 0) {

package/src/services/oauth-tokens.ts

@@ -4,7 +4,7 @@ import type { User } from "../contracts/shared";
 import { isAccountCategoryAllowed } from "./account-category-policy";
 import { isAccountExpired } from "./account-model";
 import { IDENTITY_JWKS_MAX_AGE_SECONDS } from "./identity/constants";
-import { getIdentityRuntimeConfig } from "./identity/runtime-config";
+import { getIdentityRuntimeConfig, readIdentityGroupsAdmin } from "./identity/runtime-config";
 import type { ServiceAccount } from "./service-accounts";
 import { buildProjectedUser, userProjectionJoin, userProjectionSql } from "./session/user";
 
@@ -59,6 +59,7 @@ export type AuthenticatedOAuthToken =
       kind: "service_account";
       payload: JWTPayload;
       serviceAccount: ServiceAccount;
+      oauthClientId: string;
       delegatedUser: User | null;
       scopes: string[];
     };
@@ -138,7 +139,7 @@ export const resolveOAuthTokenActor = async (
     if (serviceAccount.kind === "user_delegated" && !delegatedUser) return null;
     if (delegatedUser && isAccountExpired(delegatedUser.accountExpires)) return null;
     if (delegatedUser && !(await isAccountCategoryAllowed(delegatedUser, query))) return null;
-    return { kind: "service_account", payload, serviceAccount, delegatedUser, scopes };
+    return { kind: "service_account", payload, serviceAccount, oauthClientId: clientId, delegatedUser, scopes };
   }
 
   const rawUserId = getStringClaim(payload, "id");
@@ -161,6 +162,31 @@ export const resolveOAuthTokenActor = async (
   return { kind: "user", payload, user, scopes };
 };
 
+/**
+ * Revalidate a retained, previously authenticated service-account OAuth reference.
+ * Identifiers are not credentials: callers must protect their provenance and keep
+ * the captured scopes and expiry as caps, then authorize the domain operation.
+ */
+export const isServiceAccountOAuthAuthorityCurrent = async (
+  authority: {
+    serviceAccountId: string;
+    clientId: string;
+    expiresAt: string | null | undefined;
+  },
+  options: { query?: typeof sql; groupsAdmin?: readonly string[] } = {},
+): Promise<boolean> => {
+  const expiry = authority.expiresAt ? Date.parse(authority.expiresAt) : NaN;
+  if (!Number.isFinite(expiry) || expiry <= Date.now()) return false;
+  const groupsAdmin =
+    options.groupsAdmin ?? (options.query ? await readIdentityGroupsAdmin(options.query) : (await getIdentityRuntimeConfig()).groupsAdmin);
+  const current = await resolveOAuthTokenActor(
+    { client_id: authority.clientId, service_account_id: authority.serviceAccountId },
+    [...groupsAdmin],
+    options.query ?? sql,
+  );
+  return current?.kind === "service_account";
+};
+
 export const verifyAccessToken = async (
   token: string,
   expectedAudience: string | string[] = "cloud",

package/src/services/object-store.ts

@@ -0,0 +1,217 @@
+import type { S3ListObjectsResponse, S3Stats } from "bun";
+import { objectStoreArea } from "../_internal/object-store-area";
+import { objectStoreBackend } from "../_internal/object-store-config";
+import { validateObjectKey as validateKey } from "../_internal/object-store-key";
+import { publicCloudOrigin } from "../shared/app-url";
+import { get } from "./settings";
+
+export type ObjectVisibility = "private" | "public";
+export type ObjectWriteData = string | ArrayBuffer | ArrayBufferView | Blob | Request | Response;
+export type ObjectWriteOptions = { type?: string };
+export type ObjectPresignOptions = { method?: "GET" | "HEAD" | "DELETE"; expiresIn?: number };
+export type ObjectListOptions = {
+  prefix?: string;
+  startAfter?: string;
+  continuationToken?: string;
+  maxKeys?: number;
+};
+export type ObjectListResult = Pick<S3ListObjectsResponse, "contents" | "isTruncated" | "nextContinuationToken">;
+
+export interface ObjectStoreFile {
+  readonly key: string;
+  readonly size: Promise<number>;
+  stat(): Promise<S3Stats>;
+  write(data: ObjectWriteData, options?: ObjectWriteOptions): Promise<number>;
+  text(): Promise<string>;
+  bytes(): Promise<Uint8Array>;
+  stream(): ReadableStream<Uint8Array>;
+  exists(): Promise<boolean>;
+  delete(): Promise<void>;
+  copy(destinationKey: string): Promise<number>;
+  presign(options?: ObjectPresignOptions): Promise<string>;
+  readonly url: Promise<string>;
+}
+
+const assertSize = (size: number, limit: number): void => {
+  if (!Number.isSafeInteger(size) || size < 0 || size > limit) throw new RangeError(`Object exceeds the ${limit}-byte limit.`);
+};
+
+/** Pull one chunk at a time, propagate cancellation, and reject before buffering past the budget. */
+const boundedStream = (source: ReadableStream<Uint8Array>, limit: number): ReadableStream<Uint8Array> => {
+  const reader = source.getReader();
+  let size = 0;
+  return new ReadableStream<Uint8Array>(
+    {
+      async pull(controller) {
+        try {
+          const next = await reader.read();
+          if (next.done) {
+            reader.releaseLock();
+            controller.close();
+            return;
+          }
+          size += next.value.byteLength;
+          assertSize(size, limit);
+          controller.enqueue(next.value);
+        } catch (error) {
+          await reader.cancel(error).catch(() => {});
+          reader.releaseLock();
+          controller.error(error);
+        }
+      },
+      async cancel(reason) {
+        try {
+          await reader.cancel(reason);
+        } finally {
+          reader.releaseLock();
+        }
+      },
+    },
+    { highWaterMark: 0 },
+  );
+};
+
+const uploadData = async (data: ObjectWriteData, limit: number): Promise<string | ArrayBuffer | Uint8Array<ArrayBufferLike>> => {
+  if (typeof data === "string") {
+    assertSize(Buffer.byteLength(data), limit);
+    return data;
+  }
+  if (data instanceof ArrayBuffer || ArrayBuffer.isView(data)) {
+    assertSize(data.byteLength, limit);
+    return ArrayBuffer.isView(data) ? new Uint8Array(data.buffer, data.byteOffset, data.byteLength) : data;
+  }
+  if (data instanceof Blob || data instanceof Request || data instanceof Response) {
+    if (data instanceof Blob) assertSize(await data.size, limit);
+    const stream = data instanceof Blob ? data.stream() : data.body;
+    if (!stream) return new Uint8Array();
+    return new Response(boundedStream(stream, limit)).bytes();
+  }
+  throw new TypeError("Unsupported object data.");
+};
+
+const file = (key: string, visibility: ObjectVisibility = "private"): ObjectStoreFile => {
+  const prefix = objectStoreArea(visibility);
+  validateKey(key, prefix);
+  const path = prefix + key;
+  const stream = () => {
+    let reader: Promise<ReadableStreamDefaultReader<Uint8Array>> | undefined;
+    const source = () =>
+      (reader ??= objectStoreBackend().then(({ client, limit }) => boundedStream(client.file(path).stream(), limit).getReader()));
+    return new ReadableStream<Uint8Array>(
+      {
+        async pull(controller) {
+          try {
+            const current = await source();
+            const next = await current.read();
+            if (next.done) {
+              current.releaseLock();
+              controller.close();
+            } else controller.enqueue(next.value);
+          } catch (error) {
+            void reader?.then(
+              (current) => current.releaseLock(),
+              () => {},
+            );
+            controller.error(error);
+          }
+        },
+        async cancel(reason) {
+          if (!reader) return;
+          const current = await reader;
+          try {
+            await current.cancel(reason);
+          } finally {
+            current.releaseLock();
+          }
+        },
+      },
+      { highWaterMark: 0 },
+    );
+  };
+  return Object.freeze({
+    key,
+    get size() {
+      return objectStoreBackend().then(({ client }) => client.size(path));
+    },
+    async stat() {
+      return (await objectStoreBackend()).client.stat(path);
+    },
+    async write(data: ObjectWriteData, options: ObjectWriteOptions = {}) {
+      const { client, limit } = await objectStoreBackend();
+      const content = await uploadData(data, limit);
+      const inheritedType =
+        data instanceof Blob
+          ? data.type
+          : data instanceof Request || data instanceof Response
+            ? data.headers.get("content-type")
+            : undefined;
+      return client.file(path).write(content, { type: options.type ?? (inheritedType || undefined) });
+    },
+    text: () => new Response(stream()).text(),
+    bytes: () => new Response(stream()).bytes(),
+    stream,
+    async exists() {
+      return (await objectStoreBackend()).client.file(path).exists();
+    },
+    async delete() {
+      return (await objectStoreBackend()).client.file(path).delete();
+    },
+    async copy(destinationKey: string) {
+      validateKey(destinationKey, prefix);
+      const { client, limit } = await objectStoreBackend();
+      const metadata = await client.stat(path);
+      assertSize(metadata.size, limit);
+      const content = await new Response(boundedStream(client.file(path).stream(), limit)).bytes();
+      return client.file(prefix + destinationKey).write(content, { type: metadata.type });
+    },
+    presign(options: ObjectPresignOptions = {}) {
+      if (visibility !== "private") throw new Error("Use url for public objects.");
+      const expiresIn = options.expiresIn ?? 300;
+      const method = options.method ?? "GET";
+      if (!Number.isInteger(expiresIn) || expiresIn < 1 || expiresIn > 900) throw new RangeError("Presign expiry must be 1–900 seconds.");
+      if (!["GET", "HEAD", "DELETE"].includes(method))
+        throw new TypeError("Presign supports GET, HEAD, and DELETE; upload through write().");
+      return objectStoreBackend().then(({ client }) => client.file(path).presign({ method, expiresIn }));
+    },
+    get url() {
+      if (visibility !== "public") throw new Error("Private objects have no public URL.");
+      return get<string>("app.url").then(
+        (base) => `${publicCloudOrigin(base)}/public/storage/${path.slice("public/".length).split("/").map(encodeURIComponent).join("/")}`,
+      );
+    },
+  });
+};
+
+/** App-bound S3 operations. Identity comes from app.start(), never from an API parameter. */
+const list = async (options: ObjectListOptions = {}, visibility: ObjectVisibility = "private"): Promise<ObjectListResult> => {
+  const prefix = objectStoreArea(visibility);
+  const relative = validateKey(options.prefix ?? "", prefix, true);
+  const startAfter = options.startAfter === undefined ? undefined : prefix + validateKey(options.startAfter, prefix);
+  const maxKeys = options.maxKeys ?? 1000;
+  if (!Number.isInteger(maxKeys) || maxKeys < 1 || maxKeys > 1000) throw new RangeError("List maxKeys must be 1–1,000.");
+  if (
+    options.continuationToken !== undefined &&
+    (typeof options.continuationToken !== "string" || options.continuationToken.length > 8192)
+  ) {
+    throw new TypeError("Invalid S3 continuation token.");
+  }
+  const { client } = await objectStoreBackend();
+  const result = await client.list({ prefix: prefix + relative, startAfter, maxKeys, continuationToken: options.continuationToken });
+  const contents = result.contents?.flatMap((object) => {
+    if (!object.key.startsWith(prefix + relative)) throw new Error("S3 returned an object outside the requested area.");
+    try {
+      return [{ ...object, key: validateKey(object.key.slice(prefix.length), prefix) }];
+    } catch {
+      // Console folder markers and externally written nonconforming names are
+      // inaccessible through this API, but must not break paging for valid keys.
+      return [];
+    }
+  });
+  return { contents, isTruncated: result.isTruncated, nextContinuationToken: result.nextContinuationToken };
+};
+
+export const storage = Object.freeze({
+  file: (key: string) => file(key),
+  list: (options?: ObjectListOptions) => list(options),
+  public: Object.freeze({ file: (key: string) => file(key, "public"), list: (options?: ObjectListOptions) => list(options, "public") }),
+});