@shipfox/api-auth 2.0.0

package/.turbo/turbo-build.log

@@ -0,0 +1,2 @@
+$ shipfox-swc
+Successfully compiled: 53 files with swc (65.52ms)

package/.turbo/turbo-type$colon$emit.log

@@ -0,0 +1 @@
+$ shipfox-tsc-emit

package/.turbo/turbo-type.log

@@ -0,0 +1 @@
+$ shipfox-tsc-check

package/CHANGELOG.md

@@ -0,0 +1,116 @@
+# @shipfox/api-auth
+
+## 2.0.0
+
+### Minor Changes
+
+- c31a7e0: Adds public auth session and cookie composition APIs with password-less user and idempotent membership provisioning.
+- 1b0d344: Publishes the complete API runtime closure with packed-consumer-safe internal imports and records its exact package set in application releases.
+
+### Patch Changes
+
+- Updated dependencies [0cd6dd4]
+- Updated dependencies [c31a7e0]
+- Updated dependencies [1b0d344]
+- Updated dependencies [521e006]
+  - @shipfox/node-module@0.2.0
+  - @shipfox/api-workspaces@2.0.0
+  - @shipfox/api-auth-context@2.0.0
+  - @shipfox/api-auth-dto@2.0.0
+  - @shipfox/api-workspaces-dto@2.0.0
+  - @shipfox/node-jwt@0.2.0
+  - @shipfox/node-rate-limit@0.2.0
+  - @shipfox/node-tokens@0.2.0
+  - @shipfox/config@1.2.1
+  - @shipfox/node-drizzle@0.2.1
+  - @shipfox/node-email@0.2.1
+  - @shipfox/node-fastify@0.2.1
+  - @shipfox/node-mailer@0.1.2
+  - @shipfox/node-opentelemetry@0.5.0
+  - @shipfox/node-outbox@0.2.1
+  - @shipfox/node-postgres@0.4.1
+
+## 0.1.2
+
+### Patch Changes
+
+- Updated dependencies [705dd43]
+  - @shipfox/node-outbox@0.2.0
+  - @shipfox/api-workspaces@0.1.2
+  - @shipfox/node-module@0.1.2
+
+## 0.1.1
+
+### Patch Changes
+
+- Updated dependencies [ec75cd5]
+- Updated dependencies [6a1fb54]
+  - @shipfox/node-drizzle@0.2.0
+  - @shipfox/node-postgres@0.4.0
+  - @shipfox/api-workspaces@0.1.1
+  - @shipfox/node-module@0.1.1
+  - @shipfox/node-outbox@0.1.1
+
+## 0.1.0
+
+### Minor Changes
+
+- c0a883c: Moves the job lease capability token codec and its claims schema from the runners packages into api-auth/api-auth-dto, renaming its config to `AUTH_JOB_LEASE_TOKEN_*`, so all signed-token codecs live with authentication. Adds a shared leased-job auth context for request-scoped lease claims, and a shared `createLeaseTokenAuthMethod` (the `leased-job` auth method) registered on the auth module so any feature module can protect routes with a lease token by name.
+- 6181819: Adds runner registration sessions with bounded label contracts, session-token auth, and lease-token heartbeat ownership.
+
+### Patch Changes
+
+- d02c5fd: Queues auth and workspace transactional emails through module-owned outbox events so account verification, password reset, and invitation sends retry outside request transactions.
+- e250c4c: Propagates `projectId` end-to-end into the job lease token. Workflows sources the `{workspaceId, projectId, workflowRunId, workflowRunAttemptId, jobId, jobExecutionId}` identity tuple and threads it through the runner pending/running job tables and lease claims. This is lease-shape groundwork for per-project log-ingest authorization; the stream-stamping consumer lands separately.
+- b0a0e1a: Expose the auth `config` object through a new `@shipfox/api-auth/config` subpath export, so a module that already depends on auth can read auth-owned settings (such as `AUTH_JOB_LEASE_TOKEN_EXPIRES_IN`) without pulling in the full module graph from the package root.
+- 1c1fb3e: Adds shared fixed-window rate limiting for provisioner token minting and ephemeral runner registration.
+- 1daf39a: Tolerates concurrent refresh-token reuse within a grace window so parallel browser tabs no longer log each other out, and treats reuse past the window as a session compromise.
+- 362b3eb: Scope runner log append authorization to the dispatched step attempt carried by the job lease token.
+- 27770eb: Tightens signup, workspace, and project display-name validation with shared trimming, control and format-character rejection, length limits, and contextual client form errors.
+- fb64f13: Extracts the HS256 sign/verify mechanics into a shared `@shipfox/node-jwt` package and refactors auth user-token signing onto it, leaving the auth public API unchanged.
+- Updated dependencies [cdd8931]
+- Updated dependencies [34ba284]
+- Updated dependencies [5707d6d]
+- Updated dependencies [b9c3f32]
+- Updated dependencies [d02c5fd]
+- Updated dependencies [a81b68c]
+- Updated dependencies [c0a883c]
+- Updated dependencies [72ce351]
+- Updated dependencies [e47f8da]
+- Updated dependencies [7b175f5]
+- Updated dependencies [ae7a63c]
+- Updated dependencies [5729548]
+- Updated dependencies [f92122b]
+- Updated dependencies [e250c4c]
+- Updated dependencies [b0a0e1a]
+- Updated dependencies [857fd73]
+- Updated dependencies [1c1fb3e]
+- Updated dependencies [3afb7e3]
+- Updated dependencies [75520ff]
+- Updated dependencies [4798517]
+- Updated dependencies [362b3eb]
+- Updated dependencies [d6d4862]
+- Updated dependencies [c0a883c]
+- Updated dependencies [6077301]
+- Updated dependencies [3bea87f]
+- Updated dependencies [82d22e4]
+- Updated dependencies [27770eb]
+- Updated dependencies [6181819]
+- Updated dependencies [9c149d1]
+- Updated dependencies [fb64f13]
+  - @shipfox/node-email@0.2.0
+  - @shipfox/node-fastify@0.2.0
+  - @shipfox/node-drizzle@0.1.0
+  - @shipfox/api-auth-dto@0.1.0
+  - @shipfox/api-workspaces-dto@0.1.0
+  - @shipfox/api-workspaces@0.1.0
+  - @shipfox/node-tokens@0.1.0
+  - @shipfox/api-auth-context@0.1.0
+  - @shipfox/node-opentelemetry@0.4.2
+  - @shipfox/node-postgres@0.3.2
+  - @shipfox/node-module@0.1.0
+  - @shipfox/node-outbox@0.1.0
+  - @shipfox/node-jwt@0.1.0
+  - @shipfox/node-rate-limit@0.1.0
+  - @shipfox/node-mailer@0.1.1
+  - @shipfox/config@1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shipfox
+
+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.

package/README.md

@@ -0,0 +1,336 @@
+# Shipfox API Auth
+
+Shipfox API Auth provides the server-side auth module for Shipfox APIs. It owns user accounts, email verification, login, refresh sessions, password reset, password change, JWT auth, and its PostgreSQL tables.
+
+## Example
+
+Register the module with the API module runner:
+
+```ts
+import {authModule} from '@shipfox/api-auth';
+import {createApp, listen} from '@shipfox/node-fastify';
+import {initializeModules} from '@shipfox/node-module';
+
+const {auth, routes} = await initializeModules({
+  modules: [authModule],
+});
+
+await createApp({auth, routes});
+await listen();
+```
+
+This adds:
+
+- auth database migrations from `libs/api/auth/drizzle`
+- the JWT auth method used by protected routes
+- routes under `/auth`
+
+## Setup
+
+Install the package from the registry:
+
+```sh
+pnpm add @shipfox/api-auth
+```
+
+Required environment:
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `AUTH_JWT_SECRET` | none | Secret used to sign and verify access tokens. |
+| `AUTH_JWT_EXPIRES_IN` | `15m` | Access token lifetime. |
+| `AUTH_JOB_LEASE_TOKEN_SECRET` | none | Secret used to sign and verify job lease tokens. |
+| `AUTH_JOB_LEASE_TOKEN_EXPIRES_IN` | `90m` | Job lease token lifetime. |
+| `AUTH_RUNNER_SESSION_TOKEN_SECRET` | none | Secret used to sign and verify runner session tokens. |
+| `AUTH_RUNNER_SESSION_TOKEN_EXPIRES_IN` | `1h` | Runner session token lifetime. |
+| `AUTH_REFRESH_TOKEN_EXPIRES_IN_DAYS` | `14` | Refresh token and cookie lifetime. |
+| `AUTH_REFRESH_ROTATION_GRACE_SECONDS` | `30` | Grace window for accepting a just-rotated refresh token during concurrent refreshes. |
+| `AUTH_REFRESH_COOKIE_NAME` | `shipfox_refresh_token` | HTTP cookie name for refresh sessions. |
+| `RATE_LIMIT_IDENTIFIER_SECRET` | none | Optional secret used to HMAC identifiers before storing rate-limit counters. When unset, the module derives a stable key from `AUTH_JWT_SECRET`. |
+| `CLIENT_BASE_URL` | `http://localhost:5173` | Base URL used in email verification and password reset links. |
+| `MAILER_TRANSPORT` | `console` | Mail transport. Set to `smtp` to send real mail. |
+| `MAILER_FROM` | `noreply@shipfox.local` | Sender used by auth emails. |
+| `SMTP_HOST` | none | Required when `MAILER_TRANSPORT=smtp`. |
+| `SMTP_PORT` | `587` | SMTP server port. |
+| `SMTP_USER` | none | Optional SMTP user. |
+| `SMTP_PASSWORD` | none | Optional SMTP password. |
+
+## Security model
+
+The module issues three kinds of bearer token, all presented as
+`Authorization: Bearer <token>`. All are **stateless**: each is signed with
+HMAC-SHA256 and verified by checking its signature and expiry alone, with no
+database read on the request path. They differ in who they authenticate and what
+they grant, and the stateless tradeoff is accepted for a different reason in each
+case. Each token class has a dedicated secret and audience, so one token type
+cannot be used in place of another.
+
+### User session token
+
+- **Design:** a stateless session token. It carries the user's identity and
+  current membership list in its claims so protected routes can authorize without
+  a per-request user or membership lookup.
+- **Audience:** signed-in users on first-party clients (web app, CLI).
+- **Grants:** the user's own account routes and, downstream, any route that
+  authorizes against the membership claims. Its scope is "this user, with these
+  memberships" — never a single resource.
+- **Lifecycle:**
+  - *Emit* — issued on login, signup verification, and password reset.
+  - *Exchange* — sent on each request; a longer-lived refresh session mints a
+    fresh token when it expires.
+  - *Store* — held in client memory only, never persisted to disk or local
+    storage. Refresh sessions are stored server-side as hashes, never in raw form.
+  - *Discard* — expires on its own (minutes, not hours); the refresh session is
+    revoked on logout and on password change.
+- **Tradeoff — stale memberships:** because memberships ride in the claims, a
+  membership change only takes effect on the next refresh. Accepted because the
+  token is short-lived, so the staleness window is bounded and a per-request
+  membership read is avoided.
+
+### Runner session token
+
+A runner session token is the data-plane identity for a running manual runner.
+The runner exchanges its long-lived registration token at startup, then uses the
+short-lived session token to claim jobs. Heartbeat and step/report/log operations
+use the per-job lease token instead.
+
+- **Scope — one workspace's runner data plane.** The token names one runner
+  session, one workspace, the fixed `workspace` scope, and the session's immutable
+  label set. It can claim jobs for that workspace. It is not a user identity and
+  does not authorize dashboard management routes.
+- **Labels are self-attested.** A holder of a valid registration token chooses
+  the labels it registers with. The labels are immutable after registration and
+  signed into the session token, but they are not an authorization boundary in v1.
+  Treat the registration token's workspace scope as the trust boundary.
+- **Mechanics.** Signed with HMAC-SHA256 using `AUTH_RUNNER_SESSION_TOKEN_SECRET`
+  and the `runner-session` audience. The default lifetime is `1h`, short enough
+  to bound the residual claim window when a registration token is revoked.
+- **Tradeoff — no per-session revocation in v1.** Claim stays stateless and does
+  not check the runner session row on each poll. Revoking the registration token
+  blocks new sessions, but an existing session can keep claiming until
+  `AUTH_RUNNER_SESSION_TOKEN_EXPIRES_IN` elapses. A job execution claimed before
+  session expiry then moves to the narrower job lease token path: heartbeat can
+  renew that lease while server state still says the job execution is live, and
+  cancellation or terminal job execution state is the revocation boundary for that
+  already-claimed work.
+
+### Job lease token
+
+A single-job **capability** token, not a session. It is the means by which a
+runner proves it is the legitimate holder of one specific job while it reports
+progress and drives that job to completion.
+
+- **Scope — exactly one job execution.** The token authorizes action on the
+  single job execution it names, for the runner holding it. It is **not** a runner
+  identity, it is **not** workspace-wide, and it is **not** a substitute for the
+  long-lived runner credential used to claim work in the first place. The
+  surrounding identifiers it carries (job, run, workspace, the claiming runner)
+  are context for consumers; they do not widen what the bearer may touch. When a
+  step is dispatched, the token may also carry the current step id and attempt so
+  log append can verify signed membership in that one step attempt without
+  querying workflow state.
+- **Trust boundary.** There is exactly one issuer: the scheduling side mints a
+  lease when a runner claims a job execution, next-step re-scopes it to the
+  dispatched step attempt, and heartbeat re-mints the same narrow capability
+  after server state accepts the heartbeat. Everything
+  downstream only *verifies* — an in-process signature check, with no callback to
+  the issuer. The runner, and the untrusted agent workload it hosts, never mints
+  or modifies a token; it only presents the one it was handed.
+- **Mechanics.** Signed with HMAC-SHA256 using a dedicated secret, separate from
+  the user-session secret. Its claims name the job, job execution, and surrounding
+  context and nothing more, and it carries a fixed audience so a token minted for
+  one purpose cannot be replayed against another. It is short-lived (bounded in
+  hours, not days), with heartbeat issuing a fresh short lease for the same live
+  execution. The signing secret is supplied through configuration, never embedded
+  in code or committed. The raw token must **never** be written to logs, traces, or
+  error payloads — there is no automatic redaction to fall back on.
+- **Defense in depth — server state is the final authority.** A valid token is
+  never sufficient on its own to advance work. On the lease's own request path the
+  gate is server-side step and progression state: a report against a step that has
+  already reached a terminal state (finished, failed, or cancelled) is ignored, so
+  a still-valid token cannot re-drive work that is already done. Job-level
+  finalization is enforced outside the lease path. Cancellation flows the other way
+  as well — the server can ask the runner to stop at any point, and that request
+  rides on the response to each heartbeat rather than depending on the token.
+- **Log append scope.** A step-scoped lease is a signed membership and attempt
+  check for append-log authorization. It is not an active-step proof: until the
+  runner adopts a later step-scoped token or the lease expires, the bearer can
+  append to that step attempt's log stream. This is no broader than the job-scoped
+  append authority it replaces, and step completion remains governed by
+  server-side report/progression state.
+- **Threat model.** A leaked or replayed token has a deliberately small blast
+  radius: it grants action on one already-claimed job execution while that
+  execution remains live. It cannot claim new work, impersonate a runner, or reach
+  other workspaces. If the *signing secret* leaks, the response is to rotate it;
+  rotation invalidates every live lease at once (they fail signature verification)
+  and forces fresh claims. Isolating this secret from the user-session secret is
+  what lets one be rotated without disrupting the other.
+- **Tradeoff — no per-token revocation.** A single outstanding lease cannot be
+  revoked on its own by token ID. The claiming runner's credential is not
+  re-checked on each request, so a lease for already-claimed work can continue to
+  be renewed by heartbeat until server state cancels, completes, times out, or
+  otherwise terminates the job execution. Accepted because access is bounded in
+  scope (one execution) and server state is checked on the hot path; a
+  per-request credential lookup would sit on the hot progress-reporting path.
+- **Guidelines for future changes.** Keep the authority narrow: do not add claims
+  that grant access beyond the single job, keep the lifetime bounded, keep a single
+  issuer, and keep every other side verify-only. If the no-revocation window ever
+  proves too wide, the right fix is to bind the lease to live runner or job state —
+  not to broaden what the token itself can authorize.
+
+## Routes
+
+All routes are mounted under `/auth`.
+
+| Method | Path | Auth | Result |
+| --- | --- | --- | --- |
+| `POST` | `/signup` | none | Creates a user and sends an email verification link. |
+| `POST` | `/verify-email/confirm` | none | Verifies email, returns an access token, and sets the refresh cookie. |
+| `POST` | `/verify-email/resend` | none | Sends a new verification email when the account is eligible. |
+| `POST` | `/login` | none | Returns an access token and sets the refresh cookie. |
+| `POST` | `/refresh` | refresh cookie | Rotates the refresh token when needed and returns a new access token. |
+| `POST` | `/logout` | refresh cookie | Revokes the current refresh token and clears the cookie. |
+| `GET` | `/me` | bearer token | Returns the signed-in user. |
+| `POST` | `/change-password` | bearer token | Changes the password and revokes other refresh sessions. |
+| `POST` | `/password-reset` | none | Sends a password reset email when the account is eligible. |
+| `POST` | `/password-reset/confirm` | none | Sets a new password, returns an access token, and sets the refresh cookie. |
+
+Protected routes use the `Authorization: Bearer <token>` header. The refresh flow uses an HTTP-only cookie on the `/auth` path.
+
+> [!IMPORTANT]
+> Refresh cookies are set with `secure: true`, `httpOnly: true`, and `sameSite: "lax"`. Local browser tests need HTTPS or a test path that handles secure cookies.
+
+### Rate limiting
+
+The public auth endpoints include an application-layer abuse baseline for open source installs:
+
+| Route | IP bucket | Email bucket |
+| --- | --- | --- |
+| `POST /auth/login` | 60 attempts per 5 minutes | 10 attempts per 15 minutes |
+| `POST /auth/password-reset` | 30 email-send attempts per hour | 3 email-send attempts per hour |
+| `POST /auth/verify-email/resend` | Shared with password reset | Shared with password reset |
+
+Counters are stored in PostgreSQL as fixed windows in `auth_rate_limits`. IP addresses and email addresses are HMAC-SHA256 values before storage; raw identifiers are not persisted. `RATE_LIMIT_IDENTIFIER_SECRET` is optional. Set it when you want a dedicated HMAC secret, or leave it unset to derive the key from `AUTH_JWT_SECRET`.
+
+The limiter uses `request.ip`, so production deployments behind a reverse proxy must configure the API app's `API_TRUST_PROXY` setting. Keep the default `false` when clients connect directly. Use a positive hop count such as `1`, or a trusted proxy IP/CIDR such as `10.0.0.0/8`, when proxy headers are controlled by infrastructure you operate.
+
+This app-layer limiter protects semantic auth work such as Argon2 verification and email sending. It is not a volumetric DDoS control. Public production deployments should still use load balancer, CDN, WAF, or firewall rate limits at the network edge.
+
+## API
+
+The package exports the module entry point:
+
+```ts
+import {authModule} from '@shipfox/api-auth';
+```
+
+It also exports lower-level pieces for tests and advanced integration:
+
+- `routes`: the `/auth` route group.
+- `db` and `migrationsPath`: the Drizzle database handle and migration path.
+- `createJwtAuthMethod()`: the Fastify auth method for user JWTs.
+- `createRunnerSessionAuthMethod()`: the Fastify auth method for runner session tokens.
+- `createLeaseTokenAuthMethod()`: the Fastify auth method for job lease tokens.
+- `issueRunnerSessionToken(claims)` / `verifyRunnerSessionToken(token)`: mint and verify runner session tokens.
+- `issueJobLeaseToken(claims)` / `verifyJobLeaseToken(token)`: mint and verify job lease tokens.
+- `getClientContext(request)`: reads the authenticated user context from a Fastify request.
+- Entity types: `User`, `UserStatus`, `RefreshToken`, `EmailVerification`, and `PasswordReset`.
+
+### External identity callbacks
+
+An external identity route can use these APIs to provision a user. It can then
+create a normal Shipfox session and set its refresh cookie:
+
+```ts
+import {
+  authCookiePlugin,
+  createSessionForUser,
+  provisionUser,
+  setRefreshTokenCookie,
+} from '@shipfox/api-auth';
+import type {FastifyReply} from 'fastify';
+
+export const callbackRoutePlugins = [authCookiePlugin];
+
+export async function completeProviderCallback(
+  reply: FastifyReply,
+  profile: {email: string; name?: string},
+): Promise<string> {
+  const user = await provisionUser(profile);
+  const session = await createSessionForUser({userId: user.id});
+
+  setRefreshTokenCookie(reply, session.refreshToken);
+  return session.token;
+}
+```
+
+The provider must prove it owns `profile.email` before calling `provisionUser`.
+For OAuth providers, require a verified-email claim such as `email_verified`.
+`provisionUser` matches existing emails, and `createSessionForUser` can mint a
+session for any active, verified account. An unverified provider email could
+otherwise sign in as an existing password account with the same address.
+
+Add `authCookiePlugin` to the callback route group before calling a cookie
+helper. `getRefreshTokenCookie`, `setRefreshTokenCookie`, and
+`clearRefreshTokenCookie` use the configured cookie name and the `/auth` path.
+
+`provisionUser({email, name?})` uses the same email schema as the auth routes.
+It makes an active, verified user with no password hash. If the email already
+exists, it returns that user unchanged. It does not change the name, email,
+status, verification state, or password. Repeated and concurrent callbacks are
+safe.
+
+`createSessionForUser` accepts either a `userId` or an `email`. It only creates
+a session for an active, verified user. It can throw `UserNotFoundError`,
+`EmailNotVerifiedError`, `InvalidCredentialsError`, or
+`AuthDependencyUnavailableError`. `CreateSessionForUserParams`,
+`CreateSessionForUserResult`, and `CreateSessionForUserError` describe that
+public contract.
+
+`createJwtAuthMethod`, `createRunnerSessionAuthMethod`, and
+`createLeaseTokenAuthMethod` make request-auth methods. They do not add a
+user-facing login method.
+
+## Data Model
+
+The module creates tables with the `auth_` prefix:
+
+- `auth_users`
+- `auth_refresh_tokens`
+- `auth_email_verifications`
+- `auth_password_resets`
+- `auth_rate_limits`
+
+Passwords use Argon2id. Email verification tokens, password reset tokens, and refresh tokens are opaque tokens stored as hashes.
+
+## Behavior Notes
+
+- Signup sends a verification email and returns the new user.
+- Login only succeeds for active users with verified email addresses and a password hash.
+- Refresh tokens rotate on each refresh.
+- Password reset and email verification consume their tokens once.
+- Password change revokes other refresh sessions. It keeps the current session when the current refresh cookie is valid.
+- Password reset requests and verification resend requests do not reveal whether an account exists.
+- Login, password reset, and verification resend requests are rate-limited by IP address and email address.
+
+## Development
+
+Run checks for this package:
+
+```sh
+turbo check --filter=@shipfox/api-auth
+turbo type --filter=@shipfox/api-auth
+turbo test --filter=@shipfox/api-auth
+```
+
+Tests use Vitest and a real PostgreSQL database. Start local services before running the test suite:
+
+```sh
+docker compose up -d
+```
+
+The test environment uses the `api_test` database and sets fake auth secrets in `test/env.ts`.
+
+## License
+
+MIT

package/dist/config.d.ts

@@ -0,0 +1,22 @@
+import { type Mailer } from '@shipfox/node-mailer';
+export declare const config: Readonly<{
+    AUTH_JWT_SECRET: string;
+    AUTH_JWT_EXPIRES_IN: string;
+    AUTH_JOB_LEASE_TOKEN_SECRET: string;
+    AUTH_JOB_LEASE_TOKEN_EXPIRES_IN: string;
+    AUTH_RUNNER_SESSION_TOKEN_SECRET: string;
+    AUTH_RUNNER_SESSION_TOKEN_EXPIRES_IN: string;
+    AUTH_REFRESH_TOKEN_EXPIRES_IN_DAYS: number;
+    AUTH_REFRESH_ROTATION_GRACE_SECONDS: number;
+    AUTH_REFRESH_COOKIE_NAME: string;
+    RATE_LIMIT_IDENTIFIER_SECRET: string | undefined;
+    CLIENT_BASE_URL: string;
+    MAILER_TRANSPORT: "console" | "smtp";
+    MAILER_FROM: string;
+    SMTP_HOST: string | undefined;
+    SMTP_PORT: number;
+    SMTP_USER: string | undefined;
+    SMTP_PASSWORD: string | undefined;
+} & import("@shipfox/config").CleanedEnvAccessors>;
+export declare const mailer: Mailer;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AACA,OAAO,EAAwC,KAAK,MAAM,EAAC,MAAM,sBAAsB,CAAC;AAExF,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;kDAmEjB,CAAC;AAiBH,eAAO,MAAM,MAAM,QAAiB,CAAC"}

package/dist/config.js

@@ -0,0 +1,95 @@
+import { createConfig, num, str } from '@shipfox/config';
+import { createConsoleMailer, createSmtpMailer } from '@shipfox/node-mailer';
+export const config = createConfig({
+    AUTH_JWT_SECRET: str({
+        desc: 'Secret used to sign and verify user access tokens (JWTs). Required, with no default, so startup fails when it is missing.'
+    }),
+    AUTH_JWT_EXPIRES_IN: str({
+        desc: 'How long an access token stays valid. Accepts a duration string such as 15m, 1h, or 7d.',
+        default: '15m'
+    }),
+    AUTH_JOB_LEASE_TOKEN_SECRET: str({
+        desc: 'Secret used to sign and verify job lease tokens. Required, with no default, so startup fails when it is missing.'
+    }),
+    AUTH_JOB_LEASE_TOKEN_EXPIRES_IN: str({
+        desc: 'How long a job lease token stays valid. Set it longer than the longest job (JOB_MAX_DURATION is 60 minutes) plus a safety margin.',
+        default: '90m'
+    }),
+    AUTH_RUNNER_SESSION_TOKEN_SECRET: str({
+        desc: 'Secret used to sign and verify runner session tokens. Required, with no default, so startup fails when it is missing.'
+    }),
+    AUTH_RUNNER_SESSION_TOKEN_EXPIRES_IN: str({
+        desc: 'How long a runner session token stays valid. A revoked registration token can leave existing sessions usable until this lifetime ends.',
+        default: '1h'
+    }),
+    AUTH_REFRESH_TOKEN_EXPIRES_IN_DAYS: num({
+        desc: 'How many days a refresh token stays valid before the user must sign in again.',
+        default: 14
+    }),
+    AUTH_REFRESH_ROTATION_GRACE_SECONDS: num({
+        desc: 'Window after a refresh token is rotated during which the now-rotated token is still accepted, so concurrent refreshes from parallel tabs do not log the user out. Reuse past this window is treated as a compromise and revokes the session.',
+        default: 30
+    }),
+    AUTH_REFRESH_COOKIE_NAME: str({
+        desc: 'Name of the browser cookie that stores the refresh token.',
+        default: 'shipfox_refresh_token'
+    }),
+    RATE_LIMIT_IDENTIFIER_SECRET: str({
+        desc: 'Optional secret used to HMAC identifiers before storing rate-limit counters. Leave it unset to derive a stable key from AUTH_JWT_SECRET.',
+        default: undefined
+    }),
+    CLIENT_BASE_URL: str({
+        desc: 'Base URL of the client app. Used to build links in emails such as password resets.',
+        default: 'http://localhost:5173'
+    }),
+    MAILER_TRANSPORT: str({
+        desc: 'How emails are delivered. Use console to print them to the log, or smtp to send them through an SMTP server.',
+        choices: [
+            'console',
+            'smtp'
+        ],
+        default: 'console'
+    }),
+    MAILER_FROM: str({
+        desc: 'Sender address shown on outgoing emails.',
+        default: 'noreply@shipfox.local'
+    }),
+    SMTP_HOST: str({
+        desc: 'Hostname of the SMTP server. Required when MAILER_TRANSPORT is smtp.',
+        default: undefined
+    }),
+    SMTP_PORT: num({
+        desc: 'Port of the SMTP server.',
+        default: 587
+    }),
+    SMTP_USER: str({
+        desc: 'Username for SMTP authentication. Leave it unset if the server needs no login.',
+        default: undefined
+    }),
+    SMTP_PASSWORD: str({
+        desc: 'Password for SMTP authentication. Leave it unset if the server needs no login.',
+        default: undefined
+    })
+});
+function createMailer() {
+    if (config.MAILER_TRANSPORT === 'smtp') {
+        if (!config.SMTP_HOST) throw new Error('SMTP_HOST is required when MAILER_TRANSPORT=smtp');
+        return createSmtpMailer({
+            host: config.SMTP_HOST,
+            port: config.SMTP_PORT,
+            ...config.SMTP_USER ? {
+                user: config.SMTP_USER
+            } : {},
+            ...config.SMTP_PASSWORD ? {
+                password: config.SMTP_PASSWORD
+            } : {},
+            from: config.MAILER_FROM
+        });
+    }
+    return createConsoleMailer({
+        from: config.MAILER_FROM
+    });
+}
+export const mailer = createMailer();
+
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/config.ts"],"sourcesContent":["import {createConfig, num, str} from '@shipfox/config';\nimport {createConsoleMailer, createSmtpMailer, type Mailer} from '@shipfox/node-mailer';\n\nexport const config = createConfig({\n  AUTH_JWT_SECRET: str({\n    desc: 'Secret used to sign and verify user access tokens (JWTs). Required, with no default, so startup fails when it is missing.',\n  }),\n  AUTH_JWT_EXPIRES_IN: str({\n    desc: 'How long an access token stays valid. Accepts a duration string such as 15m, 1h, or 7d.',\n    default: '15m',\n  }),\n  AUTH_JOB_LEASE_TOKEN_SECRET: str({\n    desc: 'Secret used to sign and verify job lease tokens. Required, with no default, so startup fails when it is missing.',\n  }),\n  AUTH_JOB_LEASE_TOKEN_EXPIRES_IN: str({\n    desc: 'How long a job lease token stays valid. Set it longer than the longest job (JOB_MAX_DURATION is 60 minutes) plus a safety margin.',\n    default: '90m',\n  }),\n  AUTH_RUNNER_SESSION_TOKEN_SECRET: str({\n    desc: 'Secret used to sign and verify runner session tokens. Required, with no default, so startup fails when it is missing.',\n  }),\n  AUTH_RUNNER_SESSION_TOKEN_EXPIRES_IN: str({\n    desc: 'How long a runner session token stays valid. A revoked registration token can leave existing sessions usable until this lifetime ends.',\n    default: '1h',\n  }),\n  AUTH_REFRESH_TOKEN_EXPIRES_IN_DAYS: num({\n    desc: 'How many days a refresh token stays valid before the user must sign in again.',\n    default: 14,\n  }),\n  AUTH_REFRESH_ROTATION_GRACE_SECONDS: num({\n    desc: 'Window after a refresh token is rotated during which the now-rotated token is still accepted, so concurrent refreshes from parallel tabs do not log the user out. Reuse past this window is treated as a compromise and revokes the session.',\n    default: 30,\n  }),\n  AUTH_REFRESH_COOKIE_NAME: str({\n    desc: 'Name of the browser cookie that stores the refresh token.',\n    default: 'shipfox_refresh_token',\n  }),\n  RATE_LIMIT_IDENTIFIER_SECRET: str({\n    desc: 'Optional secret used to HMAC identifiers before storing rate-limit counters. Leave it unset to derive a stable key from AUTH_JWT_SECRET.',\n    default: undefined,\n  }),\n  CLIENT_BASE_URL: str({\n    desc: 'Base URL of the client app. Used to build links in emails such as password resets.',\n    default: 'http://localhost:5173',\n  }),\n  MAILER_TRANSPORT: str({\n    desc: 'How emails are delivered. Use console to print them to the log, or smtp to send them through an SMTP server.',\n    choices: ['console', 'smtp'],\n    default: 'console',\n  }),\n  MAILER_FROM: str({\n    desc: 'Sender address shown on outgoing emails.',\n    default: 'noreply@shipfox.local',\n  }),\n  SMTP_HOST: str({\n    desc: 'Hostname of the SMTP server. Required when MAILER_TRANSPORT is smtp.',\n    default: undefined,\n  }),\n  SMTP_PORT: num({\n    desc: 'Port of the SMTP server.',\n    default: 587,\n  }),\n  SMTP_USER: str({\n    desc: 'Username for SMTP authentication. Leave it unset if the server needs no login.',\n    default: undefined,\n  }),\n  SMTP_PASSWORD: str({\n    desc: 'Password for SMTP authentication. Leave it unset if the server needs no login.',\n    default: undefined,\n  }),\n});\n\nfunction createMailer(): Mailer {\n  if (config.MAILER_TRANSPORT === 'smtp') {\n    if (!config.SMTP_HOST) throw new Error('SMTP_HOST is required when MAILER_TRANSPORT=smtp');\n    return createSmtpMailer({\n      host: config.SMTP_HOST,\n      port: config.SMTP_PORT,\n      ...(config.SMTP_USER ? {user: config.SMTP_USER} : {}),\n      ...(config.SMTP_PASSWORD ? {password: config.SMTP_PASSWORD} : {}),\n      from: config.MAILER_FROM,\n    });\n  }\n\n  return createConsoleMailer({from: config.MAILER_FROM});\n}\n\nexport const mailer = createMailer();\n"],"names":["createConfig","num","str","createConsoleMailer","createSmtpMailer","config","AUTH_JWT_SECRET","desc","AUTH_JWT_EXPIRES_IN","default","AUTH_JOB_LEASE_TOKEN_SECRET","AUTH_JOB_LEASE_TOKEN_EXPIRES_IN","AUTH_RUNNER_SESSION_TOKEN_SECRET","AUTH_RUNNER_SESSION_TOKEN_EXPIRES_IN","AUTH_REFRESH_TOKEN_EXPIRES_IN_DAYS","AUTH_REFRESH_ROTATION_GRACE_SECONDS","AUTH_REFRESH_COOKIE_NAME","RATE_LIMIT_IDENTIFIER_SECRET","undefined","CLIENT_BASE_URL","MAILER_TRANSPORT","choices","MAILER_FROM","SMTP_HOST","SMTP_PORT","SMTP_USER","SMTP_PASSWORD","createMailer","Error","host","port","user","password","from","mailer"],"mappings":"AAAA,SAAQA,YAAY,EAAEC,GAAG,EAAEC,GAAG,QAAO,kBAAkB;AACvD,SAAQC,mBAAmB,EAAEC,gBAAgB,QAAoB,uBAAuB;AAExF,OAAO,MAAMC,SAASL,aAAa;IACjCM,iBAAiBJ,IAAI;QACnBK,MAAM;IACR;IACAC,qBAAqBN,IAAI;QACvBK,MAAM;QACNE,SAAS;IACX;IACAC,6BAA6BR,IAAI;QAC/BK,MAAM;IACR;IACAI,iCAAiCT,IAAI;QACnCK,MAAM;QACNE,SAAS;IACX;IACAG,kCAAkCV,IAAI;QACpCK,MAAM;IACR;IACAM,sCAAsCX,IAAI;QACxCK,MAAM;QACNE,SAAS;IACX;IACAK,oCAAoCb,IAAI;QACtCM,MAAM;QACNE,SAAS;IACX;IACAM,qCAAqCd,IAAI;QACvCM,MAAM;QACNE,SAAS;IACX;IACAO,0BAA0Bd,IAAI;QAC5BK,MAAM;QACNE,SAAS;IACX;IACAQ,8BAA8Bf,IAAI;QAChCK,MAAM;QACNE,SAASS;IACX;IACAC,iBAAiBjB,IAAI;QACnBK,MAAM;QACNE,SAAS;IACX;IACAW,kBAAkBlB,IAAI;QACpBK,MAAM;QACNc,SAAS;YAAC;YAAW;SAAO;QAC5BZ,SAAS;IACX;IACAa,aAAapB,IAAI;QACfK,MAAM;QACNE,SAAS;IACX;IACAc,WAAWrB,IAAI;QACbK,MAAM;QACNE,SAASS;IACX;IACAM,WAAWvB,IAAI;QACbM,MAAM;QACNE,SAAS;IACX;IACAgB,WAAWvB,IAAI;QACbK,MAAM;QACNE,SAASS;IACX;IACAQ,eAAexB,IAAI;QACjBK,MAAM;QACNE,SAASS;IACX;AACF,GAAG;AAEH,SAASS;IACP,IAAItB,OAAOe,gBAAgB,KAAK,QAAQ;QACtC,IAAI,CAACf,OAAOkB,SAAS,EAAE,MAAM,IAAIK,MAAM;QACvC,OAAOxB,iBAAiB;YACtByB,MAAMxB,OAAOkB,SAAS;YACtBO,MAAMzB,OAAOmB,SAAS;YACtB,GAAInB,OAAOoB,SAAS,GAAG;gBAACM,MAAM1B,OAAOoB,SAAS;YAAA,IAAI,CAAC,CAAC;YACpD,GAAIpB,OAAOqB,aAAa,GAAG;gBAACM,UAAU3B,OAAOqB,aAAa;YAAA,IAAI,CAAC,CAAC;YAChEO,MAAM5B,OAAOiB,WAAW;QAC1B;IACF;IAEA,OAAOnB,oBAAoB;QAAC8B,MAAM5B,OAAOiB,WAAW;IAAA;AACtD;AAEA,OAAO,MAAMY,SAASP,eAAe"}