@cortexkit/antigravity-auth-core 3.0.6 → 3.0.8

package/dist/common-auth-embedded/claustrum/availability.d.ts

@@ -0,0 +1,89 @@
+import { ClaustrumConsumerError } from './errors.js';
+export type VaultFailureClass = 'unreachable' | 'answered';
+/**
+ * Codes from claustrum-client's decoder and its subc transport. A retry action
+ * alone is not evidence of an outage: even transient vault refusals must win
+ * over a previously served credential. New codes fail closed until reviewed.
+ */
+export declare const VAULT_FAILURE_CLASSES: Readonly<{
+    ECONNREFUSED: "unreachable";
+    ENOENT: "unreachable";
+    ECONNRESET: "unreachable";
+    EPIPE: "unreachable";
+    ETIMEDOUT: "unreachable";
+    transport_error: "unreachable";
+    unavailable: "unreachable";
+    timeout: "unreachable";
+    route_closed: "unreachable";
+    daemon_draining: "unreachable";
+    connection_closed: "unreachable";
+    connection_dropped: "unreachable";
+    request_deadline: "unreachable";
+    deadline_exceeded_no_drop_observed: "unreachable";
+    module_reloading: "unreachable";
+    module_warming: "unreachable";
+    target_unavailable: "unreachable";
+    module_timeout: "unreachable";
+    invalid_response: "answered";
+    invalid_record_version: "answered";
+    invalid_expiry: "answered";
+    invalid_status: "answered";
+    invalid_params: "answered";
+    ttl_unsatisfiable: "answered";
+    not_found: "answered";
+    enrollment_revoked: "answered";
+    enrollment_invalid: "answered";
+    grant_denied: "answered";
+    credential_unavailable: "answered";
+    needs_reauth: "answered";
+    declined: "answered";
+    disabled: "answered";
+    identity_changed: "answered";
+    closed: "answered";
+    client_closed: "answered";
+    pending_exists: "answered";
+    pending_queue_full: "answered";
+    already_consumed: "answered";
+    superseded: "answered";
+    stale_generation: "answered";
+    missing_identity: "answered";
+    invalid_control_body: "answered";
+    unknown_module: "answered";
+    module_removed: "answered";
+    capability_denied: "answered";
+    unknown_channel: "unreachable";
+    stale_route_epoch: "unreachable";
+    capability_forbidden: "answered";
+    capability_unprovided: "answered";
+    capability_ambiguous: "answered";
+    invalid_capability_identifier: "answered";
+    binary_body_required: "answered";
+    binary_call_requires_call_binary: "answered";
+    corr_exhausted: "answered";
+    late_route_cleanup_failed: "answered";
+    reverse_request_capability_not_declared: "answered";
+    stale_route_handle: "answered";
+    reverse_request_unhandled: "answered";
+    handler_error: "answered";
+    health_error: "answered";
+    duplicate_module_id: "answered";
+    route_rejected: "answered";
+    lock_busy: "answered";
+    owner_invalid: "answered";
+    renewal_failed: "answered";
+    unsupported_platform: "answered";
+    EACCES: "answered";
+    EPERM: "answered";
+    ERR_PRIVATE_FILES_SECURITY: "answered";
+}>;
+/**
+ * An injected adapter may throw this ONLY when its connection/transport is
+ * unreachable, including a failed connect before getScoped. Do not wrap an
+ * adapter shutdown, cancellation, validation error or vault refusal in it.
+ * Its fixed message cannot echo enrollment or credential material, and its
+ * kind stays `unavailable` for callers handling ClaustrumConsumerError.
+ */
+export declare class ClaustrumUnreachableError extends ClaustrumConsumerError {
+    constructor();
+}
+export declare function classifyVaultFailure(error: unknown): VaultFailureClass;

package/dist/common-auth-embedded/claustrum/availability.js

@@ -0,0 +1,106 @@
+import { ClaustrumCredentialError } from '@cortexkit/claustrum-client';
+import { SocketClosedError, SocketTimeoutError, SubcCallError, } from '@cortexkit/subc-client';
+import { ClaustrumConsumerError } from './errors.js';
+/**
+ * Codes from claustrum-client's decoder and its subc transport. A retry action
+ * alone is not evidence of an outage: even transient vault refusals must win
+ * over a previously served credential. New codes fail closed until reviewed.
+ */
+export const VAULT_FAILURE_CLASSES = Object.freeze({
+    ECONNREFUSED: 'unreachable',
+    ENOENT: 'unreachable',
+    ECONNRESET: 'unreachable',
+    EPIPE: 'unreachable',
+    ETIMEDOUT: 'unreachable',
+    transport_error: 'unreachable',
+    unavailable: 'unreachable',
+    timeout: 'unreachable',
+    route_closed: 'unreachable',
+    daemon_draining: 'unreachable',
+    connection_closed: 'unreachable',
+    connection_dropped: 'unreachable',
+    request_deadline: 'unreachable',
+    deadline_exceeded_no_drop_observed: 'unreachable',
+    module_reloading: 'unreachable',
+    module_warming: 'unreachable',
+    target_unavailable: 'unreachable',
+    module_timeout: 'unreachable',
+    invalid_response: 'answered',
+    invalid_record_version: 'answered',
+    invalid_expiry: 'answered',
+    invalid_status: 'answered',
+    invalid_params: 'answered',
+    ttl_unsatisfiable: 'answered',
+    not_found: 'answered',
+    enrollment_revoked: 'answered',
+    enrollment_invalid: 'answered',
+    grant_denied: 'answered',
+    credential_unavailable: 'answered',
+    needs_reauth: 'answered',
+    declined: 'answered',
+    disabled: 'answered',
+    identity_changed: 'answered',
+    closed: 'answered',
+    client_closed: 'answered',
+    pending_exists: 'answered',
+    pending_queue_full: 'answered',
+    already_consumed: 'answered',
+    superseded: 'answered',
+    stale_generation: 'answered',
+    missing_identity: 'answered',
+    invalid_control_body: 'answered',
+    unknown_module: 'answered',
+    module_removed: 'answered',
+    capability_denied: 'answered',
+    unknown_channel: 'unreachable',
+    stale_route_epoch: 'unreachable',
+    capability_forbidden: 'answered',
+    capability_unprovided: 'answered',
+    capability_ambiguous: 'answered',
+    invalid_capability_identifier: 'answered',
+    binary_body_required: 'answered',
+    binary_call_requires_call_binary: 'answered',
+    corr_exhausted: 'answered',
+    late_route_cleanup_failed: 'answered',
+    reverse_request_capability_not_declared: 'answered',
+    stale_route_handle: 'answered',
+    reverse_request_unhandled: 'answered',
+    handler_error: 'answered',
+    health_error: 'answered',
+    duplicate_module_id: 'answered',
+    route_rejected: 'answered',
+    lock_busy: 'answered',
+    owner_invalid: 'answered',
+    renewal_failed: 'answered',
+    unsupported_platform: 'answered',
+    EACCES: 'answered',
+    EPERM: 'answered',
+    ERR_PRIVATE_FILES_SECURITY: 'answered',
+});
+/**
+ * An injected adapter may throw this ONLY when its connection/transport is
+ * unreachable, including a failed connect before getScoped. Do not wrap an
+ * adapter shutdown, cancellation, validation error or vault refusal in it.
+ * Its fixed message cannot echo enrollment or credential material, and its
+ * kind stays `unavailable` for callers handling ClaustrumConsumerError.
+ */
+export class ClaustrumUnreachableError extends ClaustrumConsumerError {
+    constructor() {
+        super('unavailable', 'Claustrum scoped operation unavailable');
+        this.name = 'ClaustrumUnreachableError';
+    }
+}
+export function classifyVaultFailure(error) {
+    if (error instanceof ClaustrumUnreachableError ||
+        error instanceof SocketClosedError ||
+        error instanceof SocketTimeoutError)
+        return 'unreachable';
+    const code = error instanceof ClaustrumCredentialError || error instanceof SubcCallError
+        ? error.code
+        : error instanceof Error && 'code' in error
+            ? error.code
+            : undefined;
+    if (typeof code !== 'string' || !Object.hasOwn(VAULT_FAILURE_CLASSES, code))
+        return 'answered';
+    return VAULT_FAILURE_CLASSES[code];
+}

package/dist/common-auth-embedded/claustrum/consumer.d.ts

@@ -1,10 +1,11 @@
 import type { ClaustrumReporterSource } from '@cortexkit/claustrum-client';
 import type { QuotaObservation } from '../quota/index.js';
 import type { RoutingRow } from '../routing/index.js';
-import { type ClaustrumFamily, type ClaustrumScopedAttempt, type ClaustrumScopedClient, type IdentityParser } from './custody.js';
+import { type ClaustrumFamily, type ClaustrumScopedAttempt, type ClaustrumScopedClient, type IdentityParser, type KeptReceiptState, type VaultGrantReach } from './custody.js';
 import { type ClaustrumLogger } from './errors.js';
 import { type InsulaQuotaOptions } from './insula.js';
 import { type AccountMapper, type QuotaReceipt, type VaultRosterFile } from './roster.js';
+import { type WatchMode } from './watch.js';
 export interface ClaustrumConsumerOptions<Q = QuotaObservation> {
     /**
      * The roster file: one row per vault account (route id, credential id,
@@ -41,6 +42,12 @@ export interface ClaustrumConsumerOptions<Q = QuotaObservation> {
      */
     onRoster?: (roster: VaultRosterFile) => void;
     onError?: (error: unknown) => void;
+    /**
+     * How often `start()` ticks. A tick lists the vault when no vault watch is
+     * open (before it is accepted, or when the vault or the client cannot
+     * watch), and otherwise only every five minutes, as a safety net. A tick
+     * polls insula (at most once a minute) only while its watch is not open.
+     */
     pollIntervalMs?: number;
     setTimeoutImpl?: typeof setTimeout;
     clearTimeoutImpl?: typeof clearTimeout;
@@ -49,6 +56,15 @@ export interface ClaustrumConsumerOptions<Q = QuotaObservation> {
     /** Optional background quota source. In-band readings still use recordQuota. */
     insula?: InsulaQuotaOptions<Q>;
 }
+/**
+ * How a started consumer learns about changes, for logs and status displays.
+ * `insula` is present when the consumer was given an insula source. Never
+ * carries secrets.
+ */
+export interface ClaustrumWatchState {
+    readonly vault: WatchMode;
+    readonly insula?: WatchMode;
+}
 export interface SendOptions {
     /**
      * What kind of request this is (for example `model`, `quota`, `profile`),
@@ -71,9 +87,33 @@ export declare class ClaustrumConsumer<Q = QuotaObservation> {
     constructor(options: ClaustrumConsumerOptions<Q>);
     /** The last committed roster this instance saw, without any I/O. */
     snapshot(): VaultRosterFile | undefined;
+    /**
+     * What this consumer is granted, from its latest discovery, without any I/O.
+     * It explains an empty roster: `grants === 0` means no grant at all, while
+     * `grants > 0` means a grant that reaches no credential (`tuples` names its
+     * selector). Undefined means unknown, never zero: the vault or client is too
+     * old to send it, nothing was discovered yet, or the roster now in memory is
+     * a different view than the one this instance discovered (a peer process
+     * held the discovery lease and its newer roster was served instead).
+     */
+    grantReach(): VaultGrantReach | undefined;
+    /** How this consumer currently learns about changes, without I/O. */
+    watchState(): ClaustrumWatchState;
+    /** Whether any account is using an in-memory outage receipt, without I/O. */
+    keptReceiptState(): KeptReceiptState;
     /** Rows for `/routing`, from the last committed roster. */
     routingRows(): RoutingRow[];
     refresh(): Promise<VaultRosterFile | undefined>;
+    /**
+     * Poll in the background and open the vault and insula watches. Until the
+     * vault watch is accepted, and whenever it is unavailable, every tick lists
+     * the vault exactly as before watches existed. While it is open a tick
+     * lists only when five minutes have passed since the last discovery, since
+     * the watch keeps no history; it still checks `isCustodyActive`, so a switch
+     * to local mode closes the connection as quickly as before. Insula is
+     * polled on the tick only while its own watch is not open. A host not in
+     * vault mode makes no request.
+     */
     start(): void;
     /**
      * Fetch on a background tick, at most once per minute across projects with

package/dist/common-auth-embedded/claustrum/consumer.js

@@ -5,6 +5,7 @@ import { readClaustrumEnrollmentToken } from './enrollment.js';
 import { ClaustrumConsumerError } from './errors.js';
 import { acquireInsulaQuotaSource } from './insula.js';
 import { acceptVaultRoute, declineVaultRoute, readVaultRoster, recordVaultAccountQuota, recordVaultQuota, refreshVaultRoster, vaultRoutingRows, } from './roster.js';
+import { SAFETY_POLL_MS } from './watch.js';
 /**
  * One plugin host's view of its vault accounts. It turns vault credentials
  * into rows for `/routing`, authorizes each physical send with the vault, and
@@ -21,9 +22,18 @@ export class ClaustrumConsumer {
     #connecting;
     #refreshing;
     #roster;
+    /**
+     * The grants named by this instance's latest discovery, with the view that
+     * discovery committed. Memory only: the roster file never carries it.
+     */
+    #grantReach;
     #timer;
     #started = false;
     #insula;
+    #vaultWatch;
+    #releaseInsulaWatch;
+    /** When this instance last completed a discovery, by `now`. */
+    #discoveredAt;
     constructor(options) {
         this.#options = options;
         this.#logger = options.logger ?? createLogger('claustrum');
@@ -86,6 +96,8 @@ export class ClaustrumConsumer {
                     requireAssertion: this.#options.requireAssertion,
                     now: this.#options.now,
                     logger: this.#logger,
+                    setTimeoutImpl: this.#options.setTimeoutImpl,
+                    clearTimeoutImpl: this.#options.clearTimeoutImpl,
                 });
                 if (this.#options.insula && client.insula) {
                     this.#insula = acquireInsulaQuotaSource(client.insula, this.#options.tokenPath);
@@ -102,6 +114,42 @@ export class ClaustrumConsumer {
     snapshot() {
         return this.#roster;
     }
+    /**
+     * What this consumer is granted, from its latest discovery, without any I/O.
+     * It explains an empty roster: `grants === 0` means no grant at all, while
+     * `grants > 0` means a grant that reaches no credential (`tuples` names its
+     * selector). Undefined means unknown, never zero: the vault or client is too
+     * old to send it, nothing was discovered yet, or the roster now in memory is
+     * a different view than the one this instance discovered (a peer process
+     * held the discovery lease and its newer roster was served instead).
+     */
+    grantReach() {
+        const latest = this.#grantReach;
+        return latest && this.#roster?.view === latest.view
+            ? latest.reach
+            : undefined;
+    }
+    /** How this consumer currently learns about changes, without I/O. */
+    watchState() {
+        return Object.freeze({
+            vault: this.#vaultWatch?.mode ?? 'polling',
+            ...(this.#options.insula && {
+                insula: this.#insula?.source.watchMode() ?? 'polling',
+            }),
+        });
+    }
+    /** Close the watches with the connection they belong to. */
+    #stopWatch() {
+        this.#vaultWatch?.close();
+        this.#vaultWatch = undefined;
+        this.#releaseInsulaWatch?.();
+        this.#releaseInsulaWatch = undefined;
+    }
+    /** Whether any account is using an in-memory outage receipt, without I/O. */
+    keptReceiptState() {
+        return (this.#custody?.keptReceiptState() ??
+            Object.freeze({ active: false, since: null }));
+    }
     /** Rows for `/routing`, from the last committed roster. */
     routingRows() {
         return vaultRoutingRows(this.#roster);
@@ -113,6 +161,8 @@ export class ClaustrumConsumer {
         this.#refreshing = (async () => {
             if (!(await this.#active())) {
                 this.#roster = undefined;
+                this.#grantReach = undefined;
+                this.#stopWatch();
                 this.#custody?.close();
                 this.#custody = undefined;
                 this.#insula?.release();
@@ -120,9 +170,17 @@ export class ClaustrumConsumer {
                 return undefined;
             }
             const custody = await this.#getCustody();
+            // Capture the inventory so its grant fields can be kept beside the roster;
+            // the roster file itself never stores them.
+            let discovered;
             const roster = await refreshVaultRoster({
                 path: this.#options.rosterPath,
-                custody,
+                custody: {
+                    discover: async (signal) => {
+                        discovered = await custody.discover(signal);
+                        return discovered;
+                    },
+                },
                 isActive: () => this.#active(),
                 signal: this.#shutdown.signal,
                 projection: () => ({
@@ -135,16 +193,35 @@ export class ClaustrumConsumer {
             this.#assertOpen();
             const changed = roster?.view !== this.#roster?.view;
             this.#roster = roster;
+            custody.retain(roster?.rows ?? []);
+            // Each discovery replaces the previous value, including with unknown. A
+            // refresh that served a peer's roster discovered nothing and leaves it;
+            // grantReach() hides it once the roster's view no longer matches.
+            if (discovered && roster?.view !== undefined)
+                this.#grantReach = discovered.grantReach
+                    ? { view: roster.view, reach: discovered.grantReach }
+                    : undefined;
             // Notify on view changes only: subscribers rewrite shared state on each
             // notification, and the poll runs every few seconds.
             if (roster && changed)
                 this.#options.onRoster?.(roster);
+            this.#discoveredAt = (this.#options.now ?? Date.now)();
             return roster;
         })().finally(() => {
             this.#refreshing = undefined;
         });
         return this.#refreshing;
     }
+    /**
+     * Poll in the background and open the vault and insula watches. Until the
+     * vault watch is accepted, and whenever it is unavailable, every tick lists
+     * the vault exactly as before watches existed. While it is open a tick
+     * lists only when five minutes have passed since the last discovery, since
+     * the watch keeps no history; it still checks `isCustodyActive`, so a switch
+     * to local mode closes the connection as quickly as before. Insula is
+     * polled on the tick only while its own watch is not open. A host not in
+     * vault mode makes no request.
+     */
     start() {
         if (this.#started)
             return;
@@ -152,8 +229,10 @@ export class ClaustrumConsumer {
         this.#started = true;
         const tick = async () => {
             try {
-                await this.refresh();
+                if (await this.#listDue())
+                    await this.refresh();
                 await this.refreshInsulaQuota();
+                this.#openWatch();
             }
             catch (error) {
                 if (!this.#shutdown.signal.aborted)
@@ -172,6 +251,53 @@ export class ClaustrumConsumer {
         };
         void tick();
     }
+    /** Whether a background tick must list the vault now. */
+    async #listDue() {
+        if (this.#vaultWatch?.mode !== 'watching')
+            return true;
+        const now = (this.#options.now ?? Date.now)();
+        if (this.#discoveredAt === undefined ||
+            now - this.#discoveredAt >= SAFETY_POLL_MS)
+            return true;
+        // refresh() is what closes the connection when the host left vault mode.
+        return !(await this.#active());
+    }
+    /**
+     * Open the vault and insula watches once a vault connection exists. Only
+     * reached in vault mode: a host in local mode never connects.
+     */
+    #openWatch() {
+        const custody = this.#custody;
+        if (this.#shutdown.signal.aborted || !custody)
+            return;
+        // The same entry point a host without a consumer uses, so both apply
+        // notices, refusals and outages alike.
+        this.#vaultWatch ??= custody.watchRoster({
+            view: () => this.#roster?.view,
+            // The existing discovery, so a watched change commits the roster and
+            // re-applies it to kept receipts exactly as a poll does. A refresh
+            // already in flight may have listed before the change was announced,
+            // so wait for it and list again.
+            onView: async () => {
+                while (this.#refreshing)
+                    await this.#refreshing.catch(() => { });
+                await this.refresh();
+            },
+            // Custody has dropped kept receipts, as a poll meeting the same
+            // refusal from list_scoped would.
+            onRefused: (error) => this.#options.onError?.(error),
+            onError: (error) => {
+                if (!this.#shutdown.signal.aborted)
+                    this.#options.onError?.(error);
+            },
+        });
+        if (this.#options.insula && this.#insula && !this.#releaseInsulaWatch)
+            this.#releaseInsulaWatch = this.#insula.source.watch({
+                provider: this.#options.insula.provider,
+                setTimeoutImpl: this.#options.setTimeoutImpl,
+                clearTimeoutImpl: this.#options.clearTimeoutImpl,
+            });
+    }
     /**
      * Fetch on a background tick, at most once per minute across projects with
      * the same daemon and enrollment token path. Admission must use the cache
@@ -246,20 +372,33 @@ export class ClaustrumConsumer {
     async authorize(routeId, signal) {
         this.#assertOpen(signal);
         const roster = this.#roster ?? (await this.#wait(this.refresh(), signal));
-        if (!roster || !(await this.#active()))
+        if (!roster || !(await this.#active())) {
+            this.#custody?.close();
+            this.#custody = undefined;
+            this.#stopWatch();
+            this.#insula?.release();
+            this.#insula = undefined;
             throw new ClaustrumConsumerError('not-active', 'Claustrum scoped custody is not active');
+        }
         const current = await readVaultRoster(this.#options.rosterPath);
         this.#assertOpen(signal);
         const observed = roster.rows.find((row) => row.routeId === routeId);
         const configured = current?.rows.find((row) => row.routeId === routeId);
-        if (configured && !configured.enabled)
+        if (configured && !configured.enabled) {
+            if (observed)
+                this.#custody?.forget(observed.credentialId);
             throw new ClaustrumConsumerError('route-declined', 'Claustrum route is disabled');
+        }
         if (!observed ||
             !configured ||
             configured.state !== 'active' ||
             configured.credentialId !== observed.credentialId ||
-            configured.accountIdentity !== observed.accountIdentity)
+            configured.accountIdentity !== observed.accountIdentity ||
+            configured.credentialType !== observed.credentialType) {
+            if (observed)
+                this.#custody?.forget(observed.credentialId);
             throw new ClaustrumConsumerError('route-unavailable', 'Claustrum route is disabled, removed or changed');
+        }
         const custody = await this.#wait(this.#getCustody(), signal);
         const combined = combineAbortSignals([
             this.#shutdown.signal,
@@ -272,7 +411,7 @@ export class ClaustrumConsumer {
                 ...(configured.accountIdentity !== undefined && {
                     accountIdentity: configured.accountIdentity,
                 }),
-            }, combined.signal);
+            }, combined.signal, routeId);
         }
         finally {
             combined.dispose();
@@ -296,6 +435,10 @@ export class ClaustrumConsumer {
         const signal = options.signal;
         let served = await this.authorize(routeId, signal);
         let response = await dispatch(served, signal);
+        if (response.status === 401 && served.fromKeptReceipt) {
+            await this.reportFailure(served, 401, options.reporterSource ?? 'direct');
+            return response;
+        }
         if (response.status === 401 && !signal?.aborted) {
             let current;
             try {
@@ -330,6 +473,7 @@ export class ClaustrumConsumer {
         this.#assertOpen();
         await declineVaultRoute(this.#options.rosterPath, routeId);
         this.#roster = await readVaultRoster(this.#options.rosterPath);
+        this.#custody?.retain(this.#roster?.rows ?? []);
     }
     async accept(routeId) {
         this.#assertOpen();
@@ -385,9 +529,11 @@ export class ClaustrumConsumer {
         if (this.#timer)
             (this.#options.clearTimeoutImpl ?? clearTimeout)(this.#timer);
         this.#timer = undefined;
+        this.#stopWatch();
         this.#custody?.close();
         this.#insula?.release();
         this.#insula = undefined;
         this.#roster = undefined;
+        this.#grantReach = undefined;
     }
 }