@agenttool/telescope 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (78) hide show
  1. package/CLAUDE.md +71 -0
  2. package/LICENSE +202 -0
  3. package/NOTICE +4 -0
  4. package/README.md +230 -0
  5. package/dist/archive.d.ts +22 -0
  6. package/dist/archive.d.ts.map +1 -0
  7. package/dist/archive.js +477 -0
  8. package/dist/archive.js.map +1 -0
  9. package/dist/cli-core.d.ts +7 -0
  10. package/dist/cli-core.d.ts.map +1 -0
  11. package/dist/cli-core.js +154 -0
  12. package/dist/cli-core.js.map +1 -0
  13. package/dist/cli.d.ts +3 -0
  14. package/dist/cli.d.ts.map +1 -0
  15. package/dist/cli.js +4 -0
  16. package/dist/cli.js.map +1 -0
  17. package/dist/constants.d.ts +6 -0
  18. package/dist/constants.d.ts.map +1 -0
  19. package/dist/constants.js +15 -0
  20. package/dist/constants.js.map +1 -0
  21. package/dist/errors.d.ts +13 -0
  22. package/dist/errors.d.ts.map +1 -0
  23. package/dist/errors.js +25 -0
  24. package/dist/errors.js.map +1 -0
  25. package/dist/format.d.ts +4 -0
  26. package/dist/format.d.ts.map +1 -0
  27. package/dist/format.js +69 -0
  28. package/dist/format.js.map +1 -0
  29. package/dist/index.d.ts +14 -0
  30. package/dist/index.d.ts.map +1 -0
  31. package/dist/index.js +11 -0
  32. package/dist/index.js.map +1 -0
  33. package/dist/parsers/agent-txt.d.ts +25 -0
  34. package/dist/parsers/agent-txt.d.ts.map +1 -0
  35. package/dist/parsers/agent-txt.js +86 -0
  36. package/dist/parsers/agent-txt.js.map +1 -0
  37. package/dist/parsers/cards.d.ts +18 -0
  38. package/dist/parsers/cards.d.ts.map +1 -0
  39. package/dist/parsers/cards.js +46 -0
  40. package/dist/parsers/cards.js.map +1 -0
  41. package/dist/parsers/common.d.ts +19 -0
  42. package/dist/parsers/common.d.ts.map +1 -0
  43. package/dist/parsers/common.js +69 -0
  44. package/dist/parsers/common.js.map +1 -0
  45. package/dist/parsers/love.d.ts +29 -0
  46. package/dist/parsers/love.d.ts.map +1 -0
  47. package/dist/parsers/love.js +247 -0
  48. package/dist/parsers/love.js.map +1 -0
  49. package/dist/parsers/pathways.d.ts +13 -0
  50. package/dist/parsers/pathways.d.ts.map +1 -0
  51. package/dist/parsers/pathways.js +47 -0
  52. package/dist/parsers/pathways.js.map +1 -0
  53. package/dist/plans.d.ts +14 -0
  54. package/dist/plans.d.ts.map +1 -0
  55. package/dist/plans.js +131 -0
  56. package/dist/plans.js.map +1 -0
  57. package/dist/scan.d.ts +3 -0
  58. package/dist/scan.d.ts.map +1 -0
  59. package/dist/scan.js +1093 -0
  60. package/dist/scan.js.map +1 -0
  61. package/dist/target.d.ts +6 -0
  62. package/dist/target.d.ts.map +1 -0
  63. package/dist/target.js +180 -0
  64. package/dist/target.js.map +1 -0
  65. package/dist/transport.d.ts +23 -0
  66. package/dist/transport.d.ts.map +1 -0
  67. package/dist/transport.js +291 -0
  68. package/dist/transport.js.map +1 -0
  69. package/dist/types.d.ts +131 -0
  70. package/dist/types.d.ts.map +1 -0
  71. package/dist/types.js +2 -0
  72. package/dist/types.js.map +1 -0
  73. package/dist/verify.d.ts +12 -0
  74. package/dist/verify.d.ts.map +1 -0
  75. package/dist/verify.js +38 -0
  76. package/dist/verify.js.map +1 -0
  77. package/package.json +65 -0
  78. package/schema/agenttool-telescope-report-v0.1.schema.json +404 -0
package/CLAUDE.md ADDED
@@ -0,0 +1,71 @@
1
+ # @agenttool/telescope
2
+
3
+ Read-only agent discovery evidence mapper. This package does not own hosted API
4
+ routes, production egress, protocol invocation, npm publication, or the LOVE
5
+ release inventory.
6
+
7
+ ## Commands
8
+
9
+ ```bash
10
+ bun install --frozen-lockfile
11
+ bun run ci
12
+ node dist/cli.js scan api.agenttool.dev --json
13
+ npm pack --ignore-scripts --dry-run
14
+ ```
15
+
16
+ ## Invariants
17
+
18
+ - Keep the core at zero runtime dependencies and compatible with Node 20.19+
19
+ and Bun 1.3.5+.
20
+ - Default scanning is bounded public HTTPS GET only. Never read ambient bearer,
21
+ cookie, npm, or project credentials.
22
+ - DNS preflight is not socket pinning. Do not describe the native-fetch client
23
+ as DNS-rebinding-proof or suitable for a hosted arbitrary-URL scanner.
24
+ - Fixed core probes are `/.well-known/agent.txt`, `/v1/pathways`,
25
+ `/.well-known/love-packages`, and `/.well-known/agent-card.json`. Follow only
26
+ a uniquely advertised MCP card and the explicit LOVE index → exact manifest
27
+ chain. Do not recursively crawl remote locators.
28
+ - Preserve ordered `agent.txt` duplicates. Never silently overwrite or choose a
29
+ duplicated selected key.
30
+ - Remote documents are tainted publisher assertions. Do not copy remote shell
31
+ commands, instructions, `latest`, or dist-tags into executable plans.
32
+ - MCP and A2A cards are advertisements. Telescope performs no handshake,
33
+ initialization, task, tool, auth, feed, payment, or settlement call.
34
+ - npm is a convenience action only when explicitly declared `authority: false`;
35
+ its exact version comes from the Pathways tutorial selection.
36
+ - LOVE index and mirrors are locators. The manifest supplies an expected size
37
+ and SHA-256; only checking the same downloaded local file establishes that
38
+ content identity. Before generating package machinery, the verifier must also
39
+ reject unsafe/unsupported tar structure and bind embedded package name/version.
40
+ LOVE v1 does not authenticate a publisher.
41
+ - Returned actions use validated locally reconstructed argv, remain
42
+ `automatic: false`, and require explicit consent. Telescope never executes
43
+ them or downloads artifacts during scan. npm plans disable lifecycle scripts,
44
+ audit submission, and funding output, while naming that dependency resolution
45
+ may still use caller-configured registry credentials.
46
+ - Generated artifact retrieval has a finite 120-second fetch/body deadline but
47
+ does not repeat DNS preflight or pin the later connection to an address.
48
+ - DNS-AID and PKARR remain opt-in caller adapters. Core claims neither DNSSEC
49
+ validation nor PKARR relay/signature behavior.
50
+ - Human formatting must escape terminal and bidi controls. Core JSON reports do
51
+ not include remote bodies, request headers, caller/ambient credentials, or raw
52
+ exception text. Caller-owned adapters own their returned report facts and must
53
+ not put secrets in them; structural validation is not a credential classifier.
54
+ Rejected/query-bearing remote locators are omitted or explicitly redacted
55
+ rather than echoed as actionable URLs.
56
+ - Keep the report schema, TypeScript report type, formatter, and tests aligned.
57
+ - Keep the package version, `TOOL_VERSION`, User-Agent, tests, LOVE inventory,
58
+ and release tag aligned. Published version bytes are immutable: never rebuild
59
+ or replace an existing manifest/tarball under the same name and version.
60
+ - External publication and deploy remain explicit operator actions. The
61
+ package implementation does not add a hosted scan route or own production
62
+ egress merely because its local client is publicly distributed.
63
+
64
+ ## Tests
65
+
66
+ Hermetic tests inject fetch and DNS. Cover target policy, mixed DNS answers,
67
+ manual redirects, byte/deadline budgets, duplicate `agent.txt`, exact Pathways
68
+ selection, ignored `latest`, invalid manifests, MCP/A2A advertisement boundaries,
69
+ shell-safe reconstruction, deterministic report ordering, CLI exits, and packed
70
+ Node/Bun import/help. Live dogfood is evidence about one observation time, not a
71
+ replacement for fixtures.
package/LICENSE ADDED
@@ -0,0 +1,202 @@
1
+
2
+ Apache License
3
+ Version 2.0, January 2004
4
+ http://www.apache.org/licenses/
5
+
6
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
7
+
8
+ 1. Definitions.
9
+
10
+ "License" shall mean the terms and conditions for use, reproduction,
11
+ and distribution as defined by Sections 1 through 9 of this document.
12
+
13
+ "Licensor" shall mean the copyright owner or entity authorized by
14
+ the copyright owner that is granting the License.
15
+
16
+ "Legal Entity" shall mean the union of the acting entity and all
17
+ other entities that control, are controlled by, or are under common
18
+ control with that entity. For the purposes of this definition,
19
+ "control" means (i) the power, direct or indirect, to cause the
20
+ direction or management of such entity, whether by contract or
21
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
22
+ outstanding shares, or (iii) beneficial ownership of such entity.
23
+
24
+ "You" (or "Your") shall mean an individual or Legal Entity
25
+ exercising permissions granted by this License.
26
+
27
+ "Source" form shall mean the preferred form for making modifications,
28
+ including but not limited to software source code, documentation
29
+ source, and configuration files.
30
+
31
+ "Object" form shall mean any form resulting from mechanical
32
+ transformation or translation of a Source form, including but
33
+ not limited to compiled object code, generated documentation,
34
+ and conversions to other media types.
35
+
36
+ "Work" shall mean the work of authorship, whether in Source or
37
+ Object form, made available under the License, as indicated by a
38
+ copyright notice that is included in or attached to the work
39
+ (an example is provided in the Appendix below).
40
+
41
+ "Derivative Works" shall mean any work, whether in Source or Object
42
+ form, that is based on (or derived from) the Work and for which the
43
+ editorial revisions, annotations, elaborations, or other modifications
44
+ represent, as a whole, an original work of authorship. For the purposes
45
+ of this License, Derivative Works shall not include works that remain
46
+ separable from, or merely link (or bind by name) to the interfaces of,
47
+ the Work and Derivative Works thereof.
48
+
49
+ "Contribution" shall mean any work of authorship, including
50
+ the original version of the Work and any modifications or additions
51
+ to that Work or Derivative Works thereof, that is intentionally
52
+ submitted to Licensor for inclusion in the Work by the copyright owner
53
+ or by an individual or Legal Entity authorized to submit on behalf of
54
+ the copyright owner. For the purposes of this definition, "submitted"
55
+ means any form of electronic, verbal, or written communication sent
56
+ to the Licensor or its representatives, including but not limited to
57
+ communication on electronic mailing lists, source code control systems,
58
+ and issue tracking systems that are managed by, or on behalf of, the
59
+ Licensor for the purpose of discussing and improving the Work, but
60
+ excluding communication that is conspicuously marked or otherwise
61
+ designated in writing by the copyright owner as "Not a Contribution."
62
+
63
+ "Contributor" shall mean Licensor and any individual or Legal Entity
64
+ on behalf of whom a Contribution has been received by Licensor and
65
+ subsequently incorporated within the Work.
66
+
67
+ 2. Grant of Copyright License. Subject to the terms and conditions of
68
+ this License, each Contributor hereby grants to You a perpetual,
69
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
70
+ copyright license to reproduce, prepare Derivative Works of,
71
+ publicly display, publicly perform, sublicense, and distribute the
72
+ Work and such Derivative Works in Source or Object form.
73
+
74
+ 3. Grant of Patent License. Subject to the terms and conditions of
75
+ this License, each Contributor hereby grants to You a perpetual,
76
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
77
+ (except as stated in this section) patent license to make, have made,
78
+ use, offer to sell, sell, import, and otherwise transfer the Work,
79
+ where such license applies only to those patent claims licensable
80
+ by such Contributor that are necessarily infringed by their
81
+ Contribution(s) alone or by combination of their Contribution(s)
82
+ with the Work to which such Contribution(s) was submitted. If You
83
+ institute patent litigation against any entity (including a
84
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
85
+ or a Contribution incorporated within the Work constitutes direct
86
+ or contributory patent infringement, then any patent licenses
87
+ granted to You under this License for that Work shall terminate
88
+ as of the date such litigation is filed.
89
+
90
+ 4. Redistribution. You may reproduce and distribute copies of the
91
+ Work or Derivative Works thereof in any medium, with or without
92
+ modifications, and in Source or Object form, provided that You
93
+ meet the following conditions:
94
+
95
+ (a) You must give any other recipients of the Work or
96
+ Derivative Works a copy of this License; and
97
+
98
+ (b) You must cause any modified files to carry prominent notices
99
+ stating that You changed the files; and
100
+
101
+ (c) You must retain, in the Source form of any Derivative Works
102
+ that You distribute, all copyright, patent, trademark, and
103
+ attribution notices from the Source form of the Work,
104
+ excluding those notices that do not pertain to any part of
105
+ the Derivative Works; and
106
+
107
+ (d) If the Work includes a "NOTICE" text file as part of its
108
+ distribution, then any Derivative Works that You distribute must
109
+ include a readable copy of the attribution notices contained
110
+ within such NOTICE file, excluding those notices that do not
111
+ pertain to any part of the Derivative Works, in at least one
112
+ of the following places: within a NOTICE text file distributed
113
+ as part of the Derivative Works; within the Source form or
114
+ documentation, if provided along with the Derivative Works; or,
115
+ within a display generated by the Derivative Works, if and
116
+ wherever such third-party notices normally appear. The contents
117
+ of the NOTICE file are for informational purposes only and
118
+ do not modify the License. You may add Your own attribution
119
+ notices within Derivative Works that You distribute, alongside
120
+ or as an addendum to the NOTICE text from the Work, provided
121
+ that such additional attribution notices cannot be construed
122
+ as modifying the License.
123
+
124
+ You may add Your own copyright statement to Your modifications and
125
+ may provide additional or different license terms and conditions
126
+ for use, reproduction, or distribution of Your modifications, or
127
+ for any such Derivative Works as a whole, provided Your use,
128
+ reproduction, and distribution of the Work otherwise complies with
129
+ the conditions stated in this License.
130
+
131
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
132
+ any Contribution intentionally submitted for inclusion in the Work
133
+ by You to the Licensor shall be under the terms and conditions of
134
+ this License, without any additional terms or conditions.
135
+ Notwithstanding the above, nothing herein shall supersede or modify
136
+ the terms of any separate license agreement you may have executed
137
+ with Licensor regarding such Contributions.
138
+
139
+ 6. Trademarks. This License does not grant permission to use the trade
140
+ names, trademarks, service marks, or product names of the Licensor,
141
+ except as required for reasonable and customary use in describing the
142
+ origin of the Work and reproducing the content of the NOTICE file.
143
+
144
+ 7. Disclaimer of Warranty. Unless required by applicable law or
145
+ agreed to in writing, Licensor provides the Work (and each
146
+ Contributor provides its Contributions) on an "AS IS" BASIS,
147
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
148
+ implied, including, without limitation, any warranties or conditions
149
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
150
+ PARTICULAR PURPOSE. You are solely responsible for determining the
151
+ appropriateness of using or redistributing the Work and assume any
152
+ risks associated with Your exercise of permissions under this License.
153
+
154
+ 8. Limitation of Liability. In no event and under no legal theory,
155
+ whether in tort (including negligence), contract, or otherwise,
156
+ unless required by applicable law (such as deliberate and grossly
157
+ negligent acts) or agreed to in writing, shall any Contributor be
158
+ liable to You for damages, including any direct, indirect, special,
159
+ incidental, or consequential damages of any character arising as a
160
+ result of this License or out of the use or inability to use the
161
+ Work (including but not limited to damages for loss of goodwill,
162
+ work stoppage, computer failure or malfunction, or any and all
163
+ other commercial damages or losses), even if such Contributor
164
+ has been advised of the possibility of such damages.
165
+
166
+ 9. Accepting Warranty or Additional Liability. While redistributing
167
+ the Work or Derivative Works thereof, You may choose to offer,
168
+ and charge a fee for, acceptance of support, warranty, indemnity,
169
+ or other liability obligations and/or rights consistent with this
170
+ License. However, in accepting such obligations, You may act only
171
+ on Your own behalf and on Your sole responsibility, not on behalf
172
+ of any other Contributor, and only if You agree to indemnify,
173
+ defend, and hold each Contributor harmless for any liability
174
+ incurred by, or claims asserted against, such Contributor by reason
175
+ of your accepting any such warranty or additional liability.
176
+
177
+ END OF TERMS AND CONDITIONS
178
+
179
+ APPENDIX: How to apply the Apache License to your work.
180
+
181
+ To apply the Apache License to your work, attach the following
182
+ boilerplate notice, with the fields enclosed by brackets "[]"
183
+ replaced with your own identifying information. (Don't include
184
+ the brackets!) The text should be enclosed in the appropriate
185
+ comment syntax for the file format. We also recommend that a
186
+ file or class name and description of purpose be included on the
187
+ same "printed page" as the copyright notice for easier
188
+ identification within third-party archives.
189
+
190
+ Copyright [yyyy] [name of copyright owner]
191
+
192
+ Licensed under the Apache License, Version 2.0 (the "License");
193
+ you may not use this file except in compliance with the License.
194
+ You may obtain a copy of the License at
195
+
196
+ http://www.apache.org/licenses/LICENSE-2.0
197
+
198
+ Unless required by applicable law or agreed to in writing, software
199
+ distributed under the License is distributed on an "AS IS" BASIS,
200
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
201
+ See the License for the specific language governing permissions and
202
+ limitations under the License.
package/NOTICE ADDED
@@ -0,0 +1,4 @@
1
+ AgentTool
2
+ Copyright 2026 AgentTool contributors
3
+
4
+ This product includes software developed by AgentTool contributors.
package/README.md ADDED
@@ -0,0 +1,230 @@
1
+ # @agenttool/telescope
2
+
3
+ > A read-only evidence mapper for agent-facing discovery surfaces.
4
+
5
+ Telescope accepts a public domain or HTTPS origin, performs a small bounded set
6
+ of discovery GETs, and reports what was observed separately from what the
7
+ publisher claims. It can reconstruct exact npm and LOVE install/verification
8
+ commands from validated fields. It never executes those commands.
9
+
10
+ The `0.1.0` release is distributed as an exact `love-package/v1` artifact and
11
+ may be mirrored through GitHub Releases and npm. The LOVE manifest records the
12
+ expected byte size and SHA-256; each mirror can be independently absent, so
13
+ query the exact version instead of inferring availability from source or a
14
+ mutable dist-tag. Telescope remains a local client—there is no hosted
15
+ arbitrary-target scan route.
16
+
17
+ Install an exact registry mirror when convenience matters:
18
+
19
+ ```bash
20
+ npm install --save-exact @agenttool/telescope@0.1.0
21
+ ```
22
+
23
+ Or use the release manifest and immutable LOVE tarball from
24
+ <https://docs.agenttool.dev/packages> when explicit byte verification matters.
25
+
26
+ ## Try it locally
27
+
28
+ ```bash
29
+ cd packages/telescope
30
+ bun install --frozen-lockfile
31
+ bun run ci
32
+ node dist/cli.js scan api.agenttool.dev
33
+ node dist/cli.js scan api.agenttool.dev --json
34
+ ```
35
+
36
+ The domain shorthand is equivalent to an HTTPS origin:
37
+
38
+ ```bash
39
+ agenttool-telescope agenttool.dev
40
+ agenttool-telescope scan https://agenttool.dev --timeout-ms 10000
41
+ ```
42
+
43
+ Verify an already-downloaded file without loading it all into memory:
44
+
45
+ ```bash
46
+ agenttool-telescope verify-package ./package.tgz \
47
+ --size 120540 \
48
+ --sha256 defbed905af240503da6bad6f171d8e08159eeb16502c0abe0f603a12da09567 \
49
+ --name @agenttool/sdk \
50
+ --version 0.13.0
51
+ ```
52
+
53
+ Exit `0` means a scan found at least one valid core surface, or a local file
54
+ matched. Exit `1` means a scan was inconclusive, a verification mismatched, or
55
+ a requested local operation failed. Exit `2` is invalid usage or target input.
56
+
57
+ ## What it observes
58
+
59
+ The core performs these fixed root-origin probes:
60
+
61
+ | Surface | Probe | Meaning of presence |
62
+ | -------------- | --------------------------------------------------- | -------------------------------------------------------------------------------------- |
63
+ | agent manifest | `/.well-known/agent.txt` | Publisher-provided key/value discovery assertions |
64
+ | pathways | `/v1/pathways` | A publisher-scoped tutorial/release selection, when the supported shape is present |
65
+ | LOVE | `/.well-known/love-packages` | A registry-neutral locator; the index and exact selected manifest may be followed |
66
+ | A2A | `/.well-known/agent-card.json` | A card advertisement at the standard path, not proof of a working task transport |
67
+ | MCP | the unique card URL advertised by valid `agent.txt` | Experimental publisher metadata, not proof of initialization, tools, or authentication |
68
+
69
+ Telescope does not query WebFinger without an exact DID. It reports advertised
70
+ WebFinger and Offer Bus locators but does not fetch feeds, invoke actions,
71
+ settle offers, make payments, initialize MCP, or contact an A2A endpoint.
72
+
73
+ `agent.txt` is parsed at the first colon. Ordered entries and duplicates are
74
+ preserved by the parser; a duplicated selected key is reported as ambiguous and
75
+ is not silently overwritten. Remote instructions and command templates are
76
+ never executed or copied into action argv.
77
+
78
+ ## npm and LOVE plans
79
+
80
+ When a supported Pathways response selects an exact SDK SemVer, Telescope
81
+ reconstructs an npm convenience command from the validated package name and
82
+ version. It does not consult `latest`, npm dist-tags, or an implicit registry
83
+ query. The generated action is marked non-authoritative and says that npm does
84
+ not independently check the LOVE manifest's size and SHA-256. Generated npm
85
+ commands include `--ignore-scripts`, `--no-audit`, and `--no-fund`; importing or
86
+ running installed package code is still execution and remains a separate trust
87
+ decision. npm may still use caller-configured registry credentials to retrieve
88
+ the selected package or declared dependencies; Telescope itself reads none.
89
+
90
+ Telescope validates the manifest's runtime-engine field shape but does not
91
+ evaluate the selected project's runtime compatibility. LOVE install actions
92
+ carry `runtime_engine_compatibility_not_evaluated`; check the declared engine
93
+ constraint in the target environment before installing or importing code.
94
+
95
+ When LOVE discovery, the exact index entry, and its manifest all validate,
96
+ Telescope emits three separate commands:
97
+
98
+ 1. Download one declared public-HTTPS mirror to the manifest's safe filename.
99
+ 2. Stream that same local file, check its exact byte length and SHA-256, reject
100
+ unsafe/unsupported tar entries, and bind embedded `package/package.json`
101
+ name/version to the manifest selection.
102
+ 3. Install that integrity- and archive-checked local tarball with lifecycle
103
+ scripts disabled.
104
+
105
+ The manifest digest is only an expected content commitment until the artifact
106
+ bytes match it. LOVE v1 does not itself authenticate a publisher, and a mirror
107
+ URL is only a locator. Declared package dependencies may still resolve through
108
+ the package manager's configured registry or cache.
109
+
110
+ The generated Node download command does not follow redirects and applies a
111
+ 120-second fetch/body deadline. It also does not repeat Telescope's
112
+ public-address DNS preflight or pin an address at later execution time, so DNS
113
+ may have changed since the report. The exact size/SHA check remains mandatory;
114
+ use a connection-pinned retrieval tool when that network boundary matters. Run
115
+ the download in a caller-controlled directory. Its helper writes to an
116
+ exclusively created random sibling, syncs complete bytes, then publishes the
117
+ exact manifest filename with a no-overwrite hard link. A pre-existing file or
118
+ symlink is refused; handled failures remove only the random partial. A hard
119
+ process interruption can leave a random `.part-*` sibling, never a partial
120
+ final filename.
121
+ `verify-package` requires `agenttool-telescope` on `PATH` (use
122
+ `node dist/cli.js verify-package ...` in a source checkout). Protect the
123
+ file from replacement between verification and install, or re-run verification
124
+ immediately before package machinery. The verifier opens one local file,
125
+ checks its complete outer commitment before decompression, then re-hashes that
126
+ same opened file while parsing the archive and requires stable file metadata.
127
+ This is a point-in-time check, not a file lock or a guarantee about what a later
128
+ package-manager process opens.
129
+
130
+ Every action is returned as `{ executable, argv, display, display_shell }` with
131
+ `automatic: false` and `requires_explicit_consent: true`. Programmatic callers
132
+ should use `executable` plus `argv`. `display_shell: "posix"` names the quoting
133
+ contract; the display string is not Windows `cmd.exe`/PowerShell syntax.
134
+
135
+ ## Network boundary
136
+
137
+ Core requests are public HTTPS GETs with credentials omitted, manual redirects,
138
+ per-document and aggregate byte limits, a total deadline, `Accept-Encoding:
139
+ identity`, and DNS preflight that fails closed if any answer is private, local,
140
+ documentation-only, or otherwise non-global.
141
+
142
+ This is a local-client safety boundary, **not a universal SSRF guarantee**.
143
+ Native `fetch` can resolve DNS again before connecting, so Telescope does not
144
+ pin the validated address to the socket or verify the connected peer address.
145
+ It also does not claim isolation from ambient proxy configuration. Do not expose
146
+ the default transport as a hosted arbitrary-URL scanner. A hosted service would
147
+ need connection-pinned egress enforcement, abuse controls, and a separate
148
+ security review.
149
+
150
+ Only public DNS names on standard HTTPS are accepted. Userinfo, IP literals,
151
+ paths, queries, fragments, local/reserved names, and non-standard ports are
152
+ rejected as scan targets. Response bodies are hashed for provenance but are not
153
+ included in reports.
154
+
155
+ ## Evidence model
156
+
157
+ The JSON schema is
158
+ [`schema/agenttool-telescope-report-v0.1.schema.json`](schema/agenttool-telescope-report-v0.1.schema.json).
159
+ Reports keep these ideas separate:
160
+
161
+ - HTTPS transport observation versus publisher assertion.
162
+ - A locator versus release selection versus expected content identity.
163
+ - An advertised card versus a successfully invoked protocol.
164
+ - Discovery versus authentication, authorization, consent, payment, or safety.
165
+
166
+ There is deliberately no `trusted` boolean and no numeric trust score. HTTPS
167
+ authenticates the connected domain under WebPKI; it does not prove that remote
168
+ claims are true or benevolent.
169
+
170
+ ## Library
171
+
172
+ ```typescript
173
+ import {
174
+ formatTelescopeReport,
175
+ inspectTarget,
176
+ verifyArtifact,
177
+ } from "@agenttool/telescope";
178
+
179
+ const report = await inspectTarget("api.agenttool.dev");
180
+ console.log(formatTelescopeReport(report));
181
+
182
+ const check = verifyArtifact(bytes, {
183
+ size: expectedSize,
184
+ sha256: expectedSha256,
185
+ });
186
+ ```
187
+
188
+ HTTP fetch, DNS lookup, time, abort signals, limits, and optional discovery
189
+ adapters are injectable for deterministic or environment-specific operation.
190
+ Reports name whether the native or an injected transport/resolver was selected.
191
+ Injected transports, resolvers, and adapters are caller-owned code and own the
192
+ behavior of their I/O seams. Adapter facts are included in the report after
193
+ bounded structural validation; adapters must not return credentials or other
194
+ secrets because Telescope cannot universally classify secret-looking content.
195
+
196
+ ## DNS-AID and PKARR
197
+
198
+ Both are extension seams in the 0.1 release, not bundled protocol
199
+ implementations:
200
+
201
+ - Core Node/Bun DNS lookup does not establish DNSSEC validation, and DNS-AID is
202
+ still a changing draft. A future adapter must report secure, insecure, bogus,
203
+ and indeterminate validation states rather than treating a record as proof of
204
+ safe behavior.
205
+ - The available PKARR JavaScript binding is pre-1.0 and contacts public relays
206
+ by default. Telescope therefore does not silently add it, contact relays,
207
+ generate keys, hold private keys, or publish packets. A valid PKARR signature
208
+ would bind bytes to a public key, not a person, DID, domain, benign service,
209
+ or consent.
210
+
211
+ No discovery result grants installation, invocation, bearer use, settlement,
212
+ payment, or consent.
213
+
214
+ ## Development
215
+
216
+ ```bash
217
+ bun install --frozen-lockfile
218
+ bun run typecheck
219
+ bun test
220
+ bun run build
221
+ npm pack --ignore-scripts --dry-run
222
+ ```
223
+
224
+ The package has no runtime dependencies or install lifecycle scripts. Unit
225
+ tests inject all network behavior; live scanning is a separate dogfood check.
226
+ The report schema is exported as
227
+ `@agenttool/telescope/report.schema.json` for tooling that needs the exact
228
+ bundled JSON Schema.
229
+
230
+ Apache-2.0. See `LICENSE` and `NOTICE`.
@@ -0,0 +1,22 @@
1
+ import type { ArtifactExpectation } from "./verify.js";
2
+ export interface NpmTarballExpectation extends ArtifactExpectation {
3
+ name: string;
4
+ version: string;
5
+ }
6
+ export interface NpmTarballInspectionResult {
7
+ ok: boolean;
8
+ code: "verified_npm_tarball" | "integrity_mismatch" | "invalid_or_unsupported_npm_tarball" | "embedded_package_identity_mismatch";
9
+ expected: NpmTarballExpectation;
10
+ actual: {
11
+ size: number | null;
12
+ sha256: string | null;
13
+ };
14
+ archive: {
15
+ entries: number | null;
16
+ package_name: string | null;
17
+ package_version: string | null;
18
+ install_lifecycle_scripts_present: boolean | null;
19
+ };
20
+ }
21
+ export declare function verifyNpmTarballFile(path: string, expected: NpmTarballExpectation): Promise<NpmTarballInspectionResult>;
22
+ //# sourceMappingURL=archive.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"archive.d.ts","sourceRoot":"","sources":["../src/archive.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAYvD,MAAM,WAAW,qBAAsB,SAAQ,mBAAmB;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,0BAA0B;IACzC,EAAE,EAAE,OAAO,CAAC;IACZ,IAAI,EACA,sBAAsB,GACtB,oBAAoB,GACpB,oCAAoC,GACpC,oCAAoC,CAAC;IACzC,QAAQ,EAAE,qBAAqB,CAAC;IAChC,MAAM,EAAE;QACN,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QACpB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;KACvB,CAAC;IACF,OAAO,EAAE;QACP,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;QACvB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;QAC5B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;QAC/B,iCAAiC,EAAE,OAAO,GAAG,IAAI,CAAC;KACnD,CAAC;CACH;AAyWD,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,qBAAqB,GAC9B,OAAO,CAAC,0BAA0B,CAAC,CA2KrC"}