my-crud-lib 2.0.0 → 2.1.0

package/dist/modules/auth/auth.service.js

@@ -1,6 +1,10 @@
 import bcrypt from 'bcryptjs';
+import { createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
 import { signAccessToken, signRefreshToken, verifyToken } from '../../utils/jwt.js';
 import { resolveRegisterRole } from './auth.defaults.js';
+const DEFAULT_REFRESH_TOKEN_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+const DEFAULT_PASSWORD_RESET_TTL_MS = 60 * 60 * 1000;
+const DEFAULT_EMAIL_VERIFICATION_TTL_MS = 24 * 60 * 60 * 1000;
 function resolvePasswordHashRounds(configured) {
     const rounds = configured ?? Number(process.env.BCRYPT_SALT);
     return Number.isInteger(rounds) && rounds > 0 ? rounds : 10;
@@ -9,15 +13,185 @@ function toAuthUser(user) {
     const { passwordHash: _passwordHash, ...safeUser } = user;
     return safeUser;
 }
-function issueTokens(user) {
+function getNow(deps) {
+    return deps.now?.() ?? new Date();
+}
+function addMs(date, ms) {
+    return new Date(date.getTime() + ms);
+}
+function isExpired(value, now) {
+    return new Date(value).getTime() <= now.getTime();
+}
+function createId(deps) {
+    return deps.idFactory?.() ?? randomUUID();
+}
+function createSecret() {
+    return randomBytes(32).toString('base64url');
+}
+function createOpaqueToken(deps) {
+    const id = createId(deps);
+    return { id, token: `${id}.${createSecret()}` };
+}
+function parseOpaqueToken(token) {
+    const [id, secret, ...rest] = token.split('.');
+    if (!id || !secret || rest.length > 0)
+        return null;
+    return { id };
+}
+function hashToken(token, secret) {
+    if (secret)
+        return createHmac('sha256', secret).update(token).digest('hex');
+    return createHash('sha256').update(token).digest('hex');
+}
+function safeEqual(a, b) {
+    const left = Buffer.from(a);
+    const right = Buffer.from(b);
+    return left.length === right.length && timingSafeEqual(left, right);
+}
+async function issueTokens(user, deps, familyId) {
     const payload = { sub: user.id, role: user.role };
-    return {
-        accessToken: signAccessToken(payload),
-        refreshToken: signRefreshToken(payload),
-    };
+    const accessToken = signAccessToken(payload);
+    if (!deps.refreshTokenRepo) {
+        return {
+            accessToken,
+            refreshToken: signRefreshToken(payload),
+        };
+    }
+    const refreshTokenId = createId(deps);
+    const resolvedFamilyId = familyId ?? createId(deps);
+    const refreshToken = signRefreshToken({ ...payload, jti: refreshTokenId, fam: resolvedFamilyId });
+    const now = getNow(deps);
+    const expiresAt = addMs(now, deps.refreshTokenTtlMs ?? DEFAULT_REFRESH_TOKEN_TTL_MS);
+    await deps.refreshTokenRepo.create({
+        id: refreshTokenId,
+        userId: user.id,
+        tokenHash: hashToken(refreshToken, deps.tokenHashSecret),
+        familyId: resolvedFamilyId,
+        expiresAt,
+    });
+    return { accessToken, refreshToken, refreshTokenId, familyId: resolvedFamilyId };
 }
 export function makeAuthService(deps) {
     const { userRepo } = deps;
+    async function requestPasswordReset(params) {
+        if (!deps.passwordResetTokenRepo || !deps.sendPasswordReset) {
+            throw new Error('PASSWORD_RESET_UNSUPPORTED');
+        }
+        const user = await userRepo.findByEmail(params.email);
+        if (!user)
+            return { ok: true };
+        const now = getNow(deps);
+        const expiresAt = addMs(now, deps.passwordResetTtlMs ?? DEFAULT_PASSWORD_RESET_TTL_MS);
+        const { id, token } = createOpaqueToken(deps);
+        await deps.passwordResetTokenRepo.create({
+            id,
+            userId: user.id,
+            tokenHash: hashToken(token, deps.tokenHashSecret),
+            expiresAt,
+        });
+        await deps.sendPasswordReset({ user: toAuthUser(user), token, expiresAt });
+        return { ok: true };
+    }
+    async function confirmPasswordReset(params) {
+        if (!deps.passwordResetTokenRepo || !userRepo.updatePassword) {
+            throw new Error('PASSWORD_RESET_UNSUPPORTED');
+        }
+        const parsed = parseOpaqueToken(params.token);
+        if (!parsed)
+            throw new Error('INVALID_PASSWORD_RESET_TOKEN');
+        const record = await deps.passwordResetTokenRepo.findById(parsed.id);
+        const now = getNow(deps);
+        if (!record ||
+            record.usedAt ||
+            record.revokedAt ||
+            isExpired(record.expiresAt, now) ||
+            !safeEqual(record.tokenHash, hashToken(params.token, deps.tokenHashSecret))) {
+            throw new Error('INVALID_PASSWORD_RESET_TOKEN');
+        }
+        const passwordHash = await bcrypt.hash(params.password, resolvePasswordHashRounds(deps.passwordHashRounds));
+        await userRepo.updatePassword(record.userId, passwordHash);
+        await deps.passwordResetTokenRepo.markUsed(record.id, { usedAt: now });
+        return { ok: true };
+    }
+    async function requestEmailVerification(params) {
+        if (!deps.emailVerificationTokenRepo || !deps.sendEmailVerification) {
+            throw new Error('EMAIL_VERIFICATION_UNSUPPORTED');
+        }
+        const user = await userRepo.findByEmail(params.email);
+        if (!user || user.emailVerifiedAt)
+            return { ok: true };
+        const now = getNow(deps);
+        const expiresAt = addMs(now, deps.emailVerificationTtlMs ?? DEFAULT_EMAIL_VERIFICATION_TTL_MS);
+        const { id, token } = createOpaqueToken(deps);
+        await deps.emailVerificationTokenRepo.create({
+            id,
+            userId: user.id,
+            tokenHash: hashToken(token, deps.tokenHashSecret),
+            expiresAt,
+        });
+        await deps.sendEmailVerification({ user: toAuthUser(user), token, expiresAt });
+        return { ok: true };
+    }
+    async function confirmEmailVerification(params) {
+        if (!deps.emailVerificationTokenRepo || !userRepo.markEmailVerified) {
+            throw new Error('EMAIL_VERIFICATION_UNSUPPORTED');
+        }
+        const parsed = parseOpaqueToken(params.token);
+        if (!parsed)
+            throw new Error('INVALID_EMAIL_VERIFICATION_TOKEN');
+        const record = await deps.emailVerificationTokenRepo.findById(parsed.id);
+        const now = getNow(deps);
+        if (!record ||
+            record.usedAt ||
+            record.revokedAt ||
+            isExpired(record.expiresAt, now) ||
+            !safeEqual(record.tokenHash, hashToken(params.token, deps.tokenHashSecret))) {
+            throw new Error('INVALID_EMAIL_VERIFICATION_TOKEN');
+        }
+        const updated = await userRepo.markEmailVerified(record.userId, now);
+        const user = updated ?? await userRepo.findById(record.userId);
+        if (!user)
+            throw new Error('USER_NOT_FOUND');
+        await deps.emailVerificationTokenRepo.markUsed(record.id, { usedAt: now });
+        return { ok: true, user: toAuthUser(user) };
+    }
+    async function signInWithOAuthProfile(profile) {
+        if (!deps.oauthAccountRepo)
+            throw new Error('OAUTH_UNSUPPORTED');
+        if (!profile.provider || !profile.providerAccountId)
+            throw new Error('INVALID_OAUTH_PROFILE');
+        const linkedAccount = await deps.oauthAccountRepo.findByProviderAccount(profile.provider, profile.providerAccountId);
+        if (linkedAccount) {
+            const existingUser = await userRepo.findById(linkedAccount.userId);
+            if (!existingUser)
+                throw new Error('USER_NOT_FOUND');
+            return { user: existingUser, ...(await issueTokens(existingUser, deps)) };
+        }
+        let user = null;
+        const canLinkByEmail = deps.linkOAuthByVerifiedEmail !== false && profile.email && profile.emailVerified === true;
+        if (canLinkByEmail && profile.email) {
+            user = await userRepo.findByEmail(profile.email);
+        }
+        if (!user) {
+            if (!profile.email)
+                throw new Error('OAUTH_EMAIL_REQUIRED');
+            const passwordHash = await bcrypt.hash(createSecret(), resolvePasswordHashRounds(deps.passwordHashRounds));
+            user = await userRepo.create({
+                email: profile.email,
+                passwordHash,
+                name: profile.name ?? null,
+                role: resolveRegisterRole(deps.defaultRegisterRole),
+            });
+        }
+        await deps.oauthAccountRepo.create({
+            provider: profile.provider,
+            providerAccountId: profile.providerAccountId,
+            userId: user.id,
+            email: profile.email ?? null,
+        });
+        const authUser = toAuthUser(user);
+        return { user: authUser, ...(await issueTokens(authUser, deps)) };
+    }
     return {
         async registerUser(params) {
             const exists = await userRepo.findByEmail(params.email);
@@ -32,7 +206,7 @@ export function makeAuthService(deps) {
                 role,
             });
             const authUser = toAuthUser(user);
-            return { user: authUser, ...issueTokens(authUser) };
+            return { user: authUser, ...(await issueTokens(authUser, deps)) };
         },
         async loginUser(params) {
             const user = await userRepo.findByEmail(params.email);
@@ -42,7 +216,7 @@ export function makeAuthService(deps) {
             if (!ok)
                 throw new Error('INVALID_CREDENTIALS');
             const authUser = toAuthUser(user);
-            return { user: authUser, ...issueTokens(authUser) };
+            return { user: authUser, ...(await issueTokens(authUser, deps)) };
         },
         async refreshSession(refreshToken) {
             const payload = verifyToken(refreshToken);
@@ -51,10 +225,47 @@ export function makeAuthService(deps) {
             const user = await userRepo.findById(payload.sub);
             if (!user)
                 throw new Error('USER_NOT_FOUND');
-            return issueTokens(user);
+            if (!deps.refreshTokenRepo)
+                return issueTokens(user, deps);
+            if (!payload.jti || !payload.fam)
+                throw new Error('INVALID_REFRESH_TOKEN');
+            const record = await deps.refreshTokenRepo.findById(payload.jti);
+            const now = getNow(deps);
+            if (!record || record.userId.toString() !== payload.sub.toString() || record.familyId !== payload.fam) {
+                throw new Error('INVALID_REFRESH_TOKEN');
+            }
+            if (record.revokedAt) {
+                await deps.refreshTokenRepo.revokeFamily?.(record.familyId, { revokedAt: now, reason: 'refresh-token-replay' });
+                throw new Error('REFRESH_TOKEN_REPLAYED');
+            }
+            if (isExpired(record.expiresAt, now) || !safeEqual(record.tokenHash, hashToken(refreshToken, deps.tokenHashSecret))) {
+                throw new Error('INVALID_REFRESH_TOKEN');
+            }
+            const nextTokens = await issueTokens(user, deps, record.familyId);
+            await deps.refreshTokenRepo.revoke(record.id, {
+                revokedAt: now,
+                replacedByTokenId: nextTokens.refreshTokenId ?? null,
+                reason: 'rotated',
+            });
+            return { accessToken: nextTokens.accessToken, refreshToken: nextTokens.refreshToken };
+        },
+        async revokeRefreshToken(refreshToken) {
+            const payload = verifyToken(refreshToken);
+            if (payload.typ !== 'refresh')
+                throw new Error('INVALID_REFRESH_TOKEN');
+            if (deps.refreshTokenRepo && payload.jti) {
+                await deps.refreshTokenRepo.revoke(payload.jti, { revokedAt: getNow(deps), reason: 'revoked' });
+            }
+            return { ok: true };
         },
         getMe(userId) {
             return userRepo.findById(userId);
         },
+        requestPasswordReset,
+        confirmPasswordReset,
+        requestEmailVerification,
+        confirmEmailVerification,
+        signInWithOAuthProfile,
+        loginWithOAuthProfile: signInWithOAuthProfile,
     };
 }

package/dist/modules/auth/auth.types.d.ts

@@ -1,10 +1,126 @@
 import type { UserRepo } from '../../core/ports/user.repo.js';
 import type { Role, UserListItem } from '../user/user.types.js';
-export type AuthUserRepo = Pick<UserRepo, 'create' | 'findByEmail' | 'findById'>;
+export type AuthUserRepo = Pick<UserRepo, 'create' | 'findByEmail' | 'findById'> & Pick<Partial<UserRepo>, 'updatePassword' | 'markEmailVerified'>;
+export type RefreshTokenRecord = {
+    id: string;
+    userId: number | string;
+    tokenHash: string;
+    familyId: string;
+    expiresAt: Date | string;
+    revokedAt?: Date | string | null;
+    replacedByTokenId?: string | null;
+};
+export type RefreshTokenRepo = {
+    create(input: {
+        id: string;
+        userId: number | string;
+        tokenHash: string;
+        familyId: string;
+        expiresAt: Date;
+    }): Promise<RefreshTokenRecord | void>;
+    findById(id: string): Promise<RefreshTokenRecord | null>;
+    revoke(id: string, input?: {
+        revokedAt?: Date;
+        replacedByTokenId?: string | null;
+        reason?: string;
+    }): Promise<void>;
+    revokeFamily?(familyId: string, input?: {
+        revokedAt?: Date;
+        reason?: string;
+    }): Promise<void>;
+};
+export type PasswordResetTokenRecord = {
+    id: string;
+    userId: number | string;
+    tokenHash: string;
+    expiresAt: Date | string;
+    usedAt?: Date | string | null;
+    revokedAt?: Date | string | null;
+};
+export type PasswordResetTokenRepo = {
+    create(input: {
+        id: string;
+        userId: number | string;
+        tokenHash: string;
+        expiresAt: Date;
+    }): Promise<PasswordResetTokenRecord | void>;
+    findById(id: string): Promise<PasswordResetTokenRecord | null>;
+    markUsed(id: string, input?: {
+        usedAt?: Date;
+    }): Promise<void>;
+    revoke?(id: string, input?: {
+        revokedAt?: Date;
+        reason?: string;
+    }): Promise<void>;
+};
+export type EmailVerificationTokenRecord = {
+    id: string;
+    userId: number | string;
+    tokenHash: string;
+    expiresAt: Date | string;
+    usedAt?: Date | string | null;
+    revokedAt?: Date | string | null;
+};
+export type EmailVerificationTokenRepo = {
+    create(input: {
+        id: string;
+        userId: number | string;
+        tokenHash: string;
+        expiresAt: Date;
+    }): Promise<EmailVerificationTokenRecord | void>;
+    findById(id: string): Promise<EmailVerificationTokenRecord | null>;
+    markUsed(id: string, input?: {
+        usedAt?: Date;
+    }): Promise<void>;
+    revoke?(id: string, input?: {
+        revokedAt?: Date;
+        reason?: string;
+    }): Promise<void>;
+};
+export type OAuthProviderProfile = {
+    provider: string;
+    providerAccountId: string;
+    email?: string | null;
+    emailVerified?: boolean;
+    name?: string | null;
+    avatarUrl?: string | null;
+};
+export type OAuthAccount = {
+    provider: string;
+    providerAccountId: string;
+    userId: number | string;
+    email?: string | null;
+};
+export type OAuthAccountRepo = {
+    findByProviderAccount(provider: string, providerAccountId: string): Promise<OAuthAccount | null>;
+    findByUserAndProvider?(userId: number | string, provider: string): Promise<OAuthAccount | null>;
+    create(input: OAuthAccount): Promise<OAuthAccount | void>;
+};
 export type AuthServiceDeps = {
     userRepo: AuthUserRepo;
     passwordHashRounds?: number;
     defaultRegisterRole?: Role;
+    refreshTokenRepo?: RefreshTokenRepo;
+    refreshTokenTtlMs?: number;
+    passwordResetTokenRepo?: PasswordResetTokenRepo;
+    passwordResetTtlMs?: number;
+    sendPasswordReset?: (input: {
+        user: AuthUser;
+        token: string;
+        expiresAt: Date;
+    }) => Promise<void> | void;
+    emailVerificationTokenRepo?: EmailVerificationTokenRepo;
+    emailVerificationTtlMs?: number;
+    sendEmailVerification?: (input: {
+        user: AuthUser;
+        token: string;
+        expiresAt: Date;
+    }) => Promise<void> | void;
+    oauthAccountRepo?: OAuthAccountRepo;
+    linkOAuthByVerifiedEmail?: boolean;
+    tokenHashSecret?: string;
+    idFactory?: () => string;
+    now?: () => Date;
 };
 export type AuthUser = UserListItem;
 export type AuthTokens = {
@@ -14,3 +130,16 @@ export type AuthTokens = {
 export type AuthResult = AuthTokens & {
     user: AuthUser;
 };
+export type PasswordResetRequestInput = {
+    email: string;
+};
+export type PasswordResetConfirmInput = {
+    token: string;
+    password: string;
+};
+export type EmailVerificationRequestInput = {
+    email: string;
+};
+export type EmailVerificationConfirmInput = {
+    token: string;
+};

package/dist/modules/user/user.types.d.ts

@@ -4,6 +4,7 @@ export type UserListItem = {
     email: string;
     name: string | null;
     role: Role;
+    emailVerifiedAt?: Date | string | null;
     createdAt: Date | string;
     updatedAt: Date | string;
     profile?: {

package/dist/schemas.d.ts

@@ -1,2 +1,2 @@
-export { loginSchema, registerSchema } from './modules/auth/auth.schemas.js';
+export { emailVerificationConfirmSchema, emailVerificationRequestSchema, loginSchema, passwordResetConfirmSchema, passwordResetRequestSchema, registerSchema, } from './modules/auth/auth.schemas.js';
 export { SortEnum, adminCreateUserSchema, adminUpdateUserSchema, listUsersQuerySchema, updateMeSchema, } from './modules/user/user.schemas.js';

package/dist/schemas.js

@@ -1,2 +1,2 @@
-export { loginSchema, registerSchema } from './modules/auth/auth.schemas.js';
+export { emailVerificationConfirmSchema, emailVerificationRequestSchema, loginSchema, passwordResetConfirmSchema, passwordResetRequestSchema, registerSchema, } from './modules/auth/auth.schemas.js';
 export { SortEnum, adminCreateUserSchema, adminUpdateUserSchema, listUsersQuerySchema, updateMeSchema, } from './modules/user/user.schemas.js';

package/dist/utils/jwt.d.ts

@@ -2,6 +2,8 @@ export type JwtPayload = {
     sub: number | string;
     role: "USER" | "ADMIN";
     typ?: "refresh";
+    jti?: string;
+    fam?: string;
 };
 export declare function signAccessToken(payload: JwtPayload): string;
 export declare function signRefreshToken(payload: JwtPayload): string;

package/docs/auth-extensions.md

@@ -0,0 +1,120 @@
+# Auth extensions
+
+The core auth flow remains stateless and adapter-driven. Advanced auth features are enabled only when the corresponding repository and hook dependencies are passed to `makeAuthService()` or `createAuthRouter()`.
+
+## Persistent refresh token rotation
+
+By default, refresh tokens are stateless JWTs. This is simple and works for small apps, but a stolen refresh token remains valid until expiry unless you rotate the signing secret.
+
+Persistent refresh tokens add server-side state:
+
+- Refresh JWTs include a token ID and token family ID.
+- The repository stores a hash of the refresh token, never the raw token.
+- `/auth/refresh` rotates the refresh token and revokes the previous token.
+- Reusing a revoked refresh token is treated as replay and revokes the full token family when the repository supports `revokeFamily`.
+- `/auth/logout` revokes the submitted refresh token.
+
+```ts
+import { createAuthRouter } from "my-crud-lib/auth";
+import {
+  makePrismaRefreshTokenRepo,
+  makePrismaUserRepo,
+} from "my-crud-lib/adapter-prisma";
+
+app.use(
+  "/auth",
+  createAuthRouter({
+    userRepo: makePrismaUserRepo(prisma),
+    refreshTokenRepo: makePrismaRefreshTokenRepo(prisma),
+  })
+);
+```
+
+## Password reset
+
+Password reset is app-owned for delivery. The library creates a one-time opaque token, stores only its hash, and calls your delivery hook.
+
+Routes:
+
+- `POST /auth/password-reset/request`
+- `POST /auth/password-reset/confirm`
+
+```ts
+import {
+  makePrismaPasswordResetTokenRepo,
+  makePrismaUserRepo,
+} from "my-crud-lib/adapter-prisma";
+
+createAuthRouter({
+  userRepo: makePrismaUserRepo(prisma),
+  passwordResetTokenRepo: makePrismaPasswordResetTokenRepo(prisma),
+  async sendPasswordReset({ user, token, expiresAt }) {
+    await emailProvider.sendPasswordReset(user.email, token, expiresAt);
+  },
+});
+```
+
+Security expectations:
+
+- Return a generic success response for unknown emails.
+- Keep reset token TTLs short.
+- Send the token only through an out-of-band channel controlled by the application.
+- Require HTTPS in production.
+
+## Email verification
+
+Email verification uses the same one-time token pattern as password reset. Delivery stays app-owned.
+
+Routes:
+
+- `POST /auth/email-verification/request`
+- `POST /auth/email-verification/confirm`
+
+```ts
+import {
+  makePrismaEmailVerificationTokenRepo,
+  makePrismaUserRepo,
+} from "my-crud-lib/adapter-prisma";
+
+createAuthRouter({
+  userRepo: makePrismaUserRepo(prisma),
+  emailVerificationTokenRepo: makePrismaEmailVerificationTokenRepo(prisma),
+  async sendEmailVerification({ user, token, expiresAt }) {
+    await emailProvider.sendVerification(user.email, token, expiresAt);
+  },
+});
+```
+
+The bundled Prisma schema includes `User.emailVerifiedAt`. Existing Prisma users only need to add that column when they enable email verification. Apps should gate privileged behavior according to their own rules.
+
+## OAuth and social login
+
+OAuth provider redirects, scopes, and provider SDKs remain outside the core package. The auth service exposes a provider-agnostic account-linking method:
+
+```ts
+import {
+  makeAuthService,
+  type OAuthProviderProfile,
+} from "my-crud-lib/auth";
+import {
+  makePrismaOAuthAccountRepo,
+  makePrismaUserRepo,
+} from "my-crud-lib/adapter-prisma";
+
+const auth = makeAuthService({
+  userRepo: makePrismaUserRepo(prisma),
+  oauthAccountRepo: makePrismaOAuthAccountRepo(prisma),
+});
+
+const profile: OAuthProviderProfile = {
+  provider: "github",
+  providerAccountId: githubUser.id,
+  email: githubUser.email,
+  emailVerified: true,
+  name: githubUser.name,
+};
+
+const result = await auth.signInWithOAuthProfile(profile);
+```
+
+If a provider account is already linked, the linked user is used. Otherwise, a verified email can be linked to an existing user. If no user exists, the service creates one with an unusable generated password hash and links the provider account.

package/docs/github-self-hosted-runner.md

@@ -0,0 +1,76 @@
+# GitHub self-hosted runner
+
+Questa configurazione sposta il calcolo delle pipeline da `ubuntu-latest` al server registrato come runner GitHub Actions.
+
+Il runner non elimina GitHub Actions: GitHub resta l'orchestratore, ma i job vengono eseguiti su questa macchina.
+
+## Strategia consigliata
+
+Per usare lo stesso server su piu progetti, registra il runner a livello di organizzazione GitHub e assegna il label custom `local-ci`.
+
+Poi in ogni workflow usa:
+
+```yaml
+runs-on: [self-hosted, linux, x64, local-ci]
+```
+
+Se i repository sono sotto un account personale e non sotto un'organizzazione, GitHub non offre un runner unico per tutto l'account: va registrato un runner per ogni repository, oppure conviene spostare i progetti dentro una organizzazione.
+
+## Registrazione da interfaccia GitHub
+
+Organizzazione:
+
+1. Vai su `Organization settings > Actions > Runners`.
+2. Crea un nuovo self-hosted runner Linux x64.
+3. Aggiungi il label `local-ci`.
+4. Se usi runner group, limita l'accesso ai repository che devono usare questo server.
+
+Repository singolo:
+
+1. Vai su `Repository settings > Actions > Runners`.
+2. Crea un nuovo self-hosted runner Linux x64.
+3. Aggiungi il label `local-ci`.
+
+## Installazione sul server
+
+Genera il token temporaneo dalla pagina GitHub del runner e poi esegui:
+
+```bash
+GITHUB_URL="https://github.com/OWNER_OR_ORG" \
+RUNNER_TOKEN="TOKEN_GENERATO_DA_GITHUB" \
+RUNNER_NAME="server-ci-01" \
+scripts/setup-github-runner.sh
+```
+
+Per un repository singolo:
+
+```bash
+GITHUB_URL="https://github.com/OWNER/REPOSITORY" \
+RUNNER_TOKEN="TOKEN_GENERATO_DA_GITHUB" \
+RUNNER_NAME="server-ci-01" \
+scripts/setup-github-runner.sh
+```
+
+Variabili utili:
+
+- `RUNNER_LABELS`: label custom, default `local-ci`.
+- `RUNNER_VERSION`: versione del runner, default `2.334.0`.
+- `RUNNER_USER`: utente Linux del servizio, default `actions-runner`.
+- `INSTALL_DIR`: directory di installazione, default `/opt/actions-runner/$RUNNER_NAME`.
+- `RUNNER_GROUP`: runner group GitHub opzionale, utile nelle organizzazioni.
+
+## Requisiti del server
+
+Per questo progetto servono Node.js e npm. Il server corrente ha Docker installato; se altri progetti usano container, assicurati che l'utente del runner abbia i permessi necessari.
+
+Installa sul server cio che usano le pipeline dei vari repository, ad esempio:
+
+```bash
+node --version
+npm --version
+docker --version
+```
+
+## Sicurezza
+
+Evita self-hosted runner su repository pubblici che eseguono workflow da pull request non fidate: codice esterno potrebbe girare sul server. Per repo pubblici, usa approvazione manuale dei workflow, runner group ristretti e segreti con scope minimo.