@timidan/rite 0.1.0

package/src/core/engine.js

@@ -0,0 +1,263 @@
+/**
+ * src/core/engine.js — Shared verification engine.
+ *
+ * verify(config, adapter, context) is the single function that owns
+ * validation, case execution, effect comparison, and report construction.
+ * CLI, MCP, and CI all call this function; none of them re-implement policy.
+ *
+ * No DOM globals. No React. No Vite-specific globals.
+ * Filesystem reads (adapter import, config load) are handled by callers;
+ * this module receives already-parsed config and a resolved adapter path.
+ */
+
+import { compareEffects } from '../instrument/effect-schema.js';
+
+export const SCHEMA_VERSION = 1;
+export const ENGINE_VERSION = '0.1.0';
+
+// ------------------------------------------------------------------ //
+// Config validation                                                    //
+// ------------------------------------------------------------------ //
+
+const VALID_DECISIONS = new Set(['allow', 'deny']);
+
+/**
+ * @typedef {{
+ *   version: number,
+ *   ruleId: string,
+ *   rule: string,
+ *   adapter: string,
+ *   paths: Array<{ entry: string, sink: string, source: string }>,
+ *   cases: Array<{
+ *     id: string,
+ *     path: string,
+ *     actor: string,
+ *     input: object,
+ *     expected: {
+ *       decision: 'allow' | 'deny',
+ *       effects: object[],
+ *       stateChanged: boolean,
+ *     }
+ *   }>
+ * }} RiteConfig
+ */
+
+/**
+ * Validate a parsed config object.
+ * Returns an array of error strings (empty = valid).
+ * @param {unknown} config
+ * @returns {string[]}
+ */
+export function validateConfig(config) {
+  const errs = [];
+  if (!config || typeof config !== 'object') {
+    errs.push('config must be an object');
+    return errs;
+  }
+  const c = /** @type {Record<string,unknown>} */ (config);
+
+  if (c.version !== 1) errs.push(`config.version must be 1 (got ${c.version})`);
+  if (typeof c.ruleId !== 'string' || !c.ruleId.trim())
+    errs.push('config.ruleId must be a non-empty string');
+  if (typeof c.rule !== 'string' || !c.rule.trim())
+    errs.push('config.rule must be a non-empty string');
+  if (typeof c.adapter !== 'string' || !c.adapter.trim())
+    errs.push('config.adapter must be a non-empty string');
+
+  // Paths
+  if (!Array.isArray(c.paths) || c.paths.length === 0)
+    errs.push('config.paths must be a non-empty array');
+  else {
+    const pathNames = new Set();
+    for (let i = 0; i < c.paths.length; i++) {
+      const p = /** @type {Record<string,unknown>} */ (c.paths[i]);
+      if (typeof p.entry !== 'string' || !p.entry.trim())
+        errs.push(`config.paths[${i}].entry must be a non-empty string`);
+      else {
+        if (pathNames.has(p.entry)) errs.push(`Duplicate path entry: ${p.entry}`);
+        pathNames.add(p.entry);
+      }
+      if (typeof p.sink !== 'string' || !p.sink.trim())
+        errs.push(`config.paths[${i}].sink must be a non-empty string`);
+      if (typeof p.source !== 'string' || !p.source.trim())
+        errs.push(`config.paths[${i}].source must be a non-empty string`);
+    }
+  }
+
+  // Cases
+  if (!Array.isArray(c.cases) || c.cases.length === 0)
+    errs.push('config.cases must be a non-empty array');
+  else {
+    const caseIds = new Set();
+    const configPaths = Array.isArray(c.paths)
+      ? new Set(c.paths.map(p => /** @type {Record<string,unknown>} */ (p).entry))
+      : new Set();
+
+    for (let i = 0; i < c.cases.length; i++) {
+      const cs = /** @type {Record<string,unknown>} */ (c.cases[i]);
+      if (typeof cs.id !== 'string' || !cs.id.trim())
+        errs.push(`config.cases[${i}].id must be a non-empty string`);
+      else {
+        if (caseIds.has(cs.id)) errs.push(`Duplicate case id: ${cs.id}`);
+        caseIds.add(cs.id);
+      }
+      if (typeof cs.path !== 'string' || !cs.path.trim())
+        errs.push(`config.cases[${i}].path must be a non-empty string`);
+      else if (!configPaths.has(cs.path))
+        errs.push(`config.cases[${i}].path "${cs.path}" not in config.paths`);
+      if (typeof cs.actor !== 'string' || !cs.actor.trim())
+        errs.push(`config.cases[${i}].actor must be a non-empty string`);
+      if (!cs.input || typeof cs.input !== 'object')
+        errs.push(`config.cases[${i}].input must be an object`);
+
+      const exp = /** @type {Record<string,unknown>} */ (cs.expected);
+      if (!exp || typeof exp !== 'object')
+        errs.push(`config.cases[${i}].expected must be an object`);
+      else {
+        if (!VALID_DECISIONS.has(/** @type {string} */ (exp.decision)))
+          errs.push(`config.cases[${i}].expected.decision must be 'allow'|'deny'`);
+        if (!Array.isArray(exp.effects))
+          errs.push(`config.cases[${i}].expected.effects must be an array`);
+        if (typeof exp.stateChanged !== 'boolean')
+          errs.push(`config.cases[${i}].expected.stateChanged must be a boolean`);
+      }
+    }
+  }
+
+  return errs;
+}
+
+// ------------------------------------------------------------------ //
+// Case execution                                                       //
+// ------------------------------------------------------------------ //
+
+/**
+ * @typedef {{
+ *   id: string,
+ *   path: string,
+ *   status: 'PASS'|'FAIL'|'ERROR',
+ *   expected: object,
+ *   observed: object,
+ *   failures: string[],
+ *   error: string | null,
+ * }} CaseResult
+ */
+
+/**
+ * Run one case through the adapter.
+ * The adapter is responsible for all isolation and fixture setup.
+ * @param {object} caseSpec
+ * @param {object} adapter  — { runCase }
+ * @returns {Promise<CaseResult>}
+ */
+async function runOneCase(caseSpec, adapter) {
+  const result = {
+    id: caseSpec.id,
+    path: caseSpec.path,
+    status: /** @type {'PASS'|'FAIL'|'ERROR'} */ ('PASS'),
+    expected: caseSpec.expected,
+    observed: null,
+    failures: [],
+    error: null,
+  };
+
+  let observed;
+  try {
+    observed = await adapter.runCase(caseSpec);
+  } catch (err) {
+    result.status = 'ERROR';
+    result.error = err instanceof Error ? `${err.message}\n${err.stack}` : String(err);
+    return result;
+  }
+
+  if (!observed || typeof observed !== 'object') {
+    result.status = 'ERROR';
+    result.error = `Adapter returned non-object: ${JSON.stringify(observed)}`;
+    return result;
+  }
+
+  result.observed = observed;
+
+  const exp = caseSpec.expected;
+  const failures = [];
+
+  // 1. Decision
+  const observedDecision = observed.decision;
+  if (observedDecision !== exp.decision)
+    failures.push(`decision: expected "${exp.decision}"; observed "${observedDecision}"`);
+
+  // 2–4. Effects: count + structural match + schema (unified via compareEffects)
+  const observedEffects = Array.isArray(observed.effects) ? observed.effects : [];
+  failures.push(...compareEffects(observedEffects, exp.effects, caseSpec.effectSchema));
+
+  // 5. State change
+  const observedStateChanged = observed.stateChanged;
+  if (observedStateChanged !== exp.stateChanged)
+    failures.push(`stateChanged: expected ${exp.stateChanged}; observed ${observedStateChanged}`);
+
+  result.failures = failures;
+  result.status = failures.length > 0 ? 'FAIL' : 'PASS';
+  return result;
+}
+
+// ------------------------------------------------------------------ //
+// Main verify function                                                 //
+// ------------------------------------------------------------------ //
+
+/**
+ * @typedef {{
+ *   schemaVersion: number,
+ *   engineVersion: string,
+ *   ruleId: string,
+ *   rule: string,
+ *   configuredPaths: Array<{ entry: string, sink: string, source: string }>,
+ *   generatedAt: string,
+ *   status: 'PASS'|'FAIL'|'ERROR',
+ *   results: CaseResult[],
+ *   error: string | null,
+ * }} VerifyReport
+ */
+
+/**
+ * Run the full verification against a loaded adapter.
+ * Returns a VerifyReport regardless of pass/fail.
+ *
+ * @param {RiteConfig} config
+ * @param {{ runCase: (caseSpec: object) => Promise<object> }} adapter
+ * @param {{ configPath?: string }} [context]
+ * @returns {Promise<VerifyReport>}
+ */
+export async function verify(config, adapter, context = {}) {
+  const report = {
+    schemaVersion: SCHEMA_VERSION,
+    engineVersion: ENGINE_VERSION,
+    ruleId: config.ruleId,
+    rule: config.rule,
+    configuredPaths: config.paths,
+    generatedAt: new Date().toISOString(),
+    status: /** @type {'PASS'|'FAIL'|'ERROR'} */ ('PASS'),
+    results: [],
+    error: null,
+  };
+
+  if (!config.cases?.length) {
+    report.status = 'ERROR';
+    report.error = 'No cases configured.';
+    return report;
+  }
+
+  for (const caseSpec of config.cases) {
+    const result = await runOneCase(caseSpec, adapter);
+    report.results.push(result);
+  }
+
+  // Aggregate: ERROR > FAIL > PASS
+  let status = 'PASS';
+  for (const r of report.results) {
+    if (r.status === 'ERROR') { status = 'ERROR'; break; }
+    if (r.status === 'FAIL') status = 'FAIL';
+  }
+  report.status = /** @type {'PASS'|'FAIL'|'ERROR'} */ (status);
+
+  return report;
+}

package/src/core/loader.js

@@ -0,0 +1,72 @@
+/**
+ * src/core/loader.js — Shared adapter loader.
+ *
+ * Resolves, bounds-checks, and imports a Rite adapter from a config-relative
+ * path. Used by the CLI, MCP server, and GitHub server — none of them
+ * re-implement path validation or the pathToFileURL import pattern.
+ *
+ * No DOM globals. No React. Pure Node.js (fs + url + path).
+ */
+
+import { existsSync } from 'node:fs';
+import { resolve, relative, isAbsolute, dirname } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+/**
+ * @typedef {{
+ *   ok: true,
+ *   adapter: { runCase: (caseSpec: object) => Promise<object> },
+ *   adapterPath: string,
+ * } | {
+ *   ok: false,
+ *   error: string,
+ * }} LoadResult
+ */
+
+/**
+ * Load a Rite adapter from a path relative to the config file's directory.
+ *
+ * Validates:
+ *   - adapterRel does not escape the configDir (no path traversal)
+ *   - The resolved file exists
+ *   - The loaded module exports a runCase() function
+ *
+ * @param {string} configDir   — absolute directory containing rite.config.json
+ * @param {string} adapterRel  — config.adapter value (relative path)
+ * @returns {Promise<LoadResult>}
+ */
+export async function loadAdapter(configDir, adapterRel) {
+  // Bounds check — adapter must stay inside config dir
+  const adapterPath = resolve(configDir, adapterRel);
+  const rel = relative(configDir, adapterPath);
+  if (isAbsolute(rel) || rel.startsWith('..')) {
+    return { ok: false, error: `Adapter path escapes the config directory: ${adapterRel}` };
+  }
+
+  if (!existsSync(adapterPath)) {
+    return { ok: false, error: `Adapter not found: ${adapterPath}` };
+  }
+
+  let adapter;
+  try {
+    adapter = await import(pathToFileURL(adapterPath).href);
+  } catch (e) {
+    return { ok: false, error: `Failed to load adapter: ${e.message}` };
+  }
+
+  if (typeof adapter.runCase !== 'function') {
+    return { ok: false, error: `Adapter must export runCase() — not found in ${adapterPath}` };
+  }
+
+  return { ok: true, adapter, adapterPath };
+}
+
+/**
+ * Convenience: load adapter from a fully-parsed config object + config file path.
+ * @param {object} config  — validated RiteConfig
+ * @param {string} configPath  — absolute path to the config file
+ * @returns {Promise<LoadResult>}
+ */
+export async function loadAdapterFromConfig(config, configPath) {
+  return loadAdapter(dirname(configPath), config.adapter);
+}

package/src/core/sarif.js

@@ -0,0 +1,126 @@
+/**
+ * src/core/sarif.js — SARIF 2.1.0 output formatter.
+ *
+ * Converts a Rite VerifyReport into a SARIF document suitable for upload
+ * to GitHub Code Scanning via `actions/upload-sarif`.
+ *
+ * Spec: https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html
+ * GitHub upload: https://docs.github.com/en/code-security/code-scanning/integrating-with-code-scanning/uploading-a-sarif-file-to-github
+ *
+ * Usage:
+ *   rite verify --config rite.config.json --sarif results.sarif
+ *
+ * SARIF level mapping:
+ *   FAIL  → error   (blocks merge when uploaded as a required check)
+ *   ERROR → error
+ *   PASS  → note    (informational, does not block)
+ */
+
+import { ENGINE_VERSION } from './engine.js';
+
+const SARIF_SCHEMA = 'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json';
+const SARIF_VERSION = '2.1.0';
+
+/**
+ * @typedef {import('./engine.js').VerifyReport} VerifyReport
+ * @typedef {import('./engine.js').CaseResult} CaseResult
+ */
+
+/**
+ * Map a case status to a SARIF notification level.
+ * @param {'PASS'|'FAIL'|'ERROR'} status
+ * @returns {'error'|'warning'|'note'}
+ */
+function toLevel(status) {
+  if (status === 'PASS') return 'note';
+  return 'error';
+}
+
+/**
+ * Build a SARIF result for one case.
+ * @param {CaseResult} r
+ * @param {string} ruleId
+ * @returns {object}
+ */
+function buildResult(r, ruleId) {
+  const level = toLevel(r.status);
+  const message = r.status === 'PASS'
+    ? `${r.id}: authorization check passed on path "${r.path}".`
+    : r.status === 'ERROR'
+      ? `${r.id}: case execution error on path "${r.path}": ${r.error?.split('\n')[0]}`
+      : `${r.id}: authorization check FAILED on path "${r.path}". ${r.failures.join(' | ')}`;
+
+  return {
+    ruleId,
+    level,
+    message: { text: message },
+    locations: [
+      {
+        physicalLocation: {
+          artifactLocation: {
+            uri: r.observed?.sourceFile ?? 'src/refunds.js',
+            uriBaseId: '%SRCROOT%',
+          },
+        },
+        logicalLocations: [
+          { name: r.path, kind: 'function' },
+        ],
+      },
+    ],
+    partialFingerprints: {
+      'rite/caseId': r.id,
+      'rite/path': r.path,
+    },
+  };
+}
+
+/**
+ * Convert a VerifyReport to a SARIF 2.1.0 document.
+ * @param {VerifyReport} report
+ * @returns {object} — serialize with JSON.stringify
+ */
+export function toSarif(report) {
+  const ruleId = report.ruleId ?? 'rite-authorization';
+
+  const rules = [
+    {
+      id: ruleId,
+      name: 'RiteAuthorizationCheck',
+      shortDescription: { text: report.rule ?? 'Authorization rule check' },
+      fullDescription: {
+        text: `Rite checks that the written authorization rule holds across all configured entry paths. Rule: ${report.rule}`,
+      },
+      defaultConfiguration: { level: 'error' },
+      helpUri: 'https://github.com/timidan/rite',
+      properties: {
+        tags: ['security', 'authorization', 'access-control'],
+        precision: 'high',
+        'security-severity': '8.0',  // CVSS-style; IDOR is typically 7-9
+      },
+    },
+  ];
+
+  const results = (report.results ?? []).map(r => buildResult(r, ruleId));
+
+  return {
+    $schema: SARIF_SCHEMA,
+    version: SARIF_VERSION,
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: 'Rite',
+            version: ENGINE_VERSION,
+            informationUri: 'https://github.com/timidan/rite',
+            rules,
+          },
+        },
+        results,
+        automationDetails: {
+          id: `rite/${report.ruleId ?? 'check'}/${report.generatedAt}`,
+        },
+        columnKind: 'utf16CodeUnits',
+      },
+    ],
+  };
+}

package/src/github/app.js

@@ -0,0 +1,134 @@
+/**
+ * src/github/app.js — GitHub App OAuth and repository helpers.
+ *
+ * Handles:
+ *   GET  /github/login          — Start OAuth flow
+ *   GET  /github/callback       — OAuth callback, set session
+ *   GET  /github/installations  — List repos the user authorised
+ *   GET  /github/runs           — List recent Rite workflow runs for a repo
+ *   GET  /github/report         — Fetch and validate a run's Rite report artifact
+ *   POST /github/logout         — Clear session
+ *
+ * Security model:
+ *   - User access token (user-to-server) for identity and session.
+ *   - Short-lived installation token (server-to-server) for artifact reads.
+ *   - App private key and session secret stay server-side — never
+ *     in browser assets, GitHub Actions logs, or Rite report JSON.
+ *   - Repository owner/name is NEVER trusted from a browser query parameter;
+ *     only repos in the user's authenticated installation list are served.
+ *   - Report schema and embedded SHA are validated against GitHub run metadata
+ *     before display. Mismatch → explicit error state, never PASS.
+ *
+ * Environment variables required:
+ *   GITHUB_APP_ID          — numeric App ID from GitHub App settings
+ *   GITHUB_APP_CLIENT_ID   — OAuth client ID
+ *   GITHUB_APP_CLIENT_SECRET
+ *   GITHUB_APP_PRIVATE_KEY or GITHUB_APP_PRIVATE_KEY_FILE
+ *   RITE_SESSION_SECRET    — Random 32+ char string for session signing
+ *   RITE_PUBLIC_URL        — e.g. https://rite.timidan.xyz (for OAuth callback)
+ *
+ * Register the App and set the environment variables above before starting
+ * the server. See docs/github-app-setup.md.
+ *
+ * GitHub App docs: https://docs.github.com/en/apps
+ */
+
+/**
+ * Check required environment variables.
+ * @returns {{ ok: boolean, missing: string[] }}
+ */
+export function checkEnv() {
+  const required = [
+    'GITHUB_APP_ID',
+    'GITHUB_APP_CLIENT_ID',
+    'GITHUB_APP_CLIENT_SECRET',
+    'RITE_SESSION_SECRET',
+    'RITE_PUBLIC_URL',
+  ];
+  const missing = required.filter(k => !process.env[k]);
+  if (!process.env.GITHUB_APP_PRIVATE_KEY && !process.env.GITHUB_APP_PRIVATE_KEY_FILE) {
+    missing.push('GITHUB_APP_PRIVATE_KEY or GITHUB_APP_PRIVATE_KEY_FILE');
+  }
+  return { ok: missing.length === 0, missing };
+}
+
+/**
+ * Build the GitHub App OAuth authorization URL.
+ * @param {string} state — CSRF token, stored in session
+ * @returns {string}
+ */
+export function buildAuthUrl(state) {
+  const clientId = process.env.GITHUB_APP_CLIENT_ID ?? '';
+  const redirectUri = encodeURIComponent(`${process.env.RITE_PUBLIC_URL}/github/callback`);
+  return `https://github.com/login/oauth/authorize?client_id=${clientId}&redirect_uri=${redirectUri}&state=${state}`;
+}
+
+/**
+ * Start installation through Rite so GitHub's OAuth-on-install callback carries
+ * the same CSRF state stored in the user's session.
+ */
+export function buildInstallUrl(state) {
+  return `https://github.com/apps/rite-authorization-check/installations/new?state=${encodeURIComponent(state)}`;
+}
+
+/**
+ * Exchange a GitHub OAuth code for a user access token.
+ * @param {string} code
+ * @returns {Promise<{ token: string, tokenType: string }>}
+ */
+export async function exchangeCode(code) {
+  const resp = await fetch('https://github.com/login/oauth/access_token', {
+    method: 'POST',
+    headers: { Accept: 'application/json', 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      client_id: process.env.GITHUB_APP_CLIENT_ID,
+      client_secret: process.env.GITHUB_APP_CLIENT_SECRET,
+      code,
+    }),
+  });
+  if (!resp.ok) throw new Error(`GitHub token exchange failed: ${resp.status}`);
+  const data = await resp.json();
+  if (data.error) throw new Error(`GitHub OAuth error: ${data.error_description ?? data.error}`);
+  return { token: data.access_token, tokenType: data.token_type };
+}
+
+/**
+ * List repositories accessible to the authenticated user via their installations.
+ * Uses the user access token — only repos the user authorised appear here.
+ * @param {string} userToken — user access token
+ * @returns {Promise<Array<{ id: number, fullName: string, installationId: number }>>}
+ */
+export async function listAuthorizedRepos(userToken) {
+  // 1. Get installations this user has authorised
+  const instResp = await fetch('https://api.github.com/user/installations', {
+    headers: {
+      Authorization: `Bearer ${userToken}`,
+      Accept: 'application/vnd.github+json',
+      'X-GitHub-Api-Version': '2022-11-28',
+    },
+  });
+  if (!instResp.ok) throw new Error(`GitHub installations list failed: ${instResp.status}`);
+  const instData = await instResp.json();
+  const installations = instData.installations ?? [];
+
+  // 2. For each installation, list repos — filter to Rite-relevant ones
+  const allRepos = [];
+  for (const inst of installations) {
+    const repoResp = await fetch(
+      `https://api.github.com/user/installations/${inst.id}/repositories`,
+      {
+        headers: {
+          Authorization: `Bearer ${userToken}`,
+          Accept: 'application/vnd.github+json',
+          'X-GitHub-Api-Version': '2022-11-28',
+        },
+      }
+    );
+    if (!repoResp.ok) continue;
+    const repoData = await repoResp.json();
+    for (const repo of repoData.repositories ?? []) {
+      allRepos.push({ id: repo.id, fullName: repo.full_name, installationId: inst.id });
+    }
+  }
+  return allRepos;
+}