Your agent needs the password. It does not need to see it.

There is a moment in almost every agent session where the work needs a password. A website login to check a page as a signed-in user. The sudo password on a Linux box. An account the agent has to do its job inside. And at that moment you have two bad options and one you have not been offered.

Type it into the session, and it is in the transcript - which is stored, scrolled back through, and quite possibly read aloud. Put it in a file in the repository, and sooner or later it is in a commit. Neither of those is a mistake anybody makes on purpose. They are what happens when the only two doors are both wrong.

The third door

cc-secrets is a command-line tool that ships in the toolbelt. It keeps a store on Windows and on Linux; on a Mac it refuses to create or read one, because a file's access control list there can let another account read it even when the permissions look private. You store the password once, by hand, on the machine that needs it. After that a session does not ask for the password - it asks the tool to do the thing the password is for, and gets back only the result.

• There is no command that prints a password. A session can list which entries exist, see their user names and the sites they belong to, and use them. It cannot read one out. That is the whole design in one sentence.
• You add entries, never a session. The add command refuses to run inside a DevThrottle session, because a password entered through a session has already been in the transcript. You open an ordinary terminal window and add it there, or pipe it in from your password manager.
• Two switches decide what a session may do with an entry. One says whether sessions on this machine may use it at all; the other limits it to running a command, to filling a login form, or both. An entry held back does not appear in a session's list, and using it gets the same answer as a name that does not exist - so a refusal never reveals which entries you are holding back.
• Every use is written down. The audit log records the time, the entry, the session that asked, the machine, the command and the outcome. A line that would contain the password is refused before it reaches the disk.

Running a command with a password

The everyday shape is: run this command, and supply the password to it. The tool can hand it over on standard input, which is what a sudo prompt reads, or in one environment variable, or through the askpass helper that sudo, ssh and git already understand.

The part worth knowing is what happens on the way back. The command's output is captured whole and cleaned before anything is shown - not streamed, because a password split across two chunks of output would slip past a check that looked at each chunk alone. It is removed as typed and in the forms output tends to carry it in: escaped for JSON, HTML or Python, percent-encoded, base64, hexadecimal. If the output still cannot be shown safely, it is withheld entirely.

Filling a login form

The other use is a browser login, and this is where the checks get strict, because a page can lie about where it is sending what you type. Before anything is typed, three things are checked against the addresses the entry allows: the tab's address read from the browser itself, where the form will send what is typed, and that it will send it by POST - a GET form would put the password in the address bar and the browser history.

From just before the password is typed until the tab has been cleaned, every request that tab makes is paused and judged, and a redirect is judged again at each hop. Afterwards the tab is made safe and that is confirmed rather than assumed: password fields emptied, history reset, the tab read back to check. If it cannot be confirmed the tab is closed, and if it cannot be closed the login fails and tells you to close it yourself.

One limit, because it will come up: if the site asks for a two-step code or a captcha, the answer is verification and you finish that login by hand.

What it does not protect against

This is the part most tools leave out, so it goes here rather than in small print. What cc-secrets protects against is accidental exposure - in transcripts, logs, command output and screenshots. It is not a defence against a hostile program running as you.

• The store is a file, protected by file permissions, not encryption. Any process running as your user can open it, including the shell a session runs in. The rule that the model never sees a password is kept by the tool never printing one.
• The clean-up catches accidents, not intent. A command that deliberately transforms the password - reverses it, splits it across lines - produces output with no recognisable form of it left to catch. What limits that is the entry's own settings, and what records it is the audit log.
• Nothing syncs. Each machine has its own store, one per operating-system user, and nothing is kept on the Gateway. Add an entry on every machine whose sessions need it.

The commands, the allowed-address rules, the exit codes and the full list of limits are in the reference: cc-secrets.