dataiku-sdk 0.12.4 → 0.12.5

package/dist/src/cli/flags.js

@@ -27,6 +27,7 @@ export const BOOLEAN_FLAGS = new Set([
     "force-rebuild",
     "latest",
     "copy-output-settings",
+    "copy-permissions",
     "continue-on-error",
     "no-backup",
     "payload-only",
@@ -38,6 +39,7 @@ export const BOOLEAN_FLAGS = new Set([
     "full-log",
     "drop-data",
     "normalize",
+    "unconfirmed-creation",
 ]);
 export const SHORT_FLAGS = {
     v: "verbose",
@@ -82,6 +84,9 @@ export const VALUE_FLAGS = new Set([
     "active",
     "deployment-mode",
     "env-version",
+    "expect-hash",
+    "expect-project-incarnation",
+    "expect-version",
     "data-file",
     "database",
     "dataset",
@@ -104,6 +109,7 @@ export const VALUE_FLAGS = new Set([
     "package",
     "packages",
     "local",
+    "manifest-version",
     "max-edges",
     "max-lines",
     "max-log-lines",
@@ -142,6 +148,7 @@ export const VALUE_FLAGS = new Set([
     "rule-id",
     "role",
     "retries",
+    "future-id",
     "poll-interval",
     "python-interpreter",
     "replace-input",
@@ -166,6 +173,7 @@ export const VALUE_FLAGS = new Set([
     "type",
     "url",
     "until",
+    "version-notes",
     "to",
     "zone",
     "zone-id",

package/dist/src/cli/helpers/app-permissions.d.ts

@@ -0,0 +1,63 @@
+import type { ProjectPermissions } from "../../resources/projects.js";
+import { UsageError } from "../usage.js";
+/**
+ * Version 3 binds every snapshot to both its DSS server and the concrete project
+ * incarnation present at capture time. Earlier versions are refused.
+ */
+export declare const APP_PERMISSIONS_SNAPSHOT_VERSION = 3;
+export interface AppPermissionsSnapshot {
+    version: number;
+    projectKey: string;
+    /** Canonical base URL of the DSS server these rules were read from. */
+    dssUrl: string;
+    /** Hash of the concrete project incarnation these rules were read from. */
+    projectIncarnationHash: string;
+    capturedAt: string;
+    hash: string;
+    permissionsHash: string;
+    permissions: ProjectPermissions;
+}
+export type AppPermissionsDifferenceStatus = "added" | "removed" | "changed";
+export interface AppPermissionsDifference {
+    path: string;
+    status: AppPermissionsDifferenceStatus;
+    backup?: unknown;
+    current?: unknown;
+}
+export interface AppPermissionsDiff {
+    changed: boolean;
+    differences: AppPermissionsDifference[];
+}
+/**
+ * Canonical hash of a permissions payload. Key order and unknown DSS fields are
+ * normalized by `stableJson`, so re-serializing a snapshot never changes the hash.
+ */
+export declare function appPermissionsHash(permissions: unknown): string;
+export declare function buildAppPermissionsSnapshot(projectKey: string, dssUrl: string, projectIncarnationHash: string, permissions: ProjectPermissions, capturedAt?: string): AppPermissionsSnapshot;
+/**
+ * Write a snapshot as owner-only JSON. Access-control rules must never sit on disk
+ * under wider permissions: `writeFileSync`'s `mode` is ignored for an existing file
+ * and a trailing `chmod` would publish the payload first, so the descriptor is
+ * clamped to 0600 before the file is truncated or written.
+ */
+export declare function writeAppPermissionsSnapshot(filePath: string, snapshot: AppPermissionsSnapshot): void;
+/** Validate envelope shape, version, and hash integrity. Never echoes permission payloads. */
+export declare function parseAppPermissionsSnapshot(text: string, source: string): AppPermissionsSnapshot;
+export declare function readAppPermissionsSnapshot(filePath: string): AppPermissionsSnapshot;
+/**
+ * Refuse to use a snapshot outside the exact project *and* DSS server it was captured
+ * from. Access-control rules are server-scoped: the same project key, users, and groups
+ * exist on other instances with different meaning, so replaying a snapshot elsewhere can
+ * silently grant or revoke access. Runs before any live permission read or write.
+ */
+export declare function assertAppPermissionsSnapshotBinding(snapshot: AppPermissionsSnapshot, targetProjectKey: string, currentDssUrl: string, currentProjectIncarnationHash?: string): void;
+export declare function appPermissionsVerificationError(projectKey: string, hashes: {
+    beforeHash: string;
+    desiredHash: string;
+    verifiedHash: string;
+}): UsageError;
+/**
+ * Deterministic, path-addressed differences between a snapshot payload and live
+ * permissions. Paths are sorted so repeated runs emit byte-identical output.
+ */
+export declare function diffAppPermissions(backup: unknown, current: unknown): AppPermissionsDiff;

package/dist/src/cli/helpers/app-permissions.js

@@ -0,0 +1,239 @@
+import * as fs from "node:fs";
+import { canonicalDssUrl, } from "../../utils/dss-url.js";
+import { compareStrings, } from "../../utils/stable-hash.js";
+import { parseJsonObject, plainRecord, stableHash, stableJson, } from "../coerce.js";
+import { UsageError, } from "../usage.js";
+/**
+ * Version 3 binds every snapshot to both its DSS server and the concrete project
+ * incarnation present at capture time. Earlier versions are refused.
+ */
+export const APP_PERMISSIONS_SNAPSHOT_VERSION = 3;
+/** Snapshots hold access-control rules: keep them owner-only on disk. */
+const SNAPSHOT_FILE_MODE = 0o600;
+/**
+ * Open for writing *without* `O_TRUNC`: truncation must wait until the descriptor
+ * has been narrowed to owner-only. `O_NOFOLLOW`, where the platform defines it,
+ * refuses a symlinked destination so a hostile link cannot redirect the snapshot —
+ * or the permission change itself — onto another file.
+ */
+const SNAPSHOT_OPEN_FLAGS = fs.constants.O_WRONLY | fs.constants.O_CREAT
+    | (typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0);
+/**
+ * Canonical hash of a permissions payload. Key order and unknown DSS fields are
+ * normalized by `stableJson`, so re-serializing a snapshot never changes the hash.
+ */
+export function appPermissionsHash(permissions) {
+    return stableHash(permissions);
+}
+export function buildAppPermissionsSnapshot(projectKey, dssUrl, projectIncarnationHash, permissions, capturedAt = new Date().toISOString()) {
+    const version = APP_PERMISSIONS_SNAPSHOT_VERSION;
+    const boundUrl = canonicalDssUrl(dssUrl);
+    if (boundUrl.length === 0) {
+        throw new UsageError("Cannot capture an app permissions snapshot without the DSS server URL it was read from.", "validation_failed");
+    }
+    if (!/^[0-9a-f]{64}$/.test(projectIncarnationHash)) {
+        throw new UsageError("Cannot capture an app permissions snapshot without a valid project-incarnation hash.", "validation_failed");
+    }
+    const permissionsHash = appPermissionsHash(permissions);
+    const hash = stableHash({
+        version,
+        projectKey,
+        dssUrl: boundUrl,
+        projectIncarnationHash,
+        capturedAt,
+        permissionsHash,
+        permissions,
+    });
+    return {
+        version,
+        projectKey,
+        dssUrl: boundUrl,
+        projectIncarnationHash,
+        capturedAt,
+        hash,
+        permissionsHash,
+        permissions,
+    };
+}
+/** Drain the payload: one `writeSync` may cover only part of the buffer. */
+function writeAllSync(fd, payload) {
+    let offset = 0;
+    while (offset < payload.length) {
+        const written = fs.writeSync(fd, payload, offset, payload.length - offset, offset);
+        if (written <= 0) {
+            throw new Error(`Stalled writing app permissions snapshot at byte ${offset}.`);
+        }
+        offset += written;
+    }
+}
+/**
+ * Write a snapshot as owner-only JSON. Access-control rules must never sit on disk
+ * under wider permissions: `writeFileSync`'s `mode` is ignored for an existing file
+ * and a trailing `chmod` would publish the payload first, so the descriptor is
+ * clamped to 0600 before the file is truncated or written.
+ */
+export function writeAppPermissionsSnapshot(filePath, snapshot) {
+    // Serialize before touching the filesystem: a serialization fault must not
+    // truncate or half-overwrite an existing snapshot.
+    const payload = Buffer.from(`${JSON.stringify(snapshot, null, 2)}\n`, "utf-8");
+    const fd = fs.openSync(filePath, SNAPSHOT_OPEN_FLAGS, SNAPSHOT_FILE_MODE);
+    let wrote = false;
+    try {
+        fs.fchmodSync(fd, SNAPSHOT_FILE_MODE);
+        fs.ftruncateSync(fd, 0);
+        writeAllSync(fd, payload);
+        wrote = true;
+    }
+    finally {
+        if (wrote) {
+            fs.closeSync(fd);
+        }
+        else {
+            try {
+                fs.closeSync(fd);
+            }
+            catch {
+                // Keep the original failure: a close fault must not mask it.
+            }
+        }
+    }
+}
+function requiredSnapshotString(record, field, source) {
+    const value = record[field];
+    if (typeof value !== "string" || value.trim().length === 0) {
+        throw new UsageError(`${source} is not an app permissions snapshot: "${field}" must be a non-empty string.`, "validation_failed");
+    }
+    return value;
+}
+/** Validate envelope shape, version, and hash integrity. Never echoes permission payloads. */
+export function parseAppPermissionsSnapshot(text, source) {
+    const record = parseJsonObject(text, source);
+    const version = record["version"];
+    if (typeof version !== "number" || !Number.isInteger(version)) {
+        throw new UsageError(`${source} is not an app permissions snapshot: "version" must be an integer.`, "validation_failed");
+    }
+    if (version !== APP_PERMISSIONS_SNAPSHOT_VERSION) {
+        throw new UsageError(`${source} has unsupported snapshot version ${String(version)} (expected ${String(APP_PERMISSIONS_SNAPSHOT_VERSION)}).`, "validation_failed", version < APP_PERMISSIONS_SNAPSHOT_VERSION
+            ? "Older snapshots are not bound to the concrete project incarnation they came from, so they cannot be applied safely after project-key reuse. Re-run `dss app permissions-snapshot` against that project to capture a current snapshot."
+            : undefined);
+    }
+    const projectKey = requiredSnapshotString(record, "projectKey", source);
+    const dssUrl = requiredSnapshotString(record, "dssUrl", source);
+    const projectIncarnationHash = requiredSnapshotString(record, "projectIncarnationHash", source);
+    const capturedAt = requiredSnapshotString(record, "capturedAt", source);
+    const hash = requiredSnapshotString(record, "hash", source);
+    const permissionsHash = requiredSnapshotString(record, "permissionsHash", source);
+    const permissions = plainRecord(record["permissions"]);
+    if (!permissions) {
+        throw new UsageError(`${source} is not an app permissions snapshot: "permissions" must be a JSON object.`, "validation_failed");
+    }
+    const actualPermissionsHash = appPermissionsHash(permissions);
+    const actualHash = stableHash({
+        version,
+        projectKey,
+        dssUrl,
+        projectIncarnationHash,
+        capturedAt,
+        permissionsHash,
+        permissions,
+    });
+    if (actualPermissionsHash !== permissionsHash || actualHash !== hash) {
+        throw new UsageError(`${source} failed its integrity check. Refusing to use a corrupted or hand-edited snapshot.`, "validation_failed", "Re-run `dss app permissions-snapshot` to capture a fresh snapshot.");
+    }
+    return {
+        version,
+        projectKey,
+        dssUrl,
+        projectIncarnationHash,
+        capturedAt,
+        hash,
+        permissionsHash,
+        permissions,
+    };
+}
+export function readAppPermissionsSnapshot(filePath) {
+    let text;
+    try {
+        text = fs.readFileSync(filePath, "utf-8");
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new UsageError(`Cannot read app permissions snapshot ${filePath}: ${message}`, "validation_failed");
+    }
+    return parseAppPermissionsSnapshot(text, filePath);
+}
+/**
+ * Refuse to use a snapshot outside the exact project *and* DSS server it was captured
+ * from. Access-control rules are server-scoped: the same project key, users, and groups
+ * exist on other instances with different meaning, so replaying a snapshot elsewhere can
+ * silently grant or revoke access. Runs before any live permission read or write.
+ */
+export function assertAppPermissionsSnapshotBinding(snapshot, targetProjectKey, currentDssUrl, currentProjectIncarnationHash) {
+    if (snapshot.projectKey !== targetProjectKey) {
+        throw new UsageError(`Snapshot was captured from project ${snapshot.projectKey} but the target project is ${targetProjectKey}. Refusing to restore permissions across projects.`, "validation_failed", `Pass --project-key ${snapshot.projectKey} to restore the project the snapshot came from.`);
+    }
+    const bound = canonicalDssUrl(snapshot.dssUrl);
+    const current = canonicalDssUrl(currentDssUrl);
+    if (bound !== current) {
+        throw new UsageError(`Snapshot was captured from DSS server ${bound} but the configured server is ${current}. Refusing to use permissions across DSS servers.`, "validation_failed", `Point the CLI at ${bound} to use this snapshot, or capture a fresh snapshot from ${current}.`, { projectKey: snapshot.projectKey, snapshotDssUrl: bound, currentDssUrl: current, });
+    }
+    if (currentProjectIncarnationHash === undefined)
+        return;
+    if (snapshot.projectIncarnationHash === currentProjectIncarnationHash)
+        return;
+    throw new UsageError(`Snapshot was captured from a different incarnation of project ${targetProjectKey}. Refusing to use permissions after project-key reuse.`, "validation_failed", "Capture a fresh permissions snapshot from the current project. Do not restore access-control data from the replaced project.", {
+        projectKey: targetProjectKey,
+        snapshotProjectIncarnationHash: snapshot.projectIncarnationHash,
+        currentProjectIncarnationHash,
+    });
+}
+export function appPermissionsVerificationError(projectKey, hashes) {
+    return new UsageError(`Permission restore verification failed for project ${projectKey}: expected hash ${hashes.desiredHash} after the update but DSS returned ${hashes.verifiedHash}.`, "validation_failed", "Re-read the live permissions with `dss app permissions-diff` before retrying; DSS may have rejected or rewritten part of the payload.", { projectKey, ...hashes, });
+}
+function differenceStatus(backup, current) {
+    if (backup === undefined)
+        return "added";
+    if (current === undefined)
+        return "removed";
+    return "changed";
+}
+function pushDifference(out, path, backup, current) {
+    out.push({
+        path,
+        status: differenceStatus(backup, current),
+        ...(backup === undefined ? {} : { backup, }),
+        ...(current === undefined ? {} : { current, }),
+    });
+}
+function collectDifferences(path, backup, current, out) {
+    if (stableJson(backup) === stableJson(current))
+        return;
+    const backupRecord = plainRecord(backup);
+    const currentRecord = plainRecord(current);
+    if (backupRecord && currentRecord) {
+        const keys = [...new Set([...Object.keys(backupRecord), ...Object.keys(currentRecord),]),]
+            .sort(compareStrings);
+        for (const key of keys) {
+            collectDifferences(path ? `${path}.${key}` : key, backupRecord[key], currentRecord[key], out);
+        }
+        return;
+    }
+    if (Array.isArray(backup) && Array.isArray(current)) {
+        const length = Math.max(backup.length, current.length);
+        for (let index = 0; index < length; index += 1) {
+            collectDifferences(`${path}[${String(index)}]`, backup[index], current[index], out);
+        }
+        return;
+    }
+    pushDifference(out, path || "(root)", backup, current);
+}
+/**
+ * Deterministic, path-addressed differences between a snapshot payload and live
+ * permissions. Paths are sorted so repeated runs emit byte-identical output.
+ */
+export function diffAppPermissions(backup, current) {
+    const differences = [];
+    collectDifferences("", backup, current, differences);
+    differences.sort((a, b) => compareStrings(a.path, b.path));
+    return { changed: differences.length > 0, differences, };
+}

package/dist/src/cli/helpers/app-successor.d.ts

@@ -0,0 +1,106 @@
+import type { DataikuClient } from "../../client.js";
+import type { AppManifestValidationResult } from "../../resources/applications.js";
+/**
+ * A DSS API key authenticates the public REST API only: the Application UI sits
+ * behind the interactive (often SSO) session, so no command in this SDK can
+ * observe it. Every app-release result therefore carries this gate explicitly
+ * instead of implying that a green API check means the UI works.
+ */
+export declare const VISUAL_UI_GATE: {
+    readonly gate: "visual-ui";
+    readonly status: "required";
+    readonly reason: "API key authenticates public REST only; use a pre-authenticated SSO browser session or dedicated UI test identity.";
+    readonly requiredAuthentication: "pre-authenticated-sso-or-dedicated-ui-test-identity";
+    readonly evidenceRequired: "Open the instance in the Dataiku Apps UI and exercise the affected tiles, forms, and actions to confirm the release behaves as intended.";
+};
+export type AppInstanceCheckName = "project-type" | "app-registration" | "manifest-version" | "manifest-references";
+export interface AppInstanceCheck {
+    check: AppInstanceCheckName;
+    status: "ok" | "failed";
+    expected: unknown;
+    actual: unknown;
+    /** Machine-readable cause when the compared values alone do not explain a failure. */
+    reason?: string;
+}
+export interface AppManifestReferenceSummary {
+    valid: boolean;
+    manifestHash: string;
+    checks: AppManifestValidationResult["checks"];
+    errors: AppManifestValidationResult["errors"];
+}
+export interface AppInstanceVerification {
+    appId: string;
+    projectKey: string;
+    projectAppType: string | null;
+    registered: boolean;
+    templateVersion: string | null;
+    expectedVersion: string | null;
+    expectedVersionSource: "expect-version" | "template-manifest";
+    instanceVersion: string | null;
+    instanceManifestHash: string | null;
+    templateManifestHash: string;
+    referenceValidation: AppManifestReferenceSummary | null;
+    checks: AppInstanceCheck[];
+    valid: boolean;
+}
+export interface SuccessorInstanceRequest {
+    appId: string;
+    from: string;
+    to: string;
+    name?: string;
+    copyPermissions: boolean;
+    dryRun: boolean;
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+}
+/** Never echoes response bodies: only the taxonomy DataikuError already deems safe. */
+export declare function safeErrorSummary(error: unknown): Record<string, unknown>;
+/**
+ * Read-only API readiness of one app instance. Only checks that the public REST
+ * API can answer authoritatively are performed; the UI gate stays external.
+ *
+ * The instance manifest is read exactly once: its version, hash and reference
+ * validation all describe that one snapshot, so a concurrent manifest edit can
+ * never produce a report whose fields contradict each other.
+ */
+export declare function verifyAppInstance(client: DataikuClient, appId: string, projectKey: string, expectVersion?: string): Promise<AppInstanceVerification>;
+/** Stage a permission copy reached. Only `copied`/`unchanged` mean the successor holds them. */
+export type AppPermissionCopyState = "not-requested" | "unchanged" | "copied" | "not-attempted" | "rejected" | "unknown" | "completed-unverified";
+/**
+ * True only when DSS definitively refused a write: a non-retryable 4xx with a
+ * classified client-side taxonomy. Transport failures (status 0), 5xx, retryable
+ * 4xx (408/425/429) and unclassified statuses leave the outcome unknown, so the
+ * effect of the request must be assumed possible.
+ */
+export declare function isDefinitiveRejection(error: unknown): boolean;
+/**
+ * Successor identity as reported by the creation future's own result.
+ *
+ * DSS names the project it created in `targetProjectKey`, and live instances of
+ * this future are also observed carrying `projectKey` for the *source template*,
+ * so the target-specific field always wins and `projectKey` speaks for the
+ * target only when no usable `targetProjectKey` is present. A missing, blank or
+ * non-string value is no identity claim at all, exactly as a blank manifest
+ * version names no release.
+ */
+export declare function futureTargetIdentity(result: unknown): {
+    projectKey: string;
+    field: "targetProjectKey" | "projectKey";
+} | null;
+/**
+ * Creation cleanup is safe only when the target was proven absent before POST.
+ * A hidden 403 is not absence: project listing can prove a collision, but it
+ * cannot prove that an inaccessible project does not exist.
+ */
+export declare function requireAbsentProjectTarget(client: DataikuClient, targetProjectKey: string, targetFlag: "--to" | "targetProjectKey"): Promise<void>;
+/**
+ * Create a new app instance from the current template version alongside an
+ * existing instance. Classic app instances have no public upgrade endpoint, so
+ * the predecessor is never touched: it stays available until it is separately
+ * and deliberately retired.
+ *
+ * After the creation POST this function never throws. A post-POST failure
+ * returns a failed-wait result carrying the target project key, so the CLI still
+ * exits 4 and the cleanup ledger still records an addressable successor.
+ */
+export declare function createSuccessorInstance(client: DataikuClient, request: SuccessorInstanceRequest, usage: string): Promise<Record<string, unknown>>;