auditreach-cli 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,233 @@
+<div align="center">
+
+# auditreach
+
+Research Reddit and YouTube from your AI agent using only official APIs, your own keys, and a log that proves exactly what you queried and why it was allowed.
+
+[![CI](https://github.com/RudrenduPaul/auditreach/actions/workflows/ci.yml/badge.svg)](https://github.com/RudrenduPaul/auditreach/actions/workflows/ci.yml)
+[![License: Apache 2.0](https://img.shields.io/github/license/RudrenduPaul/auditreach)](LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](package.json)
+
+</div>
+
+<!-- TODO: record a real terminal demo (asciinema or a short GIF) and embed it here.
+     Capture script: run the two commands under "What it does" below against a real
+     Reddit search-app credential, in a clean terminal, ~15-20s total. Save as
+     docs/demo.gif and replace this comment with:
+     ![auditreach demo: running a Reddit search and verifying the audit log](docs/demo.gif) -->
+
+## Install
+
+There's no published npm package yet -- clone and build directly, verified working end to end:
+
+```sh
+git clone https://github.com/RudrenduPaul/auditreach.git
+cd auditreach
+npm install
+npm run build
+node dist/cli.js search --platform reddit --query "your query"
+```
+
+## Table of contents
+
+- [Why auditreach exists](#why-auditreach-exists)
+- [How it compares](#how-it-compares)
+- [What it does](#what-it-does)
+- [Getting started](#getting-started)
+- [Platform coverage](#platform-coverage)
+- [Result limits](#result-limits)
+- [What is a "consent basis," honestly](#what-is-a-consent-basis-honestly)
+- [FAQ](#faq)
+- [Self-hosting / local-only by default](#self-hosting--local-only-by-default)
+- [Development](#development)
+- [Security](#security)
+- [Success stories](#success-stories)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Why auditreach exists
+
+A consultancy we talked to had an AI research agent pulling social sentiment for a client report. It worked well until the client's legal team asked, in writing, what authority the data collection was under. The honest answer was "a browser cookie session," because the tool they were using authenticates by importing a logged-in session and scraping as if it were a real user. That works. It is also not an answer you can put in a compliance memo, and it is the exact pattern Reddit sued Anthropic and SerpApi over in 2025, and the same pattern that got Pushshift's public API access shut down by Reddit back in 2024.
+
+[Agent-Reach](https://github.com/Panniantong/Agent-Reach) is not a bad tool. It has real traction (55k+ stars) because cookie-based scraping genuinely covers more ground than any official API does today, at zero API cost. But "covers more ground" and "an agency's client can pass a compliance review" are two different bars, and nothing was built specifically to clear the second one.
+
+auditreach is the CLI we wished existed instead. It talks to Reddit and YouTube only through their official, documented APIs, using your own API keys -- never a shared pool -- and every single query writes a hash-chained entry to a local audit log: which platform, which endpoint, which scope, and a plain-language line explaining the consent/ToS basis for that specific call. No cookie import. No session-token reuse. No code path that could even pretend to be a logged-in human.
+
+We are not trying to out-cover Agent-Reach's six platforms. auditreach is narrower on purpose, for the buyer who structurally can't use a cookie-based tool at all.
+
+## How it compares
+
+|                              | **auditreach**                 | **Agent-Reach**                                         | **snoowrap**                                        |
+| ---------------------------- | ------------------------------ | ------------------------------------------------------- | --------------------------------------------------- |
+| Access model                 | Official API only, BYO-key     | Cookie/session import, "zero API fees"                  | Official API, BYO-key                               |
+| Platform coverage (v0.1)     | Reddit, YouTube                | Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu | Reddit only                                         |
+| Consent/audit log            | Hash-chained, per-query, local | None                                                    | None                                                |
+| Maintenance status           | Active (this release)          | Active, 55k stars                                       | **Archived** since Feb 2023                         |
+| License                      | Apache 2.0                     | MIT                                                     | MIT                                                 |
+| Runtime deps (Reddit client) | 0 -- native `fetch`            | n/a (Python, browser-session based)                     | `request`, `request-promise`, `ws` (all deprecated) |
+
+Numbers measured directly against each repo's public GitHub metadata and, for the dependency comparison, against `snoowrap`'s own published `package.json` as of this writing -- reproducible by anyone with `gh api repos/<owner>/<repo>`.
+
+We started building auditreach's Reddit client on top of `snoowrap`, the most-used Reddit API wrapper in the Node ecosystem. Installing it pulled in `request`, `request-promise`, `form-data`, and `har-validator` -- a dependency chain with **4 CRITICAL** and multiple HIGH severity advisories, none of which snoowrap can fix because the project has been archived since 2023. We rewrote the Reddit client as a direct `fetch`-based OAuth2 client against Reddit's own documented REST endpoints instead: same functionality, zero of those CVEs, zero extra runtime dependencies. `npm audit --audit-level=high` on this repo returns clean.
+
+## What it does
+
+    node dist/cli.js search --platform reddit --query "agent memory poisoning" --subreddit MachineLearning
+
+    AuditReach v0.1 -- Official-API Research CLI
+    Platform: Reddit  |  Auth: OAuth script-app grant, read-only, public-subreddit scope
+
+    Fetching... (official API, rate-limit aware)
+    ✓ 14 results returned (Reddit API Terms -- public content, official API, read-only script-app credentials)
+
+    RESULTS (14)
+    [1] "How are people testing for memory poisoning in long-running agents?"
+        u/some_researcher · 2026-07-05T14:22:00.000Z
+        https://reddit.com/r/MachineLearning/comments/...
+    ...
+
+    Audit log entry written: ar_2026-07-12_9f3c2a
+    Consent basis: Reddit API Terms -- public content, official API, read-only script-app credentials
+    Full results: ./auditreach-results-2026-07-12.json
+    Full audit trail: ./auditreach.log.jsonl
+
+Every entry in `auditreach.log.jsonl` is hash-chained -- each entry's hash is computed from its own content, and the next entry references it. Editing, deleting, or reordering an entry breaks the chain:
+
+    $ node dist/cli.js verify-log
+    Verifying ./auditreach.log.jsonl...
+    ✓ Chain intact: 14 entries, no gaps, no tampering detected.
+
+    # after someone hand-edits a line in the log file:
+    $ node dist/cli.js verify-log
+    Verifying ./auditreach.log.jsonl...
+    ✗ Chain broken at entry 3 (ar_2026-07-12_9f3c2a): entry ar_2026-07-12_9f3c2a hash does not
+      match its own content -- entry was edited after being written
+
+See `docs/security-review-2026-07-12.md` for how the tamper-detection path was verified.
+
+## Getting started
+
+**1. Install:** see [Install](#install) above -- clone and build, `npm install -g` isn't available yet.
+
+**2. Set up credentials for the platform you want to search (BYO-key -- your own, never ours):**
+
+    node dist/cli.js auth --platform reddit
+    # Prompts for Client ID, Client secret, username, password.
+    # Create a script-app at https://www.reddit.com/prefs/apps first.
+
+    node dist/cli.js auth --platform youtube
+    # Prompts for an API key.
+    # Create one at https://console.cloud.google.com/apis/credentials
+
+All credentials are stored in your OS keychain (`@napi-rs/keyring`), never in a config file, never transmitted anywhere except the platform's own official auth endpoint. Once credentials are set, verify them without running a real search:
+
+    node dist/cli.js auth --platform reddit --verify
+
+**3. Search:**
+
+    node dist/cli.js search --platform reddit --query "your query" --subreddit some_subreddit
+    node dist/cli.js search --platform youtube --query "your query" --channel @SomeChannel
+
+Honest note on setup time: getting your own API credentials from Reddit and Google takes a few minutes the first time -- this is slower than Agent-Reach's cookie-import flow (which just reuses a browser session you already have) by design. BYOK means the setup cost is real, not hidden.
+
+## Platform coverage
+
+| Platform    | API used                                        | Status              | Known constraint                                                                                                                                                                                                                                                                                                                                                                           |
+| ----------- | ----------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Reddit      | Reddit API (OAuth2 password grant, direct REST) | Shipped             | Rate limits are generally workable for real research volumes                                                                                                                                                                                                                                                                                                                               |
+| YouTube     | YouTube Data API v3 (`googleapis`)              | Shipped             | Quota-based (10,000 units/day default), generally workable                                                                                                                                                                                                                                                                                                                                 |
+| X (Twitter) | X API v2                                        | **Not yet shipped** | X's official API pricing and post-volume caps have been widely reported as prohibitive for small teams doing meaningful research since the 2023 pricing changes. Deferred until a real user needs it enough to fund working around that constraint -- shipping it half-working would undercut the entire "honest about what official APIs can and can't do" premise this tool is built on. |
+
+## Result limits
+
+`--max-results <n>` controls how many items a single `search` call returns. Leave it off and auditreach silently applies a default of 25 -- the same shape of surprise PRAW's `get_comments()` had for years ([praw#119](https://github.com/praw-dev/praw/issues/119)): a caller who does not already know to pass the flag gets a quietly truncated result set.
+
+| Platform | Default (flag omitted) | Maximum (`--max-results`) |
+| -------- | ---------------------- | ------------------------- |
+| Reddit   | 25                     | 100                       |
+| YouTube  | 25                     | 50                        |
+
+Values above the cap are silently clamped to it. For Reddit, `--before`/`--after` let you page past a single call's results using the real cursor Reddit's own response returns (see [Success stories](#success-stories)); YouTube has no equivalent yet. Whenever the number of items returned equals the limit that was actually applied, whether that is the silent default or an explicit `--max-results` value, auditreach prints a warning to stderr telling you more results may exist and how to raise `--max-results` (up to the platform cap).
+
+## What is a "consent basis," honestly
+
+The `consent_basis` field on every audit-log entry names the specific platform API terms and auth mechanism used for that query. It certifies that the request went through the platform's official, documented API surface under the credentials you supplied. **It does not certify that your specific use case is legally sufficient for your jurisdiction or contract** -- that determination is yours to make, informed by an accurate, complete, tamper-evident record of what actually happened.
+
+## FAQ
+
+**Does auditreach store my Reddit or YouTube credentials anywhere?**
+No. Credentials go straight into your OS keychain through `@napi-rs/keyring` (`src/auth/credential-store.ts`). There is no config file, no environment variable, and no code path that writes a raw credential to disk.
+
+**How many results does a search return by default, and can I get more?**
+25, silently, unless you pass `--max-results` -- see [Result limits](#result-limits). The hard cap is 100 for Reddit and 50 for YouTube. A stderr warning fires whenever a search actually hits the applied limit, whether that's the silent default or an explicit value you passed.
+
+**Can I page past Reddit's result cap?**
+Yes, for Reddit: `search()` reads the real `after`/`before` cursor out of Reddit's own response and exposes `--before`/`--after` flags to page in either direction. See the [praw#614 success story](#success-stories) for why this exists.
+
+**Does auditreach support X (Twitter)?**
+Not yet. X API v2's pricing and post-volume caps have been prohibitive for small teams doing real research since the 2023 changes. See [Platform coverage](#platform-coverage) for the full reasoning.
+
+**How do I check my credentials are still valid without running a real search?**
+`node dist/cli.js auth --platform reddit --verify` (or `--platform youtube`). It performs the minimal authenticated check and reports pass or fail, with no `--query` needed, no results file written, and no audit-log entry appended.
+
+**Is the audit log actually tamper-evident, or just a log file?**
+Tamper-evident: each entry's hash is computed from its own content and the next entry references it, so `verify-log` can point to the exact entry a hand-edit broke. See the demo under [What it does](#what-it-does).
+
+## Self-hosting / local-only by default
+
+Nothing about auditreach requires a hosted account or server. Every command runs entirely on your machine; the audit log is a plain file you own. This is the same flow as [Install](#install) above:
+
+    git clone https://github.com/RudrenduPaul/auditreach.git
+    cd auditreach
+    npm install
+    npm run build
+    node dist/cli.js search --platform reddit --query "..."
+
+## Development
+
+    npm install
+    npm run lint          # ESLint
+    npm run format        # Prettier check
+    npm run typecheck     # tsc --noEmit --strict
+    npm run test:coverage # vitest, 66 tests, 95.4% statement coverage
+
+See `CONTRIBUTING.md` for the rules on adding a new platform client -- the short version: official API only, honest rate-limit disclosure, tests that mock the network boundary, never anything that reads or writes a raw credential outside `src/auth/credential-store.ts`.
+
+## Security
+
+See `SECURITY.md` for the vulnerability disclosure policy and `docs/security-review-2026-07-12.md` for the pre-launch OWASP/STRIDE review (zero CRITICAL/HIGH findings; one moderate, non-directly-reachable supply-chain advisory that has since been resolved -- `npm audit` on this repo currently returns zero vulnerabilities). GitHub secret scanning and push protection are enabled on this repo.
+
+## Success stories
+
+Four real issues reported against `praw-dev/praw` -- PRAW, Reddit's official Python API
+wrapper, and the closest thing this project has to prior art -- root-caused against
+auditreach's own source and used to close genuine gaps in this tool before it had a
+single outside user. Each line below is tied to the actual report that prompted it.
+
+- **[praw#614](https://github.com/praw-dev/praw/issues/614)** (@mananwason) -- asked how
+  to read the before/after pagination cursor off Reddit's search response to page past
+  its ~1,000-result cap; PRAW itself never solved this. `search()` now extracts the real
+  cursor from Reddit's response and returns it as `SearchOutcome.nextCursor`, plus
+  `--before`/`--after` flags to page in either direction.
+- **[praw#1939](https://github.com/praw-dev/praw/issues/1939)** (@Auditormadness9) -- hit
+  an undiagnosed 400 error caused by a subreddit name that still carried a leading `r/`
+  prefix. Search errors now name that specific cause when it's the likely culprit:
+  previously the CLI just returned a bare status code and left the guessing to you.
+- **[praw#984](https://github.com/praw-dev/praw/issues/984)** (@MaxMatti) -- asked for a
+  simple way to check whether Reddit bot credentials were still valid, without PRAW's
+  confusing `getMe()`-recursion workaround. `auditreach auth --platform reddit --verify`
+  does exactly that now: one lightweight check, no search required, nothing written to
+  disk.
+- **[praw#119](https://github.com/praw-dev/praw/issues/119)** (@nsp) -- hit PRAW's
+  historic silent 25-result default, discoverable only by reading an unrelated base
+  class's docstring; PRAW's own maintainer admitted he "wasn't sure the best way to make
+  this clear." `--help` and this README now state the real default and per-platform
+  caps, and a runtime warning fires whenever a search actually got truncated.
+
+## Contributing
+
+See `CONTRIBUTING.md` for the rules on adding a new platform client. Short version: official API only, honest rate-limit disclosure, tests that mock the network boundary, never a code path that reads or writes a raw credential outside `src/auth/credential-store.ts`.
+
+## License
+
+Apache 2.0. See `LICENSE`.

package/dist/audit-log/chain-verifier.d.ts

@@ -0,0 +1,9 @@
+import type { ChainVerificationResult } from "../types.js";
+/**
+ * Re-derives every entry's hash from its own content and checks it against
+ * the stored hash, then checks each entry's prev_entry_hash against the
+ * previous entry's actual hash. Either check failing means the log was
+ * edited, reordered, or an entry was deleted after the fact.
+ */
+export declare function verifyAuditLogChain(logPath?: string): Promise<ChainVerificationResult>;
+//# sourceMappingURL=chain-verifier.d.ts.map

package/dist/audit-log/chain-verifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain-verifier.d.ts","sourceRoot":"","sources":["../../src/audit-log/chain-verifier.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAiB,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAa1E;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,OAAO,GAAE,MAA+B,GACvC,OAAO,CAAC,uBAAuB,CAAC,CA8DlC"}

package/dist/audit-log/chain-verifier.js

@@ -0,0 +1,79 @@
+import { readFile } from "node:fs/promises";
+import { access, constants } from "node:fs";
+import { promisify } from "node:util";
+import { computeEntryHash } from "./hash-chain-writer.js";
+import { DEFAULT_AUDIT_LOG_PATH } from "./hash-chain-writer.js";
+const accessAsync = promisify(access);
+async function fileExists(path) {
+    try {
+        await accessAsync(path, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Re-derives every entry's hash from its own content and checks it against
+ * the stored hash, then checks each entry's prev_entry_hash against the
+ * previous entry's actual hash. Either check failing means the log was
+ * edited, reordered, or an entry was deleted after the fact.
+ */
+export async function verifyAuditLogChain(logPath = DEFAULT_AUDIT_LOG_PATH) {
+    if (!(await fileExists(logPath))) {
+        return {
+            valid: true,
+            totalEntries: 0,
+            brokenAtEntryId: null,
+            brokenAtIndex: null,
+            reason: "no log file yet -- nothing to verify",
+        };
+    }
+    const content = await readFile(logPath, "utf8");
+    const lines = content.split("\n").filter((line) => line.trim().length > 0);
+    let expectedPrevHash = null;
+    for (let i = 0; i < lines.length; i++) {
+        let entry;
+        try {
+            entry = JSON.parse(lines[i]);
+        }
+        catch {
+            return {
+                valid: false,
+                totalEntries: lines.length,
+                brokenAtEntryId: null,
+                brokenAtIndex: i,
+                reason: `line ${i + 1} is not valid JSON`,
+            };
+        }
+        if (entry.prev_entry_hash !== expectedPrevHash) {
+            return {
+                valid: false,
+                totalEntries: lines.length,
+                brokenAtEntryId: entry.entry_id,
+                brokenAtIndex: i,
+                reason: `entry ${entry.entry_id} references prev_entry_hash that does not match the actual prior entry -- chain broken or reordered`,
+            };
+        }
+        const { entry_hash, ...rest } = entry;
+        const recomputed = computeEntryHash(rest);
+        if (recomputed !== entry_hash) {
+            return {
+                valid: false,
+                totalEntries: lines.length,
+                brokenAtEntryId: entry.entry_id,
+                brokenAtIndex: i,
+                reason: `entry ${entry.entry_id} hash does not match its own content -- entry was edited after being written`,
+            };
+        }
+        expectedPrevHash = entry_hash;
+    }
+    return {
+        valid: true,
+        totalEntries: lines.length,
+        brokenAtEntryId: null,
+        brokenAtIndex: null,
+        reason: null,
+    };
+}
+//# sourceMappingURL=chain-verifier.js.map

package/dist/audit-log/chain-verifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain-verifier.js","sourceRoot":"","sources":["../../src/audit-log/chain-verifier.ts"],"names":[],"mappings":"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"}

package/dist/audit-log/hash-chain-writer.d.ts

@@ -0,0 +1,16 @@
+import type { AuditLogEntry, UnhashedAuditLogEntry } from "../types.js";
+export declare const DEFAULT_AUDIT_LOG_PATH = "./auditreach.log.jsonl";
+/**
+ * Reads the last line of the log file to find the previous entry's hash.
+ * Returns null if the log doesn't exist yet or is empty -- that's the
+ * legitimate state for the very first entry in a chain.
+ */
+export declare function getLastEntryHash(logPath?: string): Promise<string | null>;
+export declare function computeEntryHash(entry: UnhashedAuditLogEntry): string;
+/**
+ * Appends one hash-chained entry to the local audit log. This is the only
+ * write path into the log -- entries are never edited or deleted in place,
+ * which is what makes `verify-log` a meaningful tamper check.
+ */
+export declare function appendAuditLogEntry(entryWithoutHash: UnhashedAuditLogEntry, logPath?: string): Promise<AuditLogEntry>;
+//# sourceMappingURL=hash-chain-writer.d.ts.map

package/dist/audit-log/hash-chain-writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash-chain-writer.d.ts","sourceRoot":"","sources":["../../src/audit-log/hash-chain-writer.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAExE,eAAO,MAAM,sBAAsB,2BAA2B,CAAC;AAW/D;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,GAAE,MAA+B,GACvC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAYxB;AAED,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,qBAAqB,GAAG,MAAM,CAIrE;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,gBAAgB,EAAE,qBAAqB,EACvC,OAAO,GAAE,MAA+B,GACvC,OAAO,CAAC,aAAa,CAAC,CAKxB"}

package/dist/audit-log/hash-chain-writer.js

@@ -0,0 +1,49 @@
+import { appendFile, readFile } from "node:fs/promises";
+import { constants } from "node:fs";
+import { access } from "node:fs/promises";
+import { canonicalJson, sha256Hex } from "../util/crypto.js";
+export const DEFAULT_AUDIT_LOG_PATH = "./auditreach.log.jsonl";
+async function fileExists(path) {
+    try {
+        await access(path, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Reads the last line of the log file to find the previous entry's hash.
+ * Returns null if the log doesn't exist yet or is empty -- that's the
+ * legitimate state for the very first entry in a chain.
+ */
+export async function getLastEntryHash(logPath = DEFAULT_AUDIT_LOG_PATH) {
+    if (!(await fileExists(logPath))) {
+        return null;
+    }
+    const content = await readFile(logPath, "utf8");
+    const lines = content.split("\n").filter((line) => line.trim().length > 0);
+    if (lines.length === 0) {
+        return null;
+    }
+    const lastLine = lines[lines.length - 1];
+    const lastEntry = JSON.parse(lastLine);
+    return lastEntry.entry_hash;
+}
+export function computeEntryHash(entry) {
+    // prev_entry_hash is already a field on `entry`, so canonicalJson alone
+    // links this entry to the previous one -- no need to fold it in twice.
+    return sha256Hex(canonicalJson(entry));
+}
+/**
+ * Appends one hash-chained entry to the local audit log. This is the only
+ * write path into the log -- entries are never edited or deleted in place,
+ * which is what makes `verify-log` a meaningful tamper check.
+ */
+export async function appendAuditLogEntry(entryWithoutHash, logPath = DEFAULT_AUDIT_LOG_PATH) {
+    const entry_hash = computeEntryHash(entryWithoutHash);
+    const fullEntry = { ...entryWithoutHash, entry_hash };
+    await appendFile(logPath, JSON.stringify(fullEntry) + "\n", "utf8");
+    return fullEntry;
+}
+//# sourceMappingURL=hash-chain-writer.js.map

package/dist/audit-log/hash-chain-writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash-chain-writer.js","sourceRoot":"","sources":["../../src/audit-log/hash-chain-writer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAG7D,MAAM,CAAC,MAAM,sBAAsB,GAAG,wBAAwB,CAAC;AAE/D,KAAK,UAAU,UAAU,CAAC,IAAY;IACpC,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC;QACnC,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,UAAkB,sBAAsB;IAExC,IAAI,CAAC,CAAC,MAAM,UAAU,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC;QACjC,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAChD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC3E,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,QAAQ,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAW,CAAC;IACnD,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAkB,CAAC;IACxD,OAAO,SAAS,CAAC,UAAU,CAAC;AAC9B,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,KAA4B;IAC3D,wEAAwE;IACxE,uEAAuE;IACvE,OAAO,SAAS,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC;AACzC,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,gBAAuC,EACvC,UAAkB,sBAAsB;IAExC,MAAM,UAAU,GAAG,gBAAgB,CAAC,gBAAgB,CAAC,CAAC;IACtD,MAAM,SAAS,GAAkB,EAAE,GAAG,gBAAgB,EAAE,UAAU,EAAE,CAAC;IACrE,MAAM,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,MAAM,CAAC,CAAC;IACpE,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/auth/credential-store.d.ts

@@ -0,0 +1,24 @@
+import type { Platform } from "../types.js";
+export type RedditCredentialKey = "clientId" | "clientSecret" | "username" | "password";
+export type YoutubeCredentialKey = "apiKey";
+export type CredentialKey = RedditCredentialKey | YoutubeCredentialKey;
+/**
+ * All credential I/O goes through this module. It is the one place allowed
+ * to touch a raw secret -- callers get it back only to hand directly to an
+ * API client's auth constructor, never to log, print, or serialize it.
+ */
+export declare function setCredential(platform: Platform, key: CredentialKey, value: string): void;
+export declare function getCredential(platform: Platform, key: CredentialKey): string | null;
+export declare function deleteCredential(platform: Platform, key: CredentialKey): boolean;
+export interface RedditCredentials {
+    clientId: string;
+    clientSecret: string;
+    username: string;
+    password: string;
+}
+export interface YoutubeCredentials {
+    apiKey: string;
+}
+export declare function getRedditCredentials(): RedditCredentials | null;
+export declare function getYoutubeCredentials(): YoutubeCredentials | null;
+//# sourceMappingURL=credential-store.d.ts.map

package/dist/auth/credential-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential-store.d.ts","sourceRoot":"","sources":["../../src/auth/credential-store.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAI5C,MAAM,MAAM,mBAAmB,GAAG,UAAU,GAAG,cAAc,GAAG,UAAU,GAAG,UAAU,CAAC;AACxF,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;AAC5C,MAAM,MAAM,aAAa,GAAG,mBAAmB,GAAG,oBAAoB,CAAC;AAMvE;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAGzF;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,aAAa,GAAG,MAAM,GAAG,IAAI,CAOnF;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,EAAE,GAAG,EAAE,aAAa,GAAG,OAAO,CAOhF;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,oBAAoB,IAAI,iBAAiB,GAAG,IAAI,CAS/D;AAED,wBAAgB,qBAAqB,IAAI,kBAAkB,GAAG,IAAI,CAMjE"}