graphlin 0.1.3 → 0.2.1

package/runtime/daemon/extension-api.mjs

@@ -0,0 +1,203 @@
+import {
+  createFrameDocument, getExtensionDataProjection, validateGrant, extensionId,
+  id, digest, integer, exact, uniqueStrings, jsonBytes, EXTENSION_LIMITS,
+} from '../extensions/index.mjs';
+import { safeText } from '../core/privacy.mjs';
+
+const PREFIX = '/api/extensions';
+const HTTP_ERROR = Symbol('extension_http_error');
+const fail = (status, code) => { throw Object.assign(new Error(code), { status, code, [HTTP_ERROR]: true }); };
+const sameGrant = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+
+function reply(res, status, value) {
+  const body = jsonBytes(value, EXTENSION_LIMITS.projectionBytes);
+  res.writeHead(status, { 'Content-Type': 'application/json; charset=utf-8' });
+  res.end(body);
+}
+async function bodyJSON(req) {
+  if (!/^application\/json(?:;\s*charset=utf-8)?$/i.test(req.headers['content-type'] ?? '')) fail(415, 'invalid_content_type');
+  if (req.headers['content-encoding']) fail(400, 'unsupported_content_encoding');
+  const chunks = [];
+  let size = 0;
+  const timer = setTimeout(() => req.destroy(), 2000);
+  try {
+    for await (const chunk of req) {
+      size += chunk.length;
+      if (size > 16 * 1024) fail(413, 'extension_request_limit');
+      chunks.push(chunk);
+    }
+    let value;
+    try { value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks))); }
+    catch { fail(400, 'invalid_json'); }
+    return value;
+  } finally { clearTimeout(timer); }
+}
+function parameters(query, allowed) {
+  const result = {};
+  for (const [name, value] of new URLSearchParams(query)) {
+    if (!allowed.includes(name) || Object.hasOwn(result, name) || !value) fail(400, 'invalid_extension_query');
+    result[name] = value;
+  }
+  for (const field of ['scope', 'session', 'checkpoint']) {
+    if (result[field] !== undefined && !id(result[field])) fail(400, 'invalid_extension_query');
+  }
+  if (result.nonce !== undefined && !/^[A-Za-z0-9_-]{24,128}$/.test(result.nonce)) fail(400, 'invalid_frame_nonce');
+  return result;
+}
+
+/**
+ * Parent performs loopback/Host/Origin checks and viewer-cookie authentication.
+ * Never pass viewerAuthorized for an external read bearer or an opaque origin.
+ * getSnapshot is synchronous and reapplies current core policy, like model-api.
+ */
+export function createExtensionAPI({ registry, getSnapshot, projectId, runAnalysis } = {}) {
+  if (!registry || typeof getSnapshot !== 'function' || !id(projectId) ||
+    (runAnalysis !== undefined && typeof runAnalysis !== 'function')) throw new TypeError('invalid_extension_api_options');
+
+  async function requireGrant(extension, expectedDigest) {
+    const value = await registry.getGrant(extension);
+    try { validateGrant(value); } catch { fail(403, 'extension_grant_denied'); }
+    if (!value.approved || value.projectId !== projectId || value.extensionId !== extension) fail(403, 'extension_grant_denied');
+    if (expectedDigest !== undefined && value.digest !== expectedDigest) fail(409, 'extension_digest_changed');
+    return value;
+  }
+  function snapshot(params, grant) {
+    // A session selector can address historical work even without a checkpoint.
+    if ((params.checkpoint || params.session) && !grant.history) fail(403, 'history_not_granted');
+    const raw = getSnapshot({
+      ...(params.scope ? { scopeId: params.scope } : {}),
+      ...(params.session ? { sessionId: params.session } : {}),
+      ...(params.checkpoint ? { checkpointId: params.checkpoint } : {}),
+      persistent: false,
+    });
+    if (!raw || typeof raw !== 'object' || raw.then || raw.projectId !== projectId) fail(503, 'invalid_model_snapshot');
+    const projected = getExtensionDataProjection(
+      params.checkpoint ? { ...raw, checkpointId: params.checkpoint, replay: true } : raw, grant);
+    if (!projected) fail(403, 'extension_grant_denied');
+    return projected;
+  }
+  async function unchanged(extension, prior) {
+    const current = await requireGrant(extension, prior.digest);
+    if (!sameGrant(prior, current)) fail(403, 'extension_grant_changed');
+    return current;
+  }
+  async function analyze(req, res) {
+    const input = await bodyJSON(req);
+    if (!exact(input, ['id', 'digest', 'profileId', 'entityIds', 'revision']) ||
+      !extensionId(input.id) || !digest(input.digest) || !id(input.profileId) ||
+      !uniqueStrings(input.entityIds, id, 256) || !input.entityIds.length || !integer(input.revision)) {
+      fail(400, 'invalid_analysis_request');
+    }
+    const grant = await requireGrant(input.id, input.digest);
+    if (!grant.profiles?.includes(input.profileId)) fail(403, 'analysis_profile_not_granted');
+    const installed = await registry.getAssets(input.id, { digest: input.digest });
+    if (!installed.manifest.capabilities.includes('analysis.request')) fail(403, 'analysis_not_granted');
+    const profile = installed.profiles.find(value => value.id === input.profileId);
+    if (!profile) fail(403, 'analysis_profile_not_granted');
+    if (profile.selectors.fields.some(field => !grant.fields.includes(field))) fail(403, 'analysis_field_not_granted');
+    await unchanged(input.id, grant);
+    const model = snapshot({}, grant);
+    if (model.revision !== input.revision) fail(409, 'analysis_revision_changed');
+    if (!input.entityIds.every(entityId => model.entities.some(value => value.id === entityId)) ||
+      (profile.selectors.candidateIds.length &&
+        !input.entityIds.every(entityId => profile.selectors.candidateIds.includes(entityId)))) fail(403, 'analysis_candidate_not_granted');
+    if (!runAnalysis) fail(501, 'extension_analysis_unavailable');
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    req.once('aborted', abort);
+    res.once('close', abort);
+    try {
+      // Core owns provider calls, source consent/filtering, approval capabilities,
+      // evidence-version checks, subscriptions, and recording interpretations.
+      const result = await runAnalysis({
+        projectId, extensionId: input.id, digest: input.digest, profile,
+        entityIds: [...input.entityIds], revision: input.revision, grant, signal: controller.signal,
+      });
+      await unchanged(input.id, grant);
+      const current = snapshot({}, grant);
+      if (!result || !['accepted', 'pending', 'complete', 'unavailable'].includes(result.status)) fail(503, 'invalid_analysis_result');
+      const interpretationIds = Array.isArray(result.interpretationIds) ? result.interpretationIds.slice(0, 256)
+        .filter(value => id(value) && current.interpretations.some(item =>
+          item.id === value && item.namespace === profile.namespace)) : [];
+      if (!res.destroyed) reply(res, result.status === 'pending' || result.status === 'accepted' ? 202 : 200, {
+        status: result.status,
+        ...(id(result.requestId) && safeText(result.requestId, 160) ? { requestId: result.requestId } : {}),
+        interpretationIds: [...new Set(interpretationIds)],
+      });
+    } finally {
+      req.removeListener('aborted', abort);
+      res.removeListener('close', abort);
+    }
+  }
+  async function handle(req, res, { viewerAuthorized = false } = {}) {
+    if (typeof req.url !== 'string' ||
+      !(req.url === PREFIX || req.url.startsWith(`${PREFIX}/`) || req.url.startsWith(`${PREFIX}?`))) return false;
+    res.setHeader('Cache-Control', 'no-store');
+    res.setHeader('X-Content-Type-Options', 'nosniff');
+    res.setHeader('Referrer-Policy', 'no-referrer');
+    try {
+      if (viewerAuthorized !== true || req.headers.origin === 'null') fail(401, 'viewer_authorization_required');
+      if (req.url.length > 4096 || /[\s\\#]/.test(req.url) || /%(?![a-f\d]{2})/i.test(req.url)) fail(400, 'invalid_extension_route');
+      const [pathname, query = '', ...extra] = req.url.split('?');
+      if (extra.length || pathname.includes('%') || pathname.includes('//') ||
+        pathname.split('/').some(part => part === '.' || part === '..')) fail(400, 'invalid_extension_route');
+      const route = pathname.slice(PREFIX.length);
+      const read = /^\/(data|frame)\/([^/]+)$/.exec(route);
+      if (read && !extensionId(read[2])) fail(400, 'invalid_extension_id');
+      const params = parameters(query, read?.[1] === 'data' ? ['scope', 'session', 'checkpoint'] :
+        read?.[1] === 'frame' ? ['nonce'] : []);
+      if (req.method === 'GET') {
+        if (req.headers['transfer-encoding'] || Number(req.headers['content-length'] ?? 0) !== 0) fail(400, 'unexpected_body');
+        if (route === '') { reply(res, 200, await registry.list()); return true; }
+        if (!read) fail(404, 'extension_route_not_found');
+        const extension = read[2];
+        const grant = await requireGrant(extension);
+        if (read[1] === 'data') {
+          reply(res, 200, snapshot(params, grant));
+        } else {
+          if (!params.nonce) fail(400, 'invalid_frame_nonce');
+          const assets = await registry.getAssets(extension, { digest: grant.digest });
+          await unchanged(extension, grant);
+          const frame = createFrameDocument({ ...assets, nonce: params.nonce });
+          // DENY remains on every other route. Response CSP sandboxing and
+          // frame-ancestors 'self' protect the directly opened frame document.
+          res.removeHeader('X-Frame-Options');
+          for (const [name, value] of Object.entries(frame.headers)) res.setHeader(name, value);
+          res.writeHead(200); res.end(frame.body);
+        }
+        return true;
+      }
+      if (req.method !== 'POST') fail(405, 'extension_method_not_allowed');
+      if (route === '/analysis') { await analyze(req, res); return true; }
+      if (!['/grant', '/revoke'].includes(route)) fail(404, 'extension_route_not_found');
+      const input = await bodyJSON(req);
+      if (route === '/grant') {
+        if (!exact(input, ['id', 'digest', 'fields', 'history', 'approved'], ['profiles']) ||
+          !extensionId(input.id)) fail(400, 'invalid_extension_grant');
+        const { id: extension, ...request } = input;
+        reply(res, 200, await registry.grant(extension, request));
+      } else {
+        if (!exact(input, ['id']) || !extensionId(input.id)) fail(400, 'invalid_extension_revoke');
+        reply(res, 200, await registry.revoke(input.id));
+      }
+    } catch (error) {
+      const known = {
+        extension_not_installed: [404, 'extension_not_installed'],
+        extension_digest_changed: [409, 'extension_digest_changed'],
+        unrequested_data_field: [403, 'unrequested_data_field'],
+        unrequested_profile: [403, 'unrequested_profile'],
+        unrequested_history: [403, 'unrequested_history'],
+        unrequested_analysis: [403, 'unrequested_analysis'],
+        invalid_extension_grant: [400, 'invalid_extension_grant'],
+        MODEL_CHECKPOINT_UNAVAILABLE: [404, 'checkpoint_unavailable'],
+        MODEL_SCOPE_UNAVAILABLE: [404, 'scope_unavailable'],
+      }[error?.code];
+      const status = error?.[HTTP_ERROR] ? error.status : known?.[0] ?? 503;
+      const code = error?.[HTTP_ERROR] ? error.code : known?.[1] ?? 'extension_unavailable';
+      if (!res.headersSent && !res.destroyed) reply(res, status, { error: code });
+      else if (!res.destroyed) res.destroy();
+    }
+    return true;
+  }
+  return { handle };
+}

package/runtime/daemon/lineage.mjs

@@ -0,0 +1,70 @@
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { safeText } from '../core/privacy.mjs';
+
+const TTL_MS = 2000;
+const CONTROLS = /[\u0000-\u001f\u007f-\u009f\u2028\u2029\u202a-\u202e\u2066-\u2069]/;
+const BRANCH = ['symbolic-ref', '--quiet', '--short', 'HEAD'];
+const HEAD = ['rev-parse', '--verify', '--end-of-options', 'HEAD'];
+const validBranch = value => safeText(value, 240) && !CONTROLS.test(value) &&
+  !/[<>\\:\s]/.test(value) && !value.startsWith('/') && !value.startsWith('-');
+
+/** Local ref metadata only. The caller owns reconciliation and model updates. */
+export function createLineageReader({ projectRoot, projectId, execute = execFile } = {}) {
+  if (typeof projectRoot !== 'string' || !path.isAbsolute(projectRoot) ||
+      Buffer.byteLength(projectRoot) > 4096 || projectRoot.includes('\0') ||
+      typeof projectId !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9_.:-]{0,159}$/.test(projectId) ||
+      typeof execute !== 'function') throw new TypeError('invalid_lineage_options');
+  let cached, expiresAt = 0, pending;
+  const result = (status, branch, head) => Object.freeze({
+    id: createHash('sha256').update(JSON.stringify([projectId, status, branch ?? null, head ?? null])).digest('hex'),
+    status, ...(branch ? { branch } : {}), ...(head ? { head } : {}),
+  });
+
+  function git(args) {
+    return new Promise(resolve => {
+      let child, settled = false;
+      const finish = value => { if (!settled) { settled = true; clearTimeout(timer); resolve(value); } };
+      const timer = setTimeout(() => {
+        finish({ status: 'unavailable' });
+        try { child?.kill?.('SIGKILL'); } catch { /* No child details leave the reader. */ }
+      }, 800);
+      try {
+        child = execute('git', ['-c', 'core.fsmonitor=false', '-c', 'core.hooksPath=/dev/null', ...args], {
+          cwd: projectRoot, shell: false, timeout: 750, killSignal: 'SIGKILL', maxBuffer: 4096, encoding: 'utf8',
+          env: { PATH: process.env.PATH || '/usr/bin:/bin', LC_ALL: 'C',
+            GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: '/dev/null',
+            GIT_OPTIONAL_LOCKS: '0', GIT_TERMINAL_PROMPT: '0', GIT_NO_REPLACE_OBJECTS: '1', GIT_NO_LAZY_FETCH: '1' },
+        }, (error, stdout, stderr) => {
+          const text = typeof stdout === 'string' ? stdout.replace(/\r?\n$/, '') : '';
+          if (!error) return finish({ status: 'ok', text });
+          if (!error.killed && error.code === 1 && !text && args === BRANCH) return finish({ status: 'detached' });
+          finish({ status: !error.killed && error.code === 128 && typeof stderr === 'string' &&
+            stderr.includes('not a git repository') ? 'not_git' : 'unavailable' });
+        });
+      } catch { finish({ status: 'unavailable' }); }
+    });
+  }
+
+  async function readRefs() {
+    if (CONTROLS.test(projectRoot)) return result('unavailable');
+    const branch = await git(BRANCH);
+    if (branch.status === 'not_git') return result('not_git');
+    if (branch.status !== 'detached' && (branch.status !== 'ok' || !validBranch(branch.text))) return result('unavailable');
+    const head = await git(HEAD);
+    if (head.status !== 'ok' || !/^(?:[a-f0-9]{40}|[a-f0-9]{64})$/.test(head.text)) return result('unavailable');
+    // Do not combine a branch observed before checkout with another branch's HEAD.
+    const after = await git(BRANCH);
+    if (branch.status !== after.status || branch.text !== after.text) return result('unavailable');
+    return result('git', branch.status === 'ok' ? branch.text : undefined, head.text);
+  }
+
+  return async function read() {
+    if (cached && Date.now() < expiresAt) return cached;
+    if (!pending) pending = readRefs().then(value => {
+      cached = value; expiresAt = Date.now() + TTL_MS; return value;
+    }).finally(() => { pending = undefined; });
+    return pending;
+  };
+}

package/runtime/daemon/manager.mjs

@@ -33,9 +33,10 @@ function validateRuntime() {
 }
 
 function validateExisting(current, options) {
-  const { allowSource, persistEvidence, displayEvidence } = resolvePolicy(options, { current: current.policy });
+  const { allowSource, localSource, persistEvidence, displayEvidence } = resolvePolicy(options, { current: current.policy });
   const { mode = 'live', port = 0 } = options;
   if (current.mode !== mode || current.policy.transmitSource !== Boolean(allowSource) ||
+      current.policy.readSource !== Boolean(allowSource || localSource) ||
       current.policy.persistEvidence !== Boolean(persistEvidence) ||
       current.policy.displayEvidence !== Boolean(displayEvidence)) throw runtimeError('policy_restart_required');
   if (port && port !== current.port) throw runtimeError('port_restart_required');
@@ -90,11 +91,11 @@ async function stopInstance(paths, instanceId) {
  * instance closes or the caller aborts. Abort never stops a replacement owner.
  */
 export async function runForeground({ projectRoot, dataDir = defaultDataDir(), signal,
-  allowSource, persistEvidence, displayEvidence, mode = 'live', port = 0 } = {}, onReady = () => {}) {
+  allowSource, localSource, persistEvidence, displayEvidence, mode = 'live', port = 0 } = {}, onReady = () => {}) {
   validateRuntime();
   if (signal?.aborted) return;
   const paths = await projectPaths(projectRoot, dataDir);
-  const options = { allowSource, persistEvidence, displayEvidence, mode, port };
+  const options = { allowSource, localSource, persistEvidence, displayEvidence, mode, port };
   let server, launch, interrupted;
   const interruption = new Promise(resolve => { interrupted = resolve; });
   const interrupt = () => interrupted();
@@ -110,7 +111,8 @@ export async function runForeground({ projectRoot, dataDir = defaultDataDir(), s
       const demo = mode === 'demo' ? await import('./demo.mjs') : null;
       try {
         server = await startServer({ projectRoot: paths.projectRoot, dataDir: paths.dataDir, mode, port,
-          policy: { transmitSource: policy.allowSource, persistEvidence: policy.persistEvidence,
+          policy: { readSource: Boolean(policy.localSource || policy.allowSource),
+            transmitSource: policy.allowSource, persistEvidence: policy.persistEvidence,
             displayEvidence: policy.displayEvidence },
           apiKey: policy.allowSource ? process.env.TYPESAFE_API_KEY ?? settings.apiKey : undefined,
           decisionService: demo?.demoDecisionService() });
@@ -155,11 +157,11 @@ export async function runForeground({ projectRoot, dataDir = defaultDataDir(), s
 // Detached operation is reserved for an explicit CLI --background request or
 // MCP. The normal interactive CLI uses runForeground instead.
 export async function startDaemon({ projectRoot, dataDir = defaultDataDir(), background = true,
-  allowSource, persistEvidence, displayEvidence, mode = 'live', port = 0 } = {}) {
+  allowSource, localSource, persistEvidence, displayEvidence, mode = 'live', port = 0 } = {}) {
   validateRuntime();
   if (background !== true) throw runtimeError('background_required');
   const paths = await projectPaths(projectRoot, dataDir);
-  const options = { allowSource, persistEvidence, displayEvidence, mode, port };
+  const options = { allowSource, localSource, persistEvidence, displayEvidence, mode, port };
   const existing = await daemonStatus({ projectRoot: paths.projectRoot, dataDir: paths.dataDir });
   if (existing.running) return { ...await existingLaunch(paths, existing, options), foreground: false };
   const settings = mode === 'demo' ? {} : await readSettings(paths);
@@ -167,6 +169,7 @@ export async function startDaemon({ projectRoot, dataDir = defaultDataDir(), bac
   await projectPaths(projectRoot, dataDir, { create: true });
   const args = [worker, '--project', paths.projectRoot, '--data-dir', paths.dataDir, '--mode', mode, '--port', String(port)];
   if (policy.allowSource) args.push('--allow-source');
+  else if (policy.localSource) args.push('--local-source');
   if (policy.persistEvidence) args.push('--persist-evidence');
   if (!policy.displayEvidence) args.push('--no-display-evidence');
   const env = { ...process.env };