arc-1 1.1.2 → 1.2.0

package/dist/adt/data-result-context.js

@@ -0,0 +1,118 @@
+import { AdtResponseLimitError } from './errors.js';
+export const DEFAULT_DATA_PREVIEW_RESPONSE_BYTES = 2 * 1024 * 1024;
+export const DEFAULT_CONCURRENT_DATA_RESULTS = 2;
+/** One cumulative post-content-decoding allowance shared by a complete MCP tool call. */
+export class DataResponseBudget {
+    limitBytes;
+    endpointFamily;
+    committedBytes = 0;
+    inFlightBytes = 0;
+    constructor(limitBytes, endpointFamily = 'data-preview') {
+        this.limitBytes = limitBytes;
+        this.endpointFamily = endpointFamily;
+        if (!Number.isSafeInteger(limitBytes) || limitBytes < 1) {
+            throw new RangeError(`Data response limit must be a positive safe integer, got ${limitBytes}.`);
+        }
+    }
+    get consumedBytes() {
+        return this.committedBytes;
+    }
+    get reservedBytes() {
+        return this.inFlightBytes;
+    }
+    createReservation() {
+        return new DataResponseReservation(this, { bytes: 0, settled: false });
+    }
+    assertSingleResponseBytes(bytes, requestId) {
+        if (bytes > this.limitBytes) {
+            throw new AdtResponseLimitError(this.limitBytes, bytes, this.endpointFamily, requestId);
+        }
+    }
+    reserve(state, nextChunkBytes, requestId) {
+        if (state.settled)
+            throw new Error('Cannot reserve bytes on a settled data-response reservation.');
+        const observedBytes = this.committedBytes + this.inFlightBytes + nextChunkBytes;
+        if (observedBytes > this.limitBytes) {
+            throw new AdtResponseLimitError(this.limitBytes, observedBytes, this.endpointFamily, requestId);
+        }
+        state.bytes += nextChunkBytes;
+        this.inFlightBytes += nextChunkBytes;
+    }
+    commit(state) {
+        if (state.settled)
+            return;
+        state.settled = true;
+        this.inFlightBytes -= state.bytes;
+        this.committedBytes += state.bytes;
+    }
+    release(state) {
+        if (state.settled)
+            return;
+        state.settled = true;
+        this.inFlightBytes -= state.bytes;
+    }
+}
+export class DataResponseReservation {
+    budget;
+    state;
+    constructor(budget, state) {
+        this.budget = budget;
+        this.state = state;
+    }
+    add(bytes, requestId) {
+        this.budget.reserve(this.state, bytes, requestId);
+    }
+    commit() {
+        this.budget.commit(this.state);
+    }
+    release() {
+        this.budget.release(this.state);
+    }
+}
+/** Lazy process-wide admission lease plus the request's cumulative response budget. */
+export class DataResultScope {
+    semaphore;
+    responseBudget;
+    leasePromise;
+    leaseHeld = false;
+    released = false;
+    _queueWaitMs = 0;
+    constructor(limitBytes, semaphore) {
+        this.semaphore = semaphore;
+        this.responseBudget = new DataResponseBudget(limitBytes);
+    }
+    get queueWaitMs() {
+        return this._queueWaitMs;
+    }
+    get hasLease() {
+        return this.leaseHeld;
+    }
+    async acquire(signal) {
+        if (this.released)
+            throw new Error('Cannot acquire a released data-result scope.');
+        if (!this.semaphore || this.leaseHeld)
+            return;
+        if (!this.leasePromise) {
+            const startedAt = Date.now();
+            this.leasePromise = this.semaphore.acquire(signal).then(() => {
+                this._queueWaitMs = Date.now() - startedAt;
+                if (this.released) {
+                    this.semaphore?.release();
+                    throw new Error('Data-result scope was released while waiting for admission.');
+                }
+                this.leaseHeld = true;
+            });
+        }
+        await this.leasePromise;
+    }
+    release() {
+        if (this.released)
+            return;
+        this.released = true;
+        if (this.leaseHeld) {
+            this.leaseHeld = false;
+            this.semaphore?.release();
+        }
+    }
+}
+//# sourceMappingURL=data-result-context.js.map

package/dist/adt/data-result-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-result-context.js","sourceRoot":"","sources":["../../src/adt/data-result-context.ts"],"names":[],"mappings":"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"}

package/dist/adt/data-source-name.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Canonical ARC-1 data-source identity.
+ *
+ * This is the SINGLE normalizer for every value that can take part in a data-source policy
+ * decision: configuration entries, caller-supplied roots, SQL parser results, repository-search
+ * results, URI-decoded DDLS identities, dependency-graph node names and aliases, replacement-object
+ * annotations, and internal registry entries. Two different normalizers would let the name that is
+ * checked drift from the name that is executed, which is the whole class of bug this module exists
+ * to make impossible.
+ *
+ * Deliberately dependency-free (besides `node:crypto`) so `src/server/config.ts` can validate
+ * startup configuration without pulling the ABAP parser into process start.
+ */
+/** Upper bound on a canonical technical name. */
+export declare const MAX_DATA_SOURCE_NAME_LENGTH = 128;
+/** A value could not be canonicalized into an exact ABAP data-source identity. */
+export declare class DataSourceNameError extends Error {
+    constructor(message: string);
+}
+/** Strip only ASCII surrounding whitespace. Unicode whitespace is intentionally preserved. */
+export declare function asciiTrim(raw: string): string;
+/**
+ * Canonicalize one exact ABAP data-source identity, or throw.
+ *
+ * Order matters and is part of the contract: ASCII-trim, then validate the RAW value, then fold
+ * case. Nothing is ever silently removed — a name that would need character stripping is rejected.
+ *
+ * @param raw   the value as supplied by configuration, a caller, or SAP metadata
+ * @param what  short label used in the error message (for example `SAP_BLOCKED_DATA_SOURCES entry #2`)
+ */
+export declare function canonicalDataSourceName(raw: string, what?: string): string;
+/** Canonicalize a list, dropping exact duplicates while keeping first-occurrence order. */
+export declare function canonicalDataSourceNames(raws: readonly string[], what?: string): string[];
+/**
+ * Parse the `SAP_BLOCKED_DATA_SOURCES` CSV contract.
+ *
+ * - unset (caller passes `undefined`), empty, or ASCII-whitespace-only → off (empty list);
+ * - once the ASCII-trimmed value is non-empty, EVERY comma-separated field is mandatory, so
+ *   `,` `,,,` `,USR02` `USR02,` and `USR02,,PA0002` are startup errors rather than silently dropped;
+ * - each field is canonicalized with {@link canonicalDataSourceName};
+ * - duplicates collapse while preserving first-occurrence order.
+ *
+ * A value consisting only of NON-ASCII whitespace (for example U+3000) is deliberately an error, not
+ * "off": it is indistinguishable from a corrupted deployment value, and only ASCII blanks are the
+ * documented off switch.
+ */
+export declare function parseBlockedDataSourcesCsv(raw: string, sourceLabel?: string): string[];
+/**
+ * Deterministic policy fingerprint: SHA-256 over `data-source-blocklist:v1\n` followed by the
+ * sorted, unique, canonical names joined with `\n`.
+ *
+ * Order- and duplicate-independent, so two deployments with the same effective policy produce the
+ * same value. This is a configuration-drift and correlation identifier ONLY — it is unsalted by
+ * design, the candidate name space is small and guessable, and it must never be described as
+ * protecting the contents of the list. Exact values live on administrator-only surfaces.
+ */
+export declare function dataSourcePolicyFingerprint(names: readonly string[]): string;
+/** Short human-facing form of {@link dataSourcePolicyFingerprint} for startup logs. */
+export declare function shortPolicyFingerprint(names: readonly string[]): string;
+//# sourceMappingURL=data-source-name.d.ts.map

package/dist/adt/data-source-name.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-source-name.d.ts","sourceRoot":"","sources":["../../src/adt/data-source-name.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,iDAAiD;AACjD,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAqB/C,kFAAkF;AAClF,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,YAAY,OAAO,EAAE,MAAM,EAG1B;CACF;AAED,8FAA8F;AAC9F,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAE7C;AA0BD;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,SAAqB,GAAG,MAAM,CAoBtF;AAED,2FAA2F;AAC3F,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,SAAqB,GAAG,MAAM,EAAE,CAWrG;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,SAA6B,GAAG,MAAM,EAAE,CAqB1G;AAED;;;;;;;;GAQG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAK5E;AAED,uFAAuF;AACvF,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAEvE"}

package/dist/adt/data-source-name.js

@@ -0,0 +1,156 @@
+/**
+ * Canonical ARC-1 data-source identity.
+ *
+ * This is the SINGLE normalizer for every value that can take part in a data-source policy
+ * decision: configuration entries, caller-supplied roots, SQL parser results, repository-search
+ * results, URI-decoded DDLS identities, dependency-graph node names and aliases, replacement-object
+ * annotations, and internal registry entries. Two different normalizers would let the name that is
+ * checked drift from the name that is executed, which is the whole class of bug this module exists
+ * to make impossible.
+ *
+ * Deliberately dependency-free (besides `node:crypto`) so `src/server/config.ts` can validate
+ * startup configuration without pulling the ABAP parser into process start.
+ */
+import { createHash } from 'node:crypto';
+/** Upper bound on a canonical technical name. */
+export const MAX_DATA_SOURCE_NAME_LENGTH = 128;
+/**
+ * ASCII whitespace only — space, tab, LF, VT, FF, CR.
+ *
+ * `String.prototype.trim()` also strips Unicode whitespace (U+00A0, U+3000, U+2028, …). That is
+ * exactly what we must NOT do: trimming a non-ASCII pad would let `"　USR02"` canonicalize to
+ * `USR02`, i.e. two visually different configuration values collapsing to one identity. Unicode
+ * whitespace is not trimmed here, so it survives into the ASCII check below and is rejected.
+ */
+const ASCII_TRIM = /^[\t\n\v\f\r ]+|[\t\n\v\f\r ]+$/g;
+/** The complete accepted character set, tested against the RAW value before any case folding. */
+const ASCII_ALLOWED = /^[A-Za-z0-9_/$]+$/;
+/** At least one letter or digit: `/`, `$`, `_`, and combinations of them are not names. */
+const HAS_ALPHANUMERIC = /[A-Za-z0-9]/;
+/** Longest offending token echoed back in a startup error. */
+const MAX_ECHOED_TOKEN = 64;
+/** A value could not be canonicalized into an exact ABAP data-source identity. */
+export class DataSourceNameError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'DataSourceNameError';
+    }
+}
+/** Strip only ASCII surrounding whitespace. Unicode whitespace is intentionally preserved. */
+export function asciiTrim(raw) {
+    return raw.replace(ASCII_TRIM, '');
+}
+/** Echo an operator's bad token without dumping unbounded or unrelated content. */
+function echoToken(raw) {
+    const flat = raw.replace(/[\r\n\t]/g, ' ');
+    const clipped = flat.length > MAX_ECHOED_TOKEN ? `${flat.slice(0, MAX_ECHOED_TOKEN)}…` : flat;
+    return JSON.stringify(clipped);
+}
+/**
+ * Uppercase ASCII `a-z` and nothing else.
+ *
+ * `String.prototype.toUpperCase()` is Unicode-aware: `ſ` (U+017F) folds to `S`, `ß` to `SS`, and the
+ * `ff` ligature to `FF`. Applying it before validation makes a validator that claims to accept only
+ * `A-Z0-9_/$` silently accept non-ASCII input. The ASCII gate above already rejects those inputs, so
+ * this mapping is defence in depth: it stays correct even if the checks are ever reordered.
+ */
+function upperCaseAscii(value) {
+    let out = '';
+    for (let i = 0; i < value.length; i++) {
+        const code = value.charCodeAt(i);
+        out += code >= 97 && code <= 122 ? String.fromCharCode(code - 32) : value[i];
+    }
+    return out;
+}
+/**
+ * Canonicalize one exact ABAP data-source identity, or throw.
+ *
+ * Order matters and is part of the contract: ASCII-trim, then validate the RAW value, then fold
+ * case. Nothing is ever silently removed — a name that would need character stripping is rejected.
+ *
+ * @param raw   the value as supplied by configuration, a caller, or SAP metadata
+ * @param what  short label used in the error message (for example `SAP_BLOCKED_DATA_SOURCES entry #2`)
+ */
+export function canonicalDataSourceName(raw, what = 'data-source name') {
+    const trimmed = asciiTrim(raw);
+    if (trimmed.length === 0) {
+        throw new DataSourceNameError(`${what} is empty`);
+    }
+    if (trimmed.length > MAX_DATA_SOURCE_NAME_LENGTH) {
+        throw new DataSourceNameError(`${what} exceeds the ${MAX_DATA_SOURCE_NAME_LENGTH}-character limit (${trimmed.length} characters)`);
+    }
+    if (!ASCII_ALLOWED.test(trimmed)) {
+        throw new DataSourceNameError(`${what} ${echoToken(trimmed)} is not an exact technical name: only ASCII A-Z, a-z, 0-9, _, / and $ are allowed ` +
+            '(no wildcards, type prefixes, negation, quoting, regex syntax, or non-ASCII characters)');
+    }
+    if (!HAS_ALPHANUMERIC.test(trimmed)) {
+        throw new DataSourceNameError(`${what} ${echoToken(trimmed)} needs at least one ASCII letter or digit`);
+    }
+    return upperCaseAscii(trimmed);
+}
+/** Canonicalize a list, dropping exact duplicates while keeping first-occurrence order. */
+export function canonicalDataSourceNames(raws, what = 'data-source name') {
+    const seen = new Set();
+    const out = [];
+    for (const raw of raws) {
+        const name = canonicalDataSourceName(raw, what);
+        if (!seen.has(name)) {
+            seen.add(name);
+            out.push(name);
+        }
+    }
+    return out;
+}
+/**
+ * Parse the `SAP_BLOCKED_DATA_SOURCES` CSV contract.
+ *
+ * - unset (caller passes `undefined`), empty, or ASCII-whitespace-only → off (empty list);
+ * - once the ASCII-trimmed value is non-empty, EVERY comma-separated field is mandatory, so
+ *   `,` `,,,` `,USR02` `USR02,` and `USR02,,PA0002` are startup errors rather than silently dropped;
+ * - each field is canonicalized with {@link canonicalDataSourceName};
+ * - duplicates collapse while preserving first-occurrence order.
+ *
+ * A value consisting only of NON-ASCII whitespace (for example U+3000) is deliberately an error, not
+ * "off": it is indistinguishable from a corrupted deployment value, and only ASCII blanks are the
+ * documented off switch.
+ */
+export function parseBlockedDataSourcesCsv(raw, sourceLabel = 'SAP_BLOCKED_DATA_SOURCES') {
+    if (asciiTrim(raw).length === 0)
+        return [];
+    const fields = raw.split(',');
+    const seen = new Set();
+    const out = [];
+    for (let i = 0; i < fields.length; i++) {
+        const position = `${sourceLabel} entry #${i + 1} of ${fields.length}`;
+        if (asciiTrim(fields[i]).length === 0) {
+            throw new DataSourceNameError(`${position} is empty: leading, trailing, repeated, and separator-only commas are not allowed. ` +
+                `Set ${sourceLabel} to an empty value to turn the policy off.`);
+        }
+        const name = canonicalDataSourceName(fields[i], position);
+        if (!seen.has(name)) {
+            seen.add(name);
+            out.push(name);
+        }
+    }
+    return out;
+}
+/**
+ * Deterministic policy fingerprint: SHA-256 over `data-source-blocklist:v1\n` followed by the
+ * sorted, unique, canonical names joined with `\n`.
+ *
+ * Order- and duplicate-independent, so two deployments with the same effective policy produce the
+ * same value. This is a configuration-drift and correlation identifier ONLY — it is unsalted by
+ * design, the candidate name space is small and guessable, and it must never be described as
+ * protecting the contents of the list. Exact values live on administrator-only surfaces.
+ */
+export function dataSourcePolicyFingerprint(names) {
+    const canonical = [...new Set(names)].sort();
+    return createHash('sha256')
+        .update(`data-source-blocklist:v1\n${canonical.join('\n')}`)
+        .digest('hex');
+}
+/** Short human-facing form of {@link dataSourcePolicyFingerprint} for startup logs. */
+export function shortPolicyFingerprint(names) {
+    return dataSourcePolicyFingerprint(names).slice(0, 12);
+}
+//# sourceMappingURL=data-source-name.js.map

package/dist/adt/data-source-name.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-source-name.js","sourceRoot":"","sources":["../../src/adt/data-source-name.ts"],"names":[],"mappings":"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"}

package/dist/adt/data-source-policy.d.ts

@@ -0,0 +1,148 @@
+/** Experimental exact-name data-source blocklist and live CDS-lineage evaluation. */
+import { AdtSafetyError } from './errors.js';
+/**
+ * Stable, distinct client-facing outcomes.
+ *
+ * - `DATA_SOURCE_BLOCKED`      an exact configured rule matched.
+ * - `DATA_LINEAGE_UNRESOLVED`  SAP metadata/identity/graph/replacement lineage could not be proven.
+ * - `DATA_SQL_UNSUPPORTED`     the caller's SQL is outside the strict accepted grammar.
+ *
+ * They stay distinguishable on purpose: a model that cannot tell "blocked by policy" from "SQL not
+ * supported" cannot self-correct. That does permit coarse membership probing, which is a documented,
+ * deliberate trade rather than an oversight.
+ */
+export type DataSourcePolicyErrorCode = 'DATA_SOURCE_BLOCKED' | 'DATA_LINEAGE_UNRESOLVED' | 'DATA_SQL_UNSUPPORTED';
+/** Opaque, bounded, non-secret correlation id shared by the client error and the audit record. */
+export declare function newDecisionId(): string;
+export declare class DataSourcePolicyError extends AdtSafetyError {
+    readonly code: DataSourcePolicyErrorCode;
+    readonly directSource: string;
+    readonly sourcePath: string[];
+    readonly decisionId: string;
+    readonly matchedSource?: string;
+    readonly reason: string;
+    /** Always false: every policy denial happens before the SAP data request is submitted. */
+    readonly executed = false;
+    constructor(code: DataSourcePolicyErrorCode, directSource: string, sourcePath: string[], reason: string, options?: {
+        decisionId?: string;
+        matchedSource?: string;
+    });
+    /**
+     * Client-facing text.
+     *
+     * `ARC1_MINIMAL_ERRORS` is a CLIENT DISCLOSURE control only: it removes the direct root, the
+     * matched rule, the dependency path and the configuration variable name, keeping just enough for
+     * the model to act (stable code, executed=false, decision id, and a safe alternative). It does not
+     * change the decision and does not reduce what the audit event records.
+     *
+     * The three codes stay distinguishable even in minimal mode, which does permit coarse membership
+     * probing. That is a deliberate, documented trade: a model that cannot tell "blocked by policy"
+     * from "SQL not supported" cannot correct itself.
+     */
+    clientMessage(minimalErrors: boolean): string;
+    /** Guidance that does not reveal policy-sensitive names. */
+    private safeAlternative;
+}
+/**
+ * SQL node kinds SAP emits in the dependency branch. Verified live on SAP_BASIS 750, 758 and 816.
+ * Anything outside this set inside a SQL branch fails closed.
+ */
+export declare const SQL_NODE_KINDS: readonly ['CDS_VIEW', 'TABLE', 'CDS_TABLE_FUNCTION'];
+export type SqlNodeKind = (typeof SQL_NODE_KINDS)[number];
+export interface CdsDependencyNode {
+    name: string;
+    aliases: string[];
+    kind: SqlNodeKind;
+    relation?: string;
+    databaseExists?: boolean;
+    /** Access-control presence, retained as audit context only — never an authorization decision. */
+    accessControlled: boolean;
+    children: CdsDependencyNode[];
+}
+export type ResolvedDirectDataSource = {
+    kind: 'table';
+    name: string;
+} | {
+    kind: 'cds';
+    name: string;
+    ddlSource: string;
+} | {
+    kind: 'classic-view' | 'structure' | 'unknown';
+    name: string;
+};
+export interface DataSourcePolicyResolver {
+    resolveDirectSource(name: string): Promise<ResolvedDirectDataSource>;
+    readTableSource(name: string): Promise<string>;
+    readCdsDependencyGraph(ddlSource: string): Promise<CdsDependencyNode>;
+}
+export interface DataSourcePolicyBackend {
+    searchObject(name: string, maxResults: number): Promise<Array<{
+        objectName: string;
+        objectType: string;
+        uri: string;
+    }>>;
+    readTableSource(name: string): Promise<string>;
+    dependencyGraphAccept(): string | undefined;
+    readDependencyGraph(path: string, accept: string): Promise<string>;
+}
+/** Request-scoped adapter from ADT metadata reads to the pure lineage evaluator. */
+export declare class DataSourceBlocklistGuard {
+    private readonly blockedSources;
+    private readonly backend;
+    /** Per-decision instrumentation. The guard is constructed per logical request and never reused. */
+    private metadataRequests;
+    private graphNodes;
+    constructor(blockedSources: string[], backend: DataSourcePolicyBackend);
+    /**
+     * Run one policy decision and record exactly one audit event for it, allow or deny.
+     *
+     * The audit record is the protected copy: it always carries the complete normalized decision, so
+     * an operator can reconstruct a denial even when the client was told almost nothing.
+     */
+    private decide;
+    enforceTableContents(tableName: string, sqlFilter?: string): Promise<void>;
+    /**
+     * Authorize every statement of one logical request together.
+     *
+     * The union of canonical direct sources is deduplicated before any SAP call, so N chunks that all
+     * read the same table cost exactly one lineage resolution, and a source appearing in only one chunk
+     * still denies the whole batch.
+     */
+    enforceSqlBatch(statements: string[]): Promise<void>;
+    private analyzeOrThrow;
+    enforceSources(directSources: string[]): Promise<void>;
+    /** The evaluation itself, without audit framing, so exactly one event is emitted per request. */
+    private evaluate;
+    private resolveDirectSource;
+    private readCdsDependencyGraph;
+}
+/** Endpoint the SQL dependency graph is served from. */
+export declare const CDS_DEPENDENCY_GRAPH_PATH = "/sap/bc/adt/ddic/ddl/dependencies/graphdata";
+/**
+ * Wire a request-scoped guard from the ADT primitives it needs.
+ *
+ * Lives here rather than on the client so the ADT facade stays a facade: this is policy wiring, and
+ * a new guard is built per logical request so its instrumentation can never leak between decisions.
+ */
+export declare function createDataSourceBlocklistGuard(deps: {
+    blockedDataSources: string[];
+    searchObject: DataSourcePolicyBackend['searchObject'];
+    readTableSource: DataSourcePolicyBackend['readTableSource'];
+    dependencyGraphAccept: DataSourcePolicyBackend['dependencyGraphAccept'];
+    readDependencyGraph: DataSourcePolicyBackend['readDependencyGraph'];
+}): DataSourceBlocklistGuard;
+/**
+ * Parse SAP dependency-analyzer XML (750 element-info and 758/816 SQLDependencyModel v3) into one
+ * bounded, explicitly classified tree.
+ *
+ * Every node is classified before it can influence a decision. SQL nodes enter lineage; the verified
+ * auxiliary access-control chain is validated and dropped; anything else fails closed. Explicit kind
+ * classification is the primary boundary here — a later failed table-source read is defence in depth,
+ * not the protection.
+ */
+export declare function parseCdsDependencyGraph(xml: string): CdsDependencyNode;
+/** Return a table's active CDS replacement object; malformed or duplicate annotations fail closed. */
+export declare function extractReplacementObject(source: string): string | undefined;
+/** Evaluate direct sources and their active lineage before a data-preview request is sent. */
+export declare function enforceBlockedDataSources(directSources: string[], configuredBlockedSources: string[], resolver: DataSourcePolicyResolver): Promise<void>;
+//# sourceMappingURL=data-source-policy.d.ts.map

package/dist/adt/data-source-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"data-source-policy.d.ts","sourceRoot":"","sources":["../../src/adt/data-source-policy.ts"],"names":[],"mappings":"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"}