Signing in

POST /api/v1/auth/login — Public; a wrong password and an address nobody has answer the same 401 and cost the same; ten failures for an address in fifteen minutes is a 429, and an account attacked from more than three addresses gets a two-second delay before the transaction opens instead of a lockout; a sign-in posted from another site is refused. It sets the platformkit_session cookie: HttpOnly, SameSite Lax, Secure and __Host--prefixed unless PublicHost is a local name (internal/handler.go, internal/kernel.go).

POST /api/v1/auth/logout — SignedIn; deletes the session and clears the cookie; signing out when already signed out is not an error.

GET /api/v1/auth/me — SignedIn; the caller’s Identity.

POST /api/v1/auth/password — SignedIn; requires the password in force, ends every other session of this person and keeps the one asking (internal/password.go).

POST /api/v1/auth/password/forgot — Public; publishes auth.reset_requested and does nothing else, so an address somebody has and one nobody has are the same answer and the same work; the 429 counts the address asking, ten per window, never the address asked about.

POST /api/v1/auth/password/reset — Public; consumes the token the link carried, sets the password, ends every session including the caller’s and clears the cookie; an unknown, spent or expired token is one 401; twenty redemptions per address per window.

GET /api/v1/auth/roles and PUT /api/v1/auth/roles/{name} — role:manage; the PUT creates the role if it is new, refuses a permission no module defines and an operator permission outside the operator’s own tenant (422), and publishes auth.role_set only when the list changed (internal/roles.go).

GET /api/v1/auth/oidc/start and GET /api/v1/auth/oidc/callback (the configured redirect_path) — Public, registered only when an issuer is configured: PKCE and a platformkit_oidc state cookie out, a verified address back, and a session for the user this tenant has at that address; an address it has no account for is refused and nobody is created (internal/oidc.go).

Screens: none. The module registers no httpx.Resource, so the admin generates nothing for it; the sign-in page is the admin module’s GET /admin/login, whose form posts to POST /api/v1/auth/login (modules/admin/internal/pages.go). The manifest’s navigation entry "Roles" names /admin/auth/roles for role:manage, and no page in the tree serves that path; the shell reports an unserved entry once at boot and does not show it (modules/admin/internal/mount.go). Hand-written pages: none.

Publishes: the six events above; auth.login_failed is the one event in the application written outside the transaction of the thing it describes, because a 401 is a response the kernel rolls back.

Jobs: auth-sweep (internal.Sweep), cron 0 * * * *: purges the rate-limit windows once (limit.Purge), then through jobs.PerTenant deletes each tenant’s expired sessions and spent tokens a thousand rows per transaction (Purge) and logs every role that names a permission no module defines (Undeclared) (internal/sweep.go).

Subscriptions: user.invited → Offer, which mints a set-password token for an invited user and mails the link, skipping somebody who already has a password; auth.reset_requested → Reissue, which looks the address up in the worker and mails a link only to an active user who was not sent one in the last five minutes (module.go). Both are subscriptions rather than calls inside the request, so the request neither waits on a mail server nor reveals, by its timing, whether the address exists.

The kernel — main passes the returned contracts.Auth to kit/app as Options.Authorize and Options.Authenticate (apps/platformkit/main.go), so every permission any module declares is resolved against the roles table here, in the request’s own transaction, with no cache.

admin — admin.Deps.Authorize takes the same value as an httpx.Authorizer, to show only the links the caller may follow; its sign-in page posts to POST /api/v1/auth/login.

A private client module — Deps.Authorize httpx.Authorizer, the same value, to draw a write control only where the route would let it through; the private application’s registry lists auth among the three kernel modules no client may leave out.

The tenant module, through main — its OnCreate hook is seedRoles, which calls auth.SeedRoles with the operator permissions tenant:manage and billing:catalog; the flagship passes the client’s roles as defaults, checked with contracts.CheckedPermissions before boot; authcontracts.RoleAdmin names the first administrator’s role in bootstrap and start.

The admin and the native shell reach it through its routes, not through contracts/: the shell’s login is POST /api/v1/auth/login, keeping the Set-Cookie value, and logout is POST /api/v1/auth/logout (platformkit-mobile, src/effects/api.ts).

go test ./modules/auth/…​ — the fake and the real service pass one conformance suite of eighteen cases (authtest.RunService: a password opens a session, a wrong password and an address nobody has answer alike, too many failures lock the address, the link sets a password once and ends every session, an operator permission cannot be granted in a customer’s tenant); the internal tests prove that a session from another tenant is not a session here, that use slides the expiry and never past the cap, that a failed login is recorded though its request is rolled back, that the reset token is in the mail and in no row, that the forgotten-password route costs the same either way, that the soft delay holds no transaction and that the lockout is one counter for every replica; the single sign-on round trip runs against authtest’s issuer; `seed_test.go proves role provisioning needs only its transaction.

make e2e signs in through /admin/login, which posts to POST /api/v1/auth/login, before every journey (e2e/admin-tasks.spec.ts); a private shopper journey signs in the same way.

Not proven: single sign-on against a live identity provider; the password flows in a browser, since no journey follows a mailed link; the sweep against a live fleet.