Files that uploaded fine and were shared into no channel

"""Find the files your app uploaded and gave to nobody.

Read only. One paginated GET against files.list and no writes at all: sharing a
file, revoking a link and deleting a file all need files:write, and all three
are printed here rather than performed. A bot token with files:read is enough.

The question is not whether the upload worked - it did, or the file would not be
in the list. The question is whether anything was passed to
files.completeUploadExternal to say where the file should go, and the answer
lives in the share fields of every file the app owns.
"""
import argparse
import logging
import os
import sys

import requests

logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s")
log = logging.getLogger("slack_unshared_files")

API = "https://slack.com/api/"

# The two verdicts that mean nobody in the workspace can reach the file. Kept as
# a constant because the rate and the report have to agree on what counts.
UNREACHABLE = ("unshared", "link-only")


def buckets(f):
    """Where is this file shared? Read from both representations. Pure.

    Slack records the same fact twice. The modern `shares` object carries a
    `public` map and a `private` map, each keyed by conversation id. The older
    `channels`, `groups` and `ims` arrays carry it split by conversation type:
    public channels, private channels, direct messages.

    Reading only one of them is the mistake this function exists to prevent.
    `channels` is empty for a file shared into a private channel, so a check
    built on it alone reports every correctly-shared private file as an orphan,
    produces a wall of false findings on its first run, and gets switched off.

    Returns {"public": [...], "private": [...], "dm": [...]}, sorted.
    """
    f = f or {}
    out = {"public": set(), "private": set(), "dm": set()}
    shares = f.get("shares")
    if isinstance(shares, dict):
        for name in ("public", "private"):
            group = shares.get(name)
            if isinstance(group, dict):
                out[name].update(str(k) for k in group if k)
    for name, legacy in (("public", "channels"), ("private", "groups"), ("dm", "ims")):
        for cid in f.get(legacy) or []:
            if cid:
                out[name].add(str(cid))
    return {k: sorted(v) for k, v in out.items()}


def share_targets(f):
    """Every conversation this file is shared into, deduplicated. Pure."""
    got = buckets(f)
    return sorted(set(got["public"]) | set(got["private"]) | set(got["dm"]))


def share_state(f):
    """Classify one file by the audience it actually has. Pure.

    Returns (state, detail). Four of the six states look like zero from a
    distance and only two of them are findings:

      unshared      no conversation of any kind. The file exists and nobody can
                    find it. This is the note.
      link-only     no conversation, and public_url_shared is true. Unreachable
                    inside Slack and readable by anyone on the internet, which
                    is worse and is a different repair.
      dm-only       shared, into direct messages only. A narrow audience is not
                    an absent one.
      private-only  shared, into private channels only. Also not a fault.
      shared        reachable from at least one channel.
      external      hosted somewhere else; Slack holds a link, not the bytes,
                    and the sharing question belongs to that other system.
    """
    f = f or {}
    if f.get("is_external"):
        return ("external", "hosted outside Slack, so Slack holds a reference rather "
                            "than the bytes and its share fields describe nothing")
    got = buckets(f)
    targets = sorted(set(got["public"]) | set(got["private"]) | set(got["dm"]))
    if not targets:
        if f.get("public_url_shared"):
            return ("link-only", "shared into no conversation and readable by anyone "
                                 "holding permalink_public. Invisible inside Slack and "
                                 "visible outside it, which is the worse half of both")
        return ("unshared", "no channel, no private channel and no DM. The upload "
                            "finished, the file exists, and completeUploadExternal was "
                            "called without channel_id")
    if not got["public"] and not got["private"]:
        return ("dm-only", "shared into %d direct message conversation(s) and no "
                           "channel. Only the people in those conversations can find "
                           "it" % len(got["dm"]))
    if not got["public"]:
        return ("private-only", "shared into %d private channel(s). That is a real "
                                "share, and a file in a private channel has an empty "
                                "channels array by design" % len(got["private"]))
    return ("shared", "shared into %d conversation(s)" % len(targets))


def orphan_rate(states):
    """What proportion of this app's own output has no audience? Pure.

    Returns (unreachable, total, percent). External files are excluded from the
    denominator: their sharing state is another system's, and leaving them in
    would move the number for a reason that has nothing to do with the bug.
    """
    counted = [s for s in states if s != "external"]
    total = len(counted)
    bad = sum(1 for s in counted if s in UNREACHABLE)
    return (bad, total, 0.0 if not total else round(100.0 * bad / total, 1))


def page_files(session, user, page_size, max_pages):
    """Page files.list. A read, and the only network call this script makes."""
    out, page, pages = [], 1, 1
    while page <= min(pages, max_pages):
        params = {"count": str(page_size), "types": "all", "page": str(page)}
        if user:
            params["user"] = user
        body = session.get(API + "files.list", params=params, timeout=30).json()
        if body.get("ok") is not True:
            log.error("files.list unavailable    %s", body.get("error"))
            return out, pages
        out.extend(body.get("files") or [])
        pages = int((body.get("paging") or {}).get("pages") or 1)
        page += 1
    return out, pages


def main():
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("--token-env", default="SLACK_BOT_TOKEN",
                    help="environment variable holding the bot token")
    ap.add_argument("--user", default="",
                    help="owner to audit; defaults to this token's own user id")
    ap.add_argument("--all-users", action="store_true",
                    help="audit every file in the workspace rather than the app's own")
    ap.add_argument("--page-size", type=int, default=200)
    ap.add_argument("--max-pages", type=int, default=25)
    ap.add_argument("--show", default="unshared,link-only",
                    help="comma separated states to print in full")
    args = ap.parse_args()

    token = os.environ.get(args.token_env)
    if not token:
        log.error("set %s to a bot token with files:read", args.token_env)
        return 2

    s = requests.Session()
    s.headers.update({"Authorization": "Bearer " + token})
    who_resp = s.get(API + "auth.test", timeout=30)
    who = who_resp.json()
    if who.get("ok") is not True:
        log.error("auth.test  unavailable    %s", who.get("error"))
        return 2
    log.info("identity   %s (%s) in %s", who.get("user_id"), who.get("user"),
             who.get("team"))

    scopes = who_resp.headers.get("x-oauth-scopes") or ""
    if scopes and "files:read" not in scopes.split(","):
        log.warning("scope      files:read is not granted; files.list will refuse")

    owner = "" if args.all_users else (args.user or who.get("user_id") or "")
    files, pages = page_files(s, owner, args.page_size, args.max_pages)
    log.info("files      %d file(s) owned by %s, over %d page(s)",
             len(files), owner or "anyone", pages)

    wanted = {w.strip() for w in args.show.split(",") if w.strip()}
    states = []
    for f in files:
        state, detail = share_state(f)
        states.append(state)
        name = f.get("name") or f.get("title") or "?"
        line = ("state      %-14s %s %s  %s", state, f.get("id") or "?", name, detail)
        if state in UNREACHABLE:
            log.warning(*line)
        elif state in wanted:
            log.info(*line)

    bad, total, percent = orphan_rate(states)
    if not bad:
        log.info("verdict    clean          every file this app owns is shared somewhere")
        return 0
    log.warning("verdict    %d of %d file(s) owned by this app have no audience in "
                "Slack (%.1f%%)", bad, total, percent)
    log.warning("  repair: pass channel_id (a C id, not a name) to "
                "files.completeUploadExternal, with initial_comment beside it")
    log.warning("  repair: to share a file that already exists, post its permalink "
                "into the channel with the bot; Slack expands it and grants access")
    if "link-only" in states:
        log.warning("  repair: the link-only rows are also readable without a Slack "
                    "login; revoke those with files.revokePublicURL first")
    return 1


if __name__ == "__main__":
    sys.exit(main())

/**
 * Find the files your app uploaded and gave to nobody.
 *
 * Read only. One paginated GET against files.list and no writes at all: sharing
 * a file, revoking a link and deleting a file all need files:write, and all
 * three are printed here rather than performed. A bot token with files:read is
 * enough.
 *
 * The question is not whether the upload worked - it did, or the file would not
 * be in the list. The question is whether anything was passed to
 * files.completeUploadExternal to say where the file should go.
 */

const API = 'https://slack.com/api/';

// The two verdicts that mean nobody in the workspace can reach the file.
export const UNREACHABLE = ['unshared', 'link-only'];

/**
 * Where is this file shared? Read from both representations. Pure.
 *
 * Slack records the same fact twice: the modern `shares` object with `public`
 * and `private` maps keyed by conversation id, and the older `channels`,
 * `groups` and `ims` arrays split by conversation type. Reading only `channels`
 * reports every correctly-shared private file as an orphan, which is how a
 * check like this one gets switched off in its first week.
 */
export function buckets(f) {
  const file = f ?? {};
  const out = { public: new Set(), private: new Set(), dm: new Set() };
  const shares = file.shares;
  if (shares && typeof shares === 'object' && !Array.isArray(shares)) {
    for (const name of ['public', 'private']) {
      const group = shares[name];
      if (group && typeof group === 'object' && !Array.isArray(group)) {
        for (const key of Object.keys(group)) if (key) out[name].add(String(key));
      }
    }
  }
  for (const [name, legacy] of [['public', 'channels'], ['private', 'groups'],
    ['dm', 'ims']]) {
    for (const cid of file[legacy] ?? []) if (cid) out[name].add(String(cid));
  }
  return {
    public: [...out.public].sort(),
    private: [...out.private].sort(),
    dm: [...out.dm].sort(),
  };
}

/** Every conversation this file is shared into, deduplicated. Pure. */
export function shareTargets(f) {
  const got = buckets(f);
  return [...new Set([...got.public, ...got.private, ...got.dm])].sort();
}

/**
 * Classify one file by the audience it actually has. Pure.
 * Returns [state, detail]; only unshared and link-only are findings.
 */
export function shareState(f) {
  const file = f ?? {};
  if (file.is_external) {
    return ['external', 'hosted outside Slack, so Slack holds a reference rather than '
      + 'the bytes and its share fields describe nothing'];
  }
  const got = buckets(file);
  const targets = [...new Set([...got.public, ...got.private, ...got.dm])];
  if (!targets.length) {
    if (file.public_url_shared) {
      return ['link-only', 'shared into no conversation and readable by anyone holding '
        + 'permalink_public. Invisible inside Slack and visible outside it, which is '
        + 'the worse half of both'];
    }
    return ['unshared', 'no channel, no private channel and no DM. The upload finished, '
      + 'the file exists, and completeUploadExternal was called without channel_id'];
  }
  if (!got.public.length && !got.private.length) {
    return ['dm-only', `shared into ${got.dm.length} direct message conversation(s) and `
      + 'no channel. Only the people in those conversations can find it'];
  }
  if (!got.public.length) {
    return ['private-only', `shared into ${got.private.length} private channel(s). That `
      + 'is a real share, and a file in a private channel has an empty channels array '
      + 'by design'];
  }
  return ['shared', `shared into ${targets.length} conversation(s)`];
}

/**
 * What proportion of this app's own output has no audience? Pure.
 * Returns [unreachable, total, percent]. External files leave the denominator.
 */
export function orphanRate(states) {
  const counted = (states ?? []).filter((s) => s !== 'external');
  const total = counted.length;
  const bad = counted.filter((s) => UNREACHABLE.includes(s)).length;
  const percent = total ? Math.round((1000 * bad) / total) / 10 : 0;
  return [bad, total, percent];
}

function arg(args, name, fallback = null) {
  const i = args.indexOf(name);
  return i === -1 ? fallback : args[i + 1];
}

async function pageFiles(headers, user, pageSize, maxPages) {
  const files = [];
  let page = 1;
  let pages = 1;
  while (page <= Math.min(pages, maxPages)) {
    const params = new URLSearchParams({
      count: String(pageSize), types: 'all', page: String(page),
    });
    if (user) params.set('user', user);
    const body = await (await fetch(`${API}files.list?${params}`, { headers })).json();
    if (body.ok !== true) {
      console.error(`files.list unavailable    ${body.error}`);
      return [files, pages];
    }
    files.push(...(body.files ?? []));
    pages = Number((body.paging ?? {}).pages ?? 1) || 1;
    page += 1;
  }
  return [files, pages];
}

async function main() {
  const args = process.argv.slice(2);
  const tokenEnv = arg(args, '--token-env', 'SLACK_BOT_TOKEN');
  const token = process.env[tokenEnv];
  if (!token) {
    console.error(`set ${tokenEnv} to a bot token with files:read`);
    process.exitCode = 2;
    return;
  }
  const headers = { Authorization: `Bearer ${token}` };
  const whoResp = await fetch(`${API}auth.test`, { headers });
  const who = await whoResp.json();
  if (who.ok !== true) {
    console.error(`auth.test  unavailable    ${who.error}`);
    process.exitCode = 2;
    return;
  }
  console.log(`identity   ${who.user_id} (${who.user}) in ${who.team}`);

  const scopes = whoResp.headers.get('x-oauth-scopes') ?? '';
  if (scopes && !scopes.split(',').includes('files:read')) {
    console.warn('scope      files:read is not granted; files.list will refuse');
  }

  const owner = args.includes('--all-users')
    ? '' : (arg(args, '--user', '') || who.user_id || '');
  const [files, pages] = await pageFiles(headers, owner,
    Number(arg(args, '--page-size', '200')), Number(arg(args, '--max-pages', '25')));
  console.log(`files      ${files.length} file(s) owned by ${owner || 'anyone'}, over `
    + `${pages} page(s)`);

  const wanted = new Set(String(arg(args, '--show', 'unshared,link-only'))
    .split(',').map((w) => w.trim()).filter(Boolean));
  const states = [];
  for (const f of files) {
    const [state, detail] = shareState(f);
    states.push(state);
    const name = f.name ?? f.title ?? '?';
    const line = `state      ${state.padEnd(14)} ${f.id ?? '?'} ${name}  ${detail}`;
    if (UNREACHABLE.includes(state)) console.warn(line);
    else if (wanted.has(state)) console.log(line);
  }

  const [bad, total, percent] = orphanRate(states);
  if (!bad) {
    console.log('verdict    clean          every file this app owns is shared somewhere');
    return;
  }
  console.warn(`verdict    ${bad} of ${total} file(s) owned by this app have no `
    + `audience in Slack (${percent}%)`);
  console.warn('  repair: pass channel_id (a C id, not a name) to '
    + 'files.completeUploadExternal, with initial_comment beside it');
  console.warn('  repair: to share a file that already exists, post its permalink into '
    + 'the channel with the bot; Slack expands it and grants access');
  if (states.includes('link-only')) {
    console.warn('  repair: the link-only rows are also readable without a Slack login; '
      + 'revoke those with files.revokePublicURL first');
  }
  process.exitCode = 1;
}

// Only run when invoked directly, so importing this module in the tests does
// not execute main() and fail the file on a missing token.
if (import.meta.url === `file://${process.argv[1]}`) {
  main().catch((err) => { console.error(err.message); process.exitCode = 2; });
}

from slack_unshared_files import buckets, orphan_rate, share_state, share_targets


def test_the_modern_shares_object_is_read():
    f = {"shares": {"public": {"C111": [{"ts": "1.1"}]}, "private": {}}}
    assert buckets(f)["public"] == ["C111"]
    assert share_targets(f) == ["C111"]


def test_the_legacy_arrays_are_read_too():
    f = {"channels": ["C111"], "groups": ["G222"], "ims": ["D333"]}
    got = buckets(f)
    assert got == {"public": ["C111"], "private": ["G222"], "dm": ["D333"]}


def test_both_representations_of_the_same_share_collapse_to_one_target():
    f = {"shares": {"public": {"C111": []}}, "channels": ["C111"]}
    assert share_targets(f) == ["C111"]


def test_an_empty_file_object_has_no_targets_and_does_not_raise():
    assert share_targets({}) == []
    assert share_targets(None) == []
    assert buckets({"shares": []})["public"] == []


def test_a_file_shared_nowhere_is_the_finding():
    state, detail = share_state({"id": "F1", "shares": {"public": {}, "private": {}}})
    assert state == "unshared"
    assert "channel_id" in detail


def test_a_private_channel_share_is_a_share_and_not_an_orphan():
    state, detail = share_state({"id": "F1", "channels": [], "groups": ["G222"]})
    assert state == "private-only"
    assert "empty channels array" in detail


def test_a_dm_only_share_is_narrow_rather_than_absent():
    assert share_state({"id": "F1", "ims": ["D333"]})[0] == "dm-only"


def test_a_public_url_on_a_file_nobody_can_reach_gets_its_own_verdict():
    state, detail = share_state({"id": "F1", "public_url_shared": True})
    assert state == "link-only"
    assert "permalink_public" in detail


def test_a_public_url_on_a_shared_file_is_not_this_note():
    assert share_state({"id": "F1", "channels": ["C111"],
                        "public_url_shared": True})[0] == "shared"


def test_an_external_file_is_not_judged_by_slack_share_fields():
    assert share_state({"id": "F1", "is_external": True})[0] == "external"


def test_the_rate_is_a_proportion_of_what_the_app_owns():
    bad, total, percent = orphan_rate(["unshared", "unshared", "shared", "shared"])
    assert (bad, total, percent) == (2, 4, 50.0)


def test_link_only_counts_as_unreachable_inside_slack():
    assert orphan_rate(["link-only", "shared"])[0] == 1


def test_external_files_leave_the_denominator_alone():
    assert orphan_rate(["unshared", "shared", "external"]) == (1, 2, 50.0)


def test_narrow_audiences_are_not_counted_as_orphans():
    assert orphan_rate(["dm-only", "private-only", "shared"])[0] == 0


def test_an_empty_run_reports_zero_rather_than_dividing_by_it():
    assert orphan_rate([]) == (0, 0, 0.0)

import { test } from 'node:test';
import assert from 'node:assert/strict';
import {
  buckets, orphanRate, shareState, shareTargets,
} from './slack-unshared-files.mjs';

test('the modern shares object is read', () => {
  const f = { shares: { public: { C111: [{ ts: '1.1' }] }, private: {} } };
  assert.deepEqual(buckets(f).public, ['C111']);
  assert.deepEqual(shareTargets(f), ['C111']);
});

test('the legacy arrays are read too', () => {
  const f = { channels: ['C111'], groups: ['G222'], ims: ['D333'] };
  assert.deepEqual(buckets(f), { public: ['C111'], private: ['G222'], dm: ['D333'] });
});

test('both representations of the same share collapse to one target', () => {
  const f = { shares: { public: { C111: [] } }, channels: ['C111'] };
  assert.deepEqual(shareTargets(f), ['C111']);
});

test('an empty file object has no targets and does not throw', () => {
  assert.deepEqual(shareTargets({}), []);
  assert.deepEqual(shareTargets(null), []);
  assert.deepEqual(buckets({ shares: [] }).public, []);
});

test('a file shared nowhere is the finding', () => {
  const [state, detail] = shareState({ id: 'F1', shares: { public: {}, private: {} } });
  assert.equal(state, 'unshared');
  assert.match(detail, /channel_id/);
});

test('a private channel share is a share and not an orphan', () => {
  const [state, detail] = shareState({ id: 'F1', channels: [], groups: ['G222'] });
  assert.equal(state, 'private-only');
  assert.match(detail, /empty channels array/);
});

test('a dm only share is narrow rather than absent', () => {
  assert.equal(shareState({ id: 'F1', ims: ['D333'] })[0], 'dm-only');
});

test('a public url on a file nobody can reach gets its own verdict', () => {
  const [state, detail] = shareState({ id: 'F1', public_url_shared: true });
  assert.equal(state, 'link-only');
  assert.match(detail, /permalink_public/);
});

test('a public url on a shared file is not this note', () => {
  assert.equal(shareState({ id: 'F1', channels: ['C111'], public_url_shared: true })[0],
    'shared');
});

test('an external file is not judged by Slack share fields', () => {
  assert.equal(shareState({ id: 'F1', is_external: true })[0], 'external');
});

test('the rate is a proportion of what the app owns', () => {
  assert.deepEqual(orphanRate(['unshared', 'unshared', 'shared', 'shared']),
    [2, 4, 50]);
});

test('link only counts as unreachable inside Slack', () => {
  assert.equal(orphanRate(['link-only', 'shared'])[0], 1);
});

test('external files leave the denominator alone', () => {
  assert.deepEqual(orphanRate(['unshared', 'shared', 'external']), [1, 2, 50]);
});

test('narrow audiences are not counted as orphans', () => {
  assert.equal(orphanRate(['dm-only', 'private-only', 'shared'])[0], 0);
});

test('an empty run reports zero rather than dividing by it', () => {
  assert.deepEqual(orphanRate([]), [0, 0, 0]);
});