@alienplatform/sdk 1.10.7 → 1.11.0

package/dist/bindings/index.d.ts

@@ -9,4 +9,5 @@ export { Build } from "./build.js";
 export { ArtifactRegistry } from "./artifact-registry.js";
 export { WorkerBinding } from "./worker.js";
 export { ServiceAccount } from "./service-account.js";
+export { getPostgresConnection, type PostgresConnection } from "./postgres.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/bindings/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/bindings/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAA;AAC5B,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/bindings/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAA;AAC5B,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAA;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AACrD,OAAO,EAAE,qBAAqB,EAAE,KAAK,kBAAkB,EAAE,MAAM,eAAe,CAAA"}

package/dist/bindings/postgres.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Postgres binding accessor.
+ *
+ * Postgres is connection-only: unlike Storage/Kv/Queue there is no gRPC service to call,
+ * so this module does not use {@link AlienContext}. Instead the manager injects the
+ * connection details for a linked database into `ALIEN_<NAME>_BINDING` as JSON, and the
+ * workload turns them into a live connection here.
+ *
+ * The cloud variants deliberately carry only a *reference* to the connection password
+ * (Secrets Manager ARN / Secret Manager name / Key Vault URI), never the password itself.
+ * The workload resolves that reference at runtime using its own least-privilege identity
+ * — exactly what the `postgres/data-access` permission set grants — so the password never
+ * flows through the control plane or sits as a plaintext environment variable.
+ *
+ * The matching cloud secret SDK is imported lazily, so a workload only loads the SDK for
+ * the cloud it is actually running on.
+ */
+/**
+ * Everything a Postgres driver needs to connect. `ssl` is the node-postgres TLS value; for
+ * node-postgres pass it with the individual fields, not the connectionString (see the `ssl` note).
+ * It is a plain value any driver can read.
+ */
+export interface PostgresConnection {
+    /**
+     * `postgres://user:password@host:port/database?sslmode=<mode>`, with credentials
+     * percent-encoded. The `sslmode` mirrors the Rust resolver byte-for-byte (`disable`
+     * local, `prefer` external, `require` cloud) so a sslmode-aware consumer agrees with us.
+     */
+    connectionString: string;
+    /**
+     * The TLS setting for the driver: `false` for plaintext-capable bindings (local/external),
+     * `{ rejectUnauthorized: false }` for managed clouds (TLS on, cert not yet verified against a
+     * pinned CA).
+     *
+     * For node-postgres, pass this with the individual fields — `new Client({ host, port, ..., ssl })`
+     * — NOT with the connectionString. node-postgres parses the URL's `sslmode` (it treats `require`
+     * as `verify-full`) and that overwrites an explicit `ssl`, so the URL form rejects the cloud cert
+     * with "unable to get local issuer certificate". Field style lets this value take effect.
+     *
+     * `rejectUnauthorized: false` is a deliberate v1 posture: Postgres is private-only on every cloud
+     * (no public IP, reachable only from same-stack workloads), so the network boundary is the primary
+     * control and an on-path MITM would already be inside the stack VPC. Verified TLS (provider CAs) is
+     * future defense-in-depth, not a v1 requirement.
+     *
+     * For the `external` (BYO) backend this is always `false`: node-postgres has no `prefer` mode, so
+     * the field stays plaintext while the connection string's `sslmode=prefer` only reaches sslmode-aware
+     * consumers (psql). A BYO database that *requires* TLS must have TLS configured outside this struct.
+     */
+    ssl: false | {
+        rejectUnauthorized: boolean;
+    };
+    /**
+     * The same connection details as individual fields, for drivers that take them separately
+     * (`new Client({ host, port, user: username, password, database })`) instead of a URL. These are
+     * the un-encoded values that `connectionString` percent-encodes; `host` is the address to dial
+     * (the Aurora cluster endpoint for the managed-AWS backend).
+     */
+    host: string;
+    port: number;
+    database: string;
+    username: string;
+    password: string;
+}
+export declare function encodeUserinfo(value: string): string;
+/**
+ * Resolves the connection details for a linked Postgres database.
+ *
+ * @param bindingName The resource id used when the database was linked (e.g. the value
+ *   passed to `new alien.Postgres(id)`).
+ * @returns A connection string plus `ssl`, and the same details as individual fields
+ *   (`host`/`port`/`database`/`username`/`password`) — use whichever style your driver prefers.
+ * @throws AlienError if the binding env var is missing, malformed, or names a backend
+ *   whose secret resolution is not available in this build.
+ *
+ * @example
+ * ```typescript
+ * import { Client } from "pg"
+ * import { getPostgresConnection } from "@alienplatform/sdk"
+ *
+ * const conn = await getPostgresConnection("my-db")
+ * // Field style: node-postgres parses a URL's sslmode and would override `ssl`, so pass fields.
+ * const client = new Client({
+ *   host: conn.host, port: conn.port, database: conn.database,
+ *   user: conn.username, password: conn.password, ssl: conn.ssl,
+ * })
+ * await client.connect()
+ * ```
+ */
+export declare function getPostgresConnection(bindingName: string): Promise<PostgresConnection>;
+//# sourceMappingURL=postgres.d.ts.map

package/dist/bindings/postgres.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres.d.ts","sourceRoot":"","sources":["../../src/bindings/postgres.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAUH;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,gBAAgB,EAAE,MAAM,CAAA;IACxB;;;;;;;;;;;;;;;;;;OAkBG;IACH,GAAG,EAAE,KAAK,GAAG;QAAE,kBAAkB,EAAE,OAAO,CAAA;KAAE,CAAA;IAC5C;;;;;OAKG;IACH,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;CACjB;AA0ED,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAKpD;AAgCD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAmE5F"}

package/dist/bindings/postgres.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=postgres.test.d.ts.map

package/dist/bindings/postgres.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres.test.d.ts","sourceRoot":"","sources":["../../src/bindings/postgres.test.ts"],"names":[],"mappings":""}