@aiwg/cli 2026.8.26 → 2026.8.28

package/dist/src/governance/boundary.js

@@ -0,0 +1,354 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { createSanitizedSummary, evaluatePublicationGate, resolveArtifactGovernance, resolveClassificationDefinitions, } from './classification.js';
+import { createEvidenceLifecycle, validateRetentionRules, } from './retention.js';
+import { redactStructured, redactText, } from './redaction.js';
+export const DEFAULT_PUBLICATION_SINKS = {
+    'local-ephemeral': {
+        id: 'local-ephemeral', visibility: 'restricted', external: false,
+        persistent: false, mutable: true, maxClassification: 'restricted-identity',
+    },
+    'private-repository': {
+        id: 'private-repository', visibility: 'private', external: false,
+        persistent: true, mutable: true, maxClassification: 'restricted-infrastructure',
+    },
+    'public-repository': {
+        id: 'public-repository', visibility: 'public', external: true,
+        persistent: true, mutable: true, maxClassification: 'public', acceptsSanitizedSummary: true,
+    },
+    'private-issue': {
+        id: 'private-issue', visibility: 'private', external: true,
+        persistent: true, mutable: false, maxClassification: 'confidential', acceptsSanitizedSummary: true,
+    },
+    'public-issue': {
+        id: 'public-issue', visibility: 'public', external: true,
+        persistent: true, mutable: false, maxClassification: 'public', acceptsSanitizedSummary: true,
+    },
+    'encrypted-artifact-store': {
+        id: 'encrypted-artifact-store', visibility: 'restricted', external: false,
+        persistent: true, mutable: true, maxClassification: 'restricted-identity',
+    },
+};
+export function resolveGovernancePolicy(policy = {}) {
+    const resolved = {
+        ...policy,
+        sinks: { ...DEFAULT_PUBLICATION_SINKS, ...(policy.sinks ?? {}) },
+    };
+    const classes = resolveClassificationDefinitions(resolved.classification);
+    const classificationReferences = [
+        resolved.classification?.defaultClassification,
+        ...Object.values(resolved.classification?.defaultsByKind ?? {}),
+        ...Object.values(resolved.classification?.defaultsByCategory ?? {}),
+    ].filter((value) => value !== undefined);
+    for (const value of classificationReferences) {
+        if (!classes[value])
+            throw new Error(`governance policy references unknown classification '${value}'`);
+    }
+    for (const [id, sink] of Object.entries(resolved.sinks ?? {})) {
+        if (!sink || typeof sink !== 'object')
+            throw new Error(`sink '${id}' must be an object`);
+        if (sink.id !== id)
+            throw new Error(`sink map key '${id}' does not match sink ID '${sink.id}'`);
+        if (!new Set(['public', 'private', 'restricted', 'unknown']).has(sink.visibility)) {
+            throw new Error(`sink '${id}' has invalid visibility`);
+        }
+        for (const property of ['external', 'persistent', 'mutable']) {
+            if (typeof sink[property] !== 'boolean')
+                throw new Error(`sink '${id}' requires boolean ${property}`);
+        }
+        for (const property of ['acceptsSanitizedSummary', 'allowRedactionOverride']) {
+            if (sink[property] !== undefined && typeof sink[property] !== 'boolean') {
+                throw new Error(`sink '${id}' requires boolean ${property}`);
+            }
+        }
+        if (sink.maxClassification && !classes[sink.maxClassification]) {
+            throw new Error(`sink '${id}' references unknown classification '${sink.maxClassification}'`);
+        }
+    }
+    validateRetentionRules(resolved.retention ?? []);
+    // Compile configured patterns up front. Empty input cannot create findings,
+    // but invalid or high-risk organization patterns still fail validation.
+    redactText('', resolved.redaction ?? {});
+    redactStructured({ validation: 'ok' }, resolved.redaction ?? {});
+    return resolved;
+}
+function sha256(value) {
+    return `sha256:${createHash('sha256').update(value).digest('hex')}`;
+}
+function safeAuditLabel(value) {
+    try {
+        if (/^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$/.test(value) && redactText(value).sensitivity === 'none')
+            return value;
+    }
+    catch {
+        // Hashing is the fail-closed representation for malformed labels.
+    }
+    return sha256(value);
+}
+function stableStatus(value) {
+    if (!value)
+        return undefined;
+    const normalized = value.toLowerCase().replaceAll('_', '-').replaceAll(' ', '-');
+    return new Set([
+        'ok', 'pass', 'passed', 'fail', 'failed', 'complete', 'completed', 'blocked',
+        'partial', 'unknown', 'in-progress', 'review-needed', 'success', 'error',
+    ]).has(normalized) ? normalized : undefined;
+}
+function contentDigest(value) {
+    if (typeof value === 'string')
+        return sha256(value);
+    try {
+        return sha256(JSON.stringify(value) ?? '[undefined]');
+    }
+    catch {
+        return sha256('[unserializable]');
+    }
+}
+function boundedExcerpt(value, maxBytes) {
+    if (typeof value !== 'string')
+        return undefined;
+    const source = Buffer.from(value);
+    return {
+        excerpt: source.subarray(0, maxBytes).toString('utf8'),
+        bytes: source.length,
+        digest: sha256(value),
+        truncated: source.length > maxBytes,
+    };
+}
+/** Reduce command evidence to outcomes, bounded excerpts, counts, and correlation digests by default. */
+export function minimizeEvidence(payload, maxExcerptBytes = 512) {
+    if (!Number.isSafeInteger(maxExcerptBytes) || maxExcerptBytes < 0 || maxExcerptBytes > 64 * 1024) {
+        throw new Error('maxExcerptBytes must be an integer from 0 through 65536');
+    }
+    if (typeof payload === 'string') {
+        return boundedExcerpt(payload, maxExcerptBytes);
+    }
+    if (Array.isArray(payload)) {
+        return { itemCount: payload.length, digest: contentDigest(payload) };
+    }
+    if (!payload || typeof payload !== 'object')
+        return payload;
+    const source = payload;
+    const result = {
+        schemaVersion: 'ops-minimum-evidence.aiwg.io/v1',
+        sourceFieldCount: Object.keys(source).length,
+        sourceDigest: contentDigest(source),
+    };
+    for (const key of ['status', 'outcome', 'success', 'exitCode', 'durationMs', 'startedAt', 'completedAt']) {
+        const value = source[key];
+        if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean')
+            result[key] = value;
+    }
+    const stdout = boundedExcerpt(source.stdout ?? source.output, maxExcerptBytes);
+    const stderr = boundedExcerpt(source.stderr, maxExcerptBytes);
+    if (stdout)
+        result.stdout = stdout;
+    if (stderr)
+        result.stderr = stderr;
+    if (source.command !== undefined)
+        result.commandDigest = contentDigest(source.command);
+    return result;
+}
+function validOverride(override, artifactId, sinkId, now) {
+    if (!override?.id || !override.actor || !override.reason.trim())
+        return false;
+    if (override.artifactId !== artifactId || override.sinkId !== sinkId)
+        return false;
+    const approvedAt = Date.parse(override.approvedAt);
+    if (!Number.isFinite(approvedAt) || approvedAt > now)
+        return false;
+    if (override.expiresAt !== undefined) {
+        const expiresAt = Date.parse(override.expiresAt);
+        if (!Number.isFinite(expiresAt) || expiresAt <= now || expiresAt <= approvedAt)
+            return false;
+    }
+    return true;
+}
+function emptyAudit(input, sinkId, now) {
+    return {
+        schemaVersion: 'ops-evidence-boundary.aiwg.io/v1',
+        eventId: randomUUID(),
+        occurredAt: now.toISOString(),
+        artifactId: sha256(input.id),
+        artifactKind: safeAuditLabel(input.kind),
+        sinkId: safeAuditLabel(sinkId),
+        decision: 'deny',
+        reasonCodes: [],
+        redaction: 'not-needed',
+        redactionCount: 0,
+        redactionClasses: [],
+    };
+}
+function sanitizePayload(payload, options) {
+    if (typeof payload === 'string') {
+        const result = redactText(payload, options);
+        return { value: result.text, findings: result.findings };
+    }
+    const result = redactStructured(payload, options);
+    return { value: result.value, findings: result.findings };
+}
+/**
+ * Mandatory sink boundary: minimize, redact, classify/gate, and attach lifecycle
+ * metadata before returning any publishable value. Failure returns no payload.
+ */
+export function prepareEvidenceForSink(input) {
+    const now = input.now ?? new Date();
+    const audit = emptyAudit(input.artifact, input.sinkId, now);
+    let policy;
+    try {
+        policy = resolveGovernancePolicy(input.policy);
+    }
+    catch {
+        audit.reasonCodes = ['invalid-governance-policy'];
+        return { allowed: false, audit };
+    }
+    const sink = policy.sinks?.[input.sinkId];
+    if (!sink) {
+        audit.reasonCodes = ['unknown-sink'];
+        audit.redaction = 'failed';
+        return { allowed: false, audit };
+    }
+    let governance;
+    try {
+        governance = resolveArtifactGovernance({
+            kind: input.artifact.kind,
+            category: input.artifact.category,
+            metadata: input.artifact.governance,
+            parent: input.artifact.parentGovernance,
+            policy: policy.classification,
+        });
+    }
+    catch {
+        audit.reasonCodes = ['invalid-classification-metadata'];
+        return { allowed: false, audit };
+    }
+    const tier = input.artifact.tier ?? 'durable';
+    let candidate;
+    try {
+        candidate = tier === 'raw' || input.artifact.category === 'sanitized-summary'
+            ? input.artifact.payload
+            : minimizeEvidence(input.artifact.payload, input.maxExcerptBytes);
+    }
+    catch {
+        audit.reasonCodes = ['minimization-failed'];
+        return { allowed: false, audit };
+    }
+    let findings = [];
+    try {
+        const sanitized = sanitizePayload(candidate, policy.redaction ?? {});
+        candidate = sanitized.value;
+        findings = sanitized.findings;
+        audit.redaction = findings.length ? 'completed' : 'not-needed';
+        audit.redactionCount = findings.length;
+        audit.redactionClasses = [...new Set(findings.map((finding) => finding.class))].sort();
+    }
+    catch {
+        const override = input.redactionOverride;
+        if (!sink.allowRedactionOverride || !validOverride(override, input.artifact.id, sink.id, now.getTime())) {
+            audit.redaction = 'failed';
+            audit.reasonCodes = ['sanitization-failed'];
+            return { allowed: false, audit };
+        }
+        audit.redaction = 'override';
+        audit.decision = 'override';
+        audit.redactionOverrideId = override.id;
+        audit.redactionOverrideActor = override.actor;
+        audit.redactionOverrideReasonDigest = sha256(override.reason);
+    }
+    const gate = evaluatePublicationGate({
+        artifactId: input.artifact.id,
+        artifactKind: input.artifact.kind,
+        governance,
+        sink,
+        sourceRepository: input.sourceRepository,
+        approval: input.publicationApproval,
+        classes: resolveClassificationDefinitions(policy.classification),
+        now,
+    });
+    audit.publication = gate.audit;
+    audit.reasonCodes = gate.reasonCodes;
+    let summary = false;
+    const immutableSinkRequiresSummary = !sink.mutable && input.artifact.category !== 'sanitized-summary';
+    if (!gate.allowed || immutableSinkRequiresSummary) {
+        if (!gate.allowed && gate.decision !== 'summarize') {
+            audit.decision = 'deny';
+            return { allowed: false, audit };
+        }
+        candidate = createSanitizedSummary({
+            artifactId: input.artifact.id,
+            artifactKind: input.artifact.kind,
+            status: stableStatus(input.artifact.status),
+            omittedFields: candidate && typeof candidate === 'object' ? Object.keys(candidate).length : 1,
+            redactionClasses: audit.redactionClasses,
+        });
+        governance = resolveArtifactGovernance({
+            kind: 'SanitizedSummary',
+            category: 'sanitized-summary',
+            metadata: { classification: 'public', owner: governance.owner, handling: { allowedSinks: [sink.id], crossRepo: 'allow' } },
+            policy: policy.classification,
+        });
+        const summaryGate = evaluatePublicationGate({
+            artifactId: input.artifact.id,
+            artifactKind: 'SanitizedSummary',
+            governance,
+            sink,
+            sourceRepository: input.sourceRepository,
+            classes: resolveClassificationDefinitions(policy.classification),
+            now,
+        });
+        audit.publication = summaryGate.audit;
+        if (!summaryGate.allowed) {
+            audit.decision = 'deny';
+            audit.reasonCodes = ['sanitized-summary-denied', ...summaryGate.reasonCodes];
+            return { allowed: false, audit };
+        }
+        summary = true;
+    }
+    let lifecycle;
+    try {
+        lifecycle = createEvidenceLifecycle({
+            artifactId: input.artifact.id,
+            category: summary ? 'sanitized-summary' : input.artifact.category,
+            classification: governance.classification,
+            sink,
+            tier: summary ? 'durable' : tier,
+            rules: policy.retention,
+            requestedPolicyId: governance.handling.retentionPolicy,
+            rawCaptureReason: input.artifact.rawCaptureReason,
+            createdAt: now.toISOString(),
+        });
+    }
+    catch {
+        audit.decision = 'deny';
+        audit.reasonCodes = ['retention-policy-unsatisfied'];
+        return { allowed: false, audit };
+    }
+    audit.retentionPolicyId = lifecycle.policyId;
+    audit.dispositionDeadline = lifecycle.dispositionDeadline;
+    audit.decision = summary ? 'summary' : gate.decision === 'override' || audit.redaction === 'override' ? 'override' : 'allow';
+    return {
+        allowed: true,
+        prepared: {
+            payload: candidate,
+            governance: {
+                classification: governance.classification,
+                ...(governance.owner ? { owner: governance.owner } : {}),
+                handling: {
+                    allowedSinks: governance.handling.allowedSinks ?? [sink.id],
+                    crossRepo: governance.handling.crossRepo ?? 'approval-required',
+                    retentionPolicy: lifecycle.policyId,
+                },
+            },
+            lifecycle,
+            summary,
+        },
+        audit,
+    };
+}
+/** Call a sink writer only after the boundary returns publishable evidence. */
+export async function publishEvidence(input) {
+    const result = prepareEvidenceForSink(input);
+    if (result.allowed && result.prepared)
+        await input.writer(result.prepared);
+    return result;
+}
+//# sourceMappingURL=boundary.js.map

package/dist/src/governance/classification.js

@@ -0,0 +1,191 @@
+import { createHash, randomUUID } from 'node:crypto';
+export const BUILTIN_CLASSIFICATIONS = {
+    public: { rank: 0, description: 'Approved for unrestricted disclosure.' },
+    internal: { rank: 10, description: 'Routine non-public operational information.' },
+    confidential: { rank: 20, description: 'Sensitive business or operational information.' },
+    'restricted-infrastructure': { rank: 30, description: 'Topology, access path, recovery, or detailed infrastructure information.' },
+    'restricted-identity': { rank: 40, description: 'Named-user, identity-provider, authentication, or entitlement information.' },
+};
+export const SECURE_KIND_DEFAULTS = {
+    ITAsset: 'restricted-infrastructure',
+    ITService: 'restricted-infrastructure',
+    ITNetworkState: 'restricted-infrastructure',
+    OpsInventory: 'restricted-infrastructure',
+    OpsPlaybook: 'internal',
+    IncidentReport: 'confidential',
+    IdentityAudit: 'restricted-identity',
+    DREvidence: 'restricted-infrastructure',
+    RawAuditEvidence: 'restricted-infrastructure',
+};
+export const SECURE_CATEGORY_DEFAULTS = {
+    'raw-audit': 'restricted-infrastructure',
+    'identity-audit': 'restricted-identity',
+    'network-inventory': 'restricted-infrastructure',
+    'dr-evidence': 'restricted-infrastructure',
+    'sanitized-summary': 'internal',
+    generic: 'internal',
+};
+function stableId(value, label) {
+    if (!/^[a-z0-9][a-z0-9.-]{0,127}$/.test(value)) {
+        throw new Error(`${label} must be a lowercase stable identifier`);
+    }
+}
+export function resolveClassificationDefinitions(policy = {}) {
+    const classes = { ...BUILTIN_CLASSIFICATIONS };
+    for (const [id, definition] of Object.entries(policy.classes ?? {})) {
+        stableId(id, 'classification');
+        if (!Number.isSafeInteger(definition.rank) || definition.rank < 0 || definition.rank > 10_000) {
+            throw new Error(`classification '${id}' rank must be an integer from 0 through 10000`);
+        }
+        const builtin = BUILTIN_CLASSIFICATIONS[id];
+        if (builtin && builtin.rank !== definition.rank) {
+            throw new Error(`built-in classification '${id}' rank cannot be changed`);
+        }
+        classes[id] = { ...definition, ...(builtin ? { rank: builtin.rank } : {}) };
+    }
+    return classes;
+}
+function mergeHandling(parent, child) {
+    return {
+        ...(parent ?? {}),
+        ...(child ?? {}),
+        ...(child?.allowedSinks ? { allowedSinks: [...child.allowedSinks] } : parent?.allowedSinks ? { allowedSinks: [...parent.allowedSinks] } : {}),
+    };
+}
+/** Resolve explicit metadata, parent inheritance, secure kind/category defaults, then the policy default. */
+export function resolveArtifactGovernance(input) {
+    const policy = input.policy ?? {};
+    const definitions = resolveClassificationDefinitions(policy);
+    const explicitRequired = new Set(policy.requireExplicitForKinds ?? []);
+    if (explicitRequired.has(input.kind) && input.metadata?.classification === undefined) {
+        throw new Error(`artifact kind '${input.kind}' requires an explicit classification`);
+    }
+    const candidates = [
+        [input.metadata?.classification, 'artifact'],
+        [input.parent?.classification, 'parent'],
+        [policy.defaultsByKind?.[input.kind] ?? SECURE_KIND_DEFAULTS[input.kind], 'kind-default'],
+        [policy.defaultsByCategory?.[input.category] ?? SECURE_CATEGORY_DEFAULTS[input.category], 'category-default'],
+        [policy.defaultClassification ?? 'internal', 'policy-default'],
+    ];
+    const selected = candidates.find(([value]) => value !== undefined);
+    const classification = selected?.[0];
+    if (!classification || !definitions[classification]) {
+        throw new Error(`unknown or missing classification '${classification ?? '<missing>'}'`);
+    }
+    const handling = mergeHandling(input.parent?.handling, input.metadata?.handling);
+    for (const sink of handling.allowedSinks ?? [])
+        stableId(sink, 'allowed sink');
+    return {
+        classification,
+        classificationRank: definitions[classification].rank,
+        classificationSource: selected[1],
+        ...(input.metadata?.owner ?? input.parent?.owner ? { owner: input.metadata?.owner ?? input.parent?.owner } : {}),
+        handling,
+    };
+}
+function defaultSinkMaxRank(sink) {
+    switch (sink.visibility) {
+        case 'public': return BUILTIN_CLASSIFICATIONS.public.rank;
+        case 'private': return BUILTIN_CLASSIFICATIONS['restricted-infrastructure'].rank;
+        case 'restricted': return BUILTIN_CLASSIFICATIONS['restricted-identity'].rank;
+        case 'unknown': return null;
+    }
+}
+function approvalIsValid(approval, artifactId, sinkId, now) {
+    if (!approval)
+        return false;
+    if (!approval.id || !approval.actor || !approval.reason.trim())
+        return false;
+    if (approval.artifactId !== artifactId || approval.sinkId !== sinkId)
+        return false;
+    const approvedAt = Date.parse(approval.approvedAt);
+    if (!Number.isFinite(approvedAt) || approvedAt > now)
+        return false;
+    if (approval.expiresAt !== undefined) {
+        const expiresAt = Date.parse(approval.expiresAt);
+        if (!Number.isFinite(expiresAt) || expiresAt <= now || expiresAt <= approvedAt)
+            return false;
+    }
+    return true;
+}
+function reasonDigest(reason) {
+    return `sha256:${createHash('sha256').update(reason).digest('hex')}`;
+}
+function correlationDigest(value) {
+    return `sha256:${createHash('sha256').update(value).digest('hex')}`;
+}
+function safeArtifactKind(value) {
+    return /^[A-Za-z][A-Za-z0-9.-]{0,127}$/.test(value) ? value : correlationDigest(value);
+}
+/** Evaluate an artifact against a known sink before disclosure. Audit data never contains payload content. */
+export function evaluatePublicationGate(input) {
+    const occurredAt = (input.now ?? new Date()).toISOString();
+    const now = Date.parse(occurredAt);
+    const sinkId = input.sink?.id ?? 'unknown';
+    const reasons = [];
+    const sink = input.sink;
+    if (!sink || sink.visibility === 'unknown') {
+        reasons.push('unknown-sink-visibility');
+    }
+    else {
+        stableId(sink.id, 'sink');
+        if (input.governance.handling.allowedSinks && !input.governance.handling.allowedSinks.includes(sink.id)) {
+            reasons.push('sink-not-allowed');
+        }
+        const definitions = input.classes ?? resolveClassificationDefinitions();
+        const configuredMax = sink.maxClassification;
+        const maxRank = configuredMax === undefined
+            ? defaultSinkMaxRank(sink)
+            : definitions[configuredMax]?.rank;
+        if (maxRank === undefined || maxRank === null)
+            reasons.push('unknown-sink-classification-limit');
+        else if (input.governance.classificationRank > maxRank)
+            reasons.push('classification-exceeds-sink');
+        const crossRepo = Boolean(input.sourceRepository && sink.repository && input.sourceRepository !== sink.repository);
+        if (crossRepo && input.governance.handling.crossRepo === 'deny')
+            reasons.push('cross-repo-denied');
+        if (crossRepo && input.governance.handling.crossRepo === 'approval-required')
+            reasons.push('cross-repo-approval-required');
+    }
+    const validApproval = approvalIsValid(input.approval, input.artifactId, sinkId, now);
+    const overridableReasons = new Set(['classification-exceeds-sink', 'cross-repo-approval-required']);
+    const approvalCoversReasons = reasons.length > 0 && reasons.every((reason) => overridableReasons.has(reason));
+    let decision;
+    if (reasons.length === 0)
+        decision = 'allow';
+    else if (validApproval && approvalCoversReasons && sink && sink.visibility !== 'unknown')
+        decision = 'override';
+    else if (sink?.acceptsSanitizedSummary)
+        decision = 'summarize';
+    else
+        decision = 'deny';
+    const audit = {
+        schemaVersion: 'ops-publication-decision.aiwg.io/v1',
+        eventId: randomUUID(),
+        occurredAt,
+        artifactId: correlationDigest(input.artifactId),
+        artifactKind: safeArtifactKind(input.artifactKind),
+        classification: input.governance.classification,
+        sinkId,
+        decision,
+        reasonCodes: [...reasons].sort(),
+        ...(decision === 'override' && input.approval ? {
+            approvalId: input.approval.id,
+            approvalActor: input.approval.actor,
+            approvalReasonDigest: reasonDigest(input.approval.reason),
+        } : {}),
+    };
+    return { decision, allowed: decision === 'allow' || decision === 'override', reasonCodes: audit.reasonCodes, audit };
+}
+/** Produce a payload-free summary suitable for a second, separately gated publication attempt. */
+export function createSanitizedSummary(input) {
+    return {
+        schemaVersion: 'ops-sanitized-summary.aiwg.io/v1',
+        artifactFingerprint: `sha256:${createHash('sha256').update(input.artifactId).digest('hex')}`,
+        artifactKind: input.artifactKind,
+        ...(input.status ? { status: input.status } : {}),
+        omittedFields: input.omittedFields,
+        redactionClasses: [...new Set(input.redactionClasses)].sort(),
+    };
+}
+//# sourceMappingURL=classification.js.map

package/dist/src/governance/index.js

@@ -0,0 +1,5 @@
+export * from './redaction.js';
+export * from './classification.js';
+export * from './retention.js';
+export * from './boundary.js';
+//# sourceMappingURL=index.js.map