auggy 0.3.0

package/src/augments/visitor-auth/storage/types.ts

@@ -0,0 +1,164 @@
+/**
+ * Storage record shapes + the abstract VisitorAuthStore interface.
+ * Splitting the storage contract from the SQLite impl lets us swap to
+ * a Postgres-backed store later without touching the augment.
+ */
+
+export type TokenStatus = "open" | "consumed" | "expired" | "unknown";
+
+export interface IssueTokenArgs {
+  token: string;
+  email: string;
+  peerId: string;
+  threadId: string;
+  expiresAt: number; // epoch ms
+  sourceMessageId: string | null;
+}
+
+export interface ConsumeTokenResult {
+  /** True iff exactly one row transitioned from consumed=0 to consumed=1. */
+  consumed: boolean;
+  /** Set when consumed=true. */
+  email?: string;
+  /** Set when consumed=true. */
+  peerId?: string;
+  /** Set when consumed=true. */
+  threadId?: string;
+}
+
+export interface VerifiedVisitorRow {
+  visitorId: string; // vis_<uuid>
+  email: string;
+  verifiedAt: number; // epoch ms
+  lastSeenAt: number | null;
+  reverifyDueAt: number; // epoch ms
+  revoked: boolean;
+  revokedAt: number | null;
+  revokedReason: string | null;
+}
+
+export interface OpenTokenForPeer {
+  token: string;
+  email: string;
+  expiresAt: number; // epoch ms
+  issuedAt: number; // epoch ms
+}
+
+export interface VisitorAuthStore {
+  /**
+   * Idempotent schema apply. Safe to call repeatedly; safe on a fresh DB.
+   * Called from onBoot before any other operation.
+   */
+  initialize(): void;
+  /**
+   * Insert a new token row. Throws on PK collision (caller should generate
+   * a fresh UUID — collisions are statistically impossible in normal use).
+   */
+  issueToken(args: IssueTokenArgs): void;
+  /**
+   * Atomic consume. Single SQL UPDATE, returns whether exactly one row
+   * transitioned. When consumed=true the row's email/peerId/threadId are
+   * returned for the caller to mint the visitor token.
+   *
+   * Per spec fix #8 — the entire decision lives in `changes()`, no race.
+   */
+  consumeToken(token: string, now: number): ConsumeTokenResult;
+  /**
+   * Read-only status query. Used by the verify route to disambiguate
+   * 410 (consumed/expired) from 404 (unknown) after a failed consumeToken.
+   */
+  tokenStatus(token: string, now: number): TokenStatus;
+  /**
+   * The most-recent OPEN (unconsumed, unexpired) token for this peer, if any.
+   * Used by `request_auth` to invalidate prior open tokens before issuing a new one.
+   */
+  findOpenTokenForPeer(peerId: string, now: number): OpenTokenForPeer | null;
+  /**
+   * The most-recent token for this peer regardless of consumed/expired status.
+   * Used by context() to surface "verification expired" state. Returns null
+   * if the peer has never had a token issued.
+   */
+  findMostRecentTokenForPeer(
+    peerId: string,
+    now: number,
+  ): {
+    email: string;
+    expiresAt: number;
+    issuedAt: number;
+    consumed: boolean;
+  } | null;
+  /**
+   * Mark every open token for this peer as consumed (without minting a
+   * visitor token). Used when a peer requests a new email; the prior code
+   * goes dead.
+   */
+  invalidateOpenTokensForPeer(peerId: string, now: number): number;
+  /**
+   * Mark exactly one token as consumed if it is still open. Returns true
+   * if a row was modified (the token existed and was unconsumed), false
+   * otherwise. Used by the request_auth failure-path cleanup so a failed
+   * send only invalidates its OWN token — without this, a concurrent
+   * request_auth call from the same peer could be invalidated as
+   * collateral when the failed call's cleanup runs (F3).
+   */
+  invalidateTokenIfStillOpen(token: string, now: number): boolean;
+  /**
+   * Insert a verified-visitor row. Caller has already minted the visitor token.
+   * If a row with the same email exists and is not revoked, throws — caller
+   * should treat this as "already verified, prefer existing identity"
+   * (handled in the verify route).
+   */
+  recordVerifiedVisitor(row: VerifiedVisitorRow): void;
+  /** Returns the row for an email, or null. */
+  findVerifiedByEmail(email: string): VerifiedVisitorRow | null;
+  /** Update lastSeenAt; no-op if email is unknown or revoked. */
+  touchVerifiedVisitor(email: string, now: number): void;
+  /** All verified-visitor rows, ordered by verifiedAt DESC. Used by `auggy visitors`. */
+  listVerifiedVisitors(): VerifiedVisitorRow[];
+  /**
+   * Hard-revoke. Sets revoked=1 + reason. Returns the visitorId or null
+   * if the email was unknown. Used by `auggy visitors --revoke`.
+   */
+  revokeByEmail(email: string, reason: string, now: number): string | null;
+  /**
+   * Lookup a verified-visitor row by visitorId. Returns null if no row with
+   * that id exists. Used by `isVisitorRevoked` to enable real-time revocation
+   * checks at webTransport ingress (fix C1).
+   */
+  findVisitorById(visitorId: string): VerifiedVisitorRow | null;
+  /**
+   * Un-revoke a previously-revoked row and rotate to a fresh visitorId.
+   * Called by the verify route when a visitor re-verifies after their identity
+   * was revoked. A single UPDATE atomically clears revocation state, writes the
+   * new vis_<uuid>, and updates verifiedAt / lastSeenAt / reverifyDueAt.
+   *
+   * Returns true iff exactly one revoked row was updated. Returns false if the
+   * email is unknown or the row is not revoked (no-op guard).
+   */
+  unrevokeAndRotate(
+    email: string,
+    newVisitorId: string,
+    verifiedAt: number,
+    reverifyDueAt: number,
+  ): boolean;
+  /**
+   * Permanently record a visitor_id as revoked. The denylist survives even
+   * when the row is rotated by unrevokeAndRotate (which rewrites visitor_id),
+   * so old tokens cannot bypass the revocation check by returning a row that
+   * no longer carries the old id.
+   *
+   * INSERT OR IGNORE — idempotent; second call with the same id is a no-op.
+   */
+  addRevokedVisitorId(visitorId: string, email: string, reason: string, now: number): void;
+  /**
+   * Returns true iff the given visitor_id appears in the permanent denylist.
+   * Used by isVisitorRevoked in index.ts as the first check before falling
+   * through to the live row lookup.
+   */
+  isVisitorIdRevoked(visitorId: string): boolean;
+  /** True iff the augment has emitted notifyOnFirstVerify for this email yet. */
+  hasNotifiedFirstVerifyFor(email: string): boolean;
+  /** Mark notifyOnFirstVerify as fired for this email. Idempotent. */
+  markNotifiedFirstVerifyFor(email: string, now: number): void;
+  close(): void;
+}

package/src/augments/visitor-auth/types.ts

@@ -0,0 +1,123 @@
+/**
+ * Type definitions for the visitorAuth augment.
+ *
+ * Exposed to the auggy resolver (consumes VisitorAuthOptions) and to the
+ * augment's internal modules. All shapes here are stable contracts; storage
+ * record shapes live in storage/types.ts (a deliberate split — operator-facing
+ * config is separate from on-disk representation).
+ */
+
+/**
+ * AgentMail delivery configuration. visitorAuth uses src/agentmail-client.ts
+ * directly (see Plan §"Spec deviation"). Operator wires apiKey + inboxId via
+ * env-var interpolation in agent.yaml.
+ */
+export interface AgentMailConfig {
+  /** Bearer token (`am_*` prefix). Resolve via `${AGENTMAIL_API_KEY}` in agent.yaml. */
+  apiKey: string;
+  /** AgentMail inbox the verify email is sent FROM. */
+  inboxId: string;
+  /** Optional subject prefix prepended to the templated subject. Default: `[Verify] `. */
+  subjectPrefix?: string;
+  /** Optional override for the AgentMail API base URL (testing/sandbox). */
+  apiBaseUrl?: string;
+}
+
+/**
+ * Per-anonymous-peer rate-limit caps for `request_auth` calls. Defaults:
+ * 1 send per hour, 3 sends per 24 hours. State is in-memory (resets on
+ * restart — documented behavior; the verified_visitors UNIQUE-on-email
+ * constraint catches accidental double-verification).
+ */
+export interface VisitorAuthRateLimit {
+  perHour: number;
+  perDay: number;
+}
+
+/**
+ * Operator notification fired the FIRST time an email verifies on this agent.
+ * Optional; when set, visitorAuth uses agentmail-client to send a one-line
+ * note from inboxId TO the operator address. Independent from `notify`.
+ */
+export interface NotifyOnFirstVerifyConfig {
+  to: string;
+  /** Optional subject prefix (default `[New verified visitor] `). */
+  subjectPrefix?: string;
+}
+
+export interface VisitorAuthOptions {
+  /**
+   * Public-facing base URL for the magic link, e.g. `https://zip.lorf.dev`.
+   * Must be a valid URL with `http://` or `https://` scheme. Required because
+   * the magic-link URL embedded in the email is `<publicUrl>/visitor-auth/verify?token=<uuid>`.
+   */
+  publicUrl: string;
+  /** Path to the visitor-auth SQLite database. Default: `./visitor-auth.db` (relative to agent dir). */
+  dbPath: string;
+  /** AgentMail delivery config. Required. */
+  agentMail: AgentMailConfig;
+  /**
+   * HMAC signing key for minting `vis_<uuid>` visitor tokens after a successful
+   * verify. MUST match webTransport's `visitorTokens.signingKey`. Resolve via
+   * `${VISITOR_SIGNING_KEY}` in agent.yaml (same env var both augments read).
+   */
+  signingKey: string;
+  /**
+   * Stable identifier this agent uses for visitor tokens (fix C2). MUST match
+   * webTransport's `visitorTokens.agentBinding`. Default: `"auggy"`.
+   *
+   * When two agents share the same signing key, setting distinct `agentBinding`
+   * values on each prevents cross-agent replay: a token minted for agent A
+   * will be rejected by agent B because the embedded agentId will not match
+   * agent B's expected binding.
+   */
+  agentBinding?: string;
+  /** Optional rate-limit caps. Defaults: { perHour: 1, perDay: 3 }. */
+  rateLimit?: VisitorAuthRateLimit;
+  /** Days before reverification is required. Default: 90. */
+  reverifyAfterDays?: number;
+  /** Token TTL in minutes. Default: 15. */
+  tokenTtlMinutes?: number;
+  /** Optional operator-notification on first verify per email. */
+  notifyOnFirstVerify?: NotifyOnFirstVerifyConfig;
+  /**
+   * Path to the layeredMemory SQLite database for the anonymous→recognized
+   * peer-id migration on successful verify. Default: `./memory.db` (relative
+   * to agent dir). Set to `null` to disable migration (anonymous history will
+   * be orphaned but still queryable by threadId).
+   */
+  layeredMemoryDbPath?: string | null;
+}
+
+/**
+ * Extra surface exposed by the visitorAuth augment beyond the base Augment
+ * interface. Consumed by the augment resolver to wire the revocation check
+ * into webTransport without requiring a new kernel surface (fix C1).
+ */
+export interface VisitorAuthAugmentExtras {
+  /**
+   * Returns `true` iff the visitor with the given `vis_<uuid>` id has been
+   * revoked. Reads directly from the store — no caching, always current.
+   * Intended to be wired as `webTransport.visitorTokens.revocationCheck`.
+   */
+  isVisitorRevoked(visitorId: string): boolean;
+}
+
+/** Return shape of `request_auth({...})`. JSON-stringified by the tool. */
+export interface RequestAuthResult {
+  status: "sent" | "rejected" | "failed";
+  message: string;
+  /** Present iff status === "sent". TTL of the issued token. */
+  expiresInSec?: number;
+}
+
+/**
+ * Snapshot of the most-recent visitor message text the augment uses for
+ * the email-in-recent-message validation. The transcript itself lives
+ * in the kernel; visitorAuth only needs the visitor's recent text.
+ */
+export interface RecentVisitorMessage {
+  text: string;
+  /** Optional message id; recorded with the token for audit. */
+  messageId?: string;
+}

package/src/augments/visitor-auth/verify-page.ts

@@ -0,0 +1,179 @@
+/**
+ * Pure HTML builders for the verify-success + verify-failure pages.
+ *
+ * Security posture (spec fix #5):
+ *   - <meta name="referrer" content="no-referrer">
+ *   - Zero external assets (inline CSS, no fonts, no analytics, no images)
+ *   - history.replaceState fires on load to drop the token from the URL bar
+ *     before any browser history snapshot
+ *   - The visitor token is JSON-encoded and </script>-escaped before being
+ *     written into the inline <script> block
+ *   - The email is rendered via document.createTextNode (innerText), not innerHTML
+ */
+
+export interface VerifyConfirmPageInput {
+  token: string;
+  publicUrl: string;
+}
+
+export interface VerifySuccessPageInput {
+  visitorToken: string;
+  email: string;
+}
+
+export interface VerifyFailurePageInput {
+  reason: "expired" | "consumed" | "unknown" | "malformed" | string;
+}
+
+function htmlEscape(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+/**
+ * JSON-encode a string for safe interpolation inside an inline <script>.
+ * The U+003C escape neutralizes any embedded `</script>` so the script block
+ * cannot be terminated by attacker-controlled content.
+ */
+function jsStringLiteral(value: string): string {
+  return JSON.stringify(value).replace(/</g, "\\u003c");
+}
+
+const COMMON_HEAD = `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="referrer" content="no-referrer">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Auggy — verification</title>
+<style>
+:root { color-scheme: light dark; font-family: ui-sans-serif, system-ui, sans-serif; }
+body { margin: 0; padding: 3rem 1rem; max-width: 36rem; margin-inline: auto; line-height: 1.5; }
+h1 { font-size: 1.25rem; margin: 0 0 0.5rem; }
+p { margin: 0.5rem 0; color: #555; }
+@media (prefers-color-scheme: dark) {
+  body { background: #111; color: #eee; }
+  p { color: #aaa; }
+}
+</style>
+</head>`;
+
+/**
+ * Confirmation page returned by GET /visitor-auth/verify.
+ *
+ * Mail scanners follow links passively (GET); they do NOT auto-submit forms.
+ * Returning this page on GET means the scanner harmlessly receives the
+ * confirmation page without consuming the one-time token. The human clicks
+ * "Verify my email" which triggers a form POST that actually consumes it.
+ *
+ * Security notes:
+ *   - <meta name="referrer" content="no-referrer"> prevents the token from
+ *     leaking in Referer headers to third parties.
+ *   - The form POSTs to an absolute URL (publicUrl) to guarantee same-site
+ *     submission even if the user opened the link on a different device.
+ *   - Inline JS disables the button after click to prevent accidental double-
+ *     submit within the same page load.
+ *   - NO localStorage write, NO history.replaceState — those happen on the
+ *     success page served after the POST.
+ */
+export function buildVerifyConfirmPage(input: VerifyConfirmPageInput): string {
+  const base = input.publicUrl.endsWith("/") ? input.publicUrl.slice(0, -1) : input.publicUrl;
+  const actionUrl = `${base}/visitor-auth/verify`;
+  // Token comes from validated UUID input — safe to embed as a hidden field value.
+  // htmlEscape is applied for correctness even though UUIDs are [0-9a-f-] only.
+  const safeToken = htmlEscape(input.token);
+  return `${COMMON_HEAD}
+<body>
+<h1>Verify your email</h1>
+<p>Click the button below to complete email verification. This link can only be used once.</p>
+<form method="POST" action="${htmlEscape(actionUrl)}" id="vf">
+  <input type="hidden" name="token" value="${safeToken}">
+  <button type="submit" id="btn" style="font-size:1rem;padding:0.6rem 1.4rem;cursor:pointer;">Verify my email</button>
+</form>
+<script>
+(function(){
+  var btn = document.getElementById('btn');
+  var form = document.getElementById('vf');
+  if (form && btn) {
+    form.addEventListener('submit', function(){
+      btn.disabled = true;
+      btn.textContent = 'Verifying…';
+    });
+  }
+})();
+</script>
+<noscript><p>Submit the form above to verify your email.</p></noscript>
+</body>
+</html>`;
+}
+
+export function buildVerifySuccessPage(input: VerifySuccessPageInput): string {
+  const tokenLit = jsStringLiteral(input.visitorToken);
+  const emailLit = jsStringLiteral(input.email);
+  return `${COMMON_HEAD}
+<body>
+<h1 id="title">Verifying…</h1>
+<p id="msg">Please wait.</p>
+<p id="storage-fallback" style="display:none">
+  Verified, but your browser blocked storage access. Copy this token manually to your chat tab:
+  <br><code id="manual-token" style="word-break:break-all"></code>
+  <br><small>(This may happen in private/incognito mode or sandboxed iframes.)</small>
+</p>
+<script>
+(function () {
+  var token = ${tokenLit};
+  var email = ${emailLit};
+  var storageWorks = false;
+  try {
+    localStorage.setItem('auggy-visitor-token', token);
+    storageWorks = true;
+  } catch (_) { /* storage may be denied in private/incognito mode or sandboxed iframes */ }
+  try {
+    history.replaceState(null, '', './verified');
+  } catch (_) { /* older browsers — best-effort */ }
+  var titleEl = document.getElementById('title');
+  var msgEl = document.getElementById('msg');
+  var fallbackEl = document.getElementById('storage-fallback');
+  var manualEl = document.getElementById('manual-token');
+  if (titleEl) titleEl.textContent = 'Verified.';
+  if (storageWorks) {
+    if (msgEl) {
+      msgEl.textContent = 'Email verified: ' + email + '. You may close this tab; your chat tab will pick up the new identity on its next message. If you opened this link on a different device, refresh your chat tab.';
+    }
+  } else {
+    if (msgEl) msgEl.style.display = 'none';
+    if (fallbackEl) fallbackEl.style.display = '';
+    if (manualEl) manualEl.textContent = token;
+  }
+})();
+</script>
+<noscript>
+<p>Email verified, but JavaScript is required to apply the new identity to your chat tab. Please re-open your chat tab manually.</p>
+</noscript>
+</body>
+</html>`;
+}
+
+const FAILURE_COPY: Record<string, string> = {
+  expired: "This verification link has expired. Please ask the agent to send a new one.",
+  consumed:
+    "This verification link has already been used. If you didn't expect this, request a new link.",
+  unknown: "We don't recognize this verification link. It may be malformed or out of date.",
+  malformed: "This verification link is malformed.",
+  "bad-body": "The verification request was malformed (could not parse the request body).",
+};
+
+export function buildVerifyFailurePage(input: VerifyFailurePageInput): string {
+  const known = FAILURE_COPY[input.reason];
+  const safeReason = known ?? "Verification failed.";
+  return `${COMMON_HEAD}
+<body>
+<h1>Verification failed</h1>
+<p>${htmlEscape(safeReason)}</p>
+</body>
+</html>`;
+}