instar 1.3.475 → 1.3.476

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.475",
+  "version": "1.3.476",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/scripts/lib/throwaway-identity.mjs

@@ -0,0 +1,150 @@
+/**
+ * throwaway-identity.mjs — mint genuinely-distinct, readable throwaway email
+ * identities for live-integration test harnesses (Slack, Discord, …).
+ *
+ * Backed by the mail.tm public disposable-mailbox API. Each minted inbox is a
+ * real, distinct, readable address — so a live test can use N of them as N
+ * GENUINELY DISTINCT principals (distinct addresses → distinct provider user
+ * IDs) with ZERO real accounts. This is the autonomous half of the
+ * test-identity provisioning the Live Integration Security-Test Harness needs;
+ * the only step it does NOT cover is an anti-bot signup CAPTCHA at workspace/
+ * account creation, which is a deliberate human-verification control (see
+ * docs/specs/JUDGMENT-PERMISSION-LIVE-RUN-RUNBOOK.md).
+ *
+ * Pure helpers (extractCode/extractLink/matchMessage) and HTTP helpers with an
+ * injectable `fetchImpl` so the unit test runs fully hermetic (no network).
+ *
+ * CLI: scripts/throwaway-identity.mjs (mint | wait). This file is the importable
+ * library; the CLI is a thin wrapper.
+ */
+
+const DEFAULT_API_BASE = 'https://api.mail.tm';
+
+/** Extract the first verification code (default: a 6-digit run) from a message body. */
+export function extractCode(text, { pattern = /\b(\d{6})\b/ } = {}) {
+  if (typeof text !== 'string') return null;
+  const m = text.match(pattern);
+  return m ? (m[1] ?? m[0]) : null;
+}
+
+/** Extract the first URL (optionally matching a substring/regex) from a message body. */
+export function extractLink(text, { match } = {}) {
+  if (typeof text !== 'string') return null;
+  const urls = text.match(/https?:\/\/[^\s"'<>)\]]+/g) || [];
+  if (!match) return urls[0] ?? null;
+  const test = match instanceof RegExp ? (u) => match.test(u) : (u) => u.includes(match);
+  return urls.find(test) ?? null;
+}
+
+/** Does a mail.tm message summary match the caller's filter (subject/from substring or regex)? */
+export function matchMessage(msg, { subject, from } = {}) {
+  if (!msg) return false;
+  const subjOk = matchField(msg.subject, subject);
+  const fromAddr = (msg.from && (msg.from.address || msg.from.name)) || '';
+  const fromOk = matchField(fromAddr, from);
+  return subjOk && fromOk;
+}
+
+function matchField(value, filter) {
+  if (filter === undefined || filter === null) return true;
+  const v = String(value ?? '');
+  return filter instanceof RegExp ? filter.test(v) : v.toLowerCase().includes(String(filter).toLowerCase());
+}
+
+function memberArray(json) {
+  // mail.tm is a Hydra/JSON-LD API: collections live under "hydra:member".
+  if (Array.isArray(json)) return json;
+  if (json && Array.isArray(json['hydra:member'])) return json['hydra:member'];
+  return [];
+}
+
+async function jsonFetch(fetchImpl, url, opts) {
+  const res = await fetchImpl(url, opts);
+  const text = await res.text();
+  let body = null;
+  try { body = text ? JSON.parse(text) : null; } catch { body = null; }
+  if (!res.ok) {
+    const detail = (body && (body['hydra:description'] || body.message || body.detail)) || text.slice(0, 200);
+    throw new Error(`mail.tm ${opts?.method || 'GET'} ${url} → ${res.status}: ${detail}`);
+  }
+  return body;
+}
+
+/**
+ * Mint a fresh throwaway inbox: pick a domain, create the account, get a token.
+ * Returns { address, password, token, accountId }. `rand` is injectable so the
+ * test is deterministic and the script never calls Math.random in a workflow.
+ */
+export async function createInbox({
+  fetchImpl = fetch,
+  apiBase = DEFAULT_API_BASE,
+  localPart,
+  rand = () => Math.floor(Math.random() * 1e10).toString(36),
+} = {}) {
+  const domains = memberArray(await jsonFetch(fetchImpl, `${apiBase}/domains`));
+  const domain = domains.find((d) => d.isActive !== false)?.domain || domains[0]?.domain;
+  if (!domain) throw new Error('mail.tm: no available domain');
+  const local = localPart || `echo-${rand()}`;
+  const address = `${local}@${domain}`;
+  const password = `Echo!${rand()}A9`;
+  const account = await jsonFetch(fetchImpl, `${apiBase}/accounts`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ address, password }),
+  });
+  const tokenResp = await jsonFetch(fetchImpl, `${apiBase}/token`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ address, password }),
+  });
+  if (!tokenResp?.token) throw new Error('mail.tm: token request returned no token');
+  return { address, password, token: tokenResp.token, accountId: account?.id ?? null };
+}
+
+/** List message summaries in the inbox (most-recent first, per mail.tm). */
+export async function listMessages(token, { fetchImpl = fetch, apiBase = DEFAULT_API_BASE } = {}) {
+  const body = await jsonFetch(fetchImpl, `${apiBase}/messages`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  return memberArray(body);
+}
+
+/** Fetch one message's full body (text + html). */
+export async function getMessage(token, id, { fetchImpl = fetch, apiBase = DEFAULT_API_BASE } = {}) {
+  return jsonFetch(fetchImpl, `${apiBase}/messages/${id}`, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+}
+
+/**
+ * Poll the inbox until a message matches the filter, then return its full body.
+ * `sleep` and `now` are injectable so the test runs without real timers/clock.
+ * Throws on timeout. Returns the full message (with .text / .html / .subject).
+ */
+export async function waitForMessage(token, {
+  subject,
+  from,
+  timeoutMs = 120_000,
+  intervalMs = 3_000,
+  fetchImpl = fetch,
+  apiBase = DEFAULT_API_BASE,
+  sleep = (ms) => new Promise((r) => setTimeout(r, ms)),
+  now = () => Date.now(),
+} = {}) {
+  const deadline = now() + timeoutMs;
+  // First iteration runs immediately (no upfront sleep).
+  for (let first = true; ; first = false) {
+    if (!first) {
+      if (now() >= deadline) {
+        throw new Error(`waitForMessage: timed out after ${timeoutMs}ms (subject=${subject ?? '*'} from=${from ?? '*'})`);
+      }
+      await sleep(intervalMs);
+    }
+    const summaries = await listMessages(token, { fetchImpl, apiBase });
+    const hit = summaries.find((m) => matchMessage(m, { subject, from }));
+    if (hit) return getMessage(token, hit.id, { fetchImpl, apiBase });
+    if (first && now() >= deadline) {
+      throw new Error(`waitForMessage: timed out after ${timeoutMs}ms (subject=${subject ?? '*'} from=${from ?? '*'})`);
+    }
+  }
+}

package/scripts/throwaway-identity.mjs

@@ -0,0 +1,77 @@
+#!/usr/bin/env node
+/**
+ * throwaway-identity.mjs — CLI for the disposable-identity helper (lib/throwaway-identity.mjs).
+ *
+ *   node scripts/throwaway-identity.mjs mint
+ *       → mints a fresh inbox; prints JSON { address, password, token, accountId }.
+ *
+ *   node scripts/throwaway-identity.mjs wait <token> [--subject S] [--from F]
+ *                                       [--code | --link [MATCH]] [--timeout MS]
+ *       → polls the inbox until a matching message arrives, then prints either
+ *         the full message JSON, or (with --code/--link) just the extracted value.
+ *
+ * Use for live-integration test-identity provisioning (the autonomous half — an
+ * anti-bot signup CAPTCHA at account creation is the human handoff).
+ */
+import {
+  createInbox,
+  waitForMessage,
+  extractCode,
+  extractLink,
+} from './lib/throwaway-identity.mjs';
+
+function parseFlags(args) {
+  const out = { _: [] };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--code') out.code = true;
+    else if (a === '--link') { out.link = true; if (args[i + 1] && !args[i + 1].startsWith('--')) out.linkMatch = args[++i]; }
+    else if (a === '--subject') out.subject = args[++i];
+    else if (a === '--from') out.from = args[++i];
+    else if (a === '--timeout') out.timeout = parseInt(args[++i], 10);
+    else out._.push(a);
+  }
+  return out;
+}
+
+async function main() {
+  const [cmd, ...rest] = process.argv.slice(2);
+  const flags = parseFlags(rest);
+
+  if (cmd === 'mint') {
+    const inbox = await createInbox();
+    process.stdout.write(JSON.stringify(inbox) + '\n');
+    return;
+  }
+
+  if (cmd === 'wait') {
+    const token = flags._[0];
+    if (!token) { console.error('usage: throwaway-identity.mjs wait <token> [--subject S] [--from F] [--code|--link [MATCH]] [--timeout MS]'); process.exit(1); }
+    const msg = await waitForMessage(token, {
+      subject: flags.subject,
+      from: flags.from,
+      timeoutMs: flags.timeout ?? 120_000,
+    });
+    const text = msg.text || msg.html?.join?.('\n') || (Array.isArray(msg.html) ? msg.html.join('\n') : msg.html) || '';
+    if (flags.code) {
+      const code = extractCode(text);
+      if (!code) { console.error('no verification code found in message'); process.exit(1); }
+      process.stdout.write(code + '\n');
+    } else if (flags.link) {
+      const link = extractLink(text, flags.linkMatch ? { match: flags.linkMatch } : {});
+      if (!link) { console.error('no link found in message'); process.exit(1); }
+      process.stdout.write(link + '\n');
+    } else {
+      process.stdout.write(JSON.stringify({ subject: msg.subject, from: msg.from, text }) + '\n');
+    }
+    return;
+  }
+
+  console.error('usage: throwaway-identity.mjs <mint | wait>');
+  process.exit(1);
+}
+
+import { pathToFileURL } from 'node:url';
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main().catch((err) => { console.error(err instanceof Error ? err.message : String(err)); process.exit(1); });
+}

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-10T18:44:18.495Z",
-  "instarVersion": "1.3.475",
+  "generatedAt": "2026-06-10T19:09:40.028Z",
+  "instarVersion": "1.3.476",
   "entryCount": 201,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.476.md

@@ -0,0 +1,33 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Added a standalone test utility — `scripts/throwaway-identity.mjs` (+ `scripts/lib/`) — that
+mints genuinely-distinct, readable throwaway email inboxes via the mail.tm public
+disposable-mailbox API and extracts verification codes/links from them. It's the autonomous
+half of provisioning distinct test identities for the Live Integration Security-Test Harness
+(Slack today, any integration later): N distinct inboxes → N genuinely-distinct principals,
+zero real accounts. No runtime code, gate, or config is touched.
+
+## What to Tell Your User
+
+Nothing changes in how the agent runs. This is a developer/test tool. It lets the agent set
+up several genuinely-different throwaway test users (and read their email) on its own, so a
+live integration test can use real distinct identities without anyone hand-creating email
+accounts. The only step it intentionally leaves to a human is passing an anti-bot CAPTCHA at
+workspace creation.
+
+## Summary of New Capabilities
+
+- `scripts/throwaway-identity.mjs mint` — create a fresh readable throwaway inbox.
+- `scripts/throwaway-identity.mjs wait <token>` — await an email and extract its code/link.
+- `scripts/lib/throwaway-identity.mjs` — importable helper (HTTP injectable for hermetic tests).
+
+## Evidence
+
+- 15 hermetic unit tests (`tests/unit/throwaway-identity.test.ts`) — pure extractors + the
+  mint / poll-until-match / timeout flow, with fetch + clock injected (no network).
+- Live CLI smoke minted a real inbox + token. `tsc --noEmit` clean.

package/upgrades/side-effects/throwaway-identity-helper.md

@@ -0,0 +1,48 @@
+# Side-Effects Review — throwaway-identity helper
+
+**Version / slug:** `throwaway-identity-helper`
+**Date:** `2026-06-10`
+**Author:** `echo`
+**Tier:** `1` (standalone test-tooling script + lib + hermetic test; no runtime/gate/config wiring)
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+Adds `scripts/lib/throwaway-identity.mjs` (importable) + `scripts/throwaway-identity.mjs`
+(CLI) — mints genuinely-distinct, readable throwaway email inboxes via the mail.tm public
+disposable-mailbox API, and polls/extracts codes+links from them. The autonomous half of
+test-identity provisioning for live-integration test harnesses (Slack/Discord/…). + a fully
+hermetic unit test (injected fetch + clock, no network) and an ELI16.
+
+## Decision-point inventory
+
+None in runtime — it's standalone tooling, never imported by `src/` or wired into a gate.
+Internal branch points (domain selection, message-match filter, timeout) are pure functions
+covered by the test.
+
+## 1. Over-block
+
+Nothing is rejected at runtime. The tool only calls a public disposable-mail API and reads
+inboxes it just created. It is not on any agent code path.
+
+## 2. Under-block
+
+It deliberately does NOT cover the anti-bot signup CAPTCHA at workspace/account creation —
+that is a human-verification control and remains a ~30s human handoff (documented in the
+live-run runbook). It is the email half only.
+
+## 3. Level-of-abstraction fit
+
+Right layer: a `scripts/` + `scripts/lib/` test utility beside the other dev/test scripts,
+with the HTTP injected so the test is hermetic. Reusable by any integration's live harness,
+not coupled to the permission gate.
+
+## Migration / rollback
+
+No migration (standalone tooling). Rollback = delete the two scripts + the test.
+
+## Testing-integrity note
+
+15 hermetic unit tests (pure extractors + the full mint / poll-until-match / timeout flow,
+HTTP + clock injected). A separate live CLI smoke confirmed it mints a real inbox
+(`echo-…@web-library.net` + token). `tsc --noEmit` clean.