S3 User Files

/**
 * Shared utilities for s3-user-files skill.
 */
const BUCKET = process.env.S3_USER_FILES_BUCKET;
const REGION = process.env.AWS_REGION;
if (!REGION) {
  console.error("Error: AWS_REGION environment variable is not set.");
  process.exit(1);
}

/**
 * Sanitize a string for safe use as an S3 key component.
 * Removes path traversal, restricts to safe characters, limits length.
 */
function sanitize(str) {
  // Iteratively remove ".." until stable to prevent "...."->"..".
  let result = str;
  while (result.includes("..")) {
    result = result.replace(/\.\./g, "");
  }
  result = result.replace(/[^a-zA-Z0-9_\-.]/g, "_").slice(0, 256);
  // Reject leading/trailing dots (hidden files, path traversal)
  if (result.startsWith(".") || result.endsWith(".")) {
    throw new Error(
      `Invalid filename: "${result}" — leading/trailing dots not allowed`,
    );
  }
  return result;
}

/**
 * Build the S3 key from userId and optional filename.
 * Returns "sanitized_userId/" or "sanitized_userId/sanitized_filename".
 */
function buildKey(userId, filename) {
  const prefix = sanitize(userId);
  if (!filename) return `${prefix}/`;
  return `${prefix}/${sanitize(filename)}`;
}

/**
 * Validate that userId is present, not the default-user fallback,
 * and matches the expected channel_identifier namespace pattern.
 * Exits the process with an error message if validation fails.
 */
function validateUserId(userId) {
  if (!userId) {
    console.error("Error: user_id argument is required.");
    process.exit(1);
  }
  if (userId === "default-user" || userId === "default_user") {
    console.error(
      "Error: Cannot operate on files for default-user. User identity was not resolved.",
    );
    process.exit(1);
  }
  // Namespace must match channel_identifier pattern (e.g., telegram_123456789, slack_U0AGD41CBGS).
  // This prevents prompt injection attacks where a user tricks the AI into using
  // an arbitrary namespace to access another user's files.
  const VALID_NAMESPACE =
    /^(telegram|slack|discord|whatsapp)_[a-zA-Z0-9_-]{1,64}$/;
  if (!VALID_NAMESPACE.test(userId)) {
    console.error(
      `Error: Invalid user_id "${userId}". Must match channel_identifier format (e.g., telegram_123456, slack_username).`,
    );
    process.exit(1);
  }
}

/**
 * Validate that the S3_USER_FILES_BUCKET env var is set.
 * Exits the process with an error message if missing.
 */
function validateBucket() {
  if (!BUCKET) {
    console.error("Error: S3_USER_FILES_BUCKET environment variable not set.");
    process.exit(1);
  }
}

/**
 * Convert an S3 response body stream to a UTF-8 string.
 */
async function streamToString(stream) {
  const chunks = [];
  for await (const chunk of stream) {
    chunks.push(chunk);
  }
  return Buffer.concat(chunks).toString("utf-8");
}

module.exports = {
  BUCKET,
  REGION,
  sanitize,
  buildKey,
  validateUserId,
  validateBucket,
  streamToString,
};

/**
 * Tests for s3-user-files common utilities.
 * Run: node --test common.test.js
 */
const { describe, it } = require("node:test");
const assert = require("node:assert/strict");
const { sanitize, buildKey, validateUserId } = require("./common");

describe("sanitize", () => {
  it("passes through simple alphanumeric strings", () => {
    assert.equal(sanitize("telegram_12345"), "telegram_12345");
  });

  it("replaces colons with underscores", () => {
    assert.equal(sanitize("telegram:12345"), "telegram_12345");
  });

  it("removes path traversal sequences", () => {
    // ".." removed, remaining "/" become "_"
    assert.equal(sanitize("../../../etc/passwd"), "___etc_passwd");
  });

  it("replaces slashes with underscores", () => {
    assert.equal(sanitize("foo/bar/baz"), "foo_bar_baz");
  });

  it("allows hyphens and dots", () => {
    assert.equal(sanitize("my-file.md"), "my-file.md");
  });

  it("truncates to 256 characters", () => {
    const long = "a".repeat(300);
    assert.equal(sanitize(long).length, 256);
  });

  it("handles empty string", () => {
    assert.equal(sanitize(""), "");
  });

  it("replaces spaces with underscores", () => {
    assert.equal(sanitize("John Doe"), "John_Doe");
  });

  it("handles Slack user IDs", () => {
    assert.equal(sanitize("slack:U0123456789"), "slack_U0123456789");
  });

  it("iteratively removes nested dot-dot sequences", () => {
    // "......" (6 dots) -> first pass removes 3 pairs -> ""
    assert.equal(sanitize("......"), "");
    // "....." (5 dots) -> first pass removes 2 pairs -> "." -> rejected (leading dot)
    assert.throws(() => sanitize("....."), /leading\/trailing dots not allowed/);
  });

  it("rejects leading dots in filenames", () => {
    assert.throws(() => sanitize(".hidden"), /leading\/trailing dots not allowed/);
    assert.throws(() => sanitize(".env"), /leading\/trailing dots not allowed/);
  });

  it("rejects trailing dots in filenames", () => {
    assert.throws(() => sanitize("file."), /leading\/trailing dots not allowed/);
  });
});

describe("buildKey", () => {
  it("builds key with userId and filename", () => {
    assert.equal(
      buildKey("telegram_12345", "IDENTITY.md"),
      "telegram_12345/IDENTITY.md",
    );
  });

  it("sanitizes userId in key", () => {
    assert.equal(
      buildKey("telegram:12345", "notes.md"),
      "telegram_12345/notes.md",
    );
  });

  it("returns prefix with trailing slash when no filename", () => {
    assert.equal(buildKey("telegram_12345"), "telegram_12345/");
  });

  it("sanitizes both userId and filename", () => {
    assert.equal(
      buildKey("../admin", "../../etc/passwd"),
      "_admin/__etc_passwd",
    );
  });
});

describe("validateUserId", () => {
  it("accepts valid telegram namespace", () => {
    assert.doesNotThrow(() => validateUserId("telegram_123456789"));
  });

  it("accepts valid slack namespace", () => {
    assert.doesNotThrow(() => validateUserId("slack_sen-outlook"));
  });

  it("accepts valid discord namespace", () => {
    assert.doesNotThrow(() => validateUserId("discord_123456789012345678"));
  });

  it("accepts valid slack namespace with uppercase ID", () => {
    assert.doesNotThrow(() => validateUserId("slack_U0AGD41CBGS"));
  });

  it("rejects empty userId", () => {
    // validateUserId calls process.exit, so we mock it
    const originalExit = process.exit;
    let exitCode = null;
    process.exit = (code) => {
      exitCode = code;
      throw new Error("process.exit called");
    };
    try {
      assert.throws(() => validateUserId(""), /process\.exit/);
      assert.equal(exitCode, 1);
    } finally {
      process.exit = originalExit;
    }
  });

  it("rejects default-user", () => {
    const originalExit = process.exit;
    let exitCode = null;
    process.exit = (code) => {
      exitCode = code;
      throw new Error("process.exit called");
    };
    try {
      assert.throws(() => validateUserId("default-user"), /process\.exit/);
      assert.equal(exitCode, 1);
    } finally {
      process.exit = originalExit;
    }
  });

  it("rejects arbitrary namespace without channel prefix", () => {
    const originalExit = process.exit;
    let exitCode = null;
    process.exit = (code) => {
      exitCode = code;
      throw new Error("process.exit called");
    };
    try {
      assert.throws(() => validateUserId("my-custom-id"), /process\.exit/);
      assert.equal(exitCode, 1);
    } finally {
      process.exit = originalExit;
    }
  });

  it("rejects path traversal attempts", () => {
    const originalExit = process.exit;
    let exitCode = null;
    process.exit = (code) => {
      exitCode = code;
      throw new Error("process.exit called");
    };
    try {
      assert.throws(() => validateUserId("../other_user"), /process\.exit/);
      assert.equal(exitCode, 1);
    } finally {
      process.exit = originalExit;
    }
  });
});

#!/usr/bin/env node
/**
 * delete_user_file — Delete a file from a user's S3-namespaced storage.
 * Usage: node delete.js <user_id> <filename>
 */
const { S3Client, DeleteObjectCommand } = require("@aws-sdk/client-s3");
const { BUCKET, REGION, buildKey, validateUserId, validateBucket } = require("./common");

async function main() {
  const userId = process.argv[2];
  const filename = process.argv[3];

  validateUserId(userId);
  validateBucket();

  if (!filename) {
    console.error("Error: filename argument is required.");
    process.exit(1);
  }

  const key = buildKey(userId, filename);
  const client = new S3Client({ region: REGION });

  await client.send(new DeleteObjectCommand({
    Bucket: BUCKET,
    Key: key,
  }));

  console.log(`File deleted: ${key}`);
}

main().catch((err) => {
  console.error(`Error: ${err.message}`);
  process.exit(1);
});

#!/usr/bin/env node
/**
 * list_user_files — List files in a user's S3-namespaced storage.
 * Usage: node list.js <user_id>
 */
const { S3Client, ListObjectsV2Command } = require("@aws-sdk/client-s3");
const {
  BUCKET,
  REGION,
  buildKey,
  validateUserId,
  validateBucket,
} = require("./common");

async function main() {
  const userId = process.argv[2];

  validateUserId(userId);
  validateBucket();

  const prefix = buildKey(userId);
  const client = new S3Client({ region: REGION });

  const response = await client.send(
    new ListObjectsV2Command({
      Bucket: BUCKET,
      Prefix: prefix,
      MaxKeys: 1000,
    }),
  );

  const files = (response.Contents || []).map((obj) => {
    const name = obj.Key.replace(prefix, "");
    const sizeKB = (obj.Size / 1024).toFixed(1);
    const modified = obj.LastModified.toISOString().split("T")[0];
    return `- ${name} (${sizeKB} KB, ${modified})`;
  });

  if (files.length === 0) {
    console.log("No files stored for this user.");
  } else {
    let output = `Files for ${userId}:\n${files.join("\n")}`;
    if (response.IsTruncated) {
      output += `\n(truncated — more than ${files.length} files exist)`;
    }
    console.log(output);
  }
}

main().catch((err) => {
  console.error(`Error: ${err.message}`);
  process.exit(1);
});

{
  "name": "s3-user-files",
  "version": "1.0.0",
  "description": "Per-user persistent file storage backed by AWS S3",
  "private": true,
  "dependencies": {
    "@aws-sdk/client-s3": "^3.0.0",
    "@aws-sdk/s3-request-presigner": "^3.0.0"
  }
}

#!/usr/bin/env node
/**
 * presign_user_file — Generate a SigV4 presigned URL for a user's S3 file.
 * Usage: node presign.js <user_id> <filename> [expires_in_seconds]
 *
 * AWS SDK v3 uses SigV4 by default, which is required for SSE-KMS encrypted buckets.
 */
const { S3Client, GetObjectCommand } = require("@aws-sdk/client-s3");
const { getSignedUrl } = require("@aws-sdk/s3-request-presigner");
const { BUCKET, REGION, buildKey, validateUserId, validateBucket } = require("./common");

async function main() {
  const userId = process.argv[2];
  const filename = process.argv[3];
  const expiresIn = parseInt(process.argv[4], 10) || 3600;

  validateUserId(userId);
  validateBucket();

  if (!filename) {
    console.error("Error: filename argument is required.");
    process.exit(1);
  }

  const MAX_EXPIRES = 7 * 24 * 3600; // 7 days (S3 max for IAM user; STS creds may be shorter)
  if (expiresIn < 1 || expiresIn > MAX_EXPIRES) {
    console.error(`Error: expires_in must be between 1 and ${MAX_EXPIRES} seconds.`);
    process.exit(1);
  }

  const key = buildKey(userId, filename);
  const client = new S3Client({ region: REGION });

  const url = await getSignedUrl(
    client,
    new GetObjectCommand({ Bucket: BUCKET, Key: key }),
    { expiresIn },
  );

  console.log(url);
}

main().catch((err) => {
  console.error(`Error: ${err.message}`);
  process.exit(1);
});

#!/usr/bin/env node
/**
 * read_user_file — Read a file from a user's S3-namespaced storage.
 * Usage: node read.js <user_id> <filename>
 */
const { S3Client, GetObjectCommand } = require("@aws-sdk/client-s3");
const { BUCKET, REGION, buildKey, validateUserId, validateBucket, streamToString } = require("./common");

async function main() {
  const userId = process.argv[2];
  const filename = process.argv[3];

  validateUserId(userId);
  validateBucket();

  if (!filename) {
    console.error("Error: filename argument is required.");
    process.exit(1);
  }

  const key = buildKey(userId, filename);
  const client = new S3Client({ region: REGION });

  try {
    const response = await client.send(new GetObjectCommand({
      Bucket: BUCKET,
      Key: key,
    }));
    const content = await streamToString(response.Body);
    console.log(content);
  } catch (err) {
    if (err.name === "NoSuchKey" || err.$metadata?.httpStatusCode === 404) {
      console.log(`File not found: ${key}`);
    } else {
      throw err;
    }
  }
}

main().catch((err) => {
  console.error(`Error: ${err.message}`);
  process.exit(1);
});

#!/usr/bin/env node
/**
 * write_user_file — Write content to a user's S3-namespaced file.
 * Usage: node write.js <user_id> <filename> <content...>
 */
const { S3Client, PutObjectCommand } = require("@aws-sdk/client-s3");
const {
  BUCKET,
  REGION,
  buildKey,
  validateUserId,
  validateBucket,
} = require("./common");

/**
 * Read all data from stdin as a string.
 */
function readStdin() {
  return new Promise((resolve, reject) => {
    const chunks = [];
    process.stdin.setEncoding("utf-8");
    process.stdin.on("data", (chunk) => chunks.push(chunk));
    process.stdin.on("end", () => resolve(chunks.join("")));
    process.stdin.on("error", reject);
  });
}

async function main() {
  const userId = process.argv[2];
  const filename = process.argv[3];
  // Read content from argv or stdin (--stdin flag). Stdin avoids OS ARG_MAX limits.
  const argContent = process.argv.slice(4).join(" ");
  const content = argContent === "--stdin" ? await readStdin() : argContent;

  validateUserId(userId);
  validateBucket();

  if (!filename) {
    console.error("Error: filename argument is required.");
    process.exit(1);
  }
  if (!content) {
    console.error("Error: content argument is required.");
    process.exit(1);
  }

  const MAX_CONTENT_BYTES = 1 * 1024 * 1024; // 1 MB
  if (Buffer.byteLength(content, "utf-8") > MAX_CONTENT_BYTES) {
    console.error("Error: content exceeds maximum allowed size (1 MB).");
    process.exit(1);
  }

  const key = buildKey(userId, filename);
  const client = new S3Client({ region: REGION });

  await client.send(
    new PutObjectCommand({
      Bucket: BUCKET,
      Key: key,
      Body: content,
      ContentType: "text/plain; charset=utf-8",
    }),
  );

  console.log(`File written: ${key} (${content.length} bytes)`);
}

main().catch((err) => {
  console.error(`Error: ${err.message}`);
  process.exit(1);
});