@codapult/guard 0.10.0 → 0.11.0

package/dist/core/history/runs.js

@@ -46,6 +46,8 @@ function isGuardRunManifest(value) {
             Number.isFinite(Date.parse(receipt.generatedAt)) &&
             (receipt.outcome === 'pass' ||
                 receipt.outcome === 'fail' ||
+                receipt.outcome === 'incomplete' ||
+                receipt.outcome === 'policy-weakened' ||
                 receipt.outcome === 'warning' ||
                 receipt.outcome === 'needs-review' ||
                 receipt.outcome === 'not-configured') &&
@@ -65,7 +67,96 @@ function isGuardRunManifest(value) {
             (receipt.subject.baseRef === undefined || typeof receipt.subject.baseRef === 'string') &&
             (receipt.subject.baseCommit === undefined ||
                 typeof receipt.subject.baseCommit === 'string') &&
+            (receipt.subject.headSha === undefined || /^[a-f0-9]{40}$/i.test(receipt.subject.headSha)) &&
+            (receipt.subject.baseSha === undefined || /^[a-f0-9]{40}$/i.test(receipt.subject.baseSha)) &&
+            (receipt.subject.mergeSha === undefined ||
+                /^[a-f0-9]{40}$/i.test(receipt.subject.mergeSha)) &&
+            (receipt.subject.githubEvent === undefined ||
+                typeof receipt.subject.githubEvent === 'string') &&
             (receipt.policy === undefined || isGuardRunPolicy(receipt.policy)) &&
+            (receipt.verificationScope === undefined ||
+                (receipt.verificationScope !== null &&
+                    typeof receipt.verificationScope === 'object' &&
+                    receipt.verificationScope.algorithm === 'sha256' &&
+                    /^[a-f0-9]{64}$/.test(receipt.verificationScope.fingerprint) &&
+                    typeof receipt.verificationScope.complete === 'boolean' &&
+                    typeof receipt.verificationScope.stable === 'boolean' &&
+                    Array.isArray(receipt.verificationScope.files) &&
+                    receipt.verificationScope.files.every((file) => file !== null &&
+                        typeof file === 'object' &&
+                        typeof file.path === 'string' &&
+                        (file.status === 'present' ||
+                            file.status === 'deleted' ||
+                            file.status === 'unavailable') &&
+                        (file.status === 'unavailable'
+                            ? file.sha256 === undefined
+                            : typeof file.sha256 === 'string' && /^[a-f0-9]{64}$/.test(file.sha256))))) &&
+            (receipt.policySurface === undefined ||
+                (receipt.policySurface !== null &&
+                    typeof receipt.policySurface === 'object' &&
+                    Array.isArray(receipt.policySurface.protectedPaths) &&
+                    receipt.policySurface.protectedPaths.every((path) => typeof path === 'string') &&
+                    Array.isArray(receipt.policySurface.changedPaths) &&
+                    receipt.policySurface.changedPaths.every((path) => typeof path === 'string') &&
+                    (receipt.policySurface.changes === undefined ||
+                        (Array.isArray(receipt.policySurface.changes) &&
+                            receipt.policySurface.changes.every((change) => change !== null &&
+                                typeof change === 'object' &&
+                                typeof change.path === 'string' &&
+                                typeof change.pattern === 'string' &&
+                                typeof change.kind === 'string' &&
+                                (change.severity === 'warning' || change.severity === 'error')))) &&
+                    Array.isArray(receipt.policySurface.suppressionMarkers) &&
+                    receipt.policySurface.suppressionMarkers.every((marker) => typeof marker === 'string') &&
+                    typeof receipt.policySurface.workflowChanged === 'boolean' &&
+                    typeof receipt.policySurface.complete === 'boolean')) &&
+            (receipt.ciIntegrity === undefined ||
+                (receipt.ciIntegrity !== null &&
+                    typeof receipt.ciIntegrity === 'object' &&
+                    (receipt.ciIntegrity.status === 'ok' ||
+                        receipt.ciIntegrity.status === 'policy-weakened' ||
+                        receipt.ciIntegrity.status === 'incomplete') &&
+                    Array.isArray(receipt.ciIntegrity.workflows) &&
+                    receipt.ciIntegrity.workflows.every((workflow) => workflow !== null &&
+                        typeof workflow === 'object' &&
+                        typeof workflow.path === 'string' &&
+                        typeof workflow.job === 'string' &&
+                        (workflow.digest === undefined || typeof workflow.digest === 'string') &&
+                        (workflow.baseDigest === undefined || typeof workflow.baseDigest === 'string') &&
+                        Array.isArray(workflow.actions) &&
+                        workflow.actions.every((action) => typeof action === 'string') &&
+                        (workflow.baseActions === undefined ||
+                            (Array.isArray(workflow.baseActions) &&
+                                workflow.baseActions.every((action) => typeof action === 'string'))) &&
+                        (workflow.actionChanges === undefined ||
+                            (Array.isArray(workflow.actionChanges) &&
+                                workflow.actionChanges.every((change) => change !== null &&
+                                    typeof change === 'object' &&
+                                    typeof change.name === 'string' &&
+                                    Array.isArray(change.base) &&
+                                    change.base.every((action) => typeof action === 'string') &&
+                                    Array.isArray(change.current) &&
+                                    change.current.every((action) => typeof action === 'string')))) &&
+                        (workflow.status === 'ok' ||
+                            workflow.status === 'policy-weakened' ||
+                            workflow.status === 'incomplete') &&
+                        Array.isArray(workflow.issues) &&
+                        workflow.issues.every((issue) => issue !== null &&
+                            typeof issue === 'object' &&
+                            typeof issue.code === 'string' &&
+                            typeof issue.message === 'string')))) &&
+            (receipt.requiredStages === undefined ||
+                (Array.isArray(receipt.requiredStages) &&
+                    receipt.requiredStages.every((stage) => typeof stage === 'string'))) &&
+            (receipt.incompleteStages === undefined ||
+                (Array.isArray(receipt.incompleteStages) &&
+                    receipt.incompleteStages.every((stage) => typeof stage === 'string'))) &&
+            (receipt.effectiveInvocation === undefined ||
+                (receipt.effectiveInvocation !== null &&
+                    typeof receipt.effectiveInvocation === 'object' &&
+                    typeof receipt.effectiveInvocation.command === 'string' &&
+                    Array.isArray(receipt.effectiveInvocation.args) &&
+                    receipt.effectiveInvocation.args.every((argument) => typeof argument === 'string'))) &&
             receipt.stages !== null &&
             typeof receipt.stages === 'object' &&
             !Array.isArray(receipt.stages) &&
@@ -80,6 +171,14 @@ function isGuardRunManifest(value) {
                 return ((candidate.status === 'passed' ||
                     candidate.status === 'failed' ||
                     candidate.status === 'not-configured') &&
+                    (candidate.command === undefined || typeof candidate.command === 'string') &&
+                    (candidate.args === undefined ||
+                        (Array.isArray(candidate.args) &&
+                            candidate.args.every((argument) => typeof argument === 'string'))) &&
+                    (candidate.execution === undefined ||
+                        candidate.execution === 'attempted' ||
+                        candidate.execution === 'rejected' ||
+                        candidate.execution === 'not-configured') &&
                     Number.isInteger(candidate.exitCode) &&
                     typeof candidate.durationMs === 'number' &&
                     Number.isFinite(candidate.durationMs) &&
@@ -144,6 +243,8 @@ function isGuardRunManifest(value) {
         manifest.durationMs >= 0 &&
         (manifest.outcome === 'pass' ||
             manifest.outcome === 'fail' ||
+            manifest.outcome === 'incomplete' ||
+            manifest.outcome === 'policy-weakened' ||
             manifest.outcome === 'warning' ||
             manifest.outcome === 'needs-review' ||
             manifest.outcome === 'not-configured') &&
@@ -257,6 +358,8 @@ export function summarizeGuardRuns(root, limit = 100) {
         total,
         passed: runs.filter((run) => run.outcome === 'pass').length,
         failed: runs.filter((run) => run.outcome === 'fail').length,
+        incomplete: runs.filter((run) => run.outcome === 'incomplete').length,
+        policyWeakened: runs.filter((run) => run.outcome === 'policy-weakened').length,
         warnings: runs.filter((run) => run.outcome === 'warning').length,
         averageDurationMs: total === 0 ? 0 : Math.round(runs.reduce((sum, run) => sum + run.durationMs, 0) / total),
         ...(total > 0 ? { last: runs[0] } : {}),
@@ -287,6 +390,12 @@ export function finishGuardRun(root, context, outcome, gate, command = 'verify',
             workingTreeDirty: receipt?.subject.workingTreeDirty ?? false,
         },
         ...(policy ? { policy } : {}),
+        ...(receipt?.verificationScope ? { verificationScope: receipt.verificationScope } : {}),
+        ...(receipt?.policySurface ? { policySurface: receipt.policySurface } : {}),
+        ...(receipt?.ciIntegrity ? { ciIntegrity: receipt.ciIntegrity } : {}),
+        requiredStages: receipt?.requiredStages ?? [],
+        incompleteStages: receipt?.incompleteStages ?? [],
+        ...(receipt?.effectiveInvocation ? { effectiveInvocation: receipt.effectiveInvocation } : {}),
         stages: receipt?.stages ?? {},
         checks: receipt?.checks ?? {},
         findings: receipt?.findings ?? {

package/dist/core/output/attestation.d.ts

@@ -0,0 +1,17 @@
+import type { GuardVerificationReceipt } from '../history/runs.js';
+export declare const GUARD_VERIFICATION_PREDICATE_TYPE = "https://codapult.dev/attestations/guard-verification/v1";
+export interface GuardVerificationInTotoStatement {
+    _type: 'https://in-toto.io/Statement/v1';
+    subject: {
+        name: 'codapult-guard:verification-context';
+        digest: {
+            sha256: string;
+        };
+    }[];
+    predicateType: typeof GUARD_VERIFICATION_PREDICATE_TYPE;
+    predicate: {
+        receipt: GuardVerificationReceipt;
+    };
+}
+/** Bind a successful Guard receipt to the exact policy and file scope it verified. */
+export declare function guardReceiptToInToto(receipt: GuardVerificationReceipt): GuardVerificationInTotoStatement;

package/dist/core/output/attestation.js

@@ -0,0 +1,22 @@
+export const GUARD_VERIFICATION_PREDICATE_TYPE = 'https://codapult.dev/attestations/guard-verification/v1';
+/** Bind a successful Guard receipt to the exact policy and file scope it verified. */
+export function guardReceiptToInToto(receipt) {
+    const scope = receipt.verificationScope;
+    if (receipt.outcome !== 'pass' ||
+        !scope?.complete ||
+        !scope.stable ||
+        !/^[a-f0-9]{64}$/.test(scope.fingerprint)) {
+        throw new Error('Only a passing receipt with a complete, stable verification scope can be attested.');
+    }
+    return {
+        _type: 'https://in-toto.io/Statement/v1',
+        subject: [
+            {
+                name: 'codapult-guard:verification-context',
+                digest: { sha256: scope.fingerprint },
+            },
+        ],
+        predicateType: GUARD_VERIFICATION_PREDICATE_TYPE,
+        predicate: { receipt },
+    };
+}

package/dist/core/policy/schemas.d.ts

@@ -226,6 +226,44 @@ export declare const guardConfigSchema: z.ZodObject<{
         warningDays: z.ZodNumber;
         maxDays: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
+    protectedPaths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    policySurface: z.ZodOptional<z.ZodObject<{
+        paths: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            pattern: z.ZodString;
+            kind: z.ZodEnum<{
+                "ci-workflow": "ci-workflow";
+                custom: "custom";
+                "dependency-input": "dependency-input";
+                "guard-policy": "guard-policy";
+                "ignore-config": "ignore-config";
+                ownership: "ownership";
+                "suppression-source": "suppression-source";
+                "tool-config": "tool-config";
+            }>;
+            severity: z.ZodDefault<z.ZodEnum<{
+                error: "error";
+                warning: "warning";
+            }>>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>;
+    githubActions: z.ZodOptional<z.ZodObject<{
+        workflows: z.ZodArray<z.ZodObject<{
+            path: z.ZodString;
+            job: z.ZodString;
+            requiredRunIncludes: z.ZodArray<z.ZodString>;
+            requiredNeeds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            requirePullRequest: z.ZodDefault<z.ZodBoolean>;
+            requireUnfilteredPullRequest: z.ZodDefault<z.ZodBoolean>;
+            requireUnconditionalJob: z.ZodDefault<z.ZodBoolean>;
+            requireFullShaActions: z.ZodDefault<z.ZodBoolean>;
+            disallowContinueOnError: z.ZodDefault<z.ZodBoolean>;
+            maxPermissions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<{
+                none: "none";
+                read: "read";
+                write: "write";
+            }>>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export declare const guardContractsFileSchema: z.ZodObject<{
     version: z.ZodLiteral<1>;
@@ -408,5 +446,14 @@ export declare const guardAgentConfigSchema: z.ZodObject<{
             test: "test";
             typecheck: "typecheck";
         }>>;
+        requiredStages: z.ZodDefault<z.ZodArray<z.ZodEnum<{
+            adapters: "adapters";
+            "architecture-policy": "architecture-policy";
+            "ci-integrity": "ci-integrity";
+            "policy-surface": "policy-surface";
+            "project-checks": "project-checks";
+            runtime: "runtime";
+            "verification-scope": "verification-scope";
+        }>>>;
     }, z.core.$strip>;
 }, z.core.$strip>;

package/dist/core/policy/schemas.js

@@ -89,6 +89,61 @@ export const guardConfigSchema = z.object({
         path: ['maxDays'],
     })
         .optional(),
+    protectedPaths: z
+        .array(z
+        .string()
+        .trim()
+        .min(1)
+        .refine((path) => !path.startsWith('/') && !path.includes('\\') && !path.split('/').includes('..'), 'protectedPaths entries must be repository-relative paths without parent traversal'))
+        .optional(),
+    policySurface: z
+        .object({
+        paths: z
+            .array(z.object({
+            pattern: z
+                .string()
+                .trim()
+                .min(1)
+                .refine((path) => !path.startsWith('/') && !path.includes('\\') && !path.split('/').includes('..'), 'policySurface paths must be repository-relative without parent traversal'),
+            kind: z.enum([
+                'ci-workflow',
+                'guard-policy',
+                'ownership',
+                'dependency-input',
+                'tool-config',
+                'ignore-config',
+                'suppression-source',
+                'custom',
+            ]),
+            severity: z.enum(['warning', 'error']).default('error'),
+        }))
+            .default([]),
+    })
+        .optional(),
+    githubActions: z
+        .object({
+        workflows: z
+            .array(z.object({
+            path: z
+                .string()
+                .trim()
+                .min(1)
+                .refine((path) => !path.startsWith('/') && !path.includes('\\') && !path.split('/').includes('..'), 'GitHub Actions workflow paths must be repository-relative without parent traversal'),
+            job: z.string().trim().min(1),
+            requiredRunIncludes: z.array(z.string().trim().min(1)).min(1),
+            requiredNeeds: z.array(z.string().trim().min(1)).optional(),
+            requirePullRequest: z.boolean().default(true),
+            requireUnfilteredPullRequest: z.boolean().default(true),
+            requireUnconditionalJob: z.boolean().default(true),
+            requireFullShaActions: z.boolean().default(true),
+            disallowContinueOnError: z.boolean().default(true),
+            maxPermissions: z
+                .record(z.string().trim().min(1), z.enum(['none', 'read', 'write']))
+                .optional(),
+        }))
+            .min(1),
+    })
+        .optional(),
 });
 export const guardContractsFileSchema = z.object({
     version: z.literal(1),
@@ -167,5 +222,17 @@ export const guardAgentConfigSchema = z.object({
         maxIterations: z.number().int().min(1).max(10),
         projectChecks: z.boolean(),
         checks: z.array(z.enum(['lint', 'typecheck', 'test', 'build'])),
+        requiredStages: z
+            .array(z.enum([
+            'runtime',
+            'project-checks',
+            'adapters',
+            'architecture-policy',
+            'policy-surface',
+            'ci-integrity',
+            'verification-scope',
+        ]))
+            .min(1)
+            .default(['architecture-policy']),
     }),
 });

package/dist/core/verification/github-actions.d.ts

@@ -0,0 +1,25 @@
+import type { GuardGitHubActionsPolicy } from '../guard.js';
+export interface GuardCiIntegrityIssue {
+    code: 'workflow-unreadable' | 'workflow-invalid' | 'pull-request-trigger-missing' | 'pull-request-filtered' | 'pull-request-target-present' | 'job-missing' | 'job-conditional' | 'command-missing' | 'step-conditional' | 'continue-on-error' | 'dependency-missing' | 'dependency-conditional' | 'dependency-continue-on-error' | 'action-not-sha-pinned' | 'action-reference-changed' | 'base-workflow-unavailable' | 'permission-expansion';
+    message: string;
+}
+export interface GuardCiIntegrityWorkflowResult {
+    path: string;
+    job: string;
+    digest?: string | undefined;
+    baseDigest?: string | undefined;
+    actions: string[];
+    baseActions?: string[] | undefined;
+    actionChanges?: {
+        name: string;
+        base: string[];
+        current: string[];
+    }[] | undefined;
+    status: 'ok' | 'policy-weakened' | 'incomplete';
+    issues: GuardCiIntegrityIssue[];
+}
+export interface GuardCiIntegrityResult {
+    status: 'ok' | 'policy-weakened' | 'incomplete';
+    workflows: GuardCiIntegrityWorkflowResult[];
+}
+export declare function auditGitHubActions(root: string, policy: GuardGitHubActionsPolicy | undefined, baseRef?: string): GuardCiIntegrityResult | undefined;