@hasna/recordings 0.3.13 → 0.5.0

package/dist/server/index.js

@@ -15,14 +15,13 @@ var __export = (target, all) => {
     });
 };
 var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
-var __require = import.meta.require;
 
 // package.json
 var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@hasna/recordings",
-    version: "0.3.13",
+    version: "0.5.0",
     type: "module",
     description: "Speech-to-text recording tool with MCP and CLI \u2014 records, transcribes, and optionally enhances text using AI",
     repository: {
@@ -48,6 +47,19 @@ var init_package = __esm(() => {
       "./sdk": {
         import: "./dist/sdk/index.js",
         types: "./dist/sdk/index.d.ts"
+      },
+      "./contracts/hosted-v1": {
+        import: "./dist/contracts/hosted-v1.js",
+        types: "./dist/contracts/hosted-v1.d.ts"
+      },
+      "./contracts/stream-v1": {
+        import: "./dist/contracts/stream-v1.js",
+        types: "./dist/contracts/stream-v1.d.ts"
+      },
+      "./contracts/fixtures/v1": "./contracts/v1/fixtures.json",
+      "./hosted": {
+        import: "./dist/hosted/index.js",
+        types: "./dist/hosted/index.d.ts"
       }
     },
     engines: {
@@ -56,20 +68,20 @@ var init_package = __esm(() => {
     scripts: {
       clean: "rm -rf dist",
       build: "bun run clean && bun run build:cli && bun run build:mcp && bun run build:serve && bun run build:lib && tsc --emitDeclarationOnly --outDir dist",
-      "build:cli": "bun build src/cli/index.ts --target=bun --outfile=dist/cli/index.js --external=commander --external=chalk --external=openai",
-      "build:mcp": "bun build src/mcp/index.ts --target=bun --outfile=dist/mcp/index.js --external=@modelcontextprotocol/sdk --external=openai",
-      "build:serve": "bun build src/server/index.ts --target=bun --outfile=dist/server/index.js --external=@modelcontextprotocol/sdk --external=@hasna/contracts --external=openai --external=pg",
-      "build:lib": "bun build src/index.ts src/storage.ts src/sdk/index.ts --target=bun --outdir=dist --external=openai",
+      "build:cli": "bun build src/cli/index.ts --target=bun --outfile=dist/cli/index.js --external=commander --external=chalk --external=openai --external=@aws-sdk/client-s3",
+      "build:mcp": "bun build src/mcp/index.ts --target=bun --outfile=dist/mcp/index.js --external=@modelcontextprotocol/sdk --external=openai --external=@aws-sdk/client-s3",
+      "build:serve": "bun build src/server/index.ts --target=bun --outfile=dist/server/index.js --external=@modelcontextprotocol/sdk --external=@hasna/contracts --external=openai --external=pg --external=@aws-sdk/client-s3",
+      "build:lib": "bun build src/index.ts src/storage.ts src/sdk/index.ts --target=bun --outdir=dist --external=openai --external=@aws-sdk/client-s3 && bun run build:contracts",
       "build:native-fs-guard": "/bin/bash scripts/build_native_fs_guard.sh",
       "generate:sdk": "bun run scripts/generate-sdk.ts",
       migrate: "bun run scripts/migrate.ts",
       typecheck: "tsc --noEmit",
       "typecheck:tcc-contract": "tsc --noEmit -p tsconfig.tcc-contract.json",
-      test: "bun test",
+      test: "bun scripts/release-suite-gate.ts --all",
       "verify:ci-suite": "bun scripts/ci-linux-suite.ts --check",
       "verify:ci-suite:run": "bun scripts/ci-linux-suite.ts --verify-run",
       "verify:ci-native": "bun scripts/ci-native-build.ts",
-      "test:gated": 'bun scripts/ci-linux-suite.ts --check && RECORDINGS_TEST_TIMEOUT_MS="${RECORDINGS_TEST_TIMEOUT_MS:-120000}" bun test --timeout "$RECORDINGS_TEST_TIMEOUT_MS" $(bun scripts/ci-linux-suite.ts --gated)',
+      "test:gated": "bun scripts/release-suite-gate.ts",
       "test:vacuity-battery": 'bun scripts/vacuity-manifest-gen.ts > "${TMPDIR:-/tmp}/vacuity-corrupt-sites.tsv" && bun scripts/vacuity-mutation-battery.ts "${TMPDIR:-/tmp}/vacuity-corrupt-sites.tsv"',
       "test:vacuity-battery:source": "bun scripts/vacuity-mutation-battery.ts scripts/vacuity-manifests/source-side.tsv",
       "test:vacuity-battery:chain": "bun scripts/vacuity-mutation-battery.ts scripts/vacuity-manifests/install-chain.tsv",
@@ -87,11 +99,16 @@ var init_package = __esm(() => {
       "prepack:platform-gate": `bash -c 'if [ "$(uname -s)" = Darwin ]; then bun run build:native-fs-guard; else echo "WARN: native fs-guard build skipped on $(uname -s) \u2014 dry-run/CI pack; publish recordings from macOS"; fi'`,
       prepublishOnly: "bun run typecheck && bun run release-suite-gate",
       "release-suite-gate": "bun run scripts/release-suite-gate.ts",
-      "typecheck:shortcut-contract": "tsc --noEmit -p tsconfig.test.json"
+      "typecheck:shortcut-contract": "tsc --noEmit -p tsconfig.test.json",
+      "build:contracts": "bun build src/contracts/hosted-v1.ts src/contracts/stream-v1.ts src/hosted/index.ts --target=bun --root src --outdir=dist --splitting --external=@hasna/contracts"
     },
     files: [
       "dist/",
+      "!dist/__tests__/",
       "scripts/",
+      "!scripts/test-recorder-fixtures.ts",
+      "!scripts/**/__pycache__/",
+      "!scripts/**/*.pyc",
       "Dockerfile.package",
       "bun.lock",
       "src/native/Recordings/App/",
@@ -103,10 +120,14 @@ var init_package = __esm(() => {
       "src/native/Recordings/build.sh",
       "packaging/macos/",
       "README.md",
-      "LICENSE"
+      "LICENSE",
+      "contracts/v1/fixtures.json",
+      "docs/wire-contracts.md",
+      "docs/hosted-sdk.md"
     ],
     dependencies: {
-      "@hasna/contracts": "0.14.1",
+      "@aws-sdk/client-s3": "^3.1007.0",
+      "@hasna/contracts": "1.0.2",
       "@hasna/events": "0.1.11",
       "@modelcontextprotocol/sdk": "^1.12.1",
       chalk: "^5.4.1",
@@ -116,7 +137,7 @@ var init_package = __esm(() => {
       zod: "^3.24.2"
     },
     devDependencies: {
-      "@types/bun": "^1.2.5",
+      "@types/bun": "1.3.14",
       "@types/pg": "^8.11.11",
       "node-api-headers": "1.9.0",
       typescript: "^5.8.2"
@@ -203,6 +224,9 @@ var init_remote_storage = () => {};
 function resolveDatabaseUrl(env = process.env) {
   return env.HASNA_RECORDINGS_DATABASE_URL || env.RECORDINGS_DATABASE_URL || env.DATABASE_URL || undefined;
 }
+function resolveMigrationDatabaseUrl(env = process.env) {
+  return env.HASNA_RECORDINGS_MIGRATE_DATABASE_URL || env.RECORDINGS_MIGRATE_DATABASE_URL || resolveDatabaseUrl(env);
+}
 function resolveDataBackend(env = process.env) {
   return resolveDatabaseUrl(env) ? "postgresql" : "sqlite";
 }
@@ -210,7 +234,7 @@ function isPostgresBackendEnabled(env = process.env) {
   return resolveDataBackend(env) === "postgresql";
 }
 function resolveSigningSecret(env = process.env) {
-  return env.HASNA_RECORDINGS_API_SIGNING_KEY || env.HASNA_API_SIGNING_KEY || env.API_KEY_SIGNING_SECRET || undefined;
+  return env.HASNA_RECORDINGS_API_SIGNING_KEY?.trim() || env.HASNA_API_SIGNING_KEY?.trim() || env.API_KEY_SIGNING_SECRET?.trim() || undefined;
 }
 function requireSigningSecret(env = process.env) {
   const signingSecret = resolveSigningSecret(env);
@@ -224,13 +248,6 @@ function requireSigningSecret(env = process.env) {
 }
 
 // src/server/cloud-readiness.ts
-var exports_cloud_readiness = {};
-__export(exports_cloud_readiness, {
-  pingCloudReadiness: () => pingCloudReadiness,
-  pingCloudConnectivity: () => pingCloudConnectivity,
-  assertCloudSchemaReady: () => assertCloudSchemaReady,
-  assertCloudSchemaContract: () => assertCloudSchemaContract
-});
 function sameColumns(actual, expected) {
   return actual.length === expected.length && actual.every((column, index) => column === expected[index]);
 }
@@ -365,6 +382,16 @@ async function assertCloudSchemaReady(pg2) {
             AND has_schema_privilege(current_user, schema_row.oid, 'CREATE')
        ) AS can_create_in_user_schema,
        has_schema_privilege(current_user, 'public', 'USAGE') AS can_use_public,
+       COALESCE((
+         SELECT has_column_privilege(table_row.relowner, table_row.oid, 'recording_id', 'SELECT') AND
+                has_column_privilege(table_row.relowner, table_row.oid, 'recording_id', 'UPDATE')
+           FROM pg_class table_row WHERE table_row.oid = 'public.recording_idempotency'::regclass
+       ), false) AS owner_can_tombstone_recording_idempotency,
+       COALESCE((
+         SELECT has_column_privilege(table_row.relowner, table_row.oid, 'recording_id', 'SELECT') AND
+                has_table_privilege(table_row.relowner, table_row.oid, 'DELETE')
+           FROM pg_class table_row WHERE table_row.oid = 'public.recording_tags'::regclass
+       ), false) AS owner_can_delete_recording_tags,
        EXISTS (
          SELECT 1
            FROM pg_class table_row
@@ -451,6 +478,12 @@ async function assertCloudSchemaReady(pg2) {
   if (excessive.length > 0) {
     throw new Error(`cloud database role has surplus table privileges beyond runtime use: ${excessive.join(", ")}`);
   }
+  if (!row?.owner_can_tombstone_recording_idempotency) {
+    throw new Error("cloud database recording_idempotency owner lacks SELECT/UPDATE privileges required for recording deletion");
+  }
+  if (!row?.owner_can_delete_recording_tags) {
+    throw new Error("cloud database recording_tags owner lacks SELECT/DELETE privileges required for recording deletion");
+  }
 }
 async function pingCloudConnectivity(pg2) {
   const res = await pg2.get("SELECT 1 as ok");
@@ -488,6 +521,9 @@ var init_cloud_readiness = __esm(() => {
       id: ["text", false],
       audio_path: ["text", true],
       raw_text: ["text", false],
+      audio_object_key: ["text", true],
+      audio_sha256: ["text", true],
+      audio_bytes: ["bigint", true],
       processed_text: ["text", true],
       processing_mode: ["text", false],
       model_used: ["text", false],
@@ -694,16 +730,14 @@ var init_pg_migrations = __esm(() => {
      ALTER COLUMN recording_id DROP NOT NULL;
    ALTER TABLE recording_idempotency
      ADD CONSTRAINT recording_idempotency_recording_id_fkey
-     FOREIGN KEY (recording_id) REFERENCES recordings(id) ON DELETE SET NULL`
+     FOREIGN KEY (recording_id) REFERENCES recordings(id) ON DELETE SET NULL`,
+    `ALTER TABLE recordings ADD COLUMN IF NOT EXISTS audio_object_key TEXT`,
+    `ALTER TABLE recordings ADD COLUMN IF NOT EXISTS audio_sha256 TEXT`,
+    `ALTER TABLE recordings ADD COLUMN IF NOT EXISTS audio_bytes BIGINT`
   ];
 });
 
 // src/server/migrate-command.ts
-var exports_migrate_command = {};
-__export(exports_migrate_command, {
-  runCloudMigration: () => runCloudMigration,
-  applyRecordedCloudMigrations: () => applyRecordedCloudMigrations
-});
 async function applyRecordedCloudMigrations(pg2, ensureApiKeySchema) {
   await pg2.run(`CREATE TABLE IF NOT EXISTS _pg_migrations (id SERIAL PRIMARY KEY, version INT UNIQUE NOT NULL, applied_at TIMESTAMPTZ DEFAULT NOW())`);
   const applied = await pg2.all("SELECT version FROM _pg_migrations ORDER BY version");
@@ -720,10 +754,12 @@ async function applyRecordedCloudMigrations(pg2, ensureApiKeySchema) {
   }
   await ensureApiKeySchema();
 }
-async function runCloudMigration(steps) {
+async function runCloudMigration(steps, runtimePostureValidate) {
   await steps.pingConnectivity();
   await steps.applyMigrations();
   await steps.validateContract();
+  if (runtimePostureValidate)
+    await runtimePostureValidate();
 }
 var init_migrate_command = __esm(() => {
   init_pg_migrations();
@@ -732,7 +768,9 @@ var init_migrate_command = __esm(() => {
 // src/server/cloud.ts
 var exports_cloud = {};
 __export(exports_cloud, {
+  runRecordedMigration: () => runRecordedMigration,
   resolveSigningSecret: () => resolveSigningSecret,
+  resolveMigrationDatabaseUrl: () => resolveMigrationDatabaseUrl,
   resolveDatabaseUrl: () => resolveDatabaseUrl,
   resolveDataBackend: () => resolveDataBackend,
   requireSigningSecret: () => requireSigningSecret,
@@ -740,6 +778,7 @@ __export(exports_cloud, {
   pingCloud: () => pingCloud,
   migrateCloudSchema: () => migrateCloudSchema,
   isPostgresBackendEnabled: () => isPostgresBackendEnabled,
+  getMigrationPg: () => getMigrationPg,
   getCloudVerifier: () => getCloudVerifier,
   getCloudPg: () => getCloudPg,
   getApiKeyStore: () => getApiKeyStore,
@@ -759,8 +798,7 @@ function getCloudPg() {
   cachedPg = new PgAdapterAsync(url);
   return cachedPg;
 }
-function authClient() {
-  const pg2 = getCloudPg();
+function authClient(pg2 = getCloudPg()) {
   return {
     async many(sql, params = []) {
       return await pg2.all(sql, ...params);
@@ -796,8 +834,30 @@ function getCloudVerifier() {
   });
   return cachedVerifier;
 }
-async function migrateCloudSchema() {
-  await applyRecordedCloudMigrations(getCloudPg(), () => getApiKeyStore().ensureSchema());
+function getMigrationPg() {
+  const url = resolveMigrationDatabaseUrl();
+  if (!url) {
+    throw new Error("migrate requires a database URL (HASNA_RECORDINGS_MIGRATE_DATABASE_URL / RECORDINGS_MIGRATE_DATABASE_URL / HASNA_RECORDINGS_DATABASE_URL / RECORDINGS_DATABASE_URL / DATABASE_URL).");
+  }
+  return new PgAdapterAsync(url);
+}
+async function migrateCloudSchema(pg2 = getCloudPg()) {
+  await applyRecordedCloudMigrations(pg2, () => new ApiKeyStore(authClient(pg2)).ensureSchema());
+}
+async function runRecordedMigration() {
+  const migrationPg = getMigrationPg();
+  const runtimeUrl = resolveDatabaseUrl();
+  const migrationUrl = resolveMigrationDatabaseUrl();
+  const separateRoles = runtimeUrl !== undefined && migrationUrl !== undefined && runtimeUrl !== migrationUrl;
+  await runCloudMigration({
+    pingConnectivity: () => pingCloudConnectivity2(migrationPg),
+    applyMigrations: async () => {
+      await migrateCloudSchema(migrationPg);
+    },
+    validateContract: () => assertCloudSchemaContract(migrationPg)
+  }, separateRoles ? async () => {
+    await assertCloudSchemaReady(getCloudPg());
+  } : undefined);
 }
 async function ensureCloudSchema() {
   if (schemaEnsured)
@@ -942,6 +1002,9 @@ function parseRecording(row) {
   return {
     id: row["id"],
     audio_path: row["audio_path"] || null,
+    audio_object_key: row["audio_object_key"] || null,
+    audio_sha256: row["audio_sha256"] || null,
+    audio_bytes: Number(row["audio_bytes"] ?? 0) || null,
     raw_text: row["raw_text"],
     processed_text: row["processed_text"] || null,
     processing_mode: row["processing_mode"] || "raw",
@@ -1031,9 +1094,9 @@ async function createRecording(pg2, input, idempotencyKey, idempotencyContext) {
         throw new ProjectNotFoundError(input.project_id);
       resolvedProjectId = project.id;
     }
-    const insertResult = await transaction.run(`INSERT INTO recordings (id, audio_path, raw_text, processed_text, processing_mode, model_used, enhancement_model, duration_ms, language, tags, agent_id, project_id, session_id, goal, role, task_list_id, machine_id, metadata)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-     ON CONFLICT(id) DO NOTHING`, id, input.audio_path || null, input.raw_text, input.processed_text || null, input.processing_mode || "raw", input.model_used || "gpt-4o-transcribe", input.enhancement_model || null, input.duration_ms || 0, input.language || null, JSON.stringify(input.tags || []), resolvedAgentId, resolvedProjectId, input.session_id || null, input.goal || null, input.role || null, input.task_list_id || null, input.machine_id || null, JSON.stringify(input.metadata || {}));
+    const insertResult = await transaction.run(`INSERT INTO recordings (id, audio_path, audio_object_key, audio_sha256, audio_bytes, raw_text, processed_text, processing_mode, model_used, enhancement_model, duration_ms, language, tags, agent_id, project_id, session_id, goal, role, task_list_id, machine_id, metadata)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT(id) DO NOTHING`, id, input.audio_path || null, input.audio_object_key || null, input.audio_sha256 || null, input.audio_bytes || null, input.raw_text, input.processed_text || null, input.processing_mode || "raw", input.model_used || "gpt-4o-transcribe", input.enhancement_model || null, input.duration_ms || 0, input.language || null, JSON.stringify(input.tags || []), resolvedAgentId, resolvedProjectId, input.session_id || null, input.goal || null, input.role || null, input.task_list_id || null, input.machine_id || null, JSON.stringify(input.metadata || {}));
     if (insertResult.changes === 0) {
       throw new IdempotencyConflictError;
     }
@@ -1454,6 +1517,9 @@ function buildV1OpenApiDocument(version = VERSION) {
             id: { type: "string" },
             raw_text: { type: "string" },
             audio_path: { type: "string" },
+            audio_object_key: { type: "string" },
+            audio_sha256: { type: "string" },
+            audio_bytes: { type: "number" },
             processed_text: { type: "string" },
             processing_mode: { type: "string", enum: ["raw", "enhanced"] },
             model_used: { type: "string" },
@@ -1742,6 +1808,9 @@ var init_openapi = __esm(() => {
     properties: {
       id: { type: "string" },
       audio_path: { type: "string", nullable: true },
+      audio_object_key: { type: "string", nullable: true },
+      audio_sha256: { type: "string", nullable: true },
+      audio_bytes: { type: "number", nullable: true },
       raw_text: { type: "string" },
       processed_text: { type: "string", nullable: true },
       processing_mode: { type: "string", enum: ["raw", "enhanced"] },
@@ -1786,6 +1855,172 @@ var init_openapi = __esm(() => {
   };
 });
 
+// src/server/client-ip.ts
+function normalizeIpLiteral(raw) {
+  let value = (raw ?? "").trim();
+  if (!value)
+    return null;
+  const bracketed = /^\[([^\]]+)\](?::\d+)?$/.exec(value);
+  if (bracketed)
+    value = bracketed[1];
+  else if (/^\d{1,3}(?:\.\d{1,3}){3}:\d+$/.test(value))
+    value = value.slice(0, value.lastIndexOf(":"));
+  value = value.trim().toLowerCase();
+  if (!value || value.length > 45)
+    return null;
+  const mapped = /^::ffff:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/.exec(value);
+  if (mapped)
+    value = mapped[1];
+  const ipv4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(value);
+  if (ipv4) {
+    return ipv4.slice(1).every((octet) => Number(octet) <= 255 && !/^0\d/.test(octet)) ? value : null;
+  }
+  if (/^[0-9a-f:]+(?:\.\d{1,3}){0,3}$/.test(value) && value.includes(":") && !/:::/.test(value)) {
+    return value;
+  }
+  return null;
+}
+function parseForwardedFor(header) {
+  if (!header)
+    return [];
+  return header.split(",").map((entry) => normalizeIpLiteral(entry)).filter((entry) => entry !== null);
+}
+function parseCidr(entry) {
+  const slash = entry.indexOf("/");
+  const rawAddress = slash >= 0 ? entry.slice(0, slash) : entry;
+  const rawPrefix = slash >= 0 ? entry.slice(slash + 1) : null;
+  const address = normalizeIpLiteral(rawAddress);
+  if (!address)
+    return null;
+  if (address.includes(":")) {
+    if (rawPrefix !== null && !/^\d{1,3}$/.test(rawPrefix))
+      return null;
+    const prefix2 = rawPrefix === null ? 128 : Number(rawPrefix);
+    if (prefix2 < 0 || prefix2 > 128)
+      return null;
+    const bytes2 = expandV6(address);
+    if (!bytes2)
+      return null;
+    const masked2 = maskNetwork(bytes2, prefix2);
+    return { address, prefix: prefix2, bytes: masked2, family: "ipv6" };
+  }
+  if (rawPrefix !== null && !/^\d{1,3}$/.test(rawPrefix))
+    return null;
+  const prefix = rawPrefix === null ? 32 : Number(rawPrefix);
+  if (prefix < 0 || prefix > 32)
+    return null;
+  const bytes = address.split(".").map((octet) => Number(octet));
+  const masked = maskNetwork(bytes, prefix);
+  return { address, prefix, bytes: masked, family: "ipv4" };
+}
+function expandV6(address) {
+  const compressed = address.split("::");
+  if (compressed.length > 2)
+    return null;
+  let groups = [];
+  if (compressed.length === 2) {
+    const left = compressed[0] ? compressed[0].split(":") : [];
+    const right = compressed[1] ? compressed[1].split(":") : [];
+    const missing = 8 - left.length - right.length;
+    if (missing < 1)
+      return null;
+    groups = [...left, ...Array(missing).fill("0"), ...right];
+  } else {
+    groups = address.split(":");
+  }
+  if (groups.length !== 8)
+    return null;
+  const bytes = [];
+  for (const group of groups) {
+    if (!/^[0-9a-f]{1,4}$/.test(group))
+      return null;
+    const value = Number.parseInt(group, 16);
+    bytes.push(value >> 8 & 255, value & 255);
+  }
+  return bytes;
+}
+function maskNetwork(bytes, prefix) {
+  const masked = bytes.slice();
+  const fullBytes = Math.floor(prefix / 8);
+  const remainder = prefix % 8;
+  for (let i = 0;i < masked.length; i++) {
+    if (i >= fullBytes) {
+      if (i === fullBytes && remainder > 0) {
+        masked[i] = masked[i] & (255 << 8 - remainder & 255);
+      } else {
+        masked[i] = 0;
+      }
+    }
+  }
+  return masked;
+}
+function parseTrustedProxies(raw) {
+  if (!raw)
+    return [];
+  const seen = new Set;
+  const trusted = [];
+  for (const entry of raw.split(",").map((part) => part.trim()).filter(Boolean)) {
+    const cidr = parseCidr(entry);
+    if (cidr && !seen.has(entry)) {
+      seen.add(entry);
+      trusted.push(entry);
+    }
+  }
+  return trusted;
+}
+function isMatch(candidateBytes, cidr) {
+  if (cidr.bytes.length !== candidateBytes.length)
+    return false;
+  const masked = maskNetwork(candidateBytes, cidr.prefix);
+  for (let i = 0;i < cidr.bytes.length; i++) {
+    if (cidr.bytes[i] !== masked[i])
+      return false;
+  }
+  return true;
+}
+function isTrustedAddress(ip, trusted) {
+  const address = normalizeIpLiteral(ip);
+  if (!address)
+    return false;
+  const cidrs = trusted.map(parseCidr).filter((cidr) => cidr !== null);
+  for (const cidr of cidrs) {
+    if (cidr.address === address)
+      return true;
+    const bytes = cidr.family === "ipv4" ? address.split(".").map((octet) => Number(octet)) : expandV6(address);
+    if (bytes && isMatch(bytes, cidr))
+      return true;
+  }
+  return false;
+}
+function resolveTrustProxy(env = process.env) {
+  return TRUST_TRUE_VALUES.has((env[TRUST_PROXY_ENV] ?? "").trim().toLowerCase());
+}
+function trustedProxiesFromEnv(env = process.env) {
+  return parseTrustedProxies(env[TRUSTED_PROXIES_ENV]);
+}
+function resolveRequestClientIp(input) {
+  const socket = normalizeIpLiteral(input.socketAddress);
+  if (input.trustProxy !== true)
+    return socket;
+  const trusted = input.trustedProxies ?? [];
+  const real = normalizeIpLiteral(input.headers.get("x-real-ip"));
+  if (real)
+    return real;
+  const chain = parseForwardedFor(input.headers.get("x-forwarded-for"));
+  for (let i = chain.length - 1;i >= 0; i--) {
+    const hop = chain[i];
+    if (!isTrustedAddress(hop, trusted))
+      return hop;
+  }
+  if (chain.length > 0)
+    return chain[0];
+  return socket;
+}
+var TRUST_PROXY_ENV = "RECORDINGS_TRUST_PROXY", TRUSTED_PROXIES_ENV = "RECORDINGS_TRUSTED_PROXIES", TRUST_TRUE_VALUES;
+var init_client_ip = __esm(() => {
+  TRUST_TRUE_VALUES = new Set(["1", "true", "yes", "on"]);
+});
+
 // src/mcp/http.ts
 var exports_http = {};
 __export(exports_http, {
@@ -5888,32 +6123,6 @@ function assertMaintenanceAbsent(env) {
   if (pathExists(installMaintenanceMarkerPath(env)))
     throw maintenanceUnavailable();
 }
-function canonicalPotentialPath(path) {
-  const absolutePath = resolve(path);
-  let existingPath = absolutePath;
-  const missingEntries = [];
-  while (true) {
-    try {
-      return join(realpathSync(existingPath), ...missingEntries);
-    } catch (error2) {
-      if (error2.code !== "ENOENT")
-        return absolutePath;
-      const parent = dirname(existingPath);
-      if (parent === existingPath)
-        return absolutePath;
-      missingEntries.unshift(basename(existingPath));
-      existingPath = parent;
-    }
-  }
-}
-function pathIsWithin(root, candidate) {
-  const relativePath = relative(root, candidate);
-  return relativePath === "" || relativePath !== ".." && !relativePath.startsWith(`..${sep}`) && !isAbsolute(relativePath);
-}
-function isGlobalRecordingsStatePath(path, env = process.env) {
-  const globalStateRoot = join(stateParent(env), "recordings");
-  return pathIsWithin(resolve(globalStateRoot), resolve(path)) || pathIsWithin(canonicalPotentialPath(globalStateRoot), canonicalPotentialPath(path));
-}
 function removeActiveLease(activeLease, releasedLease) {
   try {
     renameSync(activeLease, releasedLease);
@@ -5999,6 +6208,9 @@ function loadConfig(configPath) {
   if (process.env.RECORDINGS_API_KEY) {
     config.openai_api_key = process.env.RECORDINGS_API_KEY;
   }
+  if (process.env.RECORDINGS_OPENAI_API_KEY) {
+    config.openai_api_key = process.env.RECORDINGS_OPENAI_API_KEY;
+  }
   if (process.env.RECORDINGS_ENHANCEMENT_KEY) {
     config.enhancement_api_key = process.env.RECORDINGS_ENHANCEMENT_KEY;
   }
@@ -6042,14 +6254,26 @@ function loadConfig(configPath) {
   if (process.env.RECORDINGS_AUDIO_DIR) {
     config.audio_dir = process.env.RECORDINGS_AUDIO_DIR;
   }
+  if (process.env.HASNA_RECORDINGS_S3_BUCKET) {
+    config.s3_bucket = process.env.HASNA_RECORDINGS_S3_BUCKET;
+  } else if (process.env.RECORDINGS_S3_BUCKET) {
+    config.s3_bucket = process.env.RECORDINGS_S3_BUCKET;
+  }
+  if (process.env.HASNA_RECORDINGS_S3_PREFIX) {
+    config.s3_prefix = process.env.HASNA_RECORDINGS_S3_PREFIX;
+  } else if (process.env.RECORDINGS_S3_PREFIX) {
+    config.s3_prefix = process.env.RECORDINGS_S3_PREFIX;
+  }
+  if (process.env.RECORDINGS_S3_REGION) {
+    config.s3_region = process.env.RECORDINGS_S3_REGION;
+  } else if (process.env.AWS_REGION) {
+    config.s3_region = process.env.AWS_REGION;
+  }
   if (process.env.RECORDINGS_MAX_SECONDS) {
     config.max_recording_seconds = parseInt(process.env.RECORDINGS_MAX_SECONDS, 10);
   }
-  if (!config.openai_api_key) {
-    config.openai_api_key = loadSecretKey("OPENAI_API_KEY");
-  }
   if (!config.enhancement_api_key) {
-    config.enhancement_api_key = config.openai_api_key || loadSecretKey("OPENAI_API_KEY");
+    config.enhancement_api_key = config.openai_api_key;
   }
   if (!explicitTranscriberModel) {
     config.transcriber_model = config.enhancement_model;
@@ -6229,66 +6453,9 @@ function mergeDirectoryContents(sourceDir, targetDir) {
     }
   }
 }
-function loadSecretKey(keyName) {
-  const secretsPath = join2(getHomeDir(), ".secrets");
-  if (!existsSync(secretsPath))
-    return "";
-  for (const candidate of listSecretFiles(secretsPath)) {
-    try {
-      const content = readFileSync(candidate, "utf-8");
-      const match = content.match(new RegExp(`export\\s+${keyName}\\s*=\\s*"([^"]+)"`));
-      const doubleQuotedValue = match?.[1];
-      if (doubleQuotedValue !== undefined)
-        return doubleQuotedValue;
-      const match2 = content.match(new RegExp(`export\\s+${keyName}\\s*=\\s*'([^']+)'`));
-      const singleQuotedValue = match2?.[1];
-      if (singleQuotedValue !== undefined)
-        return singleQuotedValue;
-      const match3 = content.match(new RegExp(`${keyName}\\s*=\\s*(.+)`));
-      const unquotedValue = match3?.[1];
-      if (unquotedValue !== undefined)
-        return unquotedValue.trim().replace(/^["']|["']$/g, "");
-    } catch {}
-  }
-  return "";
-}
-function listSecretFiles(path) {
-  try {
-    const stats = statSync(path);
-    if (stats.isFile())
-      return [path];
-    if (!stats.isDirectory())
-      return [];
-    return readdirSync(path).sort().flatMap((entry) => {
-      const child = join2(path, entry);
-      try {
-        const childStats = statSync(child);
-        if (childStats.isDirectory())
-          return listSecretFiles(child);
-        if (childStats.isFile() && child.endsWith(".env"))
-          return [child];
-      } catch {}
-      return [];
-    });
-  } catch {
-    return [];
-  }
-}
 function getHomeDir() {
   return process.env["HOME"] || process.env["USERPROFILE"] || homedir2();
 }
-function ensureDataDir(config) {
-  const { mkdirSync: mkdirSync3 } = __require("fs");
-  const dbDir = config.db_path.substring(0, config.db_path.lastIndexOf("/"));
-  const releaseLease = [config.audio_dir, dbDir].some((path) => path.length > 0 && isGlobalRecordingsStatePath(path)) ? acquireLocalStoreReaderLease() : () => {};
-  try {
-    mkdirSync3(config.audio_dir, { recursive: true });
-    if (dbDir)
-      mkdirSync3(dbDir, { recursive: true });
-  } finally {
-    releaseLease();
-  }
-}
 var POST_PROCESSING_MODES, DEFAULT_TRANSCRIPTION_MODEL = "gpt-4o-transcribe", DEFAULT_REALTIME_SESSION_MODEL = "gpt-realtime", DEFAULT_REALTIME_TRANSCRIPTION_MODEL = "gpt-realtime-whisper", DEFAULT_CONFIG;
 var init_config = __esm(() => {
   init_install_maintenance();
@@ -6330,6 +6497,9 @@ var init_config = __esm(() => {
     db_path: "",
     audio_dir: "",
     max_recording_seconds: 1800,
+    s3_bucket: "",
+    s3_prefix: "",
+    s3_region: "",
     config_warnings: []
   };
 });
@@ -6421,6 +6591,9 @@ function repairSchemaDrift(db) {
   ensureColumn(db, "recordings", "task_list_id", "TEXT");
   ensureColumn(db, "recordings", "machine_id", "TEXT");
   ensureColumn(db, "recordings", "metadata", "TEXT DEFAULT '{}'");
+  ensureColumn(db, "recordings", "audio_object_key", "TEXT");
+  ensureColumn(db, "recordings", "audio_sha256", "TEXT");
+  ensureColumn(db, "recordings", "audio_bytes", "INTEGER");
   ensureColumn(db, "agents", "active_project_id", "TEXT REFERENCES projects(id) ON DELETE SET NULL");
 }
 function ensureColumn(db, table, column, definition) {
@@ -6514,6 +6687,11 @@ var init_database = __esm(() => {
   `,
     `
   ALTER TABLE agents ADD COLUMN active_project_id TEXT REFERENCES projects(id) ON DELETE SET NULL;
+  `,
+    `
+  ALTER TABLE recordings ADD COLUMN audio_object_key TEXT;
+  ALTER TABLE recordings ADD COLUMN audio_sha256 TEXT;
+  ALTER TABLE recordings ADD COLUMN audio_bytes INTEGER;
   `
   ];
   CURRENT_MIGRATION_LEVEL = MIGRATIONS.length - 1;
@@ -6524,6 +6702,9 @@ function parseRow(row) {
   return {
     id: row["id"],
     audio_path: row["audio_path"] || null,
+    audio_object_key: row["audio_object_key"] || null,
+    audio_sha256: row["audio_sha256"] || null,
+    audio_bytes: Number(row["audio_bytes"] ?? 0) || null,
     raw_text: row["raw_text"],
     processed_text: row["processed_text"] || null,
     processing_mode: row["processing_mode"] || "raw",
@@ -6555,9 +6736,9 @@ function createRecording2(input, db, idempotencyKey) {
     }
     const tagsJson = JSON.stringify(input.tags || []);
     const metadataJson = JSON.stringify(input.metadata || {});
-    const insertResult = d.query(`INSERT INTO recordings (id, audio_path, raw_text, processed_text, processing_mode, model_used, enhancement_model, duration_ms, language, tags, agent_id, project_id, session_id, goal, role, task_list_id, machine_id, metadata)
-     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-     ON CONFLICT(id) DO NOTHING`).run(id, input.audio_path || null, input.raw_text, input.processed_text || null, input.processing_mode || "raw", input.model_used || "gpt-4o-transcribe", input.enhancement_model || null, input.duration_ms || 0, input.language || null, tagsJson, input.agent_id || null, input.project_id || null, input.session_id || null, input.goal || null, input.role || null, input.task_list_id || null, input.machine_id || null, metadataJson);
+    const insertResult = d.query(`INSERT INTO recordings (id, audio_path, audio_object_key, audio_sha256, audio_bytes, raw_text, processed_text, processing_mode, model_used, enhancement_model, duration_ms, language, tags, agent_id, project_id, session_id, goal, role, task_list_id, machine_id, metadata)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+     ON CONFLICT(id) DO NOTHING`).run(id, input.audio_path || null, input.audio_object_key || null, input.audio_sha256 || null, input.audio_bytes || null, input.raw_text, input.processed_text || null, input.processing_mode || "raw", input.model_used || "gpt-4o-transcribe", input.enhancement_model || null, input.duration_ms || 0, input.language || null, tagsJson, input.agent_id || null, input.project_id || null, input.session_id || null, input.goal || null, input.role || null, input.task_list_id || null, input.machine_id || null, metadataJson);
     if (insertResult.changes === 0) {
       const existing = getRecording2(id, d);
       if (existing?.id === id)
@@ -6574,6 +6755,13 @@ function createRecording2(input, db, idempotencyKey) {
   });
   return create();
 }
+function updateRecordingAudio(id, audioObjectKey, audioSha256, audioBytes, db) {
+  const d = db || getDatabase();
+  const result = d.query(`UPDATE recordings SET audio_object_key = ?, audio_sha256 = ?, audio_bytes = ? WHERE id = ?`).run(audioObjectKey, audioSha256, audioBytes, id);
+  if (result.changes === 0)
+    return null;
+  return getRecording2(id, d);
+}
 function getRecording2(id, db) {
   const d = db || getDatabase();
   let row = d.query("SELECT * FROM recordings WHERE id = ?").get(id);
@@ -6795,151 +6983,266 @@ var init_feedback = __esm(() => {
   init_version();
 });
 
+// src/lib/local-opt-in.ts
+import {
+  clientTransportEnvKeys,
+  credentialOverrideEnvKey,
+  credentialPointerEnvKey,
+  CREDENTIAL_PROFILE_ENV_KEY
+} from "@hasna/contracts/client";
+function isRecordingsLocalOptIn(env = process.env) {
+  return RECORDINGS_LOCAL_OPT_IN_ENV_KEYS.some((key) => (env[key] ?? "").trim() !== "");
+}
+function recordingsAuthorityEnvKeys() {
+  const keys = clientTransportEnvKeys("recordings");
+  return [
+    ...keys.apiUrlKeys,
+    ...keys.apiKeyKeys,
+    credentialOverrideEnvKey("recordings"),
+    credentialPointerEnvKey("recordings"),
+    CREDENTIAL_PROFILE_ENV_KEY
+  ].filter((key) => !RECORDINGS_CARVED_LEGACY_ENV_KEYS.includes(key));
+}
+function hasRecordingsEnvAuthorityIntent(env = process.env) {
+  return recordingsAuthorityEnvKeys().some((key) => (env[key] ?? "").trim() !== "");
+}
+function selectsRecordingsLocalStore(env = process.env) {
+  return !hasRecordingsEnvAuthorityIntent(env) && isRecordingsLocalOptIn(env);
+}
+function recordingsResolverEnv(env) {
+  const carved = RECORDINGS_CARVED_LEGACY_ENV_KEYS.filter((key) => (key in env));
+  const blanks = recordingsAuthorityEnvKeys().filter((key) => (key in env) && (env[key] ?? "").trim() === "");
+  const removed = new Set([...carved, ...blanks]);
+  if (removed.size === 0)
+    return env;
+  const next = { ...env };
+  for (const key of removed)
+    delete next[key];
+  return next;
+}
+function isAmbientRecordingsEnv(env) {
+  if (typeof process !== "undefined" && env === process.env) {
+    return true;
+  }
+  return env[CONTRACTS_AMBIENT_ENVIRONMENT] === true;
+}
+function recordingsResolverInputs(env, credentials = {}) {
+  const normalised = recordingsResolverEnv(env);
+  if (normalised === env)
+    return { env: normalised, credentials };
+  const keychain = { ...credentials.keychain };
+  if (keychain.enabled === undefined && keychain.run === undefined) {
+    keychain.enabled = isAmbientRecordingsEnv(env);
+  }
+  return { env: normalised, credentials: { ...credentials, keychain } };
+}
+var RECORDINGS_LOCAL_OPT_IN_ENV_KEYS, RECORDINGS_CARVED_LEGACY_ENV_KEYS, CONTRACTS_AMBIENT_ENVIRONMENT;
+var init_local_opt_in = __esm(() => {
+  RECORDINGS_LOCAL_OPT_IN_ENV_KEYS = [
+    "HASNA_RECORDINGS_LOCAL",
+    "RECORDINGS_LOCAL"
+  ];
+  RECORDINGS_CARVED_LEGACY_ENV_KEYS = [
+    "RECORDINGS_API_URL",
+    "RECORDINGS_API_KEY"
+  ];
+  CONTRACTS_AMBIENT_ENVIRONMENT = Symbol.for("hasna:contracts:ambientClientEnvironment");
+});
+
 // src/http/client.ts
-import { createClientTransport } from "@hasna/contracts/client";
 import {
-  createHasnaStorageClient,
+  clientTransportEnvKeys as clientTransportEnvKeys2,
+  resolveClientTransport
+} from "@hasna/contracts/client";
+import {
   resolveStorageClient
 } from "@hasna/contracts/client/storage";
-function envToken(name) {
-  return name.toUpperCase().replace(/-/g, "_");
-}
-function envKeys(name) {
-  const token = envToken(name);
-  return {
-    storeKeys: [`HASNA_${token}_CLIENT_STORE`, `${token}_CLIENT_STORE`],
-    apiUrlKeys: [`HASNA_${token}_API_URL`],
-    apiKeyKeys: [`HASNA_${token}_API_KEY`]
-  };
-}
-function normalizeClientStore(value) {
-  const normalized = value.trim().toLowerCase();
-  if (normalized === "sqlite")
-    return "sqlite";
-  if (normalized === "http" || normalized === "https")
-    return "http";
-  throw new Error(`Unknown client store: ${value}. Use sqlite or http.`);
-}
-function firstEnv(env, keys) {
-  for (const key of keys) {
-    const value = env[key]?.trim();
-    if (value)
-      return { key, value };
+function throwRecordingsAuthorityFailure(error2) {
+  const message = error2 instanceof Error ? error2.message : String(error2);
+  const name = error2 instanceof Error ? error2.name : "";
+  if (name === "CredentialResolutionError" || name === "CredentialFileUnsafeError") {
+    throw new Error(`REMOTE_API_CREDENTIAL_INVALID: ${message} There is no local fallback: ` + "local SQLite is opt-in only (HASNA_RECORDINGS_LOCAL=1) and is disabled by default \u2014 failing closed", { cause: error2 });
   }
-  return null;
+  if (/no API key could be resolved/.test(message)) {
+    if (/is not set and no API key could be resolved/.test(message)) {
+      throw new Error("REMOTE_API_CONFIG_MISSING: no Recordings credential resolved from the Keychain item " + `hasna.credentials.recordings.api-key, ~/.hasna/recordings/config/credentials, or HASNA_RECORDINGS_API_KEY. ${message} ` + "There is no local fallback: local SQLite is opt-in only (HASNA_RECORDINGS_LOCAL=1, alias RECORDINGS_LOCAL=1) " + "and is disabled by default \u2014 failing closed instead of serving the local store", { cause: error2 });
+    }
+    throw new Error("REMOTE_API_KEY_MISSING: remote Recordings storage requires HASNA_RECORDINGS_API_KEY, the Keychain item " + `hasna.credentials.recordings.api-key, or ~/.hasna/recordings/config/credentials. ${message} ` + "There is no local fallback: local SQLite is opt-in only (HASNA_RECORDINGS_LOCAL=1) and is disabled by default \u2014 failing closed", { cause: error2 });
+  }
+  throw new Error(`REMOTE_API_URL_INVALID: ${message} local SQLite fallback is disabled`, { cause: error2 });
 }
-function toV1BaseUrl(apiUrl) {
-  const url = new URL(apiUrl);
-  if (url.protocol !== "http:" && url.protocol !== "https:") {
-    throw new Error("API URL must use http or https.");
-  }
-  let path = url.pathname.replace(/\/+$/, "");
-  if (path.endsWith("/v1"))
-    path = path.slice(0, -"/v1".length);
-  url.pathname = `${path}/v1`;
-  url.search = "";
-  url.hash = "";
-  return url.toString().replace(/\/+$/, "");
-}
-function resolveTransport(name, env = process.env) {
-  const keys = envKeys(name);
-  const storeHit = firstEnv(env, keys.storeKeys);
-  const urlHit = firstEnv(env, keys.apiUrlKeys);
-  const keyHit = firstEnv(env, keys.apiKeyKeys);
-  let requested = "sqlite";
-  let modeSource = "default";
-  if (storeHit) {
-    requested = normalizeClientStore(storeHit.value);
-    modeSource = storeHit.key;
-  } else if (urlHit && keyHit) {
-    requested = "http";
-    modeSource = "auto:api-url+api-key";
-  } else if (urlHit || keyHit) {
-    const missing = urlHit ? keys.apiKeyKeys[0] : keys.apiUrlKeys[0];
-    const present = urlHit ? keys.apiUrlKeys[0] : keys.apiKeyKeys[0];
-    return {
-      transport: "sqlite",
-      requested,
-      modeSource,
-      baseUrl: null,
-      apiKeyPresent: Boolean(keyHit),
-      misconfigured: true,
-      warning: `${present} is set but ${missing} is not: the hosted API is only ` + `selected when BOTH are present. Set ${missing}, or unset ${present} to ` + `use the on-box store.`
-    };
+function resolveRecordingsCloudClient(env = process.env, options = {}) {
+  if (selectsRecordingsLocalStore(env))
+    return null;
+  const resolverInputs = recordingsResolverInputs(env, options.credentials);
+  let resolved;
+  try {
+    resolved = resolveStorageClient("recordings", resolverInputs.env, {
+      fetchImpl: (input, init) => globalThis.fetch(input, { ...init, redirect: "manual" }),
+      credentials: resolverInputs.credentials
+    });
+  } catch (error2) {
+    throwRecordingsAuthorityFailure(error2);
   }
-  if (requested === "sqlite") {
-    return { transport: "sqlite", requested, modeSource, baseUrl: null, apiKeyPresent: Boolean(keyHit), misconfigured: false, warning: null };
+  const client = resolved.client;
+  return client;
+}
+var RETRY_STATUSES, IDEMPOTENT;
+var init_client = __esm(() => {
+  init_local_opt_in();
+  RETRY_STATUSES = new Set([408, 425, 429, 500, 502, 503, 504]);
+  IDEMPOTENT = new Set(["GET", "HEAD", "PUT", "DELETE", "OPTIONS"]);
+});
+
+// src/lib/audio-artifact-storage.ts
+import { GetObjectCommand, PutObjectCommand, S3Client as AwsS3Client } from "@aws-sdk/client-s3";
+import { createHash as createHash2 } from "crypto";
+import { readFile } from "fs/promises";
+import { extname } from "path";
+function contentTypeForExtension(extension) {
+  return AUDIO_CONTENT_TYPES[extension.toLowerCase()] ?? "application/octet-stream";
+}
+
+class AudioArtifactStorage {
+  bucket;
+  prefix;
+  s3;
+  constructor(options = {}) {
+    this.bucket = options.bucket;
+    this.prefix = (options.prefix || DEFAULT_S3_PREFIX).replace(/^\/+|\/+$/g, "");
+    this.s3 = this.bucket ? options.client ?? new AwsS3Client({ region: options.region || process.env.AWS_REGION || "us-east-1" }) : undefined;
+  }
+  get usesS3() {
+    return Boolean(this.bucket);
+  }
+  objectKeyFor(recordingId, sha256, extension) {
+    assertSha256(sha256);
+    const safeExtension = extension.toLowerCase().match(/^[a-z0-9]+/)?.[0] || "bin";
+    return `${this.prefix}/${recordingId}/${sha256}.${safeExtension}`;
+  }
+  async uploadAudio(recordingId, audioPath) {
+    if (!this.bucket || !this.s3)
+      return null;
+    const bytes = await readFileBytes(audioPath);
+    if (!bytes)
+      return null;
+    const sha256 = sha256Hex(bytes);
+    const extension = extensionOf(audioPath);
+    const key = this.objectKeyFor(recordingId, sha256, extension);
+    await this.s3.send(new PutObjectCommand({
+      Bucket: this.bucket,
+      Key: key,
+      Body: bytes,
+      ContentType: contentTypeForExtension(extension)
+    }));
+    return { objectKey: key, sha256, bytes: bytes.byteLength };
+  }
+  async readAudio(objectKey) {
+    if (!this.bucket || !this.s3)
+      return null;
+    try {
+      const response = await this.s3.send(new GetObjectCommand({ Bucket: this.bucket, Key: objectKey }));
+      return await bodyToBytes(response.Body);
+    } catch {
+      return null;
+    }
   }
-  if (!urlHit) {
-    return {
-      transport: "sqlite",
-      requested,
-      modeSource,
-      baseUrl: null,
-      apiKeyPresent: Boolean(keyHit),
-      misconfigured: true,
-      warning: `${modeSource}=http but no API URL is set (${keys.apiUrlKeys[0]}). Refusing to route to the API.`
-    };
+}
+function resolveAudioArtifactStorage(env = process.env, client) {
+  const bucket = env.HASNA_RECORDINGS_S3_BUCKET || env.RECORDINGS_S3_BUCKET || undefined;
+  const prefix = env.HASNA_RECORDINGS_S3_PREFIX || env.RECORDINGS_S3_PREFIX || undefined;
+  const region = env.RECORDINGS_S3_REGION || env.AWS_REGION || undefined;
+  return new AudioArtifactStorage({ bucket, prefix, region, client });
+}
+async function uploadAudioAtCreation(recordingId, audioPath, storage = resolveAudioArtifactStorage()) {
+  if (!audioPath)
+    return null;
+  if (!storage.usesS3)
+    return null;
+  try {
+    const uploaded = await storage.uploadAudio(recordingId, audioPath);
+    if (!uploaded)
+      return null;
+    console.warn(`recordings: uploaded audio for ${recordingId} to ${uploaded.objectKey}`);
+    return uploaded;
+  } catch (error2) {
+    console.warn(`recordings: audio upload failed for ${recordingId} (${String(error2 instanceof Error ? error2.message : error2)}); keeping local audio_path only`);
+    return null;
   }
-  if (!keyHit) {
-    return {
-      transport: "sqlite",
-      requested,
-      modeSource,
-      baseUrl: null,
-      apiKeyPresent: false,
-      misconfigured: true,
-      warning: `${modeSource}=http but no API key is set (${keys.apiKeyKeys[0]}). Refusing to route to the API.`
-    };
+}
+function assertSha256(value) {
+  if (!SHA256_HEX.test(value)) {
+    throw new Error("audio digest must be a lowercase hex sha-256; refusing to build a storage key from it");
   }
-  const rawUrl = urlHit.value;
-  let baseUrl;
+}
+function sha256Hex(bytes) {
+  const hash = createHash2("sha256");
+  hash.update(bytes);
+  return hash.digest("hex");
+}
+async function readFileBytes(path) {
   try {
-    baseUrl = toV1BaseUrl(rawUrl);
-  } catch (error2) {
-    const message = error2 instanceof Error ? error2.message : String(error2);
-    return { transport: "sqlite", requested, modeSource, baseUrl: null, apiKeyPresent: true, misconfigured: true, warning: `Invalid API URL: ${message}.` };
+    return new Uint8Array(await readFile(path));
+  } catch {
+    return null;
   }
-  return { transport: "http", requested, modeSource, baseUrl, apiKeyPresent: true, misconfigured: false, warning: null };
 }
-function resolveStoreClient(name, env = process.env) {
-  const resolution = resolveTransport(name, env);
-  if (resolution.misconfigured) {
-    const wired2 = createClientTransport(name, env);
-    if (wired2.transport === "http") {
-      return {
-        transport: "http",
-        client: createHasnaStorageClient(name, wired2.client),
-        resolution: {
-          transport: "http",
-          requested: "http",
-          modeSource: resolution.modeSource === "default" ? "auto:api-url+seam-credential" : resolution.modeSource,
-          baseUrl: wired2.resolution.baseUrl,
-          apiKeyPresent: true,
-          misconfigured: false,
-          warning: null
-        }
-      };
-    }
-    throw new Error(resolution.warning ?? `Client for '${name}' is misconfigured for the /v1 API.`);
+function extensionOf(path) {
+  const extension = extname(path).replace(/^\./, "").toLowerCase();
+  return extension || "bin";
+}
+async function bodyToBytes(body) {
+  if (!body)
+    return new Uint8Array(0);
+  if (body instanceof Uint8Array)
+    return body;
+  if (typeof body.transformToByteArray === "function") {
+    return new Uint8Array(await body.transformToByteArray());
   }
-  if (resolution.transport === "sqlite" || !resolution.baseUrl) {
-    return { transport: "sqlite", client: null, resolution };
+  if (typeof body.getReader === "function") {
+    const reader = body.getReader();
+    const chunks2 = [];
+    for (;; ) {
+      const { value, done } = await reader.read();
+      if (done)
+        break;
+      if (value)
+        chunks2.push(value);
+    }
+    return concat(chunks2);
   }
-  const wired = createClientTransport(name, env);
-  if (wired.transport !== "http") {
-    throw new Error(`Client for '${name}' resolved to the /v1 API without an API key.`);
+  const chunks = [];
+  for await (const chunk of body) {
+    chunks.push(typeof chunk === "string" ? new TextEncoder().encode(chunk) : chunk);
   }
-  return { transport: "http", client: createHasnaStorageClient(name, wired.client), resolution };
+  return concat(chunks);
 }
-var RETRY_STATUSES, IDEMPOTENT;
-var init_client = __esm(() => {
-  RETRY_STATUSES = new Set([408, 425, 429, 500, 502, 503, 504]);
-  IDEMPOTENT = new Set(["GET", "HEAD", "PUT", "DELETE", "OPTIONS"]);
+function concat(chunks) {
+  const total = chunks.reduce((sum, chunk) => sum + chunk.byteLength, 0);
+  const merged = new Uint8Array(new ArrayBuffer(total));
+  let offset = 0;
+  for (const chunk of chunks) {
+    merged.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return merged;
+}
+var SHA256_HEX, DEFAULT_S3_PREFIX = "recordings", AUDIO_CONTENT_TYPES;
+var init_audio_artifact_storage = __esm(() => {
+  SHA256_HEX = /^[0-9a-f]{64}$/;
+  AUDIO_CONTENT_TYPES = {
+    wav: "audio/wav",
+    mp3: "audio/mpeg",
+    m4a: "audio/mp4",
+    aac: "audio/aac",
+    webm: "audio/webm",
+    ogg: "audio/ogg",
+    flac: "audio/flac"
+  };
 });
 
 // src/store.ts
-import { createHash as createHash2, randomUUID as randomUUID2 } from "crypto";
+import { createHash as createHash3, randomUUID as randomUUID2 } from "crypto";
 function listQuery(filter) {
   if (!filter)
     return {};
@@ -7111,7 +7414,7 @@ function apiStore(client) {
   };
 }
 function recordingPageFingerprint(items) {
-  const hash = createHash2("sha256");
+  const hash = createHash3("sha256");
   const ids = items.map((item) => String(item.id ?? "")).sort();
   for (const id of ids) {
     hash.update(String(id.length));
@@ -7146,16 +7449,19 @@ async function countStoreRecordings(store, filter) {
   }
   throw new Error(`Legacy Store exceeded ${maxPageRequests} pages while counting recordings`);
 }
-function getStore(env = process.env) {
-  if (env === process.env && cached)
+function localArtifactStorageFor() {
+  return localArtifactStorageOverride ?? resolveAudioArtifactStorage();
+}
+function getStore(env = process.env, options = {}) {
+  if (env === process.env && cached && options.credentials === undefined)
     return cached;
-  const resolved = resolveStoreClient(APP, env);
-  const store = resolved.transport === "http" ? apiStore(resolved.client) : localStore;
-  if (env === process.env)
+  const client = resolveRecordingsCloudClient(env, options);
+  const store = client ? apiStore(client) : localStore;
+  if (env === process.env && options.credentials === undefined)
     cached = store;
   return store;
 }
-var APP = "recordings", localStore, cached = null;
+var localStore, cached = null, localArtifactStorageOverride;
 var init_store = __esm(() => {
   init_recordings();
   init_agents();
@@ -7164,11 +7470,20 @@ var init_store = __esm(() => {
   init_client();
   init_recording_create_identity();
   init_install_maintenance();
+  init_audio_artifact_storage();
   localStore = {
     mode: "sqlite",
     baseUrl: null,
     async createRecording(input, idempotencyKey) {
-      return withLocalStoreReaderLease(() => createRecording2(input, undefined, idempotencyKey));
+      return withLocalStoreReaderLease(async () => {
+        const recording = createRecording2(input, undefined, idempotencyKey);
+        if (!recording.audio_path)
+          return recording;
+        const uploaded = await uploadAudioAtCreation(recording.id, recording.audio_path, localArtifactStorageFor());
+        if (!uploaded)
+          return recording;
+        return updateRecordingAudio(recording.id, uploaded.objectKey, uploaded.sha256, uploaded.bytes) ?? recording;
+      });
     },
     async getRecording(id) {
       return withLocalStoreReaderLease(() => getRecording2(id));
@@ -7240,7 +7555,7 @@ import OpenAI from "openai";
 import { createReadStream } from "fs";
 function getClient(config) {
   if (!config.openai_api_key) {
-    throw new TranscriptionError("OpenAI API key not configured. Set OPENAI_API_KEY env var or add to ~/.secrets");
+    throw new TranscriptionError("OpenAI API key not configured. Set OPENAI_API_KEY env var (e.g. " + "'secrets exec <key> --as OPENAI_API_KEY -- recordings \u2026')");
   }
   if (_client && _clientApiKey === config.openai_api_key)
     return _client;
@@ -8153,8 +8468,9 @@ var init_mcp = __esm(async () => {
   init_enhancer();
   init_version();
   init_machine();
+  init_local_opt_in();
+  init_client();
   config = loadConfig();
-  ensureDataDir(config);
   if (false) {}
 });
 
@@ -8172,13 +8488,12 @@ function jsonResponse(data, status = 200, headers) {
   });
 }
 function resolveClientIp(req, server) {
-  const trustProxy = process.env["RECORDINGS_TRUST_PROXY"] === "1" || process.env["RECORDINGS_TRUST_PROXY"] === "true";
-  if (trustProxy) {
-    const forwarded = req.headers.get("x-forwarded-for")?.split(",")[0]?.trim() || req.headers.get("x-real-ip")?.trim();
-    if (forwarded)
-      return forwarded;
-  }
-  return server.requestIP(req)?.address || "unknown";
+  return resolveRequestClientIp({
+    headers: req.headers,
+    socketAddress: server.requestIP(req)?.address,
+    trustProxy: resolveTrustProxy(),
+    trustedProxies: trustedProxiesFromEnv()
+  }) ?? "unknown";
 }
 function checkRateLimit(ip) {
   const now = Date.now();
@@ -8297,6 +8612,7 @@ var init_serve = __esm(() => {
   init_version();
   init_v1();
   init_openapi();
+  init_client_ip();
   SECURITY_HEADERS = {
     "X-Content-Type-Options": "nosniff",
     "X-Frame-Options": "DENY",
@@ -8345,32 +8661,19 @@ Commands:
   migrate         Apply the PostgreSQL schema, then exit. Idempotent.
 
 Environment:
-  HASNA_RECORDINGS_DATABASE_URL     PostgreSQL DSN (present -> postgresql backend, else sqlite)
-  HASNA_RECORDINGS_API_SIGNING_KEY  HMAC signing secret for API-key auth`);
+  HASNA_RECORDINGS_DATABASE_URL            PostgreSQL DSN (present -> postgresql backend, else sqlite)
+  HASNA_RECORDINGS_MIGRATE_DATABASE_URL    Optional MIGRATION-role DSN for migrate (two-role deploy;
+                                           falls back to the runtime DSN when unset)
+  HASNA_RECORDINGS_API_SIGNING_KEY         HMAC signing secret for API-key auth`);
 }
 async function runMigrate() {
-  const {
-    closeCloud: closeCloud2,
-    getCloudPg: getCloudPg2,
-    migrateCloudSchema: migrateCloudSchema2,
-    pingCloudConnectivity: pingCloudConnectivity3,
-    resolveDatabaseUrl: resolveDatabaseUrl2
-  } = await Promise.resolve().then(() => (init_cloud(), exports_cloud));
-  const { assertCloudSchemaContract: assertCloudSchemaContract2 } = await Promise.resolve().then(() => (init_cloud_readiness(), exports_cloud_readiness));
-  const { runCloudMigration: runCloudMigration2 } = await Promise.resolve().then(() => (init_migrate_command(), exports_migrate_command));
-  if (!resolveDatabaseUrl2()) {
-    console.error("migrate: no database URL (HASNA_RECORDINGS_DATABASE_URL / RECORDINGS_DATABASE_URL / DATABASE_URL)");
+  const { closeCloud: closeCloud2, resolveMigrationDatabaseUrl: resolveMigrationDatabaseUrl2, runRecordedMigration: runRecordedMigration2 } = await Promise.resolve().then(() => (init_cloud(), exports_cloud));
+  if (!resolveMigrationDatabaseUrl2()) {
+    console.error("migrate: no database URL (HASNA_RECORDINGS_MIGRATE_DATABASE_URL / RECORDINGS_MIGRATE_DATABASE_URL / HASNA_RECORDINGS_DATABASE_URL / RECORDINGS_DATABASE_URL / DATABASE_URL)");
     process.exit(2);
   }
   console.log("migrate: connecting\u2026");
-  await runCloudMigration2({
-    pingConnectivity: pingCloudConnectivity3,
-    applyMigrations: async () => {
-      console.log("migrate: applying schema (recordings tables + api_keys)\u2026");
-      await migrateCloudSchema2();
-    },
-    validateContract: () => assertCloudSchemaContract2(getCloudPg2())
-  });
+  await runRecordedMigration2();
   console.log("migrate: done");
   await closeCloud2();
   process.exit(0);