attestari 0.0.0-stage → 2.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 The Elite360 Corporation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,56 @@
-# Temporary Holding Version
+# attestari
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The Attestari Protect hook: the one file each agent (Claude Code first) runs itself.
+
+- `dist/hook.js` is the whole hook. It is built from `src/` by esbuild, committed, and has no runtime
+  dependency: it requires only Node's own modules (`node:fs`, `node:path`, `node:os`, and the like).
+- Build: `npm install && npm run build`. Test: `npm test` (builds, then runs `node --test` on the built file).
+  Type check: `npm run check`.
+- `node dist/hook.js status` prints each agent folder under `~/.attestari/`; every unbuilt subcommand exits 2.
+- Built for Claude Code: `pair --code <code>`, `claude-code session-start` (resolves the configured servers of its
+  folder and starts the check-in detached), `claude-code refresh` (the check-in: the policy, the events,
+  and the agent's own `deniedMcpServers` entries) and `claude-code pre-tool-use` (decides each MCP call, and starts the
+  refresh when the last check-in is over an hour old). `ATTESTARI_ACCOUNTS_URL` points the hook at another accounts
+  service only on loopback (`127.0.0.1`, `::1`, `localhost`: the tests' local server); any other address is ignored
+  with one line on stderr.
+- What it resolves: `npx`/`bunx`/`pnpx`/`pnpm dlx`/`yarn dlx` an npm package, `uvx`/`pipx run` a PyPI package, a URL a
+  remote, any other command (`docker`, `node file.js`, an executable) a local tool. A registry runner whose package
+  it cannot name (an alias, a git, tarball, file or URL spec, a second package, `${PKG}`, or any flag but `-y`,
+  `--yes`, `-q`, `--quiet`, `-p`/`--package`, uvx's `--from`, `--python` and `-p` (python) and pipx's `--spec`) is left out of the resolution,
+  reported to nobody, and denied as not checked, never a local tool; stderr says "its package could not be named"
+  with the key.
+- What it keeps, under `~/.attestari/claude-code/`: `token`, `secret` (the key of a local tool's hash), `policy.json`
+  and `policy.etag`, `resolved/<folder>.json` and `written/<folder>.json` (per working folder: `<folder>` is the first
+  16 hexadecimal characters of the SHA-256 of the session's `cwd`; the resolution holds the folder's path, and both
+  are dropped at a check-in once the folder is gone or its resolution was not rewritten by a session start for 30
+  days, its deny entries taken back when it was read whole), `sessions/<session_id>` (the folder a session
+  started in, its id and path, written at SessionStart; pruned after 30 days at a check-in), `events.jsonl`, and the
+  times `checked_in_at`, `refresh_started_at` (with the refresh's process id) and `next_refresh_at`. A call is decided
+  by the `resolved/` file of its session's start folder (the call's `cwd` follows Claude's `cd`; it is used only when
+  the session has no file); the check-in reports the union of them all, a key launching different packages in two folders
+  once per folder as `<key>/<8 hex of the folder's hash>`. `refresh --cwd <folder>` resolves that folder first when
+  it has no file yet. A check-in answered 401 `invalid_token` (the agent was removed) deletes `token`, `policy.json`
+  and `policy.etag`, so every MCP call is then denied until the agent is paired again; the deny entries are written
+  only when `~/.claude/settings.json` is unchanged between the reading and the rename.
+- The build also copies `dist/hook.js` to `plugins/attestari/hooks/hook.js`, the Claude Code plugin's copy (the
+  marketplace is `plugins/`); `test/build.test.mjs` refuses a difference, and CI refuses a committed copy older than
+  the build. `pair` installs the plugin when `claude` is on the PATH (`claude plugin marketplace add
+  attestari-ai/plugins`, then `claude plugin install attestari@attestari --scope user`; `ATTESTARI_MARKETPLACE` names
+  another marketplace, such as a local `plugins/` folder) and otherwise prints the two commands. What the hook reads
+  and writes on a computer: `docs/app.attestari.ai/hook.md`.
+- The build also makes `dist/gateway.js` (from `src/gateway-main.ts`; not committed itself, but copied byte for byte to
+  `extension/server/gateway.js`, which is, and packed into `attestari.mcpb` by `npm run pack:extension`): the Claude
+  Desktop extension's gateway (M2.5), one MCP server on stdio that starts the child servers it is given, in the home
+  folder, and relays them under `<key>__`, with its own `attestari_status` tool. Run with no argument (as Claude
+  Desktop runs it) it first runs a provisional plan from the policy held (no network call before `initialize` is
+  answered), then pairs by `ATTESTARI_INSTALL_CODE`, checks in as `Claude Desktop`, decides from the policy which
+  servers of `~/.attestari/claude-desktop/servers.json` to start (`desktop.ts`), and checks in again hourly, stopping
+  and starting children as the policy moves; `checkin.ts` is the check-in it makes (session.ts's refresh without the
+  Claude Code parts; session.ts keeps its own copy so `dist/hook.js` does not move). `--servers <file>` runs it on a
+  `{servers, refused, notice}` file instead, bypassing the policy, and only with `ATTESTARI_GATEWAY_UNSAFE_FILE=1` and
+  a loopback `ATTESTARI_ACCOUNTS_URL` (the tests'; the same condition holds for `ATTESTARI_GATEWAY_REFRESH_MS`). Once
+  paired it moves Claude Desktop's own servers (`claude_desktop_config.json`'s `mcpServers`) into `servers.json` when
+  `ATTESTARI_MOVE_SERVERS` is `"true"`, with a dated backup beside the config, and puts them back when it is `"false"`
+  (`adapters/claude-desktop.ts`). What it reads, sends and writes: `docs/app.attestari.ai/hook.md`,
+  "Claude Desktop".
+- The sources, the tests and the built file are LF everywhere.