@bastani/atomic-storage-postgres 0.0.0-placeholder.0 → 0.9.88-alpha.1

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/CHANGELOG.md ADDED
@@ -0,0 +1,28 @@
1
+ # Changelog
2
+
3
+ ## [Unreleased]
4
+
5
+ ## [0.9.88-alpha.1] - 2026-11-16
6
+
7
+ ### Added
8
+
9
+ - `@bastani/atomic-storage-postgres`, a PostgreSQL storage adapter for Atomic sessions, workflow journals, and Intercom, installed with `atomic install npm:@bastani/atomic-storage-postgres`. It keeps a pool of up to 8 connections per process, bounds every statement with a 30-second statement timeout, and works through transaction-mode poolers such as PgBouncer. The password comes from the selection's `secrets` and is read again for each new connection, so a rotated password file is picked up without a restart; a URL that carries a password is refused. Lock conflicts, cancelled statements, and refused or lost connections are reported as `StorageTransientError`, and a call that wrote nothing runs again. PostgreSQL 14 or newer is required ([#4793](https://github.com/bastani-inc/atomic/issues/4793))
10
+ - Cloud IAM authentication for the PostgreSQL adapter: set `auth` to `"azure-entra"`, `"aws-iam"` or `"gcp-iam"` and each new connection signs in with a short-lived token from the cloud's own SDK (`@azure/identity`, `@aws-sdk/rds-signer` or `google-auth-library`, installed beside the adapter as an optional peer dependency) instead of a stored password. Tokens stay in memory, each token request is time-limited, and a failure names the package to install or the SDK's reason without showing a token. The README lists the least-privilege role for each cloud ([#4793](https://github.com/bastani-inc/atomic/issues/4793))
11
+ - Wake-ups through `LISTEN`/`NOTIFY`: the adapter keeps one listening connection per process and exposes it as `notifications` on the opened database, so worker hosts and Intercom brokers learn about new work at once instead of at their next poll. Their polls stay, so a dropped listening connection or a transaction pooler only makes them slower, never loses work. Through a transaction pooler, set the new `listenUrl` option to the server's direct endpoint; otherwise the adapter detects that notifications do not arrive, unlistens, and uses polling alone for the rest of the process, so it leaves no `LISTEN` on the pooler's server connections. A listening connection that stops delivering, such as a half-open one, is found by a probe every 30 seconds and a short TCP keepalive, and replaced. `atomic storage status` says which applies ([#5103](https://github.com/bastani-inc/atomic/issues/5103))
12
+
13
+ ### Fixed
14
+
15
+ - Atomic's tables now live in a schema of their own, `atomic` (the new `schema` option), set per transaction with `SET LOCAL search_path` so a transaction-mode pooler can serve it. The owner role creates it, so `CREATE DATABASE … OWNER <role>` is enough on Azure, Amazon RDS, Cloud SQL and PostgreSQL 15 and later, where `public` gives no one `CREATE`. A database whose `public` schema holds an earlier release's tables keeps using it until `atomic storage migrate` moves them. Advisory locks and `LISTEN` channels are scoped to the schema, unchanged in `public` ([#5218](https://github.com/bastani-inc/atomic/issues/5218))
16
+ - A statement refused for a missing privilege (`42501`) now fails with `StorageConfigError` reason `missing-privilege`, which names the privilege and the fix (the runtime role's grant, or `atomic storage migrate` as the owner role), instead of the server's bare message ([#5218](https://github.com/bastani-inc/atomic/issues/5218))
17
+ - A server certificate that TLS verification refuses (`ERR_TLS_CERT_ALTNAME_INVALID`, `UNABLE_TO_VERIFY_LEAF_SIGNATURE` and the like) is no longer retried five times as an unreachable server: the open fails at once with the reason and the fix, a host name the certificate names or `sslrootcert` ([#5218](https://github.com/bastani-inc/atomic/issues/5218))
18
+ - A cloud token the server refuses (`28P01`, or Azure's `28000` for a malformed one) is dropped and a fresh one tried once, so a clock that runs behind no longer reuses an expired Entra token for every new connection ([#5218](https://github.com/bastani-inc/atomic/issues/5218))
19
+ - `@azure/identity`, `@aws-sdk/rds-signer` and `google-auth-library` installed with `atomic install npm:<package>` are now found by an adapter installed from a local path, from the user packages in `~/.atomic/agent/npm`, not only beside the adapter ([#5218](https://github.com/bastani-inc/atomic/issues/5218))
20
+ - A value over PostgreSQL's limit (`54000`, program limit exceeded) now fails with `StoragePayloadTooLargeError`, which names the 1 GB field limit, instead of being reported as the store being unavailable ([#4954](https://github.com/bastani-inc/atomic/issues/4954))
21
+ - A `?` inside a dollar-quoted string whose tag contains a non-ASCII character that is not a letter, such as `$·$` or an emoji, is no longer treated as a parameter, so the parameters after it are numbered correctly. Identifiers containing such characters are recognised the same way, matching PostgreSQL. A `?` written directly after an identifier or keyword, as in `LIMIT?`, now becomes a separate parameter instead of being read as part of that name ([#4834](https://github.com/bastani-inc/atomic/issues/4834))
22
+ - `statementTimeoutMs` now applies to statements run outside a transaction too. Before, only the client gave up on such a statement, 5 seconds after the timeout, while the server kept running it, so a write reported as failed with an unknown outcome could still be saved afterwards. The server now cancels it at the timeout and the call fails as `transaction-timeout` with nothing written, also through a transaction-mode pooler. When the client does give up on a server or network that stopped answering, it also asks the server to cancel the statement ([#4901](https://github.com/bastani-inc/atomic/issues/4901))
23
+ - An identifier longer than PostgreSQL's 63 bytes, in any statement, now reaches the server as the storage dialect's name for it (its head and a hash of the whole name) instead of being truncated, so a store whose prefix makes its names long finds again every table, index and trigger it created ([#4793](https://github.com/bastani-inc/atomic/issues/4793))
24
+ - `sslmode` now follows libpq without extra parameters: `verify-ca` checks the server certificate's CA (`sslrootcert`, or the CAs Node.js trusts) but not its host name, so a server reached by an address its certificate does not name, such as Cloud SQL by private IP, connects instead of failing with "Hostname/IP does not match certificate's altnames". `require` with `sslrootcert` does the same. `prefer` and `allow` encrypt without checking the certificate. `require` without `sslrootcert` still checks the certificate and its host name, stricter than libpq, and a URL with `uselibpqcompat` keeps pg's own reading of `sslmode`. A TLS parameter whose name is not lowercase, such as `SSLMODE=verify-full`, is now refused instead of being ignored by pg, which connected to a remote host without TLS; an `sslmode` libpq does not know is refused too ([#5113](https://github.com/bastani-inc/atomic/issues/5113))
25
+
26
+ ### Changed
27
+
28
+ - A transaction's statements now go to the server without waiting for the answer to the one before, and a transaction that sends several before it commits takes one round trip for all of them and its commit ([#5102](https://github.com/bastani-inc/atomic/issues/5102))
package/LICENSE ADDED
@@ -0,0 +1,24 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Bastani, Inc.
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ If your product or service exceeds 100 million monthly active users or $20 million in monthly revenue,
16
+ you must prominently display 'Atomic' on the user interface of such product or service.
17
+
18
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
19
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
20
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
21
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
22
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
23
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
24
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,150 @@
1
+ # @bastani/atomic-storage-postgres
2
+
3
+ A [PostgreSQL](https://www.postgresql.org) storage adapter for [Atomic](https://github.com/bastani-inc/atomic). It stores sessions, workflow journals, and Intercom multi-node routing in one shared PostgreSQL database, so several machines can use the same state. It is a separate package: install it only where you want Postgres storage.
4
+
5
+ ## Install
6
+
7
+ ```bash
8
+ atomic install npm:@bastani/atomic-storage-postgres
9
+ ```
10
+
11
+ Install in user scope (without `-l`); Atomic only searches user-scope packages for storage adapters.
12
+
13
+ ## Configure
14
+
15
+ Select the adapter in `~/.atomic/agent/settings.json`:
16
+
17
+ ```json
18
+ {
19
+ "storage": {
20
+ "adapter": "@bastani/atomic-storage-postgres",
21
+ "options": { "url": "postgresql://atomic@db.example.com:5432/atomic" },
22
+ "secrets": { "password": { "file": "postgres-password" } }
23
+ }
24
+ }
25
+ ```
26
+
27
+ ```bash
28
+ printf '%s' "$PASSWORD" > ~/.atomic/postgres-password
29
+ chmod 600 ~/.atomic/postgres-password
30
+ ```
31
+
32
+ | Option | Required | Description |
33
+ |---|---|---|
34
+ | `url` | yes | A `postgres://` or `postgresql://` URL with the user name but no password. A URL with a password, or with a `password=` parameter, is refused (`credential-in-url`). |
35
+ | `password` | when the server asks for one | Pass it through `secrets` (`{ "file": ... }` or `{ "env": ... }`). The reference is read again for every new connection, so a password file another process rotates in place is picked up by the next connection. |
36
+ | `auth` | no | `"password"` (default), or `"azure-entra"`, `"aws-iam"` or `"gcp-iam"` to sign in with a cloud identity instead of a password; see [Cloud IAM authentication](#cloud-iam-authentication). A cloud `auth` with a `password` is refused (`conflicting-token`). |
37
+ | `maxConnections` | no | Connections each process keeps open at most. Default 8. |
38
+ | `statementTimeoutMs` | no | How long one statement may run before the server cancels it. Default 30000. |
39
+ | `listenUrl` | no | A direct (session) endpoint for the connection that listens for wake-ups, when `url` goes through a transaction pooler. Default `url`. |
40
+ | `schema` | no | The schema Atomic's tables live in, a lowercase name. Default `atomic`, which the first store that sets up its tables creates when the role may. A database whose `public` schema holds an earlier release's tables, and has no `atomic` schema, keeps using `public` until `atomic storage migrate` moves them. Every transaction sets it with `SET LOCAL search_path`. |
41
+
42
+ PostgreSQL 14 or newer is required. A URL that names no `sslmode` gets `sslmode=verify-full` when its host is not this machine, so the connection is encrypted and the server certificate is checked. Name a CA with `sslrootcert=/path/to/ca.pem` when the server's certificate is not signed by a CA Node trusts, or set `sslmode` yourself. `sslmode` follows libpq: `verify-ca` checks the certificate's CA (`sslrootcert`, or else the CAs Node trusts) but not its host name, for a server reached by an address its certificate does not name; `prefer` and `allow` encrypt without checking the certificate; `disable` turns TLS off. `require` with `sslrootcert` acts as `verify-ca`; without it, `require` checks the certificate and its host name, as `verify-full` does, which is stricter than libpq. Parameter names are case-sensitive, as in libpq: a TLS parameter that is not lowercase, or an unknown `sslmode`, is refused.
43
+
44
+ The adapter works through a transaction-mode connection pooler (PgBouncer, Supavisor, and the poolers of managed services): it sets nothing outside a transaction, takes no session locks, and uses no named prepared statements.
45
+
46
+ Each process also keeps one connection outside the pool that `LISTEN`s for wake-ups (`notifications` on the opened database), so worker hosts and Intercom brokers find new work at once. A transaction-mode pooler does not deliver notifications to it: the adapter detects that with a probe and falls back to polling alone, unless `listenUrl` names the server's direct endpoint. Nothing is lost without wake-ups; work is found at the next poll. `atomic storage status` says which applies.
47
+
48
+ A failure that passes, such as a refused or lost connection, a lock conflict (SQLSTATE `40001`, `40P01`, `55P03`) or a cancelled statement (`57014`), is reported as `StorageTransientError`, and a call that wrote nothing runs again. Refused credentials (`28P01`), a missing database (`3D000`) and a refused server certificate fail at once. A missing privilege (`42501`) fails at once with `StorageConfigError` reason `missing-privilege`, which names the privilege and the grant or `atomic storage migrate` that fixes it. The password is redacted from error messages and diagnostics. Add a `prefix` to the `storage` block to keep projects or teams apart in one database. See [Storage](../coding-agent/docs/storage.md) for selection precedence and the other storage options.
49
+
50
+ ## Cloud IAM authentication
51
+
52
+ On Azure, AWS and Google Cloud the adapter can sign in with the machine's cloud identity instead of a stored password. Set `auth` and leave out `secrets.password`:
53
+
54
+ ```json
55
+ {
56
+ "storage": {
57
+ "adapter": "@bastani/atomic-storage-postgres",
58
+ "options": { "url": "postgresql://atomic-hosts@atomic.postgres.database.azure.com/atomic?sslmode=verify-full", "auth": "azure-entra" }
59
+ }
60
+ }
61
+ ```
62
+
63
+ Each cloud signs in through its own SDK, which the adapter does not bundle. Install the one your `auth` needs among the user packages (these are the versions the adapter is tested with). The adapter finds it beside itself, or in `~/.atomic/agent/npm`, where `atomic install npm:<package>` puts it, so an adapter installed from a local path finds it too:
64
+
65
+ | `auth` | SDK | Install | Where the token comes from |
66
+ |---|---|---|---|
67
+ | `azure-entra` | `@azure/identity` | `atomic install npm:@azure/identity@4.14.1` | `DefaultAzureCredential` with the scope `https://ossrdbms-aad.database.windows.net/.default`: `AZURE_*` variables, AKS workload identity, managed identity (VM, App Service, Container Apps; `AZURE_CLIENT_ID` selects a user-assigned one), then a developer's `az login`. |
68
+ | `aws-iam` | `@aws-sdk/rds-signer` | `atomic install npm:@aws-sdk/rds-signer@3.1169.0` | The RDS `Signer` for the URL's host, port and user, with the AWS SDK's default credential chain (`AWS_*` variables, profiles, IRSA, instance profile). The region comes from an RDS host name, otherwise from the SDK's configuration (`AWS_REGION` or the profile). |
69
+ | `gcp-iam` | `google-auth-library` | `atomic install npm:google-auth-library@11.3.4` | `GoogleAuth` with the scope `https://www.googleapis.com/auth/sqlservice.login`: Application Default Credentials (`GOOGLE_APPLICATION_CREDENTIALS`, the metadata server on Compute Engine, GKE and Cloud Run, or a developer's `gcloud auth application-default login`). |
70
+
71
+ In an SDK project, `npm install` the same package next to `@bastani/atomic-storage-postgres`; each is an optional peer dependency. Only the configured cloud's SDK is loaded, when the store opens its first connection.
72
+
73
+ For each new connection the adapter asks the SDK for a short-lived token and sends it as the password. Tokens are kept in memory only and never written to settings, logs or error messages; Azure tokens are reused until 5 minutes before they expire, and the AWS and Google SDKs cache their own credentials. A token the server refuses (`28P01`, or Azure's `28000` for a malformed one) is dropped, and the connection tried once more with a fresh one. One token request may take up to 8 seconds. When the SDK is missing or gives no token, opening fails with `StorageConfigError` reason `auth-unavailable`; the message names the package to install, or the SDK's own reason with anything shaped like a credential removed.
74
+
75
+ Cloud tokens require TLS; keep `sslmode=verify-full` (the default for a remote host) or at least `require`.
76
+
77
+ ### Least-privilege roles
78
+
79
+ Atomic uses two roles: an owner role that owns the database and the `atomic` schema and runs `atomic storage migrate`, and a runtime role for hosts, roots, sessions and brokers, which runs no DDL. Give a cloud identity the runtime role's privileges, as [Set up the database](../coding-agent/docs/storage.md#set-up-the-database) lists them; after `atomic storage migrate`, as the owner role:
80
+
81
+ ```sql
82
+ GRANT CONNECT ON DATABASE atomic TO "<identity>";
83
+ GRANT USAGE ON SCHEMA atomic TO "<identity>";
84
+ GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA atomic TO "<identity>";
85
+ GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA atomic TO "<identity>";
86
+ GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA atomic TO "<identity>";
87
+ ALTER DEFAULT PRIVILEGES FOR ROLE atomic_owner IN SCHEMA atomic GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO "<identity>";
88
+ ALTER DEFAULT PRIVILEGES FOR ROLE atomic_owner IN SCHEMA atomic GRANT USAGE, SELECT ON SEQUENCES TO "<identity>";
89
+ ALTER DEFAULT PRIVILEGES FOR ROLE atomic_owner IN SCHEMA atomic GRANT EXECUTE ON FUNCTIONS TO "<identity>";
90
+ ```
91
+
92
+ The cloud side needs no more than this:
93
+
94
+ **Azure Database for PostgreSQL (flexible server).** Enable Microsoft Entra authentication. As the Entra administrator, connected to the `postgres` database, create a role for the managed identity (named exactly as the identity) and grant it the database privileges:
95
+
96
+ ```sql
97
+ SELECT * FROM pgaadauth_create_principal('atomic-hosts', false, false);
98
+ GRANT CONNECT ON DATABASE atomic TO "atomic-hosts";
99
+ ```
100
+
101
+ The identity needs no Azure RBAC role; the URL's user is the role name.
102
+
103
+ **Amazon RDS and Aurora PostgreSQL.** Enable IAM database authentication on the instance or cluster, create the user, and allow only `rds-db:connect` for that user:
104
+
105
+ ```sql
106
+ CREATE USER atomic;
107
+ GRANT rds_iam TO atomic;
108
+ GRANT CONNECT ON DATABASE atomic TO atomic;
109
+ ```
110
+
111
+ ```json
112
+ {
113
+ "Effect": "Allow",
114
+ "Action": "rds-db:connect",
115
+ "Resource": "arn:aws:rds-db:<region>:<account-id>:dbuser:<DbiResourceId or cluster resource id>/atomic"
116
+ }
117
+ ```
118
+
119
+ **Google Cloud SQL for PostgreSQL.** Set the instance flag `cloudsql.iam_authentication=on`, add the service account as an IAM database user, and grant it `roles/cloudsql.instanceUser` (add `roles/cloudsql.client` only when connecting through the Cloud SQL Auth Proxy or a connector). The database user name is the service account's email without `.gserviceaccount.com`:
120
+
121
+ ```bash
122
+ gcloud sql users create atomic-hosts@my-project.iam --instance=atomic --type=cloud_iam_service_account
123
+ gcloud projects add-iam-policy-binding my-project \
124
+ --member=serviceAccount:atomic-hosts@my-project.iam.gserviceaccount.com --role=roles/cloudsql.instanceUser
125
+ ```
126
+
127
+ ```sql
128
+ GRANT CONNECT ON DATABASE atomic TO "atomic-hosts@my-project.iam";
129
+ ```
130
+
131
+ A Compute Engine VM must have the `cloud-platform` access scope for its metadata token to sign in. AlloyDB works the same way with `roles/alloydb.databaseUser` and `roles/serviceusage.serviceUsageConsumer`.
132
+
133
+ ## Use from the SDK
134
+
135
+ ```ts
136
+ import { openPostgresDatabase } from "@bastani/atomic-storage-postgres";
137
+
138
+ const database = await openPostgresDatabase({
139
+ url: "postgresql://atomic@db.example.com/atomic",
140
+ password: async () => readFile("/run/secrets/postgres-password", "utf8"),
141
+ });
142
+ ```
143
+
144
+ `password` is a string or a function called for each new connection. The returned `SqliteDatabase` can be passed as SDK `sessionStore: { kind: "database", database }` or workflow `journal: { database }`.
145
+
146
+ The package ships plain ESM JavaScript with TypeScript declarations. This import works in supported Node versions without a TypeScript loader.
147
+
148
+ ## License
149
+
150
+ MIT
package/auth.d.ts ADDED
@@ -0,0 +1,38 @@
1
+ /** A cloud identity that issues PostgreSQL passwords: Microsoft Entra ID, AWS RDS IAM, or Google Cloud SQL IAM. */
2
+ export type CloudAuth = "azure-entra" | "aws-iam" | "gcp-iam";
3
+
4
+ /**
5
+ * The SDK each cloud signs in with and the version the adapter is tested with. Each is an optional peer dependency,
6
+ * imported only when its `auth` is used: `@azure/identity`, `@aws-sdk/rds-signer`, `google-auth-library`.
7
+ */
8
+ export const CLOUD_AUTH_PACKAGES: { readonly [auth in CloudAuth]: { readonly name: string; readonly version: string } };
9
+
10
+ export interface CloudPasswordOptions {
11
+ readonly auth: CloudAuth;
12
+ /** The database host, as the connection URL names it. AWS signs its token for this host. */
13
+ readonly host: string;
14
+ readonly port: number;
15
+ /** The database user the token is for. */
16
+ readonly user: string;
17
+ /** Upper bound for one token request, in milliseconds. Default 8000. */
18
+ readonly timeoutMs?: number;
19
+ /**
20
+ * npm prefixes to find the SDK in when it is not found beside the adapter, such as `<agentDir>/npm`, where
21
+ * `atomic install npm:<package>` installs user packages.
22
+ */
23
+ readonly searchPaths?: readonly string[];
24
+ }
25
+
26
+ /**
27
+ * A password reader for `pg` that returns a cloud IAM token for each new connection, from the cloud's own SDK:
28
+ * `DefaultAzureCredential`, the RDS `Signer`, or `GoogleAuth`. Tokens live only in memory; concurrent connections
29
+ * share one request. Throws a `StorageConfigError` with reason `invalid-auth-target` when the host or user is
30
+ * missing, and the reader rejects with reason `auth-unavailable` when the SDK is not installed or issues no token.
31
+ * The adapter calls `invalidate` when the server refuses a token (`28P01`, or Azure's `28000`), and connects once more.
32
+ */
33
+ export function createCloudPasswordProvider(
34
+ options: CloudPasswordOptions,
35
+ ): (() => Promise<string>) & {
36
+ /** Forgets the cached token, so the next read asks the SDK again: after the server refused it (#5218). */
37
+ invalidate(): void;
38
+ };
package/auth.js ADDED
@@ -0,0 +1,237 @@
1
+ // @ts-check
2
+ import { createRequire } from "node:module";
3
+ import { join } from "node:path";
4
+ import { redactSecrets, StorageConfigError } from "@bastani/atomic/storage";
5
+
6
+ /**
7
+ * @typedef {"azure-entra" | "aws-iam" | "gcp-iam"} CloudAuth
8
+ * @typedef {{ auth: CloudAuth, host: string, port: number, user: string, timeoutMs?: number, searchPaths?: readonly string[] }} CloudPasswordOptions
9
+ * @typedef {{ token: string, refreshAt: number }} IssuedToken
10
+ * The parts of each cloud SDK this module uses. The SDKs are optional peer dependencies, so their own types may be
11
+ * absent where this package is type-checked.
12
+ * @typedef {{ token: string, expiresOnTimestamp: number }} AzureAccessToken
13
+ * @typedef {{ getToken(scope: string, options: { abortSignal: AbortSignal }): Promise<AzureAccessToken | null> }} AzureCredential
14
+ * @typedef {{ DefaultAzureCredential: new () => AzureCredential }} AzureIdentityModule
15
+ * @typedef {{ hostname: string, port: number, username: string, region?: string }} RdsSignerConfig
16
+ * @typedef {{ Signer: new (config: RdsSignerConfig) => { getAuthToken(): Promise<string> } }} RdsSignerModule
17
+ * @typedef {{ GoogleAuth: new (options: { scopes: string[] }) => { getAccessToken(): Promise<string | null | undefined> } }} GoogleAuthModule
18
+ */
19
+
20
+ /**
21
+ * The SDK each cloud signs in with, and the version the adapter is tested with. Each is an optional peer dependency:
22
+ * only the one the configured `auth` names is needed, and it is imported only when that `auth` is used.
23
+ */
24
+ export const CLOUD_AUTH_PACKAGES = /** @type {const} */ ({
25
+ "azure-entra": { name: "@azure/identity", version: "4.14.1" },
26
+ "aws-iam": { name: "@aws-sdk/rds-signer", version: "3.1169.0" },
27
+ "gcp-iam": { name: "google-auth-library", version: "11.3.4" },
28
+ });
29
+
30
+ /** An Azure token is replaced this long before it expires, so a connection never presents one about to lapse. */
31
+ const REFRESH_MARGIN_MS = 5 * 60_000;
32
+ /**
33
+ * How long one token request may take. pg gives a new connection 10 seconds in all, password included, so a slower
34
+ * answer would arrive after the connection already failed.
35
+ */
36
+ const DEFAULT_TIMEOUT_MS = 8_000;
37
+ /** The longest part of an SDK's failure message an error carries. */
38
+ const DETAIL_LIMIT = 300;
39
+ /** A run of characters long enough to be a token, signature or key an SDK might quote in a failure. */
40
+ const CREDENTIAL_SHAPE = /[\w+=.-]{32,}/g;
41
+ const AZURE_SCOPE = "https://ossrdbms-aad.database.windows.net/.default";
42
+ const GCP_SCOPE = "https://www.googleapis.com/auth/sqlservice.login";
43
+
44
+ /**
45
+ * @param {string} reason
46
+ * @param {string} hint
47
+ */
48
+ function authError(reason, hint) {
49
+ return new StorageConfigError("sdk", "auth", reason, hint);
50
+ }
51
+
52
+ /** Whether `error` says a module was not found, as `import()` and `require()` report it. */
53
+ function isNotFound(/** @type {unknown} */ error) {
54
+ const code = /** @type {NodeJS.ErrnoException} */ (error)?.code;
55
+ return code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND";
56
+ }
57
+
58
+ /**
59
+ * Imports `auth`'s SDK, or explains how to install it. It is found beside the adapter first, then in each of
60
+ * `searchPaths`, an npm prefix such as the one `atomic install npm:<package>` installs user packages into (#5218): an
61
+ * adapter installed from a local path resolves only its own `node_modules`, where `atomic install` puts nothing.
62
+ * @param {CloudAuth} auth
63
+ * @param {readonly string[]} searchPaths
64
+ */
65
+ async function loadSdk(auth, searchPaths) {
66
+ const { name, version } = CLOUD_AUTH_PACKAGES[auth];
67
+ try {
68
+ return await import(name);
69
+ } catch (error) {
70
+ /** @type {unknown} */
71
+ let failure = error;
72
+ if (isNotFound(error))
73
+ for (const prefix of searchPaths) {
74
+ try {
75
+ return createRequire(join(prefix, "package.json"))(name);
76
+ } catch (fallback) {
77
+ if (!isNotFound(fallback)) {
78
+ failure = fallback;
79
+ break;
80
+ }
81
+ }
82
+ }
83
+ const cause = /** @type {NodeJS.ErrnoException} */ (failure);
84
+ throw authError(
85
+ "auth-unavailable",
86
+ `${auth} auth needs the optional package ${name}, which could not be loaded (${cause.code ?? cause.message}). ` +
87
+ `Install it beside the adapter with \`atomic install npm:${name}@${version}\`, or \`npm install ${name}@${version}\` in an SDK project`,
88
+ );
89
+ }
90
+ }
91
+
92
+ /**
93
+ * The client `create` builds from `auth`'s SDK, made on first use and kept for the provider's life, so it keeps what
94
+ * it cached and learned about which credential source works. A failed load is tried again next time.
95
+ * @template T
96
+ * @param {CloudAuth} auth
97
+ * @param {(sdk: any) => T} create
98
+ * @param {readonly string[]} searchPaths
99
+ * @returns {() => Promise<T>}
100
+ */
101
+ function lazyClient(auth, create, searchPaths) {
102
+ /** @type {Promise<T> | undefined} */
103
+ let client;
104
+ return () => {
105
+ client ??= loadSdk(auth, searchPaths).then(create);
106
+ client.catch(() => {
107
+ client = undefined;
108
+ });
109
+ return client;
110
+ };
111
+ }
112
+
113
+ /**
114
+ * The token-fetching function of `auth`. Each fetch gets an abort signal that fires when it runs out of time.
115
+ * @param {CloudPasswordOptions} options
116
+ * @returns {(signal: AbortSignal) => Promise<IssuedToken>}
117
+ */
118
+ function tokenSource({ auth, host, port, user, searchPaths = [] }) {
119
+ if (auth === "azure-entra") {
120
+ const credential = lazyClient(
121
+ auth,
122
+ (/** @type {AzureIdentityModule} */ sdk) => new sdk.DefaultAzureCredential(),
123
+ searchPaths,
124
+ );
125
+ return async (signal) => {
126
+ const issued = await (await credential()).getToken(AZURE_SCOPE, { abortSignal: signal });
127
+ if (!issued?.token) throw new Error("returned no token");
128
+ // The Azure CLI and developer CLI sources run a process for every request, so tokens are reused here.
129
+ return { token: issued.token, refreshAt: issued.expiresOnTimestamp - REFRESH_MARGIN_MS };
130
+ };
131
+ }
132
+ if (auth === "aws-iam") {
133
+ // A token is signed for the database's region; an RDS endpoint names it, and the SDK's own configuration may not.
134
+ const region = host.match(/\.([a-z]{2}(?:-[a-z]+)+-\d+)\.rds\.amazonaws\.com(?:\.cn)?$/)?.[1];
135
+ const signer = lazyClient(
136
+ auth,
137
+ (/** @type {RdsSignerModule} */ sdk) =>
138
+ new sdk.Signer({ hostname: host, port, username: user, ...(region === undefined ? {} : { region }) }),
139
+ searchPaths,
140
+ );
141
+ return async () => {
142
+ const token = await (await signer()).getAuthToken();
143
+ if (!token) throw new Error("returned no token");
144
+ // Signing is local once the SDK holds credentials, which it caches and refreshes, so nothing is reused here.
145
+ return { token, refreshAt: 0 };
146
+ };
147
+ }
148
+ const client = lazyClient(
149
+ auth,
150
+ (/** @type {GoogleAuthModule} */ sdk) => new sdk.GoogleAuth({ scopes: [GCP_SCOPE] }),
151
+ searchPaths,
152
+ );
153
+ return async () => {
154
+ const token = await (await client()).getAccessToken();
155
+ if (!token) throw new Error("returned no token");
156
+ // google-auth-library caches the token and refreshes it before it expires, so nothing is reused here.
157
+ return { token, refreshAt: 0 };
158
+ };
159
+ }
160
+
161
+ /** What to do when the SDK found no credentials. */
162
+ const HINTS = /** @type {Record<CloudAuth, string>} */ ({
163
+ "azure-entra":
164
+ "Run where DefaultAzureCredential finds an identity (managed identity, AKS workload identity, AZURE_* variables, or `az login`), and grant it a database role",
165
+ "aws-iam":
166
+ "Give the AWS SDK credentials (instance profile, IRSA, AWS_* variables or a profile) allowed `rds-db:connect` for this user",
167
+ "gcp-iam":
168
+ "Run where Application Default Credentials find a service account that is a Cloud SQL IAM user, or run `gcloud auth application-default login`",
169
+ });
170
+
171
+ /**
172
+ * A password reader for `pg` that returns a cloud IAM token for each new connection, from the cloud's own SDK.
173
+ * Tokens live only in memory; concurrent connections share one request, and each request is bounded by
174
+ * `timeoutMs`. Every failure is a `StorageConfigError` with reason `auth-unavailable`, without a token in it.
175
+ * @param {CloudPasswordOptions} options
176
+ * @returns {(() => Promise<string>) & { invalidate(): void }}
177
+ */
178
+ export function createCloudPasswordProvider(options) {
179
+ const { auth, host, user } = options;
180
+ for (const [name, value] of [
181
+ ["host", host],
182
+ ["user", user],
183
+ ])
184
+ if (!value) throw authError("invalid-auth-target", `${auth} auth needs a ${name} in the URL`);
185
+ const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
186
+ const fetchToken = tokenSource(options);
187
+ /** Every token issued, so a later failure that quotes one cannot show it. */
188
+ const issuedTokens = new Set();
189
+
190
+ /** @type {IssuedToken | undefined} */
191
+ let cached;
192
+ /** @type {Promise<string> | undefined} */
193
+ let pending;
194
+
195
+ async function refresh() {
196
+ const controller = new AbortController();
197
+ /** @type {NodeJS.Timeout | undefined} */
198
+ let timer;
199
+ const deadline = new Promise((_resolve, reject) => {
200
+ timer = setTimeout(() => {
201
+ controller.abort();
202
+ reject(new Error(`timed out after ${timeoutMs} ms`));
203
+ }, timeoutMs);
204
+ });
205
+ try {
206
+ const issued = await Promise.race([fetchToken(controller.signal), deadline]);
207
+ issuedTokens.add(issued.token);
208
+ cached = issued;
209
+ return issued.token;
210
+ } catch (error) {
211
+ if (error instanceof StorageConfigError) throw error;
212
+ const message = String(/** @type {Error} */ (error)?.message ?? error)
213
+ .replace(/\s+/g, " ")
214
+ .trim();
215
+ const bounded = message.length > DETAIL_LIMIT ? `${message.slice(0, DETAIL_LIMIT)}…` : message;
216
+ const detail = redactSecrets(issuedTokens)(bounded).replace(CREDENTIAL_SHAPE, "[redacted]");
217
+ throw authError("auth-unavailable", `${auth} found no token (${detail || "no reason given"}). ${HINTS[auth]}`);
218
+ } finally {
219
+ clearTimeout(timer);
220
+ }
221
+ }
222
+
223
+ const read = async () => {
224
+ if (cached !== undefined && Date.now() < cached.refreshAt) return cached.token;
225
+ pending ??= refresh().finally(() => {
226
+ pending = undefined;
227
+ });
228
+ return pending;
229
+ };
230
+ // A token the server refused, such as one reused past its expiry by a clock that runs behind, is never used again
231
+ // (#5218).
232
+ return Object.assign(read, {
233
+ invalidate() {
234
+ cached = undefined;
235
+ },
236
+ });
237
+ }
package/listen.d.ts ADDED
@@ -0,0 +1,30 @@
1
+ import type { StorageNotifications } from "@bastani/atomic/storage";
2
+
3
+ /** A connected session the listener sends `LISTEN` on and receives notifications from. */
4
+ export interface ListenClient {
5
+ query(sql: string): Promise<unknown>;
6
+ on(event: "notification", listener: (message: { channel: string; payload?: string }) => void): unknown;
7
+ on(event: "error" | "end", listener: () => void): unknown;
8
+ end(): Promise<void>;
9
+ }
10
+
11
+ export interface ListenerOptions {
12
+ /** Opens a new session to the listening endpoint. */
13
+ connect: () => Promise<ListenClient>;
14
+ /** Sends a notification through the database's pool, as a store's transaction would. */
15
+ send: (channel: string, payload: string) => Promise<void>;
16
+ /** The identifier a channel name is sent and listened to as. */
17
+ channelName: (channel: string) => string;
18
+ /** Default `LISTEN_PROBE_TIMEOUT_MS`. */
19
+ probeTimeoutMs?: number;
20
+ /** Default `LISTEN_RETRY`. */
21
+ retry?: { readonly firstMs: number; readonly maxMs: number };
22
+ /** Default `LISTEN_HEALTH_INTERVAL_MS`. */
23
+ healthIntervalMs?: number;
24
+ }
25
+
26
+ export const LISTEN_PROBE_TIMEOUT_MS: 2000;
27
+ export const LISTEN_RETRY: { readonly firstMs: 1000; readonly maxMs: 30000 };
28
+ export const LISTEN_HEALTH_INTERVAL_MS: 30000;
29
+
30
+ export function createPostgresListener(options: ListenerOptions): StorageNotifications & { close(): Promise<void> };