.appveyor.yml

+image:
+  - Visual Studio 2019
+
+environment:
+  matrix:
+    - channel: stable
+      target: x86_64-pc-windows-msvc
+
+    - channel: stable
+      target: i686-pc-windows-msvc
+
+    - channel: beta
+      target: x86_64-pc-windows-msvc
+
+    - channel: beta
+      target: i686-pc-windows-msvc
+
+    - channel: nightly
+      target: x86_64-pc-windows-msvc
+
+    - channel: nightly
+      target: i686-pc-windows-msvc
+
+    - channel: stable
+      target: x86_64-pc-windows-gnu
+
+    - channel: stable
+      target: i686-pc-windows-gnu
+
+    - channel: beta
+      target: x86_64-pc-windows-gnu
+
+    - channel: beta
+      target: i686-pc-windows-gnu
+
+    - channel: nightly
+      target: x86_64-pc-windows-gnu
+
+    - channel: nightly
+      target: i686-pc-windows-gnu
+
+matrix:
+  allow_failures:
+    - channel: nightly
+
+install:
+  - appveyor DownloadFile https://win.rustup.rs/ -FileName rustup-init.exe
+  - rustup-init -yv --default-toolchain %channel% --default-host %target%
+  - set PATH=%PATH%;%USERPROFILE%\.cargo\bin
+  - rustc -vV
+  - cargo -vV
+  - rustup show
+
+build: false
+
+test_script:
+  - cargo test --verbose -F static-sqlite %cargoflags%

.ecrc

+{
+    "Verbose": false,
+    "Debug": false,
+    "IgnoreDefaults": false,
+    "SpacesAftertabs": false,
+    "NoColor": false,
+    "Exclude": [
+        ".(der|pfx)$"
+    ],
+    "AllowedContentTypes": [],
+    "PassedFiles": [],
+    "Disable": {
+        "EndOfLine": false,
+        "Indentation": false,
+        "IndentSize": false,
+        "InsertFinalNewline": false,
+        "TrimTrailingWhitespace": false,
+        "MaxLineLength": false
+    }
+}

.editorconfig

+root = true
+
+[*]
+charset = utf-8
+insert_final_newline = true
+end_of_line = lf
+
+[tests/shadow/shadow.data.template/hosts/**/*{key,cert,KS_hs,KP_hs}*]
+charset = unset
+end_of_line = unset
+insert_final_newline = unset
+trim_trailing_whitespace = unset
+indent_style = unset
+indent_size = unset
+
+[crates/tor-keymgr/testdata/**/*]
+charset = unset
+end_of_line = unset
+insert_final_newline = unset
+trim_trailing_whitespace = unset
+indent_style = unset
+indent_size = unset
+
+[crates/arti/tests/testcases/**/local/state/*]
+charset = unset
+end_of_line = unset
+insert_final_newline = unset
+trim_trailing_whitespace = unset
+indent_style = unset
+indent_size = unset

.flake8

+[flake8]
+
+# This is larger than the default from black.
+#
+# We let black wrap our code to its default width of 88, but
+# we allow comments and strings (which black doesn't touch)
+# to be this wide.
+max-line-length = 99
+
+extend-ignore =
+    # Whitespace before colon in `a[x + 1 :]`
+    # (We allow this for clarity, and so does black.)
+    E203

.gitignore

 /coverage/
 /coverage_meta/
+/coverage_meta_*/
 /target/
 /crates/*/target/
+/crates/*/target-coverage/
+/crates/*/fuzz/coverage/
 /crates/*/fuzz/target/
 /crates/*/fuzz/Cargo.lock
+/crates/*/fuzz-*.log
 *~
+*.tmp
 .#*
 \#*\#
 .cargo
@@ -12,3 +17,5 @@
 /arti-windows.exe
 /arti-macos
 /chutney
+/osxcross
+/.arti_rpc_test

.mailmap

+Clara Engler <cve@cve.cx> <me@emilengler.com>

CODE_OF_CONDUCT

@@ -3,4 +3,4 @@ where people feel safe to engage, share their points of view, and
 participate. For the latest version of our Code of Conduct, please
 see
 
-https://gitweb.torproject.org/community/policies.git/plain/code_of_conduct.txt
+https://community.torproject.org/policies/code_of_conduct/

CONTRIBUTING.md

@@ -4,7 +4,7 @@ We welcome new contributors!  You can get in contact with us on
 [our gitlab instance](https://gitlab.torproject.org/), or on the
 [`\#tor-dev IRC` channel on OFTC](https://www.torproject.org/contact/).
 Make sure to familiarize yourself with our
-[Code of Conduct](https://gitweb.torproject.org/community/policies.git/plain/code_of_conduct.txt).
+[Code of Conduct](https://community.torproject.org/policies/code_of_conduct/).
 
 The new-account process on our gitlab instance is moderated, to reduce
 spam and abuse.  (*Insert instructions for anonymous usage here*)
@@ -21,10 +21,11 @@ conditions.
 The following section is **not** an exhaustive guide, and only covers common
 setup and development tasks.
 
-**Install dependencies**
+**Install build dependencies**
 
 You'll need to have a working Rust environment to build the code, and a
-working Git installation to fetch the code.
+working Git installation to fetch the code. Additionally, please install
+the SQLite 3 development files and shellcheck to successfully run git hooks.
 
 - [Rust](https://www.rust-lang.org/tools/install) note, for Windows devices
   check the
@@ -32,7 +33,42 @@ working Git installation to fetch the code.
 
 - [Git](https://git-scm.com/downloads) note, for Linux, macOS, and some
   Unix-like devices Git may be available via a package manager; `apt`, `brew`,
-  `yum`, `pacman`, etc.
+  `yum`, `pacman`, etc. Git needs to be compiled with PCRE support to allow
+  the use of `git grep -P` in the git hooks. PCRE support is the default in
+  some packages, but if you compile from source set `USE_LIBPCRE=YesPlease`
+  when running `make` or `--with-libpcre` when running `./configure`.
+
+- A C compiler and C build tools (ex: GNU Make).
+
+- SQLite 3 development files (e.g. available via `apt install libsqlite3-dev`)
+
+- Perl and possibly additional Perl packages
+  (depending on your operating system/distro)
+  required to build a vendored version of OpenSSL.
+  These are needed when building or testing with `--all-features`, as recommended below.
+  For example:
+
+  ```bash
+  apt install perl
+  ```
+
+  ```bash
+  dnf install perl-interpreter perl-FindBin perl-lib perl-IPC-Cmd perl-File-Compare perl-File-Copy
+  ```
+  
+- For git hooks: [shellcheck](https://github.com/koalaman/shellcheck#installing)
+  (used in [`maint/shellcheck_all`](./maint/common/shellcheck-all))
+
+**(Optional) install development dependencies**
+
+TL;DR: `./maint/check_env`
+
+If you plan to run scripts inside the `maint/` directory, that are scripts
+such as coverage reports, you'll need a few more dependencies. For this,
+please execute `./maint/check_env`, which will check your host machine if
+all required dependencies are satisfied. If this is not the case, it will
+report the missing ones. Keep in mind that this list is pretty comprehensive
+and not every script requires all of these dependencies.
 
 **Clone the source code**
 
@@ -60,11 +96,13 @@ To get the latest updates, you can run:
 
     $ cargo test --all-features
 
-> Note, if errors similar to "Error: IO error: No such file or directory (os
-> error 2)" involving `cargo-husky`, then check that the `.git/hooks`
-> directory exists, eg.
->
->     $ [[ -d "${PWD}/.git/hooks" ]] || { mkdir "${PWD}/.git/hooks"; }
+**Installing git hooks**
+
+This repository contains some useful [git hooks](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks)
+that you might want to use to help avoid your code failing CI checks.
+You can install them with
+
+    $ cp -v maint/hooks/* .git/hooks/
 
 **Add fork URL**
 
@@ -74,11 +112,16 @@ link to your forked arti repository at:
     $ git remote add _name_ git@gitlab.torproject.org:_name_/arti.git
     $ git fetch _name_
 
-> Tip, replace `_name_` in above, and following, commands to reflect your sign
+> *Tip*: replace `_name_` in above, and following, commands to reflect your sign
 > in name.
 >
-> Note, to fork this repository, or contribute to Issues and Merge Requests
-> requires an account. Check the
+> *Note*: to fork this repository, or contribute to Issues and Merge Requests,
+> you will need an account on our gitlab server.  If you don't have an
+> account there, you can either
+> [request an account](https://gitlab.onionize.space/) or
+> [report a bug anonymously](https://anonticket.onionize.space/).
+>
+> Check the
 > [Sign In](https://gitlab.torproject.org/users/sign_in?redirect_to_referer=yes)
 > page for further instructions on requesting access.
 
@@ -91,49 +134,24 @@ link to your forked arti repository at:
 >
 >      https://gitlab.torproject.org/_name_/arti/-/merge_requests
 
-## Using Arti with Torbrowser
-
-A good first step to start hacking on arti might be to hook it up with your
-Tor Browser. Please note that arti is still a work in progress and hence you
-should assume that it **provides no security** at the moment.
-
-To do so, we will launch arti independently from Tor Browser. Build arti with
-`cargo build --release`.  After that launch it with some basic
-configuration parameters:
-
-    $ ./target/release/arti proxy -l debug -p 9150
-
-This will ensure that arti sets its SOCKS port on 9150. Now we need to launch
-Tor Browser and instruct it to use that SOCKS port.
-
-On Linux:
-
-    $ TOR_SKIP_LAUNCH=1 TOR_SOCKS_PORT=9150 ./start-tor-browser.desktop
-
-On OSX:
-
-    $ TOR_SKIP_LAUNCH=1 TOR_SOCKS_PORT=9150 /path/to/Tor\ Browser/Contents/MacOS/firefox
-
-(You may need to adjust the actual path to wherever you have put your Tor
-Browser.)
-
-When you start Tor browser, it will give you a big red error page because
-Arti isn't offering it a control port interface.  But it will still work!
-Try [check.torproject.org](https://check.torproject.org/) to be sure.
-
-The resulting Tor Browser should be using arti.  Note that onion services
-won't work (Arti doesn't have them yet), and neither will any feature
-depending on Tor's control-port protocol.
-
-Enjoy hacking on arti!
+We prefer not to rebase and squash MRs during the review cycle,
+so if you want to make changes to your MR, please add new commits rather than squashing.
+You can use the
+[`fixup!`](https://git-scm.com/docs/git-rebase#Documentation/git-rebase.txt---autosquash)
+(or `squash!`)
+[autosquash](https://thoughtbot.com/blog/autosquashing-git-commits)
+syntax if it seems best;
+this is a good idea if the un-fixed state breaks the tests or is otherwise broken,
+but is not needed otherwise.
 
 ## Where are some good places to start hacking?
 
 You might want to begin by looking around the
 [codebase](https://gitlab.torproject.org/tpo/core/arti/), or getting to
-know our [architecture](./doc/Architecture.md).
+know our [architecture](./doc/dev/Architecture.md).
 
-More tests would always be great.
+More tests would always be great. You can look at the [coverage reports](https://tpo.pages.torproject.net/core/arti/coverage/)
+to find out what parts need the more love.
 
 Parsing more Tor document types would be neat.
 
@@ -143,9 +161,20 @@ Improvements or bugfixes to the existing code would be great.
 
 Improving the look and feel of the documentation would also rock.
 
-I've made a bunch of notes throughout the document in comments with strings
+We've made a bunch of notes throughout the document in comments with strings
 like "FIXME" or "TODO".
 
+When we have TODOs that we want to fix prior to the release of a particular
+feature or milestone, we define a special TODO format.
+Right now we have "TODO HS" (or "TODO hs") for things we intend to fix
+before we release support for Tor Hidden Services (.onion services).
+
+If you want to make a temporary change that ought *definitely* not to be merged,
+mark it with <code>XX&#88;</code>.
+This will be spotted by the CI, preventing a mistaken merge.
+<!-- that's X X X with no spaces.  Putting it here literally would fail CI :-) -->
+
+
 There is a list of features that I wish other crates had in a file called
 `WANT_FROM_OTHER_CRATES`.
 
@@ -174,3 +203,10 @@ information.
 This code does not attempt to be indistinguishable from the current Tor
 implementation.
 
+When building the docs with `cargo doc`, use `--workspace --all-features`,
+or you may find broken links.
+(We welcome fixes to links broken with `--all-features`.
+`cargo doc --workspace --all-features --document-private-items`
+is also supported, to reveal (unstable) internal information.)
+
+Enjoy hacking on arti!

Cargo.toml

@@ -3,38 +3,86 @@
 # Here we declare that this is a workspace, containing several crates
 # within it.
 #
-# Please keep this list toplogically sorted by dependency relation, so
+# Please keep this list topologically sorted by dependency relation, so
 # that every crate appears _before_ any other crate that depends on it.
+# This also applies to dev-dependencies.
+# We depend on this for publishing to crates.io. e.g.
+# see
+# https://blog.iany.me/2020/10/gotchas-to-publish-rust-crates-in-a-workspace/#cyclic-dependencies
 members = [
+    "crates/oneshot-fused-workaround",
+    "crates/slotmap-careful",
+    "crates/test-temp-dir",
+    "crates/fslock-guard",
+    "crates/hashx",
+    "crates/equix",
+    "crates/tor-basic-utils",
     "crates/caret",
+    "crates/fs-mistrust",
+    "crates/safelog",
     "crates/retry-error",
-    "crates/tor-config",
+    "crates/tor-error",
+    "crates/tor-general-addr",
     "crates/tor-events",
-    "crates/tor-units",
+    "crates/tor-geoip",
     "crates/tor-rtcompat",
     "crates/tor-rtmock",
+    "crates/tor-async-utils",
+    "crates/tor-config",
+    "crates/tor-config-path",
+    "crates/tor-rpc-connect",
+    "crates/tor-log-ratelim",
+    "crates/tor-rpcbase",
+    "crates/tor-memquota",
+    "crates/tor-units",
     "crates/tor-llcrypto",
     "crates/tor-protover",
     "crates/tor-bytes",
-    "crates/tor-socksproto",
     "crates/tor-checkable",
     "crates/tor-cert",
+    "crates/tor-key-forge",
+    "crates/tor-hscrypto",
+    "crates/tor-socksproto",
     "crates/tor-linkspec",
     "crates/tor-cell",
     "crates/tor-proto",
     "crates/tor-netdoc",
     "crates/tor-consdiff",
     "crates/tor-netdir",
+    "crates/tor-relay-selection",
     "crates/tor-persist",
     "crates/tor-chanmgr",
+    "crates/tor-ptmgr",
     "crates/tor-guardmgr",
     "crates/tor-circmgr",
     "crates/tor-dirclient",
     "crates/tor-dirmgr",
+    "crates/tor-keymgr",
+    "crates/tor-hsclient",
+    "crates/tor-hsservice",
+    "crates/tor-hsrproxy",
+    "crates/tor-relay-crypto",
     "crates/arti-client",
+    "crates/arti-relay",
+    "crates/arti-rpcserver",
     "crates/arti-config",
+    "crates/arti",
     "crates/arti-bench",
-    "crates/arti"
+    "crates/arti-testing",
+
+    "crates/arti-rpc-client-core",
+
+    "maint/fixup-features",
+    "maint/keygen-openssh-test",
+
+    "examples/gsoc2023/connection-checker",
+    "examples/gsoc2023/dns-resolver",
+    "examples/gsoc2023/obfs4-checker",
+    "examples/gsoc2023/pt-proxy",
+    "examples/hyper/hyper-http-client-example",
+    "examples/hyper/hyper-http-hs-example",
+    "examples/axum/axum-hello-world",
+    "examples/download-manager",
 ]
 
 resolver = "2"
@@ -44,7 +92,7 @@ resolver = "2"
 # (Assuming xz compression on the binary.)
 #
 # The biggest win is to run `strip --strip-debug` on the binary after
-# generating it, to through out debugging symbols that we inherited from
+# generating it, to throw out debugging symbols that we inherited from
 # other libraries.  Don't do `strip --strip-unused`, though, or you'll
 # break backtraces.  That saves about 21% download size.
 
@@ -57,3 +105,22 @@ codegen-units = 1
 # Optimize for size.  [Actually this is even smaller than 'z' on rust
 # 1.56.  It saves about 11% download size over the default value of '3'.]
 opt-level = 's'
+
+[profile.release.package.slotmap-careful]
+opt-level = 2
+
+[profile.quicktest]
+# This profile is meant to be a compromise between "release" (which
+# takes a long time to build) and "dev" (which can be too slow to actually
+# use when connecting over the Tor network).
+inherits = "release"
+lto = "thin"
+codegen-units = 16
+opt-level = 2
+incremental = true
+
+[profile.bench]
+# For "cargo bench", which is only used by some crates.
+# Inherits release build settings, but adds full debug symbols.
+debug = 2
+strip = "none"

LGPL-3

+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

LICENSE-MIT

-Copyright 2019-2021, The Tor Project, Inc.
+Copyright 2019-2025, The Tor Project, Inc.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -6,17 +6,24 @@ Arti is a project to produce an embeddable, production-quality implementation
 of the [Tor](https://www.torproject.org/) anonymity protocols in the
 [Rust](https://www.rust-lang.org/) programming language.
 
-Arti is **not ready for production use**; [see below](#status) for more information.
-
 ## Links:
 
+This is the README for the Arti project as a whole.
+If you want find more practical information
+you might want to check out these links:
+
+   * [The Arti website](https://arti.torproject.org)
+
+   * [The README for the `arti` binary crate](./crates/arti/README.md),
+     which includes instructions for how to run Arti with Tor Browser.
+
    * [Official source repository](https://gitlab.torproject.org/tpo/core/arti)
 
    * [API-level developer documentation](https://tpo.pages.torproject.net/core/doc/rust/arti_client/index.html)
 
    * [Guidelines for contributors](./CONTRIBUTING.md)
 
-   * [Architectural overview](./doc/Architecture.md)
+   * [Architectural overview](./doc/dev/Architecture.md)
 
    * [Compatibility guide](./doc/Compatibility.md)
 
@@ -49,40 +56,93 @@ needlessly hard to understand and improve.
 
 ## <a name="status"></a>Current status
 
-Arti is a work-in-progress.  It can connect to the Tor network, bootstrap a
+Arti can connect to the Tor network, bootstrap a
 view of the Tor directory, and make anonymized connections over the network.
+Now that Arti has reached version 1.0.0, we believe it is suitable for
+actual use to anonymise connections.
 
-We're not _aware_ of any critical security features missing in Arti; but
-however, since Arti is comparatively new software, you should probably be
-cautious about using it in production.
+There are a number of areas (especially at the lower layers) where APIs
+(especially internal APIs) are not stable,
+and are likely to change them.
+Right now that includes the command line interface to the `arti` program.
 
-There are no guarantees about API stability yet: if you write code
-that uses Arti, you should expect it to break with future versions.  If you
-write an a configuration file for Arti, it might stop working in the future.
+And of course it's still very new so there are likely to be bugs.
 
-## Trying it out today
+## Building and using Arti
 
 Arti can act as a SOCKS proxy that uses the Tor network.
-It knows how to download directory
-information and how to load it from cache, but it doesn't try to
-download more than one directory per run.
 
-To try it out, run the demo program in `arti` as follows.  It will open a
+We expect to be providing official binaries soon.
+But, for now, you need to obtain a
+[Rust](https://www.rust-lang.org/) development environment,
+and build it yourself.
+
+To try it out, compile and run the `arti` binary using the below. It will open a
 SOCKS proxy on port 9150.
 
-    % cargo run --release -- proxy
+    $ cargo run -p arti --locked --release -- proxy
+
+You can build a binary (but not run it) with:
+
+    $ cargo build -p arti --locked --release
+
+The result can be found as `target/release/arti`.
+
+⚠ **Safety Note**: if you are using the default build options,
+the compiler will include filesystem path information in the
+binary that it generates.  If your path is sensitive (for example,
+because it includes your username), you will want to take steps
+to prevent this.  See [`doc/safer-build.md`](doc/safer-build.md)
+for more information.
+
+
+If you run into any trouble building the program, please have a
+look at [the troubleshooting guide](doc/TROUBLESHOOTING.md).
+
+### Custom compile-time options
 
-Again, do not use this program yet if you seriously need anonymity, privacy,
-security, or stability.
+Arti has a number of configurable
+[Cargo features](https://doc.rust-lang.org/cargo/reference/features.html)
+that, among other things, can affect which asynchronous runtime to use.
+
+See in the
+[Arti crate-level docs](https://tpo.pages.torproject.net/core/doc/rust/arti/index.html#compile-time-features)
+for details.
+
+## Using Arti as a library
+
+The `arti` command line utility is built on top of the 
+[`arti_client`](https://tpo.pages.torproject.net/core/doc/rust/arti_client/index.html)
+library (and its dependencies).
+
+That library's API will allow you to
+make connections over the Tor network,
+and obtain streams/sinks usable from async Rust.
+
+We make fairly frequent semver bumps the Arti library API,
+and to our lower-level crates.
+However, in practice, we don't often make disruptive changes
+that aren't easy to sort out in a dependency.
+When using Arti as a library, you should be prepared to make regular updates,
+bumping your versions requirement, not just `cargo update`.
+`cargo upgrade` can help with this.
+
+See [our version update and API compatibility policy](doc/Semver.md)
+for more details.
 
 ## Minimum supported Rust Version
 
-Arti should always build with the most recent _stable_ Rust release, and
-_may_ build with one or two older Rust releases.  Eventually, we may
-declare some long-term Minimum Supported Rust Version (MSRV), but while
-Arti is still in its early stages, you'll need to stay up-to-date.
+Our current Minimum Supported Rust Version (MSRV) is 1.77.
 
-As of this writing (24 August 2021), Arti works with Rust 1.53 and later.
+When increasing this MSRV, we won't require any Rust version released in the
+last six months. (That is, we'll only require Rust versions released at least
+six months ago.)
+
+We will not increase MSRV on PATCH releases, though our dependencies might.
+
+We won't increase MSRV just because we can: we'll only do so when we have a
+reason. (We don't guarantee that you'll agree with our reasoning; only that
+it will exist.)
 
 ## Helping out
 
@@ -113,32 +173,45 @@ get our project manager to sign off on them.
    * [x] Performance: preemptive circuit construction
    * [x] Performance: circuit build timeout inference
    * [x] API support for embedding
-   * [ ] API support for status reporting
+   * [x] API support for status reporting
    * [x] Correct timeout behavior
    * [and more...](https://gitlab.torproject.org/tpo/core/arti/-/milestones/7)
 
  * Arti 1.0.0: Initial stable release (Goal: Mid September, 2022??)
    * Target audience: **initial users**
-   * [ ] Security audit
-   * [ ] Stable API
+   * [x] Stable API (mostly)
    * [ ] Stable CLI
-   * [ ] Stable configuration format
-   * [ ] Automatic detection and response of more kinds of network problems
-   * [ ] More performance work
+   * [x] Stable configuration format
+   * [x] Automatic detection and response of more kinds of network problems
+   * [x] At least as secure as C Tor
+   * [x] Client performance similar to C Tor
+   * [x] More performance work
    * [and more...](https://gitlab.torproject.org/tpo/core/arti/-/milestones/8)
 
  * Arti 1.1.0: Anti-censorship features (Goal: End of October, 2022?)
    * Target audience: **censored users**
-   * [ ] Bridges
-   * [ ] Pluggable transports
+   * [x] Bridges
+   * [x] Pluggable transports
    * [and more...?](https://gitlab.torproject.org/tpo/core/arti/-/milestones/10)
 
- * Arti 1.2.0: Onion service support (not funded, timeframe TBD)
+ * Arti ~1.2.0: [Onion service]() support (Goal: End of 2023)
+   * [x] [Client support](https://gitlab.torproject.org/tpo/core/arti/-/issues/?label_name%5B%5D=Onion%20Services%3A%20Basic%20Client) (for connecting to onion services)
+   * [x] [Service support](https://gitlab.torproject.org/tpo/core/arti/-/issues/?sort=created_date&state=opened&label_name%5B%5D=Onion%20Services%3A%20Basic%20Service&first_page_size=100) (for running onion services)
+   * [ ] [Full security features](https://gitlab.torproject.org/tpo/core/arti/-/issues/?label_name%5B%5D=Onion%20Services%3A%20Improved%20Security) (for production-ready quality)
 
- * Arti 2.0.0: Feature parity with C tor as a client (not funded, timeframe TBD)
+ * Arti ~2.0.0: Feature parity with C tor as a client (Goal: Mid 2024)
+   * [some possible details...](https://gitlab.torproject.org/tpo/core/arti/-/milestones/9#tab-issues)
 
  * Arti ?.?.?: Relay support
 
+## <a name="reporting-bugs"></a> How can I report bugs?
+
+When you find bugs, please report them
+[on our bugtracker](https://gitlab.torproject.org/tpo/core/arti/). If you
+don't already have an account there, you can either
+[request an account](https://gitlab.onionize.space/) or
+[report a bug anonymously](https://anonticket.torproject.org/).
+
 ## How can I help out?
 
 See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for a few ideas for how to get
@@ -148,11 +221,20 @@ started.
 
 This code is licensed under either of
 
- * [Apache License, Version 2.0](http://www.apache.org/licenses/LICENSE-2.0)
- * [MIT license](http://opensource.org/licenses/MIT)
+ * [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0)
+ * [MIT license](https://opensource.org/licenses/MIT)
 
 at your option.
 
+**However**, some optional parts are licensed under the GNU Lesser General
+Public License, version 3.0,
+as indicated in the `Cargo.toml`.
+This applies to `crates/equix` and `crates/hashx`.
+See [`LGPL-and-rust.md`](./doc/LGPL-and-rust.md)
+for discussion of issues concerning redistributing binaries
+containing these crates.
+
+
 ## Contribution
 
 Unless you explicitly state otherwise, any contribution intentionally

WANT_FROM_OTHER_CRATES

@@ -24,6 +24,7 @@ ed25519-dalek:
   (I want a way, given a document D and a signature S, to construct
   a small object representing (SHA(D), S) so that I can check that
   signature later on without having to hold on to all of D.)
+  https://github.com/dalek-cryptography/ed25519-dalek/pull/186
 
 phf:
 * A much cheaper hash function.
@@ -46,6 +47,10 @@ ed25519 trait:
 native-tls:
 * Support for RFC5705 exporters where available.
 
+webpki:
+* Support for cert without extensions and/or without alpn
+  https://github.com/briansmith/webpki/issues/219
+
 
 # Not actually using these crates:
 
@@ -60,11 +65,8 @@ pem: (see arti#146 for discussion)
   base64 multiline.
 * should be stricter?
 
-webpki:
-* Support for cert without extensions and/or without alpn
 
 tls-api:
-* Async support
-* Support for disabling certificate & hostname verification
+* Support for disabling certificate verification
 * Support for getting certificate (or does it have it?)
 * Support for RFC5705 exporters

arti-corpora @ fc8b0825

-Subproject commit ae2b97eae71beee596ba4bce8c126d6990cffb7c
+Subproject commit fc8b0825779af322f353e5226e1936e2abe33163

clippy-nightly.toml

+# Config options appended to clippy.toml when we run Nightly clippy
+#
+# We must edit the tree, this way, sadly:
+#   https://github.com/rust-lang/rust-clippy/issues/8973
+
+# (currently we do not need tohave anything here; everything is dealt with
+# by suppressions maintained by maint/add_warning)

clippy-nontest.toml

+disallowed-types = [
+]
+disallowed-methods = [
+    # Disallow non-memquota bounded queues
+    # (It is hopefully obvious to programmers working on Arti that unbounded queues
+    # shouldn't be used in circumstances where an attacker can cause them to grow without bound,
+    # so we avoid having to wrap/annotate all of those.)
+    { path = "futures::channel::mpsc::channel", reason = "Consider whether to use tor_memquota::mq_queue, or mpsc_channel_no_memquota" },
+    { path = "crossbeam_channel::bounded", reason = "Consider whether to use tor_memquota::mq_queue, or mpsc_channel_no_memquota" },
+    { path = "postage::mpsc::channel", reason = "Consider whether to use tor_memquota::mq_queue, or mpsc_channel_no_memquota" },
+]