authmate 0.1.0__tar.gz

authmate-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+dist/
+build/
+*.egg-info/
+__pycache__/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.hypothesis/

authmate-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AuthMate contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

authmate-0.1.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: authmate
+Version: 0.1.0
+Summary: FastAPI-native identity and authorization contracts
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: <3.15,>=3.11
+Requires-Dist: fastapi<1,>=0.140
+Requires-Dist: pydantic<3,>=2.12
+Description-Content-Type: text/markdown
+
+# AuthMate
+
+AuthMate is a provider-neutral authorization boundary for Python services. Version
+0.1.0 is a stateless contract preview: it validates shared values, coordinates
+principal and authorization providers, and supplies a small FastAPI adapter. It
+does not authenticate requests, persist data, implement RBAC, manage credentials,
+or provide a production-readiness guarantee.
+
+> Independent by default, composable by contract.
+
+## Status
+
+The phase 0.1 runtime is implemented under `src/authmate`. Read the
+[quickstart](docs/quickstart.md) and [planning index](docs/plans/README.md) for the
+public contract and release boundary.
+
+## Supported runtime
+
+Python 3.11 through 3.14. Install this checkout with `uv sync --group dev`.
+AuthMate is distributed under the [MIT License](LICENSE).
+
+## Quick start
+
+Providers are host-owned and implement the protocols in `authmate.protocols`.
+The service calls the principal provider first, then the authorization provider
+only for an enabled, non-expired principal.
+
+```python
+from uuid import uuid4
+from authmate import (
+    AccessContext,
+    AuthMate,
+    AuthorizationDecision,
+    PrincipalKind,
+    PrincipalRecord,
+    PrincipalRef,
+)
+
+actor = PrincipalRef(id=uuid4(), kind=PrincipalKind.USER)
+
+
+class Principals:
+    async def get_principal(self, ref):
+        return PrincipalRecord(ref=ref, display_name="Ada", enabled=True)
+
+    async def aclose(self):
+        pass
+
+
+class Policy:
+    async def authorize(self, *, principal, action, resource):
+        return AuthorizationDecision(
+            allowed=True, reason="allowed", action=action, resource=resource
+        )
+
+    async def aclose(self):
+        pass
+
+
+async def check_request():
+    service = AuthMate(principal_provider=Principals(), authorization_provider=Policy())
+    try:
+        return await service.require(context=AccessContext(actor=actor), action="report.read")
+    finally:
+        await service.aclose()
+```
+
+See [the phase 0.1 quickstart](docs/quickstart.md) for FastAPI integration,
+provider contracts, lifecycle behavior, and deliberate non-goals.
+
+## Development
+
+```sh
+uv sync --frozen --group dev
+uv run ruff format --check .
+uv run ruff check .
+uv run mypy --strict src/authmate tests
+uv run pytest --cov=authmate --cov-branch --cov-fail-under=95
+uv build
+uv run twine check dist/*
+```
+
+## Planned MVP
+
+- Users, operator provisioning, opaque SQL-backed browser sessions, and revocation.
+- Service accounts, revocable API tokens, and generic delegated identity.
+- Exact RBAC scopes, FastAPI dependencies, and Python service APIs.
+- Credential metadata, exact secret-use grants, and approved environment references.
+- Durable SQL audit, rate limiting, CSRF protection, and explicit recovery procedures.
+- Typed public contracts, controlled model/provider extensions, and reviewed migrations.
+
+PostgreSQL is the production reference; SQLite supports local development. No Redis,
+broker, external identity service, or external secret manager is required. Encrypted
+SQL secret storage, federation, tenancy, and richer extensions have later release gates.
+
+## Architecture principles
+
+- AuthMate owns its security semantics and public contracts; consumers adapt to them.
+- Mandatory service checks remain authoritative with custom providers.
+- Pydantic public contracts are separate from SQLModel/SQLAlchemy persistence.
+- FastAPI composition uses explicit DI, lifespan, security, and OpenAPI integration.
+- Core requires SQL-backed state, not process-local caches or additional services.
+
+Hedron, ShuETL, and other applications may build optional adapters against AuthMate.
+Core contains no consumer workflow records, callbacks, domain imports, or release
+dependencies. Consumer-owned compatibility tests establish supported combinations.
+See [Consumer Contracts](docs/plans/CONSUMER_CONTRACTS.md) and
+[MVP gates](docs/plans/MVP.md).

authmate-0.1.0/README.md

@@ -0,0 +1,108 @@
+# AuthMate
+
+AuthMate is a provider-neutral authorization boundary for Python services. Version
+0.1.0 is a stateless contract preview: it validates shared values, coordinates
+principal and authorization providers, and supplies a small FastAPI adapter. It
+does not authenticate requests, persist data, implement RBAC, manage credentials,
+or provide a production-readiness guarantee.
+
+> Independent by default, composable by contract.
+
+## Status
+
+The phase 0.1 runtime is implemented under `src/authmate`. Read the
+[quickstart](docs/quickstart.md) and [planning index](docs/plans/README.md) for the
+public contract and release boundary.
+
+## Supported runtime
+
+Python 3.11 through 3.14. Install this checkout with `uv sync --group dev`.
+AuthMate is distributed under the [MIT License](LICENSE).
+
+## Quick start
+
+Providers are host-owned and implement the protocols in `authmate.protocols`.
+The service calls the principal provider first, then the authorization provider
+only for an enabled, non-expired principal.
+
+```python
+from uuid import uuid4
+from authmate import (
+    AccessContext,
+    AuthMate,
+    AuthorizationDecision,
+    PrincipalKind,
+    PrincipalRecord,
+    PrincipalRef,
+)
+
+actor = PrincipalRef(id=uuid4(), kind=PrincipalKind.USER)
+
+
+class Principals:
+    async def get_principal(self, ref):
+        return PrincipalRecord(ref=ref, display_name="Ada", enabled=True)
+
+    async def aclose(self):
+        pass
+
+
+class Policy:
+    async def authorize(self, *, principal, action, resource):
+        return AuthorizationDecision(
+            allowed=True, reason="allowed", action=action, resource=resource
+        )
+
+    async def aclose(self):
+        pass
+
+
+async def check_request():
+    service = AuthMate(principal_provider=Principals(), authorization_provider=Policy())
+    try:
+        return await service.require(context=AccessContext(actor=actor), action="report.read")
+    finally:
+        await service.aclose()
+```
+
+See [the phase 0.1 quickstart](docs/quickstart.md) for FastAPI integration,
+provider contracts, lifecycle behavior, and deliberate non-goals.
+
+## Development
+
+```sh
+uv sync --frozen --group dev
+uv run ruff format --check .
+uv run ruff check .
+uv run mypy --strict src/authmate tests
+uv run pytest --cov=authmate --cov-branch --cov-fail-under=95
+uv build
+uv run twine check dist/*
+```
+
+## Planned MVP
+
+- Users, operator provisioning, opaque SQL-backed browser sessions, and revocation.
+- Service accounts, revocable API tokens, and generic delegated identity.
+- Exact RBAC scopes, FastAPI dependencies, and Python service APIs.
+- Credential metadata, exact secret-use grants, and approved environment references.
+- Durable SQL audit, rate limiting, CSRF protection, and explicit recovery procedures.
+- Typed public contracts, controlled model/provider extensions, and reviewed migrations.
+
+PostgreSQL is the production reference; SQLite supports local development. No Redis,
+broker, external identity service, or external secret manager is required. Encrypted
+SQL secret storage, federation, tenancy, and richer extensions have later release gates.
+
+## Architecture principles
+
+- AuthMate owns its security semantics and public contracts; consumers adapt to them.
+- Mandatory service checks remain authoritative with custom providers.
+- Pydantic public contracts are separate from SQLModel/SQLAlchemy persistence.
+- FastAPI composition uses explicit DI, lifespan, security, and OpenAPI integration.
+- Core requires SQL-backed state, not process-local caches or additional services.
+
+Hedron, ShuETL, and other applications may build optional adapters against AuthMate.
+Core contains no consumer workflow records, callbacks, domain imports, or release
+dependencies. Consumer-owned compatibility tests establish supported combinations.
+See [Consumer Contracts](docs/plans/CONSUMER_CONTRACTS.md) and
+[MVP gates](docs/plans/MVP.md).

authmate-0.1.0/docs/plans/API_DESIGN.md

@@ -0,0 +1,91 @@
+# API Design
+
+Status: proposed MVP surface, not an implemented API. The configurable router
+prefix defaults to `/api/auth`; all paths below include that prefix exactly once.
+All body-bearing mutations use explicit JSON schemas. No OAuth2 password-grant or
+refresh endpoint is implied by local session login.
+
+## Authentication and sessions
+
+| Method and path | Authority / behavior |
+| --- | --- |
+| `POST /api/auth/login` | Public but origin-checked and rate-limited; sets opaque session cookie |
+| `GET /api/auth/me` | Current authenticated principal; redacted response |
+| `GET /api/auth/csrf` | Browser session; returns session-bound CSRF value, no-store |
+| `POST /api/auth/logout` | Browser session + CSRF; SQL revocation then cookie clear |
+| `POST /api/auth/password/change` | User session + CSRF + current password; revokes sessions |
+| `GET /api/auth/sessions` | User's own session metadata |
+| `DELETE /api/auth/sessions/{id}` | User's own session only; revoke, never disclose token |
+
+Expired/invalid sessions return 401. A restricted temporary-password session can
+only obtain its CSRF value, change its password, or log out. Login, logout, and CSRF behavior is defined in
+[Authentication](AUTHENTICATION.md). No public registration, recovery, or bootstrap
+route is included in MVP.
+
+## Management routes and permission matrix
+
+Each listed permission has the `authmate.` prefix. User/service-account/credential
+creation and top-level listing use realm-level `.create` / `.list` actions; `.manage`
+applies to existing-object read/edit. Roles and role bindings use realm-level
+management actions for all their routes. Nested token/grant operations use their
+parent resource. These are distinct registered actions, not implied suffix matching.
+
+| Paths and methods | Permission | Resource type |
+| --- | --- | --- |
+| `POST, GET /api/auth/users` | `user.create`, `user.list` respectively | realm-level actions |
+| `GET, PATCH /api/auth/users/{id}` | `user.manage` | `authmate.user` |
+| `POST /api/auth/users/{id}/disable`, `/enable` | `user.disable` | `authmate.user` |
+| `POST /api/auth/users/{id}/password-reset` | `user.password.reset` | `authmate.user` |
+| `POST, GET /api/auth/roles`; `GET, PATCH /api/auth/roles/{id}` | `role.manage` | realm-level actions |
+| `POST, GET /api/auth/role-bindings`; `DELETE /api/auth/role-bindings/{id}` | `role_binding.manage` | realm-level actions |
+| `POST, GET /api/auth/service-accounts` | `service_account.create`, `service_account.list` respectively | realm-level actions |
+| `GET, PATCH /api/auth/service-accounts/{id}` | `service_account.manage` | `authmate.service_account` |
+| `POST /api/auth/service-accounts/{id}/disable`, `/enable` | `service_account.disable` | `authmate.service_account` |
+| `POST, GET /api/auth/service-accounts/{id}/tokens`; `DELETE /api/auth/service-accounts/{id}/tokens/{token_id}` | `service_account.token.manage` | `authmate.service_account` |
+| `POST, GET /api/auth/credentials` | `credential.create`, `credential.list` respectively | realm-level actions |
+| `GET, PATCH /api/auth/credentials/{id}`; `POST /api/auth/credentials/{id}/disable`, `/enable` | `credential.manage` | `authmate.credential` |
+| `GET /api/auth/credentials/{id}` (alternative read-only authority) | `credential.read_metadata` | `authmate.credential` |
+| `POST, GET /api/auth/credentials/{id}/grants`; `DELETE /api/auth/credentials/{id}/grants/{grant_id}` | `credential.grant.manage` | `authmate.credential` |
+| `GET /api/auth/audit-events` | `audit.read` | realm-level action |
+
+A management role explicitly includes all required create/list/manage entries;
+there is no implicit permission hierarchy. Do not overload `resource=None` to
+authorize a resource action. Credential detail can use either listed authority;
+that OR is explicit and grants no secret access. Grant deletion also checks that
+the supplied grant ID belongs to the authorized parent credential.
+
+`authmate.service_account.assume` is a resource permission assigned through ordinary
+role bindings. It governs generic delegated service calls, not a workload binding
+API. Consumer workflow/approval records never become AuthMate management endpoints.
+
+The environment provider is read-only. No secret upload, secret read, or rotation
+route ships in MVP. A later writable-provider API requires capability-specific
+schemas and the encrypted-provider release gate. Service-account token creation
+is a deliberate one-time secret response; all other reads return metadata only.
+
+## Enforcement and error contract
+
+Use APIRouter, explicit Pydantic request/response models, and server-side service
+checks even for in-process callers. PATCH schemas allowlist editable fields and
+reject unknown/reserved fields. Require version/If-Match on concurrent metadata,
+role, and grant-policy edits; stale writes return 409. DELETE/revocation operations
+are idempotent within caller authority; nested IDs must belong to the parent object.
+
+Collection routes require the corresponding realm list/management/audit authority;
+credential grants and tokens are scoped to their parent. Authorize/filter in SQL before
+pagination/counts. Own a bounded Page schema: default 50, maximum 100, deterministic
+sort with ID tie-breaker, and opaque cursor where supported. Audit paging uses a
+stable time/ID cursor. A cursor is an untrusted input, never authorization evidence.
+
+Errors use `{ "code": "...", "message": "...", "request_id": "..." }`.
+Return 401 for invalid/missing identity, 403 for known prohibited operations, 404
+for missing or undiscoverable detail resources, 409 for stale/conflicting writes,
+422 for sanitized validation failures, 429 for throttling, and 503 for security
+state/provider/audit unavailability. Reject unsupported JSON media types before
+service invocation (415). Use WWW-Authenticate on bearer 401 responses. Do not expose
+SQL/provider exceptions, raw rejected input, hashes, tokens, or permission internals.
+
+Document cookie/CSRF and HTTP bearer schemes truthfully in OpenAPI. Resource RBAC
+is checked by services; OAuth scopes do not encode it. Auth/session/token responses
+use Cache-Control: no-store. AuthMate-scoped error handling must not overwrite the
+host application's handlers globally; see [FastAPI Strategy](FASTAPI_STRATEGY.md).

authmate-0.1.0/docs/plans/ARCHITECTURE.md

@@ -0,0 +1,73 @@
+# Architecture
+
+AuthMate is an embeddable FastAPI identity, authorization, and credential package.
+It defines its own public contracts independently of consumer applications.
+
+```text
+FastAPI routers/dependencies       Trusted Python/background callers
+                 \                  /
+                  AuthMate service facade
+                  /         |          \
+           Identity   Authorization   Credentials
+                  \         |          /
+                   SQL unit of work + audit
+                        |         \
+                   Persistence    Secret-provider adapters
+```
+
+Mandatory checks live in service wrappers, so direct Python calls cannot accidentally
+skip rules enforced only by HTTP routes. Providers supply mechanisms behind those
+checks. Audit is part of each protected operation, not an asynchronous afterthought.
+Secret-provider I/O is bounded and happens outside held SQL write locks; release
+requires a final current-state check and committed audit event.
+
+## Composition and contracts
+
+FastAPI dependencies handle current identity, permission enforcement, and resource
+lookup. A resource-specific dependency must derive its ResourceRef from a trusted
+lookup; `require_permission("myapp.report.read")` without a resource is insufficient
+for an exact-resource action. Python `can`, `authorize`, `require`, and credential
+resolution use explicit context and do not need HTTP request state.
+
+[Consumer Contracts](CONSUMER_CONTRACTS.md) defines PrincipalRef, AccessContext,
+ResourceRef, decisions, provider protocols, and lifecycle/error semantics. Consumers
+register generic action/resource namespaces and adapt their own APIs to AuthMate.
+Core never imports Hedron, ShuETL, ETLantic, or their ORM/domain models. Their adapters
+and compatibility tests are consumer-owned and cannot block a core release.
+
+AuthMate owns identity/security semantics and reuses maintained hashing, validation,
+SQL, and optional cryptographic/protocol libraries behind implementation adapters.
+Public Pydantic values remain separate from persistence/provider objects. SQLModel
+models represent ordinary internal tables; SQLAlchemy handles explicit transactions,
+async sessions, locking, and advanced queries.
+
+## Deployment and state
+
+Default production deployment is one or more FastAPI processes plus PostgreSQL.
+SQLite is a local-development backend. SQL stores session/token digests, security
+state, roles/grants, credential metadata, rate-limit state, and durable audit. Correctness
+never relies on process-local positive caches, a cleanup timer, Redis, or a broker.
+
+Environment-backed secret references are the MVP provider. External identity/secret
+services and the encrypted SQL provider are optional later capabilities. Process
+configuration, TLS, operator-provisioned secrets, backups, and reviewed migrations
+remain deployment responsibilities even though no additional service is mandatory.
+
+Each AuthMate instance has its own explicit configuration/provider registry and unit
+of work. No module-global current user, service locator, or shared request session.
+Host lifespan explicitly enters/closes AuthMate resources; failed startup cleans up
+partially opened providers. Async sessions never outlive their operation or cross
+concurrent tasks. See [FastAPI Strategy](FASTAPI_STRATEGY.md).
+
+## Schema and isolation
+
+AuthMate owns only its registered `authmate_*` tables and migration history, even
+when it shares a database with consumers. User/service-account metadata extensions
+use a validated model registry and reviewed migrations. Production startup verifies
+schema compatibility; it does not generate or automatically apply DDL. See
+[Persistence and Managed Migrations](MIGRATIONS.md).
+
+MVP supports one security realm per deployment. Namespaces partition action names,
+not tenants. Generic resource strings or custom claims do not establish tenant
+isolation. Strong tenant boundaries require a future schema/contract design or
+separate deployments today.

authmate-0.1.0/docs/plans/AUTHENTICATION.md

@@ -0,0 +1,122 @@
+# Authentication and Sessions
+
+Status: selected MVP design; implementation and security gates remain open.
+
+## Default transport and state
+
+MVP uses opaque, SQL-backed sessions, not self-contained JWTs or refresh tokens.
+Browser login sets a cookie; it does not return a bearer token in JSON. Machine
+clients use separately issued service-account API tokens. JWT/OIDC adapters and
+custom token claims are later features, not prerequisites for local login.
+
+Generate authentication tokens with 32 bytes from a CSPRNG. Store a SHA-256 digest of the random
+secret, never the raw token. This fast digest is for high-entropy tokens only;
+passwords use Argon2id. Use token-type prefixes and separate lookup/state tables
+so a machine token cannot be accepted as a browser session. Never accept tokens
+in query parameters. Multiple supplied authentication mechanisms are rejected
+rather than resolved by implicit precedence.
+
+Each session stores principal ID, creation/last-activity times, idle/absolute
+expiry, revocation time, and the principal's authentication epoch at issuance.
+Create a fresh session ID on every successful login; never adopt a supplied ID.
+Every authenticated operation checks current SQL state, principal enabled state,
+epoch, and expiry. Baseline has no process-local positive authorization cache.
+Use database time for expiry and atomic conditional activity updates so races
+cannot resurrect revoked or expired sessions. Proposed defaults: 30-minute idle
+and 12-hour absolute lifetime; operators can shorten both. No sliding update
+extends absolute expiry. OWASP motivates server-side state, unpredictable IDs,
+and server-enforced expiry; these exact defaults are AuthMate design choices.
+[Source: OWASP session guidance](https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html).
+
+Logout revokes the session in SQL before reporting success and clears the cookie.
+Password change/reset and principal disable atomically increment the authentication
+epoch and revoke all sessions/tokens for that principal. Re-enabling never revives
+old tokens. Role/grant removal affects the next authorization check through fresh
+SQL evaluation, without requiring logout. See the concurrency boundary in
+[Identity and Authorization](IDENTITY_AND_AUTHORIZATION.md).
+
+## Browser protection
+
+Use a deployment-unique `__Host-` cookie name, `Secure`, `HttpOnly`, `SameSite=Lax`,
+`Path=/`, and no Domain attribute. Plain HTTP cookies require an explicit local
+development profile rejected by production readiness. Cookie paths do not isolate
+mutually untrusted apps on one origin; those apps need separate origins.
+
+For unsafe cookie-authenticated requests, require both an exact configured Origin
+(or validated Referer origin fallback) and a session-bound CSRF token in a custom
+header. Obtain that token through authenticated `GET /api/auth/csrf`, with no-store
+responses and no permissive credentialed CORS. The CSRF value is an independent
+random per-session value stored in the session row and compared in constant time;
+it cannot authenticate a request and never substitutes for the opaque session cookie. Login itself requires an allowed
+origin and JSON content type, including before a session exists. Logout and login
+are never GET operations. Reject missing/invalid origin evidence for browser
+mutations; machine bearer endpoints do not use cookie authentication. Strict JSON
+content type supplements CSRF checks; it does not replace them.
+
+Cookies, CSRF values, password inputs, and token responses are excluded from
+access logs, tracing, validation error input, and caches. TLS termination and
+forwarded client IP headers are trusted only from explicitly configured proxies.
+
+## Local users and password lifecycle
+
+MVP login uses a unique normalized username; email is optional metadata, not an
+alternate unverified login identifier. Normalize usernames once (NFKC + casefold),
+store a separate display name, and enforce canonical uniqueness in SQL on both
+backends. Never normalize, trim, or silently truncate passwords.
+
+Use `pwdlib[argon2]` with explicitly configured Argon2id parameters, unique salts,
+and rehash-on-success. Start at 64 MiB, 3 iterations, parallelism 1; benchmark under
+bounded login concurrency before release. Never configure below the reviewed
+minimum of 19 MiB, 2 iterations, parallelism 1.
+[Source: OWASP password storage](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html).
+Accept 15–128 Unicode characters and at most 1024 UTF-8 bytes; allow spaces and
+password managers, reject a shipped common-password list, and impose no composition
+rules or routine forced rotation. Password policy and hashing cost are versioned
+settings, not whatever a library changes its defaults to.
+
+Unknown users perform dummy hash verification. Unknown, disabled, and incorrect
+password cases share a generic 401 response. Hash work runs off the event loop
+with bounded concurrency. A SQL rate limiter reserves attempts atomically before
+hashing, using independent account-name and source-IP windows. Initial defaults:
+5 attempts/account/5 minutes and 50 attempts/IP/5 minutes, including failures and
+unknown users; return generic 429 with Retry-After. Bound key cardinality with a
+global attempt budget and expire buckets. Tune these defaults with documented
+load/abuse tests; process-local hooks are insufficient across replicas. SQL failure
+denies login. Rate limiting reduces guessing but can be abused to deny service.
+
+Self-registration, email verification, email-based recovery, MFA, and invitation
+flows are deferred. Provisioning and recovery use an operator command or an
+explicitly privileged management operation; never a public bootstrap endpoint.
+Initial bootstrap uses a single-use SQL guard in the same transaction as the
+first administrator binding and audit event, so concurrent processes cannot both
+bootstrap. Input passwords through a hidden prompt/secure input, not CLI arguments
+or logs. Provide an audited operator recovery procedure using database access.
+An administrator can set a temporary password with a `must_change_password` flag;
+that login yields only a password-change capability (plus CSRF retrieval and logout)
+until successful replacement.
+Self password change requires the current password and revokes existing sessions.
+Hash verification happens outside SQL locks; login and password changes then acquire
+the security-state guard and recheck the hash/epoch, enabled state, and restriction
+flag before committing. A concurrent reset/disable invalidates the pending issuance.
+Rehash-on-login uses a conditional update so it cannot overwrite a concurrent reset.
+
+## Service-account API tokens
+
+A trusted co-located executor need not mint a bearer token to use a service account;
+its authority comes from the generic AccessContext and assumption permission in
+[Consumer Contracts](CONSUMER_CONTRACTS.md). An arbitrary principal ID is not proof
+of authority at an HTTP or job boundary.
+
+Remote clients may receive an opaque API token only through a caller with
+`authmate.service_account.token.manage` on that account. This permission permits
+impersonation and is distinct from metadata editing. Reveal the token exactly once
+in the creation response, with Cache-Control: no-store. Store its digest, account
+ID, creation/expiry/revocation timestamps, authentication epoch, and display prefix.
+Default expiry is 24 hours with a configurable finite maximum of 30 days. Tokens
+inherit the account's current permissions; narrower token scopes are deferred and
+must not be implied. Use separate accounts for distinct privilege sets.
+
+API-token rotation creates a new token and explicitly revokes the old one; any
+overlap must be bounded by an explicit expiry. Do not retry issuance automatically
+after an ambiguous response; list token metadata, revoke an uncertain token, and
+issue another. Token values are never recoverable from read/list endpoints.

authmate-0.1.0/docs/plans/CONSUMER_CONTRACTS.md

@@ -0,0 +1,69 @@
+# Consumer Contracts
+
+Status: proposed AuthMate-owned contracts to validate through implementation.
+Consumers adapt to these interfaces; consumer release schedules and domain models
+do not define AuthMate core. Method names below are planned, not currently callable.
+
+## Public values and protocols
+
+| Contract | Meaning and boundary |
+| --- | --- |
+| `PrincipalRef` / `PrincipalRecord` | Immutable ID/kind and explicitly public identity metadata; never ORM objects or authentication proof |
+| `AuthenticationResult` | Validated actor identity plus mechanism/time/assurance from a trusted authenticator |
+| `AccessContext` | Verified actor and optional effective service account; generic delegation is validated by AuthMate |
+| `ResourceRef` | Exact registered type and canonical ID supplied by a trusted consumer lookup |
+| `AuthorizationDecision` | Allow/deny with safe reason and diagnostic policy revision; a snapshot, not a capability |
+| `PrincipalProvider` | Fetch current principal state through authorized service access; a returned ID does not authorize impersonation |
+| `AuthorizationProvider` | Evaluate default RBAC or a selected custom policy inside mandatory AuthMate checks |
+| `CredentialResolver` | Resolve an exact credential for AccessContext after current-state checks and durable audit |
+| `SecretProvider` | Low-level backend mechanics behind CredentialResolver; not a public authorization bypass |
+| `AuditSink` | Optional delivery target for already committed typed events; SQL audit remains authoritative |
+
+Public service operations take explicit context and parameters, use async contracts,
+and raise typed AuthMate domain errors. `can()` is advisory; `authorize()` returns a
+decision; `require()` enforces or raises. FastAPI dependencies adapt transport to
+these services. Background callers use the same services without constructing an
+HTTP Request or depending on a request-scoped database session.
+
+## Delegation and credentials
+
+For direct use, actor equals effective principal. For delegated use, the authenticated
+actor must hold `authmate.service_account.assume` on the effective account, and that
+account must independently hold the requested permission or exact credential-use
+grant. AuthMate checks both principals' current state. Assumption does not union
+roles, authorize arbitrary token issuance, or recursively assume another account.
+
+An executor, automation, or administrative tool can use this generic contract.
+AuthMate does not require a pipeline, job, schedule, approved-version field, or
+consumer callback. The consumer owns constraints tying its operation to the chosen
+account/resource/credential. Correlation and initiating-user metadata are audit
+context only and cannot authenticate an actor or broaden its authority.
+
+## Ownership
+
+AuthMate owns authentication, current principal state, role/scope semantics, generic
+assumption permission, credential grants, secret release, and its audit/SQL schema.
+Consumers own their resource existence, action registration/mapping, workflow
+approval, domain data, execution lifecycle, output redaction, and any additional
+business rules. They must enforce their rules before external effects and cannot
+turn UI visibility or a prior decision into durable authorization.
+
+An adapter belongs with the consumer or in a separate package depending on both
+published APIs. No consumer-specific imports, schema, feature checks, validation
+callbacks, or release gates belong in core. AuthMate's conformance tests use generic
+report resources and a fake background client, proving the contract without sibling
+repositories. Consumer adapters run their own real-version compatibility suites.
+
+## Errors, lifecycle, and versioning
+
+Distinguish unauthenticated, denied, not-found/hidden, invalid reference/config,
+conflict, unsupported capability, and unavailable errors. No provider failure means
+allow. Metadata and error objects must never contain resolved secrets or raw tokens.
+Providers define timeout/cancellation/cleanup, and services commit mandatory audit
+before acknowledging protected mutations or releasing secret material.
+
+Registries freeze at startup; duplicate/conflicting registrations fail. Publish a
+contract/schema version and a compatibility policy before stable release. Pre-1.0
+changes must include migration notes and conformance updates; no promise of a frozen
+protocol before the first end-to-end implementation. Adapter authors receive typed
+examples and the same conformance suite used by default providers.