identity

Identity Module

This optional package belongs to the v0.2 line in the existing Foundation Go module; immutable v0.1.0 has no Identity/Audit implementation. Descriptor.Version reports the actual packaged Foundation dependency through achrix.Version(). The existing ModuleVersion constant is retained only as a deprecated unpublished source-line label, not component/update/recovery identity. Public Go declarations own exact signatures. Identity owns product-local accounts, password credentials and opaque server-side sessions; products own profiles, roles, permissions and configuration. No central service, self-registration, recovery/email, MFA, OIDC or tenant model is supplied.

Composition and authorized operations

Use audit.Migrate(ctx, dsn) and identity.Migrate(ctx, dsn) as explicit installation actions against the same product-owned PostgreSQL 18 UTF-8 database. Each context needs a deadline. Startup verifies existing migration checksum/version/columns; it does not migrate. Construct both PostgreSQL Modules, then an achrix.Application with a product Policy; construct audit.NewService(app, auditModule) followed by identity.NewService(app, identityModule, auditService). The Service rejects mismatched database profiles. Identity requires Core authorization ABI 2 and Audit append ABI 1, ordering Audit before Identity on startup and after it on shutdown.

The product must explicitly permit only Authentication for PublicPrincipal to expose credential/session attempts. This principal is never the successfully authenticated account and conveys no product rights. Login/session operations traverse that Core admission decision before expensive/database work; each subsequent product operation must separately authorize the returned account principal.

CreateAccount, Account, LookupAccount, SetPassword, SetEnabled, RevokeAll and ChangePassword have separate capabilities. Account returns current status/revision without secrets; conditional credential/status mutations require that revision. Account/status/credential/revoke-all transitions serialize against issuance through an account row lock and revision fence, revoke every session and reject overflow. Even a repeated status intent advances revision and writes its accountable event. Self-change separately authorizes the authenticated principal against its own account, verifies the current password, then rechecks the initiating live token under the account fence before committing.

LookupAccount(ctx, actor, exactLogin) reconciles a create whose database or HTTP acknowledgement was lost and whose generated ID was not received. It validates the existing login syntax/case contract, separately authorizes AccountLookup against that exact login before any account query, and returns only Account metadata. The existing unique login index bounds this exact read; there is no account list, fuzzy search, credential/session join or normalization. Missing metadata returns ErrNotFound only after authorization. AccountRead, public authentication and successful login do not imply this permission. A product must explicitly grant this protected capability to a suitable operator and retain the original login before sending create; an absent result alone does not prove an earlier interrupted transaction can never commit, so do not automatically replay a create.

Five successful event classes are atomic-required: account create, administrative credential set, own credential change, account status set and revoke-all. Each prepares an authorized Audit record before domain mutation, then calls Audit-owned append SQL in the same transaction. Any append error rolls back domain and audit state. Duplicate-login/stale-revision outcomes are conflicts. Cancellation/provider failure is safe unavailability and never promises that replay is harmless: a connection failure while committing can leave an unknown result. Read the current account revision/history before retrying; there is no automatic retry. Ordinary login/session traffic and invalid/denied requests are operational behavior, not durable Audit records in this slice.

Passwords, sessions and time

Passwords use maintained github.com/alexedwards/argon2id v1.0.0 over x/crypto Argon2id. PHC records preserve algorithm/version/cost; default memory 19 MiB, iterations 2, parallelism 1 follows the reviewed OWASP minimum. Supported bounds are memory 19–64 MiB, iterations 2–4 and parallelism 1–2, with random 16-byte salts and 32-byte keys. Stored PHC length, version, cost and sizes are checked before the library allocates; compatible weaker parameters can deliberately rehash after successful verification without silently downgrading stronger records. New passwords require 15–256 Unicode code points and at most 1024 UTF-8 bytes, without truncation/normalization. Login handles are bounded lowercase ASCII identifiers; they are not email/profile semantics.

Nonqueued hash admission admits at most two synchronous computations. Argon2 cannot be forcibly interrupted; cancellation is checked before/after. Whole expensive Service operations hold Module work leases, so shutdown closes admission, cancels and waits for them before pool closure. Config.MaxOperations bounds active owned leases, including nested database work (zero defaults to 16; explicit minimum two). Config.MaxConns bounds the instance pool (zero defaults to four; explicit minimum one). Credential mutations and login can hold an outer work lease plus a nested database lease; the minimum preserves an isolated supported operation, without promising fairness for concurrent nested work. Products still stop ingress and drain their domain work before Core shutdown. Parsed pool DSN options cannot override typed effective limits or the other fixed resource policy. Operations owns aggregate budgets and native demand-based pool behavior. The pgx parser's standard connection configuration/environment semantics remain part of the driver; products supply and protect an explicit DSN/profile rather than relying on ambient defaults.

On 2026-10-02, Go 1.27.1/Linux amd64 on the development server (two vCPU, AMD EPYC 7763, approximately 3.7 GiB RAM) measured three runs of three hashes per profile: default 21–25 ms/hash, approximately 19 MiB allocated; supported maximum 96–104 ms/hash, approximately 64 MiB allocated. These observations exclude constructor/dummy-hash setup and are not a production capacity claim or a reason to reduce the security floor. Reproduce with go test -run '^$' -bench '^BenchmarkPasswordHash' -benchmem -benchtime=3x -count=3 ./identity; a real deployment must measure and choose an intentional policy within the bounds.

Supplemental accepted raw benchmark evidence for unchanged password/hash code at candidate b505b1d18a7a7fb14c9b42ec5e06f256f0610dd3, using the same development environment and command above, measured default 22.75–33.16 ms/hash and supported maximum 173.84–186.03 ms/hash, with approximately 19/64 MiB allocated respectively. These later load-dependent samples supplement the earlier observations; neither range guarantees product latency/capacity or justifies lowering the security floor.

Session and CSRF tokens are independently generated 256-bit random opaque values. PostgreSQL stores SHA-256 hashes, never bearer/CSRF plaintext. General Session formatting, JSON secret fields and slog values are redacted; the deliberate web response includes a CSRF token but never the bearer. Login always issues a fresh token and revokes a supplied valid previous cookie in the same transaction, including account switches. Rotation is single-winner and preserves original absolute expiry; default lifetime is eight hours, configurable from one minute to 24 hours. This slice has no idle-timeout/sliding expiry. Each account holds at most 16 active session rows; expired rows are cleaned on issuance. Revocation, disabled status, changed revision and expiry fail closed. All persisted times/decisions use trusted concurrent-safe Config.Now, UTC and PostgreSQL microsecond precision; the time source must not move backwards for security decisions.

Same-origin HTTPS web boundary

NewWeb(service, exactHTTPSOrigin) provides relative /login, /csrf, /rotate, /logout, /password handlers and AuthenticateRequest for the product's own Application adapter. Actual TLS and exact Host are required; forwarded headers are not trusted. The product must terminate TLS here or supply a separately reviewed trusted proxy boundary. Mount one Web instance per authentication boundary so its shared budget covers every request. There is no CORS or cross-subdomain sharing.

The nonpersistent __Host-AChrix-Session cookie has Secure, HttpOnly, SameSite=Strict, Path=/ and no Domain. Session authentication is cookie-only; adapter requests with query strings are rejected. Mutations require a session-bound synchronizer X-CSRF-Token plus exact Origin (or single same-origin HTTPS Referer when Origin is absent). Every authentication endpoint additionally requires the non-simple X-Identity-Request: 1 header, including initial login. The same-origin /csrf endpoint refreshes the synchronizer token, invalidating the previous one; keep it in response/application memory, not URLs/cookies/persistent browser storage. These controls complement the reviewed OWASP session and CSRF guidance; they do not replace product XSS defenses or permissions.

Bodies are single strict JSON documents, 2 KiB maximum, with no unknown/trailing values. All responses are non-cacheable, nosniff, no-referrer and deny framing. The public login path uses a fixed 60/minute global budget plus 10/minute per socket-peer hash bucket in a fixed 256-entry table; collisions conservatively share a budget. No attacker-selected map/cardinality, queue or per-failure Audit/log is created. A 16-request admission limit and five-second Application operation contexts supplement the hash/pool limits. Strict JSON decoding additionally sets an actual two-second transport read deadline (or the earlier caller deadline) through net/http ResponseController; unsupported writer wrappers fail closed before decoding, and wrappers must expose Unwrap/deadline support. Context expiry alone does not bound Body.Read. Product servers also require bounded header reads, total reads/writes, idle duration and header size; the TLS proof composes those outer bounds explicitly. Real proxy/address topology and legitimate traffic policy need a supported deployment profile before tuning. Operational database failures expose only safe categories and emit at most one diagnostic per Module per second; products own slog threshold/correlation/handler policy under Operations.

Validation and retained state

scripts/validate.sh full runs real PostgreSQL account/session/concurrency/migration/atomic Audit failure tests, a cold pinned public Notes composition with real HTTPS authentication followed by product authorization, and native logical capture/restore of the retained joint dataset. Tests use dedicated private databases with guarded names. Source/configuration and both migration identities must remain available to interpret credentials and history. Backups contain sensitive password/session hashes and require access protection. Partial Identity-only/Audit-only restore is unsupported; after actual recovery, reconcile changed credentials/revocations and revoke restored sessions before reopening ingress. This proof is integration-only, not a production CMS or activation of paused #19.