@tc-libs/env 0.0.0-stage → 5.11.1

package/README.md

@@ -1,3 +1,105 @@
-# Temporary Holding Version
+# @tc-libs/env
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Configurazione d'ambiente con i segreti fuori da git. La configurazione non segreta (URL, flag, porte, TTL) resta
+versionata nei file env del progetto; i segreti stanno in AWS Secrets Manager, un segreto JSON per servizio e ambiente,
+per esempio `borgarello/dev/core`. Sulle VM il `.env` lo compone il deploy; questo pacchetto serve al codice e allo
+sviluppo locale:
+
+- `secret()` e `secretKeys()` marcano e leggono le chiavi segrete nello schema Joi del progetto, che resta l'unico
+  elenco delle variabili;
+- `secretKeysIn()` è il controllo per i test: un file env versionato non deve definire chiavi segrete;
+- la CLI `tc-env pull` compone un `.env` dalla configurazione versionata e dal segreto.
+
+## Chiavi segrete nello schema
+
+```ts
+import Joi from 'joi';
+import { secret } from '@tc-libs/env';
+
+export const envSchema = Joi.object({
+  APP_NAME: Joi.string().required(),
+  DATABASE_PASSWORD: secret(Joi.string().required()),
+  AUTH_JWT_ACCESS_TOKEN_SECRET_KEY: secret(Joi.string().min(32).required()),
+});
+```
+
+`secret()` aggiunge `.meta({ secret: true })` e non cambia la validazione.
+
+## Controllo nei test
+
+```ts
+import { readFileSync } from 'node:fs';
+import { secretKeys, secretKeysIn } from '@tc-libs/env';
+import { envSchema } from './validation';
+
+it.each(['.env.dev', '.env.staging', '.env.prod'])(
+  '%s non definisce chiavi segrete',
+  (file) => {
+    expect(
+      secretKeysIn(readFileSync(file, 'utf8'), secretKeys(envSchema)),
+    ).toEqual([]);
+  },
+);
+```
+
+## `.env` locale
+
+Uno script per ambiente nel `package.json` del progetto, per esempio:
+
+```json
+"env:pull": "tc-env pull --secret-id borgarello/dev/core --config config/local.env --out .env"
+```
+
+`tc-env pull`:
+
+- legge il segreto con le credenziali AWS locali: `--profile`, oppure `AWS_PROFILE`, oppure la catena di default
+  dell'SDK. La regione arriva da `--region`, dal profilo o da `AWS_REGION`;
+- si ferma prima di leggere il segreto se il file di output non è ignorato da git (un file versionato non lo è mai) o
+  se coincide con la configurazione;
+- scrive la configurazione così com'è e poi i segreti, con permessi 600, e stampa solo dei conteggi;
+- si ferma con un errore che nomina solo le chiavi, mai i valori, se una chiave sta sia nella configurazione sia nel
+  segreto, se il segreto non è un oggetto JSON di stringhe o se un valore non si può scrivere in un file dotenv.
+
+I valori si scrivono tra apici singoli, oppure tra backtick se contengono un apice: dotenv e `parseEnv` di Node li
+rileggono identici, senza escape. Il segreto contiene quindi il valore come lo restituisce il parser dotenv, prima
+dell'eventuale espansione delle variabili (`expandVariables` di `@nestjs/config`). Non sono supportati i valori su più
+righe e quelli che contengono sia un apice sia un backtick.
+
+## Comandi su un altro ambiente
+
+Per lanciare dal proprio PC un comando su un altro ambiente, per esempio un seed su prod, si compone un file a parte,
+ignorato da git, e lo si cancella dopo l'uso:
+
+```bash
+npx tc-env pull --secret-id borgarello/prod/core --config .env.prod --out .env.prod.local
+npx cross-env DOT_ENV_FILE=.env.prod.local npm run seed:email
+rm .env.prod.local
+```
+
+`DOT_ENV_FILE` è il meccanismo di Borgarello per scegliere il file env; ogni progetto usa il suo.
+
+## Permessi AWS
+
+Chi esegue `pull` ha bisogno di `secretsmanager:GetSecretValue` sul segreto, più `kms:Decrypt` se il segreto è cifrato
+con una chiave KMS del cliente invece di quella di default. Gli ARN dei segreti hanno un suffisso casuale, quindi la
+risorsa si indica con un carattere jolly:
+
+```json
+{
+  "Effect": "Allow",
+  "Action": "secretsmanager:GetSecretValue",
+  "Resource": "arn:aws:secretsmanager:<regione>:<account>:secret:borgarello/dev/*"
+}
+```
+
+## API
+
+| Funzione                                              | Uso                                                        |
+| ----------------------------------------------------- | ---------------------------------------------------------- |
+| `secret(schema)`                                      | marca una variabile Joi come segreto                       |
+| `secretKeys(objectSchema)`                            | chiavi segrete dello schema, in ordine alfabetico          |
+| `secretKeysIn(content, keys)`                         | chiavi segrete definite nel contenuto di un file env       |
+| `composeEnv(configContent, secrets, source)`          | testo del `.env`: configurazione e segreti                 |
+| `readSecret(secretId, region?)`                       | segreto JSON di Secrets Manager come oggetto di stringhe   |
+| `pullEnv({ secretId, configFile, outFile, region? })` | scrive il `.env` e restituisce i conteggi                  |
+| `EnvError`                                            | errore con messaggi che nominano chiavi e file, mai valori |

package/package.json

@@ -1,6 +1,23 @@
 {
   "name": "@tc-libs/env",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "5.11.1",
+  "dependencies": {
+    "@aws-sdk/client-secrets-manager": "^3.1160.0",
+    "tslib": "^2.8.1"
+  },
+  "type": "commonjs",
+  "main": "./src/index.js",
+  "typings": "./src/index.d.ts",
+  "bin": {
+    "tc-env": "./src/cli.js"
+  },
+  "peerDependencies": {
+    "joi": "^17.0.0 || ^18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "joi": {
+      "optional": true
+    }
+  },
+  "types": "./src/index.d.ts"
+}

package/src/cli.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+type Io = {
+    out: (line: string) => void;
+    err: (line: string) => void;
+};
+export declare function main(argv: string[], io?: Io): Promise<number>;
+export {};

package/src/cli.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.main = main;
+const node_util_1 = require("node:util");
+const env_error_1 = require("./env.error");
+const env_pull_1 = require("./env.pull");
+const USAGE = `Uso: tc-env pull --secret-id <id> --config <file> --out <file> [--region <regione>] [--profile <profilo>]
+
+Scrive <out> unendo la configurazione versionata <config> e il segreto JSON <id> di AWS Secrets Manager, letto con le
+credenziali AWS locali: il profilo indicato, AWS_PROFILE oppure la catena di default. <out> deve essere ignorato da git.`;
+async function main(argv, io = { out: console.log, err: console.error }) {
+    let parsed;
+    try {
+        parsed = (0, node_util_1.parseArgs)({
+            args: argv,
+            allowPositionals: true,
+            options: {
+                'secret-id': { type: 'string' },
+                config: { type: 'string' },
+                out: { type: 'string' },
+                region: { type: 'string' },
+                profile: { type: 'string' },
+            },
+        });
+    }
+    catch (error) {
+        io.err(error.message);
+        io.err(USAGE);
+        return 2;
+    }
+    const { positionals, values } = parsed;
+    const secretId = values['secret-id'];
+    const { config, out, region, profile } = values;
+    if (positionals.join(' ') !== 'pull' || !secretId || !config || !out) {
+        io.err(USAGE);
+        return 2;
+    }
+    // la catena di credenziali dell'SDK legge il profilo da AWS_PROFILE
+    if (profile)
+        process.env['AWS_PROFILE'] = profile;
+    try {
+        const result = await (0, env_pull_1.pullEnv)({
+            secretId,
+            configFile: config,
+            outFile: out,
+            region,
+        });
+        io.out(`${out}: ${result.configKeys} chiavi di configurazione e ${result.secretKeys} segreti da ${secretId}`);
+        return 0;
+    }
+    catch (error) {
+        if (!(error instanceof env_error_1.EnvError))
+            throw error;
+        io.err(`tc-env: ${error.message}`);
+        return 1;
+    }
+}
+if (require.main === module) {
+    main(process.argv.slice(2)).then((code) => {
+        process.exitCode = code;
+    });
+}
+//# sourceMappingURL=cli.js.map

package/src/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../../../packages/env/src/cli.ts"],"names":[],"mappings":";;;AAYA,oBAiDC;AA5DD,yCAAsC;AACtC,2CAAuC;AACvC,yCAAqC;AAErC,MAAM,KAAK,GAAG;;;yHAG2G,CAAC;AAInH,KAAK,UAAU,IAAI,CACxB,IAAc,EACd,KAAS,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,OAAO,CAAC,KAAK,EAAE;IAEjD,IAAI,MAAM,CAAC;IACX,IAAI,CAAC;QACH,MAAM,GAAG,IAAA,qBAAS,EAAC;YACjB,IAAI,EAAE,IAAI;YACV,gBAAgB,EAAE,IAAI;YACtB,OAAO,EAAE;gBACP,WAAW,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBAC/B,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBAC1B,GAAG,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBACvB,MAAM,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBAC1B,OAAO,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;aAC5B;SACF,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,EAAE,CAAC,GAAG,CAAE,KAAe,CAAC,OAAO,CAAC,CAAC;QACjC,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACd,OAAO,CAAC,CAAC;IACX,CAAC;IAED,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,MAAM,CAAC;IACvC,MAAM,QAAQ,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC;IACrC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;IAChD,IAAI,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,MAAM,IAAI,CAAC,QAAQ,IAAI,CAAC,MAAM,IAAI,CAAC,GAAG,EAAE,CAAC;QACrE,EAAE,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACd,OAAO,CAAC,CAAC;IACX,CAAC;IACD,oEAAoE;IACpE,IAAI,OAAO;QAAE,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC,GAAG,OAAO,CAAC;IAElD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,IAAA,kBAAO,EAAC;YAC3B,QAAQ;YACR,UAAU,EAAE,MAAM;YAClB,OAAO,EAAE,GAAG;YACZ,MAAM;SACP,CAAC,CAAC;QACH,EAAE,CAAC,GAAG,CACJ,GAAG,GAAG,KAAK,MAAM,CAAC,UAAU,+BAA+B,MAAM,CAAC,UAAU,eAAe,QAAQ,EAAE,CACtG,CAAC;QACF,OAAO,CAAC,CAAC;IACX,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAI,CAAC,CAAC,KAAK,YAAY,oBAAQ,CAAC;YAAE,MAAM,KAAK,CAAC;QAC9C,EAAE,CAAC,GAAG,CAAC,WAAW,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QACnC,OAAO,CAAC,CAAC;IACX,CAAC;AACH,CAAC;AAED,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;IAC5B,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE;QACxC,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;IAC1B,CAAC,CAAC,CAAC;AACL,CAAC"}

package/src/env.error.d.ts

@@ -0,0 +1,3 @@
+export declare class EnvError extends Error {
+    constructor(message: string);
+}

package/src/env.error.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EnvError = void 0;
+// Errore della configurazione d'ambiente: il messaggio nomina chiavi, file e segreti, mai i valori.
+class EnvError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'EnvError';
+    }
+}
+exports.EnvError = EnvError;
+//# sourceMappingURL=env.error.js.map

package/src/env.error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.error.js","sourceRoot":"","sources":["../../../../packages/env/src/env.error.ts"],"names":[],"mappings":";;;AAAA,oGAAoG;AACpG,MAAa,QAAS,SAAQ,KAAK;IACjC,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;IACzB,CAAC;CACF;AALD,4BAKC"}

package/src/env.file.d.ts

@@ -0,0 +1,2 @@
+export declare function composeEnv(configContent: string, secrets: Record<string, string>, source: string): string;
+export declare function secretKeysIn(content: string, secretKeys: readonly string[]): string[];

package/src/env.file.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.composeEnv = composeEnv;
+exports.secretKeysIn = secretKeysIn;
+const node_util_1 = require("node:util");
+const env_error_1 = require("./env.error");
+const KEY = /^[A-Za-z_][A-Za-z0-9_]*$/;
+function parse(content) {
+    return (0, node_util_1.parseEnv)(content);
+}
+// Il valore si scrive in modo che dotenv e parseEnv di Node lo rileggano identico: tra apici singoli, oppure tra
+// backtick se contiene un apice. Per entrambi i parser le due forme sono letterali, senza escape: un $ resta un $ e
+// l'eventuale espansione delle variabili (expandVariables di @nestjs/config) si comporta come con il file originale.
+function quote(key, value) {
+    if (/[\r\n]/.test(value)) {
+        throw new env_error_1.EnvError(`${key}: i valori su più righe non sono supportati`);
+    }
+    if (!value.includes("'"))
+        return `'${value}'`;
+    if (!value.includes('`'))
+        return `\`${value}\``;
+    throw new env_error_1.EnvError(`${key}: il valore contiene sia ' sia \`, che un file dotenv non sa racchiudere`);
+}
+// Il .env completo: la configurazione versionata così com'è, poi i segreti. Una chiave non può stare in entrambi.
+function composeEnv(configContent, secrets, source) {
+    const config = parse(configContent);
+    const invalid = Object.keys(secrets)
+        .filter((key) => !KEY.test(key))
+        .sort();
+    if (invalid.length) {
+        throw new env_error_1.EnvError(`nomi di variabile non validi nel segreto: ${invalid.join(', ')}`);
+    }
+    const both = Object.keys(secrets)
+        .filter((key) => key in config)
+        .sort();
+    if (both.length) {
+        throw new env_error_1.EnvError(`chiavi presenti sia nella configurazione sia nel segreto: ${both.join(', ')}`);
+    }
+    const configText = configContent.replace(/\r\n/g, '\n');
+    const secretLines = Object.keys(secrets)
+        .sort()
+        .map((key) => `${key}=${quote(key, secrets[key])}`);
+    return [
+        `# Generato da tc-env con ${source}: non modificarlo a mano e non versionarlo.`,
+        configText.endsWith('\n') || !configText ? configText : `${configText}\n`,
+        `# Segreti da ${source}`,
+        ...secretLines,
+        '',
+    ].join('\n');
+}
+// Chiavi segrete definite in un file env: in un file versionato devono essere zero. Le righe commentate non contano.
+function secretKeysIn(content, secretKeys) {
+    const env = parse(content);
+    return secretKeys.filter((key) => key in env).sort();
+}
+//# sourceMappingURL=env.file.js.map

package/src/env.file.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.file.js","sourceRoot":"","sources":["../../../../packages/env/src/env.file.ts"],"names":[],"mappings":";;AAwBA,gCAkCC;AAGD,oCAMC;AAnED,yCAAqC;AACrC,2CAAuC;AAEvC,MAAM,GAAG,GAAG,0BAA0B,CAAC;AAEvC,SAAS,KAAK,CAAC,OAAe;IAC5B,OAAO,IAAA,oBAAQ,EAAC,OAAO,CAA2B,CAAC;AACrD,CAAC;AAED,iHAAiH;AACjH,oHAAoH;AACpH,qHAAqH;AACrH,SAAS,KAAK,CAAC,GAAW,EAAE,KAAa;IACvC,IAAI,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,oBAAQ,CAAC,GAAG,GAAG,6CAA6C,CAAC,CAAC;IAC1E,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,KAAK,GAAG,CAAC;IAC9C,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,KAAK,IAAI,CAAC;IAChD,MAAM,IAAI,oBAAQ,CAChB,GAAG,GAAG,0EAA0E,CACjF,CAAC;AACJ,CAAC;AAED,kHAAkH;AAClH,SAAgB,UAAU,CACxB,aAAqB,EACrB,OAA+B,EAC/B,MAAc;IAEd,MAAM,MAAM,GAAG,KAAK,CAAC,aAAa,CAAC,CAAC;IACpC,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC;SACjC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;SAC/B,IAAI,EAAE,CAAC;IACV,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;QACnB,MAAM,IAAI,oBAAQ,CAChB,6CAA6C,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAClE,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC;SAC9B,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,IAAI,MAAM,CAAC;SAC9B,IAAI,EAAE,CAAC;IACV,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;QAChB,MAAM,IAAI,oBAAQ,CAChB,6DAA6D,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC/E,CAAC;IACJ,CAAC;IAED,MAAM,UAAU,GAAG,aAAa,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACxD,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC;SACrC,IAAI,EAAE;SACN,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,GAAG,IAAI,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC;IACtD,OAAO;QACL,4BAA4B,MAAM,6CAA6C;QAC/E,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,IAAI;QACzE,gBAAgB,MAAM,EAAE;QACxB,GAAG,WAAW;QACd,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,qHAAqH;AACrH,SAAgB,YAAY,CAC1B,OAAe,EACf,UAA6B;IAE7B,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;IAC3B,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,IAAI,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;AACvD,CAAC"}

package/src/env.pull.d.ts

@@ -0,0 +1,11 @@
+export type PullEnvOptions = {
+    secretId: string;
+    configFile: string;
+    outFile: string;
+    region?: string;
+};
+export declare function readSecret(secretId: string, region?: string): Promise<Record<string, string>>;
+export declare function pullEnv(options: PullEnvOptions): Promise<{
+    configKeys: number;
+    secretKeys: number;
+}>;

package/src/env.pull.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readSecret = readSecret;
+exports.pullEnv = pullEnv;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_util_1 = require("node:util");
+const client_secrets_manager_1 = require("@aws-sdk/client-secrets-manager");
+const env_error_1 = require("./env.error");
+const env_file_1 = require("./env.file");
+// Il segreto è un oggetto JSON piatto { "CHIAVE": "valore" }, come lo salva l'editor chiave/valore della console. Le
+// credenziali sono quelle della catena di default dell'SDK: il profilo AWS dello sviluppatore, il ruolo su EC2.
+async function readSecret(secretId, region) {
+    const client = new client_secrets_manager_1.SecretsManagerClient(region ? { region } : {});
+    let raw;
+    try {
+        const result = await client.send(new client_secrets_manager_1.GetSecretValueCommand({ SecretId: secretId }));
+        raw = result.SecretString;
+    }
+    catch (error) {
+        // nome e messaggio degli errori dell'SDK non contengono valori del segreto
+        const { name, message } = error;
+        throw new env_error_1.EnvError(`lettura di ${secretId} non riuscita: ${name}: ${message}`);
+    }
+    finally {
+        client.destroy();
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw ?? '');
+    }
+    catch {
+        throw new env_error_1.EnvError(`${secretId}: il segreto non è un JSON valido`);
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new env_error_1.EnvError(`${secretId}: il segreto deve essere un oggetto JSON { "CHIAVE": "valore" }`);
+    }
+    const notStrings = Object.entries(parsed)
+        .filter(([, value]) => typeof value !== 'string')
+        .map(([key]) => key)
+        .sort();
+    if (notStrings.length) {
+        throw new env_error_1.EnvError(`${secretId}: valori non di tipo stringa per ${notStrings.join(', ')}`);
+    }
+    return parsed;
+}
+// Un file con segreti non deve poter finire in un commit: deve essere ignorato da git, e un file versionato non lo è
+// mai. Fuori da un repository git il controllo non si applica.
+function assertGitIgnored(file) {
+    const path = (0, node_path_1.resolve)(file);
+    const dir = (0, node_path_1.dirname)(path);
+    if (!(0, node_fs_1.existsSync)(dir)) {
+        throw new env_error_1.EnvError(`la cartella di ${file} non esiste`);
+    }
+    try {
+        (0, node_child_process_1.execFileSync)('git', ['check-ignore', '-q', '--', path], {
+            cwd: dir,
+            stdio: 'ignore',
+        });
+    }
+    catch (error) {
+        const { status, code } = error;
+        if (status === 128)
+            return;
+        if (status === 1) {
+            throw new env_error_1.EnvError(`${file} non è ignorato da git: aggiungilo al .gitignore prima di scriverci dei segreti`);
+        }
+        if (code === 'ENOENT') {
+            throw new env_error_1.EnvError('git non è disponibile: serve a verificare che il file di output sia ignorato');
+        }
+        throw error;
+    }
+}
+// Compone outFile dalla configurazione versionata e dal segreto, con permessi ristretti. Restituisce solo conteggi.
+async function pullEnv(options) {
+    const { secretId, configFile, outFile, region } = options;
+    if ((0, node_path_1.resolve)(configFile) === (0, node_path_1.resolve)(outFile)) {
+        throw new env_error_1.EnvError('il file di configurazione e quello di output coincidono');
+    }
+    if (!(0, node_fs_1.existsSync)(configFile)) {
+        throw new env_error_1.EnvError(`file di configurazione ${configFile} non trovato`);
+    }
+    assertGitIgnored(outFile);
+    const configContent = (0, node_fs_1.readFileSync)(configFile, 'utf8');
+    const secrets = await readSecret(secretId, region);
+    (0, node_fs_1.writeFileSync)(outFile, (0, env_file_1.composeEnv)(configContent, secrets, secretId), {
+        mode: 0o600,
+    });
+    // writeFileSync applica mode solo ai file nuovi
+    (0, node_fs_1.chmodSync)(outFile, 0o600);
+    return {
+        configKeys: Object.keys((0, node_util_1.parseEnv)(configContent)).length,
+        secretKeys: Object.keys(secrets).length,
+    };
+}
+//# sourceMappingURL=env.pull.js.map

package/src/env.pull.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.pull.js","sourceRoot":"","sources":["../../../../packages/env/src/env.pull.ts"],"names":[],"mappings":"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"}

package/src/env.schema.d.ts

@@ -0,0 +1,3 @@
+import type { ObjectSchema, Schema } from 'joi';
+export declare function secret<T extends Schema>(schema: T): T;
+export declare function secretKeys(schema: ObjectSchema): string[];

package/src/env.schema.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.secret = secret;
+exports.secretKeys = secretKeys;
+// Marca una variabile dello schema Joi come segreto: il suo valore arriva dal secret store, mai da un file env
+// versionato. La validazione non cambia.
+function secret(schema) {
+    // meta restituisce lo stesso schema; sull'unione Schema i tipi di Joi lo allargano ad AnySchema
+    return schema.meta({ secret: true });
+}
+// Chiavi marcate con secret nello schema delle variabili d'ambiente, in ordine alfabetico. Lo schema resta l'unico
+// elenco delle variabili: niente liste parallele da tenere allineate.
+function secretKeys(schema) {
+    const keys = (schema.describe()['keys'] ?? {});
+    return Object.keys(keys)
+        .filter((key) => keys[key]?.metas?.some((meta) => meta['secret'] === true))
+        .sort();
+}
+//# sourceMappingURL=env.schema.js.map

package/src/env.schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.schema.js","sourceRoot":"","sources":["../../../../packages/env/src/env.schema.ts"],"names":[],"mappings":";;AAMA,wBAGC;AAID,gCAQC;AAjBD,+GAA+G;AAC/G,yCAAyC;AACzC,SAAgB,MAAM,CAAmB,MAAS;IAChD,gGAAgG;IAChG,OAAO,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAM,CAAC;AAC5C,CAAC;AAED,mHAAmH;AACnH,sEAAsE;AACtE,SAAgB,UAAU,CAAC,MAAoB;IAC7C,MAAM,IAAI,GAAG,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,CAG5C,CAAC;IACF,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC;SACrB,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,IAAI,CAAC,CAAC;SAC1E,IAAI,EAAE,CAAC;AACZ,CAAC"}

package/src/index.d.ts

@@ -0,0 +1,4 @@
+export * from './env.error';
+export * from './env.schema';
+export * from './env.file';
+export * from './env.pull';

package/src/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+tslib_1.__exportStar(require("./env.error"), exports);
+tslib_1.__exportStar(require("./env.schema"), exports);
+tslib_1.__exportStar(require("./env.file"), exports);
+tslib_1.__exportStar(require("./env.pull"), exports);
+//# sourceMappingURL=index.js.map

package/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../packages/env/src/index.ts"],"names":[],"mappings":";;;AAAA,sDAA4B;AAC5B,uDAA6B;AAC7B,qDAA2B;AAC3B,qDAA2B"}