@wrongstack/core 0.297.0 → 0.298.1

package/dist/coordination/mail-tools.d.ts

@@ -75,12 +75,12 @@ export declare function makeMailSendTool(opts?: MailToolsOptions): {
         required: string[];
     };
     execute(input: unknown, ctx: Context): Promise<{
-        ok: boolean;
-        error: string;
         messageId?: never;
-        from?: never;
         to?: never;
         summary?: never;
+        ok: boolean;
+        error: string;
+        from?: never;
     } | {
         error?: never;
         ok: boolean;

package/dist/coordination/mailbox-credential-store.d.ts

@@ -69,11 +69,18 @@ export interface CredentialValidation {
     credential?: MailboxCredential | undefined;
     reason?: string | undefined;
 }
+/** Verification result with the verifier hash stripped — safe for IPC/API. */
+export interface RedactedCredentialValidation {
+    valid: boolean;
+    /** The credential without the verifier or algorithm. */
+    credential?: RedactedMailboxCredential | undefined;
+    reason?: string | undefined;
+}
 /** Minimal verification contract shared by file-backed and remote stores. */
 export interface MailboxCredentialVerifier {
     load(): Promise<void>;
-    verify(credentialId: string, secret: string): CredentialValidation | Promise<CredentialValidation>;
-    verifyPersisted(credentialId: string, secret: string): Promise<CredentialValidation>;
+    verify(credentialId: string, secret: string): RedactedCredentialValidation | Promise<RedactedCredentialValidation>;
+    verifyPersisted(credentialId: string, secret: string): Promise<RedactedCredentialValidation>;
 }
 /** Default credential file name. */
 export declare const CREDENTIAL_STORE_FILE = "_mailbox_credentials.json";
@@ -87,6 +94,19 @@ export declare function createMailboxCredential(opts: IssueCredentialOptions, no
     secret: string;
 };
 /** Verify an opaque secret against a stored credential snapshot. */
+/**
+ * A credential safe to hand to a caller: everything except the authenticator.
+ *
+ * WS-025: `credential_get` and `credential_list` returned the full record,
+ * `verifier` included. That value is an HMAC over the secret, so it is not
+ * directly replayable — but it is the thing the credential is checked against,
+ * it has no purpose outside verification, and shipping it means any future
+ * change to how secrets are minted (or one weak secret) turns a read into an
+ * offline attack. Read surfaces should return this shape.
+ */
+export type RedactedMailboxCredential = Omit<MailboxCredential, 'verifier' | 'verifierAlgorithm'>;
+/** Strip the authenticator from a credential bound for a caller. */
+export declare function redactMailboxCredential(credential: MailboxCredential): RedactedMailboxCredential;
 export declare function verifyMailboxCredential(credential: MailboxCredential | undefined, secret: string, now?: number): CredentialValidation;
 /**
  * Resolve the credential store file path from the project directory.

package/dist/coordination/mailbox-credential-throttle.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Failed-attempt throttle for mailbox credential verification.
+ *
+ * WS-025: `credential_verify` takes a `credentialId` and a `secret` and answers
+ * whether they match, with no limit on how often it will answer. That is a
+ * guessing oracle: any caller that reaches the mailbox — the MCP admin tool,
+ * the project IPC daemon, an in-process caller — can grind secrets for a
+ * credential id it observed, as fast as the socket allows.
+ *
+ * The secret is 32 random bytes, so exhaustive search is not the threat.
+ * A weak or reused secret, a partially-leaked one, or a future change to how
+ * secrets are minted is — and an unbounded oracle also silently turns every
+ * such mistake into a remotely exploitable one, and burns CPU while doing it.
+ *
+ * The limiter lives at the store layer rather than in one adapter so every
+ * surface inherits it; a throttle wired into a single caller is a throttle
+ * with a documented bypass.
+ *
+ * In-memory and per-process, which matches the deployment: one mailbox daemon
+ * owns a project. A restart clears the counters — acceptable, because
+ * restarting the daemon is not something a remote caller can do at will, and
+ * persisting failure counts would put an attacker-controlled write on the
+ * unauthenticated path.
+ *
+ * @module coordination/mailbox-credential-throttle
+ */
+/** Failed attempts allowed per credential id before the cooldown starts. */
+export declare const CREDENTIAL_VERIFY_MAX_FAILURES = 10;
+/** Window over which failures accumulate. */
+export declare const CREDENTIAL_VERIFY_WINDOW_MS = 60000;
+/** How long a credential id stays refused once the limit is hit. */
+export declare const CREDENTIAL_VERIFY_COOLDOWN_MS = 60000;
+export interface ThrottleDecision {
+    allowed: boolean;
+    /** Milliseconds until the next attempt is permitted; 0 when allowed. */
+    retryAfterMs: number;
+}
+export declare class CredentialVerifyThrottle {
+    private readonly maxFailures;
+    private readonly windowMs;
+    private readonly cooldownMs;
+    private readonly records;
+    constructor(maxFailures?: number, windowMs?: number, cooldownMs?: number);
+    /** Is this credential id allowed another attempt right now? */
+    check(credentialId: string, now?: number): ThrottleDecision;
+    /** Record a failed verification. Starts the cooldown once the limit is hit. */
+    recordFailure(credentialId: string, now?: number): void;
+    /**
+     * Clear the counter after a successful verification. A legitimate holder who
+     * fluffed a few attempts is not left in a cooldown they cannot exit.
+     */
+    recordSuccess(credentialId: string): void;
+    /** Test seam. */
+    reset(): void;
+    private evictIfFull;
+}
+/**
+ * Process-wide limiter. One mailbox owns a project inside one process, so a
+ * shared instance is the correct scope — and it means a caller cannot dodge
+ * the throttle by reaching the same mailbox through a different surface.
+ */
+export declare const credentialVerifyThrottle: CredentialVerifyThrottle;
+//# sourceMappingURL=mailbox-credential-throttle.d.ts.map

package/dist/coordination/mailbox-project-server-client.d.ts

@@ -20,6 +20,13 @@ export declare class MailboxProjectServerConnection {
     private connectResolve;
     private connectReject;
     private nextId;
+    /**
+     * WS-027: read from the daemon's owner-only metadata file, never from the
+     * `hello` frame — the daemon sends `hello` to every socket that connects, so
+     * a token carried there would be handed to exactly the caller it must
+     * refuse (the mistake WS-028 found in the SAGE daemon).
+     */
+    private authToken;
     private heartbeatTimer;
     private readonly pending;
     private readonly eventListeners;
@@ -52,6 +59,15 @@ export declare class MailboxProjectServerConnection {
     private ensureConnected;
     private connectWithElection;
     private connectOnce;
+    /**
+     * The token, read lazily and re-read while still unknown.
+     *
+     * The daemon starts listening before it writes its metadata (endpoint
+     * ownership has to be won first, and clobbering another daemon's file to win
+     * it would be worse), so a client that connects in that window sees no file
+     * yet. Re-reading until one is found costs a single small `readFileSync`.
+     */
+    private currentAuthToken;
     private request;
     private onData;
     private onMessage;

package/dist/coordination/mailbox-project-server-protocol.d.ts

@@ -1,8 +1,23 @@
+import type { IssueCredentialOptions, MailboxCredential, RedactedMailboxCredential } from './mailbox-credential-store.js';
 import type { MailboxEvent } from './mailbox-events.js';
-import type { CredentialValidation, IssueCredentialOptions, MailboxCredential } from './mailbox-credential-store.js';
 import type { AgentHeartbeatInput, AgentRegistrationInput, AutoCompactOptions, AutoCompactResult, ClientHeartbeatInput, ClientRegistrationInput, ClientStatus, MailboxAckBatchInput, MailboxAckInput, MailboxAgentStatus, MailboxMessage, MailboxQuery, MailboxSendInput, PurgeOptions, PurgeResult } from './mailbox-types.js';
-export declare const MAILBOX_PROJECT_SERVER_PROTOCOL_VERSION = 3;
+/**
+ * Wire protocol version. Embedded in the IPC endpoint path (see
+ * `mailbox-project-server-endpoint.ts`), so a bump migrates clients to a fresh
+ * socket and lets the `hello` handshake detect client/daemon skew loudly.
+ *
+ * v4: `authToken` became required on every `request` and `shutdown` (WS-027).
+ * That is a breaking wire change — a pre-WS-027 client sends no token and would
+ * fail every call with `UnauthorizedMailboxRequest` against a gated daemon.
+ * Bumping the path keeps old clients on the old endpoint (where they spawn a
+ * matching old daemon) instead of silently breaking against a new one.
+ */
+export declare const MAILBOX_PROJECT_SERVER_PROTOCOL_VERSION = 4;
 export declare const MAILBOX_PROJECT_SERVER_MAX_FRAME_CHARS: number;
+/**
+ * What the daemon tells a connecting client about itself. Carries NO secret —
+ * see {@link MailboxProjectServerMetadata}.
+ */
 export interface MailboxProjectServerInfo {
     protocolVersion: number;
     pid: number;
@@ -10,6 +25,14 @@ export interface MailboxProjectServerInfo {
     endpoint: string;
     startedAt: string;
 }
+/**
+ * The daemon's on-disk metadata file, written 0600. The auth token exists
+ * here and nowhere else — never in the `hello` frame, which the daemon sends
+ * to every socket that connects (the mistake WS-028 found in the SAGE daemon).
+ */
+export interface MailboxProjectServerMetadata extends MailboxProjectServerStatus {
+    authToken: string;
+}
 export interface MailboxProjectServerStatus extends MailboxProjectServerInfo {
     clients: number;
     pendingRequests: number;
@@ -163,7 +186,11 @@ export interface MailboxServerOperations {
             credentialId: string;
             secret: string;
         };
-        result: CredentialValidation;
+        result: {
+            valid: boolean;
+            credential?: RedactedMailboxCredential | undefined;
+            reason?: string | undefined;
+        };
     };
     credentialRevoke: {
         args: {
@@ -187,11 +214,11 @@ export interface MailboxServerOperations {
         args: {
             credentialId: string;
         };
-        result: MailboxCredential | null;
+        result: RedactedMailboxCredential | null;
     };
     credentialList: {
         args: Record<string, never>;
-        result: MailboxCredential[];
+        result: RedactedMailboxCredential[];
     };
     credentialStatusCounts: {
         args: Record<string, never>;
@@ -204,12 +231,23 @@ export type MailboxProjectServerClientMessage = {
     id: number;
     op: MailboxServerOperationName;
     args: unknown;
+    /**
+     * WS-027: this daemon owns the project's message bus and its credential
+     * store, and it had no handshake credential at all — any process that
+     * could open the socket could send mail as any agent, read every
+     * message, and issue or revoke credentials. The socket is 0600, but
+     * that only excludes OTHER users, and on Windows it does not even do
+     * that. The token comes from the daemon's owner-only metadata file.
+     */
+    authToken?: string | undefined;
 } | {
     type: 'heartbeat';
 } | {
     type: 'shutdown';
     id: number;
     reason?: string | undefined;
+    /** Gated for the same reason as `request` — this stops the bus. */
+    authToken?: string | undefined;
 };
 /** Runtime boundary guard for untrusted newline-delimited IPC frames. */
 export declare function isMailboxProjectServerClientMessage(value: unknown): value is MailboxProjectServerClientMessage;