111 lines
5.3 KiB
Markdown
111 lines
5.3 KiB
Markdown
<!-- SPDX-License-Identifier: MPL-2.0 -->
|
|
|
|
# Getting started
|
|
|
|
Gamertan Web Foundations is adopted one boundary at a time. Start with the
|
|
smallest package that solves a problem the application actually has; do not
|
|
install an imagined framework lifecycle around it.
|
|
|
|
## Choose a first slice
|
|
|
|
| Application need | Begin with | What remains application-owned |
|
|
| --- | --- | --- |
|
|
| Request IDs and trustworthy client addresses | `requestmeta` | Proxy configuration and operational logs |
|
|
| Bounded structured request evidence | `requestmeta`, `requestlog` | Route names, sensitive-field policy, rotation, retention, and access |
|
|
| Browser and HTTP safety primitives | `requestmeta`, `websec` | Exact CSP, route authorization, and response policy |
|
|
| Persistent request-abuse decisions | `requestmeta`, `abuse` | Route classification, storage, appeals, and operator policy |
|
|
| Users, credentials, permissions, and sessions | `auth` | Roles, permissions, login UX, and account policy |
|
|
| Secure browser cookies around `auth` | `authhttp` | Login routes, redirects, pages, and authorization decisions |
|
|
| SQLite persistence for `auth` | `authsqlite` | Database placement, backup, migration approval, and recovery |
|
|
| One account across organizations and teams | `organizations`, `authsqlite` | Invitation UX, organization naming, and lifecycle policy |
|
|
| Organization-scoped authorization | `access`, `authsqlite` | Role definitions, resource ownership, and route enforcement |
|
|
| Aggregate projections over request records | `analytics` | Collection policy, access control, report UI, and retention |
|
|
|
|
The packages are ordinary Go imports. Pin the current preview and verify its
|
|
module checksum:
|
|
|
|
```bash
|
|
go get gamertan.com/web/requestmeta@v0.1.0-preview.5
|
|
go mod verify
|
|
```
|
|
|
|
## Preserve middleware order
|
|
|
|
Packages that consume request metadata must run inside the resolver. Build the
|
|
handler from the application outward; the final resolver assignment becomes
|
|
the first middleware to receive a request:
|
|
|
|
```go
|
|
var handler http.Handler = router
|
|
handler = requestlog.Middleware(sink, logPolicy)(handler)
|
|
handler = websec.Headers(headerPolicy)(handler)
|
|
handler = resolver.Middleware(handler)
|
|
```
|
|
|
|
The complete, copyable composition is in [`starters/basic`](../starters/basic).
|
|
It binds to loopback, shuts down gracefully, and keeps request logging optional.
|
|
|
|
Configure trusted proxy networks narrowly. A forwarding header is not evidence
|
|
by itself; it becomes usable only when the immediate peer and skipped proxy
|
|
hops satisfy the resolver's trust policy. Metadata, authentication, or storage
|
|
failures that affect security decisions should stop the request rather than
|
|
quietly changing identity or policy.
|
|
|
|
## Bootstrap an account without inventing a permanent password
|
|
|
|
`auth.GenerateTemporaryPassword` returns 256 bits of URL-safe cryptographic
|
|
entropy. An application can store that value in a newly created private file
|
|
and provision an account with `RequirePasswordChange: true`. The library does
|
|
not write or print the credential because file ownership, operator identity,
|
|
and delivery are application policy.
|
|
|
|
After authentication, inspect `principal.User.PasswordChangeRequired`. Until it
|
|
is false, permit only password change and logout. `auth.ChangePassword` verifies
|
|
the current credential, rejects reuse, writes the new Argon2id hash, clears the
|
|
requirement, and revokes every existing session atomically through the storage
|
|
adapter. Clear the browser cookie and require a fresh login after success. Do
|
|
not treat a redirect alone as enforcement; apply the restriction before every
|
|
protected handler.
|
|
|
|
For operator-led recovery, expose `auth.ResetPassword` only through a local
|
|
administrative command—not a public HTTP endpoint. The operation installs an
|
|
application-generated one-time credential, sets `PasswordChangeRequired`,
|
|
revokes every existing session, and appends a secret-free audit event in the
|
|
same repository transaction. Deliver that credential through an exclusive
|
|
root-owned mode-`0600` file, delete it after successful rotation, and never put
|
|
it in command arguments, stdout, logs, manifests, or deployment state.
|
|
|
|
## Add HTML without merging responsibilities
|
|
|
|
Handlers should convert request and service state into typed display data.
|
|
They may then render those values with any HTML system. Gamertan's preferred
|
|
companion is [Sandwich Hime](SANDWICH_HIME.md), whose generated components keep
|
|
templates typed while leaving this middleware stack and the `net/http`
|
|
application in control.
|
|
|
|
## Verify the application boundary
|
|
|
|
After adopting a package:
|
|
|
|
```bash
|
|
go mod verify
|
|
go test ./...
|
|
go test -race ./...
|
|
go vet ./...
|
|
go build ./...
|
|
```
|
|
|
|
Test the composed handler with `httptest`, not only the package in isolation.
|
|
Include a normal request, malformed or spoofed metadata, a downstream failure,
|
|
and the application's intended response headers. Existing applications should
|
|
follow the differential and rollback sequence in [ADOPTION.md](ADOPTION.md).
|
|
|
|
Deeper tutorials for accounts, analytics, and persistent abuse policy will be
|
|
written after multiple application migrations have validated those seams. The
|
|
preview documentation describes demonstrated contracts rather than prescribing
|
|
an unfinished application framework.
|
|
|
|
See [Organizations and scoped access](ORGANIZATIONS.md) before storing tenant
|
|
data. In particular, do not interpret a platform role as permission to inspect
|
|
an organization's records.
|