@pipeline-builder/api-core 4.1.20 → 4.1.22

package/lib/services/s3-client.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The shared S3-compatible client, and the bucket-ensure backstop that goes
+ * with it.
+ *
+ * Backed by MinIO in every environment (self-hosted, no AWS-account coupling);
+ * because MinIO speaks the S3 API this uses the AWS S3 SDK, so a real-S3 swap is
+ * a pure config change (drop the custom endpoint + path-style, supply IAM creds).
+ *
+ * Config (env) — one set of names, read identically by every service; each
+ * container is pointed at its OWN bucket with bucket-scoped credentials:
+ *   S3_ENDPOINT           MinIO/S3 endpoint URL (e.g. http://minio:9000). Empty
+ *                         ⇒ default AWS S3 (no custom endpoint).
+ *   S3_REGION             region (default 'us-east-1').
+ *   S3_ACCESS_KEY_ID      access key.
+ *   S3_SECRET_ACCESS_KEY  secret key.
+ *   S3_FORCE_PATH_STYLE   'true' for MinIO (path-style addressing); default true.
+ *
+ * `S3_BUCKET` is deliberately NOT read here: the bucket is the caller's, and
+ * each service keeps its own default and its own key convention.
+ *
+ * **Reached through the `@pipeline-builder/api-core/s3` subpath, never the root
+ * barrel** — only two services do blob storage, and the S3 SDK is a large
+ * eager dependency that the other eight must not pay for at boot. Same reason
+ * `@aws-sdk/client-kms` is dynamically imported inside secret-encryption.
+ */
+import { S3Client } from '@aws-sdk/client-s3';
+/**
+ * The process-wide S3 client, built from env on first use.
+ *
+ * Lazy so a service that never touches blob storage — and a test that never
+ * configures S3 — never constructs one.
+ */
+export declare function s3Client(): S3Client;
+/**
+ * Ensure `bucket` exists, once per process per bucket.
+ *
+ * MinIO — unlike an auto-provisioned S3 bucket — won't create a bucket on first
+ * write, so HEAD it and CREATE on 404/NoSuchBucket. Idempotent and
+ * concurrency-safe: concurrent callers share the single in-flight promise.
+ *
+ * The important part is the failure branch. A CreateBucket failure is EITHER a
+ * benign race (another replica created it between our HEAD and our CREATE) or a
+ * real outage (MinIO not up yet, credentials wrong, network down). Re-HEADing
+ * tells them apart:
+ *
+ *  - it now exists  → benign race, continue;
+ *  - it still does not → DROP the memo entry and fail this attempt.
+ *
+ * Dropping the entry is load-bearing. Memoizing a resolved "ready" after a
+ * failed create caches a permanently-broken success for the process lifetime:
+ * every later upload then fails `NoSuchBucket` against a MinIO that came up
+ * seconds after boot, until the pod is restarted.
+ */
+export declare function ensureBucket(bucket: string): Promise<void>;

package/lib/services/s3-client.js

@@ -0,0 +1,106 @@
+// Copyright 2026 Pipeline Builder Contributors
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * The shared S3-compatible client, and the bucket-ensure backstop that goes
+ * with it.
+ *
+ * Backed by MinIO in every environment (self-hosted, no AWS-account coupling);
+ * because MinIO speaks the S3 API this uses the AWS S3 SDK, so a real-S3 swap is
+ * a pure config change (drop the custom endpoint + path-style, supply IAM creds).
+ *
+ * Config (env) — one set of names, read identically by every service; each
+ * container is pointed at its OWN bucket with bucket-scoped credentials:
+ *   S3_ENDPOINT           MinIO/S3 endpoint URL (e.g. http://minio:9000). Empty
+ *                         ⇒ default AWS S3 (no custom endpoint).
+ *   S3_REGION             region (default 'us-east-1').
+ *   S3_ACCESS_KEY_ID      access key.
+ *   S3_SECRET_ACCESS_KEY  secret key.
+ *   S3_FORCE_PATH_STYLE   'true' for MinIO (path-style addressing); default true.
+ *
+ * `S3_BUCKET` is deliberately NOT read here: the bucket is the caller's, and
+ * each service keeps its own default and its own key convention.
+ *
+ * **Reached through the `@pipeline-builder/api-core/s3` subpath, never the root
+ * barrel** — only two services do blob storage, and the S3 SDK is a large
+ * eager dependency that the other eight must not pay for at boot. Same reason
+ * `@aws-sdk/client-kms` is dynamically imported inside secret-encryption.
+ */
+import { S3Client, HeadBucketCommand, CreateBucketCommand } from '@aws-sdk/client-s3';
+import { envBool, envStr } from '../utils/env.js';
+import { createLogger } from '../utils/logger.js';
+const logger = createLogger('s3-client');
+let client = null;
+/**
+ * The process-wide S3 client, built from env on first use.
+ *
+ * Lazy so a service that never touches blob storage — and a test that never
+ * configures S3 — never constructs one.
+ */
+export function s3Client() {
+    if (client)
+        return client;
+    const endpoint = envStr('S3_ENDPOINT', '');
+    client = new S3Client({
+        region: envStr('S3_REGION', 'us-east-1'),
+        ...(endpoint ? { endpoint } : {}),
+        // Path-style is required by MinIO (no virtual-host bucket DNS). Harmless
+        // against real S3, but default-on here because MinIO is the default backend.
+        forcePathStyle: envBool('S3_FORCE_PATH_STYLE', true),
+        credentials: {
+            accessKeyId: envStr('S3_ACCESS_KEY_ID', 'minioadmin'),
+            secretAccessKey: envStr('S3_SECRET_ACCESS_KEY', 'minioadmin'),
+        },
+    });
+    return client;
+}
+/** In-flight / settled ensure per bucket. A rejected attempt is never left here. */
+const bucketsReady = new Map();
+/**
+ * Ensure `bucket` exists, once per process per bucket.
+ *
+ * MinIO — unlike an auto-provisioned S3 bucket — won't create a bucket on first
+ * write, so HEAD it and CREATE on 404/NoSuchBucket. Idempotent and
+ * concurrency-safe: concurrent callers share the single in-flight promise.
+ *
+ * The important part is the failure branch. A CreateBucket failure is EITHER a
+ * benign race (another replica created it between our HEAD and our CREATE) or a
+ * real outage (MinIO not up yet, credentials wrong, network down). Re-HEADing
+ * tells them apart:
+ *
+ *  - it now exists  → benign race, continue;
+ *  - it still does not → DROP the memo entry and fail this attempt.
+ *
+ * Dropping the entry is load-bearing. Memoizing a resolved "ready" after a
+ * failed create caches a permanently-broken success for the process lifetime:
+ * every later upload then fails `NoSuchBucket` against a MinIO that came up
+ * seconds after boot, until the pod is restarted.
+ */
+export async function ensureBucket(bucket) {
+    let ready = bucketsReady.get(bucket);
+    if (!ready) {
+        ready = (async () => {
+            try {
+                await s3Client().send(new HeadBucketCommand({ Bucket: bucket }));
+            }
+            catch {
+                try {
+                    await s3Client().send(new CreateBucketCommand({ Bucket: bucket }));
+                    logger.info('Created S3 bucket', { bucket });
+                }
+                catch (err) {
+                    try {
+                        await s3Client().send(new HeadBucketCommand({ Bucket: bucket }));
+                        logger.warn('S3 bucket ensure race (now exists, continuing)', { bucket, error: String(err) });
+                    }
+                    catch {
+                        bucketsReady.delete(bucket);
+                        throw new Error(`S3 bucket "${bucket}" unavailable: ${String(err)}`);
+                    }
+                }
+            }
+        })();
+        bucketsReady.set(bucket, ready);
+    }
+    return ready;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiczMtY2xpZW50LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL3NlcnZpY2VzL3MzLWNsaWVudC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSwrQ0FBK0M7QUFDL0Msc0NBQXNDO0FBRXRDOzs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7R0F3Qkc7QUFFSCxPQUFPLEVBQUUsUUFBUSxFQUFFLGlCQUFpQixFQUFFLG1CQUFtQixFQUFFLE1BQU0sb0JBQW9CLENBQUM7QUFFdEYsT0FBTyxFQUFFLE9BQU8sRUFBRSxNQUFNLEVBQUUsTUFBTSxpQkFBaUIsQ0FBQztBQUNsRCxPQUFPLEVBQUUsWUFBWSxFQUFFLE1BQU0sb0JBQW9CLENBQUM7QUFFbEQsTUFBTSxNQUFNLEdBQUcsWUFBWSxDQUFDLFdBQVcsQ0FBQyxDQUFDO0FBRXpDLElBQUksTUFBTSxHQUFvQixJQUFJLENBQUM7QUFFbkM7Ozs7O0dBS0c7QUFDSCxNQUFNLFVBQVUsUUFBUTtJQUN0QixJQUFJLE1BQU07UUFBRSxPQUFPLE1BQU0sQ0FBQztJQUMxQixNQUFNLFFBQVEsR0FBRyxNQUFNLENBQUMsYUFBYSxFQUFFLEVBQUUsQ0FBQyxDQUFDO0lBQzNDLE1BQU0sR0FBRyxJQUFJLFFBQVEsQ0FBQztRQUNwQixNQUFNLEVBQUUsTUFBTSxDQUFDLFdBQVcsRUFBRSxXQUFXLENBQUM7UUFDeEMsR0FBRyxDQUFDLFFBQVEsQ0FBQyxDQUFDLENBQUMsRUFBRSxRQUFRLEVBQUUsQ0FBQyxDQUFDLENBQUMsRUFBRSxDQUFDO1FBQ2pDLHlFQUF5RTtRQUN6RSw2RUFBNkU7UUFDN0UsY0FBYyxFQUFFLE9BQU8sQ0FBQyxxQkFBcUIsRUFBRSxJQUFJLENBQUM7UUFDcEQsV0FBVyxFQUFFO1lBQ1gsV0FBVyxFQUFFLE1BQU0sQ0FBQyxrQkFBa0IsRUFBRSxZQUFZLENBQUM7WUFDckQsZUFBZSxFQUFFLE1BQU0sQ0FBQyxzQkFBc0IsRUFBRSxZQUFZLENBQUM7U0FDOUQ7S0FDRixDQUFDLENBQUM7SUFDSCxPQUFPLE1BQU0sQ0FBQztBQUNoQixDQUFDO0FBRUQsb0ZBQW9GO0FBQ3BGLE1BQU0sWUFBWSxHQUFHLElBQUksR0FBRyxFQUF5QixDQUFDO0FBRXREOzs7Ozs7Ozs7Ozs7Ozs7Ozs7O0dBbUJHO0FBQ0gsTUFBTSxDQUFDLEtBQUssVUFBVSxZQUFZLENBQUMsTUFBYztJQUMvQyxJQUFJLEtBQUssR0FBRyxZQUFZLENBQUMsR0FBRyxDQUFDLE1BQU0sQ0FBQyxDQUFDO0lBQ3JDLElBQUksQ0FBQyxLQUFLLEVBQUUsQ0FBQztRQUNYLEtBQUssR0FBRyxDQUFDLEtBQUssSUFBSSxFQUFFO1lBQ2xCLElBQUksQ0FBQztnQkFDSCxNQUFNLFFBQVEsRUFBRSxDQUFDLElBQUksQ0FBQyxJQUFJLGlCQUFpQixDQUFDLEVBQUUsTUFBTSxFQUFFLE1BQU0sRUFBRSxDQUFDLENBQUMsQ0FBQztZQUNuRSxDQUFDO1lBQUMsTUFBTSxDQUFDO2dCQUNQLElBQUksQ0FBQztvQkFDSCxNQUFNLFFBQVEsRUFBRSxDQUFDLElBQUksQ0FBQyxJQUFJLG1CQUFtQixDQUFDLEVBQUUsTUFBTSxFQUFFLE1BQU0sRUFBRSxDQUFDLENBQUMsQ0FBQztvQkFDbkUsTUFBTSxDQUFDLElBQUksQ0FBQyxtQkFBbUIsRUFBRSxFQUFFLE1BQU0sRUFBRSxDQUFDLENBQUM7Z0JBQy9DLENBQUM7Z0JBQUMsT0FBTyxHQUFHLEVBQUUsQ0FBQztvQkFDYixJQUFJLENBQUM7d0JBQ0gsTUFBTSxRQUFRLEVBQUUsQ0FBQyxJQUFJLENBQUMsSUFBSSxpQkFBaUIsQ0FBQyxFQUFFLE1BQU0sRUFBRSxNQUFNLEVBQUUsQ0FBQyxDQUFDLENBQUM7d0JBQ2pFLE1BQU0sQ0FBQyxJQUFJLENBQUMsZ0RBQWdELEVBQUUsRUFBRSxNQUFNLEVBQUUsS0FBSyxFQUFFLE1BQU0sQ0FBQyxHQUFHLENBQUMsRUFBRSxDQUFDLENBQUM7b0JBQ2hHLENBQUM7b0JBQUMsTUFBTSxDQUFDO3dCQUNQLFlBQVksQ0FBQyxNQUFNLENBQUMsTUFBTSxDQUFDLENBQUM7d0JBQzVCLE1BQU0sSUFBSSxLQUFLLENBQUMsY0FBYyxNQUFNLGtCQUFrQixNQUFNLENBQUMsR0FBRyxDQUFDLEVBQUUsQ0FBQyxDQUFDO29CQUN2RSxDQUFDO2dCQUNILENBQUM7WUFDSCxDQUFDO1FBQ0gsQ0FBQyxDQUFDLEVBQUUsQ0FBQztRQUNMLFlBQVksQ0FBQyxHQUFHLENBQUMsTUFBTSxFQUFFLEtBQUssQ0FBQyxDQUFDO0lBQ2xDLENBQUM7SUFDRCxPQUFPLEtBQUssQ0FBQztBQUNmLENBQUMiLCJzb3VyY2VzQ29udGVudCI6WyIvLyBDb3B5cmlnaHQgMjAyNiBQaXBlbGluZSBCdWlsZGVyIENvbnRyaWJ1dG9yc1xuLy8gU1BEWC1MaWNlbnNlLUlkZW50aWZpZXI6IEFwYWNoZS0yLjBcblxuLyoqXG4gKiBUaGUgc2hhcmVkIFMzLWNvbXBhdGlibGUgY2xpZW50LCBhbmQgdGhlIGJ1Y2tldC1lbnN1cmUgYmFja3N0b3AgdGhhdCBnb2VzXG4gKiB3aXRoIGl0LlxuICpcbiAqIEJhY2tlZCBieSBNaW5JTyBpbiBldmVyeSBlbnZpcm9ubWVudCAoc2VsZi1ob3N0ZWQsIG5vIEFXUy1hY2NvdW50IGNvdXBsaW5nKTtcbiAqIGJlY2F1c2UgTWluSU8gc3BlYWtzIHRoZSBTMyBBUEkgdGhpcyB1c2VzIHRoZSBBV1MgUzMgU0RLLCBzbyBhIHJlYWwtUzMgc3dhcCBpc1xuICogYSBwdXJlIGNvbmZpZyBjaGFuZ2UgKGRyb3AgdGhlIGN1c3RvbSBlbmRwb2ludCArIHBhdGgtc3R5bGUsIHN1cHBseSBJQU0gY3JlZHMpLlxuICpcbiAqIENvbmZpZyAoZW52KSDigJQgb25lIHNldCBvZiBuYW1lcywgcmVhZCBpZGVudGljYWxseSBieSBldmVyeSBzZXJ2aWNlOyBlYWNoXG4gKiBjb250YWluZXIgaXMgcG9pbnRlZCBhdCBpdHMgT1dOIGJ1Y2tldCB3aXRoIGJ1Y2tldC1zY29wZWQgY3JlZGVudGlhbHM6XG4gKiAgIFMzX0VORFBPSU5UICAgICAgICAgICBNaW5JTy9TMyBlbmRwb2ludCBVUkwgKGUuZy4gaHR0cDovL21pbmlvOjkwMDApLiBFbXB0eVxuICogICAgICAgICAgICAgICAgICAgICAgICAg4oeSIGRlZmF1bHQgQVdTIFMzIChubyBjdXN0b20gZW5kcG9pbnQpLlxuICogICBTM19SRUdJT04gICAgICAgICAgICAgcmVnaW9uIChkZWZhdWx0ICd1cy1lYXN0LTEnKS5cbiAqICAgUzNfQUNDRVNTX0tFWV9JRCAgICAgIGFjY2VzcyBrZXkuXG4gKiAgIFMzX1NFQ1JFVF9BQ0NFU1NfS0VZICBzZWNyZXQga2V5LlxuICogICBTM19GT1JDRV9QQVRIX1NUWUxFICAgJ3RydWUnIGZvciBNaW5JTyAocGF0aC1zdHlsZSBhZGRyZXNzaW5nKTsgZGVmYXVsdCB0cnVlLlxuICpcbiAqIGBTM19CVUNLRVRgIGlzIGRlbGliZXJhdGVseSBOT1QgcmVhZCBoZXJlOiB0aGUgYnVja2V0IGlzIHRoZSBjYWxsZXIncywgYW5kXG4gKiBlYWNoIHNlcnZpY2Uga2VlcHMgaXRzIG93biBkZWZhdWx0IGFuZCBpdHMgb3duIGtleSBjb252ZW50aW9uLlxuICpcbiAqICoqUmVhY2hlZCB0aHJvdWdoIHRoZSBgQHBpcGVsaW5lLWJ1aWxkZXIvYXBpLWNvcmUvczNgIHN1YnBhdGgsIG5ldmVyIHRoZSByb290XG4gKiBiYXJyZWwqKiDigJQgb25seSB0d28gc2VydmljZXMgZG8gYmxvYiBzdG9yYWdlLCBhbmQgdGhlIFMzIFNESyBpcyBhIGxhcmdlXG4gKiBlYWdlciBkZXBlbmRlbmN5IHRoYXQgdGhlIG90aGVyIGVpZ2h0IG11c3Qgbm90IHBheSBmb3IgYXQgYm9vdC4gU2FtZSByZWFzb25cbiAqIGBAYXdzLXNkay9jbGllbnQta21zYCBpcyBkeW5hbWljYWxseSBpbXBvcnRlZCBpbnNpZGUgc2VjcmV0LWVuY3J5cHRpb24uXG4gKi9cblxuaW1wb3J0IHsgUzNDbGllbnQsIEhlYWRCdWNrZXRDb21tYW5kLCBDcmVhdGVCdWNrZXRDb21tYW5kIH0gZnJvbSAnQGF3cy1zZGsvY2xpZW50LXMzJztcblxuaW1wb3J0IHsgZW52Qm9vbCwgZW52U3RyIH0gZnJvbSAnLi4vdXRpbHMvZW52LmpzJztcbmltcG9ydCB7IGNyZWF0ZUxvZ2dlciB9IGZyb20gJy4uL3V0aWxzL2xvZ2dlci5qcyc7XG5cbmNvbnN0IGxvZ2dlciA9IGNyZWF0ZUxvZ2dlcignczMtY2xpZW50Jyk7XG5cbmxldCBjbGllbnQ6IFMzQ2xpZW50IHwgbnVsbCA9IG51bGw7XG5cbi8qKlxuICogVGhlIHByb2Nlc3Mtd2lkZSBTMyBjbGllbnQsIGJ1aWx0IGZyb20gZW52IG9uIGZpcnN0IHVzZS5cbiAqXG4gKiBMYXp5IHNvIGEgc2VydmljZSB0aGF0IG5ldmVyIHRvdWNoZXMgYmxvYiBzdG9yYWdlIOKAlCBhbmQgYSB0ZXN0IHRoYXQgbmV2ZXJcbiAqIGNvbmZpZ3VyZXMgUzMg4oCUIG5ldmVyIGNvbnN0cnVjdHMgb25lLlxuICovXG5leHBvcnQgZnVuY3Rpb24gczNDbGllbnQoKTogUzNDbGllbnQge1xuICBpZiAoY2xpZW50KSByZXR1cm4gY2xpZW50O1xuICBjb25zdCBlbmRwb2ludCA9IGVudlN0cignUzNfRU5EUE9JTlQnLCAnJyk7XG4gIGNsaWVudCA9IG5ldyBTM0NsaWVudCh7XG4gICAgcmVnaW9uOiBlbnZTdHIoJ1MzX1JFR0lPTicsICd1cy1lYXN0LTEnKSxcbiAgICAuLi4oZW5kcG9pbnQgPyB7IGVuZHBvaW50IH0gOiB7fSksXG4gICAgLy8gUGF0aC1zdHlsZSBpcyByZXF1aXJlZCBieSBNaW5JTyAobm8gdmlydHVhbC1ob3N0IGJ1Y2tldCBETlMpLiBIYXJtbGVzc1xuICAgIC8vIGFnYWluc3QgcmVhbCBTMywgYnV0IGRlZmF1bHQtb24gaGVyZSBiZWNhdXNlIE1pbklPIGlzIHRoZSBkZWZhdWx0IGJhY2tlbmQuXG4gICAgZm9yY2VQYXRoU3R5bGU6IGVudkJvb2woJ1MzX0ZPUkNFX1BBVEhfU1RZTEUnLCB0cnVlKSxcbiAgICBjcmVkZW50aWFsczoge1xuICAgICAgYWNjZXNzS2V5SWQ6IGVudlN0cignUzNfQUNDRVNTX0tFWV9JRCcsICdtaW5pb2FkbWluJyksXG4gICAgICBzZWNyZXRBY2Nlc3NLZXk6IGVudlN0cignUzNfU0VDUkVUX0FDQ0VTU19LRVknLCAnbWluaW9hZG1pbicpLFxuICAgIH0sXG4gIH0pO1xuICByZXR1cm4gY2xpZW50O1xufVxuXG4vKiogSW4tZmxpZ2h0IC8gc2V0dGxlZCBlbnN1cmUgcGVyIGJ1Y2tldC4gQSByZWplY3RlZCBhdHRlbXB0IGlzIG5ldmVyIGxlZnQgaGVyZS4gKi9cbmNvbnN0IGJ1Y2tldHNSZWFkeSA9IG5ldyBNYXA8c3RyaW5nLCBQcm9taXNlPHZvaWQ+PigpO1xuXG4vKipcbiAqIEVuc3VyZSBgYnVja2V0YCBleGlzdHMsIG9uY2UgcGVyIHByb2Nlc3MgcGVyIGJ1Y2tldC5cbiAqXG4gKiBNaW5JTyDigJQgdW5saWtlIGFuIGF1dG8tcHJvdmlzaW9uZWQgUzMgYnVja2V0IOKAlCB3b24ndCBjcmVhdGUgYSBidWNrZXQgb24gZmlyc3RcbiAqIHdyaXRlLCBzbyBIRUFEIGl0IGFuZCBDUkVBVEUgb24gNDA0L05vU3VjaEJ1Y2tldC4gSWRlbXBvdGVudCBhbmRcbiAqIGNvbmN1cnJlbmN5LXNhZmU6IGNvbmN1cnJlbnQgY2FsbGVycyBzaGFyZSB0aGUgc2luZ2xlIGluLWZsaWdodCBwcm9taXNlLlxuICpcbiAqIFRoZSBpbXBvcnRhbnQgcGFydCBpcyB0aGUgZmFpbHVyZSBicmFuY2guIEEgQ3JlYXRlQnVja2V0IGZhaWx1cmUgaXMgRUlUSEVSIGFcbiAqIGJlbmlnbiByYWNlIChhbm90aGVyIHJlcGxpY2EgY3JlYXRlZCBpdCBiZXR3ZWVuIG91ciBIRUFEIGFuZCBvdXIgQ1JFQVRFKSBvciBhXG4gKiByZWFsIG91dGFnZSAoTWluSU8gbm90IHVwIHlldCwgY3JlZGVudGlhbHMgd3JvbmcsIG5ldHdvcmsgZG93bikuIFJlLUhFQURpbmdcbiAqIHRlbGxzIHRoZW0gYXBhcnQ6XG4gKlxuICogIC0gaXQgbm93IGV4aXN0cyAg4oaSIGJlbmlnbiByYWNlLCBjb250aW51ZTtcbiAqICAtIGl0IHN0aWxsIGRvZXMgbm90IOKGkiBEUk9QIHRoZSBtZW1vIGVudHJ5IGFuZCBmYWlsIHRoaXMgYXR0ZW1wdC5cbiAqXG4gKiBEcm9wcGluZyB0aGUgZW50cnkgaXMgbG9hZC1iZWFyaW5nLiBNZW1vaXppbmcgYSByZXNvbHZlZCBcInJlYWR5XCIgYWZ0ZXIgYVxuICogZmFpbGVkIGNyZWF0ZSBjYWNoZXMgYSBwZXJtYW5lbnRseS1icm9rZW4gc3VjY2VzcyBmb3IgdGhlIHByb2Nlc3MgbGlmZXRpbWU6XG4gKiBldmVyeSBsYXRlciB1cGxvYWQgdGhlbiBmYWlscyBgTm9TdWNoQnVja2V0YCBhZ2FpbnN0IGEgTWluSU8gdGhhdCBjYW1lIHVwXG4gKiBzZWNvbmRzIGFmdGVyIGJvb3QsIHVudGlsIHRoZSBwb2QgaXMgcmVzdGFydGVkLlxuICovXG5leHBvcnQgYXN5bmMgZnVuY3Rpb24gZW5zdXJlQnVja2V0KGJ1Y2tldDogc3RyaW5nKTogUHJvbWlzZTx2b2lkPiB7XG4gIGxldCByZWFkeSA9IGJ1Y2tldHNSZWFkeS5nZXQoYnVja2V0KTtcbiAgaWYgKCFyZWFkeSkge1xuICAgIHJlYWR5ID0gKGFzeW5jICgpID0+IHtcbiAgICAgIHRyeSB7XG4gICAgICAgIGF3YWl0IHMzQ2xpZW50KCkuc2VuZChuZXcgSGVhZEJ1Y2tldENvbW1hbmQoeyBCdWNrZXQ6IGJ1Y2tldCB9KSk7XG4gICAgICB9IGNhdGNoIHtcbiAgICAgICAgdHJ5IHtcbiAgICAgICAgICBhd2FpdCBzM0NsaWVudCgpLnNlbmQobmV3IENyZWF0ZUJ1Y2tldENvbW1hbmQoeyBCdWNrZXQ6IGJ1Y2tldCB9KSk7XG4gICAgICAgICAgbG9nZ2VyLmluZm8oJ0NyZWF0ZWQgUzMgYnVja2V0JywgeyBidWNrZXQgfSk7XG4gICAgICAgIH0gY2F0Y2ggKGVycikge1xuICAgICAgICAgIHRyeSB7XG4gICAgICAgICAgICBhd2FpdCBzM0NsaWVudCgpLnNlbmQobmV3IEhlYWRCdWNrZXRDb21tYW5kKHsgQnVja2V0OiBidWNrZXQgfSkpO1xuICAgICAgICAgICAgbG9nZ2VyLndhcm4oJ1MzIGJ1Y2tldCBlbnN1cmUgcmFjZSAobm93IGV4aXN0cywgY29udGludWluZyknLCB7IGJ1Y2tldCwgZXJyb3I6IFN0cmluZyhlcnIpIH0pO1xuICAgICAgICAgIH0gY2F0Y2gge1xuICAgICAgICAgICAgYnVja2V0c1JlYWR5LmRlbGV0ZShidWNrZXQpO1xuICAgICAgICAgICAgdGhyb3cgbmV3IEVycm9yKGBTMyBidWNrZXQgXCIke2J1Y2tldH1cIiB1bmF2YWlsYWJsZTogJHtTdHJpbmcoZXJyKX1gKTtcbiAgICAgICAgICB9XG4gICAgICAgIH1cbiAgICAgIH1cbiAgICB9KSgpO1xuICAgIGJ1Y2tldHNSZWFkeS5zZXQoYnVja2V0LCByZWFkeSk7XG4gIH1cbiAgcmV0dXJuIHJlYWR5O1xufVxuIl19

package/lib/types/ask-proposals.d.ts

@@ -0,0 +1,269 @@
+/**
+ * The shared contract between the ask agent's PROPOSE tools and the browser's
+ * CONFIRM handlers. Two things live here, and they live here because BOTH sides
+ * need them: `api/ask` builds its tool schema from this module, the frontend's
+ * confirm handler builds its request from it, and the tests of both assert
+ * against it. A second copy would be a second policy.
+ *
+ * Dependency-free on purpose — no runtime imports at all — so the browser can
+ * import it through api-core's `./ask-proposals` entry without dragging in the
+ * server graph (express / jwt / ioredis). The only imports are `import type`,
+ * which the compiler erases.
+ *
+ * -----------------------------------------------------------------------------
+ * 1. PROVENANCE
+ * -----------------------------------------------------------------------------
+ * Every commit that started life as an agent draft stamps
+ * `details: { proposedBy: 'ask-agent' }` onto its audit event. The audit trail
+ * is hash-chained and tamper-evident, but without this field it cannot
+ * distinguish "the admin changed this" from "an AI drafted it and the admin
+ * clicked Apply" — the two mean very different things in an incident review.
+ * The constant exists so the literal is not retyped in two codebases, where a
+ * typo would silently produce an unqueryable trail.
+ *
+ * -----------------------------------------------------------------------------
+ * 2. THE ORG-SETTINGS ALLOWLIST
+ * -----------------------------------------------------------------------------
+ * This is an ALLOWLIST, not a denylist, and the distinction is the whole point:
+ * a setting added to the platform tomorrow is UNAVAILABLE to the agent until
+ * someone deliberately adds it here, rather than being exposed by omission.
+ * If you are reading this because a proposal was refused, the fix is to add the
+ * field below WITH its `why` — not to loosen {@link pickAllowed}.
+ *
+ * A field earns a place here only if all of the following hold. They were
+ * checked against the routes, not assumed:
+ *
+ *  - **No step-up.** A route carrying `requireStepUp` is out, no exceptions.
+ *    Step-up means the platform already decided a live session is not enough
+ *    authority; a chat proposal is strictly less. This is what keeps
+ *    `PUT /organization/ai-config` out (it persists per-org provider SECRETS),
+ *    along with the MFA / password / authenticator policies,
+ *    `PUT /plugins/install-policy`, org restore and transfer-owner.
+ *  - **Not a security control.** MFA / password / authenticator / impersonation
+ *    policy, SSO+SAML and its group mappings, verified domains and domain-based
+ *    join, join-request decisions, transfer-owner and team lifecycle are ABSENT
+ *    here rather than gated within — "relax the MFA policy" is precisely what an
+ *    injection payload asks for, and it arrives through text the agent already
+ *    reads. Absent cannot be argued with; gated can.
+ *  - **Carries no secret and no callback target.** An API that returns
+ *    `hasWebhookSecret` instead of the secret is telling you the field cannot be
+ *    diffed, so it cannot be reviewed, so it cannot be proposed. Webhook URLs
+ *    and email addresses are out for the same reason plus one more: they are
+ *    exfiltration targets, and a confirmation mail to an attacker-chosen address
+ *    is a send the platform performs on the model's say-so.
+ *  - **Reviewable as a diff.** A scalar with a closed shape (boolean, bounded
+ *    integer, small enum). A list of opaque user ids renders as ids in a card
+ *    nobody can check, so recipient LISTS are out even though cadence is in.
+ *
+ * Each entry names the API that applies it. The browser applies it through the
+ * USER's own session and the user's own permissions — the agent never writes —
+ * so a proposal a member may not commit simply 403s at the route, exactly as a
+ * hand-made request would.
+ *
+ * Rule 10 lives in {@link pickAllowed}: a candidate carrying a field outside
+ * this list is the injection signal, so the refused names come back to the
+ * caller to be counted and logged rather than being quietly dropped.
+ */
+import type { Permission } from './permissions.js';
+/** The `proposedBy` value every agent-drafted commit records. */
+export declare const ASK_AGENT_PROPOSER = "ask-agent";
+/** The audit `details` key that carries provenance. */
+export declare const PROPOSED_BY_DETAIL_KEY = "proposedBy";
+/** The provenance fragment merged into a `RemoteAuditEvent.details`. */
+export interface AskProposalProvenance {
+    readonly proposedBy: typeof ASK_AGENT_PROPOSER;
+}
+/**
+ * Merge agent provenance into an audit event's free-form `details`.
+ * Provenance is applied LAST so a caller-supplied `proposedBy` cannot overwrite
+ * it — the point of the field is that it is not negotiable.
+ */
+export declare function askProposalAuditDetails(details?: Readonly<Record<string, unknown>>): Record<string, unknown> & AskProposalProvenance;
+/**
+ * The request HEADER a proposal commit stamps, and the only channel provenance
+ * travels on.
+ *
+ * A HEADER rather than a body field, for three reasons:
+ *
+ *  - **It cannot collide.** `proposedBy` in a body would be a new key in six
+ *    different domain schemas — `PipelineUpdateSchema`, the plugin/template
+ *    update schemas, three notification/settings schemas — two of which are
+ *    `.strict()` and the rest of which feed `Object.keys(body)` straight into
+ *    the update's column list and the audit's `fields`. A field named after an
+ *    audit key would then be indistinguishable from a real one, and the day a
+ *    domain grows its own `proposedBy` the two meanings merge silently.
+ *  - **It is transport metadata, and stays out of the payload.** Nothing
+ *    downstream of `validateBody` ever sees it, so it cannot be persisted, cannot
+ *    widen a diff, and cannot reach a service that forwards the body onward.
+ *  - **The platform already does this.** `X-Step-Up-Token` is the same shape of
+ *    thing — a per-request assertion about HOW the call was made rather than
+ *    WHAT it changes — and rides a header for the same reasons.
+ *
+ * Lower-case because that is how Node normalises incoming header names; the
+ * browser sends `X-PB-Proposed-By`, which arrives here.
+ */
+export declare const ASK_PROPOSED_BY_HEADER = "x-pb-proposed-by";
+/**
+ * What a request's provenance header claims.
+ *
+ * `foreign` is any value that is not EXACTLY {@link ASK_AGENT_PROPOSER} — there
+ * is one legitimate proposer and no free-form text, so anything else is a bug
+ * or a forgery and is named as such rather than folded into `none`.
+ */
+export type ProposerClaim = 'none' | 'ask-agent' | 'foreign';
+/**
+ * Read the provenance claim off a request's header bag.
+ *
+ * Deliberately exact: no trimming, no case folding, no prefix matching. The
+ * only sender is the browser's confirm path, which stamps the shared constant,
+ * so every other value is refused rather than repaired. This is what keeps a
+ * client from writing arbitrary audit `details` — the header's whole vocabulary
+ * is one word, and the word is not the client's to choose.
+ *
+ * Takes the header BAG (`req.headers`) rather than a request, so this module
+ * keeps its zero runtime imports and the browser can still import the constant.
+ */
+export declare function readProposerClaim(headers: unknown): ProposerClaim;
+/**
+ * The audit `details` for a write, with provenance folded in when — and ONLY
+ * when — the request carries the agent marker.
+ *
+ * `details` is what the HANDLER built and stays authoritative. Provenance is
+ * additive: the ONLY key it can ever write is `proposedBy`, so every field the
+ * handler set survives untouched, and {@link askProposalAuditDetails} applies
+ * that one key LAST so a `proposedBy` arriving from anywhere else cannot speak
+ * in its place. A request carrying no marker, or a `foreign` one, gets the
+ * handler's details unchanged — an ordinary edit records no `proposedBy` at
+ * all, which is the distinction the field exists to make.
+ */
+export declare function withProposalProvenance(headers: unknown, details?: Readonly<Record<string, unknown>>): Record<string, unknown>;
+/** A value an allowlisted org setting can hold. */
+export type OrgSettingValue = string | number | boolean;
+/** Which per-org record (and therefore which API) a field belongs to. */
+export type OrgSettingSurface = 'reporting' | 'complianceNotifications' | 'pluginSecurityNotifications';
+/**
+ * Every proposable setting, as `<surface>.<field>`. Writing the union out by
+ * hand (rather than inferring it from the array) is deliberate: the key space
+ * is the contract the tool schema and the confirm handler share, so it is
+ * stated once, explicitly, and a typo in an entry below is a compile error.
+ */
+export type OrgSettingKey = 'reporting.incidentWindowHours' | 'complianceNotifications.notifyOnBlock' | 'complianceNotifications.notifyOnWarning' | 'complianceNotifications.emailEnabled' | 'complianceNotifications.digestMode' | 'pluginSecurityNotifications.notifyRescan' | 'pluginSecurityNotifications.digestMode';
+/** The closed shape a proposed value must match before it is accepted. */
+export type OrgSettingShape = {
+    readonly kind: 'boolean';
+} | {
+    readonly kind: 'integer';
+    readonly min: number;
+    readonly max: number;
+} | {
+    readonly kind: 'enum';
+    readonly values: readonly string[];
+};
+/** One proposable org setting. */
+export interface OrgSettingSpec {
+    /** Stable proposal key — `<surface>.<field>`. This is what the model names. */
+    readonly key: OrgSettingKey;
+    readonly surface: OrgSettingSurface;
+    /** The request-body field name the API expects. */
+    readonly field: string;
+    readonly shape: OrgSettingShape;
+    /** The route that applies it, called by the BROWSER with the user's session. */
+    readonly api: {
+        readonly method: 'PUT';
+        readonly path: string;
+    };
+    /** The permission that route requires of the caller. */
+    readonly permission: Permission;
+    /** Short human label for the confirm card. */
+    readonly label: string;
+    /** WHY this field is safe to propose. Every entry states its own case. */
+    readonly why: string;
+}
+/**
+ * The allowlist. Adding an entry is a deliberate act: name the route you
+ * checked, confirm it carries no `requireStepUp`, and write the `why`.
+ */
+export declare const ORG_SETTING_PROPOSAL_ALLOWLIST: readonly OrgSettingSpec[];
+/**
+ * Fields DELIBERATELY excluded, with the reason, so a future reader does not
+ * re-litigate them and a reviewer can see they were considered rather than
+ * missed. This is documentation only — {@link pickAllowed} consults the
+ * allowlist alone, and a field absent from BOTH lists is refused identically.
+ */
+export declare const ORG_SETTING_PROPOSAL_EXCLUSIONS: ReadonlyArray<{
+    readonly field: string;
+    readonly why: string;
+}>;
+/** Every proposable key — the enum a propose tool's input schema is built from. */
+export declare const ORG_SETTING_PROPOSAL_KEYS: readonly OrgSettingKey[];
+/** Is `key` on the allowlist? */
+export declare function isProposableOrgSetting(key: string): key is OrgSettingKey;
+/** The spec for `key`, or undefined when it is not proposable. */
+export declare function orgSettingSpec(key: string): OrgSettingSpec | undefined;
+/** Does `value` match the shape the field declares? */
+export declare function isValidOrgSettingValue(spec: OrgSettingSpec, value: unknown): value is OrgSettingValue;
+/** A proposal's settings, keyed by allowlist key. */
+export type OrgSettingPatch = Partial<Record<OrgSettingKey, OrgSettingValue>>;
+/** What {@link pickAllowed} kept, and what it threw away. */
+export interface PickAllowedResult {
+    /** The allowlisted, shape-valid settings. */
+    readonly allowed: OrgSettingPatch;
+    /**
+     * Field names the candidate carried that are NOT on the allowlist. THIS is
+     * the injection signal (rule 10): a legitimate draft has none, so a non-empty
+     * list is a counter to increment and a line to log, not a silent drop.
+     */
+    readonly refused: readonly string[];
+    /**
+     * Allowlisted keys whose value did not match the declared shape. Dropped too,
+     * but reported separately — a bad value is a drafting mistake, not an attempt
+     * to reach a field the agent was never given.
+     */
+    readonly invalid: readonly OrgSettingKey[];
+    /** `refused.length`, so a caller can count without re-deriving it. */
+    readonly refusedCount: number;
+}
+/**
+ * Keep only the allowlisted, shape-valid fields of a candidate proposal, and
+ * report everything dropped.
+ *
+ * The result's `allowed` map IS the commit payload (rule 3): the confirm
+ * handler sends these fields and only these, so anything the model slipped in
+ * is structurally unappliable rather than merely unrendered.
+ *
+ * `candidate` is untrusted model output, so it is read defensively: anything
+ * that is not a plain object yields an empty result.
+ */
+export declare function pickAllowed(candidate: unknown): PickAllowedResult;
+/** One reviewed change: what the setting is now, and what it would become. */
+export interface OrgSettingChange {
+    readonly spec: OrgSettingSpec;
+    readonly from: OrgSettingValue | undefined;
+    readonly to: OrgSettingValue;
+}
+/**
+ * The changes a proposal actually makes, given the CURRENT values. A field
+ * whose proposed value already equals the current one is dropped — it is not a
+ * change, and rendering it as one makes a diff the user cannot read.
+ *
+ * The confirm handler re-runs this against a FRESH read immediately before
+ * committing (rule 7): these records carry no version column, so if the list
+ * that comes back differs from the one the user approved, state moved under the
+ * proposal and the commit must be refused rather than applied blind.
+ */
+export declare function diffOrgSettings(current: Readonly<OrgSettingPatch>, proposed: Readonly<OrgSettingPatch>): readonly OrgSettingChange[];
+/** One API call the confirm handler makes: one surface, one body. */
+export interface OrgSettingRequest {
+    readonly surface: OrgSettingSurface;
+    readonly method: 'PUT';
+    readonly path: string;
+    readonly permission: Permission;
+    /** Request body: the API's own field names, carrying only reviewed values. */
+    readonly body: Record<string, OrgSettingValue>;
+}
+/**
+ * Group approved changes into one request per surface, translating proposal
+ * keys back to the field names each API expects. Order follows the allowlist,
+ * so the same proposal always produces the same call sequence.
+ */
+export declare function orgSettingRequests(changes: readonly OrgSettingChange[]): readonly OrgSettingRequest[];