3tears-iam
threetears.iam -- the identity and access primitives every authenticating
service in the platform needs: password handling, OAuth2/OIDC, SAML, GitHub
sign-in, session tokens, DPoP, TOTP, WebAuthn, and the anti-automation
controls that keep all of it from being brute-forced.
Why this exists
Two services in this ecosystem grew their own identity layers independently. Both wrote argon2id password hashing with anti-enumeration timing. Both wrote a GitHub OAuth2 authorization-code flow. Both wrote a NATS-KV login throttle, a single-use SHA-256 ticket store, and a JWT mint/verify pair that pins its claim set. Neither could use the other's, because each was welded to its own database schema, its own transport, and its own config prefix.
That is the failure this package exists to stop. The protocol work -- RFC 7636
PKCE, RFC 9449 DPoP, RFC 6238 TOTP, OIDC discovery and id_token verification,
SAML assertion handling, the OAuth2 code exchange -- is the same everywhere.
Getting it subtly wrong is a security bug, and getting it subtly wrong twice
means fixing it twice, in two repos, on two schedules, and finding out the
second one was missed during an incident.
Model
The package owns protocol, crypto, and policy. It owns nobody's database schema and nobody's transport envelopes.
There is one deliberate exception on the wire side, and the reason for it is
narrow. threetears.iam.connection_types holds the shapes that describe an
authentication method to whoever configures it -- what "OIDC" needs, which
fields are secrets, whether the method may be configured per tenant. Two
services had declared those shapes independently, on the usual reasoning that a
cross-repo payload mismatch fails closed. It does not here: something answers
this call, so a divergence is a field silently dropped between the service that
knows what OIDC needs and the operator filling in the form. The shapes are
shared so a mismatch is a type error at install time; the RPC envelopes and
subjects that carry them are still each service's own.
That line is deliberate. The two services that seeded this package disagree on
almost everything below the protocol layer -- one is NATS-RPC-native with a
multi-tenant Postgres identity schema, the other is a FastAPI app with its own
control plane -- and any attempt to unify their persistence would have produced
an abstraction neither could use. So state lives behind narrow Protocols
(SingleUseTicketStore, AttemptLimiter, StateStore), with a NATS-KV
implementation shipped for the common case and nothing stopping a caller from
supplying its own.
Everything else follows from that:
- Pure functions where the protocol allows it. PKCE verification, password policy, step-up freshness, claim mapping, and API-key hashing take arguments and return answers. No I/O, no clock you cannot inject, no global state.
- Algorithms are pinned from literals, never read from the input. A DPoP
proof does not get to say which algorithm verifies it. An
id_tokendoes not get to selectnone. This mirrorsthreetears.core.security.identity_token's discipline, and the pins are written so a static reader can audit them. - Fail closed by default, and without a side channel. A malformed stored hash is an
authentication failure, not a 500. The one place a caller may choose otherwise is
CollectionAttemptLimiter'sfail_open, which exists for a cheap throttle sitting in front of an authoritative check -- it defaults to closed, and a counter with nothing behind it must leave it that way. A rejected password never says which rule it broke when saying so would build an oracle. Errors carry structural reasons only -- never token strings, key material, or credentials -- so they are safe to log at a verification boundary. - Builds on core, does not fork it.
jwk_thumbprint,build_jwks,generate_signing_keypair,ReplayGuard,RevocationGuard,WindowedCounterandseal/open_secretalready exist inthreetears.core. This package imports them.
Public surface
Imported per module -- threetears.iam itself exports only __version__, so reach for the
submodule that owns the thing:
from threetears.iam.passwords import hash_password
from threetears.iam.tokens import SessionClaims, mint_session_token
from threetears.iam.stores.nats_kv import state_store, ticket_store
- Passwords (
.passwords,.breach) --hash_password,verify_password,validate_new_password,normalize_password,PasswordVerifyResult,PasswordPolicyError, plusBreachCorpusfor k-anonymity breach screening. argon2id for new hashes, bcrypt verify-then-upgrade for migrated ones, NFKC normalization always. - OAuth2 / OIDC (
.pkce,.oidc,.github) --PkceChallengeand the RFC 7636 verifier,OidcDiscoveryClient,verify_id_token,OidcIdentity,GithubOAuth2Client,GithubProfile. - SAML (
.saml, extra:saml) --SamlMetadataResolver, assertion identity extraction, relay-state validation. - Sessions (
.tokens,.rotation) --SessionClaims,mint_session_token,verify_session_tokenover EdDSA or HS256,mint_token_pair,TokenPair,sole_audience, androtate_refresh_tokenwith reuse detection. - Proof of possession (
.dpop) --validate_dpop_proof(RFC 9449, ES256/P-256). - Second factors (
.totp,.webauthn) -- TOTP enrolment and verification, backup codes, and (extra:webauthn) passkey registration/assertion helpers. - Anti-automation (
.stores,.clientip) -- theAttemptLimiterProtocol and itsCollectionAttemptLimiterimplementation overthreetears.core.coordination.WindowedCounter, plusresolve_client_ipfor trusted-proxy-aware rate-limit keying. - Auth-method descriptors (
.connection_types) --ConnectionTypeDescriptor,ConnectionFieldDescriptor,ConnectionFieldKind,ConnectionScope: what configuring one authentication method requires, stated in data so an admin surface renders a form per method instead of carrying one. The two security rules ride along as validators -- asecretfield is write-only, androutes_by_domainneedsplatformscope -- so a violating descriptor cannot be built or parsed.typeandkindare plainstron the wire -- an unrecognised method or input control is not dangerous, and refusing a payload over one would cost the operator every other method on the form.ConnectionScopestays closed, because an unreadable scope must not slip past the cross-tenant check as an unknown string. - Storage seams (
.stores) --SingleUseTicketStoreandStateStoreProtocols,hash_ticket/new_ticket_secret, thethreetears.iam.stores.nats_kvimplementations with theirstate_store/ticket_storefactories, and in-memory doubles inthreetears.iam.stores.memoryfor consumer tests.
Install
pip install 3tears-iam
pip install '3tears-iam[saml]' # adds pysaml2; needs the xmlsec1 system binary
pip install '3tears-iam[webauthn]' # adds passkey support
Versioning policy
3tears-iam versions in lockstep with the rest of the 3tears monorepo: every
package shares one version, tracking the framework git tag. All packages move
together.
1 maintainer
Release files for 3tears-iam 0.44.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| 3tears_iam-0.44.0.tar.gz | 130.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| 3tears_iam-0.44.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 225.7 kB
Release files / 3tears_iam-0.44.0.tar.gz
| Download URL | 3tears_iam-0.44.0.tar.gz |
|---|---|
| Size | 130.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
48dd1b45f624fd5ca4de21a3904816daff16fd808c03c49261085df54b39a7ca
|
|
BLAKE2b-256 checksum How to use checksums |
870c29103227273eb138c898c12cfed713a3f526ce3871f7a01a15b4ebd15f7c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 16, 2026.
Transparency logRelease files / 3tears_iam-0.44.0-py3-none-any.whl
| Download URL | 3tears_iam-0.44.0-py3-none-any.whl |
|---|---|
| Size | 95.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1c62c4b40524c1b77ae3714ce9c00dff1a8a08e153b5890cb41895a5618769d3
|
|
BLAKE2b-256 checksum How to use checksums |
98b8a32c4e4c4ba125dec0aaded5df941e0969a03b9ef465d464433c0a45b0da
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 16, 2026.
Transparency log
