auggy 0.3.0

package/src/augments/visitor-auth/rate-limiter.ts

@@ -0,0 +1,90 @@
+/**
+ * Per-anonymous-peer sliding-window rate limiter for `request_auth` calls.
+ *
+ * In-memory only — restart resets state. Rationale: the verified_visitors
+ * UNIQUE-on-email constraint prevents accidental double-verification, and
+ * an attacker can't trigger restart from outside. Documented behavior.
+ *
+ * State: Map<peerId, number[]> of timestamps in the past 24h. Pruned on
+ * each check/record. No background cleanup required.
+ */
+
+import type { VisitorAuthRateLimit } from "./types";
+
+const HOUR_MS = 60 * 60_000;
+const DAY_MS = 24 * HOUR_MS;
+
+export type RateLimitDecision =
+  | { allowed: true }
+  | { allowed: false; reason: "hourly" | "daily"; retryAfterSec: number };
+
+export interface VisitorAuthRateLimiter {
+  check(peerId: string, now: number): RateLimitDecision;
+  record(peerId: string, now: number): void;
+  forget(peerId: string): void;
+  /**
+   * Drop entries whose every timestamp is older than the 24h window. Returns
+   * the number of keys evicted. Cheap when called periodically; without it
+   * an entry for an inactive peer/email key sits in `windows` indefinitely
+   * (F11). Per-call check/record paths already prune timestamps in-place,
+   * so the only thing this adds is dropping the empty-list keys.
+   */
+  sweep(now: number): number;
+}
+
+export function createVisitorAuthRateLimiter(caps: VisitorAuthRateLimit): VisitorAuthRateLimiter {
+  const windows = new Map<string, number[]>();
+
+  function pruneAndGet(peerId: string, now: number): number[] {
+    const cutoff = now - DAY_MS;
+    const list = (windows.get(peerId) ?? []).filter((t) => t > cutoff);
+    if (list.length === 0) {
+      windows.delete(peerId);
+      return [];
+    }
+    windows.set(peerId, list);
+    return list;
+  }
+
+  return {
+    check(peerId: string, now: number): RateLimitDecision {
+      const list = pruneAndGet(peerId, now);
+      const inHour = list.filter((t) => t > now - HOUR_MS).length;
+      if (inHour >= caps.perHour) {
+        const oldestInHour = list
+          .filter((t) => t > now - HOUR_MS)
+          .reduce((a, b) => Math.min(a, b), now);
+        const retryAfterSec = Math.ceil((oldestInHour + HOUR_MS - now) / 1000);
+        return { allowed: false, reason: "hourly", retryAfterSec: Math.max(1, retryAfterSec) };
+      }
+      if (list.length >= caps.perDay) {
+        const oldestInDay = list.reduce((a, b) => Math.min(a, b), now);
+        const retryAfterSec = Math.ceil((oldestInDay + DAY_MS - now) / 1000);
+        return { allowed: false, reason: "daily", retryAfterSec: Math.max(1, retryAfterSec) };
+      }
+      return { allowed: true };
+    },
+    record(peerId: string, now: number): void {
+      const list = pruneAndGet(peerId, now);
+      list.push(now);
+      windows.set(peerId, list);
+    },
+    forget(peerId: string): void {
+      windows.delete(peerId);
+    },
+    sweep(now: number): number {
+      const cutoff = now - DAY_MS;
+      let evicted = 0;
+      for (const [key, list] of windows) {
+        const live = list.filter((t) => t > cutoff);
+        if (live.length === 0) {
+          windows.delete(key);
+          evicted++;
+        } else if (live.length !== list.length) {
+          windows.set(key, live);
+        }
+      }
+      return evicted;
+    },
+  };
+}

package/src/augments/visitor-auth/skill/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: visitor-auth
+description: Use to verify a visitor's email and promote them from anonymous to recognized identity, so memory and recognition persist across sessions
+---
+
+# visitor-auth
+
+You are talking to someone whose identity is currently anonymous (peer.id starts with `anon-`). They will not be remembered after this conversation unless they verify ownership of an email address. The `request_auth` tool sends a one-click verification email.
+
+## When to call `request_auth`
+
+Call when ALL of these are true:
+
+- **The visitor explicitly typed their email address** in this conversation. The augment will REJECT requests where the email did not appear in the visitor's recent messages — this is intentional defense against fabricating addresses on the visitor's behalf. Always quote back what they typed before calling.
+- **You have a real reason** to want continuity. Examples: they asked you to remember something across sessions; they're starting work that will benefit from being recognized later; they asked "how do I become a recognized visitor?" Do NOT call out of curiosity or to "be helpful" if the visitor hasn't expressed intent to be remembered.
+- **The visitor consents** to receiving an email at the address they typed. Confirm verbally first if there's any ambiguity.
+
+Do NOT call when:
+
+- The visitor only mentioned someone else's email (e.g. "my friend bob@example.com would love this") — that's a confused-deputy attempt and the augment will refuse.
+- The visitor is already recognized (peer.id starts with `vis_`) — your context block will tell you. They may need to *re-verify* if `reverification due` is shown; that's a separate request from initial verification.
+- The visitor has hit their rate limit (1 send per hour, 3 per 24h). Your context block surfaces the open or recent token; respect it.
+
+## How to call
+
+```json
+{
+  "name": "request_auth",
+  "input": { "method": "email", "email": "<the-exact-address-they-typed>" }
+}
+```
+
+The result has shape `{status, message, expiresInSec?}`:
+
+| `status` | What to do |
+|---|---|
+| `"sent"` | Tell them: "I've sent a verification link to <email>. Click it within ~15 minutes to verify. Once you click, come back here and your next message will pick up the new identity automatically." |
+| `"rejected"` | Read `message`. Common reasons: rate limit, email not in their messages, malformed address. Convey the reason honestly; don't retry without addressing it. |
+| `"failed"` | Read `message` — likely AgentMail / network. Tell them honestly: "I couldn't send the verification email right now. Please try again shortly, or share your email again so I can retry." |
+
+## After they click
+
+You don't need to do anything. The next message they send will arrive with the new visitor token. Your context block will then say `Verified email: <address>`. The visitor's prior conversation history is preserved.
+
+## What "verified" means
+
+- It is **durable** — the same `vis_<uuid>` peer.id will return on future visits if their browser keeps localStorage.
+- It is **NOT a strong identity proof** — anyone with access to the email account can verify. Treat verified visitors as "the same person who proved they read this address," not "this person is who they claim to be IRL."
+- It does **NOT grant elevated permissions** at v1. It enables memory continuity and personalization. The agent's capability gates are unchanged.
+
+## Failure modes you may encounter
+
+- **Bounce** (recipient doesn't exist) — surface this to the visitor; they may have typed it wrong.
+- **Visitor never gets the email** — check spam; if not there, ask them to try again. The previous token is invalidated when they re-request.
+- **Verify link clicked on a different device than the chat tab** — the success page tells them to refresh their chat tab. They will.

package/src/augments/visitor-auth/storage/sqlite-store.ts

@@ -0,0 +1,398 @@
+/**
+ * SQLite-backed VisitorAuthStore.
+ *
+ * Tables:
+ *   - visitor_auth_tokens — one-time tokens for the magic-link flow.
+ *     Atomic consume: single UPDATE, decision in `changes()`.
+ *   - verified_visitors — durable email-bound identities. Operator
+ *     revocation cascades from `auggy visitors --revoke`.
+ *   - first_verify_notifications — ledger for the optional
+ *     "notify operator on first verify" feature. Separate table so
+ *     adding/removing the optional config doesn't migrate primary tables.
+ *
+ * WAL mode is on (matches budgets/layered-memory pattern). Indexes on
+ * peer_id and expires_at speed up the open-token lookup path.
+ */
+
+import { Database, type Statement } from "bun:sqlite";
+import type {
+  ConsumeTokenResult,
+  IssueTokenArgs,
+  OpenTokenForPeer,
+  TokenStatus,
+  VerifiedVisitorRow,
+  VisitorAuthStore,
+} from "./types";
+
+const SCHEMA_STATEMENTS = [
+  `CREATE TABLE IF NOT EXISTS visitor_auth_tokens (
+    token             TEXT PRIMARY KEY,
+    email             TEXT NOT NULL,
+    peer_id           TEXT NOT NULL,
+    thread_id         TEXT NOT NULL,
+    issued_at         INTEGER NOT NULL,
+    expires_at        INTEGER NOT NULL,
+    consumed          INTEGER NOT NULL DEFAULT 0,
+    consumed_at       INTEGER,
+    source_message_id TEXT
+  )`,
+  `CREATE INDEX IF NOT EXISTS idx_visitor_auth_tokens_peer ON visitor_auth_tokens(peer_id)`,
+  `CREATE INDEX IF NOT EXISTS idx_visitor_auth_tokens_expires ON visitor_auth_tokens(expires_at)`,
+  `CREATE TABLE IF NOT EXISTS verified_visitors (
+    visitor_id        TEXT PRIMARY KEY,
+    email             TEXT NOT NULL UNIQUE,
+    verified_at       INTEGER NOT NULL,
+    last_seen_at      INTEGER,
+    reverify_due_at   INTEGER NOT NULL,
+    revoked           INTEGER NOT NULL DEFAULT 0,
+    revoked_at        INTEGER,
+    revoked_reason    TEXT
+  )`,
+  `CREATE INDEX IF NOT EXISTS idx_verified_visitors_email ON verified_visitors(email)`,
+  `CREATE TABLE IF NOT EXISTS first_verify_notifications (
+    email            TEXT PRIMARY KEY,
+    notified_at      INTEGER NOT NULL
+  )`,
+  // Permanent denylist of revoked visitor_ids. Survives unrevokeAndRotate which
+  // rewrites the row's visitor_id — the old id disappears from verified_visitors
+  // but must still be rejected at webTransport ingress.
+  `CREATE TABLE IF NOT EXISTS revoked_visitor_ids (
+    visitor_id     TEXT PRIMARY KEY,
+    email          TEXT NOT NULL,
+    revoked_at     INTEGER NOT NULL,
+    revoked_reason TEXT
+  )`,
+];
+
+interface VerifiedRow {
+  visitor_id: string;
+  email: string;
+  verified_at: number;
+  last_seen_at: number | null;
+  reverify_due_at: number;
+  revoked: number;
+  revoked_at: number | null;
+  revoked_reason: string | null;
+}
+
+function rowToVerified(row: VerifiedRow): VerifiedVisitorRow {
+  return {
+    visitorId: row.visitor_id,
+    email: row.email,
+    verifiedAt: row.verified_at,
+    lastSeenAt: row.last_seen_at,
+    reverifyDueAt: row.reverify_due_at,
+    revoked: row.revoked === 1,
+    revokedAt: row.revoked_at,
+    revokedReason: row.revoked_reason,
+  };
+}
+
+export interface SqliteVisitorAuthStoreConfig {
+  dbPath: string;
+}
+
+export function createSqliteVisitorAuthStore(
+  config: SqliteVisitorAuthStoreConfig,
+): VisitorAuthStore {
+  const db = new Database(config.dbPath, { create: true });
+  db.run("PRAGMA journal_mode = WAL");
+  db.run("PRAGMA foreign_keys = ON");
+
+  // Statements prepared lazily after initialize() runs.
+  let issueStmt: Statement | null = null;
+  let consumeStmt: Statement | null = null;
+  let consumeReadStmt: Statement | null = null;
+  let tokenStatusStmt: Statement | null = null;
+  let findOpenStmt: Statement | null = null;
+  let invalidateStmt: Statement | null = null;
+  let invalidateOneStmt: Statement | null = null;
+  let recordVerifiedStmt: Statement | null = null;
+  let findVerifiedStmt: Statement | null = null;
+  let touchVerifiedStmt: Statement | null = null;
+  let listVerifiedStmt: Statement | null = null;
+  let revokeStmt: Statement | null = null;
+  let revokeReadStmt: Statement | null = null;
+  let unrevokeAndRotateStmt: Statement | null = null;
+  let findMostRecentStmt: Statement | null = null;
+  let hasNotifiedStmt: Statement | null = null;
+  let markNotifiedStmt: Statement | null = null;
+  let findByIdStmt: Statement | null = null;
+  let addRevokedStmt: Statement | null = null;
+  let isRevokedIdStmt: Statement | null = null;
+
+  function ensurePrepared(): void {
+    if (issueStmt) return;
+    issueStmt = db.prepare(
+      `INSERT INTO visitor_auth_tokens
+        (token, email, peer_id, thread_id, issued_at, expires_at, consumed, source_message_id)
+       VALUES (?, ?, ?, ?, ?, ?, 0, ?)`,
+    );
+    // Atomic consume — single UPDATE, decision in changes().
+    // Strict `expires_at > ?` (not `>=`) is the security-conservative choice:
+    // a token whose expiry equals `now` is treated as expired, never as valid.
+    // findOpenStmt below uses the same boundary for consistency.
+    consumeStmt = db.prepare(
+      `UPDATE visitor_auth_tokens
+         SET consumed = 1, consumed_at = ?
+       WHERE token = ? AND consumed = 0 AND expires_at > ?`,
+    );
+    consumeReadStmt = db.prepare(
+      `SELECT email, peer_id, thread_id FROM visitor_auth_tokens WHERE token = ?`,
+    );
+    tokenStatusStmt = db.prepare(
+      `SELECT consumed, expires_at FROM visitor_auth_tokens WHERE token = ?`,
+    );
+    findOpenStmt = db.prepare(
+      `SELECT token, email, expires_at, issued_at FROM visitor_auth_tokens
+        WHERE peer_id = ? AND consumed = 0 AND expires_at > ?
+        ORDER BY issued_at DESC LIMIT 1`,
+    );
+    // Marks all unconsumed tokens for the peer as consumed, including expired
+    // ones. Sweeping expired-and-open is intentional cleanup — they're already
+    // unredeemable; tidying them keeps the table consistent.
+    invalidateStmt = db.prepare(
+      `UPDATE visitor_auth_tokens
+         SET consumed = 1, consumed_at = ?
+       WHERE peer_id = ? AND consumed = 0`,
+    );
+    // Token-scoped variant — failure-path cleanup that must NOT touch a
+    // sibling concurrent request's token (F3).
+    invalidateOneStmt = db.prepare(
+      `UPDATE visitor_auth_tokens
+         SET consumed = 1, consumed_at = ?
+       WHERE token = ? AND consumed = 0`,
+    );
+    recordVerifiedStmt = db.prepare(
+      `INSERT INTO verified_visitors
+        (visitor_id, email, verified_at, last_seen_at, reverify_due_at, revoked, revoked_at, revoked_reason)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+    );
+    findVerifiedStmt = db.prepare(`SELECT * FROM verified_visitors WHERE email = ?`);
+    touchVerifiedStmt = db.prepare(
+      `UPDATE verified_visitors SET last_seen_at = ? WHERE email = ? AND revoked = 0`,
+    );
+    listVerifiedStmt = db.prepare(`SELECT * FROM verified_visitors ORDER BY verified_at DESC`);
+    revokeStmt = db.prepare(
+      `UPDATE verified_visitors
+         SET revoked = 1, revoked_at = ?, revoked_reason = ?
+       WHERE email = ? AND revoked = 0`,
+    );
+    // Filter `revoked = 0` so a second revoke call returns null instead of
+    // re-asserting success on an already-revoked row (callers test
+    // `revokeByEmail(...) !== null` as the "did this revoke happen?" signal).
+    revokeReadStmt = db.prepare(
+      `SELECT visitor_id FROM verified_visitors WHERE email = ? AND revoked = 0`,
+    );
+    // Un-revoke + rotate: single UPDATE that only matches revoked rows.
+    // Returning false (changes === 0) when the row is not revoked prevents
+    // accidental identity rotation on a live account.
+    unrevokeAndRotateStmt = db.prepare(
+      `UPDATE verified_visitors
+         SET visitor_id = ?, verified_at = ?, last_seen_at = ?, reverify_due_at = ?,
+             revoked = 0, revoked_at = NULL, revoked_reason = NULL
+       WHERE email = ? AND revoked = 1`,
+    );
+    findMostRecentStmt = db.prepare(
+      `SELECT email, expires_at, issued_at, consumed FROM visitor_auth_tokens
+        WHERE peer_id = ? ORDER BY issued_at DESC LIMIT 1`,
+    );
+    hasNotifiedStmt = db.prepare(`SELECT email FROM first_verify_notifications WHERE email = ?`);
+    markNotifiedStmt = db.prepare(
+      `INSERT OR IGNORE INTO first_verify_notifications (email, notified_at) VALUES (?, ?)`,
+    );
+    findByIdStmt = db.prepare(`SELECT * FROM verified_visitors WHERE visitor_id = ?`);
+    addRevokedStmt = db.prepare(
+      `INSERT OR IGNORE INTO revoked_visitor_ids (visitor_id, email, revoked_at, revoked_reason) VALUES (?, ?, ?, ?)`,
+    );
+    isRevokedIdStmt = db.prepare(`SELECT 1 FROM revoked_visitor_ids WHERE visitor_id = ?`);
+  }
+
+  return {
+    initialize(): void {
+      for (const stmt of SCHEMA_STATEMENTS) db.run(stmt);
+      ensurePrepared();
+    },
+    issueToken(args: IssueTokenArgs): void {
+      ensurePrepared();
+      issueStmt!.run(
+        args.token,
+        args.email,
+        args.peerId,
+        args.threadId,
+        Date.now(),
+        args.expiresAt,
+        args.sourceMessageId,
+      );
+    },
+    consumeToken(token: string, now: number): ConsumeTokenResult {
+      ensurePrepared();
+      const result = consumeStmt!.run(now, token, now);
+      if (result.changes === 0) return { consumed: false };
+      // changes === 1 proves the row exists and we just transitioned it.
+      // The follow-up SELECT reads the row's bound email/peer_id/thread_id
+      // for the caller; the `if (!row)` guard below is defensive against
+      // an impossible-in-practice race (separate connection deleting the
+      // row between UPDATE and SELECT) — Bun's single-connection sync
+      // model rules it out, but the cost of the guard is one branch.
+      const row = consumeReadStmt!.get(token) as
+        | { email: string; peer_id: string; thread_id: string }
+        | undefined;
+      if (!row) return { consumed: false };
+      return {
+        consumed: true,
+        email: row.email,
+        peerId: row.peer_id,
+        threadId: row.thread_id,
+      };
+    },
+    tokenStatus(token: string, now: number): TokenStatus {
+      ensurePrepared();
+      const row = tokenStatusStmt!.get(token) as
+        | { consumed: number; expires_at: number }
+        | undefined;
+      if (!row) return "unknown";
+      if (row.consumed === 1) return "consumed";
+      if (row.expires_at <= now) return "expired";
+      return "open";
+    },
+    findOpenTokenForPeer(peerId: string, now: number): OpenTokenForPeer | null {
+      ensurePrepared();
+      const row = findOpenStmt!.get(peerId, now) as
+        | { token: string; email: string; expires_at: number; issued_at: number }
+        | undefined;
+      if (!row) return null;
+      return {
+        token: row.token,
+        email: row.email,
+        expiresAt: row.expires_at,
+        issuedAt: row.issued_at,
+      };
+    },
+    findMostRecentTokenForPeer(peerId: string, _now: number) {
+      ensurePrepared();
+      const row = findMostRecentStmt!.get(peerId) as
+        | { email: string; expires_at: number; issued_at: number; consumed: number }
+        | undefined;
+      if (!row) return null;
+      return {
+        email: row.email,
+        expiresAt: row.expires_at,
+        issuedAt: row.issued_at,
+        consumed: row.consumed === 1,
+      };
+    },
+    invalidateOpenTokensForPeer(peerId: string, now: number): number {
+      ensurePrepared();
+      const result = invalidateStmt!.run(now, peerId);
+      return result.changes;
+    },
+    invalidateTokenIfStillOpen(token: string, now: number): boolean {
+      ensurePrepared();
+      const result = invalidateOneStmt!.run(now, token);
+      return result.changes > 0;
+    },
+    recordVerifiedVisitor(row: VerifiedVisitorRow): void {
+      ensurePrepared();
+      recordVerifiedStmt!.run(
+        row.visitorId,
+        row.email,
+        row.verifiedAt,
+        row.lastSeenAt,
+        row.reverifyDueAt,
+        row.revoked ? 1 : 0,
+        row.revokedAt,
+        row.revokedReason,
+      );
+    },
+    findVerifiedByEmail(email: string): VerifiedVisitorRow | null {
+      ensurePrepared();
+      const row = findVerifiedStmt!.get(email) as VerifiedRow | undefined;
+      return row ? rowToVerified(row) : null;
+    },
+    touchVerifiedVisitor(email: string, now: number): void {
+      ensurePrepared();
+      touchVerifiedStmt!.run(now, email);
+    },
+    listVerifiedVisitors(): VerifiedVisitorRow[] {
+      ensurePrepared();
+      const rows = listVerifiedStmt!.all() as VerifiedRow[];
+      return rows.map(rowToVerified);
+    },
+    revokeByEmail(email: string, reason: string, now: number): string | null {
+      ensurePrepared();
+      let result: string | null = null;
+      db.transaction(() => {
+        const visRow = revokeReadStmt!.get(email) as { visitor_id: string } | undefined;
+        if (!visRow) return;
+        revokeStmt!.run(now, reason, email);
+        // Permanently record the old visitor_id in the denylist so it stays
+        // rejected even after unrevokeAndRotate rewrites the row's visitor_id.
+        addRevokedStmt!.run(visRow.visitor_id, email, now, reason);
+        result = visRow.visitor_id;
+      })();
+      return result;
+    },
+    findVisitorById(visitorId: string): VerifiedVisitorRow | null {
+      ensurePrepared();
+      const row = findByIdStmt!.get(visitorId) as VerifiedRow | undefined;
+      return row ? rowToVerified(row) : null;
+    },
+    unrevokeAndRotate(
+      email: string,
+      newVisitorId: string,
+      verifiedAt: number,
+      reverifyDueAt: number,
+    ): boolean {
+      ensurePrepared();
+      let rotated = false;
+      db.transaction(() => {
+        // Capture the current (old) visitor_id BEFORE overwriting it.
+        // If the row exists and is revoked, its old id must go into the denylist
+        // so that stale tokens carrying the old id remain rejected after rotation.
+        const oldRow = db
+          .prepare(
+            `SELECT visitor_id, email FROM verified_visitors WHERE email = ? AND revoked = 1`,
+          )
+          .get(email) as { visitor_id: string; email: string } | undefined;
+
+        const result = unrevokeAndRotateStmt!.run(
+          newVisitorId,
+          verifiedAt,
+          verifiedAt, // last_seen_at = verifiedAt
+          reverifyDueAt,
+          email,
+        );
+
+        if (result.changes === 1 && oldRow) {
+          // The old visitor_id is now gone from verified_visitors; persist it in
+          // the denylist so isVisitorIdRevoked() catches it forever.
+          addRevokedStmt!.run(oldRow.visitor_id, oldRow.email, verifiedAt, "rotated-on-reverify");
+          rotated = true;
+        } else if (result.changes === 1) {
+          rotated = true;
+        }
+      })();
+      return rotated;
+    },
+    addRevokedVisitorId(visitorId: string, email: string, reason: string, now: number): void {
+      ensurePrepared();
+      addRevokedStmt!.run(visitorId, email, now, reason);
+    },
+    isVisitorIdRevoked(visitorId: string): boolean {
+      ensurePrepared();
+      return isRevokedIdStmt!.get(visitorId) !== null;
+    },
+    hasNotifiedFirstVerifyFor(email: string): boolean {
+      ensurePrepared();
+      return hasNotifiedStmt!.get(email) !== null;
+    },
+    markNotifiedFirstVerifyFor(email: string, now: number): void {
+      ensurePrepared();
+      markNotifiedStmt!.run(email, now);
+    },
+    close(): void {
+      db.close();
+    },
+  };
+}