wowbagger 0.1.0-alpha.1

package/src/claim-request.js

@@ -0,0 +1,140 @@
+// src/claim-request.js
+// Schema validation for work-claim requests (docs/work-claim-contract.md section 5).
+// This intentionally re-implements the rules test/work-claim-reference.js's
+// requestSchemaError encodes for the reference model — production code must not
+// depend on test code, so the rules are duplicated here rather than imported.
+import { pointer } from './request.js';
+
+const NAMESPACE_ID = /^wbns_[a-f0-9]{32}$/;
+const ITEM_ID = /^wb_[0-9A-HJKMNP-TV-Z]{26}$/;
+const OWNER_ID = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$/;
+const UTC_INSTANT = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})\.(\d{3})Z$/;
+const MAX_EPOCH = 18446744073709551615n;
+const MAX_LEASE_DURATION_MS = 86400000;
+
+const REQUIRED_MEMBERS = {
+  read: ['ledger_namespace', 'item_id'],
+  acquire: ['ledger_namespace', 'item_id', 'owner_id', 'lease_duration_ms', 'expected'],
+  renew: ['ledger_namespace', 'item_id', 'owner_id', 'epoch', 'expected_expires_at', 'lease_duration_ms'],
+  release: ['ledger_namespace', 'item_id', 'owner_id', 'epoch', 'expected_expires_at'],
+};
+
+// Returns an array of {path, code, message} issues (empty when the request is valid).
+// The request must already be JSON-parsed and deep-normalized (plain objects/arrays,
+// JsonNumber unwrapped) — this module only checks shape, not JSON syntax.
+export function validateClaimRequest(operation, request) {
+  const required = REQUIRED_MEMBERS[operation];
+  if (!isPlainObject(request)) {
+    return [problem([], 'invalid-type', `The ${operation} request must be a JSON object.`)];
+  }
+
+  const actual = Object.keys(request).sort().join(',');
+  const expected = [...required].sort().join(',');
+  if (actual !== expected) {
+    return [problem([], 'invalid-value', `The ${operation} request must have exactly: ${required.join(', ')}.`)];
+  }
+
+  const issues = [];
+  if (!NAMESPACE_ID.test(request.ledger_namespace)) {
+    issues.push(problem(['ledger_namespace'], 'invalid-value', 'Member ledger_namespace must match wbns_[a-f0-9]{32}.'));
+  }
+  if (!ITEM_ID.test(request.item_id)) {
+    issues.push(problem(['item_id'], 'invalid-value', 'Member item_id must match wb_[0-9A-HJKMNP-TV-Z]{26}.'));
+  }
+  if (required.includes('owner_id') && !isOwnerId(request.owner_id)) {
+    issues.push(problem(['owner_id'], 'invalid-value', 'Member owner_id must match [A-Za-z0-9][A-Za-z0-9._:/-]{0,127}.'));
+  }
+  if (required.includes('epoch') && !isCanonicalUint64(request.epoch, false)) {
+    issues.push(problem(['epoch'], 'invalid-value', 'Member epoch must be a canonical unsigned-64 decimal string.'));
+  }
+  if (required.includes('expected_expires_at') && !isStrictUtcInstant(request.expected_expires_at)) {
+    issues.push(problem(['expected_expires_at'], 'invalid-value', 'Member expected_expires_at must match YYYY-MM-DDTHH:MM:SS.mmmZ.'));
+  }
+  if (required.includes('lease_duration_ms') && !isLeaseDuration(request.lease_duration_ms)) {
+    issues.push(problem(['lease_duration_ms'], 'invalid-value', `Member lease_duration_ms must be an integer from 1 through ${MAX_LEASE_DURATION_MS}.`));
+  }
+  if (required.includes('expected')) {
+    issues.push(...expectedIssues(request.expected));
+  }
+  return issues;
+}
+
+function expectedIssues(expected) {
+  if (!isPlainObject(expected)) {
+    return [problem(['expected'], 'invalid-value', 'Member expected must be an object with exactly last_epoch and active.')];
+  }
+  const keys = Object.keys(expected).sort().join(',');
+  if (keys !== 'active,last_epoch') {
+    return [problem(['expected'], 'invalid-value', 'Member expected must have exactly last_epoch and active.')];
+  }
+
+  const issues = [];
+  if (!isCanonicalUint64(expected.last_epoch, true)) {
+    issues.push(problem(['expected', 'last_epoch'], 'invalid-value', 'Member expected.last_epoch must be a canonical unsigned-64 decimal string.'));
+  }
+  const active = expected.active;
+  if (active !== null) {
+    if (!isPlainObject(active)) {
+      issues.push(problem(['expected', 'active'], 'invalid-value', 'Member expected.active must be null or an object.'));
+      return issues;
+    }
+    const activeKeys = Object.keys(active).sort().join(',');
+    if (activeKeys !== 'epoch,expires_at,issued_at,owner_id') {
+      issues.push(problem(['expected', 'active'], 'invalid-value', 'Member expected.active must have exactly owner_id, epoch, issued_at, and expires_at.'));
+      return issues;
+    }
+    if (!isOwnerId(active.owner_id)) {
+      issues.push(problem(['expected', 'active', 'owner_id'], 'invalid-value', 'Member expected.active.owner_id must match [A-Za-z0-9][A-Za-z0-9._:/-]{0,127}.'));
+    }
+    if (!isCanonicalUint64(active.epoch, false)) {
+      issues.push(problem(['expected', 'active', 'epoch'], 'invalid-value', 'Member expected.active.epoch must be a canonical unsigned-64 decimal string.'));
+    }
+    if (!isStrictUtcInstant(active.issued_at)) {
+      issues.push(problem(['expected', 'active', 'issued_at'], 'invalid-value', 'Member expected.active.issued_at must match YYYY-MM-DDTHH:MM:SS.mmmZ.'));
+    }
+    if (!isStrictUtcInstant(active.expires_at)) {
+      issues.push(problem(['expected', 'active', 'expires_at'], 'invalid-value', 'Member expected.active.expires_at must match YYYY-MM-DDTHH:MM:SS.mmmZ.'));
+    }
+  }
+  return issues;
+}
+
+function isOwnerId(value) {
+  return typeof value === 'string' && OWNER_ID.test(value);
+}
+
+function isCanonicalUint64(value, allowZero) {
+  const pattern = allowZero ? /^(0|[1-9][0-9]{0,19})$/ : /^[1-9][0-9]{0,19}$/;
+  if (typeof value !== 'string' || !pattern.test(value)) {
+    return false;
+  }
+  try {
+    return BigInt(value) <= MAX_EPOCH;
+  } catch {
+    return false;
+  }
+}
+
+function isStrictUtcInstant(value) {
+  const match = typeof value === 'string' ? UTC_INSTANT.exec(value) : null;
+  if (!match) {
+    return false;
+  }
+  const [, year, month, day, hour, minute, second, millis] = match.map(Number);
+  const date = new Date(Date.UTC(year, month - 1, day, hour, minute, second, millis));
+  return date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day
+    && date.getUTCHours() === hour && date.getUTCMinutes() === minute && date.getUTCSeconds() === second
+    && date.getUTCMilliseconds() === millis;
+}
+
+function isLeaseDuration(value) {
+  return Number.isInteger(value) && value >= 1 && value <= MAX_LEASE_DURATION_MS;
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function problem(location, code, message) {
+  return { path: pointer(location), code, message };
+}

package/src/claim-store.js

@@ -0,0 +1,198 @@
+import { randomUUID } from 'node:crypto';
+import { execFile } from 'node:child_process';
+import { link, mkdir, open, readFile, realpath, rename, rm, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+const GIT_ENVIRONMENT = Object.fromEntries(
+  Object.entries(process.env).filter(([name]) => !name.startsWith('GIT_')),
+);
+
+export async function resolveGitCommonDir(startDir) {
+  let current = path.resolve(startDir);
+  for (;;) {
+    const candidate = path.join(current, '.git');
+    let info = null;
+    try {
+      info = await stat(candidate);
+    } catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+    }
+    if (info?.isDirectory()) return candidate;
+    if (info?.isFile()) {
+      const text = await readFile(candidate, 'utf8');
+      const match = /^gitdir:\s*(.+)\s*$/m.exec(text);
+      if (!match) return null;
+      const gitDir = path.resolve(current, match[1].trim());
+      try {
+        const commonText = await readFile(path.join(gitDir, 'commondir'), 'utf8');
+        return path.resolve(gitDir, commonText.trim());
+      } catch (error) {
+        if (error?.code !== 'ENOENT') throw error;
+        return gitDir;
+      }
+    }
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+export async function resolveVerifiedGitCommonDir(startDir) {
+  const discovered = await resolveGitCommonDir(startDir);
+  if (!discovered) return null;
+  try {
+    const { stdout } = await execFileAsync(
+      'git',
+      ['rev-parse', '--path-format=absolute', '--git-common-dir'],
+      {
+        cwd: path.resolve(startDir),
+        encoding: 'utf8',
+        env: GIT_ENVIRONMENT,
+        maxBuffer: 1024 * 1024,
+      },
+    );
+    const [reported, expected] = await Promise.all([
+      realpath(stdout.trim()),
+      realpath(discovered),
+    ]);
+    return reported === expected ? discovered : null;
+  } catch {
+    return null;
+  }
+}
+
+export function claimStorePath(commonDir, namespace) {
+  return path.join(commonDir, 'wowbagger', `claims-${namespace}.json`);
+}
+
+export function emptyClaimState(namespace) {
+  return { schema_version: 1, ledger_namespace: namespace, clock_floor: null, claims: [] };
+}
+
+export async function readClaimState(storePath, namespace) {
+  try {
+    const parsed = JSON.parse(await readFile(storePath, 'utf8'));
+    if (parsed?.ledger_namespace !== namespace) return emptyClaimState(namespace);
+    return parsed;
+  } catch (error) {
+    if (error?.code === 'ENOENT') return emptyClaimState(namespace);
+    throw error;
+  }
+}
+
+export async function writeClaimState(storePath, state) {
+  await mkdir(path.dirname(storePath), { recursive: true });
+  const ordered = {
+    ...state,
+    claims: [...state.claims].sort((left, right) => (left.item_id < right.item_id ? -1 : left.item_id > right.item_id ? 1 : 0)),
+  };
+  const temporary = `${storePath}.tmp`;
+  const handle = await open(temporary, 'w');
+  try {
+    await handle.writeFile(`${JSON.stringify(ordered, null, 2)}\n`, 'utf8');
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+  await rename(temporary, storePath);
+}
+
+export async function withClaimLock(storePath, fn) {
+  const directory = path.dirname(storePath);
+  await mkdir(directory, { recursive: true });
+  const lockPath = `${storePath}.lock`;
+  const recoveryPath = `${lockPath}.recovery`;
+  const owner = { version: 1, pid: process.pid, token: randomUUID() };
+  const candidatePath = `${lockPath}.${owner.token}.candidate`;
+  const candidate = await open(candidatePath, 'wx');
+  try {
+    await candidate.writeFile(`${JSON.stringify(owner)}\n`, 'utf8');
+    await candidate.sync();
+  } finally {
+    await candidate.close();
+  }
+
+  try {
+    await acquireClaimLock(candidatePath, lockPath, recoveryPath);
+    try {
+      return await fn();
+    } finally {
+      if ((await readLockOwner(lockPath))?.token === owner.token) {
+        await rm(lockPath, { force: true });
+      }
+    }
+  } finally {
+    await rm(candidatePath, { force: true });
+  }
+}
+
+async function acquireClaimLock(candidatePath, lockPath, recoveryPath) {
+  for (;;) {
+    const recoveryOwner = await readLockOwner(recoveryPath);
+    if (recoveryOwner) {
+      if (!isDeadProcess(recoveryOwner.pid)) throw claimLockHeld();
+      await rm(recoveryPath, { force: true });
+      continue;
+    }
+    try {
+      await link(candidatePath, lockPath);
+      return;
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+    }
+
+    try {
+      await link(candidatePath, recoveryPath);
+    } catch (error) {
+      if (error?.code === 'EEXIST') continue;
+      throw error;
+    }
+    try {
+      const lockOwner = await readLockOwner(lockPath);
+      if (!lockOwner || !isDeadProcess(lockOwner.pid)) throw claimLockHeld();
+      await rm(lockPath, { force: true });
+    } finally {
+      await rm(recoveryPath, { force: true });
+    }
+  }
+}
+
+async function readLockOwner(lockPath) {
+  let source;
+  try {
+    source = await readFile(lockPath, 'utf8');
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null;
+    throw error;
+  }
+  try {
+    const owner = JSON.parse(source);
+    if (owner?.version !== 1
+      || !Number.isSafeInteger(owner.pid)
+      || owner.pid <= 0
+      || typeof owner.token !== 'string'
+      || owner.token.length === 0) {
+      throw new Error('invalid lock owner');
+    }
+    return owner;
+  } catch {
+    throw claimLockHeld();
+  }
+}
+
+function isDeadProcess(pid) {
+  try {
+    process.kill(pid, 0);
+    return false;
+  } catch (error) {
+    return error?.code === 'ESRCH';
+  }
+}
+
+function claimLockHeld() {
+  const error = new Error('claim store lock is held');
+  error.code = 'CLAIM_LOCK_HELD';
+  return error;
+}