@metreeca/gear-gcp 0.3.1 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.d.ts +32 -5
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +59 -1
- package/dist/index.js.map +1 -1
- package/dist/secrets.d.ts +33 -0
- package/dist/secrets.d.ts.map +1 -0
- package/dist/secrets.js +106 -0
- package/dist/secrets.js.map +1 -0
- package/package.json +10 -2
package/dist/index.d.ts
CHANGED
|
@@ -1,10 +1,37 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Google Cloud
|
|
2
|
+
* The Google Cloud Platform execution environment.
|
|
3
3
|
*
|
|
4
|
-
*
|
|
5
|
-
*
|
|
4
|
+
* Exposes the ambient settings shared by the Google Cloud integrations, such as whether the process is deployed to a
|
|
5
|
+
* Google Cloud runtime, which port its HTTP service listens on and which project it runs in. Each setting is resolved
|
|
6
|
+
* on first access and retained afterwards, so later changes to the environment of the process are not reflected.
|
|
6
7
|
*
|
|
7
|
-
* @
|
|
8
|
+
* @see {@link https://cloud.google.com/docs/authentication Google Cloud Authentication}
|
|
8
9
|
*/
|
|
9
|
-
export {
|
|
10
|
+
export declare const gcp: {
|
|
11
|
+
/**
|
|
12
|
+
* Whether the current process is running on Google Cloud.
|
|
13
|
+
*
|
|
14
|
+
* The flag is set for a process deployed to Cloud Run, Cloud Functions, App Engine, Google Kubernetes Engine or
|
|
15
|
+
* Compute Engine. It is cleared for a process running locally, such as a development server or a test runner.
|
|
16
|
+
*
|
|
17
|
+
* @see {@link https://cloud.google.com/run/docs/container-contract#env-vars Cloud Run environment variables}
|
|
18
|
+
* @see {@link https://cloud.google.com/appengine/docs/standard/nodejs/runtime#environment_variables App Engine environment variables}
|
|
19
|
+
*/
|
|
20
|
+
readonly cloud: boolean;
|
|
21
|
+
/**
|
|
22
|
+
* The port an HTTP service is expected to listen on.
|
|
23
|
+
*
|
|
24
|
+
* The port is read from the `PORT` environment variable, which managed Google Cloud runtimes set to the port they
|
|
25
|
+
* route requests to; it defaults to `8080` if the variable is unset or empty.
|
|
26
|
+
*/
|
|
27
|
+
readonly port: number;
|
|
28
|
+
/**
|
|
29
|
+
* The ID of the Google Cloud project the process runs in.
|
|
30
|
+
*
|
|
31
|
+
* On a Google Cloud runtime the project is the one the process is deployed to; locally it is the one selected by
|
|
32
|
+
* the application default credentials or by the `gcloud` configuration. The promise rejects if no project is
|
|
33
|
+
* configured for the process.
|
|
34
|
+
*/
|
|
35
|
+
readonly project: Promise<string>;
|
|
36
|
+
};
|
|
10
37
|
//# sourceMappingURL=index.d.ts.map
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAuCA;;;;;;;;GAQG;AACH,eAAO,MAAM,GAAG;IAEf;;;;;;;;OAQG;oBACU,OAAO;IAMpB;;;;;OAKG;mBACS,MAAM;IAMlB;;;;;;OAMG;sBACY,OAAO,CAAC,MAAM,CAAC;CAM7B,CAAC"}
|
package/dist/index.js
CHANGED
|
@@ -13,5 +13,63 @@
|
|
|
13
13
|
* See the License for the specific language governing permissions and
|
|
14
14
|
* limitations under the License.
|
|
15
15
|
*/
|
|
16
|
-
|
|
16
|
+
/**
|
|
17
|
+
* Google Cloud service implementations.
|
|
18
|
+
*
|
|
19
|
+
* Exposes the settings of the Google Cloud environment a job runs in. Dedicated subpath modules provide implementations
|
|
20
|
+
* of the shared services a job relies on, backed by Google Cloud facilities, to be bound in place of the defaults for
|
|
21
|
+
* the duration of an execution, with no configuration beyond the ambient Google Cloud credentials.
|
|
22
|
+
*
|
|
23
|
+
* @module index
|
|
24
|
+
*/
|
|
25
|
+
import { immutable } from "@metreeca/core/values";
|
|
26
|
+
import { getGCPResidency } from "gcp-metadata";
|
|
27
|
+
import { GoogleAuth } from "google-auth-library";
|
|
28
|
+
/**
|
|
29
|
+
* Values of the {@link gcp} settings, each resolved on first access and kept for the lifetime of the process.
|
|
30
|
+
*/
|
|
31
|
+
const cache = {};
|
|
32
|
+
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
33
|
+
/**
|
|
34
|
+
* The Google Cloud Platform execution environment.
|
|
35
|
+
*
|
|
36
|
+
* Exposes the ambient settings shared by the Google Cloud integrations, such as whether the process is deployed to a
|
|
37
|
+
* Google Cloud runtime, which port its HTTP service listens on and which project it runs in. Each setting is resolved
|
|
38
|
+
* on first access and retained afterwards, so later changes to the environment of the process are not reflected.
|
|
39
|
+
*
|
|
40
|
+
* @see {@link https://cloud.google.com/docs/authentication Google Cloud Authentication}
|
|
41
|
+
*/
|
|
42
|
+
export const gcp = immutable({
|
|
43
|
+
/**
|
|
44
|
+
* Whether the current process is running on Google Cloud.
|
|
45
|
+
*
|
|
46
|
+
* The flag is set for a process deployed to Cloud Run, Cloud Functions, App Engine, Google Kubernetes Engine or
|
|
47
|
+
* Compute Engine. It is cleared for a process running locally, such as a development server or a test runner.
|
|
48
|
+
*
|
|
49
|
+
* @see {@link https://cloud.google.com/run/docs/container-contract#env-vars Cloud Run environment variables}
|
|
50
|
+
* @see {@link https://cloud.google.com/appengine/docs/standard/nodejs/runtime#environment_variables App Engine environment variables}
|
|
51
|
+
*/
|
|
52
|
+
get cloud() {
|
|
53
|
+
return cache.cloud ??= getGCPResidency() || Boolean(process.env.GAE_SERVICE);
|
|
54
|
+
},
|
|
55
|
+
/**
|
|
56
|
+
* The port an HTTP service is expected to listen on.
|
|
57
|
+
*
|
|
58
|
+
* The port is read from the `PORT` environment variable, which managed Google Cloud runtimes set to the port they
|
|
59
|
+
* route requests to; it defaults to `8080` if the variable is unset or empty.
|
|
60
|
+
*/
|
|
61
|
+
get port() {
|
|
62
|
+
return cache.port ??= Number(process.env.PORT || 8080);
|
|
63
|
+
},
|
|
64
|
+
/**
|
|
65
|
+
* The ID of the Google Cloud project the process runs in.
|
|
66
|
+
*
|
|
67
|
+
* On a Google Cloud runtime the project is the one the process is deployed to; locally it is the one selected by
|
|
68
|
+
* the application default credentials or by the `gcloud` configuration. The promise rejects if no project is
|
|
69
|
+
* configured for the process.
|
|
70
|
+
*/
|
|
71
|
+
get project() {
|
|
72
|
+
return cache.project ??= new GoogleAuth().getProjectId();
|
|
73
|
+
}
|
|
74
|
+
});
|
|
17
75
|
//# sourceMappingURL=index.js.map
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG"}
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;GAQG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAGjD;;GAEG;AACH,MAAM,KAAK,GAA0D,EAAE,CAAC;AAGxE,wHAAwH;AAExH;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,GAAG,GAAG,SAAS,CAAC;IAE5B;;;;;;;;OAQG;IACH,IAAI,KAAK;QAER,OAAO,KAAK,CAAC,KAAK,KAAK,eAAe,EAAE,IAAI,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAE9E,CAAC;IAED;;;;;OAKG;IACH,IAAI,IAAI;QAEP,OAAO,KAAK,CAAC,IAAI,KAAK,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC;IAExD,CAAC;IAED;;;;;;OAMG;IACH,IAAI,OAAO;QAEV,OAAO,KAAK,CAAC,OAAO,KAAK,IAAI,UAAU,EAAE,CAAC,YAAY,EAAE,CAAC;IAE1D,CAAC;CAED,CAAC,CAAC"}
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
import { Vault } from "@metreeca/gear/vault";
|
|
2
|
+
/**
|
|
3
|
+
* Creates a Secret Manager vault.
|
|
4
|
+
*
|
|
5
|
+
* Parameters are looked up among the secrets of the project the process is authenticated against as each request is
|
|
6
|
+
* served, so that a secret created or rotated after the vault was constructed is retrieved as well. Each lookup
|
|
7
|
+
* returns the payload of the latest version of the secret, under the naming constraints {@link secret} defines.
|
|
8
|
+
*
|
|
9
|
+
* @returns A vault retrieving parameters from the Secret Manager of the project the process is authenticated against
|
|
10
|
+
*
|
|
11
|
+
* @throws {@link !Error Error} While retrieving a parameter, under the conditions listed by {@link secret}
|
|
12
|
+
*/
|
|
13
|
+
export declare function createGCPVault(): Vault;
|
|
14
|
+
/**
|
|
15
|
+
* Reads a secret.
|
|
16
|
+
*
|
|
17
|
+
* Retrieves the payload of the latest version of a secret from the Secret Manager of the project the process is
|
|
18
|
+
* authenticated against.
|
|
19
|
+
*
|
|
20
|
+
* Secret names are limited to letters, digits, underscores and hyphens: a `key` carrying any other character names no
|
|
21
|
+
* secret and is reported as a failure.
|
|
22
|
+
*
|
|
23
|
+
* @param key The name of the secret to be read
|
|
24
|
+
*
|
|
25
|
+
* @returns A promise resolving to the textual payload of the latest version of the secret named `key`
|
|
26
|
+
*
|
|
27
|
+
* @throws {@link !Error Error} If `key` names no secret, if the secret is not accessible, or if its latest version
|
|
28
|
+
* carries no payload
|
|
29
|
+
*
|
|
30
|
+
* @see {@link https://cloud.google.com/secret-manager/docs/creating-and-accessing-secrets Accessing secrets}
|
|
31
|
+
*/
|
|
32
|
+
export declare function secret(key: string): Promise<string>;
|
|
33
|
+
//# sourceMappingURL=secrets.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"secrets.d.ts","sourceRoot":"","sources":["../src/secrets.ts"],"names":[],"mappings":"AAuCA,OAAO,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAkB7C;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,IAAI,KAAK,CAItC;AAKD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAqCzD"}
|
package/dist/secrets.js
ADDED
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
/*
|
|
2
|
+
* Copyright © 2026 Metreeca srl
|
|
3
|
+
*
|
|
4
|
+
* Licensed under the Apache License, Version 2.0 (the "License");
|
|
5
|
+
* you may not use this file except in compliance with the License.
|
|
6
|
+
* You may obtain a copy of the License at
|
|
7
|
+
*
|
|
8
|
+
* http://www.apache.org/licenses/LICENSE-2.0
|
|
9
|
+
*
|
|
10
|
+
* Unless required by applicable law or agreed to in writing, software
|
|
11
|
+
* distributed under the License is distributed on an "AS IS" BASIS,
|
|
12
|
+
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
13
|
+
* See the License for the specific language governing permissions and
|
|
14
|
+
* limitations under the License.
|
|
15
|
+
*/
|
|
16
|
+
/**
|
|
17
|
+
* Secret Manager parameter lookup.
|
|
18
|
+
*
|
|
19
|
+
* Looks up credentials, API keys and other sensitive parameters among the secrets stored in Google Cloud Secret
|
|
20
|
+
* Manager. The project is discovered from the ambient Google Cloud credentials, with no configuration required.
|
|
21
|
+
*
|
|
22
|
+
* @module
|
|
23
|
+
*
|
|
24
|
+
* @remarks
|
|
25
|
+
*
|
|
26
|
+
* Secrets are read from the project the ambient credentials resolve to and no other: no configuration is available to
|
|
27
|
+
* target a different project, so a task reading its secrets has to be executed under credentials for that project.
|
|
28
|
+
*
|
|
29
|
+
* The Secret Manager client is created when the module is first imported and retained for the lifetime of the process:
|
|
30
|
+
* the gRPC channel it opens is never closed and keeps the event loop alive, so a short-lived task may have to exit
|
|
31
|
+
* explicitly once its work is done, rather than wait for the process to terminate on its own.
|
|
32
|
+
*
|
|
33
|
+
* @see {@link https://cloud.google.com/nodejs/docs/reference/secret-manager/latest Secret Manager Node.js Client}
|
|
34
|
+
* @see {@link https://cloud.google.com/nodejs/docs/reference/secret-manager/latest/secret-manager/v1.secretmanagerserviceclient SecretManagerServiceClient}
|
|
35
|
+
*/
|
|
36
|
+
import { SecretManagerServiceClient } from "@google-cloud/secret-manager";
|
|
37
|
+
import { error } from "@metreeca/core";
|
|
38
|
+
/**
|
|
39
|
+
* The gRPC status code reporting a secret or a secret version that doesn't exist.
|
|
40
|
+
*
|
|
41
|
+
* @see {@link https://grpc.io/docs/guides/status-codes/ gRPC status codes}
|
|
42
|
+
*/
|
|
43
|
+
const NOT_FOUND = 5;
|
|
44
|
+
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
45
|
+
const client = new SecretManagerServiceClient();
|
|
46
|
+
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
47
|
+
/**
|
|
48
|
+
* Creates a Secret Manager vault.
|
|
49
|
+
*
|
|
50
|
+
* Parameters are looked up among the secrets of the project the process is authenticated against as each request is
|
|
51
|
+
* served, so that a secret created or rotated after the vault was constructed is retrieved as well. Each lookup
|
|
52
|
+
* returns the payload of the latest version of the secret, under the naming constraints {@link secret} defines.
|
|
53
|
+
*
|
|
54
|
+
* @returns A vault retrieving parameters from the Secret Manager of the project the process is authenticated against
|
|
55
|
+
*
|
|
56
|
+
* @throws {@link !Error Error} While retrieving a parameter, under the conditions listed by {@link secret}
|
|
57
|
+
*/
|
|
58
|
+
export function createGCPVault() {
|
|
59
|
+
return secret;
|
|
60
|
+
}
|
|
61
|
+
////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////
|
|
62
|
+
/**
|
|
63
|
+
* Reads a secret.
|
|
64
|
+
*
|
|
65
|
+
* Retrieves the payload of the latest version of a secret from the Secret Manager of the project the process is
|
|
66
|
+
* authenticated against.
|
|
67
|
+
*
|
|
68
|
+
* Secret names are limited to letters, digits, underscores and hyphens: a `key` carrying any other character names no
|
|
69
|
+
* secret and is reported as a failure.
|
|
70
|
+
*
|
|
71
|
+
* @param key The name of the secret to be read
|
|
72
|
+
*
|
|
73
|
+
* @returns A promise resolving to the textual payload of the latest version of the secret named `key`
|
|
74
|
+
*
|
|
75
|
+
* @throws {@link !Error Error} If `key` names no secret, if the secret is not accessible, or if its latest version
|
|
76
|
+
* carries no payload
|
|
77
|
+
*
|
|
78
|
+
* @see {@link https://cloud.google.com/secret-manager/docs/creating-and-accessing-secrets Accessing secrets}
|
|
79
|
+
*/
|
|
80
|
+
export async function secret(key) {
|
|
81
|
+
try {
|
|
82
|
+
const name = client.secretVersionPath(await client.getProjectId(), key, "latest");
|
|
83
|
+
const [version] = await client.accessSecretVersion({ name });
|
|
84
|
+
const value = version.payload?.data?.toString();
|
|
85
|
+
return value ?? error(`undefined secret <${key}>`);
|
|
86
|
+
}
|
|
87
|
+
catch (e) {
|
|
88
|
+
if (missing(e)) {
|
|
89
|
+
throw error(`unknown secret <${key}>`);
|
|
90
|
+
}
|
|
91
|
+
else {
|
|
92
|
+
throw error(`failed to access secret <${key}>: ${e}`);
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
/**
|
|
96
|
+
* Checks if a failure reports a missing secret.
|
|
97
|
+
*
|
|
98
|
+
* @param cause The failure reported while accessing a secret
|
|
99
|
+
*
|
|
100
|
+
* @returns `true` if `cause` carries the {@link NOT_FOUND} gRPC status code; `false` otherwise
|
|
101
|
+
*/
|
|
102
|
+
function missing(cause) {
|
|
103
|
+
return typeof cause === "object" && cause !== null && "code" in cause && cause.code === NOT_FOUND;
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
//# sourceMappingURL=secrets.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"secrets.js","sourceRoot":"","sources":["../src/secrets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,EAAE,0BAA0B,EAAE,MAAM,8BAA8B,CAAC;AAC1E,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAIvC;;;;GAIG;AACH,MAAM,SAAS,GAAG,CAAC,CAAC;AAGpB,wHAAwH;AAExH,MAAM,MAAM,GAAG,IAAI,0BAA0B,EAAE,CAAC;AAGhD,wHAAwH;AAExH;;;;;;;;;;GAUG;AACH,MAAM,UAAU,cAAc;IAE7B,OAAO,MAAM,CAAC;AAEf,CAAC;AAGD,wHAAwH;AAExH;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,GAAW;IAEvC,IAAI,CAAC;QAEJ,MAAM,IAAI,GAAG,MAAM,CAAC,iBAAiB,CAAC,MAAM,MAAM,CAAC,YAAY,EAAE,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAC;QAClF,MAAM,CAAC,OAAO,CAAC,GAAG,MAAM,MAAM,CAAC,mBAAmB,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;QAC7D,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;QAEhD,OAAO,KAAK,IAAI,KAAK,CAAC,qBAAqB,GAAG,GAAG,CAAC,CAAC;IAEpD,CAAC;IAAC,OAAQ,CAAC,EAAG,CAAC;QAEd,IAAK,OAAO,CAAC,CAAC,CAAC,EAAG,CAAC;YAElB,MAAM,KAAK,CAAC,mBAAmB,GAAG,GAAG,CAAC,CAAC;QAExC,CAAC;aAAM,CAAC;YAEP,MAAM,KAAK,CAAC,4BAA4B,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC;QAEvD,CAAC;IAEF,CAAC;IAED;;;;;;OAMG;IACH,SAAS,OAAO,CAAC,KAAc;QAE9B,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,MAAM,IAAI,KAAK,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,CAAC;IAEnG,CAAC;AAEF,CAAC"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@metreeca/gear-gcp",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.0",
|
|
4
4
|
"description": "Google Cloud service implementations for @metreeca/gear.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"typescript",
|
|
@@ -31,6 +31,10 @@
|
|
|
31
31
|
".": {
|
|
32
32
|
"@metreeca/source": "./src/index.ts",
|
|
33
33
|
"default": "./dist/index.js"
|
|
34
|
+
},
|
|
35
|
+
"./secrets": {
|
|
36
|
+
"@metreeca/source": "./src/secrets.ts",
|
|
37
|
+
"default": "./dist/secrets.js"
|
|
34
38
|
}
|
|
35
39
|
},
|
|
36
40
|
"files": [
|
|
@@ -47,7 +51,11 @@
|
|
|
47
51
|
"check": "npx vitest --typecheck run"
|
|
48
52
|
},
|
|
49
53
|
"dependencies": {
|
|
50
|
-
"@
|
|
54
|
+
"@google-cloud/secret-manager": "^7.2.0",
|
|
55
|
+
"@metreeca/core": "^0.13.0",
|
|
56
|
+
"@metreeca/gear": "^0.4.0",
|
|
57
|
+
"gcp-metadata": "^9.2.1",
|
|
58
|
+
"google-auth-library": "^11.3.1"
|
|
51
59
|
},
|
|
52
60
|
"devDependencies": {
|
|
53
61
|
"@types/node": "^25.9.3",
|