feat: define workspace evidence descriptor contract
This commit is contained in:
@@ -6,6 +6,7 @@ import {
|
||||
parseWorkspaceYaml,
|
||||
serializeWorkspaceYaml,
|
||||
validateCanonicalWorkspace,
|
||||
validateWorkspaceDescriptor,
|
||||
type WorkspaceDescriptor,
|
||||
} from "../src/workspaces/schema.js";
|
||||
|
||||
@@ -272,3 +273,316 @@ test("serializes canonical YAML that parses back to the same workspace", () => {
|
||||
expect(serializeWorkspaceYaml(parseWorkspaceYaml(serialized))).toBe(serialized);
|
||||
expect(parseWorkspaceYaml(serialized)).toEqual(workspace);
|
||||
});
|
||||
|
||||
|
||||
function validWorkspaceObject(): Record<string, any> {
|
||||
return parseWorkspaceYaml(validYaml) as Record<string, any>;
|
||||
}
|
||||
|
||||
function withEvidence(source: Record<string, unknown>, policy?: Record<string, unknown>): Record<string, any> {
|
||||
const workspace = structuredClone(validWorkspaceObject());
|
||||
workspace.evidence = policy === undefined ? { source } : { source, policy };
|
||||
return workspace;
|
||||
}
|
||||
|
||||
function expectSafeEvidenceError(workspace: unknown, path: RegExp, canary?: string): void {
|
||||
let message = "";
|
||||
try {
|
||||
validateWorkspaceDescriptor(workspace);
|
||||
} catch (error) {
|
||||
message = error instanceof Error ? error.message : String(error);
|
||||
}
|
||||
expect(message.replace(/\s+/g, " ")).toMatch(path);
|
||||
if (canary !== undefined) expect(message).not.toContain(canary);
|
||||
}
|
||||
|
||||
const explicitPolicy = { max_chunk_chars: 8_000, retain_published_generations: 5 };
|
||||
|
||||
const validEvidenceSources = [
|
||||
{
|
||||
name: "filesystem with explicit values",
|
||||
source: {
|
||||
type: "filesystem",
|
||||
uri: "workspace-content/psd-clinical/evidence",
|
||||
patterns: ["documents/**/*.pdf", "notes/*.md"],
|
||||
max_bytes: 12_000_000,
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "HTTP without authentication",
|
||||
source: {
|
||||
type: "http",
|
||||
uris: ["https://evidence.example/manifest.json", "http://evidence.example/files/list.txt"],
|
||||
authentication: "none",
|
||||
connect_timeout_ms: 2_000,
|
||||
read_timeout_ms: 20_000,
|
||||
max_bytes: 12_000_000,
|
||||
max_redirects: 2,
|
||||
allow_private_hosts: false,
|
||||
max_cache_bytes: 24_000_000,
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "HTTP signed URL manifest",
|
||||
source: {
|
||||
type: "http",
|
||||
uris: ["https://evidence.example/signed-urls.txt"],
|
||||
authentication: "signed_urls_file",
|
||||
connect_timeout_ms: 2_000,
|
||||
read_timeout_ms: 20_000,
|
||||
max_bytes: 12_000_000,
|
||||
max_redirects: 2,
|
||||
allow_private_hosts: true,
|
||||
max_cache_bytes: 24_000_000,
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "S3 with ambient credentials",
|
||||
source: {
|
||||
type: "s3",
|
||||
uri: "s3://clinical-evidence/published/",
|
||||
region: "eu-west-1",
|
||||
credentials: "ambient",
|
||||
trusted_endpoint: false,
|
||||
allow_private_endpoint: false,
|
||||
allow_insecure_endpoint: false,
|
||||
max_bytes: 12_000_000,
|
||||
max_objects: 2_000,
|
||||
max_pages: 20,
|
||||
page_size: 100,
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "S3 with static-file credentials and a trusted endpoint",
|
||||
source: {
|
||||
type: "s3",
|
||||
uri: "s3://clinical-evidence/published/",
|
||||
endpoint_url: "https://objects.example",
|
||||
region: "eu-west-1",
|
||||
credentials: "static_files",
|
||||
trusted_endpoint: true,
|
||||
allow_private_endpoint: false,
|
||||
allow_insecure_endpoint: false,
|
||||
max_bytes: 12_000_000,
|
||||
max_objects: 2_000,
|
||||
max_pages: 20,
|
||||
page_size: 100,
|
||||
},
|
||||
},
|
||||
] as const;
|
||||
|
||||
test.each(validEvidenceSources)("accepts evidence source: $name", ({ source }) => {
|
||||
expect(validateWorkspaceDescriptor(withEvidence(source, explicitPolicy))).toMatchObject({
|
||||
evidence: { source, policy: explicitPolicy },
|
||||
});
|
||||
});
|
||||
|
||||
test("applies filesystem and policy defaults to the canonical descriptor", () => {
|
||||
const parsed = validateWorkspaceDescriptor(withEvidence({
|
||||
type: "filesystem",
|
||||
uri: "workspace-content/psd-clinical/evidence",
|
||||
}));
|
||||
|
||||
expect(parsed).toMatchObject({
|
||||
evidence: {
|
||||
source: {
|
||||
type: "filesystem",
|
||||
uri: "workspace-content/psd-clinical/evidence",
|
||||
patterns: ["**/*.md"],
|
||||
max_bytes: 10 * 1024 * 1024,
|
||||
},
|
||||
policy: { max_chunk_chars: 4_000, retain_published_generations: 3 },
|
||||
},
|
||||
});
|
||||
});
|
||||
|
||||
test("keeps evidence optional on schema v3", () => {
|
||||
expect(validateWorkspaceDescriptor(validWorkspaceObject())).not.toHaveProperty("evidence");
|
||||
});
|
||||
|
||||
test("serializes defaulted evidence canonically and parses it without loss", () => {
|
||||
const canonical = validateWorkspaceDescriptor(withEvidence({
|
||||
type: "filesystem",
|
||||
uri: "workspace-content/psd-clinical/evidence",
|
||||
}));
|
||||
if (canonical.workspace.schema_version !== 3) throw new Error("expected schema v3");
|
||||
|
||||
expect(parseWorkspaceYaml(serializeWorkspaceYaml(canonical))).toEqual(canonical);
|
||||
});
|
||||
|
||||
const invalidFilesystemPaths = [
|
||||
"/workspace-content/psd-clinical/evidence",
|
||||
"workspace-content/../psd-clinical/evidence",
|
||||
"workspace-content/./psd-clinical/evidence",
|
||||
"workspace-content//psd-clinical/evidence",
|
||||
"workspace-content/psd-clinical/evidence/..",
|
||||
"workspace-content\\psd-clinical\\evidence",
|
||||
"workspace-content/psd-clinical/evidence\u0000",
|
||||
"workspace-content/other-workspace/evidence",
|
||||
"workspace-content/psd-clinical",
|
||||
"workspace-content/psd-clinical/evidence/nested",
|
||||
];
|
||||
|
||||
test.each(invalidFilesystemPaths)("rejects unsafe or noncanonical filesystem URI %#", (uri) => {
|
||||
expectSafeEvidenceError(withEvidence({ type: "filesystem", uri }), /evidence.*source.*uri/i);
|
||||
});
|
||||
|
||||
const invalidPatterns = ["", "/absolute", "../escape", ".", "folder/./file", "folder//file", "folder/../file", "a\\b", "a\u0007b"];
|
||||
|
||||
test.each(invalidPatterns)("rejects unsafe evidence glob %#", (pattern) => {
|
||||
expectSafeEvidenceError(withEvidence({
|
||||
type: "filesystem",
|
||||
uri: "workspace-content/psd-clinical/evidence",
|
||||
patterns: [pattern],
|
||||
}), /evidence.*source.*patterns/i);
|
||||
});
|
||||
|
||||
test("rejects empty and duplicate filesystem patterns", () => {
|
||||
const source = { type: "filesystem", uri: "workspace-content/psd-clinical/evidence" };
|
||||
expectSafeEvidenceError(withEvidence({ ...source, patterns: [] }), /patterns/i);
|
||||
expectSafeEvidenceError(withEvidence({ ...source, patterns: ["**/*.pdf", "**/*.pdf"] }), /patterns/i);
|
||||
});
|
||||
|
||||
test.each(["ftp", "git", "unknown"])("rejects unsupported evidence discriminator %s", (type) => {
|
||||
expectSafeEvidenceError(withEvidence({ type, uri: "workspace-content/psd-clinical/evidence" }), /evidence.*source.*type/i);
|
||||
});
|
||||
|
||||
test("rejects unknown evidence keys", () => {
|
||||
expectSafeEvidenceError({ ...withEvidence({
|
||||
type: "filesystem",
|
||||
uri: "workspace-content/psd-clinical/evidence",
|
||||
}), evidence: {
|
||||
source: { type: "filesystem", uri: "workspace-content/psd-clinical/evidence", mystery: true },
|
||||
policy: explicitPolicy,
|
||||
mystery: true,
|
||||
} }, /unrecognized|mystery/i);
|
||||
});
|
||||
|
||||
const credentialFields = [
|
||||
"password", "api_key", "access_key", "secret_key", "session_token", "signed_url", "headers", "ca_contents",
|
||||
];
|
||||
|
||||
test.each(credentialFields)("rejects credential-shaped evidence field %s without leaking it", (field) => {
|
||||
const canary = `CANARY-${field}-DO-NOT-LEAK`;
|
||||
expectSafeEvidenceError(withEvidence({
|
||||
type: "filesystem",
|
||||
uri: "workspace-content/psd-clinical/evidence",
|
||||
[field]: canary,
|
||||
}), /evidence.*source/i, canary);
|
||||
});
|
||||
|
||||
const invalidHttpUris = [
|
||||
"https://user:CANARY-HTTP@example.com/manifest",
|
||||
"https://example.com/manifest?token=CANARY-HTTP",
|
||||
"https://example.com/manifest#CANARY-HTTP",
|
||||
"ftp://example.com/manifest/CANARY-HTTP",
|
||||
];
|
||||
|
||||
test.each(invalidHttpUris)("rejects unsafe HTTP descriptor URI %# without leaking it", (uri) => {
|
||||
expectSafeEvidenceError(withEvidence({ type: "http", uris: [uri] }), /evidence.*source.*uris.*0/i, "CANARY-HTTP");
|
||||
});
|
||||
|
||||
test("rejects empty and canonically duplicate HTTP manifests", () => {
|
||||
expectSafeEvidenceError(withEvidence({ type: "http", uris: [] }), /uris/i);
|
||||
expectSafeEvidenceError(withEvidence({
|
||||
type: "http",
|
||||
uris: ["https://EXAMPLE.com:443/manifest", "https://example.com/manifest"],
|
||||
}), /uris/i);
|
||||
});
|
||||
|
||||
const invalidHttpBounds = [
|
||||
["connect_timeout_ms", 0], ["read_timeout_ms", 0], ["max_bytes", 0],
|
||||
["max_redirects", -1], ["max_cache_bytes", 0], ["connect_timeout_ms", Number.MAX_SAFE_INTEGER + 1],
|
||||
] as const;
|
||||
|
||||
test.each(invalidHttpBounds)("rejects invalid HTTP bound %s=%s", (field, value) => {
|
||||
expectSafeEvidenceError(withEvidence({
|
||||
type: "http",
|
||||
uris: ["https://example.com/manifest"],
|
||||
[field]: value,
|
||||
}), new RegExp(field, "i"));
|
||||
});
|
||||
|
||||
const invalidS3Uris = [
|
||||
"https://bucket/prefix", "s3:///prefix", "s3://user:CANARY-S3@bucket/prefix",
|
||||
"s3://bucket/prefix?token=CANARY-S3", "s3://bucket/prefix#CANARY-S3",
|
||||
];
|
||||
|
||||
test.each(invalidS3Uris)("rejects invalid S3 URI %# without leaking it", (uri) => {
|
||||
expectSafeEvidenceError(withEvidence({ type: "s3", uri }), /evidence.*source.*uri/i, "CANARY-S3");
|
||||
});
|
||||
|
||||
const invalidS3Endpoints = [
|
||||
{ endpoint_url: "ftp://objects.example", trusted_endpoint: true },
|
||||
{ endpoint_url: "https://user:CANARY-S3@objects.example", trusted_endpoint: true },
|
||||
{ endpoint_url: "https://objects.example/path", trusted_endpoint: true },
|
||||
{ endpoint_url: "https://objects.example?token=CANARY-S3", trusted_endpoint: true },
|
||||
{ endpoint_url: "https://objects.example#CANARY-S3", trusted_endpoint: true },
|
||||
{ endpoint_url: "https://objects.example", trusted_endpoint: false },
|
||||
{ endpoint_url: "http://objects.example", trusted_endpoint: true, allow_insecure_endpoint: false },
|
||||
{ trusted_endpoint: true },
|
||||
{ allow_private_endpoint: true },
|
||||
{ allow_insecure_endpoint: true },
|
||||
];
|
||||
|
||||
test.each(invalidS3Endpoints)("rejects unsafe or inconsistent S3 endpoint %#", (endpoint) => {
|
||||
expectSafeEvidenceError(withEvidence({ type: "s3", uri: "s3://bucket/prefix", ...endpoint }), /evidence.*source/i, "CANARY-S3");
|
||||
});
|
||||
|
||||
const invalidS3Bounds = [
|
||||
["max_bytes", 0], ["max_objects", 0], ["max_pages", 0], ["page_size", 0],
|
||||
["max_objects", Number.MAX_SAFE_INTEGER + 1],
|
||||
] as const;
|
||||
|
||||
test.each(invalidS3Bounds)("rejects invalid S3 bound %s=%s", (field, value) => {
|
||||
expectSafeEvidenceError(withEvidence({
|
||||
type: "s3", uri: "s3://bucket/prefix", [field]: value,
|
||||
}), new RegExp(field, "i"));
|
||||
});
|
||||
|
||||
test.each([
|
||||
["max_chunk_chars", 0],
|
||||
["max_chunk_chars", Number.MAX_SAFE_INTEGER + 1],
|
||||
["retain_published_generations", 0],
|
||||
["retain_published_generations", Number.MAX_SAFE_INTEGER + 1],
|
||||
] as const)("rejects invalid evidence policy bound %s=%s", (field, value) => {
|
||||
expectSafeEvidenceError(withEvidence({
|
||||
type: "filesystem", uri: "workspace-content/psd-clinical/evidence",
|
||||
}, { ...explicitPolicy, [field]: value }), new RegExp(field, "i"));
|
||||
});
|
||||
|
||||
test("rejects evidence on strict schema v1 and v2 descriptors", () => {
|
||||
for (const schemaVersion of [1, 2]) {
|
||||
const yaml = validYaml
|
||||
.replace("schema_version: 3", `schema_version: ${schemaVersion}`)
|
||||
.replace(`semantic_index:
|
||||
vector_store:
|
||||
engine: qdrant
|
||||
collection: psd-clinical
|
||||
dimensions: 1024
|
||||
distance: cosine
|
||||
embedding:
|
||||
provider: ollama_internal
|
||||
model: qwen3-embedding:0.6b
|
||||
dimensions: 1024`, `semantic_index:
|
||||
vector_store:
|
||||
engine: pgvector
|
||||
database: postgres
|
||||
schema: vectors
|
||||
collection: documents
|
||||
dimensions: 1024
|
||||
distance: cosine
|
||||
supported_transports:
|
||||
- pgvector_direct
|
||||
embedding:
|
||||
provider: ollama_compatible
|
||||
model: evidence-test
|
||||
dimensions: 1024`)
|
||||
+ `evidence:
|
||||
source:
|
||||
type: filesystem
|
||||
uri: workspace-content/psd-clinical/evidence
|
||||
`;
|
||||
expect(() => parseWorkspaceYaml(yaml)).toThrow(/evidence|unrecognized/i);
|
||||
}
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user