toolroll 0.9.49 → 0.9.51

package/dist/session-http.js

@@ -1,3 +1,4 @@
+import { adapterPolicy } from "./server/route-policy.js";
 import { SESSION_REQUEST_BYTES, SESSION_RESPONSE_BYTES, isSessionResponse, sessionDescriptor, validateSessionRequest, } from './session-contract.js';
 import { limitWords } from './request-budget.js';
 function readBody(request) {
@@ -122,6 +123,8 @@ export async function handleSessionHttp(request, response, options) {
     }
     if (options.admitAuthenticated && refuseAdmission(options.admitAuthenticated(request, actor)))
         return true;
+    if (!adapterPolicy({ caller: "bearer", capability: "act" }, spec.mutation ? "act" : "read").ok)
+        return reject(403, "forbidden", "Current operator access is required.");
     const media = request.headers['content-type']?.split(';')[0]?.trim().toLowerCase();
     if (media !== 'application/json')
         return reject(415, 'unsupported-media-type', 'Send the session request as application/json.');

package/dist/sign-in-guard.d.ts

@@ -1,31 +1,56 @@
+import { AsyncLocalStorage } from "node:async_hooks";
 /**
- * Password guessing (v99). Five wrong passwords in a row lock that account
- * for 15 minutes, doubling with each further lock up to a day; a right one
- * clears the count. Every password check counts: signing in, a request that
- * carries a password, and each step-up inside the console. Unknown names
- * count too, so guessing names gains nothing.
- *
- * Kept in memory, per database: a restart forgives, which someone locked out
- * by another's guessing may need. The console reports each lock to the
- * action ledger through onLock.
+ * Five failures lock a source/account pair, with exponential backoff. Across sources, failures slow an account and
+ * admit only a few unproven checks per minute before password derivation. A validated same-account browser session
+ * bypasses that shared admission budget, never a source's own lock. Fabricated names follow the same admission path.
+ * Source and name records expire by time. Both use bounded, non-evicting keyed storage, regardless of whether the
+ * account exists. Saturation shares overflow buckets without displacing or changing individually tracked state.
  */
 export type GuardPolicy = {
     failuresBeforeLock: number;
     firstLockMs: number;
     maxLockMs: number;
+    firstSlowMs: number;
 };
 export declare const DEFAULT_GUARD_POLICY: GuardPolicy;
+/** Default/loopback source for callers without an explicit native CLI context. */
+export declare const LOCAL_SOURCE = "local";
+/** Native CLI only: no HTTP peer or forwarded header can select this source. */
+export declare const CLI_PASSWORD_SOURCE = "local-cli";
+export declare const ACCOUNT_PASSWORD_TRIES = 3;
+export declare const ACCOUNT_PASSWORD_WINDOW_MS = 60000;
+/** Run `work` with every password check inside it counted against `source`. */
+export declare const withPasswordSource: <T>(source: string, work: () => T) => T;
+/** Where the password being checked now came from (LOCAL_SOURCE outside a request). */
+export declare const currentPasswordSource: () => string;
+/** Set only after the server validates a browser session, never from submitted form fields. */
+export declare const provenPasswordAccount: AsyncLocalStorage<{
+    name: string;
+    generation: number;
+} | null>;
 export declare class PasswordGuard {
     readonly policy: GuardPolicy;
-    private readonly accounts;
+    private readonly secret;
+    private readonly sources;
+    private readonly slowdowns;
+    private nextPruneAt;
     /** Told once per lock: the account (as typed), and for how long. */
     onLock: ((account: string, lockMs: number) => void) | null;
     constructor(policy?: GuardPolicy);
     private static key;
-    /** Milliseconds this account stays locked (0: it may try). */
-    lockedFor(account: string, now: number): number;
-    failed(account: string, now: number): void;
-    succeeded(account: string): void;
+    private static pair;
+    /** Prune by the supplied time, even below capacity; retain a lock's escalation history for a day. */
+    private prune;
+    /** Source-local snapshot for existing callers. Authentication must use preflight to spend the shared budget. */
+    lockedFor(account: string, now: number, source?: string): number;
+    /** Reserve one password check, or return its wait. No password derivation may precede this call. */
+    preflight(account: string, now: number, source?: string, proven?: boolean): number;
+    /** A wrong password; only a database lookup may establish `exists`. */
+    failed(account: string, now: number, source?: string, exists?: boolean): void;
+    /** The right password clears individually tracked state; shared overflow buckets must expire by time. */
+    succeeded(account: string, source?: string): void;
+    /** Individually tracked source-and-name entries (at most TRACKED), excluding fixed shared overflow buckets. */
+    get size(): number;
 }
 /** The guard for one database (a store): every password check against it counts. */
 export declare function passwordGuardOf(owner: object): PasswordGuard;
@@ -40,6 +65,6 @@ export declare class SourceBudget {
     private readonly sources;
     constructor(tries?: number, windowMs?: number);
     /** Milliseconds until this address may try again (0: it may). */
-    waitFor(source: string, now: number): number;
-    failed(source: string, now: number): void;
+    waitFor(address: string, now: number): number;
+    failed(address: string, now: number): void;
 }

package/dist/sign-in-guard.js

@@ -1,39 +1,161 @@
-export const DEFAULT_GUARD_POLICY = { failuresBeforeLock: 5, firstLockMs: 15 * 60_000, maxLockMs: 24 * 60 * 60_000 };
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createHmac, randomBytes } from "node:crypto";
+import { sourceKey } from "./source-key.js";
+export const DEFAULT_GUARD_POLICY = { failuresBeforeLock: 5, firstLockMs: 15 * 60_000, maxLockMs: 24 * 60 * 60_000, firstSlowMs: 60_000 };
 const TRACKED = 10_000;
+/** Default/loopback source for callers without an explicit native CLI context. */
+export const LOCAL_SOURCE = "local";
+/** Native CLI only: no HTTP peer or forwarded header can select this source. */
+export const CLI_PASSWORD_SOURCE = "local-cli";
+export const ACCOUNT_PASSWORD_TRIES = 3;
+export const ACCOUNT_PASSWORD_WINDOW_MS = 60_000;
+const LOCAL_PEERS = new Set(["127.0.0.1", "::1"]);
+const passwordSource = new AsyncLocalStorage();
+/** Run `work` with every password check inside it counted against `source`. */
+export const withPasswordSource = (source, work) => passwordSource.run(source, work);
+/** Where the password being checked now came from (LOCAL_SOURCE outside a request). */
+export const currentPasswordSource = () => passwordSource.getStore() ?? LOCAL_SOURCE;
+/** Set only after the server validates a browser session, never from submitted form fields. */
+export const provenPasswordAccount = new AsyncLocalStorage();
+/**
+ * Keep the first TRACKED live keys exactly; further keys share TRACKED overflow buckets. Hashes use the guard's
+ * private secret, so callers cannot choose collisions. Neither tier evicts live state. Overflow never mutates the
+ * exact tier, and cannot move into a freed exact slot until all overflow state expires: moving would reset budgets.
+ * A success may clear its exact record, but never a shared bucket (which could also hold another name's failures).
+ */
+class KeyedGuardState {
+    secret;
+    domain;
+    entries = new Map();
+    overflow = new Map();
+    constructor(secret, domain) {
+        this.secret = secret;
+        this.domain = domain;
+    }
+    hash(key) { return createHmac("sha256", this.secret).update(this.domain).update("\0").update(key).digest("hex"); }
+    bucket(hash) { return parseInt(hash.slice(0, 8), 16) % TRACKED; }
+    get(key) {
+        const hash = this.hash(key);
+        return this.entries.get(hash) ?? this.overflow.get(this.bucket(hash));
+    }
+    retain(key, create) {
+        const hash = this.hash(key), kept = this.entries.get(hash);
+        if (kept !== undefined)
+            return kept;
+        if (this.overflow.size === 0 && this.entries.size < TRACKED) {
+            const entry = create();
+            this.entries.set(hash, entry);
+            return entry;
+        }
+        const bucket = this.bucket(hash), shared = this.overflow.get(bucket);
+        if (shared !== undefined)
+            return shared;
+        const entry = create();
+        this.overflow.set(bucket, entry);
+        return entry;
+    }
+    clear(key) { this.entries.delete(this.hash(key)); }
+    prune(now, lifetime) {
+        let next = Infinity;
+        const pruneEntries = (entries) => {
+            for (const [key, entry] of entries) {
+                const expires = entry.lastAt + lifetime;
+                if (expires <= now)
+                    entries.delete(key);
+                else
+                    next = Math.min(next, expires);
+            }
+        };
+        pruneEntries(this.entries);
+        pruneEntries(this.overflow);
+        return next;
+    }
+    /** Individual source/name records; shared overflow storage has its own fixed TRACKED-bucket bound. */
+    get size() { return this.entries.size; }
+}
 export class PasswordGuard {
     policy;
-    accounts = new Map();
+    secret = randomBytes(32);
+    sources = new KeyedGuardState(this.secret, "source/name");
+    slowdowns = new KeyedGuardState(this.secret, "name");
+    nextPruneAt = Infinity;
     /** Told once per lock: the account (as typed), and for how long. */
     onLock = null;
     constructor(policy = DEFAULT_GUARD_POLICY) {
         this.policy = policy;
     }
     static key(account) { return account.trim().toLowerCase().slice(0, 64); }
-    /** Milliseconds this account stays locked (0: it may try). */
-    lockedFor(account, now) {
-        const state = this.accounts.get(PasswordGuard.key(account));
-        return state === undefined ? 0 : Math.max(0, state.lockedUntil - now);
+    static pair(account, source) {
+        const key = sourceKey(source);
+        return `${LOCAL_PEERS.has(key) ? LOCAL_SOURCE : key}\u0000${PasswordGuard.key(account)}`;
+    }
+    /** Prune by the supplied time, even below capacity; retain a lock's escalation history for a day. */
+    prune(now) {
+        if (now < this.nextPruneAt)
+            return;
+        this.nextPruneAt = Math.min(this.sources.prune(now, this.policy.maxLockMs), this.slowdowns.prune(now, this.policy.maxLockMs));
     }
-    failed(account, now) {
+    /** Source-local snapshot for existing callers. Authentication must use preflight to spend the shared budget. */
+    lockedFor(account, now, source = currentPasswordSource()) {
+        this.prune(now);
+        const pair = PasswordGuard.pair(account, source);
+        const tries = this.sources.get(pair);
+        if (tries === undefined)
+            return 0;
+        const slowdown = this.slowdowns.get(PasswordGuard.key(account));
+        // Legacy observation only: account existence never affects authentication or state retention.
+        return Math.max(0, tries.lockedUntil - now, slowdown?.observedAccount === true ? slowdown.until - now : 0);
+    }
+    /** Reserve one password check, or return its wait. No password derivation may precede this call. */
+    preflight(account, now, source = currentPasswordSource(), proven = false) {
+        this.prune(now);
+        const tries = this.sources.get(PasswordGuard.pair(account, source));
         const key = PasswordGuard.key(account);
-        const state = this.accounts.get(key) ?? { failures: 0, lockedUntil: 0, locks: 0 };
-        this.accounts.delete(key);
-        state.failures += 1;
-        if (state.failures >= this.policy.failuresBeforeLock) {
-            const lockMs = Math.min(this.policy.maxLockMs, this.policy.firstLockMs * 2 ** state.locks);
-            state.lockedUntil = now + lockMs;
-            state.locks += 1;
-            state.failures = 0;
+        const slowdown = this.slowdowns.get(key);
+        const sourceWait = Math.max(0, (tries?.lockedUntil ?? 0) - now, tries === undefined ? 0 : (slowdown?.until ?? 0) - now);
+        if (sourceWait > 0)
+            return sourceWait;
+        if (proven || slowdown === undefined || slowdown.until <= now)
+            return 0;
+        slowdown.admissions = slowdown.admissions.filter(at => at > now - ACCOUNT_PASSWORD_WINDOW_MS);
+        if (slowdown.admissions.length >= ACCOUNT_PASSWORD_TRIES) {
+            return slowdown.admissions[0] + ACCOUNT_PASSWORD_WINDOW_MS - now;
+        }
+        slowdown.admissions.push(now);
+        return 0;
+    }
+    /** A wrong password; only a database lookup may establish `exists`. */
+    failed(account, now, source = currentPasswordSource(), exists = false) {
+        this.prune(now);
+        const pair = PasswordGuard.pair(account, source);
+        const tries = this.sources.retain(pair, () => ({ failures: 0, lockedUntil: 0, locks: 0, lastAt: now }));
+        tries.failures += 1;
+        tries.lastAt = now;
+        this.nextPruneAt = Math.min(this.nextPruneAt, now + this.policy.maxLockMs);
+        if (tries.failures >= this.policy.failuresBeforeLock) {
+            const lockMs = Math.min(this.policy.maxLockMs, this.policy.firstLockMs * 2 ** tries.locks);
+            tries.lockedUntil = now + lockMs;
+            tries.locks += 1;
+            tries.failures = 0;
             this.onLock?.(account.trim().slice(0, 64), lockMs);
         }
-        this.accounts.set(key, state);
-        // Bounded: the oldest tracked names go first.
-        while (this.accounts.size > TRACKED)
-            this.accounts.delete(this.accounts.keys().next().value);
+        const key = PasswordGuard.key(account);
+        const slowdown = this.slowdowns.retain(key, () => ({ failures: 0, until: 0, lastAt: now, admissions: [], observedAccount: false }));
+        slowdown.observedAccount = exists;
+        slowdown.failures += 1;
+        slowdown.lastAt = now;
+        const over = slowdown.failures - this.policy.failuresBeforeLock;
+        if (over >= 0)
+            slowdown.until = now + Math.min(this.policy.maxLockMs, this.policy.firstSlowMs * 2 ** Math.min(over, 32));
     }
-    succeeded(account) {
-        this.accounts.delete(PasswordGuard.key(account));
+    /** The right password clears individually tracked state; shared overflow buckets must expire by time. */
+    succeeded(account, source = currentPasswordSource()) {
+        const pair = PasswordGuard.pair(account, source);
+        this.sources.clear(pair);
+        this.slowdowns.clear(PasswordGuard.key(account));
     }
+    /** Individually tracked source-and-name entries (at most TRACKED), excluding fixed shared overflow buckets. */
+    get size() { return this.sources.size; }
 }
 const guards = new WeakMap();
 /** The guard for one database (a store): every password check against it counts. */
@@ -59,11 +181,12 @@ export class SourceBudget {
         this.windowMs = windowMs;
     }
     /** Milliseconds until this address may try again (0: it may). */
-    waitFor(source, now) {
-        const recent = (this.sources.get(source) ?? []).filter(at => now - at < this.windowMs);
+    waitFor(address, now) {
+        const recent = (this.sources.get(sourceKey(address)) ?? []).filter(at => now - at < this.windowMs);
         return recent.length < this.tries ? 0 : this.windowMs - (now - recent[0]);
     }
-    failed(source, now) {
+    failed(address, now) {
+        const source = sourceKey(address);
         const recent = (this.sources.get(source) ?? []).filter(at => now - at < this.windowMs);
         recent.push(now);
         this.sources.delete(source);

package/dist/source-key.d.ts

@@ -0,0 +1,2 @@
+/** The budget key for one address, as described above. */
+export declare function sourceKey(source: string): string;

package/dist/source-key.js

@@ -0,0 +1,49 @@
+/**
+ * The key a per-source budget counts under. One IPv6 subscriber is usually handed a whole /64, so keying by the full
+ * address would give one caller 2^64 fresh budgets: a native IPv6 address counts as its /64 (`2001:db8:1:2::/64`),
+ * however it is spelled. IPv4 stays exact, and an IPv4-mapped IPv6 address (`::ffff:203.0.113.5`) is that IPv4 address.
+ * `::1` stays itself, so this computer is never pooled with anything else. The trusted proxy's `fwd:` marker is kept,
+ * and anything that isn't an address ("unknown", a tenant id) is returned unchanged.
+ */
+const IPV4 = /^(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)(\.(25[0-5]|2[0-4]\d|1\d\d|[1-9]?\d)){3}$/;
+/** The eight 16-bit groups of an IPv6 address (brackets and a zone ignored), or null when it isn't one. */
+function ipv6Groups(text) {
+    let bare = text.trim().replace(/^\[(.*)\]$/, "$1").replace(/%.*$/, "").toLowerCase();
+    if (!bare.includes(":") || !/^[0-9a-f:.]+$/.test(bare))
+        return null;
+    // An embedded IPv4 tail is two groups.
+    const tail = /^(.*:)(\d+\.\d+\.\d+\.\d+)$/.exec(bare);
+    if (tail !== null) {
+        if (!IPV4.test(tail[2]))
+            return null;
+        const [a, b, c, d] = tail[2].split(".").map(Number);
+        bare = `${tail[1]}${((a << 8) | b).toString(16)}:${((c << 8) | d).toString(16)}`;
+    }
+    const halves = bare.split("::");
+    if (halves.length > 2)
+        return null;
+    const part = (one) => one === "" ? [] : one.split(":").every(group => /^[0-9a-f]{1,4}$/.test(group)) ? one.split(":") : null;
+    const head = part(halves[0]), rest = halves.length === 2 ? part(halves[1]) : [];
+    if (head === null || rest === null)
+        return null;
+    const missing = 8 - head.length - rest.length;
+    if (halves.length === 2 ? missing < 1 : missing !== 0)
+        return null;
+    return [...head, ...Array(halves.length === 2 ? missing : 0).fill("0"), ...rest].map(group => parseInt(group, 16));
+}
+/** The budget key for one address, as described above. */
+export function sourceKey(source) {
+    if (source.startsWith("fwd:"))
+        return `fwd:${sourceKey(source.slice(4))}`;
+    if (IPV4.test(source))
+        return source;
+    const groups = ipv6Groups(source);
+    if (groups === null)
+        return source;
+    if (groups.slice(0, 5).every(group => group === 0) && groups[5] === 0xffff) {
+        return `${groups[6] >> 8}.${groups[6] & 0xff}.${groups[7] >> 8}.${groups[7] & 0xff}`;
+    }
+    if (groups.slice(0, 7).every(group => group === 0) && groups[7] === 1)
+        return "::1";
+    return `${groups.slice(0, 4).map(group => group.toString(16)).join(":")}::/64`;
+}

package/dist/team-http.d.ts

@@ -2,8 +2,15 @@ import type { IncomingMessage, ServerResponse } from 'node:http';
 import { type TeamActor, type TeamExecute } from './team-contract.js';
 import { type Admission } from './request-budget.js';
 export declare const TEAM_REQUEST_BYTES: number;
+/** How long a password bearer's proof stands on a long /api/team/events stream before its password is checked again.
+ * The account, its revocation and its credential generation are still rechecked on every tick. */
+export declare const TEAM_PASSWORD_REVERIFY_MS: number;
+/** Account role belongs to HTTP authentication; API tokens carry their own scope. */
+export type TeamHttpActor = TeamActor & {
+    role?: 'approver' | 'viewer';
+};
 export type TeamHttpOptions = {
-    authenticate: (request: IncomingMessage) => TeamActor | null | Promise<TeamActor | null>;
+    authenticate: (request: IncomingMessage) => TeamHttpActor | null | Promise<TeamHttpActor | null>;
     /** Recheck the original credential/session and current account, without extending idle expiry. */
     revalidate: (request: IncomingMessage, actor: TeamActor) => boolean;
     authorizeMutation: (request: IncomingMessage, actor: TeamActor) => boolean;

package/dist/team-http.js

@@ -1,6 +1,10 @@
-import { TEAM_OPERATIONS, teamScopeAllows } from './team-contract.js';
+import { adapterPolicy } from "./server/route-policy.js";
+import { TEAM_OPERATIONS, TEAM_MUTATIONS, teamScopeAllows } from './team-contract.js';
 import { limitWords } from './request-budget.js';
 export const TEAM_REQUEST_BYTES = 64 * 1024;
+/** How long a password bearer's proof stands on a long /api/team/events stream before its password is checked again.
+ * The account, its revocation and its credential generation are still rechecked on every tick. */
+export const TEAM_PASSWORD_REVERIFY_MS = 5 * 60_000;
 const failure = (code, message) => ({ version: 1, ok: false, code, message });
 function send(response, status, value, headers = {}) {
     if (response.destroyed || response.writableEnded)
@@ -63,6 +67,9 @@ export async function handleTeamHttp(request, response, options) {
         return reject(401, 'unauthenticated', 'Sign in to continue.');
     if (options.admitAuthenticated && refuseAdmission(options.admitAuthenticated(request, actor)))
         return true;
+    const policyPrincipal = () => ({ caller: request.headers.authorization ? 'bearer' : 'cookie', capability: actor.principal?.scope ?? (actor.role === 'approver' ? 'act' : 'read'), token: actor.principal !== undefined });
+    if (!adapterPolicy(policyPrincipal()).ok)
+        return reject(403, 'read-only', 'Your token reads only. Use an act token for this.');
     const conversationId = url.searchParams.get('conversation') ?? undefined;
     if (url.pathname === '/api/team/events') {
         if (request.method !== 'GET')
@@ -147,7 +154,7 @@ export async function handleTeamHttp(request, response, options) {
         return reject(405, 'method-not-allowed', 'Use GET or POST.');
     if (!options.revalidate(request, actor))
         return reject(401, 'unauthenticated', 'Sign in to continue.');
-    if (!teamScopeAllows(actor, input.operation))
+    if (!adapterPolicy(policyPrincipal(), TEAM_MUTATIONS[input.operation] ? "act" : "read").ok || !teamScopeAllows(actor, input.operation))
         return reject(403, 'read-only', 'Your token reads only. Use an act token for this.');
     try {
         const result = await options.execute(actor, input);

package/dist/teams.js

@@ -1,3 +1,4 @@
+import { adapterPolicy } from "./server/route-policy.js";
 /** Microsoft Teams: the leased delivery loop hosted by the ordinary worker,
  * and the HTTPS receiver the console mounts for the Bot Framework. Teams
  * has no client-initiated socket, so inbound activities arrive over HTTPS
@@ -37,6 +38,8 @@ export async function handleTeamsHttp(request, response, options) {
     const claims = await verifyTeamsToken(request.headers.authorization, credentials.app, options.fetcher ?? fetch);
     if (claims === null)
         return reply(401);
+    if (!adapterPolicy({ caller: "service", capability: "none" }).ok)
+        return reply(403);
     if (refuseAdmission(options.admitTenant(credentials.tenant)))
         return true;
     if (Number(request.headers["content-length"] ?? 0) > TEAMS_ACTIVITY_BYTES)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolroll",
-  "version": "0.9.49",
+  "version": "0.9.51",
   "description": "A control plane for unattended coding agents — queue tasks, walk away, come back to pull requests. Agents build in leased worktrees, never touch your default branch, and interrupt you only for decisions that need a human.",
   "directories": {
     "doc": "docs"