@cortexkit/antigravity-auth-core 3.0.11 → 3.0.13

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

@@ -4,6 +4,7 @@ import { ClaustrumUnreachableError, classifyVaultFailure, } from './availability
 import { readClaustrumEnrollmentToken } from './enrollment.js';
 import { ClaustrumConsumerError } from './errors.js';
 import { CUSTODY_PLACEHOLDER_PREFIX } from './host-slot.js';
+import { drainShutdown, shutdownWarning } from './shutdown.js';
 import { ScopedRosterWatch, } from './watch.js';
 /** Only a new version of the same account may replace an in-flight 401. */
 export function isScopedCredentialRotation(served, current) {
@@ -79,15 +80,56 @@ function accessTokenFromMaterial(material) {
     return access;
 }
 function credentialTypeOf(row, family) {
+    const notMine = { kind: 'not-mine' };
     if (!row.operations.includes('read'))
-        return undefined;
+        return notMine;
     if (!row.categories.includes(family.category))
-        return undefined;
+        return notMine;
+    if (row.credentialType !== 'oauth' && row.credentialType !== 'api_key')
+        return notMine;
+    if ('classify' in family) {
+        // Older clients omit these facts entirely; do not call a policy that needs them.
+        const facts = {
+            credentialId: row.id,
+            credentialType: row.credentialType,
+            categories: row.categories,
+            refreshAdapter: row.refreshAdapter,
+            ...rowFactsOf(row),
+        };
+        if (facts.providerIds === undefined)
+            return { kind: 'refused', code: 'unmapped' };
+        try {
+            const result = family.classify(facts);
+            if (result.kind === 'not-mine')
+                return notMine;
+            if (result.kind === 'mine' && typeof result.member === 'string')
+                return { kind: 'mine', type: row.credentialType, member: result.member };
+            if (result.kind === 'refused' &&
+                typeof result.code === 'string' &&
+                /^[a-z][a-z0-9-]{0,31}$/.test(result.code) &&
+                !result.code.includes('\n') &&
+                family.refusalCodes.includes(result.code))
+                return { kind: 'refused', code: result.code };
+        }
+        catch {
+            // A classifier error may contain vault data; expose only a fixed code.
+        }
+        return { kind: 'refused', code: 'unclassified' };
+    }
     if (row.credentialType === 'oauth')
-        return row.refreshAdapter === family.refreshAdapter ? 'oauth' : undefined;
+        return row.refreshAdapter === family.refreshAdapter
+            ? { kind: 'mine', type: 'oauth' }
+            : notMine;
     if (row.credentialType === 'api_key' && family.apiKeys)
-        return row.refreshAdapter === undefined ? 'api_key' : undefined;
-    return undefined;
+        return row.refreshAdapter === undefined
+            ? { kind: 'mine', type: 'api_key' }
+            : notMine;
+    return notMine;
+}
+/** Structural access keeps the public facts independent of client declarations. */
+function rowFactsOf(row) {
+    const metadata = row;
+    return { providerIds: metadata.providerIds, authMethod: metadata.authMethod };
 }
 /**
  * The grants named in the vault's list reply, or undefined when it names none.
@@ -136,6 +178,9 @@ export class ClaustrumScopedCustody {
     /** The view of the last successful `discover()`, for `watchRoster`. */
     #discoveredView;
     #watches = new Set();
+    #tokenReads = new Set();
+    #warnShutdown;
+    #disposing;
     constructor(options) {
         const tokenPath = options.tokenPath;
         if (options.readToken) {
@@ -153,6 +198,7 @@ export class ClaustrumScopedCustody {
         this.#requireAssertion = options.requireAssertion ?? false;
         this.#now = options.now ?? Date.now;
         this.#logger = options.logger ?? defaultLogger;
+        this.#warnShutdown = shutdownWarning(this.#logger);
         this.#setTimeout = options.setTimeoutImpl ?? setTimeout;
         this.#clearTimeout = options.clearTimeoutImpl ?? clearTimeout;
     }
@@ -220,7 +266,15 @@ export class ClaustrumScopedCustody {
     }
     async #token(signal) {
         this.#check(signal);
-        const value = await this.#readToken();
+        const pending = this.#readToken();
+        this.#tokenReads.add(pending);
+        let value;
+        try {
+            value = await pending;
+        }
+        finally {
+            this.#tokenReads.delete(pending);
+        }
         this.#check(signal);
         if (!/^[0-9a-f]{64}$/.test(value.token) ||
             !Number.isSafeInteger(value.token_generation) ||
@@ -299,17 +353,32 @@ export class ClaustrumScopedCustody {
             throw error;
         }
         const skipped = [];
+        const refused = [];
+        let notMine = 0;
         const candidates = [];
         const counts = new Map();
         for (const row of inventory.rows) {
-            const type = credentialTypeOf(row, this.#family);
-            if (!type)
+            const classified = credentialTypeOf(row, this.#family);
+            if (classified.kind === 'not-mine') {
+                notMine++;
+                continue;
+            }
+            if (classified.kind === 'refused') {
+                refused.push({
+                    ...(row.id.trim() && { credentialId: row.id }),
+                    code: classified.code,
+                });
                 continue;
-            candidates.push({ row, type });
+            }
+            candidates.push({
+                row,
+                type: classified.type,
+                ...(classified.member !== undefined && { member: classified.member }),
+            });
             counts.set(row.id, (counts.get(row.id) ?? 0) + 1);
         }
         const credentials = [];
-        for (const { row, type } of candidates) {
+        for (const { row, type, member } of candidates) {
             let reason;
             if (!row.id.trim())
                 reason = 'empty credential id';
@@ -320,12 +389,17 @@ export class ClaustrumScopedCustody {
             else if (!row.state.trim())
                 reason = 'empty state';
             if (reason) {
-                skipped.push({ ...(row.id.trim() && { credentialId: row.id }), reason });
+                skipped.push({
+                    ...(row.id.trim() && { credentialId: row.id }),
+                    ...(member !== undefined && { member }),
+                    reason,
+                });
                 continue;
             }
             credentials.push(Object.freeze({
                 credentialId: row.id,
                 credentialType: type,
+                ...(member !== undefined && { member }),
                 ...(row.accountId !== undefined && {
                     accountIdentity: row.accountId,
                 }),
@@ -341,6 +415,10 @@ export class ClaustrumScopedCustody {
             view: inventory.view,
             credentials: Object.freeze(credentials),
             skipped: Object.freeze(skipped),
+            ...('classify' in this.#family && {
+                refused: Object.freeze(refused),
+                notMine,
+            }),
             ...(grantReach && { grantReach }),
         };
     }
@@ -646,4 +724,10 @@ export class ClaustrumScopedCustody {
         this.#kept.clear();
         this.#client.close();
     }
+    /** Stop immediately; allow token reads 2 s and share an owner's timeout warning. */
+    async dispose(onTimeout = this.#warnShutdown) {
+        this.close();
+        this.#disposing ??= drainShutdown(this.#tokenReads, onTimeout);
+        await this.#disposing;
+    }
 }

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

@@ -3,6 +3,7 @@ import { constants as fsConstants } from 'node:fs';
 import { chmod, mkdir, open, readFile, realpath, rename, stat, unlink, } from 'node:fs/promises';
 import { basename, dirname, extname, isAbsolute, join, resolve, } from 'node:path';
 import { ClaustrumCredentialError, ClaustrumClient as ClaustrumWireClient, writeEnrollmentTokenFile, } from '@cortexkit/claustrum-client';
+import { FileReadCache } from '../fs/file-read-cache.js';
 import { acquireRefreshFileLock } from '../fs/index.js';
 import { ensurePrivateDirectory as ensureWindowsDirectory, PrivateFileError, readPrivateText, verifySafeDirectory, windowsPrivateFiles, writePrivateAtomic, } from '../fs/private-files.js';
 import { ClaustrumConsumerError } from './errors.js';
@@ -402,32 +403,56 @@ async function writeStateAtomic(path, state, ancestorOptions = {}) {
             await unlink(temporary).catch(() => { });
     }
 }
+const enrollmentStatusCache = new FileReadCache();
 export async function readClaustrumEnrollmentStatus(paths, proposedName) {
+    // Windows ACL, owner and ancestry checks are not represented by stat identity.
+    // Keep the native private-file validation and full read on every call there.
+    const result = windowsPrivateFiles
+        ? await readEnrollmentStatus(paths, proposedName)
+        : await enrollmentStatusCache.read([paths.tokenPath, paths.statePath], async ([tokenPath = paths.tokenPath, statePath = paths.statePath]) => readEnrollmentStatus({ tokenPath, statePath }, proposedName), (identities) => {
+            // Recheck the current effective user as well as mode and regular-file kind.
+            // lstat probes also prevent a link to the old inode from becoming a hit.
+            for (const metadata of identities)
+                if (metadata !== 'absent')
+                    validateReadableSecretFile(metadata);
+        });
+    const status = { ...result.status };
+    if (result.usesProposedName && status.state === 'approved')
+        status.proposedName = proposedName;
+    return status;
+}
+async function readEnrollmentStatus(paths, proposedName) {
     const tokenValue = await readBoundedJson(paths.tokenPath);
     const token = tokenValue === undefined ? undefined : decodeTokenFile(tokenValue);
     const stateValue = await readBoundedJson(paths.statePath);
     const state = stateValue === undefined ? undefined : decodeEnrollmentState(stateValue);
     if (token) {
         return {
-            state: 'approved',
-            proposedName: state?.proposedName ?? proposedName,
-            ...(state?.phase === 'approved' &&
-                state.approvedName !== undefined && {
-                approvedName: state.approvedName,
-            }),
-            tokenGeneration: token.token_generation,
+            usesProposedName: state === undefined,
+            status: {
+                state: 'approved',
+                proposedName: state?.proposedName ?? proposedName,
+                ...(state?.phase === 'approved' &&
+                    state.approvedName !== undefined && {
+                    approvedName: state.approvedName,
+                }),
+                tokenGeneration: token.token_generation,
+            },
         };
     }
     if (!state)
-        return { state: 'idle' };
+        return { status: { state: 'idle' }, usesProposedName: false };
     if (state.phase === 'approved') {
         return {
-            state: 'blocked',
-            proposedName: state.proposedName,
-            code: 'missing_token',
+            usesProposedName: false,
+            status: {
+                state: 'blocked',
+                proposedName: state.proposedName,
+                code: 'missing_token',
+            },
         };
     }
-    return statusFromState(state);
+    return { status: statusFromState(state), usesProposedName: false };
 }
 /**
  * Resolve the host's account mode from its enrollment files. It never changes

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

@@ -4,7 +4,7 @@
  * `code`, a `class` and an `action`), so callers can tell the vault's verdict
  * apart from a check made on this side.
  */
-export type ClaustrumConsumerFailureKind = 'closed' | 'not-enrolled' | 'invalid-token' | 'unavailable' | 'identity-changed' | 'identity-unasserted' | 'insufficient-validity' | 'invalid-material' | 'not-active' | 'route-unavailable' | 'route-declined' | 'no-receipt' | 'unsafe-file' | 'invalid-state' | 'wrong-consumer' | 'roster-busy' | 'host-slot-login' | 'host-slot-placeholder' | 'placeholder-refresh';
+export type ClaustrumConsumerFailureKind = 'closed' | 'not-enrolled' | 'invalid-token' | 'unavailable' | 'identity-changed' | 'identity-unasserted' | 'insufficient-validity' | 'invalid-material' | 'not-active' | 'route-unavailable' | 'route-declined' | 'no-receipt' | 'unsafe-file' | 'invalid-state' | 'wrong-consumer' | 'roster-busy' | 'host-slot-login' | 'host-slot-placeholder' | 'placeholder-refresh' | 'invalid-order';
 export declare class ClaustrumConsumerError extends Error {
     readonly kind: ClaustrumConsumerFailureKind;
     constructor(kind: ClaustrumConsumerFailureKind, message: string);

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

@@ -0,0 +1,195 @@
+import type { QuotaObservation } from '../quota/index.js';
+import { type ClaustrumConsumer } from './consumer.js';
+import { type ClassifyingClaustrumFamily, type ClaustrumScopedClient, ClaustrumScopedCustody, type IdentityParser, type KeptReceiptState, type VaultGrantReach } from './custody.js';
+import { type ClaustrumLogger } from './errors.js';
+import { type AccountMapper, type VaultRosterFile } from './roster.js';
+import { type WatchMode } from './watch.js';
+export interface ClaustrumDiscoveryHubOptions {
+    /**
+     * The plugin's owner-only state directory. Member rosters live under
+     * `<stateDir>/rosters/<hostGeneration>/<fingerprint>/<provider>.json`.
+     */
+    stateDir: string;
+    /**
+     * Which host generation this process runs (for example `opencode1`,
+     * `opencode2` or `pi`). Hosts that classify rows differently keep separate
+     * roster directories.
+     */
+    hostGeneration: string;
+    /**
+     * Everything the plugin's classifier decides with, as plain JSON: the
+     * exact object it hands the classifier (its version, the supported-table
+     * entries, the reserved provider set and every host fact it reads). The
+     * hub hashes it, with the member set, `routePrefix` and `mapAccount`, into
+     * the roster key, so processes whose classifiers or projections could
+     * disagree never share a roster file. Configuration that `mapAccount`
+     * reads, beyond its own source text, belongs here too.
+     */
+    classifierInput: unknown;
+    /**
+     * Every provider the plugin serves on this host, fixed for the hub's life.
+     * Each is the `member` a classified row names and a roster file name, so
+     * it is lowercase ASCII: letters, digits, `.`, `_` and `-`.
+     */
+    members: readonly string[];
+    /** Prefix of every member's vault route ids; part of the roster key. */
+    routePrefix?: string;
+    /**
+     * How every member presents a vault credential (the credential names its
+     * member). Part of the roster key by its source text.
+     */
+    mapAccount?: AccountMapper;
+    /** This host's enrollment token, written by setup. */
+    tokenPath: string;
+    /**
+     * The plugin's classifying family. A legacy `ClaustrumFamily` names no
+     * member for any row and is refused.
+     */
+    family: ClassifyingClaustrumFamily<string>;
+    connect: () => Promise<ClaustrumScopedClient>;
+    /**
+     * How long one `connect()` attempt may take before the hub treats the vault
+     * as unreachable (default 10 s, as `ClaustrumConsumerOptions`). The hub's
+     * connect is shared by every member waiting for a lease, so an attempt that
+     * never settles would hold every one of them; after the limit they get an
+     * unreachable error and the next acquire connects again.
+     */
+    connectTimeoutMs?: number;
+    /**
+     * Whether the plugin takes its accounts from the vault. Read from local
+     * state only, never from the vault: on every hub tick, and when a member
+     * refreshes or authorizes. The first false read revokes every lease,
+     * closes the connection and clears every member.
+     */
+    isCustodyActive?: () => boolean | Promise<boolean>;
+    parseIdentity?: IdentityParser;
+    /** As `ClaustrumConsumerOptions.requireAssertion`, for every member. */
+    requireAssertion?: boolean;
+    /**
+     * How often the hub ticks (default 5 s). A tick reads authority, installs
+     * member roster files another writer changed under the same view, and
+     * lists when a list is due: on every tick while no vault watch is open,
+     * when a pending member's retry is due (a member the last list did not
+     * commit, retried with a backoff), otherwise every five minutes as a
+     * safety net.
+     */
+    pollIntervalMs?: number;
+    setTimeoutImpl?: typeof setTimeout;
+    clearTimeoutImpl?: typeof clearTimeout;
+    now?: () => number;
+    logger?: ClaustrumLogger;
+    /**
+     * Errors of the hub's own tick, list and watch. A failed list and a vault
+     * refusal of the watch also reach every member's `onError`.
+     */
+    onError?: (error: unknown) => void;
+}
+/**
+ * What one hub member takes: only what is per provider. The hub owns the
+ * roster path, the enrollment token, the family, the connection, the
+ * authority check, the poll timer and the projection inputs that are part of
+ * the roster key (`routePrefix`, `mapAccount`), so none of them can be given
+ * here. The type parameter matches the consumer `member` returns; members
+ * have no insula source.
+ */
+export interface ClaustrumHubMemberOptions<_Q = QuotaObservation> {
+    /**
+     * Ids of the plugin's local pool rows; no vault route id may equal one.
+     * Read on every projection and install, so it may change at any time.
+     */
+    reservedRouteIds?: () => Iterable<string>;
+    /** As `ClaustrumConsumerOptions.onRoster`: once per change of view. */
+    onRoster?: (roster: VaultRosterFile) => void;
+    /** This member's own failures, such as a roster commit that failed. */
+    onError?: (error: unknown) => void;
+    logger?: ClaustrumLogger;
+}
+/** What a lease may do with the shared custody. */
+export type ClaustrumLeasedCustody = Pick<ClaustrumScopedCustody, 'authorize' | 'reportFailure' | 'forget' | 'keptReceiptState'>;
+/**
+ * One acquisition of the hub's shared custody. `custody` throws `closed`
+ * after `release()`, and once the connection it belongs to ended for any
+ * reason, vault mode going off included. `release()` is idempotent.
+ */
+export interface CustodyLease {
+    readonly custody: ClaustrumLeasedCustody;
+    /** The connection this lease belongs to; each new connection counts up. */
+    readonly generation: number;
+    release(): void;
+}
+/** The rows the hub's last complete discovery refused or left to others. */
+export interface ClaustrumHubRefusals {
+    readonly view: string;
+    readonly refused: readonly {
+        credentialId?: string;
+        code: string;
+    }[];
+    readonly notMine: number;
+}
+/**
+ * One discovery hub per host process: the only vault connection and the only
+ * `ClaustrumScopedCustody`, one vault watch and one list per refresh, fanned
+ * out to one roster per provider. Members (`member()`) are ordinary
+ * `ClaustrumConsumer`s that never connect, list or watch themselves; each
+ * holds a custody lease. The connection stays open while vault mode is on,
+ * because the hub's own discovery holds a lease of its own, and closes when
+ * the last lease of a connection is released, when vault mode goes off, or
+ * at `close()`.
+ */
+export declare class ClaustrumDiscoveryHub {
+    #private;
+    constructor(options: ClaustrumDiscoveryHubOptions);
+    /** The roster file member `provider` reads and the hub commits. */
+    rosterPath(provider: string): string;
+    /**
+     * Build the consumer for `provider`, once. It is an ordinary
+     * `ClaustrumConsumer` whose roster path is `rosterPath(provider)`; it
+     * connects, lists and watches only through this hub.
+     */
+    member<Q = QuotaObservation>(provider: string, options: ClaustrumHubMemberOptions<Q>): ClaustrumConsumer<Q>;
+    /**
+     * Take a lease on the current connection, connecting first when there is
+     * none. The acquirer's count is taken before anything is awaited, so a
+     * release elsewhere meanwhile cannot end the connection under it. An abort
+     * or a failed connect gives that count back; an acquirer whose connection
+     * ended while it waited tries once more on the current one. Rejects with
+     * `not-active` while vault mode is off.
+     */
+    acquire(signal?: AbortSignal): Promise<CustodyLease>;
+    /** The current connection and its lease count, for status and tests. */
+    leaseState(): {
+        readonly generation?: number;
+        readonly count: number;
+    };
+    /**
+     * Start the hub's tick, which runs until `close()`. While vault mode is
+     * off a tick only reads authority and makes no vault request.
+     */
+    start(): void;
+    /**
+     * List once and commit every member, as a tick does. Resolves once every
+     * member's memory holds its new roster. Rejects when the list fails; a
+     * member's own commit error goes to that member's `onError`.
+     */
+    refresh(): Promise<void>;
+    /**
+     * Rows the last discovery every member committed refused, with their fixed
+     * codes, and how many rows it left to other plugins. Undefined while
+     * unknown: before a complete discovery, and while vault mode is off.
+     */
+    refusals(): ClaustrumHubRefusals | undefined;
+    /** The grant reach of the same discovery as `refusals()`. */
+    grantReach(): VaultGrantReach | undefined;
+    /** How the hub learns about changes; `polling` until a watch is open. */
+    watchState(): WatchMode;
+    /** The shared custody's kept receipts, host-wide. */
+    keptReceiptState(): KeptReceiptState;
+    /**
+     * Stop the tick and the watch and close the connection. Members are not
+     * closed; they fail `closed` from then on. Use `dispose()` to also allow
+     * in-flight discovery up to two seconds to release its file handles.
+     */
+    close(): void;
+    /** Close immediately, then join background work for at most two seconds. */
+    dispose(): Promise<void>;
+}