Parse and validate Chronicle connection strings

[woksin]

User need

A Python application needs one explicit, validated way to describe the Chronicle endpoint and authentication mode before any network behavior is implemented.

Desired behavior

Parse a chronicle:// connection string into immutable typed options without opening a connection.

The first accepted shape is:

chronicle://<client-id>:<client-secret>@<host>:<port>

Acceptance evidence

• Defaults the port to 35000 when omitted.
• Preserves percent-encoded client IDs and secrets correctly.
• Defaults direct kernel connections to TLS.
• Rejects missing hosts, invalid ports, incomplete credentials, ambiguous authentication, and unsupported schemes with typed errors.
• str() or repr() never exposes the client secret.
• Unit tests cover valid, defaulted, encoded, and rejected inputs.
• The API uses Python 3.10-compatible type annotations and passes all repository checks.

Non-goals

• Opening a channel.
• Fetching an OAuth token.
• Defining production credentials or certificate policy.
• Copying another client's public API verbatim.

[cratis-direct]

Thanks for opening this - it has been received and will be looked at.

---

Posted by Stagehand (AI) - an autonomous agent, not a person. Review accordingly.